-
Notifications
You must be signed in to change notification settings - Fork 789
/
dif_sram_ctrl.h
276 lines (255 loc) · 9.91 KB
/
dif_sram_ctrl.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
// Copyright lowRISC contributors (OpenTitan project).
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
#ifndef OPENTITAN_SW_DEVICE_LIB_DIF_DIF_SRAM_CTRL_H_
#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_SRAM_CTRL_H_
/**
* @file
* @brief <a href="/hw/ip/sram_ctrl/doc/">SRAM Controller</a> Device Interface
* Functions
*/
#include <stdint.h>
#include "sw/device/lib/base/multibits.h"
#include "sw/device/lib/dif/autogen/dif_sram_ctrl_autogen.h"
#ifdef __cplusplus
extern "C" {
#endif // __cplusplus
/**
* SRAM Controller status information bitfield.
*/
typedef uint32_t dif_sram_ctrl_status_bitfield_t;
/**
* SRAM Controller status flags.
*
* Invariants are used to extract information encoded in
* `dif_sram_ctrl_status_bitfield_t`.
*
* More than one status flag can be set at the same time, and a caller may use
* these invariants to look-up individual or a group of flags.
*
* Note: these must match the autogenerated register definition bit offsets.
*/
typedef enum dif_sram_ctrl_status {
/**
* Bus integrity fault is detected. This error triggers a fatal_error alert.
* This condition is terminal.
*/
kDifSramCtrlStatusBusIntegErr = 0x1,
/**
* Initialization counter has reached an invalid state. This error triggers
* a fatal_error alert. This condition is terminal.
*/
kDifSramCtrlStatusInitErr = (0x1 << 1),
/**
* SRAM Controller has received an escalate request, the scrambling keys have
* been reset to the default values and all subsequent memory requests will
* be blocked. This condition is terminal.
*/
kDifSramCtrlStatusEscalated = (0x1 << 2),
/**
* New scrambling key has been successfully obtained from OTP. If the flag is
* not set, the SRAM contents are still scrambled, but a default all-zero key
* and nonce are used to do so.
*/
kDifSramCtrlStatusScrKeyValid = (0x1 << 3),
/**
* Scrambling key has been derived from a valid key seed in OTP. When
* `kDifSramCtrlStatusScrKeyValid` is set, but this flag is unset - the
* scrambling key is still ephemeral (i.e., it is derived using entropy from
* CSRNG), but a default all-zero value is used as the key seed. This could
* happen when the scrambling key seeds have not yet been provisioned to OTP.
*/
kDifSramCtrlStatusScrKeySeedValid = (0x1 << 4),
/**
* Hardware initialization triggered via `dif_sram_ctrl_scramble` or
* `dif_sram_ctrl_wipe` has completed.
*/
kDifSramCtrlStatusInitDone = (0x1 << 5),
} dif_sram_ctrl_status_t;
/**
* SRAM Controller lockable functionality.
*/
typedef enum dif_sram_ctrl_lock {
/**
* SRAM scrambling key renewal and "wiping" lock, which includes the following
* API: `dif_sram_ctrl_scramble`, `dif_sram_ctrl_request_new_key`
* and `dif_sram_ctrl_wipe`.
*/
kDifSramCtrlLockCtrl = 0,
/**
* Code execution from SRAM lock, which includes the following API:
* `dif_sram_ctrl_exec_set_enabled`.
*
* Note: this setting may not be available depending on the OTP configuration
* of the chip (EN_SRAM_IFETCH fuse).
*/
kDifSramCtrlLockExec,
/**
* Readback feature lock. When locked, disabling or enabling the SRAM readback
* feature is not available anymore. Includes the following API:
* `dif_sram_ctrl_readback_set`.
*/
kDifSramCtrlLockReadback,
} dif_sram_ctrl_lock_t;
/**
* Performs blocking SRAM scrambling operation.
*
* This function should only be called when the data is no longer used.
*
* This is a compound operation covering both data and address "scrambling".
* In other words logical re-mapping of the physical addresses and data
* scrambling, followed by the entire SRAM overwriting with a pseudo-random
* data.
*
* The intention of this operation is to ensure that there is no predefined
* values or predictable data that could potentially make "unscrambling"
* easier.
*
* This operation is expected to take a significant amount of CPU cycles. If
* a non-blocking alternative is required, then `dif_sram_ctrl_request_new_key`,
* should be used followed by `dif_sram_ctrl_wipe`. The status of these
* operations can be found through `dif_sram_ctrl_get_status`.
*
* Note: when dealing with the Main RAM, additional implication is that the
* C runtime can be invalidated by the call to this function, and must be
* re-configured prior to any C code execution.
*
* @param sram_ctrl A SRAM Controller handle.
* @return The result of the operation.
*/
OT_WARN_UNUSED_RESULT
dif_result_t dif_sram_ctrl_scramble(const dif_sram_ctrl_t *sram_ctrl);
/**
* Requests a new scrambling key.
*
* This function should only be called when the data is no longer used.
*
* On successful completion SRAM addresses (due to different logical mapping of
* the physical addresses) and the data are scrambled. However, it is
* recommended to additionally overwrite SRAM with pseudo-random data by calling
* `dif_sram_ctrl_wipe`. This should minimize the chances of revealing the XOR
* key-stream.
*
* This operation is expected to take a significant amount of CPU cycles. The
* status can be checked via `kDifSramCtrlStatusScrKeyValid`, which is useful
* when a non-blocking work flow is desirable. Otherwise any SRAM access will
* automatically block until this operation has finished.
*
* Note: when dealing with the Main RAM, additional implication is that the
* C runtime can be invalidated by the call to this function, and must be
* re-configured prior to any C code execution.
*
* @param sram_ctrl A SRAM Controller handle.
* @return The result of the operation.
*/
OT_WARN_UNUSED_RESULT
dif_result_t dif_sram_ctrl_request_new_key(const dif_sram_ctrl_t *sram_ctrl);
/**
* Overwrites "wipes" the entire SRAM with pseudo-random data.
*
* This function should only be called when the data is no longer used.
*
* This operation is expected to take a significant amount of CPU cycles. The
* status can be checked via `kDifSramCtrlStatusInitDone`, which is useful when
* a non-blocking work flow is desirable. Otherwise any SRAM access will
* automatically block until this operation has finished.
*
* Note: when dealing with the Main RAM, additional implication is that the
* C runtime can be invalidated by the call to this function, and must be
* re-configured prior to any C code execution.
*
* @param sram_ctrl A SRAM Controller handle.
* @return The result of the operation.
*/
OT_WARN_UNUSED_RESULT
dif_result_t dif_sram_ctrl_wipe(const dif_sram_ctrl_t *sram_ctrl);
/**
* Checks whether execution from SRAM is currently enabled or disabled.
*
* @param sram_ctrl A SRAM Controller handle.
* @param[out] state Out-param toggle state of the SRAM execution.
* @return The result of the operation.
*/
OT_WARN_UNUSED_RESULT
dif_result_t dif_sram_ctrl_exec_get_enabled(const dif_sram_ctrl_t *sram_ctrl,
dif_toggle_t *state);
/**
* Sets whether execution from SRAM enabled or disabled.
*
* @param sram_ctrl A SRAM Controller handle.
* @param state The new toggle state for the SRAM execution.
* @return The result of the operation.
*/
OT_WARN_UNUSED_RESULT
dif_result_t dif_sram_ctrl_exec_set_enabled(const dif_sram_ctrl_t *sram_ctrl,
dif_toggle_t state);
/**
* Sets whether the SRAM readback feature is enabled or disabled.
*
* @param sram_ctrl A SRAM Controller handle.
* @param state The new toggle state for the SRAM readback feature.
* @return The result of the operation.
*/
OT_WARN_UNUSED_RESULT
dif_result_t dif_sram_ctrl_readback_set(const dif_sram_ctrl_t *sram_ctrl,
dif_toggle_t state);
/**
* Queries the SRAM Controller status.
*
* `dif_sram_ctrl_status_t` is used to then extract individual status bits.
*
* @param sram_ctrl A SRAM Controller handle.
* @param[out] SRAM Controller status bitfield.
* @return The result of the operation.
*/
OT_WARN_UNUSED_RESULT
dif_result_t dif_sram_ctrl_get_status(const dif_sram_ctrl_t *sram_ctrl,
dif_sram_ctrl_status_bitfield_t *status);
/**
* Locks out requested SRAM Controller functionality.
*
* This function is reentrant: calling it while functionality is locked will
* have no effect and return `kDifOk`.
*
* @param sram_ctrl A SRAM Controller handle.
* @param lock SRAM functionality to lock.
* @return The result of the operation.
*/
OT_WARN_UNUSED_RESULT
dif_result_t dif_sram_ctrl_lock(const dif_sram_ctrl_t *sram_ctrl,
dif_sram_ctrl_lock_t lock);
/**
* Checks whether requested SRAM Controller functionality is locked.
*
* @param sram_ctrl A SRAM Controller handle.
* @param lock SRAM functionality to query locked state for.
* @param[out] is_locked Out-param for the locked state.
* @return The result of the operation.
*/
OT_WARN_UNUSED_RESULT
dif_result_t dif_sram_ctrl_is_locked(const dif_sram_ctrl_t *sram_ctrl,
dif_sram_ctrl_lock_t lock,
bool *is_locked);
/**
* Checks whether requested SRAM Controller successfully obtained a new key.
*
* success is set to kMultiBitBool4True if a key rotation was successful.
*
* The clear parameter can be set to kMultiBitBool4True in order to clear
* the key rotation state back to kMultiBitBool4False after reading it.
* If the state should not be cleared, set clear to kMultiBitBool4False.
*
* @param sram_ctrl A SRAM Controller handle.
* @param[out] success Outparam for the success state.
* @param clear Parameter indicating whether to CSR should be cleared after
* reading.
* @return The result of the operation.
*/
OT_WARN_UNUSED_RESULT
dif_result_t dif_sram_ctrl_scr_key_rotated(const dif_sram_ctrl_t *sram_ctrl,
multi_bit_bool_t *success,
multi_bit_bool_t clear);
#ifdef __cplusplus
} // extern "C"
#endif // __cplusplus
#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_SRAM_CTRL_H_