* [PATCH 1/2] docs: driver-model: device: Add DEVICE_ATTR_{RO,RW} examples
2021-03-03 13:38 [PATCH 0/2] docs: driver-model: device: Add helper macro examples Geert Uytterhoeven
@ 2021-03-03 13:38 ` Geert Uytterhoeven
2021-03-03 13:38 ` [PATCH 2/2] docs: driver-model: device: Add ATTRIBUTE_GROUPS() example Geert Uytterhoeven
` (2 subsequent siblings)
3 siblings, 0 replies; 5+ messages in thread
From: Geert Uytterhoeven @ 2021-03-03 13:38 UTC (permalink / raw)
To: Jonathan Corbet, Greg Kroah-Hartman, Rafael J . Wysocki
Cc: linux-doc, linux-kernel, Geert Uytterhoeven
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 <geert+renesas@glider.be>
---
Documentation/driver-api/driver-model/device.rst | 10 ++++++++--
1 file changed, 8 insertions(+), 2 deletions(-)
diff --git a/Documentation/driver-api/driver-model/device.rst b/Documentation/driver-api/driver-model/device.rst
index b9b022371e856e83..41c819fafd9c1aee 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
--
2.25.1
^ permalink raw reply related [flat|nested] 5+ messages in thread
* [PATCH 2/2] docs: driver-model: device: Add ATTRIBUTE_GROUPS() example
2021-03-03 13:38 [PATCH 0/2] docs: driver-model: device: Add helper macro examples Geert Uytterhoeven
2021-03-03 13:38 ` [PATCH 1/2] docs: driver-model: device: Add DEVICE_ATTR_{RO,RW} examples Geert Uytterhoeven
@ 2021-03-03 13:38 ` Geert Uytterhoeven
2021-03-03 14:05 ` [PATCH 0/2] docs: driver-model: device: Add helper macro examples Greg Kroah-Hartman
2021-03-09 0:07 ` Jonathan Corbet
3 siblings, 0 replies; 5+ messages in thread
From: Geert Uytterhoeven @ 2021-03-03 13:38 UTC (permalink / raw)
To: Jonathan Corbet, Greg Kroah-Hartman, Rafael J . Wysocki
Cc: linux-doc, linux-kernel, Geert Uytterhoeven
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 <geert+renesas@glider.be>
---
Documentation/driver-api/driver-model/device.rst | 13 +++++++++----
1 file changed, 9 insertions(+), 4 deletions(-)
diff --git a/Documentation/driver-api/driver-model/device.rst b/Documentation/driver-api/driver-model/device.rst
index 41c819fafd9c1aee..0833be568b06cace 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
--
2.25.1
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [PATCH 0/2] docs: driver-model: device: Add helper macro examples
2021-03-03 13:38 [PATCH 0/2] docs: driver-model: device: Add helper macro examples Geert Uytterhoeven
2021-03-03 13:38 ` [PATCH 1/2] docs: driver-model: device: Add DEVICE_ATTR_{RO,RW} examples Geert Uytterhoeven
2021-03-03 13:38 ` [PATCH 2/2] docs: driver-model: device: Add ATTRIBUTE_GROUPS() example Geert Uytterhoeven
@ 2021-03-03 14:05 ` Greg Kroah-Hartman
2021-03-09 0:07 ` Jonathan Corbet
3 siblings, 0 replies; 5+ messages in thread
From: Greg Kroah-Hartman @ 2021-03-03 14:05 UTC (permalink / raw)
To: Geert Uytterhoeven
Cc: Jonathan Corbet, Rafael J . Wysocki, linux-doc, linux-kernel
On Wed, Mar 03, 2021 at 02:38:43PM +0100, Geert Uytterhoeven wrote:
> Hi Jon, Greg, Rafael,
>
> The DEVICE_ATTR_* and ATTRIBUTE_GROUPS() helper macros have existed for
> more than a decade, but are still not mentioned in the driver-model
> device documentation. Hence this patch series adds them, including
> examples, to the documentation.
>
> Thanks for your comments!
>
> Geert Uytterhoeven (2):
> docs: driver-model: device: Add DEVICE_ATTR_{RO,RW} examples
> docs: driver-model: device: Add ATTRIBUTE_GROUPS() example
Thanks for adding these:
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [PATCH 0/2] docs: driver-model: device: Add helper macro examples
2021-03-03 13:38 [PATCH 0/2] docs: driver-model: device: Add helper macro examples Geert Uytterhoeven
` (2 preceding siblings ...)
2021-03-03 14:05 ` [PATCH 0/2] docs: driver-model: device: Add helper macro examples Greg Kroah-Hartman
@ 2021-03-09 0:07 ` Jonathan Corbet
3 siblings, 0 replies; 5+ messages in thread
From: Jonathan Corbet @ 2021-03-09 0:07 UTC (permalink / raw)
To: Geert Uytterhoeven, Greg Kroah-Hartman, Rafael J . Wysocki
Cc: linux-doc, linux-kernel, Geert Uytterhoeven
Geert Uytterhoeven <geert+renesas@glider.be> writes:
> Hi Jon, Greg, Rafael,
>
> The DEVICE_ATTR_* and ATTRIBUTE_GROUPS() helper macros have existed for
> more than a decade, but are still not mentioned in the driver-model
> device documentation. Hence this patch series adds them, including
> examples, to the documentation.
>
> Thanks for your comments!
>
> Geert Uytterhoeven (2):
> docs: driver-model: device: Add DEVICE_ATTR_{RO,RW} examples
> docs: driver-model: device: Add ATTRIBUTE_GROUPS() example
>
> .../driver-api/driver-model/device.rst | 23 ++++++++++++++-----
> 1 file changed, 17 insertions(+), 6 deletions(-)
Set applied, thanks.
jon
^ permalink raw reply [flat|nested] 5+ messages in thread