namespace ara::sm

Namespace ara::sm provides domain-specific error handling and coordination structures for State Management in AUTOSAR Adaptive (AUTOSAR_AP_SWS_StateManagement §7.5 p. 34). Via SmErrc, SmErrorDomain, and MakeErrorCode, it defines standardized mechanisms for detecting communication errors, timeouts, and rejections during synchronized state transitions such as Suspend-to-RAM ([SWS_SM_81240], [SWS_SM_81244]). An essential constraint is the mutual exclusivity between automated state machine control and direct API access to coordination instances ([SWS_SM_00684]).

more ›

Context

Namespace ara::sm forms the fundamental interface for state management (State Management) of the AUTOSAR Adaptive Platform and provides types for error handling and for controlling machine-wide state configurations. In addition to the central error domain SmErrorDomain and the associated exception type SmException, the module includes functional mechanisms for synchronizing system states, in particular within the scope of the Suspend-to-RAM functionality according to AUTOSAR_AP_SWS_StateManagement §7.5 “Interaction with Suspend-to-RAM Functionality” p. 34. Key interaction partners include control applications such as the SMControlApplication, the internal StateMachine controller of the State Management daemon, and processes connected via satellites (AUTOSAR_AP_SWS_StateManagement §7.5.1 “S2R Hub” p. 35).

The architecture strictly separates declarative state machines from programmatic control: if the system follows the StateMachine approach, the control entity integrates the coordination internally, so that external applications are denied direct access to the C++ API of S2RHub ([SWS_SM_00684]; AUTOSAR_AP_SWS_StateManagement §7.7.15 p. 96). Safety- and security-relevant interactions are also subject to Identity and Access Management (IAM) checks to ensure that only authorized processes are permitted to perform registrations or request state changes ([SWS_SM_00706], [SWS_SM_00714], [SWS_SM_00715]).

Context diagram: Distribution of roles and interaction paths between control application, State Management daemon, satellites, and error domain. Sources: [SWS_SM_00684], [SWS_SM_00701], [SWS_SM_00710], [SWS_SM_81240], [SWS_SM_81251].

Usage Path

Typical usage of the namespace is structured into registering application-side processes, triggering coordinated transitions, and evaluating resulting error codes. For processes that possess suspend-to-RAM capabilities, the cycle begins with providing their interface via Offer ([SWS_SM_00710]). Prior to the transition of the operating system into the sleep state, the controlling entity sends a request to all registered satellites by means of RequestToEnterSuspendMode, whereupon their callback EnterSuspendMode is triggered ([SWS_SM_00701], [SWS_SM_00711]).

The coordinating function blocks or monitors the transition until all involved satellites have responded or have been deregistered ([SWS_SM_00702]). Upon wake-up, the call to RequestToLeaveSuspendMode takes place analogously, which restores normal operation via LeaveSuspendMode ([SWS_SM_00703], [SWS_SM_00711]). If aborts occur during communication or state changes, the module resorts to the free function MakeErrorCode ([SWS_SM_81244]) to create specific ara::core::ErrorCode instances based on the enumeration SmErrc and provide them to the calling application.

Sequence diagram: Typical sequence of suspend coordination with satellites and error handling. Sources: [SWS_SM_00701], [SWS_SM_00702], [SWS_SM_00707], [SWS_SM_81240], [SWS_SM_81244].

Error Scenarios

Error handling in ara::sm is strictly typed and based on the enumeration SmErrc ([SWS_SM_81240]). The defined error codes include:

• kOfferFailed: The service could not be offered because communication with the State Management daemon failed ([SWS_SM_81240]).
• kCommunicationFailed: Error on the lower transport layers during communication with satellites ([SWS_SM_81240]).
• kCommunicationTimeout: An addressed satellite exceeded the specified response time ([SWS_SM_81240], [SWS_SM_00707]).
• kAtLeastOneRejected: At least one satellite could not enter the suspend state properly ([SWS_SM_81240]).
• kAtLeastOneHadIssuesToLeave: At least one satellite reported kRejected when leaving suspend mode ([SWS_SM_81240], [SWS_SM_00707]).
• kAuthenticationRequired: IAM authentication is enforced and requires an explicit identity check of the satellite ([SWS_SM_81240], [SWS_SM_00716]).

Providing the global error domain via GetSmDomain ([SWS_SM_81251]) and creating error codes via MakeErrorCode ([SWS_SM_81244]) are declared as noexcept and guarantee exception safety as well as thread safety. Interpretation: Throwing an SmException is likely used primarily when callers wish to convert error codes of SmErrorDomain into exception-based control flows, whereas functional interfaces regularly return ara::core::ErrorCode in case of an error. Question Q-5afcc13f11bdf19b (open)