~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/devicetree/bindings/writing-bindings.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/devicetree/bindings/writing-bindings.rst (Architecture i386) and /Documentation/devicetree/bindings/writing-bindings.rst (Architecture sparc)


  1 .. SPDX-License-Identifier: GPL-2.0                 1 .. SPDX-License-Identifier: GPL-2.0
  2                                                     2 
  3 ==============================================      3 ============================================================
  4 DOs and DON'Ts for designing and writing Devic      4 DOs and DON'Ts for designing and writing Devicetree bindings
  5 ==============================================      5 ============================================================
  6                                                     6 
  7 This is a list of common review feedback items      7 This is a list of common review feedback items focused on binding design. With
  8 every rule, there are exceptions and bindings       8 every rule, there are exceptions and bindings have many gray areas.
  9                                                     9 
 10 For guidelines related to patches, see             10 For guidelines related to patches, see
 11 Documentation/devicetree/bindings/submitting-p     11 Documentation/devicetree/bindings/submitting-patches.rst
 12                                                    12 
 13                                                    13 
 14 Overall design                                     14 Overall design
 15 ==============                                     15 ==============
 16                                                    16 
 17 - DO attempt to make bindings complete even if     17 - DO attempt to make bindings complete even if a driver doesn't support some
 18   features. For example, if a device has an in     18   features. For example, if a device has an interrupt, then include the
 19   'interrupts' property even if the driver is      19   'interrupts' property even if the driver is only polled mode.
 20                                                    20 
 21 - DON'T refer to Linux or "device driver" in b     21 - DON'T refer to Linux or "device driver" in bindings. Bindings should be
 22   based on what the hardware has, not what an      22   based on what the hardware has, not what an OS and driver currently support.
 23                                                    23 
 24 - DO use node names matching the class of the      24 - DO use node names matching the class of the device. Many standard names are
 25   defined in the DT Spec. If there isn't one,      25   defined in the DT Spec. If there isn't one, consider adding it.
 26                                                    26 
 27 - DO check that the example matches the docume     27 - DO check that the example matches the documentation especially after making
 28   review changes.                                  28   review changes.
 29                                                    29 
 30 - DON'T create nodes just for the sake of inst     30 - DON'T create nodes just for the sake of instantiating drivers. Multi-function
 31   devices only need child nodes when the child     31   devices only need child nodes when the child nodes have their own DT
 32   resources. A single node can be multiple pro     32   resources. A single node can be multiple providers (e.g. clocks and resets).
 33                                                    33 
 34 - DON'T use 'syscon' alone without a specific      34 - DON'T use 'syscon' alone without a specific compatible string. A 'syscon'
 35   hardware block should have a compatible stri     35   hardware block should have a compatible string unique enough to infer the
 36   register layout of the entire block (at a mi     36   register layout of the entire block (at a minimum).
 37                                                    37 
 38                                                    38 
 39 Properties                                         39 Properties
 40 ==========                                         40 ==========
 41                                                    41 
 42 - DO make 'compatible' properties specific. DO     42 - DO make 'compatible' properties specific. DON'T use wildcards in compatible
 43   strings. DO use fallback compatibles when de     43   strings. DO use fallback compatibles when devices are the same as or a subset
 44   of prior implementations. DO add new compati     44   of prior implementations. DO add new compatibles in case there are new
 45   features or bugs.                                45   features or bugs.
 46                                                    46 
 47 - DO use a vendor prefix on device-specific pr     47 - DO use a vendor prefix on device-specific property names. Consider if
 48   properties could be common among devices of      48   properties could be common among devices of the same class. Check other
 49   existing bindings for similar devices.           49   existing bindings for similar devices.
 50                                                    50 
 51 - DON'T redefine common properties. Just refer     51 - DON'T redefine common properties. Just reference the definition and define
 52   constraints specific to the device.              52   constraints specific to the device.
 53                                                    53 
 54 - DO use common property unit suffixes for pro     54 - DO use common property unit suffixes for properties with scientific units.
 55   Recommended suffixes are listed at               55   Recommended suffixes are listed at
 56   https://github.com/devicetree-org/dt-schema/     56   https://github.com/devicetree-org/dt-schema/blob/main/dtschema/schemas/property-units.yaml
 57                                                    57 
 58 - DO define properties in terms of constraints     58 - DO define properties in terms of constraints. How many entries? What are
 59   possible values? What is the order?              59   possible values? What is the order?
 60                                                    60 
 61 Typical cases and caveats                          61 Typical cases and caveats
 62 =========================                          62 =========================
 63                                                    63 
 64 - Phandle entries, like clocks/dmas/interrupts     64 - Phandle entries, like clocks/dmas/interrupts/resets, should always be
 65   explicitly ordered. Include the {clock,dma,i     65   explicitly ordered. Include the {clock,dma,interrupt,reset}-names if there is
 66   more than one phandle. When used, both of th     66   more than one phandle. When used, both of these fields need the same
 67   constraints (e.g.  list of items).               67   constraints (e.g.  list of items).
 68                                                    68 
 69 - For names used in {clock,dma,interrupt,reset     69 - For names used in {clock,dma,interrupt,reset}-names, do not add any suffix,
 70   e.g.: "tx" instead of "txirq" (for interrupt     70   e.g.: "tx" instead of "txirq" (for interrupt).
 71                                                    71 
 72 - Properties without schema types (e.g. withou     72 - Properties without schema types (e.g. without standard suffix or not defined
 73   by schema) need the type, even if this is an     73   by schema) need the type, even if this is an enum.
 74                                                    74 
 75 - If schema includes other schema (e.g. /schem     75 - If schema includes other schema (e.g. /schemas/i2c/i2c-controller.yaml) use
 76   "unevaluatedProperties:false". In other case     76   "unevaluatedProperties:false". In other cases, usually use
 77   "additionalProperties:false".                    77   "additionalProperties:false".
 78                                                    78 
 79 - For sub-blocks/components of bigger device (     79 - For sub-blocks/components of bigger device (e.g. SoC blocks) use rather
 80   device-based compatible (e.g. SoC-based comp     80   device-based compatible (e.g. SoC-based compatible), instead of custom
 81   versioning of that component.                    81   versioning of that component.
 82   For example use "vendor,soc1234-i2c" instead     82   For example use "vendor,soc1234-i2c" instead of "vendor,i2c-v2".
 83                                                    83 
 84 - "syscon" is not a generic property. Use vend     84 - "syscon" is not a generic property. Use vendor and type, e.g.
 85   "vendor,power-manager-syscon".                   85   "vendor,power-manager-syscon".
 86                                                    86 
 87 Board/SoC .dts Files                               87 Board/SoC .dts Files
 88 ====================                               88 ====================
 89                                                    89 
 90 - DO put all MMIO devices under a bus node and     90 - DO put all MMIO devices under a bus node and not at the top-level.
 91                                                    91 
 92 - DO use non-empty 'ranges' to limit the size      92 - DO use non-empty 'ranges' to limit the size of child buses/devices. 64-bit
 93   platforms don't need all devices to have 64-     93   platforms don't need all devices to have 64-bit address and size.
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php