Software APIs
Typedefs | Enumerations | Functions
dif_sram_ctrl.h File Reference

(8b2da8d)

SRAM Controller Device Interface Functions More...

#include <stdint.h>
#include "sw/device/lib/base/multibits.h"
#include "sw/device/lib/dif/autogen/dif_sram_ctrl_autogen.h"

Go to the source code of this file.

Typedefs

typedef uint32_t dif_sram_ctrl_status_bitfield_t
 SRAM Controller status information bitfield.
 
typedef enum dif_sram_ctrl_status dif_sram_ctrl_status_t
 SRAM Controller status flags. More...
 
typedef enum dif_sram_ctrl_lock dif_sram_ctrl_lock_t
 SRAM Controller lockable functionality.
 

Enumerations

enum  dif_sram_ctrl_status {
  kDifSramCtrlStatusBusIntegErr = 0x1,
  kDifSramCtrlStatusInitErr = (0x1 << 1),
  kDifSramCtrlStatusEscalated = (0x1 << 2),
  kDifSramCtrlStatusScrKeyValid = (0x1 << 3),
  kDifSramCtrlStatusScrKeySeedValid = (0x1 << 4),
  kDifSramCtrlStatusInitDone = (0x1 << 5)
}
 SRAM Controller status flags. More...
 
enum  dif_sram_ctrl_lock {
  kDifSramCtrlLockCtrl = 0,
  kDifSramCtrlLockExec,
  kDifSramCtrlLockReadback
}
 SRAM Controller lockable functionality. More...
 

Functions

OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_scramble (const dif_sram_ctrl_t *sram_ctrl)
 Performs blocking SRAM scrambling operation. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_request_new_key (const dif_sram_ctrl_t *sram_ctrl)
 Requests a new scrambling key. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_wipe (const dif_sram_ctrl_t *sram_ctrl)
 Overwrites "wipes" the entire SRAM with pseudo-random data. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_exec_get_enabled (const dif_sram_ctrl_t *sram_ctrl, dif_toggle_t *state)
 Checks whether execution from SRAM is currently enabled or disabled. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_exec_set_enabled (const dif_sram_ctrl_t *sram_ctrl, dif_toggle_t state)
 Sets whether execution from SRAM enabled or disabled. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_readback_set (const dif_sram_ctrl_t *sram_ctrl, dif_toggle_t state)
 Sets whether the SRAM readback feature is enabled or disabled. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_get_status (const dif_sram_ctrl_t *sram_ctrl, dif_sram_ctrl_status_bitfield_t *status)
 Queries the SRAM Controller status. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_lock (const dif_sram_ctrl_t *sram_ctrl, dif_sram_ctrl_lock_t lock)
 Locks out requested SRAM Controller functionality. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_is_locked (const dif_sram_ctrl_t *sram_ctrl, dif_sram_ctrl_lock_t lock, bool *is_locked)
 Checks whether requested SRAM Controller functionality is locked. More...
 
OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_scr_key_rotated (const dif_sram_ctrl_t *sram_ctrl, multi_bit_bool_t *success, multi_bit_bool_t clear)
 Checks whether requested SRAM Controller successfully obtained a new key. More...
 

Detailed Description

SRAM Controller Device Interface Functions

Definition in file dif_sram_ctrl.h.

Typedef Documentation

◆ dif_sram_ctrl_status_t

SRAM Controller status flags.

Invariants are used to extract information encoded in dif_sram_ctrl_status_bitfield_t.

More than one status flag can be set at the same time, and a caller may use these invariants to look-up individual or a group of flags.

Note: these must match the autogenerated register definition bit offsets.

Enumeration Type Documentation

◆ dif_sram_ctrl_lock

SRAM Controller lockable functionality.

Enumerator
kDifSramCtrlLockCtrl 

SRAM scrambling key renewal and "wiping" lock, which includes the following API: dif_sram_ctrl_scramble, dif_sram_ctrl_request_new_key and dif_sram_ctrl_wipe.

kDifSramCtrlLockExec 

Code execution from SRAM lock, which includes the following API: dif_sram_ctrl_exec_set_enabled.

