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

(915ba13)

OTBN Device Interface Functions More...

#include <stddef.h>
#include <stdint.h>
#include "sw/device/lib/base/mmio.h"

Go to the source code of this file.

Data Structures

struct  dif_otbn_config
 Configuration for initializing an OTBN device. More...
 
struct  dif_otbn
 Internal state of a OTBN device. More...
 

Typedefs

typedef struct dif_otbn_config dif_otbn_config_t
 Configuration for initializing an OTBN device.
 
typedef struct dif_otbn dif_otbn_t
 Internal state of a OTBN device. More...
 
typedef enum dif_otbn_result dif_otbn_result_t
 Generic return codes for the functions in the OTBN DIF library.
 
typedef enum dif_otbn_cmd dif_otbn_cmd_t
 OTBN commands.
 
typedef enum dif_otbn_status dif_otbn_status_t
 OTBN status.
 
typedef enum dif_otbn_err_bits dif_otbn_err_bits_t
 OTBN Errors. More...
 
typedef enum dif_otbn_interrupt dif_otbn_interrupt_t
 OTBN interrupt configuration. More...
 
typedef enum dif_otbn_enable dif_otbn_enable_t
 Generic enable/disable enumeration. More...
 

Enumerations

enum  dif_otbn_result {
  kDifOtbnOk,
  kDifOtbnError,
  kDifOtbnBadArg
}
 Generic return codes for the functions in the OTBN DIF library. More...
 
enum  dif_otbn_cmd {
  kDifOtbnCmdExecute = 0x01,
  kDifOtbnCmdSecWipeDmem = 0x02,
  kDifOtbnCmdSecWipeImem = 0x03,
  kOtbnCmdExecute = 0x01,
  kOtbnCmdSecWipeDmem = 0x02,
  kOtbnCmdSecWipeImem = 0x03
}
 OTBN commands.
 
enum  dif_otbn_status {
  kDifOtbnStatusIdle = 0x00,
  kDifOtbnStatusBusyExecute = 0x01,
  kDifOtbnStatusBusySecWipeDmem = 0x02,
  kDifOtbnStatusBusySecWipeImem = 0x03,
  kDifOtbnStatusLocked = 0xFF
}
 OTBN status.
 
enum  dif_otbn_err_bits {
  kDifOtbnErrBitsNoError = 0,
  kDifOtbnErrBitsBadDataAddr = (1 << 0),
  kDifOtbnErrBitsBadInsnAddr = (1 << 1),
  kDifOtbnErrBitsCallStack = (1 << 2),
  kDifOtbnErrBitsIllegalInsn = (1 << 3),
  kDifOtbnErrBitsLoop = (1 << 4),
  kDifOtbnErrBitsImemIntgViolation = (1 << 16),
  kDifOtbnErrBitsDmemIntgViolation = (1 << 17),
  kDifOtbnErrBitsRegIntgViolation = (1 << 18),
  kDifOtbnErrBitsBusIntgViolation = (1 << 19),
  kDifOtbnErrBitsIllegalBusAccess = (1 << 20),
  kDifOtbnErrBitsLifecycleEscalation = (1 << 21)
}
 OTBN Errors. More...
 
enum  dif_otbn_interrupt { kDifOtbnInterruptDone = 0 }
 OTBN interrupt configuration. More...
 
enum  dif_otbn_enable {
  kDifOtbnEnable = 0,
  kDifOtbnDisable
}
 Generic enable/disable enumeration. More...
 

Functions

dif_otbn_result_t dif_otbn_init (const dif_otbn_config_t *config, dif_otbn_t *otbn)
 Initialize a OTBN device using config and return its internal state. More...
 
dif_otbn_result_t dif_otbn_reset (const dif_otbn_t *otbn)
 Reset OTBN device. More...
 
dif_otbn_result_t dif_otbn_irq_state_get (const dif_otbn_t *otbn, dif_otbn_interrupt_t irq_type, dif_otbn_enable_t *state)
 OTBN get requested IRQ state. More...
 
dif_otbn_result_t dif_otbn_irq_state_clear (const dif_otbn_t *otbn, dif_otbn_interrupt_t irq_type)
 OTBN clear requested IRQ state. More...
 
