ara::phm

Overview

The Platform Health Management Functional Cluster supervises application execution and drives recovery when a supervision fails. This page specifies the public API of the ara::phm namespace — the generated checkpoint headers, supervised entities, recovery actions, and the associated error domain — organized by header file.

Library · Headers · Linking

• Library: lib/libpara_phm.so
• CMake: find_package(para-phm) → para::phm
• Standard headers: include/ara/phm/
• Runtime daemon: bin/PHM

1 Header: ara/phm/supervised_entities/{<si-namespace-derived-directory-path-lower>}/{<phmssi-sn>}.h

Kind:	Header File
Syntax:	ara/phm/supervised_entities/{<si-namespace-derived-directory-path-lower>}/{<phmssi-sn>}.h
Description:	For each modeled PhmSupervisedEntityInterface a header file shall be generated according to this directory and path/file name convention - a multiple inclusion guard shall be placed around the whole header file as per SWS_CORE_90002.

Example:

// File=ara/phm/supervised_entities/n/n_p_1/n_p_2/si_checkpoint.h    (1)
#ifndef N_NPLUS1_NPLUS2_SI_CHECKPOINT_H_                            (2)
#define N_NPLUS1_NPLUS2_SI_CHECKPOINT_H_                            (2)
...
#endif // N_NPLUS1_NPLUS2_SI_CHECKPOINT_H_                          (2)

1.1 Namespaces

1.1.1 ara::phm::supervised_entities::{<hierarchical-namespace-list-lower-skeleton>}

Kind:	namespace
Header file:	#include "ara/phm/supervised_entities/{<si-namespace-derived-directory-path-lower>}/{<phmssi-sn>}.h"
Scope:	namespace ara::phm::supervised_entities
Syntax:	namespace ::{<hierarchical-namespace-list-lower-skeleton>}
Description:	The generator shall use the SymbolProps aggregated in the role PortInterface. PortInterface.namespace. For each PortInterface.namespace in the ordered list: PortInterface.namespace[N+1] shall be an inner namespace of PortInterface.namespace[N] converted to lower-case.

1.2 Non-Member Types

1.2.1 Enumeration: {<phmssi-sn>}

Kind:	enumeration
Header file:	#include "ara/phm/supervised_entities/{<si-namespace-derived-directory-path-lower>}/{<phmssi-sn>}.h"
Forwarding header file:	#include "ara/phm/phm_fwd.h"
Scope:	namespace ara::phm::supervised_entities::{<hierarchical-namespace-list-lower-skeleton>}
Symbol:	{<phmssi-sn>}
Underlying type:	std::uint32_t
Syntax:	enum class {<phmssi-sn>} : std::uint32_t {...};
Values:	{<phm-checkpoint-list>}	--
Description:	Defines the checkpoints for the ara::phm::PhmSupervisedEntityInterface

1.3 Global Variables

1.3.1 {<symbol-phm-checkpoint>}

Kind:	variable
Header file:	#include "ara/phm/supervised_entities/{<si-namespace-derived-directory-path-lower>}/{<phmssi-sn>}.h"
Scope:	namespace ara::phm::supervised_entities::{<hierarchical-namespace-list-lower-skeleton>}
Symbol:	{<symbol-phm-checkpoint>}
Type:	--
Syntax:	{<symbol-phm-checkpoint>} = {<phm-checkpoint-value>};
Description:	For each enumeration in {<phm-checkpoint-list>} in SWS_PHM_00424 there shall exist a C++ enumerator declaration.

Example:

enum class MyPhmCheckpoints : std::uint32_t {
  Initializing = 0U,
  StartupTest = 1U,
  InitializingFinished = 2U
};

2 Header: ara/phm/phm_error_domain.h

2.1 Non-Member Types

2.1.1 Enumeration: PhmErrc

Kind:	enumeration
Header file:	#include "ara/phm/phm_error_domain.h"
Forwarding header file:	#include "ara/phm/phm_fwd.h"
Scope:	namespace ara::phm
Symbol:	PhmErrc
Underlying type:	ara::core::ErrorDomain::CodeType
Syntax:	enum class PhmErrc : ara::core::ErrorDomain::CodeType {...};
Values:	kOfferFailed	= 2
		Service could not be offered due to failure of communication with Phm daemon
	kSMCanNotHandleRecovery	= 3
		State Management cannot handle the recovery and PlatformHealthManagement will take over by firing the watchdog.
	kServiceNotReady	= 4
		There is already an ongoing Enable or Disable request.
Description:	Defines an enumeration class for the Platform Health Management error codes.

2.2 Non-Member Functions

2.2.1 Other

2.2.1.1 GetPhmDomain

Kind:	function
Header file:	#include "ara/phm/phm_error_domain.h"
Scope:	namespace ara::phm
Syntax:	constexpr const ara::core::ErrorDomain & GetPhmDomain () noexcept;
Return value:	const ara::core::ErrorDomain &	The global PhmErrorDomain object.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	Returns the global PhmErrorDomain object.

2.2.1.2 MakeErrorCode

Kind:	function
Header file:	#include "ara/phm/phm_error_domain.h"
Scope:	namespace ara::phm
Syntax:	constexpr ara::core::ErrorCode MakeErrorCode (ara::phm::PhmErrc code, ara::core::ErrorDomain::SupportDataType data) noexcept;
Parameters (in):	code	Error code number.
	data	Vendor defined data associated with the error.
Return value:	ara::core::ErrorCode	An ErrorCode object.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	Creates an error code.

2.3 Class: PhmErrorDomain

Kind:	class
Header file:	#include "ara/phm/phm_error_domain.h"
Forwarding header file:	#include "ara/phm/phm_fwd.h"
Scope:	namespace ara::phm
Symbol:	PhmErrorDomain
Base class:	ara::core::ErrorDomain
Syntax:	class PhmErrorDomain final : public ara::core::ErrorDomain {...};
Description:	Defines the error domain for Platform Health Management.

2.3.1 Public Member Types

2.3.1.1 Type Alias: Errc

Kind:	type alias
Header file:	#include "ara/phm/phm_error_domain.h"
Scope:	ara::phm::PhmErrorDomain
Symbol:	Errc
Syntax:	using Errc = PhmErrc;
Description:	Alias for the error code value enumeration.

2.3.1.2 Type Alias: Exception

Kind:	type alias
Header file:	#include "ara/phm/phm_error_domain.h"
Scope:	ara::phm::PhmErrorDomain
Symbol:	Exception
Syntax:	using Exception = PhmException;
Description:	Alias for the exception base class.

2.3.2 Public Member Functions

2.3.2.1 Special Member Functions

2.3.2.1.1 Default Constructor

Kind:	function
Header file:	#include "ara/phm/phm_error_domain.h"
Scope:	ara::phm::PhmErrorDomain
Syntax:	PhmErrorDomain () noexcept;
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	Creates a PhmErrorDomain instance.

2.3.2.2 Member Functions

2.3.2.2.1 Message

Kind:	function
Header file:	#include "ara/phm/phm_error_domain.h"
Scope:	ara::phm::PhmErrorDomain
Syntax:	const char * Message (CodeType errorCode) const noexcept override;
Parameters (in):	errorCode	The error code number.
Return value:	const char *	The message associated with the error code.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	Returns the message associated with the error code.

2.3.2.2.2 Name

Kind:	function
Header file:	#include "ara/phm/phm_error_domain.h"
Scope:	ara::phm::PhmErrorDomain
Syntax:	const char * Name () const noexcept override;
Return value:	const char *	As per ara::phm::PhmErrorDomain in SWS_CORE_90023
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	Returns the name of the error domain.

2.3.2.2.3 ThrowAsException

