Diese Präsentation wurde erfolgreich gemeldet.
Die SlideShare-Präsentation wird heruntergeladen. ×

HKG18-120 - Devicetree Schema Documentation and Validation

Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Anzeige
Nächste SlideShare
Grails workshops
Grails workshops
Wird geladen in …3
×

Hier ansehen

1 von 12 Anzeige

HKG18-120 - Devicetree Schema Documentation and Validation

Herunterladen, um offline zu lesen

"Session ID: HKG18-120
Session Name: HKG18-120 - Structured Documentation and Validation for Device Tree
Speaker: Grant Likely
Track: Kernel


★ Session Summary ★
Devicetree has become the dominant hardware configuration language used when building embedded systems. Projects using Devicetree now include Linux, U-Boot, Android, FreeBSD, and Zephyr. However, it is notoriously difficult to write correct Devicetree data files. The dtc tools perform limited tests for valid data, and there there is not yet a way to add validity test for specific hardware descriptions. Neither is there a good way to document requirements for specific bindings. Work is underway to solve these problems. This session will present a proposal for adding Devicetree schema files to the Devicetree toolchain that can be used to both validate data and produce usable documentation.
---------------------------------------------------
★ Resources ★
Event Page: http://connect.linaro.org/resource/hkg18/hkg18-120/
Presentation: http://connect.linaro.org.s3.amazonaws.com/hkg18/presentations/hkg18-120.pdf
Video: http://connect.linaro.org.s3.amazonaws.com/hkg18/videos/hkg18-120.mp4
---------------------------------------------------
★ Event Details ★
Linaro Connect Hong Kong 2018 (HKG18)
19-23 March 2018
Regal Airport Hotel Hong Kong

---------------------------------------------------
Keyword: Kernel
'http://www.linaro.org'
'http://connect.linaro.org'
---------------------------------------------------
Follow us on Social Media
https://www.facebook.com/LinaroOrg
https://www.youtube.com/user/linaroorg?sub_confirmation=1
https://www.linkedin.com/company/1026961"

"Session ID: HKG18-120
Session Name: HKG18-120 - Structured Documentation and Validation for Device Tree
Speaker: Grant Likely
Track: Kernel


★ Session Summary ★
Devicetree has become the dominant hardware configuration language used when building embedded systems. Projects using Devicetree now include Linux, U-Boot, Android, FreeBSD, and Zephyr. However, it is notoriously difficult to write correct Devicetree data files. The dtc tools perform limited tests for valid data, and there there is not yet a way to add validity test for specific hardware descriptions. Neither is there a good way to document requirements for specific bindings. Work is underway to solve these problems. This session will present a proposal for adding Devicetree schema files to the Devicetree toolchain that can be used to both validate data and produce usable documentation.
---------------------------------------------------
★ Resources ★
Event Page: http://connect.linaro.org/resource/hkg18/hkg18-120/
Presentation: http://connect.linaro.org.s3.amazonaws.com/hkg18/presentations/hkg18-120.pdf
Video: http://connect.linaro.org.s3.amazonaws.com/hkg18/videos/hkg18-120.mp4
---------------------------------------------------
★ Event Details ★
Linaro Connect Hong Kong 2018 (HKG18)
19-23 March 2018
Regal Airport Hotel Hong Kong

---------------------------------------------------
Keyword: Kernel
'http://www.linaro.org'
'http://connect.linaro.org'
---------------------------------------------------
Follow us on Social Media
https://www.facebook.com/LinaroOrg
https://www.youtube.com/user/linaroorg?sub_confirmation=1
https://www.linkedin.com/company/1026961"

Anzeige
Anzeige

Weitere Verwandte Inhalte

Ähnlich wie HKG18-120 - Devicetree Schema Documentation and Validation (20)

Weitere von Linaro (20)

Anzeige

Aktuellste (20)

