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

Pull devicetree updates from Rob Herring:

 - Update dtc to upstream version v1.6.0-31-gcbca977ea121

 - dtx_diff help text reformatting

 - Speed-up validation time for binding and dtb checks using json for
   intermediate files

 - Add support for running yamllint on DT schema files

 - Remove old booting-without-of.rst

 - Extend the example schema to address common issues

 - Cleanup handling of additionalProperties/unevaluatedProperties

 - Ensure all DSI controller schemas reference dsi-controller.yaml

 - Vendor prefixes for Zealz, Wandbord/Technexion, Embest RIoT, Rex,
   DFI, and Cisco Meraki

 - Convert at25, SPMI bus, TI hwlock, HiSilicon Hi3660 USB3 PHY, Arm
   SP805 watchdog, Arm SP804, and Samsung 11-pin USB connector to DT
   schema

 - Convert HiSilicon SoC and syscon bindings to DT schema

 - Convert SiFive Risc-V L2 cache, PLIC, PRCI, and PWM to DT schema

 - Convert i.MX bindings for w1, crypto, rng, SIM, PM, DDR, SATA, vf610
   GPIO, and UART to DT schema

 - Add i.MX 8M compatible strings

 - Add LM81 and DS1780 as trivial devices

 - Various missing properties added to fix dtb validation warnings

* tag 'devicetree-for-5.10' of git://git.kernel.org/pub/scm/linux/kernel/git/robh/linux: (111 commits)
  dt-bindings: misc: explicitly add #address-cells for slave mode
  spi: dt-bindings: spi-controller: explicitly require #address-cells=<0> for slave mode
  dt: Remove booting-without-of.rst
  dt-bindings: update usb-c-connector example
  dt-bindings: arm: hisilicon: add missing properties into cpuctrl.yaml
  dt-bindings: arm: hisilicon: add missing properties into sysctrl.yaml
  dt-bindings: pwm: imx: document i.MX compatibles
  scripts/dtc: Update to upstream version v1.6.0-31-gcbca977ea121
  dt-bindings: Add running yamllint to dt_binding_check
  dt-bindings: powerpc: Add a schema for the 'sleep' property
  dt-bindings: pinctrl: sirf: Fix typo abitrary
  dt-bindings: pinctrl: qcom: Fix typo abitrary
  dt-bindings: Explicitly allow additional properties in common schemas
  dt-bindings: Use 'additionalProperties' instead of 'unevaluatedProperties'
  dt-bindings: Add missing 'unevaluatedProperties'
  Docs: Fixing spelling errors in Documentation/devicetree/bindings/
  dt-bindings: arm: hisilicon: convert Hi6220 domain controller bindings to json-schema
  dt-bindings: riscv: convert pwm bindings to json-schema
  dt-bindings: riscv: convert plic bindings to json-schema
  dt-bindings: fu540: prci: convert PRCI bindings to json-schema
  ...

2 files changed, 111 insertions, 0 deletions

