drivers/base/core.c: merge fixup

Documentation/driver-model/binding.txt

+
+Driver Binding
+
+Driver binding is the process of associating a device with a device
+driver that can control it. Bus drivers have typically handled this
+because there have been bus-specific structures to represent the
+devices and the drivers. With generic device and device driver
+structures, most of the binding can take place using common code.
+
+
+Bus
+~~~
+
+The bus type structure contains a list of all devices that on that bus
+type in the system. When device_register is called for a device, it is
+inserted into the end of this list. The bus object also contains a
+list of all drivers of that bus type. When driver_register is called
+for a driver, it is inserted into the end of this list. These are the
+two events which trigger driver binding.
+
+
+device_register
+~~~~~~~~~~~~~~~
+
+When a new device is added, the bus's list of drivers is iterated over
+to find one that supports it. In order to determine that, the device
+ID of the device must match one of the device IDs that the driver
+supports. The format and semantics for comparing IDs is bus-specific. 
+Instead of trying to derive a complex state machine and matching
+algorithm, it is up to the bus driver to provide a callback to compare
+a device against the IDs of a driver. The bus returns 1 if a match was
+found; 0 otherwise.
+
+int match(struct device * dev, struct device_driver * drv);
+
+If a match is found, the device's driver field is set to the driver
+and the driver's probe callback is called. This gives the driver a
+chance to verify that it really does support the hardware, and that
+it's in a working state. 
+
+Device Class
+~~~~~~~~~~~~
+
+Upon the successful completion of probe, the device is registered with
+the class to which it belongs. Device drivers belong to one and only
+class, and that is set in the driver's devclass field. 
+devclass_add_device is called to enumerate the device within the class
+and actually register it with the class, which happens with the
+class's register_dev callback.
+
+NOTE: The device class structures and core routines to manipulate them
+are not in the mainline kernel, so the discussion is still a bit
+speculative. 
+
+
+Driver
+~~~~~~
+
+When a driver is attached to a device, the device is inserted into the
+driver's list of devices. 
+
+
+driverfs
+~~~~~~~~
+
+A symlink is created in the bus's 'devices' directory that points to
+the device's directory in the physical hierarchy.
+
+A symlink is created in the driver's 'devices' directory that points
+to the device's directory in the physical hierarchy.
+
+A directory for the device is created in the class's directory. A
+symlink is created in that directory that points to the device's
+physical location in the driverfs tree. 
+
+A symlink can be created (though this isn't done yet) in the device's
+physical directory to either its class directory, or the class's
+top-level directory. One can also be created to point to its driver's
+directory also. 
+
+
+driver_register
+~~~~~~~~~~~~~~~
+
+The process is almost identical for when a new driver is added. 
+The bus's list of devices is iterated over to find a match. Devices
+that already have a driver are skipped. All the devices are iterated
+over, to bind as many devices as possible to the driver.
+
+
+Removal
+~~~~~~~
+
+When a device is removed, the reference count for it will eventually
+go to 0. When it does, the remove callback of the driver is called. It
+is removed from the driver's list of devices and the reference count
+of the driver is decremented. All symlinks between the two are removed.
+
+When a driver is removed, the list of devices that it supports is
+iterated over, and the driver's remove callback is called for each
+one. The device is removed from that list and the symlinks removed. 
+

Documentation/driver-model/bus.txt

+
+Bus Types 
+
+Definition
+~~~~~~~~~~
+
+struct bus_type {
+        char                    * name;
+        rwlock_t                lock;
+        atomic_t                refcount;
+
+        struct list_head        node;
+        struct list_head        devices;
+        struct list_head        drivers;
+
+        struct driver_dir_entry dir;
+        struct driver_dir_entry device_dir;
+        struct driver_dir_entry driver_dir;
+
+        int     (*match)        (struct device * dev, struct device_driver * drv);
+	struct device (*add)	(struct device * parent, char * bus_id);
+};
+
+int bus_register(struct bus_type * bus);
+
+
+Declaration
+~~~~~~~~~~~
+
+Each bus type in the kernel (PCI, USB, etc) should declare one static
+object of this type. They must initialize the name field, and may
+optionally initialize the match callback.
+
+struct bus_type pci_bus_type = {
+       name:	"pci",
+       match:	pci_bus_match,
+};
+
+The structure should be exported to drivers in a header file:
+
+extern struct bus_type pci_bus_type;
+
+
+Registration
+~~~~~~~~~~~~
+
+When a bus driver is initialized, it calls bus_register. This
+initializes the rest of the fields in the bus object and inserts it
+into a global list of bus types. Once the bus object is registered, 
+the fields in it (e.g. the rwlock_t) are usable by the bus driver. 
+
+
+Callbacks
+~~~~~~~~~
+
+match(): Attaching Drivers to Devices
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The format of device ID structures and the semantics for comparing
+them are inherently bus-specific. Drivers typically declare an array
+of device IDs of device they support that reside in a bus-specific
+driver structure. 
+
+The purpose of the match callback is provide the bus an opportunity to
+determine if a particular driver supports a particular device by
+comparing the device IDs the driver supports with the device ID of a
+particular device, without sacrificing bus-specific functionality or
+type-safety. 
+
+When a driver is registered with the bus, the bus's list of devices is
+iterated over, and the match callback is called for each device that
+does not have a driver associated with it. 
+
+add(): Adding a child device
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The add callback is available to notify the bus about a child device
+at a particular location. 
+
+The parent parameter is the parent device of the child to be added. If
+parent == NULL, the bus should add the device as a child of a default
+parent device or as a child of the root. This policy decision is up to
+the bus driver.
+
+The format of the bus_id field should be consistent with the format of
+the bus_id field of the rest of the devices on the bus. This requires
+the caller to know the format.
+
+On return, the bus driver should return a pointer to the device that
+was created. If the device was not created, the bus driver should
+return an appropriate error code. Refer to include/linux/err.h for
+helper functions to encode errors. Some sample code:
+
+struct device * pci_bus_add(struct device * parent, char * bus_id)
+{
+	...
+	/* the device already exists */
+	return ERR_PTR(-EEXIST);
+	...
+}
+
+The caller can check the return value using IS_ERR():
+
+    struct device * newdev = pci_bus_type.add(parent,bus_id);
+    if (IS_ERR(newdev)) {
+	...
+    }
+
+
+Device and Driver Lists
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The lists of devices and drivers are intended to replace the local
+lists that many buses keep. They are lists of struct devices and
+struct device_drivers, respectively. Bus drivers are free to use the
+lists as they please, but conversion to the bus-specific type may be
+necessary. 
+
+The LDM core provides helper functions for iterating over each list.
+
+int bus_for_each_dev(struct bus_type * bus, void * data, 
+		     int (*callback)(struct device * dev, void * data));
+int bus_for_each_drv(struct bus_type * bus, void * data,
+		     int (*callback)(struct device_driver * drv, void * data));
+
+These helpers iterate over the respective list, and call the callback
+for each device or driver in the list. All list accesses are
+synchronized by taking the bus's lock (read currently). The reference
+count on each object in the list is incremented before the callback is
+called; it is decremented after the next object has been obtained. The
+lock is not held when calling the callback. 
+
+
+driverfs
+~~~~~~~~
+There is a top-level directory named 'bus'.
+
+Each bus gets a directory in the bus directory, along with two default
+directories:
+
+	/sys/bus/pci/
+	|-- devices
+	`-- drivers
+
+Drivers registered with the bus get a directory in the bus's drivers
+directory:
+
+	/sys/bus/pci/
+	|-- devices
+	`-- drivers
+	    |-- Intel ICH
+	    |-- Intel ICH Joystick
+	    |-- agpgart
+	    `-- e100
+
+Each device that is discovered a bus of that type gets a symlink in
+the bus's devices directory to the device's directory in the physical
+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
+	`-- drivers
+
+
+Exporting Attributes
+~~~~~~~~~~~~~~~~~~~~
+struct bus_attribute {
+        struct attribute        attr;
+        ssize_t (*show)(struct bus_type *, char * buf, size_t count, loff_t off);
+        ssize_t (*store)(struct bus_type *, const char * buf, size_t count, loff_t off);
+};
+
+Bus drivers can export attributes using the BUS_ATTR macro that works
+similarly to the DEVICE_ATTR macro for devices. For example, a definition 
+like this:
+
+static BUS_ATTR(debug,0644,show_debug,store_debug);
+
+is equivalent to declaring:
+
+static bus_attribute bus_attr_debug;
+
+This can then be used to add and remove the attribute from the bus's
+driverfs directory using:
+
+int bus_create_file(struct bus_type *, struct bus_attribute *);
+void bus_remove_file(struct bus_type *, struct bus_attribute *);
+
+

Documentation/driver-model/class.txt

+
+Device Classes
+
+
+Introduction
+~~~~~~~~~~~~
+A device class describes a type of device, like an audio or network
+device. The following device classes have been identified:
+
+<Insert List of Device Classes Here>
+
+
+Each device class defines a set of semantics and a programming interface
+that devices of that class adhere to. Device drivers are the
+implemention of that programming interface for a particular device on
+a particular bus. 
+
+Device classes are agnostic with respect to what bus a device resides
+on. 
+
+
+Programming Interface
+~~~~~~~~~~~~~~~~~~~~~
+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;
+};
+
+A typical device class definition would look like: 
+
+struct device_class input_devclass = {
+        .name		= "input",
+        .add_device	= input_add_device,
+	.remove_device	= input_remove_device,
+};
+
+Each device class structure should be exported in a header file so it
+can be used by drivers, extensions and interfaces.
+
+Device classes are registered and unregistered with the core using: 
+
+int devclass_register(struct device_class * cls);
+void devclass_unregister(struct device_class * cls);
+
+
+Devices
+~~~~~~~
+As devices are bound to drivers, they are added to the device class
+that the driver belongs to. Before the driver model core, this would
+typically happen during the driver's probe() callback, once the device
+has been initialized. It now happens after the probe() callback
+finishes from the core. 
+
+The device is enumerated in the class. Each time a device is added to
+the class, the class's devnum field is incremented and assigned to the
+device. The field is never decremented, so if the device is removed
+from the class and re-added, it will receive a different enumerated
+value. 
+
+The class is allowed to create a class-specific structure for the
+device and store it in the device's class_data pointer. 
+
+There is no list of devices in the device class. Each driver has a
+list of devices that it supports. The device class has a list of
+drivers of that particular class. To access all of the devices in the
+class, iterate over the device lists of each driver in the class.
+
+
+Device Drivers
+~~~~~~~~~~~~~~
+Device drivers are added to device classes when they are registered
+with the core. A driver specifies the class it belongs to by setting
+the struct device_driver::devclass field. 
+
+
+driverfs directory structure
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+There is a top-level driverfs directory named 'class'. 
+
+Each class gets a directory in the class directory, along with two
+default subdirectories:
+
+        class/
+        `-- input
+            |-- devices
+            `-- drivers
+
+
+Drivers registered with the class get a symlink in the drivers/ directory 
+that points the driver's directory (under its bus directory):
+
+   class/
+   `-- input
+       |-- devices
+       `-- drivers
+           `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/
+
+
+Each device gets a symlink in the devices/ directory that points to the 
+device's directory in the physical hierarchy:
+
+   class/
+   `-- input
+       |-- devices
+       |   `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/
+       `-- drivers
+
+
+Exporting Attributes
+~~~~~~~~~~~~~~~~~~~~
+struct devclass_attribute {
+        struct attribute        attr;
+        ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off);
+        ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off);
+};
+
+Class drivers can export attributes using the DEVCLASS_ATTR macro that works
+similarly to the DEVICE_ATTR macro for devices. For example, a definition 
+like this:
+
+static DEVCLASS_ATTR(debug,0644,show_debug,store_debug);
+
+is equivalent to declaring:
+
+static devclass_attribute devclass_attr_debug;
+
+The bus driver can add and remove the attribute from the class's
+driverfs directory using:
+
+int devclass_create_file(struct device_class *, struct devclass_attribute *);
+void devclass_remove_file(struct device_class *, struct devclass_attribute *);
+
+In the example above, the file will be named 'debug' in placed in the
+class's directory in driverfs. 
+
+
+Interfaces
+~~~~~~~~~~
+There may exist multiple mechanisms for accessing the same device of a
+particular class type. Device interfaces describe these mechanisms. 
+
+When a device is added to a device class, the core attempts to add it
+to every interface that is registered with the device class.
+

