that the kernel tries to find out the default console and has      knowledge of various types like 8250 serial ports. You may want      to extend this function to add your own.  Note that u-boot creates and fills in the chosen node for platforms  that use it.  (Note: a practice that is now obsolete was to include a property  under /chosen called interrupt-controller which had a phandle value  that pointed to the main interrupt controller)  f) the /soc<SOCname> node  This node is used to represent a system-on-a-chip (SOC) and must be  present if the processor is a SOC. The top-level soc node contains  information that is global to all devices on the SOC. The node name  should contain a unit address for the SOC, which is the base address  of the memory-mapped register set for the SOC. The name of an soc  node should start with "soc", and the remainder of the name should  represent the part number for the soc.  For example, the MPC8540's  soc node would be called "soc8540".  Required properties:    - device_type : Should be "soc"    - ranges : Should be defined as specified in 1) to describe the      translation of SOC addresses for memory mapped SOC registers.    - bus-frequency: Contains the bus frequency for the SOC node.      Typically, the value of this field is filled in by the boot      loader.   Recommended properties:    - reg : This property defines the address and size of the      memory-mapped registers that are used for the SOC node itself.      It does not include the child device registers - these will be      defined inside each child node.  The address specified in the      "reg" property should match the unit address of the SOC node.    - #address-cells : Address representation for "soc" devices.  The      format of this field may vary depending on whether or not the      device registers are memory mapped.  For memory mapped      registers, this field represents the number of cells needed to      represent the address of the registers.  For SOCs that do not      use MMIO, a special address format should be defined that      contains enough cells to represent the required information.      See 1) above for more details on defining #address-cells.    - #size-cells : Size representation for "soc" devices    - #interrupt-cells : Defines the width of cells used to represent       interrupts.  Typically this value is <2>, which includes a       32-bit number that represents the interrupt number, and a       32-bit number that represents the interrupt sense and level.       This field is only needed if the SOC contains an interrupt       controller.  The SOC node may contain child nodes for each SOC device that the  platform uses.  Nodes should not be created for devices which exist  on the SOC but are not used by a particular platform. See chapter VI  for more information on how to specify devices that are part of a SOC.  Example SOC node for the MPC8540:	soc8540@e0000000 {		#address-cells = <1>;		#size-cells = <1>;		#interrupt-cells = <2>;		device_type = "soc";		ranges = <00000000 e0000000 00100000>		reg = <e0000000 00003000>;		bus-frequency = <0>;	}IV - "dtc", the device tree compiler====================================dtc source code can be found at<http://ozlabs.org/~dgibson/dtc/dtc.tar.gz>WARNING: This version is still in early development stage; theresulting device-tree "blobs" have not yet been validated with thekernel. The current generated bloc lacks a useful reserve map (it willbe fixed to generate an empty one, it's up to the bootloader to fillit up) among others. The error handling needs work, bugs are lurking,etc...dtc basically takes a device-tree in a given format and outputs adevice-tree in another format. The currently supported formats are:  Input formats:  -------------     - "dtb": "blob" format, that is a flattened device-tree block       with        header all in a binary blob.     - "dts": "source" format. This is a text file containing a       "source" for a device-tree. The format is defined later in this        chapter.     - "fs" format. This is a representation equivalent to the        output of /proc/device-tree, that is nodes are directories and	properties are files Output formats: ---------------     - "dtb": "blob" format     - "dts": "source" format     - "asm": assembly language file. This is 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.The syntax of the dtc tool is    dtc [-I <input-format>] [-O <output-format>]        [-o output-filename] [-V output_version] input_filenameThe "output_version" defines what version of the "blob" format will begenerated. Supported versions are 1,2,3 and 16. The default iscurrently version 3 but that may change in the future to version 16.Additionally, dtc performs various sanity checks on the tree, like theuniqueness of linux, phandle properties, validity of strings, etc...The format of the .dts "source" file is "C" like, supports C and C++style comments./ {}The above is the "device-tree" definition. It's the only statementsupported currently at the toplevel./ {  property1 = "string_value";	/* define a property containing a 0                                 * terminated string				 */  property2 = <1234abcd>;	/* define a property containing a                                 * numerical 32-bit value (hexadecimal)				 */  property3 = <12345678 12345678 deadbeef>;                                /* define a property containing 3                                 * numerical 32-bit values (cells) in                                 * hexadecimal				 */  property4 = [0a 0b 0c 0d de ea ad be ef];                                /* define a property whose content is                                 * an arbitrary array of bytes                                 */  childnode@addresss {	/* define a child node named "childnode"                                 * whose unit name is "childnode at				 * address"                                 */    childprop = "hello\n";      /* define a property "childprop" of                                 * childnode (in this case, a string)                                 */  };};Nodes can contain other nodes etc... thus defining the hierarchicalstructure of the tree.Strings support common escape sequences from C: "\n", "\t", "\r","\(octal value)", "\x(hex value)".It is also suggested that you pipe your source file through cpp (gccpreprocessor) so you can use #include's, #define for constants, etc...Finally, various options are planned but not yet implemented, likeautomatic generation of phandles, labels (exported to the asm file soyou can point to a property content and change it easily from whateveryou link the device-tree with), label or path instead of numeric valuein some cells to "point" to a node (replaced by a phandle at compiletime), export of reserve map address to the asm file, ability tospecify reserve map content at compile time, etc...We may provide a .h include file with common definitions of thatproves useful for some properties (like building PCI properties orinterrupt maps) though it may be better to add a notion of structdefinitions to the compiler...V - Recommendations for a bootloader====================================Here are some various ideas/recommendations that have been proposedwhile all this has been defined and implemented.  - The bootloader may want to be able to use the device-tree itself    and may want to manipulate it (to add/edit some properties,    like physical memory size or kernel arguments). At this point, 2    choices can be made. Either the bootloader works directly on the    flattened format, or the bootloader has its own internal tree    representation with pointers (similar to the kernel one) and    re-flattens the tree when booting the kernel. The former is a bit    more difficult to edit/modify, the later requires probably a bit    more code to handle the tree structure. Note that the structure    format has been designed so it's relatively easy to "insert"    properties or nodes or delete them by just memmoving things    around. It contains no internal offsets or pointers for this    purpose.  - An example of code for iterating nodes & retrieving properties    directly from the flattened tree format can be found in the kernel    file arch/ppc64/kernel/prom.c, look at scan_flat_dt() function,    its usage in early_init_devtree(), and the corresponding various    early_init_dt_scan_*() callbacks. That code can be re-used in a    GPL bootloader, and as the author of that code, I would be happy    to discuss possible free licensing to any vendor who wishes to    integrate all or part of this code into a non-GPL bootloader.VI - System-on-a-chip devices and nodes=======================================Many companies are now starting to develop system-on-a-chipprocessors, where the processor core (CPU) and many peripheral devicesexist on a single piece of silicon.  For these SOCs, an SOC nodeshould be used that defines child nodes for the devices that makeup the SOC. While platforms are not required to use this model inorder to boot the kernel, it is highly encouraged that all SOCimplementations define as complete a flat-device-tree as possible todescribe the devices on the SOC.  This will allow for thegenericization of much of the kernel code.1) Defining child nodes of an SOC---------------------------------Each device that is part of an SOC may have its own node entry insidethe SOC node.  For each device that is included in the SOC, the unitaddress property represents the address offset for this device'smemory-mapped registers in the parent's address space.  The parent'saddress space is defined by the "ranges" property in the top-level socnode. The "reg" property for each node that exists directly under theSOC node should contain the address mapping from the child address spaceto the parent SOC address space and the size of the device'smemory-mapped register file.For many devices that may exist inside an SOC, there are predefinedspecifications for the format of the device tree node.  All SOC childnodes should follow these specifications, except where noted in thisdocument.See appendix A for an example partial SOC node definition for theMPC8540.2) Representing devices without a current OF specification----------------------------------------------------------Currently, there are many devices on SOCs that do not have a standardrepresentation pre-defined as part of the open firmwarespecifications, mainly because the boards that contain these SOCs arenot currently booted using open firmware.   This section containsdescriptions for the SOC devices for which new nodes have beendefined; this list will expand as more and more SOC-containingplatforms are moved over to use the flattened-device-tree model.  a) MDIO IO device  The MDIO is a bus to which the PHY devices are connected.  For each  device that exists on this bus, a child node should be created.  See  the definition of the PHY node below for an example of how to define  a PHY.  Required properties:    - reg : Offset and length of the register set for the device    - device_type : Should be "mdio"    - compatible : Should define the compatible device type for the      mdio.  Currently, this is most likely to be "gianfar"  Example:	mdio@24520 {		reg = <24520 20>;		device_type = "mdio"; 		compatible = "gianfar";		ethernet-phy@0 {			......		};	};  b) Gianfar-compatible ethernet nodes  Required properties:    - device_type : Should be "network"    - model : Model of the device.  Can be "TSEC", "eTSEC", or "FEC"    - compatible : Should be "gianfar"    - reg : Offset and length of the register set for the device    - mac-address : List of bytes representing the ethernet address of      this controller    - interrupts : <a b> where a is the interrupt number and b is a      field that represents an encoding of the sense and level      information for the interrupt.  This should be encoded based on      the information in section 2) depending on the type of interrupt      controller you have.    - interrupt-parent : the phandle for the interrupt controller that      services interrupts for this device.    - phy-handle : The phandle for the PHY connected to this ethernet      controller.