Programmer’s Guide
Initialization
The following code snippet demonstrates initializing the EDN block.
void edn_init(unsigned int enable) {
// set the control register enable bit
*CTRL_REG = enable; // should be 0x1 by default
// the EDN interrupts can optionally be enabled
}
Module enable and disable
EDN may only be enabled if CSRNG is enabled. Once disabled, EDN may only be re-enabled after CSRNG has been disabled and re-enabled. The only exception to this is when firmware takes care of properly uninstantiating the associated CSRNG instance before disabling EDN. EDN can then be safely re-enabled without disabling and re-enabling CSRNG first. For details, refer to Uninstantiating CSRNG instance through EDN.
The recommended enable sequence for the entropy complex is to first enable ENTROPY_SRC, then CSRNG, and finally EDN.
Uninstantiating CSRNG through EDN
To disable and re-enable EDN without disabling and re-enabling CSRNG, firmware must ensure the associated CSRNG instance is properly uninstantiated. Otherwise, EDN and the associated CSRNG application interface may get out of sync at which point both EDN and CSRNG have to be disabled and re-enabled. This means unrelated CSRNG instances and EDNs also get disabled and then need to be re-configured.
The procedure for uninstantiating the associated CSRNG instance depends on the mode in which EDN is operating.
-
When running in Software Port Mode, firmware has to individually trigger commands via the
SW_CMD_REQ
register. The status of the current command can be inferred using theSW_CMD_STS
register. For details, refer to Interaction with CSRNG Application Interface Ports. In case the current command is agenerate
command, firmware must wait for all entropy generated from this command to be consumed before the command is acknowledged by CSRNG (indicated by theCMD_ACK
bit of theSW_CMD_STS
register being set). Firmware can then issue anuninstantiate
command to destroy the associated CSRNG instance. Once theuninstantiate
command is acknowledged, firmware can safely reconfigure EDN. -
When running in Boot-Time Request Mode, firmware must first de-assert the
BOOT_REQ_MODE
andAUTO_REQ_MODE
fields inCTRL
and then must wait for all boot-time entropy to be consumed. EDN then automatically issues anuninstantiate
command to destroy the associated CSRNG instance. Upon completion, the state machine of EDN enters theSWPortMode
state. At this point, EDN has entered Software Port Mode (see above) and firmware can then safely reconfigure EDN. -
When running in Auto Request Mode, firmware must first de-assert the
AUTO_REQ_MODE
andBOOT_REQ_MODE
fields inCTRL
and then must wait for the current command to complete, after which the state machine of EDN enters theSWPortMode
state. At this point, EDN has entered Software Port Mode (see above), and firmware can issue anuninstantiate
command to destroy the associated CSRNG instance. Once theuninstantiate
command is acknowledged, firmware can safely reconfigure EDN.
Notes:
-
Firmware can infer the EDN state using the
MAIN_SM_STATE
register. -
The de-assertion of the
BOOT_REQ_MODE
andAUTO_REQ_MODE
fields inCTRL
is only registered by the EDN state machine upon completion of the current command. In case of thegenerate
command, this means to wait for all entropy generated from this command to have been consumed, which depending on the configuration of the system, may take a very long time. To accelerate this process, firmware can for example do the following:- For EDN0, repeatedly trigger reseeding operations of the AES PRNGs via the
PRNG_RESEED
bit of the AESTRIGGER
register. Once all entropy is consumed, the reseed operation doesn’t finish anymore and theIDLE
bit of the AESSTATUS
register remains de-asserted. - For EDN1 which only interfaces the RND port of OTBN, load and repeatedly run an OTBN program snippet that reads from the RND port such as
randomness.s
. Once all entropy is consumed, the program doesn’t finish anymore and theSTATUS
register remains atBUSY_EXECUTE
.
Future versions of EDN will likely support an automated way for consuming any remaining entropy, see also Issue #22850.
- For EDN0, repeatedly trigger reseeding operations of the AES PRNGs via the
Running EDN in Auto Request Mode with ENTROPY_SRC disabled
Once the entropy complex has been enabled and all configured CSRNG instances have been seeded with entropy, firmware can again disable ENTROPY_SRC (and the PTRNG noise source to e.g. save power) while CSRNG and EDN remain running to keep serving entropy to consumers.
Depending on the mode in which EDN and the associated CSRNG instance are running, firmware can use a different mechanism to efficiently operate the entropy complex without having the ENTROPY_SRC continuously running:
Regular, non-deterministic mode
The same guidance applies as for CSRNG.
Fully deterministic mode
The same guidance applies as for CSRNG.
However, the generate
and reseed
commands including the additional data fields can only be configured before starting Auto Request Mode via the GENERATE_CMD
and RESEED_CMD
FIFOs.
To inject fresh entropy, firmware thus has to uninstantiate the CSRNG instance through EDN, disable EDN, configure the FIFOs and then re-enable EDN in Auto Request Mode, and finally trigger the instantiate
command.
Error conditions
Need to alert the system of a FIFO overflow condition.