Re: [PATCH] driver-core: improve driver binding documentation

[Jonathan Corbet <corbet@lwn.net>]

Danilo Krummrich <dakr@kernel.org> writes:

> 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.
>
> Signed-off-by: Danilo Krummrich <dakr@kernel.org>
> ---
>  Documentation/driver-api/driver-model/binding.rst | 9 ++++++---
>  1 file changed, 6 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/driver-api/driver-model/binding.rst b/Documentation/driver-api/driver-model/binding.rst
> index 7ea1d7a41e1d..d1d311a4011f 100644
> --- a/Documentation/driver-api/driver-model/binding.rst
> +++ b/Documentation/driver-api/driver-model/binding.rst
> @@ -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.

Applied, thanks.

jon