Asymmetric Cryptographic Coprocessor (ACC) driver. More...

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

Data Structures
struct	acc_app
	Information about an embedded ACC application image. More...

Macros
#define	ACC_SYMBOL_PTR(app_name, sym)
	Generate the prefix to add to an ACC symbol name used on the Ibex side.

#define	ACC_SYMBOL_ADDR(app_name, sym)
	Generate the prefix to add to an ACC symbol name used on the ACC side.

#define	ACC_DECLARE_SYMBOL_PTR(app_name, symbol_name)
	Makes a symbol in the ACC application image available.

#define	ACC_DECLARE_SYMBOL_ADDR(app_name, symbol_name)
	Makes the ACC address of a symbol in the ACC application available.

#define	ACC_DECLARE_APP_SYMBOLS(app_name)
	Makes an embedded ACC application image available for use.

#define	ACC_APP_T_INIT(app_name)
	Initializes the ACC application information structure.

#define	ACC_ADDR_T_INIT(app_name, symbol_name)
	Initializes an `acc_addr_t`.

Typedefs
typedef struct acc_app	acc_app_t
	Information about an embedded ACC application image.

typedef uint32_t	acc_addr_t
	The address of an ACC symbol as seen by ACC.

Functions
OT_WARN_UNUSED_RESULT status_t	acc_testutils_load_app (const dif_acc_t *acc, const acc_app_t app)
	(Re-)loads the application into ACC.

OT_WARN_UNUSED_RESULT status_t	acc_testutils_execute (const dif_acc_t *acc)
	Starts the ACC execute operation.

OT_WARN_UNUSED_RESULT status_t	acc_testutils_wait_for_done (const dif_acc_t *acc, dif_acc_err_bits_t expected_err_bits)
	Waits for ACC to be done with the current operation.

OT_WARN_UNUSED_RESULT status_t	acc_testutils_write_data (const dif_acc_t acc, size_t len_bytes, const void src, acc_addr_t dest)
	Copies data from the CPU memory to ACC data memory.

OT_WARN_UNUSED_RESULT status_t	acc_testutils_read_data (const dif_acc_t acc, size_t len_bytes, acc_addr_t src, void dest)
	Copies data from ACC's data memory to CPU memory.

OT_WARN_UNUSED_RESULT status_t	acc_testutils_dump_dmem (const dif_acc_t *acc, uint32_t max_addr)
	Writes a LOG_INFO message with the contents of each 256b DMEM word.

Detailed Description

Asymmetric Cryptographic Coprocessor (ACC) driver.

Definition in file acc_testutils.h.

Data Structure Documentation

◆ acc_app

struct acc_app

Information about an embedded ACC application image.

All pointers reference data in the normal CPU address space.

Use ACC_DECLARE_APP_SYMBOLS() together with ACC_APP_T_INIT() to initialize this structure.

Definition at line 26 of file acc_testutils.h.

Data Fields
const uint8_t *	dmem_data_end	End of initialized ACC data memory.
const uint8_t *	dmem_data_start	Start of initialized ACC data memory. Data in this section is copied into DMEM when the app is loaded.
const uint8_t *	imem_end	End of ACC instruction memory.
const uint8_t *	imem_start	Start of ACC instruction memory.

Macro Definition Documentation

◆ ACC_ADDR_T_INIT

#define ACC_ADDR_T_INIT	(		app_name,
			symbol_name )

Value:

((uint32_t)ACC_SYMBOL_ADDR(app_name, symbol_name))

Initializes an acc_addr_t.

Definition at line 144 of file acc_testutils.h.

◆ ACC_APP_T_INIT

#define ACC_APP_T_INIT ( app_name )

Value:

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

Initializes the ACC application information structure.

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

Parameters

app_name Name of the application to load.

See also: ACC_DECLARE_APP_SYMBOLS()

Definition at line 133 of file acc_testutils.h.

◆ ACC_DECLARE_APP_SYMBOLS

#define ACC_DECLARE_APP_SYMBOLS ( app_name )

Value:

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

Makes an embedded ACC 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 acc_testutils.h.

◆ ACC_DECLARE_SYMBOL_ADDR

#define ACC_DECLARE_SYMBOL_ADDR	(		app_name,
			symbol_name )

Value:

extern const uint8_t ACC_SYMBOL_ADDR(app_name, symbol_name)[]

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

