Re: [PATCH 5/9] doc: add include/dm/device.h to the HTML documentation
On 1/12/22 10:53, Patrick Delaunay wrote: Correct Sphinx style comments in include/dm/device.h and add the driver model device API to the HTML documentation. Signed-off-by: Patrick Delaunay --- doc/api/dm.rst | 5 ++ include/dm/device.h | 209 2 files changed, 121 insertions(+), 93 deletions(-) diff --git a/doc/api/dm.rst b/doc/api/dm.rst index 6f72b0b620..7a77a91c1f 100644 --- a/doc/api/dm.rst +++ b/doc/api/dm.rst @@ -10,3 +10,8 @@ Uclass and Driver .. kernel-doc:: include/dm/root.h .. kernel-doc:: include/dm/lists.h .. kernel-doc:: include/dm/platdata.h + +Device +-- + +.. kernel-doc:: include/dm/device.h diff --git a/include/dm/device.h b/include/dm/device.h index cf785f7ae2..bc8da72b50 100644 --- a/include/dm/device.h +++ b/include/dm/device.h @@ -145,7 +145,7 @@ enum { * @uclass_node: Used by uclass to link its devices * @child_head: List of children of this device * @sibling_node: Next device in list of all devices - * @flags_: Flags for this device DM_FLAG_... (do not access outside driver + * @flags_: Flags for this device `DM_FLAG_...` (do not access outside driver *model) * @seq_: Allocated sequence number for this device (-1 = none). This is set up * when the device is bound and is unique within the device's uclass. If the @@ -193,14 +193,14 @@ struct udevice { }; /** - * udevice_rt - runtime information set up by U-Boot + * struct udevice_rt - runtime information set up by U-Boot * * This is only used with OF_PLATDATA_RT * * There is one of these for every udevice in the linker list, indexed by * the udevice_info idx value. * - * @flags_: Flags for this device DM_FLAG_... (do not access outside driver + * @flags_: Flags for this device `DM_FLAG_...` (do not access outside driver *model) */ struct udevice_rt { @@ -239,7 +239,7 @@ static inline void dev_bic_flags(struct udevice *dev, u32 bic) * dev_ofnode() - get the DT node reference associated with a udevice * * @dev: device to check - * @return reference of the the device's DT node + * Return: reference of the device's DT node */ static inline ofnode dev_ofnode(const struct udevice *dev) { @@ -351,7 +351,7 @@ struct udevice_id { * @ops: Driver-specific operations. This is typically a list of function * pointers defined by the driver, to implement driver functions required by * the uclass. - * @flags: driver flags - see DM_FLAGS_... + * @flags: driver flags - see `DM_FLAGS_...` * @acpi_ops: Advanced Configuration and Power Interface (ACPI) operations, * allowing the device to add things to the ACPI tables passed to Linux */ @@ -378,11 +378,24 @@ struct driver { #endif }; -/* Declare a new U-Boot driver */ +/** + * U_BOOT_DRIVER() - Declare a new U-Boot driver + * @__name: name of the driver + */ #define U_BOOT_DRIVER(__name) \ ll_entry_declare(struct driver, __name, driver) -/* Get a pointer to a given driver */ +/** + * DM_DRIVER_GET() - Get a pointer to a given driver + * + * This is useful in code for referencing a driver at build time. + * Before this is used, an extern U_BOOT_DRIVER() must have been + * declared. + * + * @__name:Name of the driver. This must be a valid C identifier, + * used by the linker_list + * Return: struct driver * for the driver + */ #define DM_DRIVER_GET(__name) \ ll_entry_get(struct driver, __name, driver) @@ -392,60 +405,69 @@ struct driver { * This is useful in data structures and code for referencing a driver at * build time. Before this is used, an extern U_BOOT_DRIVER() must have been * declared. + * This is like DM_DRIVER_GET, but without the extra code, so it is suitable + * for putting into data structures. * - * For example: - * - * extern U_BOOT_DRIVER(sandbox_fixed_clock); + * For example: :: * - * struct driver *drvs[] = { - * DM_DRIVER_REF(sandbox_fixed_clock), - * }; + * extern U_BOOT_DRIVER(sandbox_fixed_clock); + * struct driver *drvs[] = { + * DM_DRIVER_REF(sandbox_fixed_clock), + * }; * - * @_name: Name of the driver. This must be a valid C identifier, used by the - * linker_list - * @returns struct driver * for the driver + * @_name: Name of the driver. This must be a valid C identifier, + * used by the linker_list + * Return: struct driver * for the driver */ #define DM_DRIVER_REF(_name) \ ll_entry_ref(struct driver, _name, driver) /** - * Declare a macro to state a alias for a driver name. This macro will nits: %s/a alias/an alias/ - * produce no code but its information will be parsed by tools like - * dtoc + * DM_DRIVER_ALIAS() - Declare a macro to state a alias for a driver name + * + * This macro will produce no code but its information will be parsed by tools + * like dtoc + * + * @__name:name of driver + *
[PATCH 5/9] doc: add include/dm/device.h to the HTML documentation
Correct Sphinx style comments in include/dm/device.h and add the driver model device API to the HTML documentation. Signed-off-by: Patrick Delaunay --- doc/api/dm.rst | 5 ++ include/dm/device.h | 209 2 files changed, 121 insertions(+), 93 deletions(-) diff --git a/doc/api/dm.rst b/doc/api/dm.rst index 6f72b0b620..7a77a91c1f 100644 --- a/doc/api/dm.rst +++ b/doc/api/dm.rst @@ -10,3 +10,8 @@ Uclass and Driver .. kernel-doc:: include/dm/root.h .. kernel-doc:: include/dm/lists.h .. kernel-doc:: include/dm/platdata.h + +Device +-- + +.. kernel-doc:: include/dm/device.h diff --git a/include/dm/device.h b/include/dm/device.h index cf785f7ae2..bc8da72b50 100644 --- a/include/dm/device.h +++ b/include/dm/device.h @@ -145,7 +145,7 @@ enum { * @uclass_node: Used by uclass to link its devices * @child_head: List of children of this device * @sibling_node: Next device in list of all devices - * @flags_: Flags for this device DM_FLAG_... (do not access outside driver + * @flags_: Flags for this device `DM_FLAG_...` (do not access outside driver * model) * @seq_: Allocated sequence number for this device (-1 = none). This is set up * when the device is bound and is unique within the device's uclass. If the @@ -193,14 +193,14 @@ struct udevice { }; /** - * udevice_rt - runtime information set up by U-Boot + * struct udevice_rt - runtime information set up by U-Boot * * This is only used with OF_PLATDATA_RT * * There is one of these for every udevice in the linker list, indexed by * the udevice_info idx value. * - * @flags_: Flags for this device DM_FLAG_... (do not access outside driver + * @flags_: Flags for this device `DM_FLAG_...` (do not access outside driver * model) */ struct udevice_rt { @@ -239,7 +239,7 @@ static inline void dev_bic_flags(struct udevice *dev, u32 bic) * dev_ofnode() - get the DT node reference associated with a udevice * * @dev: device to check - * @return reference of the the device's DT node + * Return: reference of the device's DT node */ static inline ofnode dev_ofnode(const struct udevice *dev) { @@ -351,7 +351,7 @@ struct udevice_id { * @ops: Driver-specific operations. This is typically a list of function * pointers defined by the driver, to implement driver functions required by * the uclass. - * @flags: driver flags - see DM_FLAGS_... + * @flags: driver flags - see `DM_FLAGS_...` * @acpi_ops: Advanced Configuration and Power Interface (ACPI) operations, * allowing the device to add things to the ACPI tables passed to Linux */ @@ -378,11 +378,24 @@ struct driver { #endif }; -/* Declare a new U-Boot driver */ +/** + * U_BOOT_DRIVER() - Declare a new U-Boot driver + * @__name: name of the driver + */ #define U_BOOT_DRIVER(__name) \ ll_entry_declare(struct driver, __name, driver) -/* Get a pointer to a given driver */ +/** + * DM_DRIVER_GET() - Get a pointer to a given driver + * + * This is useful in code for referencing a driver at build time. + * Before this is used, an extern U_BOOT_DRIVER() must have been + * declared. + * + * @__name:Name of the driver. This must be a valid C identifier, + * used by the linker_list + * Return: struct driver * for the driver + */ #define DM_DRIVER_GET(__name) \ ll_entry_get(struct driver, __name, driver) @@ -392,60 +405,69 @@ struct driver { * This is useful in data structures and code for referencing a driver at * build time. Before this is used, an extern U_BOOT_DRIVER() must have been * declared. + * This is like DM_DRIVER_GET, but without the extra code, so it is suitable + * for putting into data structures. * - * For example: - * - * extern U_BOOT_DRIVER(sandbox_fixed_clock); + * For example: :: * - * struct driver *drvs[] = { - * DM_DRIVER_REF(sandbox_fixed_clock), - * }; + * extern U_BOOT_DRIVER(sandbox_fixed_clock); + * struct driver *drvs[] = { + * DM_DRIVER_REF(sandbox_fixed_clock), + * }; * - * @_name: Name of the driver. This must be a valid C identifier, used by the - * linker_list - * @returns struct driver * for the driver + * @_name: Name of the driver. This must be a valid C identifier, + * used by the linker_list + * Return: struct driver * for the driver */ #define DM_DRIVER_REF(_name) \ ll_entry_ref(struct driver, _name, driver) /** - * Declare a macro to state a alias for a driver name. This macro will - * produce no code but its information will be parsed by tools like - * dtoc + * DM_DRIVER_ALIAS() - Declare a macro to state a alias for a driver name + * + * This macro will produce no code but its information will be parsed by tools + * like dtoc + * + * @__name:name of driver + * @__alias: alias for the driver name */ #define DM_DRIVER_ALIAS(__name, __alias) /** - * Declare a macro to