Kind:	function
Header file:	#include "ara/phm/phm_error_domain.h"
Scope:	ara::phm::PhmErrorDomain
Syntax:	void ThrowAsException (const ara::core::ErrorCode &errorCode) const override;
Parameters (in):	errorCode	The error to throw.
Return value:	None
Exception Safety:	not exception safe
Thread Safety:	thread-safe
Description:	Throws the exception associated with the error code. As per SWS_CORE_10304, this function does not participate in overload resolution when C++ exceptions are disabled in the compiler toolchain.

2.4 Class: PhmException

Kind:	class
Header file:	#include "ara/phm/phm_error_domain.h"
Forwarding header file:	#include "ara/phm/phm_fwd.h"
Scope:	namespace ara::phm
Symbol:	PhmException
Base class:	ara::core::Exception
Syntax:	class PhmException : public ara::core::Exception {...};
Description:	Exception type thrown by Platform Health Management.

2.4.1 Public Member Functions

2.4.1.1 Constructors

2.4.1.1.1 PhmException

Kind:	function
Header file:	#include "ara/phm/phm_error_domain.h"
Scope:	ara::phm::PhmException
Syntax:	explicit PhmException (ara::core::ErrorCode errorCode) noexcept;
Parameters (in):	errorCode	The error code.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	Construct a new PlatformHealthManagement exception object containing an error code.

3 Header: ara/phm/recovery_action.h

3.1 Non-Member Types

3.1.1 Enumeration: TypeOfSupervision

Kind:	enumeration
Header file:	#include "ara/phm/recovery_action.h"
Forwarding header file:	#include "ara/phm/phm_fwd.h"
Scope:	namespace ara::phm
Symbol:	TypeOfSupervision
Underlying type:	std::uint32_t
Syntax:	enum class TypeOfSupervision : std::uint32_t {...};
Values:	kAliveSupervision	= 0
		Supervision is of type AliveSupervision.
	kDeadlineSupervision	= 1
		Supervision is of type DeadlineSupervision.
	kLogicalSupervision	= 2
		Supervision is of type LogicalSupervision.
Description:	Enumeration of type of supervision. Scoped Enumeration of uint32_t.

3.2 Class: RecoveryAction

Kind:	class
Port Interfaces:	PhmSupervisionRecoveryNotificationInterface
Header file:	#include "ara/phm/recovery_action.h"
Forwarding header file:	#include "ara/phm/phm_fwd.h"
Scope:	namespace ara::phm
Symbol:	RecoveryAction
Syntax:	class RecoveryAction {...};
Description:	RecoveryAction abstract class.

3.2.1 Public Member Functions

3.2.1.1 Special Member Functions

3.2.1.1.1 Copy Constructor

Kind:	function
Header file:	#include "ara/phm/recovery_action.h"
Scope:	ara::phm::RecoveryAction
Syntax:	RecoveryAction (const RecoveryAction &)=delete;
Description:	The copy constructor for RecoveryAction shall not be used.

3.2.1.1.2 Move Constructor

Kind:	function
Header file:	#include "ara/phm/recovery_action.h"
Scope:	ara::phm::RecoveryAction
Syntax:	RecoveryAction (RecoveryAction &&ra)=delete;
Description:	The move constructor operator for the RecoveryAction shall not be used. Rationale: Using the move constructor after a RecoveryAction instance has been offered may result in premature invocation of RecoveryHandler before the derived class is fully constructed. This can lead to undefined behavior or unhandled exceptions, compromising system stability and safety

3.2.1.1.3 Copy Assignment Operator

Kind:	function
Header file:	#include "ara/phm/recovery_action.h"
Scope:	ara::phm::RecoveryAction
Syntax:	ara::phm::RecoveryAction & operator= (const ara::phm::RecoveryAction &)=delete;
Description:	The copy assignment operator for RecoveryAction shall not be used.

3.2.1.1.4 Move Assignment Operator

