dtc/Documentation/dtc-paper.tex

44   flattened-tree representation of the system's hardware based on the
45   device tree supplied by Open Firmware on IBM\R servers and Apple\R
48   The ``blob'' representing the device tree can be created using \dtc
50   representation of the tree into the compact representation used by
55   This flattened-tree approach is now the only supported method of
63 \subsection{OF and the device tree}
67 Among other boot-time services, OF maintains a device tree that
70 the Linux kernel uses OF calls to scan the device tree and transfer it
74 The device tree consists of nodes representing devices or
85 but nothing as detailed or complete as the OF device tree.  This has
88 device tree.  These vary from specialised boot wrappers to parse
98 around the lack of a device tree.  Even so, the lack means the iSeries
102 The device tree also presents a problem for implementing \kexec.  When
110 tree that addresses all these problems.  When booting on OF systems,
113 walks the device tree using OF calls, and transcribes it into a
114 compact, flattened format.  The resulting device tree ``blob'' is then
115 passed to the kernel proper, which eventually unflattens the tree into
121 directly from the entry point taking a flattened device tree.  The
122 device tree blob must be passed in from outside, rather than generated
124 \texttt{kexec} tools build the blob from the runtime device tree
129 \subsection{Properties of the flattened tree}
131 The flattened tree format should be easy to handle, both for the
141   make tweaks to the flattened tree, such as deleting or inserting a
143   having to effectively regenerate the whole flattened tree.  In
148   resources, particularly RAM and flash memory space.  Thus, the tree
152 \subsection{Format of the device tree blob}
199   \caption{Device tree blob layout}
206 included as part of the \dtc (see \S\ref{sec:dtc}) git tree,
210 containing the device tree.  It has three sections of variable size:
225 The structure block contains the device tree proper.  Each node is
232 the end of the whole tree\footnote{This is redundant, but included for
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.
253 In many cases a flat tree can be simpler than a typical OF provided
254 device tree.  The flattened tree need only provide those nodes and
255 properties that the kernel actually requires; the flattened tree
257 For example, an OF device tree would normally include nodes for each
258 PCI device on the system.  A flattened tree need only include nodes
260 described to find the subsidiary devices.  The device tree can include
266 describe various buses in the device tree (for example,
277 tree.  In OF, each node in the tree has an associated phandle, a
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
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
293 retrieved from OF.  When the tree is generated without OF, however,
297 Another complication arises because nodes in an OF tree have two
310 flattened tree format only requires the unit names to be present.
311 When the kernel unflattens the tree, it automatically generates a
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
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
376 flattened tree must be generated from scratch.
379 it's usually possible to build the device tree blob at compile time
382 the tree before passing it to the booted kernel.
386 so is tedious.  The ``device tree compiler'', \dtc{}\footnote{\dtc can
388 tree blobs easier by converting a text representation of the tree
393 As well as the normal mode of compiling a device tree blob from text
394 source, \dtc can convert a device tree between a number of
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
402   device tree blob.
403 \item filesystem (\texttt{fs}), input is a directory tree in the
404   layout of \texttt{/proc/device-tree} (roughly, a directory for each
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
420   device tree blob, with symbols giving the beginning of the blob and
429 necessary adjustments to the tree that are necessary for the specified
439 tree in a vaguely C-like form.  Figure \ref{fig:dts} shows an
442 then the device tree proper is described.
444 Nodes of the tree are introduced with the node name, followed by a
462 full path to some node in the tree.  For example, in Figure
466 output tree, the value of the referenced node's phandle is included in
480 essentially fixed device tree with a few variable properties, such as
482 tree linked in, including a symbol referring to the right place in the
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:
502 \item \emph{Linux requirements}:  \dtc checks that the device tree
507 These checks are useful to catch simple problems with the device tree,
516 The flattened device tree has always been the only supported way to
522 to the flattened device tree approach.  We plan to remove the
524 various embedded boards to use the flattened device tree.
531 \item \emph{better tree checking}: Although \dtc already performs a
532   number of checks on the device tree, they are rather haphazard.  In
535   \texttt{-f} parameter that forces \dtc to generate an output tree
540   tree to incorporate as a property a block of binary data for some
546   sort of macros so that a tree containing a number of similar devices
562 as well as the device tree compiler.  In the past, he has worked on