(30d7e787c7)

OpenTitan Big Number Accelerator (OTBN) driver. More...

#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/base/status.h"
#include "sw/device/lib/dif/dif_base.h"
#include "sw/device/lib/dif/dif_otbn.h"

Go to the source code of this file.

Data Structures
struct	otbn_app
	Information about an embedded OTBN application image. More...

Macros
#define	OTBN_SYMBOL_PTR(app_name, sym) _otbn_local_app_##app_name##_##sym
	Generate the prefix to add to an OTBN symbol name used on the Ibex side. More...

#define	OTBN_SYMBOL_ADDR(app_name, sym) _otbn_remote_app_##app_name##_##sym
	Generate the prefix to add to an OTBN symbol name used on the OTBN side. More...

#define	OTBN_DECLARE_SYMBOL_PTR(app_name, symbol_name) extern const uint8_t OTBN_SYMBOL_PTR(app_name, symbol_name)[]
	Makes a symbol in the OTBN application image available. More...

#define	OTBN_DECLARE_SYMBOL_ADDR(app_name, symbol_name) extern const uint8_t OTBN_SYMBOL_ADDR(app_name, symbol_name)[]
	Makes the OTBN address of a symbol in the OTBN application available. More...

#define	OTBN_DECLARE_APP_SYMBOLS(app_name)
	Makes an embedded OTBN application image available for use. More...

#define	OTBN_APP_T_INIT(app_name)
	Initializes the OTBN application information structure. More...

#define	OTBN_ADDR_T_INIT(app_name, symbol_name) ((uint32_t)OTBN_SYMBOL_ADDR(app_name, symbol_name))
	Initializes an `otbn_addr_t`.

Typedefs
typedef struct otbn_app	otbn_app_t
	Information about an embedded OTBN application image. More...

typedef uint32_t	otbn_addr_t
	The address of an OTBN symbol as seen by OTBN. More...

Functions
OT_WARN_UNUSED_RESULT status_t	otbn_testutils_load_app (const dif_otbn_t *otbn, const otbn_app_t app)
	(Re-)loads the application into OTBN. More...

OT_WARN_UNUSED_RESULT status_t	otbn_testutils_execute (const dif_otbn_t *otbn)
	Starts the OTBN execute operation. More...

OT_WARN_UNUSED_RESULT status_t	otbn_testutils_wait_for_done (const dif_otbn_t *otbn, dif_otbn_err_bits_t expected_err_bits)
	Waits for OTBN to be done with the current operation. More...

OT_WARN_UNUSED_RESULT status_t	otbn_testutils_write_data (const dif_otbn_t otbn, size_t len_bytes, const void src, otbn_addr_t dest)
	Copies data from the CPU memory to OTBN data memory. More...

OT_WARN_UNUSED_RESULT status_t	otbn_testutils_read_data (const dif_otbn_t otbn, size_t len_bytes, otbn_addr_t src, void dest)
	Copies data from OTBN's data memory to CPU memory. More...

OT_WARN_UNUSED_RESULT status_t	otbn_testutils_dump_dmem (const dif_otbn_t *otbn, uint32_t max_addr)
	Writes a LOG_INFO message with the contents of each 256b DMEM word. More...

Detailed Description

OpenTitan Big Number Accelerator (OTBN) driver.

Definition in file otbn_testutils.h.

Data Structure Documentation

◆ otbn_app

struct otbn_app

Information about an embedded OTBN application image.

All pointers reference data in the normal CPU address space. uint32_t values are addresses in the OTBN address space.

Use OTBN_DECLARE_APP_SYMBOLS() together with OTBN_APP_T_INIT() to initialize this structure.

All pointers reference data in the normal CPU address space.

Use OTBN_DECLARE_APP_SYMBOLS() together with OTBN_APP_T_INIT() to initialize this structure.

Definition at line 47 of file otbn.h.

Data Fields
const uint32_t	checksum	Application checksum. This value represents a CRC32 checksum over IMEM and the `.data` portion of DMEM.
const uint32_t *	dmem_data_end	The first word after initialized OTBN data in the embedded program. This pointer references Ibex's memory. Should satisfy `dmem_data_start <= dmem_data_end`.
const uint8_t *	dmem_data_end	End of initialized OTBN data memory.
const uint32_t *	dmem_data_start	Start of initialized OTBN data in the embedded program. This pointer references Ibex's memory. Data in between `dmem_data_start` and `dmem_data_end` will be copied to OTBN at app load time.
const uint8_t *	dmem_data_start	Start of initialized OTBN data memory. Data in this section is copied into DMEM when the app is loaded.
const otbn_addr_t	dmem_data_start_addr	Start of initialized data section in OTBN's DMEM. This pointer references OTBN's memory and is used to copy data at app load time.
const uint32_t *	imem_end	The first word after OTBN instruction memory in the embedded program. This pointer references Ibex's memory. This address satifies `imem_start < imem_end`.
const uint8_t *	imem_end	End of OTBN instruction memory.
const uint32_t *	imem_start	Start of OTBN instruction memory in the embedded program. This pointer references Ibex's memory.
const uint8_t *	imem_start	Start of OTBN instruction memory.

