From 797b2a2ed4a0d34ea521e6ee07a31bdb5bd8c14a Mon Sep 17 00:00:00 2001 From: Patrick Delaunay Date: Wed, 12 Jan 2022 10:53:42 +0100 Subject: [PATCH] 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 Reviewed-by: Heinrich Schuchardt --- doc/api/dm.rst | 9 +++++ doc/api/index.rst | 1 + include/dm/uclass.h | 83 +++++++++++++++++++++++---------------------- 3 files changed, 52 insertions(+), 41 deletions(-) create mode 100644 doc/api/dm.rst diff --git a/doc/api/dm.rst b/doc/api/dm.rst new file mode 100644 index 0000000000..edce25da51 --- /dev/null +++ b/doc/api/dm.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Driver Model +============ + +Uclass and Driver +----------------- + +.. kernel-doc:: include/dm/uclass.h diff --git a/doc/api/index.rst b/doc/api/index.rst index 806c7385a6..3f36174167 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -7,6 +7,7 @@ U-Boot API documentation :maxdepth: 2 dfu + dm efi getopt linker_lists diff --git a/include/dm/uclass.h b/include/dm/uclass.h index f1fd2ba246..7f33c34214 100644 --- a/include/dm/uclass.h +++ b/include/dm/uclass.h @@ -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)) \ -- 2.39.5