Instructions for compiling device trees never worked

[ali1234]

https://www.raspberrypi.com/documentation/computers/configuration.html#device-trees-overlays-and-parameters

To reproduce:

1. Make a fresh install of Raspberry Pi OS Lite 64 bit
2. sudo apt install git bc bison flex libssl-dev make device-tree-compiler
3. git clone --depth 1 https://github.com/raspberrypi/linux
4. cd linux/arch/arm/boot/dts/overlays
5. dtc -@ -Hepapr -I dts -O dtb -o vc4-kms-v3d-pi5.dtbo vc4-kms-v3d-pi5-overlay.dts

Result:

Error: vc4-kms-v3d-pi5-overlay.dts:3.1-2 syntax error
FATAL ERROR: Unable to parse input tree

Now try the version of dtc built by the kernel itself:

1. cd ~/linux
2. KERNEL=kernel_2712
3. make bcm2712_defconfig
4. make dtbs
5. scripts/dtc/dtc -@ -Hepapr -I dts -O dtbo -o vc4-kms-v3d-pi5.dtbo arch/arm/boot/dts/overlays/vc4-kms-v3d-pi5-overlay.dts

Result:

Error: arch/arm/boot/dts/overlays/vc4-kms-v3d-pi5-overlay.dts:3.1-2 syntax error
FATAL ERROR: Unable to parse input tree

The specific part of the documentation that I find problematic:

If dtc returns an error about the third line, it doesn’t have the extensions required for overlay work. Run sudo apt install device-tree-compiler and try again - this time, compilation should complete successfully. Note that a suitable compiler is also available in the kernel tree as scripts/dtc/dtc, built when the dtbs make target is used:

It does appear to be complaining about the third line. But the version built by the kernel does exactly the same thing. It would be useful to have the actual error message in the docs here, so that I know if that's the problem I am facing.

PS running make dtbs did build vc4-kms-v3d-pi5.dtbo so it must be possible somehow.

PPS I'm trying to build that specific overlay because I need composite and HDMI to work at the same time, and I know that is possible because when you enable composite and boot with HDMI connected, the HDMI output is left switched on and displaying the last framebuffer it was sent. It just doesn't appear as an output in kms.

[lurch]

ping @pelwell

[pelwell]

The OP has missed the point - the comments are about the simple example presented in the docs (https://www.raspberrypi.com/documentation/computers/configuration.html#part2.1 - it's referred to as 1st-overlay.dts, and the third line is /plugin/;.

The problem with trying to build vc4-kms-v3d-pi5.dtbo by hand is that the overlays in the kernel tree tend to assume that the C preprocessor (cpp) has been run on the source file to expand #includes and perform macro substitution. This isn't a problem because the kernel's Makefiles take care of that, so make ... dtbs is the preferred way to build them.

For an example of the steps needed, take a look at overlaycheck in our utils repo. This (https://github.com/raspberrypi/utils/blob/master/overlaycheck/overlaycheck#L804) is a function that runs cpp before dtc, using the definition of @cpp_cmd created here (https://github.com/raspberrypi/utils/blob/master/overlaycheck/overlaycheck#L148).

[ali1234]

If I've missed the point, it's because the point is not covered in the documentation.

[pelwell]

Perhaps a note such as:

Overlays and .dts files found in the kernel source tree should be compiled using the kernel's makefiles, i.e. make ARCH=arm ... dtbs or make ARCH=arm64 ... dtbs. Running dtc manually is likely to lead to errors due to the use of cpp directives in the source.

[lurch]

☝️ @nathan-contino

[pelwell]

@ali1234 The utils repo has just gained another command - kdtc. It's a wrapper around dtc that runs the inputs through cpp. It also has a simple mode that allows you to write kdtc <input> <output> and have it do the right thing.