Add qemu 2.4.0

Change-Id: Ic99cbad4b61f8b127b7dc74d04576c0bcbaaf4f5
Signed-off-by: Yang Zhang <yang.z.zhang@intel.com>

4 files changed, 1422 insertions, 0 deletions

diff --git a/qemu/dtc/Documentation/dtc-paper.bib b/qemu/dtc/Documentation/dtc-paper.bib
new file mode 100644
index 000000000..d01e2ff9e
--- /dev/null
+++ b/qemu/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/qemu/dtc/Documentation/dtc-paper.tex b/qemu/dtc/Documentation/dtc-paper.tex
new file mode 100644
index 000000000..4494226d8
--- /dev/null
+++ b/qemu/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/qemu/dtc/Documentation/dts-format.txt b/qemu/dtc/Documentation/dts-format.txt
new file mode 100644
index 000000000..41741dffc
--- /dev/null
+++ b/qemu/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/qemu/dtc/Documentation/manual.txt b/qemu/dtc/Documentation/manual.txt
new file mode 100644
index 000000000..65c8540be
--- /dev/null
+++ b/qemu/dtc/Documentation/manual.txt
@@ -0,0 +1,660 @@
+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 jdl.com.
+The gitweb interface is:
+
+    http://git.jdl.com/gitweb/
+
+The repository is here:
+
+    git://www.jdl.com/software/dtc.git
+    http://www.jdl.com/software/dtc.git
+
+Tarballs of the 1.0.0 and latest releases are here:
+
+    http://www.jdl.com/software/dtc-v1.2.0.tgz
+    http://www.jdl.com/software/dtc-latest.tgz
+
+1.1) Submitting Patches
+
+Patches should be sent to jdl@jdl.com, and CC'ed to
+devicetree-discuss@lists.ozlabs.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.
+
+
+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.
+
+    -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:   list_of_memreserve devicetree
+
+    memreserve:   label 'memreserve' ADDR ADDR ';'
+		| label 'memreserve' ADDR '-' ADDR ';'
+
+    devicetree:   '/' nodedef
+
+    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 it turn has a string property
+      called "childprop".
+
+	childnode@addresss {
+	    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 exmaple, a node is labled "mpic" and then referenced:
+
+    mpic:  interrupt-controller@40000 {
+	...
+    };
+
+    ethernet-phy@3 {
+	interrupt-parent = <&mpic>;
+	...
+    };
+
+And used in properties, lables 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 informations 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 informations 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 <DTB-file-name>