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 definitionTable of Contents=================  I - Introduction    1) Entry point for arch/powerpc    2) Board support  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      a) MDIO IO device      b) Gianfar-compatible ethernet nodes      c) PHY nodes      d) Interrupt controllers      e) I2C      f) Freescale SOC USB controllers      g) Freescale SOC SEC Security Engines      h) Board Control and Status (BCSR)      i) Freescale QUICC Engine module (QE)      j) CFI or JEDEC memory-mapped NOR flash      k) Global Utilities Block      l) Xilinx IP cores  VII - Specifying interrupt information for devices    1) interrupts property    2) interrupt-parent property    3) OpenPIC Interrupt Controllers    4) ISA Interrupt Controllers  Appendix A - Sample SOC node for MPC8540Revision 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 recent development of the Linux/ppc64 kernel, and morespecifically, the addition of new platform types outside of the oldIBM pSeries/iSeries pair, it was decided to enforce some strict rulesregarding the kernel entry and bootloader <-> kernel interfaces, inorder to avoid the degeneration that had become the ppc32 kernel entrypoint and the way a new platform should be added to the kernel. Thelegacy iSeries platform breaks those rules as it predates this scheme,but no new board support will be accepted in the main tree thatdoesn't follows them properly.  In addition, since the advent of thearch/powerpc merged architecture for ppc32 and ppc64, new 32-bitplatforms and 32-bit platforms which move into arch/powerpc will berequired to use these rules as well.The main requirement that will be defined in more detail below isthe presence of a device-tree whose format is defined after OpenFirmware specification. However, in order to make life easierto embedded board vendors, the kernel doesn't require the device-treeto represent every device in the system and only requires some nodesand properties to be present. This will be described in detail insection III, but, for example, the kernel does not require you tocreate a node for every PCI device in the system. It is a requirementto have a node for PCI host bridges in order to provide interruptrouting informations and memory/IO ranges, among others. It is alsorecommended to define nodes for on chip devices and other busses thatdon't specifically fit in an existing OF specification. This creates agreat flexibility in the way the kernel can then probe those and matchdrivers to device, without having to hard code all sorts of tables. Italso makes it more flexible for board vendors to do minor hardwareupgrades without significantly impacting the kernel code or clutteringit with special cases.1) Entry point for arch/powerpc-------------------------------   There is one and 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                and a non-1:1 mapping.                r5 : NULL (as to differentiate with method a)        Note about SMP entry: Either your firmware puts your other        CPUs in some sleep loop or spin loop in ROM where you can get        them out via a soft reset or some other means, in which case        you don't need to care, or you'll have to enter the kernel        with all CPUs. The way to do that with method b) will be        described in a later revision of this document.2) Board support----------------64-bit kernels:   Board supports (platforms) are not exclusive config options. An   arbitrary set of board supports can be built in a single kernel   image. The kernel will "know" what set of functions to use for a   given platform based on the content of the device-tree. Thus, you   should:        a) add your platform support as a _boolean_ option in        arch/powerpc/Kconfig, following the example of PPC_PSERIES,        PPC_PMAC and PPC_MAPLE. The later is probably a good        example of a board support to start from.        b) create your main platform file as        "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it        to the Makefile under the condition of your CONFIG_        option. This file will define a structure of type "ppc_md"        containing the various callbacks that the generic code will        use to get to your platform specific code        c) Add a reference to your "ppc_md" structure in the        "machines" table in arch/powerpc/kernel/setup_64.c if you are        a 64-bit platform.        d) request and get assigned a platform number (see PLATFORM_*        constants in include/asm-powerpc/processor.h32-bit embedded kernels:  Currently, board support is essentially an exclusive config option.  The kernel is configured for a single platform.  Part of the reason  for this is to keep kernels on embedded systems small and efficient;  part of this is due to the fact the code is already that way. In the  future, a kernel may support multiple platforms, but only if the  platforms feature the same core architecture.  A single kernel build  cannot support both configurations with Book E and configurations  with classic Powerpc architectures.  32-bit embedded platforms that are moved into arch/powerpc using a  flattened device tree should adopt the merged tree practice of  setting ppc_md up dynamically, even though the kernel is currently  built with support for only a single platform at a time.  This allows  unification of the setup code, and will make it easier to go to a  multiple-platform-support model in the future.NOTE: I believe the above will be true once Ben's done with the mergeof the boot sequences.... someone speak up if this is wrong!  To add a 32-bit embedded platform support, follow the instructions  for 64-bit platforms above, with the exception that the Kconfig  option should be set up such that the kernel builds exclusively for  the platform selected.  The processor type for the platform should  enable another config option to select the specific board  supported.NOTE: If Ben doesn't merge the setup files, may need to change this topoint to setup_32.c   I will describe later the boot process and various callbacks that   your platform should implement.II - The DT block format========================This chapter defines the actual format of the flattened device-treepassed to the kernel. The actual content of it and kernel requirementsare described later. You can find example of code manipulating thatformat in various places, including arch/powerpc/kernel/prom_init.cwhich will generate a flattened device-tree from the Open Firmwarerepresentation, or the fs2dt utility which is part of the kexec toolswhich will generate one from a filesystem representation. It isexpected that a bootloader like uboot provides a bit more support,that will be discussed later as well.Note: The block has to be in main memory. It has to be accessible inboth real mode and virtual mode with no mapping other than mainmemory. If you are writing a simple flash bootloader, it should copythe 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 */