Software APIs
dif_otbn.h
Go to the documentation of this file.
1 // Copyright lowRISC contributors.
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 
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,
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  kDifOtbnStatusLocked = 0xFF,
44 
45 /**
46  * OTBN Errors
47  *
48  * OTBN uses a bitfield to indicate which errors have been seen. Multiple errors
49  * can be seen at the same time. This enum gives the individual bits that may be
50  * set for different errors.
51  */
52 typedef enum dif_otbn_err_bits {
53  kDifOtbnErrBitsNoError = 0,
54  /** A BAD_DATA_ADDR error was observed. */
56  /** A BAD_INSN_ADDR error was observed. */
58  /** A CALL_STACK error was observed. */
60  /** An ILLEGAL_INSN error was observed. */
62  /** A LOOP error was observed. */
63  kDifOtbnErrBitsLoop = (1 << 4),
64  /** A IMEM_INTG_VIOLATION error was observed. */
66  /** A DMEM_INTG_VIOLATION error was observed. */
68  /** A REG_INTG_VIOLATION error was observed. */
70  /** A BUS_INTG_VIOLATION error was observed. */
72  /** An ILLEGAL_BUS_ACCESS error was observed. */
74  /** A LIFECYCLE_ESCALATION error was observed. */
76  /** A FATAL_SOFTWARE error was observed. */
79 
80 /**
81  * Reset OTBN device.
82  *
83  * Resets the given OTBN device by setting its configuration registers to
84  * reset values. Disables interrupts, output, and input filter.
85  *
86  * @param otbn OTBN instance
87  * @return The result of the operation.
88  */
90 
91 /**
92  * Start an operation by issuing a command.
93  *
94  * @param otbn OTBN instance.
95  * @param cmd The command.
96  * @return The result of the operation.
97  */
99 
100 /**
101  * Gets the current status of OTBN.
102  *
103  * @param otbn OTBN instance
104  * @param[out] status OTBN status
105  * @return The result of the operation.
106  */
108  dif_otbn_status_t *status);
109 
110 /**
111  * Get the error bits set by the device if the operation failed.
112  *
113  * @param otbn OTBN instance
114  * @param[out] err_bits The error bits returned by the hardware.
115  * @return The result of the operation.
116  */
118  dif_otbn_err_bits_t *err_bits);
119 
120 /**
121  * Gets the number of executed OTBN instructions.
122  *
123  * Gets the number of instructions executed so far in the current OTBN run if
124  * there is one. Otherwise, gets the number executed in total in the previous
125  * OTBN run.
126  *
127  * @param otbn OTBN instance
128  * @param[out] insn_cnt The number of instructions executed by OTBN.
129  * @return The result of the operation.
130  */
131 dif_result_t dif_otbn_get_insn_cnt(const dif_otbn_t *otbn, uint32_t *insn_cnt);
132 
133 /**
134  * Write an OTBN application into its instruction memory (IMEM)
135  *
136  * Only 32b-aligned 32b word accesses are allowed.
137  *
138  * @param otbn OTBN instance
139  * @param offset_bytes the byte offset in IMEM the first word is written to
140  * @param src the main memory location to start reading from.
141  * @param len_bytes number of bytes to copy.
142  * @return The result of the operation.
143  */
144 dif_result_t dif_otbn_imem_write(const dif_otbn_t *otbn, uint32_t offset_bytes,
145  const void *src, size_t len_bytes);
146 
147 /**
148  * Read from OTBN's instruction memory (IMEM)
149  *
150  * Only 32b-aligned 32b word accesses are allowed.
151  *
152  * @param otbn OTBN instance
153  * @param offset_bytes the byte offset in IMEM the first word is read from
154  * @param[out] dest the main memory location to copy the data to (preallocated)
155  * @param len_bytes number of bytes to copy.
156  * @return The result of the operation.
157  */
158 dif_result_t dif_otbn_imem_read(const dif_otbn_t *otbn, uint32_t offset_bytes,
159  void *dest, size_t len_bytes);
160 
161 /**
162  * Write to OTBN's data memory (DMEM)
163  *
164  * Only 32b-aligned 32b word accesses are allowed.
165  *
166  * @param otbn OTBN instance
167  * @param offset_bytes the byte offset in DMEM the first word is written to
168  * @param src the main memory location to start reading from.
169  * @param len_bytes number of bytes to copy.
170  * @return The result of the operation.
171  */
172 dif_result_t dif_otbn_dmem_write(const dif_otbn_t *otbn, uint32_t offset_bytes,
173  const void *src, size_t len_bytes);
174 
175 /**
176  * Read from OTBN's data memory (DMEM)
177  *
178  * Only 32b-aligned 32b word accesses are allowed.
179  *
180  * @param otbn OTBN instance
181  * @param offset_bytes the byte offset in DMEM the first word is read from
182  * @param[out] dest the main memory location to copy the data to (preallocated)
183  * @param len_bytes number of bytes to copy.
184  * @return The result of the operation.
185  */
186 dif_result_t dif_otbn_dmem_read(const dif_otbn_t *otbn, uint32_t offset_bytes,
187  void *dest, size_t len_bytes);
188 
189 /**
190  * Sets the software errors are fatal bit in the control register.
191  *
192  * When set any software error becomes a fatal error. The bit can only be
193  * changed when the OTBN status is IDLE.
194  *
195  * @param otbn OTBN instance
196  * @param enable Enable or disable whether software errors are fatal.
197  * @return The result of the operation, `kDifUnavailable` is returned when the
198  * requested change cannot be made.
199  */
201  bool enable);
202 
203 /**
204  * Get the size of OTBN's data memory in bytes.
205  *
206  * @param otbn OTBN instance
207  * @return data memory size in bytes
208  */
210 
211 /**
212  * Get the size of OTBN's instruction memory in bytes.
213  *
214  * @param otbn OTBN instance
215  * @return instruction memory size in bytes
216  */
218 
219 #ifdef __cplusplus
220 } // extern "C"
221 #endif // __cplusplus
222 
223 #endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_OTBN_H_