(8a1a5fe)

Alert handler Device Interface Functions More...

#include <stdint.h>
#include "sw/device/lib/base/macros.h"
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_base.h"
#include "sw/device/lib/dif/autogen/dif_alert_handler_autogen.h"

Go to the source code of this file.

Data Structures
struct	dif_alert_handler_escalation_phase
	Runtime configuration for an escalation phase. More...

struct	dif_alert_handler_class_config
	Runtime configuration for a particular alert class. More...

struct	dif_alert_handler_config
	Runtime configuration for the alert handler. More...

Macros
#define	LIST_OF_CLASSES(X)
	Helper X macro for defining enums and case statements related to alert classes. More...

#define	ALERT_CLASS_ENUM_INIT_(class_, value_) kDifAlertHandlerClass##class_ = value_,
	Helper macro for defining a `dif_alert_handler_class_t` enumeration constant. More...

#define	LIST_OF_LOC_ALERTS(X)
	Helper X macro for defining enums and case statements related to local alerts. More...

#define	LOC_ALERT_ENUM_INIT_(name_, value_) name_ = value_,
	Helper macro for defining a `dif_alert_handler_local_alert_t` enumeration constant. More...

Typedefs
typedef enum dif_alert_handler_class	dif_alert_handler_class_t
	An alert class. More...

typedef uint32_t	dif_alert_handler_alert_t
	An alert, identified by a numeric id. More...

typedef enum dif_alert_handler_local_alert	dif_alert_handler_local_alert_t
	A local alert originating from within the alert handler itself. More...

typedef enum dif_alert_handler_class_state	dif_alert_handler_class_state_t
	An alert class state. More...

typedef uint32_t	dif_alert_handler_escalation_signal_t
	An escalation signal, identified by a numeric ID. More...

typedef struct dif_alert_handler_escalation_phase	dif_alert_handler_escalation_phase_t
	Runtime configuration for an escalation phase.

typedef struct dif_alert_handler_class_config	dif_alert_handler_class_config_t
	Runtime configuration for a particular alert class. More...

typedef struct dif_alert_handler_config	dif_alert_handler_config_t
	Runtime configuration for the alert handler. More...

Enumerations
enum	dif_alert_handler_class
	An alert class. More...

enum	dif_alert_handler_local_alert
	A local alert originating from within the alert handler itself. More...

enum	dif_alert_handler_class_state { kDifAlertHandlerClassStateIdle, kDifAlertHandlerClassStateTimeout, kDifAlertHandlerClassStateFsmError, kDifAlertHandlerClassStateTerminal, kDifAlertHandlerClassStatePhase0, kDifAlertHandlerClassStatePhase1, kDifAlertHandlerClassStatePhase2, kDifAlertHandlerClassStatePhase3 }
	An alert class state. More...

Functions
OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_configure_alert (const dif_alert_handler_t *alert_handler, dif_alert_handler_alert_t alert, dif_alert_handler_class_t alert_class, dif_toggle_t enabled, dif_toggle_t locked)
	Configures an alert in the alert handler. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_configure_local_alert (const dif_alert_handler_t *alert_handler, dif_alert_handler_local_alert_t local_alert, dif_alert_handler_class_t alert_class, dif_toggle_t enabled, dif_toggle_t locked)
	Configures a local alert in the alert handler. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_configure_class (const dif_alert_handler_t *alert_handler, dif_alert_handler_class_t alert_class, dif_alert_handler_class_config_t config, dif_toggle_t enabled, dif_toggle_t locked)
	Configures the escalation protocol of an alert class in the alert handler. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_configure_ping_timer (const dif_alert_handler_t *alert_handler, uint32_t ping_timeout, dif_toggle_t enabled, dif_toggle_t locked)
	Configures the ping timer in the alert handler. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_ping_timer_set_enabled (const dif_alert_handler_t *alert_handler, dif_toggle_t locked)
	Enables the ping timer in the alert handler. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_lock_alert (const dif_alert_handler_t *alert_handler, dif_alert_handler_alert_t alert)
	Locks out an alert handler alert configuration. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_is_alert_locked (const dif_alert_handler_t alert_handler, dif_alert_handler_alert_t alert, bool is_locked)
	Checks whether an alert handler's alert is locked. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_lock_local_alert (const dif_alert_handler_t *alert_handler, dif_alert_handler_local_alert_t local_alert)
	Locks out an alert handler local alert configuration. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_is_local_alert_locked (const dif_alert_handler_t alert_handler, dif_alert_handler_local_alert_t local_alert, bool is_locked)
	Checks whether an alert handler's local alert is locked. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_lock_class (const dif_alert_handler_t *alert_handler, dif_alert_handler_class_t alert_class)
	Locks out an alert handler class configuration. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_is_class_locked (const dif_alert_handler_t alert_handler, dif_alert_handler_class_t alert_class, bool is_locked)
	Checks whether an alert handler's class is locked. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_lock_ping_timer (const dif_alert_handler_t *alert_handler)
	Locks out alert handler ping timer configuration. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_is_ping_timer_locked (const dif_alert_handler_t alert_handler, bool is_locked)
	Checks whether alert handler's ping timer is locked. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_alert_is_cause (const dif_alert_handler_t alert_handler, dif_alert_handler_alert_t alert, bool is_cause)
	Checks whether an alert is one of the causes for an alert IRQ. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_alert_acknowledge (const dif_alert_handler_t *alert_handler, dif_alert_handler_alert_t alert)
	Clears an alert from the cause vector, similar to an IRQ acknowledgement. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_local_alert_is_cause (const dif_alert_handler_t alert_handler, dif_alert_handler_local_alert_t local_alert, bool is_cause)
	Checks whether a local alert is one of the causes for an alert IRQ. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_local_alert_acknowledge (const dif_alert_handler_t *alert_handler, dif_alert_handler_local_alert_t local_alert)
	Clears a local alert from the cause vector, similar to an IRQ acknowledgement. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_escalation_can_clear (const dif_alert_handler_t alert_handler, dif_alert_handler_class_t alert_class, bool can_clear)
	Checks whether software can clear escalations for this class. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_escalation_disable_clearing (const dif_alert_handler_t *alert_handler, dif_alert_handler_class_t alert_class)
	Disables escalation clearing for this class. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_escalation_clear (const dif_alert_handler_t *alert_handler, dif_alert_handler_class_t alert_class)
	Clears an on-going escalation, as well as the class accumulator. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_get_accumulator (const dif_alert_handler_t alert_handler, dif_alert_handler_class_t alert_class, uint16_t num_alerts)
	Gets the accumulator value for this class. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_get_escalation_counter (const dif_alert_handler_t alert_handler, dif_alert_handler_class_t alert_class, uint32_t cycles)
	Gets the current value of the "escalation counter". More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_alert_handler_get_class_state (const dif_alert_handler_t alert_handler, dif_alert_handler_class_t alert_class, dif_alert_handler_class_state_t state)
	Gets the current state of this class. More...

Detailed Description

Alert handler Device Interface Functions

Definition in file dif_alert_handler.h.

Data Structure Documentation

◆ dif_alert_handler_escalation_phase

struct dif_alert_handler_escalation_phase

Runtime configuration for an escalation phase.

Definition at line 179 of file dif_alert_handler.h.

Data Fields
uint32_t	duration_cycles	The duration of this phase, in cycles.
dif_alert_handler_class_state_t	phase	The phase this configuration describes. It is an error for this to not be one of the `Phase` constants in `dif_alert_handler_class_state_t`.
dif_alert_handler_escalation_signal_t	signal	The escalation signal that should be triggered when this phase begins.

◆ dif_alert_handler_class_config

struct dif_alert_handler_class_config

Runtime configuration for a particular alert class.

This struct describes the escalation protocol for an alert class.

Definition at line 202 of file dif_alert_handler.h.

