Skip to contentSkip to conversation

device property: Add a note to the fwnode.h

PATCH Superseded Andy Shevchenko 3 participants 6 messages Mar 31, 2025 – Apr 8, 2025

Subsystems (3)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore

Andy Shevchenko

author reviewer
#0 lore raw

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

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.

---

v2: added "...into the driver" piece at the end to remove ambiguity

 include/linux/fwnode.h | 6 ++++++
 1 file changed, 6 insertions(+)
include/linux/fwnode.h +6 -0
index 6fa0a268d538..4c4d3f93534c 100644
@@ -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 <[email protected]>
  */
Signature · 1 line
2.47.2
#1 lore raw
Quoted 6 lines · Andy Shevchenko

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

author reviewer
#2 lore raw
Quoted 9 lines · Zijun Hu
Quoted 5 lines · Andy Shevchenko

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

Signature · 2 lines
With Best Regards,
Andy Shevchenko
#3 lore raw
In reply to Andy Shevchenko
Quoted 17 lines · 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.

---

v2: added "...into the driver" piece at the end to remove ambiguity

 include/linux/fwnode.h | 6 ++++++
 1 file changed, 6 insertions(+)
include/linux/fwnode.h +0 -0
index 6fa0a268d538..4c4d3f93534c 100644

include/linux/fwnode.h line 6

Quoted 5 lines
include/linux/fwnode.h +2 -0
@@ -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

include/linux/fwnode.h line 9

Quoted 3 lines
include/linux/fwnode.h +3 -0
+ * 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.

Quoted 4 lines
include/linux/fwnode.h +1 -0
+ *
  * Copyright (C) 2015, Intel Corporation
  * Author: Rafael J. Wysocki <[email protected]>
  */
author reviewer
#4 lore raw
Quoted 4 lines · Zijun Hu
Quoted 3 lines · 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.

...

Quoted 15 lines
Quoted 2 lines

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

Quoted 3 lines

+ * 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)
   ^           ^         ^        ^
   |           |         |        |
Quoted 4 lines

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.

Signature · 2 lines
With Best Regards,
Andy Shevchenko
author reviewer
#5 lore raw
Quoted 2 lines · Andy Shevchenko
Quoted 1 line · Zijun Hu

On 2025/4/1 00:35, Andy Shevchenko wrote:

...

Quoted 12 lines
Quoted 12 lines
Quoted 3 lines

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

Quoted 5 lines
Quoted 2 lines

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.

Signature · 2 lines
With Best Regards,
Andy Shevchenko