kernel/git/stable/linux.git/Documentation/devicetree/bindings/writing-bindings.rst, branch master

docs: dt: writing-bindings: Extend compatible fallbacks guideline

2026-05-05T15:40:08+00:00

Extend the guidelines when to use fallback compatibles to cover to common review responses. Devices are most likely compatible and should use fallbacks when having: 1. Compatible programming interface, meaning one is a subset, and Linux device drivers can use the subset to correctly match/bind and still operate with the subset features. 2. Device variant discovery through some means, like registers. Devices are incompatible and fallback is not suitable when that fallback cannot be used by the drivers to match/bind. In the same time commit message should clearly explain when the code suggests devices are compatible, but the binding does not define them as such. Acked-by: Conor Dooley Signed-off-by: Krzysztof Kozlowski Link: https://patch.msgid.link/20260427160739.175451-2-krzysztof.kozlowski@oss.qualcomm.com Signed-off-by: Rob Herring (Arm)

docs: dt: writing-bindings: Document node name ABI and simple-mfd

2025-09-03T14:01:25+00:00

Document established Devicetree bindings maintainers review practice: 1. Device node names should not be treated as an ABI, unless for children of a device when documented. There were many patches posted using of_find_node_by_name() or of_node_name_eq() for accessing siblings or completely different nodes. These cases were introducing undocumented ABI, so they are discouraged. 2. 'simple-mfd' means children do not depend on parent device resources. 'simple-bus' is so simple, that even 'reg' properties are not applicable. Signed-off-by: Krzysztof Kozlowski Link: https://lore.kernel.org/r/20250818132534.120217-2-krzysztof.kozlowski@linaro.org Signed-off-by: Rob Herring (Arm)

docs: dt: writing-bindings: Document discouraged instance IDs

2025-07-14T21:23:52+00:00

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 Reviewed-by: Conor Dooley Link: https://lore.kernel.org/r/20250713-dt-bindings-docs-v2-3-672c898054ae@linaro.org Signed-off-by: Rob Herring (Arm)

docs: dt: writing-bindings: Document compatible and filename naming

2025-07-14T21:23:52+00:00

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 Reviewed-by: Conor Dooley Link: https://lore.kernel.org/r/20250713-dt-bindings-docs-v2-2-672c898054ae@linaro.org Signed-off-by: Rob Herring (Arm)

docs: dt: writing-bindings: Consistently use single-whitespace

2025-07-08T12:22:22+00:00

Document uses only single whitespace after full stop, so fix inconsistency. Signed-off-by: Krzysztof Kozlowski Reviewed-by: Conor Dooley Link: https://lore.kernel.org/r/20250707095019.66792-6-krzysztof.kozlowski@linaro.org Signed-off-by: Rob Herring (Arm)

docs: dt: writing-bindings: Express better expectations of "specific"

2025-07-08T12:22:12+00:00

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 Reviewed-by: Conor Dooley Link: https://lore.kernel.org/r/20250707095019.66792-5-krzysztof.kozlowski@linaro.org Signed-off-by: Rob Herring (Arm)

docs: dt: writing-bindings: Rephrase typical fallback (superset) usage

2025-07-08T12:20:04+00:00

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 Signed-off-by: Krzysztof Kozlowski Reviewed-by: Conor Dooley Link: https://lore.kernel.org/r/20250707095019.66792-4-krzysztof.kozlowski@linaro.org Signed-off-by: Rob Herring (Arm)

docs: dt: writing-bindings: Update URL to DT schemas

2022-06-30T21:38:25+00:00

The previous URL was giving a 404 error. Signed-off-by: Paul Cercueil Reviewed-by: Krzysztof Kozlowski Signed-off-by: Rob Herring Link: https://lore.kernel.org/r/20220627223950.35748-1-paul@crapouillou.net

docs: dt: writing-bindings: describe typical cases

2022-04-05T00:55:03+00:00

Add a chapter for caveats or typical mistakes. Source: Rob Herring's (Devicetree bindings maintainer) comments on LKML. Signed-off-by: Krzysztof Kozlowski Signed-off-by: Rob Herring Link: https://lore.kernel.org/r/20220403081849.8051-1-krzysztof.kozlowski@linaro.org

docs: dt: Fix a few grammar nits in the binding/schema docs

2021-10-04T18:55:37+00:00

Add missing hyphens and reword one sentence for clarity. Signed-off-by: Simon Glass Reviewed-by: Randy Dunlap Link: https://lore.kernel.org/r/20211003124936.1.Idc7beddc77250bca0cfb5912b56be719d9073bc4@changeid Signed-off-by: Rob Herring