Note: this setting may not be available depending on the OTP configuration of the chip (EN_SRAM_IFETCH fuse).

kDifSramCtrlLockReadback 

Readback feature lock.

When locked, disabling or enabling the SRAM readback feature is not available anymore. Includes the following API: dif_sram_ctrl_readback_set.

Definition at line 81 of file dif_sram_ctrl.h.

◆ dif_sram_ctrl_status

SRAM Controller status flags.

Invariants are used to extract information encoded in dif_sram_ctrl_status_bitfield_t.

More than one status flag can be set at the same time, and a caller may use these invariants to look-up individual or a group of flags.

Note: these must match the autogenerated register definition bit offsets.

Enumerator
kDifSramCtrlStatusBusIntegErr 

Bus integrity fault is detected.

This error triggers a fatal_error alert. This condition is terminal.

kDifSramCtrlStatusInitErr 

Initialization counter has reached an invalid state.

This error triggers a fatal_error alert. This condition is terminal.

kDifSramCtrlStatusEscalated 

SRAM Controller has received an escalate request, the scrambling keys have been reset to the default values and all subsequent memory requests will be blocked.

This condition is terminal.

kDifSramCtrlStatusScrKeyValid 

New scrambling key has been successfully obtained from OTP.

If the flag is not set, the SRAM contents are still scrambled, but a default all-zero key and nonce are used to do so.

kDifSramCtrlStatusScrKeySeedValid 

Scrambling key has been derived from a valid key seed in OTP.

When kDifSramCtrlStatusScrKeyValid is set, but this flag is unset - the scrambling key is still ephemeral (i.e., it is derived using entropy from CSRNG), but a default all-zero value is used as the key seed. This could happen when the scrambling key seeds have not yet been provisioned to OTP.

kDifSramCtrlStatusInitDone 

Hardware initialization triggered via dif_sram_ctrl_scramble or dif_sram_ctrl_wipe has completed.

Definition at line 40 of file dif_sram_ctrl.h.

Function Documentation

◆ dif_sram_ctrl_exec_get_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_exec_get_enabled ( const dif_sram_ctrl_t sram_ctrl,
dif_toggle_t state 
)

Checks whether execution from SRAM is currently enabled or disabled.

Parameters
sram_ctrlA SRAM Controller handle.
[out]stateOut-param toggle state of the SRAM execution.
Returns
The result of the operation.

Definition at line 168 of file dif_sram_ctrl.c.

◆ dif_sram_ctrl_exec_set_enabled()

OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_exec_set_enabled ( const dif_sram_ctrl_t sram_ctrl,
dif_toggle_t  state 
)

Sets whether execution from SRAM enabled or disabled.

Parameters
sram_ctrlA SRAM Controller handle.
stateThe new toggle state for the SRAM execution.
Returns
The result of the operation.

Definition at line 182 of file dif_sram_ctrl.c.

◆ dif_sram_ctrl_get_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_get_status ( const dif_sram_ctrl_t sram_ctrl,
dif_sram_ctrl_status_bitfield_t status 
)

Queries the SRAM Controller status.

dif_sram_ctrl_status_t is used to then extract individual status bits.

Parameters
sram_ctrlA SRAM Controller handle.
[out]SRAMController status bitfield.
Returns
The result of the operation.

Definition at line 153 of file dif_sram_ctrl.c.

◆ dif_sram_ctrl_is_locked()

OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_is_locked ( const dif_sram_ctrl_t sram_ctrl,
dif_sram_ctrl_lock_t  lock,
bool *  is_locked 
)

Checks whether requested SRAM Controller functionality is locked.

Parameters
sram_ctrlA SRAM Controller handle.
lockSRAM functionality to query locked state for.
[out]is_lockedOut-param for the locked state.
Returns
The result of the operation.

Definition at line 240 of file dif_sram_ctrl.c.

◆ dif_sram_ctrl_lock()

Locks out requested SRAM Controller functionality.

This function is reentrant: calling it while functionality is locked will have no effect and return kDifOk.

Parameters
sram_ctrlA SRAM Controller handle.
lockSRAM functionality to lock.
Returns
The result of the operation.

Definition at line 217 of file dif_sram_ctrl.c.

◆ dif_sram_ctrl_readback_set()

OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_readback_set ( const dif_sram_ctrl_t sram_ctrl,
dif_toggle_t  state 
)

Sets whether the SRAM readback feature is enabled or disabled.

Parameters
sram_ctrlA SRAM Controller handle.
stateThe new toggle state for the SRAM readback feature.
Returns
The result of the operation.

Definition at line 199 of file dif_sram_ctrl.c.

◆ dif_sram_ctrl_request_new_key()

OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_request_new_key ( const dif_sram_ctrl_t sram_ctrl)

Requests a new scrambling key.

This function should only be called when the data is no longer used.

On successful completion SRAM addresses (due to different logical mapping of the physical addresses) and the data are scrambled. However, it is recommended to additionally overwrite SRAM with pseudo-random data by calling dif_sram_ctrl_wipe. This should minimize the chances of revealing the XOR key-stream.

This operation is expected to take a significant amount of CPU cycles. The status can be checked via kDifSramCtrlStatusScrKeyValid, which is useful when a non-blocking work flow is desirable. Otherwise any SRAM access will automatically block until this operation has finished.

Note: when dealing with the Main RAM, additional implication is that the C runtime can be invalidated by the call to this function, and must be re-configured prior to any C code execution.

Parameters
sram_ctrlA SRAM Controller handle.
Returns
The result of the operation.

Definition at line 122 of file dif_sram_ctrl.c.

◆ dif_sram_ctrl_scr_key_rotated()

OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_scr_key_rotated ( const dif_sram_ctrl_t sram_ctrl,
multi_bit_bool_t *  success,
multi_bit_bool_t  clear 
)

Checks whether requested SRAM Controller successfully obtained a new key.

success is set to kMultiBitBool4True if a key rotation was successful.

The clear parameter can be set to kMultiBitBool4True in order to clear the key rotation state back to kMultiBitBool4False after reading it. If the state should not be cleared, set clear to kMultiBitBool4False.

Parameters
sram_ctrlA SRAM Controller handle.
[out]successOutparam for the success state.
clearParameter indicating whether to CSR should be cleared after reading.
Returns
The result of the operation.

Definition at line 264 of file dif_sram_ctrl.c.

◆ dif_sram_ctrl_scramble()

OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_scramble ( const dif_sram_ctrl_t sram_ctrl)

Performs blocking SRAM scrambling operation.

This function should only be called when the data is no longer used.

This is a compound operation covering both data and address "scrambling". In other words logical re-mapping of the physical addresses and data scrambling, followed by the entire SRAM overwriting with a pseudo-random data.

The intention of this operation is to ensure that there is no predefined values or predictable data that could potentially make "unscrambling" easier.

This operation is expected to take a significant amount of CPU cycles. If a non-blocking alternative is required, then dif_sram_ctrl_request_new_key, should be used followed by dif_sram_ctrl_wipe. The status of these operations can be found through dif_sram_ctrl_get_status.

Note: when dealing with the Main RAM, additional implication is that the C runtime can be invalidated by the call to this function, and must be re-configured prior to any C code execution.

Parameters
sram_ctrlA SRAM Controller handle.
Returns
The result of the operation.

Definition at line 89 of file dif_sram_ctrl.c.

◆ dif_sram_ctrl_wipe()

OT_WARN_UNUSED_RESULT dif_result_t dif_sram_ctrl_wipe ( const dif_sram_ctrl_t sram_ctrl)

Overwrites "wipes" the entire SRAM with pseudo-random data.

This function should only be called when the data is no longer used.

This operation is expected to take a significant amount of CPU cycles. The status can be checked via kDifSramCtrlStatusInitDone, which is useful when a non-blocking work flow is desirable. Otherwise any SRAM access will automatically block until this operation has finished.

Note: when dealing with the Main RAM, additional implication is that the C runtime can be invalidated by the call to this function, and must be re-configured prior to any C code execution.

Parameters
sram_ctrlA SRAM Controller handle.
Returns
The result of the operation.

Definition at line 138 of file dif_sram_ctrl.c.