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
+ 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
+ c) PHY nodes
+ b) Gianfar-compatible ethernet 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)
+ g) Flash chip nodes
+
+ 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 MPC8540
+
+
+Revision Information
+====================
May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet.
- Change version 16 format to always align
property data to 4 bytes. Since tokens are
already aligned, that means no specific
- required alignement between property size
+ required alignment between property size
and property data. The old style variable
alignment would make it impossible to do
"simple" insertion of properties using
- memove (thanks Milton for
+ memmove (thanks Milton for
noticing). Updated kernel patch as well
- - Correct a few more alignement constraints
+ - 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.
ToDo:
- Add some definitions of interrupt tree (simple/complex)
- - Add some definitions for pci host bridges
+ - 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
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
+ bindings to powerpc. Only the 32-bit client interface
is currently supported
r3, r4 : address & length of an initrd if any or 0
in case you are entering the kernel with MMU enabled
and a non-1:1 mapping.
- r5 : NULL (as to differenciate with method a)
+ 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
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 architectire. A single kernel build
+ platforms feature the same core architecture. A single kernel build
cannot support both configurations with Book E and configurations
with classic Powerpc architectures.
enable another config option to select the specific board
supported.
-NOTE: If ben doesn't merge the setup files, may need to change this to
+NOTE: If Ben doesn't merge the setup files, may need to change this to
point to setup_32.c
---------
The kernel is entered with r3 pointing to an area of memory that is
- roughtly described in include/asm-powerpc/prom.h by the structure
+ roughly described in include/asm-powerpc/prom.h by the structure
boot_param_header:
struct boot_param_header {
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 */
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:
#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 */
- 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
+ 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
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.
+ should be 64-bit aligned.
- version
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. You should always generate a structure of the highest
- version defined at the time of your implementation. Currently
- that is version 16, unless you explicitely aim at being backward
- compatible.
+ 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
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 0x10 if you generate a tree of version 0x10
+ 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
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
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 0x10 makes it
+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 differenciate nodes with
+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
-name's, the "@" sign, and a "unit address", which definition is
+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
interrupt tree which will be described in a further version of this
document.
-This "linux, phandle" property is a 32 bit value that uniquely
+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
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
+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
| |- device_type = "cpu"
| |- reg = <0>
| |- clock-frequency = <5f5e1000>
- | |- linux,boot-cpu
+ | |- 64-bit
| |- linux,phandle = <2>
|
o memory@0
o chosen
|- name = "chosen"
|- bootargs = "root=/dev/sda2"
- |- linux,platform = <00000600>
|- linux,phandle = <4>
This tree is almost a minimal tree. It pretty much contains the
through /chosen, like in this example, the platform type (mandatory)
and the kernel command line arguments (optional).
-The /cpus/PowerPC,970@0/linux,boot-cpu property is an example of a
+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
* [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 of no
- * value)
- * 32 bit value of offset in string block of property name
+ * 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 summmarised as a start token, a full path,
-a list of properties, a list of child node and an end token. Every
+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.
-4) Device tree 'strings" block
+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
the Open Firmware client interface, those properties will be created
by the trampoline code in the kernel's prom_init() file. For example,
that's where you'll have to add code to detect your board model and
-set the platform number. However, when using the flatenned device-tree
+set the platform number. However, when using the flattened device-tree
entry point, there is no prom_init() pass, and thus you have to
provide those properties yourself.
----------------------------------------------
The general rule is documented in the various Open Firmware
-documentations. If you chose to describe a bus with the device-tree
+documentations. If you choose to describe a bus with the device-tree
and there exist an OF bus binding, then you should follow the
specification. However, the kernel does not require every single
device or bus to be described by the device tree.
on the processor bus.
Those 2 properties define 'cells' for representing an address and a
-size. A "cell" is a 32 bit number. For example, if both contain 2
+size. A "cell" is a 32-bit number. For example, if both contain 2
like the example tree given above, then an address and a size are both
-composed of 2 cells, and each is a 64 bit number (cells are
+composed of 2 cells, and each is a 64-bit number (cells are
concatenated and expected to be in big endian format). Another example
is the way Apple firmware defines them, with 2 cells for an address
and one cell for a size. Most 32-bit implementations should define
prom_parse.c file of the recent kernels for your bus type.
The "reg" property only defines addresses and sizes (if #size-cells
-is
-non-0) within a given bus. In order to translate addresses upward
-(that is into parent bus addresses, and possibly into cpu physical
+is non-0) within a given bus. In order to translate addresses upward
+(that is into parent bus addresses, and possibly into CPU physical
addresses), all busses must contain a "ranges" property. If the
"ranges" property is missing at a given level, it's assumed that
-translation isn't possible. The format of the "ranges" proprety for a
+translation isn't possible. The format of the "ranges" property for a
bus is a list of:
bus address, parent bus address, size
PCI<->ISA bridge, that would be a PCI address. It defines the base
address in the parent bus where the beginning of that range is mapped.
-For a new 64 bit powerpc board, I recommend either the 2/2 format or
+For a new 64-bit powerpc board, I recommend either the 2/2 format or
Apple's 2/1 format which is slightly more compact since sizes usually
-fit in a single 32 bit word. New 32 bit powerpc boards should use a
+fit in a single 32-bit word. New 32-bit powerpc boards should use a
1/1 format, unless the processor supports physical addresses greater
than 32-bits, in which case a 2/1 format is recommended.
4) Note about node and property names and character set
-------------------------------------------------------
-While open firmware provides more flexibe usage of 8859-1, this
+While open firmware provides more flexible usage of 8859-1, this
specification enforces more strict rules. Nodes and properties should
be comprised only of ASCII characters 'a' to 'z', '0' to
'9', ',', '.', '_', '+', '#', '?', and '-'. Node names additionally
that typically get driven by the same platform code in the
kernel, you would use a different "model" property but put a
value in "compatible". The kernel doesn't directly use that
- value (see /chosen/linux,platform for how the kernel choses a
- platform type) but it is generally useful.
+ value but it is generally useful.
The root node is also generally where you add additional properties
specific to your board like the serial number if any, that sort of
- thing. it is recommended that if you add any "custom" property whose
+ thing. It is recommended that if you add any "custom" property whose
name may clash with standard defined ones, you prefix them with your
vendor name and a comma.
Required properties:
- device_type : has to be "cpu"
- - reg : This is the physical cpu number, it's a single 32 bit cell
+ - reg : This is the physical CPU number, it's a single 32-bit cell
and is also used as-is as the unit number for constructing the
unit name in the full path. For example, with 2 CPUs, you would
have the full path:
bytes
- d-cache-size : one cell, size of L1 data cache in bytes
- i-cache-size : one cell, size of L1 instruction cache in bytes
- - linux, boot-cpu : Should be defined if this cpu is the boot cpu.
Recommended properties:
the kernel timebase/decrementer calibration based on this
value.
- clock-frequency : a cell indicating the CPU core clock frequency
- in Hz. A new property will be defined for 64 bit values, but if
+ in Hz. A new property will be defined for 64-bit values, but if
your frequency is < 4Ghz, one cell is enough. Here as well as
for the above, the common code doesn't use that property, but
you are welcome to re-use the pSeries or Maple one. A future
your board. It's a list of addresses/sizes concatenated
together, with the number of cells of each defined by the
#address-cells and #size-cells of the root node. For example,
- with both of these properties beeing 2 like in the example given
+ with both of these properties being 2 like in the example given
earlier, a 970 based machine with 6Gb of RAM could typically
have a "reg" property here that looks like:
This node is a bit "special". Normally, that's where open firmware
puts some variable environment information, like the arguments, or
- phandle pointers to nodes like the main interrupt controller, or the
- default input/output devices.
+ the default input/output devices.
This specification makes a few of these mandatory, but also defines
some linux-specific properties that would be normally constructed by
the prom_init() trampoline when booting with an OF client interface,
but that you have to provide yourself when using the flattened format.
- Required properties:
-
- - linux,platform : This is your platform number as assigned by the
- architecture maintainers
-
Recommended properties:
- bootargs : This zero-terminated string is passed as the kernel
console device if any. Typically, if you have serial devices on
your board, you may want to put the full path to the one set as
the default console in the firmware here, for the kernel to pick
- it up as it's own default console. If you look at the funciton
+ it up as its own default console. If you look at the function
set_preferred_console() in arch/ppc64/kernel/setup.c, you'll see
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.
- - interrupt-controller : This is one cell containing a phandle
- value that matches the "linux,phandle" property of your main
- interrupt controller node. May be used for interrupt routing.
-
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
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 an
-SOC.
+ for more information on how to specify devices that are part of a SOC.
Example SOC node for the MPC8540:
- "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 use
+ assembly file exports some symbols that can be used.
The syntax of the dtc tool is
[-o output-filename] [-V output_version] input_filename
-The "output_version" defines what versio of the "blob" format will be
+The "output_version" defines what version of the "blob" format will be
generated. Supported versions are 1,2,3 and 16. The default is
currently version 3 but that may change in the future to version 16.
Additionally, dtc performs various sanity checks on the tree, like the
-uniqueness of linux,phandle properties, validity of strings, etc...
+uniqueness of linux, phandle properties, validity of strings, etc...
The format of the .dts "source" file is "C" like, supports C and C++
-style commments.
+style comments.
/ {
}
*/
property2 = <1234abcd>; /* define a property containing a
- * numerical 32 bits value (hexadecimal)
+ * numerical 32-bit value (hexadecimal)
*/
property3 = <12345678 12345678 deadbeef>;
/* define a property containing 3
- * numerical 32 bits values (cells) in
+ * numerical 32-bit values (cells) in
* hexadecimal
*/
property4 = [0a 0b 0c 0d de ea ad be ef];
around. It contains no internal offsets or pointers for this
purpose.
- - An example of code for iterating nodes & retreiving properties
+ - 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,
- it's usage in early_init_devtree(), and the corresponding various
+ 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
- do discuss possible free licencing to any vendor who wishes to
+ to discuss possible free licensing to any vendor who wishes to
integrate all or part of this code into a non-GPL bootloader.
=======================================
Many companies are now starting to develop system-on-a-chip
-processors, where the processor core (cpu) and many peripheral devices
+processors, where the processor core (CPU) and many peripheral devices
exist on a single piece of silicon. For these SOCs, an SOC node
should be used that defines child nodes for the devices that make
up the SOC. While platforms are not required to use this model in
MPC8540.
-2) Specifying interrupt information for SOC devices
----------------------------------------------------
-
-Each device that is part of an SOC and which generates interrupts
-should have the following properties:
-
- - interrupt-parent : contains the phandle of the interrupt
- controller which handles interrupts for this device
- - interrupts : a list of tuples representing the interrupt
- number and the interrupt sense and level for each interupt
- for this device.
-
-This information is used by the kernel to build the interrupt table
-for the interrupt controllers in the system.
-
-Sense and level information should be encoded as follows:
-
- Devices connected to openPIC-compatible controllers should encode
- sense and polarity as follows:
-
- 0 = high to low edge sensitive type enabled
- 1 = active low level sensitive type enabled
- 2 = low to high edge sensitive type enabled
- 3 = active high level sensitive type enabled
-
- ISA PIC interrupt controllers should adhere to the ISA PIC
- encodings listed below:
-
- 0 = active low level sensitive type enabled
- 1 = active high level sensitive type enabled
- 2 = high to low edge sensitive type enabled
- 3 = low to high edge sensitive type enabled
-
-
-
-3) Representing devices without a current OF specification
+2) Representing devices without a current OF specification
----------------------------------------------------------
Currently, there are many devices on SOCs that do not have a standard
- phy-handle : The phandle for the PHY connected to this ethernet
controller.
+ Recommended properties:
+
+ - linux,network-index : This is the intended "index" of this
+ network device. This is used by the bootwrapper to interpret
+ MAC addresses passed by the firmware when no information other
+ than indices is available to associate an address with a device.
+
Example:
ethernet@24000 {
and additions :
Required properties :
- - compatible : Should be "fsl-usb2-mph" for multi port host usb
- controllers, or "fsl-usb2-dr" for dual role usb controllers
- - phy_type : For multi port host usb controllers, should be one of
- "ulpi", or "serial". For dual role usb controllers, should be
+ - compatible : Should be "fsl-usb2-mph" for multi port host USB
+ controllers, or "fsl-usb2-dr" for dual role USB controllers
+ - phy_type : For multi port host USB controllers, should be one of
+ "ulpi", or "serial". For dual role USB controllers, should be
one of "ulpi", "utmi", "utmi_wide", or "serial".
- reg : Offset and length of the register set for the device
- port0 : boolean; if defined, indicates port0 is connected for
fsl-usb2-mph compatible controllers. Either this property or
"port0" (or both) must be defined for "fsl-usb2-mph" compatible
controllers.
+ - dr_mode : indicates the working mode for "fsl-usb2-dr" compatible
+ controllers. Can be "host", "peripheral", or "otg". Default to
+ "host" if not defined for backward compatibility.
Recommended properties :
- interrupts : <a b> where a is the interrupt number and b is a
- interrupt-parent : the phandle for the interrupt controller that
services interrupts for this device.
- Example multi port host usb controller device node :
+ Example multi port host USB controller device node :
usb@22000 {
device_type = "usb";
compatible = "fsl-usb2-mph";
port1;
};
- Example dual role usb controller device node :
+ Example dual role USB controller device node :
usb@23000 {
device_type = "usb";
compatible = "fsl-usb2-dr";
#size-cells = <0>;
interrupt-parent = <700>;
interrupts = <26 1>;
+ dr_mode = "otg";
phy = "ulpi";
};
- channel-fifo-len : An integer representing the number of
descriptor pointers each channel fetch fifo can hold.
- exec-units-mask : The bitmask representing what execution units
- (EUs) are available. It's a single 32 bit cell. EU information
+ (EUs) are available. It's a single 32-bit cell. EU information
should be encoded following the SEC's Descriptor Header Dword
EU_SEL0 field documentation, i.e. as follows:
bits 8 through 31 are reserved for future SEC EUs.
- descriptor-types-mask : The bitmask representing what descriptors
- are available. It's a single 32 bit cell. Descriptor type
+ are available. It's a single 32-bit cell. Descriptor type
information should be encoded following the SEC's Descriptor
Header Dword DESC_TYPE field documentation, i.e. as follows:
descriptor-types-mask = <012b0ebf>;
};
+ h) Board Control and Status (BCSR)
+
+ Required properties:
+
+ - device_type : Should be "board-control"
+ - reg : Offset and length of the register set for the device
+
+ Example:
+
+ bcsr@f8000000 {
+ device_type = "board-control";
+ reg = <f8000000 8000>;
+ };
+
+ i) Freescale QUICC Engine module (QE)
+ This represents qe module that is installed on PowerQUICC II Pro.
+ Hopefully it will merge backward compatibility with CPM/CPM2.
+ Basically, it is a bus of devices, that could act more or less
+ as a complete entity (UCC, USB etc ). All of them should be siblings on
+ the "root" qe node, using the common properties from there.
+ The description below applies to the qe of MPC8360 and
+ more nodes and properties would be extended in the future.
+
+ i) Root QE device
+
+ Required properties:
+ - device_type : should be "qe";
+ - model : precise model of the QE, Can be "QE", "CPM", or "CPM2"
+ - reg : offset and length of the device registers.
+ - bus-frequency : the clock frequency for QUICC Engine.
+
+ Recommended properties
+ - brg-frequency : the internal clock source frequency for baud-rate
+ generators in Hz.
+
+ Example:
+ qe@e0100000 {
+ #address-cells = <1>;
+ #size-cells = <1>;
+ #interrupt-cells = <2>;
+ device_type = "qe";
+ model = "QE";
+ ranges = <0 e0100000 00100000>;
+ reg = <e0100000 480>;
+ brg-frequency = <0>;
+ bus-frequency = <179A7B00>;
+ }
+
+
+ ii) SPI (Serial Peripheral Interface)
+
+ Required properties:
+ - device_type : should be "spi".
+ - compatible : should be "fsl_spi".
+ - mode : the SPI operation mode, it can be "cpu" or "qe".
+ - reg : Offset and length of the register set for the device
+ - 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.
+
+ Example:
+ spi@4c0 {
+ device_type = "spi";
+ compatible = "fsl_spi";
+ reg = <4c0 40>;
+ interrupts = <82 0>;
+ interrupt-parent = <700>;
+ mode = "cpu";
+ };
+
+
+ iii) USB (Universal Serial Bus Controller)
+
+ Required properties:
+ - device_type : should be "usb".
+ - compatible : could be "qe_udc" or "fhci-hcd".
+ - mode : the could be "host" or "slave".
+ - reg : Offset and length of the register set for the device
+ - 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.
+
+ Example(slave):
+ usb@6c0 {
+ device_type = "usb";
+ compatible = "qe_udc";
+ reg = <6c0 40>;
+ interrupts = <8b 0>;
+ interrupt-parent = <700>;
+ mode = "slave";
+ };
+
+
+ iv) UCC (Unified Communications Controllers)
+
+ Required properties:
+ - device_type : should be "network", "hldc", "uart", "transparent"
+ "bisync" or "atm".
+ - compatible : could be "ucc_geth" or "fsl_atm" and so on.
+ - model : should be "UCC".
+ - device-id : the ucc number(1-8), corresponding to UCCx in UM.
+ - reg : Offset and length of the register set for the device
+ - 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.
+ - pio-handle : The phandle for the Parallel I/O port configuration.
+ - rx-clock : represents the UCC receive clock source.
+ 0x00 : clock source is disabled;
+ 0x1~0x10 : clock source is BRG1~BRG16 respectively;
+ 0x11~0x28: clock source is QE_CLK1~QE_CLK24 respectively.
+ - tx-clock: represents the UCC transmit clock source;
+ 0x00 : clock source is disabled;
+ 0x1~0x10 : clock source is BRG1~BRG16 respectively;
+ 0x11~0x28: clock source is QE_CLK1~QE_CLK24 respectively.
+
+ Required properties for network device_type:
+ - mac-address : list of bytes representing the ethernet address.
+ - phy-handle : The phandle for the PHY connected to this controller.
+
+ Recommended properties:
+ - linux,network-index : This is the intended "index" of this
+ network device. This is used by the bootwrapper to interpret
+ MAC addresses passed by the firmware when no information other
+ than indices is available to associate an address with a device.
+ - phy-connection-type : a string naming the controller/PHY interface type,
+ i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id", "tbi",
+ or "rtbi".
+
+ Example:
+ ucc@2000 {
+ device_type = "network";
+ compatible = "ucc_geth";
+ model = "UCC";
+ device-id = <1>;
+ reg = <2000 200>;
+ interrupts = <a0 0>;
+ interrupt-parent = <700>;
+ mac-address = [ 00 04 9f 00 23 23 ];
+ rx-clock = "none";
+ tx-clock = "clk9";
+ phy-handle = <212000>;
+ phy-connection-type = "gmii";
+ pio-handle = <140001>;
+ };
+
+
+ v) Parallel I/O Ports
+
+ This node configures Parallel I/O ports for CPUs with QE support.
+ The node should reside in the "soc" node of the tree. For each
+ device that using parallel I/O ports, a child node should be created.
+ See the definition of the Pin configuration nodes below for more
+ information.
+
+ Required properties:
+ - device_type : should be "par_io".
+ - reg : offset to the register set and its length.
+ - num-ports : number of Parallel I/O ports
+
+ Example:
+ par_io@1400 {
+ reg = <1400 100>;
+ #address-cells = <1>;
+ #size-cells = <0>;
+ device_type = "par_io";
+ num-ports = <7>;
+ ucc_pin@01 {
+ ......
+ };
+
+
+ vi) Pin configuration nodes
+
+ Required properties:
+ - linux,phandle : phandle of this node; likely referenced by a QE
+ device.
+ - pio-map : array of pin configurations. Each pin is defined by 6
+ integers. The six numbers are respectively: port, pin, dir,
+ open_drain, assignment, has_irq.
+ - port : port number of the pin; 0-6 represent port A-G in UM.
+ - pin : pin number in the port.
+ - dir : direction of the pin, should encode as follows:
+
+ 0 = The pin is disabled
+ 1 = The pin is an output
+ 2 = The pin is an input
+ 3 = The pin is I/O
+
+ - open_drain : indicates the pin is normal or wired-OR:
+
+ 0 = The pin is actively driven as an output
+ 1 = The pin is an open-drain driver. As an output, the pin is
+ driven active-low, otherwise it is three-stated.
+
+ - assignment : function number of the pin according to the Pin Assignment
+ tables in User Manual. Each pin can have up to 4 possible functions in
+ QE and two options for CPM.
+ - has_irq : indicates if the pin is used as source of external
+ interrupts.
+
+ Example:
+ ucc_pin@01 {
+ linux,phandle = <140001>;
+ pio-map = <
+ /* port pin dir open_drain assignment has_irq */
+ 0 3 1 0 1 0 /* TxD0 */
+ 0 4 1 0 1 0 /* TxD1 */
+ 0 5 1 0 1 0 /* TxD2 */
+ 0 6 1 0 1 0 /* TxD3 */
+ 1 6 1 0 3 0 /* TxD4 */
+ 1 7 1 0 1 0 /* TxD5 */
+ 1 9 1 0 2 0 /* TxD6 */
+ 1 a 1 0 2 0 /* TxD7 */
+ 0 9 2 0 1 0 /* RxD0 */
+ 0 a 2 0 1 0 /* RxD1 */
+ 0 b 2 0 1 0 /* RxD2 */
+ 0 c 2 0 1 0 /* RxD3 */
+ 0 d 2 0 1 0 /* RxD4 */
+ 1 1 2 0 2 0 /* RxD5 */
+ 1 0 2 0 2 0 /* RxD6 */
+ 1 4 2 0 2 0 /* RxD7 */
+ 0 7 1 0 1 0 /* TX_EN */
+ 0 8 1 0 1 0 /* TX_ER */
+ 0 f 2 0 1 0 /* RX_DV */
+ 0 10 2 0 1 0 /* RX_ER */
+ 0 0 2 0 1 0 /* RX_CLK */
+ 2 9 1 0 3 0 /* GTX_CLK - CLK10 */
+ 2 8 2 0 1 0>; /* GTX125 - CLK9 */
+ };
+
+ vii) Multi-User RAM (MURAM)
+
+ Required properties:
+ - device_type : should be "muram".
+ - mode : the could be "host" or "slave".
+ - ranges : Should be defined as specified in 1) to describe the
+ translation of MURAM addresses.
+ - data-only : sub-node which defines the address area under MURAM
+ bus that can be allocated as data/parameter
+
+ Example:
+
+ muram@10000 {
+ device_type = "muram";
+ ranges = <0 00010000 0000c000>;
+
+ data-only@0{
+ reg = <0 c000>;
+ };
+ };
+
+ j) Flash chip nodes
+
+ Flash chips (Memory Technology Devices) are often used for solid state
+ file systems on embedded devices.
+
+ Required properties:
+
+ - device_type : has to be "rom"
+ - compatible : Should specify what this flash device is compatible with.
+ Currently, this is most likely to be "direct-mapped" (which
+ corresponds to the MTD physmap mapping driver).
+ - reg : Offset and length of the register set (or memory mapping) for
+ the device.
+ - bank-width : Width of the flash data bus in bytes. Required
+ for the NOR flashes (compatible == "direct-mapped" and others) ONLY.
+
+ Recommended properties :
+
+ - partitions : Several pairs of 32-bit values where the first value is
+ partition's offset from the start of the device and the second one is
+ partition size in bytes with LSB used to signify a read only
+ partition (so, the partition size should always be an even number).
+ - partition-names : The list of concatenated zero terminated strings
+ representing the partition names.
+ - probe-type : The type of probe which should be done for the chip
+ (JEDEC vs CFI actually). Valid ONLY for NOR flashes.
+
+ Example:
+
+ flash@ff000000 {
+ device_type = "rom";
+ compatible = "direct-mapped";
+ probe-type = "CFI";
+ reg = <ff000000 01000000>;
+ bank-width = <4>;
+ partitions = <00000000 00f80000
+ 00f80000 00080001>;
+ partition-names = "fs\0firmware";
+ };
More devices will be defined as this spec matures.
+VII - Specifying interrupt information for devices
+===================================================
+
+The device tree represents the busses and devices of a hardware
+system in a form similar to the physical bus topology of the
+hardware.
+
+In addition, a logical 'interrupt tree' exists which represents the
+hierarchy and routing of interrupts in the hardware.
+
+The interrupt tree model is fully described in the
+document "Open Firmware Recommended Practice: Interrupt
+Mapping Version 0.9". The document is available at:
+<http://playground.sun.com/1275/practice>.
+
+1) interrupts property
+----------------------
+
+Devices that generate interrupts to a single interrupt controller
+should use the conventional OF representation described in the
+OF interrupt mapping documentation.
+
+Each device which generates interrupts must have an 'interrupt'
+property. The interrupt property value is an arbitrary number of
+of 'interrupt specifier' values which describe the interrupt or
+interrupts for the device.
+
+The encoding of an interrupt specifier is determined by the
+interrupt domain in which the device is located in the
+interrupt tree. The root of an interrupt domain specifies in
+its #interrupt-cells property the number of 32-bit cells
+required to encode an interrupt specifier. See the OF interrupt
+mapping documentation for a detailed description of domains.
+
+For example, the binding for the OpenPIC interrupt controller
+specifies an #interrupt-cells value of 2 to encode the interrupt
+number and level/sense information. All interrupt children in an
+OpenPIC interrupt domain use 2 cells per interrupt in their interrupts
+property.
+
+The PCI bus binding specifies a #interrupt-cell value of 1 to encode
+which interrupt pin (INTA,INTB,INTC,INTD) is used.
+
+2) interrupt-parent property
+----------------------------
+
+The interrupt-parent property is specified to define an explicit
+link between a device node and its interrupt parent in
+the interrupt tree. The value of interrupt-parent is the
+phandle of the parent node.
+
+If the interrupt-parent property is not defined for a node, it's
+interrupt parent is assumed to be an ancestor in the node's
+_device tree_ hierarchy.
+
+3) OpenPIC Interrupt Controllers
+--------------------------------
+
+OpenPIC interrupt controllers require 2 cells to encode
+interrupt information. The first cell defines the interrupt
+number. The second cell defines the sense and level
+information.
+
+Sense and level information should be encoded as follows:
+
+ 0 = low to high edge sensitive type enabled
+ 1 = active low level sensitive type enabled
+ 2 = active high level sensitive type enabled
+ 3 = high to low edge sensitive type enabled
+
+4) ISA Interrupt Controllers
+----------------------------
+
+ISA PIC interrupt controllers require 2 cells to encode
+interrupt information. The first cell defines the interrupt
+number. The second cell defines the sense and level
+information.
+
+ISA PIC interrupt controllers should adhere to the ISA PIC
+encodings listed below:
+
+ 0 = active low level sensitive type enabled
+ 1 = active high level sensitive type enabled
+ 2 = high to low edge sensitive type enabled
+ 3 = low to high edge sensitive type enabled
+
Appendix A - Sample SOC node for MPC8540
========================================