[RFC] (early draft) dt: Linux dt usage model documentation

[Randy Dunlap]

On Mon, 13 Jun 2011 07:32:15 -0600 Grant Likely wrote:

> Signed-off-by: Grant Likely <grant.likely at secretlab.ca>
> ---
> 
> Hey all,
> 
> This is an early draft of the usage model document for the device
> tree, but I wanted to get it out there for feedback, and so that some
> of the Linaro engineers could get started on migrating board ports.
> 
> g.
> 
>  Documentation/devicetree/usage-model |  403 ++++++++++++++++++++++++++++++++++
>  1 files changed, 403 insertions(+), 0 deletions(-)
>  create mode 100644 Documentation/devicetree/usage-model
> 
> diff --git a/Documentation/devicetree/usage-model b/Documentation/devicetree/usage-model
> new file mode 100644
> index 0000000..4203119
> --- /dev/null
> +++ b/Documentation/devicetree/usage-model
> @@ -0,0 +1,403 @@
> +Linux and the Device Tree
> +The Linux usage model for device tree data
> +
> +Author: Grant Likely <grant.likely at secretlab.ca>
> +
> +This article describes how Linux uses the device tree.  An overview of
> +the device tree data format can be found at the <a
> +href="http://devicetree.org/Device_Tree_Usage">Device Tree Usage</a>
> +page on <a href="http://devicetree.org">devicetree.org</a>.
> +
> +
> +	All the cool architectures are using device tree.  I want to
> +	use device tree too!
> +
> +The "Open Firmware Device Tree", or simply Device Tree (DT), is a data
> +structure and language for describing hardware.  More specifically, it
> +is an description of hardware that is readable by an operating system

   is a

> +so that the operating system doesn't need to hard code details of the
> +machine.
> +
> +Structurally, the DT is a tree, or acyclic graph with named nodes, and
> +nodes may have an arbitrary number of named properties encapsulating
> +arbitrary data.  A mechanism also exists to create arbitrary
> +links from one node to another outside of the natural tree structure..

Drop second period.

> +
> +Conceptually, a common set of usage conventions, called 'bindings',
> +is defined for how data should appear in the tree to describe typical
> +hardware characteristics including data busses, interrupt lines, gpio
> +connections, and peripheral devices.
> +
> +As much as possible, hardware is described using existing bindings to
> +maximize use of existing support code, but since property and node
> +names are simply text strings, it is easy to extend existing bindings
> +or create new ones by defining new nodes and properties.
> +
> +<h2>History</h2>
> +The DT was originally created by Open Firmware as part of the
> +communication method for passing data from Open Firmware to a client
> +program (like to an operating system).  An operating system used the
> +Device Tree to discover the topology of the hardware at runtime, and
> +thereby support a majority of available hardware without hard coded
> +information (assuming drivers were available for all devices).
> +
> +Since Open Firmware is commonly used on PowerPC and SPARC platforms,
> +the Linux support for those architectures has for a long time used the
> +Device Tree.
> +
> +In 2005, when PowerPC Linux began a major cleanup and to merge 32 bit

                                                                  32-bit

> +and 64 support, the decision was made to require DT support on all

       64-bit