Documentation/driver-model/device.txt

+
+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.
+
+name:	       ASCII description of device. 
+	       Example: " 3Com Corporation 3c905 100BaseTX [Boomerang]"
+
+bus_id:	       ASCII representation of device's bus position. This 
+	       field should 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 driverfs directory.
+
+driver:	       Pointer to struct device_driver that controls the device.
+
+driver_data:   Driver-specific data.
+
+class_num:     Class-enumerated value of the device.
+
+platform_data: Platform data specific to the device.
+
+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).
+
+
+Programming Interface
+~~~~~~~~~~~~~~~~~~~~~
+The bus driver that discovers the device uses this to register the
+device with the core:
+
+int device_register(struct device * dev);
+
+The bus should initialize the following fields:
+
+    - parent
+    - name
+    - bus_id
+    - bus
+
+A device is removed from the core when its reference count goes to
+0. The reference count can be adjusted using:
+
+struct device * get_device(struct device * dev);
+void put_device(struct device * dev);
+
+get_device() will return a pointer to the struct device passed to it
+if the reference is not already 0 (if it's in the process of being
+removed already).
+
+A driver can take use the lock in the device structure using: 
+
+void lock_device(struct device * dev);
+void unlock_device(struct device * dev);
+
+
+Attributes
+~~~~~~~~~~
+struct device_attribute {
+        struct attribute        attr;
+        ssize_t (*show)(struct device * dev, char * buf, size_t count, loff_t off);
+        ssize_t (*store)(struct device * dev, const char * buf, size_t count, loff_t off);
+};
+
+Attributes of devices can be exported via drivers using a simple
+procfs-like interface. 
+
+Please see Documentation/filesystems/driverfs.txt for more information
+on how driverfs works.
+
+Attributes are declared using a macro called DEVICE_ATTR:
+
+#define DEVICE_ATTR(name,mode,show,store)
+
+Example:
+
+DEVICE_ATTR(power,0644,show_power,store_power);
+
+This declares a structure of type struct device_attribute named
+'dev_attr_power'. This can then be added and removed to the device's
+directory using:
+
+int device_create_file(struct device *device, struct device_attribute * entry);
+void device_remove_file(struct device * dev, struct device_attribute * attr);
+
+Example:
+
+device_create_file(dev,&dev_attr_power);
+device_remove_file(dev,&dev_attr_power);
+
+The file name will be 'power' with a mode of 0644 (-rw-r--r--).
+

