diff options
Diffstat (limited to 'dtc/Documentation')
| -rw-r--r-- | dtc/Documentation/dt-object-internal.txt | 310 | ||||
| -rw-r--r-- | dtc/Documentation/dtc-paper.bib | 43 | ||||
| -rw-r--r-- | dtc/Documentation/dtc-paper.tex | 597 | ||||
| -rw-r--r-- | dtc/Documentation/dts-format.txt | 122 | ||||
| -rw-r--r-- | dtc/Documentation/manual.txt | 762 |
5 files changed, 1834 insertions, 0 deletions
diff --git a/dtc/Documentation/dt-object-internal.txt b/dtc/Documentation/dt-object-internal.txt new file mode 100644 index 000000000..51d68ab93 --- /dev/null +++ b/dtc/Documentation/dt-object-internal.txt @@ -0,0 +1,310 @@ +Device Tree Dynamic Object format internals +------------------------------------------- + +The Device Tree for most platforms is a static representation of +the hardware capabilities. This is insufficient for platforms +that need to dynamically insert Device Tree fragments into the +live tree. + +This document explains the the Device Tree object format and +modifications made to the Device Tree compiler, which make it possible. + +1. Simplified Problem Definition +-------------------------------- + +Assume we have a platform which boots using following simplified Device Tree. + +---- foo.dts ----------------------------------------------------------------- + /* FOO platform */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + }; + }; +---- foo.dts ----------------------------------------------------------------- + +We have a number of peripherals that after probing (using some undefined method) +should result in different Device Tree configuration. + +We cannot boot with this static tree because due to the configuration of the +foo platform there exist multiple conficting peripherals DT fragments. + +So for the bar peripheral we would have this: + +---- foo+bar.dts ------------------------------------------------------------- + /* FOO platform + bar peripheral */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + + /* bar peripheral */ + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + }; + }; + }; +---- foo+bar.dts ------------------------------------------------------------- + +While for the baz peripheral we would have this: + +---- foo+baz.dts ------------------------------------------------------------- + /* FOO platform + baz peripheral */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + /* baz resources */ + baz_res: res_baz { ... }; + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + + /* baz peripheral */ + baz { + compatible = "corp,baz"; + /* reference to another point in the tree */ + ref-to-res = <&baz_res>; + ... /* various properties and child nodes */ + }; + }; + }; +---- foo+baz.dts ------------------------------------------------------------- + +We note that the baz case is more complicated, since the baz peripheral needs to +reference another node in the DT tree. + +2. Device Tree Object Format Requirements +----------------------------------------- + +Since the Device Tree is used for booting a number of very different hardware +platforms it is imperative that we tread very carefully. + +2.a) No changes to the Device Tree binary format for the base tree. We cannot +modify the tree format at all and all the information we require should be +encoded using Device Tree itself. We can add nodes that can be safely ignored +by both bootloaders and the kernel. The plugin dtbs are optionally tagged +with a different magic number in the header but otherwise they're simple +blobs. + +2.b) Changes to the DTS source format should be absolutely minimal, and should +only be needed for the DT fragment definitions, and not the base boot DT. + +2.c) An explicit option should be used to instruct DTC to generate the required +information needed for object resolution. Platforms that don't use the +dynamic object format can safely ignore it. + +2.d) Finally, DT syntax changes should be kept to a minimum. It should be +possible to express everything using the existing DT syntax. + +3. Implementation +----------------- + +The basic unit of addressing in Device Tree is the phandle. Turns out it's +relatively simple to extend the way phandles are generated and referenced +so that it's possible to dynamically convert symbolic references (labels) +to phandle values. This is a valid assumption as long as the author uses +reference syntax and does not assign phandle values manually (which might +be a problem with decompiled source files). + +We can roughly divide the operation into two steps. + +3.a) Compilation of the base board DTS file using the '-@' option +generates a valid DT blob with an added __symbols__ node at the root node, +containing a list of all nodes that are marked with a label. + +Using the foo.dts file above the following node will be generated; + +$ dtc -@ -O dtb -o foo.dtb -b 0 foo.dts +$ fdtdump foo.dtb +... +/ { + ... + res { + ... + phandle = <0x00000001>; + ... + }; + ocp { + ... + phandle = <0x00000002>; + ... + }; + __symbols__ { + res="/res"; + ocp="/ocp"; + }; +}; + +Notice that all the nodes that had a label have been recorded, and that +phandles have been generated for them. + +This blob can be used to boot the board normally, the __symbols__ node will +be safely ignored both by the bootloader and the kernel (the only loss will +be a few bytes of memory and disk space). + +We generate a __symbols__ node to record nodes that had labels in the base +tree (or subsequent loaded overlays) so that they can be matched up with +references made to them in Device Tree objects. + +3.b) The Device Tree fragments must be compiled with the same option but they +must also have a tag (/plugin/) that allows undefined references to nodes +that are not present at compilation time to be recorded so that the runtime +loader can fix them. + +So the bar peripheral's DTS format would be of the form: + +/dts-v1/; +/plugin/; /* allow undefined references and record them */ +/ { + .... /* various properties for loader use; i.e. part id etc. */ + fragment@0 { + target = <&ocp>; + __overlay__ { + /* bar peripheral */ + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + } + }; + }; +}; + +Note that there's a target property that specifies the location where the +contents of the overlay node will be placed, and it references the node +in the foo.dts file. + +$ dtc -@ -O dtb -o bar.dtbo -b 0 bar.dts +$ fdtdump bar.dtbo +... +/ { + ... /* properties */ + fragment@0 { + target = <0xffffffff>; + __overlay__ { + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + } + }; + }; + __fixups__ { + ocp = "/fragment@0:target:0"; + }; +}; + +No __symbols__ node has been generated (no label in bar.dts). +Note that the target's ocp label is undefined, so the phandle +value is filled with the illegal value '0xffffffff', while a __fixups__ +node has been generated, which marks the location in the tree where +the label lookup should store the runtime phandle value of the ocp node. + +The format of the __fixups__ node entry is + + <label> = "<local-full-path>:<property-name>:<offset>" + [, "<local-full-path>:<property-name>:<offset>"...]; + + <label> Is the label we're referring + <local-full-path> Is the full path of the node the reference is + <property-name> Is the name of the property containing the + reference + <offset> The offset (in bytes) of where the property's + phandle value is located. + +Doing the same with the baz peripheral's DTS format is a little bit more +involved, since baz contains references to local labels which require +local fixups. + +/dts-v1/; +/plugin/; /* allow undefined label references and record them */ +/ { + .... /* various properties for loader use; i.e. part id etc. */ + fragment@0 { + target = <&res>; + __overlay__ { + /* baz resources */ + baz_res: res_baz { ... }; + }; + }; + fragment@1 { + target = <&ocp>; + __overlay__ { + /* baz peripheral */ + baz { + compatible = "corp,baz"; + /* reference to another point in the tree */ + ref-to-res = <&baz_res>; + ... /* various properties and child nodes */ + } + }; + }; +}; + +Note that &bar_res reference. + +$ dtc -@ -O dtb -o baz.dtbo -b 0 baz.dts +$ fdtdump baz.dtbo +... +/ { + ... /* properties */ + fragment@0 { + target = <0xffffffff>; + __overlay__ { + res_baz { + .... + phandle = <0x00000001>; + }; + }; + }; + fragment@1 { + target = <0xffffffff>; + __overlay__ { + baz { + compatible = "corp,baz"; + ... /* various properties and child nodes */ + ref-to-res = <0x00000001>; + } + }; + }; + __fixups__ { + res = "/fragment@0:target:0"; + ocp = "/fragment@1:target:0"; + }; + __local_fixups__ { + fragment@1 { + __overlay__ { + baz { + ref-to-res = <0>; + }; + }; + }; + }; +}; + +This is similar to the bar case, but the reference of a local label by the +baz node generates a __local_fixups__ entry that records the place that the +local reference is being made. No matter how phandles are allocated from dtc +the run time loader must apply an offset to each phandle in every dynamic +DT object loaded. The __local_fixups__ node records the offset relative to the +start of every local reference within that property so that the loader can apply +the offset. diff --git a/dtc/Documentation/dtc-paper.bib b/dtc/Documentation/dtc-paper.bib new file mode 100644 index 000000000..d01e2ff9e --- /dev/null +++ b/dtc/Documentation/dtc-paper.bib @@ -0,0 +1,43 @@ +@STRING{pub-IEEE = "IEEE Computer Society"} +@STRING{pub-IEEE:adr = "345 E. 47th St, New York, NY 10017, USA"} + +@BOOK{IEEE1275, + key = "IEEE1275", + title = "{IEEE} {S}tandard for {B}oot ({I}nitialization {C}onfiguration) {F}irmware: {C}ore {R}equirements and {P}ractices", + publisher = pub-IEEE, + address = pub-IEEE:adr, + series = "IEEE Std 1275-1994", + year = 1994, +} + +@BOOK{IEEE1275-pci, + key = "IEEE1275-pci", + title = "{PCI} {B}us {B}inding to: {IEEE} {S}td 1275-1994 {S}tandard for {B}oot ({I}nitialization {C}onfiguration) {F}irmware", + publisher = pub-IEEE, + address = pub-IEEE:adr, + note = "Revision 2.1", + year = 1998, +} + +@MISC{noof1, + author = "Benjamin Herrenschmidt", + title = "Booting the {L}inux/ppc kernel without {O}pen {F}irmware", + month = may, + year = 2005, + note = "v0.1, \url{http://ozlabs.org/pipermail/linuxppc64-dev/2005-May/004073.html}", +} + +@MISC{noof5, + author = "Benjamin Herrenschmidt", + title = "Booting the {L}inux/ppc kernel without {O}pen {F}irmware", + month = nov, + year = 2005, + note = "v0.5, \url{http://ozlabs.org/pipermail/linuxppc64-dev/2005-December/006994.html}", +} + +@MISC{dtcgit, + author = "David Gibson et al.", + title = "\dtc{}", + howpublished = "git tree", + note = "\url{http://ozlabs.org/~dgibson/dtc/dtc.git}", +} diff --git a/dtc/Documentation/dtc-paper.tex b/dtc/Documentation/dtc-paper.tex new file mode 100644 index 000000000..4494226d8 --- /dev/null +++ b/dtc/Documentation/dtc-paper.tex @@ -0,0 +1,597 @@ +\documentclass[a4paper,twocolumn]{article} + +\usepackage{abstract} +\usepackage{xspace} +\usepackage{amssymb} +\usepackage{latexsym} +\usepackage{tabularx} +\usepackage[T1]{fontenc} +\usepackage{calc} +\usepackage{listings} +\usepackage{color} +\usepackage{url} + +\title{Device trees everywhere} + +\author{David Gibson \texttt{<{dwg}{@}{au1.ibm.com}>}\\ + Benjamin Herrenschmidt \texttt{<{benh}{@}{kernel.crashing.org}>}\\ + \emph{OzLabs, IBM Linux Technology Center}} + +\newcommand{\R}{\textsuperscript{\textregistered}\xspace} +\newcommand{\tm}{\textsuperscript{\texttrademark}\xspace} +\newcommand{\tge}{$\geqslant$} +%\newcommand{\ditto}{\textquotedbl\xspace} + +\newcommand{\fixme}[1]{$\bigstar$\emph{\textbf{\large #1}}$\bigstar$\xspace} + +\newcommand{\ppc}{\mbox{PowerPC}\xspace} +\newcommand{\of}{Open Firmware\xspace} +\newcommand{\benh}{Ben Herrenschmidt\xspace} +\newcommand{\kexec}{\texttt{kexec()}\xspace} +\newcommand{\dtbeginnode}{\texttt{OF\_DT\_BEGIN\_NODE\xspace}} +\newcommand{\dtendnode}{\texttt{OF\_DT\_END\_NODE\xspace}} +\newcommand{\dtprop}{\texttt{OF\_DT\_PROP\xspace}} +\newcommand{\dtend}{\texttt{OF\_DT\_END\xspace}} +\newcommand{\dtc}{\texttt{dtc}\xspace} +\newcommand{\phandle}{\texttt{linux,phandle}\xspace} +\begin{document} + +\maketitle + +\begin{abstract} + We present a method for booting a \ppc{}\R Linux\R kernel on an + embedded machine. To do this, we supply the kernel with a compact + flattened-tree representation of the system's hardware based on the + device tree supplied by Open Firmware on IBM\R servers and Apple\R + Power Macintosh\R machines. + + The ``blob'' representing the device tree can be created using \dtc + --- the Device Tree Compiler --- that turns a simple text + representation of the tree into the compact representation used by + the kernel. The compiler can produce either a binary ``blob'' or an + assembler file ready to be built into a firmware or bootwrapper + image. + + This flattened-tree approach is now the only supported method of + booting a \texttt{ppc64} kernel without Open Firmware, and we plan + to make it the only supported method for all \texttt{powerpc} + kernels in the future. +\end{abstract} + +\section{Introduction} + +\subsection{OF and the device tree} + +Historically, ``everyday'' \ppc machines have booted with the help of +\of (OF), a firmware environment defined by IEEE1275 \cite{IEEE1275}. +Among other boot-time services, OF maintains a device tree that +describes all of the system's hardware devices and how they're +connected. During boot, before taking control of memory management, +the Linux kernel uses OF calls to scan the device tree and transfer it +to an internal representation that is used at run time to look up +various device information. + +The device tree consists of nodes representing devices or +buses\footnote{Well, mostly. There are a few special exceptions.}. +Each node contains \emph{properties}, name--value pairs that give +information about the device. The values are arbitrary byte strings, +and for some properties, they contain tables or other structured +information. + +\subsection{The bad old days} + +Embedded systems, by contrast, usually have a minimal firmware that +might supply a few vital system parameters (size of RAM and the like), +but nothing as detailed or complete as the OF device tree. This has +meant that the various 32-bit \ppc embedded ports have required a +variety of hacks spread across the kernel to deal with the lack of +device tree. These vary from specialised boot wrappers to parse +parameters (which are at least reasonably localised) to +CONFIG-dependent hacks in drivers to override normal probe logic with +hardcoded addresses for a particular board. As well as being ugly of +itself, such CONFIG-dependent hacks make it hard to build a single +kernel image that supports multiple embedded machines. + +Until relatively recently, the only 64-bit \ppc machines without OF +were legacy (pre-POWER5\R) iSeries\R machines. iSeries machines often +only have virtual IO devices, which makes it quite simple to work +around the lack of a device tree. Even so, the lack means the iSeries +boot sequence must be quite different from the pSeries or Macintosh, +which is not ideal. + +The device tree also presents a problem for implementing \kexec. When +the kernel boots, it takes over full control of the system from OF, +even re-using OF's memory. So, when \kexec comes to boot another +kernel, OF is no longer around for the second kernel to query. + +\section{The Flattened Tree} + +In May 2005 \benh implemented a new approach to handling the device +tree that addresses all these problems. When booting on OF systems, +the first thing the kernel runs is a small piece of code in +\texttt{prom\_init.c}, which executes in the context of OF. This code +walks the device tree using OF calls, and transcribes it into a +compact, flattened format. The resulting device tree ``blob'' is then +passed to the kernel proper, which eventually unflattens the tree into +its runtime form. This blob is the only data communicated between the +\texttt{prom\_init.c} bootstrap and the rest of the kernel. + +When OF isn't available, either because the machine doesn't have it at +all or because \kexec has been used, the kernel instead starts +directly from the entry point taking a flattened device tree. The +device tree blob must be passed in from outside, rather than generated +by part of the kernel from OF. For \kexec, the userland +\texttt{kexec} tools build the blob from the runtime device tree +before invoking the new kernel. For embedded systems the blob can +come either from the embedded bootloader, or from a specialised +version of the \texttt{zImage} wrapper for the system in question. + +\subsection{Properties of the flattened tree} + +The flattened tree format should be easy to handle, both for the +kernel that parses it and the bootloader that generates it. In +particular, the following properties are desirable: + +\begin{itemize} +\item \emph{relocatable}: the bootloader or kernel should be able to + move the blob around as a whole, without needing to parse or adjust + its internals. In practice that means we must not use pointers + within the blob. +\item \emph{insert and delete}: sometimes the bootloader might want to + make tweaks to the flattened tree, such as deleting or inserting a + node (or whole subtree). It should be possible to do this without + having to effectively regenerate the whole flattened tree. In + practice this means limiting the use of internal offsets in the blob + that need recalculation if a section is inserted or removed with + \texttt{memmove()}. +\item \emph{compact}: embedded systems are frequently short of + resources, particularly RAM and flash memory space. Thus, the tree + representation should be kept as small as conveniently possible. +\end{itemize} + +\subsection{Format of the device tree blob} +\label{sec:format} + +\begin{figure}[htb!] + \centering + \footnotesize + \begin{tabular}{r|c|l} + \multicolumn{1}{r}{\textbf{Offset}}& \multicolumn{1}{c}{\textbf{Contents}} \\\cline{2-2} + \texttt{0x00} & \texttt{0xd00dfeed} & magic number \\\cline{2-2} + \texttt{0x04} & \emph{totalsize} \\\cline{2-2} + \texttt{0x08} & \emph{off\_struct} & \\\cline{2-2} + \texttt{0x0C} & \emph{off\_strs} & \\\cline{2-2} + \texttt{0x10} & \emph{off\_rsvmap} & \\\cline{2-2} + \texttt{0x14} & \emph{version} \\\cline{2-2} + \texttt{0x18} & \emph{last\_comp\_ver} & \\\cline{2-2} + \texttt{0x1C} & \emph{boot\_cpu\_id} & \tge v2 only\\\cline{2-2} + \texttt{0x20} & \emph{size\_strs} & \tge v3 only\\\cline{2-2} + \multicolumn{1}{r}{\vdots} & \multicolumn{1}{c}{\vdots} & \\\cline{2-2} + \emph{off\_rsvmap} & \emph{address0} & memory reserve \\ + + \texttt{0x04} & ...& table \\\cline{2-2} + + \texttt{0x08} & \emph{len0} & \\ + + \texttt{0x0C} & ...& \\\cline{2-2} + \vdots & \multicolumn{1}{c|}{\vdots} & \\\cline{2-2} + & \texttt{0x00000000}- & end marker\\ + & \texttt{00000000} & \\\cline{2-2} + & \texttt{0x00000000}- & \\ + & \texttt{00000000} & \\\cline{2-2} + \multicolumn{1}{r}{\vdots} & \multicolumn{1}{c}{\vdots} & \\\cline{2-2} + \emph{off\_strs} & \texttt{'n' 'a' 'm' 'e'} & strings block \\ + + \texttt{0x04} & \texttt{~0~ 'm' 'o' 'd'} & \\ + + \texttt{0x08} & \texttt{'e' 'l' ~0~ \makebox[\widthof{~~~}]{\textrm{...}}} & \\ + \vdots & \multicolumn{1}{c|}{\vdots} & \\\cline{2-2} + \multicolumn{1}{r}{+ \emph{size\_strs}} \\ + \multicolumn{1}{r}{\vdots} & \multicolumn{1}{c}{\vdots} & \\\cline{2-2} + \emph{off\_struct} & \dtbeginnode & structure block \\\cline{2-2} + + \texttt{0x04} & \texttt{'/' ~0~ ~0~ ~0~} & root node\\\cline{2-2} + + \texttt{0x08} & \dtprop & \\\cline{2-2} + + \texttt{0x0C} & \texttt{0x00000005} & ``\texttt{model}''\\\cline{2-2} + + \texttt{0x10} & \texttt{0x00000008} & \\\cline{2-2} + + \texttt{0x14} & \texttt{'M' 'y' 'B' 'o'} & \\ + + \texttt{0x18} & \texttt{'a' 'r' 'd' ~0~} & \\\cline{2-2} + \vdots & \multicolumn{1}{c|}{\vdots} & \\\cline{2-2} + & \texttt{\dtendnode} \\\cline{2-2} + & \texttt{\dtend} \\\cline{2-2} + \multicolumn{1}{r}{\vdots} & \multicolumn{1}{c}{\vdots} & \\\cline{2-2} + \multicolumn{1}{r}{\emph{totalsize}} \\ + \end{tabular} + \caption{Device tree blob layout} + \label{fig:blob-layout} +\end{figure} + +The format for the blob we devised, was first described on the +\texttt{linuxppc64-dev} mailing list in \cite{noof1}. The format has +since evolved through various revisions, and the current version is +included as part of the \dtc (see \S\ref{sec:dtc}) git tree, +\cite{dtcgit}. + +Figure \ref{fig:blob-layout} shows the layout of the blob of data +containing the device tree. It has three sections of variable size: +the \emph{memory reserve table}, the \emph{structure block} and the +\emph{strings block}. A small header gives the blob's size and +version and the locations of the three sections, plus a handful of +vital parameters used during early boot. + +The memory reserve map section gives a list of regions of memory that +the kernel must not use\footnote{Usually such ranges contain some data +structure initialised by the firmware that must be preserved by the +kernel.}. The list is represented as a simple array of (address, +size) pairs of 64 bit values, terminated by a zero size entry. The +strings block is similarly simple, consisting of a number of +null-terminated strings appended together, which are referenced from +the structure block as described below. + +The structure block contains the device tree proper. Each node is +introduced with a 32-bit \dtbeginnode tag, followed by the node's name +as a null-terminated string, padded to a 32-bit boundary. Then +follows all of the properties of the node, each introduced with a +\dtprop tag, then all of the node's subnodes, each introduced with +their own \dtbeginnode tag. The node ends with an \dtendnode tag, and +after the \dtendnode for the root node is an \dtend tag, indicating +the end of the whole tree\footnote{This is redundant, but included for +ease of parsing.}. The structure block starts with the \dtbeginnode +introducing the description of the root node (named \texttt{/}). + +Each property, after the \dtprop, has a 32-bit value giving an offset +from the beginning of the strings block at which the property name is +stored. Because it's common for many nodes to have properties with +the same name, this approach can substantially reduce the total size +of the blob. The name offset is followed by the length of the +property value (as a 32-bit value) and then the data itself padded to +a 32-bit boundary. + +\subsection{Contents of the tree} +\label{sec:treecontents} + +Having seen how to represent the device tree structure as a flattened +blob, what actually goes into the tree? The short answer is ``the +same as an OF tree''. On OF systems, the flattened tree is +transcribed directly from the OF device tree, so for simplicity we +also use OF conventions for the tree on other systems. + +In many cases a flat tree can be simpler than a typical OF provided +device tree. The flattened tree need only provide those nodes and +properties that the kernel actually requires; the flattened tree +generally need not include devices that the kernel can probe itself. +For example, an OF device tree would normally include nodes for each +PCI device on the system. A flattened tree need only include nodes +for the PCI host bridges; the kernel will scan the buses thus +described to find the subsidiary devices. The device tree can include +nodes for devices where the kernel needs extra information, though: +for example, for ISA devices on a subsidiary PCI/ISA bridge, or for +devices with unusual interrupt routing. + +Where they exist, we follow the IEEE1275 bindings that specify how to +describe various buses in the device tree (for example, +\cite{IEEE1275-pci} describe how to represent PCI devices). The +standard has not been updated for a long time, however, and lacks +bindings for many modern buses and devices. In particular, embedded +specific devices such as the various System-on-Chip buses are not +covered. We intend to create new bindings for such buses, in keeping +with the general conventions of IEEE1275 (a simple such binding for a +System-on-Chip bus was included in \cite{noof5} a revision of +\cite{noof1}). + +One complication arises for representing ``phandles'' in the flattened +tree. In OF, each node in the tree has an associated phandle, a +32-bit integer that uniquely identifies the node\footnote{In practice +usually implemented as a pointer or offset within OF memory.}. This +handle is used by the various OF calls to query and traverse the tree. +Sometimes phandles are also used within the tree to refer to other +nodes in the tree. For example, devices that produce interrupts +generally have an \texttt{interrupt-parent} property giving the +phandle of the interrupt controller that handles interrupts from this +device. Parsing these and other interrupt related properties allows +the kernel to build a complete representation of the system's +interrupt tree, which can be quite different from the tree of bus +connections. + +In the flattened tree, a node's phandle is represented by a special +\phandle property. When the kernel generates a flattened tree from +OF, it adds a \phandle property to each node, containing the phandle +retrieved from OF. When the tree is generated without OF, however, +only nodes that are actually referred to by phandle need to have this +property. + +Another complication arises because nodes in an OF tree have two +names. First they have the ``unit name'', which is how the node is +referred to in an OF path. The unit name generally consists of a +device type followed by an \texttt{@} followed by a \emph{unit +address}. For example \texttt{/memory@0} is the full path of a memory +node at address 0, \texttt{/ht@0,f2000000/pci@1} is the path of a PCI +bus node, which is under a HyperTransport\tm bus node. The form of +the unit address is bus dependent, but is generally derived from the +node's \texttt{reg} property. In addition, nodes have a property, +\texttt{name}, whose value is usually equal to the first path of the +unit name. For example, the nodes in the previous example would have +\texttt{name} properties equal to \texttt{memory} and \texttt{pci}, +respectively. To save space in the blob, the current version of the +flattened tree format only requires the unit names to be present. +When the kernel unflattens the tree, it automatically generates a +\texttt{name} property from the node's path name. + +\section{The Device Tree Compiler} +\label{sec:dtc} + +\begin{figure}[htb!] + \centering + \begin{lstlisting}[frame=single,basicstyle=\footnotesize\ttfamily, + tabsize=3,numbers=left,xleftmargin=2em] +/memreserve/ 0x20000000-0x21FFFFFF; + +/ { + model = "MyBoard"; + compatible = "MyBoardFamily"; + #address-cells = <2>; + #size-cells = <2>; + + cpus { + #address-cells = <1>; + #size-cells = <0>; + PowerPC,970@0 { + device_type = "cpu"; + reg = <0>; + clock-frequency = <5f5e1000>; + timebase-frequency = <1FCA055>; + linux,boot-cpu; + i-cache-size = <10000>; + d-cache-size = <8000>; + }; + }; + + memory@0 { + device_type = "memory"; + memreg: reg = <00000000 00000000 + 00000000 20000000>; + }; + + mpic@0x3fffdd08400 { + /* Interrupt controller */ + /* ... */ + }; + + pci@40000000000000 { + /* PCI host bridge */ + /* ... */ + }; + + chosen { + bootargs = "root=/dev/sda2"; + linux,platform = <00000600>; + interrupt-controller = + < &/mpic@0x3fffdd08400 >; + }; +}; +\end{lstlisting} + \caption{Example \dtc source} + \label{fig:dts} +\end{figure} + +As we've seen, the flattened device tree format provides a convenient +way of communicating device tree information to the kernel. It's +simple for the kernel to parse, and simple for bootloaders to +manipulate. On OF systems, it's easy to generate the flattened tree +by walking the OF maintained tree. However, for embedded systems, the +flattened tree must be generated from scratch. + +Embedded bootloaders are generally built for a particular board. So, +it's usually possible to build the device tree blob at compile time +and include it in the bootloader image. For minor revisions of the +board, the bootloader can contain code to make the necessary tweaks to +the tree before passing it to the booted kernel. + +The device trees for embedded boards are usually quite simple, and +it's possible to hand construct the necessary blob by hand, but doing +so is tedious. The ``device tree compiler'', \dtc{}\footnote{\dtc can +be obtained from \cite{dtcgit}.}, is designed to make creating device +tree blobs easier by converting a text representation of the tree +into the necessary blob. + +\subsection{Input and output formats} + +As well as the normal mode of compiling a device tree blob from text +source, \dtc can convert a device tree between a number of +representations. It can take its input in one of three different +formats: +\begin{itemize} +\item source, the normal case. The device tree is described in a text + form, described in \S\ref{sec:dts}. +\item blob (\texttt{dtb}), the flattened tree format described in + \S\ref{sec:format}. This mode is useful for checking a pre-existing + device tree blob. +\item filesystem (\texttt{fs}), input is a directory tree in the + layout of \texttt{/proc/device-tree} (roughly, a directory for each + node in the device tree, a file for each property). This is useful + for building a blob for the device tree in use by the currently + running kernel. +\end{itemize} + +In addition, \dtc can output the tree in one of three different +formats: +\begin{itemize} +\item blob (\texttt{dtb}), as in \S\ref{sec:format}. The most + straightforward use of \dtc is to compile from ``source'' to + ``blob'' format. +\item source (\texttt{dts}), as in \S\ref{sec:dts}. If used with blob + input, this allows \dtc to act as a ``decompiler''. +\item assembler source (\texttt{asm}). \dtc can produce an assembler + file, which will assemble into a \texttt{.o} file containing the + device tree blob, with symbols giving the beginning of the blob and + its various subsections. This can then be linked directly into a + bootloader or firmware image. +\end{itemize} + +For maximum applicability, \dtc can both read and write any of the +existing revisions of the blob format. When reading, \dtc takes the +version from the blob header, and when writing it takes a command line +option specifying the desired version. It automatically makes any +necessary adjustments to the tree that are necessary for the specified +version. For example, formats before 0x10 require each node to have +an explicit \texttt{name} property. When \dtc creates such a blob, it +will automatically generate \texttt{name} properties from the unit +names. + +\subsection{Source format} +\label{sec:dts} + +The ``source'' format for \dtc is a text description of the device +tree in a vaguely C-like form. Figure \ref{fig:dts} shows an +example. The file starts with \texttt{/memreserve/} directives, which +gives address ranges to add to the output blob's memory reserve table, +then the device tree proper is described. + +Nodes of the tree are introduced with the node name, followed by a +\texttt{\{} ... \texttt{\};} block containing the node's properties +and subnodes. Properties are given as just {\emph{name} \texttt{=} + \emph{value}\texttt{;}}. The property values can be given in any +of three forms: +\begin{itemize} +\item \emph{string} (for example, \texttt{"MyBoard"}). The property + value is the given string, including terminating NULL. C-style + escapes (\verb+\t+, \verb+\n+, \verb+\0+ and so forth) are allowed. +\item \emph{cells} (for example, \texttt{<0 8000 f0000000>}). The + property value is made up of a list of 32-bit ``cells'', each given + as a hex value. +\item \emph{bytestring} (for example, \texttt{[1234abcdef]}). The + property value is given as a hex bytestring. +\end{itemize} + +Cell properties can also contain \emph{references}. Instead of a hex +number, the source can give an ampersand (\texttt{\&}) followed by the +full path to some node in the tree. For example, in Figure +\ref{fig:dts}, the \texttt{/chosen} node has an +\texttt{interrupt-controller} property referring to the interrupt +controller described by the node \texttt{/mpic@0x3fffdd08400}. In the +output tree, the value of the referenced node's phandle is included in +the property. If that node doesn't have an explicit phandle property, +\dtc will automatically create a unique phandle for it. This approach +makes it easy to create interrupt trees without having to explicitly +assign and remember phandles for the various interrupt controller +nodes. + +The \dtc source can also include ``labels'', which are placed on a +particular node or property. For example, Figure \ref{fig:dts} has a +label ``\texttt{memreg}'' on the \texttt{reg} property of the node +\texttt{/memory@0}. When using assembler output, corresponding labels +in the output are generated, which will assemble into symbols +addressing the part of the blob with the node or property in question. +This is useful for the common case where an embedded board has an +essentially fixed device tree with a few variable properties, such as +the size of memory. The bootloader for such a board can have a device +tree linked in, including a symbol referring to the right place in the +blob to update the parameter with the correct value determined at +runtime. + +\subsection{Tree checking} + +Between reading in the device tree and writing it out in the new +format, \dtc performs a number of checks on the tree: +\begin{itemize} +\item \emph{syntactic structure}: \dtc checks that node and property + names contain only allowed characters and meet length restrictions. + It checks that a node does not have multiple properties or subnodes + with the same name. +\item \emph{semantic structure}: In some cases, \dtc checks that + properties whose contents are defined by convention have appropriate + values. For example, it checks that \texttt{reg} properties have a + length that makes sense given the address forms specified by the + \texttt{\#address-cells} and \texttt{\#size-cells} properties. It + checks that properties such as \texttt{interrupt-parent} contain a + valid phandle. +\item \emph{Linux requirements}: \dtc checks that the device tree + contains those nodes and properties that are required by the Linux + kernel to boot correctly. +\end{itemize} + +These checks are useful to catch simple problems with the device tree, +rather than having to debug the results on an embedded kernel. With +the blob input mode, it can also be used for diagnosing problems with +an existing blob. + +\section{Future Work} + +\subsection{Board ports} + +The flattened device tree has always been the only supported way to +boot a \texttt{ppc64} kernel on an embedded system. With the merge of +\texttt{ppc32} and \texttt{ppc64} code it has also become the only +supported way to boot any merged \texttt{powerpc} kernel, 32-bit or +64-bit. In fact, the old \texttt{ppc} architecture exists mainly just +to support the old ppc32 embedded ports that have not been migrated +to the flattened device tree approach. We plan to remove the +\texttt{ppc} architecture eventually, which will mean porting all the +various embedded boards to use the flattened device tree. + +\subsection{\dtc features} + +While it is already quite usable, there are a number of extra features +that \dtc could include to make creating device trees more convenient: +\begin{itemize} +\item \emph{better tree checking}: Although \dtc already performs a + number of checks on the device tree, they are rather haphazard. In + many cases \dtc will give up after detecting a minor error early and + won't pick up more interesting errors later on. There is a + \texttt{-f} parameter that forces \dtc to generate an output tree + even if there are errors. At present, this needs to be used more + often than one might hope, because \dtc is bad at deciding which + errors should really be fatal, and which rate mere warnings. +\item \emph{binary include}: Occasionally, it is useful for the device + tree to incorporate as a property a block of binary data for some + board-specific purpose. For example, many of Apple's device trees + incorporate bytecode drivers for certain platform devices. \dtc's + source format ought to allow this by letting a property's value be + read directly from a binary file. +\item \emph{macros}: it might be useful for \dtc to implement some + sort of macros so that a tree containing a number of similar devices + (for example, multiple identical ethernet controllers or PCI buses) + can be written more quickly. At present, this can be accomplished + in part by running the source file through CPP before compiling with + \dtc. It's not clear whether ``native'' support for macros would be + more useful. +\end{itemize} + +\bibliographystyle{amsplain} +\bibliography{dtc-paper} + +\section*{About the authors} + +David Gibson has been a member of the IBM Linux Technology Center, +working from Canberra, Australia, since 2001. Recently he has worked +on Linux hugepage support and performance counter support for ppc64, +as well as the device tree compiler. In the past, he has worked on +bringup for various ppc and ppc64 embedded systems, the orinoco +wireless driver, ramfs, and a userspace checkpointing system +(\texttt{esky}). + +Benjamin Herrenschmidt was a MacOS developer for about 10 years, but +ultimately saw the light and installed Linux on his Apple PowerPC +machine. After writing a bootloader, BootX, for it in 1998, he +started contributing to the PowerPC Linux port in various areas, +mostly around the support for Apple machines. He became official +PowerMac maintainer in 2001. In 2003, he joined the IBM Linux +Technology Center in Canberra, Australia, where he ported the 64 bit +PowerPC kernel to Apple G5 machines and the Maple embedded board, +among others things. He's a member of the ppc64 development ``team'' +and one of his current goals is to make the integration of embedded +platforms smoother and more maintainable than in the 32-bit PowerPC +kernel. + +\section*{Legal Statement} + +This work represents the view of the author and does not necessarily +represent the view of IBM. + +IBM, \ppc, \ppc Architecture, POWER5, pSeries and iSeries are +trademarks or registered trademarks of International Business Machines +Corporation in the United States and/or other countries. + +Apple and Power Macintosh are a registered trademarks of Apple +Computer Inc. in the United States, other countries, or both. + +Linux is a registered trademark of Linus Torvalds. + +Other company, product, and service names may be trademarks or service +marks of others. + +\end{document} diff --git a/dtc/Documentation/dts-format.txt b/dtc/Documentation/dts-format.txt new file mode 100644 index 000000000..41741dffc --- /dev/null +++ b/dtc/Documentation/dts-format.txt @@ -0,0 +1,122 @@ +Device Tree Source Format (version 1) +===================================== + +The Device Tree Source (DTS) format is a textual representation of a +device tree in a form that can be processed by dtc into a binary +device tree in the form expected by the kernel. The description below +is not a formal syntax definition of DTS, but describes the basic +constructs used to represent device trees. + +Node and property definitions +----------------------------- + +Device tree nodes are defined with a node name and unit address with +braces marking the start and end of the node definition. They may be +preceded by a label. + + [label:] node-name[@unit-address] { + [properties definitions] + [child nodes] + } + +Nodes may contain property definitions and/or child node +definitions. If both are present, properties must come before child +nodes. + +Property definitions are name value pairs in the form: + [label:] property-name = value; +except for properties with empty (zero length) value which have the +form: + [label:] property-name; + +Property values may be defined as an array of 8, 16, 32, or 64-bit integer +elements, as NUL-terminated strings, as bytestrings or a combination of these. + +* Arrays are represented by angle brackets surrounding a space separated list + of C-style integers or character literals. Array elements default to 32-bits + in size. An array of 32-bit elements is also known as a cell list or a list + of cells. A cell being an unsigned 32-bit integer. + + e.g. interrupts = <17 0xc>; + +* A 64-bit value can be represented with two 32-bit elements. + + e.g. clock-frequency = <0x00000001 0x00000000>; + +* The storage size of an element can be changed using the /bits/ prefix. The + /bits/ prefix allows for the creation of 8, 16, 32, and 64-bit elements. + The resulting array will not be padded to a multiple of the default 32-bit + element size. + + e.g. interrupts = /bits/ 8 <17 0xc>; + e.g. clock-frequency = /bits/ 64 <0x0000000100000000>; + +* A NUL-terminated string value is represented using double quotes + (the property value is considered to include the terminating NUL + character). + + e.g. compatible = "simple-bus"; + +* A bytestring is enclosed in square brackets [] with each byte + represented by two hexadecimal digits. Spaces between each byte are + optional. + + e.g. local-mac-address = [00 00 12 34 56 78]; or equivalently + local-mac-address = [000012345678]; + +* Values may have several comma-separated components, which are + concatenated together. + e.g. compatible = "ns16550", "ns8250"; + example = <0xf00f0000 19>, "a strange property format"; + +* In an array a reference to another node will be expanded to that node's + phandle. References may by '&' followed by a node's label: + e.g. interrupt-parent = < &mpic >; + or they may be '&' followed by a node's full path in braces: + e.g. interrupt-parent = < &{/soc/interrupt-controller@40000} >; + References are only permitted in arrays that have an element size of + 32-bits. + +* Outside an array, a reference to another node will be expanded to that + node's full path. + e.g. ethernet0 = &EMAC0; + +* Labels may also appear before or after any component of a property + value, or between elements of an array, or between bytes of a bytestring. + e.g. reg = reglabel: <0 sizelabel: 0x1000000>; + e.g. prop = [ab cd ef byte4: 00 ff fe]; + e.g. str = start: "string value" end: ; + + +File layout +----------- + +Version 1 DTS files have the overall layout: + /dts-v1/; + + [memory reservations] + + / { + [property definitions] + [child nodes] + }; + +* The "/dts-v1/;" must be present to identify the file as a version 1 + DTS (dts files without this tag will be treated by dtc as being in + the obsolete "version 0", which uses a different format for integers + amongst other small but incompatible changes). + +* Memory reservations define an entry for the device tree blob's + memory reservation table. They have the form: + e.g. /memreserve/ <address> <length>; + Where <address> and <length> are 64-bit C-style integers. + +* The / { ... }; section defines the root node of the device tree. + +* C style (/* ... */) and C++ style (// ...) comments are supported. + + + + -- David Gibson <david@gibson.dropbear.id.au> + -- Yoder Stuart <stuart.yoder@freescale.com> + -- Anton Staaf <robotboy@chromium.org> diff --git a/dtc/Documentation/manual.txt b/dtc/Documentation/manual.txt new file mode 100644 index 000000000..97e53b9dd --- /dev/null +++ b/dtc/Documentation/manual.txt @@ -0,0 +1,762 @@ +Device Tree Compiler Manual +=========================== + +I - "dtc", the device tree compiler + 1) Obtaining Sources + 1.1) Submitting Patches + 2) Description + 3) Command Line + 4) Source File + 4.1) Overview + 4.2) Properties + 4.3) Labels and References + +II - The DT block format + 1) Header + 2) Device tree generalities + 3) Device tree "structure" block + 4) Device tree "strings" block + + +III - libfdt + +IV - Utility Tools + 1) convert-dtsv0 -- Conversion to Version 1 + 1) fdtdump + + +I - "dtc", the device tree compiler +=================================== + +1) Sources + +Source code for the Device Tree Compiler can be found at git.kernel.org. + +The upstream repository is here: + + git://git.kernel.org/pub/scm/utils/dtc/dtc.git + https://git.kernel.org/pub/scm/utils/dtc/dtc.git + +The gitweb interface for the upstream repository is: + + https://git.kernel.org/cgit/utils/dtc/dtc.git/ + +1.1) Submitting Patches + +Patches should be sent to the maintainers: + David Gibson <david@gibson.dropbear.id.au> + Jon Loeliger <loeliger@gmail.com> +and CCed to <devicetree-compiler@vger.kernel.org>. + +2) Description + +The Device Tree Compiler, dtc, takes as input a device-tree in +a given format and outputs a device-tree in another format. +Typically, the input format is "dts", a human readable source +format, and creates a "dtb", or binary format as output. + +The currently supported Input Formats are: + + - "dtb": "blob" format. A flattened device-tree block with + header in one binary blob. + + - "dts": "source" format. A text file containing a "source" + for a device-tree. + + - "fs" format. A representation equivalent to the output of + /proc/device-tree where nodes are directories and + properties are files. + +The currently supported Output Formats are: + + - "dtb": "blob" format + + - "dts": "source" format + + - "asm": assembly language file. A file that can be sourced + by gas to generate a device-tree "blob". That file can + then simply be added to your Makefile. Additionally, the + assembly file exports some symbols that can be used. + + - "yaml": DT encoded in YAML format. This representation is an + intermediate format used for validation tools. + + +3) Command Line + +The syntax of the dtc command line is: + + dtc [options] [<input_filename>] + +Options: + + <input_filename> + The name of the input source file. If no <input_filename> + or "-" is given, stdin is used. + + -b <number> + Set the physical boot cpu. + + -f + Force. Try to produce output even if the input tree has errors. + + -h + Emit a brief usage and help message. + + -I <input_format> + The source input format, as listed above. + + -o <output_filename> + The name of the generated output file. Use "-" for stdout. + + -O <output_format> + The generated output format, as listed above. + + -d <dependency_filename> + Generate a dependency file during compilation. + + -q + Quiet: -q suppress warnings, -qq errors, -qqq all + + -R <number> + Make space for <number> reserve map entries + Relevant for dtb and asm output only. + + -@ + Generates a __symbols__ node at the root node of the resulting blob + for any node labels used, and for any local references using phandles + it also generates a __local_fixups__ node that tracks them. + + When using the /plugin/ tag all unresolved label references to + be tracked in the __fixups__ node, making dynamic resolution possible. + + -A + Generate automatically aliases for all node labels. This is similar to + the -@ option (the __symbols__ node contain identical information) but + the semantics are slightly different since no phandles are automatically + generated for labeled nodes. + + -S <bytes> + Ensure the blob at least <bytes> long, adding additional + space if needed. + + -v + Print DTC version and exit. + + -V <output_version> + Generate output conforming to the given <output_version>. + By default the most recent version is generated. + Relevant for dtb and asm output only. + + +The <output_version> defines what version of the "blob" format will be +generated. Supported versions are 1, 2, 3, 16 and 17. The default is +always the most recent version and is likely the highest number. + +Additionally, dtc performs various sanity checks on the tree. + + +4) Device Tree Source file + +4.1) Overview + +Here is a very rough overview of the layout of a DTS source file: + + + sourcefile: versioninfo plugindecl list_of_memreserve devicetree + + memreserve: label 'memreserve' ADDR ADDR ';' + | label 'memreserve' ADDR '-' ADDR ';' + + devicetree: '/' nodedef + + versioninfo: '/' 'dts-v1' '/' ';' + + plugindecl: '/' 'plugin' '/' ';' + | /* empty */ + + nodedef: '{' list_of_property list_of_subnode '}' ';' + + property: label PROPNAME '=' propdata ';' + + propdata: STRING + | '<' list_of_cells '>' + | '[' list_of_bytes ']' + + subnode: label nodename nodedef + +That structure forms a hierarchical layout of nodes and properties +rooted at an initial node as: + + / { + } + +Both classic C style and C++ style comments are supported. + +Source files may be directly included using the syntax: + + /include/ "filename" + + +4.2) Properties + +Properties are named, possibly labeled, values. Each value +is one of: + + - A null-teminated C-like string, + - A numeric value fitting in 32 bits, + - A list of 32-bit values + - A byte sequence + +Here are some example property definitions: + + - A property containing a 0 terminated string + + property1 = "string_value"; + + - A property containing a numerical 32-bit hexadecimal value + + property2 = <1234abcd>; + + - A property containing 3 numerical 32-bit hexadecimal values + + property3 = <12345678 12345678 deadbeef>; + + - A property whose content is an arbitrary array of bytes + + property4 = [0a 0b 0c 0d de ea ad be ef]; + + +Node may contain sub-nodes to obtain a hierarchical structure. +For example: + + - A child node named "childnode" whose unit name is + "childnode at address". It in turn has a string property + called "childprop". + + childnode@address { + childprop = "hello\n"; + }; + + +By default, all numeric values are hexadecimal. Alternate bases +may be specified using a prefix "d#" for decimal, "b#" for binary, +and "o#" for octal. + +Strings support common escape sequences from C: "\n", "\t", "\r", +"\(octal value)", "\x(hex value)". + + +4.3) Labels and References + +Labels may be applied to nodes or properties. Labels appear +before a node name, and are referenced using an ampersand: &label. +Absolute node path names are also allowed in node references. + +In this example, a node is labeled "mpic" and then referenced: + + mpic: interrupt-controller@40000 { + ... + }; + + ethernet-phy@3 { + interrupt-parent = <&mpic>; + ... + }; + +And used in properties, labels may appear before or after any value: + + randomnode { + prop: string = data: "mystring\n" data_end: ; + ... + }; + + + +II - The DT block format +======================== + +This chapter defines the format of the flattened device-tree +passed to the kernel. The actual content of the device tree +are described in the kernel documentation in the file + + linux-2.6/Documentation/powerpc/booting-without-of.txt + +You can find example of code manipulating that format within +the kernel. For example, the file: + + including arch/powerpc/kernel/prom_init.c + +will generate a flattened device-tree from the Open Firmware +representation. Other utilities such as fs2dt, which is part of +the kexec tools, will generate one from a filesystem representation. +Some bootloaders such as U-Boot provide a bit more support by +using the libfdt code. + +For booting the kernel, the device tree block has to be in main memory. +It has to be accessible in both real mode and virtual mode with no +mapping other than main memory. If you are writing a simple flash +bootloader, it should copy the block to RAM before passing it to +the kernel. + + +1) Header +--------- + +The kernel is entered with r3 pointing to an area of memory that is +roughly described in include/asm-powerpc/prom.h by the structure +boot_param_header: + + struct boot_param_header { + u32 magic; /* magic word OF_DT_HEADER */ + u32 totalsize; /* total size of DT block */ + u32 off_dt_struct; /* offset to structure */ + u32 off_dt_strings; /* offset to strings */ + u32 off_mem_rsvmap; /* offset to memory reserve map */ + u32 version; /* format version */ + u32 last_comp_version; /* last compatible version */ + + /* version 2 fields below */ + u32 boot_cpuid_phys; /* Which physical CPU id we're + booting on */ + /* version 3 fields below */ + u32 size_dt_strings; /* size of the strings block */ + + /* version 17 fields below */ + u32 size_dt_struct; /* size of the DT structure block */ + }; + +Along with the constants: + + /* Definitions used by the flattened device tree */ + #define OF_DT_HEADER 0xd00dfeed /* 4: version, + 4: total size */ + #define OF_DT_BEGIN_NODE 0x1 /* Start node: full name + */ + #define OF_DT_END_NODE 0x2 /* End node */ + #define OF_DT_PROP 0x3 /* Property: name off, + size, content */ + #define OF_DT_END 0x9 + +All values in this header are in big endian format, the various +fields in this header are defined more precisely below. All "offset" +values are in bytes from the start of the header; that is from the +value of r3. + + - magic + + This is a magic value that "marks" the beginning of the + device-tree block header. It contains the value 0xd00dfeed and is + defined by the constant OF_DT_HEADER + + - totalsize + + This is the total size of the DT block including the header. The + "DT" block should enclose all data structures defined in this + chapter (who are pointed to by offsets in this header). That is, + the device-tree structure, strings, and the memory reserve map. + + - off_dt_struct + + This is an offset from the beginning of the header to the start + of the "structure" part the device tree. (see 2) device tree) + + - off_dt_strings + + This is an offset from the beginning of the header to the start + of the "strings" part of the device-tree + + - off_mem_rsvmap + + This is an offset from the beginning of the header to the start + of the reserved memory map. This map is a list of pairs of 64- + bit integers. Each pair is a physical address and a size. The + list is terminated by an entry of size 0. This map provides the + kernel with a list of physical memory areas that are "reserved" + and thus not to be used for memory allocations, especially during + early initialization. The kernel needs to allocate memory during + boot for things like un-flattening the device-tree, allocating an + MMU hash table, etc... Those allocations must be done in such a + way to avoid overriding critical things like, on Open Firmware + capable machines, the RTAS instance, or on some pSeries, the TCE + tables used for the iommu. Typically, the reserve map should + contain _at least_ this DT block itself (header,total_size). If + you are passing an initrd to the kernel, you should reserve it as + well. You do not need to reserve the kernel image itself. The map + should be 64-bit aligned. + + - version + + This is the version of this structure. Version 1 stops + here. Version 2 adds an additional field boot_cpuid_phys. + Version 3 adds the size of the strings block, allowing the kernel + to reallocate it easily at boot and free up the unused flattened + structure after expansion. Version 16 introduces a new more + "compact" format for the tree itself that is however not backward + compatible. Version 17 adds an additional field, size_dt_struct, + allowing it to be reallocated or moved more easily (this is + particularly useful for bootloaders which need to make + adjustments to a device tree based on probed information). You + should always generate a structure of the highest version defined + at the time of your implementation. Currently that is version 17, + unless you explicitly aim at being backward compatible. + + - last_comp_version + + Last compatible version. This indicates down to what version of + the DT block you are backward compatible. For example, version 2 + is backward compatible with version 1 (that is, a kernel build + for version 1 will be able to boot with a version 2 format). You + should put a 1 in this field if you generate a device tree of + version 1 to 3, or 16 if you generate a tree of version 16 or 17 + using the new unit name format. + + - boot_cpuid_phys + + This field only exist on version 2 headers. It indicate which + physical CPU ID is calling the kernel entry point. This is used, + among others, by kexec. If you are on an SMP system, this value + should match the content of the "reg" property of the CPU node in + the device-tree corresponding to the CPU calling the kernel entry + point (see further chapters for more information on the required + device-tree contents) + + - size_dt_strings + + This field only exists on version 3 and later headers. It + gives the size of the "strings" section of the device tree (which + starts at the offset given by off_dt_strings). + + - size_dt_struct + + This field only exists on version 17 and later headers. It gives + the size of the "structure" section of the device tree (which + starts at the offset given by off_dt_struct). + +So the typical layout of a DT block (though the various parts don't +need to be in that order) looks like this (addresses go from top to +bottom): + + ------------------------------ + r3 -> | struct boot_param_header | + ------------------------------ + | (alignment gap) (*) | + ------------------------------ + | memory reserve map | + ------------------------------ + | (alignment gap) | + ------------------------------ + | | + | device-tree structure | + | | + ------------------------------ + | (alignment gap) | + ------------------------------ + | | + | device-tree strings | + | | + -----> ------------------------------ + | + | + --- (r3 + totalsize) + + (*) The alignment gaps are not necessarily present; their presence + and size are dependent on the various alignment requirements of + the individual data blocks. + + +2) Device tree generalities +--------------------------- + +This device-tree itself is separated in two different blocks, a +structure block and a strings block. Both need to be aligned to a 4 +byte boundary. + +First, let's quickly describe the device-tree concept before detailing +the storage format. This chapter does _not_ describe the detail of the +required types of nodes & properties for the kernel, this is done +later in chapter III. + +The device-tree layout is strongly inherited from the definition of +the Open Firmware IEEE 1275 device-tree. It's basically a tree of +nodes, each node having two or more named properties. A property can +have a value or not. + +It is a tree, so each node has one and only one parent except for the +root node who has no parent. + +A node has 2 names. The actual node name is generally contained in a +property of type "name" in the node property list whose value is a +zero terminated string and is mandatory for version 1 to 3 of the +format definition (as it is in Open Firmware). Version 16 makes it +optional as it can generate it from the unit name defined below. + +There is also a "unit name" that is used to differentiate nodes with +the same name at the same level, it is usually made of the node +names, the "@" sign, and a "unit address", which definition is +specific to the bus type the node sits on. + +The unit name doesn't exist as a property per-se but is included in +the device-tree structure. It is typically used to represent "path" in +the device-tree. More details about the actual format of these will be +below. + +The kernel powerpc generic code does not make any formal use of the +unit address (though some board support code may do) so the only real +requirement here for the unit address is to ensure uniqueness of +the node unit name at a given level of the tree. Nodes with no notion +of address and no possible sibling of the same name (like /memory or +/cpus) may omit the unit address in the context of this specification, +or use the "@0" default unit address. The unit name is used to define +a node "full path", which is the concatenation of all parent node +unit names separated with "/". + +The root node doesn't have a defined name, and isn't required to have +a name property either if you are using version 3 or earlier of the +format. It also has no unit address (no @ symbol followed by a unit +address). The root node unit name is thus an empty string. The full +path to the root node is "/". + +Every node which actually represents an actual device (that is, a node +which isn't only a virtual "container" for more nodes, like "/cpus" +is) is also required to have a "device_type" property indicating the +type of node . + +Finally, every node that can be referenced from a property in another +node is required to have a "linux,phandle" property. Real open +firmware implementations provide a unique "phandle" value for every +node that the "prom_init()" trampoline code turns into +"linux,phandle" properties. However, this is made optional if the +flattened device tree is used directly. An example of a node +referencing another node via "phandle" is when laying out the +interrupt tree which will be described in a further version of this +document. + +This "linux, phandle" property is a 32-bit value that uniquely +identifies a node. You are free to use whatever values or system of +values, internal pointers, or whatever to generate these, the only +requirement is that every node for which you provide that property has +a unique value for it. + +Here is an example of a simple device-tree. In this example, an "o" +designates a node followed by the node unit name. Properties are +presented with their name followed by their content. "content" +represents an ASCII string (zero terminated) value, while <content> +represents a 32-bit hexadecimal value. The various nodes in this +example will be discussed in a later chapter. At this point, it is +only meant to give you a idea of what a device-tree looks like. I have +purposefully kept the "name" and "linux,phandle" properties which +aren't necessary in order to give you a better idea of what the tree +looks like in practice. + + / o device-tree + |- name = "device-tree" + |- model = "MyBoardName" + |- compatible = "MyBoardFamilyName" + |- #address-cells = <2> + |- #size-cells = <2> + |- linux,phandle = <0> + | + o cpus + | | - name = "cpus" + | | - linux,phandle = <1> + | | - #address-cells = <1> + | | - #size-cells = <0> + | | + | o PowerPC,970@0 + | |- name = "PowerPC,970" + | |- device_type = "cpu" + | |- reg = <0> + | |- clock-frequency = <5f5e1000> + | |- 64-bit + | |- linux,phandle = <2> + | + o memory@0 + | |- name = "memory" + | |- device_type = "memory" + | |- reg = <00000000 00000000 00000000 20000000> + | |- linux,phandle = <3> + | + o chosen + |- name = "chosen" + |- bootargs = "root=/dev/sda2" + |- linux,phandle = <4> + +This tree is almost a minimal tree. It pretty much contains the +minimal set of required nodes and properties to boot a linux kernel; +that is, some basic model information at the root, the CPUs, and the +physical memory layout. It also includes misc information passed +through /chosen, like in this example, the platform type (mandatory) +and the kernel command line arguments (optional). + +The /cpus/PowerPC,970@0/64-bit property is an example of a +property without a value. All other properties have a value. The +significance of the #address-cells and #size-cells properties will be +explained in chapter IV which defines precisely the required nodes and +properties and their content. + + +3) Device tree "structure" block + +The structure of the device tree is a linearized tree structure. The +"OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE" +ends that node definition. Child nodes are simply defined before +"OF_DT_END_NODE" (that is nodes within the node). A 'token' is a 32 +bit value. The tree has to be "finished" with a OF_DT_END token + +Here's the basic structure of a single node: + + * token OF_DT_BEGIN_NODE (that is 0x00000001) + * for version 1 to 3, this is the node full path as a zero + terminated string, starting with "/". For version 16 and later, + this is the node unit name only (or an empty string for the + root node) + * [align gap to next 4 bytes boundary] + * for each property: + * token OF_DT_PROP (that is 0x00000003) + * 32-bit value of property value size in bytes (or 0 if no + value) + * 32-bit value of offset in string block of property name + * property value data if any + * [align gap to next 4 bytes boundary] + * [child nodes if any] + * token OF_DT_END_NODE (that is 0x00000002) + +So the node content can be summarized as a start token, a full path, +a list of properties, a list of child nodes, and an end token. Every +child node is a full node structure itself as defined above. + +NOTE: The above definition requires that all property definitions for +a particular node MUST precede any subnode definitions for that node. +Although the structure would not be ambiguous if properties and +subnodes were intermingled, the kernel parser requires that the +properties come first (up until at least 2.6.22). Any tools +manipulating a flattened tree must take care to preserve this +constraint. + +4) Device tree "strings" block + +In order to save space, property names, which are generally redundant, +are stored separately in the "strings" block. This block is simply the +whole bunch of zero terminated strings for all property names +concatenated together. The device-tree property definitions in the +structure block will contain offset values from the beginning of the +strings block. + + +III - libfdt +============ + +This library should be merged into dtc proper. +This library should likely be worked into U-Boot and the kernel. + + +IV - Utility Tools +================== + +1) convert-dtsv0 -- Conversion to Version 1 + +convert-dtsv0 is a small utility program which converts (DTS) +Device Tree Source from the obsolete version 0 to version 1. + +Version 1 DTS files are marked by line "/dts-v1/;" at the top of the file. + +The syntax of the convert-dtsv0 command line is: + + convert-dtsv0 [<input_filename ... >] + +Each file passed will be converted to the new /dts-v1/ version by creating +a new file with a "v1" appended the filename. + +Comments, empty lines, etc. are preserved. + + +2) fdtdump -- Flat Device Tree dumping utility + +The fdtdump program prints a readable version of a flat device tree file. + +The syntax of the fdtdump command line is: + + fdtdump [options] <DTB-file-name> + +Where options are: + -d,--debug Dump debug information while decoding the file + -s,--scan Scan for an embedded fdt in given file + +3) fdtoverlay -- Flat Device Tree overlay applicator + +The fdtoverlay applies an arbitrary number of FDT overlays to a base FDT blob +to a given output file. + +The syntax of the fdtoverlay command line is: + + fdtoverlay -i <base-blob> -o <output-blob> <overlay-blob0> [<overlay-blob1> ...] + +Where options are: + -i, --input Input base DT blob + -o, --output Output DT blob + -v, --verbose Verbose message output + +4 ) fdtget -- Read properties from device tree + +This command can be used to obtain individual values from the device tree in a +nicely formatted way. You can specify multiple nodes to display (when using -p) +or multiple node/property pairs (when not using -p). For the latter, each +property is displayed on its own line, with a space between each cell within +the property. + +The syntax of the fdtget command is: + + fdtget <options> <dt file> [<node> <property>]... + fdtget -p <options> <dt file> [<node> ]... + +where options are: + + <type> s=string, i=int, u=unsigned, x=hex + Optional modifier prefix: + hh or b=byte, h=2 byte, l=4 byte (default) + + Options: -[t:pld:hV] + -t, --type <arg> Type of data + -p, --properties List properties for each node + -l, --list List subnodes for each node + -d, --default <arg> Default value to display when the property is missing + -h, --help Print this help and exit + -V, --version Print version and exit + +If -t is not provided, fdtget will try to figure out the type, trying to detect +strings, string lists and the size of each value in the property. This is +similar to how fdtdump works, and uses the same heuristics. + + +5 ) fdtput - Write properties to a device tree + +The syntax of the fdtput command is: + + fdtput <options> <dt file> <node> <property> [<value>...] + fdtput -c <options> <dt file> [<node>...] + fdtput -r <options> <dt file> [<node>...] + fdtput -d <options> <dt file> <node> [<property>...] + +Options are: + + <type> s=string, i=int, u=unsigned, x=hex + Optional modifier prefix: + hh or b=byte, h=2 byte, l=4 byte (default) + + -c, --create Create nodes if they don't already exist + -r, --remove Delete nodes (and any subnodes) if they already exist + -d, --delete Delete properties if they already exist + -p, --auto-path Automatically create nodes as needed for the node path + -t, --type <arg> Type of data + -v, --verbose Display each value decoded from command line + -h, --help Print this help and exit + -V, --version Print version and exit + +The option determines which usage is selected and therefore the operation that +is performed. The first usage adds or updates properties; the rest are used to +create/delete nodes and delete properties. + +For the first usage, the command line arguments are joined together into a +single value which is written to the property. The -t option is required so +that fdtput knows how to decode its arguments. |