Software APIs
Data Structures | Macros | Typedefs | Enumerations | Functions
dif_alert_handler.h File Reference

(a649ec5)

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):

  1. clear the write enable for the accumulation counter clear register, or
  2. 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

Runtime configuration for a particular alert class.

This struct describes the escalation protocol for an alert class.

◆ 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

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

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

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

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

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

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

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_handlerAn alert handler handle.
alertThe 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_handlerAn alert handler handle.
alertThe alert to check.
[out]is_causeOut-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_handlerAn alert handler handle.
alertThe alert to be configured.
alert_classThe class to assign the alert to.
enabledThe enablement state to configure the alert in.
lockedThe 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_handlerAn alert handler handle.
alert_classThe class to be configured.
configThe escalation protocol configuration.
enabledThe enablement state of the class escalation protocol.
lockedThe 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_handlerAn alert handler handle.
local_alertThe local alert to be configured.
alert_classThe class to assign the alert to.
enabledThe enablement state to configure the alert in.
lockedThe 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_handlerAn alert handler handle.
ping_timeoutThe alert ping timeout, in cycles.
enabledThe enablement state to configure the ping timer in.
lockedThe 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_handlerAn alert handler handle.
alert_classThe class to check.
[out]can_clearOut-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_handlerAn alert handler handle.
alert_classThe 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_handlerAn alert handler handle.
alert_classThe 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_handlerAn alert handler handle.
alert_classThe class to get the accumulator for.
[out]num_alertsOut-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_handlerAn alert handler handle.
alert_classThe class to get the state of
[out]stateOut-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_handlerAn alert handler handle.
alert_classThe class to set the counter for.
[out]cyclesOut-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_handlerAn alert handler handle.
alertThe alert to check is locked.
[out]is_lockedOut-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_handlerAn alert handler handle.
alert_classThe alert class to check is locked.
[out]is_lockedOut-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_handlerAn alert handler handle.
local_alertThe local alert to check is locked.
[out]is_lockedOut-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_handlerAn alert handler handle.
[out]is_lockedOut-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_handlerAn alert handler handle.
local_alertThe 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_handlerAn alert handler handle.
local_alertThe local alert to check.
[out]is_causeOut-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_handlerAn alert handler handle.
alertThe 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_handlerAn alert handler handle.
alert_classThe 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_handlerAn alert handler handle.
local_alertThe 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_handlerAn 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_handlerAn alert handler handle.
lockedThe 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.