[PATCH] Documentation: devicetree: mention when symbols are required in base DT

[PATCH] Documentation: devicetree: mention when symbols are required in base DT

[Ahmad Fatoum]

The barebox error message:

  ERROR: of_resolver: __symbols__ missing from base devicetree

can be a bit cryptic if unfamiliar with how overlays work internally.

Let's mention the error message in the documentation, so it turns up in
a search and add some extra information.

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 Documentation/user/devicetree.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/Documentation/user/devicetree.rst b/Documentation/user/devicetree.rst
index 91afffdcda76..9f46eee4ea95 100644
--- a/Documentation/user/devicetree.rst
+++ b/Documentation/user/devicetree.rst
@@ -83,6 +83,14 @@ barebox has support for device tree overlays. barebox knows two different trees,
 the live tree and the device tree the kernel is started with. Both can be applied
 overlays to.
 
+.. note:: Compiling a device tree discards label information by default. To be able
+ to use phandles into the base device tree from inside an overlay, pass to dtc the
+ ``-@`` option when compiling the base device tree.
+   This will populate ``/__symbols__`` in the base device tree.
+
+ Having ``__fixups__`` in the overlay, but no ``__symbols__`` in the base device
+ tree is not allowed: ``ERROR: of_resolver: __symbols__ missing from base devicetree``.
+
 Device tree overlays on the live tree
 .....................................
 
@@ -91,6 +99,9 @@ detect any changes to the live tree. To let the overlays have any effect, board
 code must make sure the live tree is patched before the devices are instanciated
 from it.
 
+The ``CONFIG_OF_OVERLAY_LIVE`` option will need to be enabled to generate
+``__symbols__`` into the barebox device tree.
+
 Device tree overlays on the kernel device tree
 ..............................................
 
@@ -118,3 +129,9 @@ the kernel. The behaviour is controlled by different variables:
   ``global.of.overlay.compatible`` above. The default is ``filepattern compatible``
   which means the two generic filters are active. This list may be replaced or
   supplemented by board specific filters.
+
+The kernel device trees need to be built with symbols (``dtc -@`` option) enabled.
+For upstream device trees, this is currently done on a case-by-case basis in the
+Makefiles::
+
+  DTC_FLAGS_bcm2711-rpi-4-b := -@
-- 
2.39.5

Re: [PATCH] Documentation: devicetree: mention when symbols are required in base DT

[Sascha Hauer]

On Mon, 26 May 2025 12:06:27 +0200, Ahmad Fatoum wrote:
> The barebox error message:
> 
>   ERROR: of_resolver: __symbols__ missing from base devicetree
> 
> can be a bit cryptic if unfamiliar with how overlays work internally.
> 
> Let's mention the error message in the documentation, so it turns up in
> a search and add some extra information.
> 
> [...]

Applied, thanks!

[1/1] Documentation: devicetree: mention when symbols are required in base DT
      https://git.pengutronix.de/cgit/barebox/commit/?id=977d7e7a448e (link may not be stable)

Best regards,
-- 
Sascha Hauer <s.hauer@pengutronix.de>