Add random number generation APIs to the HTML documentation. Fix style issues.
Signed-off-by: Heinrich Schuchardt xypron.glpk@gmx.de --- MAINTAINERS | 1 + doc/api/index.rst | 1 + doc/api/rng.rst | 17 +++++++++++++++++ include/rand.h | 6 +++--- include/rng.h | 26 ++++++++++++++++++-------- 5 files changed, 40 insertions(+), 11 deletions(-) create mode 100644 doc/api/rng.rst
diff --git a/MAINTAINERS b/MAINTAINERS index 1fd975c72f..00985c0e8e 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -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 diff --git a/doc/api/index.rst b/doc/api/index.rst index fd3b5bdc82..b7eb5725f2 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -9,5 +9,6 @@ U-Boot API documentation dfu efi linker_lists + rng serial unicode diff --git a/doc/api/rng.rst b/doc/api/rng.rst new file mode 100644 index 0000000000..b826d4fd4a --- /dev/null +++ b/doc/api/rng.rst @@ -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: diff --git a/include/rand.h b/include/rand.h index c9d15f50a1..4c54fbbd10 100644 --- a/include/rand.h +++ b/include/rand.h @@ -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);
diff --git a/include/rng.h b/include/rng.h index d2c0f9af62..37af554363 100644 --- a/include/rng.h +++ b/include/rng.h @@ -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 * - * Return: 0 if OK, -ve on error + * 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); }; -- 2.27.0