[linux-2.6-block.git] / Documentation / devicetree / bindings / writing-bindings.txt

DOs and DON'Ts for designing and writing Devicetree bindings

This is a list of common review feedback items focused on binding design. With
every rule, there are exceptions and bindings have many gray areas.

For guidelines related to patches, see
Documentation/devicetree/bindings/submitting-patches.txt


Overall design

- DO attempt to make bindings complete even if a driver doesn't support some
  features. For example, if a device has an interrupt, then include the
  'interrupts' property even if the driver is only polled mode.

- DON'T refer to Linux or "device driver" in bindings. Bindings should be
  based on what the hardware has, not what an OS and driver currently support.

- DO use node names matching the class of the device. Many standard names are
  defined in the DT Spec. If there isn't one, consider adding it.

- DO check that the example matches the documentation especially after making
  review changes.

- DON'T create nodes just for the sake of instantiating drivers. Multi-function
  devices only need child nodes when the child nodes have their own DT
  resources. A single node can be multiple providers (e.g. clocks and resets).

- DON'T use 'syscon' alone without a specific compatible string. A 'syscon'
  hardware block should have a compatible string unique enough to infer the
  register layout of the entire block (at a minimum).


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 subset
  of prior implementations. DO add new compatibles in case there are new
  features or bugs.

- DO use a vendor prefix on device specific property names. Consider if
  properties could be common among devices of the same class. Check other
  existing bindings for similar devices.

- DON'T redefine common properties. Just reference the definition and define
  constraints specific to the device.

- DO use common property unit suffixes for properties with scientific units.
  See property-units.txt.

- DO define properties in terms of constraints. How many entries? What are
  possible values? What is the order?


Board/SoC .dts Files

- DO put all MMIO devices under a bus node and not at the top-level.

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