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

(dcee03a)

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

#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,
  kOtbnExecutionFailed = 3
}
 The result of an OTBN operation. More...
 

Functions

otbn_result_t otbn_init (otbn_t *ctx, const dif_otbn_config_t dif_config)
 Initializes the OTBN context structure. More...
 
otbn_result_t otbn_load_app (otbn_t *ctx, const otbn_app_t app)
 (Re-)loads the RSA application into OTBN. More...
 
otbn_result_t otbn_call_function (otbn_t *ctx, otbn_ptr_t func)
 Calls a function on OTBN. More...
 
otbn_result_t otbn_busy_wait_for_done (otbn_t *ctx)
 Busy waits for OTBN to be done with its 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...
 

Detailed Description

OpenTitan Big Number Accelerator (OTBN) driver.

Definition in file otbn.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.

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

Definition at line 23 of file otbn.h.

Data Fields
const uint8_t * dmem_end End of OTBN data memory.
const uint8_t * dmem_start Start of OTBN data memory.
const uint8_t * imem_end End of OTBN instruction memory.
const uint8_t * imem_start Start of OTBN instruction memory.

◆ otbn

struct otbn

OTBN context structure.

Use otbn_init() to initialize.

Definition at line 83 of file otbn.h.

Data Fields
otbn_app_t app The application loaded or to be loaded into OTBN.

Only valid if app_is_loaded is true.

bool app_is_loaded Is the application loaded into OTBN?
dif_otbn_t dif The OTBN DIF to access the hardware.

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 130 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 114 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 150 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 51 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.

kOtbnExecutionFailed 

The execution of the application on OTBN failed.

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

Definition at line 56 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 its operation.

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

Definition at line 58 of file otbn.c.

◆ otbn_call_function()

otbn_result_t otbn_call_function ( otbn_t ctx,
otbn_ptr_t  func 
)

Calls a function on OTBN.

Set the entry point (start address) of OTBN to the desired function, and starts the OTBN operation.

Use otbn_busy_wait_for_done() to wait for the function call to complete.

Parameters
ctxThe context object.
funcThe function to be called.
Returns
The result of the operation.

Definition at line 122 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 159 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 140 of file otbn.c.

◆ otbn_init()

otbn_result_t otbn_init ( otbn_t ctx,
const dif_otbn_config_t  dif_config 
)

Initializes the OTBN context structure.

Parameters
ctxThe context object.
dif_configThe OTBN DIF configuration (passed on to the DIF).
Returns
The result of the operation.

Definition at line 76 of file otbn.c.

◆ otbn_load_app()

otbn_result_t otbn_load_app ( otbn_t ctx,
const otbn_app_t  app 
)

(Re-)loads the RSA 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 90 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 178 of file otbn.c.