> +powerpc platforms, regardless of whether or not they used Open
> +Firmware.  To do this, a DT representation called the Flattened Device
> +Tree (FDT) was created which could be passed to the kernel as a binary
> +blob without requiring a real Open Firmware implementation.  U-Boot,
> +kexec, and other bootloaders were modified to support both passing a
> +Device Tree Binary (dtb) and to modify a dtb at boot time.
> +
> +Some time later, FDT infrastructure was generalized to be usable by
> +all architectures.  At the time of this writing, 5 mainlined
> +architectures (arm, mips, powerpc, sparc, and x86) and 1 out of
> +mainline architecture (nios) have some level of DT support.
> +
> +<h2>Data Model</h2>
> +If you haven't already read the
> +href="http://devicetree.org/Device_Tree_Usage">Device Tree Usage</a>
> +page, then go read it now.  It's okay, I'll wait....
> +
> +<h3>High Level View</h3>
> +The most important thing to understand is that the DT is simply a data
> +structure that describes the hardware.  There is nothing magical about
> +it, and it doesn't magically make all hardware configuration problems
> +go away.  What it does do is provide a language for decoupling the
> +hardware configuration from the board and device driver support in the
> +Linux kernel (or any other operating system for that matter).  Using
> +it allows board and device support to become data driven; to make
> +setup decisions based on data passed into the kernel instead of on
> +per-machine hard coded selections.
> +
> +Ideally, data driven platform setup should result in less code
> +duplication and make it easier to support a wide range of hardware
> +with a single kernel image.
> +
> +Linux uses DT data for three major purposes:
> +1) platform identification,
> +2) runtime configuration, and
> +3) device population.
> +
> +<h4>Platform Identification</h4>
> +First and foremost, the kernel will use data in the DT to identify the
> +specific machine.  In a perfect world, the specific platform shouldn't
> +matter to the kernel because all platform details would be described
> +perfectly by the device tree in a consistent and reliable manner.
> +Hardware is not perfect though, and so the kernel must identify the
> +machine during early boot so that it has the opportunity to run
> +machine specific fixups.

   machine-specific

> +
> +In the majority of cases, the machine identity is irrelevant, and the
> +kernel will instead select setup code based on the machines core

                                                      machine's

> +cpu or SoC.  On ARM for example, setup_arch() in

   CPU (preferably; globally)

> +arch/arm/kernel/setup.c will call setup_machine_fdt() in
> +arch/arm/kernel/devicetree.c which searches through the machine_desc
> +table and selects the machine_desc which best matches the device tree
> +data.  It determines the best match by looking at the 'compatible'
> +property in the root device tree node, and comparing it with the
> +dt_compat list in struct machine_desc.
> +
> +The 'compatible' property contains a sorted list of strings starting
> +with the exact name of the machine, followed by an optional list of
> +boards it is compatible with sorted from most compatible to list.  For

                                                               least.

> +example, the root compatible properties for the TI BeagleBoard and its
> +successor, the BeagleBoard xM board might look like:
> +
> +	compatible = "ti,omap3-beagleboard", "ti,omap3450", "ti,omap3";
> +	compatible = "ti,omap3-beagleboard-xm", "ti,omap3450", "ti,omap3";
> +
> +Where "ti,omap3-beagleboard-xm" specifies the exact model, it also
> +claims that it compatible with the OMAP 3450 SoC, and the omap3 family
> +of SoCs in general.  You'll notice that the list is sorted from most
> +specific (exact board) to least specific (SoC family).
> +
> +Astute readers might point out that the Beagle xM could also claim
> +compatibility with the original Beagle board.  However, one should be
> +cautioned about doing so at the board level since there is typically a
> +high level of change from one board to another, even within the same
> +product line, that it is hard to nail down exactly is meant when one

                 and that ...                         what is meant when one

> +board claims to be compatible with another.  For the top level, it is
> +better to err on the side of caution and not claim one board is
> +compatible with another.  The notable exception would be when one
> +board is a carrier for another, such as a cpu module attached to a
> +carrier board.
> +
> +One more note on compatible values.  Any string used in a compatible
> +property must be documented as to what it indicates.  Add
> +documentation for compatible strings in Documentation/devicetree/bindings.
> +
> +Again on ARM, the for each machine_desc, the kernel looks to see if

                 the for ?

> +any of the dt_compat list entries appear in the compatible property.

                                     appears

> +If one does, then that machine_desc is a candidate for driving the
> +machine.  After searching the entire table of machine_descs,
> +setup_machine_fdt() returns the 'most compatible' machine_desc based
> +on which entry in the compatible property each machine_desc matches
> +against.  If no matching machine_desc is found, then it returns NULL.
> +
> +The reasoning behind this scheme is the observation that in the majority
> +of cases, a single machine_desc can support a large number of boards
> +if that all use the same SoC, or same family of SoCs.  However,

      they

> +invariably there will be some exceptions where a specific board will
> +require special setup code that is not useful in the generic case.
> +Special cases could be handled by explicitly checking for the
> +troublesome board(s) in generic setup code, but doing so very quickly
> +becomes ugly and/or unmaintainable if it is more than just a couple of
> +cases.
> +
> +Instead, the compatible list allows a generic machine_desc to provide
> +support for a wide common set of boards by specifying "less
> +compatible" value in the dt_compat list.  In the example above,
> +generic board support can claim compatibility with "ti,omap3" or
> +"ti,omap3450".  If a bug was discovered on the original beagleboard
> +that required special workaround code during early boot, then a new
> +machine_desc could be added which implements the workarounds and only
> +matches on "ti,beagleboard".
> +
> +PowerPC uses a slightly different scheme where it calls the .probe()
> +hook from each machine_desc, and the first one returning TRUE is used.
> +However, this approach does not take into account the priority of the
> +compatible list, and probably should be avoided for new architecture
> +support.
> +
> +<h4>Runtime configuration</h4>
> +In most cases, a DT will be the sole method of communicating data from
> +firmware to the kernel, so also gets used to pass in runtime and
> +configuration data like the kernel parameters string and the location
> +of an initrd image.
> +
> +Most of this data is contained in the /chosen node, and when booting
> +Linux it will look something like this:
> +
> +	chosen {
> +		bootargs = "console=ttyS0,115200 loglevel=8";
> +		initrd-start = <0xc8000000>;
> +		initrd-end = <0xc8200000>;
> +	};
> +
> +The bootargs property contains the kernel arguments, and the initrd-*
> +properties define the address and size of an initrd blob.  The
> +chosen node may also optionally contain an arbitrary number of
> +additional properties for platform specific configuration data.

                             platform-specific

> +
> +During early boot, the architecture setup code calls of_scan_flat_dt()
> +several times with different helper callbacks to parse device tree
> +data before paging is setup.  The of_scan_flat_dt() code scans through
> +the device tree and uses the helpers to extract information required
> +during early boot.  Typically the early_init_dt_scan_chosen() helper
> +is used to parse the chosen node including kernel parameters,
> +early_init_dt_scan_root() to initialize the DT address space model,
> +and early_init_dt_scan_memory() to determine the size and
> +location of usable RAM.
> +
> +On ARM, the function setup_machine_fdt() is responsible for early
> +scanning of the device tree after selecting the correct machine_desc
> +that supports the board.
> +
> +<h4>Device population</h4>
> +After the board has been identified, and after the early configuration data
> +has been parsed, then kernel initialization can proceed in the normal
> +way.  At some point in this process, unflatten_device_tree() is called
> +to convert the data into a more efficient runtime representation.
> +This is also when machine specific setup hooks will get called, like

                     machine-specific

> +the machine_desc .init_early(), .init_irq() and .init_machine() hooks
> +on ARM.  The remainder of this section uses examples from the ARM
> +implementation, but all architectures will do pretty much the same
> +thing when using a DT.
> +
> +As can be guessed by the names, .init_early() is used for any machine

                                                                 machine-

> +specific setup that needs to be executed early in the boot process,
> +and .init_irq() is used to set up interrupt handling.  Using a DT
> +doesn't materially change the behaviour of either of these functions.
> +If a DT is provided, then both .init_early() and .init_irq() are able
> +to call any of the DT query functions (of_* in include/linux/of*.h) to
> +get additional data about the platform.
> +
> +The most interesting hook in the DT context is .init_machine() which
> +is primarily responsible for populating the Linux device model with
> +data about the platform.  Historically this has been implemented on
> +embedded platforms by defining a set of static clock structures,
> +platform_devices, and other data in the board support .c file, and
> +registering it en-masse in .init_machine().  When DT is used, then
> +instead of hard coding static devices for each platform, the list of
> +devices can be obtained by parsing the DT, and allocating device
> +structures dynamically.
> +
> +The simplest case is when .init_machine() is only responsible for
> +registering a block of platform_devices.  Platform devices are concept

                                                                  concepts
