[RFC PATCH 0/5] DT binding documents using text markup
During the Device Tree microconference at Linux Plumbers 2015, we had a short discussion about how to improve DT Binding Documentation. A number of issues were raised (again, as these things have been discussed in the past) including: * Inconsistency between binding documents due to prose text format. * Inability to reliably machine read bindings for mass update or search. * Bit rot of bindings as new conventions are agreed upon but only new bindings are changed. Grant Likely probably summed up the issue best with "...as long as bindings are human readable, we'll have issues...". The context of that comment was, of course, regarding our current documents written in very inconsistent prose style. When the topic of needing the bindings in a rigid format was raised, there was general head nodding that this was needed. It was noted that this has been discussed many times before and nothing has been done. My proposed solution to the problem is to convert all DT bindings a rigid text markup format. In choosing a text markup language my requirements were: 1) Human readable 2) Well documented 3) Easy to translate to other data formats 4) Well supported by tools and libraries After looking at a number of markup options, YAML stood out as the one that meets all of these requirements. The YAML syntax is adopted in many projects specifically because of the high level of readability. A comprehensive spec is at http://www.yaml.org/spec/1.2/spec.html. There's a number of tools to convert between YAML and other popular data formats such as JSON and XML. XML was cited by Behan Webster during the microconference as an important data format as the type of developers that may produce comprehensive DTS Binding validation tools will want to use XML. Every major scripting language has a high level binding to the low level libyaml C library to facilitate handling of YAML data files. One caveat with YAML is it does not tolerate tabs. Yes, I said it. No tabs! This can be managed with proper editor modes and also with helper scripts to strip tabs to aid in people passing planned checkpatch.pl checks that would run YAML DT Binding specific tag validators for new bindings. The scope of the initial YAML DT Binding format was specifically limited to supporting *only* the content we have in bindings today. The idea here is to propose and agree on something that will take us just a few steps in the right direction. If we move *all* current binding content to a machine parseable format, additional features can be added with more automation and scripting. As it stands today, because of the inconsistency of the wording of the files, we can't add a lot of new features to the content until we convert what we have today into a standard format. With that said, it should be noted that some new features such as "type" tags to indicate cell types could be added to support additional DTS validation beyond what the current content supports. Another possibility is adding "range" type information to validate the legal values for a cell. This series is broken up into three major parts: 1) The documentation defining the YAML DT binding format 2) A skeleton device binding example illustrating use of this format 3) Some real binding conversions (eeprom.txt, phy-bindings.txt, and ti-phy.txt As a proof of concept of what can be done with a proper machine readable DT binding source file, there's a simple markdown document generator at https://github.com/konsulko/dtgendoc. Also, to see actual output from the generator, the generated markdown from those bindings is viewable at https://github.com/konsulko/dtgendoc/wiki There's a lot of other possibilities for validation tools using only the data we have today in the bindings. In addition, Frank Rowand covered some DT debug techniques that would benefit from the binding documentation being 100% reliably searchable. I found it useful to see a side-by-side view of a converted doc versus the original content, so here's a screenshot of eeprom.txt vs. eeprom.yaml: https://github.com/konsulko/dtgendoc/wiki#eepromtxt-vs-eepromyaml When we decide on a text markup format that is acceptable, then the next step is to convert all the bindings. That process would start with the complete set of generic bindings as they will be referenced by the actual device bindings. If the RFC wasn't explicit enough...comments welcome. -Matt Matt Porter (5): Documentation: dt-bindings: add documentation on new DT binding format Documentation: dt-bindings: add example DT binding document Documentation: dt-bindings: add YAML eeprom binding Documentation: dt-bindings: phy: add YAML generic PHY binding Documentation: dt-bindings: phy: add YAML TI PHY binding .../devicetree/bindings/dt-binding-format.txt | 106 + Documentation/devicetree/bindings/eeprom.yaml | 44 ++ .../devicetree/bindings/phy/phy-bindi
[RFC PATCH 1/5] Documentation: dt-bindings: add documentation on new DT binding format
Documentation explaining the syntax and format of the YAML-based DT binding
documentation.
Signed-off-by: Matt Porter
---
.../devicetree/bindings/dt-binding-format.txt | 106 +
1 file changed, 106 insertions(+)
create mode 100644 Documentation/devicetree/bindings/dt-binding-format.txt
diff --git a/Documentation/devicetree/bindings/dt-binding-format.txt
b/Documentation/devicetree/bindings/dt-binding-format.txt
new file mode 100644
index 000..f9acc22
--- /dev/null
+++ b/Documentation/devicetree/bindings/dt-binding-format.txt
@@ -0,0 +1,106 @@
+--
+Device Tree Binding Format
+--
+
+Background
+--
+
+DT bindings historically were written as text in prose format which
+led to issues in usability of that source documentation. Some of
+these issues include the need to programmatically process binding
+source documentation to do DTS validation, perform mass updates to
+format/style, and to generate publishable documentation in HTML or
+PDF form.
+
+Overview
+
+
+The DT binding format is based on the YAML text markup language.
+Although there are many text markup options available, YAML
+fulfills all requirements considered for a DT binding source format
+which include:
+
+1) Must be human readable
+2) Must be easily translated to other data formats (XML, JSON, etc).
+3) Must have sufficient tools and libraries to enable developers to
+ build new tools for DT binding processing
+4) Must have a complete spec to refer to syntax
+
+YAML is documentated in the specification found at
+http://www.yaml.org/spec/1.2/spec.html
+
+The required YAML DT binding tag format and syntax are defined in
+the following sections.
+
+YAML DT Binding Syntax
+--
+
+* Lines starting with "#" are comments and not part of the binding itself
+* "%YAML 1.2" starts a file, indicating the version of YAML in use
+* "---" starts a binding document
+* "..." ends a binding document
+* Multiple binding documents may exist in a single file
+* Tabs are not permitted
+* Scope is denoted by indentation of two spaces
+* Key value pairs are denoted by "key: value"
+* Sequences are denoted by "- "
+* Scalar values may convert newlines to spaces and preserve blank
+ lines for long description formatting using ">"
+* Scalar values may escape all reserved characters and preserve
+ newlines by using "|" to denote literal style
+
+For additional information on YAML syntax, refer to the specification
+at http://www.yaml.org/spec/1.2/spec.html
+
+YAML DT Binding Format
+--
+
+The following YAML types are supported in the DT binding format:
+
+* [R] id: unique identifier in property form (e.g. skel-device)
+
+* [R] title: title of the binding
+
+* [O] maintainer: sequence of maintainers
+ [R] name: name and email of maintainer or mailing list in RFC822
+form.
+
+* [O] description: full description of the binding
+
+* [O] compatible: sequence of valid compatible descriptors
+ [R] name: the compatible string surrounded in double quotes
+ [O] deprecated: a deprecated compatible string surrounded in
+ double quotes
+ [O] description: description of the compatible string
+
+* [O] required: sequence of required properties:
+ [R] name: name of the property surrounded in double quotes
+ [R] description: description of the property
+ [O] reference: optional reference to a binding id
+
+* [O] optional: sequence of optional properties:
+ [R] name: name of the property surrounded in double quotes
+ [R] description: description of the property
+ [O] reference: optional reference to a binding id
+
+* [O] deprecated: sequence of deprecated properties:
+ [R] name: name of the property surrounded in double quotes
+ [R] description: description of the property
+ [O] reference: optional reference to a binding id
+
+* [R] example: sequence of examples:
+ [R] dts: DT source of example usage. The example text must use
+ literal style ("|") so that it retains indentation and
+ newlines.
+ [O] description: description of the example
+
+Note: [R] and [O] denote required and optional fields, respectively.
+
+Skeleton Binding
+
+
+The skeleton.yaml binding found in the top of the DT binding tree
+is the canonical example of syntax and format to use when writing
+a DT binding document. It is maintained with the latest formatting
+conventions, making it the best starting point when writing a new DT
+binding.
--
2.1.4
--
To unsubscribe from this list: send the line "unsubscribe devicetree-spec" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[RFC PATCH 4/5] Documentation: dt-bindings: phy: add YAML generic PHY binding
Convert the generic phy-bindings.txt binding to standard YAML
DT binding format.
Signed-off-by: Matt Porter
---
.../devicetree/bindings/phy/phy-bindings.yaml | 89 ++
1 file changed, 89 insertions(+)
create mode 100644 Documentation/devicetree/bindings/phy/phy-bindings.yaml
diff --git a/Documentation/devicetree/bindings/phy/phy-bindings.yaml
b/Documentation/devicetree/bindings/phy/phy-bindings.yaml
new file mode 100644
index 000..9b164d1
--- /dev/null
+++ b/Documentation/devicetree/bindings/phy/phy-bindings.yaml
@@ -0,0 +1,89 @@
+%YAML 1.2
+---
+id: phy-device
+
+title: PHY device
+
+description: >
+ This document explains only the device tree data binding. For general
+ information about PHY subsystem refer to Documentation/phy.txt
+
+required:
+ - name: "#phy-cells"
+description: >
+ number of cells in a PHY specifier. The meaning of all those
+ cells is defined by the binding for the phy node. The PHY
+ provider can use the values in cells to find the appropriate
+ PHY.
+
+optional:
+ - name: "phy-supply"
+description: >
+ phandle to a regulator that provides power to the PHY. This
+ regulator will be managed during the PHY power on/off sequence.
+
+example:
+ - dts: |
+ phys: phy {
+ compatible = "xxx";
+ reg = <...>;
+ .
+ .
+ #phy-cells = <1>;
+ .
+ .
+ };
+description: >
+ Describes an IP block (PHY provider) that implements 2 different
+ PHYs. In order to differentiate between these 2 PHYs, an
+ additional specifier should be given while trying to get a
+ reference to it.
+...
+
+---
+id: phy-user
+
+title: PHY user
+
+required:
+ - name: "phys"
+description: >
+ the phandle for the PHY device (used by the PHY subsystem)
+ - name: "phy-names"
+description: >
+ the names of the PHY corresponding to the PHYs present in the
+ *phys* phandle
+
+example:
+ - dts: |
+ usb1: usb_otg_ss@xxx {
+ compatible = "xxx";
+ reg = ;
+ .
+ .
+ phys = <&usb2_phy>, <&usb3_phy>;
+ phy-names = "usb2phy", "usb3phy";
+ .
+ .
+ };
+description: >
+ Represents a controller that uses two PHYs, one for usb2 and one
+ for usb3.
+
+ - dts: |
+ usb2: usb_otg_ss@xxx {
+ compatible = "xxx";
+ reg = ;
+ .
+ .
+ phys = <&phys 1>;
+ phy-names = "usbphy";
+ .
+ .
+ };
+description: >
+ Represents a controller that uses one of the PHYs of the PHY
+ provider device defined previously. Note that the phy handle
+ has an additional specifier "1" to differentiate between the
+ two PHYs.
+...
--
2.1.4
--
To unsubscribe from this list: send the line "unsubscribe devicetree-spec" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[RFC PATCH 5/5] Documentation: dt-bindings: phy: add YAML TI PHY binding
Convert the ti-phy.txt binding to standard YAML DT binding
format. This binding references the YAML generic PHY binding.
Signed-off-by: Matt Porter
---
Documentation/devicetree/bindings/phy/ti-phy.yaml | 166 ++
1 file changed, 166 insertions(+)
create mode 100644 Documentation/devicetree/bindings/phy/ti-phy.yaml
diff --git a/Documentation/devicetree/bindings/phy/ti-phy.yaml
b/Documentation/devicetree/bindings/phy/ti-phy.yaml
new file mode 100644
index 000..ec93501
--- /dev/null
+++ b/Documentation/devicetree/bindings/phy/ti-phy.yaml
@@ -0,0 +1,166 @@
+%YAML 1.2
+---
+id: omap-control-phy
+
+title: OMAP Control PHY
+
+compatible:
+ - name: "ti,control-phy-otghs"
+description: if it has otghs_control mailbox register as on OMAP4.
+ - name: "ti,control-phy-usb2"
+description: if it has Power down bit in control_dev_conf register
+ e.g. USB2_PHY on OMAP5.
+ - name: "ti,control-phy-pipe3"
+description: if it has DPLL and individual Rx & Tx power control
+ e.g. USB3 PHY and SATA PHY on OMAP5.
+ - name: "ti,control-phy-pcie"
+description: for pcie to support external clock for pcie and to
+ set PCS delay value. e.g. PCIE PHY in DRA7x
+ - name: "ti,control-phy-usb2-dra7"
+description: if it has power down register like USB2 PHY on DRA7
+ DRA7 platform.
+ - name: "ti,control-phy-usb2-am437"
+description: if it has power down register like USB2 PHY on AM437
+ platform.
+required:
+ - name: "reg"
+description: register ranges as listed in the reg-names property
+ - name: "reg-names"
+description: >
+ "otghs_control" for control-phy-otghs "power",
+ "pcie_pcs" and "control_sma" for control-phy-pcie
+ "power" for all other types
+
+example:
+ - dts: |
+ omap_control_usb: omap-control-usb@4a002300 {
+ compatible = "ti,control-phy-otghs";
+ reg = <0x4a00233c 0x4>;
+ reg-names = "otghs_control";
+ };
+...
+
+---
+id: omap-usb2-phy
+
+title: OMAP USB2 PHY
+
+compatible:
+ - name: "ti,omap-usb2"
+
+required:
+ - name: "reg"
+description: >
+ Address and length of the register set for the device.
+ - name: "#phy-cells"
+description: >
+ determine the number of cells that should be given in
+ the phandle while referencing this phy.
+reference: phy-device
+ - name: "clocks"
+description: >
+ a list of phandles and clock-specifier pairs, one for
+ each entry in clock-names.
+reference: clock-consumer
+ - name: "clock-names"
+description: >
+ should include:
+ * "wkupclk" - wakeup clock.
+ * "refclk" - reference clock (optional).
+reference: clock-consumer
+
+optional:
+ - name: "ctrl-module"
+description: >
+ phandle of the control module used by PHY driver to
+ power on the PHY.
+
+example:
+ - dts: |
+ usb2phy@4a0ad080 {
+compatible = "ti,omap-usb2";
+reg = <0x4a0ad080 0x58>;
+ctrl-module = <&omap_control_usb>;
+#phy-cells = <0>;
+clocks = <&usb_phy_cm_clk32k>, <&usb_otg_ss_refclk960m>;
+clock-names = "wkupclk", "refclk";
+ };
+description: >
+ This is usually a subnode of ocp2scp to which it is
+ connected.
+...
+
+---
+id: ti-pipe3-phy
+
+title: TI Pipe3 PHY
+
+compatible:
+ - name: "ti,phy-usb3"
+ - name: "ti,phy-pipe3-sata"
+ - name: "ti,phy-pipe3-pcie"
+ - deprecated: "ti,omap-usb3"
+
+required:
+ - name: "reg"
+description: >
+ Address and length of the register set for the device.
+ - name: "reg-names"
+description: >
+ The names of the register addresses corresponding to
+ the registers filled in "reg".
+ - name: "#phy-cells"
+description: >
+ determine the number of cells that should be given in
+ the phandle while referencing this phy.
+reference: phy-device
+ - name: "clocks"
+description: >
+ a list of phandles and clock-specifier pairs, one for
+ each entry in clock-names.
+reference: clock-consumer
+ - name: "clock-names"
+description: >
+ should include:
+ * "wkupclk" - wakeup clock.
+ * "sysclk" - system clock.
+ * "refclk" - reference clock.
+ * "dpll_ref" - external dpll ref clk
+ * "dpll_ref_m2" - external dpll ref clk
+ * "phy-div" - divider for apll
+ * "div-clk" - apll clock
+reference: clock-consumer
+
+optional:
+ - name: "ctrl-module"
+description: >
+ phandle of the control module used by PHY driver to
+ power
[RFC PATCH 2/5] Documentation: dt-bindings: add example DT binding document
Add a skeleton DT binding document that serves as the canonical
example for implementing YAML-based DT bindings documentation.
The skeleton binding illustrates use of all fields and variations
described in the dt-binding-format.txt documentation.
Signed-off-by: Matt Porter
---
Documentation/devicetree/bindings/skeleton.yaml | 98 +
1 file changed, 98 insertions(+)
create mode 100644 Documentation/devicetree/bindings/skeleton.yaml
diff --git a/Documentation/devicetree/bindings/skeleton.yaml
b/Documentation/devicetree/bindings/skeleton.yaml
new file mode 100644
index 000..175965f
--- /dev/null
+++ b/Documentation/devicetree/bindings/skeleton.yaml
@@ -0,0 +1,98 @@
+%YAML 1.2
+---
+id: skel-device
+
+title: Skeleton Device
+
+maintainer:
+ - name: Skeleton Person
+
+description: >
+ The Skeleton Device binding represents the SK11 device produced by
+ the Skeleton Corporation. The binding can also support compatible
+ clones made by second source vendors.
+
+compatible:
+ - name: "skel,sk11"
+ - name: "faux,fx11"
+description: A clone of the original sk11 device
+
+required:
+ - name: "reg"
+description: chip select address of skeleton device
+reference: spi-slave
+ - name: "spi-max-frequency"
+description: >
+ Maximum SPI clocking speed of skeleton device in Hz, must be
+ 100
+reference: spi-slave
+
+optional:
+ - name: "spi-cs-high"
+description: >
+ Set if skeleton device configuration straps are set for chip
+ select polarity high
+reference: spi-slave
+
+deprecated:
+ - name: "skel,deprecated1"
+description: >
+ First of two deprecated properties.
+ - name: "skel,deprecated2"
+description: >
+ Second of two deprecated properties.
+
+example:
+ - dts: |
+ sk11@0 {
+ compatible = "skel,sk11";
+ reg = <0>;
+ spi-max-frequency = <100>;
+ spi-cs-high;
+ };
+...
+
+---
+id: skel-mini
+
+title: Skeleton Mini Device
+
+maintainer:
+ - name: Rogue Developer
+
+description: >
+ The Skeleton Mini Device binding represents the SK47x series devices
+ produced by the Skeleton Corporation.
+
+compatible:
+ - name: "skel,sk472"
+ - name: "skel,sk473"
+ - name: "skel,sk474"
+ - deprecated: "skel,sk47x"
+
+required:
+ - name: "reg"
+description: offset and length of the registers
+
+optional:
+ - name: "skel,sync-mode"
+description: Enable synchronous transfer mode
+
+example:
+ - dts: |
+ sk472@beef {
+ compatible = "skel,sk472";
+ reg = <0xbeef 0x100>;
+ };
+description: >
+ Demonstrates an SK472 in normal mode.
+
+ - dts: |
+ sk474@dead {
+ compatible = "skel,sk474";
+ reg = <0xdead 0x100>;
+ skel,sync-mode;
+ };
+description: >
+ Demonstrates an SK474 in synchronous mode.
+...
--
2.1.4
--
To unsubscribe from this list: send the line "unsubscribe devicetree-spec" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
[RFC PATCH 3/5] Documentation: dt-bindings: add YAML eeprom binding
Convert the eeprom.txt binding to standard YAML DT
binding format.
Signed-off-by: Matt Porter
---
Documentation/devicetree/bindings/eeprom.yaml | 44 +++
1 file changed, 44 insertions(+)
create mode 100644 Documentation/devicetree/bindings/eeprom.yaml
diff --git a/Documentation/devicetree/bindings/eeprom.yaml
b/Documentation/devicetree/bindings/eeprom.yaml
new file mode 100644
index 000..bf1244b
--- /dev/null
+++ b/Documentation/devicetree/bindings/eeprom.yaml
@@ -0,0 +1,44 @@
+%YAML 1.2
+---
+id: eeprom-i2c
+
+title: EEPROMs (I2C)
+
+compatible:
+ - name: ",24c00"
+ - name: ",24c01"
+ - name: ",24c02"
+ - name: ",24c04"
+ - name: ",24c08"
+ - name: ",24c16"
+ - name: ",24c32"
+ - name: ",24c64"
+ - name: ",24c128"
+ - name: ",24c256"
+ - name: ",24c512"
+ - name: ",24c1024"
+ - name: ",spd"
+
+required:
+ - name: "reg"
+description: the I2c address of the EEPROM
+
+optional:
+ - name: "pagesize"
+description: >
+ the length of the pagesize for writing. Please consult the
+ manual of your device, that value varies a lot. A wrong value
+ may result in data loss! If not specified, a safety value of
+ '1' is used which will be very slow.
+ - name: "read-only"
+description: >
+ this parameterless property disables writes to the eeprom
+
+example:
+ - dts: |
+ eeprom@52 {
+ compatible = "atmel,24c32";
+ reg = <0x52>;
+ pagesize = <32>;
+ };
+...
--
2.1.4
--
To unsubscribe from this list: send the line "unsubscribe devicetree-spec" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
