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