Documentation/driver-model/interface.txt

+
+Device Interfaces
+
+Introduction
+~~~~~~~~~~~~
+
+Device interfaces are the logical interfaces of device classes that correlate
+directly to userspace interfaces, like device nodes. 
+   
+Each device class may have multiple interfaces through which you can 
+access the same device. An input device may support the mouse interface, 
+the 'evdev' interface, and the touchscreen interface. A SCSI disk would 
+support the disk interface, the SCSI generic interface, and possibly a raw 
+device interface. 
+
+Device interfaces are registered with the class they belong to. As devices
+are added to the class, they are added to each interface registered with
+the class. The interface is responsible for determining whether the device
+supports the interface or not. 
+
+
+Programming Interface
+~~~~~~~~~~~~~~~~~~~~~
+
+struct device_interface {
+	char			* name;
+	rwlock_t		lock;
+	u32			devnum;
+	struct device_class	* devclass;
+
+	struct list_head	node;
+	struct driver_dir_entry	dir;
+
+	int (*add_device)(struct device *);
+	int (*add_device)(struct intf_data *);
+};
+
+int interface_register(struct device_interface *);
+void interface_unregister(struct device_interface *);
+
+
+An interface must specify the device class it belongs to. It is added
+to that class's list of interfaces on registration.
+
+
+Interfaces can be added to a device class at any time. Whenever it is
+added, each device in the class is passed to the interface's
+add_device callback. When an interface is removed, each device is
+removed from the interface.
+
+
+Devices
+~~~~~~~
+Once a device is added to a device class, it is added to each
+interface that is registered with the device class. The class
+is expected to place a class-specific data structure in 
+struct device::class_data. The interface can use that (along with
+other fields of struct device) to determine whether or not the driver
+and/or device support that particular interface.
+
+
+Data
+~~~~
+
+struct intf_data {
+	struct list_head	node;
+	struct device_interface	* intf;
+	struct device 		* dev;
+	u32			intf_num;
+};
+
+int interface_add_data(struct interface_data *);
+
+The interface is responsible for allocating and initializing a struct 
+intf_data and calling interface_add_data() to add it to the device's list
+of interfaces it belongs to. This list will be iterated over when the device
+is removed from the class (instead of all possible interfaces for a class).
+This structure should probably be embedded in whatever per-device data 
+structure the interface is allocating anyway.
+   
+Devices are enumerated within the interface. This happens in interface_add_data()
+and the enumerated value is stored in the struct intf_data for that device. 
+
+driverfs
+~~~~~~~~
+Each interface is given a directory in the directory of the device
+class it belongs to:
+
+Interfaces get a directory in the class's directory as well:
+
+   class/
+   `-- input
+       |-- devices
+       |-- drivers
+       |-- mouse
+       `-- evdev
+
+When a device is added to the interface, a symlink is created that points 
+to the device's directory in the physical hierarchy:
+
+   class/
+   `-- input
+       |-- devices
+       |   `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/
+       |-- drivers
+       |   `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/
+       |-- mouse
+       |   `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/
+       `-- evdev
+           `-- 1 -> ../../../root/pci0/00:1f.0/usb_bus/00:1f.2-1:0/
+
+
+Future Plans
+~~~~~~~~~~~~
+A device interface is correlated directly with a userspace interface
+for a device, specifically a device node. For instance, a SCSI disk
+exposes at least two interfaces to userspace: the standard SCSI disk
+interface and the SCSI generic interface. It might also export a raw
+device interface. 
+
+Many interfaces have a major number associated with them and each
+device gets a minor number. Or, multiple interfaces might share one
+major number, and each get receive a range of minor numbers (like in
+the case of input devices).
+
+These major and minor numbers could be stored in the interface
+structure. Major and minor allocation could happen when the interface
+is registered with the class, or via a helper function. 
+

Documentation/driver-model/overview.txt

+The Linux Kernel Device Model
+
+Patrick Mochel	<mochel@osdl.org>
+
+26 August 2002
+
+
+Overview
+~~~~~~~~
+
+This driver model is a unification of all the current, disparate driver models
+that are currently in the kernel. It is intended is to augment the
+bus-specific drivers for bridges and devices by consolidating a set of data
+and operations into globally accessible data structures.
+
+Current driver models implement some sort of tree-like structure (sometimes
+just a list) for the devices they control. But, there is no linkage between
+the different bus types.
+
+A common data structure can provide this linkage with little overhead: when a
+bus driver discovers a particular device, it can insert it into the global
+tree as well as its local tree. In fact, the local tree becomes just a subset
+of the global tree.
+
+Common data fields can also be moved out of the local bus models into the
+global model. Some of the manipulation of these fields can also be
+consolidated. Most likely, manipulation functions will become a set
+of helper functions, which the bus drivers wrap around to include any
+bus-specific items.
+
+The common device and bridge interface currently reflects the goals of the
+modern PC: namely the ability to do seamless Plug and Play, power management,
+and hot plug. (The model dictated by Intel and Microsoft (read: ACPI) ensures
+us that any device in the system may fit any of these criteria.)
+
+In reality, not every bus will be able to support such operations. But, most
+buses will support a majority of those operations, and all future buses will.
+In other words, a bus that doesn't support an operation is the exception,
+instead of the other way around.
+
+
+
+Downstream Access
+~~~~~~~~~~~~~~~~~
+
+Common data fields have been moved out of individual bus layers into a common
+data structure. But, these fields must still be accessed by the bus layers,
+and sometimes by the device-specific drivers.
+
+Other bus layers are encouraged to do what has been done for the PCI layer.
+struct pci_dev now looks like this:
+
+struct pci_dev {
+	...
+
+	struct device device;
+};
+
+Note first that it is statically allocated. This means only one allocation on
+device discovery. Note also that it is at the _end_ of struct pci_dev. This is
+to make people think about what they're doing when switching between the bus
+driver and the global driver; and to prevent against mindless casts between
+the two.
+
+The PCI bus layer freely accesses the fields of struct device. It knows about
+the structure of struct pci_dev, and it should know the structure of struct
+device. PCI devices that have been converted generally do not touch the fields
+of struct device. More precisely, device-specific drivers should not touch
+fields of struct device unless there is a strong compelling reason to do so.
+
+This abstraction is prevention of unnecessary pain during transitional phases.
+If the name of the field changes or is removed, then every downstream driver
+will break. On the other hand, if only the bus layer (and not the device
+layer) accesses struct device, it is only those that need to change.
+
+
+User Interface
+~~~~~~~~~~~~~~
+
+By virtue of having a complete hierarchical view of all the devices in the
+system, exporting a complete hierarchical view to userspace becomes relatively
+easy. This has been accomplished by implementing a special purpose virtual
+file system named driverfs. It is hence possible for the user to mount the
+whole driverfs filesystem anywhere in userspace.
+
+This can be done permanently by providing the following entry into the
+/etc/fstab (under the provision that the mount point does exist, of course):
+
+none     	/devices	driverfs    defaults		0	0
+
+Or by hand on the command line:
+
+~: mount -t driverfs none /devices
+
+Whenever a device is inserted into the tree, a directory is created for it.
+This directory may be populated at each layer of discovery - the global layer,
+the bus layer, or the device layer.
+
+The global layer currently creates two files - name and 'power'. The
+former only reports the name of the device. The latter reports the
+current power state of the device. It also be used to set the current
+power state. 
+
+The bus layer may also create files for the devices it finds while probing the
+bus. For example, the PCI layer currently creates 'irq' and 'resource' files
+for each PCI device.
+
+A device-specific driver may also export files in its directory to expose
+device-specific data or tunable interfaces.
+
+More information about the driverfs directory layout can be found in
+the other documents in this directory and in the file 
+Documentation/filesystems/driverfs.txt.
+

Documentation/driver-model/platform.txt

+Platform Devices and Drivers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Platform devices
+~~~~~~~~~~~~~~~~
+Platform devices are devices that typically appear as autonomous
+entities in the system. This includes legacy port-based devices and
+host bridges to peripheral buses. 
+
+
+Platform drivers
+~~~~~~~~~~~~~~~~
+Drivers for platform devices have typically very simple and
+unstructured. Either the device was present at a particular I/O port
+and the driver was loaded, or there was not. There was no possibility
+of hotplugging or alternative discovery besides probing at a specific
+I/O address and expecting a specific response.
+
+
+Other Architectures, Modern Firmware, and new Platforms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+These devices are not always at the legacy I/O ports. This is true on
+other architectures and on some modern architectures. In most cases,
+the drivers are modified to discover the devices at other well-known
+ports for the given platform. However, the firmware in these systems
+does usually know where exactly these devices reside, and in some
+cases, it's the only way of discovering them. 
+
+
+The Platform Bus
+~~~~~~~~~~~~~~~~
+A platform bus has been created to deal with these issues. First and
+foremost, it groups all the legacy devices under a common bus, and
+gives them a common parent if they don't already have one. 
+
+But, besides the organizational benefits, the platform bus can also
+accomodate firmware-based enumeration. 
+
+
+Device Discovery
+~~~~~~~~~~~~~~~~
+The platform bus has no concept of probing for devices. Devices
+discovery is left up to either the legacy drivers or the
+firmware. These entities are expected to notify the platform of
+devices that it discovers via the bus's add() callback:
+
+	platform_bus.add(parent,bus_id).
+
+
+Bus IDs
+~~~~~~~
+Bus IDs are the canonical name for the device. There is no globally
+standard addressing mechanism for legacy devices. In the IA-32 world,
+we have Pnp IDs to use, as well as the legacy I/O ports. However,
+neither tell what the device really is or have any meaning on other
+platforms. 
+
+Since both PnP IDs and the legacy I/O ports (and other standard I/O
+ports for specific devices) have a 1:1 mapping, we map the
+platform-specific name or identifier to a generic name (at least
+within the scope of the kernel).
+
+For example, a serial driver might find a device at I/O 0x3f8. The
+ACPI firmware might also discover a device with PnP ID (_HID)
+PNP0501. Both correspond to the same device should be mapped to the
+canonical name 'serial'. 
+
+The bus_id field should be a concatenation of the canonical name and
+the instance of that type of device. For example, the device at I/O
+port 0x3f8 should have a bus_id of "serial0". This places the
+responsibility of enumerating devices of a particular type up to the
+discovery mechanism. But, they are the entity that should know best
+(as opposed to the platform bus driver).
+
+
+Drivers 
+~~~~~~~
+Drivers for platform devices should have a name that is the same as
+the canonical name of the devices they support. This allows the
+platform bus driver to do simple matching with the basic data
+structures to determine if a driver supports a certain device. 
+
+For example, a legacy serial driver should have a name of 'serial' and
+register itself with the platform bus. 
+
+
+Driver Binding
+~~~~~~~~~~~~~~
+Legacy drivers assume they are bound to the device once they start up
+and probe an I/O port. Divorcing them from this will be a difficult
+process. However, that shouldn't prevent us from impelementing
+firmware-based enumeration. 
+
+The firmware should notify the platform bus about devices before the
+legacy drivers have had a chance to load. Once the drivers are loaded,
+they driver model core will attempt to bind the driver to any
+previously-discovered devices. Once that has happened, it will be free
+to discover any other devices it pleases.
+

