Software APIs
dif_csrng.c
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
6
12
13#include "hw/top/csrng_regs.h" // Generated
14
15/**
16 * Reads the output data register status.
17 */
18static void get_output_status(const dif_csrng_t *csrng,
20 uint32_t reg =
21 mmio_region_read32(csrng->base_addr, CSRNG_GENBITS_VLD_REG_OFFSET);
22 status->valid_data =
23 bitfield_bit32_read(reg, CSRNG_GENBITS_VLD_GENBITS_VLD_BIT);
24 status->fips_mode =
25 bitfield_bit32_read(reg, CSRNG_GENBITS_VLD_GENBITS_FIPS_BIT);
26}
27
28/**
29 * Returns true if the data register has valid data.
30 */
31static void spin_until_ready(const dif_csrng_t *csrng) {
33 do {
34 get_output_status(csrng, &status);
35 } while (!status.valid_data);
36}
37
38enum {
39 /**
40 * Number of INT_STATE_VAL words making up the internal state of an instance.
41 */
42 kCsrngIntStateNumWords = 26,
43 /**
44 * Word indexes of the internal state fields within INT_STATE_VAL.
45 */
46 kCsrngIntStateReseedCounterIdx = 0,
47 kCsrngIntStateVIdx = 1,
48 kCsrngIntStateKeyIdx = 5,
49 kCsrngIntStateFlagsIdx = 25,
50};
51
52/**
53 * Returns an INT_STATE_HALT register value that halts (`halt` is true) or
54 * resumes the instance selected by INT_STATE_NUM.
55 */
56static uint32_t int_state_halt_reg(bool halt) {
57 return bitfield_field32_write(
58 0, CSRNG_INT_STATE_HALT_INT_STATE_HALT_FIELD,
59 halt ? kMultiBitBool4True : kMultiBitBool4False);
60}
61
62static dif_result_t check_locked(const dif_csrng_t *csrng) {
63 if (mmio_region_read32(csrng->base_addr, CSRNG_REGWEN_REG_OFFSET) == 0) {
64 return kDifLocked;
65 }
66 return kDifOk;
67}
68
69dif_result_t dif_csrng_configure(const dif_csrng_t *csrng) {
70 if (csrng == NULL) {
71 return kDifBadArg;
72 }
73 DIF_RETURN_IF_ERROR(check_locked(csrng));
74
75 uint32_t reg =
76 bitfield_field32_write(0, CSRNG_CTRL_ENABLE_FIELD, kMultiBitBool4True);
77 reg = bitfield_field32_write(reg, CSRNG_CTRL_SW_APP_ENABLE_FIELD,
78 kMultiBitBool4True);
79 reg = bitfield_field32_write(reg, CSRNG_CTRL_READ_INT_STATE_FIELD,
80 kMultiBitBool4True);
81 reg = bitfield_field32_write(reg, CSRNG_CTRL_WRITE_INT_STATE_FIELD,
82 kMultiBitBool4False);
83 reg = bitfield_field32_write(reg, CSRNG_CTRL_FIPS_FORCE_ENABLE_FIELD,
84 kMultiBitBool4False);
85 mmio_region_write32(csrng->base_addr, CSRNG_CTRL_REG_OFFSET, reg);
86 return kDifOk;
87}
88
89dif_result_t dif_csrng_instantiate(
90 const dif_csrng_t *csrng, dif_csrng_entropy_src_toggle_t entropy_src_enable,
91 const dif_csrng_seed_material_t *seed_material) {
92 if (csrng == NULL || seed_material == NULL) {
93 return kDifBadArg;
94 }
95 return csrng_send_app_cmd(csrng->base_addr, kCsrngAppCmdTypeCsrng,
97 .id = kCsrngAppCmdInstantiate,
98 .entropy_src_enable = entropy_src_enable,
99 .seed_material = seed_material,
100 });
101}
102
103dif_result_t dif_csrng_reseed(const dif_csrng_t *csrng,
104 const dif_csrng_seed_material_t *seed_material) {
105 if (csrng == NULL || seed_material == NULL) {
106 return kDifBadArg;
107 }
108 return csrng_send_app_cmd(csrng->base_addr, kCsrngAppCmdTypeCsrng,
110 .id = kCsrngAppCmdReseed,
111 .seed_material = seed_material,
112 });
113}
114
115dif_result_t dif_csrng_update(const dif_csrng_t *csrng,
116 const dif_csrng_seed_material_t *seed_material) {
117 if (csrng == NULL || seed_material == NULL) {
118 return kDifBadArg;
119 }
120 return csrng_send_app_cmd(csrng->base_addr, kCsrngAppCmdTypeCsrng,
122 .id = kCsrngAppCmdUpdate,
123 .seed_material = seed_material,
124 });
125}
126
127dif_result_t dif_csrng_generate_start(
128 const dif_csrng_t *csrng, const dif_csrng_seed_material_t *additional_data,
129 size_t len) {
130 if (csrng == NULL || len == 0) {
131 return kDifBadArg;
132 }
133
134 // Round up the number of 128bit blocks. Aligning with respect to uint32_t.
135 // TODO(#6112): Consider using a canonical reference for alignment operations.
136 const uint32_t num_128bit_blocks = (len + 3) / 4;
137 return csrng_send_app_cmd(csrng->base_addr, kCsrngAppCmdTypeCsrng,
139 .id = kCsrngAppCmdGenerate,
140 .seed_material = additional_data,
141 .generate_len = num_128bit_blocks,
142 });
143}
144
145dif_result_t dif_csrng_generate_read(const dif_csrng_t *csrng, uint32_t *buf,
146 size_t len) {
147 if (csrng == NULL || buf == NULL) {
148 return kDifBadArg;
149 }
150
151 for (size_t i = 0; i < len; ++i) {
152 // Block until there is more data available in the genbits buffer.
153 if (i % kCsrngGenBitsBufferSize == 0) {
154 spin_until_ready(csrng);
155 }
156 buf[i] = mmio_region_read32(csrng->base_addr, CSRNG_GENBITS_REG_OFFSET);
157 }
158 return kDifOk;
159}
160
161dif_result_t dif_csrng_uninstantiate(const dif_csrng_t *csrng) {
162 if (csrng == NULL) {
163 return kDifBadArg;
164 }
165 return csrng_send_app_cmd(csrng->base_addr, kCsrngAppCmdTypeCsrng,
167 .id = kCsrngAppCmdUninstantiate,
168 });
169}
170
171dif_result_t dif_csrng_get_cmd_interface_status(
173 if (csrng == NULL || status == NULL) {
174 return kDifBadArg;
175 }
177
178 uint32_t reg =
179 mmio_region_read32(csrng->base_addr, CSRNG_SW_CMD_STS_REG_OFFSET);
180 bool cmd_ready = bitfield_bit32_read(reg, CSRNG_SW_CMD_STS_CMD_RDY_BIT);
181 uint32_t cmd_sts = bitfield_field32_read(reg, CSRNG_SW_CMD_STS_CMD_STS_FIELD);
182
183 status->cmd_sts = cmd_sts;
184 // If the command did not execute successfully, return the error status.
185 if (cmd_sts != 0) {
187 return kDifOk;
188 }
189
190 if (cmd_ready) {
192 return kDifOk;
193 }
194
196 return kDifOk;
197}
198
199dif_result_t dif_csrng_get_cmd_force_unhealthy_fifo(const dif_csrng_t *csrng,
200 dif_csrng_fifo_t fifo) {
201 if (csrng == NULL) {
202 return kDifBadArg;
203 }
204
205 uint32_t fifo_bit;
206 switch (fifo) {
207 case kDifCsrngFifoCmd:
208 fifo_bit = CSRNG_ERR_CODE_SFIFO_CMD_ERR_BIT;
209 break;
210 case kDifCsrngFifoGenBits:
211 fifo_bit = CSRNG_ERR_CODE_SFIFO_GENBITS_ERR_BIT;
212 break;
213 default:
214 return kDifBadArg;
215 }
216
217 DIF_RETURN_IF_ERROR(check_locked(csrng));
218 mmio_region_write32(csrng->base_addr, CSRNG_ERR_CODE_TEST_REG_OFFSET,
219 fifo_bit);
220 return kDifOk;
221}
222
223dif_result_t dif_csrng_get_cmd_force_error(const dif_csrng_t *csrng,
224 dif_csrng_error_t error) {
225 if (csrng == NULL) {
226 return kDifBadArg;
227 }
228
229 uint32_t error_bit;
230 switch (error) {
232 error_bit = CSRNG_ERR_CODE_CMD_STAGE_SM_ERR_BIT;
233 break;
235 error_bit = CSRNG_ERR_CODE_MAIN_SM_ERR_BIT;
236 break;
238 error_bit = CSRNG_ERR_CODE_CTR_DRBG_SM_ERR_BIT;
239 break;
241 error_bit = CSRNG_ERR_CODE_AES_CIPHER_SM_ERR_BIT;
242 break;
244 error_bit = CSRNG_ERR_CODE_CTR_ERR_BIT;
245 break;
247 error_bit = CSRNG_ERR_CODE_FIFO_WRITE_ERR_BIT;
248 break;
250 error_bit = CSRNG_ERR_CODE_FIFO_READ_ERR_BIT;
251 break;
253 error_bit = CSRNG_ERR_CODE_FIFO_STATE_ERR_BIT;
254 break;
255 default:
256 return kDifBadArg;
257 }
258
259 DIF_RETURN_IF_ERROR(check_locked(csrng));
260 mmio_region_write32(csrng->base_addr, CSRNG_ERR_CODE_TEST_REG_OFFSET,
261 error_bit);
262 return kDifOk;
263}
264
265dif_result_t dif_csrng_get_main_state_machine(const dif_csrng_t *csrng,
266 uint32_t *state) {
267 if (csrng == NULL || state == NULL) {
268 return kDifBadArg;
269 }
270
271 *state = mmio_region_read32(csrng->base_addr, CSRNG_MAIN_SM_STATE_REG_OFFSET);
272 return kDifOk;
273}
274
275dif_result_t dif_csrng_get_hw_csrng_exceptions(const dif_csrng_t *csrng,
276 uint32_t *exceptions) {
277 if (csrng == NULL || exceptions == NULL) {
278 return kDifBadArg;
279 }
280
281 *exceptions =
282 mmio_region_read32(csrng->base_addr, CSRNG_HW_EXC_STS_REG_OFFSET);
283 return kDifOk;
284}
285
286dif_result_t dif_csrng_clear_hw_csrng_exceptions(const dif_csrng_t *csrng) {
287 if (csrng == NULL) {
288 return kDifBadArg;
289 }
290
291 mmio_region_write32(csrng->base_addr, CSRNG_HW_EXC_STS_REG_OFFSET, 0);
292 return kDifOk;
293}
294
295dif_result_t dif_csrng_get_output_status(const dif_csrng_t *csrng,
297 if (csrng == NULL || status == NULL) {
298 return kDifBadArg;
299 }
300 get_output_status(csrng, status);
301 return kDifOk;
302}
303
304dif_result_t dif_csrng_get_internal_state(
305 const dif_csrng_t *csrng, dif_csrng_internal_state_id_t instance_id,
307 if (csrng == NULL || state == NULL) {
308 return kDifBadArg;
309 }
310
311 // Select the instance id to read the internal state from.
312 uint32_t reg = bitfield_field32_write(
313 0, CSRNG_INT_STATE_NUM_INT_STATE_NUM_FIELD, instance_id);
314 mmio_region_write32(csrng->base_addr, CSRNG_INT_STATE_NUM_REG_OFFSET, reg);
315 uint32_t actual_reg =
316 mmio_region_read32(csrng->base_addr, CSRNG_INT_STATE_NUM_REG_OFFSET);
317 if (reg != actual_reg) {
318 return kDifError;
319 }
320
321 // Confirm that saving the internal state of the instance is enabled.
322 if (!mmio_region_get_bit32(csrng->base_addr,
323 CSRNG_INT_STATE_READ_ENABLE_REG_OFFSET,
324 (uint32_t)instance_id)) {
325 return kDifLocked;
326 }
327
328 // Confirm that halting the instance is enabled.
329 if (!mmio_region_get_bit32(csrng->base_addr,
330 CSRNG_INT_STATE_HALT_ENABLE_REG_OFFSET,
331 (uint32_t)instance_id)) {
332 return kDifLocked;
333 }
334
335 // Request that the instance halts, and wait for it to do so.
336 mmio_region_write32(csrng->base_addr, CSRNG_INT_STATE_HALT_REG_OFFSET,
337 int_state_halt_reg(/*halt=*/true));
338 while (!mmio_region_get_bit32(csrng->base_addr,
339 CSRNG_INT_STATE_STS_REG_OFFSET,
340 CSRNG_INT_STATE_STS_HALTED_BIT)) {
341 }
342
343 // Read the complete internal state, such that the word pointer wraps around.
344 uint32_t words[kCsrngIntStateNumWords];
345 for (size_t i = 0; i < ARRAYSIZE(words); ++i) {
346 words[i] =
347 mmio_region_read32(csrng->base_addr, CSRNG_INT_STATE_VAL_REG_OFFSET);
348 }
349
350 state->reseed_counter = words[kCsrngIntStateReseedCounterIdx];
351
352 for (size_t i = 0; i < ARRAYSIZE(state->v); ++i) {
353 state->v[i] = words[kCsrngIntStateVIdx + i];
354 }
355
356 for (size_t i = 0; i < ARRAYSIZE(state->key); ++i) {
357 state->key[i] = words[kCsrngIntStateKeyIdx + i];
358 }
359
360 uint32_t flags = words[kCsrngIntStateFlagsIdx];
361
362 // The following bit indexes are defined in
363 // https://opentitan.org/book/hw/ip/csrng/doc/theory_of_operation.html#working-state-values
364 state->instantiated = bitfield_bit32_read(flags, /*bit_index=*/0u);
365 state->fips_compliance = bitfield_bit32_read(flags, /*bit_index=*/1u);
366
367 // Resume normal command processing for this instance.
368 mmio_region_write32(csrng->base_addr, CSRNG_INT_STATE_HALT_REG_OFFSET,
369 int_state_halt_reg(/*halt=*/false));
370
371 return kDifOk;
372}
373
374dif_result_t dif_csrng_get_reseed_counter(
375 const dif_csrng_t *csrng, dif_csrng_internal_state_id_t instance_id,
376 uint32_t *reseed_counter) {
377 if (csrng == NULL || reseed_counter == NULL) {
378 return kDifBadArg;
379 }
380
381 uint32_t reg_offset;
382 switch (instance_id) {
384 reg_offset = CSRNG_RESEED_COUNTER_0_REG_OFFSET;
385 break;
387 reg_offset = CSRNG_RESEED_COUNTER_1_REG_OFFSET;
388 break;
390 reg_offset = CSRNG_RESEED_COUNTER_2_REG_OFFSET;
391 break;
392 default:
393 return kDifBadArg;
394 }
395
396 // Read the reseed counter.
397 *reseed_counter = mmio_region_read32(csrng->base_addr, (ptrdiff_t)reg_offset);
398
399 return kDifOk;
400}
401
402dif_result_t dif_csrng_lock(const dif_csrng_t *csrng) {
403 if (csrng == NULL) {
404 return kDifBadArg;
405 }
406 mmio_region_write32(csrng->base_addr, CSRNG_REGWEN_REG_OFFSET, 0);
407 return kDifOk;
408}
409
410dif_result_t dif_csrng_is_locked(const dif_csrng_t *csrng, bool *is_locked) {
411 if (csrng == NULL || is_locked == NULL) {
412 return kDifBadArg;
413 }
414 *is_locked = check_locked(csrng) != kDifOk;
415 return kDifOk;
416}
417
418dif_result_t dif_csrng_stop(const dif_csrng_t *csrng) {
419 if (csrng == NULL) {
420 return kDifBadArg;
421 }
422 DIF_RETURN_IF_ERROR(check_locked(csrng));
423 mmio_region_write32(csrng->base_addr, CSRNG_CTRL_REG_OFFSET,
424 CSRNG_CTRL_REG_RESVAL);
425 return kDifOk;
426}
427
428dif_result_t dif_csrng_get_recoverable_alerts(const dif_csrng_t *csrng,
429 uint32_t *alerts) {
430 if (csrng == NULL || alerts == NULL) {
431 return kDifBadArg;
432 }
433
434 *alerts =
435 mmio_region_read32(csrng->base_addr, CSRNG_RECOV_ALERT_STS_REG_OFFSET);
436
437 return kDifOk;
438}
439
440dif_result_t dif_csrng_clear_recoverable_alerts(const dif_csrng_t *csrng) {
441 if (csrng == NULL) {
442 return kDifBadArg;
443 }
444 mmio_region_write32(csrng->base_addr, CSRNG_RECOV_ALERT_STS_REG_OFFSET, 0);
445 return kDifOk;
446}