Software APIs
dif_entropy_src.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_ENTROPY_SRC_H_
6#define OPENTITAN_SW_DEVICE_LIB_DIF_DIF_ENTROPY_SRC_H_
7
8/**
9 * @file
10 * @brief <a href="/hw/ip/entropy_src/doc/">Entropy Source</a> Device Interface
11 * Functions
12 */
13
14#include <stdint.h>
15
19
21
22#ifdef __cplusplus
23extern "C" {
24#endif // __cplusplus
25
26/**
27 * A single-bit RNG mode, where only one bit is sampled.
28 */
30 /**
31 * Single-bit-mode, sampling the zeroth bit.
32 */
34 /**
35 * Single-bit-mode, sampling the first bit.
36 */
38 /**
39 * Single-bit-mode, sampling the second bit.
40 */
42 /**
43 * Single-bit-mode, sampling the third bit.
44 */
46 /**
47 * Indicates that single-bit-mode is disabled.
48 */
51
52/**
53 * Main FSM state.
54 */
56 kDifEntropySrcMainFsmStateIdle = 0x0f5,
57 kDifEntropySrcMainFsmStateBootHTRunning = 0x1d2,
58 kDifEntropySrcMainFsmStateBootPostHTChk = 0x16e,
59 kDifEntropySrcMainFsmStateBootPhaseDone = 0x08e,
60 kDifEntropySrcMainFsmStateStartupHTStart = 0x02c,
61 kDifEntropySrcMainFsmStateStartupPhase1 = 0x101,
62 kDifEntropySrcMainFsmStateStartupPass1 = 0x1a5,
63 kDifEntropySrcMainFsmStateStartupFail1 = 0x017,
64 kDifEntropySrcMainFsmStateContHTStart = 0x040,
65 kDifEntropySrcMainFsmStateContHTRunning = 0x1a2,
66 kDifEntropySrcMainFsmStateFWInsertStart = 0x0c3,
67 kDifEntropySrcMainFsmStateFWInsertMsg = 0x059,
68 kDifEntropySrcMainFsmStateSha3MsgDone = 0x10f,
69 kDifEntropySrcMainFsmStateSha3Process = 0x0f8,
70 kDifEntropySrcMainFsmStateSha3Valid = 0x0bf,
71 kDifEntropySrcMainFsmStateSha3Done = 0x198,
72 kDifEntropySrcMainFsmStateAlertState = 0x1cd,
73 kDifEntropySrcMainFsmStateAlertHang = 0x1fb,
74 kDifEntropySrcMainFsmStateError = 0x73
76
77/**
78 * Firmware override parameters for an entropy source.
79 */
81 /**
82 * Enables firmware to insert entropy bits back into the pre-conditioner FIFO
83 * via `dif_entropy_src_fw_ov_data_write()` calls. This feature is useful when
84 * the firmware is required to implement additional health checks, and to
85 * perform known answer tests of the conditioner.
86 *
87 * To take effect, this requires the firmware override feature to be enabled.
88 */
90 /**
91 * This field sets the depth of the observe FIFO hardware buffer used when
92 * the firmware override feature is enabled.
93 */
96
97/**
98 * Runtime configuration for an entropy source.
99 *
100 * This struct describes runtime information for one-time configuration of the
101 * hardware.
102 */
104 /**
105 * If set, FIPS compliant entropy will be generated by this module after being
106 * processed by an SP 800-90B compliant conditioning function.
107 *
108 * Software may opt for implementing FIPS mode of operation without hardware
109 * support by setting this field to false. In such case, software is
110 * responsible for implementing the conditioning function.
111 */
113 /**
114 * If set, the produced output entropy is marked as FIPS compliant
115 * through the FIPS bit being set to high.
116 */
118 /**
119 * If set, the noise source is instructed to produce high quality entropy.
120 */
122 /**
123 * If set, entropy will be routed to a firmware-visible register instead of
124 * being distributed to other hardware IPs.
125 */
127 /**
128 * If set, raw entropy will be sent to CSRNG, bypassing the conditioner block
129 * and disabling the FIPS flag. Note that the FIPS flag is different from
130 * running the block in FIPS mode. FIPS mode refers to running the entropy_src
131 * in continuous mode. Also note that if `fips_enable` is set to `True`, then
132 * at most one of either `route_to_firmware` or `bypass_conditioner` may be
133 * set, but will result in disabling the FIPS mode of operation from a
134 * hardware perspective.
135 */
137 /**
138 * Specifies which single-bit-mode to use, if any at all. FIPS mode of
139 * operation is disabled in single-bit-mode of operation is selected.
140 */
142 /**
143 * Controls the scope (either by-line or by-sum) of the health tests.
144 *
145 * If true, the Adaptive Proportion and Markov Tests will accumulate all RNG
146 * input lines into a single score, and thresholds will be applied to the sum
147 * of all the entropy input lines.
148 *
149 * If false, the RNG input lines are all scored individually. A statistical
150 * deviation in any one input line, be it due to coincidence or failure, will
151 * force rejection of the sample, and count toward the total alert count.
152 */
154 /**
155 * The size of the window used for health tests.
156 *
157 * Units: bits
158 */
160 /**
161 * The number of health test failures that must occur before an alert is
162 * triggered. When set to 0, alerts are disabled.
163 */
166
167/**
168 * A statistical test on the bits emitted by an entropy source.
169 */
171 /**
172 * An SP 800-90B repetition count test.
173 *
174 * This test screens for stuck bits, or a total failure of the noise source.
175 * This test fails if any sequence of bits repeats too many times in a row
176 * for too many samples.
177 */
179 /**
180 * An SP 800-90B symbol repetition count test.
181 *
182 * This is similar to the above, test but is performed on a symbol, instead of
183 * bit, basis.
184 */
186 /**
187 * An SP 800-90B adaptive proportion test.
188 *
189 * This test screens for statistical bias in the number of ones or zeros
190 * output by the noise source.
191 */
193 /**
194 * A bucket test.
195 *
196 * This test looks for correlations between individual noise channels.
197 */
199 /**
200 * A "Markov" test.
201 *
202 * This test looks for unexpected first-order temporal correlations
203 * between individual noise channels.
204 */
206 /**
207 * A firmware-driven "mailbox" test.
208 *
209 * This test allows firmware to inspect 2kbit blocks of entropy, and signal
210 * potential concerns to the hardware.
211 */
213 /** \internal */
214 kDifEntropySrcTestNumVariants = 6,
216
217/**
218 * Criteria used by various entropy source health tests to decide whether the
219 * test has failed.
220 */
222 /**
223 * The entropy source health test type to configure.
224 */
226 /**
227 * The high threshold for the health test (contains both FIPS and bypass
228 * thresholds).
229 */
231 /**
232 * The low threshold for the health test (contains both FIPS and bypass
233 * thresholds).
234 *
235 * If the corresponding health test has no low threshold, set to 0, otherwise
236 * `dif_entropy_src_health_test_configure()` will return `kDifBadArg`.
237 */
240
241/**
242 * Revision information for an entropy source.
243 *
244 * The fields of this struct have an implementation-specific interpretation.
245 */
247 uint8_t abi_revision;
248 uint8_t hw_revision;
249 uint8_t chip_type;
251
252/**
253 * Statistics on entropy source health tests.
254 */
256 /**
257 * High watermark indicating the highest value emitted by a particular test.
258 */
259 uint16_t high_watermark[kDifEntropySrcTestNumVariants];
260 /**
261 * Low watermark indicating the lowest value emitted by a particular test
262 * (contains both FIPS and bypass watermarks).
263 *
264 * Note, some health tests do not emit a low watermark as there is no low
265 * threshold. For these tests, this value will always be UINT16_MAX.
266 */
267 uint16_t low_watermark[kDifEntropySrcTestNumVariants];
268 /**
269 * The number of times a particular test has failed above the high threshold
270 * (contains both FIPS and bypass watermarks).
271 */
272 uint32_t high_fails[kDifEntropySrcTestNumVariants];
273 /**
274 * The number of times a particular test has failed below the low threshold.
275 *
276 * Note, some health tests do not have a low threshold. For these tests, this
277 * value will always be 0.
278 */
279 uint32_t low_fails[kDifEntropySrcTestNumVariants];
281
282/**
283 * Statistics on entropy source health tests failures that triggered alerts.
284 */
286 /**
287 * The total number of test failures, across all test types, that contributed
288 * to the alerts fired.
289 */
290 uint16_t total_fails;
291 /**
292 * The number of test failures, due to the specific test execeeding the high
293 * threshold, that cause alerts to be fired.
294 */
295 uint8_t high_fails[kDifEntropySrcTestNumVariants];
296 /**
297 * The number of test failures, due to the specific test execeeding the low
298 * threshold, that cause alerts to be fired.
299 *
300 * Note, some health tests do not have a low threshold. For these tests, this
301 * value will always be 0.
302 */
303 uint8_t low_fails[kDifEntropySrcTestNumVariants];
305
306/**
307 * SHA3 state machine states.
308 *
309 * See `hw/ip/kmac/rtl/sha3_pkg.sv` for more details.
310 */
312 kDifEntropySrcSha3StateIdle = 0,
313 kDifEntropySrcSha3StateAbsorb = 1,
314 kDifEntropySrcSha3StateSqueeze = 2,
315 kDifEntropySrcSha3StateManualRun = 3,
316 kDifEntropySrcSha3StateFlush = 4,
317 kDifEntropySrcSha3StateError = 5,
319
320/**
321 * Debug status information.
322 */
324 /**
325 * Depth of the entropy source FIFO.
326 *
327 * Valid range: [0, 7]
328 */
330 /**
331 * The current state of the SHA3 preconditioner state machine.
332 *
333 * See `dif_entropy_src_sha3_state_t` for more details.
334 */
336 /**
337 * Whether the SHA3 preconditioner has completed processing the current block.
338 */
340 /**
341 * Whether the SHA3 preconditioner is in the squeezing state.
342 */
344 /**
345 * Whether the SHA3 preconditioner is in the absorbed state.
346 */
348 /**
349 * Whether the SHA3 preconditioner has is in an error state.
350 */
352 /**
353 * Whether the main FSM is in the idle state.
354 */
356 /**
357 * Whether the main FSM is in the boot done state.
358 */
361
362/**
363 * Recoverable alerts.
364 */
366 /**
367 * Triggered when the FIPS_ENABLE field in the CONF register is set to an
368 * unsupported value.
369 */
371 /**
372 * Triggered when the ENTROPY_DATA_REG_ENABLE field in the CONF register is
373 * set to an unsupported value.
374 */
376 /**
377 * Triggered when the MODULE_ENABLE field in the MODULE_ENABLE register is set
378 * to an unsupported value.
379 */
381 /**
382 * Triggered when the THRESHOLD_SCOPE field in the CONF register is set to an
383 * unsupported value.
384 */
386 /**
387 * Triggered when the RNG_BIT_ENABLE field in the CONF register is set to an
388 * unsupported value.
389 */
391 /**
392 * Triggered when the FW_OV_SHA3_START field in the FW_OV_SHA3_START register
393 * is set to an unsupported value.
394 */
396 /**
397 * Triggered when the FW_OV_MODE field in the FW_OV_CONTROL register is set to
398 * an unsupported value.
399 */
401 /**
402 * Triggered when the FW_OV_ENTROPY_INSERT field in the FW_OV_CONTROL register
403 * is set to an unsupported value.
404 */
406 /**
407 * Triggered when the ES_ROUTE field in the ENTROPY_CONTROL register is set to
408 * an unsupported value.
409 */
411 /**
412 * Triggered when the ES_TYPE field in the ENTROPY_CONTROL register is set to
413 * an unsupported value.
414 */
416 /**
417 * Triggered when the main state machine detects a threshold failure state.
418 */
420 /**
421 * Triggered when the internal entropy bus value is equal to the prior valid
422 * value on the bus, indicating a possible attack.
423 */
425 /**
426 * Triggered when the ALERT_THRESHOLD register is not configured properly,
427 * i.e., the upper field must be the exact inverse of the lower field.
428 */
430 /**
431 * Triggered when the packer FIFO has been written but was full at the time
432 * and we are in FW_OV_MODE and FW_OV_ENTROPY_INSERT modes.
433 */
435 /**
436 * Triggered when FW_OV_SHA3_START has been set to kMultiBitBool4False,
437 * without waiting for the bypass packer FIFO to clear.
438 */
440 /**
441 * Triggered when the FIPS_FLAG field in the CONF register is set to an
442 * unsupported value.
443 */
445 /**
446 * Triggered when the RNG_FIPS field in the CONF register is set to an
447 * unsupported value.
448 */
450 /**
451 * All alert reasons.
452 *
453 * This is useful when clearing all recoverable alerts at once.
454 */
457
458/**
459 * Error codes (non-recoverable).
460 */
462 /**
463 * Triggered when a write error has been detected for the esrng FIFO.
464 */
466 /**
467 * Triggered when a read error has been detected for the esrng FIFO.
468 */
470 /**
471 * Triggered when a state error has been detected for the esrng FIFO.
472 */
474 /**
475 * Triggered when a write error has been detected for the observe FIFO.
476 */
478 /**
479 * Triggered when a read error has been detected for the observe FIFO.
480 */
482 /**
483 * Triggered when a state error has been detected for the observe FIFO.
484 */
486 /**
487 * Triggered when a write error has been detected for the esfinal FIFO.
488 */
490 /**
491 * Triggered when a read error has been detected for the esfinal FIFO.
492 */
494 /**
495 * Triggered when a state error has been detected for the esfinal FIFO.
496 */
498 /**
499 * Triggered when an error has been detected for the acknowledgment stage
500 * state machine.
501 */
503 /**
504 * Triggered when an error has been detected for the main state machine.
505 */
507 /**
508 * Triggered when an error has been detected for a hardened counter.
509 */
512
513/**
514 * Stops the current mode of operation and disables the entropy_src module
515 *
516 * @param entropy_src An entropy source handle.
517 * @return The result of the operation.
518 */
521
522/**
523 * Configures entropy source with runtime information.
524 *
525 * This function should only need to be called once for the lifetime of the
526 * `entropy` handle.
527 *
528 * @param entropy_src An entropy source handle.
529 * @param config Runtime configuration parameters.
530 * @param enabled The enablement state of the entropy source.
531 * @return The result of the operation.
532 */
536 dif_toggle_t enabled);
537
538/**
539 * Configures entropy source firmware override feature with runtime information.
540 *
541 * This function should only need to be called once for the lifetime of the
542 * `entropy` handle.
543 *
544 * @param entropy_src An entropy source handle.
545 * @param config Runtime configuration parameters for firmware override.
546 * @param enabled The enablement state of the firmware override option.
547 * @return The result of the operation.
548 */
551 const dif_entropy_src_t *entropy_src,
553
554/**
555 * Configures whether to start the entropy source's SHA3 process and be ready to
556 * accept entropy data.
557 *
558 * This is used in firmware override mode and should be enabled before writing
559 * to the override FIFO. Disable this after writing has finished to ensure the
560 * SHA3 block finishes processing and pushes the results to the `esfinal` FIFO.
561 *
562 * @param entropy_src An entropy source handle.
563 * @param enabled Whether to start the SHA3 process.
564 */
567 const dif_entropy_src_t *entropy_src, dif_toggle_t enabled);
568
569/**
570 * Configures an entropy source health test feature with runtime information.
571 *
572 * This function should only need to be called once for each health test that
573 * requires configuration for the lifetime of the `entropy` handle.
574 *
575 * @param entropy_src An entropy source handle.
576 * @param config Runtime configuration parameters for the health test.
577 * @return The result of the operation.
578 */
581 const dif_entropy_src_t *entropy_src,
583
584/**
585 * Enables/Disables the entropy source.
586 *
587 * @param entropy_src An entropy source handle.
588 * @param enabled The enablement state to configure the entropy source in.
589 * @return The result of the operation.
590 */
593 dif_toggle_t enabled);
594
595/**
596 * Locks out entropy source functionality.
597 *
598 * This function is reentrant: calling it while functionality is locked will
599 * have no effect and return `kDifEntropySrcOk`.
600 *
601 * @param entropy_src An entropy source handle.
602 * @return The result of the operation.
603 */
606
607/**
608 * Checks whether this entropy source is locked.
609 *
610 * @param entropy_src An entropy source handle.
611 * @param[out] is_locked Out-param for the locked state.
612 * @return The result of the operation.
613 */
616 bool *is_locked);
617
618/**
619 * Queries the entropy_src source IP for its revision information.
620 *
621 * @param entropy_src An entropy source handle.
622 * @param[out] revision Out-param for revision data.
623 * @return The result of the operation.
624 */
628
629/**
630 * Queries the entropy source for health test statistics.
631 *
632 * @param entropy_src An entropy source handle.
633 * @param[out] stats Out-param for stats data.
634 * @return The result of the operation.
635 */
638 const dif_entropy_src_t *entropy_src,
640
641/**
642 * Queries the entropy source for health test failure statistics.
643 *
644 * @param entropy_src An entropy source handle.
645 * @param[out] counts Out-param for test failure data that triggers alerts.
646 * @return The result of the operation.
647 */
650 const dif_entropy_src_t *entropy_src,
652
653/**
654 * Checks to see if entropy is available for software consumption.
655 *
656 * @param entropy_src An entropy source handle.
657 * @return The result of the operation.
658 */
661 const dif_entropy_src_t *entropy_src);
662
663/**
664 * Reads a word of entropy from the entropy source.
665 *
666 * @param entropy_src An entropy source handle.
667 * @param[out] word Out-param for the entropy word.
668 * @return The result of the operation.
669 */
672 const dif_entropy_src_t *entropy_src, uint32_t *word);
673
674/**
675 * Performs a blocking read from the entropy pipeline through the observe FIFO,
676 * which contains post health-test, unconditioned entropy.
677 *
678 * The entropy source must be configured with firmware override mode enabled,
679 * and the `len` parameter must be less than or equal to the FIFO threshold set
680 * in the firmware override parameters (that is, the threshold that triggers an
681 * interrupt). Additionally, `buf` may be `NULL`; in this case, reads will be
682 * discarded.
683 *
684 * @param entropy_src An entropy source handle.
685 * @param[out] buf A buffer to fill with words from the pipeline.
686 * @param len The number of words to read into `buf`.
687 * @return The result of the operation.
688 */
691 const dif_entropy_src_t *entropy_src, uint32_t *buf, size_t len);
692
693/**
694 * Performs a nonblocking read from the entropy pipeline through the observe
695 * FIFO, which contains post health-test, unconditioned entropy.
696 *
697 * The entropy source must be configured with firmware override mode enabled.
698 * This function will read at most `*len` words from the observe FIFO and store
699 * them in `buf` if it is not `NULL`. If `buf` is `NULL` then the reads will be
700 * discarded instead. This function never blocks and returns as soon as the FIFO
701 * is empty. It updates `*len` to store the number of actually read words.
702 *
703 * @param entropy_src An entropy source handle.
704 * @param[out] buf A buffer to fill with words from the pipeline.
705 * @param[inout] len A pointer to the maximum number of words to reads. This
706 * value is updated to contain the number of words acually read.
707 * @return The result of the operation.
708 */
711 const dif_entropy_src_t *entropy_src, uint32_t *buf, size_t *len);
712
713/**
714 * Performs a write to the entropy pipeline through the firmware override FIFO.
715 *
716 * Entropy source must be configured with firmware override and insert mode
717 * enabled, otherwise the function will return `kDifError`.
718 *
719 * @param entropy_src An entropy source handle.
720 * @param buf A buffer to push words from into the pipeline.
721 * @param len The number of words to write from `buf`.
722 * @param[out] written The number of words successfully written.
723 * @return The result of the operation.
724 */
727 const dif_entropy_src_t *entropy_src, const uint32_t *buf, size_t len,
728 size_t *written);
729
730/**
731 * Starts conditioner operation.
732 *
733 * Initializes the conditioner. Use the `dif_entropy_src_fw_ov_data_write()`
734 * function to send data to the conditioner, and
735 * `dif_entropy_src_conditioner_stop()` once ready to stop the conditioner
736 * operation.
737 *
738 * This function is only available when firmware override mode is enabled. See
739 * `dif_entropy_src_fw_override_configure()` for more details.
740 *
741 * @param entropy_src An entropy source handle.
742 * @return The result of the operation.
743 */
746 const dif_entropy_src_t *entropy_src);
747
748/**
749 * Stops conditioner operation.
750 *
751 * The conditioner stops processing input data and deposits the result digest
752 * in the entropy source output buffer. This operation is only available in
753 * firmware override mode.
754 *
755 * @param entropy_src An entropy source handle.
756 * @return The result of the operation.
757 */
760 const dif_entropy_src_t *entropy_src);
761
762/**
763 * Checks whether the firmware override write FIFO is full.
764 *
765 * @param entropy_src An entropy source handle.
766 * @param[out] is_full Whether the FIFO is full.
767 * @return The result of the operation.
768 */
771 bool *is_full);
772
773/**
774 * Checks whether the firmware override read FIFO has overflowed.
775 *
776 * @param entropy_src An entropy source handle.
777 * @param[out] has_overflowed Whether the FIFO has overflowed, and data has been
778 * lost.
779 * @return The result of the operation.
780 */
783 const dif_entropy_src_t *entropy_src, bool *has_overflowed);
784
785/**
786 * Read the firmware override FIFO depth.
787 *
788 * @param entropy_src An entropy source handle.
789 * @param[out] fifo_depth The FIFO depth.
790 * @return The result of the operation.
791 */
794 const dif_entropy_src_t *entropy_src, uint32_t *fifo_depth);
795
796/**
797 * Reads the debug status register.
798 *
799 * @param entropy_src An entropy source handle.
800 * @param[out] debug_state The current debug state of the IP.
801 * @return The result of the operation.
802 */
805 const dif_entropy_src_t *entropy_src,
806 dif_entropy_src_debug_state_t *debug_state);
807
808/**
809 * Reads the recoverable alert status register.
810 *
811 * @param entropy_src An entropy source handle.
812 * @param[out] alerts The alerts that were triggered (one or more
813 * `dif_entropy_src_alert_t`'s ORed together).
814 * @return The result of the operation.
815 */
818 const dif_entropy_src_t *entropy_src, uint32_t *alerts);
819
820/**
821 * Clears the alerts that are recoverable.
822 *
823 * @param entropy_src An entropy source handle.
824 * @param alerts The alerts to be cleared (one or more
825 * `dif_entropy_src_alert_t`'s ORed together).
826 * @return The result of the operation.
827 */
830 const dif_entropy_src_t *entropy_src, uint32_t alerts);
831
832/**
833 * Reads the (nonrecoverable) error code status register.
834 *
835 * @param entropy_src An entropy source handle.
836 * @param[out] errors The errors that were triggered (one or more
837 * `dif_entropy_src_error_t`'s ORed together).
838 * @return The result of the operation.
839 */
842 uint32_t *errors);
843
844/**
845 * Forces the hardware to generate a error for testing purposes.
846 *
847 * @param entropy_src An entropy source handle.
848 * @param error The error to force (for testing purposes).
849 * @return The result of the operation.
850 */
854
855/**
856 * Reads the current main FSM state.
857 *
858 * @param entropy_src An entropy source handle.
859 * @param[out] state The current FSM state.
860 * @return The result of the operation.
861 */
864 const dif_entropy_src_t *entropy_src, dif_entropy_src_main_fsm_t *state);
865
866#ifdef __cplusplus
867} // extern "C"
868#endif // __cplusplus
869
870#endif // OPENTITAN_SW_DEVICE_LIB_DIF_DIF_ENTROPY_SRC_H_