drivers/base/Makefile

 # Makefile for the Linux device tree
 
 obj-y		:= core.o sys.o interface.o power.o bus.o \
-			driver.o class.o intf.o
+			driver.o class.o intf.o platform.o
 
 obj-y		+= fs/
 

drivers/base/core.c

@@ -97,15 +97,10 @@ static int device_attach(struct device * dev)
 
 static void device_detach(struct device * dev)
 {
-	struct device_driver * drv; 
+	struct device_driver * drv = dev->driver;
 
-	if (dev->driver) {
+	if (drv) {
 		devclass_remove_device(dev);
-		spin_lock(&device_lock);
-		drv = dev->driver;
-		spin_unlock(&device_lock);
-
-		/* detach from driver */
 		if (drv && drv->remove)
 			drv->remove(dev);
 

drivers/base/platform.c

+/*
+ * platform.c - platform 'psuedo' bus for legacy devices
+ *
+ * Please see Documentation/driver-model/platform.txt for more
+ * information.
+ */
+
+#include <linux/device.h>
+#include <linux/module.h>
+#include <linux/init.h>
+
+static int platform_match(struct device * dev, struct device_driver * drv)
+{
+	return 0;
+}
+
+struct bus_type platform_bus = {
+	.name		= "platform",
+	.match		= platform_match,
+};
+
+static int __init platform_bus_init(void)
+{
+	return bus_register(&platform_bus);
+}
+
+postcore_initcall(platform_bus_init);

drivers/base/power.c

@@ -92,13 +92,13 @@ void device_resume(u32 level)
  */
 void device_shutdown(void)
 {
-	struct list_head * node;
+	struct list_head * node, * next;
 	struct device * prev = NULL;
 
 	printk(KERN_EMERG "Shutting down devices\n");
 
 	spin_lock(&device_lock);
-	list_for_each(node,&global_device_list) {
+	list_for_each_safe(node,next,&global_device_list) {
 		struct device * dev = get_device_locked(to_dev(node));
 		if (dev) {
 			spin_unlock(&device_lock);
@@ -111,6 +111,8 @@ void device_shutdown(void)
 		}
 	}
 	spin_unlock(&device_lock);
+	if (prev)
+		put_device(prev);
 }
 
 EXPORT_SYMBOL(device_suspend);

drivers/pci/probe.c

@@ -444,6 +444,8 @@ struct pci_dev * __devinit pci_scan_device(struct pci_dev *temp)
 		return NULL;
 	}
 
+	pci_name_device(dev);
+
 	/* now put in global tree */
 	strcpy(dev->dev.name,dev->name);
 	strcpy(dev->dev.bus_id,dev->slot_name);
@@ -471,7 +473,6 @@ struct pci_dev * __devinit pci_scan_slot(struct pci_dev *temp)
 		dev = pci_scan_device(temp);
 		if (!dev)
 			continue;
-		pci_name_device(dev);
 		if (!func) {
 			is_multi = hdr_type & 0x80;
 			first_dev = dev;

fs/driverfs/inode.c

@@ -150,7 +150,6 @@ static int driverfs_mknod(struct inode *dir, struct dentry *dentry, int mode, in
 	inode = driverfs_get_inode(dir->i_sb, mode, dev);
 	if (inode) {
 		d_instantiate(dentry, inode);
-		dget(dentry);
 		error = 0;
 	}
 	return error;
@@ -223,48 +222,10 @@ static int driverfs_unlink(struct inode *dir, struct dentry *dentry)
 	struct inode *inode = dentry->d_inode;
 	down(&inode->i_sem);
 	dentry->d_inode->i_nlink--;
-	dput(dentry);
 	up(&inode->i_sem);
-	d_delete(dentry);
-	return 0;
-}
-
-static void d_unhash(struct dentry *dentry)
-{
-	dget(dentry);
-	spin_lock(&dcache_lock);
-	switch (atomic_read(&dentry->d_count)) {
-	default:
-		spin_unlock(&dcache_lock);
-		shrink_dcache_parent(dentry);
-		spin_lock(&dcache_lock);
-		if (atomic_read(&dentry->d_count) != 2)
-			break;
-	case 2:
-		list_del_init(&dentry->d_hash);
-	}
-	spin_unlock(&dcache_lock);
-}
-
-static int driverfs_rmdir(struct inode *dir, struct dentry *dentry)
-{
-	int error = -ENOTEMPTY;
-	struct inode * inode = dentry->d_inode;
-
-	down(&inode->i_sem);
-	d_unhash(dentry);
-	if (driverfs_empty(dentry)) {
-		dentry->d_inode->i_nlink -= 2;
-		dput(dentry);
-		inode->i_flags |= S_DEAD;
-		dir->i_nlink--;
-		error = 0;
-	}
-	up(&inode->i_sem);
-	if (!error)
-		d_delete(dentry);
+	d_invalidate(dentry);
 	dput(dentry);
-	return error;
+	return 0;
 }
 
 /**
@@ -622,9 +583,6 @@ driverfs_create_file(struct attribute * entry,
 	if (!entry || !parent)
 		return -EINVAL;
 
-	/* make sure we're mounted */
-	get_mount();
-
 	if (!parent->dentry) {
 		put_mount();
 		return -EINVAL;
@@ -638,8 +596,6 @@ driverfs_create_file(struct attribute * entry,
 	} else
 		error = PTR_ERR(dentry);
 	up(&parent->dentry->d_inode->i_sem);
-	if (error)
-		put_mount();
 	return error;
 }
 
@@ -659,8 +615,6 @@ int driverfs_create_symlink(struct driver_dir_entry * parent,
 	if (!parent)
 		return -EINVAL;
 
-	get_mount();
-
 	if (!parent->dentry) {
 		put_mount();
 		return -EINVAL;
@@ -672,8 +626,6 @@ int driverfs_create_symlink(struct driver_dir_entry * parent,
 	else
 		error = PTR_ERR(dentry);
 	up(&parent->dentry->d_inode->i_sem);
-	if (error)
-		put_mount();
 	return error;
 }
 
@@ -699,8 +651,6 @@ void driverfs_remove_file(struct driver_dir_entry * dir, const char * name)
 		if (dentry->d_inode && 
 		    (dentry->d_parent->d_inode == dir->dentry->d_inode)) {
 			driverfs_unlink(dir->dentry->d_inode,dentry);
-			dput(dentry);
-			put_mount();
 		}
 	}
 	up(&dir->dentry->d_inode->i_sem);
@@ -711,33 +661,39 @@ void driverfs_remove_file(struct driver_dir_entry * dir, const char * name)
  * @dir:	directory to remove
  *
  * To make sure we don't orphan anyone, first remove
- * all the children in the list, then do vfs_rmdir() to remove it
- * and decrement the refcount..
+ * all the children in the list, then do clean up the directory.
  */
 void driverfs_remove_dir(struct driver_dir_entry * dir)
 {
-	struct list_head * node;
+	struct list_head * node, * next;
 	struct dentry * dentry = dir->dentry;
+	struct dentry * parent;
 
 	if (!dentry)
 		goto done;
 
-	down(&dentry->d_parent->d_inode->i_sem);
+	parent = dget(dentry->d_parent);
+	down(&parent->d_inode->i_sem);
 	down(&dentry->d_inode->i_sem);
 
-	node = dentry->d_subdirs.next;
-	while (node != &dentry->d_subdirs) {
+	list_for_each_safe(node,next,&dentry->d_subdirs) {
 		struct dentry * d = list_entry(node,struct dentry,d_child);
+		/* make sure dentry is still there */
+		if (d->d_inode)
+			driverfs_unlink(dentry->d_inode,d);
+	}
 
-		node = node->next;
-		driverfs_unlink(dentry->d_inode,d);
-		dput(d);
-		put_mount();
+	d_invalidate(dentry);
+	if (driverfs_empty(dentry)) {
+		dentry->d_inode->i_nlink -= 2;
+		dentry->d_inode->i_flags |= S_DEAD;
+		parent->d_inode->i_nlink--;
 	}
 	up(&dentry->d_inode->i_sem);
-	driverfs_rmdir(dentry->d_parent->d_inode,dentry);
-	up(&dentry->d_parent->d_inode->i_sem);
 	dput(dentry);
+
+	up(&parent->d_inode->i_sem);
+	dput(parent);
  done:
 	put_mount();
 }

include/linux/device.h

@@ -65,7 +65,8 @@ struct bus_type {
 	struct driver_dir_entry	device_dir;
 	struct driver_dir_entry	driver_dir;
 
-	int	(*match)	(struct device * dev, struct device_driver * drv);
+	int		(*match)(struct device * dev, struct device_driver * drv);
+	struct device * (*add)	(struct device * parent, char * bus_id);
 };
 
 
@@ -281,6 +282,8 @@ struct device {
 	void		*driver_data;	/* data private to the driver */
 
 	u32		class_num;	/* class-enumerated value */
+	void		* class_data;	/* class-specific data */
+
 	void		*platform_data;	/* Platform specific data (e.g. ACPI,
 					   BIOS data relevant to device) */
 
@@ -378,6 +381,9 @@ extern void put_device(struct device * dev);
 extern int register_sys_device(struct device * dev);
 extern void unregister_sys_device(struct device * dev);
 
+/* drivers/base/platform.c */
+extern struct bus_type platform_bus;
+
 /* drivers/base/power.c */
 extern int device_suspend(u32 state, u32 level);
 extern void device_resume(u32 level);