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
- 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
=========================