diff --git a/Documentation/powerpc/booting.rst b/Documentation/powerpc/booting.rst
new file mode 100644
index 000000000000..2d0ec2ff2b57
--- /dev/null
+++ b/Documentation/powerpc/booting.rst
@@ -0,0 +1,110 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+DeviceTree Booting
+------------------
+
+During the development of the Linux/ppc64 kernel, and more specifically, the
+addition of new platform types outside of the old IBM pSeries/iSeries pair, it
+was decided to enforce some strict rules regarding the kernel entry and
+bootloader <-> kernel interfaces, in order to avoid the degeneration that had
+become the ppc32 kernel entry point and the way a new platform should be added
+to the kernel. The legacy iSeries platform breaks those rules as it predates
+this scheme, but no new board support will be accepted in the main tree that
+doesn't follow them properly.  In addition, since the advent of the arch/powerpc
+merged architecture for ppc32 and ppc64, new 32-bit platforms and 32-bit
+platforms which move into arch/powerpc will be required to use these rules as
+well.
+
+The main requirement that will be defined in more detail below is the presence
+of a device-tree whose format is defined after Open Firmware specification.
+However, in order to make life easier to embedded board vendors, the kernel
+doesn't require the device-tree to represent every device in the system and only
+requires some nodes and properties to be present. For example, the kernel does
+not require you to create a node for every PCI device in the system. It is a
+requirement to have a node for PCI host bridges in order to provide interrupt
+routing information and memory/IO ranges, among others. It is also recommended
+to define nodes for on chip devices and other buses that don't specifically fit
+in an existing OF specification. This creates a great flexibility in the way the
+kernel can then probe those and match drivers to device, without having to hard
+code all sorts of tables. It also makes it more flexible for board vendors to do
+minor hardware upgrades without significantly impacting the kernel code or
+cluttering it with special cases.
+
+
+Entry point
+~~~~~~~~~~~
+
+There is one single entry point to the kernel, at the start
+of the kernel image. That entry point supports two calling
+conventions:
+
+        a) Boot from Open Firmware. If your firmware is compatible
+        with Open Firmware (IEEE 1275) or provides an OF compatible
+        client interface API (support for "interpret" callback of
+        forth words isn't required), you can enter the kernel with:
+
+              r5 : OF callback pointer as defined by IEEE 1275
+              bindings to powerpc. Only the 32-bit client interface
+              is currently supported
+
+              r3, r4 : address & length of an initrd if any or 0
+
+              The MMU is either on or off; the kernel will run the
+              trampoline located in arch/powerpc/kernel/prom_init.c to
+              extract the device-tree and other information from open
+              firmware and build a flattened device-tree as described
+              in b). prom_init() will then re-enter the kernel using
+              the second method. This trampoline code runs in the
+              context of the firmware, which is supposed to handle all
+              exceptions during that time.
+
+        b) Direct entry with a flattened device-tree block. This entry
+        point is called by a) after the OF trampoline and can also be
+        called directly by a bootloader that does not support the Open
+        Firmware client interface. It is also used by "kexec" to
+        implement "hot" booting of a new kernel from a previous
+        running one. This method is what I will describe in more
+        details in this document, as method a) is simply standard Open
+        Firmware, and thus should be implemented according to the
+        various standard documents defining it and its binding to the
+        PowerPC platform. The entry point definition then becomes:
+
+                r3 : physical pointer to the device-tree block
+                (defined in chapter II) in RAM
+
+                r4 : physical pointer to the kernel itself. This is
+                used by the assembly code to properly disable the MMU
+                in case you are entering the kernel with MMU enabled
+                and a non-1:1 mapping.
+
+                r5 : NULL (as to differentiate with method a)
+
+Note about SMP entry: Either your firmware puts your other
+CPUs in some sleep loop or spin loop in ROM where you can get
+them out via a soft reset or some other means, in which case
+you don't need to care, or you'll have to enter the kernel
+with all CPUs. The way to do that with method b) will be
+described in a later revision of this document.
+
+Board supports (platforms) are not exclusive config options. An
+arbitrary set of board supports can be built in a single kernel
+image. The kernel will "know" what set of functions to use for a
+given platform based on the content of the device-tree. Thus, you
+should:
+
+        a) add your platform support as a _boolean_ option in
+        arch/powerpc/Kconfig, following the example of PPC_PSERIES,
+        PPC_PMAC and PPC_MAPLE. The later is probably a good
+        example of a board support to start from.
+
+        b) create your main platform file as
+        "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it
+        to the Makefile under the condition of your ``CONFIG_``
+        option. This file will define a structure of type "ppc_md"
+        containing the various callbacks that the generic code will
+        use to get to your platform specific code
+
+A kernel image may support multiple platforms, but only if the
+platforms feature the same core architecture.  A single kernel build
+cannot support both configurations with Book E and configurations
+with classic Powerpc architectures.
diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst
index 748bf483b1c2..6ec64b0d5257 100644
--- a/Documentation/powerpc/index.rst
+++ b/Documentation/powerpc/index.rst
@@ -7,6 +7,7 @@ powerpc
 .. toctree::
     :maxdepth: 1
 
+    booting
     bootwrapper
     cpu_families
     cpu_features