dif_otbn_result_t dif_otbn_irqs_disable (const dif_otbn_t *otbn, uint32_t *state)
 OTBN disable interrupts. More...
 
dif_otbn_result_t dif_otbn_irqs_restore (const dif_otbn_t *otbn, uint32_t state)
 OTBN restore IRQ state. More...
 
dif_otbn_result_t dif_otbn_irq_control (const dif_otbn_t *otbn, dif_otbn_interrupt_t irq_type, dif_otbn_enable_t enable)
 OTBN interrupt control. More...
 
dif_otbn_result_t dif_otbn_irq_force (const dif_otbn_t *otbn, dif_otbn_interrupt_t irq_type)
 OTBN interrupt force. More...
 
dif_otbn_result_t dif_otbn_set_start_addr (const dif_otbn_t *otbn, unsigned int start_addr)
 Set the start address of the execution. More...
 
dif_otbn_result_t dif_otbn_write_cmd (const dif_otbn_t *otbn, dif_otbn_cmd_t cmd)
 Start an operation by issuing a command. More...
 
dif_otbn_result_t dif_otbn_get_status (const dif_otbn_t *otbn, dif_otbn_status_t *status)
 Gets the current status of OTBN. More...
 
dif_otbn_result_t dif_otbn_get_err_bits (const dif_otbn_t *otbn, dif_otbn_err_bits_t *err_bits)
 Get the error bits set by the device if the operation failed. More...
 
dif_otbn_result_t dif_otbn_get_insn_cnt (const dif_otbn_t *otbn, uint32_t *insn_cnt)
 Gets the number of executed OTBN instructions. More...
 
dif_otbn_result_t dif_otbn_imem_write (const dif_otbn_t *otbn, uint32_t offset_bytes, const void *src, size_t len_bytes)
 Write an OTBN application into its instruction memory (IMEM) More...
 
dif_otbn_result_t dif_otbn_imem_read (const dif_otbn_t *otbn, uint32_t offset_bytes, void *dest, size_t len_bytes)
 Read from OTBN's instruction memory (IMEM) More...
 
dif_otbn_result_t dif_otbn_dmem_write (const dif_otbn_t *otbn, uint32_t offset_bytes, const void *src, size_t len_bytes)
 Write to OTBN's data memory (DMEM) More...
 
dif_otbn_result_t dif_otbn_dmem_read (const dif_otbn_t *otbn, uint32_t offset_bytes, void *dest, size_t len_bytes)
 Read from OTBN's data memory (DMEM) More...
 
size_t dif_otbn_get_dmem_size_bytes (const dif_otbn_t *otbn)
 Get the size of OTBN's data memory in bytes. More...
 
size_t dif_otbn_get_imem_size_bytes (const dif_otbn_t *otbn)
 Get the size of OTBN's instruction memory in bytes. More...
 

Detailed Description

OTBN Device Interface Functions

Definition in file dif_otbn.h.


Data Structure Documentation

◆ dif_otbn_config

struct dif_otbn_config

Configuration for initializing an OTBN device.

Definition at line 25 of file dif_otbn.h.

Data Fields
mmio_region_t base_addr Base address of the OTBN device in the system.

◆ dif_otbn

struct dif_otbn

Internal state of a OTBN device.

Instances of this struct must be initialized by dif_otbn_init() before being passed to other functions.

Definition at line 36 of file dif_otbn.h.

Data Fields
mmio_region_t base_addr Base address of the OTBN device in the system.

Typedef Documentation

◆ dif_otbn_enable_t

Generic enable/disable enumeration.

Enumeration used to enable/disable bits, flags, ...

◆ dif_otbn_err_bits_t

OTBN Errors.

OTBN uses a bitfield to indicate which errors have been seen. Multiple errors can be seen at the same time. This enum gives the individual bits that may be set for different errors.

◆ dif_otbn_interrupt_t

OTBN interrupt configuration.

Enumeration used to enable, disable, test and query the OTBN interrupts. Please see the comportability specification for more information: https://docs.opentitan.org/doc/rm/comportability_specification/

◆ dif_otbn_t

typedef struct dif_otbn dif_otbn_t

Internal state of a OTBN device.

Instances of this struct must be initialized by dif_otbn_init() before being passed to other functions.

Enumeration Type Documentation

◆ dif_otbn_enable

