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 
16 #include "sw/device/lib/base/mmio.h"
17 #include "sw/device/lib/dif/dif_base.h"
18 
19 #include "sw/device/lib/dif/autogen/dif_otbn_autogen.h"
20 
21 #ifdef __cplusplus
22 extern "C" {
23 #endif // __cplusplus
24 
25 /**
26  * OTBN commands.
27  */
28 typedef enum dif_otbn_cmd {
29  kDifOtbnCmdExecute = 0xd8,
30  kDifOtbnCmdSecWipeDmem = 0xc3,
31  kDifOtbnCmdSecWipeImem = 0x1e,
32 } dif_otbn_cmd_t;
33 
34 /**
35  * OTBN status.
36  */
37 typedef enum dif_otbn_status {
38  kDifOtbnStatusIdle = 0x00,
39  kDifOtbnStatusBusyExecute = 0x01,
40  kDifOtbnStatusBusySecWipeDmem = 0x02,
41  kDifOtbnStatusBusySecWipeImem = 0x03,
42  kDifOtbnStatusBusySecWipeInt = 0x04,
43  kDifOtbnStatusLocked = 0xFF,
44 } dif_otbn_status_t;
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  */
53 typedef enum dif_otbn_err_bits {
54  kDifOtbnErrBitsNoError = 0,
55  /** A BAD_DATA_ADDR error was observed. */
56  kDifOtbnErrBitsBadDataAddr = (1 << 0),
57  /** A BAD_INSN_ADDR error was observed. */
58  kDifOtbnErrBitsBadInsnAddr = (1 << 1),
59  /** A CALL_STACK error was observed. */
60  kDifOtbnErrBitsCallStack = (1 << 2),
61  /** An ILLEGAL_INSN error was observed. */
62  kDifOtbnErrBitsIllegalInsn = (1 << 3),
63  /** A LOOP error was observed. */
64  kDifOtbnErrBitsLoop = (1 << 4),
65  /** A RND_FIPS_CHECK_FAIL error was observed. */
66  kDifOtbnErrBitsRndFipsChkFail = (1 << 7),
67  /** A IMEM_INTG_VIOLATION error was observed. */
68  kDifOtbnErrBitsImemIntgViolation = (1 << 16),
69  /** A DMEM_INTG_VIOLATION error was observed. */
70  kDifOtbnErrBitsDmemIntgViolation = (1 << 17),
71  /** A REG_INTG_VIOLATION error was observed. */
72  kDifOtbnErrBitsRegIntgViolation = (1 << 18),
73  /** A BUS_INTG_VIOLATION error was observed. */
74  kDifOtbnErrBitsBusIntgViolation = (1 << 19),
75  /** A BAD_INTERNAL_STATE error was observed. */
76  kDifOtbnErrBitsBadInternalState = (1 << 20),
77  /** An ILLEGAL_BUS_ACCESS error was observed. */
78  kDifOtbnErrBitsIllegalBusAccess = (1 << 21),
79  /** A LIFECYCLE_ESCALATION error was observed. */
80  kDifOtbnErrBitsLifecycleEscalation = (1 << 22),
81  /** A FATAL_SOFTWARE error was observed. */
82  kDifOtbnErrBitsFatalSoftware = (1 << 23),
83 } dif_otbn_err_bits_t;
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  */
94 OT_WARN_UNUSED_RESULT
95 dif_result_t dif_otbn_reset(const dif_otbn_t *otbn);
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  */
104 OT_WARN_UNUSED_RESULT
105 dif_result_t dif_otbn_write_cmd(const dif_otbn_t *otbn, dif_otbn_cmd_t cmd);
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  */
114 OT_WARN_UNUSED_RESULT
115 dif_result_t dif_otbn_get_status(const dif_otbn_t *otbn,
116  dif_otbn_status_t *status);
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  */
125 OT_WARN_UNUSED_RESULT
126 dif_result_t dif_otbn_get_err_bits(const dif_otbn_t *otbn,
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  */
140 OT_WARN_UNUSED_RESULT
141 dif_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  */
152 OT_WARN_UNUSED_RESULT
153 dif_result_t dif_otbn_get_load_checksum(const dif_otbn_t *otbn,
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  */
164 OT_WARN_UNUSED_RESULT
165 dif_result_t dif_otbn_clear_load_checksum(const dif_otbn_t *otbn);
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  */
178 OT_WARN_UNUSED_RESULT
179 dif_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  */
193 OT_WARN_UNUSED_RESULT
194 dif_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  */
208 OT_WARN_UNUSED_RESULT
209 dif_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  */
223 OT_WARN_UNUSED_RESULT
224 dif_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  */
238 OT_WARN_UNUSED_RESULT
239 dif_result_t dif_otbn_set_ctrl_software_errs_fatal(const dif_otbn_t *otbn,
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  */
248 size_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  */
256 size_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_
Return to OpenTitan Documentation