Difuse/u-boot
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

doc: add system reset to API documentation

Browse source 
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>
This commit is contained in:
Heinrich Schuchardt 2021-09-23 11:06:16 +02:00 committed by Heinrich Schuchardt
parent 87a4fc1081
commit 1da0b6ab2a
3 changed files with 42 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
doc/api/index.rst
View file

@ -15,5 +15,6 @@ U-Boot API documentation
rng
sandbox
serial
sysreset
timer
unicode

7
doc/api/sysreset.rst Normal file
View file

@ -0,0 +1,7 @@
.. SPDX-License-Identifier: GPL-2.0+
System reset
============
.. kernel-doc:: include/sysreset.h
:internal:

53
include/sysreset.h
View file

@ -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);