From 1364c67875251cd254c4fbbe10650e8a603493d8 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Thu, 25 Feb 2021 10:11:24 +0100 Subject: docs: driver-model: Remove obsolete device class documentation None of this is valid since v2.5.69. Signed-off-by: Geert Uytterhoeven Link: https://lore.kernel.org/r/20210225091124.686078-1-geert+renesas@glider.be Signed-off-by: Jonathan Corbet --- Documentation/driver-api/driver-model/class.rst | 149 ------------------------ Documentation/driver-api/driver-model/index.rst | 1 - 2 files changed, 150 deletions(-) delete mode 100644 Documentation/driver-api/driver-model/class.rst (limited to 'Documentation/driver-api') diff --git a/Documentation/driver-api/driver-model/class.rst b/Documentation/driver-api/driver-model/class.rst deleted file mode 100644 index fff55b80e86a..000000000000 --- a/Documentation/driver-api/driver-model/class.rst +++ /dev/null @@ -1,149 +0,0 @@ -============== -Device Classes -============== - -Introduction -~~~~~~~~~~~~ -A device class describes a type of device, like an audio or network -device. The following device classes have been identified: - - - - -Each device class defines a set of semantics and a programming interface -that devices of that class adhere to. Device drivers are the -implementation 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 *); - -See the kerneldoc for the struct class. - -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. - - -sysfs directory structure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -There is a top-level sysfs 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 to 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 -sysfs 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 sysfs. - - -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. diff --git a/Documentation/driver-api/driver-model/index.rst b/Documentation/driver-api/driver-model/index.rst index 755016422269..4831bdd92e5c 100644 --- a/Documentation/driver-api/driver-model/index.rst +++ b/Documentation/driver-api/driver-model/index.rst @@ -7,7 +7,6 @@ Driver Model binding bus - class design-patterns device devres -- cgit v1.2.3-59-g8ed1b From d944f0b1156c87c2c1994befab72816457ec738d Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Wed, 3 Mar 2021 14:38:44 +0100 Subject: docs: driver-model: device: Add DEVICE_ATTR_{RO,RW} examples bus.rst, driver.rst, and hwmon-kernel-api.rst refer to the DEVICE_ATTR_* macros for devices, but device.rst does not mention them. Add a paragraph about these helper macros, and use them in the examples. Retain the old description, as it is still useful for less common values of mode. Change the names of the example "show" and "store" methods, to match the expectations of the DEVICE_ATTR_* macros. Signed-off-by: Geert Uytterhoeven Reviewed-by: Greg Kroah-Hartman Link: https://lore.kernel.org/r/20210303133845.3939403-2-geert+renesas@glider.be Signed-off-by: Jonathan Corbet --- Documentation/driver-api/driver-model/device.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'Documentation/driver-api') diff --git a/Documentation/driver-api/driver-model/device.rst b/Documentation/driver-api/driver-model/device.rst index b9b022371e85..41c819fafd9c 100644 --- a/Documentation/driver-api/driver-model/device.rst +++ b/Documentation/driver-api/driver-model/device.rst @@ -63,8 +63,14 @@ Attributes are declared using a macro called DEVICE_ATTR:: Example::: - static DEVICE_ATTR(type, 0444, show_type, NULL); - static DEVICE_ATTR(power, 0644, show_power, store_power); + static DEVICE_ATTR(type, 0444, type_show, NULL); + static DEVICE_ATTR(power, 0644, power_show, power_store); + +Helper macros are available for common values of mode, so the above examples +can be simplified to::: + + static DEVICE_ATTR_RO(type); + static DEVICE_ATTR_RW(power); This declares two structures of type struct device_attribute with respective names 'dev_attr_type' and 'dev_attr_power'. These two attributes can be -- cgit v1.2.3-59-g8ed1b From 459d7ed81223ba4ed634d50231219c7a3f9f4a01 Mon Sep 17 00:00:00 2001 From: Geert Uytterhoeven Date: Wed, 3 Mar 2021 14:38:45 +0100 Subject: docs: driver-model: device: Add ATTRIBUTE_GROUPS() example Add a paragraph about the ATTRIBUTE_GROUPS() helper macro, and use it in the example. Retain the old description, as it is still useful in case of multiple groups. Change the names of the group(s) structures, to match the ATTRIBUTE_GROUPS() macro. Signed-off-by: Geert Uytterhoeven Reviewed-by: Greg Kroah-Hartman Link: https://lore.kernel.org/r/20210303133845.3939403-3-geert+renesas@glider.be Signed-off-by: Jonathan Corbet --- Documentation/driver-api/driver-model/device.rst | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) (limited to 'Documentation/driver-api') diff --git a/Documentation/driver-api/driver-model/device.rst b/Documentation/driver-api/driver-model/device.rst index 41c819fafd9c..0833be568b06 100644 --- a/Documentation/driver-api/driver-model/device.rst +++ b/Documentation/driver-api/driver-model/device.rst @@ -82,19 +82,24 @@ organized as follows into a group:: NULL, }; - static struct attribute_group dev_attr_group = { + static struct attribute_group dev_group = { .attrs = dev_attrs, }; - static const struct attribute_group *dev_attr_groups[] = { - &dev_attr_group, + static const struct attribute_group *dev_groups[] = { + &dev_group, NULL, }; +A helper macro is available for the common case of a single group, so the +above two structures can be declared using::: + + ATTRIBUTE_GROUPS(dev); + This array of groups can then be associated with a device by setting the group pointer in struct device before device_register() is invoked:: - dev->groups = dev_attr_groups; + dev->groups = dev_groups; device_register(dev); The device_register() function will use the 'groups' pointer to create the -- cgit v1.2.3-59-g8ed1b From 2379d15a7c303421689ab2a853553ec460fbb2c5 Mon Sep 17 00:00:00 2001 From: Bryan Brattlof Date: Tue, 23 Mar 2021 14:55:59 +0000 Subject: Documentation: gpio: chip should be plural Signed-off-by: Bryan Brattlof Reviewed-by: Linus Walleij Link: https://lore.kernel.org/r/20210323145509.139393-1-hello@bryanbrattlof.com Signed-off-by: Jonathan Corbet --- Documentation/driver-api/gpio/intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/driver-api') diff --git a/Documentation/driver-api/gpio/intro.rst b/Documentation/driver-api/gpio/intro.rst index 94dd7185e76e..2e924fb5b3d5 100644 --- a/Documentation/driver-api/gpio/intro.rst +++ b/Documentation/driver-api/gpio/intro.rst @@ -27,7 +27,7 @@ What is a GPIO? =============== A "General Purpose Input/Output" (GPIO) is a flexible software-controlled -digital signal. They are provided from many kinds of chip, and are familiar +digital signal. They are provided from many kinds of chips, and are familiar to Linux developers working with embedded and custom hardware. Each GPIO represents a bit connected to a particular pin, or "ball" on Ball Grid Array (BGA) packages. Board schematics show which external hardware connects to -- cgit v1.2.3-59-g8ed1b