Software APIs
Macros | Typedefs | Enumerations | Functions
dif_rstmgr.h File Reference

(c03805b)

Reset Manager Device Interface Functions More...

#include <stdbool.h>
#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_rstmgr_autogen.h"

Go to the source code of this file.

Macros

#define DIF_RSTMGR_ALERT_INFO_MAX_SIZE   0xf
 The maximal size of the alert crash info dump. More...
 
#define DIF_RSTMGR_CPU_INFO_MAX_SIZE   0xf
 The maximal size of the CPU crash info dump. More...
 

Typedefs

typedef enum dif_rstmgr_software_reset dif_rstmgr_software_reset_t
 Reset Manager peripheral software reset control.
 
typedef uint32_t dif_rstmgr_reset_info_bitfield_t
 Reset Manager reset information bitfield.
 
typedef enum dif_rstmgr_reset_info dif_rstmgr_reset_info_t
 Reset Manager possible reset information enumeration. More...
 
typedef uint32_t dif_rstmgr_peripheral_t
 Reset Manager software reset available peripherals.
 
typedef enum dif_rstmgr_fatal_err_type dif_rstmgr_fatal_err_type_t
 
typedef uint32_t dif_rstmgr_fatal_err_codes_t
 A set of fatal errors. More...
 
typedef uint32_t dif_rstmgr_alert_info_dump_segment_t
 Alert info crash dump segment. More...
 
typedef uint32_t dif_rstmgr_cpu_info_dump_segment_t
 CPU info crash dump segment. More...
 

Enumerations

enum  dif_rstmgr_software_reset {
  kDifRstmgrSoftwareReset = 0,
  kDifRstmgrSoftwareResetHold,
  kDifRstmgrSoftwareResetRelease
}
 Reset Manager peripheral software reset control. More...
 
enum  dif_rstmgr_reset_info {
  kDifRstmgrResetInfoPor = 0x1,
  kDifRstmgrResetInfoLowPowerExit = (0x1 << 1),
  kDifRstmgrResetInfoSw = (0x1 << 2),
  kDifRstmgrResetInfoHwReq = (0x1f << 3),
  kDifRstmgrResetInfoSysRstCtrl = (1 << 3),
  kDifRstmgrResetInfoWatchdog = (1 << 4),
  kDifRstmgrResetInfoPowerUnstable = (1 << 5),
  kDifRstmgrResetInfoEscalation = (1 << 6),
  kDifRstmgrResetInfoNdm = (1 << 7)
}
 Reset Manager possible reset information enumeration. More...
 
enum  dif_rstmgr_fatal_err_type {
  kDifRstmgrFatalErrTypeRegfileIntegrity = 1u << 0,
  kDifRstmgrFatalErrTypeResetConsistency = 1u << 1
}
 

Functions

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_reset (const dif_rstmgr_t *handle)
 Resets the Reset Manager registers to sane defaults. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_reset_lock (const dif_rstmgr_t *handle, dif_rstmgr_peripheral_t peripheral)
 Locks out requested peripheral reset functionality. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_reset_is_locked (const dif_rstmgr_t *handle, dif_rstmgr_peripheral_t peripheral, bool *is_locked)
 Checks whether requested peripheral reset functionality is locked. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_reset_info_get (const dif_rstmgr_t *handle, dif_rstmgr_reset_info_bitfield_t *info)
 Obtains the complete Reset Manager reset information. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_reset_info_clear (const dif_rstmgr_t *handle)
 Clears the reset information in Reset Manager. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_alert_info_set_enabled (const dif_rstmgr_t *handle, dif_toggle_t state)
 Enables or disables the alert crash dump capture. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_alert_info_get_enabled (const dif_rstmgr_t *handle, dif_toggle_t *state)
 Retrieves the alert info crash dump capture state. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_alert_info_get_size (const dif_rstmgr_t *handle, size_t *size)
 Get alert info dump size. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_alert_info_dump_read (const dif_rstmgr_t *handle, dif_rstmgr_alert_info_dump_segment_t *dump, size_t dump_size, size_t *segments_read)
 Reads the entire alert info crash dump. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_cpu_info_set_enabled (const dif_rstmgr_t *handle, dif_toggle_t state)
 Enables or disables the CPU crash dump capture. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_cpu_info_get_enabled (const dif_rstmgr_t *handle, dif_toggle_t *state)
 Retrieves the CPU info crash dump capture state. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_cpu_info_get_size (const dif_rstmgr_t *handle, size_t *size)
 Get cpu info dump size. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_cpu_info_dump_read (const dif_rstmgr_t *handle, dif_rstmgr_cpu_info_dump_segment_t *dump, size_t dump_size, size_t *segments_read)
 Reads the entire CPU info crash dump. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_software_reset (const dif_rstmgr_t *handle, dif_rstmgr_peripheral_t peripheral, dif_rstmgr_software_reset_t reset)
 Asserts or de-asserts software reset for the requested peripheral. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_software_reset_is_held (const dif_rstmgr_t *handle, dif_rstmgr_peripheral_t peripheral, bool *asserted)
 Queries whether the requested peripheral is held in reset. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_software_device_reset (const dif_rstmgr_t *handle)
 Software request for system reset. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_fatal_err_code_get_codes (const dif_rstmgr_t *rstmgr, dif_rstmgr_fatal_err_codes_t *codes)
 Read the fatal error codes. More...
 

