docs: dt: writing-schema: Document usage of CHECK_DTBS make flag
Subsystems (2)
PATCH 1/1 docs: dt: writing-schema: Document usage of CHECK_DTBS make flag
It is possible to run checks on a Devicetree by passing the CHECK_DTBS flag when building. This is a useful shortcut to the dtbs_check make target since it avoids checking unrelated Devicetrees, which can take some time and is unnecessary if no bindings were modified. Document it.
---
Documentation/devicetree/bindings/writing-schema.rst | 7 +++++++ 1 file changed, 7 insertions(+)
Documentation/devicetree/bindings/writing-schema.rst +7 -0
@@ -167,6 +167,13 @@ setting the ``DT_SCHEMA_FILES`` variable to a specific schema file or pattern. make dt_binding_check DT_SCHEMA_FILES=/gpio/ make dtbs_check DT_SCHEMA_FILES=trivial-devices.yaml +Note that ``make dtbs_check`` will validate every DT source file that is +enabled. When making changes to a DT but not to the bindings, a possible +shortcut to validate only the DT in question is to explicitly build it with +the ``CHECK_DTBS`` flag enabled. For example:: + + make CHECK_DTBS=y mediatek/mt8192-evb.dtb + json-schema Resources ---------------------
Signature · 1 line
2.38.1
AngeloGioacchino Del Regno
maintainerIl 02/11/22 22:43, Nícolas F. R. A. Prado ha scritto:
Quoted 16 lines
It is possible to run checks on a Devicetree by passing the
CHECK_DTBSflag when building. This is a useful shortcut to thedtbs_checkmake target since it avoids checking unrelated Devicetrees, which can take some time and is unnecessary if no bindings were modified. Document it.Signed-off-by Nícolas F. R. A. Prado <[email protected]>Quoted 1 line
---
Documentation/devicetree/bindings/writing-schema.rst | 7 +++++++ 1 file changed, 7 insertions(+)Documentation/devicetree/bindings/writing-schema.rst +0
-0
Documentation/devicetree/bindings/writing-schema.rst setting the ``DT_SCHEMA_FILES`` variable to a specific schema file or pattern. · line 170
Quoted 4 lines
Documentation/devicetree/bindings/writing-schema.rst +1
-0@@ -167,6 +167,13 @@ setting the ``DT_SCHEMA_FILES`` variable to a specific schema file or pattern. make dt_binding_check DT_SCHEMA_FILES=/gpio/ make dtbs_check DT_SCHEMA_FILES=trivial-devices.yaml +Note that ``make dtbs_check`` will validate every DT source file that is
"Note that xxxx" looks a bit repeated... read:
Note that ``dtbs_check`` will skip any binding schema files with errors. (etc etc)
Note that ``make dtbs_check`` will validate every DT source file ... (etc etc)
Perhaps we can change the first paragraph saying "In order to perform validation of DT source files, use..." to something like:
In order to perform validation of all DT source files, use the ``dtbs_check`` target, or set the ``CHECK_DTBS`` variable to ``y`` when building specific DTs::
::
make dtbs_check
make CHECK_DTBS=y mediatek/mt8192-evb.dtb
Any opinion?
Cheers,
Angelo
Quoted 36 lines · AngeloGioacchino Del Regno
Il 02/11/22 22:43, Nícolas F. R. A. Prado ha scritto:
Quoted 16 lines
It is possible to run checks on a Devicetree by passing the
CHECK_DTBSflag when building. This is a useful shortcut to thedtbs_checkmake target since it avoids checking unrelated Devicetrees, which can take some time and is unnecessary if no bindings were modified. Document it.Signed-off-by Nícolas F. R. A. Prado <[email protected]>Quoted 1 line
---
Documentation/devicetree/bindings/writing-schema.rst | 7 +++++++ 1 file changed, 7 insertions(+)Documentation/devicetree/bindings/writing-schema.rst +0
-0Documentation/devicetree/bindings/writing-schema.rst setting the ``DT_SCHEMA_FILES`` variable to a specific schema file or pattern. · line 169
Quoted 3 lines
Documentation/devicetree/bindings/writing-schema.rst +1
-0@@ -167,6 +167,13 @@ setting the ``DT_SCHEMA_FILES`` variable to a specific schema file or pattern. make dt_binding_check DT_SCHEMA_FILES=/gpio/ make dtbs_check DT_SCHEMA_FILES=trivial-devices.yaml +Note that ``make dtbs_check`` will validate every DT source file that is"Note that xxxx" looks a bit repeated... read:
Note that ``dtbs_check`` will skip any binding schema files with errors. (etc etc)
Note that ``make dtbs_check`` will validate every DT source file ... (etc etc)
Perhaps we can change the first paragraph saying "In order to perform validation of DT source files, use..." to something like:
In order to perform validation of all DT source files, use the ``dtbs_check`` target, or set the ``CHECK_DTBS`` variable to ``y`` when building specific DTs::
Quoted 6 lines
::
make
dtbs_check
make CHECK_DTBS=y mediatek/mt8192-evb.dtbAny opinion?
Something to keep in mind is that the purpose of this section is to describe how to validate binding changes (both on the binding itself and in the DTs that use them). For this, people really should be using dtbs_check since otherwise a new warning might be missed. Using CHECK_DTBS is more suitable for a different use case, which is to validate some dtbs without having changed the bindings, which is why I added it at the end of the section more as a side note. For this reason I think it's better to keep them separate.
About repeating the "Note that", that could just be changed for "It's worth noting that" or something similar.
Thanks,
Nícolas
Hi Nícolas,
Quoted 17 lines · Nícolas F. R. A. Prado
It is possible to run checks on a Devicetree by passing the
CHECK_DTBSflag when building. This is a useful shortcut to thedtbs_checkmake target since it avoids checking unrelated Devicetrees, which can take some time and is unnecessary if no bindings were modified. Document it.Signed-off-by Nícolas F. R. A. Prado <[email protected]>---
Documentation/devicetree/bindings/writing-schema.rst | 7 +++++++ 1 file changed, 7 insertions(+)Documentation/devicetree/bindings/writing-schema.rst +0
-0
Documentation/devicetree/bindings/writing-schema.rst setting the ``DT_SCHEMA_FILES`` variable to a specific schema file or pattern. · line 175
Quoted 9 lines
Documentation/devicetree/bindings/writing-schema.rst +6
-0@@ -167,6 +167,13 @@ setting the ``DT_SCHEMA_FILES`` variable to a specific schema file or pattern. make dt_binding_check DT_SCHEMA_FILES=/gpio/ make dtbs_check DT_SCHEMA_FILES=trivial-devices.yaml +Note that ``make dtbs_check`` will validate every DT source file that is +enabled. When making changes to a DT but not to the bindings, a possible +shortcut to validate only the DT in question is to explicitly build it with +the ``CHECK_DTBS`` flag enabled. For example:: + + make CHECK_DTBS=y mediatek/mt8192-evb.dtb
I have a bit of trouble getting this to work on a _clean_ out directory (perhaps this should have been reported at the original patch, I had always been using Dmitry's version [1] which didn't suffer from this problem).
Consider running with the following:
rm out -r
make ARCH=arm64 O=out defconfig
make ARCH=arm64 O=out CHECK_DTBS=y qcom/sm8450-sony-xperia-nagara-pdx223.dtb
After compiling preliminaries, it exits with:
make[3]: *** No rule to make target 'arch/arm64/boot/dts/qcom/sm8450-sony-xperia-nagara-pdx223.dtb'. Stop.
make[2]: *** [../scripts/Makefile.build:500: arch/arm64/boot/dts/qcom] Error 2
make[1]: *** [/kernel/Makefile:1460: qcom/sm8450-sony-xperia-nagara-pdx223.dtb] Error 2
make[1]: Leaving directory '/kernel/out'
make: *** [Makefile:231: __sub-make] Error 2However, if I lint all DTBs first by running dtbs_check, it seems the schema preliminaries are built:
LINT Documentation/devicetree/bindings
CHKDT Documentation/devicetree/bindings/processed-schema.json
... bunch of warnings
SCHEMA Documentation/devicetree/bindings/processed-schema.json
And here I ctrl+c the build so that it doesn't run DTC_CHK over every dts. If I now re-run the original command on my .dtb of choice, it completes successfully with the warnings that I expect. Is the logic behind CHECK_DTBS=y simply missing a step to make sure SCHEMA is built and up-to-date?
Aside from not working in a clean output directly, could this imply schema changes (edits in Documentation/devicetree/bindings) _are not_ propagated when running with `CHECK_DTBS=y?
At the same time running this command twice results in no output the second time around, supposedly because the dtb has "already been built". Is that also something we can improve?
[1]: https://lore.kernel.org/linux-arm-msm/[email protected]/
Thanks!
- Marijn
+CC Konrad and Dmitry whom I discussed this with before.
Quoted 76 lines · Marijn Suijten
Hi Nícolas,
Quoted 17 lines · Nícolas F. R. A. Prado
It is possible to run checks on a Devicetree by passing the
CHECK_DTBSflag when building. This is a useful shortcut to thedtbs_checkmake target since it avoids checking unrelated Devicetrees, which can take some time and is unnecessary if no bindings were modified. Document it.Signed-off-by Nícolas F. R. A. Prado <[email protected]>---
Documentation/devicetree/bindings/writing-schema.rst | 7 +++++++ 1 file changed, 7 insertions(+)Documentation/devicetree/bindings/writing-schema.rst +0
-0Documentation/devicetree/bindings/writing-schema.rst setting the ``DT_SCHEMA_FILES`` variable to a specific schema file or pattern. · line 175
Quoted 9 lines
Documentation/devicetree/bindings/writing-schema.rst +6
-0@@ -167,6 +167,13 @@ setting the ``DT_SCHEMA_FILES`` variable to a specific schema file or pattern. make dt_binding_check DT_SCHEMA_FILES=/gpio/ make dtbs_check DT_SCHEMA_FILES=trivial-devices.yaml +Note that ``make dtbs_check`` will validate every DT source file that is +enabled. When making changes to a DT but not to the bindings, a possible +shortcut to validate only the DT in question is to explicitly build it with +the ``CHECK_DTBS`` flag enabled. For example:: + + make CHECK_DTBS=y mediatek/mt8192-evb.dtbI have a bit of trouble getting this to work on a _clean_ out directory (perhaps this should have been reported at the original patch, I had always been using Dmitry's version [1] which didn't suffer from this problem).
Consider running with the following:
rm out -r
make ARCH=arm64 O=out defconfig
make ARCH=arm64 O=out CHECK_DTBS=y qcom/sm8450-sony-xperia-nagara-pdx223.dtbAfter compiling preliminaries, it exits with:
make[3]: *** No rule to make target 'arch/arm64/boot/dts/qcom/sm8450-sony-xperia-nagara-pdx223.dtb'. Stop. make[2]: *** [../scripts/Makefile.build:500: arch/arm64/boot/dts/qcom] Error 2 make[1]: *** [/kernel/Makefile:1460: qcom/sm8450-sony-xperia-nagara-pdx223.dtb] Error 2 make[1]: Leaving directory '/kernel/out' make: *** [Makefile:231: __sub-make] Error 2However, if I lint all DTBs first by running
dtbs_check, it seems the schema preliminaries are built:LINT
Documentation/devicetree/bindings
CHKDTDocumentation/devicetree/bindings/processed-schema.json
... bunch of warnings
SCHEMADocumentation/devicetree/bindings/processed-schema.jsonAnd here I ctrl+c the build so that it doesn't run
DTC_CHKover every dts. If I now re-run the original command on my .dtb of choice, it completes successfully with the warnings that I expect. Is the logic behindCHECK_DTBS=ysimply missing a step to make sure SCHEMA is built and up-to-date?Aside from not working in a clean output directly, could this imply schema changes (edits in
Documentation/devicetree/bindings)_arenot_propagated when running with `CHECK_DTBS=y?At the same time running this command twice results in no output the second time around, supposedly because the dtb has "already been built". Is that also something we can improve?
[1]: https://lore.kernel.org/linux-arm-msm/[email protected]/
Thanks!
- Marijn