Data Fields
uint16_t	accumulator_threshold	The threshold for the class accmulator which indicates the number of alerts that must fire because the class's escalation protocol will trigger.
dif_toggle_t	auto_lock_accumulation_counter	Whether to automatically lock the accumulation counter. There are two ways to lock the accumulation counter (prevent it from being cleared once the class's escalation protocol has been triggered): clear the write enable for the accumulation counter clear register, or to set this configuration flag which will automatically clear the write enable for the accumulation counter clear register once the class's escalation protocol has been triggered.
dif_alert_handler_class_state_t	crashdump_escalation_phase	The escalation phase to capture the crashdump information in. It is an error for this to not be one of the `Phase` constants in `dif_alert_handler_class_state_t`. Note, it is recommended to capture the crashdump upon entering the first escalation phase that activates a countermeasure with many side-effects (e.g. life cycle state scrapping) in order to prevent spurious alert events from masking the original alert causes.
const dif_alert_handler_escalation_phase_t *	escalation_phases	Escalation phases to be configured for this class. Each escalation phase in this list will additionally be set as enabled for this class; phases not listed will have their escalation signals disabled.
size_t	escalation_phases_len	The length of the array `escalation_phases`.
uint32_t	irq_deadline_cycles	The number of cycles this class's associated IRQ handler has to acknowledge the IRQ before escalation is triggered. A value of zero disables the timeout.

◆ dif_alert_handler_config

struct dif_alert_handler_config

Runtime configuration for the alert handler.

This struct describes runtime information for a single-shot configuration of the alert handler hardware.

Note, any of the array pointers may be NULL, in which case the associated length should be 0.

Definition at line 260 of file dif_alert_handler.h.

Data Fields
dif_alert_handler_class_t *	alert_classes	A list of classes to assign each alert to.
dif_alert_handler_alert_t *	alerts	A list of alerts to configure.
size_t	alerts_len	The lengths of the arrays `alerts` and `alert_classes`.
const dif_alert_handler_class_config_t *	class_configs	A list of alert class (escalation protocol) configurations.
const dif_alert_handler_class_t *	classes	A list of alert classes to configure.
size_t	classes_len	The length of the arrays `classes` and `class_configs`.
dif_alert_handler_class_t *	local_alert_classes	A list of classes to assign each local alert to.
dif_alert_handler_local_alert_t *	local_alerts	A list of local alerts to configure.
size_t	local_alerts_len	The lengths of the arrays `local_alerts` and `local_alert_classes`.
uint32_t	ping_timeout	The alert ping timeout, in cycles. The alert handler will regularly, at random intervals, ping alert sources. If a source fails to respond, a local alert will be raised. The appropriate value will be dependent on all of the clocks involved on a chip. Note that the ping timer won't start until `dif_alert_handler_lock()` is successfully called. Note while this value must fit into the timeout register which is smaller than the native word length.

Macro Definition Documentation

◆ ALERT_CLASS_ENUM_INIT_

#define ALERT_CLASS_ENUM_INIT_	(	class_,
		value_
	)	kDifAlertHandlerClass##class_ = value_,

Helper macro for defining a dif_alert_handler_class_t enumeration constant.

@class_ Alert class of the enumeration constant. @value_ Value of the enumeration constant.

Definition at line 42 of file dif_alert_handler.h.

◆ LIST_OF_CLASSES

#define LIST_OF_CLASSES ( X )

Value:

  X(A, 0)                  \
  X(B, 1)                  \
  X(C, 2)                  \
  X(D, 3)

Helper X macro for defining enums and case statements related to alert classes.

If an additional class is ever added to the hardware, this list can be updated.

Definition at line 31 of file dif_alert_handler.h.

◆ LIST_OF_LOC_ALERTS

#define LIST_OF_LOC_ALERTS ( X )

Value:

  X(kDifAlertHandlerLocalAlertAlertPingFail, 0)           \
  X(kDifAlertHandlerLocalAlertEscalationPingFail, 1)      \
  X(kDifAlertHandlerLocalAlertAlertIntegrityFail, 2)      \
  X(kDifAlertHandlerLocalAlertEscalationIntegrityFail, 3) \
  X(kDifAlertHandlerLocalAlertBusIntegrityFail, 4)        \
  X(kDifAlertHandlerLocalAlertShadowedUpdateError, 5)     \
  X(kDifAlertHandlerLocalAlertShadowedStorageError, 6)

Helper X macro for defining enums and case statements related to local alerts.

If an additional class is ever added to the hardware, this list can be updated.

Definition at line 78 of file dif_alert_handler.h.

◆ LOC_ALERT_ENUM_INIT_

#define LOC_ALERT_ENUM_INIT_	(	name_,
		value_
	)	name_ = value_,

Helper macro for defining a dif_alert_handler_local_alert_t enumeration constant.

@name_ Name of the enumeration constant.

Definition at line 92 of file dif_alert_handler.h.

Typedef Documentation

◆ dif_alert_handler_alert_t

typedef uint32_t dif_alert_handler_alert_t

An alert, identified by a numeric id.

Alerts are hardware-level events indicating that something catastrophic has happened. The alert handler consumes alerts, classifies them into a particular dif_alert_handler_class_t, and uses policy information attached to that class to handle it.

The number of alerts is configurable at hardware-synthesis time.

Definition at line 71 of file dif_alert_handler.h.

◆ dif_alert_handler_class_config_t

typedef struct dif_alert_handler_class_config dif_alert_handler_class_config_t

Runtime configuration for a particular alert class.

This struct describes the escalation protocol for an alert class.

◆ dif_alert_handler_class_state_t

typedef enum dif_alert_handler_class_state dif_alert_handler_class_state_t

An alert class state.

This enum describes the sequence of states in the escalation protocol, which triggers under two different conditions:

If too many alerts of a particular class accumulate.
If the software IRQ handler for that class times out.

When either of these conditions is reached, phase 0 begins. This may trigger an escalation signal, and after a configured duration, proceed to phase 1. This process repeats until phase 3 ends, at which point the class enters a "bricked" terminal state, which cannot be exited except by reset.

At any point, software may end the escalation protocol by calling dif_alert_handler_escalation_clear() (unless clearing is disabled). Successfully calling this function, or clearing the IRQ on time, will reset the state back to idle. Note that this function cannot clear the terminal state; that state can only be cleared by resetting the chip.

◆ dif_alert_handler_class_t

typedef enum dif_alert_handler_class dif_alert_handler_class_t

An alert class.

An alert class roughly specifies how to deal with an alert. The class determines which interrupt handler is fired for an alert, as well as the fine-grained details of the escalation policy, for when the processor fails to respond to an alert quickly enough.

Alert classes serve as the alert handler's IRQ types. There is one IRQ for each class. Whenever an alert fires, the corresponding class's IRQ is serviced by the processor (if enabled).

◆ dif_alert_handler_config_t

typedef struct dif_alert_handler_config dif_alert_handler_config_t

Runtime configuration for the alert handler.

This struct describes runtime information for a single-shot configuration of the alert handler hardware.

Note, any of the array pointers may be NULL, in which case the associated length should be 0.

◆ dif_alert_handler_escalation_signal_t

typedef uint32_t dif_alert_handler_escalation_signal_t

An escalation signal, identified by a numeric ID.

An escalation signal is a generic "response" to failing to handle alert(s). The meaning of each escalation signal is determined by the chip.

An alert class can be configured to raise various escalation signal(s) during various escalation phases as part of its escalation policy.

Definition at line 174 of file dif_alert_handler.h.

◆ dif_alert_handler_local_alert_t

typedef enum dif_alert_handler_local_alert dif_alert_handler_local_alert_t

A local alert originating from within the alert handler itself.

A local alert is exactly the same as a normal dif_alert_handler_alert_t, except that they use different functions for setting up classification and for getting causes.

Enumeration Type Documentation

◆ dif_alert_handler_class

enum dif_alert_handler_class

An alert class.

An alert class roughly specifies how to deal with an alert. The class determines which interrupt handler is fired for an alert, as well as the fine-grained details of the escalation policy, for when the processor fails to respond to an alert quickly enough.

Alert classes serve as the alert handler's IRQ types. There is one IRQ for each class. Whenever an alert fires, the corresponding class's IRQ is serviced by the processor (if enabled).

