Compatibles with multiple entries should have usually only one fallback
compatible thus enum followed by enum is not a common case. Use 'const'
as second compatible to show the recommended approach.
Explain also when clock-names are not really necessary.
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Link: https://lore.kernel.org/r/20230612092611.12385-1-krzysztof.kozlowski@linaro.org
Signed-off-by: Rob Herring <robh@kernel.org>
Just as unevaluatedProperties or additionalProperties are required at
the top level of schemas, they should (and will) also be required for
child node schemas. That ensures only documented properties are
present.
Add unevaluatedProperties or additionalProperties as appropriate, and
then add any missing properties flagged by the addition.
Acked-by: Sebastian Reichel <sebastian.reichel@collabora.com>
Acked-by: Guenter Roeck <linux@roeck-us.net>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Acked-by: Mark Brown <broonie@kernel.org>
Acked-by: Lee Jones <lee@kernel.org>
Reviewed-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Link: https://lore.kernel.org/r/20230124230228.372305-1-robh@kernel.org
Signed-off-by: Rob Herring <robh@kernel.org>
The Devicetree bindings document does not have to say in the title that
it is a "Devicetree binding" or a "schema", but instead just describe
the hardware.
Manual updates to various binding titles, including capitalizing them.
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com>
Reviewed-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
Acked-by: Ulf Hansson <ulf.hansson@linaro.org> # MMC
Acked-by: Stephen Boyd <sboyd@kernel.org> # clk
Acked-by: Dmitry Torokhov <dmitry.torokhov@gmail.com> # input
Acked-by: Mark Brown <broonie@kernel.org>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org> # opp
Link: https://lore.kernel.org/r/20221216163815.522628-10-krzysztof.kozlowski@linaro.org
[robh: add trivial-devices.yaml and net/can/microchip,mcp251xfd.yaml]
Signed-off-by: Rob Herring <robh@kernel.org>
Mention the usage of YAML coding style. Describe explicitly that
four-space indentation in DTS examples is preferred, because:
1. The YAML's default two-space indentation for DTS code makes it
significantly less readable.
2. Linux coding style tabs would introduce inconsistency (entire file is
indented with spaces).
3. On the other hand, eight spaces would not align with example's
opening ' - |' part. Four spaces makes the code nicely aligned with
it.
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Signed-off-by: Rob Herring <robh@kernel.org>
Link: https://lore.kernel.org/r/20220403081849.8051-2-krzysztof.kozlowski@linaro.org
Extend the example with:
- an array where each element has constraints (min/max value),
- property not allowed in case of different compatible.
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
Signed-off-by: Rob Herring <robh@kernel.org>
Link: https://lore.kernel.org/r/20220223073547.8746-2-krzysztof.kozlowski@canonical.com
If a property has an 'items' list, then a 'minItems' or 'maxItems' with the
same size as the list is redundant and can be dropped. Note that is DT
schema specific behavior and not standard json-schema behavior. The tooling
will fixup the final schema adding any unspecified minItems/maxItems.
This condition is partially checked with the meta-schema already, but
only if both 'minItems' and 'maxItems' are equal to the 'items' length.
An improved meta-schema is pending.
Cc: Jens Axboe <axboe@kernel.dk>
Cc: Stephen Boyd <sboyd@kernel.org>
Cc: Herbert Xu <herbert@gondor.apana.org.au>
Cc: "David S. Miller" <davem@davemloft.net>
Cc: David Airlie <airlied@linux.ie>
Cc: Daniel Vetter <daniel@ffwll.ch>
Cc: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Cc: Kamal Dasu <kdasu.kdev@gmail.com>
Cc: Lars-Peter Clausen <lars@metafoo.de>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Marc Zyngier <maz@kernel.org>
Cc: Joerg Roedel <joro@8bytes.org>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Krzysztof Kozlowski <krzysztof.kozlowski@canonical.com>
Cc: Jakub Kicinski <kuba@kernel.org>
Cc: Wolfgang Grandegger <wg@grandegger.com>
Cc: Andrew Lunn <andrew@lunn.ch>
Cc: Vivien Didelot <vivien.didelot@gmail.com>
Cc: Vladimir Oltean <olteanv@gmail.com>
Cc: Bjorn Helgaas <bhelgaas@google.com>
Cc: Kishon Vijay Abraham I <kishon@ti.com>
Cc: Linus Walleij <linus.walleij@linaro.org>
Cc: "Uwe Kleine-König" <u.kleine-koenig@pengutronix.de>
Cc: Lee Jones <lee.jones@linaro.org>
Cc: Ohad Ben-Cohen <ohad@wizery.com>
Cc: Mathieu Poirier <mathieu.poirier@linaro.org>
Cc: Paul Walmsley <paul.walmsley@sifive.com>
Cc: Palmer Dabbelt <palmer@dabbelt.com>
Cc: Albert Ou <aou@eecs.berkeley.edu>
Cc: Alessandro Zummo <a.zummo@towertech.it>
Cc: Alexandre Belloni <alexandre.belloni@bootlin.com>
Cc: Zhang Rui <rui.zhang@intel.com>
Cc: Daniel Lezcano <daniel.lezcano@linaro.org>
Cc: Wim Van Sebroeck <wim@linux-watchdog.org>
Cc: Guenter Roeck <linux@roeck-us.net>
Signed-off-by: Rob Herring <robh@kernel.org>
Acked-by: Marc Kleine-Budde <mkl@pengutronix.de>
Acked-by: Ulf Hansson <ulf.hansson@linaro.org> # for MMC
Acked-by: Jassi Brar <jassisinghbrar@gmail.com>
Acked-By: Vinod Koul <vkoul@kernel.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Arnaud Pouliquen <arnaud.pouliquen@st.com>
Acked-by: Mark Brown <broonie@kernel.org>
Acked-by: Philipp Zabel <p.zabel@pengutronix.de>
Acked-by: Wolfram Sang <wsa@kernel.org> # for I2C
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
Link: https://lore.kernel.org/r/20210615191543.1043414-1-robh@kernel.org
Improve grammar in recently added sentences:
- Drop superfluous "be" in front of "have",
- Add missing articles.
Fixes: 73f76a41c4 ("dt-bindings: example: Extend based on practice")
Reviewed-by: Krzysztof Kozlowski <krzk@kernel.org>
Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Link: https://lore.kernel.org/r/20200925111429.3146-1-geert+renesas@glider.be
Signed-off-by: Rob Herring <robh@kernel.org>
Extend the example schema with common rules which seems to be not that
obvious:
1. Expecting arrays of phandles to be always ordered, regardless if
"xxx-names" is provided (e.g. clocks),
2. Add example of altering a property based on presence of other
property,
3. Document usage of unevaluatedProperties.
Signed-off-by: Krzysztof Kozlowski <krzk@kernel.org>
Link: https://lore.kernel.org/r/20200910184706.9677-1-krzk@kernel.org
Signed-off-by: Rob Herring <robh@kernel.org>
json-schema versions draft7 and earlier have a weird behavior in that
any keywords combined with a '$ref' are ignored (silently). The correct
form was to put a '$ref' under an 'allOf'. This behavior is now changed
in the 2019-09 json-schema spec and '$ref' can be mixed with other
keywords. The json-schema library doesn't yet support this, but the
tooling now does a fixup for this and either way works.
This has been a constant source of review comments, so let's change this
treewide so everyone copies the simpler syntax.
Scripted with ruamel.yaml with some manual fixups. Some minor whitespace
changes from the script.
Signed-off-by: Rob Herring <robh@kernel.org>
Acked-by: Maxime Ripard <mripard@kernel.org>
Acked-by: Lee Jones <lee.jones@linaro.org>
Acked-By: Vinod Koul <vkoul@kernel.org>
Acked-by: Mark Brown <broonie@kernel.org>
Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com>
Acked-by: Wolfram Sang <wsa@the-dreams.de> # for I2C
Reviewed-by: Linus Walleij <linus.walleij@linaro.org>
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> #for-iio
Reviewed-by: Stephen Boyd <sboyd@kernel.org> # clock
Signed-off-by: Rob Herring <robh@kernel.org>
It is no longer needed to wrap URLs in double quotes.
Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Rob Herring <robh@kernel.org>
Even the DT maintainer gets confused. The schema in dt-schema was wrong
too, so this was passing validation until trying to add some common
incorrect patterns to check.
Fixes: 58fbe999ff ("dt-bindings: example-schema: Add some additional examples and commentary")
Signed-off-by: Rob Herring <robh@kernel.org>
Add examples for properties with standard units, child nodes,
dependencies, and if/then schema. Also, make some minor updates based on
common questions and review issues.
Signed-off-by: Rob Herring <robh@kernel.org>
Add a how-to doc on writing DT schema documentation. This gives a
description of each section and details on how to validate the DT schema
file. The DT schema are written using json-schema vocabulary in a YAML
encoded document. Using jsonschema gives us access to existing tooling.
A YAML encoding gives us something easy to edit. The example is
annotated to help explain what each section does.
This example is just the tip of the iceberg, but is it the part most
developers writing bindings will interact with. Backing all this up
are meta-schema (to validate the binding schemas), some DT core schema,
YAML encoded DT output with dtc, and a small number of python scripts to
run validation.
Cc: Mark Rutland <mark.rutland@arm.com>
Cc: devicetree@vger.kernel.org
Signed-off-by: Rob Herring <robh@kernel.org>