Generic enable/disable enumeration.

Enumeration used to enable/disable bits, flags, ...

Enumerator
kDifOtbnEnable 

Enable functionality.

kDifOtbnDisable 

Disable functionality.

Definition at line 143 of file dif_otbn.h.

◆ dif_otbn_err_bits

OTBN Errors.

OTBN uses a bitfield to indicate which errors have been seen. Multiple errors can be seen at the same time. This enum gives the individual bits that may be set for different errors.

Enumerator
kDifOtbnErrBitsBadDataAddr 

A BAD_DATA_ADDR error was observed.

kDifOtbnErrBitsBadInsnAddr 

A BAD_INSN_ADDR error was observed.

kDifOtbnErrBitsCallStack 

A CALL_STACK error was observed.

kDifOtbnErrBitsIllegalInsn 

An ILLEGAL_INSN error was observed.

kDifOtbnErrBitsLoop 

A LOOP error was observed.

kDifOtbnErrBitsImemIntgViolation 

A IMEM_INTG_VIOLATION error was observed.

kDifOtbnErrBitsDmemIntgViolation 

A DMEM_INTG_VIOLATION error was observed.

kDifOtbnErrBitsRegIntgViolation 

A REG_INTG_VIOLATION error was observed.

kDifOtbnErrBitsBusIntgViolation 

A BUS_INTG_VIOLATION error was observed.

kDifOtbnErrBitsIllegalBusAccess 

An ILLEGAL_BUS_ACCESS error was observed.

kDifOtbnErrBitsLifecycleEscalation 

A LIFECYCLE_ESCALATION error was observed.

Definition at line 95 of file dif_otbn.h.

◆ dif_otbn_interrupt

OTBN interrupt configuration.

Enumeration used to enable, disable, test and query the OTBN interrupts. Please see the comportability specification for more information: https://docs.opentitan.org/doc/rm/comportability_specification/

Enumerator
kDifOtbnInterruptDone 

OTBN is done, it has run the application to completion.

Associated with the otbn.INTR_STATE.done hardware interrupt.

Definition at line 128 of file dif_otbn.h.

◆ dif_otbn_result

Generic return codes for the functions in the OTBN DIF library.

Enumerator
kDifOtbnOk 

The function succeeded.

kDifOtbnError 

The function failed a non-specific assertion.

This error is not recoverable.

kDifOtbnBadArg 

There is a problem with the argument(s) to the function.

This return code is only returned before the function has any side effects.

This error is recoverable and the operation can be retried after correcting the problem with the argument(s).

Definition at line 44 of file dif_otbn.h.

Function Documentation

◆ dif_otbn_dmem_read()

dif_otbn_result_t dif_otbn_dmem_read ( const dif_otbn_t otbn,
uint32_t  offset_bytes,
void *  dest,
size_t  len_bytes 
)

Read from OTBN's data memory (DMEM)

Only 32b-aligned 32b word accesses are allowed.

Parameters
otbnOTBN instance
offset_bytesthe byte offset in DMEM the first word is read from
[out]destthe main memory location to copy the data to (preallocated)
len_bytesnumber of bytes to copy.
Returns
kDifOtbnBadArg if otbn is NULL or len_bytes or size are invalid, kDifOtbnOk otherwise.

Definition at line 322 of file dif_otbn.c.

◆ dif_otbn_dmem_write()

dif_otbn_result_t dif_otbn_dmem_write ( const dif_otbn_t otbn,
uint32_t  offset_bytes,
const void *  src,
size_t  len_bytes 
)

Write to OTBN's data memory (DMEM)

Only 32b-aligned 32b word accesses are allowed.

Parameters
otbnOTBN instance
offset_bytesthe byte offset in DMEM the first word is written to
srcthe main memory location to start reading from.
len_bytesnumber of bytes to copy.
Returns
kDifOtbnBadArg if otbn is NULL or len_bytes or size are invalid, kDifOtbnOk otherwise.

Definition at line 308 of file dif_otbn.c.

◆ dif_otbn_get_dmem_size_bytes()

size_t dif_otbn_get_dmem_size_bytes ( const dif_otbn_t otbn)

Get the size of OTBN's data memory in bytes.

Parameters
otbnOTBN instance
Returns
data memory size in bytes