Definition at line 57 of file dif_alert_handler.h.

◆ dif_alert_handler_class_state

enum dif_alert_handler_class_state

An alert class state.

This enum describes the sequence of states in the escalation protocol, which triggers under two different conditions:

If too many alerts of a particular class accumulate.
If the software IRQ handler for that class times out.

When either of these conditions is reached, phase 0 begins. This may trigger an escalation signal, and after a configured duration, proceed to phase 1. This process repeats until phase 3 ends, at which point the class enters a "bricked" terminal state, which cannot be exited except by reset.

At any point, software may end the escalation protocol by calling dif_alert_handler_escalation_clear() (unless clearing is disabled). Successfully calling this function, or clearing the IRQ on time, will reset the state back to idle. Note that this function cannot clear the terminal state; that state can only be cleared by resetting the chip.

Enumerator
kDifAlertHandlerClassStateIdle	The initial, idle state.
kDifAlertHandlerClassStateTimeout	The "timeout" state, that is, the IRQ has been fired and the clock is ticking for the processor to handle the alert.
kDifAlertHandlerClassStateFsmError	The "fsm_error" state. This is a terminal state indicating the FSM has been glitched.
kDifAlertHandlerClassStateTerminal	The terminal state. Most configurations will never reach this state, since one of the previous phases will use an escalation signal to reset the device.
kDifAlertHandlerClassStatePhase0	The zeroth escalation phase.
kDifAlertHandlerClassStatePhase1	The first escalation phase.
kDifAlertHandlerClassStatePhase2	The second escalation phase.
kDifAlertHandlerClassStatePhase3	The third escalation phase.

Definition at line 124 of file dif_alert_handler.h.

◆ dif_alert_handler_local_alert

enum dif_alert_handler_local_alert

A local alert originating from within the alert handler itself.

A local alert is exactly the same as a normal dif_alert_handler_alert_t, except that they use different functions for setting up classification and for getting causes.

Definition at line 101 of file dif_alert_handler.h.

Function Documentation

◆ dif_alert_handler_alert_acknowledge()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_alert_acknowledge	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_alert_t	alert
	)

Clears an alert from the cause vector, similar to an IRQ acknowledgement.

Parameters

alert_handler	An alert handler handle.
alert	The alert to acknowledge.

Returns: The result of the operation.

Definition at line 667 of file dif_alert_handler.c.

◆ dif_alert_handler_alert_is_cause()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_alert_is_cause	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_alert_t	alert,
		bool *	is_cause
	)

Checks whether an alert is one of the causes for an alert IRQ.

Note that multiple alerts may be causes at the same time.

Parameters

	alert_handler	An alert handler handle.
	alert	The alert to check.
[out]	is_cause	Out-param for whether this alert is a cause.

Returns: The result of the operation.

Definition at line 652 of file dif_alert_handler.c.

◆ dif_alert_handler_configure_alert()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_configure_alert	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_alert_t	alert,
		dif_alert_handler_class_t	alert_class,
		dif_toggle_t	enabled,
		dif_toggle_t	locked
	)

Configures an alert in the alert handler.

This operation is lock-protected, meaning once the configuration is locked, it cannot be reconfigured until after a system reset.

Parameters

alert_handler	An alert handler handle.
alert	The alert to be configured.
alert_class	The class to assign the alert to.
enabled	The enablement state to configure the alert in.
locked	The locked state to configure the alert in.

Returns: The result of the operation.

Configures an alert in the alert handler.

(I.e., alert N has enable multireg N).

Definition at line 151 of file dif_alert_handler.c.

◆ dif_alert_handler_configure_class()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_configure_class	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_class_t	alert_class,
		dif_alert_handler_class_config_t	config,
		dif_toggle_t	enabled,
		dif_toggle_t	locked
	)

Configures the escalation protocol of an alert class in the alert handler.

This operation is lock-protected, meaning once the configuration is locked, it cannot be reconfigured until after a system reset.

Note, regardless if the class is enabled or, IRQs will still fire based on the accumulation counter threshold configuration for the class, however, the escalation protocol will not trigger.

Parameters

alert_handler	An alert handler handle.
alert_class	The class to be configured.
config	The escalation protocol configuration.
enabled	The enablement state of the class escalation protocol.
locked	The locked state to configure the class in.

Returns: The result of the operation.

Definition at line 249 of file dif_alert_handler.c.

◆ dif_alert_handler_configure_local_alert()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_configure_local_alert	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_local_alert_t	local_alert,
		dif_alert_handler_class_t	alert_class,
		dif_toggle_t	enabled,
		dif_toggle_t	locked
	)

Configures a local alert in the alert handler.

This operation is lock-protected, meaning once the configuration is locked, it cannot be reconfigured until after a system reset.

Parameters

alert_handler	An alert handler handle.
local_alert	The local alert to be configured.
alert_class	The class to assign the alert to.
enabled	The enablement state to configure the alert in.
locked	The locked state to configure the alert in.

Returns: The result of the operation.

Definition at line 191 of file dif_alert_handler.c.

◆ dif_alert_handler_configure_ping_timer()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_configure_ping_timer	(	const dif_alert_handler_t *	alert_handler,
		uint32_t	ping_timeout,
		dif_toggle_t	enabled,
		dif_toggle_t	locked
	)

Configures the ping timer in the alert handler.

This operation is lock-protected, meaning once the configuration is locked, it cannot be reconfigured until after a system reset.

Note, the ping timer will only ping alerts that have been enabled AND locked. Therefore, this DIF should be invoked after configuring and enabling each (local) alert.

Parameters

alert_handler	An alert handler handle.
ping_timeout	The alert ping timeout, in cycles.
enabled	The enablement state to configure the ping timer in.
locked	The locked state to configure ping timer in.

Returns: The result of the operation.

Definition at line 459 of file dif_alert_handler.c.

◆ dif_alert_handler_escalation_can_clear()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_escalation_can_clear	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_class_t	alert_class,
		bool *	can_clear
	)

Checks whether software can clear escalations for this class.

If automatic_locking has been set in a class's configuration, this function may suddenly begin returning false instead of true without software invervention, if escalation has been triggered.

Parameters

	alert_handler	An alert handler handle.
	alert_class	The class to check.
[out]	can_clear	Out-param for the clear enablement state.

Returns: The result of the operation.

Definition at line 718 of file dif_alert_handler.c.

◆ dif_alert_handler_escalation_clear()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_escalation_clear	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_class_t	alert_class
	)

Clears an on-going escalation, as well as the class accumulator.

This operation can be disabled with dif_alert_handler_escalation_disable_clearing().

Parameters

alert_handler	An alert handler handle.
alert_class	The class to clear an escalation for.

Returns: The result of the operation.

Definition at line 756 of file dif_alert_handler.c.

◆ dif_alert_handler_escalation_disable_clearing()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_escalation_disable_clearing	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_class_t	alert_class
	)

Disables escalation clearing for this class.

This operation is similar to locking in that it cannot be undone.

Parameters

alert_handler	An alert handler handle.
alert_class	The class to disable clearing for.

Returns: The result of the operation.

Definition at line 737 of file dif_alert_handler.c.

◆ dif_alert_handler_get_accumulator()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_get_accumulator	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_class_t	alert_class,
		uint16_t *	num_alerts
	)

Gets the accumulator value for this class.

This value is the number of alerts of this class that have been logged so far (more or less, since multiple alerts on the same cycle will be merged into one). Once this value equals the configured threshold, any followup alerts will immediately trigger the escalation protocol.

This value is cleared as a side-effect of dif_alert_handler_escalation_clear().

Parameters

	alert_handler	An alert handler handle.
	alert_class	The class to get the accumulator for.
[out]	num_alerts	Out-param for the number of alerts that have accumulated.

Returns: The result of the operation.

Definition at line 782 of file dif_alert_handler.c.

◆ dif_alert_handler_get_class_state()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_get_class_state	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_class_t	alert_class,
		dif_alert_handler_class_state_t *	state
	)

Gets the current state of this class.

See dif_alert_handler_class_state_t for potential states.

Parameters

	alert_handler	An alert handler handle.
	alert_class	The class to get the state of
[out]	state	Out-param for the class state.

Returns: The result of the operation.

Definition at line 838 of file dif_alert_handler.c.

◆ dif_alert_handler_get_escalation_counter()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_get_escalation_counter	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_class_t	alert_class,
		uint32_t *	cycles
	)

Gets the current value of the "escalation counter".

The interpretation of this value depends on the value returned by dif_alert_handler_class_state_get(). If it is in the timeout state, it returns the number of cycles counted towards that cycle so far. If in an escalation phase, it returns the number of cycles that phase has been active for.

Parameters

	alert_handler	An alert handler handle.
	alert_class	The class to set the counter for.
[out]	cycles	Out-param for the counter.

Returns: The result of the operation.

Definition at line 812 of file dif_alert_handler.c.

◆ dif_alert_handler_is_alert_locked()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_is_alert_locked	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_alert_t	alert,
		bool *	is_locked
	)

Checks whether an alert handler's alert is locked.

Parameters

	alert_handler	An alert handler handle.
	alert	The alert to check is locked.
[out]	is_locked	Out-param for the locked state.

Returns: The result of the operation.

Definition at line 537 of file dif_alert_handler.c.

◆ dif_alert_handler_is_class_locked()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_is_class_locked	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_class_t	alert_class,
		bool *	is_locked
	)

Checks whether an alert handler's class is locked.

Parameters

	alert_handler	An alert handler handle.
	alert_class	The alert class to check is locked.
[out]	is_locked	Out-param for the locked state.

Returns: The result of the operation.

Definition at line 609 of file dif_alert_handler.c.

◆ dif_alert_handler_is_local_alert_locked()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_is_local_alert_locked	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_local_alert_t	local_alert,
		bool *	is_locked
	)

Checks whether an alert handler's local alert is locked.

Parameters

	alert_handler	An alert handler handle.
	local_alert	The local alert to check is locked.
[out]	is_locked	Out-param for the locked state.

Returns: The result of the operation.

Definition at line 571 of file dif_alert_handler.c.

◆ dif_alert_handler_is_ping_timer_locked()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_is_ping_timer_locked	(	const dif_alert_handler_t *	alert_handler,
		bool *	is_locked
	)

Checks whether alert handler's ping timer is locked.

Parameters

	alert_handler	An alert handler handle.
[out]	is_locked	Out-param for the locked state.

Returns: The result of the operation.

Definition at line 640 of file dif_alert_handler.c.

◆ dif_alert_handler_local_alert_acknowledge()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_local_alert_acknowledge	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_local_alert_t	local_alert
	)

Clears a local alert from the cause vector, similar to an IRQ acknowledgement.

Parameters

alert_handler	An alert handler handle.
local_alert	The local alert to acknowledge.

Returns: The result of the operation.

Definition at line 699 of file dif_alert_handler.c.

◆ dif_alert_handler_local_alert_is_cause()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_local_alert_is_cause	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_local_alert_t	local_alert,
		bool *	is_cause
	)

Checks whether a local alert is one of the causes for an alert IRQ.

Note that multiple alerts may be causes at the same time.

Parameters

	alert_handler	An alert handler handle.
	local_alert	The local alert to check.
[out]	is_cause	Out-param for whether this alert is a cause.

Returns: The result of the operation.

Definition at line 680 of file dif_alert_handler.c.

◆ dif_alert_handler_lock_alert()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_lock_alert	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_alert_t	alert
	)

Locks out an alert handler alert configuration.

This operation cannot be undone, and should be performed at the end of configuring the alert handler in early boot.

This function is reentrant: calling it while functionality is locked will have no effect and return kDifOk.

Parameters

alert_handler	An alert handler handle.
alert	The alert to lock.

Returns: The result of the operation.

Definition at line 524 of file dif_alert_handler.c.

◆ dif_alert_handler_lock_class()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_lock_class	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_class_t	alert_class
	)

Locks out an alert handler class configuration.

This operation cannot be undone, and should be performed at the end of configuring the alert handler in early boot.

