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

(dcee03a)

Reset Manager Device Interface Functions More...

#include <stdbool.h>
#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_rstmgr_params
 Hardware instantiation parameters for Reset Manager. More...
 
struct  dif_rstmgr
 A handle to rstmgr. More...
 

Macros

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

Typedefs

typedef enum dif_rstmgr_toggle dif_rstmgr_toggle_t
 Enumeration for enabling/disabling various functionality.
 
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_result dif_rstmgr_result_t
 The result of a Reset Manager operation.
 
typedef struct dif_rstmgr_params dif_rstmgr_params_t
 Hardware instantiation parameters for Reset Manager. More...
 
typedef struct dif_rstmgr dif_rstmgr_t
 A handle to rstmgr. More...
 
typedef uint32_t dif_rstmgr_alert_info_dump_segment_t
 Alert info crash dump segment. More...
 
typedef enum dif_rstmgr_software_reset_result dif_rstmgr_software_reset_result_t
 The result of a Reset Manager software reset operation.
 

Enumerations

enum  dif_rstmgr_toggle {
  kDifRstmgrToggleEnabled,
  kDifRstmgrToggleDisabled
}
 Enumeration for enabling/disabling various functionality. More...
 
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),
  kDifRstmgrResetInfoNdm = (0x1 << 2),
  kDifRstmgrResetInfoHwReq = (0x3 << 3)
}
 Reset Manager possible reset information enumeration. More...
 
enum  dif_rstmgr_result {
  kDifRstmgrOk = 0,
  kDifRstmgrError = 1,
  kDifRstmgrBadArg = 2
}
 The result of a Reset Manager operation. More...
 
enum  dif_rstmgr_software_reset_result {
  kDifRstmgrSoftwareResetOk = kDifRstmgrOk,
  kDifRstmgrSoftwareResetError = kDifRstmgrError,
  kDifRstmgrSoftwareResetBadArg = kDifRstmgrBadArg,
  kDifRstmgrSoftwareResetLocked
}
 The result of a Reset Manager software reset operation. More...
 

Functions

DIF_WARN_UNUSED_RESULT dif_rstmgr_result_t dif_rstmgr_init (dif_rstmgr_params_t params, dif_rstmgr_t *handle)
 Creates a new handle for Reset Manager. More...
 
DIF_WARN_UNUSED_RESULT dif_rstmgr_result_t dif_rstmgr_reset (const dif_rstmgr_t *handle)
 Resets the Reset Manager registers to sane defaults. More...
 
DIF_WARN_UNUSED_RESULT dif_rstmgr_result_t dif_rstmgr_reset_lock (const dif_rstmgr_t *handle, dif_rstmgr_peripheral_t peripheral)
 Locks out requested peripheral reset functionality. More...
 
DIF_WARN_UNUSED_RESULT dif_rstmgr_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...
 
DIF_WARN_UNUSED_RESULT dif_rstmgr_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...
 
DIF_WARN_UNUSED_RESULT dif_rstmgr_result_t dif_rstmgr_reset_info_clear (const dif_rstmgr_t *handle)
 Clears the reset information in Reset Manager. More...
 
DIF_WARN_UNUSED_RESULT dif_rstmgr_result_t dif_rstmgr_alert_info_set_enabled (const dif_rstmgr_t *handle, dif_rstmgr_toggle_t state)
 Enables or disables the alert crash dump capture. More...
 
dif_rstmgr_result_t dif_rstmgr_alert_info_get_enabled (const dif_rstmgr_t *handle, dif_rstmgr_toggle_t *state)
 Retrieves the alert info crash dump capture state. More...
 
DIF_WARN_UNUSED_RESULT dif_rstmgr_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...
 
DIF_WARN_UNUSED_RESULT dif_rstmgr_software_reset_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...
 
DIF_WARN_UNUSED_RESULT dif_rstmgr_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...
 

Detailed Description

Reset Manager Device Interface Functions

Definition in file dif_rstmgr.h.


Data Structure Documentation

◆ dif_rstmgr_params

struct dif_rstmgr_params

Hardware instantiation parameters for Reset Manager.

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 125 of file dif_rstmgr.h.

Data Fields
mmio_region_t base_addr The base address for the rstmgr hardware registers.

◆ dif_rstmgr

