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

(dcee03a)

Alert handler Device Interface Functions More...

#include <stdint.h>
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_warn_unused_result.h"

Go to the source code of this file.

Data Structures

struct  dif_alert_handler_params
 Hardware instantiation parameters for the alert handler. More...
 
struct  dif_alert_handler
 A handle to alert handler. More...
 
struct  dif_alert_handler_class_phase_signal
 Runtime configuration for responding to a given escalation phase. More...
 
struct  dif_alert_handler_class_phase_duration
 Runtime configuration for the duration of 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 alert handler. More...
 

Typedefs

typedef enum dif_alert_handler_toggle dif_alert_handler_toggle_t
 A toggle state: enabled, or disabled. More...
 
typedef struct dif_alert_handler_params dif_alert_handler_params_t
 Hardware instantiation parameters for the alert handler. More...
 
typedef struct dif_alert_handler dif_alert_handler_t
 A handle to alert handler. More...
 
typedef enum dif_alert_handler_result dif_alert_handler_result_t
 The result of an alert handler operation.
 
typedef enum dif_alert_handler_config_result dif_alert_handler_config_result_t
 The result of an alert handler configuration operation.
 
typedef enum dif_alert_handler_class dif_alert_handler_class_t
 An alert class. More...
 
typedef uint32_t dif_alert_handler_irq_snapshot_t
 A snapshot of the enablement state of the interrupts for alert handler. 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 uint32_t dif_alert_handler_signal_t
 An escalation signal, identified by a numeric id. More...
 
typedef enum dif_alert_handler_class_state dif_alert_handler_class_state_t
 An alert class state. More...
 
typedef struct dif_alert_handler_class_phase_signal dif_alert_handler_class_phase_signal_t
 Runtime configuration for responding to a given escalation phase. More...
 
typedef struct dif_alert_handler_class_phase_duration dif_alert_handler_class_phase_duration_t
 Runtime configuration for the duration of an escalation phase. More...
 
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 alert handler. More...
 

Enumerations

enum  dif_alert_handler_toggle {
  kDifAlertHandlerToggleEnabled,
  kDifAlertHandlerToggleDisabled
}
 A toggle state: enabled, or disabled. More...
 
enum  dif_alert_handler_result {
  kDifAlertHandlerOk = 0,
  kDifAlertHandlerError = 1,
  kDifAlertHandlerBadArg = 2
}
 The result of an alert handler operation. More...
 
enum  dif_alert_handler_config_result {
  kDifAlertHandlerConfigOk = kDifAlertHandlerOk,
  kDifAlertHandlerConfigError = kDifAlertHandlerError,
  kDifAlertHandlerConfigBadArg = kDifAlertHandlerBadArg,
  kDifAlertHandlerConfigLocked = 3
}
 The result of an alert handler configuration operation. More...
 
enum  dif_alert_handler_class {
  kDifAlertHandlerClassA = 0,
  kDifAlertHandlerClassB = 1,
  kDifAlertHandlerClassC = 2,
  kDifAlertHandlerClassD = 3
}
 An alert class. More...
 
enum  dif_alert_handler_local_alert {
  kDifAlertHandlerLocalAlertAlertPingFail,
  kDifAlertHandlerLocalAlertEscalationPingFail,
  kDifAlertHandlerLocalAlertAlertIntegrityFail,
  kDifAlertHandlerLocalAlertEscalationIntegrityFail
}
 A local alert originating from within the alert handler itself. More...
 
enum  dif_alert_handler_class_state {
  kDifAlertHandlerClassStateIdle,
  kDifAlertHandlerClassStateTimeout,
  kDifAlertHandlerClassStatePhase0,
  kDifAlertHandlerClassStatePhase1,
  kDifAlertHandlerClassStatePhase2,
  kDifAlertHandlerClassStatePhase3,
  kDifAlertHandlerClassStateTerminal
}
 An alert class state. More...
 