This function is reentrant: calling it while functionality is locked will have no effect and return kDifOk.

Parameters

alert_handler	An alert handler handle.
alert_class	The alert class to lock.

Returns: The result of the operation.

Definition at line 590 of file dif_alert_handler.c.

◆ dif_alert_handler_lock_local_alert()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_lock_local_alert	(	const dif_alert_handler_t *	alert_handler,
		dif_alert_handler_local_alert_t	local_alert
	)

Locks out an alert handler local alert configuration.

This operation cannot be undone, and should be performed at the end of configuring the alert handler in early boot.

This function is reentrant: calling it while functionality is locked will have no effect and return kDifOk.

Parameters

alert_handler	An alert handler handle.
local_alert	The local alert to lock.

Returns: The result of the operation.

Definition at line 552 of file dif_alert_handler.c.

◆ dif_alert_handler_lock_ping_timer()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_lock_ping_timer ( const dif_alert_handler_t * alert_handler )

Locks out alert handler ping timer configuration.

This operation cannot be undone, and should be performed at the end of configuring the alert handler in early boot.

This function is reentrant: calling it while functionality is locked will have no effect and return kDifOk.

Parameters

alert_handler An alert handler handle.

Returns: The result of the operation.

Definition at line 628 of file dif_alert_handler.c.

◆ dif_alert_handler_ping_timer_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_alert_handler_ping_timer_set_enabled	(	const dif_alert_handler_t *	alert_handler,
		dif_toggle_t	locked
	)

Enables the ping timer in the alert handler.

This operation is lock-protected, meaning once the configuration is locked, it cannot be reconfigured until after a system reset.

Note, the ping timer will only ping alerts that have been enabled AND locked. Therefore, this DIF should be invoked after configuring and enabling each (local) alert.

Parameters

alert_handler	An alert handler handle.
locked	The locked state to configure ping timer in after enabling it.

Returns: The result of the operation.

Definition at line 498 of file dif_alert_handler.c.

(8a1a5fe)

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ dif_alert_handler_escalation_phase

◆ dif_alert_handler_class_config

◆ dif_alert_handler_config

Macro Definition Documentation

◆ ALERT_CLASS_ENUM_INIT_

◆ LIST_OF_CLASSES

◆ LIST_OF_LOC_ALERTS

◆ LOC_ALERT_ENUM_INIT_

Typedef Documentation

◆ dif_alert_handler_alert_t

◆ dif_alert_handler_class_config_t

◆ dif_alert_handler_class_state_t

◆ dif_alert_handler_class_t

◆ dif_alert_handler_config_t

◆ dif_alert_handler_escalation_signal_t

◆ dif_alert_handler_local_alert_t

Enumeration Type Documentation

◆ dif_alert_handler_class

◆ dif_alert_handler_class_state

◆ dif_alert_handler_local_alert

Function Documentation

◆ dif_alert_handler_alert_acknowledge()

◆ dif_alert_handler_alert_is_cause()

◆ dif_alert_handler_configure_alert()

◆ dif_alert_handler_configure_class()

◆ dif_alert_handler_configure_local_alert()

◆ dif_alert_handler_configure_ping_timer()

◆ dif_alert_handler_escalation_can_clear()

◆ dif_alert_handler_escalation_clear()

◆ dif_alert_handler_escalation_disable_clearing()

◆ dif_alert_handler_get_accumulator()

◆ dif_alert_handler_get_class_state()

◆ dif_alert_handler_get_escalation_counter()

◆ dif_alert_handler_is_alert_locked()

◆ dif_alert_handler_is_class_locked()

◆ dif_alert_handler_is_local_alert_locked()

◆ dif_alert_handler_is_ping_timer_locked()

◆ dif_alert_handler_local_alert_acknowledge()

◆ dif_alert_handler_local_alert_is_cause()

◆ dif_alert_handler_lock_alert()

◆ dif_alert_handler_lock_class()

◆ dif_alert_handler_lock_local_alert()

◆ dif_alert_handler_lock_ping_timer()

◆ dif_alert_handler_ping_timer_set_enabled()