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_
sw
device
lib
dif
dif_otbn.h
Return to
OpenTitan Documentation