doc: random number generation

Add random number generation APIs to the HTML documentation.
Fix style issues.

Signed-off-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
This commit is contained in:
Heinrich Schuchardt 2020-06-13 12:29:52 +02:00
parent 9d886fd6a0
commit c7ff87e0ae
5 changed files with 40 additions and 11 deletions

View File

@ -877,6 +877,7 @@ M: Sughosh Ganu <sughosh.ganu@linaro.org>
R: Heinrich Schuchardt <xypron.glpk@gmx.de>
S: Maintained
F: cmd/rng.c
F: doc/api/rng.rst
F: drivers/rng/
F: drivers/virtio/virtio_rng.c
F: include/rng.h

View File

@ -9,5 +9,6 @@ U-Boot API documentation
dfu
efi
linker_lists
rng
serial
unicode

17
doc/api/rng.rst Normal file
View File

@ -0,0 +1,17 @@
.. SPDX-License-Identifier: GPL-2.0+
.. Copyright (c) 2018 Heinrich Schuchardt
Random number generation
========================
Hardware random number generation
---------------------------------
.. kernel-doc:: include/rng.h
:internal:
Pseudo random number generation
-------------------------------
.. kernel-doc:: include/rand.h
:internal:

View File

@ -22,7 +22,7 @@ void srand(unsigned int seed);
/**
* rand() - Get a 32-bit pseudo-random number
*
* @returns next random number in the sequence
* Return: next random number in the sequence
*/
unsigned int rand(void);
@ -32,8 +32,8 @@ unsigned int rand(void);
* This version of the function allows multiple sequences to be used at the
* same time, since it requires the caller to store the seed value.
*
* @seed value to use, updated on exit
* @returns next random number in the sequence
* @seedp: seed value to use, updated on exit
* Return: next random number in the sequence
*/
unsigned int rand_r(unsigned int *seedp);

View File

@ -10,22 +10,32 @@ struct udevice;
/**
* dm_rng_read() - read a random number seed from the rng device
* @buffer: input buffer to put the read random seed into
* @size: number of bytes of random seed read
*
* The function blocks until the requested number of bytes is read.
*
* @dev: random number generator device
* @buffer: input buffer to put the read random seed into
* @size: number of random bytes to read
* Return: 0 if OK, -ve on error
*/
int dm_rng_read(struct udevice *dev, void *buffer, size_t size);
/* struct dm_rng_ops - Operations for the hwrng uclass */
/**
* struct dm_rng_ops - operations for the hwrng uclass
*
* This structures contains the function implemented by a hardware random
* number generation device.
*/
struct dm_rng_ops {
/**
* @read() - read a random number seed
* @read: read a random bytes
*
* @data: input buffer to read the random seed
* @max: total number of bytes to read
* The function blocks until the requested number of bytes is read.
*
* Return: 0 if OK, -ve on error
* @read.dev: random number generator device
* @read.data: input buffer to read the random seed into
* @read.max: number of random bytes to read
* @read.Return: 0 if OK, -ve on error
*/
int (*read)(struct udevice *dev, void *data, size_t max);
};