Macro Definition Documentation

◆ OTBN_APP_T_INIT

#define OTBN_APP_T_INIT ( app_name )

Value:

  ((otbn_app_t){                                                      \
      .imem_start = OTBN_SYMBOL_PTR(app_name, _imem_start),           \
      .imem_end = OTBN_SYMBOL_PTR(app_name, _imem_end),               \
      .dmem_data_start = OTBN_SYMBOL_PTR(app_name, _dmem_data_start), \
      .dmem_data_end = OTBN_SYMBOL_PTR(app_name, _dmem_data_end),     \
  })

Initializes the OTBN application information structure.

After making all required symbols from the application image available through OTBN_DECLARE_APP_SYMBOLS(), use this macro to initialize an otbn_app_t struct with those symbols.

Parameters

app_name Name of the application to load.

See also: OTBN_DECLARE_APP_SYMBOLS()

Definition at line 133 of file otbn_testutils.h.

◆ OTBN_DECLARE_APP_SYMBOLS

#define OTBN_DECLARE_APP_SYMBOLS ( app_name )

Value:

  OTBN_DECLARE_SYMBOL_PTR(app_name, _imem_start);      \
  OTBN_DECLARE_SYMBOL_PTR(app_name, _imem_end);        \
  OTBN_DECLARE_SYMBOL_PTR(app_name, _dmem_data_start); \
  OTBN_DECLARE_SYMBOL_PTR(app_name, _dmem_data_end)

Makes an embedded OTBN application image available for use.

Make symbols available that indicate the start and the end of instruction and data memory regions, as they are stored in the device memory.

Use this macro instead of manually declaring the symbols as symbol names might change.

Parameters

app_name Name of the application to load, which is typically the name of the main (assembly) source file.

Definition at line 117 of file otbn_testutils.h.

◆ OTBN_DECLARE_SYMBOL_ADDR

#define OTBN_DECLARE_SYMBOL_ADDR	(	app_name,
		symbol_name
	)	extern const uint8_t OTBN_SYMBOL_ADDR(app_name, symbol_name)[]

Makes the OTBN address of a symbol in the OTBN application available.

Symbols are typically function or data pointers, i.e. labels in assembly code. Unlike OTBN_DECLARE_SYMBOL_PTR, this will work for symbols in the .bss section (which exist on the OTBN side, even though they don't have backing data on Ibex).

Use this macro instead of manually declaring the symbols as symbol names might change.

Parameters

app_name	Name of the application the function is contained in.
symbol_name	Name of the symbol (function, label).

Definition at line 102 of file otbn_testutils.h.

◆ OTBN_DECLARE_SYMBOL_PTR

#define OTBN_DECLARE_SYMBOL_PTR	(	app_name,
		symbol_name
	)	extern const uint8_t OTBN_SYMBOL_PTR(app_name, symbol_name)[]

Makes a symbol in the OTBN application image available.

This is needed by the OTBN driver to support DMEM/IMEM ranges but application code shouldn't need to use this. To get access to OTBN addresses, use OTBN_DECLARE_SYMBOL_ADDR instead.

Definition at line 85 of file otbn_testutils.h.

◆ OTBN_SYMBOL_ADDR

#define OTBN_SYMBOL_ADDR	(	app_name,
		sym
	)	_otbn_remote_app_##app_name##_##sym

Generate the prefix to add to an OTBN symbol name used on the OTBN side.

The result is a pointer whose integer value is the address by which the symbol should be accessed in OTBN memory.

This is an internal macro used in OTBN_DECLARE_SYMBOL_ADDR and OTBN_ADDR_T_INIT but application code shouldn't need to use it directly.

Definition at line 76 of file otbn_testutils.h.

◆ OTBN_SYMBOL_PTR

#define OTBN_SYMBOL_PTR	(	app_name,
		sym
	)	_otbn_local_app_##app_name##_##sym

Generate the prefix to add to an OTBN symbol name used on the Ibex side.

The result is a pointer to Ibex's rodata that should be used to initialise memory for that symbol.

