[PATCH v2 1/1] device property: Add a note to the fwnode.h

[PATCH v2 1/1] device property: Add a note to the fwnode.h

[Andy Shevchenko]

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
+ * 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>
  */
-- 
2.47.2

Re: [PATCH v2 1/1] device property: Add a note to the fwnode.h

[Zijun Hu]

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 ?

Re: [PATCH v2 1/1] device property: Add a note to the fwnode.h

[Andy Shevchenko]

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.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v2 1/1] device property: Add a note to the fwnode.h

[Zijun Hu]

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>
>   */

Re: [PATCH v2 1/1] device property: Add a note to the fwnode.h

[Andy Shevchenko]

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.

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v2 1/1] device property: Add a note to the fwnode.h

[Andy Shevchenko]

On Fri, Apr 04, 2025 at 01:19:32PM +0300, Andy Shevchenko wrote:
> On Fri, Apr 04, 2025 at 10:59:41AM +0800, Zijun Hu wrote:
> > On 2025/4/1 00:35, Andy Shevchenko wrote:

...

> > > + * 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.

FWIW, Rafael proposed better wording which I'm going to use in v3 in the header.
Commit message would be similar, though.

-- 
With Best Regards,
Andy Shevchenko