[PATCH 0/2] KernelDoc:Move the driver model structure to the kerneldoc

[PATCH 0/2] KernelDoc:Move the driver model structure to the kerneldoc

[wanlong.gao]

From: Wanlong Gao <wanlong.gao@gmail.com>


Hi Greg:

I think I did the right work as you said .

1/2:Add the structures to the kerneldoc by add the comments to the device.h
2/2:Remove the structures from the driver-model docs.

Did I?

Thanks

Best regards

Wanlong Gao

[PATCH 1/2] KernelDoc:Add the device driver-model structures to kerneldoc

[wanlong.gao]

From: Wanlong Gao <wanlong.gao@gmail.com>

Add the comment the structure bus_type, device_driver, device,
class for generating the driver-model kerneldoc.

Signed-off-by: Wanlong Gao <wanlong.gao@gmail.com>
---
 Documentation/DocBook/device-drivers.tmpl |    6 +-
 include/linux/device.h                    |  104 ++++++++++++++++++++++++++++-
 2 files changed, 104 insertions(+), 6 deletions(-)

diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
index 36f63d4..5e482e0 100644
--- a/Documentation/DocBook/device-drivers.tmpl
+++ b/Documentation/DocBook/device-drivers.tmpl
@@ -96,10 +96,10 @@ X!Iinclude/linux/kobject.h
 
   <chapter id="devdrivers">
      <title>Device drivers infrastructure</title>
+     <sect1><title>The Basic Device Driver-Model Structure </title>
+!Iinclude/linux/device.h
+     </sect1>
      <sect1><title>Device Drivers Base</title>
-<!--
-X!Iinclude/linux/device.h
--->
 !Edrivers/base/driver.c
 !Edrivers/base/core.c
 !Edrivers/base/class.c
diff --git a/include/linux/device.h b/include/linux/device.h
index ab8dfc0..5258d5d 100644
--- a/include/linux/device.h
+++ b/include/linux/device.h
@@ -47,6 +47,23 @@ extern int __must_check bus_create_file(struct bus_type *,
 					struct bus_attribute *);
 extern void bus_remove_file(struct bus_type *, struct bus_attribute *);
 
+/**
+ * struct bus_type - The bus type of the device .
+ *
+ * @name:	The name of the bus
+ * @bus_attrs:	The attributes of the bus
+ * @dev_attrs:	The default attributes of the devices on the bus
+ * @drv_attrs:	The default attributes of the device drivers on the bus
+ * @match:	Attaching drivers to devices
+ * @uevent:	Add the environment variable for device plug
+ * @probe:	Probe the device
+ * @remove:	Remove the device
+ * @shutdown:	Shutdown method
+ * @suspend:	Suspend method
+ * @resume:	Resume method
+ * @pm:		Device power management operations
+ * @p:		The private data the subsystem
+ */ 
 struct bus_type {
 	const char		*name;
 	struct bus_attribute	*bus_attrs;
@@ -119,6 +136,23 @@ extern int bus_unregister_notifier(struct bus_type *bus,
 extern struct kset *bus_get_kset(struct bus_type *bus);
 extern struct klist *bus_get_device_klist(struct bus_type *bus);
 
+/**
+ * struct device_driver - The basic device driver structure
+ * @name:	Name of the device driver
+ * @bus:	The bus the device driver belongs to
+ * @owner:	The driver's owner
+ * @mod_name:	Used for built-in modules
+ * @suppress_bind_attrs:Disables bind/unbind via sysfs
+ * @of_match_table:Id table for matching the driver to device
+ * @probe:	Called to bound a driver to the device
+ * @remove:	Called to unbind a driver from a device
+ * @shutdown:	Called when shutdown
+ * @suspend:	Called to put the device in a low power state
+ * @resume:	Used to bring a device from a low power state
+ * @groups:	Driver's attribute groups
+ * @pm:		Device's power management operations
+ * @p:		Driver's private data
+ */
 struct device_driver {
 	const char		*name;
 	struct bus_type		*bus;
@@ -185,8 +219,24 @@ struct device *driver_find_device(struct device_driver *drv,
 				  struct device *start, void *data,
 				  int (*match)(struct device *dev, void *data));
 
-/*
- * device classes
+/**
+ * struct class - device classes
+ * @name:	Name of the class
+ * @owner:	Class' owner
+ * @class_attrs:The attributes of the class
+ * @dev_attrs:	The default attributes of the device belongs to the class
+ * @dev_bin_attrs:The default binary attributes of the device belongs to the class
+ * @dev_kobj:	Kobject of the class
+ * @dev_uevent:	Used to plug
+ * @devnode:	Callback to provide the devtmpfs
+ * @class_release:Called to release the class
+ * @dev_release:Called to release the device
+ * @suspend:	Used to put the device to a low power state
+ * @resume:	Used to bring the device from a low power state
+ * @ns_type:	Callbacks so sysfs can detemine namespaces
+ * @namespace:	Namespace of the device
+ * @pm:		The default device power management operations
+ * @p:		The private data of the subsystem
  */
 struct class {
 	const char		*name;
@@ -401,6 +451,54 @@ struct device_dma_parameters {
 	unsigned long segment_boundary_mask;
 };
 
+/**
+ * struct device - The basic device structure.
+ * @parent:	Parent of the device.
+ * @p:		Hold the private to the driver core portions of the device.
+ * 		See the comment of the struct device_private for detail.
+ * @kobj:	A top-level, abstract class from which other classes are derived.
+ * @init_name:	Initial name of the device.
+ * @type:	The type of device.
+ * 		This identifies the device type and carries type-specific
+ * 		information.
+ * @mutex:	Mutex to synchronize calls to its driver.
+ * @bus:	Type of bus device is on.
+ * @driver:	Which driver has allocated this
+ * @platform_data:Platform data specific to the device.
+ * 		Example..For devices on custom boards, as typical of embedded
+ * 		and SOC based hardware, Linux often uses platform_data to point
+ * 		to board-specific structures describing devices and how they
+ * 		are wired.  That can include what ports are available, chip
+ * 		variants, which GPIO pins act in what additional roles, and so
+ * 		on.  This shrinks the "Board Support Packages" (BSPs) and
+ * 		minimizes board-specific #ifdefs in drivers.
+ * @power:	For device power management.
+ * 		See the Documentation/power/devices.txt for details.
+ * @pwr_domain:	Provide callbacks that are executed during system suspend,
+ * 		hibernation, system resume and during runtime PM transitions 
+ * 		along with subsystem-level and driver-level callbacks.
+ * @numa_node:	NUMA node this device is close to.
+ * @dma_mask:	Dma mask (if dma'ble device).
+ * @coherent_dma_mask:Like dma_mask, but for alloc_coherent mapping as not all
+ * 		hardware supports 64 bit addresses for consistent allocations
+ * 		such description.
+ * @dma_parms:	A low level driver may set these to teach IOMMU code about
+ * 		segment limitations.
+ * @dma_pools:	Dma pools (if dma'ble device) .
+ * @dma_mem:	Internal for coherent mem override.
+ * @archdata:	For arch specific additions.
+ * @of_node:	Associated device tree node.
+ * @of_match:	Matching of_device_id from driver.
+ * @devt:	For creating the sysfs "dev".
+ * @devres_lock:Spinlock to protect the resource of the device.
+ * @devres_head:The resources list of the device.
+ * @knode_class:The node used to add the device to the class list.
+ * @class:	The class of the device.
+ * @groups:	Optional attribute groups.
+ * @release:	Callback to free the device after all references have 
+ * 		gone away. This should be set by the allocator of the 
+ * 		device (i.e. the bus driver that discovered the device).
+ */
 struct device {
 	struct device		*parent;
 
@@ -611,7 +709,7 @@ extern int (*platform_notify)(struct device *dev);
 extern int (*platform_notify_remove)(struct device *dev);
 
 
-/**
+/*
  * get_device - atomically increment the reference count for the device.
  *
  */
-- 
1.7.4.1

Re: [PATCH 1/2] KernelDoc:Add the device driver-model structures to kerneldoc

[Randy Dunlap]

On Mon,  2 May 2011 23:04:40 +0800 wanlong.gao@gmail.com wrote:

> From: Wanlong Gao <wanlong.gao@gmail.com>
> 
> Add the comment the structure bus_type, device_driver, device,
> class for generating the driver-model kerneldoc.

Warning: trailing whitespace in lines 66,478,498,499 of include/linux/device.h

Other than that:

Acked-by: Randy Dunlap <rdunlap@xenotime.net>

Thanks.

Greg, do you want to merge this or should I?


> Signed-off-by: Wanlong Gao <wanlong.gao@gmail.com>
> ---
>  Documentation/DocBook/device-drivers.tmpl |    6 +-
>  include/linux/device.h                    |  104 ++++++++++++++++++++++++++++-
>  2 files changed, 104 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
> index 36f63d4..5e482e0 100644
> --- a/Documentation/DocBook/device-drivers.tmpl
> +++ b/Documentation/DocBook/device-drivers.tmpl
> @@ -96,10 +96,10 @@ X!Iinclude/linux/kobject.h
>  
>    <chapter id="devdrivers">
>       <title>Device drivers infrastructure</title>
> +     <sect1><title>The Basic Device Driver-Model Structure </title>
> +!Iinclude/linux/device.h
> +     </sect1>
>       <sect1><title>Device Drivers Base</title>
> -<!--
> -X!Iinclude/linux/device.h
> --->
>  !Edrivers/base/driver.c
>  !Edrivers/base/core.c
>  !Edrivers/base/class.c
> diff --git a/include/linux/device.h b/include/linux/device.h
> index ab8dfc0..5258d5d 100644
> --- a/include/linux/device.h
> +++ b/include/linux/device.h
> @@ -47,6 +47,23 @@ extern int __must_check bus_create_file(struct bus_type *,
>  					struct bus_attribute *);
>  extern void bus_remove_file(struct bus_type *, struct bus_attribute *);
>  
> +/**
> + * struct bus_type - The bus type of the device .
> + *
> + * @name:	The name of the bus
> + * @bus_attrs:	The attributes of the bus
> + * @dev_attrs:	The default attributes of the devices on the bus
> + * @drv_attrs:	The default attributes of the device drivers on the bus
> + * @match:	Attaching drivers to devices
> + * @uevent:	Add the environment variable for device plug
> + * @probe:	Probe the device
> + * @remove:	Remove the device
> + * @shutdown:	Shutdown method
> + * @suspend:	Suspend method
> + * @resume:	Resume method
> + * @pm:		Device power management operations
> + * @p:		The private data the subsystem
> + */ 
>  struct bus_type {
>  	const char		*name;
>  	struct bus_attribute	*bus_attrs;
> @@ -119,6 +136,23 @@ extern int bus_unregister_notifier(struct bus_type *bus,
>  extern struct kset *bus_get_kset(struct bus_type *bus);
>  extern struct klist *bus_get_device_klist(struct bus_type *bus);
>  
> +/**
> + * struct device_driver - The basic device driver structure
> + * @name:	Name of the device driver
> + * @bus:	The bus the device driver belongs to
> + * @owner:	The driver's owner
> + * @mod_name:	Used for built-in modules
> + * @suppress_bind_attrs:Disables bind/unbind via sysfs
> + * @of_match_table:Id table for matching the driver to device
> + * @probe:	Called to bound a driver to the device
> + * @remove:	Called to unbind a driver from a device
> + * @shutdown:	Called when shutdown
> + * @suspend:	Called to put the device in a low power state
> + * @resume:	Used to bring a device from a low power state
> + * @groups:	Driver's attribute groups
> + * @pm:		Device's power management operations
> + * @p:		Driver's private data
> + */
>  struct device_driver {
>  	const char		*name;
>  	struct bus_type		*bus;
> @@ -185,8 +219,24 @@ struct device *driver_find_device(struct device_driver *drv,
>  				  struct device *start, void *data,
>  				  int (*match)(struct device *dev, void *data));
>  
> -/*
> - * device classes
> +/**
> + * struct class - device classes
> + * @name:	Name of the class
> + * @owner:	Class' owner
> + * @class_attrs:The attributes of the class
> + * @dev_attrs:	The default attributes of the device belongs to the class
> + * @dev_bin_attrs:The default binary attributes of the device belongs to the class
> + * @dev_kobj:	Kobject of the class
> + * @dev_uevent:	Used to plug
> + * @devnode:	Callback to provide the devtmpfs
> + * @class_release:Called to release the class
> + * @dev_release:Called to release the device
> + * @suspend:	Used to put the device to a low power state
> + * @resume:	Used to bring the device from a low power state
> + * @ns_type:	Callbacks so sysfs can detemine namespaces
> + * @namespace:	Namespace of the device
> + * @pm:		The default device power management operations
> + * @p:		The private data of the subsystem
>   */
>  struct class {
>  	const char		*name;
> @@ -401,6 +451,54 @@ struct device_dma_parameters {
>  	unsigned long segment_boundary_mask;
>  };
>  
> +/**
> + * struct device - The basic device structure.
> + * @parent:	Parent of the device.
> + * @p:		Hold the private to the driver core portions of the device.
> + * 		See the comment of the struct device_private for detail.
> + * @kobj:	A top-level, abstract class from which other classes are derived.
> + * @init_name:	Initial name of the device.
> + * @type:	The type of device.
> + * 		This identifies the device type and carries type-specific
> + * 		information.
> + * @mutex:	Mutex to synchronize calls to its driver.
> + * @bus:	Type of bus device is on.
> + * @driver:	Which driver has allocated this
> + * @platform_data:Platform data specific to the device.
> + * 		Example..For devices on custom boards, as typical of embedded
> + * 		and SOC based hardware, Linux often uses platform_data to point
> + * 		to board-specific structures describing devices and how they
> + * 		are wired.  That can include what ports are available, chip
> + * 		variants, which GPIO pins act in what additional roles, and so
> + * 		on.  This shrinks the "Board Support Packages" (BSPs) and
> + * 		minimizes board-specific #ifdefs in drivers.
> + * @power:	For device power management.
> + * 		See the Documentation/power/devices.txt for details.
> + * @pwr_domain:	Provide callbacks that are executed during system suspend,
> + * 		hibernation, system resume and during runtime PM transitions 
> + * 		along with subsystem-level and driver-level callbacks.
> + * @numa_node:	NUMA node this device is close to.
> + * @dma_mask:	Dma mask (if dma'ble device).
> + * @coherent_dma_mask:Like dma_mask, but for alloc_coherent mapping as not all
> + * 		hardware supports 64 bit addresses for consistent allocations
> + * 		such description.
> + * @dma_parms:	A low level driver may set these to teach IOMMU code about
> + * 		segment limitations.
> + * @dma_pools:	Dma pools (if dma'ble device) .
> + * @dma_mem:	Internal for coherent mem override.
> + * @archdata:	For arch specific additions.
> + * @of_node:	Associated device tree node.
> + * @of_match:	Matching of_device_id from driver.
> + * @devt:	For creating the sysfs "dev".
> + * @devres_lock:Spinlock to protect the resource of the device.
> + * @devres_head:The resources list of the device.
> + * @knode_class:The node used to add the device to the class list.
> + * @class:	The class of the device.
> + * @groups:	Optional attribute groups.
> + * @release:	Callback to free the device after all references have 
> + * 		gone away. This should be set by the allocator of the 
> + * 		device (i.e. the bus driver that discovered the device).
> + */
>  struct device {
>  	struct device		*parent;
>  
> @@ -611,7 +709,7 @@ extern int (*platform_notify)(struct device *dev);
>  extern int (*platform_notify_remove)(struct device *dev);
>  
>  
> -/**
> +/*
>   * get_device - atomically increment the reference count for the device.
>   *
>   */
> -- 
> 1.7.4.1
> 


---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: [PATCH 1/2] KernelDoc:Add the device driver-model structures to kerneldoc

[Greg KH]

On Mon, May 02, 2011 at 08:26:09AM -0700, Randy Dunlap wrote:
> On Mon,  2 May 2011 23:04:40 +0800 wanlong.gao@gmail.com wrote:
> 
> > From: Wanlong Gao <wanlong.gao@gmail.com>
> > 
> > Add the comment the structure bus_type, device_driver, device,
> > class for generating the driver-model kerneldoc.
> 
> Warning: trailing whitespace in lines 66,478,498,499 of include/linux/device.h
> 
> Other than that:
> 
> Acked-by: Randy Dunlap <rdunlap@xenotime.net>
> 
> Thanks.
> 
> Greg, do you want to merge this or should I?

Please don't, I have some issues with it that I will respond to in a
minute.

thanks,

greg k-h

Re: [PATCH 1/2] KernelDoc:Add the device driver-model structures to kerneldoc

[wanlong.gao]

在 2011-05-02一的 08:26 -0700，Randy Dunlap写道：
> On Mon,  2 May 2011 23:04:40 +0800 wanlong.gao@gmail.com wrote:
> 
> > From: Wanlong Gao <wanlong.gao@gmail.com>
> > 
> > Add the comment the structure bus_type, device_driver, device,
> > class for generating the driver-model kerneldoc.
> 
> Warning: trailing whitespace in lines 66,478,498,499 of include/linux/device.h
> 
> Other than that:
> 
> Acked-by: Randy Dunlap <rdunlap@xenotime.net>
> 
> Thanks.
> 
> Greg, do you want to merge this or should I?
> 
Randy:
	Sorry for the writespace.


>From eea23d68008c2ca8a944b303a835e32c2b81834c Mon Sep 17 00:00:00 2001
From: Wanlong Gao <wanlong.gao@gmail.com>
Date: Mon, 2 May 2011 23:34:02 +0800
Subject: [PATCH] KernelDoc:Add the device driver-model structures to
kerneldoc

Add the comment the structure bus_type, device_driver, device,
class for generating the driver-model kerneldoc.

Signed-off-by: Wanlong Gao <wanlong.gao@gmail.com>
---
 Documentation/DocBook/device-drivers.tmpl |    6 +-
 include/linux/device.h                    |  104
++++++++++++++++++++++++++++-
 2 files changed, 104 insertions(+), 6 deletions(-)

diff --git a/Documentation/DocBook/device-drivers.tmpl
b/Documentation/DocBook/device-drivers.tmpl
index 36f63d4..5e482e0 100644
--- a/Documentation/DocBook/device-drivers.tmpl
+++ b/Documentation/DocBook/device-drivers.tmpl
@@ -96,10 +96,10 @@ X!Iinclude/linux/kobject.h
 
   <chapter id="devdrivers">
      <title>Device drivers infrastructure</title>
+     <sect1><title>The Basic Device Driver-Model Structure </title>
+!Iinclude/linux/device.h
+     </sect1>
      <sect1><title>Device Drivers Base</title>
-<!--
-X!Iinclude/linux/device.h
--->
 !Edrivers/base/driver.c
 !Edrivers/base/core.c
 !Edrivers/base/class.c
diff --git a/include/linux/device.h b/include/linux/device.h
index ab8dfc0..aa1bd07 100644
--- a/include/linux/device.h
+++ b/include/linux/device.h
@@ -47,6 +47,23 @@ extern int __must_check bus_create_file(struct
bus_type *,
 					struct bus_attribute *);
 extern void bus_remove_file(struct bus_type *, struct bus_attribute *);
 
+/**
+ * struct bus_type - The bus type of the device .
+ *
+ * @name:	The name of the bus
+ * @bus_attrs:	The attributes of the bus
+ * @dev_attrs:	The default attributes of the devices on the bus
+ * @drv_attrs:	The default attributes of the device drivers on the bus
+ * @match:	Attaching drivers to devices
+ * @uevent:	Add the environment variable for device plug
+ * @probe:	Probe the device
+ * @remove:	Remove the device
+ * @shutdown:	Shutdown method
+ * @suspend:	Suspend method
+ * @resume:	Resume method
+ * @pm:		Device power management operations
+ * @p:		The private data the subsystem
+ */
 struct bus_type {
 	const char		*name;
 	struct bus_attribute	*bus_attrs;
@@ -119,6 +136,23 @@ extern int bus_unregister_notifier(struct bus_type
*bus,
 extern struct kset *bus_get_kset(struct bus_type *bus);
 extern struct klist *bus_get_device_klist(struct bus_type *bus);
 
+/**
+ * struct device_driver - The basic device driver structure
+ * @name:	Name of the device driver
+ * @bus:	The bus the device driver belongs to
+ * @owner:	The driver's owner
+ * @mod_name:	Used for built-in modules
+ * @suppress_bind_attrs:Disables bind/unbind via sysfs
+ * @of_match_table:Id table for matching the driver to device
+ * @probe:	Called to bound a driver to the device
+ * @remove:	Called to unbind a driver from a device
+ * @shutdown:	Called when shutdown
+ * @suspend:	Called to put the device in a low power state
+ * @resume:	Used to bring a device from a low power state
+ * @groups:	Driver's attribute groups
+ * @pm:		Device's power management operations
+ * @p:		Driver's private data
+ */
 struct device_driver {
 	const char		*name;
 	struct bus_type		*bus;
@@ -185,8 +219,24 @@ struct device *driver_find_device(struct
device_driver *drv,
 				  struct device *start, void *data,
 				  int (*match)(struct device *dev, void *data));
 
-/*
- * device classes
+/**
+ * struct class - device classes
+ * @name:	Name of the class
+ * @owner:	Class' owner
+ * @class_attrs:The attributes of the class
+ * @dev_attrs:	The default attributes of the device belongs to the
class
+ * @dev_bin_attrs:The default binary attributes of the device belongs
to the class
+ * @dev_kobj:	Kobject of the class
+ * @dev_uevent:	Used to plug
+ * @devnode:	Callback to provide the devtmpfs
+ * @class_release:Called to release the class
+ * @dev_release:Called to release the device
+ * @suspend:	Used to put the device to a low power state
+ * @resume:	Used to bring the device from a low power state
+ * @ns_type:	Callbacks so sysfs can detemine namespaces
+ * @namespace:	Namespace of the device
+ * @pm:		The default device power management operations
+ * @p:		The private data of the subsystem
  */
 struct class {
 	const char		*name;
@@ -401,6 +451,54 @@ struct device_dma_parameters {
 	unsigned long segment_boundary_mask;
 };
 
+/**
+ * struct device - The basic device structure.
+ * @parent:	Parent of the device.
+ * @p:		Hold the private to the driver core portions of the device.
+ * 		See the comment of the struct device_private for detail.
+ * @kobj:	A top-level, abstract class from which other classes are
derived.
+ * @init_name:	Initial name of the device.
+ * @type:	The type of device.
+ * 		This identifies the device type and carries type-specific
+ * 		information.
+ * @mutex:	Mutex to synchronize calls to its driver.
+ * @bus:	Type of bus device is on.
+ * @driver:	Which driver has allocated this
+ * @platform_data:Platform data specific to the device.
+ * 		Example..For devices on custom boards, as typical of embedded
+ * 		and SOC based hardware, Linux often uses platform_data to point
+ * 		to board-specific structures describing devices and how they
+ * 		are wired.  That can include what ports are available, chip
+ * 		variants, which GPIO pins act in what additional roles, and so
+ * 		on.  This shrinks the "Board Support Packages" (BSPs) and
+ * 		minimizes board-specific #ifdefs in drivers.
+ * @power:	For device power management.
+ * 		See the Documentation/power/devices.txt for details.
+ * @pwr_domain:	Provide callbacks that are executed during system
suspend,
+ * 		hibernation, system resume and during runtime PM transitions
+ * 		along with subsystem-level and driver-level callbacks.
+ * @numa_node:	NUMA node this device is close to.
+ * @dma_mask:	Dma mask (if dma'ble device).
+ * @coherent_dma_mask:Like dma_mask, but for alloc_coherent mapping as
not all
+ * 		hardware supports 64 bit addresses for consistent allocations
+ * 		such description.
+ * @dma_parms:	A low level driver may set these to teach IOMMU code
about
+ * 		segment limitations.
+ * @dma_pools:	Dma pools (if dma'ble device) .
+ * @dma_mem:	Internal for coherent mem override.
+ * @archdata:	For arch specific additions.
+ * @of_node:	Associated device tree node.
+ * @of_match:	Matching of_device_id from driver.
+ * @devt:	For creating the sysfs "dev".
+ * @devres_lock:Spinlock to protect the resource of the device.
+ * @devres_head:The resources list of the device.
+ * @knode_class:The node used to add the device to the class list.
+ * @class:	The class of the device.
+ * @groups:	Optional attribute groups.
+ * @release:	Callback to free the device after all references have
+ * 		gone away. This should be set by the allocator of the
+ * 		device (i.e. the bus driver that discovered the device).
+ */
 struct device {
 	struct device		*parent;
 
@@ -611,7 +709,7 @@ extern int (*platform_notify)(struct device *dev);
 extern int (*platform_notify_remove)(struct device *dev);
 
 
-/**
+/*
  * get_device - atomically increment the reference count for the
device.
  *
  */
-- 
1.7.4.1

Re: [PATCH 1/2] KernelDoc:Add the device driver-model structures to kerneldoc

[Greg KH]

On Mon, May 02, 2011 at 11:04:40PM +0800, wanlong.gao@gmail.com wrote:
> From: Wanlong Gao <wanlong.gao@gmail.com>
> 
> Add the comment the structure bus_type, device_driver, device,
> class for generating the driver-model kerneldoc.
> 
> Signed-off-by: Wanlong Gao <wanlong.gao@gmail.com>
> ---
>  Documentation/DocBook/device-drivers.tmpl |    6 +-
>  include/linux/device.h                    |  104 ++++++++++++++++++++++++++++-
>  2 files changed, 104 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl
> index 36f63d4..5e482e0 100644
> --- a/Documentation/DocBook/device-drivers.tmpl
> +++ b/Documentation/DocBook/device-drivers.tmpl
> @@ -96,10 +96,10 @@ X!Iinclude/linux/kobject.h
>  
>    <chapter id="devdrivers">
>       <title>Device drivers infrastructure</title>
> +     <sect1><title>The Basic Device Driver-Model Structure </title>
> +!Iinclude/linux/device.h
> +     </sect1>
>       <sect1><title>Device Drivers Base</title>
> -<!--
> -X!Iinclude/linux/device.h
> --->
>  !Edrivers/base/driver.c
>  !Edrivers/base/core.c
>  !Edrivers/base/class.c
> diff --git a/include/linux/device.h b/include/linux/device.h
> index ab8dfc0..5258d5d 100644
> --- a/include/linux/device.h
> +++ b/include/linux/device.h
> @@ -47,6 +47,23 @@ extern int __must_check bus_create_file(struct bus_type *,
>  					struct bus_attribute *);
>  extern void bus_remove_file(struct bus_type *, struct bus_attribute *);
>  
> +/**
> + * struct bus_type - The bus type of the device .
> + *
> + * @name:	The name of the bus
> + * @bus_attrs:	The attributes of the bus

Default attributes of the bus.

> + * @dev_attrs:	The default attributes of the devices on the bus
> + * @drv_attrs:	The default attributes of the device drivers on the bus
> + * @match:	Attaching drivers to devices

No, this is called when the driver core wants to know if this driver can
accept this device.  It does not do an "attach" here.

> + * @uevent:	Add the environment variable for device plug

"device plug"?  No, not always, it is for when a device is added,
removed, or a few other things that generate uevents.

> + * @probe:	Probe the device
> + * @remove:	Remove the device
> + * @shutdown:	Shutdown method
> + * @suspend:	Suspend method
> + * @resume:	Resume method

All of these can get more descriptions, right?

> + * @pm:		Device power management operations
> + * @p:		The private data the subsystem

p is private to the driver core, not to the subsystem.  Only the driver
core can touch this.

> + */ 
>  struct bus_type {
>  	const char		*name;
>  	struct bus_attribute	*bus_attrs;
> @@ -119,6 +136,23 @@ extern int bus_unregister_notifier(struct bus_type *bus,
>  extern struct kset *bus_get_kset(struct bus_type *bus);
>  extern struct klist *bus_get_device_klist(struct bus_type *bus);
>  
> +/**
> + * struct device_driver - The basic device driver structure
> + * @name:	Name of the device driver
> + * @bus:	The bus the device driver belongs to
> + * @owner:	The driver's owner

The module owner.

> + * @mod_name:	Used for built-in modules

Huh?

> + * @suppress_bind_attrs:Disables bind/unbind via sysfs
> + * @of_match_table:Id table for matching the driver to device

No, this is an open firmware table.

> + * @probe:	Called to bound a driver to the device

To bind.

> + * @remove:	Called to unbind a driver from a device
> + * @shutdown:	Called when shutdown
> + * @suspend:	Called to put the device in a low power state

Suspend is more than a "low power state"

> + * @resume:	Used to bring a device from a low power state

Same here.

> + * @groups:	Driver's attribute groups

Default attributes that get created by the driver core automatically.

> + * @pm:		Device's power management operations
> + * @p:		Driver's private data

Again, the driver core's private data, not the driver's private data,
very big difference.  No one other than the driver core can touch this.

Same goes for the other comments you added...

I think this needs a whole lot more description than what you have
provided in order for it to be acceptable.

Care to work on it?

thanks,

greg k-h

Re: [PATCH 1/2] KernelDoc:Add the device driver-model structures to kerneldoc

[Wanlong Gao]

On 5/2/11, Greg KH <gregkh@suse.de> wrote:

> Again, the driver core's private data, not the driver's private data,
> very big difference.  No one other than the driver core can touch this.
>
> Same goes for the other comments you added...
>
> I think this needs a whole lot more description than what you have
> provided in order for it to be acceptable.
>
> Care to work on it?
>
> thanks,
>
> greg k-h
Greg:
Thanks for your comments and I will do my best and resend the patch.

Thanks
Wanlong Gao

[PATCH 2/2] Documentation:remove the driver-model structures from the docs

[wanlong.gao]

From: Wanlong Gao <wanlong.gao@gmail.com>

Remove the struct bus_type, class, device, device_driver from the
driver-model docs.

Signed-off-by: Wanlong Gao <wanlong.gao@gmail.com>
---
 Documentation/driver-model/bus.txt    |   19 +-------
 Documentation/driver-model/class.txt  |   17 +------
 Documentation/driver-model/device.txt |   91 +--------------------------------
 Documentation/driver-model/driver.txt |   18 +------
 4 files changed, 4 insertions(+), 141 deletions(-)

diff --git a/Documentation/driver-model/bus.txt b/Documentation/driver-model/bus.txt
index 5001b75..6754b2d 100644
--- a/Documentation/driver-model/bus.txt
+++ b/Documentation/driver-model/bus.txt
@@ -3,24 +3,7 @@ Bus Types
 
 Definition
 ~~~~~~~~~~
-
-struct bus_type {
-	char			* name;
-
-	struct subsystem	subsys;
-	struct kset		drivers;
-	struct kset		devices;
-
-	struct bus_attribute	* bus_attrs;
-	struct device_attribute	* dev_attrs;
-	struct driver_attribute	* drv_attrs;
-
-	int		(*match)(struct device * dev, struct device_driver * drv);
-	int		(*hotplug) (struct device *dev, char **envp, 
-				    int num_envp, char *buffer, int buffer_size);
-	int		(*suspend)(struct device * dev, pm_message_t state);
-	int		(*resume)(struct device * dev);
-};
+See the kerneldoc for the struct bus_type.
 
 int bus_register(struct bus_type * bus);
 
diff --git a/Documentation/driver-model/class.txt b/Documentation/driver-model/class.txt
index 548505f..1fefc48 100644
--- a/Documentation/driver-model/class.txt
+++ b/Documentation/driver-model/class.txt
@@ -27,22 +27,7 @@ The device class structure looks like:
 typedef int (*devclass_add)(struct device *);
 typedef void (*devclass_remove)(struct device *);
 
-struct device_class {
-	char			* name;
-	rwlock_t		lock;
-	u32			devnum;
-	struct list_head	node;
-
-	struct list_head	drivers;
-	struct list_head	intf_list;
-
-	struct driver_dir_entry	dir;
-	struct driver_dir_entry	device_dir;
-	struct driver_dir_entry	driver_dir;
-
-	devclass_add		add_device;
-	devclass_remove		remove_device;
-};
+See the kerneldoc for the struct class.
 
 A typical device class definition would look like: 
 
diff --git a/Documentation/driver-model/device.txt b/Documentation/driver-model/device.txt
index a124f31..b2ff426 100644
--- a/Documentation/driver-model/device.txt
+++ b/Documentation/driver-model/device.txt
@@ -2,96 +2,7 @@
 The Basic Device Structure
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-struct device {
-        struct list_head g_list;
-        struct list_head node;
-        struct list_head bus_list;
-        struct list_head driver_list;
-        struct list_head intf_list;
-        struct list_head children;
-        struct device   * parent;
-
-        char    name[DEVICE_NAME_SIZE];
-        char    bus_id[BUS_ID_SIZE];
-
-        spinlock_t      lock;
-        atomic_t        refcount;
-
-        struct bus_type * bus;
-        struct driver_dir_entry dir;
-
-	u32		class_num;
-
-        struct device_driver *driver;
-        void            *driver_data;
-        void            *platform_data;
-
-        u32             current_state;
-        unsigned char *saved_state;
-
-        void    (*release)(struct device * dev);
-};
-
-Fields 
-~~~~~~
-g_list:	Node in the global device list.
-
-node:	Node in device's parent's children list.
-
-bus_list: Node in device's bus's devices list.
-
-driver_list:   Node in device's driver's devices list.
-
-intf_list:     List of intf_data. There is one structure allocated for
-	       each interface that the device supports.
-
-children:      List of child devices.
-
-parent:        *** FIXME ***
-
-name:	       ASCII description of device. 
-	       Example: " 3Com Corporation 3c905 100BaseTX [Boomerang]"
-
-bus_id:	       ASCII representation of device's bus position. This 
-	       field should be a name unique across all devices on the
-	       bus type the device belongs to. 
-
-	       Example: PCI bus_ids are in the form of
-	       <bus number>:<slot number>.<function number> 
-	       This name is unique across all PCI devices in the system.
-
-lock:	       Spinlock for the device. 
-
-refcount:      Reference count on the device.
-
-bus:	       Pointer to struct bus_type that device belongs to.
-
-dir:	       Device's sysfs directory.
-
-class_num:     Class-enumerated value of the device.
-
-driver:	       Pointer to struct device_driver that controls the device.
-
-driver_data:   Driver-specific data.
-
-platform_data: Platform data specific to the device.
-
-	       Example:  for devices on custom boards, as typical of embedded
-	       and SOC based hardware, Linux often uses platform_data to point
-	       to board-specific structures describing devices and how they
-	       are wired.  That can include what ports are available, chip
-	       variants, which GPIO pins act in what additional roles, and so
-	       on.  This shrinks the "Board Support Packages" (BSPs) and
-	       minimizes board-specific #ifdefs in drivers.
-
-current_state: Current power state of the device.
-
-saved_state:   Pointer to saved state of the device. This is usable by
-	       the device driver controlling the device.
-
-release:       Callback to free the device after all references have 
-	       gone away. This should be set by the allocator of the 
-	       device (i.e. the bus driver that discovered the device).
+See the kerneldoc for the struct device.
 
 
 Programming Interface
diff --git a/Documentation/driver-model/driver.txt b/Documentation/driver-model/driver.txt
index d2cd6fb..4421135 100644
--- a/Documentation/driver-model/driver.txt
+++ b/Documentation/driver-model/driver.txt
@@ -1,23 +1,7 @@
 
 Device Drivers
 
-struct device_driver {
-        char                    * name;
-        struct bus_type         * bus;
-
-        struct completion	unloaded;
-        struct kobject		kobj;
-        list_t                  devices;
-
-        struct module		*owner;
-
-        int     (*probe)        (struct device * dev);
-        int     (*remove)       (struct device * dev);
-
-        int     (*suspend)      (struct device * dev, pm_message_t state);
-        int     (*resume)       (struct device * dev);
-};
-
+See the kerneldoc for the struct device_driver.
 
 
 Allocation
-- 
1.7.4.1