Kind:	function
Header file:	#include "ara/phm/recovery_action.h"
Scope:	ara::phm::RecoveryAction
Syntax:	ara::phm::RecoveryAction & operator= (ara::phm::RecoveryAction &&ra)=delete;
Description:	The move assignment operator for the RecoveryAction shall not be used. Rationale: Using the move assignment after a RecoveryAction instance has been offered may result in premature invocation of RecoveryHandler before the derived class is fully constructed. This can lead to undefined behavior or unhandled exceptions, compromising system stability and safety.

3.2.1.1.5 Destructor

Kind:	function
Header file:	#include "ara/phm/recovery_action.h"
Scope:	ara::phm::RecoveryAction
Syntax:	virtual ~RecoveryAction () noexcept;
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	Destructor for RecoveryAction.

3.2.1.2 Constructors

3.2.1.2.1 RecoveryAction

Kind:	function
Header file:	#include "ara/phm/recovery_action.h"
Scope:	ara::phm::RecoveryAction
Syntax:	explicit RecoveryAction (const ara::core::InstanceSpecifier &instance) noexcept;
Parameters (in):	instance	instance specifier to the PPortPrototype of a PhmRecoveryActionInterface
Exception Safety:	exception safe
Thread Safety:	thread-safe
Violations:	AraNotInitializedViolation	Violation message that is sent in case a constructor or function checks for an initialized ara and identifies that ara is not initialized.
	InstanceSpecifierMappingIntegrityViolation	InstanceSpecifier either cannot be resolved in the model in the context of your executable, or it refers to a model element other than a PortPrototype.
	PortInterfaceMappingViolation	A PortPrototype that is referenced by a RecoveryNotificationToPPortPrototypeMapping needs to be typed by a PhmSupervisionRecoveryNotificationInterface.
	ProcessMappingViolation	Matching InstanceRef exists, but no matching (modelled) Process found that matches the (runtime) process.
	InstanceSpecifierAlreadyInUseViolation	Violation message that is sent in case a constructor in the ara framework was called with an InstanceSpecifier already in use in this process.
Description:	Creation of an RecoveryAction.

3.2.1.3 Member Functions

3.2.1.3.1 Offer

Kind:	function
Header file:	#include "ara/phm/recovery_action.h"
Scope:	ara::phm::RecoveryAction
Syntax:	ara::core::Result< void > Offer () noexcept;
Return value:	ara::core::Result< void >	A Result, being either empty or containing any of the errors defined below.
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Errors:	PhmErrc::kOfferFailed	rollback_semantics
		Service could not be offered due to failure of communication with Phm daemon
Description:	Enables potential invocations of RecoveryHandler.

3.2.1.3.2 RecoveryHandler

Kind:	function
Header file:	#include "ara/phm/recovery_action.h"
Scope:	ara::phm::RecoveryAction
Syntax:	virtual ara::core::Future< void > RecoveryHandler (const ara::exec::ExecutionErrorEvent &executionError, ara::phm::TypeOfSupervision supervision) noexcept=0;
Parameters (in):	executionError	Information on detected error, shall give further information for error recovery.
	supervision	The type of elementary supervision which failed.
Return value:	ara::core::Future< void >	void if recovery is successful, otherwise it returns kSMCanNotHandleRecovery error
Exception Safety:	exception safe
Thread Safety:	thread-safe
Errors:	PhmErrc::kSMCanNotHandleRecovery	rollback_semantics
		State Management cannot handle the recovery and PlatformHealthManagement will take over by firing the watchdog.
Description:	RecoveryHandler to be invoked by PHM. The handler invocation needs to be enabled before by a call of RecoveryAction::Offer.

3.2.1.3.3 StopOffer

Kind:	function
Header file:	#include "ara/phm/recovery_action.h"
Scope:	ara::phm::RecoveryAction
Syntax:	void StopOffer () noexcept;
Return value:	None
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	Disables invocations of RecoveryHandler.

4 Header: ara/phm/supervised_entity.h

4.1 Non-Member Types

4.1.1 Enumeration: ElementarySupervisionStatus

Kind:	enumeration
Header file:	#include "ara/phm/supervised_entity.h"
Forwarding header file:	#include "ara/phm/phm_fwd.h"
Scope:	namespace ara::phm
Symbol:	ElementarySupervisionStatus
Underlying type:	std::uint32_t
Syntax:	enum class ElementarySupervisionStatus : std::uint32_t {...};
Values:	kOK	= 0
		Supervision is active and no failure is present.
	kFailed	= 1
		A failure was detected but still within tolerance/debouncing.
	kExpired	= 2
		A failure was detected and qualified.
	kDeactivated	= 4
		Supervision is not active.
Description:	Enumeration of elementary supervision status. Scoped Enumeration of uint32_t.

4.1.2 Enumeration: GlobalSupervisionStatus

Kind:	enumeration
Header file:	#include "ara/phm/supervised_entity.h"
Forwarding header file:	#include "ara/phm/phm_fwd.h"
Scope:	namespace ara::phm
Symbol:	GlobalSupervisionStatus
Underlying type:	std::uint32_t
Syntax:	enum class GlobalSupervisionStatus : std::uint32_t {...};
Values:	kOK	= 0
		At least one Elementary Supervision corresponding to the Global Supervision is in status kOK and none in status kFailed or kExpired.
	kFailed	= 1
		At least one Elementary Supervision corresponding to the Global Supervision is in status kFailed but none in status kExpired.
	kExpired	= 2
		At least one Elementary Supervision corresponding to the Global Supervision is in status kExpired but the time elapsed since reaching kExpired has not exceeded the tolerance.
	kStopped	= 3
		At least one Elementary Supervision corresponding to the Global Supervision is in status kExpired and the time elapsed since reaching kExpired has exceeded the tolerance.
	kDeactivated	= 4
		All Elementary Supervisions corresponding to the Global Supervision are in status kDeactivated.
Description:	Enumeration of global supervision status. Scoped Enumeration of uint32_t.

4.2 Class: SupervisedEntity

Kind:	class
Port Interfaces:	PhmSupervisedEntityInterface
Header file:	#include "ara/phm/supervised_entity.h"
Forwarding header file:	#include "ara/phm/phm_fwd.h"
Scope:	namespace ara::phm
Symbol:	SupervisedEntity
Syntax:	template <typename EnumT> class SupervisedEntity final {...};
Template param:	EnumT	An enum type that contains a list of checkpoint identifier
Description:	SupervisedEntity Class.

4.2.1 Public Member Functions

4.2.1.1 Special Member Functions

4.2.1.1.1 Copy Constructor

Kind:	function
Header file:	#include "ara/phm/supervised_entity.h"
Scope:	ara::phm::SupervisedEntity
Syntax:	SupervisedEntity (const SupervisedEntity &se)=delete;
Description:	The copy constructor for SupervisedEntity shall not be used.

4.2.1.1.2 Move Constructor

Kind:	function
Header file:	#include "ara/phm/supervised_entity.h"
Scope:	ara::phm::SupervisedEntity
Syntax:	SupervisedEntity (SupervisedEntity &&se) noexcept;
Parameters (in):	se	The SupervisedEntity object to be moved.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	Move constructor for SupervisedEntity.

4.2.1.1.3 Move Assignment Operator

Kind:	function
Header file:	#include "ara/phm/supervised_entity.h"
Scope:	ara::phm::SupervisedEntity
Syntax:	ara::phm::SupervisedEntity & operator= (ara::phm::SupervisedEntity &&se) noexcept;
Parameters (in):	se	The SupervisedEntity object to be moved.
Return value:	SupervisedEntity &	The moved SupervisedEntity object.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Description:	Move assignment operator for SupervisedEntity.

4.2.1.1.4 Copy Assignment Operator

Kind:	function
Header file:	#include "ara/phm/supervised_entity.h"
Scope:	ara::phm::SupervisedEntity
Syntax:	ara::phm::SupervisedEntity & operator= (const ara::phm::SupervisedEntity &se)=delete;
Description:	The copy assignment operator for SupervisedEntity shall not be used.

4.2.1.1.5 Destructor

Kind:	function
Header file:	#include "ara/phm/supervised_entity.h"
Scope:	ara::phm::SupervisedEntity
Syntax:	~SupervisedEntity () noexcept;
Exception Safety:	exception safe
Thread Safety:	not thread-safe
Description:	Destructor of a SupervisedEntity.

4.2.1.2 Constructors

4.2.1.2.1 SupervisedEntity

Kind:	function
Header file:	#include "ara/phm/supervised_entity.h"
Scope:	ara::phm::SupervisedEntity
Syntax:	explicit SupervisedEntity (const ara::core::InstanceSpecifier &instance) noexcept;
Parameters (in):	instance	instance specifier of the supervised entity.
Exception Safety:	exception safe
Thread Safety:	thread-safe
Violations:	AraNotInitializedViolation	Violation message that is sent in case a constructor or function checks for an initialized ara and identifies that ara is not initialized.
	InstanceSpecifierMappingIntegrityViolation	InstanceSpecifier either cannot be resolved in the model in the context of your executable, or it refers to a model element other than a PortPrototype.
	PortInterfaceMappingViolation	A PortPrototype that is typed by a PhmSupervisedEntityInterface needs to be referenced by a SupervisionCheckpoint.
	ProcessMappingViolation	A wrong process is trying to create this SupervisedEntity object (i.e. none of the corresponding SupervisionCheckpoint references includes a reference to the current process).
	InstanceSpecifierAlreadyInUseViolation	Violation message that is sent in case a constructor in the ara framework was called with an InstanceSpecifier already in use in this process.
Description:	Creation of a SupervisedEntity.

4.2.1.3 Member Functions

4.2.1.3.1 Disable

Kind:	function
Header file:	#include "ara/phm/supervised_entity.h"
Scope:	ara::phm::SupervisedEntity
Syntax:	ara::core::Future< void > Disable () noexcept;
Return value:	ara::core::Future< void >	void if successful, otherwise an error
Exception Safety:	exception safe
Thread Safety:	not-threadsafe
Errors:	PhmErrc::kServiceNotReady	rollback_semantics
		There is already an ongoing Enable or Disable request.
Description:	Disable supervision until Enable() is called.

4.2.1.3.2 Enable

Kind:	function
Header file:	#include "ara/phm/supervised_entity.h"
Scope:	ara::phm::SupervisedEntity
Syntax:	ara::core::Future< void > Enable () noexcept;
Return value:	ara::core::Future< void >	void if successful, otherwise an error
Exception Safety:	exception safe
Thread Safety:	not-threadsafe
Errors:	PhmErrc::kServiceNotReady	rollback_semantics
		There is already an ongoing Enable or Disable request.
Description:	Enable supervision, if possible in the current function group state.

4.2.1.3.3 ReportCheckpoint

Kind:	function
Header file:	#include "ara/phm/supervised_entity.h"
Scope:	ara::phm::SupervisedEntity
Syntax:	void ReportCheckpoint (EnumT checkpointId) noexcept;
Parameters (in):	checkpointId	checkpoint identifier.
Return value:	None
Exception Safety:	exception safe
Thread Safety:	thread-safe
Violations:	InsufficientPermissionsViolation	ReportCheckpoint was invoked by a process which is not modelled by the corresponding SupervisionCheckpoint.SupervisionCheckpoint.process reference.
Description:	Reports an occurrence of a Checkpoint.

See also

• Supervision and recovery in the runtime model: PARA Overview
• Supervised entity configuration: PhmSupervisedEntityInterface, Supervision configuration