mirror of
https://github.com/Fishwaldo/u-boot.git
synced 2025-03-17 12:41:32 +00:00
doc: add include/dm/uclass.h to the HTML documentation
Correct Sphinx style comments in include/dm/uclass.h and add the driver model UCLASS API to the HTML documentation. Signed-off-by: Patrick Delaunay <patrick.delaunay@foss.st.com> Reviewed-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
This commit is contained in:
Patrick Delaunay
Heinrich Schuchardt
parent
8804b276a7
commit
797b2a2ed4
3 changed files with 52 additions and 41 deletions
9
doc/api/dm.rst
Normal file
9
doc/api/dm.rst
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
.. SPDX-License-Identifier: GPL-2.0+
|
||||
|
||||
Driver Model
|
||||
============
|
||||
|
||||
Uclass and Driver
|
||||
-----------------
|
||||
|
||||
.. kernel-doc:: include/dm/uclass.h
|
||||
|
|
@ -7,6 +7,7 @@ U-Boot API documentation
|
|||
:maxdepth: 2
|
||||
|
||||
dfu
|
||||
dm
|
||||
efi
|
||||
getopt
|
||||
linker_lists
|
||||
|
|
|
|||
|
|
@ -84,7 +84,7 @@ struct udevice;
|
|||
* its children. If non-zero this is the size of this data, to be allocated
|
||||
* in the child device's parent_plat pointer. This value is only used as
|
||||
* a fallback if this member is 0 in the driver.
|
||||
* @flags: Flags for this uclass (DM_UC_...)
|
||||
* @flags: Flags for this uclass ``(DM_UC_...)``
|
||||
*/
|
||||
struct uclass_driver {
|
||||
const char *name;
|
||||
|
|
@ -127,17 +127,16 @@ struct uclass_driver {
|
|||
* build time. Before this is used, an extern UCLASS_DRIVER() must have been
|
||||
* declared.
|
||||
*
|
||||
* For example:
|
||||
* For example::
|
||||
*
|
||||
* extern UCLASS_DRIVER(clk);
|
||||
*
|
||||
* struct uclass_driver *drvs[] = {
|
||||
* DM_UCLASS_DRIVER_REF(clk),
|
||||
* };
|
||||
* extern UCLASS_DRIVER(clk);
|
||||
* struct uclass_driver *drvs[] = {
|
||||
* DM_UCLASS_DRIVER_REF(clk),
|
||||
* };
|
||||
*
|
||||
* @_name: Name of the uclass_driver. This must be a valid C identifier, used by
|
||||
* the linker_list.
|
||||
* @returns struct uclass_driver * for the uclass driver
|
||||
* Return: struct uclass_driver * for the uclass driver
|
||||
*/
|
||||
#define DM_UCLASS_DRIVER_REF(_name) \
|
||||
ll_entry_ref(struct uclass_driver, _name, uclass_driver)
|
||||
|
|
@ -145,8 +144,8 @@ struct uclass_driver {
|
|||
/**
|
||||
* uclass_get_priv() - Get the private data for a uclass
|
||||
*
|
||||
* @uc Uclass to check
|
||||
* @return private data, or NULL if none
|
||||
* @uc: Uclass to check
|
||||
* Return: private data, or NULL if none
|
||||
*/
|
||||
void *uclass_get_priv(const struct uclass *uc);
|
||||
|
||||
|
|
@ -159,8 +158,9 @@ void *uclass_get_priv(const struct uclass *uc);
|
|||
*
|
||||
* @key: ID to look up
|
||||
* @ucp: Returns pointer to uclass (there is only one per ID)
|
||||
* @return 0 if OK, -EDEADLK if driver model is not yet inited, other -ve on
|
||||
* other error
|
||||
* Return:
|
||||
* 0 if OK, -EDEADLK if driver model is not yet inited,
|
||||
* other -ve on other error
|
||||
*/
|
||||
int uclass_get(enum uclass_id key, struct uclass **ucp);
|
||||
|
||||
|
|
@ -168,16 +168,16 @@ int uclass_get(enum uclass_id key, struct uclass **ucp);
|
|||
* uclass_get_name() - Get the name of a uclass driver
|
||||
*
|
||||
* @id: ID to look up
|
||||
* @returns the name of the uclass driver for that ID, or NULL if none
|
||||
* Return: the name of the uclass driver for that ID, or NULL if none
|
||||
*/
|
||||
const char *uclass_get_name(enum uclass_id id);
|
||||
|
||||
/**
|
||||
* uclass_get_by_name() - Look up a uclass by its driver name
|
||||
* uclass_get_by_name_len() - Look up a uclass by its partial driver name
|
||||
*
|
||||
* @name: Name to look up
|
||||
* @len: Length of name
|
||||
* @returns the associated uclass ID, or UCLASS_INVALID if not found
|
||||
* @len: Length of the partial name
|
||||
* Return: the associated uclass ID, or UCLASS_INVALID if not found
|
||||
*/
|
||||
enum uclass_id uclass_get_by_name_len(const char *name, int len);
|
||||
|
||||
|
|
@ -185,7 +185,7 @@ enum uclass_id uclass_get_by_name_len(const char *name, int len);
|
|||
* uclass_get_by_name() - Look up a uclass by its driver name
|
||||
*
|
||||
* @name: Name to look up
|
||||
* @returns the associated uclass ID, or UCLASS_INVALID if not found
|
||||
* Return: the associated uclass ID, or UCLASS_INVALID if not found
|
||||
*/
|
||||
enum uclass_id uclass_get_by_name(const char *name);
|
||||
|
||||
|
|
@ -197,7 +197,7 @@ enum uclass_id uclass_get_by_name(const char *name);
|
|||
* @id: ID to look up
|
||||
* @index: Device number within that uclass (0=first)
|
||||
* @devp: Returns pointer to device (there is only one per for each ID)
|
||||
* @return 0 if OK, -ve on error
|
||||
* Return: 0 if OK, -ve on error
|
||||
*/
|
||||
int uclass_get_device(enum uclass_id id, int index, struct udevice **devp);
|
||||
|
||||
|
|
@ -211,7 +211,7 @@ int uclass_get_device(enum uclass_id id, int index, struct udevice **devp);
|
|||
* @id: ID to look up
|
||||
* @name: name of a device to get
|
||||
* @devp: Returns pointer to device (the first one with the name)
|
||||
* @return 0 if OK, -ve on error
|
||||
* Return: 0 if OK, -ve on error
|
||||
*/
|
||||
int uclass_get_device_by_name(enum uclass_id id, const char *name,
|
||||
struct udevice **devp);
|
||||
|
|
@ -228,7 +228,7 @@ int uclass_get_device_by_name(enum uclass_id id, const char *name,
|
|||
* @id: ID to look up
|
||||
* @seq: Sequence number to find (0=first)
|
||||
* @devp: Returns pointer to device (there is only one for each seq)
|
||||
* @return 0 if OK, -ve on error
|
||||
* Return: 0 if OK, -ve on error
|
||||
*/
|
||||
int uclass_get_device_by_seq(enum uclass_id id, int seq, struct udevice **devp);
|
||||
|
||||
|
|
@ -243,7 +243,7 @@ int uclass_get_device_by_seq(enum uclass_id id, int seq, struct udevice **devp);
|
|||
* @id: ID to look up
|
||||
* @node: Device tree offset to search for (if -ve then -ENODEV is returned)
|
||||
* @devp: Returns pointer to device (there is only one for each node)
|
||||
* @return 0 if OK, -ve on error
|
||||
* Return: 0 if OK, -ve on error
|
||||
*/
|
||||
int uclass_get_device_by_of_offset(enum uclass_id id, int node,
|
||||
struct udevice **devp);
|
||||
|
|
@ -257,9 +257,9 @@ int uclass_get_device_by_of_offset(enum uclass_id id, int node,
|
|||
* The device is probed to activate it ready for use.
|
||||
*
|
||||
* @id: ID to look up
|
||||
* @np: Device tree node to search for (if NULL then -ENODEV is returned)
|
||||
* @node: Device tree node to search for (if NULL then -ENODEV is returned)
|
||||
* @devp: Returns pointer to device (there is only one for each node)
|
||||
* @return 0 if OK, -ve on error
|
||||
* Return: 0 if OK, -ve on error
|
||||
*/
|
||||
int uclass_get_device_by_ofnode(enum uclass_id id, ofnode node,
|
||||
struct udevice **devp);
|
||||
|
|
@ -271,12 +271,13 @@ int uclass_get_device_by_ofnode(enum uclass_id id, ofnode node,
|
|||
*
|
||||
* The device is probed to activate it ready for use.
|
||||
*
|
||||
* @id: uclass ID to look up
|
||||
* @id: uclass ID to look up
|
||||
* @phandle_id: the phandle id to look up
|
||||
* @devp: Returns pointer to device (there is only one for each node). NULL if
|
||||
* there is no such device.
|
||||
* @return 0 if OK, -ENODEV if there is no device match the phandle, other
|
||||
* -ve on error
|
||||
* @devp: Returns pointer to device (there is only one for each node).
|
||||
* NULL if there is no such device.
|
||||
* Return:
|
||||
* 0 if OK, -ENODEV if there is no device match the phandle,
|
||||
* other -ve on error
|
||||
*/
|
||||
int uclass_get_device_by_phandle_id(enum uclass_id id, uint phandle_id,
|
||||
struct udevice **devp);
|
||||
|
|
@ -292,8 +293,8 @@ int uclass_get_device_by_phandle_id(enum uclass_id id, uint phandle_id,
|
|||
* @parent: Parent device containing the phandle pointer
|
||||
* @name: Name of property in the parent device node
|
||||
* @devp: Returns pointer to device (there is only one for each node)
|
||||
* @return 0 if OK, -ENOENT if there is no @name present in the node, other
|
||||
* -ve on error
|
||||
* Return: 0 if OK, -ENOENT if there is no @name present in the node, other
|
||||
* -ve on error
|
||||
*/
|
||||
int uclass_get_device_by_phandle(enum uclass_id id, struct udevice *parent,
|
||||
const char *name, struct udevice **devp);
|
||||
|
|
@ -310,7 +311,7 @@ int uclass_get_device_by_phandle(enum uclass_id id, struct udevice *parent,
|
|||
* @id: ID to look up
|
||||
* @drv: Driver to look for
|
||||
* @devp: Returns pointer to the first device with that driver
|
||||
* @return 0 if OK, -ve on error
|
||||
* Return: 0 if OK, -ve on error
|
||||
*/
|
||||
int uclass_get_device_by_driver(enum uclass_id id, const struct driver *drv,
|
||||
struct udevice **devp);
|
||||
|
|
@ -327,7 +328,7 @@ int uclass_get_device_by_driver(enum uclass_id id, const struct driver *drv,
|
|||
* @devp: Returns pointer to the first device in that uclass if no error
|
||||
* occurred, or NULL if there is no first device, or an error occurred with
|
||||
* that device.
|
||||
* @return 0 if OK (found or not found), other -ve on error
|
||||
* Return: 0 if OK (found or not found), other -ve on error
|
||||
*/
|
||||
int uclass_first_device(enum uclass_id id, struct udevice **devp);
|
||||
|
||||
|
|
@ -338,7 +339,7 @@ int uclass_first_device(enum uclass_id id, struct udevice **devp);
|
|||
*
|
||||
* @id: Uclass ID to look up
|
||||
* @devp: Returns pointer to the first device in that uclass, or NULL if none
|
||||
* @return 0 if found, -ENODEV if not found, other -ve on error
|
||||
* Return: 0 if found, -ENODEV if not found, other -ve on error
|
||||
*/
|
||||
int uclass_first_device_err(enum uclass_id id, struct udevice **devp);
|
||||
|
||||
|
|
@ -353,7 +354,7 @@ int uclass_first_device_err(enum uclass_id id, struct udevice **devp);
|
|||
* @devp: On entry, pointer to device to lookup. On exit, returns pointer
|
||||
* to the next device in the uclass if no error occurred, or NULL if there is
|
||||
* no next device, or an error occurred with that next device.
|
||||
* @return 0 if OK (found or not found), other -ve on error
|
||||
* Return: 0 if OK (found or not found), other -ve on error
|
||||
*/
|
||||
int uclass_next_device(struct udevice **devp);
|
||||
|
||||
|
|
@ -365,7 +366,7 @@ int uclass_next_device(struct udevice **devp);
|
|||
* @devp: On entry, pointer to device to lookup. On exit, returns pointer
|
||||
* to the next device in the uclass if no error occurred, or NULL if
|
||||
* there is no next device.
|
||||
* @return 0 if found, -ENODEV if not found, other -ve on error
|
||||
* Return: 0 if found, -ENODEV if not found, other -ve on error
|
||||
*/
|
||||
int uclass_next_device_err(struct udevice **devp);
|
||||
|
||||
|
|
@ -380,7 +381,7 @@ int uclass_next_device_err(struct udevice **devp);
|
|||
* @id: Uclass ID to look up
|
||||
* @devp: Returns pointer to the first device in that uclass, or NULL if there
|
||||
* is no first device
|
||||
* @return 0 if OK (found or not found), other -ve on error. If an error occurs
|
||||
* Return: 0 if OK (found or not found), other -ve on error. If an error occurs
|
||||
* it is still possible to move to the next device.
|
||||
*/
|
||||
int uclass_first_device_check(enum uclass_id id, struct udevice **devp);
|
||||
|
|
@ -395,7 +396,7 @@ int uclass_first_device_check(enum uclass_id id, struct udevice **devp);
|
|||
*
|
||||
* @devp: On entry, pointer to device to lookup. On exit, returns pointer
|
||||
* to the next device in the uclass if any
|
||||
* @return 0 if OK (found or not found), other -ve on error. If an error occurs
|
||||
* Return: 0 if OK (found or not found), other -ve on error. If an error occurs
|
||||
* it is still possible to move to the next device.
|
||||
*/
|
||||
int uclass_next_device_check(struct udevice **devp);
|
||||
|
|
@ -409,7 +410,7 @@ int uclass_next_device_check(struct udevice **devp);
|
|||
* @id: Uclass ID to check
|
||||
* @driver_data: Driver data to search for
|
||||
* @devp: Returns pointer to the first matching device in that uclass, if found
|
||||
* @return 0 if found, -ENODEV if not found, other -ve on error
|
||||
* Return: 0 if found, -ENODEV if not found, other -ve on error
|
||||
*/
|
||||
int uclass_first_device_drvdata(enum uclass_id id, ulong driver_data,
|
||||
struct udevice **devp);
|
||||
|
|
@ -421,7 +422,7 @@ int uclass_first_device_drvdata(enum uclass_id id, ulong driver_data,
|
|||
* looking for its ID.
|
||||
*
|
||||
* @id: uclass ID to look up
|
||||
* @return 0 if OK, other -ve on error
|
||||
* Return: 0 if OK, other -ve on error
|
||||
*/
|
||||
int uclass_probe_all(enum uclass_id id);
|
||||
|
||||
|
|
@ -429,7 +430,7 @@ int uclass_probe_all(enum uclass_id id);
|
|||
* uclass_id_count() - Count the number of devices in a uclass
|
||||
*
|
||||
* @id: uclass ID to look up
|
||||
* @return number of devices in that uclass (0 if none)
|
||||
* Return: number of devices in that uclass (0 if none)
|
||||
*/
|
||||
int uclass_id_count(enum uclass_id id);
|
||||
|
||||
|
|
@ -444,7 +445,7 @@ int uclass_id_count(enum uclass_id id);
|
|||
* @id: enum uclass_id ID to use
|
||||
* @pos: struct udevice * to hold the current device. Set to NULL when there
|
||||
* are no more devices.
|
||||
* @uc: temporary uclass variable (struct uclass *)
|
||||
* @uc: temporary uclass variable (``struct uclass *``)
|
||||
*/
|
||||
#define uclass_id_foreach_dev(id, pos, uc) \
|
||||
if (!uclass_get(id, &uc)) \
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue