Software APIs
Data Structures | Macros | Typedefs | Enumerations | Functions
otbn.h File Reference

(b233d14)

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

#include "sw/device/lib/base/mmio.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...
 
struct  otbn
 OTBN context structure. 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...
 
typedef enum otbn_result otbn_result_t
 The result of an OTBN operation.
 
typedef struct otbn otbn_t
 OTBN context structure. More...
 

Enumerations

enum  otbn_result {
  kOtbnOk = 0,
  kOtbnError = 1,
  kOtbnBadArg = 2,
  kOtbnOperationFailed = 3
}
 The result of an OTBN operation. More...
 

Functions

otbn_result_t otbn_init (otbn_t *ctx, mmio_region_t base_addr)
 Initializes the OTBN context structure. More...
 
otbn_result_t otbn_load_app (otbn_t *ctx, const otbn_app_t app)
 (Re-)loads the application into OTBN. More...
 
otbn_result_t otbn_execute (otbn_t *ctx)
 Starts the OTBN execute operation. More...
 
otbn_result_t otbn_busy_wait_for_done (otbn_t *ctx)
 Busy waits for OTBN to be done with the current operation. More...
 
otbn_result_t otbn_copy_data_to_otbn (otbn_t *ctx, size_t len_bytes, const void *src, otbn_addr_t dest)
 Copies data from the CPU memory to OTBN data memory. More...
 
otbn_result_t otbn_copy_data_from_otbn (otbn_t *ctx, size_t len_bytes, otbn_addr_t src, void *dest)
 Copies data from OTBN's data memory to CPU memory. More...
 
otbn_result_t otbn_zero_data_memory (otbn_t *ctx)
 Overwrites all of OTBN's data memory with zeros. More...
 
otbn_result_t otbn_dump_dmem (const otbn_t *ctx, 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.h.

Macro Definition Documentation

◆ OTBN_APP_T_INIT

#define OTBN_APP_T_INIT (   app_name)
Value:
.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_nameName of the application to load.
See also
OTBN_DECLARE_APP_SYMBOLS()

Definition at line 181 of file otbn.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_nameName of the application to load, which is typically the name of the main (assembly) source file.

Definition at line 165 of file otbn.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_nameName of the application the function is contained in.
symbol_nameName of the symbol (function, label).

Definition at line 150 of file otbn.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 133 of file otbn.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 124 of file otbn.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 113 of file otbn.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 52 of file otbn.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.

◆ otbn_t

typedef struct otbn otbn_t

OTBN context structure.

Use otbn_init() to initialize.

Enumeration Type Documentation

◆ otbn_result

The result of an OTBN operation.

Enumerator
kOtbnOk 

The operation succeeded.

kOtbnError 

An unspecified failure occurred.

kOtbnBadArg 

A precondition check for an argument passed into the function failed.

kOtbnOperationFailed 

The operation performed on OTBN failed.

More specific error information can be obtained with dif_otbn_get_err_code().

Definition at line 57 of file otbn.h.

Function Documentation

◆ otbn_busy_wait_for_done()

otbn_result_t otbn_busy_wait_for_done ( otbn_t ctx)

Busy waits for OTBN to be done with the current operation.

After an operation, triggered by a command, OTBN is back in idle state.

Parameters
ctxThe context object.
Returns
The result of the operation.

Busy waits for OTBN to be done with the current operation.

Parameters
ctxThe context object.
Returns
The result of the operation.

Definition at line 21 of file otbn_util.c.

◆ otbn_copy_data_from_otbn()

otbn_result_t otbn_copy_data_from_otbn ( otbn_t ctx,
size_t  len_bytes,
otbn_addr_t  src,
void *  dest 
)

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

Parameters
ctxThe context object.
len_bytesThe number of bytes to copy.
srcThe address in OTBN data memory to copy from.
[out]destThe destination of the copied data in main memory (preallocated).
Returns
The result of the operation.

Definition at line 137 of file otbn.c.

◆ otbn_copy_data_to_otbn()

otbn_result_t otbn_copy_data_to_otbn ( otbn_t ctx,
size_t  len_bytes,
const void *  src,
otbn_addr_t  dest 
)

Copies data from the CPU memory to OTBN data memory.

Parameters
ctxThe context object.
len_bytesNumber of bytes to copy.
destAddress of the destination in OTBN's data memory.
srcSource of the data to copy.
Returns
The result of the operation.

Definition at line 125 of file otbn.c.

◆ otbn_dump_dmem()

otbn_result_t otbn_dump_dmem ( const otbn_t ctx,
uint32_t  max_addr 
)

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

Parameters
ctxThe context object.
max_addrThe highest address to dump. Set to 0 to output the whole DMEM. Must be a multiple of WLEN.
Returns
The result of the operation.

Definition at line 170 of file otbn.c.

◆ otbn_execute()

otbn_result_t otbn_execute ( otbn_t ctx)

Starts the OTBN execute operation.

Use otbn_busy_wait_for_done() to wait for execution to complete.

Parameters
ctxThe context object.
Returns
The result of the operation.

Definition at line 113 of file otbn.c.

◆ otbn_init()

otbn_result_t otbn_init ( otbn_t ctx,
mmio_region_t  base_addr 
)

Initializes the OTBN context structure.

Parameters
ctxThe context object.
base_addrThe OTBN hardware base address.
Returns
The result of the operation.

Definition at line 37 of file otbn.c.

◆ otbn_load_app()

otbn_result_t otbn_load_app ( otbn_t ctx,
const otbn_app_t  app 
)

(Re-)loads the application into OTBN.

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

Parameters
ctxThe context object.
appThe application to load into OTBN.
Returns
The result of the operation.

(Re-)loads the application into OTBN.

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

Parameters
ctxThe context object.
appThe application to load into OTBN.
Returns
The result of the operation.

Definition at line 57 of file otbn_util.c.

◆ otbn_zero_data_memory()

otbn_result_t otbn_zero_data_memory ( otbn_t ctx)

Overwrites all of OTBN's data memory with zeros.

This function tries to perform the operation for all data words, even if a single write fails.

Parameters
ctxThe context object.
Returns
The result of the operation.

Definition at line 149 of file otbn.c.