Skip to content

Instantly share code, notes, and snippets.

@sheharyaar

sheharyaar/dtschema.md

Created May 7, 2024 21:51
Show Gist options
  • Save sheharyaar/250cb215a79634129537164846e7f4c7 to your computer and use it in GitHub Desktop.
Save sheharyaar/250cb215a79634129537164846e7f4c7 to your computer and use it in GitHub Desktop.
Download ZIP
Steps to write yamls for Devicetree bindings and test them
Raw
dtschema.md

DTSchema YAMLs and deps

  1. First convert a Devicetree '.txt' to yaml. Let's take my patch for example : https://lore.kernel.org/all/20240423115749.15786-1-sheharyaar48@gmail.com/

  2. Check which architecture use the related drivers. In my patch the related drivers are (under the compatible) :

+  compatible:
+    const: nvidia,tegra20-ac97
  1. Search the dts and dtsi files where nvidia,tegra20-ac97 have been used. I use rg program (Github link) instead of grep :
$ rg "nvidia,tegra20-ac97"
sound/soc/tegra/tegra20_ac97.c
441:	{ .compatible = "nvidia,tegra20-ac97", },

Documentation/devicetree/bindings/sound/nvidia,tegra20-ac97.yaml
4:$id: http://devicetree.org/schemas/sound/nvidia,tegra20-ac97.yaml#
15:    const: nvidia,tegra20-ac97
71:        compatible = "nvidia,tegra20-ac97";

Next/merge.log
10540: .../bindings/sound/nvidia,tegra20-ac97.txt         |   36 -
10541: .../bindings/sound/nvidia,tegra20-ac97.yaml        |   82 +
10981: delete mode 100644 Documentation/devicetree/bindings/sound/nvidia,tegra20-ac97.txt
10982: create mode 100644 Documentation/devicetree/bindings/sound/nvidia,tegra20-ac97.yaml

arch/arm/boot/dts/nvidia/tegra20.dtsi               --> this here is a 'dtsi' file
379:		compatible = "nvidia,tegra20-ac97";

The architecture for this dts file is arm (from the file path).

dtsi files are included by other files, so we need to find those files as well

  1. Search dts files associated with the dtsi files (if any) :
$ rg "tegra20.dtsi"

arch/arm/boot/dts/nvidia/tegra20-acer-a500-picasso.dts
9:#include "tegra20.dtsi"

arch/arm/boot/dts/nvidia/tegra20-asus-tf101.dts
9:#include "tegra20.dtsi"

arch/arm/boot/dts/nvidia/tegra20-colibri.dtsi
2:#include "tegra20.dtsi"

arch/arm/boot/dts/nvidia/tegra20-tamonten.dtsi
2:#include "tegra20.dtsi"

arch/arm/boot/dts/nvidia/tegra20-paz00.dts
7:#include "tegra20.dtsi"

arch/arm/boot/dts/nvidia/tegra20-trimslice.dts
5:#include "tegra20.dtsi"

arch/arm/boot/dts/nvidia/tegra20-ventana.dts
6:#include "tegra20.dtsi"

arch/arm/boot/dts/nvidia/tegra20-harmony.dts
5:#include "tegra20.dtsi"

arch/arm/boot/dts/nvidia/tegra20-seaboard.dts
5:#include "tegra20.dtsi"

You can see a lot of files refer to this dtsi file. All these files must build without errors for making a correct patch.

Testing the binding

  1. I have x86_64 but I need to build for arm, so I need a cross-compiler. On Arch Linux, I need aarch64-linux-gnu-gcc package from AUR for this.

  2. After installing the required compiler you need to do the following to cross-compile :

  3. First run : make clean && make mrproper

  4. Then run : export CROSS_COMPILE=aarch64-linux-gnu- ARCH=arm KBUILD_OUTPUT=out/. This configures make to cross compile for arm using aarch64-linux-gnu- we installed earlier and the output files will be in out/ folder

  5. Now we need to make sure everything is clean and ready for the new arch, run : make clean && make mrproper

  6. Now we need a default config : make defconfig

  7. Now we are ready to test our binding.

  8. First we test our yaml file by :

# to test a single file
make clean && make -j8 dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/sound/nvidia,tegra30-i2s.yaml

# to test a directory
make clean && make dt_binding_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/usb/
  • I use make clean to be sure that my changes are being built. In the term -j8 replace 8 with the number of threads your cpu has : lscpu | egrep 'Model name|Socket|Thread|NUMA|CPU\(s\)'
  • Look at DT_SCHEMA_FILES, it should have the path oof your yaml file : DT_SCHEMA_FILES=<path to your yaml>
  1. Now we will test this yaml file against the dtb files which will be built using (Don't run make clean in the following commands) :
# to test against all the dtbs
$ make -j8 dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/sound/nvidia,tegra30-i2s.yaml

# to test only against a directory (here : arch/arm/boot/aspeed)
$ make -j8 dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/usb/usb-uhci.yaml arch/arm/boot/aspeed

General Tips

  • explain any new changes or if any variable you may have removed in the commit description
  • sometimes the dts and dtso files may have deprecated labels, you should fix them rather than modifying the yaml.
  • do not add too much examples in the yaml file, a single example is fine.
  • make sure to look around similar yamls for code inspiration and try to follow the pattern.
  • when making patches make sure to read the rules regarding commit message from the kernel documentation.

Resources

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment