dif_sram_ctrl.h File Reference

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

Detailed Description

SRAM Controller Device Interface Functions

Definition in file dif_sram_ctrl.h.

Typedef Documentation

dif_sram_ctrl_status_bitfield_t

typedef uint32_t dif_sram_ctrl_status_bitfield_t

SRAM Controller status information bitfield.

Definition at line 27 of file dif_sram_ctrl.h.

dif_sram_ctrl_status_t

typedef enum dif_sram_ctrl_status 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

enum 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

enum 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_ctrl	A SRAM Controller handle.
[out]	state	Out-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_ctrl	A SRAM Controller handle.
state	The 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_ctrl	A SRAM Controller handle.
[out]	SRAM	Controller 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_ctrl	A SRAM Controller handle.
	lock	SRAM functionality to query locked state for.
[out]	is_locked	Out-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()

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.

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

Parameters

sram_ctrl	A SRAM Controller handle.
lock	SRAM 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_ctrl	A SRAM Controller handle.
state	The 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.

Note: during an ongoing memory initialization, the hardware ignores the key request.

Parameters

sram_ctrl

A 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_ctrl	A SRAM Controller handle.
[out]	success	Outparam for the success state.
	clear	Parameter 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_ctrl

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

Note: during this memory initialization, the hardware ignores key requests that are issued while this operation is pending.

Parameters

sram_ctrl

A SRAM Controller handle.

Returns

The result of the operation.

Definition at line 138 of file dif_sram_ctrl.c.