From 5c812742c68d6564061ab195e1e8bc157c0f815a Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Thu, 20 May 2021 17:08:17 +1000 Subject: [PATCH] docs: Add description for Linux getrandom() function --- components/esp_hw_support/include/esp_random.h | 3 ++- docs/en/api-reference/system/random.rst | 17 +++++++++++++++++ 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/components/esp_hw_support/include/esp_random.h b/components/esp_hw_support/include/esp_random.h index 3b939ef132..cf4f408b51 100644 --- a/components/esp_hw_support/include/esp_random.h +++ b/components/esp_hw_support/include/esp_random.h @@ -29,7 +29,8 @@ extern "C" { * Guide "Random Number Generation" section for necessary prerequisites. * * This function automatically busy-waits to ensure enough external entropy has been - * introduced into the hardware RNG state, before returning a new random number. + * introduced into the hardware RNG state, before returning a new random number. This delay + * is very short (always less than 100 CPU cycles). * * @return Random value between 0 and UINT32_MAX */ diff --git a/docs/en/api-reference/system/random.rst b/docs/en/api-reference/system/random.rst index a25f65946f..da4cb1e321 100644 --- a/docs/en/api-reference/system/random.rst +++ b/docs/en/api-reference/system/random.rst @@ -45,5 +45,22 @@ API Reference .. include-build-file:: inc/esp_random.inc .. include-build-file:: inc/bootloader_random.inc +getrandom +--------- + +A compatible version of the Linux ``getrandom()`` function is also provided for ease of porting: + +.. code-block:: c + + #include + + ssize_t getrandom(void *buf, size_t buflen, unsigned int flags); + +This function is implemented by calling :cpp:func:`esp_fill_random` internally. + +The ``flags`` argument is ignored, this function is always non-blocking but the strength of any random numbers is dependent on the same conditions described above. + +Return value is -1 (with ``errno`` set to ``EFAULT``) if the ``buf`` argument is NULL, and equal to ``buflen`` otherwise. + .. _Dieharder: https://webhome.phy.duke.edu/~rgb/General/dieharder.php