(8a1a5fe)

OTBN Device Interface Functions. More...

#include <stddef.h>
#include <stdint.h>
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_base.h"
#include "sw/device/lib/dif/autogen/dif_otbn_autogen.h"

Go to the source code of this file.

Typedefs
typedef enum dif_otbn_cmd	dif_otbn_cmd_t
	OTBN commands.

typedef enum dif_otbn_status	dif_otbn_status_t
	OTBN status.

typedef enum dif_otbn_err_bits	dif_otbn_err_bits_t
	OTBN Errors. More...

Enumerations
enum	dif_otbn_cmd { kDifOtbnCmdExecute = 0xd8, kDifOtbnCmdSecWipeDmem = 0xc3, kDifOtbnCmdSecWipeImem = 0x1e }
	OTBN commands.

enum	dif_otbn_status { kDifOtbnStatusIdle = 0x00, kDifOtbnStatusBusyExecute = 0x01, kDifOtbnStatusBusySecWipeDmem = 0x02, kDifOtbnStatusBusySecWipeImem = 0x03, kDifOtbnStatusBusySecWipeInt = 0x04, kDifOtbnStatusLocked = 0xFF }
	OTBN status.

enum	dif_otbn_err_bits { kDifOtbnErrBitsNoError = 0, kDifOtbnErrBitsBadDataAddr = (1 << 0), kDifOtbnErrBitsBadInsnAddr = (1 << 1), kDifOtbnErrBitsCallStack = (1 << 2), kDifOtbnErrBitsIllegalInsn = (1 << 3), kDifOtbnErrBitsLoop = (1 << 4), kDifOtbnErrBitsRndFipsChkFail = (1 << 7), kDifOtbnErrBitsImemIntgViolation = (1 << 16), kDifOtbnErrBitsDmemIntgViolation = (1 << 17), kDifOtbnErrBitsRegIntgViolation = (1 << 18), kDifOtbnErrBitsBusIntgViolation = (1 << 19), kDifOtbnErrBitsBadInternalState = (1 << 20), kDifOtbnErrBitsIllegalBusAccess = (1 << 21), kDifOtbnErrBitsLifecycleEscalation = (1 << 22), kDifOtbnErrBitsFatalSoftware = (1 << 23) }
	OTBN Errors. More...

Functions
OT_WARN_UNUSED_RESULT dif_result_t	dif_otbn_reset (const dif_otbn_t *otbn)
	Reset OTBN device. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otbn_write_cmd (const dif_otbn_t *otbn, dif_otbn_cmd_t cmd)
	Start an operation by issuing a command. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otbn_get_status (const dif_otbn_t otbn, dif_otbn_status_t status)
	Gets the current status of OTBN. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otbn_get_err_bits (const dif_otbn_t otbn, dif_otbn_err_bits_t err_bits)
	Get the error bits set by the device if the operation failed. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otbn_get_insn_cnt (const dif_otbn_t otbn, uint32_t insn_cnt)
	Gets the number of executed OTBN instructions. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otbn_get_load_checksum (const dif_otbn_t otbn, uint32_t insn_cnt)
	Gets the content of the load checksum register. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otbn_clear_load_checksum (const dif_otbn_t *otbn)
	Clears the load checksum register. More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otbn_imem_write (const dif_otbn_t otbn, uint32_t offset_bytes, const void src, size_t len_bytes)
	Write an OTBN application into its instruction memory (IMEM). More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otbn_imem_read (const dif_otbn_t otbn, uint32_t offset_bytes, void dest, size_t len_bytes)
	Read from OTBN's instruction memory (IMEM). More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otbn_dmem_write (const dif_otbn_t otbn, uint32_t offset_bytes, const void src, size_t len_bytes)
	Write to OTBN's data memory (DMEM). More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otbn_dmem_read (const dif_otbn_t otbn, uint32_t offset_bytes, void dest, size_t len_bytes)
	Read from OTBN's data memory (DMEM). More...

OT_WARN_UNUSED_RESULT dif_result_t	dif_otbn_set_ctrl_software_errs_fatal (const dif_otbn_t *otbn, bool enable)
	Sets the software errors are fatal bit in the control register. More...

size_t	dif_otbn_get_dmem_size_bytes (const dif_otbn_t *otbn)
	Get the size of OTBN's data memory in bytes. More...

size_t	dif_otbn_get_imem_size_bytes (const dif_otbn_t *otbn)
	Get the size of OTBN's instruction memory in bytes. More...

Detailed Description

OTBN Device Interface Functions.

Definition in file dif_otbn.h.

Typedef Documentation

◆ dif_otbn_err_bits_t

typedef enum dif_otbn_err_bits dif_otbn_err_bits_t

OTBN Errors.

OTBN uses a bitfield to indicate which errors have been seen. Multiple errors can be seen at the same time. This enum gives the individual bits that may be set for different errors.

