Software APIs
dif_rv_core_ibex.h File Reference

Access to Ibex state (e.g. 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_rv_core_ibex_autogen.h"

Go to the source code of this file.

Data Structures

struct  dif_rv_core_ibex_addr_translation_mapping
 Address translation matching region. More...
 
struct  dif_rv_core_ibex_nmi_state
 NMI enabled status and current state. More...
 
struct  dif_rv_core_ibex_crash_dump_state
 
struct  dif_rv_core_ibex_previous_crash_dump_state
 
struct  dif_rv_core_ibex_crash_dump_info
 Under normal circumstances, only the current crash dump state is valid. More...
 

Typedefs

typedef enum dif_rv_core_ibex_addr_translation_slot dif_rv_core_ibex_addr_translation_slot_t
 Address translation slot selection.
 
typedef enum dif_rv_core_ibex_addr_translation_bus dif_rv_core_ibex_addr_translation_bus_t
 Address translation bus selection.
 
typedef struct dif_rv_core_ibex_addr_translation_mapping dif_rv_core_ibex_addr_translation_mapping_t
 Address translation matching region.
 
typedef enum dif_rv_core_ibex_error_status dif_rv_core_ibex_error_status_t
 Ibex error status detected by rv_core_ibex peripheral.
 
typedef enum dif_rv_core_ibex_rnd_status_code dif_rv_core_ibex_rnd_status_code_t
 
typedef uint32_t dif_rv_core_ibex_rnd_status_t
 Bitmask with the dif_rv_core_ibex_rnd_status_code_t values.
 
typedef struct dif_rv_core_ibex_nmi_state dif_rv_core_ibex_nmi_state_t
 NMI enabled status and current state.
 
typedef enum dif_rv_core_ibex_nmi_source dif_rv_core_ibex_nmi_source_t
 
typedef struct dif_rv_core_ibex_crash_dump_state dif_rv_core_ibex_crash_dump_state_t
 
typedef struct dif_rv_core_ibex_previous_crash_dump_state dif_rv_core_ibex_previous_crash_dump_state_t
 
typedef struct dif_rv_core_ibex_crash_dump_info dif_rv_core_ibex_crash_dump_info_t
 Under normal circumstances, only the current crash dump state is valid.
 
typedef uint32_t dif_rv_core_ibex_fpga_info_t
 

Enumerations

enum  dif_rv_core_ibex_addr_translation_slot {
  kDifRvCoreIbexAddrTranslationSlot_0 ,
  kDifRvCoreIbexAddrTranslationSlot_1 ,
  kDifRvCoreIbexAddrTranslationSlotCount
}
 Address translation slot selection. More...
 
enum  dif_rv_core_ibex_addr_translation_bus {
  kDifRvCoreIbexAddrTranslationDBus ,
  kDifRvCoreIbexAddrTranslationIBus ,
  kDifRvCoreIbexAddrTranslationBusCount
}
 Address translation bus selection. More...
 
enum  dif_rv_core_ibex_error_status {
  kDifRvCoreIbexErrorStatusRegisterTransmissionIntegrity = 1 << 0 ,
  kDifRvCoreIbexErrorStatusFatalResponseIntegrity = 1 << 8 ,
  kDifRvCoreIbexErrorStatusFatalInternalError = 1 << 9 ,
  kDifRvCoreIbexErrorStatusRecoverableInternal = 1 << 10 ,
  kDifRvCoreIbexErrorStatusAll = (1 << 0 | 1 << 8 | 1 << 9 | 1 << 10)
}
 Ibex error status detected by rv_core_ibex peripheral. More...
 
enum  dif_rv_core_ibex_rnd_status_code {
  kDifRvCoreIbexRndStatusValid = 1 << 0 ,
  kDifRvCoreIbexRndStatusFipsCompliant = 1 << 1
}
 
enum  dif_rv_core_ibex_nmi_source {
  kDifRvCoreIbexNmiSourceAlert = 1 << 0 ,
  kDifRvCoreIbexNmiSourceWdog = 1 << 1 ,
  kDifRvCoreIbexNmiSourceAll = 0x3
}
 

Functions

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_configure_addr_translation (const dif_rv_core_ibex_t *rv_core_ibex, dif_rv_core_ibex_addr_translation_slot_t slot, dif_rv_core_ibex_addr_translation_bus_t bus, dif_rv_core_ibex_addr_translation_mapping_t addr_map)
 Configure address translation for the given bus (either instruction or data) in the slot.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_enable_addr_translation (const dif_rv_core_ibex_t *rv_core_ibex, dif_rv_core_ibex_addr_translation_slot_t slot, dif_rv_core_ibex_addr_translation_bus_t bus)
 Enable address translation for the given bus (either instruction or data) in the slot.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_disable_addr_translation (const dif_rv_core_ibex_t *rv_core_ibex, dif_rv_core_ibex_addr_translation_slot_t slot, dif_rv_core_ibex_addr_translation_bus_t bus)
 Disable address translation for the given bus (either instruction or data) in the slot.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_read_addr_translation (const dif_rv_core_ibex_t *rv_core_ibex, dif_rv_core_ibex_addr_translation_slot_t slot, dif_rv_core_ibex_addr_translation_bus_t bus, dif_rv_core_ibex_addr_translation_mapping_t *addr_map)
 Read a discription of the address mapping configured on a given slot for a given bus.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_lock_addr_translation (const dif_rv_core_ibex_t *rv_core_ibex, dif_rv_core_ibex_addr_translation_slot_t slot, dif_rv_core_ibex_addr_translation_bus_t bus)
 Lock the address translation settings for a given slot and bus registers.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_get_error_status (const dif_rv_core_ibex_t *rv_core_ibex, dif_rv_core_ibex_error_status_t *error_status)
 Read the ibex error status.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_clear_error_status (const dif_rv_core_ibex_t *rv_core_ibex, dif_rv_core_ibex_error_status_t error_status)
 Clear the ibex error status, after the software has handled it.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_enable_nmi (const dif_rv_core_ibex_t *rv_core_ibex, dif_rv_core_ibex_nmi_source_t nmi)
 Enables NMI support for security alert events and watchdog bark.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_get_nmi_state (const dif_rv_core_ibex_t *rv_core_ibex, dif_rv_core_ibex_nmi_state_t *nmi_state)
 Read the NMI enable status and current event state.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_clear_nmi_state (const dif_rv_core_ibex_t *rv_core_ibex, dif_rv_core_ibex_nmi_source_t nmi)
 Clear the NMI current event state.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_get_rnd_status (const dif_rv_core_ibex_t *rv_core_ibex, dif_rv_core_ibex_rnd_status_t *status)
 Gets whether the rnd data is either valid or is FIPS compliant.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_read_rnd_data (const dif_rv_core_ibex_t *rv_core_ibex, uint32_t *data)
 Reads a random word from the RISC-V Ibex core wrapper.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_read_fpga_info (const dif_rv_core_ibex_t *rv_core_ibex, dif_rv_core_ibex_fpga_info_t *info)
 Read the FPGA build timestamp info.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_get_sw_recov_err_alert (const dif_rv_core_ibex_t *rv_core_ibex, bool *enabled)
 Software fatal alert.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_trigger_sw_recov_err_alert (const dif_rv_core_ibex_t *rv_core_ibex)
 Software recoverable alert.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_get_sw_fatal_err_alert (const dif_rv_core_ibex_t *rv_core_ibex, bool *enabled)
 Get the software fatal alert trigger status.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_trigger_sw_fatal_err_alert (const dif_rv_core_ibex_t *rv_core_ibex)
 Software fatal alert.
 
OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_parse_crash_dump (const dif_rv_core_ibex_t *rv_core_ibex, uint32_t *cpu_info, uint32_t cpu_info_len, dif_rv_core_ibex_crash_dump_info_t *crash_dump_info)
 Parse the cpu info read from the rstmgr.
 

Detailed Description

Access to Ibex state (e.g.

addresses, crashdumps, alerts)

Definition in file dif_rv_core_ibex.h.


Data Structure Documentation

◆ dif_rv_core_ibex_addr_translation_mapping

struct dif_rv_core_ibex_addr_translation_mapping

Address translation matching region.

The value programmed is done at power-of-2 alignment. For example, if the intended matching region is 0x8000_0000 to 0x8000_FFFF, the value programmed is 0x8000_7FFF.

The value programmed can be determined from the translation granule. Assume the user wishes to translate a specific 64KB block to a different address: 64KB has a hex value of 0x10000. Subtract 1 from this value and then right shift by one to obtain 0x7FFF. This value is then logically OR'd with the upper address bits that would select which 64KB to translate.

Definition at line 56 of file dif_rv_core_ibex.h.

Data Fields
uintptr_t matching_addr Matching address (Virtual address).

When an incoming transaction matches the matching region, it is redirected to the new address. If a transaction does not match, then it is directly passed through.

uintptr_t remap_addr Remap address (Physical address).

The region where the matched transtaction will be redirected to.

size_t size Address region size.

◆ dif_rv_core_ibex_nmi_state

struct dif_rv_core_ibex_nmi_state

NMI enabled status and current state.

Definition at line 127 of file dif_rv_core_ibex.h.

Data Fields
bool alert_enabled NMI alert is currently enabled.
bool alert_raised Alert has been raised.
bool wdog_barked Watchdog has barked.
bool wdog_enabled NMI watchdog is currently enabled.

◆ dif_rv_core_ibex_crash_dump_state

struct dif_rv_core_ibex_crash_dump_state

Definition at line 161 of file dif_rv_core_ibex.h.

Data Fields
uint32_t mcpc The current PC.
uint32_t mdaa The last data access address.
uint32_t mnpc The next PC.
uint32_t mpec The last exception PC.
uint32_t mtval The last exception address.

◆ dif_rv_core_ibex_previous_crash_dump_state

struct dif_rv_core_ibex_previous_crash_dump_state

Definition at line 188 of file dif_rv_core_ibex.h.

Data Fields
uint32_t mpec The last exception PC for the previous crash.
uint32_t mtval The exception address for the previous crash.

◆ dif_rv_core_ibex_crash_dump_info

struct dif_rv_core_ibex_crash_dump_info

Under normal circumstances, only the current crash dump state is valid.

When the CPU encounters a double fault, the current crash dump is moved to previous, and the new crash dump is shown in current.

Definition at line 205 of file dif_rv_core_ibex.h.

Data Fields
dif_toggle_t double_fault kDifToggleEnabled if a double fault happened, otherwise kDifToggleDisabled
dif_rv_core_ibex_crash_dump_state_t fault_state The crash dump state for the current execution.
dif_rv_core_ibex_previous_crash_dump_state_t previous_fault_state The crash dump state for the previous execution.

It will only contain valid data in case of a double fault, which will be indicated by the double_fault member.

Typedef Documentation

◆ dif_rv_core_ibex_addr_translation_mapping_t

Address translation matching region.

The value programmed is done at power-of-2 alignment. For example, if the intended matching region is 0x8000_0000 to 0x8000_FFFF, the value programmed is 0x8000_7FFF.

The value programmed can be determined from the translation granule. Assume the user wishes to translate a specific 64KB block to a different address: 64KB has a hex value of 0x10000. Subtract 1 from this value and then right shift by one to obtain 0x7FFF. This value is then logically OR'd with the upper address bits that would select which 64KB to translate.

◆ dif_rv_core_ibex_crash_dump_info_t

Under normal circumstances, only the current crash dump state is valid.

When the CPU encounters a double fault, the current crash dump is moved to previous, and the new crash dump is shown in current.

◆ dif_rv_core_ibex_fpga_info_t

typedef uint32_t dif_rv_core_ibex_fpga_info_t

Definition at line 386 of file dif_rv_core_ibex.h.

◆ dif_rv_core_ibex_rnd_status_t

Bitmask with the dif_rv_core_ibex_rnd_status_code_t values.

Definition at line 122 of file dif_rv_core_ibex.h.

Enumeration Type Documentation

◆ dif_rv_core_ibex_addr_translation_bus

Address translation bus selection.

Definition at line 37 of file dif_rv_core_ibex.h.

◆ dif_rv_core_ibex_addr_translation_slot

Address translation slot selection.

Definition at line 28 of file dif_rv_core_ibex.h.

◆ dif_rv_core_ibex_error_status

Ibex error status detected by rv_core_ibex peripheral.

Enumerator
kDifRvCoreIbexErrorStatusRegisterTransmissionIntegrity 

Register transmission integrity error.

kDifRvCoreIbexErrorStatusFatalResponseIntegrity 

Response integrity error.

kDifRvCoreIbexErrorStatusFatalInternalError 

Fatal internal error (alert_major_internal_o from Ibex seen).

kDifRvCoreIbexErrorStatusRecoverableInternal 

recoverable internal error (alert_minor from Ibex seen).

kDifRvCoreIbexErrorStatusAll 

All errors combined.

Definition at line 81 of file dif_rv_core_ibex.h.

◆ dif_rv_core_ibex_nmi_source

Enumerator
kDifRvCoreIbexNmiSourceAlert 

NMI alert handler.

kDifRvCoreIbexNmiSourceWdog 

NMI watchdog bark.

kDifRvCoreIbexNmiSourceAll 

All ibex NMIs.

Definition at line 146 of file dif_rv_core_ibex.h.

◆ dif_rv_core_ibex_rnd_status_code

Enumerator
kDifRvCoreIbexRndStatusValid 

The current rnd word is valid.

kDifRvCoreIbexRndStatusFipsCompliant 

The current rnd word is fips compliant.

Definition at line 108 of file dif_rv_core_ibex.h.

Function Documentation

◆ dif_rv_core_ibex_clear_error_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_clear_error_status ( const dif_rv_core_ibex_t * rv_core_ibex,
dif_rv_core_ibex_error_status_t error_status )

Clear the ibex error status, after the software has handled it.

Parameters
rv_core_ibexHandle.
error_statusThe error to be cleared.
Returns
The result of the operation.

Definition at line 221 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_clear_nmi_state()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_clear_nmi_state ( const dif_rv_core_ibex_t * rv_core_ibex,
dif_rv_core_ibex_nmi_source_t nmi )

Clear the NMI current event state.

Parameters
rv_core_ibexHandle
nmiA bitmask with nmi sources to be cleared.
Returns
The result of the operation.

Definition at line 281 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_configure_addr_translation()

Configure address translation for the given bus (either instruction or data) in the slot.

Parameters
rv_core_ibexHandle.
slotSlot to be used.
busBus to be translated.
addr_mapAddress mapping description.
Returns
The result of the operation.

Definition at line 108 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_disable_addr_translation()

Disable address translation for the given bus (either instruction or data) in the slot.

Parameters
rv_core_ibexHandle.
slotSlot to be used.
busBus to be translated.
Returns
The result of the operation.

Definition at line 150 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_enable_addr_translation()

Enable address translation for the given bus (either instruction or data) in the slot.

Parameters
rv_core_ibexHandle.
slotSlot to be used.
busBus to be translated.
Returns
The result of the operation.

Definition at line 133 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_enable_nmi()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_enable_nmi ( const dif_rv_core_ibex_t * rv_core_ibex,
dif_rv_core_ibex_nmi_source_t nmi )

Enables NMI support for security alert events and watchdog bark.

Parameters
rv_core_ibexHandle.
nmiA bitmask with nmi sources to be enabled.
Returns
The result of the operation.

Definition at line 235 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_get_error_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_get_error_status ( const dif_rv_core_ibex_t * rv_core_ibex,
dif_rv_core_ibex_error_status_t * error_status )

Read the ibex error status.

Parameters
rv_core_ibexHandle.
error_statusPointer to receive the error status value.
Returns
The result of the operation.

Definition at line 208 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_get_nmi_state()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_get_nmi_state ( const dif_rv_core_ibex_t * rv_core_ibex,
dif_rv_core_ibex_nmi_state_t * nmi_state )

Read the NMI enable status and current event state.

Parameters
rv_core_ibexHandle.
[out]nmi_stateThe nmi state.
Returns
The result of the operation.

Definition at line 255 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_get_rnd_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_get_rnd_status ( const dif_rv_core_ibex_t * rv_core_ibex,
dif_rv_core_ibex_rnd_status_t * status )

Gets whether the rnd data is either valid or is FIPS compliant.

Parameters
rv_core_ibexHandle.
[out]statusPointer to be filled with the current rnd status.
Returns
The result of the operation.

Definition at line 300 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_get_sw_fatal_err_alert()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_get_sw_fatal_err_alert ( const dif_rv_core_ibex_t * rv_core_ibex,
bool * enabled )

Get the software fatal alert trigger status.

Parameters
rv_core_ibexHandle.
[out]enabledReturns true if enabled.
Returns
The result of the operation.

Definition at line 361 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_get_sw_recov_err_alert()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_get_sw_recov_err_alert ( const dif_rv_core_ibex_t * rv_core_ibex,
bool * enabled )

Software fatal alert.

When triggered, a fatal alert is sent. Note, this alert once cleared cannot be set and will continuously cause alert events. Get the software recoverable alert sate.

Parameters
rv_core_ibexHandle.
[out]enabledReturns true if enabled.
Returns
The result of the operation.

Definition at line 335 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_lock_addr_translation()

Lock the address translation settings for a given slot and bus registers.

Once locked it can no longer be unlocked until the next system reset. This function will quietly do nothing if the settings are already locked.

Parameters
rv_core_ibexHandle.
slotSlot to be locked.
busTranslated bus to be locked.
Returns
The result of the operation.

Definition at line 190 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_parse_crash_dump()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_parse_crash_dump ( const dif_rv_core_ibex_t * rv_core_ibex,
uint32_t * cpu_info,
uint32_t cpu_info_len,
dif_rv_core_ibex_crash_dump_info_t * crash_dump_info )

Parse the cpu info read from the rstmgr.

Parameters
rv_core_ibexHandle.
cpu_infoBuffer with the cpu info read from the rstmgr.
cpu_info_lenThe amount of words in the cpu_info buffer.
[out]crash_dump_infoParsed dump.
Returns
The result of the operation.

Definition at line 399 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_read_addr_translation()

Read a discription of the address mapping configured on a given slot for a given bus.

Parameters
rv_core_ibexHandle.
slotSlot of interest.
busBus of interest.
[out]addr_mapDescription of address mapping.
Returns
The result of the operation.

Definition at line 167 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_read_fpga_info()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_read_fpga_info ( const dif_rv_core_ibex_t * rv_core_ibex,
dif_rv_core_ibex_fpga_info_t * info )

Read the FPGA build timestamp info.

This function only returns valid data for fpga environments, for all other environments it is simply 0.

Parameters
rv_core_ibexHandle.
[out]infoA pointer to receive the FPGA timestamp info.
Returns
The result of the operation.

Definition at line 323 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_read_rnd_data()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_read_rnd_data ( const dif_rv_core_ibex_t * rv_core_ibex,
uint32_t * data )

Reads a random word from the RISC-V Ibex core wrapper.

Parameters
rv_core_ibexHandle.
[out]dataPointer to be filled with the random word.
Returns
The result of the operation.

Definition at line 312 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_trigger_sw_fatal_err_alert()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_trigger_sw_fatal_err_alert ( const dif_rv_core_ibex_t * rv_core_ibex)

Software fatal alert.

When triggered, a fatal alert is sent. Note, once this alert is triggered it cannot be reset and will continuously cause alert events.

Parameters
rv_core_ibexHandle.
Returns
The result of the operation.

Definition at line 372 of file dif_rv_core_ibex.c.

◆ dif_rv_core_ibex_trigger_sw_recov_err_alert()

OT_WARN_UNUSED_RESULT dif_result_t dif_rv_core_ibex_trigger_sw_recov_err_alert ( const dif_rv_core_ibex_t * rv_core_ibex)

Software recoverable alert.

When triggered, a recoverable alert is sent. Once the alert is sent, the register is then reset to disabled.

Parameters
rv_core_ibexHandle.
Returns
The result of the operation.

Definition at line 346 of file dif_rv_core_ibex.c.