or
                                             A platform device is a concept

> +used by Linux for memory or io mapped devices which cannot be detected

                               IO (or I/O)

> +by hardware, and for 'composite' or 'virtual' devices (more on those
> +later).  While there is no 'platform device' terminology for the DT,
> +platform devices roughly correspond to device nodes at the root of the
> +tree and children of simple memory mapped bus nodes.
> +
> +About now is a good time to lay out an example.  Here is part of the
> +device tree for the NVIDIA Tegra board.
> +
> +/{
> +	compatible = "nvidia,harmony", "nvidia,tegra250";
> +	#address-cells = <1>;
> +	#size-cells = <1>;
> +	interrupt-parent = <&intc>;
> +
> +	chosen { };
> +	aliases { };
> +
> +	memory {
> +		device_type = "memory";
> +		reg = <0x00000000 0x40000000>;
> +	};
> +
> +	soc {
> +		compatible = "nvidia,tegra250-soc", "simple-bus";
> +		#address-cells = <1>;
> +		#size-cells = <1>;
> +		ranges;
> +
> +		intc: interrupt-controller at 50041000 {
> +			compatible = "nvidia,tegra250-gic";
> +			interrupt-controller;
> +			#interrupt-cells = <1>;
> +			reg = <0x50041000 0x1000>, < 0x50040100 0x0100 >;
> +		};
> +
> +		serial at 70006300 {
> +			compatible = "nvidia,tegra250-uart";
> +			reg = <0x70006300 0x100>;
> +			interrupts = <122>;
> +		};
> +
> +		i2s-1: i2s at 70002800 {
> +			compatible = "nvidia,tegra250-i2s";
> +			reg = <0x70002800 0x100>;
> +			interrupts = <77>;
> +			codec = <&wm8903>;
> +		};
> +
> +		i2c at 7000c000 {
> +			compatible = "nvidia,tegra250-i2c";
> +			#address-cells = <1>;
> +			#size-cells = <1>;
> +			reg = <0x7000c000 0x100>;
> +			interrupts = <70>;
> +
> +			wm8903: codec at 1a {
> +				compatible = "wlf,wm8903";
> +				reg = <0x1a>;
> +				interrupts = <347>;
> +			};
> +		};
> +	};
> +
> +	sound {
> +		compatible = "nvidia,harmony-sound";
> +		i2s-controller = <&i2s-1>;
> +		i2s-codec = <&wm8903>;
> +	};
> +};
> +
> +At .machine_init() time, Tegra board support code will need to look at
> +this DT and decide which nodes to create platform_devices for.
> +However, looking at the tree, it is not immediately obvious what kind
> +of device each node represents, or even if a node represents a device
> +at all.  The /chosen, /aliases, and /memory nodes are informational
> +nodes that don't describe devices (although arguably memory could be
> +considered a device).  The children of the /soc node are memory mapped
> +devices, but the codec at 1a is an i2c device, and the sound node
> +represents not a device, but rather how other devices are connected
> +together to create the audio subsystem.  I know what each device is
> +because I'm familiar with the board design, but how does the kernel
> +know what to do with each node?
> +
> +The trick is that the kernel starts at the root of the tree and looks
> +for nodes that have a 'compatible' property.  First, it is generally
> +assumed that any node with a 'compatible' property represents a device
> +of some kind, and second, it can be assumed that any node at the root
> +of the tree is either directly attached to the processor bus, or is a
> +miscellaneous system device that cannot be described any other way.
> +For each of these nodes, Linux allocates and registers a
> +platform_device, which in turn may get bound to a platform_driver.
> +
> +Why is using a platform_device for these nodes a safe assumption?
> +Well, for the way that Linux models devices, just about all bus_types
> +assume that its devices are children of a bus controller.  For
> +example, each i2c_client is a child of an i2c_master.  Each spi_device
> +is a child of an spi bus.  Similarly for USB, PCI, MDIO, etc.  The

