ia64/kvm: compilation fix. export account_system_vtime.
[pv_ops_mirror.git] / Documentation / powerpc / booting-without-of.txt
blob1d2a772506cfa46e23acda9c3660369b72e1e85f
1            Booting the Linux/ppc kernel without Open Firmware
2            --------------------------------------------------
4 (c) 2005 Benjamin Herrenschmidt <benh at kernel.crashing.org>,
5     IBM Corp.
6 (c) 2005 Becky Bruce <becky.bruce at freescale.com>,
7     Freescale Semiconductor, FSL SOC and 32-bit additions
8 (c) 2006 MontaVista Software, Inc.
9     Flash chip node definition
11 Table of Contents
12 =================
14   I - Introduction
15     1) Entry point for arch/powerpc
16     2) Board support
18   II - The DT block format
19     1) Header
20     2) Device tree generalities
21     3) Device tree "structure" block
22     4) Device tree "strings" block
24   III - Required content of the device tree
25     1) Note about cells and address representation
26     2) Note about "compatible" properties
27     3) Note about "name" properties
28     4) Note about node and property names and character set
29     5) Required nodes and properties
30       a) The root node
31       b) The /cpus node
32       c) The /cpus/* nodes
33       d) the /memory node(s)
34       e) The /chosen node
35       f) the /soc<SOCname> node
37   IV - "dtc", the device tree compiler
39   V - Recommendations for a bootloader
41   VI - System-on-a-chip devices and nodes
42     1) Defining child nodes of an SOC
43     2) Representing devices without a current OF specification
44       a) MDIO IO device
45       b) Gianfar-compatible ethernet nodes
46       c) PHY nodes
47       d) Interrupt controllers
48       e) I2C
49       f) Freescale SOC USB controllers
50       g) Freescale SOC SEC Security Engines
51       h) Board Control and Status (BCSR)
52       i) Freescale QUICC Engine module (QE)
53       j) CFI or JEDEC memory-mapped NOR flash
54       k) Global Utilities Block
55       l) Freescale Communications Processor Module
56       m) Chipselect/Local Bus
57       n) 4xx/Axon EMAC ethernet nodes
58       o) Xilinx IP cores
59       p) Freescale Synchronous Serial Interface
60           q) USB EHCI controllers
62   VII - Marvell Discovery mv64[345]6x System Controller chips
63     1) The /system-controller node
64     2) Child nodes of /system-controller
65       a) Marvell Discovery MDIO bus
66       b) Marvell Discovery ethernet controller
67       c) Marvell Discovery PHY nodes
68       d) Marvell Discovery SDMA nodes
69       e) Marvell Discovery BRG nodes
70       f) Marvell Discovery CUNIT nodes
71       g) Marvell Discovery MPSCROUTING nodes
72       h) Marvell Discovery MPSCINTR nodes
73       i) Marvell Discovery MPSC nodes
74       j) Marvell Discovery Watch Dog Timer nodes
75       k) Marvell Discovery I2C nodes
76       l) Marvell Discovery PIC (Programmable Interrupt Controller) nodes
77       m) Marvell Discovery MPP (Multipurpose Pins) multiplexing nodes
78       n) Marvell Discovery GPP (General Purpose Pins) nodes
79       o) Marvell Discovery PCI host bridge node
80       p) Marvell Discovery CPU Error nodes
81       q) Marvell Discovery SRAM Controller nodes
82       r) Marvell Discovery PCI Error Handler nodes
83       s) Marvell Discovery Memory Controller nodes
85   VIII - Specifying interrupt information for devices
86     1) interrupts property
87     2) interrupt-parent property
88     3) OpenPIC Interrupt Controllers
89     4) ISA Interrupt Controllers
91   VIII - Specifying GPIO information for devices
92     1) gpios property
93     2) gpio-controller nodes
95   Appendix A - Sample SOC node for MPC8540
98 Revision Information
99 ====================
101    May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet.
103    May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or
104                            clarifies the fact that a lot of things are
105                            optional, the kernel only requires a very
106                            small device tree, though it is encouraged
107                            to provide an as complete one as possible.
109    May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM
110                          - Misc fixes
111                          - Define version 3 and new format version 16
112                            for the DT block (version 16 needs kernel
113                            patches, will be fwd separately).
114                            String block now has a size, and full path
115                            is replaced by unit name for more
116                            compactness.
117                            linux,phandle is made optional, only nodes
118                            that are referenced by other nodes need it.
119                            "name" property is now automatically
120                            deduced from the unit name
122    June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and
123                            OF_DT_END_NODE in structure definition.
124                          - Change version 16 format to always align
125                            property data to 4 bytes. Since tokens are
126                            already aligned, that means no specific
127                            required alignment between property size
128                            and property data. The old style variable
129                            alignment would make it impossible to do
130                            "simple" insertion of properties using
131                            memmove (thanks Milton for
132                            noticing). Updated kernel patch as well
133                          - Correct a few more alignment constraints
134                          - Add a chapter about the device-tree
135                            compiler and the textural representation of
136                            the tree that can be "compiled" by dtc.
138    November 21, 2005: Rev 0.5
139                          - Additions/generalizations for 32-bit
140                          - Changed to reflect the new arch/powerpc
141                            structure
142                          - Added chapter VI
145  ToDo:
146         - Add some definitions of interrupt tree (simple/complex)
147         - Add some definitions for PCI host bridges
148         - Add some common address format examples
149         - Add definitions for standard properties and "compatible"
150           names for cells that are not already defined by the existing
151           OF spec.
152         - Compare FSL SOC use of PCI to standard and make sure no new
153           node definition required.
154         - Add more information about node definitions for SOC devices
155           that currently have no standard, like the FSL CPM.
158 I - Introduction
159 ================
161 During the recent development of the Linux/ppc64 kernel, and more
162 specifically, the addition of new platform types outside of the old
163 IBM pSeries/iSeries pair, it was decided to enforce some strict rules
164 regarding the kernel entry and bootloader <-> kernel interfaces, in
165 order to avoid the degeneration that had become the ppc32 kernel entry
166 point and the way a new platform should be added to the kernel. The
167 legacy iSeries platform breaks those rules as it predates this scheme,
168 but no new board support will be accepted in the main tree that
169 doesn't follows them properly.  In addition, since the advent of the
170 arch/powerpc merged architecture for ppc32 and ppc64, new 32-bit
171 platforms and 32-bit platforms which move into arch/powerpc will be
172 required to use these rules as well.
174 The main requirement that will be defined in more detail below is
175 the presence of a device-tree whose format is defined after Open
176 Firmware specification. However, in order to make life easier
177 to embedded board vendors, the kernel doesn't require the device-tree
178 to represent every device in the system and only requires some nodes
179 and properties to be present. This will be described in detail in
180 section III, but, for example, the kernel does not require you to
181 create a node for every PCI device in the system. It is a requirement
182 to have a node for PCI host bridges in order to provide interrupt
183 routing informations and memory/IO ranges, among others. It is also
184 recommended to define nodes for on chip devices and other busses that
185 don't specifically fit in an existing OF specification. This creates a
186 great flexibility in the way the kernel can then probe those and match
187 drivers to device, without having to hard code all sorts of tables. It
188 also makes it more flexible for board vendors to do minor hardware
189 upgrades without significantly impacting the kernel code or cluttering
190 it with special cases.
193 1) Entry point for arch/powerpc
194 -------------------------------
196    There is one and one single entry point to the kernel, at the start
197    of the kernel image. That entry point supports two calling
198    conventions:
200         a) Boot from Open Firmware. If your firmware is compatible
201         with Open Firmware (IEEE 1275) or provides an OF compatible
202         client interface API (support for "interpret" callback of
203         forth words isn't required), you can enter the kernel with:
205               r5 : OF callback pointer as defined by IEEE 1275
206               bindings to powerpc. Only the 32-bit client interface
207               is currently supported
209               r3, r4 : address & length of an initrd if any or 0
211               The MMU is either on or off; the kernel will run the
212               trampoline located in arch/powerpc/kernel/prom_init.c to
213               extract the device-tree and other information from open
214               firmware and build a flattened device-tree as described
215               in b). prom_init() will then re-enter the kernel using
216               the second method. This trampoline code runs in the
217               context of the firmware, which is supposed to handle all
218               exceptions during that time.
220         b) Direct entry with a flattened device-tree block. This entry
221         point is called by a) after the OF trampoline and can also be
222         called directly by a bootloader that does not support the Open
223         Firmware client interface. It is also used by "kexec" to
224         implement "hot" booting of a new kernel from a previous
225         running one. This method is what I will describe in more
226         details in this document, as method a) is simply standard Open
227         Firmware, and thus should be implemented according to the
228         various standard documents defining it and its binding to the
229         PowerPC platform. The entry point definition then becomes:
231                 r3 : physical pointer to the device-tree block
232                 (defined in chapter II) in RAM
234                 r4 : physical pointer to the kernel itself. This is
235                 used by the assembly code to properly disable the MMU
236                 in case you are entering the kernel with MMU enabled
237                 and a non-1:1 mapping.
239                 r5 : NULL (as to differentiate with method a)
241         Note about SMP entry: Either your firmware puts your other
242         CPUs in some sleep loop or spin loop in ROM where you can get
243         them out via a soft reset or some other means, in which case
244         you don't need to care, or you'll have to enter the kernel
245         with all CPUs. The way to do that with method b) will be
246         described in a later revision of this document.
249 2) Board support
250 ----------------
252 64-bit kernels:
254    Board supports (platforms) are not exclusive config options. An
255    arbitrary set of board supports can be built in a single kernel
256    image. The kernel will "know" what set of functions to use for a
257    given platform based on the content of the device-tree. Thus, you
258    should:
260         a) add your platform support as a _boolean_ option in
261         arch/powerpc/Kconfig, following the example of PPC_PSERIES,
262         PPC_PMAC and PPC_MAPLE. The later is probably a good
263         example of a board support to start from.
265         b) create your main platform file as
266         "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it
267         to the Makefile under the condition of your CONFIG_
268         option. This file will define a structure of type "ppc_md"
269         containing the various callbacks that the generic code will
270         use to get to your platform specific code
272         c) Add a reference to your "ppc_md" structure in the
273         "machines" table in arch/powerpc/kernel/setup_64.c if you are
274         a 64-bit platform.
276         d) request and get assigned a platform number (see PLATFORM_*
277         constants in include/asm-powerpc/processor.h
279 32-bit embedded kernels:
281   Currently, board support is essentially an exclusive config option.
282   The kernel is configured for a single platform.  Part of the reason
283   for this is to keep kernels on embedded systems small and efficient;
284   part of this is due to the fact the code is already that way. In the
285   future, a kernel may support multiple platforms, but only if the
286   platforms feature the same core architecture.  A single kernel build
287   cannot support both configurations with Book E and configurations
288   with classic Powerpc architectures.
290   32-bit embedded platforms that are moved into arch/powerpc using a
291   flattened device tree should adopt the merged tree practice of
292   setting ppc_md up dynamically, even though the kernel is currently
293   built with support for only a single platform at a time.  This allows
294   unification of the setup code, and will make it easier to go to a
295   multiple-platform-support model in the future.
297 NOTE: I believe the above will be true once Ben's done with the merge
298 of the boot sequences.... someone speak up if this is wrong!
300   To add a 32-bit embedded platform support, follow the instructions
301   for 64-bit platforms above, with the exception that the Kconfig
302   option should be set up such that the kernel builds exclusively for
303   the platform selected.  The processor type for the platform should
304   enable another config option to select the specific board
305   supported.
307 NOTE: If Ben doesn't merge the setup files, may need to change this to
308 point to setup_32.c
311    I will describe later the boot process and various callbacks that
312    your platform should implement.
315 II - The DT block format
316 ========================
319 This chapter defines the actual format of the flattened device-tree
320 passed to the kernel. The actual content of it and kernel requirements
321 are described later. You can find example of code manipulating that
322 format in various places, including arch/powerpc/kernel/prom_init.c
323 which will generate a flattened device-tree from the Open Firmware
324 representation, or the fs2dt utility which is part of the kexec tools
325 which will generate one from a filesystem representation. It is
326 expected that a bootloader like uboot provides a bit more support,
327 that will be discussed later as well.
329 Note: The block has to be in main memory. It has to be accessible in
330 both real mode and virtual mode with no mapping other than main
331 memory. If you are writing a simple flash bootloader, it should copy
332 the block to RAM before passing it to the kernel.
335 1) Header
336 ---------
338    The kernel is entered with r3 pointing to an area of memory that is
339    roughly described in include/asm-powerpc/prom.h by the structure
340    boot_param_header:
342 struct boot_param_header {
343         u32     magic;                  /* magic word OF_DT_HEADER */
344         u32     totalsize;              /* total size of DT block */
345         u32     off_dt_struct;          /* offset to structure */
346         u32     off_dt_strings;         /* offset to strings */
347         u32     off_mem_rsvmap;         /* offset to memory reserve map
348                                            */
349         u32     version;                /* format version */
350         u32     last_comp_version;      /* last compatible version */
352         /* version 2 fields below */
353         u32     boot_cpuid_phys;        /* Which physical CPU id we're
354                                            booting on */
355         /* version 3 fields below */
356         u32     size_dt_strings;        /* size of the strings block */
358         /* version 17 fields below */
359         u32     size_dt_struct;         /* size of the DT structure block */
362    Along with the constants:
364 /* Definitions used by the flattened device tree */
365 #define OF_DT_HEADER            0xd00dfeed      /* 4: version,
366                                                    4: total size */
367 #define OF_DT_BEGIN_NODE        0x1             /* Start node: full name
368                                                    */
369 #define OF_DT_END_NODE          0x2             /* End node */
370 #define OF_DT_PROP              0x3             /* Property: name off,
371                                                    size, content */
372 #define OF_DT_END               0x9
374    All values in this header are in big endian format, the various
375    fields in this header are defined more precisely below. All
376    "offset" values are in bytes from the start of the header; that is
377    from the value of r3.
379    - magic
381      This is a magic value that "marks" the beginning of the
382      device-tree block header. It contains the value 0xd00dfeed and is
383      defined by the constant OF_DT_HEADER
385    - totalsize
387      This is the total size of the DT block including the header. The
388      "DT" block should enclose all data structures defined in this
389      chapter (who are pointed to by offsets in this header). That is,
390      the device-tree structure, strings, and the memory reserve map.
392    - off_dt_struct
394      This is an offset from the beginning of the header to the start
395      of the "structure" part the device tree. (see 2) device tree)
397    - off_dt_strings
399      This is an offset from the beginning of the header to the start
400      of the "strings" part of the device-tree
402    - off_mem_rsvmap
404      This is an offset from the beginning of the header to the start
405      of the reserved memory map. This map is a list of pairs of 64-
406      bit integers. Each pair is a physical address and a size. The
407      list is terminated by an entry of size 0. This map provides the
408      kernel with a list of physical memory areas that are "reserved"
409      and thus not to be used for memory allocations, especially during
410      early initialization. The kernel needs to allocate memory during
411      boot for things like un-flattening the device-tree, allocating an
412      MMU hash table, etc... Those allocations must be done in such a
413      way to avoid overriding critical things like, on Open Firmware
414      capable machines, the RTAS instance, or on some pSeries, the TCE
415      tables used for the iommu. Typically, the reserve map should
416      contain _at least_ this DT block itself (header,total_size). If
417      you are passing an initrd to the kernel, you should reserve it as
418      well. You do not need to reserve the kernel image itself. The map
419      should be 64-bit aligned.
421    - version
423      This is the version of this structure. Version 1 stops
424      here. Version 2 adds an additional field boot_cpuid_phys.
425      Version 3 adds the size of the strings block, allowing the kernel
426      to reallocate it easily at boot and free up the unused flattened
427      structure after expansion. Version 16 introduces a new more
428      "compact" format for the tree itself that is however not backward
429      compatible. Version 17 adds an additional field, size_dt_struct,
430      allowing it to be reallocated or moved more easily (this is
431      particularly useful for bootloaders which need to make
432      adjustments to a device tree based on probed information). You
433      should always generate a structure of the highest version defined
434      at the time of your implementation. Currently that is version 17,
435      unless you explicitly aim at being backward compatible.
437    - last_comp_version
439      Last compatible version. This indicates down to what version of
440      the DT block you are backward compatible. For example, version 2
441      is backward compatible with version 1 (that is, a kernel build
442      for version 1 will be able to boot with a version 2 format). You
443      should put a 1 in this field if you generate a device tree of
444      version 1 to 3, or 16 if you generate a tree of version 16 or 17
445      using the new unit name format.
447    - boot_cpuid_phys
449      This field only exist on version 2 headers. It indicate which
450      physical CPU ID is calling the kernel entry point. This is used,
451      among others, by kexec. If you are on an SMP system, this value
452      should match the content of the "reg" property of the CPU node in
453      the device-tree corresponding to the CPU calling the kernel entry
454      point (see further chapters for more informations on the required
455      device-tree contents)
457    - size_dt_strings
459      This field only exists on version 3 and later headers.  It
460      gives the size of the "strings" section of the device tree (which
461      starts at the offset given by off_dt_strings).
463    - size_dt_struct
465      This field only exists on version 17 and later headers.  It gives
466      the size of the "structure" section of the device tree (which
467      starts at the offset given by off_dt_struct).
469    So the typical layout of a DT block (though the various parts don't
470    need to be in that order) looks like this (addresses go from top to
471    bottom):
474              ------------------------------
475        r3 -> |  struct boot_param_header  |
476              ------------------------------
477              |      (alignment gap) (*)   |
478              ------------------------------
479              |      memory reserve map    |
480              ------------------------------
481              |      (alignment gap)       |
482              ------------------------------
483              |                            |
484              |    device-tree structure   |
485              |                            |
486              ------------------------------
487              |      (alignment gap)       |
488              ------------------------------
489              |                            |
490              |     device-tree strings    |
491              |                            |
492       -----> ------------------------------
493       |
494       |
495       --- (r3 + totalsize)
497   (*) The alignment gaps are not necessarily present; their presence
498       and size are dependent on the various alignment requirements of
499       the individual data blocks.
502 2) Device tree generalities
503 ---------------------------
505 This device-tree itself is separated in two different blocks, a
506 structure block and a strings block. Both need to be aligned to a 4
507 byte boundary.
509 First, let's quickly describe the device-tree concept before detailing
510 the storage format. This chapter does _not_ describe the detail of the
511 required types of nodes & properties for the kernel, this is done
512 later in chapter III.
514 The device-tree layout is strongly inherited from the definition of
515 the Open Firmware IEEE 1275 device-tree. It's basically a tree of
516 nodes, each node having two or more named properties. A property can
517 have a value or not.
519 It is a tree, so each node has one and only one parent except for the
520 root node who has no parent.
522 A node has 2 names. The actual node name is generally contained in a
523 property of type "name" in the node property list whose value is a
524 zero terminated string and is mandatory for version 1 to 3 of the
525 format definition (as it is in Open Firmware). Version 16 makes it
526 optional as it can generate it from the unit name defined below.
528 There is also a "unit name" that is used to differentiate nodes with
529 the same name at the same level, it is usually made of the node
530 names, the "@" sign, and a "unit address", which definition is
531 specific to the bus type the node sits on.
533 The unit name doesn't exist as a property per-se but is included in
534 the device-tree structure. It is typically used to represent "path" in
535 the device-tree. More details about the actual format of these will be
536 below.
538 The kernel powerpc generic code does not make any formal use of the
539 unit address (though some board support code may do) so the only real
540 requirement here for the unit address is to ensure uniqueness of
541 the node unit name at a given level of the tree. Nodes with no notion
542 of address and no possible sibling of the same name (like /memory or
543 /cpus) may omit the unit address in the context of this specification,
544 or use the "@0" default unit address. The unit name is used to define
545 a node "full path", which is the concatenation of all parent node
546 unit names separated with "/".
548 The root node doesn't have a defined name, and isn't required to have
549 a name property either if you are using version 3 or earlier of the
550 format. It also has no unit address (no @ symbol followed by a unit
551 address). The root node unit name is thus an empty string. The full
552 path to the root node is "/".
554 Every node which actually represents an actual device (that is, a node
555 which isn't only a virtual "container" for more nodes, like "/cpus"
556 is) is also required to have a "device_type" property indicating the
557 type of node .
559 Finally, every node that can be referenced from a property in another
560 node is required to have a "linux,phandle" property. Real open
561 firmware implementations provide a unique "phandle" value for every
562 node that the "prom_init()" trampoline code turns into
563 "linux,phandle" properties. However, this is made optional if the
564 flattened device tree is used directly. An example of a node
565 referencing another node via "phandle" is when laying out the
566 interrupt tree which will be described in a further version of this
567 document.
569 This "linux, phandle" property is a 32-bit value that uniquely
570 identifies a node. You are free to use whatever values or system of
571 values, internal pointers, or whatever to generate these, the only
572 requirement is that every node for which you provide that property has
573 a unique value for it.
575 Here is an example of a simple device-tree. In this example, an "o"
576 designates a node followed by the node unit name. Properties are
577 presented with their name followed by their content. "content"
578 represents an ASCII string (zero terminated) value, while <content>
579 represents a 32-bit hexadecimal value. The various nodes in this
580 example will be discussed in a later chapter. At this point, it is
581 only meant to give you a idea of what a device-tree looks like. I have
582 purposefully kept the "name" and "linux,phandle" properties which
583 aren't necessary in order to give you a better idea of what the tree
584 looks like in practice.
586   / o device-tree
587       |- name = "device-tree"
588       |- model = "MyBoardName"
589       |- compatible = "MyBoardFamilyName"
590       |- #address-cells = <2>
591       |- #size-cells = <2>
592       |- linux,phandle = <0>
593       |
594       o cpus
595       | | - name = "cpus"
596       | | - linux,phandle = <1>
597       | | - #address-cells = <1>
598       | | - #size-cells = <0>
599       | |
600       | o PowerPC,970@0
601       |   |- name = "PowerPC,970"
602       |   |- device_type = "cpu"
603       |   |- reg = <0>
604       |   |- clock-frequency = <5f5e1000>
605       |   |- 64-bit
606       |   |- linux,phandle = <2>
607       |
608       o memory@0
609       | |- name = "memory"
610       | |- device_type = "memory"
611       | |- reg = <00000000 00000000 00000000 20000000>
612       | |- linux,phandle = <3>
613       |
614       o chosen
615         |- name = "chosen"
616         |- bootargs = "root=/dev/sda2"
617         |- linux,phandle = <4>
619 This tree is almost a minimal tree. It pretty much contains the
620 minimal set of required nodes and properties to boot a linux kernel;
621 that is, some basic model informations at the root, the CPUs, and the
622 physical memory layout.  It also includes misc information passed
623 through /chosen, like in this example, the platform type (mandatory)
624 and the kernel command line arguments (optional).
626 The /cpus/PowerPC,970@0/64-bit property is an example of a
627 property without a value. All other properties have a value. The
628 significance of the #address-cells and #size-cells properties will be
629 explained in chapter IV which defines precisely the required nodes and
630 properties and their content.
633 3) Device tree "structure" block
635 The structure of the device tree is a linearized tree structure. The
636 "OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE"
637 ends that node definition. Child nodes are simply defined before
638 "OF_DT_END_NODE" (that is nodes within the node). A 'token' is a 32
639 bit value. The tree has to be "finished" with a OF_DT_END token
641 Here's the basic structure of a single node:
643      * token OF_DT_BEGIN_NODE (that is 0x00000001)
644      * for version 1 to 3, this is the node full path as a zero
645        terminated string, starting with "/". For version 16 and later,
646        this is the node unit name only (or an empty string for the
647        root node)
648      * [align gap to next 4 bytes boundary]
649      * for each property:
650         * token OF_DT_PROP (that is 0x00000003)
651         * 32-bit value of property value size in bytes (or 0 if no
652           value)
653         * 32-bit value of offset in string block of property name
654         * property value data if any
655         * [align gap to next 4 bytes boundary]
656      * [child nodes if any]
657      * token OF_DT_END_NODE (that is 0x00000002)
659 So the node content can be summarized as a start token, a full path,
660 a list of properties, a list of child nodes, and an end token. Every
661 child node is a full node structure itself as defined above.
663 NOTE: The above definition requires that all property definitions for
664 a particular node MUST precede any subnode definitions for that node.
665 Although the structure would not be ambiguous if properties and
666 subnodes were intermingled, the kernel parser requires that the
667 properties come first (up until at least 2.6.22).  Any tools
668 manipulating a flattened tree must take care to preserve this
669 constraint.
671 4) Device tree "strings" block
673 In order to save space, property names, which are generally redundant,
674 are stored separately in the "strings" block. This block is simply the
675 whole bunch of zero terminated strings for all property names
676 concatenated together. The device-tree property definitions in the
677 structure block will contain offset values from the beginning of the
678 strings block.
681 III - Required content of the device tree
682 =========================================
684 WARNING: All "linux,*" properties defined in this document apply only
685 to a flattened device-tree. If your platform uses a real
686 implementation of Open Firmware or an implementation compatible with
687 the Open Firmware client interface, those properties will be created
688 by the trampoline code in the kernel's prom_init() file. For example,
689 that's where you'll have to add code to detect your board model and
690 set the platform number. However, when using the flattened device-tree
691 entry point, there is no prom_init() pass, and thus you have to
692 provide those properties yourself.
695 1) Note about cells and address representation
696 ----------------------------------------------
698 The general rule is documented in the various Open Firmware
699 documentations. If you choose to describe a bus with the device-tree
700 and there exist an OF bus binding, then you should follow the
701 specification. However, the kernel does not require every single
702 device or bus to be described by the device tree.
704 In general, the format of an address for a device is defined by the
705 parent bus type, based on the #address-cells and #size-cells
706 properties.  Note that the parent's parent definitions of #address-cells
707 and #size-cells are not inhereted so every node with children must specify
708 them.  The kernel requires the root node to have those properties defining
709 addresses format for devices directly mapped on the processor bus.
711 Those 2 properties define 'cells' for representing an address and a
712 size. A "cell" is a 32-bit number. For example, if both contain 2
713 like the example tree given above, then an address and a size are both
714 composed of 2 cells, and each is a 64-bit number (cells are
715 concatenated and expected to be in big endian format). Another example
716 is the way Apple firmware defines them, with 2 cells for an address
717 and one cell for a size.  Most 32-bit implementations should define
718 #address-cells and #size-cells to 1, which represents a 32-bit value.
719 Some 32-bit processors allow for physical addresses greater than 32
720 bits; these processors should define #address-cells as 2.
722 "reg" properties are always a tuple of the type "address size" where
723 the number of cells of address and size is specified by the bus
724 #address-cells and #size-cells. When a bus supports various address
725 spaces and other flags relative to a given address allocation (like
726 prefetchable, etc...) those flags are usually added to the top level
727 bits of the physical address. For example, a PCI physical address is
728 made of 3 cells, the bottom two containing the actual address itself
729 while the top cell contains address space indication, flags, and pci
730 bus & device numbers.
732 For busses that support dynamic allocation, it's the accepted practice
733 to then not provide the address in "reg" (keep it 0) though while
734 providing a flag indicating the address is dynamically allocated, and
735 then, to provide a separate "assigned-addresses" property that
736 contains the fully allocated addresses. See the PCI OF bindings for
737 details.
739 In general, a simple bus with no address space bits and no dynamic
740 allocation is preferred if it reflects your hardware, as the existing
741 kernel address parsing functions will work out of the box. If you
742 define a bus type with a more complex address format, including things
743 like address space bits, you'll have to add a bus translator to the
744 prom_parse.c file of the recent kernels for your bus type.
746 The "reg" property only defines addresses and sizes (if #size-cells is
747 non-0) within a given bus. In order to translate addresses upward
748 (that is into parent bus addresses, and possibly into CPU physical
749 addresses), all busses must contain a "ranges" property. If the
750 "ranges" property is missing at a given level, it's assumed that
751 translation isn't possible, i.e., the registers are not visible on the
752 parent bus.  The format of the "ranges" property for a bus is a list
755         bus address, parent bus address, size
757 "bus address" is in the format of the bus this bus node is defining,
758 that is, for a PCI bridge, it would be a PCI address. Thus, (bus
759 address, size) defines a range of addresses for child devices. "parent
760 bus address" is in the format of the parent bus of this bus. For
761 example, for a PCI host controller, that would be a CPU address. For a
762 PCI<->ISA bridge, that would be a PCI address. It defines the base
763 address in the parent bus where the beginning of that range is mapped.
765 For a new 64-bit powerpc board, I recommend either the 2/2 format or
766 Apple's 2/1 format which is slightly more compact since sizes usually
767 fit in a single 32-bit word.   New 32-bit powerpc boards should use a
768 1/1 format, unless the processor supports physical addresses greater
769 than 32-bits, in which case a 2/1 format is recommended.
771 Alternatively, the "ranges" property may be empty, indicating that the
772 registers are visible on the parent bus using an identity mapping
773 translation.  In other words, the parent bus address space is the same
774 as the child bus address space.
776 2) Note about "compatible" properties
777 -------------------------------------
779 These properties are optional, but recommended in devices and the root
780 node. The format of a "compatible" property is a list of concatenated
781 zero terminated strings. They allow a device to express its
782 compatibility with a family of similar devices, in some cases,
783 allowing a single driver to match against several devices regardless
784 of their actual names.
786 3) Note about "name" properties
787 -------------------------------
789 While earlier users of Open Firmware like OldWorld macintoshes tended
790 to use the actual device name for the "name" property, it's nowadays
791 considered a good practice to use a name that is closer to the device
792 class (often equal to device_type). For example, nowadays, ethernet
793 controllers are named "ethernet", an additional "model" property
794 defining precisely the chip type/model, and "compatible" property
795 defining the family in case a single driver can driver more than one
796 of these chips. However, the kernel doesn't generally put any
797 restriction on the "name" property; it is simply considered good
798 practice to follow the standard and its evolutions as closely as
799 possible.
801 Note also that the new format version 16 makes the "name" property
802 optional. If it's absent for a node, then the node's unit name is then
803 used to reconstruct the name. That is, the part of the unit name
804 before the "@" sign is used (or the entire unit name if no "@" sign
805 is present).
807 4) Note about node and property names and character set
808 -------------------------------------------------------
810 While open firmware provides more flexible usage of 8859-1, this
811 specification enforces more strict rules. Nodes and properties should
812 be comprised only of ASCII characters 'a' to 'z', '0' to
813 '9', ',', '.', '_', '+', '#', '?', and '-'. Node names additionally
814 allow uppercase characters 'A' to 'Z' (property names should be
815 lowercase. The fact that vendors like Apple don't respect this rule is
816 irrelevant here). Additionally, node and property names should always
817 begin with a character in the range 'a' to 'z' (or 'A' to 'Z' for node
818 names).
820 The maximum number of characters for both nodes and property names
821 is 31. In the case of node names, this is only the leftmost part of
822 a unit name (the pure "name" property), it doesn't include the unit
823 address which can extend beyond that limit.
826 5) Required nodes and properties
827 --------------------------------
828   These are all that are currently required. However, it is strongly
829   recommended that you expose PCI host bridges as documented in the
830   PCI binding to open firmware, and your interrupt tree as documented
831   in OF interrupt tree specification.
833   a) The root node
835   The root node requires some properties to be present:
837     - model : this is your board name/model
838     - #address-cells : address representation for "root" devices
839     - #size-cells: the size representation for "root" devices
840     - device_type : This property shouldn't be necessary. However, if
841       you decide to create a device_type for your root node, make sure it
842       is _not_ "chrp" unless your platform is a pSeries or PAPR compliant
843       one for 64-bit, or a CHRP-type machine for 32-bit as this will
844       matched by the kernel this way.
846   Additionally, some recommended properties are:
848     - compatible : the board "family" generally finds its way here,
849       for example, if you have 2 board models with a similar layout,
850       that typically get driven by the same platform code in the
851       kernel, you would use a different "model" property but put a
852       value in "compatible". The kernel doesn't directly use that
853       value but it is generally useful.
855   The root node is also generally where you add additional properties
856   specific to your board like the serial number if any, that sort of
857   thing. It is recommended that if you add any "custom" property whose
858   name may clash with standard defined ones, you prefix them with your
859   vendor name and a comma.
861   b) The /cpus node
863   This node is the parent of all individual CPU nodes. It doesn't
864   have any specific requirements, though it's generally good practice
865   to have at least:
867                #address-cells = <00000001>
868                #size-cells    = <00000000>
870   This defines that the "address" for a CPU is a single cell, and has
871   no meaningful size. This is not necessary but the kernel will assume
872   that format when reading the "reg" properties of a CPU node, see
873   below
875   c) The /cpus/* nodes
877   So under /cpus, you are supposed to create a node for every CPU on
878   the machine. There is no specific restriction on the name of the
879   CPU, though It's common practice to call it PowerPC,<name>. For
880   example, Apple uses PowerPC,G5 while IBM uses PowerPC,970FX.
882   Required properties:
884     - device_type : has to be "cpu"
885     - reg : This is the physical CPU number, it's a single 32-bit cell
886       and is also used as-is as the unit number for constructing the
887       unit name in the full path. For example, with 2 CPUs, you would
888       have the full path:
889         /cpus/PowerPC,970FX@0
890         /cpus/PowerPC,970FX@1
891       (unit addresses do not require leading zeroes)
892     - d-cache-block-size : one cell, L1 data cache block size in bytes (*)
893     - i-cache-block-size : one cell, L1 instruction cache block size in
894       bytes
895     - d-cache-size : one cell, size of L1 data cache in bytes
896     - i-cache-size : one cell, size of L1 instruction cache in bytes
898 (*) The cache "block" size is the size on which the cache management
899 instructions operate. Historically, this document used the cache
900 "line" size here which is incorrect. The kernel will prefer the cache
901 block size and will fallback to cache line size for backward
902 compatibility.
904   Recommended properties:
906     - timebase-frequency : a cell indicating the frequency of the
907       timebase in Hz. This is not directly used by the generic code,
908       but you are welcome to copy/paste the pSeries code for setting
909       the kernel timebase/decrementer calibration based on this
910       value.
911     - clock-frequency : a cell indicating the CPU core clock frequency
912       in Hz. A new property will be defined for 64-bit values, but if
913       your frequency is < 4Ghz, one cell is enough. Here as well as
914       for the above, the common code doesn't use that property, but
915       you are welcome to re-use the pSeries or Maple one. A future
916       kernel version might provide a common function for this.
917     - d-cache-line-size : one cell, L1 data cache line size in bytes
918       if different from the block size
919     - i-cache-line-size : one cell, L1 instruction cache line size in
920       bytes if different from the block size
922   You are welcome to add any property you find relevant to your board,
923   like some information about the mechanism used to soft-reset the
924   CPUs. For example, Apple puts the GPIO number for CPU soft reset
925   lines in there as a "soft-reset" property since they start secondary
926   CPUs by soft-resetting them.
929   d) the /memory node(s)
931   To define the physical memory layout of your board, you should
932   create one or more memory node(s). You can either create a single
933   node with all memory ranges in its reg property, or you can create
934   several nodes, as you wish. The unit address (@ part) used for the
935   full path is the address of the first range of memory defined by a
936   given node. If you use a single memory node, this will typically be
937   @0.
939   Required properties:
941     - device_type : has to be "memory"
942     - reg : This property contains all the physical memory ranges of
943       your board. It's a list of addresses/sizes concatenated
944       together, with the number of cells of each defined by the
945       #address-cells and #size-cells of the root node. For example,
946       with both of these properties being 2 like in the example given
947       earlier, a 970 based machine with 6Gb of RAM could typically
948       have a "reg" property here that looks like:
950       00000000 00000000 00000000 80000000
951       00000001 00000000 00000001 00000000
953       That is a range starting at 0 of 0x80000000 bytes and a range
954       starting at 0x100000000 and of 0x100000000 bytes. You can see
955       that there is no memory covering the IO hole between 2Gb and
956       4Gb. Some vendors prefer splitting those ranges into smaller
957       segments, but the kernel doesn't care.
959   e) The /chosen node
961   This node is a bit "special". Normally, that's where open firmware
962   puts some variable environment information, like the arguments, or
963   the default input/output devices.
965   This specification makes a few of these mandatory, but also defines
966   some linux-specific properties that would be normally constructed by
967   the prom_init() trampoline when booting with an OF client interface,
968   but that you have to provide yourself when using the flattened format.
970   Recommended properties:
972     - bootargs : This zero-terminated string is passed as the kernel
973       command line
974     - linux,stdout-path : This is the full path to your standard
975       console device if any. Typically, if you have serial devices on
976       your board, you may want to put the full path to the one set as
977       the default console in the firmware here, for the kernel to pick
978       it up as its own default console. If you look at the function
979       set_preferred_console() in arch/ppc64/kernel/setup.c, you'll see
980       that the kernel tries to find out the default console and has
981       knowledge of various types like 8250 serial ports. You may want
982       to extend this function to add your own.
984   Note that u-boot creates and fills in the chosen node for platforms
985   that use it.
987   (Note: a practice that is now obsolete was to include a property
988   under /chosen called interrupt-controller which had a phandle value
989   that pointed to the main interrupt controller)
991   f) the /soc<SOCname> node
993   This node is used to represent a system-on-a-chip (SOC) and must be
994   present if the processor is a SOC. The top-level soc node contains
995   information that is global to all devices on the SOC. The node name
996   should contain a unit address for the SOC, which is the base address
997   of the memory-mapped register set for the SOC. The name of an soc
998   node should start with "soc", and the remainder of the name should
999   represent the part number for the soc.  For example, the MPC8540's
1000   soc node would be called "soc8540".
1002   Required properties:
1004     - device_type : Should be "soc"
1005     - ranges : Should be defined as specified in 1) to describe the
1006       translation of SOC addresses for memory mapped SOC registers.
1007     - bus-frequency: Contains the bus frequency for the SOC node.
1008       Typically, the value of this field is filled in by the boot
1009       loader. 
1012   Recommended properties:
1014     - reg : This property defines the address and size of the
1015       memory-mapped registers that are used for the SOC node itself.
1016       It does not include the child device registers - these will be
1017       defined inside each child node.  The address specified in the
1018       "reg" property should match the unit address of the SOC node.
1019     - #address-cells : Address representation for "soc" devices.  The
1020       format of this field may vary depending on whether or not the
1021       device registers are memory mapped.  For memory mapped
1022       registers, this field represents the number of cells needed to
1023       represent the address of the registers.  For SOCs that do not
1024       use MMIO, a special address format should be defined that
1025       contains enough cells to represent the required information.
1026       See 1) above for more details on defining #address-cells.
1027     - #size-cells : Size representation for "soc" devices
1028     - #interrupt-cells : Defines the width of cells used to represent
1029        interrupts.  Typically this value is <2>, which includes a
1030        32-bit number that represents the interrupt number, and a
1031        32-bit number that represents the interrupt sense and level.
1032        This field is only needed if the SOC contains an interrupt
1033        controller.
1035   The SOC node may contain child nodes for each SOC device that the
1036   platform uses.  Nodes should not be created for devices which exist
1037   on the SOC but are not used by a particular platform. See chapter VI
1038   for more information on how to specify devices that are part of a SOC.
1040   Example SOC node for the MPC8540:
1042         soc8540@e0000000 {
1043                 #address-cells = <1>;
1044                 #size-cells = <1>;
1045                 #interrupt-cells = <2>;
1046                 device_type = "soc";
1047                 ranges = <00000000 e0000000 00100000>
1048                 reg = <e0000000 00003000>;
1049                 bus-frequency = <0>;
1050         }
1054 IV - "dtc", the device tree compiler
1055 ====================================
1058 dtc source code can be found at
1059 <http://ozlabs.org/~dgibson/dtc/dtc.tar.gz>
1061 WARNING: This version is still in early development stage; the
1062 resulting device-tree "blobs" have not yet been validated with the
1063 kernel. The current generated bloc lacks a useful reserve map (it will
1064 be fixed to generate an empty one, it's up to the bootloader to fill
1065 it up) among others. The error handling needs work, bugs are lurking,
1066 etc...
1068 dtc basically takes a device-tree in a given format and outputs a
1069 device-tree in another format. The currently supported formats are:
1071   Input formats:
1072   -------------
1074      - "dtb": "blob" format, that is a flattened device-tree block
1075        with
1076         header all in a binary blob.
1077      - "dts": "source" format. This is a text file containing a
1078        "source" for a device-tree. The format is defined later in this
1079         chapter.
1080      - "fs" format. This is a representation equivalent to the
1081         output of /proc/device-tree, that is nodes are directories and
1082         properties are files
1084  Output formats:
1085  ---------------
1087      - "dtb": "blob" format
1088      - "dts": "source" format
1089      - "asm": assembly language file. This is a file that can be
1090        sourced by gas to generate a device-tree "blob". That file can
1091        then simply be added to your Makefile. Additionally, the
1092        assembly file exports some symbols that can be used.
1095 The syntax of the dtc tool is
1097     dtc [-I <input-format>] [-O <output-format>]
1098         [-o output-filename] [-V output_version] input_filename
1101 The "output_version" defines what version of the "blob" format will be
1102 generated. Supported versions are 1,2,3 and 16. The default is
1103 currently version 3 but that may change in the future to version 16.
1105 Additionally, dtc performs various sanity checks on the tree, like the
1106 uniqueness of linux, phandle properties, validity of strings, etc...
1108 The format of the .dts "source" file is "C" like, supports C and C++
1109 style comments.
1111 / {
1114 The above is the "device-tree" definition. It's the only statement
1115 supported currently at the toplevel.
1117 / {
1118   property1 = "string_value";   /* define a property containing a 0
1119                                  * terminated string
1120                                  */
1122   property2 = <1234abcd>;       /* define a property containing a
1123                                  * numerical 32-bit value (hexadecimal)
1124                                  */
1126   property3 = <12345678 12345678 deadbeef>;
1127                                 /* define a property containing 3
1128                                  * numerical 32-bit values (cells) in
1129                                  * hexadecimal
1130                                  */
1131   property4 = [0a 0b 0c 0d de ea ad be ef];
1132                                 /* define a property whose content is
1133                                  * an arbitrary array of bytes
1134                                  */
1136   childnode@addresss {  /* define a child node named "childnode"
1137                                  * whose unit name is "childnode at
1138                                  * address"
1139                                  */
1141     childprop = "hello\n";      /* define a property "childprop" of
1142                                  * childnode (in this case, a string)
1143                                  */
1144   };
1147 Nodes can contain other nodes etc... thus defining the hierarchical
1148 structure of the tree.
1150 Strings support common escape sequences from C: "\n", "\t", "\r",
1151 "\(octal value)", "\x(hex value)".
1153 It is also suggested that you pipe your source file through cpp (gcc
1154 preprocessor) so you can use #include's, #define for constants, etc...
1156 Finally, various options are planned but not yet implemented, like
1157 automatic generation of phandles, labels (exported to the asm file so
1158 you can point to a property content and change it easily from whatever
1159 you link the device-tree with), label or path instead of numeric value
1160 in some cells to "point" to a node (replaced by a phandle at compile
1161 time), export of reserve map address to the asm file, ability to
1162 specify reserve map content at compile time, etc...
1164 We may provide a .h include file with common definitions of that
1165 proves useful for some properties (like building PCI properties or
1166 interrupt maps) though it may be better to add a notion of struct
1167 definitions to the compiler...
1170 V - Recommendations for a bootloader
1171 ====================================
1174 Here are some various ideas/recommendations that have been proposed
1175 while all this has been defined and implemented.
1177   - The bootloader may want to be able to use the device-tree itself
1178     and may want to manipulate it (to add/edit some properties,
1179     like physical memory size or kernel arguments). At this point, 2
1180     choices can be made. Either the bootloader works directly on the
1181     flattened format, or the bootloader has its own internal tree
1182     representation with pointers (similar to the kernel one) and
1183     re-flattens the tree when booting the kernel. The former is a bit
1184     more difficult to edit/modify, the later requires probably a bit
1185     more code to handle the tree structure. Note that the structure
1186     format has been designed so it's relatively easy to "insert"
1187     properties or nodes or delete them by just memmoving things
1188     around. It contains no internal offsets or pointers for this
1189     purpose.
1191   - An example of code for iterating nodes & retrieving properties
1192     directly from the flattened tree format can be found in the kernel
1193     file arch/ppc64/kernel/prom.c, look at scan_flat_dt() function,
1194     its usage in early_init_devtree(), and the corresponding various
1195     early_init_dt_scan_*() callbacks. That code can be re-used in a
1196     GPL bootloader, and as the author of that code, I would be happy
1197     to discuss possible free licensing to any vendor who wishes to
1198     integrate all or part of this code into a non-GPL bootloader.
1202 VI - System-on-a-chip devices and nodes
1203 =======================================
1205 Many companies are now starting to develop system-on-a-chip
1206 processors, where the processor core (CPU) and many peripheral devices
1207 exist on a single piece of silicon.  For these SOCs, an SOC node
1208 should be used that defines child nodes for the devices that make
1209 up the SOC. While platforms are not required to use this model in
1210 order to boot the kernel, it is highly encouraged that all SOC
1211 implementations define as complete a flat-device-tree as possible to
1212 describe the devices on the SOC.  This will allow for the
1213 genericization of much of the kernel code.
1216 1) Defining child nodes of an SOC
1217 ---------------------------------
1219 Each device that is part of an SOC may have its own node entry inside
1220 the SOC node.  For each device that is included in the SOC, the unit
1221 address property represents the address offset for this device's
1222 memory-mapped registers in the parent's address space.  The parent's
1223 address space is defined by the "ranges" property in the top-level soc
1224 node. The "reg" property for each node that exists directly under the
1225 SOC node should contain the address mapping from the child address space
1226 to the parent SOC address space and the size of the device's
1227 memory-mapped register file.
1229 For many devices that may exist inside an SOC, there are predefined
1230 specifications for the format of the device tree node.  All SOC child
1231 nodes should follow these specifications, except where noted in this
1232 document.
1234 See appendix A for an example partial SOC node definition for the
1235 MPC8540.
1238 2) Representing devices without a current OF specification
1239 ----------------------------------------------------------
1241 Currently, there are many devices on SOCs that do not have a standard
1242 representation pre-defined as part of the open firmware
1243 specifications, mainly because the boards that contain these SOCs are
1244 not currently booted using open firmware.   This section contains
1245 descriptions for the SOC devices for which new nodes have been
1246 defined; this list will expand as more and more SOC-containing
1247 platforms are moved over to use the flattened-device-tree model.
1249   a) MDIO IO device
1251   The MDIO is a bus to which the PHY devices are connected.  For each
1252   device that exists on this bus, a child node should be created.  See
1253   the definition of the PHY node below for an example of how to define
1254   a PHY.
1256   Required properties:
1257     - reg : Offset and length of the register set for the device
1258     - compatible : Should define the compatible device type for the
1259       mdio.  Currently, this is most likely to be "fsl,gianfar-mdio"
1261   Example:
1263         mdio@24520 {
1264                 reg = <24520 20>;
1265                 compatible = "fsl,gianfar-mdio";
1267                 ethernet-phy@0 {
1268                         ......
1269                 };
1270         };
1273   b) Gianfar-compatible ethernet nodes
1275   Required properties:
1277     - device_type : Should be "network"
1278     - model : Model of the device.  Can be "TSEC", "eTSEC", or "FEC"
1279     - compatible : Should be "gianfar"
1280     - reg : Offset and length of the register set for the device
1281     - mac-address : List of bytes representing the ethernet address of
1282       this controller
1283     - interrupts : <a b> where a is the interrupt number and b is a
1284       field that represents an encoding of the sense and level
1285       information for the interrupt.  This should be encoded based on
1286       the information in section 2) depending on the type of interrupt
1287       controller you have.
1288     - interrupt-parent : the phandle for the interrupt controller that
1289       services interrupts for this device.
1290     - phy-handle : The phandle for the PHY connected to this ethernet
1291       controller.
1292     - fixed-link : <a b c d e> where a is emulated phy id - choose any,
1293       but unique to the all specified fixed-links, b is duplex - 0 half,
1294       1 full, c is link speed - d#10/d#100/d#1000, d is pause - 0 no
1295       pause, 1 pause, e is asym_pause - 0 no asym_pause, 1 asym_pause.
1297   Recommended properties:
1299     - phy-connection-type : a string naming the controller/PHY interface type,
1300       i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id", "sgmii",
1301       "tbi", or "rtbi".  This property is only really needed if the connection
1302       is of type "rgmii-id", as all other connection types are detected by
1303       hardware.
1306   Example:
1308         ethernet@24000 {
1309                 #size-cells = <0>;
1310                 device_type = "network";
1311                 model = "TSEC";
1312                 compatible = "gianfar";
1313                 reg = <24000 1000>;
1314                 mac-address = [ 00 E0 0C 00 73 00 ];
1315                 interrupts = <d 3 e 3 12 3>;
1316                 interrupt-parent = <40000>;
1317                 phy-handle = <2452000>
1318         };
1322    c) PHY nodes
1324    Required properties:
1326     - device_type : Should be "ethernet-phy"
1327     - interrupts : <a b> where a is the interrupt number and b is a
1328       field that represents an encoding of the sense and level
1329       information for the interrupt.  This should be encoded based on
1330       the information in section 2) depending on the type of interrupt
1331       controller you have.
1332     - interrupt-parent : the phandle for the interrupt controller that
1333       services interrupts for this device.
1334     - reg : The ID number for the phy, usually a small integer
1335     - linux,phandle :  phandle for this node; likely referenced by an
1336       ethernet controller node.
1339    Example:
1341         ethernet-phy@0 {
1342                 linux,phandle = <2452000>
1343                 interrupt-parent = <40000>;
1344                 interrupts = <35 1>;
1345                 reg = <0>;
1346                 device_type = "ethernet-phy";
1347         };
1350    d) Interrupt controllers
1352    Some SOC devices contain interrupt controllers that are different
1353    from the standard Open PIC specification.  The SOC device nodes for
1354    these types of controllers should be specified just like a standard
1355    OpenPIC controller.  Sense and level information should be encoded
1356    as specified in section 2) of this chapter for each device that
1357    specifies an interrupt.
1359    Example :
1361         pic@40000 {
1362                 linux,phandle = <40000>;
1363                 clock-frequency = <0>;
1364                 interrupt-controller;
1365                 #address-cells = <0>;
1366                 reg = <40000 40000>;
1367                 built-in;
1368                 compatible = "chrp,open-pic";
1369                 device_type = "open-pic";
1370                 big-endian;
1371         };
1374    e) I2C
1376    Required properties :
1378     - device_type : Should be "i2c"
1379     - reg : Offset and length of the register set for the device
1381    Recommended properties :
1383     - compatible : Should be "fsl-i2c" for parts compatible with
1384       Freescale I2C specifications.
1385     - interrupts : <a b> where a is the interrupt number and b is a
1386       field that represents an encoding of the sense and level
1387       information for the interrupt.  This should be encoded based on
1388       the information in section 2) depending on the type of interrupt
1389       controller you have.
1390     - interrupt-parent : the phandle for the interrupt controller that
1391       services interrupts for this device.
1392     - dfsrr : boolean; if defined, indicates that this I2C device has
1393       a digital filter sampling rate register
1394     - fsl5200-clocking : boolean; if defined, indicated that this device
1395       uses the FSL 5200 clocking mechanism.
1397    Example :
1399         i2c@3000 {
1400                 interrupt-parent = <40000>;
1401                 interrupts = <1b 3>;
1402                 reg = <3000 18>;
1403                 device_type = "i2c";
1404                 compatible  = "fsl-i2c";
1405                 dfsrr;
1406         };
1409    f) Freescale SOC USB controllers
1411    The device node for a USB controller that is part of a Freescale
1412    SOC is as described in the document "Open Firmware Recommended
1413    Practice : Universal Serial Bus" with the following modifications
1414    and additions :  
1416    Required properties :
1417     - compatible : Should be "fsl-usb2-mph" for multi port host USB
1418       controllers, or "fsl-usb2-dr" for dual role USB controllers
1419     - phy_type : For multi port host USB controllers, should be one of
1420       "ulpi", or "serial". For dual role USB controllers, should be
1421       one of "ulpi", "utmi", "utmi_wide", or "serial".
1422     - reg : Offset and length of the register set for the device
1423     - port0 : boolean; if defined, indicates port0 is connected for
1424       fsl-usb2-mph compatible controllers.  Either this property or
1425       "port1" (or both) must be defined for "fsl-usb2-mph" compatible 
1426       controllers.
1427     - port1 : boolean; if defined, indicates port1 is connected for
1428       fsl-usb2-mph compatible controllers.  Either this property or
1429       "port0" (or both) must be defined for "fsl-usb2-mph" compatible 
1430       controllers.
1431     - dr_mode : indicates the working mode for "fsl-usb2-dr" compatible
1432       controllers.  Can be "host", "peripheral", or "otg".  Default to
1433       "host" if not defined for backward compatibility.
1435    Recommended properties :
1436     - interrupts : <a b> where a is the interrupt number and b is a
1437       field that represents an encoding of the sense and level
1438       information for the interrupt.  This should be encoded based on
1439       the information in section 2) depending on the type of interrupt
1440       controller you have.
1441     - interrupt-parent : the phandle for the interrupt controller that
1442       services interrupts for this device.
1444    Example multi port host USB controller device node :
1445         usb@22000 {
1446                 compatible = "fsl-usb2-mph";
1447                 reg = <22000 1000>;
1448                 #address-cells = <1>;
1449                 #size-cells = <0>;
1450                 interrupt-parent = <700>;
1451                 interrupts = <27 1>;
1452                 phy_type = "ulpi";
1453                 port0;
1454                 port1;
1455         };
1457    Example dual role USB controller device node :
1458         usb@23000 {
1459                 compatible = "fsl-usb2-dr";
1460                 reg = <23000 1000>;
1461                 #address-cells = <1>;
1462                 #size-cells = <0>;
1463                 interrupt-parent = <700>;
1464                 interrupts = <26 1>;
1465                 dr_mode = "otg";
1466                 phy = "ulpi";
1467         };
1470    g) Freescale SOC SEC Security Engines
1472    Required properties:
1474     - device_type : Should be "crypto"
1475     - model : Model of the device.  Should be "SEC1" or "SEC2"
1476     - compatible : Should be "talitos"
1477     - reg : Offset and length of the register set for the device
1478     - interrupts : <a b> where a is the interrupt number and b is a
1479       field that represents an encoding of the sense and level
1480       information for the interrupt.  This should be encoded based on
1481       the information in section 2) depending on the type of interrupt
1482       controller you have.
1483     - interrupt-parent : the phandle for the interrupt controller that
1484       services interrupts for this device.
1485     - num-channels : An integer representing the number of channels
1486       available.
1487     - channel-fifo-len : An integer representing the number of
1488       descriptor pointers each channel fetch fifo can hold.
1489     - exec-units-mask : The bitmask representing what execution units
1490       (EUs) are available. It's a single 32-bit cell. EU information
1491       should be encoded following the SEC's Descriptor Header Dword
1492       EU_SEL0 field documentation, i.e. as follows:
1494         bit 0 = reserved - should be 0
1495         bit 1 = set if SEC has the ARC4 EU (AFEU)
1496         bit 2 = set if SEC has the DES/3DES EU (DEU)
1497         bit 3 = set if SEC has the message digest EU (MDEU)
1498         bit 4 = set if SEC has the random number generator EU (RNG)
1499         bit 5 = set if SEC has the public key EU (PKEU)
1500         bit 6 = set if SEC has the AES EU (AESU)
1501         bit 7 = set if SEC has the Kasumi EU (KEU)
1503       bits 8 through 31 are reserved for future SEC EUs.
1505     - descriptor-types-mask : The bitmask representing what descriptors
1506       are available. It's a single 32-bit cell. Descriptor type
1507       information should be encoded following the SEC's Descriptor
1508       Header Dword DESC_TYPE field documentation, i.e. as follows:
1510         bit 0  = set if SEC supports the aesu_ctr_nonsnoop desc. type
1511         bit 1  = set if SEC supports the ipsec_esp descriptor type
1512         bit 2  = set if SEC supports the common_nonsnoop desc. type
1513         bit 3  = set if SEC supports the 802.11i AES ccmp desc. type
1514         bit 4  = set if SEC supports the hmac_snoop_no_afeu desc. type
1515         bit 5  = set if SEC supports the srtp descriptor type
1516         bit 6  = set if SEC supports the non_hmac_snoop_no_afeu desc.type
1517         bit 7  = set if SEC supports the pkeu_assemble descriptor type
1518         bit 8  = set if SEC supports the aesu_key_expand_output desc.type
1519         bit 9  = set if SEC supports the pkeu_ptmul descriptor type
1520         bit 10 = set if SEC supports the common_nonsnoop_afeu desc. type
1521         bit 11 = set if SEC supports the pkeu_ptadd_dbl descriptor type
1523       ..and so on and so forth.
1525    Example:
1527        /* MPC8548E */
1528        crypto@30000 {
1529                device_type = "crypto";
1530                model = "SEC2";
1531                compatible = "talitos";
1532                reg = <30000 10000>;
1533                interrupts = <1d 3>;
1534                interrupt-parent = <40000>;
1535                num-channels = <4>;
1536                channel-fifo-len = <18>;
1537                exec-units-mask = <000000fe>;
1538                descriptor-types-mask = <012b0ebf>;
1539        };
1541    h) Board Control and Status (BCSR)
1543    Required properties:
1545     - device_type : Should be "board-control"
1546     - reg : Offset and length of the register set for the device
1548     Example:
1550         bcsr@f8000000 {
1551                 device_type = "board-control";
1552                 reg = <f8000000 8000>;
1553         };
1555    i) Freescale QUICC Engine module (QE)
1556    This represents qe module that is installed on PowerQUICC II Pro.
1558    NOTE:  This is an interim binding; it should be updated to fit
1559    in with the CPM binding later in this document.
1561    Basically, it is a bus of devices, that could act more or less
1562    as a complete entity (UCC, USB etc ). All of them should be siblings on
1563    the "root" qe node, using the common properties from there.
1564    The description below applies to the qe of MPC8360 and
1565    more nodes and properties would be extended in the future.
1567    i) Root QE device
1569    Required properties:
1570    - compatible : should be "fsl,qe";
1571    - model : precise model of the QE, Can be "QE", "CPM", or "CPM2"
1572    - reg : offset and length of the device registers.
1573    - bus-frequency : the clock frequency for QUICC Engine.
1575    Recommended properties
1576    - brg-frequency : the internal clock source frequency for baud-rate
1577      generators in Hz.
1579    Example:
1580         qe@e0100000 {
1581                 #address-cells = <1>;
1582                 #size-cells = <1>;
1583                 #interrupt-cells = <2>;
1584                 compatible = "fsl,qe";
1585                 ranges = <0 e0100000 00100000>;
1586                 reg = <e0100000 480>;
1587                 brg-frequency = <0>;
1588                 bus-frequency = <179A7B00>;
1589         }
1592    ii) SPI (Serial Peripheral Interface)
1594    Required properties:
1595    - cell-index : SPI controller index.
1596    - compatible : should be "fsl,spi".
1597    - mode : the SPI operation mode, it can be "cpu" or "cpu-qe".
1598    - reg : Offset and length of the register set for the device
1599    - interrupts : <a b> where a is the interrupt number and b is a
1600      field that represents an encoding of the sense and level
1601      information for the interrupt.  This should be encoded based on
1602      the information in section 2) depending on the type of interrupt
1603      controller you have.
1604    - interrupt-parent : the phandle for the interrupt controller that
1605      services interrupts for this device.
1607    Example:
1608         spi@4c0 {
1609                 cell-index = <0>;
1610                 compatible = "fsl,spi";
1611                 reg = <4c0 40>;
1612                 interrupts = <82 0>;
1613                 interrupt-parent = <700>;
1614                 mode = "cpu";
1615         };
1618    iii) USB (Universal Serial Bus Controller)
1620    Required properties:
1621    - compatible : could be "qe_udc" or "fhci-hcd".
1622    - mode : the could be "host" or "slave".
1623    - reg : Offset and length of the register set for the device
1624    - interrupts : <a b> where a is the interrupt number and b is a
1625      field that represents an encoding of the sense and level
1626      information for the interrupt.  This should be encoded based on
1627      the information in section 2) depending on the type of interrupt
1628      controller you have.
1629    - interrupt-parent : the phandle for the interrupt controller that
1630      services interrupts for this device.
1632    Example(slave):
1633         usb@6c0 {
1634                 compatible = "qe_udc";
1635                 reg = <6c0 40>;
1636                 interrupts = <8b 0>;
1637                 interrupt-parent = <700>;
1638                 mode = "slave";
1639         };
1642    iv) UCC (Unified Communications Controllers)
1644    Required properties:
1645    - device_type : should be "network", "hldc", "uart", "transparent"
1646      "bisync", "atm", or "serial".
1647    - compatible : could be "ucc_geth" or "fsl_atm" and so on.
1648    - cell-index : the ucc number(1-8), corresponding to UCCx in UM.
1649    - reg : Offset and length of the register set for the device
1650    - interrupts : <a b> where a is the interrupt number and b is a
1651      field that represents an encoding of the sense and level
1652      information for the interrupt.  This should be encoded based on
1653      the information in section 2) depending on the type of interrupt
1654      controller you have.
1655    - interrupt-parent : the phandle for the interrupt controller that
1656      services interrupts for this device.
1657    - pio-handle : The phandle for the Parallel I/O port configuration.
1658    - port-number : for UART drivers, the port number to use, between 0 and 3.
1659      This usually corresponds to the /dev/ttyQE device, e.g. <0> = /dev/ttyQE0.
1660      The port number is added to the minor number of the device.  Unlike the
1661      CPM UART driver, the port-number is required for the QE UART driver.
1662    - soft-uart : for UART drivers, if specified this means the QE UART device
1663      driver should use "Soft-UART" mode, which is needed on some SOCs that have
1664      broken UART hardware.  Soft-UART is provided via a microcode upload.
1665    - rx-clock-name: the UCC receive clock source
1666      "none": clock source is disabled
1667      "brg1" through "brg16": clock source is BRG1-BRG16, respectively
1668      "clk1" through "clk24": clock source is CLK1-CLK24, respectively
1669    - tx-clock-name: the UCC transmit clock source
1670      "none": clock source is disabled
1671      "brg1" through "brg16": clock source is BRG1-BRG16, respectively
1672      "clk1" through "clk24": clock source is CLK1-CLK24, respectively
1673    The following two properties are deprecated.  rx-clock has been replaced
1674    with rx-clock-name, and tx-clock has been replaced with tx-clock-name.
1675    Drivers that currently use the deprecated properties should continue to
1676    do so, in order to support older device trees, but they should be updated
1677    to check for the new properties first.
1678    - rx-clock : represents the UCC receive clock source.
1679      0x00 : clock source is disabled;
1680      0x1~0x10 : clock source is BRG1~BRG16 respectively;
1681      0x11~0x28: clock source is QE_CLK1~QE_CLK24 respectively.
1682    - tx-clock: represents the UCC transmit clock source;
1683      0x00 : clock source is disabled;
1684      0x1~0x10 : clock source is BRG1~BRG16 respectively;
1685      0x11~0x28: clock source is QE_CLK1~QE_CLK24 respectively.
1687    Required properties for network device_type:
1688    - mac-address : list of bytes representing the ethernet address.
1689    - phy-handle : The phandle for the PHY connected to this controller.
1691    Recommended properties:
1692    - phy-connection-type : a string naming the controller/PHY interface type,
1693      i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id" (Internal
1694      Delay), "rgmii-txid" (delay on TX only), "rgmii-rxid" (delay on RX only),
1695      "tbi", or "rtbi".
1697    Example:
1698         ucc@2000 {
1699                 device_type = "network";
1700                 compatible = "ucc_geth";
1701                 cell-index = <1>;
1702                 reg = <2000 200>;
1703                 interrupts = <a0 0>;
1704                 interrupt-parent = <700>;
1705                 mac-address = [ 00 04 9f 00 23 23 ];
1706                 rx-clock = "none";
1707                 tx-clock = "clk9";
1708                 phy-handle = <212000>;
1709                 phy-connection-type = "gmii";
1710                 pio-handle = <140001>;
1711         };
1714    v) Parallel I/O Ports
1716    This node configures Parallel I/O ports for CPUs with QE support.
1717    The node should reside in the "soc" node of the tree.  For each
1718    device that using parallel I/O ports, a child node should be created.
1719    See the definition of the Pin configuration nodes below for more
1720    information.
1722    Required properties:
1723    - device_type : should be "par_io".
1724    - reg : offset to the register set and its length.
1725    - num-ports : number of Parallel I/O ports
1727    Example:
1728         par_io@1400 {
1729                 reg = <1400 100>;
1730                 #address-cells = <1>;
1731                 #size-cells = <0>;
1732                 device_type = "par_io";
1733                 num-ports = <7>;
1734                 ucc_pin@01 {
1735                         ......
1736                 };
1739    vi) Pin configuration nodes
1741    Required properties:
1742    - linux,phandle : phandle of this node; likely referenced by a QE
1743      device.
1744    - pio-map : array of pin configurations.  Each pin is defined by 6
1745      integers.  The six numbers are respectively: port, pin, dir,
1746      open_drain, assignment, has_irq.
1747      - port : port number of the pin; 0-6 represent port A-G in UM.
1748      - pin : pin number in the port.
1749      - dir : direction of the pin, should encode as follows:
1751         0 = The pin is disabled
1752         1 = The pin is an output
1753         2 = The pin is an input
1754         3 = The pin is I/O
1756      - open_drain : indicates the pin is normal or wired-OR:
1758         0 = The pin is actively driven as an output
1759         1 = The pin is an open-drain driver. As an output, the pin is
1760             driven active-low, otherwise it is three-stated.
1762      - assignment : function number of the pin according to the Pin Assignment
1763        tables in User Manual.  Each pin can have up to 4 possible functions in
1764        QE and two options for CPM.
1765      - has_irq : indicates if the pin is used as source of external
1766        interrupts.
1768    Example:
1769         ucc_pin@01 {
1770                 linux,phandle = <140001>;
1771                 pio-map = <
1772                 /* port  pin  dir  open_drain  assignment  has_irq */
1773                         0  3  1  0  1  0        /* TxD0 */
1774                         0  4  1  0  1  0        /* TxD1 */
1775                         0  5  1  0  1  0        /* TxD2 */
1776                         0  6  1  0  1  0        /* TxD3 */
1777                         1  6  1  0  3  0        /* TxD4 */
1778                         1  7  1  0  1  0        /* TxD5 */
1779                         1  9  1  0  2  0        /* TxD6 */
1780                         1  a  1  0  2  0        /* TxD7 */
1781                         0  9  2  0  1  0        /* RxD0 */
1782                         0  a  2  0  1  0        /* RxD1 */
1783                         0  b  2  0  1  0        /* RxD2 */
1784                         0  c  2  0  1  0        /* RxD3 */
1785                         0  d  2  0  1  0        /* RxD4 */
1786                         1  1  2  0  2  0        /* RxD5 */
1787                         1  0  2  0  2  0        /* RxD6 */
1788                         1  4  2  0  2  0        /* RxD7 */
1789                         0  7  1  0  1  0        /* TX_EN */
1790                         0  8  1  0  1  0        /* TX_ER */
1791                         0  f  2  0  1  0        /* RX_DV */
1792                         0  10 2  0  1  0        /* RX_ER */
1793                         0  0  2  0  1  0        /* RX_CLK */
1794                         2  9  1  0  3  0        /* GTX_CLK - CLK10 */
1795                         2  8  2  0  1  0>;      /* GTX125 - CLK9 */
1796         };
1798    vii) Multi-User RAM (MURAM)
1800    Required properties:
1801    - compatible : should be "fsl,qe-muram", "fsl,cpm-muram".
1802    - mode : the could be "host" or "slave".
1803    - ranges : Should be defined as specified in 1) to describe the
1804       translation of MURAM addresses.
1805    - data-only : sub-node which defines the address area under MURAM
1806       bus that can be allocated as data/parameter
1808    Example:
1810         muram@10000 {
1811                 compatible = "fsl,qe-muram", "fsl,cpm-muram";
1812                 ranges = <0 00010000 0000c000>;
1814                 data-only@0{
1815                         compatible = "fsl,qe-muram-data",
1816                                      "fsl,cpm-muram-data";
1817                         reg = <0 c000>;
1818                 };
1819         };
1821    viii) Uploaded QE firmware
1823          If a new firwmare has been uploaded to the QE (usually by the
1824          boot loader), then a 'firmware' child node should be added to the QE
1825          node.  This node provides information on the uploaded firmware that
1826          device drivers may need.
1828          Required properties:
1829          - id: The string name of the firmware.  This is taken from the 'id'
1830                member of the qe_firmware structure of the uploaded firmware.
1831                Device drivers can search this string to determine if the
1832                firmware they want is already present.
1833          - extended-modes: The Extended Modes bitfield, taken from the
1834                            firmware binary.  It is a 64-bit number represented
1835                            as an array of two 32-bit numbers.
1836          - virtual-traps: The virtual traps, taken from the firmware binary.
1837                           It is an array of 8 32-bit numbers.
1839          Example:
1841                 firmware {
1842                         id = "Soft-UART";
1843                         extended-modes = <0 0>;
1844                         virtual-traps = <0 0 0 0 0 0 0 0>;
1845                 }
1847    j) CFI or JEDEC memory-mapped NOR flash
1849     Flash chips (Memory Technology Devices) are often used for solid state
1850     file systems on embedded devices.
1852      - compatible : should contain the specific model of flash chip(s)
1853        used, if known, followed by either "cfi-flash" or "jedec-flash"
1854      - reg : Address range of the flash chip
1855      - bank-width : Width (in bytes) of the flash bank.  Equal to the
1856        device width times the number of interleaved chips.
1857      - device-width : (optional) Width of a single flash chip.  If
1858        omitted, assumed to be equal to 'bank-width'.
1859      - #address-cells, #size-cells : Must be present if the flash has
1860        sub-nodes representing partitions (see below).  In this case
1861        both #address-cells and #size-cells must be equal to 1.
1863     For JEDEC compatible devices, the following additional properties
1864     are defined:
1866      - vendor-id : Contains the flash chip's vendor id (1 byte).
1867      - device-id : Contains the flash chip's device id (1 byte).
1869     In addition to the information on the flash bank itself, the
1870     device tree may optionally contain additional information
1871     describing partitions of the flash address space.  This can be
1872     used on platforms which have strong conventions about which
1873     portions of the flash are used for what purposes, but which don't
1874     use an on-flash partition table such as RedBoot.
1876     Each partition is represented as a sub-node of the flash device.
1877     Each node's name represents the name of the corresponding
1878     partition of the flash device.
1880     Flash partitions
1881      - reg : The partition's offset and size within the flash bank.
1882      - label : (optional) The label / name for this flash partition.
1883        If omitted, the label is taken from the node name (excluding
1884        the unit address).
1885      - read-only : (optional) This parameter, if present, is a hint to
1886        Linux that this flash partition should only be mounted
1887        read-only.  This is usually used for flash partitions
1888        containing early-boot firmware images or data which should not
1889        be clobbered.
1891     Example:
1893         flash@ff000000 {
1894                 compatible = "amd,am29lv128ml", "cfi-flash";
1895                 reg = <ff000000 01000000>;
1896                 bank-width = <4>;
1897                 device-width = <1>;
1898                 #address-cells = <1>;
1899                 #size-cells = <1>;
1900                 fs@0 {
1901                         label = "fs";
1902                         reg = <0 f80000>;
1903                 };
1904                 firmware@f80000 {
1905                         label ="firmware";
1906                         reg = <f80000 80000>;
1907                         read-only;
1908                 };
1909         };
1911    k) Global Utilities Block
1913    The global utilities block controls power management, I/O device
1914    enabling, power-on-reset configuration monitoring, general-purpose
1915    I/O signal configuration, alternate function selection for multiplexed
1916    signals, and clock control.
1918    Required properties:
1920     - compatible : Should define the compatible device type for
1921       global-utilities.
1922     - reg : Offset and length of the register set for the device.
1924   Recommended properties:
1926     - fsl,has-rstcr : Indicates that the global utilities register set
1927       contains a functioning "reset control register" (i.e. the board
1928       is wired to reset upon setting the HRESET_REQ bit in this register).
1930     Example:
1932         global-utilities@e0000 {        /* global utilities block */
1933                 compatible = "fsl,mpc8548-guts";
1934                 reg = <e0000 1000>;
1935                 fsl,has-rstcr;
1936         };
1938    l) Freescale Communications Processor Module
1940    NOTE: This is an interim binding, and will likely change slightly,
1941    as more devices are supported.  The QE bindings especially are
1942    incomplete.
1944    i) Root CPM node
1946    Properties:
1947    - compatible : "fsl,cpm1", "fsl,cpm2", or "fsl,qe".
1948    - reg : A 48-byte region beginning with CPCR.
1950    Example:
1951         cpm@119c0 {
1952                 #address-cells = <1>;
1953                 #size-cells = <1>;
1954                 #interrupt-cells = <2>;
1955                 compatible = "fsl,mpc8272-cpm", "fsl,cpm2";
1956                 reg = <119c0 30>;
1957         }
1959    ii) Properties common to mulitple CPM/QE devices
1961    - fsl,cpm-command : This value is ORed with the opcode and command flag
1962                        to specify the device on which a CPM command operates.
1964    - fsl,cpm-brg : Indicates which baud rate generator the device
1965                    is associated with.  If absent, an unused BRG
1966                    should be dynamically allocated.  If zero, the
1967                    device uses an external clock rather than a BRG.
1969    - reg : Unless otherwise specified, the first resource represents the
1970            scc/fcc/ucc registers, and the second represents the device's
1971            parameter RAM region (if it has one).
1973    iii) Serial
1975    Currently defined compatibles:
1976    - fsl,cpm1-smc-uart
1977    - fsl,cpm2-smc-uart
1978    - fsl,cpm1-scc-uart
1979    - fsl,cpm2-scc-uart
1980    - fsl,qe-uart
1982    Example:
1984         serial@11a00 {
1985                 device_type = "serial";
1986                 compatible = "fsl,mpc8272-scc-uart",
1987                              "fsl,cpm2-scc-uart";
1988                 reg = <11a00 20 8000 100>;
1989                 interrupts = <28 8>;
1990                 interrupt-parent = <&PIC>;
1991                 fsl,cpm-brg = <1>;
1992                 fsl,cpm-command = <00800000>;
1993         };
1995    iii) Network
1997    Currently defined compatibles:
1998    - fsl,cpm1-scc-enet
1999    - fsl,cpm2-scc-enet
2000    - fsl,cpm1-fec-enet
2001    - fsl,cpm2-fcc-enet (third resource is GFEMR)
2002    - fsl,qe-enet
2004    Example:
2006         ethernet@11300 {
2007                 device_type = "network";
2008                 compatible = "fsl,mpc8272-fcc-enet",
2009                              "fsl,cpm2-fcc-enet";
2010                 reg = <11300 20 8400 100 11390 1>;
2011                 local-mac-address = [ 00 00 00 00 00 00 ];
2012                 interrupts = <20 8>;
2013                 interrupt-parent = <&PIC>;
2014                 phy-handle = <&PHY0>;
2015                 fsl,cpm-command = <12000300>;
2016         };
2018    iv) MDIO
2020    Currently defined compatibles:
2021    fsl,pq1-fec-mdio (reg is same as first resource of FEC device)
2022    fsl,cpm2-mdio-bitbang (reg is port C registers)
2024    Properties for fsl,cpm2-mdio-bitbang:
2025    fsl,mdio-pin : pin of port C controlling mdio data
2026    fsl,mdc-pin : pin of port C controlling mdio clock
2028    Example:
2030         mdio@10d40 {
2031                 device_type = "mdio";
2032                 compatible = "fsl,mpc8272ads-mdio-bitbang",
2033                              "fsl,mpc8272-mdio-bitbang",
2034                              "fsl,cpm2-mdio-bitbang";
2035                 reg = <10d40 14>;
2036                 #address-cells = <1>;
2037                 #size-cells = <0>;
2038                 fsl,mdio-pin = <12>;
2039                 fsl,mdc-pin = <13>;
2040         };
2042    v) Baud Rate Generators
2044    Currently defined compatibles:
2045    fsl,cpm-brg
2046    fsl,cpm1-brg
2047    fsl,cpm2-brg
2049    Properties:
2050    - reg : There may be an arbitrary number of reg resources; BRG
2051      numbers are assigned to these in order.
2052    - clock-frequency : Specifies the base frequency driving
2053      the BRG.
2055    Example:
2057         brg@119f0 {
2058                 compatible = "fsl,mpc8272-brg",
2059                              "fsl,cpm2-brg",
2060                              "fsl,cpm-brg";
2061                 reg = <119f0 10 115f0 10>;
2062                 clock-frequency = <d#25000000>;
2063         };
2065    vi) Interrupt Controllers
2067    Currently defined compatibles:
2068    - fsl,cpm1-pic
2069      - only one interrupt cell
2070    - fsl,pq1-pic
2071    - fsl,cpm2-pic
2072      - second interrupt cell is level/sense:
2073        - 2 is falling edge
2074        - 8 is active low
2076    Example:
2078         interrupt-controller@10c00 {
2079                 #interrupt-cells = <2>;
2080                 interrupt-controller;
2081                 reg = <10c00 80>;
2082                 compatible = "mpc8272-pic", "fsl,cpm2-pic";
2083         };
2085    vii) USB (Universal Serial Bus Controller)
2087    Properties:
2088    - compatible : "fsl,cpm1-usb", "fsl,cpm2-usb", "fsl,qe-usb"
2090    Example:
2091         usb@11bc0 {
2092                 #address-cells = <1>;
2093                 #size-cells = <0>;
2094                 compatible = "fsl,cpm2-usb";
2095                 reg = <11b60 18 8b00 100>;
2096                 interrupts = <b 8>;
2097                 interrupt-parent = <&PIC>;
2098                 fsl,cpm-command = <2e600000>;
2099         };
2101    viii) Multi-User RAM (MURAM)
2103    The multi-user/dual-ported RAM is expressed as a bus under the CPM node.
2105    Ranges must be set up subject to the following restrictions:
2107    - Children's reg nodes must be offsets from the start of all muram, even
2108      if the user-data area does not begin at zero.
2109    - If multiple range entries are used, the difference between the parent
2110      address and the child address must be the same in all, so that a single
2111      mapping can cover them all while maintaining the ability to determine
2112      CPM-side offsets with pointer subtraction.  It is recommended that
2113      multiple range entries not be used.
2114    - A child address of zero must be translatable, even if no reg resources
2115      contain it.
2117    A child "data" node must exist, compatible with "fsl,cpm-muram-data", to
2118    indicate the portion of muram that is usable by the OS for arbitrary
2119    purposes.  The data node may have an arbitrary number of reg resources,
2120    all of which contribute to the allocatable muram pool.
2122    Example, based on mpc8272:
2124         muram@0 {
2125                 #address-cells = <1>;
2126                 #size-cells = <1>;
2127                 ranges = <0 0 10000>;
2129                 data@0 {
2130                         compatible = "fsl,cpm-muram-data";
2131                         reg = <0 2000 9800 800>;
2132                 };
2133         };
2135    m) Chipselect/Local Bus
2137    Properties:
2138    - name : Should be localbus
2139    - #address-cells : Should be either two or three.  The first cell is the
2140                       chipselect number, and the remaining cells are the
2141                       offset into the chipselect.
2142    - #size-cells : Either one or two, depending on how large each chipselect
2143                    can be.
2144    - ranges : Each range corresponds to a single chipselect, and cover
2145               the entire access window as configured.
2147    Example:
2148         localbus@f0010100 {
2149                 compatible = "fsl,mpc8272-localbus",
2150                              "fsl,pq2-localbus";
2151                 #address-cells = <2>;
2152                 #size-cells = <1>;
2153                 reg = <f0010100 40>;
2155                 ranges = <0 0 fe000000 02000000
2156                           1 0 f4500000 00008000>;
2158                 flash@0,0 {
2159                         compatible = "jedec-flash";
2160                         reg = <0 0 2000000>;
2161                         bank-width = <4>;
2162                         device-width = <1>;
2163                 };
2165                 board-control@1,0 {
2166                         reg = <1 0 20>;
2167                         compatible = "fsl,mpc8272ads-bcsr";
2168                 };
2169         };
2172     n) 4xx/Axon EMAC ethernet nodes
2174     The EMAC ethernet controller in IBM and AMCC 4xx chips, and also
2175     the Axon bridge.  To operate this needs to interact with a ths
2176     special McMAL DMA controller, and sometimes an RGMII or ZMII
2177     interface.  In addition to the nodes and properties described
2178     below, the node for the OPB bus on which the EMAC sits must have a
2179     correct clock-frequency property.
2181       i) The EMAC node itself
2183     Required properties:
2184     - device_type       : "network"
2186     - compatible        : compatible list, contains 2 entries, first is
2187                           "ibm,emac-CHIP" where CHIP is the host ASIC (440gx,
2188                           405gp, Axon) and second is either "ibm,emac" or
2189                           "ibm,emac4".  For Axon, thus, we have: "ibm,emac-axon",
2190                           "ibm,emac4"
2191     - interrupts        : <interrupt mapping for EMAC IRQ and WOL IRQ>
2192     - interrupt-parent  : optional, if needed for interrupt mapping
2193     - reg               : <registers mapping>
2194     - local-mac-address : 6 bytes, MAC address
2195     - mal-device        : phandle of the associated McMAL node
2196     - mal-tx-channel    : 1 cell, index of the tx channel on McMAL associated
2197                           with this EMAC
2198     - mal-rx-channel    : 1 cell, index of the rx channel on McMAL associated
2199                           with this EMAC
2200     - cell-index        : 1 cell, hardware index of the EMAC cell on a given
2201                           ASIC (typically 0x0 and 0x1 for EMAC0 and EMAC1 on
2202                           each Axon chip)
2203     - max-frame-size    : 1 cell, maximum frame size supported in bytes
2204     - rx-fifo-size      : 1 cell, Rx fifo size in bytes for 10 and 100 Mb/sec
2205                           operations.
2206                           For Axon, 2048
2207     - tx-fifo-size      : 1 cell, Tx fifo size in bytes for 10 and 100 Mb/sec
2208                           operations.
2209                           For Axon, 2048.
2210     - fifo-entry-size   : 1 cell, size of a fifo entry (used to calculate
2211                           thresholds).
2212                           For Axon, 0x00000010
2213     - mal-burst-size    : 1 cell, MAL burst size (used to calculate thresholds)
2214                           in bytes.
2215                           For Axon, 0x00000100 (I think ...)
2216     - phy-mode          : string, mode of operations of the PHY interface.
2217                           Supported values are: "mii", "rmii", "smii", "rgmii",
2218                           "tbi", "gmii", rtbi", "sgmii".
2219                           For Axon on CAB, it is "rgmii"
2220     - mdio-device       : 1 cell, required iff using shared MDIO registers
2221                           (440EP).  phandle of the EMAC to use to drive the
2222                           MDIO lines for the PHY used by this EMAC.
2223     - zmii-device       : 1 cell, required iff connected to a ZMII.  phandle of
2224                           the ZMII device node
2225     - zmii-channel      : 1 cell, required iff connected to a ZMII.  Which ZMII
2226                           channel or 0xffffffff if ZMII is only used for MDIO.
2227     - rgmii-device      : 1 cell, required iff connected to an RGMII. phandle
2228                           of the RGMII device node.
2229                           For Axon: phandle of plb5/plb4/opb/rgmii
2230     - rgmii-channel     : 1 cell, required iff connected to an RGMII.  Which
2231                           RGMII channel is used by this EMAC.
2232                           Fox Axon: present, whatever value is appropriate for each
2233                           EMAC, that is the content of the current (bogus) "phy-port"
2234                           property.
2236     Optional properties:
2237     - phy-address       : 1 cell, optional, MDIO address of the PHY. If absent,
2238                           a search is performed.
2239     - phy-map           : 1 cell, optional, bitmap of addresses to probe the PHY
2240                           for, used if phy-address is absent. bit 0x00000001 is
2241                           MDIO address 0.
2242                           For Axon it can be absent, thouugh my current driver
2243                           doesn't handle phy-address yet so for now, keep
2244                           0x00ffffff in it.
2245     - rx-fifo-size-gige : 1 cell, Rx fifo size in bytes for 1000 Mb/sec
2246                           operations (if absent the value is the same as
2247                           rx-fifo-size).  For Axon, either absent or 2048.
2248     - tx-fifo-size-gige : 1 cell, Tx fifo size in bytes for 1000 Mb/sec
2249                           operations (if absent the value is the same as
2250                           tx-fifo-size). For Axon, either absent or 2048.
2251     - tah-device        : 1 cell, optional. If connected to a TAH engine for
2252                           offload, phandle of the TAH device node.
2253     - tah-channel       : 1 cell, optional. If appropriate, channel used on the
2254                           TAH engine.
2256     Example:
2258         EMAC0: ethernet@40000800 {
2259                 device_type = "network";
2260                 compatible = "ibm,emac-440gp", "ibm,emac";
2261                 interrupt-parent = <&UIC1>;
2262                 interrupts = <1c 4 1d 4>;
2263                 reg = <40000800 70>;
2264                 local-mac-address = [00 04 AC E3 1B 1E];
2265                 mal-device = <&MAL0>;
2266                 mal-tx-channel = <0 1>;
2267                 mal-rx-channel = <0>;
2268                 cell-index = <0>;
2269                 max-frame-size = <5dc>;
2270                 rx-fifo-size = <1000>;
2271                 tx-fifo-size = <800>;
2272                 phy-mode = "rmii";
2273                 phy-map = <00000001>;
2274                 zmii-device = <&ZMII0>;
2275                 zmii-channel = <0>;
2276         };
2278       ii) McMAL node
2280     Required properties:
2281     - device_type        : "dma-controller"
2282     - compatible         : compatible list, containing 2 entries, first is
2283                            "ibm,mcmal-CHIP" where CHIP is the host ASIC (like
2284                            emac) and the second is either "ibm,mcmal" or
2285                            "ibm,mcmal2".
2286                            For Axon, "ibm,mcmal-axon","ibm,mcmal2"
2287     - interrupts         : <interrupt mapping for the MAL interrupts sources:
2288                            5 sources: tx_eob, rx_eob, serr, txde, rxde>.
2289                            For Axon: This is _different_ from the current
2290                            firmware.  We use the "delayed" interrupts for txeob
2291                            and rxeob. Thus we end up with mapping those 5 MPIC
2292                            interrupts, all level positive sensitive: 10, 11, 32,
2293                            33, 34 (in decimal)
2294     - dcr-reg            : < DCR registers range >
2295     - dcr-parent         : if needed for dcr-reg
2296     - num-tx-chans       : 1 cell, number of Tx channels
2297     - num-rx-chans       : 1 cell, number of Rx channels
2299       iii) ZMII node
2301     Required properties:
2302     - compatible         : compatible list, containing 2 entries, first is
2303                            "ibm,zmii-CHIP" where CHIP is the host ASIC (like
2304                            EMAC) and the second is "ibm,zmii".
2305                            For Axon, there is no ZMII node.
2306     - reg                : <registers mapping>
2308       iv) RGMII node
2310     Required properties:
2311     - compatible         : compatible list, containing 2 entries, first is
2312                            "ibm,rgmii-CHIP" where CHIP is the host ASIC (like
2313                            EMAC) and the second is "ibm,rgmii".
2314                            For Axon, "ibm,rgmii-axon","ibm,rgmii"
2315     - reg                : <registers mapping>
2316     - revision           : as provided by the RGMII new version register if
2317                            available.
2318                            For Axon: 0x0000012a
2320    o) Xilinx IP cores
2322    The Xilinx EDK toolchain ships with a set of IP cores (devices) for use
2323    in Xilinx Spartan and Virtex FPGAs.  The devices cover the whole range
2324    of standard device types (network, serial, etc.) and miscellanious
2325    devices (gpio, LCD, spi, etc).  Also, since these devices are
2326    implemented within the fpga fabric every instance of the device can be
2327    synthesised with different options that change the behaviour.
2329    Each IP-core has a set of parameters which the FPGA designer can use to
2330    control how the core is synthesized.  Historically, the EDK tool would
2331    extract the device parameters relevant to device drivers and copy them
2332    into an 'xparameters.h' in the form of #define symbols.  This tells the
2333    device drivers how the IP cores are configured, but it requres the kernel
2334    to be recompiled every time the FPGA bitstream is resynthesized.
2336    The new approach is to export the parameters into the device tree and
2337    generate a new device tree each time the FPGA bitstream changes.  The
2338    parameters which used to be exported as #defines will now become
2339    properties of the device node.  In general, device nodes for IP-cores
2340    will take the following form:
2342         (name): (generic-name)@(base-address) {
2343                 compatible = "xlnx,(ip-core-name)-(HW_VER)"
2344                              [, (list of compatible devices), ...];
2345                 reg = <(baseaddr) (size)>;
2346                 interrupt-parent = <&interrupt-controller-phandle>;
2347                 interrupts = < ... >;
2348                 xlnx,(parameter1) = "(string-value)";
2349                 xlnx,(parameter2) = <(int-value)>;
2350         };
2352         (generic-name):   an open firmware-style name that describes the
2353                         generic class of device.  Preferably, this is one word, such
2354                         as 'serial' or 'ethernet'.
2355         (ip-core-name): the name of the ip block (given after the BEGIN
2356                         directive in system.mhs).  Should be in lowercase
2357                         and all underscores '_' converted to dashes '-'.
2358         (name):         is derived from the "PARAMETER INSTANCE" value.
2359         (parameter#):   C_* parameters from system.mhs.  The C_ prefix is
2360                         dropped from the parameter name, the name is converted
2361                         to lowercase and all underscore '_' characters are
2362                         converted to dashes '-'.
2363         (baseaddr):     the baseaddr parameter value (often named C_BASEADDR).
2364         (HW_VER):       from the HW_VER parameter.
2365         (size):         the address range size (often C_HIGHADDR - C_BASEADDR + 1).
2367    Typically, the compatible list will include the exact IP core version
2368    followed by an older IP core version which implements the same
2369    interface or any other device with the same interface.
2371    'reg', 'interrupt-parent' and 'interrupts' are all optional properties.
2373    For example, the following block from system.mhs:
2375         BEGIN opb_uartlite
2376                 PARAMETER INSTANCE = opb_uartlite_0
2377                 PARAMETER HW_VER = 1.00.b
2378                 PARAMETER C_BAUDRATE = 115200
2379                 PARAMETER C_DATA_BITS = 8
2380                 PARAMETER C_ODD_PARITY = 0
2381                 PARAMETER C_USE_PARITY = 0
2382                 PARAMETER C_CLK_FREQ = 50000000
2383                 PARAMETER C_BASEADDR = 0xEC100000
2384                 PARAMETER C_HIGHADDR = 0xEC10FFFF
2385                 BUS_INTERFACE SOPB = opb_7
2386                 PORT OPB_Clk = CLK_50MHz
2387                 PORT Interrupt = opb_uartlite_0_Interrupt
2388                 PORT RX = opb_uartlite_0_RX
2389                 PORT TX = opb_uartlite_0_TX
2390                 PORT OPB_Rst = sys_bus_reset_0
2391         END
2393    becomes the following device tree node:
2395         opb_uartlite_0: serial@ec100000 {
2396                 device_type = "serial";
2397                 compatible = "xlnx,opb-uartlite-1.00.b";
2398                 reg = <ec100000 10000>;
2399                 interrupt-parent = <&opb_intc_0>;
2400                 interrupts = <1 0>; // got this from the opb_intc parameters
2401                 current-speed = <d#115200>;     // standard serial device prop
2402                 clock-frequency = <d#50000000>; // standard serial device prop
2403                 xlnx,data-bits = <8>;
2404                 xlnx,odd-parity = <0>;
2405                 xlnx,use-parity = <0>;
2406         };
2408    Some IP cores actually implement 2 or more logical devices.  In
2409    this case, the device should still describe the whole IP core with
2410    a single node and add a child node for each logical device.  The
2411    ranges property can be used to translate from parent IP-core to the
2412    registers of each device.  In addition, the parent node should be
2413    compatible with the bus type 'xlnx,compound', and should contain
2414    #address-cells and #size-cells, as with any other bus.  (Note: this
2415    makes the assumption that both logical devices have the same bus
2416    binding.  If this is not true, then separate nodes should be used
2417    for each logical device).  The 'cell-index' property can be used to
2418    enumerate logical devices within an IP core.  For example, the
2419    following is the system.mhs entry for the dual ps2 controller found
2420    on the ml403 reference design.
2422         BEGIN opb_ps2_dual_ref
2423                 PARAMETER INSTANCE = opb_ps2_dual_ref_0
2424                 PARAMETER HW_VER = 1.00.a
2425                 PARAMETER C_BASEADDR = 0xA9000000
2426                 PARAMETER C_HIGHADDR = 0xA9001FFF
2427                 BUS_INTERFACE SOPB = opb_v20_0
2428                 PORT Sys_Intr1 = ps2_1_intr
2429                 PORT Sys_Intr2 = ps2_2_intr
2430                 PORT Clkin1 = ps2_clk_rx_1
2431                 PORT Clkin2 = ps2_clk_rx_2
2432                 PORT Clkpd1 = ps2_clk_tx_1
2433                 PORT Clkpd2 = ps2_clk_tx_2
2434                 PORT Rx1 = ps2_d_rx_1
2435                 PORT Rx2 = ps2_d_rx_2
2436                 PORT Txpd1 = ps2_d_tx_1
2437                 PORT Txpd2 = ps2_d_tx_2
2438         END
2440    It would result in the following device tree nodes:
2442         opb_ps2_dual_ref_0: opb-ps2-dual-ref@a9000000 {
2443                 #address-cells = <1>;
2444                 #size-cells = <1>;
2445                 compatible = "xlnx,compound";
2446                 ranges = <0 a9000000 2000>;
2447                 // If this device had extra parameters, then they would
2448                 // go here.
2449                 ps2@0 {
2450                         compatible = "xlnx,opb-ps2-dual-ref-1.00.a";
2451                         reg = <0 40>;
2452                         interrupt-parent = <&opb_intc_0>;
2453                         interrupts = <3 0>;
2454                         cell-index = <0>;
2455                 };
2456                 ps2@1000 {
2457                         compatible = "xlnx,opb-ps2-dual-ref-1.00.a";
2458                         reg = <1000 40>;
2459                         interrupt-parent = <&opb_intc_0>;
2460                         interrupts = <3 0>;
2461                         cell-index = <0>;
2462                 };
2463         };
2465    Also, the system.mhs file defines bus attachments from the processor
2466    to the devices.  The device tree structure should reflect the bus
2467    attachments.  Again an example; this system.mhs fragment:
2469         BEGIN ppc405_virtex4
2470                 PARAMETER INSTANCE = ppc405_0
2471                 PARAMETER HW_VER = 1.01.a
2472                 BUS_INTERFACE DPLB = plb_v34_0
2473                 BUS_INTERFACE IPLB = plb_v34_0
2474         END
2476         BEGIN opb_intc
2477                 PARAMETER INSTANCE = opb_intc_0
2478                 PARAMETER HW_VER = 1.00.c
2479                 PARAMETER C_BASEADDR = 0xD1000FC0
2480                 PARAMETER C_HIGHADDR = 0xD1000FDF
2481                 BUS_INTERFACE SOPB = opb_v20_0
2482         END
2484         BEGIN opb_uart16550
2485                 PARAMETER INSTANCE = opb_uart16550_0
2486                 PARAMETER HW_VER = 1.00.d
2487                 PARAMETER C_BASEADDR = 0xa0000000
2488                 PARAMETER C_HIGHADDR = 0xa0001FFF
2489                 BUS_INTERFACE SOPB = opb_v20_0
2490         END
2492         BEGIN plb_v34
2493                 PARAMETER INSTANCE = plb_v34_0
2494                 PARAMETER HW_VER = 1.02.a
2495         END
2497         BEGIN plb_bram_if_cntlr
2498                 PARAMETER INSTANCE = plb_bram_if_cntlr_0
2499                 PARAMETER HW_VER = 1.00.b
2500                 PARAMETER C_BASEADDR = 0xFFFF0000
2501                 PARAMETER C_HIGHADDR = 0xFFFFFFFF
2502                 BUS_INTERFACE SPLB = plb_v34_0
2503         END
2505         BEGIN plb2opb_bridge
2506                 PARAMETER INSTANCE = plb2opb_bridge_0
2507                 PARAMETER HW_VER = 1.01.a
2508                 PARAMETER C_RNG0_BASEADDR = 0x20000000
2509                 PARAMETER C_RNG0_HIGHADDR = 0x3FFFFFFF
2510                 PARAMETER C_RNG1_BASEADDR = 0x60000000
2511                 PARAMETER C_RNG1_HIGHADDR = 0x7FFFFFFF
2512                 PARAMETER C_RNG2_BASEADDR = 0x80000000
2513                 PARAMETER C_RNG2_HIGHADDR = 0xBFFFFFFF
2514                 PARAMETER C_RNG3_BASEADDR = 0xC0000000
2515                 PARAMETER C_RNG3_HIGHADDR = 0xDFFFFFFF
2516                 BUS_INTERFACE SPLB = plb_v34_0
2517                 BUS_INTERFACE MOPB = opb_v20_0
2518         END
2520    Gives this device tree (some properties removed for clarity):
2522         plb@0 {
2523                 #address-cells = <1>;
2524                 #size-cells = <1>;
2525                 compatible = "xlnx,plb-v34-1.02.a";
2526                 device_type = "ibm,plb";
2527                 ranges; // 1:1 translation
2529                 plb_bram_if_cntrl_0: bram@ffff0000 {
2530                         reg = <ffff0000 10000>;
2531                 }
2533                 opb@20000000 {
2534                         #address-cells = <1>;
2535                         #size-cells = <1>;
2536                         ranges = <20000000 20000000 20000000
2537                                   60000000 60000000 20000000
2538                                   80000000 80000000 40000000
2539                                   c0000000 c0000000 20000000>;
2541                         opb_uart16550_0: serial@a0000000 {
2542                                 reg = <a00000000 2000>;
2543                         };
2545                         opb_intc_0: interrupt-controller@d1000fc0 {
2546                                 reg = <d1000fc0 20>;
2547                         };
2548                 };
2549         };
2551    That covers the general approach to binding xilinx IP cores into the
2552    device tree.  The following are bindings for specific devices:
2554       i) Xilinx ML300 Framebuffer
2556       Simple framebuffer device from the ML300 reference design (also on the
2557       ML403 reference design as well as others).
2559       Optional properties:
2560        - resolution = <xres yres> : pixel resolution of framebuffer.  Some
2561                                     implementations use a different resolution.
2562                                     Default is <d#640 d#480>
2563        - virt-resolution = <xvirt yvirt> : Size of framebuffer in memory.
2564                                            Default is <d#1024 d#480>.
2565        - rotate-display (empty) : rotate display 180 degrees.
2567       ii) Xilinx SystemACE
2569       The Xilinx SystemACE device is used to program FPGAs from an FPGA
2570       bitstream stored on a CF card.  It can also be used as a generic CF
2571       interface device.
2573       Optional properties:
2574        - 8-bit (empty) : Set this property for SystemACE in 8 bit mode
2576       iii) Xilinx EMAC and Xilinx TEMAC
2578       Xilinx Ethernet devices.  In addition to general xilinx properties
2579       listed above, nodes for these devices should include a phy-handle
2580       property, and may include other common network device properties
2581       like local-mac-address.
2582       
2583       iv) Xilinx Uartlite
2585       Xilinx uartlite devices are simple fixed speed serial ports.
2587       Requred properties:
2588        - current-speed : Baud rate of uartlite
2590       v) Xilinx hwicap
2592                 Xilinx hwicap devices provide access to the configuration logic
2593                 of the FPGA through the Internal Configuration Access Port
2594                 (ICAP).  The ICAP enables partial reconfiguration of the FPGA,
2595                 readback of the configuration information, and some control over
2596                 'warm boots' of the FPGA fabric.
2598                 Required properties:
2599                 - xlnx,family : The family of the FPGA, necessary since the
2600                       capabilities of the underlying ICAP hardware
2601                       differ between different families.  May be
2602                       'virtex2p', 'virtex4', or 'virtex5'.
2604       vi) Xilinx Uart 16550
2606       Xilinx UART 16550 devices are very similar to the NS16550 but with
2607       different register spacing and an offset from the base address.
2609       Requred properties:
2610        - clock-frequency : Frequency of the clock input
2611        - reg-offset : A value of 3 is required
2612        - reg-shift : A value of 2 is required
2615     p) Freescale Synchronous Serial Interface
2617        The SSI is a serial device that communicates with audio codecs.  It can
2618        be programmed in AC97, I2S, left-justified, or right-justified modes.
2620        Required properties:
2621        - compatible       : compatible list, containing "fsl,ssi"
2622        - cell-index       : the SSI, <0> = SSI1, <1> = SSI2, and so on
2623        - reg              : offset and length of the register set for the device
2624        - interrupts       : <a b> where a is the interrupt number and b is a
2625                             field that represents an encoding of the sense and
2626                             level information for the interrupt.  This should be
2627                             encoded based on the information in section 2)
2628                             depending on the type of interrupt controller you
2629                             have.
2630        - interrupt-parent : the phandle for the interrupt controller that
2631                             services interrupts for this device.
2632        - fsl,mode         : the operating mode for the SSI interface
2633                             "i2s-slave" - I2S mode, SSI is clock slave
2634                             "i2s-master" - I2S mode, SSI is clock master
2635                             "lj-slave" - left-justified mode, SSI is clock slave
2636                             "lj-master" - l.j. mode, SSI is clock master
2637                             "rj-slave" - right-justified mode, SSI is clock slave
2638                             "rj-master" - r.j., SSI is clock master
2639                             "ac97-slave" - AC97 mode, SSI is clock slave
2640                             "ac97-master" - AC97 mode, SSI is clock master
2642        Optional properties:
2643        - codec-handle     : phandle to a 'codec' node that defines an audio
2644                             codec connected to this SSI.  This node is typically
2645                             a child of an I2C or other control node.
2647        Child 'codec' node required properties:
2648        - compatible       : compatible list, contains the name of the codec
2650        Child 'codec' node optional properties:
2651        - clock-frequency  : The frequency of the input clock, which typically
2652                             comes from an on-board dedicated oscillator.
2654     * Freescale 83xx DMA Controller
2656     Freescale PowerPC 83xx have on chip general purpose DMA controllers.
2658     Required properties:
2660     - compatible        : compatible list, contains 2 entries, first is
2661                          "fsl,CHIP-dma", where CHIP is the processor
2662                          (mpc8349, mpc8360, etc.) and the second is
2663                          "fsl,elo-dma"
2664     - reg               : <registers mapping for DMA general status reg>
2665     - ranges            : Should be defined as specified in 1) to describe the
2666                           DMA controller channels.
2667     - cell-index        : controller index.  0 for controller @ 0x8100
2668     - interrupts        : <interrupt mapping for DMA IRQ>
2669     - interrupt-parent  : optional, if needed for interrupt mapping
2672     - DMA channel nodes:
2673             - compatible        : compatible list, contains 2 entries, first is
2674                                  "fsl,CHIP-dma-channel", where CHIP is the processor
2675                                  (mpc8349, mpc8350, etc.) and the second is
2676                                  "fsl,elo-dma-channel"
2677             - reg               : <registers mapping for channel>
2678             - cell-index        : dma channel index starts at 0.
2680     Optional properties:
2681             - interrupts        : <interrupt mapping for DMA channel IRQ>
2682                                   (on 83xx this is expected to be identical to
2683                                    the interrupts property of the parent node)
2684             - interrupt-parent  : optional, if needed for interrupt mapping
2686   Example:
2687         dma@82a8 {
2688                 #address-cells = <1>;
2689                 #size-cells = <1>;
2690                 compatible = "fsl,mpc8349-dma", "fsl,elo-dma";
2691                 reg = <82a8 4>;
2692                 ranges = <0 8100 1a4>;
2693                 interrupt-parent = <&ipic>;
2694                 interrupts = <47 8>;
2695                 cell-index = <0>;
2696                 dma-channel@0 {
2697                         compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel";
2698                         cell-index = <0>;
2699                         reg = <0 80>;
2700                 };
2701                 dma-channel@80 {
2702                         compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel";
2703                         cell-index = <1>;
2704                         reg = <80 80>;
2705                 };
2706                 dma-channel@100 {
2707                         compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel";
2708                         cell-index = <2>;
2709                         reg = <100 80>;
2710                 };
2711                 dma-channel@180 {
2712                         compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel";
2713                         cell-index = <3>;
2714                         reg = <180 80>;
2715                 };
2716         };
2718    * Freescale 85xx/86xx DMA Controller
2720     Freescale PowerPC 85xx/86xx have on chip general purpose DMA controllers.
2722     Required properties:
2724     - compatible        : compatible list, contains 2 entries, first is
2725                          "fsl,CHIP-dma", where CHIP is the processor
2726                          (mpc8540, mpc8540, etc.) and the second is
2727                          "fsl,eloplus-dma"
2728     - reg               : <registers mapping for DMA general status reg>
2729     - cell-index        : controller index.  0 for controller @ 0x21000,
2730                                              1 for controller @ 0xc000
2731     - ranges            : Should be defined as specified in 1) to describe the
2732                           DMA controller channels.
2734     - DMA channel nodes:
2735             - compatible        : compatible list, contains 2 entries, first is
2736                                  "fsl,CHIP-dma-channel", where CHIP is the processor
2737                                  (mpc8540, mpc8560, etc.) and the second is
2738                                  "fsl,eloplus-dma-channel"
2739             - cell-index        : dma channel index starts at 0.
2740             - reg               : <registers mapping for channel>
2741             - interrupts        : <interrupt mapping for DMA channel IRQ>
2742             - interrupt-parent  : optional, if needed for interrupt mapping
2744   Example:
2745         dma@21300 {
2746                 #address-cells = <1>;
2747                 #size-cells = <1>;
2748                 compatible = "fsl,mpc8540-dma", "fsl,eloplus-dma";
2749                 reg = <21300 4>;
2750                 ranges = <0 21100 200>;
2751                 cell-index = <0>;
2752                 dma-channel@0 {
2753                         compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel";
2754                         reg = <0 80>;
2755                         cell-index = <0>;
2756                         interrupt-parent = <&mpic>;
2757                         interrupts = <14 2>;
2758                 };
2759                 dma-channel@80 {
2760                         compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel";
2761                         reg = <80 80>;
2762                         cell-index = <1>;
2763                         interrupt-parent = <&mpic>;
2764                         interrupts = <15 2>;
2765                 };
2766                 dma-channel@100 {
2767                         compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel";
2768                         reg = <100 80>;
2769                         cell-index = <2>;
2770                         interrupt-parent = <&mpic>;
2771                         interrupts = <16 2>;
2772                 };
2773                 dma-channel@180 {
2774                         compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel";
2775                         reg = <180 80>;
2776                         cell-index = <3>;
2777                         interrupt-parent = <&mpic>;
2778                         interrupts = <17 2>;
2779                 };
2780         };
2782     * Freescale 8xxx/3.0 Gb/s SATA nodes
2784     SATA nodes are defined to describe on-chip Serial ATA controllers.
2785     Each SATA port should have its own node.
2787     Required properties:
2788     - compatible        : compatible list, contains 2 entries, first is
2789                          "fsl,CHIP-sata", where CHIP is the processor
2790                          (mpc8315, mpc8379, etc.) and the second is
2791                          "fsl,pq-sata"
2792     - interrupts        : <interrupt mapping for SATA IRQ>
2793     - cell-index        : controller index.
2794                               1 for controller @ 0x18000
2795                               2 for controller @ 0x19000
2796                               3 for controller @ 0x1a000
2797                               4 for controller @ 0x1b000
2799     Optional properties:
2800     - interrupt-parent  : optional, if needed for interrupt mapping
2801     - reg               : <registers mapping>
2803    Example:
2805         sata@18000 {
2806                 compatible = "fsl,mpc8379-sata", "fsl,pq-sata";
2807                 reg = <0x18000 0x1000>;
2808                 cell-index = <1>;
2809                 interrupts = <2c 8>;
2810                 interrupt-parent = < &ipic >;
2811         };
2813     q) USB EHCI controllers
2815     Required properties:
2816       - compatible : should be "usb-ehci".
2817       - reg : should contain at least address and length of the standard EHCI
2818         register set for the device. Optional platform-dependent registers
2819         (debug-port or other) can be also specified here, but only after
2820         definition of standard EHCI registers.
2821       - interrupts : one EHCI interrupt should be described here.
2822     If device registers are implemented in big endian mode, the device
2823     node should have "big-endian-regs" property.
2824     If controller implementation operates with big endian descriptors,
2825     "big-endian-desc" property should be specified.
2826     If both big endian registers and descriptors are used by the controller
2827     implementation, "big-endian" property can be specified instead of having
2828     both "big-endian-regs" and "big-endian-desc".
2830      Example (Sequoia 440EPx):
2831             ehci@e0000300 {
2832                    compatible = "ibm,usb-ehci-440epx", "usb-ehci";
2833                    interrupt-parent = <&UIC0>;
2834                    interrupts = <1a 4>;
2835                    reg = <0 e0000300 90 0 e0000390 70>;
2836                    big-endian;
2837            };
2839     r) Freescale Display Interface Unit
2841     The Freescale DIU is a LCD controller, with proper hardware, it can also
2842     drive DVI monitors.
2844     Required properties:
2845     - compatible : should be "fsl-diu".
2846     - reg : should contain at least address and length of the DIU register
2847       set.
2848     - Interrupts : one DIU interrupt should be describe here.
2850     Example (MPC8610HPCD)
2851         display@2c000 {
2852                 compatible = "fsl,diu";
2853                 reg = <0x2c000 100>;
2854                 interrupts = <72 2>;
2855                 interrupt-parent = <&mpic>;
2856         };
2858     s) Freescale on board FPGA
2860     This is the memory-mapped registers for on board FPGA.
2862     Required properities:
2863     - compatible : should be "fsl,fpga-pixis".
2864     - reg : should contain the address and the lenght of the FPPGA register
2865       set.
2867     Example (MPC8610HPCD)
2868         board-control@e8000000 {
2869                 compatible = "fsl,fpga-pixis";
2870                 reg = <0xe8000000 32>;
2871         };
2873 VII - Marvell Discovery mv64[345]6x System Controller chips
2874 ===========================================================
2876 The Marvell mv64[345]60 series of system controller chips contain
2877 many of the peripherals needed to implement a complete computer
2878 system.  In this section, we define device tree nodes to describe
2879 the system controller chip itself and each of the peripherals
2880 which it contains.  Compatible string values for each node are
2881 prefixed with the string "marvell,", for Marvell Technology Group Ltd.
2883 1) The /system-controller node
2885   This node is used to represent the system-controller and must be
2886   present when the system uses a system contller chip. The top-level
2887   system-controller node contains information that is global to all
2888   devices within the system controller chip. The node name begins
2889   with "system-controller" followed by the unit address, which is
2890   the base address of the memory-mapped register set for the system
2891   controller chip.
2893   Required properties:
2895     - ranges : Describes the translation of system controller addresses
2896       for memory mapped registers.
2897     - clock-frequency: Contains the main clock frequency for the system
2898       controller chip.
2899     - reg : This property defines the address and size of the
2900       memory-mapped registers contained within the system controller
2901       chip.  The address specified in the "reg" property should match
2902       the unit address of the system-controller node.
2903     - #address-cells : Address representation for system controller
2904       devices.  This field represents the number of cells needed to
2905       represent the address of the memory-mapped registers of devices
2906       within the system controller chip.
2907     - #size-cells : Size representation for for the memory-mapped
2908       registers within the system controller chip.
2909     - #interrupt-cells : Defines the width of cells used to represent
2910       interrupts.
2912   Optional properties:
2914     - model : The specific model of the system controller chip.  Such
2915       as, "mv64360", "mv64460", or "mv64560".
2916     - compatible : A string identifying the compatibility identifiers
2917       of the system controller chip.
2919   The system-controller node contains child nodes for each system
2920   controller device that the platform uses.  Nodes should not be created
2921   for devices which exist on the system controller chip but are not used
2923   Example Marvell Discovery mv64360 system-controller node:
2925     system-controller@f1000000 { /* Marvell Discovery mv64360 */
2926             #address-cells = <1>;
2927             #size-cells = <1>;
2928             model = "mv64360";                      /* Default */
2929             compatible = "marvell,mv64360";
2930             clock-frequency = <133333333>;
2931             reg = <0xf1000000 0x10000>;
2932             virtual-reg = <0xf1000000>;
2933             ranges = <0x88000000 0x88000000 0x1000000 /* PCI 0 I/O Space */
2934                     0x80000000 0x80000000 0x8000000 /* PCI 0 MEM Space */
2935                     0xa0000000 0xa0000000 0x4000000 /* User FLASH */
2936                     0x00000000 0xf1000000 0x0010000 /* Bridge's regs */
2937                     0xf2000000 0xf2000000 0x0040000>;/* Integrated SRAM */
2939             [ child node definitions... ]
2940     }
2942 2) Child nodes of /system-controller
2944    a) Marvell Discovery MDIO bus
2946    The MDIO is a bus to which the PHY devices are connected.  For each
2947    device that exists on this bus, a child node should be created.  See
2948    the definition of the PHY node below for an example of how to define
2949    a PHY.
2951    Required properties:
2952      - #address-cells : Should be <1>
2953      - #size-cells : Should be <0>
2954      - device_type : Should be "mdio"
2955      - compatible : Should be "marvell,mv64360-mdio"
2957    Example:
2959      mdio {
2960              #address-cells = <1>;
2961              #size-cells = <0>;
2962              device_type = "mdio";
2963              compatible = "marvell,mv64360-mdio";
2965              ethernet-phy@0 {
2966                      ......
2967              };
2968      };
2971    b) Marvell Discovery ethernet controller
2973    The Discover ethernet controller is described with two levels
2974    of nodes.  The first level describes an ethernet silicon block
2975    and the second level describes up to 3 ethernet nodes within
2976    that block.  The reason for the multiple levels is that the
2977    registers for the node are interleaved within a single set
2978    of registers.  The "ethernet-block" level describes the
2979    shared register set, and the "ethernet" nodes describe ethernet
2980    port-specific properties.
2982    Ethernet block node
2984    Required properties:
2985      - #address-cells : <1>
2986      - #size-cells : <0>
2987      - compatible : "marvell,mv64360-eth-block"
2988      - reg : Offset and length of the register set for this block
2990    Example Discovery Ethernet block node:
2991      ethernet-block@2000 {
2992              #address-cells = <1>;
2993              #size-cells = <0>;
2994              compatible = "marvell,mv64360-eth-block";
2995              reg = <0x2000 0x2000>;
2996              ethernet@0 {
2997                      .......
2998              };
2999      };
3001    Ethernet port node
3003    Required properties:
3004      - device_type : Should be "network".
3005      - compatible : Should be "marvell,mv64360-eth".
3006      - reg : Should be <0>, <1>, or <2>, according to which registers
3007        within the silicon block the device uses.
3008      - interrupts : <a> where a is the interrupt number for the port.
3009      - interrupt-parent : the phandle for the interrupt controller
3010        that services interrupts for this device.
3011      - phy : the phandle for the PHY connected to this ethernet
3012        controller.
3013      - local-mac-address : 6 bytes, MAC address
3015    Example Discovery Ethernet port node:
3016      ethernet@0 {
3017              device_type = "network";
3018              compatible = "marvell,mv64360-eth";
3019              reg = <0>;
3020              interrupts = <32>;
3021              interrupt-parent = <&PIC>;
3022              phy = <&PHY0>;
3023              local-mac-address = [ 00 00 00 00 00 00 ];
3024      };
3028    c) Marvell Discovery PHY nodes
3030    Required properties:
3031      - device_type : Should be "ethernet-phy"
3032      - interrupts : <a> where a is the interrupt number for this phy.
3033      - interrupt-parent : the phandle for the interrupt controller that
3034        services interrupts for this device.
3035      - reg : The ID number for the phy, usually a small integer
3037    Example Discovery PHY node:
3038      ethernet-phy@1 {
3039              device_type = "ethernet-phy";
3040              compatible = "broadcom,bcm5421";
3041              interrupts = <76>;      /* GPP 12 */
3042              interrupt-parent = <&PIC>;
3043              reg = <1>;
3044      };
3047    d) Marvell Discovery SDMA nodes
3049    Represent DMA hardware associated with the MPSC (multiprotocol
3050    serial controllers).
3052    Required properties:
3053      - compatible : "marvell,mv64360-sdma"
3054      - reg : Offset and length of the register set for this device
3055      - interrupts : <a> where a is the interrupt number for the DMA
3056        device.
3057      - interrupt-parent : the phandle for the interrupt controller
3058        that services interrupts for this device.
3060    Example Discovery SDMA node:
3061      sdma@4000 {
3062              compatible = "marvell,mv64360-sdma";
3063              reg = <0x4000 0xc18>;
3064              virtual-reg = <0xf1004000>;
3065              interrupts = <36>;
3066              interrupt-parent = <&PIC>;
3067      };
3070    e) Marvell Discovery BRG nodes
3072    Represent baud rate generator hardware associated with the MPSC
3073    (multiprotocol serial controllers).
3075    Required properties:
3076      - compatible : "marvell,mv64360-brg"
3077      - reg : Offset and length of the register set for this device
3078      - clock-src : A value from 0 to 15 which selects the clock
3079        source for the baud rate generator.  This value corresponds
3080        to the CLKS value in the BRGx configuration register.  See
3081        the mv64x60 User's Manual.
3082      - clock-frequence : The frequency (in Hz) of the baud rate
3083        generator's input clock.
3084      - current-speed : The current speed setting (presumably by
3085        firmware) of the baud rate generator.
3087    Example Discovery BRG node:
3088      brg@b200 {
3089              compatible = "marvell,mv64360-brg";
3090              reg = <0xb200 0x8>;
3091              clock-src = <8>;
3092              clock-frequency = <133333333>;
3093              current-speed = <9600>;
3094      };
3097    f) Marvell Discovery CUNIT nodes
3099    Represent the Serial Communications Unit device hardware.
3101    Required properties:
3102      - reg : Offset and length of the register set for this device
3104    Example Discovery CUNIT node:
3105      cunit@f200 {
3106              reg = <0xf200 0x200>;
3107      };
3110    g) Marvell Discovery MPSCROUTING nodes
3112    Represent the Discovery's MPSC routing hardware
3114    Required properties:
3115      - reg : Offset and length of the register set for this device
3117    Example Discovery CUNIT node:
3118      mpscrouting@b500 {
3119              reg = <0xb400 0xc>;
3120      };
3123    h) Marvell Discovery MPSCINTR nodes
3125    Represent the Discovery's MPSC DMA interrupt hardware registers
3126    (SDMA cause and mask registers).
3128    Required properties:
3129      - reg : Offset and length of the register set for this device
3131    Example Discovery MPSCINTR node:
3132      mpsintr@b800 {
3133              reg = <0xb800 0x100>;
3134      };
3137    i) Marvell Discovery MPSC nodes
3139    Represent the Discovery's MPSC (Multiprotocol Serial Controller)
3140    serial port.
3142    Required properties:
3143      - device_type : "serial"
3144      - compatible : "marvell,mv64360-mpsc"
3145      - reg : Offset and length of the register set for this device
3146      - sdma : the phandle for the SDMA node used by this port
3147      - brg : the phandle for the BRG node used by this port
3148      - cunit : the phandle for the CUNIT node used by this port
3149      - mpscrouting : the phandle for the MPSCROUTING node used by this port
3150      - mpscintr : the phandle for the MPSCINTR node used by this port
3151      - cell-index : the hardware index of this cell in the MPSC core
3152      - max_idle : value needed for MPSC CHR3 (Maximum Frame Length)
3153        register
3154      - interrupts : <a> where a is the interrupt number for the MPSC.
3155      - interrupt-parent : the phandle for the interrupt controller
3156        that services interrupts for this device.
3158    Example Discovery MPSCINTR node:
3159      mpsc@8000 {
3160              device_type = "serial";
3161              compatible = "marvell,mv64360-mpsc";
3162              reg = <0x8000 0x38>;
3163              virtual-reg = <0xf1008000>;
3164              sdma = <&SDMA0>;
3165              brg = <&BRG0>;
3166              cunit = <&CUNIT>;
3167              mpscrouting = <&MPSCROUTING>;
3168              mpscintr = <&MPSCINTR>;
3169              cell-index = <0>;
3170              max_idle = <40>;
3171              interrupts = <40>;
3172              interrupt-parent = <&PIC>;
3173      };
3176    j) Marvell Discovery Watch Dog Timer nodes
3178    Represent the Discovery's watchdog timer hardware
3180    Required properties:
3181      - compatible : "marvell,mv64360-wdt"
3182      - reg : Offset and length of the register set for this device
3184    Example Discovery Watch Dog Timer node:
3185      wdt@b410 {
3186              compatible = "marvell,mv64360-wdt";
3187              reg = <0xb410 0x8>;
3188      };
3191    k) Marvell Discovery I2C nodes
3193    Represent the Discovery's I2C hardware
3195    Required properties:
3196      - device_type : "i2c"
3197      - compatible : "marvell,mv64360-i2c"
3198      - reg : Offset and length of the register set for this device
3199      - interrupts : <a> where a is the interrupt number for the I2C.
3200      - interrupt-parent : the phandle for the interrupt controller
3201        that services interrupts for this device.
3203    Example Discovery I2C node:
3204              compatible = "marvell,mv64360-i2c";
3205              reg = <0xc000 0x20>;
3206              virtual-reg = <0xf100c000>;
3207              interrupts = <37>;
3208              interrupt-parent = <&PIC>;
3209      };
3212    l) Marvell Discovery PIC (Programmable Interrupt Controller) nodes
3214    Represent the Discovery's PIC hardware
3216    Required properties:
3217      - #interrupt-cells : <1>
3218      - #address-cells : <0>
3219      - compatible : "marvell,mv64360-pic"
3220      - reg : Offset and length of the register set for this device
3221      - interrupt-controller
3223    Example Discovery PIC node:
3224      pic {
3225              #interrupt-cells = <1>;
3226              #address-cells = <0>;
3227              compatible = "marvell,mv64360-pic";
3228              reg = <0x0 0x88>;
3229              interrupt-controller;
3230      };
3233    m) Marvell Discovery MPP (Multipurpose Pins) multiplexing nodes
3235    Represent the Discovery's MPP hardware
3237    Required properties:
3238      - compatible : "marvell,mv64360-mpp"
3239      - reg : Offset and length of the register set for this device
3241    Example Discovery MPP node:
3242      mpp@f000 {
3243              compatible = "marvell,mv64360-mpp";
3244              reg = <0xf000 0x10>;
3245      };
3248    n) Marvell Discovery GPP (General Purpose Pins) nodes
3250    Represent the Discovery's GPP hardware
3252    Required properties:
3253      - compatible : "marvell,mv64360-gpp"
3254      - reg : Offset and length of the register set for this device
3256    Example Discovery GPP node:
3257      gpp@f000 {
3258              compatible = "marvell,mv64360-gpp";
3259              reg = <0xf100 0x20>;
3260      };
3263    o) Marvell Discovery PCI host bridge node
3265    Represents the Discovery's PCI host bridge device.  The properties
3266    for this node conform to Rev 2.1 of the PCI Bus Binding to IEEE
3267    1275-1994.  A typical value for the compatible property is
3268    "marvell,mv64360-pci".
3270    Example Discovery PCI host bridge node
3271      pci@80000000 {
3272              #address-cells = <3>;
3273              #size-cells = <2>;
3274              #interrupt-cells = <1>;
3275              device_type = "pci";
3276              compatible = "marvell,mv64360-pci";
3277              reg = <0xcf8 0x8>;
3278              ranges = <0x01000000 0x0        0x0
3279                              0x88000000 0x0 0x01000000
3280                        0x02000000 0x0 0x80000000
3281                              0x80000000 0x0 0x08000000>;
3282              bus-range = <0 255>;
3283              clock-frequency = <66000000>;
3284              interrupt-parent = <&PIC>;
3285              interrupt-map-mask = <0xf800 0x0 0x0 0x7>;
3286              interrupt-map = <
3287                      /* IDSEL 0x0a */
3288                      0x5000 0 0 1 &PIC 80
3289                      0x5000 0 0 2 &PIC 81
3290                      0x5000 0 0 3 &PIC 91
3291                      0x5000 0 0 4 &PIC 93
3293                      /* IDSEL 0x0b */
3294                      0x5800 0 0 1 &PIC 91
3295                      0x5800 0 0 2 &PIC 93
3296                      0x5800 0 0 3 &PIC 80
3297                      0x5800 0 0 4 &PIC 81
3299                      /* IDSEL 0x0c */
3300                      0x6000 0 0 1 &PIC 91
3301                      0x6000 0 0 2 &PIC 93
3302                      0x6000 0 0 3 &PIC 80
3303                      0x6000 0 0 4 &PIC 81
3305                      /* IDSEL 0x0d */
3306                      0x6800 0 0 1 &PIC 93
3307                      0x6800 0 0 2 &PIC 80
3308                      0x6800 0 0 3 &PIC 81
3309                      0x6800 0 0 4 &PIC 91
3310              >;
3311      };
3314    p) Marvell Discovery CPU Error nodes
3316    Represent the Discovery's CPU error handler device.
3318    Required properties:
3319      - compatible : "marvell,mv64360-cpu-error"
3320      - reg : Offset and length of the register set for this device
3321      - interrupts : the interrupt number for this device
3322      - interrupt-parent : the phandle for the interrupt controller
3323        that services interrupts for this device.
3325    Example Discovery CPU Error node:
3326      cpu-error@0070 {
3327              compatible = "marvell,mv64360-cpu-error";
3328              reg = <0x70 0x10 0x128 0x28>;
3329              interrupts = <3>;
3330              interrupt-parent = <&PIC>;
3331      };
3334    q) Marvell Discovery SRAM Controller nodes
3336    Represent the Discovery's SRAM controller device.
3338    Required properties:
3339      - compatible : "marvell,mv64360-sram-ctrl"
3340      - reg : Offset and length of the register set for this device
3341      - interrupts : the interrupt number for this device
3342      - interrupt-parent : the phandle for the interrupt controller
3343        that services interrupts for this device.
3345    Example Discovery SRAM Controller node:
3346      sram-ctrl@0380 {
3347              compatible = "marvell,mv64360-sram-ctrl";
3348              reg = <0x380 0x80>;
3349              interrupts = <13>;
3350              interrupt-parent = <&PIC>;
3351      };
3354    r) Marvell Discovery PCI Error Handler nodes
3356    Represent the Discovery's PCI error handler device.
3358    Required properties:
3359      - compatible : "marvell,mv64360-pci-error"
3360      - reg : Offset and length of the register set for this device
3361      - interrupts : the interrupt number for this device
3362      - interrupt-parent : the phandle for the interrupt controller
3363        that services interrupts for this device.
3365    Example Discovery PCI Error Handler node:
3366      pci-error@1d40 {
3367              compatible = "marvell,mv64360-pci-error";
3368              reg = <0x1d40 0x40 0xc28 0x4>;
3369              interrupts = <12>;
3370              interrupt-parent = <&PIC>;
3371      };
3374    s) Marvell Discovery Memory Controller nodes
3376    Represent the Discovery's memory controller device.
3378    Required properties:
3379      - compatible : "marvell,mv64360-mem-ctrl"
3380      - reg : Offset and length of the register set for this device
3381      - interrupts : the interrupt number for this device
3382      - interrupt-parent : the phandle for the interrupt controller
3383        that services interrupts for this device.
3385    Example Discovery Memory Controller node:
3386      mem-ctrl@1400 {
3387              compatible = "marvell,mv64360-mem-ctrl";
3388              reg = <0x1400 0x60>;
3389              interrupts = <17>;
3390              interrupt-parent = <&PIC>;
3391      };
3394 VIII - Specifying interrupt information for devices
3395 ===================================================
3397 The device tree represents the busses and devices of a hardware
3398 system in a form similar to the physical bus topology of the
3399 hardware.
3401 In addition, a logical 'interrupt tree' exists which represents the
3402 hierarchy and routing of interrupts in the hardware.
3404 The interrupt tree model is fully described in the
3405 document "Open Firmware Recommended Practice: Interrupt
3406 Mapping Version 0.9".  The document is available at:
3407 <http://playground.sun.com/1275/practice>.
3409 1) interrupts property
3410 ----------------------
3412 Devices that generate interrupts to a single interrupt controller
3413 should use the conventional OF representation described in the
3414 OF interrupt mapping documentation.
3416 Each device which generates interrupts must have an 'interrupt'
3417 property.  The interrupt property value is an arbitrary number of
3418 of 'interrupt specifier' values which describe the interrupt or
3419 interrupts for the device.
3421 The encoding of an interrupt specifier is determined by the
3422 interrupt domain in which the device is located in the
3423 interrupt tree.  The root of an interrupt domain specifies in
3424 its #interrupt-cells property the number of 32-bit cells
3425 required to encode an interrupt specifier.  See the OF interrupt
3426 mapping documentation for a detailed description of domains.
3428 For example, the binding for the OpenPIC interrupt controller
3429 specifies  an #interrupt-cells value of 2 to encode the interrupt
3430 number and level/sense information. All interrupt children in an
3431 OpenPIC interrupt domain use 2 cells per interrupt in their interrupts
3432 property.
3434 The PCI bus binding specifies a #interrupt-cell value of 1 to encode
3435 which interrupt pin (INTA,INTB,INTC,INTD) is used.
3437 2) interrupt-parent property
3438 ----------------------------
3440 The interrupt-parent property is specified to define an explicit
3441 link between a device node and its interrupt parent in
3442 the interrupt tree.  The value of interrupt-parent is the
3443 phandle of the parent node.
3445 If the interrupt-parent property is not defined for a node, it's
3446 interrupt parent is assumed to be an ancestor in the node's
3447 _device tree_ hierarchy.
3449 3) OpenPIC Interrupt Controllers
3450 --------------------------------
3452 OpenPIC interrupt controllers require 2 cells to encode
3453 interrupt information.  The first cell defines the interrupt
3454 number.  The second cell defines the sense and level
3455 information.
3457 Sense and level information should be encoded as follows:
3459         0 = low to high edge sensitive type enabled
3460         1 = active low level sensitive type enabled
3461         2 = active high level sensitive type enabled
3462         3 = high to low edge sensitive type enabled
3464 4) ISA Interrupt Controllers
3465 ----------------------------
3467 ISA PIC interrupt controllers require 2 cells to encode
3468 interrupt information.  The first cell defines the interrupt
3469 number.  The second cell defines the sense and level
3470 information.
3472 ISA PIC interrupt controllers should adhere to the ISA PIC
3473 encodings listed below:
3475         0 =  active low level sensitive type enabled
3476         1 =  active high level sensitive type enabled
3477         2 =  high to low edge sensitive type enabled
3478         3 =  low to high edge sensitive type enabled
3480 VIII - Specifying GPIO information for devices
3481 ==============================================
3483 1) gpios property
3484 -----------------
3486 Nodes that makes use of GPIOs should define them using `gpios' property,
3487 format of which is: <&gpio-controller1-phandle gpio1-specifier
3488                      &gpio-controller2-phandle gpio2-specifier
3489                      0 /* holes are permitted, means no GPIO 3 */
3490                      &gpio-controller4-phandle gpio4-specifier
3491                      ...>;
3493 Note that gpio-specifier length is controller dependent.
3495 gpio-specifier may encode: bank, pin position inside the bank,
3496 whether pin is open-drain and whether pin is logically inverted.
3498 Example of the node using GPIOs:
3500         node {
3501                 gpios = <&qe_pio_e 18 0>;
3502         };
3504 In this example gpio-specifier is "18 0" and encodes GPIO pin number,
3505 and empty GPIO flags as accepted by the "qe_pio_e" gpio-controller.
3507 2) gpio-controller nodes
3508 ------------------------
3510 Every GPIO controller node must have #gpio-cells property defined,
3511 this information will be used to translate gpio-specifiers.
3513 Example of two SOC GPIO banks defined as gpio-controller nodes:
3515         qe_pio_a: gpio-controller@1400 {
3516                 #gpio-cells = <2>;
3517                 compatible = "fsl,qe-pario-bank-a", "fsl,qe-pario-bank";
3518                 reg = <0x1400 0x18>;
3519                 gpio-controller;
3520         };
3522         qe_pio_e: gpio-controller@1460 {
3523                 #gpio-cells = <2>;
3524                 compatible = "fsl,qe-pario-bank-e", "fsl,qe-pario-bank";
3525                 reg = <0x1460 0x18>;
3526                 gpio-controller;
3527         };
3529 Appendix A - Sample SOC node for MPC8540
3530 ========================================
3532 Note that the #address-cells and #size-cells for the SoC node
3533 in this example have been explicitly listed; these are likely
3534 not necessary as they are usually the same as the root node.
3536         soc8540@e0000000 {
3537                 #address-cells = <1>;
3538                 #size-cells = <1>;
3539                 #interrupt-cells = <2>;
3540                 device_type = "soc";
3541                 ranges = <00000000 e0000000 00100000>
3542                 reg = <e0000000 00003000>;
3543                 bus-frequency = <0>;
3545                 mdio@24520 {
3546                         reg = <24520 20>;
3547                         device_type = "mdio";
3548                         compatible = "gianfar";
3550                         ethernet-phy@0 {
3551                                 linux,phandle = <2452000>
3552                                 interrupt-parent = <40000>;
3553                                 interrupts = <35 1>;
3554                                 reg = <0>;
3555                                 device_type = "ethernet-phy";
3556                         };
3558                         ethernet-phy@1 {
3559                                 linux,phandle = <2452001>
3560                                 interrupt-parent = <40000>;
3561                                 interrupts = <35 1>;
3562                                 reg = <1>;
3563                                 device_type = "ethernet-phy";
3564                         };
3566                         ethernet-phy@3 {
3567                                 linux,phandle = <2452002>
3568                                 interrupt-parent = <40000>;
3569                                 interrupts = <35 1>;
3570                                 reg = <3>;
3571                                 device_type = "ethernet-phy";
3572                         };
3574                 };
3576                 ethernet@24000 {
3577                         #size-cells = <0>;
3578                         device_type = "network";
3579                         model = "TSEC";
3580                         compatible = "gianfar";
3581                         reg = <24000 1000>;
3582                         mac-address = [ 00 E0 0C 00 73 00 ];
3583                         interrupts = <d 3 e 3 12 3>;
3584                         interrupt-parent = <40000>;
3585                         phy-handle = <2452000>;
3586                 };
3588                 ethernet@25000 {
3589                         #address-cells = <1>;
3590                         #size-cells = <0>;
3591                         device_type = "network";
3592                         model = "TSEC";
3593                         compatible = "gianfar";
3594                         reg = <25000 1000>;
3595                         mac-address = [ 00 E0 0C 00 73 01 ];
3596                         interrupts = <13 3 14 3 18 3>;
3597                         interrupt-parent = <40000>;
3598                         phy-handle = <2452001>;
3599                 };
3601                 ethernet@26000 {
3602                         #address-cells = <1>;
3603                         #size-cells = <0>;
3604                         device_type = "network";
3605                         model = "FEC";
3606                         compatible = "gianfar";
3607                         reg = <26000 1000>;
3608                         mac-address = [ 00 E0 0C 00 73 02 ];
3609                         interrupts = <19 3>;
3610                         interrupt-parent = <40000>;
3611                         phy-handle = <2452002>;
3612                 };
3614                 serial@4500 {
3615                         device_type = "serial";
3616                         compatible = "ns16550";
3617                         reg = <4500 100>;
3618                         clock-frequency = <0>;
3619                         interrupts = <1a 3>;
3620                         interrupt-parent = <40000>;
3621                 };
3623                 pic@40000 {
3624                         linux,phandle = <40000>;
3625                         clock-frequency = <0>;
3626                         interrupt-controller;
3627                         #address-cells = <0>;
3628                         reg = <40000 40000>;
3629                         built-in;
3630                         compatible = "chrp,open-pic";
3631                         device_type = "open-pic";
3632                         big-endian;
3633                 };
3635                 i2c@3000 {
3636                         interrupt-parent = <40000>;
3637                         interrupts = <1b 3>;
3638                         reg = <3000 18>;
3639                         device_type = "i2c";
3640                         compatible  = "fsl-i2c";
3641                         dfsrr;
3642                 };
3644         };