[doc] Document how to disable ENTROPY_SRC while CSRNG/EDN remain running

Disabling ENTROPY_SRC (as well as the analog noise source) once all
CSRNG instances have been seeded helps saving power. At the same time,
CSRNG can remain powered to keep serving entropy using the current
seeds. Not having to disable/re-enable the entire entropy complex is
beneficial from a programmer's perspective.

Signed-off-by: Pirmin Vogel <[email protected]>
(cherry picked from commit d56d531)

Author: vogelpi

hw/ip/csrng/doc/programmers_guide.md

@@ -8,6 +8,28 @@ CSRNG may only be disabled if all EDNs are disabled.
 
 The recommended enable sequence for the entropy complex is to first enable ENTROPY_SRC, then CSRNG, and finally the EDNs.
 
+## Running CSRNG with ENTROPY_SRC disabled
+
+Once the entropy complex has been enabled and all configured CSRNG instances have been seeded with entropy, software can again disable ENTROPY_SRC (and the PTRNG noise source to e.g. save power) while CSRNG and the EDNs remain running to keep serving entropy to consumers.
+
+Depending on the mode in which the CSRNG instance is running, software can use a different mechanism to efficiently operate the entropy complex without having the ENTROPY_SRC continuously running:
+
+### Regular, non-deterministic mode
+
+If a CSRNG instance is running in regular, non-deterministic mode (`flag0` being false, see [Generated Bits (`genbits`) Interface](theory_of_operation.md#generated-bits-genbits-interface) for details), the `cs_entropy_req` interrupt will assert whenever the instance requests entropy from ENTROPY_SRC.
+Once software observes the interrupt, it has to enable ENTROPY_SRC.
+The ENTROPY_SRC block will then perform the startup health testing and eventually deliver a new seed to the CSRNG instance.
+Note that the startup health testing may take a non-negligible time (see [Startup Health Testing](../../entropy_src/doc/theory_of_operation.md#startup-health-testing) during which the CSRNG instance is blocked.
+Thus, it is recommended that software tracks the age of the seed currently in use via the corresponding [`RESEED_COUNTER`](registers.md#reseed_counter) register to re-enable ENTROPY_SRC ahead of the `cs_entropy_req` interrupt firing.
+
+### Fully deterministic mode
+
+For CSRNG instances running in fully deterministic mode (`flag0` being true, see [Generated Bits (`genbits`) Interface](theory_of_operation.md#generated-bits-genbits-interface) for details), software has to provide entropy for instantiation and reseeding via the additional data field of the <tt>instantiate</tt> and <tt>reseed</tt> command, respectively.
+If no additional data is provided, CSRNG will use an all-zero seed.
+Additional entropy can be provided via the additional data field of every <tt>generate</tt> command.
+The entropy to be provided to these commands can for example be generated by running the ENTROPY_SRC block in a dedicated mode, see [Reading Entropy Output](../../entropy_src/doc/programmers_guide.md#reading-entropy-output) for details.
+Software is recommended to manage a buffer of seeds which is filled whenever it enables ENTROPY_SRC in this mode to reduce the duty cycle of ENTROPY_SRC (and the PTRNG noise source) thereby improving power efficiency and latency.
+
 ## Endianness and Known-Answer Tests
 
 All CSRNG registers are little-endian.

hw/ip/edn/doc/programmers_guide.md

@@ -60,6 +60,21 @@ Notes:
 
   Future versions of EDN will likely support an automated way for consuming any remaining entropy, see also [Issue #22850](https://github.com/lowRISC/opentitan/issues/22850).
 
+## 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](../../csrng/doc/programmers_guide.md#regular-non-deterministic-mode).
+
+### Fully deterministic mode
+
+The same guidance applies as for [CSRNG](../../csrng/doc/programmers_guide.md#fully-deterministic-mode).
+However, the `generate` and `reseed` commands including the additional data fields can only be configured before starting **[Auto Request Mode](./theory_of_operation.md#auto-request-mode)** via the [`GENERATE_CMD`](registers.md#generate_cmd) and [`RESEED_CMD`](registers.md#reseed_cmd) FIFOs.
+To inject fresh entropy, firmware thus has to [uninstantiate the CSRNG instance through EDN](#uninstantiating-csrng-through-edn), disable EDN, configure the FIFOs and then re-enable EDN in Auto Request Mode, and finally trigger the `instantiate` command.
 
 ## Error conditions