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

(5e04ded)

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_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_DECLARE_PTR_SYMBOL(app_name, symbol_name)   extern const uint8_t _otbn_app_##app_name##_##symbol_name[]
 Makes a symbol in the OTBN application image available. More...
 
#define OTBN_PTR_T_INIT(app_name, symbol_name)   ((otbn_ptr_t)_otbn_app_##app_name##_##symbol_name)
 Initializes an otbn_ptr_t.
 

Typedefs

typedef struct otbn_app otbn_app_t
 Information about an embedded OTBN application image. More...
 
typedef uint8_t * otbn_ptr_t
 A pointer to a symbol in OTBN's instruction or data memory. 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_ptr_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, const otbn_ptr_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_data_ptr_to_dmem_addr (const otbn_t *ctx, otbn_ptr_t ptr, uint32_t *dmem_addr_otbn)
 Gets the address in OTBN data memory referenced by ptr. 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_app_##app_name##__imem_start, \
.imem_end = _otbn_app_##app_name##__imem_end, \
.dmem_start = _otbn_app_##app_name##__dmem_start, \
.dmem_end = _otbn_app_##app_name##__dmem_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 132 of file otbn.h.

◆ OTBN_DECLARE_APP_SYMBOLS

#define OTBN_DECLARE_APP_SYMBOLS (   app_name)
Value:
extern const uint8_t _otbn_app_##app_name##__imem_start[]; \
extern const uint8_t _otbn_app_##app_name##__imem_end[]; \
extern const uint8_t _otbn_app_##app_name##__dmem_start[]; \
extern const uint8_t _otbn_app_##app_name##__dmem_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 116 of file otbn.h.

◆ OTBN_DECLARE_PTR_SYMBOL

#define OTBN_DECLARE_PTR_SYMBOL (   app_name,
  symbol_name 
)    extern const uint8_t _otbn_app_##app_name##_##symbol_name[]

Makes a symbol in the OTBN application image available.

Symbols are typically function or data pointers, i.e. labels in assembly code.

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 152 of file otbn.h.

Typedef Documentation

◆ 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_ptr_t

typedef uint8_t* otbn_ptr_t

A pointer to a symbol in OTBN's instruction or data memory.

Use OTBN_DECLARE_PTR_SYMBOL() together with OTBN_PTR_T_INIT() to initialize this type.

The value of the pointer is an address in the normal CPU address space, and must be first converted into OTBN address space before it can be used there.

Definition at line 53 of file otbn.h.

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

Definition at line 31 of file otbn.c.

◆ otbn_copy_data_from_otbn()

otbn_result_t otbn_copy_data_from_otbn ( otbn_t ctx,
size_t  len_bytes,
const otbn_ptr_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 pointer 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 128 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_ptr_t  dest 
)

Copies data from the CPU memory to OTBN data memory.

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

Definition at line 109 of file otbn.c.

◆ otbn_data_ptr_to_dmem_addr()

otbn_result_t otbn_data_ptr_to_dmem_addr ( const otbn_t ctx,
otbn_ptr_t  ptr,
uint32_t *  dmem_addr_otbn 
)

Gets the address in OTBN data memory referenced by ptr.

Parameters
ctxThe context object.
ptrThe pointer to convert.
[out]dmem_addr_otbnThe address of the data in OTBN's data memory.
Returns
The result of the operation; kOtbnBadArg if ptr is not in the data memory space of the currently loaded application.

Definition at line 17 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 167 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 97 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 51 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.

Definition at line 65 of file otbn.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 146 of file otbn.c.