ara::sm
Overview
The State Management Functional Cluster drives machine and application state,
including the Suspend-to-RAM protocol between a hub and its satellites. This page
specifies the public API of the ara::sm namespace — the S2R hub and satellite
classes and the associated error domain — organized by header file.
Library · Headers · Linking
- Library:
lib/libpara_sm.so - CMake:
find_package(para-sm)→para::sm - Standard headers:
include/ara/sm/ - PARA extension headers:
include/apext/sm/power_state_interface.h - Runtime daemon:
bin/SM
1 Header: ara/sm/sm_error_domain.h
1.1 Non-Member Types
1.1.1 Enumeration: SmErrc
| Kind: | enumeration | |
| Header file: | #include "ara/sm/sm_error_domain.h" | |
| Forwarding header file: | #include "ara/sm/sm_fwd.h" | |
| Scope: | namespace ara::sm | |
| Symbol: | SmErrc | |
| Underlying type: | ara::core::ErrorDomain::CodeType | |
| Syntax: | enum class SmErrc : ara::core::ErrorDomain::CodeType {...}; | |
| Values: | kOfferFailed | = 2 |
| Service could not be offered due to failure of communication with Sm daemon | ||
| kCommunicationFailed | = 3 | |
| Communication to satellites failed on lower layers. | ||
| kCommunicationTimeout | = 4 | |
| Timeout of communication with satellites. | ||
| kAtLeastOneRejected | = 5 | |
| At least one Satellite instance had issues to enter Suspend Mode. | ||
| kAtLeastOneHadIssuesToLeave | = 6 | |
| At least one Satellite instance had issues to leave Suspend Mode. | ||
| kRejected | = 7 | |
| Issue to enter or leave the Suspend Mode. | ||
| kAuthenticationRequired | = 8 | |
| S2R Satellite requires IAM authentication. SWS_SM_81003.ara::sm::s2r::S2RSatellite::S2RSatellite has to be used instead. | ||
| Description: | Defines an enumeration class for the State Management error codes. | |
1.2 Non-Member Functions
1.2.1 Other
1.2.1.1 GetSmDomain
| Kind: | function | |
| Header file: | #include "ara/sm/sm_error_domain.h" | |
| Scope: | namespace ara::sm | |
| Syntax: | constexpr const ara::core::ErrorDomain & GetSmDomain () noexcept; | |
| Return value: | const ara::core::ErrorDomain & | The global SmErrorDomain object. |
| Exception Safety: | exception safe | |
| Thread Safety: | thread-safe | |
| Description: | Returns the global SmErrorDomain object. | |
1.2.1.2 MakeErrorCode
| Kind: | function | |
| Header file: | #include "ara/sm/sm_error_domain.h" | |
| Scope: | namespace ara::sm | |
| Syntax: | constexpr ara::core::ErrorCode MakeErrorCode (ara::sm::SmErrc code, ara::core::ErrorDomain::SupportDataType data) noexcept; | |
| Parameters (in): | code | Error code number. |
| data | Vendor defined data associated with the error. | |
| Return value: | ara::core::ErrorCode | An ErrorCode object. |
| Exception Safety: | exception safe | |
| Thread Safety: | thread-safe | |
| Description: | Creates an error code. | |
1.3 Class: SmErrorDomain
| Kind: | class | |
| Header file: | #include "ara/sm/sm_error_domain.h" | |
| Forwarding header file: | #include "ara/sm/sm_fwd.h" | |
| Scope: | namespace ara::sm | |
| Symbol: | SmErrorDomain | |
| Base class: | ara::core::ErrorDomain | |
| Syntax: | class SmErrorDomain final : public ara::core::ErrorDomain {...}; | |
| Description: | Defines the error domain for State Management. | |
1.3.1 Public Member Types
1.3.1.1 Type Alias: Errc
| Kind: | type alias | |
| Header file: | #include "ara/sm/sm_error_domain.h" | |
| Scope: | ara::sm::SmErrorDomain | |
| Symbol: | Errc | |
| Syntax: | using Errc = SmErrc; | |
| Description: | Alias for the error code value enumeration. | |
1.3.1.2 Type Alias: Exception
| Kind: | type alias | |
| Header file: | #include "ara/sm/sm_error_domain.h" | |
| Scope: | ara::sm::SmErrorDomain | |
| Symbol: | Exception | |
| Syntax: | using Exception = SmException; | |
| Description: | Alias for the exception base class. | |
1.3.2 Public Member Functions
1.3.2.1 Special Member Functions
1.3.2.1.1 Default Constructor
| Kind: | function | |
| Header file: | #include "ara/sm/sm_error_domain.h" | |
| Scope: | ara::sm::SmErrorDomain | |
| Syntax: | SmErrorDomain () noexcept; | |
| Exception Safety: | exception safe | |
| Thread Safety: | thread-safe | |
| Description: | Creates a SmErrorDomain instance. | |
1.3.2.2 Member Functions
1.3.2.2.1 Message
| Kind: | function | |
| Header file: | #include "ara/sm/sm_error_domain.h" | |
| Scope: | ara::sm::SmErrorDomain | |
| Syntax: | const char * Message (CodeType errorCode) const noexcept override; | |
| Parameters (in): | errorCode | The error code number. |
| Return value: | const char * | The message associated with the error code. |
| Exception Safety: | exception safe | |
| Thread Safety: | thread-safe | |
| Description: | Returns the message associated with the error code. | |
1.3.2.2.2 Name
| Kind: | function | |
| Header file: | #include "ara/sm/sm_error_domain.h" | |
| Scope: | ara::sm::SmErrorDomain | |
| Syntax: | const char * Name () const noexcept override; | |
| Return value: | const char * | "Sm". |
| Exception Safety: | exception safe | |
| Thread Safety: | thread-safe | |
| Description: | Returns the name of the error domain. | |
1.3.2.2.3 ThrowAsException
| Kind: | function | |
| Header file: | #include "ara/sm/sm_error_domain.h" | |
| Scope: | ara::sm::SmErrorDomain | |
| Syntax: | void ThrowAsException (const ara::core::ErrorCode &errorCode) const override; | |
| Parameters (in): | errorCode | The error to throw. |
| Return value: | None | |
| Exception Safety: | not exception safe | |
| Thread Safety: | thread-safe | |
| Description: | Throws the exception associated with the error code. As per SWS_CORE_10304, this function does not participate in overload resolution when C++ exceptions are disabled in the compiler toolchain. | |
1.4 Class: SmException
| Kind: | class | |
| Header file: | #include "ara/sm/sm_error_domain.h" | |
| Forwarding header file: | #include "ara/sm/sm_fwd.h" | |
| Scope: | namespace ara::sm | |
| Symbol: | SmException | |
| Base class: | ara::core::Exception | |
| Syntax: | class SmException : public ara::core::Exception {...}; | |
| Description: | Exception type thrown by State Management. | |
1.4.1 Public Member Functions
1.4.1.1 Constructors
1.4.1.1.1 SmException
| Kind: | function | |
| Header file: | #include "ara/sm/sm_error_domain.h" | |
| Scope: | ara::sm::SmException | |
| Syntax: | explicit SmException (ara::core::ErrorCode errorCode) noexcept; | |
| Parameters (in): | errorCode | The error code. |
| Exception Safety: | exception safe | |
| Thread Safety: | thread-safe | |
| Description: | Construct a new StateManagement exception object containing an error code. | |
2 Header: ara/sm/s2r/S2RHub.h
2.1 Class: S2RHub
| Kind: | class | |
| Header file: | #include "ara/sm/s2r/S2RHub.h" | |
| Forwarding header file: | #include "ara/sm/sm_fwd.h" | |
| Scope: | namespace ara::sm::s2r | |
| Symbol: | S2RHub | |
| Syntax: | class S2RHub {...}; | |
| Description: | S2RHub class. | |
2.1.1 Public Member Functions
2.1.1.1 Special Member Functions
2.1.1.1.1 Move Constructor
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RHub.h" | |
| Scope: | ara::sm::s2r::S2RHub | |
| Syntax: | S2RHub (S2RHub &&ra) noexcept; | |
| Parameters (in): | ra | The S2RHub object to be moved. |
| Exception Safety: | exception safe | |
| Thread Safety: | thread-safe | |
| Description: | Move constructor for S2RHub. | |
2.1.1.1.2 Copy Constructor
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RHub.h" | |
| Scope: | ara::sm::s2r::S2RHub | |
| Syntax: | S2RHub (const S2RHub &)=delete; | |
| Description: | The copy constructor for S2RHub shall not be used. | |
2.1.1.1.3 Copy Assignment Operator
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RHub.h" | |
| Scope: | ara::sm::s2r::S2RHub | |
| Syntax: | ara::sm::s2r::S2RHub & operator= (const ara::sm::s2r::S2RHub &)=delete; | |
| Description: | The copy assignment operator for S2RHub shall not be used. | |
2.1.1.1.4 Move Assignment Operator
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RHub.h" | |
| Scope: | ara::sm::s2r::S2RHub | |
| Syntax: | ara::sm::s2r::S2RHub & operator= (ara::sm::s2r::S2RHub &&ra) noexcept; | |
| Parameters (in): | ra | The S2RHub object to be moved. |
| Return value: | S2RHub & | The moved S2RHub object. |
| Exception Safety: | exception safe | |
| Thread Safety: | thread-safe | |
| Description: | Move assignment operator for S2RHub. | |
2.1.1.1.5 Destructor
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RHub.h" | |
| Scope: | ara::sm::s2r::S2RHub | |
| Syntax: | virtual ~S2RHub () noexcept; | |
| Exception Safety: | exception safe | |
| Thread Safety: | not thread-safe | |
| Description: | Destructor for S2RHub. | |
2.1.1.2 Constructors
2.1.1.2.1 S2RHub
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RHub.h" | |
| Scope: | ara::sm::s2r::S2RHub | |
| Syntax: | explicit S2RHub (const ara::core::InstanceSpecifier &instance) noexcept; | |
| Parameters (in): | instance | instance specifier to the PPortPrototype of a SM... |
| Exception Safety: | exception safe | |
| Thread Safety: | thread-safe | |
| Violations: | InsufficientPermissionsViolation | Sent in case the caller had insufficient permissions for the requested operation. |
| InstanceSpecifierMappingIntegrityViolation | InstanceSpecifier either cannot be resolved in the model in the context of your executable, or it refers to a model element other than a PortPrototype. | |
| PortInterfaceMappingViolation | The type of mapping does not match the expected type of PortInterface: {portInterfaceTypeName} referenced by a {mappingTypeName}. | |
| ProcessMappingViolation | Matching InstanceRef exists, but no matching (modelled) Process found that matches the (runtime) process. | |
| InstanceSpecifierAlreadyInUseViolation | Violation message that is sent in case a constructor in the ara framework was called with an InstanceSpecifier already in use in this process. | |
| AraNotInitializedViolation | Violation message that is sent in case a constructor or function checks for an initialized ara and identifies that ara is not initialized. | |
| Description: | Creation of an S2RHub. | |
2.1.1.3 Member Functions
2.1.1.3.1 EnterSuspendToRamOs
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RHub.h" | |
| Scope: | ara::sm::s2r::S2RHub | |
| Syntax: | void EnterSuspendToRamOs () noexcept; | |
| Return value: | None | |
| Exception Safety: | exception safe | |
| Thread Safety: | not-threadsafe | |
| Description: | Function to trigger OS to enter Suspend To RAM. | |
2.1.1.3.2 RequestToEnterSuspendMode
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RHub.h" | |
| Scope: | ara::sm::s2r::S2RHub | |
| Syntax: | ara::core::Future< void > RequestToEnterSuspendMode (int timeout=1000) noexcept; | |
| Parameters (in): | timeout | Timeout value in ms until the S2R Satellite have to respond. |
| Return value: | ara::core::Future< void > | HubResult if it is successful |
| Exception Safety: | exception safe | |
| Thread Safety: | not-threadsafe | |
| Errors: | SmErrc::kCommunicationFailed | rollback_semantics |
| Communication to satellites failed on lower layers. | ||
| SmErrc::kCommunicationTimeout | rollback_semantics | |
| Timeout of communication with satellites. | ||
| SmErrc::kAtLeastOneRejected | no_rollback_semantics | |
| Some S2RSatellites entered suspend state, but not all. | ||
| Description: | Function to Request all S2R Satellite to enter suspend state. | |
2.1.1.3.3 RequestToLeaveSuspendMode
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RHub.h" | |
| Scope: | ara::sm::s2r::S2RHub | |
| Syntax: | ara::core::Future< void > RequestToLeaveSuspendMode (int timeout=1000) noexcept; | |
| DIRECTION NOT DEFINED: | timeout | -- |
| Return value: | ara::core::Future< void > | HubResult if it is successful |
| Exception Safety: | exception safe | |
| Thread Safety: | not-threadsafe | |
| Errors: | SmErrc::kCommunicationFailed | rollback_semantics |
| Communication to satellites failed on lower layers. | ||
| SmErrc::kCommunicationTimeout | rollback_semantics | |
| Timeout of communication with satellites. | ||
| SmErrc::kAtLeastOneHadIssuesToLeave | no_rollback_semantics | |
| Some S2RSatellites left suspend state, but not all. | ||
| Description: | Function to request all registered S2R Satellite to leave suspend state. | |
3 Header: ara/sm/s2r/S2RSatellite.h
3.1 Class: S2RSatellite
| Kind: | class | |
| Header file: | #include "ara/sm/s2r/S2RSatellite.h" | |
| Forwarding header file: | #include "ara/sm/sm_fwd.h" | |
| Scope: | namespace ara::sm::s2r | |
| Symbol: | S2RSatellite | |
| Syntax: | class S2RSatellite {...}; | |
| Description: | S2RSatellite abstract class. | |
3.1.1 Public Member Functions
3.1.1.1 Special Member Functions
3.1.1.1.1 Move Constructor
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RSatellite.h" | |
| Scope: | ara::sm::s2r::S2RSatellite | |
| Syntax: | S2RSatellite (S2RSatellite &&ra) noexcept; | |
| Parameters (in): | ra | The S2RSatellite object to be moved. |
| Exception Safety: | exception safe | |
| Thread Safety: | thread-safe | |
| Description: | Move constructor for S2RSatellite. | |
3.1.1.1.2 Default Constructor
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RSatellite.h" | |
| Scope: | ara::sm::s2r::S2RSatellite | |
| Syntax: | S2RSatellite ()=delete; | |
| Description: | Default constructor for S2RSatellite shall not be used. | |
3.1.1.1.3 Copy Constructor
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RSatellite.h" | |
| Scope: | ara::sm::s2r::S2RSatellite | |
| Syntax: | S2RSatellite (const S2RSatellite &)=delete; | |
| Description: | The copy constructor for S2RSatellite shall not be used. | |
3.1.1.1.4 Move Assignment Operator
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RSatellite.h" | |
| Scope: | ara::sm::s2r::S2RSatellite | |
| Syntax: | ara::sm::s2r::S2RSatellite & operator= (ara::sm::s2r::S2RSatellite &&ra) noexcept; | |
| Parameters (in): | ra | The S2RSatellite object to be moved. |
| Return value: | S2RSatellite & | The moved S2RSatellite object. |
| Exception Safety: | exception safe | |
| Thread Safety: | thread-safe | |
| Description: | Move assignment operator for S2RSatellite. | |
3.1.1.1.5 Copy Assignment Operator
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RSatellite.h" | |
| Scope: | ara::sm::s2r::S2RSatellite | |
| Syntax: | ara::sm::s2r::S2RSatellite & operator= (const ara::sm::s2r::S2RSatellite &)=delete; | |
| Description: | The copy assignment operator for S2RSatellite shall not be used. | |
3.1.1.1.6 Destructor
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RSatellite.h" | |
| Scope: | ara::sm::s2r::S2RSatellite | |
| Syntax: | virtual ~S2RSatellite () noexcept; | |
| Exception Safety: | exception safe | |
| Thread Safety: | not thread-safe | |
| Description: | Destructor for S2RSatellite. | |
3.1.1.2 Constructors
3.1.1.2.1 S2RSatellite
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RSatellite.h" | |
| Scope: | ara::sm::s2r::S2RSatellite | |
| Syntax: | explicit S2RSatellite (const ara::core::InstanceSpecifier &instance) noexcept; | |
| Parameters (in): | instance | instance specifier to the PPortPrototype of a SuspendToRamSatelliteInterface |
| Exception Safety: | exception safe | |
| Thread Safety: | thread-safe | |
| Violations: | InstanceSpecifierMappingIntegrityViolation | InstanceSpecifier either cannot be resolved in the model in the context of your executable, or it refers to a model element other than a PortPrototype. |
| PortInterfaceMappingViolation | The type of mapping does not match the expected type of PortInterface: {portInterfaceTypeName} referenced by a {mappingTypeName}. | |
| ProcessMappingViolation | Matching InstanceRef exists, but no matching (modelled) Process found that matches the (runtime) process. | |
| InstanceSpecifierAlreadyInUseViolation | Violation message that is sent in case a constructor in the ara framework was called with an InstanceSpecifier already in use in this process. | |
| AraNotInitializedViolation | Violation message that is sent in case a constructor or function checks for an initialized ara and identifies that ara is not initialized. | |
| Description: | Creation of an S2RSatellite. | |
3.1.1.3 Member Functions
3.1.1.3.1 Create
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RSatellite.h" | |
| Scope: | ara::sm::s2r::S2RSatellite | |
| Syntax: | static ara::core::Result< ara::sm::s2r::S2RSatellite > Create () noexcept; | |
| Return value: | ara::core::Result< S2RSatellite > | a result that contains either a object or an error. |
| Exception Safety: | exception safe | |
| Thread Safety: | thread-safe | |
| Violations: | AraNotInitializedViolation | Violation message that is sent in case a constructor or function checks for an initialized ara and identifies that ara is not initialized. |
| Errors: | ara::sm::SmErrc::kAuthenticationRequired | rollback_semantics |
| S2R Satellite requires IAM authentication. SWS_SM_81003.ara::sm::s2r::S2RSatellite::S2RSatellite has to be used instead. | ||
| Description: | Creation of an conneting directly to S2RHub within the current machine. | |
3.1.1.3.2 EnterSuspendMode
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RSatellite.h" | |
| Scope: | ara::sm::s2r::S2RSatellite | |
| Syntax: | virtual ara::core::Future< void > EnterSuspendMode ()=0; | |
| Return value: | ara::core::Future< void > | void in case the Suspend Mode is successfully entered; or the error kRejected if there is an issue to enter Suspend Mode. |
| Exception Safety: | not exception safe | |
| Thread Safety: | not-threadsafe | |
| Errors: | SmErrc::kRejected | rollback_semantics |
| There are issues to enter Suspend Mode. | ||
| Description: | EnterSuspendMode is called to enter Suspend Mode. The handler invocation needs to be enabled before by a call of Offer(). | |
3.1.1.3.3 LeaveSuspendMode
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RSatellite.h" | |
| Scope: | ara::sm::s2r::S2RSatellite | |
| Syntax: | virtual ara::core::Future< void > LeaveSuspendMode ()=0; | |
| Return value: | ara::core::Future< void > | void in case the Suspend Mode is left; or the error kRejected if the resume is not successful. |
| Exception Safety: | not exception safe | |
| Thread Safety: | not-threadsafe | |
| Errors: | SmErrc::kRejected | rollback_semantics |
| There are issues to leave Suspend Mode. | ||
| Description: | LeaveSuspendMode is called to leave Suspend Mode. The handler invocation needs to be enabled before by a call of Offer(). | |
3.1.1.3.4 Offer
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RSatellite.h" | |
| Scope: | ara::sm::s2r::S2RSatellite | |
| Syntax: | ara::core::Result< void > Offer () noexcept; | |
| Return value: | ara::core::Result< void > | A Result, being either empty or containing any of the errors defined below. |
| Exception Safety: | exception safe | |
| Thread Safety: | not thread-safe | |
| Errors: | SmErrc::kOfferFailed | rollback_semantics |
| Service could not be offered due to failure of communication with Sm daemon | ||
| Description: | Enables potential invocations of handlers . | |
3.1.1.3.5 StopOffer
| Kind: | function | |
| Header file: | #include "ara/sm/s2r/S2RSatellite.h" | |
| Scope: | ara::sm::s2r::S2RSatellite | |
| Syntax: | void StopOffer () noexcept; | |
| Return value: | None | |
| Exception Safety: | exception safe | |
| Thread Safety: | not thread-safe | |
| Description: | Disables invocations of handlers. | |
See also
- Suspend-to-RAM and the runtime model: PARA Overview
- State Management configuration: Function Group configuration, Machine state configuration