class ara::sm::s2r::S2RHub

In State Management, class ara::sm::s2r::S2RHub coordinates entering and leaving the Suspend-to-RAM state for registered satellite applications (AUTOSAR_AP_EXP_SWArchitecture §9.2.2.1.4 “Interfaces for Suspend-to-Ram Notifications”). It allows a control application to request satellite preparation prior to putting the operating system into sleep mode and to return them to normal operation after wake-up ([SWS_SM_00701], [SWS_SM_81112]). Use of the C++ API strictly precludes the internal StateMachine approach and requires verified IAM permissions ([SWS_SM_00684], [SWS_SM_00706]).

more ›

Context

Class ara::sm::s2r::S2RHub forms the central interface of State Management for coordinating Suspend-to-RAM transitions on the Adaptive Platform (AUTOSAR_AP_EXP_SWArchitecture §9.2.2.1.4 “Interfaces for Suspend-to-Ram Notifications”). To optimize machine shutdown and startup times, Suspend-to-RAM can be used instead of a full system reboot (AUTOSAR_AP_SWS_StateManagement §7.5 “Interaction with Suspend-to-RAM Functionality”). The primary task of the hub is to address all actively registered satellite instances (ara::sm::s2r::S2RSatellite) in order to initiate orderly preparation before transitioning the operating system to the suspend state and to coordinate the resumption of operation after wake-up ([SWS_SM_00701], [SWS_SM_00703]).

Use of class S2RHub is reserved for dedicated control applications such as SMControlApplication and is not intended for regular Adaptive Applications (AUTOSAR_AP_EXP_SWArchitecture §9.2.2.1.4 “Interfaces for Suspend-to-Ram Notifications”). Access to the hub functionality can occur either via the C++ API or internally via the StateMachine approach; both variants are mutually exclusive to prevent race conditions and state inconsistencies (AUTOSAR_AP_SWS_StateManagement §7.5.1 “S2R Hub”, AUTOSAR_AP_SWS_StateManagement §7.7.15 “Mutual exclusivity of StateMachine approach and S2RHub API usage”, [SWS_SM_00684]). Interaction with processes and satellites is secured via Identity and Access Management (IAM) ([SWS_SM_00706], [SWS_SM_00714], [SWS_SM_00715]).

Context diagram: Embedding of S2RHub between control application, satellites, and operating system. Sources: AUTOSAR_AP_EXP_SWArchitecture §9.2.2.1.4, AUTOSAR_AP_SWS_StateManagement §7.5.1, [SWS_SM_81112].

Lifecycle

An instance of ara::sm::s2r::S2RHub is created explicitly via a ara::core::InstanceSpecifier ([SWS_SM_81103]). Mandatory IAM authorization checking occurs during construction, where the calling process context is validated against the model mapping (SuspendToRamHubMapping.process) ([SWS_SM_00706], [SWS_SM_00714]). Copy operations are completely prohibited for the class ([SWS_SM_81107], [SWS_SM_81109]). However, the class supports move semantics via move constructor and move assignment operator ([SWS_SM_81106], [SWS_SM_81108]).

Regarding concurrency, the parameterized constructor and the move operations are specified as thread-safe ([SWS_SM_81103], [SWS_SM_81106], [SWS_SM_81108]). By contrast, the virtual destructor ~S2RHub() and the operational methods for suspend coordination are not thread-safe ([SWS_SM_81105], [SWS_SM_81110], [SWS_SM_81111], [SWS_SM_81112]). Callers must therefore ensure that destruction and execution of transitions occur sequentially and without concurrent calls.

Usage Path

The regular sequence for initiating and terminating Suspend-to-RAM is divided into three consecutive phases:

1. Preparation of the suspend state: Prior to suspending the operating system, function groups with non-supporting processes must be shut down (AUTOSAR_AP_SWS_StateManagement §7.5). Subsequently, the control application calls RequestToEnterSuspendMode() on the hub ([SWS_SM_81110]). The hub notifies all satellites registered via Offer through EnterSuspendMode ([SWS_SM_00701], [SWS_SM_00710], [SWS_SM_00711]). The method returns a ara::core::Future<void> that completes only once all addressed satellites have responded, unregistered, or timed out ([SWS_SM_00702], [SWS_SM_81110]).
2. Triggering the system suspend: After successful feedback from all satellites, the caller triggers the operating system via the synchronous function EnterSuspendToRamOs() to put the machine into Suspend-to-RAM mode ([SWS_SM_81112]).
3. Resumption after wake-up: As soon as the operating system wakes up again, the control application initiates the resumption of regular operation via RequestToLeaveSuspendMode() ([SWS_SM_81111]). The hub requests all active satellites via their callback function to exit suspend mode ([SWS_SM_00703], [SWS_SM_00711]). The returned future resolves positively if all satellites acknowledge positively or unregister via StopOffer ([SWS_SM_00707], [SWS_SM_81111]).

Sequence diagram: Typical call sequence for suspend preparation, OS suspend execution, and subsequent reactivation. Sources: [SWS_SM_00701], [SWS_SM_00702], [SWS_SM_00703], [SWS_SM_00707], [SWS_SM_81110], [SWS_SM_81111], [SWS_SM_81112].

Error Scenarios

Depending on the phase, error conditions are signaled in S2RHub via architectural violations or via error codes in the ara::core::Future:

• Construction errors and violations: If authorization checking of the calling process fails, violation InsufficientPermissionsViolation and security event SEV_ACCESS_CONTROL_SM_IAM_ACCESS_DENIED are triggered ([SWS_SM_00706], [SWS_SM_81103]). Other defined violations include InstanceSpecifierMappingIntegrityViolation (invalidity of the model specifier), PortInterfaceMappingViolation (incompatible interface type), ProcessMappingViolation (missing process mapping), InstanceSpecifierAlreadyInUseViolation (multiple use in the same process), and AraNotInitializedViolation (missing initialization of the Adaptive Platform) ([SWS_SM_81103]).
• Errors when entering the suspend state: If lower-layer communication fails, the future of RequestToEnterSuspendMode() fails with SmErrc::kCommunicationFailed ([SWS_SM_81110]). If at least one satellite does not respond within the configurable time window (default: 1000 ms), this results in SmErrc::kCommunicationTimeout ([SWS_SM_81110]). Both errors have rollback semantics. If at least one satellite reports rejection of the transition, the future returns error SmErrc::kAtLeastOneRejected without rollback semantics ([SWS_SM_81110]).
• Errors when leaving the suspend state: Analogously, communication issues or timeouts during RequestToLeaveSuspendMode() lead to SmErrc::kCommunicationFailed or SmErrc::kCommunicationTimeout, respectively ([SWS_SM_00707], [SWS_SM_81111]). If a satellite responds with kRejected, the future reports error code SmErrc::kAtLeastOneHadIssuesToLeave ([SWS_SM_00707], [SWS_SM_81111]).
• Rejected satellite registration: Registration attempts by satellites are rejected by the hub if their process context does not match the model configuration ([SWS_SM_00715]).