Merge tag 'devicetree-for-5.8' of git://git.kernel.org/pub/scm/linux/kernel/git/robh/linux

Pull devicetree updates from Rob Herring:

 - Convert various DT (non-binding) doc files to ReST

 - Various improvements to device link code

 - Fix __of_attach_node_sysfs refcounting bug

 - Add support for 'memory-region-names' with reserved-memory binding

 - Vendor prefixes for Protonic Holland, BeagleBoard.org, Alps, Check
   Point, Würth Elektronik, U-Boot, Vaisala, Baikal Electronics,
   Shanghai Awinic Technology Co., MikroTik, Silex Insight

 - A bunch more binding conversions to DT schema. Only 3K to go.

 - Add a minimum version check for schema tools

 - Treewide dropping of 'allOf' usage with schema references. Not needed
   in new json-schema spec.

 - Some formatting clean-ups of schemas

* tag 'devicetree-for-5.8' of git://git.kernel.org/pub/scm/linux/kernel/git/robh/linux: (194 commits)
  dt-bindings: clock: Add documentation for X1830 bindings.
  dt-bindings: mailbox: Convert imx mu to json-schema
  dt-bindings: power: Convert imx gpcv2 to json-schema
  dt-bindings: power: Convert imx gpc to json-schema
  dt-bindings: Merge gpio-usb-b-connector with usb-connector
  dt-bindings: timer: renesas: cmt: Convert to json-schema
  dt-bindings: clock: Convert i.MX8QXP LPCG to json-schema
  dt-bindings: timer: Convert i.MX GPT to json-schema
  dt-bindings: thermal: rcar-thermal: Add device tree support for r8a7742
  dt-bindings: serial: Add binding for UART pin swap
  dt-bindings: geni-se: Add interconnect binding for GENI QUP
  dt-bindings: geni-se: Convert QUP geni-se bindings to YAML
  dt-bindings: vendor-prefixes: Add Silex Insight vendor prefix
  dt-bindings: input: touchscreen: edt-ft5x06: change reg property
  dt-bindings: usb: qcom,dwc3: Introduce interconnect properties for Qualcomm DWC3 driver
  dt-bindings: timer: renesas: mtu2: Convert to json-schema
  of/fdt: Remove redundant kbasename function call
  dt-bindings: clock: Convert i.MX1 clock to json-schema
  dt-bindings: clock: Convert i.MX21 clock to json-schema
  dt-bindings: clock: Convert i.MX25 clock to json-schema
  ...

1 files changed, 67 insertions, 0 deletions

diff --git a/Documentation/devicetree/bindings/writing-bindings.rst b/Documentation/devicetree/bindings/writing-bindings.rst
new file mode 100644
index 000000000000..45ff426d0019
--- /dev/null
+++ b/Documentation/devicetree/bindings/writing-bindings.rst
@@ -0,0 +1,67 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============================================================
+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.rst
+
+
+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.