Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  3) ============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  4) DOs and DON'Ts for designing and writing Devicetree bindings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  5) ============================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  6) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  7) This is a list of common review feedback items focused on binding design. With
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) every rule, there are exceptions and bindings have many gray areas.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) For guidelines related to patches, see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) Documentation/devicetree/bindings/submitting-patches.rst
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) Overall design
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) - DO attempt to make bindings complete even if a driver doesn't support some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)   features. For example, if a device has an interrupt, then include the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)   'interrupts' property even if the driver is only polled mode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) - DON'T refer to Linux or "device driver" in bindings. Bindings should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)   based on what the hardware has, not what an OS and driver currently support.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) - DO use node names matching the class of the device. Many standard names are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)   defined in the DT Spec. If there isn't one, consider adding it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) - DO check that the example matches the documentation especially after making
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)   review changes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) - DON'T create nodes just for the sake of instantiating drivers. Multi-function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)   devices only need child nodes when the child nodes have their own DT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)   resources. A single node can be multiple providers (e.g. clocks and resets).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) - DON'T use 'syscon' alone without a specific compatible string. A 'syscon'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)   hardware block should have a compatible string unique enough to infer the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)   register layout of the entire block (at a minimum).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) Properties
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) - DO make 'compatible' properties specific. DON'T use wildcards in compatible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)   strings. DO use fallback compatibles when devices are the same as or a subset
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)   of prior implementations. DO add new compatibles in case there are new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)   features or bugs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) - DO use a vendor prefix on device specific property names. Consider if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)   properties could be common among devices of the same class. Check other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)   existing bindings for similar devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) - DON'T redefine common properties. Just reference the definition and define
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)   constraints specific to the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) - DO use common property unit suffixes for properties with scientific units.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)   See property-units.txt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) - DO define properties in terms of constraints. How many entries? What are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)   possible values? What is the order?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) Board/SoC .dts Files
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) ====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) - DO put all MMIO devices under a bus node and not at the top-level.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) - DO use non-empty 'ranges' to limit the size of child buses/devices. 64-bit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)   platforms don't need all devices to have 64-bit address and size.