Enumeration Type Documentation

◆ dif_otbn_err_bits

enum dif_otbn_err_bits

OTBN Errors.

OTBN uses a bitfield to indicate which errors have been seen. Multiple errors can be seen at the same time. This enum gives the individual bits that may be set for different errors.

Enumerator
kDifOtbnErrBitsBadDataAddr	A BAD_DATA_ADDR error was observed.
kDifOtbnErrBitsBadInsnAddr	A BAD_INSN_ADDR error was observed.
kDifOtbnErrBitsCallStack	A CALL_STACK error was observed.
kDifOtbnErrBitsIllegalInsn	An ILLEGAL_INSN error was observed.
kDifOtbnErrBitsLoop	A LOOP error was observed.
kDifOtbnErrBitsRndFipsChkFail	A RND_FIPS_CHECK_FAIL error was observed.
kDifOtbnErrBitsImemIntgViolation	A IMEM_INTG_VIOLATION error was observed.
kDifOtbnErrBitsDmemIntgViolation	A DMEM_INTG_VIOLATION error was observed.
kDifOtbnErrBitsRegIntgViolation	A REG_INTG_VIOLATION error was observed.
kDifOtbnErrBitsBusIntgViolation	A BUS_INTG_VIOLATION error was observed.
kDifOtbnErrBitsBadInternalState	A BAD_INTERNAL_STATE error was observed.
kDifOtbnErrBitsIllegalBusAccess	An ILLEGAL_BUS_ACCESS error was observed.
kDifOtbnErrBitsLifecycleEscalation	A LIFECYCLE_ESCALATION error was observed.
kDifOtbnErrBitsFatalSoftware	A FATAL_SOFTWARE error was observed.

Definition at line 53 of file dif_otbn.h.

Function Documentation

◆ dif_otbn_clear_load_checksum()

OT_WARN_UNUSED_RESULT dif_result_t dif_otbn_clear_load_checksum ( const dif_otbn_t * otbn )

Clears the load checksum register.

Writes 0 to the load checksum register to clear it.

Parameters

otbn	OTBN instance.

Returns: The result of the operation.

Definition at line 137 of file dif_otbn.c.

◆ dif_otbn_dmem_read()

OT_WARN_UNUSED_RESULT dif_result_t dif_otbn_dmem_read	(	const dif_otbn_t *	otbn,
		uint32_t	offset_bytes,
		void *	dest,
		size_t	len_bytes
	)

Read from OTBN's data memory (DMEM).

Only 32b-aligned 32b word accesses are allowed.

Parameters

	otbn	OTBN instance
	offset_bytes	the byte offset in DMEM the first word is read from.
[out]	dest	the main memory location to copy the data to (preallocated).
	len_bytes	number of bytes to copy.

Returns: The result of the operation.

Definition at line 186 of file dif_otbn.c.

◆ dif_otbn_dmem_write()

OT_WARN_UNUSED_RESULT dif_result_t dif_otbn_dmem_write	(	const dif_otbn_t *	otbn,
		uint32_t	offset_bytes,
		const void *	src,
		size_t	len_bytes
	)

Write to OTBN's data memory (DMEM).

Only 32b-aligned 32b word accesses are allowed.

Parameters

otbn	OTBN instance.
offset_bytes	the byte offset in DMEM the first word is written to.
src	the main memory location to start reading from.
len_bytes	number of bytes to copy.

Returns: The result of the operation.

Definition at line 173 of file dif_otbn.c.

◆ dif_otbn_get_dmem_size_bytes()

size_t dif_otbn_get_dmem_size_bytes ( const dif_otbn_t * otbn )

Get the size of OTBN's data memory in bytes.

Parameters

otbn	OTBN instance.

Returns: data memory size in bytes.

Definition at line 222 of file dif_otbn.c.

◆ dif_otbn_get_err_bits()

OT_WARN_UNUSED_RESULT dif_result_t dif_otbn_get_err_bits	(	const dif_otbn_t *	otbn,
		dif_otbn_err_bits_t *	err_bits
	)

Get the error bits set by the device if the operation failed.

Parameters

	otbn	OTBN instance.
[out]	err_bits	The error bits returned by the hardware.

Returns: The result of the operation.

Definition at line 104 of file dif_otbn.c.

◆ dif_otbn_get_imem_size_bytes()

size_t dif_otbn_get_imem_size_bytes ( const dif_otbn_t * otbn )

Get the size of OTBN's instruction memory in bytes.

Parameters

otbn	OTBN instance.

Returns: instruction memory size in bytes.

Definition at line 226 of file dif_otbn.c.

◆ dif_otbn_get_insn_cnt()

OT_WARN_UNUSED_RESULT dif_result_t dif_otbn_get_insn_cnt	(	const dif_otbn_t *	otbn,
		uint32_t *	insn_cnt
	)

