^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) Linux and the Device Tree
^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) The Linux usage model for device tree data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) :Author: Grant Likely <grant.likely@secretlab.ca>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) This article describes how Linux uses the device tree. An overview of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) the device tree data format can be found on the device tree usage page
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) at devicetree.org\ [1]_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) .. [1] https://elinux.org/Device_Tree_Usage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) The "Open Firmware Device Tree", or simply Device Tree (DT), is a data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) structure and language for describing hardware. More specifically, it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) is a description of hardware that is readable by an operating system
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) so that the operating system doesn't need to hard code details of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) machine.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) Structurally, the DT is a tree, or acyclic graph with named nodes, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) nodes may have an arbitrary number of named properties encapsulating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) arbitrary data. A mechanism also exists to create arbitrary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) links from one node to another outside of the natural tree structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) Conceptually, a common set of usage conventions, called 'bindings',
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) is defined for how data should appear in the tree to describe typical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) hardware characteristics including data busses, interrupt lines, GPIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) connections, and peripheral devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) As much as possible, hardware is described using existing bindings to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) maximize use of existing support code, but since property and node
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) names are simply text strings, it is easy to extend existing bindings
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) or create new ones by defining new nodes and properties. Be wary,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) however, of creating a new binding without first doing some homework
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) about what already exists. There are currently two different,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) incompatible, bindings for i2c busses that came about because the new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) binding was created without first investigating how i2c devices were
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) already being enumerated in existing systems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) 1. History
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) ----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) The DT was originally created by Open Firmware as part of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) communication method for passing data from Open Firmware to a client
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) program (like to an operating system). An operating system used the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) Device Tree to discover the topology of the hardware at runtime, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) thereby support a majority of available hardware without hard coded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) information (assuming drivers were available for all devices).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) Since Open Firmware is commonly used on PowerPC and SPARC platforms,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) the Linux support for those architectures has for a long time used the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) Device Tree.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) In 2005, when PowerPC Linux began a major cleanup and to merge 32-bit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) and 64-bit support, the decision was made to require DT support on all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) powerpc platforms, regardless of whether or not they used Open
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) Firmware. To do this, a DT representation called the Flattened Device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) Tree (FDT) was created which could be passed to the kernel as a binary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) blob without requiring a real Open Firmware implementation. U-Boot,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) kexec, and other bootloaders were modified to support both passing a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) Device Tree Binary (dtb) and to modify a dtb at boot time. DT was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) also added to the PowerPC boot wrapper (``arch/powerpc/boot/*``) so that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) a dtb could be wrapped up with the kernel image to support booting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) existing non-DT aware firmware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) Some time later, FDT infrastructure was generalized to be usable by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) all architectures. At the time of this writing, 6 mainlined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) architectures (arm, microblaze, mips, powerpc, sparc, and x86) and 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) out of mainline (nios) have some level of DT support.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) 2. Data Model
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) If you haven't already read the Device Tree Usage\ [1]_ page,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) then go read it now. It's okay, I'll wait....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) 2.1 High Level View
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) The most important thing to understand is that the DT is simply a data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) structure that describes the hardware. There is nothing magical about
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) it, and it doesn't magically make all hardware configuration problems
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) go away. What it does do is provide a language for decoupling the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) hardware configuration from the board and device driver support in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) Linux kernel (or any other operating system for that matter). Using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) it allows board and device support to become data driven; to make
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) setup decisions based on data passed into the kernel instead of on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) per-machine hard coded selections.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) Ideally, data driven platform setup should result in less code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) duplication and make it easier to support a wide range of hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) with a single kernel image.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) Linux uses DT data for three major purposes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) 1) platform identification,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) 2) runtime configuration, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) 3) device population.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) 2.2 Platform Identification
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) ---------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) First and foremost, the kernel will use data in the DT to identify the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) specific machine. In a perfect world, the specific platform shouldn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) matter to the kernel because all platform details would be described
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) perfectly by the device tree in a consistent and reliable manner.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) Hardware is not perfect though, and so the kernel must identify the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) machine during early boot so that it has the opportunity to run
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) machine-specific fixups.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) In the majority of cases, the machine identity is irrelevant, and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) kernel will instead select setup code based on the machine's core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) CPU or SoC. On ARM for example, setup_arch() in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) arch/arm/kernel/setup.c will call setup_machine_fdt() in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) arch/arm/kernel/devtree.c which searches through the machine_desc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) table and selects the machine_desc which best matches the device tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) data. It determines the best match by looking at the 'compatible'
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) property in the root device tree node, and comparing it with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) dt_compat list in struct machine_desc (which is defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) arch/arm/include/asm/mach/arch.h if you're curious).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) The 'compatible' property contains a sorted list of strings starting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) with the exact name of the machine, followed by an optional list of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) boards it is compatible with sorted from most compatible to least. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) example, the root compatible properties for the TI BeagleBoard and its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) successor, the BeagleBoard xM board might look like, respectively::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) compatible = "ti,omap3-beagleboard", "ti,omap3450", "ti,omap3";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) compatible = "ti,omap3-beagleboard-xm", "ti,omap3450", "ti,omap3";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) Where "ti,omap3-beagleboard-xm" specifies the exact model, it also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) claims that it compatible with the OMAP 3450 SoC, and the omap3 family
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) of SoCs in general. You'll notice that the list is sorted from most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) specific (exact board) to least specific (SoC family).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) Astute readers might point out that the Beagle xM could also claim
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) compatibility with the original Beagle board. However, one should be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) cautioned about doing so at the board level since there is typically a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) high level of change from one board to another, even within the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) product line, and it is hard to nail down exactly what is meant when one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) board claims to be compatible with another. For the top level, it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) better to err on the side of caution and not claim one board is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) compatible with another. The notable exception would be when one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) board is a carrier for another, such as a CPU module attached to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) carrier board.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) One more note on compatible values. Any string used in a compatible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) property must be documented as to what it indicates. Add
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) documentation for compatible strings in Documentation/devicetree/bindings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) Again on ARM, for each machine_desc, the kernel looks to see if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) any of the dt_compat list entries appear in the compatible property.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) If one does, then that machine_desc is a candidate for driving the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) machine. After searching the entire table of machine_descs,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) setup_machine_fdt() returns the 'most compatible' machine_desc based
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) on which entry in the compatible property each machine_desc matches
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) against. If no matching machine_desc is found, then it returns NULL.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) The reasoning behind this scheme is the observation that in the majority
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) of cases, a single machine_desc can support a large number of boards
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) if they all use the same SoC, or same family of SoCs. However,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) invariably there will be some exceptions where a specific board will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) require special setup code that is not useful in the generic case.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) Special cases could be handled by explicitly checking for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) troublesome board(s) in generic setup code, but doing so very quickly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) becomes ugly and/or unmaintainable if it is more than just a couple of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) cases.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) Instead, the compatible list allows a generic machine_desc to provide
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) support for a wide common set of boards by specifying "less
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) compatible" values in the dt_compat list. In the example above,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) generic board support can claim compatibility with "ti,omap3" or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) "ti,omap3450". If a bug was discovered on the original beagleboard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) that required special workaround code during early boot, then a new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) machine_desc could be added which implements the workarounds and only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) matches on "ti,omap3-beagleboard".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) PowerPC uses a slightly different scheme where it calls the .probe()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) hook from each machine_desc, and the first one returning TRUE is used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) However, this approach does not take into account the priority of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) compatible list, and probably should be avoided for new architecture
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) support.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) 2.3 Runtime configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) In most cases, a DT will be the sole method of communicating data from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) firmware to the kernel, so also gets used to pass in runtime and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) configuration data like the kernel parameters string and the location
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) of an initrd image.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) Most of this data is contained in the /chosen node, and when booting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) Linux it will look something like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) chosen {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) bootargs = "console=ttyS0,115200 loglevel=8";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) initrd-start = <0xc8000000>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) initrd-end = <0xc8200000>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) The bootargs property contains the kernel arguments, and the initrd-*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) properties define the address and size of an initrd blob. Note that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) initrd-end is the first address after the initrd image, so this doesn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) match the usual semantic of struct resource. The chosen node may also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) optionally contain an arbitrary number of additional properties for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) platform-specific configuration data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) During early boot, the architecture setup code calls of_scan_flat_dt()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) several times with different helper callbacks to parse device tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) data before paging is setup. The of_scan_flat_dt() code scans through
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) the device tree and uses the helpers to extract information required
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) during early boot. Typically the early_init_dt_scan_chosen() helper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) is used to parse the chosen node including kernel parameters,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) early_init_dt_scan_root() to initialize the DT address space model,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) and early_init_dt_scan_memory() to determine the size and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) location of usable RAM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) On ARM, the function setup_machine_fdt() is responsible for early
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) scanning of the device tree after selecting the correct machine_desc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) that supports the board.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) 2.4 Device population
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) After the board has been identified, and after the early configuration data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) has been parsed, then kernel initialization can proceed in the normal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) way. At some point in this process, unflatten_device_tree() is called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) to convert the data into a more efficient runtime representation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) This is also when machine-specific setup hooks will get called, like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) the machine_desc .init_early(), .init_irq() and .init_machine() hooks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) on ARM. The remainder of this section uses examples from the ARM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) implementation, but all architectures will do pretty much the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) thing when using a DT.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) As can be guessed by the names, .init_early() is used for any machine-
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) specific setup that needs to be executed early in the boot process,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) and .init_irq() is used to set up interrupt handling. Using a DT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) doesn't materially change the behaviour of either of these functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) If a DT is provided, then both .init_early() and .init_irq() are able
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) to call any of the DT query functions (of_* in include/linux/of*.h) to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) get additional data about the platform.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) The most interesting hook in the DT context is .init_machine() which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) is primarily responsible for populating the Linux device model with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) data about the platform. Historically this has been implemented on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) embedded platforms by defining a set of static clock structures,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) platform_devices, and other data in the board support .c file, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) registering it en-masse in .init_machine(). When DT is used, then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) instead of hard coding static devices for each platform, the list of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) devices can be obtained by parsing the DT, and allocating device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) structures dynamically.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) The simplest case is when .init_machine() is only responsible for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) registering a block of platform_devices. A platform_device is a concept
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) used by Linux for memory or I/O mapped devices which cannot be detected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) by hardware, and for 'composite' or 'virtual' devices (more on those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) later). While there is no 'platform device' terminology for the DT,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) platform devices roughly correspond to device nodes at the root of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) tree and children of simple memory mapped bus nodes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) About now is a good time to lay out an example. Here is part of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) device tree for the NVIDIA Tegra board::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) /{
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) compatible = "nvidia,harmony", "nvidia,tegra20";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) #address-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) #size-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) interrupt-parent = <&intc>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) chosen { };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) aliases { };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) memory {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) device_type = "memory";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) reg = <0x00000000 0x40000000>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) soc {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) compatible = "nvidia,tegra20-soc", "simple-bus";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) #address-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) #size-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) ranges;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) intc: interrupt-controller@50041000 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) compatible = "nvidia,tegra20-gic";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) interrupt-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) #interrupt-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) reg = <0x50041000 0x1000>, < 0x50040100 0x0100 >;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) serial@70006300 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) compatible = "nvidia,tegra20-uart";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) reg = <0x70006300 0x100>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) interrupts = <122>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) i2s1: i2s@70002800 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) compatible = "nvidia,tegra20-i2s";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) reg = <0x70002800 0x100>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) interrupts = <77>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) codec = <&wm8903>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) i2c@7000c000 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) compatible = "nvidia,tegra20-i2c";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) #address-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) #size-cells = <0>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) reg = <0x7000c000 0x100>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) interrupts = <70>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) wm8903: codec@1a {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) compatible = "wlf,wm8903";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) reg = <0x1a>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) interrupts = <347>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) sound {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) compatible = "nvidia,harmony-sound";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) i2s-controller = <&i2s1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) i2s-codec = <&wm8903>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) At .init_machine() time, Tegra board support code will need to look at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) this DT and decide which nodes to create platform_devices for.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) However, looking at the tree, it is not immediately obvious what kind
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) of device each node represents, or even if a node represents a device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) at all. The /chosen, /aliases, and /memory nodes are informational
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) nodes that don't describe devices (although arguably memory could be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) considered a device). The children of the /soc node are memory mapped
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) devices, but the codec@1a is an i2c device, and the sound node
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) represents not a device, but rather how other devices are connected
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) together to create the audio subsystem. I know what each device is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) because I'm familiar with the board design, but how does the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) know what to do with each node?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) The trick is that the kernel starts at the root of the tree and looks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) for nodes that have a 'compatible' property. First, it is generally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) assumed that any node with a 'compatible' property represents a device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) of some kind, and second, it can be assumed that any node at the root
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) of the tree is either directly attached to the processor bus, or is a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) miscellaneous system device that cannot be described any other way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) For each of these nodes, Linux allocates and registers a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) platform_device, which in turn may get bound to a platform_driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) Why is using a platform_device for these nodes a safe assumption?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) Well, for the way that Linux models devices, just about all bus_types
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) assume that its devices are children of a bus controller. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) example, each i2c_client is a child of an i2c_master. Each spi_device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) is a child of an SPI bus. Similarly for USB, PCI, MDIO, etc. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) same hierarchy is also found in the DT, where I2C device nodes only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) ever appear as children of an I2C bus node. Ditto for SPI, MDIO, USB,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) etc. The only devices which do not require a specific type of parent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) device are platform_devices (and amba_devices, but more on that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) later), which will happily live at the base of the Linux /sys/devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) tree. Therefore, if a DT node is at the root of the tree, then it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) really probably is best registered as a platform_device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) Linux board support code calls of_platform_populate(NULL, NULL, NULL, NULL)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) to kick off discovery of devices at the root of the tree. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) parameters are all NULL because when starting from the root of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) tree, there is no need to provide a starting node (the first NULL), a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) parent struct device (the last NULL), and we're not using a match
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) table (yet). For a board that only needs to register devices,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) .init_machine() can be completely empty except for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) of_platform_populate() call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) In the Tegra example, this accounts for the /soc and /sound nodes, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) what about the children of the SoC node? Shouldn't they be registered
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) as platform devices too? For Linux DT support, the generic behaviour
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) is for child devices to be registered by the parent's device driver at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) driver .probe() time. So, an i2c bus device driver will register a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) i2c_client for each child node, an SPI bus driver will register
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) its spi_device children, and similarly for other bus_types.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) According to that model, a driver could be written that binds to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) SoC node and simply registers platform_devices for each of its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) children. The board support code would allocate and register an SoC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) device, a (theoretical) SoC device driver could bind to the SoC device,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) and register platform_devices for /soc/interrupt-controller, /soc/serial,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) /soc/i2s, and /soc/i2c in its .probe() hook. Easy, right?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) Actually, it turns out that registering children of some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) platform_devices as more platform_devices is a common pattern, and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) device tree support code reflects that and makes the above example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) simpler. The second argument to of_platform_populate() is an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) of_device_id table, and any node that matches an entry in that table
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) will also get its child nodes registered. In the Tegra case, the code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) can look something like this::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) static void __init harmony_init_machine(void)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) /* ... */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) of_platform_populate(NULL, of_default_bus_match_table, NULL, NULL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) "simple-bus" is defined in the Devicetree Specification as a property
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) meaning a simple memory mapped bus, so the of_platform_populate() code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) could be written to just assume simple-bus compatible nodes will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) always be traversed. However, we pass it in as an argument so that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) board support code can always override the default behaviour.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) [Need to add discussion of adding i2c/spi/etc child devices]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) Appendix A: AMBA devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) ------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) ARM Primecells are a certain kind of device attached to the ARM AMBA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) bus which include some support for hardware detection and power
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) management. In Linux, struct amba_device and the amba_bus_type is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) used to represent Primecell devices. However, the fiddly bit is that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) not all devices on an AMBA bus are Primecells, and for Linux it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) typical for both amba_device and platform_device instances to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) siblings of the same bus segment.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414) When using the DT, this creates problems for of_platform_populate()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) because it must decide whether to register each node as either a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) platform_device or an amba_device. This unfortunately complicates the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) device creation model a little bit, but the solution turns out not to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) be too invasive. If a node is compatible with "arm,amba-primecell", then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) of_platform_populate() will register it as an amba_device instead of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) platform_device.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags