| Message ID | 20210923091247.14191-1-heinrich.schuchardt@canonical.com |
|---|---|
| State | Accepted, archived |
| Delegated to: | Heinrich Schuchardt |
| Headers | show |
| Series | [1/1] doc: add system reset to API documentation | expand |
On Thu, 23 Sept 2021 at 03:12, Heinrich Schuchardt <heinrich.schuchardt@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@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 Reviewed-by: Simon Glass <sjg@chromium.org>
On Thu, Sep 23, 2021 at 11:12 AM Heinrich Schuchardt <heinrich.schuchardt@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@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. Thanks, Alex > + * -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 >
On 9/24/21 1:27 AM, Alexandre Ghiti wrote: > On Thu, Sep 23, 2021 at 11:12 AM Heinrich Schuchardt > <heinrich.schuchardt@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@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 >>
On 9/24/21 7:51 AM, Sean Anderson wrote: > On 9/24/21 1:27 AM, Alexandre Ghiti wrote: >> On Thu, Sep 23, 2021 at 11:12 AM Heinrich Schuchardt >> <heinrich.schuchardt@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@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]. We should stick with [1]. If the formatting is not correct, it is a problem with the Sphinx C-domain. We inherited doc/sphinx/parse-headers.pl from Linux. I guess this is the code which needs to be fixed. Best regards Heinrich > > --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 >>> >
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: + * -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);
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@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