43   embedded machine.  To do this, we supply the kernel with a compact
44   flattened-tree representation of the system's hardware based on the
48   The ``blob'' representing the device tree can be created using \dtc
49   --- the Device Tree Compiler --- that turns a simple text
50   representation of the tree into the compact representation used by
51   the kernel.  The compiler can produce either a binary ``blob'' or an
55   This flattened-tree approach is now the only supported method of
57   to make it the only supported method for all \texttt{powerpc}
58   kernels in the future.
63 \subsection{OF and the device tree}
65 Historically, ``everyday'' \ppc machines have booted with the help of
68 describes all of the system's hardware devices and how they're
70 the Linux kernel uses OF calls to scan the device tree and transfer it
77 information about the device.  The values are arbitrary byte strings,
84 might supply a few vital system parameters (size of RAM and the like),
85 but nothing as detailed or complete as the OF device tree.  This has
86 meant that the various 32-bit \ppc embedded ports have required a
87 variety of hacks spread across the kernel to deal with the lack of
95 Until relatively recently, the only 64-bit \ppc machines without OF
98 around the lack of a device tree.  Even so, the lack means the iSeries
99 boot sequence must be quite different from the pSeries or Macintosh,
103 the kernel boots, it takes over full control of the system from OF,
105 kernel, OF is no longer around for the second kernel to query.
109 In May 2005 \benh implemented a new approach to handling the device
111 the first thing the kernel runs is a small piece of code in
112 \texttt{prom\_init.c}, which executes in the context of OF.  This code
113 walks the device tree using OF calls, and transcribes it into a
115 passed to the kernel proper, which eventually unflattens the tree into
116 its runtime form.  This blob is the only data communicated between the
117 \texttt{prom\_init.c} bootstrap and the rest of the kernel.
119 When OF isn't available, either because the machine doesn't have it at
120 all or because \kexec has been used, the kernel instead starts
121 directly from the entry point taking a flattened device tree.  The
123 by part of the kernel from OF.  For \kexec, the userland
124 \texttt{kexec} tools build the blob from the runtime device tree
125 before invoking the new kernel.  For embedded systems the blob can
126 come either from the embedded bootloader, or from a specialised
127 version of the \texttt{zImage} wrapper for the system in question.
129 \subsection{Properties of the flattened tree}
131 The flattened tree format should be easy to handle, both for the
132 kernel that parses it and the bootloader that generates it.  In
133 particular, the following properties are desirable:
136 \item \emph{relocatable}: the bootloader or kernel should be able to
137   move the blob around as a whole, without needing to parse or adjust
139   within the blob.
140 \item \emph{insert and delete}: sometimes the bootloader might want to
141   make tweaks to the flattened tree, such as deleting or inserting a
143   having to effectively regenerate the whole flattened tree.  In
144   practice this means limiting the use of internal offsets in the blob
148   resources, particularly RAM and flash memory space.  Thus, the tree
152 \subsection{Format of the device tree blob}
203 The format for the blob we devised, was first described on the
205 since evolved through various revisions, and the current version is
206 included as part of the \dtc (see \S\ref{sec:dtc}) git tree,
209 Figure \ref{fig:blob-layout} shows the layout of the blob of data
210 containing the device tree.  It has three sections of variable size:
211 the \emph{memory reserve table}, the \emph{structure block} and the
212 \emph{strings block}.  A small header gives the blob's size and
213 version and the locations of the three sections, plus a handful of
217 the kernel must not use\footnote{Usually such ranges contain some data
218 structure initialised by the firmware that must be preserved by the
223 the structure block as described below.
225 The structure block contains the device tree proper.  Each node is
226 introduced with a 32-bit \dtbeginnode tag, followed by the node's name
228 follows all of the properties of the node, each introduced with a
229 \dtprop tag, then all of the node's subnodes, each introduced with
231 after the \dtendnode for the root node is an \dtend tag, indicating
232 the end of the whole tree\footnote{This is redundant, but included for
233 ease of parsing.}.  The structure block starts with the \dtbeginnode
234 introducing the description of the root node (named \texttt{/}).
236 Each property, after the \dtprop, has a 32-bit value giving an offset
237 from the beginning of the strings block at which the property name is
239 the same name, this approach can substantially reduce the total size
240 of the blob.  The name offset is followed by the length of the
241 property value (as a 32-bit value) and then the data itself padded to
244 \subsection{Contents of the tree}
247 Having seen how to represent the device tree structure as a flattened
248 blob, what actually goes into the tree?  The short answer is ``the
249 same as an OF tree''.  On OF systems, the flattened tree is
250 transcribed directly from the OF device tree, so for simplicity we
251 also use OF conventions for the tree on other systems.
255 properties that the kernel actually requires; the flattened tree
256 generally need not include devices that the kernel can probe itself.
258 PCI device on the system.  A flattened tree need only include nodes
259 for the PCI host bridges; the kernel will scan the buses thus
260 described to find the subsidiary devices.  The device tree can include
261 nodes for devices where the kernel needs extra information, though:
265 Where they exist, we follow the IEEE1275 bindings that specify how to
266 describe various buses in the device tree (for example,
270 specific devices such as the various System-on-Chip buses are not
272 with the general conventions of IEEE1275 (a simple such binding for a
276 One complication arises for representing ``phandles'' in the flattened
277 tree.  In OF, each node in the tree has an associated phandle, a
278 32-bit integer that uniquely identifies the node\footnote{In practice
280 handle is used by the various OF calls to query and traverse the tree.
281 Sometimes phandles are also used within the tree to refer to other
282 nodes in the tree.  For example, devices that produce interrupts
283 generally have an \texttt{interrupt-parent} property giving the
284 phandle of the interrupt controller that handles interrupts from this
286 the kernel to build a complete representation of the system's
287 interrupt tree, which can be quite different from the tree of bus
290 In the flattened tree, a node's phandle is represented by a special
291 \phandle property.  When the kernel generates a flattened tree from
292 OF, it adds a \phandle property to each node, containing the phandle
293 retrieved from OF.  When the tree is generated without OF, however,
298 names.  First they have the ``unit name'', which is how the node is
301 address}.  For example \texttt{/memory@0} is the full path of a memory
302 node at address 0, \texttt{/ht@0,f2000000/pci@1} is the path of a PCI
304 the unit address is bus dependent, but is generally derived from the
306 \texttt{name}, whose value is usually equal to the first path of the
307 unit name. For example, the nodes in the previous example would have
309 respectively.  To save space in the blob, the current version of the
310 flattened tree format only requires the unit names to be present.
311 When the kernel unflattens the tree, it automatically generates a
312 \texttt{name} property from the node's path name.
371 As we've seen, the flattened device tree format provides a convenient
372 way of communicating device tree information to the kernel.  It's
373 simple for the kernel to parse, and simple for bootloaders to
374 manipulate.  On OF systems, it's easy to generate the flattened tree
375 by walking the OF maintained tree.  However, for embedded systems, the
379 it's usually possible to build the device tree blob at compile time
380 and include it in the bootloader image.  For minor revisions of the
381 board, the bootloader can contain code to make the necessary tweaks to
382 the tree before passing it to the booted kernel.
385 it's possible to hand construct the necessary blob by hand, but doing
388 tree blobs easier by converting a text representation of the tree
389 into the necessary blob.
393 As well as the normal mode of compiling a device tree blob from text
398 \item source, the normal case.  The device tree is described in a text
400 \item blob (\texttt{dtb}), the flattened tree format described in
403 \item filesystem (\texttt{fs}), input is a directory tree in the
405   node in the device tree, a file for each property).  This is useful
406   for building a blob for the device tree in use by the currently
410 In addition, \dtc can output the tree in one of three different
419   file, which will assemble into a \texttt{.o} file containing the
420   device tree blob, with symbols giving the beginning of the blob and
425 For maximum applicability, \dtc can both read and write any of the
426 existing revisions of the blob format.  When reading, \dtc takes the
427 version from the blob header, and when writing it takes a command line
428 option specifying the desired version.  It automatically makes any
429 necessary adjustments to the tree that are necessary for the specified
432 will automatically generate \texttt{name} properties from the unit
438 The ``source'' format for \dtc is a text description of the device
441 gives address ranges to add to the output blob's memory reserve table,
442 then the device tree proper is described.
444 Nodes of the tree are introduced with the node name, followed by a
445 \texttt{\{} ... \texttt{\};} block containing the node's properties
451   value is the given string, including terminating NULL.  C-style
461 number, the source can give an ampersand (\texttt{\&}) followed by the
462 full path to some node in the tree.  For example, in Figure
463 \ref{fig:dts}, the \texttt{/chosen} node has an
464 \texttt{interrupt-controller} property referring to the interrupt
465 controller described by the node \texttt{/mpic@0x3fffdd08400}.  In the
466 output tree, the value of the referenced node's phandle is included in
467 the property.  If that node doesn't have an explicit phandle property,
470 assign and remember phandles for the various interrupt controller
475 label ``\texttt{memreg}'' on the \texttt{reg} property of the node
477 in the output are generated, which will assemble into symbols
478 addressing the part of the blob with the node or property in question.
479 This is useful for the common case where an embedded board has an
481 the size of memory.  The bootloader for such a board can have a device
482 tree linked in, including a symbol referring to the right place in the
483 blob to update the parameter with the correct value determined at
488 Between reading in the device tree and writing it out in the new
489 format, \dtc performs a number of checks on the tree:
494   with the same name.
498   length that makes sense given the address forms specified by the
502 \item \emph{Linux requirements}:  \dtc checks that the device tree
503   contains those nodes and properties that are required by the Linux
507 These checks are useful to catch simple problems with the device tree,
508 rather than having to debug the results on an embedded kernel.  With
509 the blob input mode, it can also be used for diagnosing problems with
516 The flattened device tree has always been the only supported way to
517 boot a \texttt{ppc64} kernel on an embedded system.  With the merge of
518 \texttt{ppc32} and \texttt{ppc64} code it has also become the only
520 64-bit.  In fact, the old \texttt{ppc} architecture exists mainly just
521 to support the old ppc32 embedded ports that have not been migrated
522 to the flattened device tree approach.  We plan to remove the
523 \texttt{ppc} architecture eventually, which will mean porting all the
524 various embedded boards to use the flattened device tree.
532   number of checks on the device tree, they are rather haphazard.  In
539 \item \emph{binary include}: Occasionally, it is useful for the device
549   in part by running the source file through CPP before compiling with
557 \section*{About the authors}
559 David Gibson has been a member of the IBM Linux Technology Center,
562 as well as the device tree compiler.  In the past, he has worked on
563 bringup for various ppc and ppc64 embedded systems, the orinoco
568 ultimately saw the light and installed Linux on his Apple PowerPC
570 started contributing to the PowerPC Linux port in various areas,
571 mostly around the support for Apple machines. He became official
572 PowerMac maintainer in 2001. In 2003, he joined the IBM Linux
573 Technology Center in Canberra, Australia, where he ported the 64 bit
574 PowerPC kernel to Apple G5 machines and the Maple embedded board,
575 among others things.  He's a member of the ppc64 development ``team''
576 and one of his current goals is to make the integration of embedded
577 platforms smoother and more maintainable than in the 32-bit PowerPC
582 This work represents the view of the author and does not necessarily
583 represent the view of IBM.
587 Corporation in the United States and/or other countries.
590 Computer Inc. in the United States, other countries, or both.

Indexes created Sat May 18 11:27:04 MDT 2024