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

(f166105)

OTBN Device Interface Functions More...

#include <stddef.h>
#include <stdint.h>
#include "sw/device/lib/base/mmio.h"
#include "sw/device/lib/dif/dif_base.h"
#include "sw/device/lib/dif/autogen/dif_otbn_autogen.h"

Go to the source code of this file.

Typedefs

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

Enumerations

enum  dif_otbn_cmd {
  kDifOtbnCmdExecute = 0xd8,
  kDifOtbnCmdSecWipeDmem = 0xc3,
  kDifOtbnCmdSecWipeImem = 0x1e,
  kOtbnCmdExecute = 0xd8,
  kOtbnCmdSecWipeDmem = 0xc3,
  kOtbnCmdSecWipeImem = 0x1e
}
 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),
  kDifOtbnErrBitsBadInternalState = (1 << 20),
  kDifOtbnErrBitsIllegalBusAccess = (1 << 21),
  kDifOtbnErrBitsLifecycleEscalation = (1 << 22),
  kDifOtbnErrBitsFatalSoftware = (1 << 23)
}
 OTBN Errors. More...
 

Functions

dif_result_t dif_otbn_reset (const dif_otbn_t *otbn)
 Reset OTBN device. More...
 
dif_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_result_t dif_otbn_get_status (const dif_otbn_t *otbn, dif_otbn_status_t *status)
 Gets the current status of OTBN. More...
 
dif_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_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_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_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_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_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...
 
dif_result_t dif_otbn_set_ctrl_software_errs_fatal (const dif_otbn_t *otbn, bool enable)
 Sets the software errors are fatal bit in the control register. 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.

Typedef Documentation

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

Enumeration Type Documentation

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

kDifOtbnErrBitsBadInternalState 

A BAD_INTERNAL_STATE error was observed.

kDifOtbnErrBitsIllegalBusAccess 

An ILLEGAL_BUS_ACCESS error was observed.

kDifOtbnErrBitsLifecycleEscalation 

A LIFECYCLE_ESCALATION error was observed.

kDifOtbnErrBitsFatalSoftware 

A FATAL_SOFTWARE error was observed.

Definition at line 52 of file dif_otbn.h.

Function Documentation

◆ dif_otbn_dmem_read()

dif_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
The result of the operation.

Definition at line 165 of file dif_otbn.c.

◆ dif_otbn_dmem_write()

dif_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
The result of the operation.

Definition at line 152 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 201 of file dif_otbn.c.

◆ dif_otbn_get_err_bits()

dif_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
The result of the operation.

Definition at line 104 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 205 of file dif_otbn.c.

◆ dif_otbn_get_insn_cnt()

dif_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
The result of the operation.

Definition at line 117 of file dif_otbn.c.

◆ dif_otbn_get_status()

dif_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
The result of the operation.

Definition at line 93 of file dif_otbn.c.

◆ dif_otbn_imem_read()

dif_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
The result of the operation.

Definition at line 139 of file dif_otbn.c.

◆ dif_otbn_imem_write()

dif_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
The result of the operation.

Definition at line 126 of file dif_otbn.c.

◆ dif_otbn_reset()

dif_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
The result of the operation.

Definition at line 70 of file dif_otbn.c.

◆ dif_otbn_set_ctrl_software_errs_fatal()

dif_result_t dif_otbn_set_ctrl_software_errs_fatal ( const dif_otbn_t otbn,
bool  enable 
)

Sets the software errors are fatal bit in the control register.

When set any software error becomes a fatal error. The bit can only be changed when the OTBN status is IDLE.

Parameters
otbnOTBN instance
enableEnable or disable whether software errors are fatal.
Returns
The result of the operation, kDifUnavailable is returned when the requested change cannot be made.

Definition at line 178 of file dif_otbn.c.

◆ dif_otbn_write_cmd()

dif_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
The result of the operation.

Definition at line 83 of file dif_otbn.c.