On Tue, Nov 14, 2017 at 12:11 AM, David Gibson
<david@xxxxxxxxxxxxxxxxxxxxx> wrote:
> On Fri, Nov 03, 2017 at 04:11:46PM +0200, Pantelis Antoniou wrote:
>> Hi Rob,
>>
>> > On Nov 3, 2017, at 15:59 , Rob Herring <robh@xxxxxxxxxx> wrote:
>> >
>> > On Thu, Nov 2, 2017 at 11:44 AM, Grant Likely <grant.likely@xxxxxxxxxxxx> wrote:
>> >> Hi Pantelis and Rob,
>> >>
>> >> After the workshop next week, I'm trying to capture the direction
>> >> we're going for the schema format. Roughly I think we're aiming
>> >> towards:
>> >>
>> >> - Schema files to be written in YAML
>> >> - DT files shall remain written in DTS for the foreseeable future.
>> >> YAML will be treated as an intermediary format
>> >> - That said, we'll try to make design decisions that allow YAML to
>> >> be used as a source format.
>> >> - All schema files and yaml-encoded-dt files must be parsable by stock
>> >> YAML parsers
>> >> - Schema files to use the jsonschema vocabulary
>> >> - (jsonschema assumes json files, but YAML is a superset so this will be okay)
>> >> - Extended to add vocabulary for DT concepts (ignored by stock validators)
>> >> - C-like expressions as used in Pantelis' yamldt could be added in this way
>> >> - Need to write a jsonschema "metaschema" do define DT specific extensions
>> >> - metaschema will be used to validate format of schema files
>> >> - Existing tools can confirm is schema files are in the right format.
>> >> - will make review a lot easier.
>> >
>> > I want to start small here with defining top-level board/soc bindings.
>> > This is essentially just defining the root node compatible strings.
>> > Seems easy enough, right? However, I quickly run into the problem of
>> > how to match for when to apply the schema. "compatible" is the obvious
>> > choice, but that's also what I'm checking. We can't key off of what we
>> > are validating. So we really need 2 schema. The first is for matching
>> > on any valid compatible for board, then 2nd is checking for valid
>> > combinations (e.g. 1 board compatible followed by 1 SoC compatible). I
>> > don't like that as we'd be listing compatibles twice. An alternative
>> > would be we apply every board schema and exactly 1 must pass. Perhaps
>> > we generate a schema that's a "oneOf" of all the boards? Then we just
>> > need to tag board schemas in some way.
>> >
>>
>> I’ve run into this as the first problem with validation using compatible properties.
>>
>> The way I’ve solved it is by having a ‘selected’ property that is generating
>> a test for when to check a binding against a node.
>>
>> For a concrete example using the spi-slave binding
>>
>> —- spi-slave.yaml ---
>> ...
>> inherings: *device-compatible
>> …
>>
>> Where device compatible is:
>>
>> %YAML 1.1
>> ---
>> device-compatible: &device-compatible
>> title: Contraint for devices with compatible properties
>> # select node for checking when the compatible constraint and
>> # the device status enable constraint are met.
>> selected: [ "compatible", *device-status-enabled ]
>>
>> class: constraint
>> virtual: true
>>
>> The selected property here declares that any “compatible” property constraint
>> for the node under test must match and that the device-status-enabled
>> rule matches too.
>
> I think the basic idea of having a "selector" that says when the
> binding applies is correct. However, I think the details of this
> verison (AFAICT) are a bit too ad hoc.
>
> I think of it in terms of "patterns" which a node might or might not
> match. Those can be simple {compatible includes "blah"} or complex -
> a full set of binding requirements.
>
> Bindings will generally be of the form:
> if (PatternA) matches
> then (PatternB) must match
>
> e.g.
> if (compatible includes "blah")
> then ("blah" binding details) must match
>
> or
> if ("interrupts" exists)
> then (irq binding must apply)
>
> But in order to keep things general, both the "selector" and the
> "requirements" patterns should be specified in the same way.
>
> I had the feeling that jsonschema worked that way from Grant's talk,
> although I'm not 100% certain.
Yes, but it is only in the pre-release draft version at the moment.
jsonschema is proposing if/then/else keywords which behave pretty much
exactly as you describe. There is good discussion here:
https://github.com/json-schema-org/json-schema-spec/issues/180#issuecomment-266986089
g.
>
>>
>> The device-status-enabled is declared as follows:
>>
>> %YAML 1.1
>> ---
>> device-enabled:
>> title: Contraint for enabled devices
>>
>> class: constraint
>> virtual: true
>>
>> properties:
>> status: &device-status-enabled
>> category: optional
>> type: str
>> description: Marks device state as enabled
>> constraint: |
>> !exists || streq(v, "okay") || streq(v, "ok”)
>>
>> This declares that the constraint matches when either the optional
>> status property is not present or if it is, it’s either “okay” or “ok”.
>>
>> Taken together when the spi-slave binding is inherited (for instance
>> by the jedec,spi-nor binding:
>>
>> — jedec,spi-nor.yaml —
>>
>> …
>> inherits: *spi-slave
>>
>> …
>> compatible: &jedec-spi-nor-compatible
>> category: required
>> type: strseq
>> constraint: |
>> anystreq(v, "at25df321a") ||
>> ….
>>
>>
>> > I'm thinking of this very specific case, but no doubt it is going to
>> > apply in other places. This has been one of the harder problems with
>> > writing dtc checks. What to key off of to trigger checks and how to
>> > check errors in the key itself.
>> >
>> > Rob
>>
>> Regards
>>
>> — Pantelis
>>
>
> --
> David Gibson | I'll have my music baroque, and my code
> david AT gibson.dropbear.id.au | minimalist, thank you. NOT _the_ _other_
> | _way_ _around_!
> http://www.ozlabs.org/~dgibson
--
To unsubscribe from this list: send the line "unsubscribe devicetree-spec" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