Symbols are typically function or data pointers, i.e. labels in assembly code. Unlike ACC_DECLARE_SYMBOL_PTR, this will work for symbols in the .bss section (which exist on the ACC 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 acc_testutils.h.

◆ ACC_DECLARE_SYMBOL_PTR

#define ACC_DECLARE_SYMBOL_PTR	(		app_name,
			symbol_name )

Value:

extern const uint8_t ACC_SYMBOL_PTR(app_name, symbol_name)[]

Makes a symbol in the ACC application image available.

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

Definition at line 85 of file acc_testutils.h.

◆ ACC_SYMBOL_ADDR

#define ACC_SYMBOL_ADDR	(		app_name,
			sym )

Value:

_acc_remote_app_##app_name##_##sym

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

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

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

Definition at line 76 of file acc_testutils.h.

◆ ACC_SYMBOL_PTR

#define ACC_SYMBOL_PTR	(		app_name,
			sym )

Value:

_acc_local_app_##app_name##_##sym

Generate the prefix to add to an ACC 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 ACC driver to support DMEM/IMEM ranges but application code shouldn't need to use this. Use the acc_addr_t type and supporting macros instead.

Definition at line 65 of file acc_testutils.h.

Typedef Documentation

◆ acc_addr_t

typedef uint32_t acc_addr_t

The address of an ACC symbol as seen by ACC.

Use ACC_DECLARE_SYMBOL_ADDR() together with ACC_ADDR_T_INIT() to initialize this type.

Definition at line 53 of file acc_testutils.h.

◆ acc_app_t

typedef struct acc_app acc_app_t

Information about an embedded ACC application image.

All pointers reference data in the normal CPU address space.

Use ACC_DECLARE_APP_SYMBOLS() together with ACC_APP_T_INIT() to initialize this structure.

Function Documentation

◆ acc_testutils_dump_dmem()

OT_WARN_UNUSED_RESULT status_t acc_testutils_dump_dmem	(	const dif_acc_t *	acc,
		uint32_t	max_addr )

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

Parameters

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

◆ acc_testutils_execute()

OT_WARN_UNUSED_RESULT status_t acc_testutils_execute ( const dif_acc_t * acc )

Starts the ACC execute operation.

Use acc_testutils_wait_for_done() to wait for execution to complete.

Parameters

acc	The context object.

Returns: The result of the operation.

Definition at line 87 of file acc_testutils.c.

◆ acc_testutils_load_app()

OT_WARN_UNUSED_RESULT status_t acc_testutils_load_app	(	const dif_acc_t *	acc,
		const acc_app_t	app )

(Re-)loads the application into ACC.

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

Parameters

acc	The context object.
app	The application to load into ACC.

Returns: The result of the operation.

Definition at line 68 of file acc_testutils.c.

◆ acc_testutils_read_data()

OT_WARN_UNUSED_RESULT status_t acc_testutils_read_data	(	const dif_acc_t *	acc,
		size_t	len_bytes,
		acc_addr_t	src,
		void *	dest )

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

Parameters

	acc	The context object.
	len_bytes	The number of bytes to copy.
	src	The address in ACC 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 acc_testutils.c.

◆ acc_testutils_wait_for_done()

OT_WARN_UNUSED_RESULT status_t acc_testutils_wait_for_done	(	const dif_acc_t *	acc,
		dif_acc_err_bits_t	expected_err_bits )

Waits for ACC to be done with the current operation.

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

Parameters

acc	The context object.
expected_err_bits	Expected error bits.

Returns: The result of the operation.

Definition at line 22 of file acc_testutils.c.

◆ acc_testutils_write_data()

OT_WARN_UNUSED_RESULT status_t acc_testutils_write_data	(	const dif_acc_t *	acc,
		size_t	len_bytes,
		const void *	src,
		acc_addr_t	dest )

Copies data from the CPU memory to ACC data memory.

Parameters

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

Returns: The result of the operation.

Definition at line 92 of file acc_testutils.c.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ acc_app

Macro Definition Documentation

◆ ACC_ADDR_T_INIT

◆ ACC_APP_T_INIT

◆ ACC_DECLARE_APP_SYMBOLS

◆ ACC_DECLARE_SYMBOL_ADDR

◆ ACC_DECLARE_SYMBOL_PTR

◆ ACC_SYMBOL_ADDR

◆ ACC_SYMBOL_PTR

Typedef Documentation

◆ acc_addr_t

◆ acc_app_t

Function Documentation

◆ acc_testutils_dump_dmem()

◆ acc_testutils_execute()

◆ acc_testutils_load_app()

◆ acc_testutils_read_data()

◆ acc_testutils_wait_for_done()

◆ acc_testutils_write_data()