doc: add system reset to API documentation

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>

diff --git a/doc/api/index.rst b/doc/api/index.rst
index ea02aa571578dd8751e638dce303a172be312e7b..281d1dca96cc213160dfdffdcaa5acf2083414c4 100644 (file)
--- 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 (file)
index 0000000..a51b06c
--- /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 701e4f5c86e42d78ae0193389100461b77f7f936..9d4ed87ceafbf41b8636a97f061ea770a597c921 100644 (file)
--- a/include/sysreset.h
+++ b/include/sysreset.h
@@ -9,43 +9,55 @@
 
 struct udevice;
 
+/**
+ * enum sysreset_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);