Detailed Description

Reset Manager Device Interface Functions

Definition in file dif_rstmgr.h.

Macro Definition Documentation

◆ DIF_RSTMGR_ALERT_INFO_MAX_SIZE

#define DIF_RSTMGR_ALERT_INFO_MAX_SIZE   0xf

The maximal size of the alert crash info dump.

Note: must match the autogenerated register definition.

Definition at line 32 of file dif_rstmgr.h.

◆ DIF_RSTMGR_CPU_INFO_MAX_SIZE

#define DIF_RSTMGR_CPU_INFO_MAX_SIZE   0xf

The maximal size of the CPU crash info dump.

Note: must match the autogenerated register definition.

Definition at line 39 of file dif_rstmgr.h.

Typedef Documentation

◆ dif_rstmgr_alert_info_dump_segment_t

Alert info crash dump segment.

The alert info crash dump consists of 32-bit data segments

Definition at line 241 of file dif_rstmgr.h.

◆ dif_rstmgr_cpu_info_dump_segment_t

CPU info crash dump segment.

The CPU info crash dump consists of 32-bit data segments

Definition at line 311 of file dif_rstmgr.h.

◆ dif_rstmgr_fatal_err_codes_t

typedef uint32_t dif_rstmgr_fatal_err_codes_t

A set of fatal errors.

This type is used to read the fatal error codes.

Definition at line 129 of file dif_rstmgr.h.

◆ dif_rstmgr_reset_info_t

Reset Manager possible reset information enumeration.

Invariants are used to extract information encoded in dif_rstmgr_reset_info_bitfield_t, which means that the values must correspond to the individual bits (0x1, 0x2, 0x4, ..., 0x80000000).

Note: these must match the autogenerated register definitions.

Enumeration Type Documentation

◆ dif_rstmgr_fatal_err_type

Enumerator
kDifRstmgrFatalErrTypeRegfileIntegrity 

A fatal error for regfile integrity.

kDifRstmgrFatalErrTypeResetConsistency 

A fatal error for reset consistency.

Definition at line 113 of file dif_rstmgr.h.

◆ dif_rstmgr_reset_info

Reset Manager possible reset information enumeration.

Invariants are used to extract information encoded in dif_rstmgr_reset_info_bitfield_t, which means that the values must correspond to the individual bits (0x1, 0x2, 0x4, ..., 0x80000000).

Note: these must match the autogenerated register definitions.

Enumerator
kDifRstmgrResetInfoPor 

Device has reset due to power up.

kDifRstmgrResetInfoLowPowerExit 

Device has reset due to low power exit.

kDifRstmgrResetInfoSw 

Device has reset due to software request.

kDifRstmgrResetInfoHwReq 

Device has reset due to a peripheral request.

This can be an alert escalation, watchdog or anything else.

kDifRstmgrResetInfoSysRstCtrl 

Device has reset due to the peripheral system reset control request.

kDifRstmgrResetInfoWatchdog 

Device has reset due to watchdog bite.

kDifRstmgrResetInfoPowerUnstable 

Device has reset due to power unstable.

kDifRstmgrResetInfoEscalation 

Device has reset due to alert escalation.

kDifRstmgrResetInfoNdm 

Device has reset due to non-debug-module request.

Definition at line 68 of file dif_rstmgr.h.

◆ dif_rstmgr_software_reset

Reset Manager peripheral software reset control.

Enumerator
kDifRstmgrSoftwareReset 

Simple reset (release straight away).

kDifRstmgrSoftwareResetHold 

Hold peripheral in reset.

kDifRstmgrSoftwareResetRelease 

Release peripheral from reset.

Definition at line 44 of file dif_rstmgr.h.

Function Documentation

◆ dif_rstmgr_alert_info_dump_read()

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_alert_info_dump_read ( const dif_rstmgr_t handle,
dif_rstmgr_alert_info_dump_segment_t dump,
size_t  dump_size,
size_t *  segments_read 
)

Reads the entire alert info crash dump.

The crash dump is always retained after any kind of reset, except on Power-On-Reset (POR).

Parameters
handleA Reset Manager handle.
dumpAddress of buffer where the alert dump will be written.
dump_sizeSize of the alert dump buffer. The entire crash dump will be read, and the actual size can be determined through the segments_read parameter. It is an error if dump_size is not large enough.
[out]segments_readNumber of segments read.
Returns
The result of the operation.

Definition at line 232 of file dif_rstmgr.c.

◆ dif_rstmgr_alert_info_get_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_alert_info_get_enabled ( const dif_rstmgr_t handle,
dif_toggle_t state 
)

Retrieves the alert info crash dump capture state.

The alert info crash dump capture is automatically disabled upon system reset (even if the Reset Manager is not reset).

Parameters
handleA Reset Manager handle.
[out]stateThe state of the crash dump capture.
Returns
The result of the operation.

Definition at line 204 of file dif_rstmgr.c.

◆ dif_rstmgr_alert_info_get_size()

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_alert_info_get_size ( const dif_rstmgr_t handle,
size_t *  size 
)

Get alert info dump size.

Parameters
handleA Reset Manager handle.
[out]sizeThe size of the alert info dump in 32 bit words.
Returns
The result of the operation.

Definition at line 221 of file dif_rstmgr.c.

◆ dif_rstmgr_alert_info_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_alert_info_set_enabled ( const dif_rstmgr_t handle,
dif_toggle_t  state 
)

Enables or disables the alert crash dump capture.

When enabled, will capture the alert crash dump prior to a triggered reset.

The alert info crash dump capture is automatically disabled upon system reset (even if the Reset Manager is not reset).

Parameters
handleA Reset Manager handle.
stateThe new toggle state for the crash dump capture.
Returns
The result of the operation.

Definition at line 182 of file dif_rstmgr.c.

◆ dif_rstmgr_cpu_info_dump_read()

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_cpu_info_dump_read ( const dif_rstmgr_t handle,
dif_rstmgr_cpu_info_dump_segment_t dump,
size_t  dump_size,
size_t *  segments_read 
)

Reads the entire CPU info crash dump.

The crash dump is always retained after any kind of reset, except on Power-On-Reset (POR).

Parameters
handleA Reset Manager handle.
dumpAddress of buffer where the crash dump will be written.
dump_sizeSize of the crash dump buffer. The entire crash dump will be read, and the actual size can be determined through the segments_read parameter. It is an error if dump_size is not large enough.
[out]segments_readNumber of segments read.
Returns
The result of the operation.

Definition at line 320 of file dif_rstmgr.c.

◆ dif_rstmgr_cpu_info_get_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_cpu_info_get_enabled ( const dif_rstmgr_t handle,
dif_toggle_t state 
)

Retrieves the CPU info crash dump capture state.

The CPU info crash dump capture is automatically disabled upon system reset (even if the Reset Manager is not reset).

Parameters
handleA Reset Manager handle.
[out]stateThe state of the crash dump capture.
Returns
The result of the operation.

Definition at line 293 of file dif_rstmgr.c.

◆ dif_rstmgr_cpu_info_get_size()

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_cpu_info_get_size ( const dif_rstmgr_t handle,
size_t *  size 
)

Get cpu info dump size.

