namespace ara::sm::s2r

Namespace ara::sm::s2r coordinates the Suspend-to-RAM mechanism for optimizing shutdown and startup times in the AUTOSAR Adaptive Platform (SWS StateManagement §7.5 “Interaction with Suspend-to-RAM Functionality”). Via the central component S2RHub and registered S2RSatellite instances, S2R-capable processes are notified prior to entering the operating system sleep state and are transitioned back to regular operation upon wake-up. As an essential constraint, usage via the internal StateMachine approach strictly precludes access via the C++ API, while IAM checks secure all participating process contexts ([SWS_SM_00684]).

more ›

Context

Namespace ara::sm::s2r provides functionalities for coordinating Suspend-to-RAM (S2R) within the State Management module. The goal of this mechanism is to optimize machine shutdown and startup times by using a RAM-based sleep state of the operating system instead of a full shutdown and cold start (SWS StateManagement §7.5 “Interaction with Suspend-to-RAM Functionality”). Before transitioning into the suspend state of the operating system, function clusters without S2R support must be deactivated and processes whose executable is marked as suspendToRamAware must be notified in time (SWS StateManagement §7.5 “Interaction with Suspend-to-RAM Functionality”).

The central hub is formed by class S2RHub, which controls communication with instances of the abstract class S2RSatellite (SWS StateManagement §7.5.1 “S2R Hub”). The orchestration of S2RHub can take place either internally via the StateMachine approach of State Management or externally via a C++ API (for example in a SMControlApplication); both approaches are strictly mutually exclusive ([SWS_SM_00684], SWS StateManagement p. 96). Accesses to the hub and the registration of satellites are secured by Identity and Access Management (IAM) ([SWS_SM_00706], [SWS_SM_00714], [SWS_SM_00715]).

Context diagram: Interaction of State Management, S2RHub, S2RSatellite, and IAM. Sources: SWS StateManagement §7.5.1 “S2R Hub”, [SWS_SM_00684], [SWS_SM_00715].

Lifecycle

Instantiation of ara::sm::s2r::S2RHub depends on the architectural approach: In StateMachine mode, the instance is automatically created by State Management as soon as the action list items EnterSuspendToRam, EnterSuspendToRamOS, or LeaveSuspendToRam terminate ([SWS_SM_00690]). When calling the constructor ara::sm::s2r::S2RHub::S2RHub, IAM checks whether the current process context matches the configuration SuspendToRamHubMapping.process ([SWS_SM_00706]). Only authorized processes may perform the instantiation ([SWS_SM_00714]).

Satellites are initialized via the factory method ara::sm::s2r::S2RSatellite::Create ([SWS_SM_00716]). Since S2RSatellite is an abstract class, an application-specific derived class is likely implemented to provide the concrete reactions (interpretation). Question Q-e4747345883235e0 (open) Registration with the hub is performed actively by calling ara::sm::s2r::S2RSatellite::Offer ([SWS_SM_00710]). The hub validates the process context of the satellite using SuspendToRamSatelliteMapping.process ([SWS_SM_00715]). A satellite remains in the actively registered state until it deregisters via ara::sm::s2r::S2RSatellite::StopOffer ([SWS_SM_00710], [SWS_SM_00713]).

With regard to the state machine life cycle, the constraint applies that states responsible for the suspend state must not be configured with the action list item LeaveSuspendToRam ([SWS_SM_CONSTR_00035]). This item is reserved exclusively for the return phase upon wake-up (SWS StateManagement p. 98).

Usage Path

Typical usage of the namespace is divided into registration, preparation for the sleep state, operating system suspend, and subsequent wake-up:

1. Registration: The S2R-capable application creates its satellite and calls ara::sm::s2r::S2RSatellite::Offer to register with the hub ([SWS_SM_00710]). The notification between hub and satellites presumably occurs via platform-internal inter-process communication (interpretation). Question (open)
2. Request Suspend: The control plane calls ara::sm::s2r::S2RHub::RequestToEnterSuspendMode ([SWS_SM_00701]). In the StateMachine approach, this is triggered by item EnterSuspendToRam, with its configuration value maxActionItemDuration passed as the timeout parameter ([SWS_SM_00689]).
3. Notify Satellites: The hub addresses all registered satellites and triggers execution of callback ara::sm::s2r::S2RSatellite::EnterSuspendMode ([SWS_SM_00701], [SWS_SM_00711]). RequestToEnterSuspendMode returns as soon as all satellites have responded, have deregistered, or a timeout has occurred ([SWS_SM_00702]).
4. Suspend Operating System: By calling ara::sm::s2r::S2RHub::EnterSuspendToRamOs (or via the action list item EnterSuspendToRamOs), the actual sleep state of the operating system is initiated ([SWS_SM_00692]).
5. Coordinate Wake-up: After restarting, ara::sm::s2r::S2RHub::RequestToLeaveSuspendMode is called ([SWS_SM_00703], [SWS_SM_00691]). The hub instructs the satellites to execute callback ara::sm::s2r::S2RSatellite::LeaveSuspendMode ([SWS_SM_00703], [SWS_SM_00711]).
6. Deregistration: If a process no longer wishes to participate, it deregisters via ara::sm::s2r::S2RSatellite::StopOffer ([SWS_SM_00710], [SWS_SM_00713]).

Sequence diagram: Call sequence for preparing and terminating Suspend-to-RAM. Sources: [SWS_SM_00701], [SWS_SM_00702], [SWS_SM_00703], [SWS_SM_00707], [SWS_SM_00710], [SWS_SM_00711].

Error Scenarios

Specific error conditions occur in the interaction of the classes:

• IAM Violation During Hub Creation: If the process context does not match SuspendToRamHubMapping.process during the constructor call, violation InsufficientPermissionsViolation is triggered and security event SEV_ACCESS_CONTROL_SM_IAM_ACCESS_DENIED</a> is reported ([SWS_SM_00706]).
• Rejection of Unauthenticated Satellites: If the context of S2RSatellite deviates from the process stored in SuspendToRamSatelliteMapping, the hub rejects registration ([SWS_SM_00715]).
• Authentication Requirement on Satellite: If the Force IAM switch configuration is set, ara::sm::s2r::S2RSatellite::Create fails with error code kAuthenticationRequired ([SWS_SM_00716]).
• Communication Timeout: If an addressed satellite does not respond within deadline timeout during the suspend or wake-up phase, the operation returns error code kCommunicationTimeout ([SWS_SM_00707]).
• Issues Leaving Suspend Mode: If at least one satellite responds negatively with kRejected to the request to leave suspend mode, RequestToLeaveSuspendMode acknowledges the overall result with kAtLeastOneHadIssuesToLeave ([SWS_SM_00707]).
• Concurrent API Usage: Concurrent use of the C++ API of S2RHub alongside the internal StateMachine approach is prohibited and leads to inconsistencies ([SWS_SM_00684]).