Functions

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_init (dif_alert_handler_params_t params, dif_alert_handler_t *handler)
 Creates a new handle for alert handler. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_config_result_t dif_alert_handler_configure (const dif_alert_handler_t *handler, dif_alert_handler_config_t config)
 Configures alert handler with runtime information. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_lock (const dif_alert_handler_t *handler)
 Locks out alert handler configuration functionality. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_is_locked (const dif_alert_handler_t *handler, bool *is_locked)
 Checks whether this alert handler is locked. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_irq_is_pending (const dif_alert_handler_t *handler, dif_alert_handler_class_t alert_class, bool *is_pending)
 Returns whether a particular interrupt is currently pending. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_irq_acknowledge (const dif_alert_handler_t *handler, dif_alert_handler_class_t alert_class)
 Acknowledges a particular interrupt, indicating to the hardware that it has been successfully serviced. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_irq_get_enabled (const dif_alert_handler_t *handler, dif_alert_handler_class_t alert_class, dif_alert_handler_toggle_t *state)
 Checks whether a particular interrupt is currently enabled or disabled. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_irq_set_enabled (const dif_alert_handler_t *handler, dif_alert_handler_class_t alert_class, dif_alert_handler_toggle_t state)
 Sets whether a particular interrupt is currently enabled or disabled. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_irq_force (const dif_alert_handler_t *handler, dif_alert_handler_class_t alert_class)
 Forces a particular interrupt, causing it to be serviced as if hardware had asserted it. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_irq_disable_all (const dif_alert_handler_t *handler, dif_alert_handler_irq_snapshot_t *snapshot)
 Disables all interrupts, optionally snapshotting all toggle state for later restoration. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_irq_restore_all (const dif_alert_handler_t *handler, const dif_alert_handler_irq_snapshot_t *snapshot)
 Restores interrupts from the given snapshot. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_alert_is_cause (const dif_alert_handler_t *handler, dif_alert_handler_alert_t alert, bool *is_cause)
 Checks whether an alert is one of the causes for an alert IRQ. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_alert_acknowledge (const dif_alert_handler_t *handler, dif_alert_handler_alert_t alert)
 Clears an alert from the cause vector, similar to an IRQ acknowledgement. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_local_alert_is_cause (const dif_alert_handler_t *handler, dif_alert_handler_local_alert_t alert, bool *is_cause)
 Checks whether a local alert is one of the causes for an alert IRQ. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_local_alert_acknowledge (const dif_alert_handler_t *handler, dif_alert_handler_local_alert_t alert)
 Clears a local alert from the cause vector, similar to an IRQ acknowledgement. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_escalation_can_clear (const dif_alert_handler_t *handler, dif_alert_handler_class_t alert_class, bool *can_clear)
 Checks whether software can clear escalations for this class. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_escalation_disable_clearing (const dif_alert_handler_t *handler, dif_alert_handler_class_t alert_class)
 Disables escalation clearing for this class. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_escalation_clear (const dif_alert_handler_t *handler, dif_alert_handler_class_t alert_class)
 Clears an on-going escalation, as well as the class accumulator. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_get_accumulator (const dif_alert_handler_t *handler, dif_alert_handler_class_t alert_class, uint16_t *alerts)
 Gets the accumulator value for this class. More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_get_escalation_counter (const dif_alert_handler_t *handler, dif_alert_handler_class_t alert_class, uint32_t *cycles)
 Gets the current value of the "escalation counter". More...
 
DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_get_class_state (const dif_alert_handler_t *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_params

struct dif_alert_handler_params

Hardware instantiation parameters for the alert handler.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

Definition at line 47 of file dif_alert_handler.h.

Data Fields
uint32_t alert_count The configured number of alerts.

This value is fixed by the hardware, but not known to this library.

mmio_region_t base_addr The base address for the alert handler hardware registers.
uint32_t escalation_signal_count The configured number of escalation signals.

This value is fixed by the hardware, but not known to this library.

◆ dif_alert_handler

struct dif_alert_handler

A handle to alert handler.

This type should be treated as opaque by users.

Definition at line 73 of file dif_alert_handler.h.

Data Fields
dif_alert_handler_params_t params

◆ dif_alert_handler_class_phase_signal

struct dif_alert_handler_class_phase_signal

Runtime configuration for responding to a given escalation phase.

See dif_alert_handler_class_config_t.

Definition at line 262 of file dif_alert_handler.h.

Data Fields
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_signal_t signal The signal that should be triggered when this phase begins.

◆ dif_alert_handler_class_phase_duration

struct dif_alert_handler_class_phase_duration

Runtime configuration for the duration of an escalation phase.

See dif_alert_handler_class_config_t.

Definition at line 281 of file dif_alert_handler.h.

Data Fields
uint32_t 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_class_config

struct dif_alert_handler_class_config

Runtime configuration for a particular alert class.

This struct describes how a particular alert class should be configured, such as which signals are associated with it, and what options are turned on for the escalation protocol.

For each of the pointer/length field pairs below, if the length is zero, the pointer may be NULL.

Definition at line 305 of file dif_alert_handler.h.

Data Fields
uint16_t accumulator_threshold The threshold for the class accmulator which, when reached, will automatically trigger escalation.
dif_alert_handler_class_t alert_class The class this configuration describes.
const dif_alert_handler_alert_t * alerts A list of alerts that should be classified as having this class.

Each alert in this list will additionally be set as enabled.

size_t alerts_len The length of the array alerts.
dif_alert_handler_toggle_t automatic_locking Whether automatic escalation locking should be used for this class.

When enabled, upon beginning the escalation protocol, the hardware will lock the escalation clear bit, so that software cannot stop escalation once it has begun.

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.

const
dif_alert_handler_local_alert_t *
local_alerts A list of local that should be classified as having this class.

Each local alert in this list will additionally be set as enabled.

size_t local_alerts_len The length of the array local_alerts.
const
dif_alert_handler_class_phase_duration_t *
phase_durations Durations, in cycles, of each escalation phase.
size_t phase_durations_len The length of the array phase_durations.
const
dif_alert_handler_class_phase_signal_t *
phase_signals Signals to associate to each escalation phase.

Each escalation phase signal in this list will additionally be set as enabled; phases not listed will have their escalation signals disabled.

size_t phase_signals_len The length of the array phase_signals.
dif_alert_handler_toggle_t use_escalation_protocol Whether the escalation protocol should be used for this class (i.e., accumulator and timeout based escalation).

Class IRQs will still fire regardless of this setting.

◆ dif_alert_handler_config

struct dif_alert_handler_config

Runtime configuration for alert handler.

This struct describes runtime information for one-time configuration of the hardware.

Definition at line 393 of file dif_alert_handler.h.

Data Fields
const
dif_alert_handler_class_config_t *
classes A list of alert classes to configure.
size_t classes_len The length of the array 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.

This value must fit in 24 bits.

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. An alert handler handle.consumes alerts, classifies them to 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, and is specified by the software when initializing a dif_alert_handler_t.

Definition at line 175 of file dif_alert_handler.h.

◆ dif_alert_handler_class_config_t

Runtime configuration for a particular alert class.

This struct describes how a particular alert class should be configured, such as which signals are associated with it, and what options are turned on for the escalation protocol.

For each of the pointer/length field pairs below, if the length is zero, the pointer may be NULL.

◆ dif_alert_handler_class_phase_duration_t

Runtime configuration for the duration of an escalation phase.

See dif_alert_handler_class_config_t.

◆ dif_alert_handler_class_phase_signal_t

Runtime configuration for responding to a given escalation phase.

See dif_alert_handler_class_config_t.

◆ 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 accumualte.
  • 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 back to the idle state. 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 alert handler.

This struct describes runtime information for one-time configuration of the hardware.

◆ dif_alert_handler_irq_snapshot_t

A snapshot of the enablement state of the interrupts for alert handler.

This is an opaque type, to be used with the dif_alert_handler_irq_disable_all() and dif_alert_handler_irq_restore_all() functions.

Definition at line 162 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.

◆ dif_alert_handler_params_t

Hardware instantiation parameters for the alert handler.

This struct describes information about the underlying hardware that is not determined until the hardware design is used as part of a top-level design.

◆ dif_alert_handler_signal_t

typedef uint32_t dif_alert_handler_signal_t

An escalation signal, identified by a numeric id.

An escalation signal is a generic "response" to failing to handle a catastrophic event. What each signal means is determined by the chip.

A dif_alert_handler_class_t can be configured to raise escalation signals as part of its policy.

Definition at line 200 of file dif_alert_handler.h.

◆ dif_alert_handler_t

A handle to alert handler.

This type should be treated as opaque by users.

◆ dif_alert_handler_toggle_t

A toggle state: enabled, or disabled.

This enum may be used instead of a bool when describing an enabled/disabled state.

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

Enumerator
kDifAlertHandlerClassA 

Alert class "A".

kDifAlertHandlerClassB 

Alert class "B".

kDifAlertHandlerClassC 

Alert class "C".

kDifAlertHandlerClassD 

Alert class "D".

Definition at line 136 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 accumualte.
  • 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 back to the idle state. 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.

kDifAlertHandlerClassStatePhase0 

The zeroth escalation phase.

kDifAlertHandlerClassStatePhase1 

The first escalation phase.

kDifAlertHandlerClassStatePhase2 

The second escalation phase.

kDifAlertHandlerClassStatePhase3 

The third escalation phase.

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.

Definition at line 221 of file dif_alert_handler.h.

◆ dif_alert_handler_config_result

The result of an alert handler configuration operation.

Enumerator
kDifAlertHandlerConfigOk 

Indicates that the operation succeeded.

kDifAlertHandlerConfigError 

Indicates some unspecified failure.

kDifAlertHandlerConfigBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

kDifAlertHandlerConfigLocked 

Indicates that this operation has been locked out, and can never succeed until hardware reset.

Definition at line 101 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 184 of file dif_alert_handler.h.

◆ dif_alert_handler_result

The result of an alert handler operation.

Enumerator
kDifAlertHandlerOk 

Indicates that the operation succeeded.

kDifAlertHandlerError 

Indicates some unspecified failure.

kDifAlertHandlerBadArg 

Indicates that some parameter passed into a function failed a precondition.

When this value is returned, no hardware operations occurred.

Definition at line 80 of file dif_alert_handler.h.

◆ dif_alert_handler_toggle

A toggle state: enabled, or disabled.

This enum may be used instead of a bool when describing an enabled/disabled state.

Enumerator
kDifAlertHandlerToggleEnabled 

The "enabled" state.

kDifAlertHandlerToggleDisabled 

The "disabled" state.

Definition at line 29 of file dif_alert_handler.h.

Function Documentation

◆ dif_alert_handler_alert_acknowledge()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_alert_acknowledge ( const dif_alert_handler_t handler,
dif_alert_handler_alert_t  alert 
)

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

Parameters
handlerAn alert handler handle.
alertThe alert to acknowledge.
Returns
The result of the operation.

Definition at line 646 of file dif_alert_handler.c.

◆ dif_alert_handler_alert_is_cause()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_alert_is_cause ( const dif_alert_handler_t 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
handlerAn alert handler handle.
alertThe alert to check.
is_causeOut-param for whether this alert is a cause.
Returns
The result of the operation.

Definition at line 631 of file dif_alert_handler.c.

◆ dif_alert_handler_configure()

DIF_WARN_UNUSED_RESULT dif_alert_handler_config_result_t dif_alert_handler_configure ( const dif_alert_handler_t handler,
dif_alert_handler_config_t  config 
)

Configures alert handler with runtime information.

This function should need to be called once for the lifetime of handle.

This operation is lock-protected.

Parameters
handlerAn alert handler handle.
configRuntime configuration parameters.
Returns
The result of the operation.

Definition at line 398 of file dif_alert_handler.c.

◆ dif_alert_handler_escalation_can_clear()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_escalation_can_clear ( const dif_alert_handler_t 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
handlerAn alert handler handle.
alert_classThe class to check.
can_clearOut-param for the clear enablement state.
Returns
The result of the operation.

Definition at line 740 of file dif_alert_handler.c.

◆ dif_alert_handler_escalation_clear()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_escalation_clear ( const dif_alert_handler_t 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
handlerAn alert handler handle.
alert_classThe class to clear an escalation for.
Returns
The result of the operation.

Definition at line 777 of file dif_alert_handler.c.

◆ dif_alert_handler_escalation_disable_clearing()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_escalation_disable_clearing ( const dif_alert_handler_t 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
handlerAn alert handler handle.
alert_classThe class to disable clearing for.
Returns
The result of the operation.

Definition at line 759 of file dif_alert_handler.c.

◆ dif_alert_handler_get_accumulator()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_get_accumulator ( const dif_alert_handler_t handler,
dif_alert_handler_class_t  alert_class,
uint16_t *  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
handlerAn alert handler handle.
alert_classThe class to get the accumulator for.
alertsOut-param for the accumulator.
Returns
The result of the operation.

Definition at line 808 of file dif_alert_handler.c.

◆ dif_alert_handler_get_class_state()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_get_class_state ( const dif_alert_handler_t 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
handlerAn alert handler handle.
alert_classThe class to get the state of
stateOut-param for the class state.
Returns
The result of the operation.

Definition at line 874 of file dif_alert_handler.c.

◆ dif_alert_handler_get_escalation_counter()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_get_escalation_counter ( const dif_alert_handler_t 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
handlerAn alert handler handle.
alert_classThe class to set the counter for.
cyclesOut-param for the counter.
Returns
The result of the operation.

Definition at line 844 of file dif_alert_handler.c.

◆ dif_alert_handler_init()

Creates a new handle for alert handler.

This function does not actuate the hardware.

Parameters
paramsHardware instantiation parameters.
handlerOut param for the initialized handle.
Returns
The result of the operation.

Definition at line 18 of file dif_alert_handler.c.

◆ dif_alert_handler_irq_acknowledge()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_irq_acknowledge ( const dif_alert_handler_t handler,
dif_alert_handler_class_t  alert_class 
)

Acknowledges a particular interrupt, indicating to the hardware that it has been successfully serviced.

Parameters
handlerAn alert handler handle.
alert_classAn alert class.
Returns
The result of the operation.

Definition at line 516 of file dif_alert_handler.c.

◆ dif_alert_handler_irq_disable_all()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_irq_disable_all ( const dif_alert_handler_t handler,
dif_alert_handler_irq_snapshot_t snapshot 
)

Disables all interrupts, optionally snapshotting all toggle state for later restoration.

Parameters
handlerAn alert handler handle.
snapshotOut-param for the snapshot; may be NULL.
Returns
The result of the operation.

Definition at line 600 of file dif_alert_handler.c.

◆ dif_alert_handler_irq_force()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_irq_force ( const dif_alert_handler_t handler,
dif_alert_handler_class_t  alert_class 
)

Forces a particular interrupt, causing it to be serviced as if hardware had asserted it.

Parameters
handlerAn alert handler handle.
alert_classAn alert class.
Returns
The result of the operation.

Definition at line 582 of file dif_alert_handler.c.

◆ dif_alert_handler_irq_get_enabled()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_irq_get_enabled ( const dif_alert_handler_t handler,
dif_alert_handler_class_t  alert_class,
dif_alert_handler_toggle_t state 
)

Checks whether a particular interrupt is currently enabled or disabled.

Parameters
handlerAn alert handler handle.
alert_classAn alert class.
stateOut-param toggle state of the interrupt.
Returns
The result of the operation.

Definition at line 536 of file dif_alert_handler.c.

◆ dif_alert_handler_irq_is_pending()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_irq_is_pending ( const dif_alert_handler_t handler,
dif_alert_handler_class_t  alert_class,
bool *  is_pending 
)

Returns whether a particular interrupt is currently pending.

Parameters
handlerAn alert handler handle.
alert_classAn alert class.
is_pendingOut-param for whether the interrupt is pending.
Returns
The result of the operation.

Definition at line 497 of file dif_alert_handler.c.

◆ dif_alert_handler_irq_restore_all()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_irq_restore_all ( const dif_alert_handler_t handler,
const dif_alert_handler_irq_snapshot_t snapshot 
)

Restores interrupts from the given snapshot.

This function can be used with dif_alert_handler_irq_disable_all() to temporary interrupt save-and-restore.

Parameters
handlerAn alert handler handle.
snapshotA snapshot to restore from.
Returns
The result of the operation.

Definition at line 618 of file dif_alert_handler.c.

◆ dif_alert_handler_irq_set_enabled()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_irq_set_enabled ( const dif_alert_handler_t handler,
dif_alert_handler_class_t  alert_class,
dif_alert_handler_toggle_t  state 
)

Sets whether a particular interrupt is currently enabled or disabled.

Parameters
handlerAn alert handler handle.
alert_classAn alert class.
stateThe new toggle state for the interrupt.
Returns
The result of the operation.

Definition at line 556 of file dif_alert_handler.c.

◆ dif_alert_handler_is_locked()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_is_locked ( const dif_alert_handler_t handler,
bool *  is_locked 
)

Checks whether this alert handler is locked.

See dif_alert_handler_lock().

Parameters
handlerAn alert handler handle.
is_lockedOut-param for the locked state.
Returns
The result of the operation.

Definition at line 461 of file dif_alert_handler.c.

◆ dif_alert_handler_local_alert_acknowledge()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_local_alert_acknowledge ( const dif_alert_handler_t handler,
dif_alert_handler_local_alert_t  alert 
)

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

Parameters
handlerAn alert handler handle.
alertThe alert to acknowledge.
Returns
The result of the operation.

Definition at line 700 of file dif_alert_handler.c.

◆ dif_alert_handler_local_alert_is_cause()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_local_alert_is_cause ( const dif_alert_handler_t handler,
dif_alert_handler_local_alert_t  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
handlerAn alert handler handle.
alertThe alert to check.
is_causeOut-param for whether this alert is a cause.
Returns
The result of the operation.

Definition at line 681 of file dif_alert_handler.c.

◆ dif_alert_handler_lock()

DIF_WARN_UNUSED_RESULT dif_alert_handler_result_t dif_alert_handler_lock ( const dif_alert_handler_t handler)

Locks out alert handler configuration functionality.

Once locked, dif_alert_handler_configure() will return kDifAlertHandlerConfigLocked.

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 kDifAlertHandlerOk.

Parameters
handlerAn alert handler handle.
Returns
The result of the operation.

Definition at line 448 of file dif_alert_handler.c.