Definition at line 336 of file dif_otbn.c.

◆ dif_otbn_get_err_bits()

dif_otbn_result_t dif_otbn_get_err_bits ( const dif_otbn_t otbn,
dif_otbn_err_bits_t err_bits 
)

Get the error bits set by the device if the operation failed.

Parameters
otbnOTBN instance
[out]err_bitsThe error bits returned by the hardware.
Returns
kDifOtbnBadArg if otbn or err_code is NULL, kDifOtbnOk otherwise.

Definition at line 257 of file dif_otbn.c.

◆ dif_otbn_get_imem_size_bytes()

size_t dif_otbn_get_imem_size_bytes ( const dif_otbn_t otbn)

Get the size of OTBN's instruction memory in bytes.

Parameters
otbnOTBN instance
Returns
instruction memory size in bytes

Definition at line 340 of file dif_otbn.c.

◆ dif_otbn_get_insn_cnt()

dif_otbn_result_t dif_otbn_get_insn_cnt ( const dif_otbn_t otbn,
uint32_t *  insn_cnt 
)

Gets the number of executed OTBN instructions.

Gets the number of instructions executed so far in the current OTBN run if there is one. Otherwise, gets the number executed in total in the previous OTBN run.

Parameters
otbnOTBN instance
[out]insn_cntThe number of instructions executed by OTBN.
Returns
kDifOtbnBadArg if otbn or insn_cnt is NULL, kDifOtbnOk otherwise.

Definition at line 270 of file dif_otbn.c.

◆ dif_otbn_get_status()

dif_otbn_result_t dif_otbn_get_status ( const dif_otbn_t otbn,
dif_otbn_status_t status 
)

Gets the current status of OTBN.

Parameters
otbnOTBN instance
[out]statusOTBN status
Returns
kDifOtbnBadArg if otbn or status is NULL, kDifOtbnOk otherwise.

Definition at line 246 of file dif_otbn.c.

◆ dif_otbn_imem_read()

dif_otbn_result_t dif_otbn_imem_read ( const dif_otbn_t otbn,
uint32_t  offset_bytes,
void *  dest,
size_t  len_bytes 
)

Read from OTBN's instruction memory (IMEM)

Only 32b-aligned 32b word accesses are allowed.

Parameters
otbnOTBN instance
offset_bytesthe byte offset in IMEM the first word is read from
[out]destthe main memory location to copy the data to (preallocated)
len_bytesnumber of bytes to copy.
Returns
kDifOtbnBadArg if otbn is NULL or len_bytes or size are invalid, kDifOtbnOk otherwise.

Definition at line 294 of file dif_otbn.c.

◆ dif_otbn_imem_write()

dif_otbn_result_t dif_otbn_imem_write ( const dif_otbn_t otbn,
uint32_t  offset_bytes,
const void *  src,
size_t  len_bytes 
)

Write an OTBN application into its instruction memory (IMEM)

Only 32b-aligned 32b word accesses are allowed.

Parameters
otbnOTBN instance
offset_bytesthe byte offset in IMEM the first word is written to
srcthe main memory location to start reading from.
len_bytesnumber of bytes to copy.
Returns
kDifOtbnBadArg if otbn is NULL or len_bytes or size are invalid, kDifOtbnOk otherwise.

Definition at line 280 of file dif_otbn.c.

◆ dif_otbn_init()

dif_otbn_result_t dif_otbn_init ( const dif_otbn_config_t config,
dif_otbn_t otbn 
)

Initialize a OTBN device using config and return its internal state.

A particular OTBN device must first be initialized by this function before calling other functions of this library.

Parameters
configConfiguration for initializing an OTBN device.
[out]otbnOTBN instance that will store the internal state of the initialized OTBN device.
Returns
kDifOtbnBadArg if otbn is NULL, kDifOtbnOk otherwise.

Definition at line 86 of file dif_otbn.c.

◆ dif_otbn_irq_control()

dif_otbn_result_t dif_otbn_irq_control ( const dif_otbn_t otbn,
dif_otbn_interrupt_t  irq_type,
dif_otbn_enable_t  enable 
)

OTBN interrupt control.

Enable/disable an OTBN interrupt specified in irq_type.

