path: root/Documentation/devicetree/booting-without-of.txt

           Booting the Linux/ppc kernel without Open Firmware
           --------------------------------------------------

(c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>,
    IBM Corp.
(c) 2005 Becky Bruce <becky.bruce at freescale.com>,
    Freescale Semiconductor, FSL SOC and 32-bit additions
(c) 2006 MontaVista Software, Inc.
    Flash chip node definition

Table of Contents
=================

  I - Introduction
    1) Entry point for arch/powerpc

  II - The DT block format
    1) Header
    2) Device tree generalities
    3) Device tree "structure" block
    4) Device tree "strings" block

  III - Required content of the device tree
    1) Note about cells and address representation
    2) Note about "compatible" properties
    3) Note about "name" properties
    4) Note about node and property names and character set
    5) Required nodes and properties
      a) The root node
      b) The /cpus node
      c) The /cpus/* nodes
      d) the /memory node(s)
      e) The /chosen node
      f) the /soc<SOCname> node

  IV - "dtc", the device tree compiler

  V - Recommendations for a bootloader

  VI - System-on-a-chip devices and nodes
    1) Defining child nodes of an SOC
    2) Representing devices without a current OF specification

  VII - Specifying interrupt information for devices
    1) interrupts property
    2) interrupt-parent property
    3) OpenPIC Interrupt Controllers
    4) ISA Interrupt Controllers

  VIII - Specifying device power management information (sleep property)

  Appendix A - Sample SOC node for MPC8540


Revision Information
====================

   May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet.

   May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or
                           clarifies the fact that a lot of things are
                           optional, the kernel only requires a very
                           small device tree, though it is encouraged
                           to provide an as complete one as possible.

   May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM
			 - Misc fixes
			 - Define version 3 and new format version 16
			   for the DT block (version 16 needs kernel
			   patches, will be fwd separately).
			   String block now has a size, and full path
			   is replaced by unit name for more
			   compactness.
			   linux,phandle is made optional, only nodes
			   that are referenced by other nodes need it.
			   "name" property is now automatically
			   deduced from the unit name

   June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and
                           OF_DT_END_NODE in structure definition.
                         - Change version 16 format to always align
                           property data to 4 bytes. Since tokens are
                           already aligned, that means no specific
                           required alignment between property size
                           and property data. The old style variable
                           alignment would make it impossible to do
                           "simple" insertion of properties using
                           memmove (thanks Milton for
                           noticing). Updated kernel patch as well
			 - Correct a few more alignment constraints
			 - Add a chapter about the device-tree
                           compiler and the textural representation of
                           the tree that can be "compiled" by dtc.

   November 21, 2005: Rev 0.5
			 - Additions/generalizations for 32-bit
			 - Changed to reflect the new arch/powerpc
			   structure
			 - Added chapter VI


 ToDo:
	- Add some definitions of interrupt tree (simple/complex)
	- Add some definitions for PCI host bridges
	- Add some common address format examples
	- Add definitions for standard properties and "compatible"
	  names for cells that are not already defined by the existing
	  OF spec.
	- Compare FSL SOC use of PCI to standard and make sure no new
	  node definition required.
	- Add more information about node definitions for SOC devices
  	  that currently have no standard, like the FSL CPM.


I - Introduction
================

During the development of the Linux/ppc64 kernel, and more
specifically, the addition of new platform types outside of the old
IBM pSeries/iSeries pair, it was decided to enforce some strict rules
regarding the kernel entry and bootloader <-> kernel interfaces, in
order to avoid the degeneration that had become the ppc32 kernel entry
point and the way a new platform should be added to the kernel. The
legacy iSeries platform breaks those rules as it predates this scheme,
but no new board support will be accepted in the main tree that
doesn't follow them properly.  In addition, since the advent of the
arch/powerpc merged architecture for ppc32 and ppc64, new 32-bit
platforms and 32-bit platforms which move into arch/powerpc will be
required to use these rules as well.

The main requirement that will be defined in more detail below is
the presence of a device-tree whose format is defined after Open
Firmware specification. However, in order to make life easier
to embedded board vendors, the kernel doesn't require the device-tree
to represent every device in the system and only requires some nodes
and properties to be present. This will be described in detail in
section III, but, for example, the kernel does not require you to
create a node for every PCI device in the system. It is a requirement
to have a node for PCI host bridges in order to provide interrupt
routing informations and memory/IO ranges, among others. It is also
recommended to define nodes for on chip devices and other buses that
don't specifically fit in an existing OF specification. This creates a
great flexibility in the way the kernel can then probe those and match
drivers to device, without having to hard code all sorts of tables. It
also makes it more flexible for board vendors to do minor hardware
upgrades without significantly impacting the kernel code or cluttering
it with special cases.


1) Entry point for arch/powerpc
-------------------------------

   There is one single entry point to the kernel, at the start
   of the kernel image. That entry point supports two calling
   conventions:

        a) Boot from Open Firmware. If your firmware is compatible
        with Open Firmware (IEEE 1275) or provides an OF compatible
        client interface API (support for "interpret" callback of
        forth words isn't required), you can enter the kernel with:

              r5 : OF callback pointer as defined by IEEE 1275
              bindings to powerpc. Only the 32-bit client interface
              is currently supported

              r3, r4 : address & length of an initrd if any or 0

              The MMU is either on or off; the kernel will run the
              trampoline located in arch/powerpc/kernel/prom_init.c to
              extract the device-tree and other information from open
              firmware and build a flattened device-tree as described
              in b). prom_init() will then re-enter the kernel using
              the second method. This trampoline code runs in the
              context of the firmware, which is supposed to handle all
              exceptions during that time.

        b) Direct entry with a flattened device-tree block. This entry
        point is called by a) after the OF trampoline and can also be
        called directly by a bootloader that does not support the Open
        Firmware client interface. It is also used by "kexec" to
        implement "hot" booting of a new kernel from a previous
        running one. This method is what I will describe in more
        details in this document, as method a) is simply standard Open
        Firmware, and thus should be implemented according to the
        various standard documents defining it and its binding to the
        PowerPC platform. The entry point definition then becomes:

                r3 : physical pointer to the device-tree block
                (defined in chapter II) in RAM

                r4 : physical pointer to the kernel itself. This is
                used by the assembly code to properly disable the MMU
                in case you are entering the kernel with MMU enabled