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>
16 
17 #ifdef __cplusplus
18 extern "C" {
19 #endif // __cplusplus
20 
21 /**
22  * Configuration for initializing an OTBN device.
23  */
24 typedef struct dif_otbn_config {
25  /** Base address of the OTBN device in the system. */
28 
29 /**
30  * Internal state of a OTBN device.
31  *
32  * Instances of this struct must be initialized by `dif_otbn_init()` before
33  * being passed to other functions.
34  */
35 typedef struct dif_otbn {
36  /** Base address of the OTBN device in the system. */
38 } dif_otbn_t;
39 
40 /**
41  * Generic return codes for the functions in the OTBN DIF library.
42  */
43 typedef enum dif_otbn_result {
44  /**
45  * The function succeeded.
46  */
48 
49  /**
50  * The function failed a non-specific assertion.
51  *
52  * This error is not recoverable.
53  */
55 
56  /**
57  * There is a problem with the argument(s) to the function.
58  *
59  * This return code is only returned before the function has any side effects.
60  *
61  * This error is recoverable and the operation can be retried after correcting
62  * the problem with the argument(s).
63  */
66 
67 /**
68  * OTBN Errors
69  *
70  * OTBN uses a bitfield to indicate which errors have been seen. Multiple errors
71  * can be seen at the same time. This enum gives the individual bits that may be
72  * set for different errors.
73  */
74 typedef enum dif_otbn_err_bits {
75  kDifOtbnErrBitsNoError = 0,
76  /** Load or store to invalid address. */
78  /** Instruction fetch from invalid address. */
80  /** Call stack underflow or overflow. */
82  /** Illegal instruction execution attempted */
84  /** LOOP[I] related error */
85  kDifOtbnErrBitsLoop = (1 << 4),
86  /** Error seen in Imem read */
88  /** Error seen in Dmem read */
90  /** Error seen in RF read */
93 
94 /**
95  * OTBN interrupt configuration.
96  *
97  * Enumeration used to enable, disable, test and query the OTBN interrupts.
98  * Please see the comportability specification for more information:
99  * https://docs.opentitan.org/doc/rm/comportability_specification/
100  */
101 typedef enum dif_otbn_interrupt {
102  /**
103  * OTBN is done, it has run the application to completion.
104  *
105  * Associated with the `otbn.INTR_STATE.done` hardware interrupt.
106  */
108 
110 
111 /**
112  * Generic enable/disable enumeration.
113  *
114  * Enumeration used to enable/disable bits, flags, ...
115  */
116 typedef enum dif_otbn_enable {
117  /** Enable functionality. */
119  /** Disable functionality. */
122 
123 /**
124  * Initialize a OTBN device using `config` and return its internal state.
125  *
126  * A particular OTBN device must first be initialized by this function
127  * before calling other functions of this library.
128  *
129  * @param config Configuration for initializing an OTBN device.
130  * @param[out] otbn OTBN instance that will store the internal state of the
131  * initialized OTBN device.
132  * @return `kDifOtbnBadArg` if `otbn` is `NULL`, `kDifOtbnOk` otherwise.
133  */
134 dif_otbn_result_t dif_otbn_init(const dif_otbn_config_t *config,
135  dif_otbn_t *otbn);
136 
137 /**
138  * Reset OTBN device.
139  *
140  * Resets the given OTBN device by setting its configuration registers to
141  * reset values. Disables interrupts, output, and input filter.
142  *
143  * @param otbn OTBN instance
144  * @return `kDifOtbnBadArg` if `otbn` is `NULL`, `kDifOtbnOk` otherwise.
145  */
146 dif_otbn_result_t dif_otbn_reset(const dif_otbn_t *otbn);
147 
148 /**
149  * OTBN get requested IRQ state.
150  *
151  * Get the state of the requested IRQ in `irq_type`.
152  *
153  * @param otbn OTBN state data.
154  * @param irq_type IRQ to get the state of.
155  * @param[out] state IRQ state.
156  * @return `kDifOtbnBadArg` if `otbn` is `NULL`, `kDifOtbnOk` otherwise.
157  */
158 dif_otbn_result_t dif_otbn_irq_state_get(const dif_otbn_t *otbn,
159  dif_otbn_interrupt_t irq_type,
160  dif_otbn_enable_t *state);
161 
162 /**
163  * OTBN clear requested IRQ state.
164  *
165  * Clear the state of the requested IRQ in `irq_type`. Primary use of this
166  * function is to de-assert the interrupt after it has been serviced.
167  *
168  * @param otbn OTBN state data.
169  * @param irq_type IRQ to be de-asserted.
170  * @return `kDifOtbnBadArg` if `otbn` is `NULL`, `kDifOtbnOk` otherwise.
171  */
172 dif_otbn_result_t dif_otbn_irq_state_clear(const dif_otbn_t *otbn,
173  dif_otbn_interrupt_t irq_type);
174 
175 /**
176  * OTBN disable interrupts.
177  *
178  * Disable generation of all OTBN interrupts, and pass previous interrupt state
179  * in `state` back to the caller. Parameter `state` is ignored if NULL.
180  *
181  * @param otbn OTBN state data.
182  * @param[out] state IRQ state for use with `dif_otbn_irqs_restore`.
183  * @return `kDifOtbnBadArg` if `otbn` is `NULL`, `kDifOtbnOk` otherwise.
184  */
185 dif_otbn_result_t dif_otbn_irqs_disable(const dif_otbn_t *otbn,
186  uint32_t *state);
187 
188 /**
189  * OTBN restore IRQ state.
190  *
191  * Restore previous OTBN IRQ state. This function is used to restore the
192  * OTBN interrupt state prior to `dif_otbn_irqs_disable` function call.
193  *
194  * @param otbn OTBN instance
195  * @param state IRQ state to restore.
196  * @return `kDifOtbnBadArg` if `otbn` is `NULL`, `kDifOtbnOk` otherwise.
197  */
198 dif_otbn_result_t dif_otbn_irqs_restore(const dif_otbn_t *otbn, uint32_t state);
199 
200 /**
201  * OTBN interrupt control.
202  *
203  * Enable/disable an OTBN interrupt specified in `irq_type`.
204  *
205  * @param otbn OTBN instance
206  * @param irq_type OTBN interrupt type.
207  * @param enable enable or disable the interrupt.
208  * @return `kDifOtbnBadArg` if `otbn` is `NULL`, `kDifOtbnOk` otherwise.
209  */
210 dif_otbn_result_t dif_otbn_irq_control(const dif_otbn_t *otbn,
211  dif_otbn_interrupt_t irq_type,
212  dif_otbn_enable_t enable);
213 
214 /**
215  * OTBN interrupt force.
216  *
217  * Force interrupt specified in `irq_type`.
218  *
219  * @param otbn OTBN instance
220  * @param irq_type OTBN interrupt type to be forced.
221  * @return `dif_otbn_result_t`.
222  */
223 dif_otbn_result_t dif_otbn_irq_force(const dif_otbn_t *otbn,
224  dif_otbn_interrupt_t irq_type);
225 
226 /**
227  * Start the execution of the application loaded into OTBN at the start address.
228  *
229  * @param otbn OTBN instance
230  * @param start_addr The IMEM byte address to start the execution at.
231  * @return `kDifOtbnBadArg` if `otbn` is `NULL` or `start_addr` is invalid,
232  * `kDifOtbnOk` otherwise.
233  */
234 dif_otbn_result_t dif_otbn_start(const dif_otbn_t *otbn,
235  unsigned int start_addr);
236 
237 /**
238  * Is OTBN busy executing an application?
239  *
240  * @param otbn OTBN instance
241  * @param[out] busy OTBN is busy
242  * @return `kDifOtbnBadArg` if `otbn` or `busy` is `NULL`,
243  * `kDifOtbnOk` otherwise.
244  */
245 dif_otbn_result_t dif_otbn_is_busy(const dif_otbn_t *otbn, bool *busy);
246 
247 /**
248  * Get the error bits set by the device if the operation failed.
249  *
250  * @param otbn OTBN instance
251  * @param[out] err_bits The error bits returned by the hardware.
252  * @return `kDifOtbnBadArg` if `otbn` or `err_code` is `NULL`,
253  * `kDifOtbnOk` otherwise.
254  */
255 dif_otbn_result_t dif_otbn_get_err_bits(const dif_otbn_t *otbn,
256  dif_otbn_err_bits_t *err_bits);
257 
258 /**
259  * Write an OTBN application into its instruction memory (IMEM)
260  *
261  * Only 32b-aligned 32b word accesses are allowed.
262  *
263  * @param otbn OTBN instance
264  * @param offset_bytes the byte offset in IMEM the first word is written to
265  * @param src the main memory location to start reading from.
266  * @param len_bytes number of bytes to copy.
267  * @return `kDifOtbnBadArg` if `otbn` is `NULL` or len_bytes or size are
268  * invalid, `kDifOtbnOk` otherwise.
269  */
270 dif_otbn_result_t dif_otbn_imem_write(const dif_otbn_t *otbn,
271  uint32_t offset_bytes, const void *src,
272  size_t len_bytes);
273 
274 /**
275  * Read from OTBN's instruction memory (IMEM)
276  *
277  * Only 32b-aligned 32b word accesses are allowed.
278  *
279  * @param otbn OTBN instance
280  * @param offset_bytes the byte offset in IMEM the first word is read from
281  * @param[out] dest the main memory location to copy the data to (preallocated)
282  * @param len_bytes number of bytes to copy.
283  * @return `kDifOtbnBadArg` if `otbn` is `NULL` or len_bytes or size are
284  * invalid, `kDifOtbnOk` otherwise.
285  */
286 dif_otbn_result_t dif_otbn_imem_read(const dif_otbn_t *otbn,
287  uint32_t offset_bytes, void *dest,
288  size_t len_bytes);
289 
290 /**
291  * Write to OTBN's data memory (DMEM)
292  *
293  * Only 32b-aligned 32b word accesses are allowed.
294  *
295  * @param otbn OTBN instance
296  * @param offset_bytes the byte offset in DMEM the first word is written to
297  * @param src the main memory location to start reading from.
298  * @param len_bytes number of bytes to copy.
299  * @return `kDifOtbnBadArg` if `otbn` is `NULL` or len_bytes or size are
300  * invalid, `kDifOtbnOk` otherwise.
301  */
302 dif_otbn_result_t dif_otbn_dmem_write(const dif_otbn_t *otbn,
303  uint32_t offset_bytes, const void *src,
304  size_t len_bytes);
305 
306 /**
307  * Read from OTBN's data memory (DMEM)
308  *
309  * Only 32b-aligned 32b word accesses are allowed.
310  *
311  * @param otbn OTBN instance
312  * @param offset_bytes the byte offset in DMEM the first word is read from
313  * @param[out] dest the main memory location to copy the data to (preallocated)
314  * @param len_bytes number of bytes to copy.
315  * @return `kDifOtbnBadArg` if `otbn` is `NULL` or len_bytes or size are
316  * invalid, `kDifOtbnOk` otherwise.
317  */
318 dif_otbn_result_t dif_otbn_dmem_read(const dif_otbn_t *otbn,
319  uint32_t offset_bytes, void *dest,
320  size_t len_bytes);
321 
322 /**
323  * Get the size of OTBN's data memory in bytes.
324  *
325  * @param otbn OTBN instance
326  * @return data memory size in bytes
327  */
329 
330 /**
331  * Get the size of OTBN's instruction memory in bytes.
332  *
333  * @param otbn OTBN instance
334  * @return instruction memory size in bytes
335  */
337 
338 #ifdef __cplusplus
339 } // extern "C"
340 #endif // __cplusplus
341 
342 #endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_OTBN_H_