namespace ara::phm

Namespace ara::phm provides mechanisms for runtime monitoring of software entities regarding alive status, deadlines, and control flow on the Adaptive Platform [SWS_PHM_01138]. Detected anomalies undergo multi-stage error qualification from debouncing to system shutdown [SWS_PHM_01137]. For errors that cannot be resolved by State Management, the module takes over error reaction and actuates the system watchdog [SWS_PHM_01240].

more ›

Context

Namespace ara::phm represents the C++ interface of Platform Health Management (PHM) within the AUTOSAR Adaptive Platform. Its central task is the functional monitoring of software units to ensure system integrity. SupervisedEntity, which represent monitored functional processes, and abstract class RecoveryAction, via which application recovery actions can be defined, act as primary entities. Monitoring is subdivided via enumeration TypeOfSupervision [SWS_PHM_01138] into three fundamental mechanisms: cyclic alive supervision (kAliveSupervision), compliance with timing limits between checkpoints (kDeadlineSupervision), and verification of correct execution order (kLogicalSupervision).

In the overall system, ara::phm not only interacts with the utilizing processes, but communicates closely with the PHM daemon and State Management (SM). If State Management cannot perform a necessary recovery, Platform Health Management escalates remediation directly to the hardware or system watchdog [SWS_PHM_01240].

Context diagram: Interaction between SupervisedEntity, PHM daemon, State Management, RecoveryAction, and watchdog. Sources: [SWS_PHM_01138], [SWS_PHM_01240]

Lifecycle

The lifecycle and state model of Platform Health Management is structured in two stages and distinguishes between elementary and global monitoring states. An individual monitoring function assumes states according to ElementarySupervisionStatus [SWS_PHM_01358]: In the inactive state it remains in kDeactivated, after activation without errors in kOK. If an anomaly occurs, it initially transitions to kFailed as long as the error is still within configured tolerances or debouncing times. Only after debouncing has expired is the error considered qualified and the status transitions to kExpired [SWS_PHM_01358].

The overall assessment of multiple elementary monitorings is aggregated in GlobalSupervisionStatus [SWS_PHM_01137]. If all assigned monitorings are inactive, the global state is in kDeactivated. As soon as at least one monitoring reports kOK and none is faulty, the overall status is kOK. If at least one monitoring is in kFailed and none in kExpired, this is reflected in global state kFailed. If a monitoring reaches the qualified error state kExpired, the global status remains in kExpired as long as the defined tolerance time has not expired. After this tolerance period has elapsed, the system transitions to the final state kStopped [SWS_PHM_01137].

State diagram: State transitions of global supervision depending on error detection and tolerance times. Sources: [SWS_PHM_01137], [SWS_PHM_01358]

Usage Path

In a typical integration order, an application includes the classes of the namespace via #include "ara/phm/supervised_entity.h" or the forwarding header #include "ara/phm/phm_fwd.h" [SWS_PHM_01358]. The application instantiates and manages an object of SupervisedEntity, which represents the functional execution to be safeguarded. Interpretation: Via this object, the application reports its alive indications or control flow events to Platform Health Management during regular operation. Question (open)

The PHM daemon continuously matches the reported events against the parameterized criteria for kAliveSupervision, kDeadlineSupervision, or kLogicalSupervision [SWS_PHM_01138]. As long as all signals arrive on time and according to rules, the evaluation remains in state kOK [SWS_PHM_01358]. If limit values are violated, the monitoring passes through error qualification and initiates the configured recovery upon reaching kExpired or kStopped [SWS_PHM_01137]. Interface RecoveryAction is used here, presumably to execute application-specific countermeasures in a structured manner before escalation to State Management occurs. Question (open)

Error Scenarios

Specific error states within the module are standardized via error domain PhmErrorDomain and enumeration PhmErrc [SWS_PHM_01240]. The enumeration defines the following error codes:

• PhmErrc::kOfferFailed (= 2): The service could not be offered due to failed communication with the PHM daemon [SWS_PHM_01240].
• PhmErrc::kSMCanNotHandleRecovery (= 3): State Management cannot handle the requested recovery; Platform Health Management then takes over recovery and triggers the watchdog [SWS_PHM_01240].
• PhmErrc::kServiceNotReady (= 4): A request cannot be executed because an enable/disable request is already active [SWS_PHM_01240].

To create suitable error objects, the namespace provides the helper function MakeErrorCode, which constructs a ara::core::ErrorCode from a PhmErrc and vendor-specific supplementary data [SWS_PHM_01244]. The reference to the global error domain can be obtained via GetPhmDomain [SWS_PHM_01251]. Both functions are declared as constexpr and noexcept and guarantee exception safety and thread safety [SWS_PHM_01244], [SWS_PHM_01251]. In the event of a synchronous error or exceptions in the module, exception type PhmException is also used.