service interface UpdateRequest

The service method PrepareRollback of the service interface UpdateRequest is called by Update and Configuration Management to prepare the rollback of changes for the function groups of a software cluster passed in parameter functionGroupList [SWS_SM_91105]. The call is made without fire-and-forget semantics, so that State Management reports the result of the preparation back to the caller [SWS_SM_91105].

Fixed conditions apply to the call and error handling:

• Session context: The call is only permitted within an active update session. If it occurs outside an active session, State Management rejects the operation with error kOperationRejected [SWS_SM_00213].
• Application errors: In addition to kOperationRejected in case of an invalid internal state, the method can return kOperationFailed if preparation fails [SWS_SM_91105].

In the state model, the method call has direct effects on the participating state machines:

• State machines that manage one of the passed function groups are marked as ImpactedByUpdate by the controlling process [SWS_SM_00654].
• If a state machine of type Agent is marked, this status also transitively transfers to the parent Controller [SWS_SM_00655].
• For state machines marked as ImpactedByUpdate, reported execution errors (ExecutionErrorEvent::executionError) are not handled via recovery, but are ignored and merely logged [SWS_SM_00664].

use

The service method PrepareUpdate is called by Update and Configuration Management (UCM) to request State Management to prepare the update of a set of function groups [SWS_SM_00206], [SWS_SM_91103]. It is provided via the service interface UpdateRequest and accepts the list functionGroupList of type FunctionGroupListType as an input parameter, which specifies the function groups to be updated within the software cluster [SWS_SM_91103]. Since fire & forget is deactivated, the call has synchronous response semantics with feedback to the caller [SWS_SM_91103].

Ordering Requirements and Concurrency

A call is only permissible within an update session previously successfully initiated by RequestUpdateSession [SWS_SM_91103]. During the call, the controlling process marks all state machines that manage one of the passed function groups as ImpactedByUpdate [SWS_SM_00654]. If this affects a state machine of type Agent, the superordinate Controller state machine is automatically marked as ImpactedByUpdate as well [SWS_SM_00655]. As long as this state persists, external state transitions are blocked: Each call to RequestTransition is answered with kUpdateInProgress [SWS_SM_00649]. In addition, recovery requests in case of execution errors (ExecutionErrorEvent::executionError) are ignored and merely logged [SWS_SM_00664].

Error handling

Two specific application errors are defined for the method [SWS_SM_91103]:

• kOperationRejected: Is returned when the call occurs outside an active update session [SWS_SM_00213] or the internal state of State Management rejects the operation [SWS_SM_91103].
• kOperationFailed: Indicates that the requested preparation of the function groups has failed [SWS_SM_91103].

Interpretation: The method is likely to return only after initiation or completion of the internal state transitions of the function groups, since no separate asynchronous confirmation mechanism is defined in the interface. Question Q-9994d886fd5504d8 (open)

The service method RequestUpdateSession of interface UpdateRequest is called without parameters (Fire & Forget: false) and serves Update and Configuration Management as an entry point for initiating a software update [SWS_SM_91102]. Calling it initiates the transition into an active update session, which lasts until the update is terminated [SWS_SM_00210] [SWS_SM_00213].

Per machine, at most one port may be typed with interface UpdateRequest [SWS_SM_CONSTR_00020], which may only be provided by a process controlling a StateMachine of type Controller [SWS_SM_00629]. To ensure platform consistency, only a single update session may be active at any time [SWS_SM_00210]. Additionally, State Management persists the session state so that it can be read out after a machine reboot [SWS_SM_00204].

Successful acceptance of the session is a strict ordering constraint: subsequent methods such as PrepareUpdate [SWS_SM_91103], ResetMachine [SWS_SM_91100], or StopUpdateSession [SWS_SM_91101] require that RequestUpdateSession was previously called successfully [SWS_SM_00213].

In case of an error, two application-specific errors are defined [SWS_SM_91102]: If the method is called during an already ongoing session, it returns kNotAllowedMultipleUpdateSessions [SWS_SM_00209]. If verification (e.g. via interface UpdateAllowed) shows that the machine currently does not allow an update, the request is rejected with error kOperationRejected [SWS_SM_00630].

The service method ResetMachine in the service interface UpdateRequest is called by Update and Configuration Management (UCM) to request a restart of the machine during an ongoing update session [SWS_SM_91100]. The method has no input parameters and is declared with fire-and-forget semantics [SWS_SM_91100].

Before performing the restart, all machine-internal information must be stored persistently [SWS_SM_91100]. For this purpose, State Management backs up the data of the active update session so that UCM can consistently continue the update procedure after the machine restarts [SWS_SM_00204]. When calling the method, the controlling process transitions the StateMachine of type Controller into the state Restart [SWS_SM_00658]. After the machine restart has occurred, the Controller transitions into the state ContinueUpdate to resume the update SWS StateManagement §7.2 “ResetMachine notification”.

For synchronization and tracking of execution, State Management provides the field ResetMachineNotifier [SWS_SM_00211] [SWS_SM_91106], whose initial value is kIdle [SWS_SM_00212]. Since ResetMachine is designed as a fire-and-forget call, UCM is likely to monitor the result of the restart primarily asynchronously via this notifier (interpretation). Question Q-732913d75d024929 (open)

If an update session was not successfully established beforehand via RequestUpdateSession, the call is rejected and returns the error kOperationRejected [SWS_SM_91100]. In the event of a call outside an update session, the process additionally sets the value of the field ResetMachineNotifier to kRejected [SWS_SM_00661].

The service field ResetMachineNotifier of type UpdateStatusType [SWS_SM_91027] belongs to the service interface UpdateRequest and serves to enable Update and Configuration Management (UCM) to track the status of the method ResetMachine during and after its execution [SWS_SM_00211] [SWS_SM_91106]. The field provides a getter and a notifier, but has no setter [SWS_SM_91106]. UCM is typically expected to subscribe to the notifier in order to receive state changes asynchronously without polling after the machine restarts. Question Q-122f44b23cd76238 (open)

The lifecycle of the field comprises the following states and state transitions:

• Initial value: The default value of the field is kIdle [SWS_SM_00212].
• Rejection outside a session: If ResetMachine is called outside an active update session, the modeled controller process sets the field value to kRejected [SWS_SM_00661].
• Reset and continuation: Within an update session, ResetMachine leads to a transition to the state Restart [SWS_SM_00658]. After the machine boots up, State Management and UCM synchronize again. Upon successful completion of the transition to ContinueUpdate, the field is set to kSuccessful [SWS_SM_00662].
• Error case: If the execution of the transition to ContinueUpdate fails, the value of the field changes to kFailed [SWS_SM_00663].

If the update session is terminated via StopUpdateSession, the state machine transitions to the state AfterUpdate [SWS_SM_00646], and State Management resets the field ResetMachineNotifier back to the default value kIdle [SWS_SM_00660].

The service method StopUpdateSession of the service interface UpdateRequest ([SWS_SM_91101]) is called by Update and Configuration Management as soon as the update is completed and the machine is in a stable state. The call takes place without parameters and has synchronous or asynchronous request-response semantics (fire & forget is false).

Call Conditions and Error Handling

Execution requires a previously successfully started update session. If the call of StopUpdateSession occurs outside an active update session, the request is rejected and returns the error kOperationRejected ([SWS_SM_00213], [SWS_SM_91101]).

System Behavior and State Transitions

The call ends the ongoing update session (AUTOSAR_AP_SWS_StateManagement p. 90). In State Management, this triggers several coordinated actions:

• The modeled process that controls the StateMachine of type Controller transitions it into the state AfterUpdate ([SWS_SM_00646]).
• The field ResetMachineNotifier is reset to its default value ([SWS_SM_00660]).
• For StateMachine instances of type Controller, the blocking of RequestTransition is removed; subsequent calls no longer respond with kUpdateInProgress ([SWS_SM_00647]).
• The flag ImpactedByUpdate is removed from affected StateMachine instances ([SWS_SM_00656]), thereby releasing regular state transitions and recovery actions again.

Usage and Call Context

The service method VerifyUpdate is called by Update and Configuration Management (UCM) via the service interface UpdateRequest to instruct State Management to verify updated function groups [SWS_SM_00207]. The parameter passed is functionGroupList (type FunctionGroupListType), which contains the list of function groups to be checked in the respective SoftwareCluster [SWS_SM_91104]. Since the method is not defined as fire-and-forget (Fire & Forget: false), the caller expects a synchronous feedback or feedback available upon completion [SWS_SM_91104].

Sequence and Error Handling

The call is subject to strict state preconditions: It is only permitted within an active update session and requires that State Management has allowed the update and that phase PrepareUpdate has been completed successfully beforehand [SWS_SM_91104].

• kOperationRejected: Returned if the call occurs outside an active update session [SWS_SM_00213] or if the internal state of State Management or the participating state machines rejects verification (for example, if PrepareUpdate was not successful) [SWS_SM_91104].
• kOperationFailed: Indicates that the requested verification operation has failed [SWS_SM_91104].

Interaction and Concurrency

During processing, the controlling Modeled Process of a StateMachine of type Controller marks every state machine as ImpactedByUpdate whose managed function groups are listed in functionGroupList [SWS_SM_00654]. If this affects a StateMachine of type Agent, the associated Controller is also indirectly marked as ImpactedByUpdate [SWS_SM_00655]. As long as this state is active, reported execution errors (ExecutionErrorEvent::executionError) from Platform Health Management or Execution Management are ignored and merely logged [SWS_SM_00664]. Presumably, the affected state machines are transitioned during this step into state VerifyUpdate, which is among the five mandatory states of every StateMachine AUTOSAR_AP_SWS_StateManagement §7.7.1 “StateMachine introduction”. Question Q-cd5deaf13acfc2f5 (open)