Document established Devicetree bindings maintainers review practice:
instance indexes, either as properties or as custom new OF alias, are
not accepted. Recommended way is to use, depending on the
situation/hardware: different compatible, cell arguments or syscon
phandle arguments.
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
Link: https://lore.kernel.org/r/20250713-dt-bindings-docs-v2-3-672c898054ae@linaro.org
Signed-off-by: Rob Herring (Arm) <robh@kernel.org>
Document established Devicetree bindings maintainers review practices:
1. Compatibles should not use bus suffixes to encode the type of
interface, because the parent bus node defines that interface, e.g.
"vendor,device" instead of "vendor,device-i2c" + "vendor,device-spi".
2. If the compatible represents the device as a whole, it should not
contain the type of device in the name.
3. Filenames should match compatible. The best if match is 100%, but if
binding has multiple compatibles, then one of the fallbacks should be
used. Alternatively a genericish name is allowed if it follows
"vendor,device" style.
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
Link: https://lore.kernel.org/r/20250713-dt-bindings-docs-v2-2-672c898054ae@linaro.org
Signed-off-by: Rob Herring (Arm) <robh@kernel.org>
Document uses only single whitespace after full stop, so fix
inconsistency.
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
Link: https://lore.kernel.org/r/20250707095019.66792-6-krzysztof.kozlowski@linaro.org
Signed-off-by: Rob Herring (Arm) <robh@kernel.org>
Devicetree bindings are supposed to be specific in terms of compatibles
and other properties. Short "specific" has many implications, so extend
the description to cover them:
1. Mention no family names and avoid generic SoC fallbacks in
compatible. The list grew, mixing DO's and DON'T's, so split it into
multiple items.
2. No properties implied by the compatible.
3. Document desired lack of ABI impact and acceptable solution if such
needs arises: clearly marking it in commit msg.
All above follows established Devicetree bindings maintainers review
practice, so no new rules in practice are introduced here.
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
Link: https://lore.kernel.org/r/20250707095019.66792-5-krzysztof.kozlowski@linaro.org
Signed-off-by: Rob Herring (Arm) <robh@kernel.org>
When speaking about compatibles for new devices comparing to "prior
implementations", usually we expect new device to come with more
features, thus logically it is a superset, not subset, of "prior
implementations".
Suggested-by: Conor Dooley <conor@kernel.org>
Signed-off-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Reviewed-by: Conor Dooley <conor.dooley@microchip.com>
Link: https://lore.kernel.org/r/20250707095019.66792-4-krzysztof.kozlowski@linaro.org
Signed-off-by: Rob Herring (Arm) <robh@kernel.org>
The previous URL was giving a 404 error.
Signed-off-by: Paul Cercueil <paul@crapouillou.net>
Reviewed-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
Signed-off-by: Rob Herring <robh@kernel.org>
Link: https://lore.kernel.org/r/20220627223950.35748-1-paul@crapouillou.net
Add a chapter for caveats or typical mistakes. Source: Rob Herring's
(Devicetree bindings maintainer) comments on LKML.
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-1-krzysztof.kozlowski@linaro.org
property-units.txt is not maintained anymore. New suffixes are now
supported that have not been added here.
To avoid people incorrectly think a given suffix is not in the list remove
the file entirely and point to the authoritative place where the
recommended suffixes are maintained.
Signed-off-by: Luca Ceresoli <luca@lucaceresoli.net>
Link: https://lore.kernel.org/r/20210512152311.7399-1-luca@lucaceresoli.net
Signed-off-by: Rob Herring <robh@kernel.org>
- Add a SPDX header;
- Adjust document and section titles;
- Mark literal blocks as such;
- Add it to bindings/index.rst.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Rob Herring <robh@kernel.org>
