Skip to contentSkip to conversation

driver-core: improve driver binding documentation

PATCH Applied Danilo Krummrich 3 participants 3 messages Jan 15 – Jan 16

Subsystems (2)
lore
Share & tools
lore

Danilo Krummrich

author maintainer
#0 lore raw

PATCH 1/1 driver-core: improve driver binding documentation

The driver binding documentation (still) mentions that "When a driver is attached to a device, the device is inserted into the driver's list of devices.".

While it is true that the driver-core keeps track of all the devices that are attached to a driver, this is purely for internal purposes (i.e. it is an implementation detail) and has no relevance for user facing documentation.

In fact, it is even misleading, since it could be read as if it were valid for driver implementations to keep track of all the devices bound to it.

Instead, drivers operate on a per-device basis, with a separate per-device instance created when the driver is bound to a device.

Hence, remove the mention of a driver's list of devices and instead add some documentation of the relationship between drivers and devices.

---
 Documentation/driver-api/driver-model/binding.rst | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)
Documentation/driver-api/driver-model/binding.rst +6 -3
index 7ea1d7a41e1d..d1d311a4011f 100644
@@ -53,9 +53,12 @@ class's register_dev callback.
 Driver
 ~~~~~~
 
-When a driver is attached to a device, the device is inserted into the
-driver's list of devices.
-
+When a driver is attached to a device, the driver's probe() function is
+called. Within probe(), the driver initializes the device and allocates
+and initializes per-device data structures. This per-device state is
+associated with the device object for as long as the driver remains bound
+to it. Conceptually, this per-device data together with the binding to
+the device can be thought of as an instance of the driver.
 
 sysfs
 ~~~~~
Signature · 1 line
2.52.0
maintainer Reviewed-by on v1 1/1
#1 lore raw
Quoted 47 lines · Danilo Krummrich

The driver binding documentation (still) mentions that "When a driver is attached to a device, the device is inserted into the driver's list of devices.".

While it is true that the driver-core keeps track of all the devices that are attached to a driver, this is purely for internal purposes (i.e. it is an implementation detail) and has no relevance for user facing documentation.

In fact, it is even misleading, since it could be read as if it were valid for driver implementations to keep track of all the devices bound to it.

Instead, drivers operate on a per-device basis, with a separate per-device instance created when the driver is bound to a device.

Hence, remove the mention of a driver's list of devices and instead add some documentation of the relationship between drivers and devices.

---
 Documentation/driver-api/driver-model/binding.rst | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)
Documentation/driver-api/driver-model/binding.rst +6 -3
index 7ea1d7a41e1d..d1d311a4011f 100644
@@ -53,9 +53,12 @@ class's register_dev callback.
 Driver
 ~~~~~~
 
-When a driver is attached to a device, the device is inserted into the
-driver's list of devices.
-
+When a driver is attached to a device, the driver's probe() function is
+called. Within probe(), the driver initializes the device and allocates
+and initializes per-device data structures. This per-device state is
+associated with the device object for as long as the driver remains bound
+to it. Conceptually, this per-device data together with the binding to
+the device can be thought of as an instance of the driver.
 
 sysfs
 ~~~~~
Signature · 1 line
2.52.0

Wow that was written a long time ago, thanks for updating it.

maintainer Applied
#2 lore raw
In reply to Danilo Krummrich
Quoted 31 lines · Danilo Krummrich

The driver binding documentation (still) mentions that "When a driver is attached to a device, the device is inserted into the driver's list of devices.".

While it is true that the driver-core keeps track of all the devices that are attached to a driver, this is purely for internal purposes (i.e. it is an implementation detail) and has no relevance for user facing documentation.

In fact, it is even misleading, since it could be read as if it were valid for driver implementations to keep track of all the devices bound to it.

Instead, drivers operate on a per-device basis, with a separate per-device instance created when the driver is bound to a device.

Hence, remove the mention of a driver's list of devices and instead add some documentation of the relationship between drivers and devices.

---
 Documentation/driver-api/driver-model/binding.rst | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)
Documentation/driver-api/driver-model/binding.rst +0 -0
index 7ea1d7a41e1d..d1d311a4011f 100644
@@ -53,9 +53,12 @@ class's register_dev callback.
 Driver
 ~~~~~~

Documentation/driver-api/driver-model/binding.rst class's register_dev callback. · line 61

Quoted 10 lines
Documentation/driver-api/driver-model/binding.rst +6 -3
 
-When a driver is attached to a device, the device is inserted into the
-driver's list of devices.
-
+When a driver is attached to a device, the driver's probe() function is
+called. Within probe(), the driver initializes the device and allocates
+and initializes per-device data structures. This per-device state is
+associated with the device object for as long as the driver remains bound
+to it. Conceptually, this per-device data together with the binding to
+the device can be thought of as an instance of the driver.

Applied, thanks.

jon