HKG18-120 - Devicetree Schema Documentation and Validation

  1. 1. Devicetree Schema Documentation and Validation Grant Likely - Arm
  2. 2. Devicetree Schema Documentation and Validation The problem: too easy to get devicetree wrong ● Data must be encoded in very specific ways ● Toolchain provides little validation ● No checks against documented schema (aka. bindings) ○ Schemas are loosely structure prose ○ Not machine readable ● Steep learning curve
  3. 3. Project Goals ● Define a DT schema language ○ Human friendly ○ Machine readable ○ Include binding documentation ● Better tooling ○ Validate DTS files at build time ○ Validate DT Schema files are in the correct format ○ Useful error and warning messages ● Leverage existing technology ○ Use existing schema validation framework ■ Extended to handle quirks of DT ○ Don’t write a lot of code! ○ Don’t define an entirely new language! ● Generate Specification Documentation from Schema files
  4. 4. Prototype Implementation http://github.com/robherring/yaml-bindings Based on: ● Python3 ● YAML 1.2 file format ● JSON Schema vocabulary ○ As implemented in Python jsonschema library ● Sphinx-Doc extension ~250 lines of python code ~250 lines of metaschema files ~250 lines of schema files
  5. 5. YAML File Format http://www.yaml.org ● Human friendly ● Portable ● Structured ● Simple transcode DTS to YAML ● Extensible with custom datatypes ● Superset of JSON %YAML 1.2 --- YAML: YAML Ain't Markup Language What It Is: YAML is a human friendly data serialization standard for all programming languages. YAML Resources: YAML 1.2 (3rd Edition): http://yaml.org/spec/1.2/spec.html YAML 1.1 (2nd Edition): http://yaml.org/spec/1.1/ YAML 1.0 (1st Edition): http://yaml.org/spec/1.0/ YAML Issues Page: https://github.com/yaml/yaml/issues YAML Mailing List: yaml-core@lists.sourceforge.net YAML IRC Channel: "#yaml on irc.freenode.net" YAML Cookbook (Ruby): http://yaml4r.sourceforge.net/cookbook/ (local) YAML Reference Parser: http://ben-kiki.org/ypaste/ Projects: C/C++ Libraries: - libyaml # "C" Fast YAML 1.1 - Syck # (dated) "C" YAML 1.0 - yaml-cpp # C++ YAML 1.2 implementation Python: - PyYAML # YAML 1.1, pure python and libyaml binding - ruamel.yaml # YAML 1.2, update of PyYAML with round-tripping
  6. 6. JSON Schema Vocabulary http://json-schema.org ● Intended for and encoded in JSON ○ Works fine with YAML ● Defines vocabulary and processing model for validation ○ Can extend with DT specific vocabulary ● JSON Schema nodes apply constraints on target document { "title": "Person", "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "age": { "description": "Age in years", "type": "integer", "minimum": 0 } }, "required": ["firstName", "lastName"] }
  7. 7. DT Schema Conceptual Model Meta- Schema .dts Schema. Schema. Schemaa Schema
  8. 8. Examples -- (best to go look at project) Meta Schema %YAML 1.2 --- $id: "http://devicetree.org/meta-schemas/core.yaml#" $schema: "http://json-schema.org/draft-06/schema#" description: "Metaschema for devicetree binding documentation" allOf: [ { $ref: "http://json-schema.org/draft-06/schema#" } ] [...] properties: $id: pattern: 'http://devicetree.org/(test/)?schemas/.*.yaml#' $schema: const: "http://devicetree.org/meta-schemas/core.yaml#" [...] Required: [$id, $schema, version, title, maintainers, description] additionalProperties: false Schema %YAML 1.2 --- $id: http://devicetree.org/schemas/root-node.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: Common root node description: | Common properties always required in the root node of the tree maintainers: - Device Tree <dt@kernel.org> select: required: ["$path"] properties: $path: {enum: ["/"]} properties: compatible: {} model: type: string "#address-cells": {} "#size-cells": {} memory: {}
  9. 9. Generate Documentation title: /aliases Node description: | A devicetree may have an aliases node (``/aliases``) that defines one or more alias properties. patternProperties: "^[a-z][a-z0-9-]*$": { type: string } additionalProperties: false examples: example1: | aliases { serial0 = "/simple-bus@fe000000/serial@11c500"; ethernet0 = "/simple-bus@fe000000/ethernet@31c000"; }; maintainers: - Devicetree Specification Mailing List <devicetree-spec@vger.kernel.org>
  10. 10. Demonstration ● Devicetree Validation $ ./dt-validate.py test/juno.cpp.yaml ● Devicetree Schema Validation $ ./tools/dt-doc-validate test/schemas/good-example.yaml $ ./tools/dt-doc-validate test/schemas/bad-example.yaml ● Running Testcases $ make test
  11. 11. Next Steps ● Start requiring binding files to be YAML encoded ○ Can be enforced in kernel ● Add DTSchema support into DTC ○ Add YAML output filter to DTC, or ○ Update libfdt Python bindings to expose JSON object model ● Get working with DTS files in kernel ● Flush out core schema files ● Decide where code should live ○ Separate Repo? ○ In DTC repo? ○ In Devicetree-schema repo? ○ In kernel? DTSchema hacking Tuesday and Wednesday mornings in Core Hacking Room
  12. 12. Thank You #HKG18 HKG18 keynotes and videos on: connect.linaro.org For further information: www.linaro.org

×