[PATCH 1/1] doc: add system reset to API documentation
Sean Anderson
seanga2 at gmail.com
Fri Sep 24 07:51:14 CEST 2021
On 9/24/21 1:27 AM, Alexandre Ghiti wrote:
> On Thu, Sep 23, 2021 at 11:12 AM Heinrich Schuchardt
> <heinrich.schuchardt at canonical.com> wrote:
>>
>> Complete the Sphinx documentation in include/sysreset.h
>> Add the include to the generated HTML documentation of the U-Boot API.
>>
>> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
>> ---
>> doc/api/index.rst | 1 +
>> doc/api/sysreset.rst | 7 ++++++
>> include/sysreset.h | 53 ++++++++++++++++++++++++++++----------------
>> 3 files changed, 42 insertions(+), 19 deletions(-)
>> create mode 100644 doc/api/sysreset.rst
>>
>> diff --git a/doc/api/index.rst b/doc/api/index.rst
>> index ea02aa5715..281d1dca96 100644
>> --- a/doc/api/index.rst
>> +++ b/doc/api/index.rst
>> @@ -15,5 +15,6 @@ U-Boot API documentation
>> rng
>> sandbox
>> serial
>> + sysreset
>> timer
>> unicode
>> diff --git a/doc/api/sysreset.rst b/doc/api/sysreset.rst
>> new file mode 100644
>> index 0000000000..a51b06c387
>> --- /dev/null
>> +++ b/doc/api/sysreset.rst
>> @@ -0,0 +1,7 @@
>> +.. SPDX-License-Identifier: GPL-2.0+
>> +
>> +System reset
>> +============
>> +
>> +.. kernel-doc:: include/sysreset.h
>> + :internal:
>> diff --git a/include/sysreset.h b/include/sysreset.h
>> index 701e4f5c86..e8411f9664 100644
>> --- a/include/sysreset.h
>> +++ b/include/sysreset.h
>> @@ -9,43 +9,55 @@
>>
>> struct udevice;
>>
>> +/**
>> + * enum systreset_t - system reset types
>> + */
>> enum sysreset_t {
>> - SYSRESET_WARM, /* Reset CPU, keep GPIOs active */
>> - SYSRESET_COLD, /* Reset CPU and GPIOs */
>> - SYSRESET_POWER, /* Reset PMIC (remove and restore power) */
>> - SYSRESET_POWER_OFF, /* Turn off power */
>> -
>> + /** @SYSRESET_WARM: reset CPU, keep GPIOs active */
>> + SYSRESET_WARM,
>> + /** @SYSRESET_COLD: reset CPU and GPIOs */
>> + SYSRESET_COLD,
>> + /** @SYSRESET_POWER: reset PMIC (remove and restore power) */
>> + SYSRESET_POWER,
>> + /** @SYSRESET_POWER_OFF: turn off power */
>> + SYSRESET_POWER_OFF,
>> + /** @SYSRESET_COUNT: number of available reset types */
>> SYSRESET_COUNT,
>> };
>>
>> +/**
>> + * struct sysreset_ops - operations of system reset drivers
>> + */
>> struct sysreset_ops {
>> /**
>> - * request() - request a sysreset of the given type
>> + * @request: request a sysreset of the given type
>> *
>> * Note that this function may return before the reset takes effect.
>> *
>> + * @dev: Device to be used for system reset
>> * @type: Reset type to request
>> - * @return -EINPROGRESS if the reset has been started and
>> - * will complete soon, -EPROTONOSUPPORT if not supported
>> - * by this device, 0 if the reset has already happened
>> - * (in which case this method will not actually return)
>> + * Return:
>
> Shouldn't this be @Return (and for all others below too)? Otherwise
> the output of "Result" is not bold.
> And I also noticed that all parameters and return descriptions appear
> on the same line: include/dm/pinctrl.h adds newlines between each
> parameter description and then every argument has its own line.
The issue here is that the recommended style [1] does not work well for
struct members. To get things looking reasonably you have to mess with
the formatting a bit. An alternative is to put a short description in
the struct itself, and add a longer version in ifdef'd out "virtual"
functions, such as in [2].
--Sean
[1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#return-values
[2] https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/include/linux/phylink.h#n81
>> + * -EINPROGRESS if the reset has been started and
>> + * will complete soon, -EPROTONOSUPPORT if not supported
>> + * by this device, 0 if the reset has already happened
>> + * (in which case this method will not actually return)
>> */
>> int (*request)(struct udevice *dev, enum sysreset_t type);
>> /**
>> - * get_status() - get printable reset status information
>> + * @get_status: get printable reset status information
>> *
>> * @dev: Device to check
>> * @buf: Buffer to receive the textual reset information
>> * @size: Size of the passed buffer
>> - * @return 0 if OK, -ve on error
>> + * Return: 0 if OK, -ve on error
>> */
>> int (*get_status)(struct udevice *dev, char *buf, int size);
>>
>> /**
>> - * get_last() - get information on the last reset
>> + * @get_last: get information on the last reset
>> *
>> * @dev: Device to check
>> - * @return last reset state (enum sysreset_t) or -ve error
>> + * Return: last reset state (enum :enum:`sysreset_t`) or -ve error
>> */
>> int (*get_last)(struct udevice *dev);
>> };
>> @@ -55,8 +67,9 @@ struct sysreset_ops {
>> /**
>> * sysreset_request() - request a sysreset
>> *
>> + * @dev: Device to be used for system reset
>> * @type: Reset type to request
>> - * @return 0 if OK, -EPROTONOSUPPORT if not supported by this device
>> + * Return: 0 if OK, -EPROTONOSUPPORT if not supported by this device
>> */
>> int sysreset_request(struct udevice *dev, enum sysreset_t type);
>>
>> @@ -66,7 +79,7 @@ int sysreset_request(struct udevice *dev, enum sysreset_t type);
>> * @dev: Device to check
>> * @buf: Buffer to receive the textual reset information
>> * @size: Size of the passed buffer
>> - * @return 0 if OK, -ve on error
>> + * Return: 0 if OK, -ve on error
>> */
>> int sysreset_get_status(struct udevice *dev, char *buf, int size);
>>
>> @@ -74,7 +87,7 @@ int sysreset_get_status(struct udevice *dev, char *buf, int size);
>> * sysreset_get_last() - get information on the last reset
>> *
>> * @dev: Device to check
>> - * @return last reset state (enum sysreset_t) or -ve error
>> + * Return: last reset state (enum sysreset_t) or -ve error
>> */
>> int sysreset_get_last(struct udevice *dev);
>>
>> @@ -88,7 +101,7 @@ int sysreset_get_last(struct udevice *dev);
>> * If this function fails to reset, it will display a message and halt
>> *
>> * @type: Reset type to request
>> - * @return -EINPROGRESS if a reset is in progress, -ENOSYS if not available
>> + * Return: -EINPROGRESS if a reset is in progress, -ENOSYS if not available
>> */
>> int sysreset_walk(enum sysreset_t type);
>>
>> @@ -101,7 +114,7 @@ int sysreset_walk(enum sysreset_t type);
>> *
>> * If no device prives the information, this function returns -ENOENT
>> *
>> - * @return last reset state (enum sysreset_t) or -ve error
>> + * Return: last reset state (enum sysreset_t) or -ve error
>> */
>> int sysreset_get_last_walk(void);
>>
>> @@ -110,6 +123,8 @@ int sysreset_get_last_walk(void);
>> *
>> * This calls sysreset_walk(). If it returns, indicating that reset is not
>> * supported, it prints a message and halts.
>> + *
>> + * @type: Reset type to request
>> */
>> void sysreset_walk_halt(enum sysreset_t type);
>>
>> --
>> 2.32.0
>>
More information about the U-Boot
mailing list