diff options
| -rw-r--r-- | Documentation/devicetree/bindings/writing-bindings.rst | 27 |
1 files changed, 22 insertions, 5 deletions
diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst index 66c94b5adc87..962e38a1751a 100644 --- a/Documentation/devicetree/bindings/writing-bindings.rst +++ b/Documentation/devicetree/bindings/writing-bindings.rst @@ -39,10 +39,18 @@ Overall design Properties ========== -- DO make 'compatible' properties specific. DON'T use wildcards in compatible - strings. DO use fallback compatibles when devices are the same as or a - superset of prior implementations. DO add new compatibles in case there are - new features or bugs. +- DO make 'compatible' properties specific. + + - DON'T use wildcards or device-family names in compatible strings. + + - DO use fallback compatibles when devices are the same as or a superset of + prior implementations. + + - DO add new compatibles in case there are new features or bugs. + + - DO use a SoC-specific compatible for all SoC devices, followed by a + fallback if appropriate. SoC-specific compatibles are also preferred for + the fallbacks. - DO use a vendor prefix on device-specific property names. Consider if properties could be common among devices of the same class. Check other @@ -51,12 +59,21 @@ Properties - DON'T redefine common properties. Just reference the definition and define constraints specific to the device. +- DON'T add properties to avoid a specific compatible. DON'T add properties if + they are implied by (deducible from) the compatible. + - DO use common property unit suffixes for properties with scientific units. Recommended suffixes are listed at https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml - DO define properties in terms of constraints. How many entries? What are - possible values? What is the order? + possible values? What is the order? All these constraints represent the ABI + as well. + +- DON'T make changes that break the ABI without explicit and detailed rationale + for why the changes have to be made and their impact. ABI impact goes beyond + the Linux kernel, because it also covers other open-source upstream projects. + Typical cases and caveats ========================= |