[PATCH] Driver Core: driver model doc update

From: Greg KH
Date: Mon Jun 20 2005 - 22:21:18 EST

[PATCH] Driver Core: driver model doc update

This updates some driver data documentation:

- removes references to some fields that haven't been there for a
long time now, e.g. pre-kobject or even older;

- giving more information about the probe() method;

- adding an example of how platform_data is used

Signed-off-by: David Brownell <dbrownell@xxxxxxxxxxxxxxxxxxxxx>
Signed-off-by: Greg Kroah-Hartman <gregkh@xxxxxxx>

---
commit 4109aca06cb7b042ea791d0f9d3c9615bc3bf5cd
tree 36312d5fe016d507ec0682de914e1ac6b66c3246
parent 4b45099b75832434c5113b9aed1499f8a69d13d5
author David Brownell <david-b@xxxxxxxxxxx> Mon, 16 May 2005 17:19:55 -0700
committer Greg Kroah-Hartman <gregkh@xxxxxxx> Mon, 20 Jun 2005 15:15:29 -0700

Documentation/driver-model/device.txt | 8 +++++
Documentation/driver-model/driver.txt | 51 ++++++++++++++++-----------------
2 files changed, 33 insertions(+), 26 deletions(-)

diff --git a/Documentation/driver-model/device.txt b/Documentation/driver-model/device.txt
--- a/Documentation/driver-model/device.txt
+++ b/Documentation/driver-model/device.txt
@@ -76,6 +76,14 @@ 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
diff --git a/Documentation/driver-model/driver.txt b/Documentation/driver-model/driver.txt
--- a/Documentation/driver-model/driver.txt
+++ b/Documentation/driver-model/driver.txt
@@ -5,21 +5,17 @@ struct device_driver {
char * name;
struct bus_type * bus;

- rwlock_t lock;
- atomic_t refcount;
-
- list_t bus_list;
+ struct completion unloaded;
+ struct kobject kobj;
list_t devices;

- struct driver_dir_entry dir;
+ struct module *owner;

int (*probe) (struct device * dev);
int (*remove) (struct device * dev);

int (*suspend) (struct device * dev, pm_message_t state, u32 level);
int (*resume) (struct device * dev, u32 level);
-
- void (*release) (struct device_driver * drv);
};


@@ -51,7 +47,6 @@ being converted completely to the new mo
static struct device_driver eepro100_driver = {
.name = "eepro100",
.bus = &pci_bus_type,
- .devclass = &ethernet_devclass, /* when it's implemented */

.probe = eepro100_probe,
.remove = eepro100_remove,
@@ -85,7 +80,6 @@ static struct pci_driver eepro100_driver
.driver = {
.name = "eepro100",
.bus = &pci_bus_type,
- .devclass = &ethernet_devclass, /* when it's implemented */
.probe = eepro100_probe,
.remove = eepro100_remove,
.suspend = eepro100_suspend,
@@ -166,27 +160,32 @@ Callbacks

int (*probe) (struct device * dev);

-probe is called to verify the existence of a certain type of
-hardware. This is called during the driver binding process, after the
-bus has verified that the device ID of a device matches one of the
-device IDs supported by the driver.
-
-This callback only verifies that there actually is supported hardware
-present. It may allocate a driver-specific structure, but it should
-not do any initialization of the hardware itself. The device-specific
-structure may be stored in the device's driver_data field.
-
- int (*init) (struct device * dev);
-
-init is called during the binding stage. It is called after probe has
-successfully returned and the device has been registered with its
-class. It is responsible for initializing the hardware.
+The probe() entry is called in task context, with the bus's rwsem locked
+and the driver partially bound to the device. Drivers commonly use
+container_of() to convert "dev" to a bus-specific type, both in probe()
+and other routines. That type often provides device resource data, such
+as pci_dev.resource[] or platform_device.resources, which is used in
+addition to dev->platform_data to initialize the driver.
+
+This callback holds the driver-specific logic to bind the driver to a
+given device. That includes verifying that the device is present, that
+it's a version the driver can handle, that driver data structures can
+be allocated and initialized, and that any hardware can be initialized.
+Drivers often store a pointer to their state with dev_set_drvdata().
+When the driver has successfully bound itself to that device, then probe()
+returns zero and the driver model code will finish its part of binding
+the driver to that device.
+
+A driver's probe() may return a negative errno value to indicate that
+the driver did not bind to this device, in which case it should have
+released all reasources it allocated.

int (*remove) (struct device * dev);

-remove is called to dissociate a driver with a device. This may be
+remove is called to unbind a driver from a device. This may be
called if a device is physically removed from the system, if the
-driver module is being unloaded, or during a reboot sequence.
+driver module is being unloaded, during a reboot sequence, or
+in other cases.

It is up to the driver to determine if the device is present or
not. It should free any resources allocated specifically for the

-
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/