Hi All, On Friday 18 of October 2013 16:57:36 Tomasz Figa wrote: > /* > * schema.dtss - Sample Device Tree schema file. > * > * Copyright (C) 2013 Samsung Electronics Co., Ltd. > * Author: Tomasz Figa <t.figa@xxxxxxxxxxx> > * > * This program is free software; you can redistribute it and/or > * modify it under the terms of the GNU General Public License as > * published by the Free Software Foundation version 2. > * > * This program is distributed "as is" WITHOUT ANY WARRANTY of any > * kind, whether express or implied; without even the implied warranty > * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the > * GNU General Public License for more details. > */ I know the following text is quite hard to read, as I am not a good text writer, but it would be nice if you could review this proposal, especially in following terms: a) Is the scope of validation presented below close to what we need to have? I mean especially whether all the points marked ToDo are really what we need to have or can be simply dropped. b) Ideas for resolving the remaining ToDo points, if there are some of them that are really needed (and I believe some of them are). c) Things that need explanation - I will be happy to explain anything not clear. As for a) and scope of validation in general, my take on this is that it that it would be reasonable to cover just the DT ABI itself with the schemas as a starter and for the time being ignore checking of data, i.e. ranges, strings, etc. Correct me if I am wrong. b) and c) are left completely for you to comment on. :) Best regards, Tomasz > /dtss-v1/; > > /* > * Basic introduction to dtss syntax. > * > * The syntax is heavily based on DTS syntax, with some extensions based > * on Perl and POSIX extended regular expressions. See description of > * particular constructs to learn where the extensions can be used. An > * exception from DTS syntax is that there is no overridding of nodes > * and properties, defining a node or property with the same name (or > * other key that identifies it) simply creates a new rule to validate > * such node or property. > * > * Special keywords: > * > * /template/ > * Defines schema template that can be used to represent generic bindings > * which may be then included in device bindings by /use/ keyword. * A > template can take a set of required or optional parameters. * Optional > parameters need to have default value specified, which is * used when > the parameter is omited from parameters of /use/ clause. * > * Template declaration uses following syntax: > * /template/ template-name { > * /arg/ argument-name-1; // Required argument > * /arg/ argument-name-2 = <1>; // Optional argument > * // Here follows binding specification described further > * // in this document. > * }; > * > * A template argument is dereferenced by its name prefixed with > * a dollar ($) sign. An arbitrary property specified in parsed > * tree can be dereferenced by its absolute or relative path or > * by a lookup up the tree (interrupt-parent like). > * > * /arg/ > * Marks following property declaration as a template argument. > * Can be used only inside a template declaration, to declare template > * arguments, as described above in /template/ keyword description. > * > * /use/ > * Instantiates binding template. Causes the specified template to be > * included as a part of the binding specified by current node. > * > * Syntax used to instatiate templates: > * /use/ template-name { > * // List of template arguments and their values, e.g. > * argument-name-1 = <int-value>; > * argument-name-2 = "string-value"; > * // etc. > * }; > * > * /incomplete/ > * Tells the validator that the schema is not complete, i.e. > * only specified properties and subnodes should be validated, > * without complaining about ones not specified in the schema. > * > * Example of use: > * { > * compatible = "simple-bus"; > * #address-cells = <1>; > * #size-cells = <1>; > * > * *.* { // Zero or more subnodes > * /incomplete/; // of unspecified contents > * }; > * }; > * > * /inheritable/ > * Marks property as inheritable by subnodes of node in which > * it is defined. An example of such property is interrupt-parent, > * which, if not specified in the same node as interrupts property, > * is assumed to be the same as the closest interrupt-parent property > * found when walking up the tree. > * > * This is purely a helper construct to allow referencing to > * a property from inside of a DTSS, even if it is not specified > * in referred node explicitly. > * > * Example of use: > * { > * /inheritable/ interrupt-parent = phandle; > * > * .* { > * // interrupt-parent is defined for this node > * // implicitly, even if not specified explicitly > * }; > * }; > * > * /default/ > * Specifies default value of the property. > * > * This is purely a helper construct to allow referencing a property > * from inside of a DTSS, even if it is not specified in referred > * node explicitly. > * > * Example of use: > * { > * ?#address-cells = cell; > * /default/ #address-cells = <2>; > * > * // If #address-cells is not specified in device tree > * // in this node, then it is assumed to be 2. > * }; > * > * Binding description > * > * A binding starts with a top level node that must be described using at > * least one of the key node attributes specified below. The top level > node * can contains a set of properties and subnodes that describe the > binding. * They can be specified using the DTS Schema syntax, which is > basically * the standard DTS syntax modified to convey information about > the schema, * not contents. > * > * Node description > * > * A node starts with a node-name, then { and ends with matching } and > * a semicolon. It can be described by a set of key attributes, which > are: * - compatible property, > * - device_type property, > * - node name (DEPRECATED for top level nodes of bindings). > * > * Once a node matches all specified key attributes of a defined binding > * it is validated according to description of this binding. > * > * Property specification > * > * Each property inside a node is specified just as in a normal DTS file, > * except that the value specified determines value type and range of * > allowed values, not a particular value itself. In addition, property * > name can be prefixed with an optionality quantifier, marking the > property * as optional (specified 0 or 1 times). > * > * Property type can be specified using type specification syntax. It is > * a regular expression like syntax, but including special type keywords, > * that represent all the defined DTS value types, which is: > * 1) string: a string of characters enclosed by quotation marks, > * 2) cell: a single, unsigned 32-bit value, > * 3) phandle: a valid phandle to any device node, > * 4) binary: a sequence of bytes (NOTE: quantifiers work as byte count > here). * Property types can be mixed inside the property, so the value > can consist * of followed multiple blocks of data of different types. > * > * In addition, string and cell types can be limited to specified set > * of allowed values, discrete or contiguous (cell only), by using > * parentheses after type name. Regular expressions are allowed when > * specifying allowed string values. > * > * Inside property specifiers, other properties and template arguments > * can be dereferenced by preceding their names with dollar "$" sign. > * Element count of a property that is an array can be received by > * preceding its name with at "@" sign. The property name following > * $ or @ sign is interpreted as a path in device tree, either absolute > * if started by a slash "/" or relative otherwise. > * > * Example properties built from strings: > * > * string-property-1 = string; // one string > * string-property-2 = string+; // array of strings > * string-property-3 = string{@clock-names}; // same count as in > * // clock-names property > * string-property-4 = string("one", "two", "three"); // three > * // allowed values > * string-property-5 = string("[a-zA-Z]+[0-9]"); // allowed values > * // defined using a regexp > * > * Example properties built from cells: > * > * cell-property-1 = cell; // one cell > * cell-property-2 = (cell{$#cell-property-2-cells})+; // cell count > * // specified by #cell-property-name-cells property > * cell-property-3 = cell(0, 1, 2, 3, 4); // integers from 0 to 4 > * cell-property-4 = cell(0..4); // same as above, but using a range > * > * Example proprerties built from phandles: > * > * phandle-property-1 = phandle; // one phandle > * > * Example properties built from binary data: > * > * binary-property-1 = binary+; // one or more bytes of binary data > * binary-property-2 = binary{6}; // 6 bytes of binary data > * > * Example mixed properties: > * > * mixed-property-1 = ((phandle),cell{$\2/#mixed-property-1-cells})+; > * // typical specifier - phandle of controller node and a set of cells > * // defined by #*-cells property of controller node. Note the use > * // of backreferences here. > * // TODO: How to represent references to properties in a node > * // pointed by a phandle? > * > * Quantifiers > * > * Determines valid iteration count for element after the quantifier > * symbol, which can be a property or a child node. <quantifier> can be > * any valid quantifier according to POSIX extended regular expression > * syntax. > * > * Examples of use: > * > * // For properties > * property-name-1; // Required property > * ?property-name-2; // Optional property > * > * // For subnodes > * node-name-1 {}; // Required node (exactly 1 time) > * ?node-name-2 {}; // Optional node (0 or 1 times) > * +node-name-3 {}; // Required node (1 or more times) > * *node-name-4 {}; // Optional nodes (0 or more times) > * {1,3}node-name-5 {}; // From 1 to 3 subnodes must be present > * > * // For data types > * property-name-1 = cell; // One cell > * property-name-2 = string+; // One or more strings > * property-name-3 = phandle{3,8}; // From three to eight phandles > * > * Real-life examples > * > * Following is a set of examples of DTS Schema syntax use, based on > existing * device tree bindings. All examples are commented to explain > used mechanisms. * Note that all the examples are valid and should > compile fine using a DTS * Schema enabled version of the DTC compiler. > */ > > /* > * Utility schema templates. > */ > /template/ reg-property { > /* > * This template takes one argument reg-count, which is optional > * and if omitted, takes the default value of 1. > */ > /arg/ reg-count = <1>; > > /* > * The example below defines a mandatory "reg" property, consisting > * of exactly reg-count groups, each consisting of (#address-cells + > * #size-cells) cells each. > */ > reg = (cell{$../#address-cells},cell{$../#size-cells}){$reg-count}; > }; > > /template/ status-property { > /* > * Template without arguments. > * > * Defines a single, optional status property that can take one of > * enumerated values. > */ > ?status = string("okay", "disabled"); > }; > > /template/ device { > /* Optional argument, defaulting to 1. */ > > /* TODO: How to specify variable entry count? */ > /arg/ reg-count = <1>; > > /* Use a template. */ > /use/ reg-property { > /* > * Specify value of template argument. > * Note the reference to argument of this template. > */ > reg-count = $reg-count; > }; > /* Use another template. This time without arguments specified. */ > /use/ status-property; > }; > > /template/ bus { > #address-cells = cell; > #size-cells = cell; > > /default/ #address-cells = <2>; > /default/ #size-cells = <1>; > }; > > /* > * Generic SPI bindings. > */ > /template/ spi { > /* Mandatory argument, without default value. */ > /arg/ cs-cells = cell; > > /* #address-cells property equal to cs-cells argument. */ > #address-cells = <$cs-cells>; > /* Fixed value of #size-cells property. */ > #size-cells = <0>; > /* A single-cell property num-cs. */ > num-cs = cell; > > /* From 0 to $num-cs subnodes with any name. */ > {0,$num-cs}.* { > /* This node must have a reg property, with one entry. */ > /use/ reg-property { > reg-count = <1>; > }; > /* This binding does not fully define node contents. */ > /incomplete/; > }; > }; > > /* > * Generic interrupt bindings. > */ > /template/ interrupts { > /* > * Optional argument, specifying number of entries in interrupts > * property. Defaults to 1. > * TODO: How to specify optional interrupts or interrupt lists > * that vary with compatible string? > */ > /arg/ interrupt-count = <1>; > > /* Optional phandle to interrupt controller. */ > /inheritable/ ?interrupt-parent = phandle; > /* > * List of interrupts. > * TODO: variable interrupt count? > */ > interrupts = > (cell{$($interrupt-parent)/#interrupt-cells}){$interrupt-count}; }; > > /* > * Generic clock bindings. > */ > /template/ clocks { > /* > * Required argument specifying number of clocks. > * TODO: Optional clocks? > */ > /arg/ clock-count = cell; > > /* > * List of exactly $count clock specifiers. > * TODO: How to dereference phandles of specifiers properly. > */ > clocks = ((phandle),cell{$\2/#clock-cells}){$count}; > }; > > /* > * Generic pinctrl bindings. > */ > /template/ pinctrl { > /* > * List of pinctrl names. > * TODO: Optional pinctrl states? > */ > /arg/ names = string+; > > /* Pinctrl names, as specified in $names. */ > pinctrl-names = $names; > /* > * Pinctrl groups for every entry of pinctrl-names property. > * TODO: Find a correct way to define a series of properties. > */ > pinctrl-[0-@names] = phandle+; > }; > > /template/ pinctrl-default { > /* Fixed value of required pinctrl-names property. */ > pinctrl-names = "default"; > /* > * List of pinctrl groups for default pinctrl state. > * NOTE that an empty list of groups can be specified too. > */ > pinctrl-0 = phandle*; > }; > > /* > * Generic video interface (V4L2/media) bindings. > */ > /template/ video-port { > port { > /* Bus with 1-cell addresses and no sizes. */ > #address-cells = <1>; > #size-cells = <0>; > > /* One or more endpoint nodes. */ > +endpoint { > /* Single entry reg property. */ > /use/ reg-property; > /* > * Required phandle to remote endpoint. > * TODO: Do we need to check things like bidirectional > * connectivity? I.e. whether the node pointed by > * $remote-endpoint points to this node? > */ > remote-endpoint = phandle; > /* Optional property indicating slave mode operation. */ > ?slave-mode; > /* Optional bus width */ > ?bus-width = cell; > /* ... */ > }; > }; > }; > > /template/ video-ports { > /* Bus with 1-cell addresses and no sizes. */ > #address-cells = <1>; > #size-cells = <0>; > > /* Include video port template. */ > /use/ video-port { > /* Override quantifier of port subnodes. */ > +port { > /* Single entry reg property. */ > /use/ reg-property; > }; > }; > }; > > /* > * Skeleton schema for all DTSes according to ePAPR 1.1. > * > * NOTE explicit node location specified. > */ > &{/} { > /* Human readable board model. */ > model = string; > /* Set of board compatible values. */ > compatible = string+; > /* Optional version of ePAPR spec this device tree complies to. */ > ?epapr-version = string; > /* Top level bus */ > /use/ bus; > > /* Required chosen node. */ > chosen { > /* Optional bootargs string. */ > ?bootargs = string; > /* Optional stdout-path string. */ > ?stdout-path = string; > /* Optional stdin-path string. */ > ?stdin-path = string; > }; > > /* Required aliases node. */ > aliases { > /* > * Optional list of aliases with arbitrary names, pointing > * to device nodes either by path... > */ > ?[a-z0-9_]+ = string; /* TODO: Should we check path validity? */ > /* ...or phandle. */ > ?[a-z0-9_]+ = phandle; > }; > > /* Required memory node. */ > memory { > /* Required single entry reg property. */ > /use/ reg-property { > reg-count = /* TODO: how to specify a range here */; > }; > > /* Required device_type set to "memory". */ > device_type = "memory"; > /* Optional property containing multiple reg-like entries. */ > ?initial-mapped-area = (cell{../#address-cells},cell{../#size- cells})+; > }; > > /* Required cpus node. */ > cpus { > /* A bus with 1-cell address and 0-cell size specifiers. */ > #address-cells = <1>; > #size-cells = <0>; > > /* A set of CPU nodes. At least one is required. */ > +cpu { > /* 1-entry reg property, for CPU MPIDR. */ > /use/ reg-property; > /* This node can have status property. */ > /use/ status-property; > /* The device_type property must be set to "cpu". */ > device_type = "cpu"; > /* > * Optional clock-frequency property, specified > * using 1 or 2 cells, depending on the platform. > */ > ?clock-frequency = cell{1,2}; > > /* > * Additional platform-specific properties might be > * present here, which are out of scope of this > * binding. > */ > /incomplete/; > }; > }; > > /* Any optional device nodes. */ > *.* { > /* Out of scope of this binding. */ > /incomplete/; > }; > }; > > /* > * Davinci SPI controller device bindings > */ > { > /* Binding is defined for any of following compatible values. */ > compatible = string("ti,dm64410-spi", "ti,da830-spi"); > > /* Use generic device bindings. */ > /use/ device; > /* Use generic SPI bindings. */ > /use/ spi { > /* Chip select is identified using one cell. */ > cs-cells = <1>; > }; > /* Use generic interrupt bindings. */ > /use/ interrupts { > /* This device has one interrupt signal. */ > interrupt-count = <1>; > }; > /* Use generic clock bindings. */ > /use/ clocks { > /* > * This device consumes one clock, without the need to > * specify its name. > */ > count = <1>; > }; > > /* > * Device-specific property that defines which IP interrupt signal > * is tied to SoC's interrupt controller. > * > * TODO: Is this correct? > */ > ti,davinci-spi-intr-line = cell(<0>, <1>); > }; > > /* > * Samsung S5P/EXYNOS SoC Camera Subsystem (FIMC) > */ > { > /* Binding is defined for following compatible value. */ > compatible = "samsung,fimc"; > > /* Use generic clock bindings. */ > /use/ clocks { > clock-count = <4>; > }; > /* Clocks with following names must be specified. */ > clock-names = "sclk_cam0", "sclk_cam1", "pxl_async0", "pxl_async1"; > /* Use generic pinctrl bindings. */ > /use/ pinctrl { > /* > * At least "default" state must be specified. Remaining > * three states are optional. > * TODO: Revise handling of optional states. > */ > names = "default", ("idle", "active-a", "active-b")?; > }; > /* This node can have a status property. */ > /use/ status-property; > /* This node represents a bus with 1-cell addresses and sizes. */ > #address-cells = <1>; > #size-cells = <1>; > > /* Optional node representing parallel camera ports. */ > ?parallel-ports { > /* > * This node represents a bus with 1-cell addresses and > * no sizes. > */ > #address-cells = <1>; > #size-cells = <0>; > > /* Use generic video port bindings. */ > /use/ video-port; > }; > > /* At least one fimc node is required */ > +fimc { > /* Compatible should be set to one of following values. */ > compatible = string("samsung,s5pv210-fimc", > "samsung,exynos4210-fimc", > "samsung,exynos4212-fimc"); > /* This is a device. */ > /use/ device; > /* This device has a single interrupt signal. */ > /use/ interrupts; > /* Clocks are used. */ > /use/ clocks { > clock-count = <2>; > }; > /* With following clock names. */ > clock-names = "fimc", "sclk_fimc"; > > /* > * Here follows an example set of properties described > * as in existing binding documentation files. > * > * NOTE: Each property is followed by its description. > */ > > /* Required properties: */ > samsung,pix-limits = cell{4}; > /* > * an array of maximum supported image sizes in pixels, for > * details refer to Table 2-1 in the S5PV210 SoC User Manual; The > meaning of * each cell is as follows: > * 0 - scaler input horizontal size, > * 1 - input horizontal size for the scaler bypassed, > * 2 - REAL_WIDTH without input rotation, > * 3 - REAL_HEIGHT with input rotation. > */ > samsung,sysreg = phandle; > /* A phandle to the SYSREG node. */ > > /* Optional properties: */ > ?clock-frequency = cell; > /* maximum FIMC local clock (LCLK) frequency */ > ?samsung,min-pix-sizes = cell{2}; > /* > * An array specifying minimum image size in pixels at > * the FIMC input and output DMA, in the first and second cell > * respectively. Default value when this property is not > * present is <16 16> > */ > ?samsung,min-pix-alignment = cell{2}; > /* > * minimum supported image height alignment (first cell) > * and the horizontal image offset (second cell). The values > * are in pixels and default to <2 1> when this property is > * not present > */ > ?samsung,mainscaler-ext; > /* > * A boolean property indicating whether the FIMC IP > * supports extended image size and has CIEXTEN register. > */ > ?samsung,rotators = cell; > /* > * A bitmask specifying whether this IP has the input and > * the output rotator. Bits 4 and 0 correspond to input and > * output rotator respectively. If a rotator is present its > * corresponding bit should be set. Default value when this > * property is not specified is 0x11. > */ > ?samsung,cam-if; > /* > * A bolean property indicating whether the IP block includes > * the camera input interface. > */ > ?samsung,isp-wb; > /* > * This property must be present if the IP block has the ISP > * writeback input. > */ > ?samsung,lcd-wb; > /* > * This property must be present if the IP block has the LCD > * writeback input. > */ > }; > > /* > * One or more optional csis node. > * Contents unspecified by this binding. > */ > *csis { > /incomplete/; > }; > > /* > * One or more optional fimc-lite node. > * Contents unspecified by this binding. > */ > *fimc-lite { > /incomplete/; > }; > }; > > /* > * PCI device binding template (used by PCI bus binding) > */ > /template/ pci-device { > /* Compatible string matching any of listed regular expressions. */ > compatible = string("pciclass,([0-9a-f]{4})([0-9a-f]{2})?", > "pci([1-9a-f][0-9a-f]{0,3}|0),([1-9a-f][0-9a-f]{0,3}|0)\.([1-9a-f] [0-9 > a-f]{0,3})\.([1-9a-f][0-9a-f]{0,3}|0)\.([1-9a-f][0-9a-f]?|0)", > "pci([1-9a-f][0-9a-f]{0,3}|0),([1-9a-f][0-9a-f]{0,3}|0)\.([1-9a-f][0-9a- > f]{0,3})\.([1-9a-f][0-9a-f]{0,3}|0)", > "pci([1-9a-f][0-9a-f]{0,3}),([1-9a-f][0-9a-f]{0,3}|0)", > "pci([1-9a-f][0-9a-f]{0,3}|0),([1-9a-f][0-9a-f]{0,3}|0)\.([1-9a-f] [0-9 > a-f]?|0)", "pci([1-9a-f][0-9a-f]{0,3}|0),([1-9a-f][0-9a-f]{0,3}|0)", > "pciclass,([0-9a-f]{4})([0-9a-f]{2})?"); > /* Device name string. */ > name = string; > /* > * A set of 5-cell reg entries defined accordign to PCI binding > * specification. > */ > reg = (cell{5})+; > /* Optional interrupt specifier. */ > /use/ ?interrupts = { > interrupt-count = <1>; > }; > > /* Optional alternate reg property. */ > ?alternate-reg = (cell{5})+; > /* Optional single cell property. */ > ?fcode-rom-offset = cell; > /* Optional list of up to 6 Assigned addresses. */ > ?assigned-addresses = (cell{5}){0,6}; > /* Optional list of power consumption values - from 1 to 10 cells. */ > ?power-consumption = cell{1,10}; > > /* > * Simple single cell properties defined in PCI binding > * specification. > */ > vendor-id = cell; > device-id = cell; > revision-id = cell; > class-code = cell; > min-grant = cell; > max-latency = cell; > devsel-speed = cell; > ?cache-line-size = cell; > ?fast-back-to-back; > ?subsystem-id = cell; > ?subsystem-vendor-id = cell; > > /* Boolean properties. */ > ?66mhz-capable; > ?udf-supported; > > /* Extra per-device attributes are allowed. */ > /incomplete/; > }; > > /* > * PCI bus binding template > */ > /template/ pci-bus { > /* PCI bus node must have device_type set to "pci". */ > device_type = "pci"; > /* Standard bus attributes. */ > #address-cells = <3>; > #size-cells = <2>; > ranges; > > /* A set of optional properties. */ > ?bus-range = cell{2}; > ?clock-frequency = cell; > ?slot-names = cell, string+; > ?bus-master-capable = cell; > > /* PCI devices */ > * { > /use/ pci-device; > }; > }; > > /* > * NVIDIA Tegra PCIe controller > */ > { > /* Binding is identified by following compatible list. */ > compatible = string("nvidia,tegra20-pcie", "nvidia,tegra30-pcie"); > /* It is a PCI bus. */ > /use/ pci-bus; > /* Needs 3 reg entries. */ > /use/ reg-property { > reg-count = <3>; > }; > /* Names of reg entries must be specified as follows. */ > reg-names = "pads", "afi", "cs"; > /* Neds 2 interrupts. */ > /use/ interrupts { > interrupt-count = <2>; > }; > /* With names as specified below. */ > interrupt-names = "intr", "msi"; > /* Needs 5 clocks. */ > /use/ clocks { > clock-count = <5>; > }; > /* With following input names. */ > clock-names = "pex", "afi", "pcie_xclk", "pll_e", "cml"; > /* Needs pex-clk regulator. */ > /use/ regulator { > supply-name = "pex-clk"; > }; > /* Needs vdd regulator. */ > /use/ regulator { > supply-name = "vdd"; > }; > /* Needs avdd regulator. */ > /use/ regulator { > supply-name = "avdd"; > }; > > /* Root port nodes. */ > *pci { > /use/ pci-bus; > nvidia,num-lanes = cell; > }; > }; > > -- > To unsubscribe from this list: send the line "unsubscribe devicetree" in > the body of a message to majordomo@xxxxxxxxxxxxxxx > More majordomo info at http://vger.kernel.org/majordomo-info.html -- To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html