 |
Software APIs
|
|
Software APIs
|
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, kDifAlertHandlerClassStatePhase0, kDifAlertHandlerClassStatePhase1, kDifAlertHandlerClassStatePhase2, kDifAlertHandlerClassStatePhase3, kDifAlertHandlerClassStateTerminal } |
| An alert class state. More... | |
Alert handler Device Interface Functions
Definition in file dif_alert_handler.h.
| struct dif_alert_handler_escalation_phase |
Runtime configuration for an escalation phase.
Definition at line 174 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 |
| dif_alert_handler_escalation_signal_t | signal | The escalation signal that should be triggered when this phase begins. |
| 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 197 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):
|
| 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 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. |
| 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 255 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 Note while this value must fit into the timeout register which is smaller than the native word length. |
| #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.
| #define LIST_OF_CLASSES | ( | X | ) |
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.
| #define LIST_OF_LOC_ALERTS | ( | X | ) |
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.
| #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 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.
| 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.
An alert class state.
This enum describes the sequence of states in the escalation protocol, which triggers under two different conditions:
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.
| 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).
| 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.
| 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 169 of file dif_alert_handler.h.
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.
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.
An alert class state.
This enum describes the sequence of states in the escalation protocol, which triggers under two different conditions:
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.
Definition at line 124 of file dif_alert_handler.h.
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.
| 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.
| alert_handler | An alert handler handle. |
| alert | The alert to acknowledge. |
Definition at line 667 of file dif_alert_handler.c.
| 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.
| alert_handler | An alert handler handle. | |
| alert | The alert to check. | |
| [out] | is_cause | Out-param for whether this alert is a cause. |
Definition at line 652 of file dif_alert_handler.c.
| 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.
| 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. |
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.
| 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.
| 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. |
Definition at line 249 of file dif_alert_handler.c.
| 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.
| 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. |
Definition at line 191 of file dif_alert_handler.c.
| 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.
| 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. |
Definition at line 459 of file dif_alert_handler.c.
| 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.
| alert_handler | An alert handler handle. | |
| alert_class | The class to check. | |
| [out] | can_clear | Out-param for the clear enablement state. |
Definition at line 718 of file dif_alert_handler.c.
| 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().
| alert_handler | An alert handler handle. |
| alert_class | The class to clear an escalation for. |
Definition at line 756 of file dif_alert_handler.c.
| 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.
| alert_handler | An alert handler handle. |
| alert_class | The class to disable clearing for. |
Definition at line 737 of file dif_alert_handler.c.
| 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().
| 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. |
Definition at line 782 of file dif_alert_handler.c.
| 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.
| alert_handler | An alert handler handle. | |
| alert_class | The class to get the state of | |
| [out] | state | Out-param for the class state. |
Definition at line 838 of file dif_alert_handler.c.
| 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.
| alert_handler | An alert handler handle. | |
| alert_class | The class to set the counter for. | |
| [out] | cycles | Out-param for the counter. |
Definition at line 812 of file dif_alert_handler.c.
| 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.
| alert_handler | An alert handler handle. | |
| alert | The alert to check is locked. | |
| [out] | is_locked | Out-param for the locked state. |
Definition at line 537 of file dif_alert_handler.c.
| 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.
| alert_handler | An alert handler handle. | |
| alert_class | The alert class to check is locked. | |
| [out] | is_locked | Out-param for the locked state. |
Definition at line 609 of file dif_alert_handler.c.
| 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.
| alert_handler | An alert handler handle. | |
| local_alert | The local alert to check is locked. | |
| [out] | is_locked | Out-param for the locked state. |
Definition at line 571 of file dif_alert_handler.c.
| 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.
| alert_handler | An alert handler handle. | |
| [out] | is_locked | Out-param for the locked state. |
Definition at line 640 of file dif_alert_handler.c.
| 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.
| alert_handler | An alert handler handle. |
| local_alert | The local alert to acknowledge. |
Definition at line 699 of file dif_alert_handler.c.
| 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.
| 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. |
Definition at line 680 of file dif_alert_handler.c.
| 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.
| alert_handler | An alert handler handle. |
| alert | The alert to lock. |
Definition at line 524 of file dif_alert_handler.c.
| 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.
| alert_handler | An alert handler handle. |
| alert_class | The alert class to lock. |
Definition at line 590 of file dif_alert_handler.c.
| 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.
| alert_handler | An alert handler handle. |
| local_alert | The local alert to lock. |
Definition at line 552 of file dif_alert_handler.c.
| 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.
| alert_handler | An alert handler handle. |
Definition at line 628 of file dif_alert_handler.c.
| 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.
| alert_handler | An alert handler handle. |
| locked | The locked state to configure ping timer in after enabling it. |
Definition at line 498 of file dif_alert_handler.c.