Re: [PATCH] Fix the over time interface of the driver-model docs

[Randy Dunlap]

On Sun,  1 May 2011 13:50:56 +0800 wanlong.gao@xxxxxxxxx wrote:

> From: Wanlong Gao<wanlong.gao@xxxxxxxxx>
> 
> The driver-model documentation seems like out-of-date, Can we
> fix them or rewrite ?

GregKH should get this patch.......


> Signed-off-by: Wanlong Gao<wanlong.gao@xxxxxxxxx>
> ---
>  Documentation/driver-model/bus.txt    |   32 ++++----
>  Documentation/driver-model/device.txt |  149 +++++++++++++++++++--------------
>  2 files changed, 104 insertions(+), 77 deletions(-)
> 
> diff --git a/Documentation/driver-model/bus.txt b/Documentation/driver-model/bus.txt
> index 5001b75..82bca26 100644
> --- a/Documentation/driver-model/bus.txt
> +++ b/Documentation/driver-model/bus.txt
> @@ -5,21 +5,23 @@ Definition
>  ~~~~~~~~~~
>  
>  struct bus_type {
> -	char			* name;
> +	const char		*name;
> +	struct bus_attribute	*bus_attrs;
> +	struct device_attribute	*dev_attrs;
> +	struct driver_attribute	*drv_attrs;
>  
> -	struct subsystem	subsys;
> -	struct kset		drivers;
> -	struct kset		devices;
> +	int (*match)(struct device *dev, struct device_driver *drv);
> +	int (*uevent)(struct device *dev, struct kobj_uevent_env *env);
> +	int (*probe)(struct device *dev);
> +	int (*remove)(struct device *dev);
> +	void (*shutdown)(struct device *dev);
>  
> -	struct bus_attribute	* bus_attrs;
> -	struct device_attribute	* dev_attrs;
> -	struct driver_attribute	* drv_attrs;
> +	int (*suspend)(struct device *dev, pm_message_t state);
> +	int (*resume)(struct device *dev);
>  
> -	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);
> +	const struct dev_pm_ops *pm;
> +
> +	struct subsys_private *p;
>  };
>  
>  int bus_register(struct bus_type * bus);
> @@ -127,9 +129,9 @@ hierarchy:
>  
>  	/sys/bus/pci/
>  	|-- devices
> -	|   |-- 00:00.0 -> ../../../root/pci0/00:00.0
> -	|   |-- 00:01.0 -> ../../../root/pci0/00:01.0
> -	|   `-- 00:02.0 -> ../../../root/pci0/00:02.0
> +	|   |-- 00:00.0 -> ../../../devices/pci0/00:00.0
> +	|   |-- 00:01.0 -> ../../../devices/pci0/00:01.0
> +	|   `-- 00:02.0 -> ../../../devices/pci0/00:02.0
>  	`-- drivers
>  
>  
> diff --git a/Documentation/driver-model/device.txt b/Documentation/driver-model/device.txt
> index a124f31..98dca04 100644
> --- a/Documentation/driver-model/device.txt
> +++ b/Documentation/driver-model/device.txt
> @@ -3,95 +3,121 @@ 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;
> +	struct device		*parent;
>  
> -        char    name[DEVICE_NAME_SIZE];
> -        char    bus_id[BUS_ID_SIZE];
> +	struct device_private	*p;
>  
> -        spinlock_t      lock;
> -        atomic_t        refcount;
> +	struct kobject kobj;
> +	const char		*init_name;
> +	struct device_type	*type;
>  
> -        struct bus_type * bus;
> -        struct driver_dir_entry dir;
> +	struct mutex		mutex;
> +	struct bus_type	*bus;
> +	struct device_driver *driver;
> +	void		*platform_data;
> +	struct dev_pm_info	power;
> +	struct dev_power_domain	*pwr_domain;
>  
> -	u32		class_num;
> +#ifdef CONFIG_NUMA
> +	int		numa_node;
> +#endif
> +	u64		*dma_mask;
> +	u64		coherent_dma_mask;
>  
> -        struct device_driver *driver;
> -        void            *driver_data;
> -        void            *platform_data;
> +	struct device_dma_parameters *dma_parms;
>  
> -        u32             current_state;
> -        unsigned char *saved_state;
> +	struct list_head	dma_pools;
>  
> -        void    (*release)(struct device * dev);
> +	struct dma_coherent_mem	*dma_mem;
> +	struct dev_archdata	archdata;
> +
> +	struct device_node	*of_node;
> +	const struct of_device_id *of_match;
> +
> +	dev_t			devt;
> +
> +	spinlock_t		devres_lock;
> +	struct list_head	devres_head;
> +
> +	struct klist_node	knode_class;
> +	struct class		*class;
> +	const struct attribute_group **groups;
> +
> +	void	(*release)(struct device *dev);
>  };
>  
>  Fields 
>  ~~~~~~
> -g_list:	Node in the global device list.
> +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.
>  
> -node:	Node in device's parent's children list.
> +bus:		Type of bus device is on.
>  
> -bus_list: Node in device's bus's devices list.
> +platform_data:	Platform data specific to the device.
>  
> -driver_list:   Node in device's driver's devices list.
> +		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.
>  
> -intf_list:     List of intf_data. There is one structure allocated for
> -	       each interface that the device supports.
> +power:		For device power management.
> +		See the Documentation/power/devices.txt for details.
>  
> -children:      List of child devices.
> +dev_power_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.
>  
> -parent:        *** FIXME ***
> +numa_node:	NUMA node this device is close to.
>  
> -name:	       ASCII description of device. 
> -	       Example: " 3Com Corporation 3c905 100BaseTX [Boomerang]"
> +dma_mask:	Dma mask (if dma'ble device).
>  
> -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. 
> +coherent_dma_mask:Like dma_mask, but for alloc_coherent mapping as not all
> +		hardware supports 64 bit addresses for consistent allocations
> +		such description.
>  
> -	       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.
> +dma_parms:	A low level driver may set these to teach IOMMU code about
> +		segment limitations.
>  
> -lock:	       Spinlock for the device. 
> +dma_pools:	Dma pools (if dma'ble device) .
>  
> -refcount:      Reference count on the device.
> +dma_mem:	Internal for coherent mem override.
>  
> -bus:	       Pointer to struct bus_type that device belongs to.
> +archdata:	For arch specific additions.
>  
> -dir:	       Device's sysfs directory.
> +of_node:	Associated device tree node.
>  
> -class_num:     Class-enumerated value of the device.
> +of_match:	Matching of_device_id from driver.
>  
> -driver:	       Pointer to struct device_driver that controls the device.
> +devt:		For creating the sysfs "dev".
>  
> -driver_data:   Driver-specific data.
> +devres_lock:	Spinlock to protect the resource of the device.
>  
> -platform_data: Platform data specific to the device.
> +devres_head:	The resources list of 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.
> +knode_class:	The node used to add the device to the class list.
>  
> -current_state: Current power state of the device.
> +class:		The class of the device.
>  
> -saved_state:   Pointer to saved state of the device. This is usable by
> -	       the device driver controlling 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).
> +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).
>  
>  
>  Programming Interface
> @@ -104,8 +130,7 @@ int device_register(struct device * dev);
>  The bus should initialize the following fields:
>  
>      - parent
> -    - name
> -    - bus_id
> +    - init_name OR kobj->name
>      - bus
>  
>  A device is removed from the core when its reference count goes to
> @@ -120,8 +145,8 @@ removed already).
>  
>  A driver can access the lock in the device structure using: 
>  
> -void lock_device(struct device * dev);
> -void unlock_device(struct device * dev);
> +void device_lock(struct device * dev);
> +void device_unlock(struct device * dev);
>  
>  
>  Attributes
> @@ -193,4 +218,4 @@ Then in the module init function is would do:
>  
>  And assuming 'dev' is the struct device passed into the probe hook, the driver
>  probe function would do something like:
> -	create_device(&mydriver_class, dev, chrdev, &private_data, "my_name");
> +	device_create(&mydriver_class, dev->parent, devt, &drvdata, "my_name");
> -- 


---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/