struct dif_rstmgr

A handle to rstmgr.

This type should be treated as opaque by users.

Definition at line 137 of file dif_rstmgr.h.

Data Fields
dif_rstmgr_params_t params

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 29 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 251 of file dif_rstmgr.h.

◆ dif_rstmgr_params_t

Hardware instantiation parameters for Reset Manager.

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

◆ dif_rstmgr_t

typedef struct dif_rstmgr dif_rstmgr_t

A handle to rstmgr.

This type should be treated as opaque by users.

Enumeration Type Documentation

◆ 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 lowe power exit.

kDifRstmgrResetInfoNdm 

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

kDifRstmgrResetInfoHwReq 

Device has reset due to a peripheral request.

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

Definition at line 72 of file dif_rstmgr.h.

◆ dif_rstmgr_result

The result of a Reset Manager operation.

Enumerator
kDifRstmgrOk 

Indicates that the operation succeeded.

kDifRstmgrError 

Indicates some unspecified failure.

kDifRstmgrBadArg 

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

When this value is returned, no hardware operations occurred.

Definition at line 100 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 48 of file dif_rstmgr.h.

◆ dif_rstmgr_software_reset_result

The result of a Reset Manager software reset operation.

Enumerator
kDifRstmgrSoftwareResetOk 

Indicates that the operation succeeded.

kDifRstmgrSoftwareResetError 

Indicates some unspecified failure.

kDifRstmgrSoftwareResetBadArg 

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

When this value is returned, no hardware operations occurred.

kDifRstmgrSoftwareResetLocked 

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

Definition at line 276 of file dif_rstmgr.h.

◆ dif_rstmgr_toggle

Enumeration for enabling/disabling various functionality.

Enumerator
kDifRstmgrToggleEnabled 

Enabled state.

kDifRstmgrToggleDisabled 

Disabled state.

Definition at line 34 of file dif_rstmgr.h.

Function Documentation

◆ dif_rstmgr_alert_info_dump_read()

DIF_WARN_UNUSED_RESULT dif_rstmgr_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.
dumpAlert info crash dump.
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.
segments_readNumber of read segments.
Returns
The result of the operation.

Definition at line 204 of file dif_rstmgr.c.

◆ dif_rstmgr_alert_info_get_enabled()

dif_rstmgr_result_t dif_rstmgr_alert_info_get_enabled ( const dif_rstmgr_t handle,
dif_rstmgr_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.
stateThe state of the crash dump capture.
Returns
The result of the operation.

Definition at line 187 of file dif_rstmgr.c.

◆ dif_rstmgr_alert_info_set_enabled()

DIF_WARN_UNUSED_RESULT dif_rstmgr_result_t dif_rstmgr_alert_info_set_enabled ( const dif_rstmgr_t handle,
dif_rstmgr_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 169 of file dif_rstmgr.c.

◆ dif_rstmgr_init()

DIF_WARN_UNUSED_RESULT dif_rstmgr_result_t dif_rstmgr_init ( dif_rstmgr_params_t  params,
dif_rstmgr_t handle 
)

Creates a new handle for Reset Manager.

This function does not actuate the hardware.

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

Definition at line 89 of file dif_rstmgr.c.

◆ dif_rstmgr_reset()

DIF_WARN_UNUSED_RESULT dif_rstmgr_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 100 of file dif_rstmgr.c.

◆ dif_rstmgr_reset_info_clear()

DIF_WARN_UNUSED_RESULT dif_rstmgr_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_rstmgr_result_t.
The result of the operation.

Definition at line 157 of file dif_rstmgr.c.

◆ dif_rstmgr_reset_info_get()

DIF_WARN_UNUSED_RESULT dif_rstmgr_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 145 of file dif_rstmgr.c.

◆ dif_rstmgr_reset_is_locked()

DIF_WARN_UNUSED_RESULT dif_rstmgr_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 131 of file dif_rstmgr.c.

◆ dif_rstmgr_reset_lock()

DIF_WARN_UNUSED_RESULT dif_rstmgr_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 kDifRstmgrOk.

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

Definition at line 115 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 243 of file dif_rstmgr.c.

◆ dif_rstmgr_software_reset_is_held()

DIF_WARN_UNUSED_RESULT dif_rstmgr_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 273 of file dif_rstmgr.c.