Why capitalize USB and PCI but not spi?
I would capitalize SPI and GPIO throughout the file.

> +same hierarchy is also found in the DT, where i2c device nodes only
> +ever appear as children of an i2c bus node.  Ditto for spi, mdio, usb,

and usb
At least be consistent, please.

> +etc.  The only devices which do not require a specific type of parent
> +device are platform_devices (and amba_devices, but more on that
> +later), which will happily live at the base of the Linux /sys/devices
> +tree.  Therefore, if a DT node is at the root of the tree, then it
> +really probably is best registered as a platform_device.
> +
> +Linux board support code calls of_platform_populate(NULL, NULL, NULL)
> +to kick of discovery of devices at the root of the tree.  The

           off

> +parameters are all NULL because when starting from the root of the
> +tree, there is no need to provide a starting node (the first NULL), a
> +parent struct device (the last NULL), and we're not using a match
> +table (yet).  For a board that only needs to register devices,
> +.init_machine() can be completely empty except for the
> +of_platform_populate() call.
> +
> +In the Tegra example, this accounts for the /soc and /sound nodes, but
> +what about the children of the soc node?  Shouldn't they be registered

                                  SoC ?

> +as platform devices too?  For Linux DT support, the generic behaviour
> +is for child devices to be registered by the parent's device driver at
> +driver .probe() time.  So, an i2c bus device driver will register a
> +i2c_client for each child node, an spi bus driver will register
> +it's spi_device children, and similarly for other bus_types.

   its

> +According to that model, a driver could be written that binds to the
> +soc node and simply registers platform_devices for each of it's

   SoC                                                        its

> +children.  The board support code would allocate and register an soc

SoC (globally except in node or file names)

> +device, an soc device driver would bind to the soc device, and
> +register platform_devices for /soc/interrupt-controller, /soc/serial,
> +/soc/i2s, and /soc/i2c in it's .probe() hook.  Easy, right?  Although
> +it is a lot of mucking about for just registering platform devices.
> +
> +It turns out that registering children of certain platform_devices as
> +more platform_devices is a common pattern, and the device tree support
> +code reflects that.  The second argument to of_platform_populate() is
> +an of_device_id table, and any node that matches an entry in that
> +table will also get it's child nodes registered.  In the tegra case,

                       its

> +the code can look something like this:
> +
> +static struct of_device_id harmony_bus_ids[] __initdata = {
> +	{ .compatible = "simple-bus", },
> +	{}
> +};
> +
> +static void __init harmony_init_machine(void)
> +{
> +	/* ... */
> +	of_platform_populate(NULL, harmony_bus_ids, NULL);
> +}
> +
> +"simple-bus" is defined in the ePAPR 1.0 specification as a property
> +meaning a simple memory mapped bus, so the of_platform_populate() code
> +could be written to just assume simple-bus compatible nodes will
> +always be traversed.  However, we pass it in as an argument so that
> +board support code can always override the default behaviour.
> +
> +<h2>Appendix A: AMBA devices</h2>
> +
> +ARM Primecells are a certain kind of device attached to the ARM AMBA
> +bus which include some support for hardware detection and power
> +management.  In Linux, struct amba_device and the amba_bus_type is
> +used to represent Primecell devices.  However, the fiddly bit is that
> +not all devices on an AMBA bus are Primecells, and for Linux it is
> +typical for both amba_device and platform_device instances to be
> +siblings of the same bus segment.
> +
> +When using the DT, this creates problems for of_platform_populate()
> +because it must decide whether to register each node as either a
> +platform_device or an amba_device.  This unfortunately complicates the
> +device creation model a little bit, but the solution turns out not to
> +be too invasive.  If a node is compatible with "arm,amba-primecell", then
> +of_platform_populate() will register it as an amba_device instead of a
> +platform_device.
> 

HTH.

---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***