| Message ID | 20250331163540.280606-1-andriy.shevchenko@linux.intel.com |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v2,1/1] device property: Add a note to the fwnode.h | expand |
On 4/1/2025 12:35 AM, Andy Shevchenko wrote: > + * Note, this header is not meant to be used by the leaf drivers. > + * It provides the low level data types and definitions for the firmware > + * and device property providers. The respective API headers should > + * guarantee all the required data types and definitions without including > + * this header directly into the driver. > + * sorry, i don't understand both "leaf drivers" and "respective API headers". could you have examples ?
On Thu, Apr 03, 2025 at 06:03:57PM +0800, Zijun Hu wrote: > On 4/1/2025 12:35 AM, Andy Shevchenko wrote: > > + * Note, this header is not meant to be used by the leaf drivers. > > + * It provides the low level data types and definitions for the firmware > > + * and device property providers. The respective API headers should > > + * guarantee all the required data types and definitions without including > > + * this header directly into the driver. > > sorry, i don't understand both "leaf drivers" and "respective API > headers". could you have examples ? leaf driver is like almost anything under drivers/iio, for example. The respective API headers is usually: of.h or property.h (the latter is highly preferred in a new code). TL;DR: the rule of thumb is do not include this until you know exactly what you are doing.
On 2025/4/1 00:35, Andy Shevchenko wrote: > Add a note to the fwnode.h that the header should not be used > directly in the leaf drivers, they all should use the higher > level APIs and the respective headers. > > Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com> > --- > > v2: added "...into the driver" piece at the end to remove ambiguity > > include/linux/fwnode.h | 6 ++++++ > 1 file changed, 6 insertions(+) > > diff --git a/include/linux/fwnode.h b/include/linux/fwnode.h > index 6fa0a268d538..4c4d3f93534c 100644 > --- a/include/linux/fwnode.h > +++ b/include/linux/fwnode.h > @@ -2,6 +2,12 @@ > /* > * fwnode.h - Firmware device node object handle type definition. > * > + * Note, this header is not meant to be used by the leaf drivers. > + * It provides the low level data types and definitions for the firmware Ack > + * and device property providers. The respective API headers should > + * guarantee all the required data types and definitions without including > + * this header directly into the driver. device property(include/linux/property.h) ^ | firmware node(include/linux/fwnode.h) ^ ^ ^ ^ | | | | DT ACPI SWNODE ... For various firmware implementations(DT|ACPI|SWNODE...), i feel we may allow them include fwnode.h by their header or source files. > + * > * Copyright (C) 2015, Intel Corporation > * Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> > */
On Fri, Apr 04, 2025 at 10:59:41AM +0800, Zijun Hu wrote: > On 2025/4/1 00:35, Andy Shevchenko wrote: > > Add a note to the fwnode.h that the header should not be used > > directly in the leaf drivers, they all should use the higher > > level APIs and the respective headers. ... > > + * Note, this header is not meant to be used by the leaf drivers. > > + * It provides the low level data types and definitions for the firmware > > Ack > > > + * and device property providers. The respective API headers should > > + * guarantee all the required data types and definitions without including > > + * this header directly into the driver. > > device property(include/linux/property.h) > ^ > | > firmware node(include/linux/fwnode.h) > ^ ^ ^ ^ > | | | | > DT ACPI SWNODE ... > > For various firmware implementations(DT|ACPI|SWNODE...), i feel we may > allow them include fwnode.h by their header or source files. That's the point, yes. And that's what exactly I put under the first sentence. The device property providers are not the leaf drivers in this sense.
diff --git a/include/linux/fwnode.h b/include/linux/fwnode.h index 6fa0a268d538..4c4d3f93534c 100644 --- a/include/linux/fwnode.h +++ b/include/linux/fwnode.h @@ -2,6 +2,12 @@ /* * fwnode.h - Firmware device node object handle type definition. * + * Note, this header is not meant to be used by the leaf drivers. + * It provides the low level data types and definitions for the firmware + * and device property providers. The respective API headers should + * guarantee all the required data types and definitions without including + * this header directly into the driver. + * * Copyright (C) 2015, Intel Corporation * Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> */
Add a note to the fwnode.h that the header should not be used directly in the leaf drivers, they all should use the higher level APIs and the respective headers. Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com> --- v2: added "...into the driver" piece at the end to remove ambiguity include/linux/fwnode.h | 6 ++++++ 1 file changed, 6 insertions(+)