add thread info to pico_rand docs (#1214)

This commit is contained in:
Graham Sanderson 2023-02-02 12:29:06 -06:00 committed by GitHub
parent 31780aed2c
commit fff2c6b467
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

View File

@ -18,14 +18,14 @@ extern "C" {
* *
* Random Number Generator API * Random Number Generator API
* *
* This module generates random numbers at runtime via a number of possible entropy * This module generates random numbers at runtime utilizing a number of possible entropy
* sources and uses those sources to modify the state of a 128-bit 'Pseudo * sources and uses those sources to modify the state of a 128-bit 'Pseudo
* Random Number Generator' implemented in software. * Random Number Generator' implemented in software.
* *
* The random numbers (32 to 128 bit) to be supplied are read from the PRNG which is used * The random numbers (32 to 128 bit) to be supplied are read from the PRNG which is used
* to help provide a large number space. * to help provide a large number space.
* *
* The following (multiple) sources of entropy are available of varying quality, each enabled by a #define: * The following (multiple) sources of entropy are available (of varying quality), each enabled by a #define:
* *
* - The Ring Oscillator (ROSC) (\ref PICO_RAND_ENTROPY_SRC_ROSC == 1): * - The Ring Oscillator (ROSC) (\ref PICO_RAND_ENTROPY_SRC_ROSC == 1):
* \ref PICO_RAND_ROSC_BIT_SAMPLE_COUNT bits are gathered from the ring oscillator "random bit" and mixed in each * \ref PICO_RAND_ROSC_BIT_SAMPLE_COUNT bits are gathered from the ring oscillator "random bit" and mixed in each
@ -54,6 +54,9 @@ extern "C" {
* *
* With default settings, the seed generation takes approximately 1 millisecond while * With default settings, the seed generation takes approximately 1 millisecond while
* subsequent random numbers generally take between 10 and 20 microseconds to generate. * subsequent random numbers generally take between 10 and 20 microseconds to generate.
*
* pico_rand methods may be safely called from either core or from an IRQ, but be careful in the latter case as the
* the calls may block for a number of microseconds waiting on more entropy.
*/ */
// --------------- // ---------------
@ -148,13 +151,19 @@ typedef struct rng_128 {
/*! \brief Get 128-bit random number /*! \brief Get 128-bit random number
* \ingroup pico_rand * \ingroup pico_rand
* *
* \param rand128 Pointer to storage to accept a 128-bit random number * This method may be safely called from either core or from an IRQ, but be careful in the latter case as
* the call may block for a number of microseconds waiting on more entropy.
*
* \param rand128 Pointer to storage to accept a 128-bit random number
*/ */
void get_rand_128(rng_128_t *rand128); void get_rand_128(rng_128_t *rand128);
/*! \brief Get 64-bit random number /*! \brief Get 64-bit random number
* \ingroup pico_rand * \ingroup pico_rand
* *
* This method may be safely called from either core or from an IRQ, but be careful in the latter case as
* the call may block for a number of microseconds waiting on more entropy.
*
* \return 64-bit random number * \return 64-bit random number
*/ */
uint64_t get_rand_64(void); uint64_t get_rand_64(void);
@ -162,6 +171,9 @@ uint64_t get_rand_64(void);
/*! \brief Get 32-bit random number /*! \brief Get 32-bit random number
* \ingroup pico_rand * \ingroup pico_rand
* *
* This method may be safely called from either core or from an IRQ, but be careful in the latter case as
* the call may block for a number of microseconds waiting on more entropy.
*
* \return 32-bit random number * \return 32-bit random number
*/ */
uint32_t get_rand_32(void); uint32_t get_rand_32(void);