Gets the number of executed OTBN instructions.

Gets the number of instructions executed so far in the current OTBN run if there is one. Otherwise, gets the number executed in total in the previous OTBN run.

Parameters

	otbn	OTBN instance.
[out]	insn_cnt	The number of instructions executed by OTBN.

Returns: The result of the operation.

Definition at line 117 of file dif_otbn.c.

◆ dif_otbn_get_load_checksum()

OT_WARN_UNUSED_RESULT dif_result_t dif_otbn_get_load_checksum	(	const dif_otbn_t *	otbn,
		uint32_t *	insn_cnt
	)

Gets the content of the load checksum register.

Gets the 32-bit CRC checksum of data written to memory.

Parameters

	otbn	OTBN instance.
[out]	insn_cnt	The number of instructions executed by OTBN.

Returns: The result of the operation.

Definition at line 126 of file dif_otbn.c.

◆ dif_otbn_get_status()

OT_WARN_UNUSED_RESULT dif_result_t dif_otbn_get_status	(	const dif_otbn_t *	otbn,
		dif_otbn_status_t *	status
	)

Gets the current status of OTBN.

Parameters

	otbn	OTBN instance.
[out]	status	OTBN status.

Returns: The result of the operation.

Definition at line 93 of file dif_otbn.c.

◆ dif_otbn_imem_read()

OT_WARN_UNUSED_RESULT dif_result_t dif_otbn_imem_read	(	const dif_otbn_t *	otbn,
		uint32_t	offset_bytes,
		void *	dest,
		size_t	len_bytes
	)

Read from OTBN's instruction memory (IMEM).

Only 32b-aligned 32b word accesses are allowed.

Parameters

	otbn	OTBN instance
	offset_bytes	the byte offset in IMEM the first word is read from.
[out]	dest	the main memory location to copy the data to (preallocated).
	len_bytes	number of bytes to copy.

Returns: The result of the operation.

Definition at line 160 of file dif_otbn.c.

◆ dif_otbn_imem_write()

OT_WARN_UNUSED_RESULT dif_result_t dif_otbn_imem_write	(	const dif_otbn_t *	otbn,
		uint32_t	offset_bytes,
		const void *	src,
		size_t	len_bytes
	)

Write an OTBN application into its instruction memory (IMEM).

Only 32b-aligned 32b word accesses are allowed.

Parameters

otbn	OTBN instance.
offset_bytes	the byte offset in IMEM the first word is written to.
src	the main memory location to start reading from.
len_bytes	number of bytes to copy.

Returns: The result of the operation.

Definition at line 147 of file dif_otbn.c.

◆ dif_otbn_reset()

OT_WARN_UNUSED_RESULT dif_result_t dif_otbn_reset ( const dif_otbn_t * otbn )

Reset OTBN device.

Resets the given OTBN device by setting its configuration registers to reset values. Disables interrupts, output, and input filter.

Parameters

otbn	OTBN instance.

Returns: The result of the operation.

Definition at line 70 of file dif_otbn.c.

◆ dif_otbn_set_ctrl_software_errs_fatal()

OT_WARN_UNUSED_RESULT dif_result_t dif_otbn_set_ctrl_software_errs_fatal	(	const dif_otbn_t *	otbn,
		bool	enable
	)

Sets the software errors are fatal bit in the control register.

When set any software error becomes a fatal error. The bit can only be changed when the OTBN status is IDLE.

Parameters

otbn	OTBN instance.
enable	Enable or disable whether software errors are fatal.

Returns: The result of the operation, kDifUnavailable is returned when the requested change cannot be made.

Definition at line 199 of file dif_otbn.c.

◆ dif_otbn_write_cmd()

OT_WARN_UNUSED_RESULT dif_result_t dif_otbn_write_cmd	(	const dif_otbn_t *	otbn,
		dif_otbn_cmd_t	cmd
	)

Start an operation by issuing a command.

Parameters

otbn	OTBN instance.
cmd	The command.

Returns: The result of the operation.

Definition at line 83 of file dif_otbn.c.

(8a1a5fe)

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ dif_otbn_err_bits_t

Enumeration Type Documentation

◆ dif_otbn_err_bits

Function Documentation

◆ dif_otbn_clear_load_checksum()

◆ dif_otbn_dmem_read()

◆ dif_otbn_dmem_write()

◆ dif_otbn_get_dmem_size_bytes()

◆ dif_otbn_get_err_bits()

◆ dif_otbn_get_imem_size_bytes()

◆ dif_otbn_get_insn_cnt()

◆ dif_otbn_get_load_checksum()

◆ dif_otbn_get_status()

◆ dif_otbn_imem_read()

◆ dif_otbn_imem_write()

◆ dif_otbn_reset()

◆ dif_otbn_set_ctrl_software_errs_fatal()

◆ dif_otbn_write_cmd()