Parameters
handleA Reset Manager handle.
[out]sizeThe size of the cpu info dump in 32 bit words.
Returns
The result of the operation.

Definition at line 309 of file dif_rstmgr.c.

◆ dif_rstmgr_cpu_info_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_cpu_info_set_enabled ( const dif_rstmgr_t handle,
dif_toggle_t  state 
)

Enables or disables the CPU crash dump capture.

When enabled, will capture the CPU crash dump prior to a triggered reset.

The CPU info crash dump capture is automatically disabled upon system reset (even if the Reset Manager is not reset).

Parameters
handleA Reset Manager handle.
stateThe new toggle state for the CPU crash dump capture.
Returns
The result of the operation.

Definition at line 271 of file dif_rstmgr.c.

◆ dif_rstmgr_fatal_err_code_get_codes()

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_fatal_err_code_get_codes ( const dif_rstmgr_t rstmgr,
dif_rstmgr_fatal_err_codes_t codes 
)

Read the fatal error codes.

Parameters
rstmgrReset Manager Handle.
[out]codesThe fatal error codes.
Returns
The result of the operation.

Definition at line 416 of file dif_rstmgr.c.

◆ dif_rstmgr_reset()

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_reset ( const dif_rstmgr_t handle)

Resets the Reset Manager registers to sane defaults.

Note that software reset enable registers cannot be cleared once have been locked.

Parameters
handleA Reset Manager handle.
Returns
The result of the operation.

Definition at line 110 of file dif_rstmgr.c.

◆ dif_rstmgr_reset_info_clear()

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_reset_info_clear ( const dif_rstmgr_t handle)

Clears the reset information in Reset Manager.

Parameters
handleA Reset Manager handle.
Returns
dif_result_t.
The result of the operation.

Definition at line 170 of file dif_rstmgr.c.

◆ dif_rstmgr_reset_info_get()

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_reset_info_get ( const dif_rstmgr_t handle,
dif_rstmgr_reset_info_bitfield_t info 
)

Obtains the complete Reset Manager reset information.

The reset info are parsed and presented to the caller as an array of flags in 'info'.

Parameters
handleA Reset Manager handle.
infoReset information.
Returns
The result of the operation.

Definition at line 158 of file dif_rstmgr.c.

◆ dif_rstmgr_reset_is_locked()

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_reset_is_locked ( const dif_rstmgr_t handle,
dif_rstmgr_peripheral_t  peripheral,
bool *  is_locked 
)

Checks whether requested peripheral reset functionality is locked.

Parameters
handleA Reset Manager handle.
peripheralPeripheral to check the reset lock for.
is_lockedOut-param for the locked state.
Returns
The result of the operation.

Definition at line 144 of file dif_rstmgr.c.

◆ dif_rstmgr_reset_lock()

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_reset_lock ( const dif_rstmgr_t handle,
dif_rstmgr_peripheral_t  peripheral 
)

Locks out requested peripheral reset functionality.

Calling this function when software reset is locked will have no effect and return kDifOk.

Parameters
handleA Reset Manager handle.
peripheralPeripheral to lock the reset functionality for.
Returns
The result of the operation.

Definition at line 129 of file dif_rstmgr.c.

◆ dif_rstmgr_software_device_reset()

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_software_device_reset ( const dif_rstmgr_t handle)

Software request for system reset.

Parameters
handleA Reset Manager handle.
Returns
The result of the operation.

Definition at line 405 of file dif_rstmgr.c.

◆ dif_rstmgr_software_reset()

Asserts or de-asserts software reset for the requested peripheral.

Parameters
handleA Reset Manager handle.
peripheralPeripheral to assert/de-assert reset for.
resetReset control.
Returns
The result of the operation.

Definition at line 359 of file dif_rstmgr.c.

◆ dif_rstmgr_software_reset_is_held()

OT_WARN_UNUSED_RESULT dif_result_t dif_rstmgr_software_reset_is_held ( const dif_rstmgr_t handle,
dif_rstmgr_peripheral_t  peripheral,
bool *  asserted 
)

Queries whether the requested peripheral is held in reset.

Parameters
handleA Reset Manager handle.
peripheralPeripheral to query.
asserted'true' when held in reset, false otherwise.
Returns
The result of the operation.

Definition at line 389 of file dif_rstmgr.c.