Software APIs
dif_otbn.h
Go to the documentation of this file.
1// Copyright lowRISC contributors (OpenTitan project).
2// Licensed under the Apache License, Version 2.0, see LICENSE for details.
3// SPDX-License-Identifier: Apache-2.0
4
5#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_OTBN_H_
6#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_OTBN_H_
7
8/**
9 * @file
10 * @brief <a href="/hw/ip/otbn/doc/">OTBN</a> Device Interface Functions.
11 */
12
13#include <stddef.h>
14#include <stdint.h>
15
18
19#include "sw/device/lib/dif/autogen/dif_otbn_autogen.h"
20
21#ifdef __cplusplus
22extern "C" {
23#endif // __cplusplus
24
25/**
26 * OTBN commands.
27 */
28typedef enum dif_otbn_cmd {
29 kDifOtbnCmdExecute = 0xd8,
30 kDifOtbnCmdSecWipeDmem = 0xc3,
31 kDifOtbnCmdSecWipeImem = 0x1e,
33
34/**
35 * OTBN status.
36 */
37typedef enum dif_otbn_status {
38 kDifOtbnStatusIdle = 0x00,
39 kDifOtbnStatusBusyExecute = 0x01,
40 kDifOtbnStatusBusySecWipeDmem = 0x02,
41 kDifOtbnStatusBusySecWipeImem = 0x03,
42 kDifOtbnStatusBusySecWipeInt = 0x04,
43 kDifOtbnStatusLocked = 0xFF,
45
46/**
47 * OTBN Errors.
48 *
49 * OTBN uses a bitfield to indicate which errors have been seen. Multiple errors
50 * can be seen at the same time. This enum gives the individual bits that may be
51 * set for different errors.
52 */
53typedef enum dif_otbn_err_bits {
54 kDifOtbnErrBitsNoError = 0,
55 /** A BAD_DATA_ADDR error was observed. */
57 /** A BAD_INSN_ADDR error was observed. */
59 /** A CALL_STACK error was observed. */
61 /** An ILLEGAL_INSN error was observed. */
63 /** A LOOP error was observed. */
65 /** A RND_FIPS_CHECK_FAIL error was observed. */
67 /** A IMEM_INTG_VIOLATION error was observed. */
69 /** A DMEM_INTG_VIOLATION error was observed. */
71 /** A REG_INTG_VIOLATION error was observed. */
73 /** A BUS_INTG_VIOLATION error was observed. */
75 /** A BAD_INTERNAL_STATE error was observed. */
77 /** An ILLEGAL_BUS_ACCESS error was observed. */
79 /** A LIFECYCLE_ESCALATION error was observed. */
81 /** A FATAL_SOFTWARE error was observed. */
84
85/**
86 * Reset OTBN device.
87 *
88 * Resets the given OTBN device by setting its configuration registers to
89 * reset values. Disables interrupts, output, and input filter.
90 *
91 * @param otbn OTBN instance.
92 * @return The result of the operation.
93 */
96
97/**
98 * Start an operation by issuing a command.
99 *
100 * @param otbn OTBN instance.
101 * @param cmd The command.
102 * @return The result of the operation.
103 */
106
107/**
108 * Gets the current status of OTBN.
109 *
110 * @param otbn OTBN instance.
111 * @param[out] status OTBN status.
112 * @return The result of the operation.
113 */
117
118/**
119 * Get the error bits set by the device if the operation failed.
120 *
121 * @param otbn OTBN instance.
122 * @param[out] err_bits The error bits returned by the hardware.
123 * @return The result of the operation.
124 */
127 dif_otbn_err_bits_t *err_bits);
128
129/**
130 * Gets the number of executed OTBN instructions.
131 *
132 * Gets the number of instructions executed so far in the current OTBN run if
133 * there is one. Otherwise, gets the number executed in total in the previous
134 * OTBN run.
135 *
136 * @param otbn OTBN instance.
137 * @param[out] insn_cnt The number of instructions executed by OTBN.
138 * @return The result of the operation.
139 */
141dif_result_t dif_otbn_get_insn_cnt(const dif_otbn_t *otbn, uint32_t *insn_cnt);
142
143/**
144 * Gets the content of the load checksum register.
145 *
146 * Gets the 32-bit CRC checksum of data written to memory.
147 *
148 * @param otbn OTBN instance.
149 * @param[out] insn_cnt The number of instructions executed by OTBN.
150 * @return The result of the operation.
151 */
154 uint32_t *insn_cnt);
155
156/**
157 * Clears the load checksum register.
158 *
159 * Writes 0 to the load checksum register to clear it.
160 *
161 * @param otbn OTBN instance.
162 * @return The result of the operation.
163 */
166
167/**
168 * Write an OTBN application into its instruction memory (IMEM).
169 *
170 * Only 32b-aligned 32b word accesses are allowed.
171 *
172 * @param otbn OTBN instance.
173 * @param offset_bytes the byte offset in IMEM the first word is written to.
174 * @param src the main memory location to start reading from.
175 * @param len_bytes number of bytes to copy.
176 * @return The result of the operation.
177 */
179dif_result_t dif_otbn_imem_write(const dif_otbn_t *otbn, uint32_t offset_bytes,
180 const void *src, size_t len_bytes);
181
182/**
183 * Read from OTBN's instruction memory (IMEM).
184 *
185 * Only 32b-aligned 32b word accesses are allowed.
186 *
187 * @param otbn OTBN instance
188 * @param offset_bytes the byte offset in IMEM the first word is read from.
189 * @param[out] dest the main memory location to copy the data to (preallocated).
190 * @param len_bytes number of bytes to copy.
191 * @return The result of the operation.
192 */
194dif_result_t dif_otbn_imem_read(const dif_otbn_t *otbn, uint32_t offset_bytes,
195 void *dest, size_t len_bytes);
196
197/**
198 * Write to OTBN's data memory (DMEM).
199 *
200 * Only 32b-aligned 32b word accesses are allowed.
201 *
202 * @param otbn OTBN instance.
203 * @param offset_bytes the byte offset in DMEM the first word is written to.
204 * @param src the main memory location to start reading from.
205 * @param len_bytes number of bytes to copy.
206 * @return The result of the operation.
207 */
209dif_result_t dif_otbn_dmem_write(const dif_otbn_t *otbn, uint32_t offset_bytes,
210 const void *src, size_t len_bytes);
211
212/**
213 * Read from OTBN's data memory (DMEM).
214 *
215 * Only 32b-aligned 32b word accesses are allowed.
216 *
217 * @param otbn OTBN instance
218 * @param offset_bytes the byte offset in DMEM the first word is read from.
219 * @param[out] dest the main memory location to copy the data to (preallocated).
220 * @param len_bytes number of bytes to copy.
221 * @return The result of the operation.
222 */
224dif_result_t dif_otbn_dmem_read(const dif_otbn_t *otbn, uint32_t offset_bytes,
225 void *dest, size_t len_bytes);
226
227/**
228 * Sets the software errors are fatal bit in the control register.
229 *
230 * When set any software error becomes a fatal error. The bit can only be
231 * changed when the OTBN status is IDLE.
232 *
233 * @param otbn OTBN instance.
234 * @param enable Enable or disable whether software errors are fatal.
235 * @return The result of the operation, `kDifUnavailable` is returned when the
236 * requested change cannot be made.
237 */
240 bool enable);
241
242/**
243 * Get the size of OTBN's data memory in bytes.
244 *
245 * @param otbn OTBN instance.
246 * @return data memory size in bytes.
247 */
248size_t dif_otbn_get_dmem_size_bytes(const dif_otbn_t *otbn);
249
250/**
251 * Get the size of OTBN's instruction memory in bytes.
252 *
253 * @param otbn OTBN instance.
254 * @return instruction memory size in bytes.
255 */
256size_t dif_otbn_get_imem_size_bytes(const dif_otbn_t *otbn);
257
258#ifdef __cplusplus
259} // extern "C"
260#endif // __cplusplus
261
262#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_OTBN_H_