Parameters
otbnOTBN instance
irq_typeOTBN interrupt type.
enableenable or disable the interrupt.
Returns
kDifOtbnBadArg if otbn is NULL, kDifOtbnOk otherwise.

Definition at line 179 of file dif_otbn.c.

◆ dif_otbn_irq_force()

dif_otbn_result_t dif_otbn_irq_force ( const dif_otbn_t otbn,
dif_otbn_interrupt_t  irq_type 
)

OTBN interrupt force.

Force interrupt specified in irq_type.

Parameters
otbnOTBN instance
irq_typeOTBN interrupt type to be forced.
Returns
dif_otbn_result_t.

Definition at line 202 of file dif_otbn.c.

◆ dif_otbn_irq_state_clear()

dif_otbn_result_t dif_otbn_irq_state_clear ( const dif_otbn_t otbn,
dif_otbn_interrupt_t  irq_type 
)

OTBN clear requested IRQ state.

Clear the state of the requested IRQ in irq_type. Primary use of this function is to de-assert the interrupt after it has been serviced.

Parameters
otbnOTBN state data.
irq_typeIRQ to be de-asserted.
Returns
kDifOtbnBadArg if otbn is NULL, kDifOtbnOk otherwise.

Definition at line 131 of file dif_otbn.c.

◆ dif_otbn_irq_state_get()

dif_otbn_result_t dif_otbn_irq_state_get ( const dif_otbn_t otbn,
dif_otbn_interrupt_t  irq_type,
dif_otbn_enable_t state 
)

OTBN get requested IRQ state.

Get the state of the requested IRQ in irq_type.

Parameters
otbnOTBN state data.
irq_typeIRQ to get the state of.
[out]stateIRQ state.
Returns
kDifOtbnBadArg if otbn is NULL, kDifOtbnOk otherwise.

Definition at line 111 of file dif_otbn.c.

◆ dif_otbn_irqs_disable()

dif_otbn_result_t dif_otbn_irqs_disable ( const dif_otbn_t otbn,
uint32_t *  state 
)

OTBN disable interrupts.

Disable generation of all OTBN interrupts, and pass previous interrupt state in state back to the caller. Parameter state is ignored if NULL.

Parameters
otbnOTBN state data.
[out]stateIRQ state for use with dif_otbn_irqs_restore.
Returns
kDifOtbnBadArg if otbn is NULL, kDifOtbnOk otherwise.

Definition at line 150 of file dif_otbn.c.

◆ dif_otbn_irqs_restore()

dif_otbn_result_t dif_otbn_irqs_restore ( const dif_otbn_t otbn,
uint32_t  state 
)

OTBN restore IRQ state.

Restore previous OTBN IRQ state. This function is used to restore the OTBN interrupt state prior to dif_otbn_irqs_disable function call.

Parameters
otbnOTBN instance
stateIRQ state to restore.
Returns
kDifOtbnBadArg if otbn is NULL, kDifOtbnOk otherwise.

Definition at line 167 of file dif_otbn.c.

◆ dif_otbn_reset()

dif_otbn_result_t dif_otbn_reset ( const dif_otbn_t otbn)

Reset OTBN device.

Resets the given OTBN device by setting its configuration registers to reset values. Disables interrupts, output, and input filter.

Parameters
otbnOTBN instance
Returns
kDifOtbnBadArg if otbn is NULL, kDifOtbnOk otherwise.

Definition at line 98 of file dif_otbn.c.

◆ dif_otbn_set_start_addr()

dif_otbn_result_t dif_otbn_set_start_addr ( const dif_otbn_t otbn,
unsigned int  start_addr 
)

Set the start address of the execution.

Parameters
otbnOTBN instance.
start_addrThe IMEM byte address to start the execution at.
Returns
kDifOtbnBadArg if otbn is NULL or start_addr is invalid, kDifOtbnOk otherwise.

Definition at line 223 of file dif_otbn.c.

◆ dif_otbn_write_cmd()

dif_otbn_result_t dif_otbn_write_cmd ( const dif_otbn_t otbn,
dif_otbn_cmd_t  cmd 
)

Start an operation by issuing a command.

Parameters
otbnOTBN instance.
cmdThe command.
Returns
kDifOtbnBadArg if otbn is NULL, kDifOtbnOk otherwise.

Definition at line 235 of file dif_otbn.c.