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