This is needed by the OTBN driver to support DMEM/IMEM ranges but application code shouldn't need to use this. Use the otbn_addr_t type and supporting macros instead.

Definition at line 65 of file otbn_testutils.h.

Typedef Documentation

◆ otbn_addr_t

typedef uint32_t otbn_addr_t

The address of an OTBN symbol as seen by OTBN.

Use OTBN_DECLARE_SYMBOL_ADDR() together with OTBN_ADDR_T_INIT() to initialize this type.

Definition at line 53 of file otbn_testutils.h.

◆ otbn_app_t

typedef struct otbn_app otbn_app_t

Information about an embedded OTBN application image.

All pointers reference data in the normal CPU address space.

Use OTBN_DECLARE_APP_SYMBOLS() together with OTBN_APP_T_INIT() to initialize this structure.

Function Documentation

◆ otbn_testutils_dump_dmem()

OT_WARN_UNUSED_RESULT status_t otbn_testutils_dump_dmem	(	const dif_otbn_t *	otbn,
		uint32_t	max_addr
	)

Writes a LOG_INFO message with the contents of each 256b DMEM word.

Parameters

otbn	The context object.
max_addr	The highest address to dump. Set to 0 to output the whole DMEM. Must be a multiple of WLEN.

Returns: The result of the operation.

◆ otbn_testutils_execute()

OT_WARN_UNUSED_RESULT status_t otbn_testutils_execute ( const dif_otbn_t * otbn )

Starts the OTBN execute operation.

Use otbn_testutils_wait_for_done() to wait for execution to complete.

Parameters

otbn	The context object.

Returns: The result of the operation.

Definition at line 87 of file otbn_testutils.c.

◆ otbn_testutils_load_app()

OT_WARN_UNUSED_RESULT status_t otbn_testutils_load_app	(	const dif_otbn_t *	otbn,
		const otbn_app_t	app
	)

(Re-)loads the application into OTBN.

Load the application image with both instruction and data segments into OTBN.

Parameters

otbn	The context object.
app	The application to load into OTBN.

Returns: The result of the operation.

Definition at line 68 of file otbn_testutils.c.

◆ otbn_testutils_read_data()

OT_WARN_UNUSED_RESULT status_t otbn_testutils_read_data	(	const dif_otbn_t *	otbn,
		size_t	len_bytes,
		otbn_addr_t	src,
		void *	dest
	)

Copies data from OTBN's data memory to CPU memory.

Parameters

	otbn	The context object.
	len_bytes	The number of bytes to copy.
	src	The address in OTBN data memory to copy from.
[out]	dest	The destination of the copied data in main memory (preallocated).

Returns: The result of the operation.

Definition at line 98 of file otbn_testutils.c.

◆ otbn_testutils_wait_for_done()

OT_WARN_UNUSED_RESULT status_t otbn_testutils_wait_for_done	(	const dif_otbn_t *	otbn,
		dif_otbn_err_bits_t	expected_err_bits
	)

Waits for OTBN to be done with the current operation.

Polls the status register until OTBN is idle. Produces a CHECK-fail if OTBN is or becomes locked. Checks that the final error bits match expectations.

Parameters

otbn	The context object.
expected_err_bits	Expected error bits.

Returns: The result of the operation.

Definition at line 22 of file otbn_testutils.c.

◆ otbn_testutils_write_data()

OT_WARN_UNUSED_RESULT status_t otbn_testutils_write_data	(	const dif_otbn_t *	otbn,
		size_t	len_bytes,
		const void *	src,
		otbn_addr_t	dest
	)

Copies data from the CPU memory to OTBN data memory.

Parameters

otbn	The context object.
len_bytes	Number of bytes to copy.
dest	Address of the destination in OTBN's data memory.
src	Source of the data to copy.

Returns: The result of the operation.

Definition at line 92 of file otbn_testutils.c.

(30d7e787c7)

Data Structures

Macros

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ otbn_app

Macro Definition Documentation

◆ OTBN_APP_T_INIT

◆ OTBN_DECLARE_APP_SYMBOLS

◆ OTBN_DECLARE_SYMBOL_ADDR

◆ OTBN_DECLARE_SYMBOL_PTR

◆ OTBN_SYMBOL_ADDR

◆ OTBN_SYMBOL_PTR

Typedef Documentation

◆ otbn_addr_t

◆ otbn_app_t

Function Documentation

◆ otbn_testutils_dump_dmem()

◆ otbn_testutils_execute()

◆ otbn_testutils_load_app()

◆ otbn_testutils_read_data()

◆ otbn_testutils_wait_for_done()

◆ otbn_testutils_write_data()