dt-bindings: Improve validation build error handling
Subsystems (3)
Rob Herring
maintainerPATCH 1/1 dt-bindings: Improve validation build error handling
Schema errors can cause make to exit before useful information is printed. This leaves developers wondering what's wrong. It can be overcome passing '-k' to make, but that's not an obvious solution. There's 2 scenarios where this happens.
When using DT_SCHEMA_FILES to validate with a single schema, any error in the schema results in processed-schema.yaml being empty causing a make error. The result is the specific errors in the schema are never shown because processed-schema.yaml is the first target built. Simply making processed-schema.yaml last in extra-y ensures the full schema validation with detailed error messages happen first.
The 2nd problem is while schema errors are ignored for processed-schema.yaml, full validation of the schema still runs in parallel and any schema validation errors will still stop the build when running validation of dts files. The fix is to not add the schema examples to extra-y in this case. This means 'dtbs_check' is no longer a superset of 'dt_binding_check'. Update the documentation to make this clear.
--- Documentation/devicetree/bindings/Makefile | 5 ++++- Documentation/devicetree/writing-schema.rst | 6 ++++-- 2 files changed, 8 insertions(+), 3 deletions(-)
Documentation/devicetree/bindings/Makefile +4 -1
@@ -12,7 +12,6 @@ $(obj)/%.example.dts: $(src)/%.yaml FORCE $(call if_changed,chk_binding) DT_TMP_SCHEMA := processed-schema.yaml -extra-y += $(DT_TMP_SCHEMA) quiet_cmd_mk_schema = SCHEMA $@ cmd_mk_schema = $(DT_MK_SCHEMA) $(DT_MK_SCHEMA_FLAGS) -o $@ $(real-prereqs)
@@ -26,8 +25,12 @@ DT_DOCS = $(shell \ DT_SCHEMA_FILES ?= $(addprefix $(src)/,$(DT_DOCS)) +ifeq ($(CHECK_DTBS),) extra-y += $(patsubst $(src)/%.yaml,%.example.dts, $(DT_SCHEMA_FILES)) extra-y += $(patsubst $(src)/%.yaml,%.example.dt.yaml, $(DT_SCHEMA_FILES)) +endif $(obj)/$(DT_TMP_SCHEMA): $(DT_SCHEMA_FILES) FORCE $(call if_changed,mk_schema) + +extra-y += $(DT_TMP_SCHEMA)
Documentation/devicetree/writing-schema.rst +4 -2
@@ -133,11 +133,13 @@ binding schema. All of the DT binding documents can be validated using the make dt_binding_check -In order to perform validation of DT source files, use the `dtbs_check` target:: +In order to perform validation of DT source files, use the ``dtbs_check`` target:: make dtbs_check -This will first run the `dt_binding_check` which generates the processed schema. +Note that ``dtbs_check`` will skip any binding schema files with errors. It is +necessary to use ``dt_binding_check`` to get all the validation errors in the +binding schema files. It is also possible to run checks with a single schema file by setting the ``DT_SCHEMA_FILES`` variable to a specific schema file.
Signature · 1 line
2.20.1
Quoted 20 lines · Rob Herring
Schema errors can cause make to exit before useful information is printed. This leaves developers wondering what's wrong. It can be overcome passing '-k' to make, but that's not an obvious solution. There's 2 scenarios where this happens.
When using
DT_SCHEMA_FILESto validate with a single schema, any error in the schema results inprocessed-schema.yamlbeing empty causing a make error. The result is the specific errors in the schema are never shown becauseprocessed-schema.yamlis the first target built. Simply makingprocessed-schema.yamllast in extra-y ensures the full schema validation with detailed error messages happen first.The 2nd problem is while schema errors are ignored for
processed-schema.yaml, full validation of the schema still runs in parallel and any schema validation errors will still stop the build when running validation of dts files. The fix is to not add the schema examples to extra-y in this case. This means 'dtbs_check' is no longer a superset of 'dt_binding_check'. Update the documentation to make this clear.
Quoted 3 lines
Cc Jeffrey Hugo <[email protected]>Cc Masahiro Yamada <[email protected]>Signed-off-by Rob Herring <[email protected]>
I injected a syntax error into a random binding file, and compared the output with and without this patch. This patch makes a massive improvement in giving the user the necessary information to identify and fix issues. Thanks!
Quoted 51 lines
--- Documentation/devicetree/bindings/Makefile | 5 ++++- Documentation/devicetree/writing-schema.rst | 6 ++++-- 2 files changed, 8 insertions(+), 3 deletions(-)Documentation/devicetree/bindings/Makefile +4
-1@@ -12,7 +12,6 @@ $(obj)/%.example.dts: $(src)/%.yaml FORCE $(call if_changed,chk_binding) DT_TMP_SCHEMA := processed-schema.yaml -extra-y += $(DT_TMP_SCHEMA) quiet_cmd_mk_schema = SCHEMA $@ cmd_mk_schema = $(DT_MK_SCHEMA) $(DT_MK_SCHEMA_FLAGS) -o $@ $(real-prereqs)@@ -26,8 +25,12 @@ DT_DOCS = $(shell \ DT_SCHEMA_FILES ?= $(addprefix $(src)/,$(DT_DOCS)) +ifeq ($(CHECK_DTBS),) extra-y += $(patsubst $(src)/%.yaml,%.example.dts, $(DT_SCHEMA_FILES)) extra-y += $(patsubst $(src)/%.yaml,%.example.dt.yaml, $(DT_SCHEMA_FILES)) +endif $(obj)/$(DT_TMP_SCHEMA): $(DT_SCHEMA_FILES) FORCE $(call if_changed,mk_schema) + +extra-y += $(DT_TMP_SCHEMA)Documentation/devicetree/writing-schema.rst +4
-2@@ -133,11 +133,13 @@ binding schema. All of the DT binding documents can be validated using the make dt_binding_check -In order to perform validation of DT source files, use the `dtbs_check` target:: +In order to perform validation of DT source files, use the ``dtbs_check`` target:: make dtbs_check -This will first run the `dt_binding_check` which generates the processed schema. +Note that ``dtbs_check`` will skip any binding schema files with errors. It is +necessary to use ``dt_binding_check`` to get all the validation errors in the +binding schema files. It is also possible to run checks with a single schema file by setting the ``DT_SCHEMA_FILES`` variable to a specific schema file.
Signature · 3 lines
Jeffrey Hugo Qualcomm Technologies, Inc. is a member of the Code Aurora Forum, a Linux Foundation Collaborative Project.
Rob Herring
maintainerQuoted 22 lines · Jeffrey Hugo
Quoted 20 lines · Rob Herring
Schema errors can cause make to exit before useful information is printed. This leaves developers wondering what's wrong. It can be overcome passing '-k' to make, but that's not an obvious solution. There's 2 scenarios where this happens.
When using
DT_SCHEMA_FILESto validate with a single schema, any error in the schema results inprocessed-schema.yamlbeing empty causing a make error. The result is the specific errors in the schema are never shown becauseprocessed-schema.yamlis the first target built. Simply makingprocessed-schema.yamllast in extra-y ensures the full schema validation with detailed error messages happen first.The 2nd problem is while schema errors are ignored for
processed-schema.yaml, full validation of the schema still runs in parallel and any schema validation errors will still stop the build when running validation of dts files. The fix is to not add the schema examples to extra-y in this case. This means 'dtbs_check' is no longer a superset of 'dt_binding_check'. Update the documentation to make this clear.
Quoted 8 lines
Quoted 3 lines
Cc Jeffrey Hugo <[email protected]>Cc Masahiro Yamada <[email protected]>Signed-off-by Rob Herring <[email protected]>I injected a syntax error into a random binding file, and compared the output with and without this patch. This patch makes a massive improvement in giving the user the necessary information to identify and fix issues. Thanks!
BTW, update dtschema and you'll get better (or more at least) messages when 'is not valid under any of the given schemas' errors occur.
Quoted 1 line
Tested-by Jeffrey Hugo <[email protected]>
Thanks.
Rob
Quoted 24 lines · Rob Herring
Quoted 22 lines · Jeffrey Hugo
Quoted 20 lines · Rob Herring
Schema errors can cause make to exit before useful information is printed. This leaves developers wondering what's wrong. It can be overcome passing '-k' to make, but that's not an obvious solution. There's 2 scenarios where this happens.
When using
DT_SCHEMA_FILESto validate with a single schema, any error in the schema results inprocessed-schema.yamlbeing empty causing a make error. The result is the specific errors in the schema are never shown becauseprocessed-schema.yamlis the first target built. Simply makingprocessed-schema.yamllast in extra-y ensures the full schema validation with detailed error messages happen first.The 2nd problem is while schema errors are ignored for
processed-schema.yaml, full validation of the schema still runs in parallel and any schema validation errors will still stop the build when running validation of dts files. The fix is to not add the schema examples to extra-y in this case. This means 'dtbs_check' is no longer a superset of 'dt_binding_check'. Update the documentation to make this clear.
Quoted 8 lines
Quoted 8 lines
Quoted 3 lines
Cc Jeffrey Hugo <[email protected]>Cc Masahiro Yamada <[email protected]>Signed-off-by Rob Herring <[email protected]>I injected a syntax error into a random binding file, and compared the output with and without this patch. This patch makes a massive improvement in giving the user the necessary information to identify and fix issues. Thanks!
Could you show me an example of the injected syntax error, and how this commit will improve the diagnostic?
For example, I changed as follows:
(quoted diff) +0 -0
b/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml index 47bc1ac36426..358cb1fa4bb6 100644
Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml +1 -1
@@ -89,7 +89,7 @@ required: - clocks allOf: - - if: + - if2: properties: compatible: contains:
The tool clearly explains the cause of the error. I am struggling to understand what the current problem is.
masahiro@pug:~/ref/linux$ make -j8 ARCH=arm dt_binding_check CHKDT Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml DTC Documentation/devicetree/bindings/arm/altera.example.dt.yaml DTC Documentation/devicetree/bindings/arm/nxp/lpc32xx.example.dt.yaml DTC Documentation/devicetree/bindings/arm/pmu.example.dt.yaml DTC Documentation/devicetree/bindings/arm/rockchip.example.dt.yaml DTC Documentation/devicetree/bindings/arm/altera/socfpga-clk-manager.example.dt.yaml DTC Documentation/devicetree/bindings/arm/primecell.example.dt.yaml DTC Documentation/devicetree/bindings/arm/renesas.example.dt.yaml CHECK Documentation/devicetree/bindings/arm/nxp/lpc32xx.example.dt.yaml CHECK Documentation/devicetree/bindings/arm/pmu.example.dt.yaml CHECK Documentation/devicetree/bindings/arm/altera.example.dt.yaml CHECK Documentation/devicetree/bindings/arm/rockchip.example.dt.yaml CHECK Documentation/devicetree/bindings/arm/altera/socfpga-clk-manager.example.dt.yaml CHECK Documentation/devicetree/bindings/arm/primecell.example.dt.yaml CHECK Documentation/devicetree/bindings/arm/renesas.example.dt.yaml /home/masahiro/ref/linux/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml: allOf:0: 'if2' is not one of ['$ref', 'if', 'then', 'else'] make[1]: *** [Documentation/devicetree/bindings/Makefile;12: Documentation/devicetree/bindings/gpu/arm,mali-midgard.example.dts] Error 1 make[1]: *** Waiting for unfinished jobs.... make: *** [Makefile;1266: dt_binding_check] Error 2
Quoted 8 lines
BTW, update dtschema and you'll get better (or more at least) messages when 'is not valid under any of the given schemas' errors occur.
Quoted 1 line
Tested-by Jeffrey Hugo <[email protected]>Thanks.
Rob
Signature · 2 lines
Best Regards Masahiro Yamada
Rob Herring
maintainerQuoted 59 lines · Masahiro Yamada
Quoted 24 lines · Rob Herring
Quoted 22 lines · Jeffrey Hugo
Quoted 20 lines · Rob Herring
Schema errors can cause make to exit before useful information is printed. This leaves developers wondering what's wrong. It can be overcome passing '-k' to make, but that's not an obvious solution. There's 2 scenarios where this happens.
When using
DT_SCHEMA_FILESto validate with a single schema, any error in the schema results inprocessed-schema.yamlbeing empty causing a make error. The result is the specific errors in the schema are never shown becauseprocessed-schema.yamlis the first target built. Simply makingprocessed-schema.yamllast in extra-y ensures the full schema validation with detailed error messages happen first.The 2nd problem is while schema errors are ignored for
processed-schema.yaml, full validation of the schema still runs in parallel and any schema validation errors will still stop the build when running validation of dts files. The fix is to not add the schema examples to extra-y in this case. This means 'dtbs_check' is no longer a superset of 'dt_binding_check'. Update the documentation to make this clear.Quoted 8 lines
Quoted 8 lines
Quoted 3 lines
Cc Jeffrey Hugo <[email protected]>Cc Masahiro Yamada <[email protected]>Signed-off-by Rob Herring <[email protected]>I injected a syntax error into a random binding file, and compared the output with and without this patch. This patch makes a massive improvement in giving the user the necessary information to identify and fix issues. Thanks!
Could you show me an example of the injected syntax error, and how this commit will improve the diagnostic?
For example, I changed as follows:
Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml +1
-1@@ -89,7 +89,7 @@ required: - clocks allOf: - - if: + - if2: properties: compatible: contains:
Quoted 6 lines
The tool clearly explains the cause of the error. I am struggling to understand what the current problem is.
masahiro@pug:~/ref/linux$ make -j8 ARCH=arm dt_binding_check
Before this patch, you should see processed-schema.yaml built first. Clean your tree and do:
make -j8 ARCH=arm DT_SCHEMA_FILES=Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml dt_binding_check
Building processed-schema.yaml will fail because it will be empty as the 1 file included had an error.
Quoted 42 lines
CHKDT Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml DTC Documentation/devicetree/bindings/arm/altera.example.dt.yaml DTC Documentation/devicetree/bindings/arm/nxp/lpc32xx.example.dt.yaml DTC Documentation/devicetree/bindings/arm/pmu.example.dt.yaml DTC Documentation/devicetree/bindings/arm/rockchip.example.dt.yaml DTC Documentation/devicetree/bindings/arm/altera/socfpga-clk-manager.example.dt.yaml DTC Documentation/devicetree/bindings/arm/primecell.example.dt.yaml DTC Documentation/devicetree/bindings/arm/renesas.example.dt.yaml CHECK Documentation/devicetree/bindings/arm/nxp/lpc32xx.example.dt.yaml CHECK Documentation/devicetree/bindings/arm/pmu.example.dt.yaml CHECK Documentation/devicetree/bindings/arm/altera.example.dt.yaml CHECK Documentation/devicetree/bindings/arm/rockchip.example.dt.yaml CHECK Documentation/devicetree/bindings/arm/altera/socfpga-clk-manager.example.dt.yaml CHECK Documentation/devicetree/bindings/arm/primecell.example.dt.yaml CHECK Documentation/devicetree/bindings/arm/renesas.example.dt.yaml
/home/masahiro/ref/linux/Documentation/devicetree/bindings/gpu/arm,mali-midgard.yaml:
allOf:0: 'if2' is not one of ['$ref', 'if', 'then', 'else']
make[1]: *** [Documentation/devicetree/bindings/Makefile;12:Documentation/devicetree/bindings/gpu/arm,mali-midgard.example.dts] Error 1
make[1]: *** Waiting for unfinished jobs....
make: *** [Makefile;1266:dt_binding_check] Error 2Quoted 8 lines
BTW, update dtschema and you'll get better (or more at least) messages when 'is not valid under any of the given schemas' errors occur.
Quoted 1 line
Tested-by Jeffrey Hugo <[email protected]>Thanks.
Rob
--
Best Regards
Masahiro Yamada