[POWERPC] Xilinx: hwicap: update booting-without-of.txt
[sfrench/cifs-2.6.git] / Documentation / powerpc / booting-without-of.txt
1            Booting the Linux/ppc kernel without Open Firmware
2            --------------------------------------------------
3
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
10
11 Table of Contents
12 =================
13
14   I - Introduction
15     1) Entry point for arch/powerpc
16     2) Board support
17
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
23
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
36
37   IV - "dtc", the device tree compiler
38
39   V - Recommendations for a bootloader
40
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
61   VII - Specifying interrupt information for devices
62     1) interrupts property
63     2) interrupt-parent property
64     3) OpenPIC Interrupt Controllers
65     4) ISA Interrupt Controllers
66
67   Appendix A - Sample SOC node for MPC8540
68
69
70 Revision Information
71 ====================
72
73    May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet.
74
75    May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or
76                            clarifies the fact that a lot of things are
77                            optional, the kernel only requires a very
78                            small device tree, though it is encouraged
79                            to provide an as complete one as possible.
80
81    May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM
82                          - Misc fixes
83                          - Define version 3 and new format version 16
84                            for the DT block (version 16 needs kernel
85                            patches, will be fwd separately).
86                            String block now has a size, and full path
87                            is replaced by unit name for more
88                            compactness.
89                            linux,phandle is made optional, only nodes
90                            that are referenced by other nodes need it.
91                            "name" property is now automatically
92                            deduced from the unit name
93
94    June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and
95                            OF_DT_END_NODE in structure definition.
96                          - Change version 16 format to always align
97                            property data to 4 bytes. Since tokens are
98                            already aligned, that means no specific
99                            required alignment between property size
100                            and property data. The old style variable
101                            alignment would make it impossible to do
102                            "simple" insertion of properties using
103                            memmove (thanks Milton for
104                            noticing). Updated kernel patch as well
105                          - Correct a few more alignment constraints
106                          - Add a chapter about the device-tree
107                            compiler and the textural representation of
108                            the tree that can be "compiled" by dtc.
109
110    November 21, 2005: Rev 0.5
111                          - Additions/generalizations for 32-bit
112                          - Changed to reflect the new arch/powerpc
113                            structure
114                          - Added chapter VI
115
116
117  ToDo:
118         - Add some definitions of interrupt tree (simple/complex)
119         - Add some definitions for PCI host bridges
120         - Add some common address format examples
121         - Add definitions for standard properties and "compatible"
122           names for cells that are not already defined by the existing
123           OF spec.
124         - Compare FSL SOC use of PCI to standard and make sure no new
125           node definition required.
126         - Add more information about node definitions for SOC devices
127           that currently have no standard, like the FSL CPM.
128
129
130 I - Introduction
131 ================
132
133 During the recent development of the Linux/ppc64 kernel, and more
134 specifically, the addition of new platform types outside of the old
135 IBM pSeries/iSeries pair, it was decided to enforce some strict rules
136 regarding the kernel entry and bootloader <-> kernel interfaces, in
137 order to avoid the degeneration that had become the ppc32 kernel entry
138 point and the way a new platform should be added to the kernel. The
139 legacy iSeries platform breaks those rules as it predates this scheme,
140 but no new board support will be accepted in the main tree that
141 doesn't follows them properly.  In addition, since the advent of the
142 arch/powerpc merged architecture for ppc32 and ppc64, new 32-bit
143 platforms and 32-bit platforms which move into arch/powerpc will be
144 required to use these rules as well.
145
146 The main requirement that will be defined in more detail below is
147 the presence of a device-tree whose format is defined after Open
148 Firmware specification. However, in order to make life easier
149 to embedded board vendors, the kernel doesn't require the device-tree
150 to represent every device in the system and only requires some nodes
151 and properties to be present. This will be described in detail in
152 section III, but, for example, the kernel does not require you to
153 create a node for every PCI device in the system. It is a requirement
154 to have a node for PCI host bridges in order to provide interrupt
155 routing informations and memory/IO ranges, among others. It is also
156 recommended to define nodes for on chip devices and other busses that
157 don't specifically fit in an existing OF specification. This creates a
158 great flexibility in the way the kernel can then probe those and match
159 drivers to device, without having to hard code all sorts of tables. It
160 also makes it more flexible for board vendors to do minor hardware
161 upgrades without significantly impacting the kernel code or cluttering
162 it with special cases.
163
164
165 1) Entry point for arch/powerpc
166 -------------------------------
167
168    There is one and one single entry point to the kernel, at the start
169    of the kernel image. That entry point supports two calling
170    conventions:
171
172         a) Boot from Open Firmware. If your firmware is compatible
173         with Open Firmware (IEEE 1275) or provides an OF compatible
174         client interface API (support for "interpret" callback of
175         forth words isn't required), you can enter the kernel with:
176
177               r5 : OF callback pointer as defined by IEEE 1275
178               bindings to powerpc. Only the 32-bit client interface
179               is currently supported
180
181               r3, r4 : address & length of an initrd if any or 0
182
183               The MMU is either on or off; the kernel will run the
184               trampoline located in arch/powerpc/kernel/prom_init.c to
185               extract the device-tree and other information from open
186               firmware and build a flattened device-tree as described
187               in b). prom_init() will then re-enter the kernel using
188               the second method. This trampoline code runs in the
189               context of the firmware, which is supposed to handle all
190               exceptions during that time.
191
192         b) Direct entry with a flattened device-tree block. This entry
193         point is called by a) after the OF trampoline and can also be
194         called directly by a bootloader that does not support the Open
195         Firmware client interface. It is also used by "kexec" to
196         implement "hot" booting of a new kernel from a previous
197         running one. This method is what I will describe in more
198         details in this document, as method a) is simply standard Open
199         Firmware, and thus should be implemented according to the
200         various standard documents defining it and its binding to the
201         PowerPC platform. The entry point definition then becomes:
202
203                 r3 : physical pointer to the device-tree block
204                 (defined in chapter II) in RAM
205
206                 r4 : physical pointer to the kernel itself. This is
207                 used by the assembly code to properly disable the MMU
208                 in case you are entering the kernel with MMU enabled
209                 and a non-1:1 mapping.
210
211                 r5 : NULL (as to differentiate with method a)
212
213         Note about SMP entry: Either your firmware puts your other
214         CPUs in some sleep loop or spin loop in ROM where you can get
215         them out via a soft reset or some other means, in which case
216         you don't need to care, or you'll have to enter the kernel
217         with all CPUs. The way to do that with method b) will be
218         described in a later revision of this document.
219
220
221 2) Board support
222 ----------------
223
224 64-bit kernels:
225
226    Board supports (platforms) are not exclusive config options. An
227    arbitrary set of board supports can be built in a single kernel
228    image. The kernel will "know" what set of functions to use for a
229    given platform based on the content of the device-tree. Thus, you
230    should:
231
232         a) add your platform support as a _boolean_ option in
233         arch/powerpc/Kconfig, following the example of PPC_PSERIES,
234         PPC_PMAC and PPC_MAPLE. The later is probably a good
235         example of a board support to start from.
236
237         b) create your main platform file as
238         "arch/powerpc/platforms/myplatform/myboard_setup.c" and add it
239         to the Makefile under the condition of your CONFIG_
240         option. This file will define a structure of type "ppc_md"
241         containing the various callbacks that the generic code will
242         use to get to your platform specific code
243
244         c) Add a reference to your "ppc_md" structure in the
245         "machines" table in arch/powerpc/kernel/setup_64.c if you are
246         a 64-bit platform.
247
248         d) request and get assigned a platform number (see PLATFORM_*
249         constants in include/asm-powerpc/processor.h
250
251 32-bit embedded kernels:
252
253   Currently, board support is essentially an exclusive config option.
254   The kernel is configured for a single platform.  Part of the reason
255   for this is to keep kernels on embedded systems small and efficient;
256   part of this is due to the fact the code is already that way. In the
257   future, a kernel may support multiple platforms, but only if the
258   platforms feature the same core architecture.  A single kernel build
259   cannot support both configurations with Book E and configurations
260   with classic Powerpc architectures.
261
262   32-bit embedded platforms that are moved into arch/powerpc using a
263   flattened device tree should adopt the merged tree practice of
264   setting ppc_md up dynamically, even though the kernel is currently
265   built with support for only a single platform at a time.  This allows
266   unification of the setup code, and will make it easier to go to a
267   multiple-platform-support model in the future.
268
269 NOTE: I believe the above will be true once Ben's done with the merge
270 of the boot sequences.... someone speak up if this is wrong!
271
272   To add a 32-bit embedded platform support, follow the instructions
273   for 64-bit platforms above, with the exception that the Kconfig
274   option should be set up such that the kernel builds exclusively for
275   the platform selected.  The processor type for the platform should
276   enable another config option to select the specific board
277   supported.
278
279 NOTE: If Ben doesn't merge the setup files, may need to change this to
280 point to setup_32.c
281
282
283    I will describe later the boot process and various callbacks that
284    your platform should implement.
285
286
287 II - The DT block format
288 ========================
289
290
291 This chapter defines the actual format of the flattened device-tree
292 passed to the kernel. The actual content of it and kernel requirements
293 are described later. You can find example of code manipulating that
294 format in various places, including arch/powerpc/kernel/prom_init.c
295 which will generate a flattened device-tree from the Open Firmware
296 representation, or the fs2dt utility which is part of the kexec tools
297 which will generate one from a filesystem representation. It is
298 expected that a bootloader like uboot provides a bit more support,
299 that will be discussed later as well.
300
301 Note: The block has to be in main memory. It has to be accessible in
302 both real mode and virtual mode with no mapping other than main
303 memory. If you are writing a simple flash bootloader, it should copy
304 the block to RAM before passing it to the kernel.
305
306
307 1) Header
308 ---------
309
310    The kernel is entered with r3 pointing to an area of memory that is
311    roughly described in include/asm-powerpc/prom.h by the structure
312    boot_param_header:
313
314 struct boot_param_header {
315         u32     magic;                  /* magic word OF_DT_HEADER */
316         u32     totalsize;              /* total size of DT block */
317         u32     off_dt_struct;          /* offset to structure */
318         u32     off_dt_strings;         /* offset to strings */
319         u32     off_mem_rsvmap;         /* offset to memory reserve map
320                                            */
321         u32     version;                /* format version */
322         u32     last_comp_version;      /* last compatible version */
323
324         /* version 2 fields below */
325         u32     boot_cpuid_phys;        /* Which physical CPU id we're
326                                            booting on */
327         /* version 3 fields below */
328         u32     size_dt_strings;        /* size of the strings block */
329
330         /* version 17 fields below */
331         u32     size_dt_struct;         /* size of the DT structure block */
332 };
333
334    Along with the constants:
335
336 /* Definitions used by the flattened device tree */
337 #define OF_DT_HEADER            0xd00dfeed      /* 4: version,
338                                                    4: total size */
339 #define OF_DT_BEGIN_NODE        0x1             /* Start node: full name
340                                                    */
341 #define OF_DT_END_NODE          0x2             /* End node */
342 #define OF_DT_PROP              0x3             /* Property: name off,
343                                                    size, content */
344 #define OF_DT_END               0x9
345
346    All values in this header are in big endian format, the various
347    fields in this header are defined more precisely below. All
348    "offset" values are in bytes from the start of the header; that is
349    from the value of r3.
350
351    - magic
352
353      This is a magic value that "marks" the beginning of the
354      device-tree block header. It contains the value 0xd00dfeed and is
355      defined by the constant OF_DT_HEADER
356
357    - totalsize
358
359      This is the total size of the DT block including the header. The
360      "DT" block should enclose all data structures defined in this
361      chapter (who are pointed to by offsets in this header). That is,
362      the device-tree structure, strings, and the memory reserve map.
363
364    - off_dt_struct
365
366      This is an offset from the beginning of the header to the start
367      of the "structure" part the device tree. (see 2) device tree)
368
369    - off_dt_strings
370
371      This is an offset from the beginning of the header to the start
372      of the "strings" part of the device-tree
373
374    - off_mem_rsvmap
375
376      This is an offset from the beginning of the header to the start
377      of the reserved memory map. This map is a list of pairs of 64-
378      bit integers. Each pair is a physical address and a size. The
379      list is terminated by an entry of size 0. This map provides the
380      kernel with a list of physical memory areas that are "reserved"
381      and thus not to be used for memory allocations, especially during
382      early initialization. The kernel needs to allocate memory during
383      boot for things like un-flattening the device-tree, allocating an
384      MMU hash table, etc... Those allocations must be done in such a
385      way to avoid overriding critical things like, on Open Firmware
386      capable machines, the RTAS instance, or on some pSeries, the TCE
387      tables used for the iommu. Typically, the reserve map should
388      contain _at least_ this DT block itself (header,total_size). If
389      you are passing an initrd to the kernel, you should reserve it as
390      well. You do not need to reserve the kernel image itself. The map
391      should be 64-bit aligned.
392
393    - version
394
395      This is the version of this structure. Version 1 stops
396      here. Version 2 adds an additional field boot_cpuid_phys.
397      Version 3 adds the size of the strings block, allowing the kernel
398      to reallocate it easily at boot and free up the unused flattened
399      structure after expansion. Version 16 introduces a new more
400      "compact" format for the tree itself that is however not backward
401      compatible. Version 17 adds an additional field, size_dt_struct,
402      allowing it to be reallocated or moved more easily (this is
403      particularly useful for bootloaders which need to make
404      adjustments to a device tree based on probed information). You
405      should always generate a structure of the highest version defined
406      at the time of your implementation. Currently that is version 17,
407      unless you explicitly aim at being backward compatible.
408
409    - last_comp_version
410
411      Last compatible version. This indicates down to what version of
412      the DT block you are backward compatible. For example, version 2
413      is backward compatible with version 1 (that is, a kernel build
414      for version 1 will be able to boot with a version 2 format). You
415      should put a 1 in this field if you generate a device tree of
416      version 1 to 3, or 16 if you generate a tree of version 16 or 17
417      using the new unit name format.
418
419    - boot_cpuid_phys
420
421      This field only exist on version 2 headers. It indicate which
422      physical CPU ID is calling the kernel entry point. This is used,
423      among others, by kexec. If you are on an SMP system, this value
424      should match the content of the "reg" property of the CPU node in
425      the device-tree corresponding to the CPU calling the kernel entry
426      point (see further chapters for more informations on the required
427      device-tree contents)
428
429    - size_dt_strings
430
431      This field only exists on version 3 and later headers.  It
432      gives the size of the "strings" section of the device tree (which
433      starts at the offset given by off_dt_strings).
434
435    - size_dt_struct
436
437      This field only exists on version 17 and later headers.  It gives
438      the size of the "structure" section of the device tree (which
439      starts at the offset given by off_dt_struct).
440
441    So the typical layout of a DT block (though the various parts don't
442    need to be in that order) looks like this (addresses go from top to
443    bottom):
444
445
446              ------------------------------
447        r3 -> |  struct boot_param_header  |
448              ------------------------------
449              |      (alignment gap) (*)   |
450              ------------------------------
451              |      memory reserve map    |
452              ------------------------------
453              |      (alignment gap)       |
454              ------------------------------
455              |                            |
456              |    device-tree structure   |
457              |                            |
458              ------------------------------
459              |      (alignment gap)       |
460              ------------------------------
461              |                            |
462              |     device-tree strings    |
463              |                            |
464       -----> ------------------------------
465       |
466       |
467       --- (r3 + totalsize)
468
469   (*) The alignment gaps are not necessarily present; their presence
470       and size are dependent on the various alignment requirements of
471       the individual data blocks.
472
473
474 2) Device tree generalities
475 ---------------------------
476
477 This device-tree itself is separated in two different blocks, a
478 structure block and a strings block. Both need to be aligned to a 4
479 byte boundary.
480
481 First, let's quickly describe the device-tree concept before detailing
482 the storage format. This chapter does _not_ describe the detail of the
483 required types of nodes & properties for the kernel, this is done
484 later in chapter III.
485
486 The device-tree layout is strongly inherited from the definition of
487 the Open Firmware IEEE 1275 device-tree. It's basically a tree of
488 nodes, each node having two or more named properties. A property can
489 have a value or not.
490
491 It is a tree, so each node has one and only one parent except for the
492 root node who has no parent.
493
494 A node has 2 names. The actual node name is generally contained in a
495 property of type "name" in the node property list whose value is a
496 zero terminated string and is mandatory for version 1 to 3 of the
497 format definition (as it is in Open Firmware). Version 16 makes it
498 optional as it can generate it from the unit name defined below.
499
500 There is also a "unit name" that is used to differentiate nodes with
501 the same name at the same level, it is usually made of the node
502 names, the "@" sign, and a "unit address", which definition is
503 specific to the bus type the node sits on.
504
505 The unit name doesn't exist as a property per-se but is included in
506 the device-tree structure. It is typically used to represent "path" in
507 the device-tree. More details about the actual format of these will be
508 below.
509
510 The kernel powerpc generic code does not make any formal use of the
511 unit address (though some board support code may do) so the only real
512 requirement here for the unit address is to ensure uniqueness of
513 the node unit name at a given level of the tree. Nodes with no notion
514 of address and no possible sibling of the same name (like /memory or
515 /cpus) may omit the unit address in the context of this specification,
516 or use the "@0" default unit address. The unit name is used to define
517 a node "full path", which is the concatenation of all parent node
518 unit names separated with "/".
519
520 The root node doesn't have a defined name, and isn't required to have
521 a name property either if you are using version 3 or earlier of the
522 format. It also has no unit address (no @ symbol followed by a unit
523 address). The root node unit name is thus an empty string. The full
524 path to the root node is "/".
525
526 Every node which actually represents an actual device (that is, a node
527 which isn't only a virtual "container" for more nodes, like "/cpus"
528 is) is also required to have a "device_type" property indicating the
529 type of node .
530
531 Finally, every node that can be referenced from a property in another
532 node is required to have a "linux,phandle" property. Real open
533 firmware implementations provide a unique "phandle" value for every
534 node that the "prom_init()" trampoline code turns into
535 "linux,phandle" properties. However, this is made optional if the
536 flattened device tree is used directly. An example of a node
537 referencing another node via "phandle" is when laying out the
538 interrupt tree which will be described in a further version of this
539 document.
540
541 This "linux, phandle" property is a 32-bit value that uniquely
542 identifies a node. You are free to use whatever values or system of
543 values, internal pointers, or whatever to generate these, the only
544 requirement is that every node for which you provide that property has
545 a unique value for it.
546
547 Here is an example of a simple device-tree. In this example, an "o"
548 designates a node followed by the node unit name. Properties are
549 presented with their name followed by their content. "content"
550 represents an ASCII string (zero terminated) value, while <content>
551 represents a 32-bit hexadecimal value. The various nodes in this
552 example will be discussed in a later chapter. At this point, it is
553 only meant to give you a idea of what a device-tree looks like. I have
554 purposefully kept the "name" and "linux,phandle" properties which
555 aren't necessary in order to give you a better idea of what the tree
556 looks like in practice.
557
558   / o device-tree
559       |- name = "device-tree"
560       |- model = "MyBoardName"
561       |- compatible = "MyBoardFamilyName"
562       |- #address-cells = <2>
563       |- #size-cells = <2>
564       |- linux,phandle = <0>
565       |
566       o cpus
567       | | - name = "cpus"
568       | | - linux,phandle = <1>
569       | | - #address-cells = <1>
570       | | - #size-cells = <0>
571       | |
572       | o PowerPC,970@0
573       |   |- name = "PowerPC,970"
574       |   |- device_type = "cpu"
575       |   |- reg = <0>
576       |   |- clock-frequency = <5f5e1000>
577       |   |- 64-bit
578       |   |- linux,phandle = <2>
579       |
580       o memory@0
581       | |- name = "memory"
582       | |- device_type = "memory"
583       | |- reg = <00000000 00000000 00000000 20000000>
584       | |- linux,phandle = <3>
585       |
586       o chosen
587         |- name = "chosen"
588         |- bootargs = "root=/dev/sda2"
589         |- linux,phandle = <4>
590
591 This tree is almost a minimal tree. It pretty much contains the
592 minimal set of required nodes and properties to boot a linux kernel;
593 that is, some basic model informations at the root, the CPUs, and the
594 physical memory layout.  It also includes misc information passed
595 through /chosen, like in this example, the platform type (mandatory)
596 and the kernel command line arguments (optional).
597
598 The /cpus/PowerPC,970@0/64-bit property is an example of a
599 property without a value. All other properties have a value. The
600 significance of the #address-cells and #size-cells properties will be
601 explained in chapter IV which defines precisely the required nodes and
602 properties and their content.
603
604
605 3) Device tree "structure" block
606
607 The structure of the device tree is a linearized tree structure. The
608 "OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE"
609 ends that node definition. Child nodes are simply defined before
610 "OF_DT_END_NODE" (that is nodes within the node). A 'token' is a 32
611 bit value. The tree has to be "finished" with a OF_DT_END token
612
613 Here's the basic structure of a single node:
614
615      * token OF_DT_BEGIN_NODE (that is 0x00000001)
616      * for version 1 to 3, this is the node full path as a zero
617        terminated string, starting with "/". For version 16 and later,
618        this is the node unit name only (or an empty string for the
619        root node)
620      * [align gap to next 4 bytes boundary]
621      * for each property:
622         * token OF_DT_PROP (that is 0x00000003)
623         * 32-bit value of property value size in bytes (or 0 if no
624           value)
625         * 32-bit value of offset in string block of property name
626         * property value data if any
627         * [align gap to next 4 bytes boundary]
628      * [child nodes if any]
629      * token OF_DT_END_NODE (that is 0x00000002)
630
631 So the node content can be summarized as a start token, a full path,
632 a list of properties, a list of child nodes, and an end token. Every
633 child node is a full node structure itself as defined above.
634
635 NOTE: The above definition requires that all property definitions for
636 a particular node MUST precede any subnode definitions for that node.
637 Although the structure would not be ambiguous if properties and
638 subnodes were intermingled, the kernel parser requires that the
639 properties come first (up until at least 2.6.22).  Any tools
640 manipulating a flattened tree must take care to preserve this
641 constraint.
642
643 4) Device tree "strings" block
644
645 In order to save space, property names, which are generally redundant,
646 are stored separately in the "strings" block. This block is simply the
647 whole bunch of zero terminated strings for all property names
648 concatenated together. The device-tree property definitions in the
649 structure block will contain offset values from the beginning of the
650 strings block.
651
652
653 III - Required content of the device tree
654 =========================================
655
656 WARNING: All "linux,*" properties defined in this document apply only
657 to a flattened device-tree. If your platform uses a real
658 implementation of Open Firmware or an implementation compatible with
659 the Open Firmware client interface, those properties will be created
660 by the trampoline code in the kernel's prom_init() file. For example,
661 that's where you'll have to add code to detect your board model and
662 set the platform number. However, when using the flattened device-tree
663 entry point, there is no prom_init() pass, and thus you have to
664 provide those properties yourself.
665
666
667 1) Note about cells and address representation
668 ----------------------------------------------
669
670 The general rule is documented in the various Open Firmware
671 documentations. If you choose to describe a bus with the device-tree
672 and there exist an OF bus binding, then you should follow the
673 specification. However, the kernel does not require every single
674 device or bus to be described by the device tree.
675
676 In general, the format of an address for a device is defined by the
677 parent bus type, based on the #address-cells and #size-cells
678 properties.  Note that the parent's parent definitions of #address-cells
679 and #size-cells are not inhereted so every node with children must specify
680 them.  The kernel requires the root node to have those properties defining
681 addresses format for devices directly mapped on the processor bus.
682
683 Those 2 properties define 'cells' for representing an address and a
684 size. A "cell" is a 32-bit number. For example, if both contain 2
685 like the example tree given above, then an address and a size are both
686 composed of 2 cells, and each is a 64-bit number (cells are
687 concatenated and expected to be in big endian format). Another example
688 is the way Apple firmware defines them, with 2 cells for an address
689 and one cell for a size.  Most 32-bit implementations should define
690 #address-cells and #size-cells to 1, which represents a 32-bit value.
691 Some 32-bit processors allow for physical addresses greater than 32
692 bits; these processors should define #address-cells as 2.
693
694 "reg" properties are always a tuple of the type "address size" where
695 the number of cells of address and size is specified by the bus
696 #address-cells and #size-cells. When a bus supports various address
697 spaces and other flags relative to a given address allocation (like
698 prefetchable, etc...) those flags are usually added to the top level
699 bits of the physical address. For example, a PCI physical address is
700 made of 3 cells, the bottom two containing the actual address itself
701 while the top cell contains address space indication, flags, and pci
702 bus & device numbers.
703
704 For busses that support dynamic allocation, it's the accepted practice
705 to then not provide the address in "reg" (keep it 0) though while
706 providing a flag indicating the address is dynamically allocated, and
707 then, to provide a separate "assigned-addresses" property that
708 contains the fully allocated addresses. See the PCI OF bindings for
709 details.
710
711 In general, a simple bus with no address space bits and no dynamic
712 allocation is preferred if it reflects your hardware, as the existing
713 kernel address parsing functions will work out of the box. If you
714 define a bus type with a more complex address format, including things
715 like address space bits, you'll have to add a bus translator to the
716 prom_parse.c file of the recent kernels for your bus type.
717
718 The "reg" property only defines addresses and sizes (if #size-cells is
719 non-0) within a given bus. In order to translate addresses upward
720 (that is into parent bus addresses, and possibly into CPU physical
721 addresses), all busses must contain a "ranges" property. If the
722 "ranges" property is missing at a given level, it's assumed that
723 translation isn't possible, i.e., the registers are not visible on the
724 parent bus.  The format of the "ranges" property for a bus is a list
725 of:
726
727         bus address, parent bus address, size
728
729 "bus address" is in the format of the bus this bus node is defining,
730 that is, for a PCI bridge, it would be a PCI address. Thus, (bus
731 address, size) defines a range of addresses for child devices. "parent
732 bus address" is in the format of the parent bus of this bus. For
733 example, for a PCI host controller, that would be a CPU address. For a
734 PCI<->ISA bridge, that would be a PCI address. It defines the base
735 address in the parent bus where the beginning of that range is mapped.
736
737 For a new 64-bit powerpc board, I recommend either the 2/2 format or
738 Apple's 2/1 format which is slightly more compact since sizes usually
739 fit in a single 32-bit word.   New 32-bit powerpc boards should use a
740 1/1 format, unless the processor supports physical addresses greater
741 than 32-bits, in which case a 2/1 format is recommended.
742
743 Alternatively, the "ranges" property may be empty, indicating that the
744 registers are visible on the parent bus using an identity mapping
745 translation.  In other words, the parent bus address space is the same
746 as the child bus address space.
747
748 2) Note about "compatible" properties
749 -------------------------------------
750
751 These properties are optional, but recommended in devices and the root
752 node. The format of a "compatible" property is a list of concatenated
753 zero terminated strings. They allow a device to express its
754 compatibility with a family of similar devices, in some cases,
755 allowing a single driver to match against several devices regardless
756 of their actual names.
757
758 3) Note about "name" properties
759 -------------------------------
760
761 While earlier users of Open Firmware like OldWorld macintoshes tended
762 to use the actual device name for the "name" property, it's nowadays
763 considered a good practice to use a name that is closer to the device
764 class (often equal to device_type). For example, nowadays, ethernet
765 controllers are named "ethernet", an additional "model" property
766 defining precisely the chip type/model, and "compatible" property
767 defining the family in case a single driver can driver more than one
768 of these chips. However, the kernel doesn't generally put any
769 restriction on the "name" property; it is simply considered good
770 practice to follow the standard and its evolutions as closely as
771 possible.
772
773 Note also that the new format version 16 makes the "name" property
774 optional. If it's absent for a node, then the node's unit name is then
775 used to reconstruct the name. That is, the part of the unit name
776 before the "@" sign is used (or the entire unit name if no "@" sign
777 is present).
778
779 4) Note about node and property names and character set
780 -------------------------------------------------------
781
782 While open firmware provides more flexible usage of 8859-1, this
783 specification enforces more strict rules. Nodes and properties should
784 be comprised only of ASCII characters 'a' to 'z', '0' to
785 '9', ',', '.', '_', '+', '#', '?', and '-'. Node names additionally
786 allow uppercase characters 'A' to 'Z' (property names should be
787 lowercase. The fact that vendors like Apple don't respect this rule is
788 irrelevant here). Additionally, node and property names should always
789 begin with a character in the range 'a' to 'z' (or 'A' to 'Z' for node
790 names).
791
792 The maximum number of characters for both nodes and property names
793 is 31. In the case of node names, this is only the leftmost part of
794 a unit name (the pure "name" property), it doesn't include the unit
795 address which can extend beyond that limit.
796
797
798 5) Required nodes and properties
799 --------------------------------
800   These are all that are currently required. However, it is strongly
801   recommended that you expose PCI host bridges as documented in the
802   PCI binding to open firmware, and your interrupt tree as documented
803   in OF interrupt tree specification.
804
805   a) The root node
806
807   The root node requires some properties to be present:
808
809     - model : this is your board name/model
810     - #address-cells : address representation for "root" devices
811     - #size-cells: the size representation for "root" devices
812     - device_type : This property shouldn't be necessary. However, if
813       you decide to create a device_type for your root node, make sure it
814       is _not_ "chrp" unless your platform is a pSeries or PAPR compliant
815       one for 64-bit, or a CHRP-type machine for 32-bit as this will
816       matched by the kernel this way.
817
818   Additionally, some recommended properties are:
819
820     - compatible : the board "family" generally finds its way here,
821       for example, if you have 2 board models with a similar layout,
822       that typically get driven by the same platform code in the
823       kernel, you would use a different "model" property but put a
824       value in "compatible". The kernel doesn't directly use that
825       value but it is generally useful.
826
827   The root node is also generally where you add additional properties
828   specific to your board like the serial number if any, that sort of
829   thing. It is recommended that if you add any "custom" property whose
830   name may clash with standard defined ones, you prefix them with your
831   vendor name and a comma.
832
833   b) The /cpus node
834
835   This node is the parent of all individual CPU nodes. It doesn't
836   have any specific requirements, though it's generally good practice
837   to have at least:
838
839                #address-cells = <00000001>
840                #size-cells    = <00000000>
841
842   This defines that the "address" for a CPU is a single cell, and has
843   no meaningful size. This is not necessary but the kernel will assume
844   that format when reading the "reg" properties of a CPU node, see
845   below
846
847   c) The /cpus/* nodes
848
849   So under /cpus, you are supposed to create a node for every CPU on
850   the machine. There is no specific restriction on the name of the
851   CPU, though It's common practice to call it PowerPC,<name>. For
852   example, Apple uses PowerPC,G5 while IBM uses PowerPC,970FX.
853
854   Required properties:
855
856     - device_type : has to be "cpu"
857     - reg : This is the physical CPU number, it's a single 32-bit cell
858       and is also used as-is as the unit number for constructing the
859       unit name in the full path. For example, with 2 CPUs, you would
860       have the full path:
861         /cpus/PowerPC,970FX@0
862         /cpus/PowerPC,970FX@1
863       (unit addresses do not require leading zeroes)
864     - d-cache-block-size : one cell, L1 data cache block size in bytes (*)
865     - i-cache-block-size : one cell, L1 instruction cache block size in
866       bytes
867     - d-cache-size : one cell, size of L1 data cache in bytes
868     - i-cache-size : one cell, size of L1 instruction cache in bytes
869
870 (*) The cache "block" size is the size on which the cache management
871 instructions operate. Historically, this document used the cache
872 "line" size here which is incorrect. The kernel will prefer the cache
873 block size and will fallback to cache line size for backward
874 compatibility.
875
876   Recommended properties:
877
878     - timebase-frequency : a cell indicating the frequency of the
879       timebase in Hz. This is not directly used by the generic code,
880       but you are welcome to copy/paste the pSeries code for setting
881       the kernel timebase/decrementer calibration based on this
882       value.
883     - clock-frequency : a cell indicating the CPU core clock frequency
884       in Hz. A new property will be defined for 64-bit values, but if
885       your frequency is < 4Ghz, one cell is enough. Here as well as
886       for the above, the common code doesn't use that property, but
887       you are welcome to re-use the pSeries or Maple one. A future
888       kernel version might provide a common function for this.
889     - d-cache-line-size : one cell, L1 data cache line size in bytes
890       if different from the block size
891     - i-cache-line-size : one cell, L1 instruction cache line size in
892       bytes if different from the block size
893
894   You are welcome to add any property you find relevant to your board,
895   like some information about the mechanism used to soft-reset the
896   CPUs. For example, Apple puts the GPIO number for CPU soft reset
897   lines in there as a "soft-reset" property since they start secondary
898   CPUs by soft-resetting them.
899
900
901   d) the /memory node(s)
902
903   To define the physical memory layout of your board, you should
904   create one or more memory node(s). You can either create a single
905   node with all memory ranges in its reg property, or you can create
906   several nodes, as you wish. The unit address (@ part) used for the
907   full path is the address of the first range of memory defined by a
908   given node. If you use a single memory node, this will typically be
909   @0.
910
911   Required properties:
912
913     - device_type : has to be "memory"
914     - reg : This property contains all the physical memory ranges of
915       your board. It's a list of addresses/sizes concatenated
916       together, with the number of cells of each defined by the
917       #address-cells and #size-cells of the root node. For example,
918       with both of these properties being 2 like in the example given
919       earlier, a 970 based machine with 6Gb of RAM could typically
920       have a "reg" property here that looks like:
921
922       00000000 00000000 00000000 80000000
923       00000001 00000000 00000001 00000000
924
925       That is a range starting at 0 of 0x80000000 bytes and a range
926       starting at 0x100000000 and of 0x100000000 bytes. You can see
927       that there is no memory covering the IO hole between 2Gb and
928       4Gb. Some vendors prefer splitting those ranges into smaller
929       segments, but the kernel doesn't care.
930
931   e) The /chosen node
932
933   This node is a bit "special". Normally, that's where open firmware
934   puts some variable environment information, like the arguments, or
935   the default input/output devices.
936
937   This specification makes a few of these mandatory, but also defines
938   some linux-specific properties that would be normally constructed by
939   the prom_init() trampoline when booting with an OF client interface,
940   but that you have to provide yourself when using the flattened format.
941
942   Recommended properties:
943
944     - bootargs : This zero-terminated string is passed as the kernel
945       command line
946     - linux,stdout-path : This is the full path to your standard
947       console device if any. Typically, if you have serial devices on
948       your board, you may want to put the full path to the one set as
949       the default console in the firmware here, for the kernel to pick
950       it up as its own default console. If you look at the function
951       set_preferred_console() in arch/ppc64/kernel/setup.c, you'll see
952       that the kernel tries to find out the default console and has
953       knowledge of various types like 8250 serial ports. You may want
954       to extend this function to add your own.
955
956   Note that u-boot creates and fills in the chosen node for platforms
957   that use it.
958
959   (Note: a practice that is now obsolete was to include a property
960   under /chosen called interrupt-controller which had a phandle value
961   that pointed to the main interrupt controller)
962
963   f) the /soc<SOCname> node
964
965   This node is used to represent a system-on-a-chip (SOC) and must be
966   present if the processor is a SOC. The top-level soc node contains
967   information that is global to all devices on the SOC. The node name
968   should contain a unit address for the SOC, which is the base address
969   of the memory-mapped register set for the SOC. The name of an soc
970   node should start with "soc", and the remainder of the name should
971   represent the part number for the soc.  For example, the MPC8540's
972   soc node would be called "soc8540".
973
974   Required properties:
975
976     - device_type : Should be "soc"
977     - ranges : Should be defined as specified in 1) to describe the
978       translation of SOC addresses for memory mapped SOC registers.
979     - bus-frequency: Contains the bus frequency for the SOC node.
980       Typically, the value of this field is filled in by the boot
981       loader. 
982
983
984   Recommended properties:
985
986     - reg : This property defines the address and size of the
987       memory-mapped registers that are used for the SOC node itself.
988       It does not include the child device registers - these will be
989       defined inside each child node.  The address specified in the
990       "reg" property should match the unit address of the SOC node.
991     - #address-cells : Address representation for "soc" devices.  The
992       format of this field may vary depending on whether or not the
993       device registers are memory mapped.  For memory mapped
994       registers, this field represents the number of cells needed to
995       represent the address of the registers.  For SOCs that do not
996       use MMIO, a special address format should be defined that
997       contains enough cells to represent the required information.
998       See 1) above for more details on defining #address-cells.
999     - #size-cells : Size representation for "soc" devices
1000     - #interrupt-cells : Defines the width of cells used to represent
1001        interrupts.  Typically this value is <2>, which includes a
1002        32-bit number that represents the interrupt number, and a
1003        32-bit number that represents the interrupt sense and level.
1004        This field is only needed if the SOC contains an interrupt
1005        controller.
1006
1007   The SOC node may contain child nodes for each SOC device that the
1008   platform uses.  Nodes should not be created for devices which exist
1009   on the SOC but are not used by a particular platform. See chapter VI
1010   for more information on how to specify devices that are part of a SOC.
1011
1012   Example SOC node for the MPC8540:
1013
1014         soc8540@e0000000 {
1015                 #address-cells = <1>;
1016                 #size-cells = <1>;
1017                 #interrupt-cells = <2>;
1018                 device_type = "soc";
1019                 ranges = <00000000 e0000000 00100000>
1020                 reg = <e0000000 00003000>;
1021                 bus-frequency = <0>;
1022         }
1023
1024
1025
1026 IV - "dtc", the device tree compiler
1027 ====================================
1028
1029
1030 dtc source code can be found at
1031 <http://ozlabs.org/~dgibson/dtc/dtc.tar.gz>
1032
1033 WARNING: This version is still in early development stage; the
1034 resulting device-tree "blobs" have not yet been validated with the
1035 kernel. The current generated bloc lacks a useful reserve map (it will
1036 be fixed to generate an empty one, it's up to the bootloader to fill
1037 it up) among others. The error handling needs work, bugs are lurking,
1038 etc...
1039
1040 dtc basically takes a device-tree in a given format and outputs a
1041 device-tree in another format. The currently supported formats are:
1042
1043   Input formats:
1044   -------------
1045
1046      - "dtb": "blob" format, that is a flattened device-tree block
1047        with
1048         header all in a binary blob.
1049      - "dts": "source" format. This is a text file containing a
1050        "source" for a device-tree. The format is defined later in this
1051         chapter.
1052      - "fs" format. This is a representation equivalent to the
1053         output of /proc/device-tree, that is nodes are directories and
1054         properties are files
1055
1056  Output formats:
1057  ---------------
1058
1059      - "dtb": "blob" format
1060      - "dts": "source" format
1061      - "asm": assembly language file. This is a file that can be
1062        sourced by gas to generate a device-tree "blob". That file can
1063        then simply be added to your Makefile. Additionally, the
1064        assembly file exports some symbols that can be used.
1065
1066
1067 The syntax of the dtc tool is
1068
1069     dtc [-I <input-format>] [-O <output-format>]
1070         [-o output-filename] [-V output_version] input_filename
1071
1072
1073 The "output_version" defines what version of the "blob" format will be
1074 generated. Supported versions are 1,2,3 and 16. The default is
1075 currently version 3 but that may change in the future to version 16.
1076
1077 Additionally, dtc performs various sanity checks on the tree, like the
1078 uniqueness of linux, phandle properties, validity of strings, etc...
1079
1080 The format of the .dts "source" file is "C" like, supports C and C++
1081 style comments.
1082
1083 / {
1084 }
1085
1086 The above is the "device-tree" definition. It's the only statement
1087 supported currently at the toplevel.
1088
1089 / {
1090   property1 = "string_value";   /* define a property containing a 0
1091                                  * terminated string
1092                                  */
1093
1094   property2 = <1234abcd>;       /* define a property containing a
1095                                  * numerical 32-bit value (hexadecimal)
1096                                  */
1097
1098   property3 = <12345678 12345678 deadbeef>;
1099                                 /* define a property containing 3
1100                                  * numerical 32-bit values (cells) in
1101                                  * hexadecimal
1102                                  */
1103   property4 = [0a 0b 0c 0d de ea ad be ef];
1104                                 /* define a property whose content is
1105                                  * an arbitrary array of bytes
1106                                  */
1107
1108   childnode@addresss {  /* define a child node named "childnode"
1109                                  * whose unit name is "childnode at
1110                                  * address"
1111                                  */
1112
1113     childprop = "hello\n";      /* define a property "childprop" of
1114                                  * childnode (in this case, a string)
1115                                  */
1116   };
1117 };
1118
1119 Nodes can contain other nodes etc... thus defining the hierarchical
1120 structure of the tree.
1121
1122 Strings support common escape sequences from C: "\n", "\t", "\r",
1123 "\(octal value)", "\x(hex value)".
1124
1125 It is also suggested that you pipe your source file through cpp (gcc
1126 preprocessor) so you can use #include's, #define for constants, etc...
1127
1128 Finally, various options are planned but not yet implemented, like
1129 automatic generation of phandles, labels (exported to the asm file so
1130 you can point to a property content and change it easily from whatever
1131 you link the device-tree with), label or path instead of numeric value
1132 in some cells to "point" to a node (replaced by a phandle at compile
1133 time), export of reserve map address to the asm file, ability to
1134 specify reserve map content at compile time, etc...
1135
1136 We may provide a .h include file with common definitions of that
1137 proves useful for some properties (like building PCI properties or
1138 interrupt maps) though it may be better to add a notion of struct
1139 definitions to the compiler...
1140
1141
1142 V - Recommendations for a bootloader
1143 ====================================
1144
1145
1146 Here are some various ideas/recommendations that have been proposed
1147 while all this has been defined and implemented.
1148
1149   - The bootloader may want to be able to use the device-tree itself
1150     and may want to manipulate it (to add/edit some properties,
1151     like physical memory size or kernel arguments). At this point, 2
1152     choices can be made. Either the bootloader works directly on the
1153     flattened format, or the bootloader has its own internal tree
1154     representation with pointers (similar to the kernel one) and
1155     re-flattens the tree when booting the kernel. The former is a bit
1156     more difficult to edit/modify, the later requires probably a bit
1157     more code to handle the tree structure. Note that the structure
1158     format has been designed so it's relatively easy to "insert"
1159     properties or nodes or delete them by just memmoving things
1160     around. It contains no internal offsets or pointers for this
1161     purpose.
1162
1163   - An example of code for iterating nodes & retrieving properties
1164     directly from the flattened tree format can be found in the kernel
1165     file arch/ppc64/kernel/prom.c, look at scan_flat_dt() function,
1166     its usage in early_init_devtree(), and the corresponding various
1167     early_init_dt_scan_*() callbacks. That code can be re-used in a
1168     GPL bootloader, and as the author of that code, I would be happy
1169     to discuss possible free licensing to any vendor who wishes to
1170     integrate all or part of this code into a non-GPL bootloader.
1171
1172
1173
1174 VI - System-on-a-chip devices and nodes
1175 =======================================
1176
1177 Many companies are now starting to develop system-on-a-chip
1178 processors, where the processor core (CPU) and many peripheral devices
1179 exist on a single piece of silicon.  For these SOCs, an SOC node
1180 should be used that defines child nodes for the devices that make
1181 up the SOC. While platforms are not required to use this model in
1182 order to boot the kernel, it is highly encouraged that all SOC
1183 implementations define as complete a flat-device-tree as possible to
1184 describe the devices on the SOC.  This will allow for the
1185 genericization of much of the kernel code.
1186
1187
1188 1) Defining child nodes of an SOC
1189 ---------------------------------
1190
1191 Each device that is part of an SOC may have its own node entry inside
1192 the SOC node.  For each device that is included in the SOC, the unit
1193 address property represents the address offset for this device's
1194 memory-mapped registers in the parent's address space.  The parent's
1195 address space is defined by the "ranges" property in the top-level soc
1196 node. The "reg" property for each node that exists directly under the
1197 SOC node should contain the address mapping from the child address space
1198 to the parent SOC address space and the size of the device's
1199 memory-mapped register file.
1200
1201 For many devices that may exist inside an SOC, there are predefined
1202 specifications for the format of the device tree node.  All SOC child
1203 nodes should follow these specifications, except where noted in this
1204 document.
1205
1206 See appendix A for an example partial SOC node definition for the
1207 MPC8540.
1208
1209
1210 2) Representing devices without a current OF specification
1211 ----------------------------------------------------------
1212
1213 Currently, there are many devices on SOCs that do not have a standard
1214 representation pre-defined as part of the open firmware
1215 specifications, mainly because the boards that contain these SOCs are
1216 not currently booted using open firmware.   This section contains
1217 descriptions for the SOC devices for which new nodes have been
1218 defined; this list will expand as more and more SOC-containing
1219 platforms are moved over to use the flattened-device-tree model.
1220
1221   a) MDIO IO device
1222
1223   The MDIO is a bus to which the PHY devices are connected.  For each
1224   device that exists on this bus, a child node should be created.  See
1225   the definition of the PHY node below for an example of how to define
1226   a PHY.
1227
1228   Required properties:
1229     - reg : Offset and length of the register set for the device
1230     - compatible : Should define the compatible device type for the
1231       mdio.  Currently, this is most likely to be "fsl,gianfar-mdio"
1232
1233   Example:
1234
1235         mdio@24520 {
1236                 reg = <24520 20>;
1237                 compatible = "fsl,gianfar-mdio";
1238
1239                 ethernet-phy@0 {
1240                         ......
1241                 };
1242         };
1243
1244
1245   b) Gianfar-compatible ethernet nodes
1246
1247   Required properties:
1248
1249     - device_type : Should be "network"
1250     - model : Model of the device.  Can be "TSEC", "eTSEC", or "FEC"
1251     - compatible : Should be "gianfar"
1252     - reg : Offset and length of the register set for the device
1253     - mac-address : List of bytes representing the ethernet address of
1254       this controller
1255     - interrupts : <a b> where a is the interrupt number and b is a
1256       field that represents an encoding of the sense and level
1257       information for the interrupt.  This should be encoded based on
1258       the information in section 2) depending on the type of interrupt
1259       controller you have.
1260     - interrupt-parent : the phandle for the interrupt controller that
1261       services interrupts for this device.
1262     - phy-handle : The phandle for the PHY connected to this ethernet
1263       controller.
1264     - fixed-link : <a b c d e> where a is emulated phy id - choose any,
1265       but unique to the all specified fixed-links, b is duplex - 0 half,
1266       1 full, c is link speed - d#10/d#100/d#1000, d is pause - 0 no
1267       pause, 1 pause, e is asym_pause - 0 no asym_pause, 1 asym_pause.
1268
1269   Recommended properties:
1270
1271     - linux,network-index : This is the intended "index" of this
1272       network device.  This is used by the bootwrapper to interpret
1273       MAC addresses passed by the firmware when no information other
1274       than indices is available to associate an address with a device.
1275     - phy-connection-type : a string naming the controller/PHY interface type,
1276       i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id", "sgmii",
1277       "tbi", or "rtbi".  This property is only really needed if the connection
1278       is of type "rgmii-id", as all other connection types are detected by
1279       hardware.
1280
1281
1282   Example:
1283
1284         ethernet@24000 {
1285                 #size-cells = <0>;
1286                 device_type = "network";
1287                 model = "TSEC";
1288                 compatible = "gianfar";
1289                 reg = <24000 1000>;
1290                 mac-address = [ 00 E0 0C 00 73 00 ];
1291                 interrupts = <d 3 e 3 12 3>;
1292                 interrupt-parent = <40000>;
1293                 phy-handle = <2452000>
1294         };
1295
1296
1297
1298    c) PHY nodes
1299
1300    Required properties:
1301
1302     - device_type : Should be "ethernet-phy"
1303     - interrupts : <a b> where a is the interrupt number and b is a
1304       field that represents an encoding of the sense and level
1305       information for the interrupt.  This should be encoded based on
1306       the information in section 2) depending on the type of interrupt
1307       controller you have.
1308     - interrupt-parent : the phandle for the interrupt controller that
1309       services interrupts for this device.
1310     - reg : The ID number for the phy, usually a small integer
1311     - linux,phandle :  phandle for this node; likely referenced by an
1312       ethernet controller node.
1313
1314
1315    Example:
1316
1317         ethernet-phy@0 {
1318                 linux,phandle = <2452000>
1319                 interrupt-parent = <40000>;
1320                 interrupts = <35 1>;
1321                 reg = <0>;
1322                 device_type = "ethernet-phy";
1323         };
1324
1325
1326    d) Interrupt controllers
1327
1328    Some SOC devices contain interrupt controllers that are different
1329    from the standard Open PIC specification.  The SOC device nodes for
1330    these types of controllers should be specified just like a standard
1331    OpenPIC controller.  Sense and level information should be encoded
1332    as specified in section 2) of this chapter for each device that
1333    specifies an interrupt.
1334
1335    Example :
1336
1337         pic@40000 {
1338                 linux,phandle = <40000>;
1339                 clock-frequency = <0>;
1340                 interrupt-controller;
1341                 #address-cells = <0>;
1342                 reg = <40000 40000>;
1343                 built-in;
1344                 compatible = "chrp,open-pic";
1345                 device_type = "open-pic";
1346                 big-endian;
1347         };
1348
1349
1350    e) I2C
1351
1352    Required properties :
1353
1354     - device_type : Should be "i2c"
1355     - reg : Offset and length of the register set for the device
1356
1357    Recommended properties :
1358
1359     - compatible : Should be "fsl-i2c" for parts compatible with
1360       Freescale I2C specifications.
1361     - interrupts : <a b> where a is the interrupt number and b is a
1362       field that represents an encoding of the sense and level
1363       information for the interrupt.  This should be encoded based on
1364       the information in section 2) depending on the type of interrupt
1365       controller you have.
1366     - interrupt-parent : the phandle for the interrupt controller that
1367       services interrupts for this device.
1368     - dfsrr : boolean; if defined, indicates that this I2C device has
1369       a digital filter sampling rate register
1370     - fsl5200-clocking : boolean; if defined, indicated that this device
1371       uses the FSL 5200 clocking mechanism.
1372
1373    Example :
1374
1375         i2c@3000 {
1376                 interrupt-parent = <40000>;
1377                 interrupts = <1b 3>;
1378                 reg = <3000 18>;
1379                 device_type = "i2c";
1380                 compatible  = "fsl-i2c";
1381                 dfsrr;
1382         };
1383
1384
1385    f) Freescale SOC USB controllers
1386
1387    The device node for a USB controller that is part of a Freescale
1388    SOC is as described in the document "Open Firmware Recommended
1389    Practice : Universal Serial Bus" with the following modifications
1390    and additions :  
1391
1392    Required properties :
1393     - compatible : Should be "fsl-usb2-mph" for multi port host USB
1394       controllers, or "fsl-usb2-dr" for dual role USB controllers
1395     - phy_type : For multi port host USB controllers, should be one of
1396       "ulpi", or "serial". For dual role USB controllers, should be
1397       one of "ulpi", "utmi", "utmi_wide", or "serial".
1398     - reg : Offset and length of the register set for the device
1399     - port0 : boolean; if defined, indicates port0 is connected for
1400       fsl-usb2-mph compatible controllers.  Either this property or
1401       "port1" (or both) must be defined for "fsl-usb2-mph" compatible 
1402       controllers.
1403     - port1 : boolean; if defined, indicates port1 is connected for
1404       fsl-usb2-mph compatible controllers.  Either this property or
1405       "port0" (or both) must be defined for "fsl-usb2-mph" compatible 
1406       controllers.
1407     - dr_mode : indicates the working mode for "fsl-usb2-dr" compatible
1408       controllers.  Can be "host", "peripheral", or "otg".  Default to
1409       "host" if not defined for backward compatibility.
1410
1411    Recommended properties :
1412     - interrupts : <a b> where a is the interrupt number and b is a
1413       field that represents an encoding of the sense and level
1414       information for the interrupt.  This should be encoded based on
1415       the information in section 2) depending on the type of interrupt
1416       controller you have.
1417     - interrupt-parent : the phandle for the interrupt controller that
1418       services interrupts for this device.
1419
1420    Example multi port host USB controller device node :
1421         usb@22000 {
1422                 compatible = "fsl-usb2-mph";
1423                 reg = <22000 1000>;
1424                 #address-cells = <1>;
1425                 #size-cells = <0>;
1426                 interrupt-parent = <700>;
1427                 interrupts = <27 1>;
1428                 phy_type = "ulpi";
1429                 port0;
1430                 port1;
1431         };
1432
1433    Example dual role USB controller device node :
1434         usb@23000 {
1435                 compatible = "fsl-usb2-dr";
1436                 reg = <23000 1000>;
1437                 #address-cells = <1>;
1438                 #size-cells = <0>;
1439                 interrupt-parent = <700>;
1440                 interrupts = <26 1>;
1441                 dr_mode = "otg";
1442                 phy = "ulpi";
1443         };
1444
1445
1446    g) Freescale SOC SEC Security Engines
1447
1448    Required properties:
1449
1450     - device_type : Should be "crypto"
1451     - model : Model of the device.  Should be "SEC1" or "SEC2"
1452     - compatible : Should be "talitos"
1453     - reg : Offset and length of the register set for the device
1454     - interrupts : <a b> where a is the interrupt number and b is a
1455       field that represents an encoding of the sense and level
1456       information for the interrupt.  This should be encoded based on
1457       the information in section 2) depending on the type of interrupt
1458       controller you have.
1459     - interrupt-parent : the phandle for the interrupt controller that
1460       services interrupts for this device.
1461     - num-channels : An integer representing the number of channels
1462       available.
1463     - channel-fifo-len : An integer representing the number of
1464       descriptor pointers each channel fetch fifo can hold.
1465     - exec-units-mask : The bitmask representing what execution units
1466       (EUs) are available. It's a single 32-bit cell. EU information
1467       should be encoded following the SEC's Descriptor Header Dword
1468       EU_SEL0 field documentation, i.e. as follows:
1469
1470         bit 0 = reserved - should be 0
1471         bit 1 = set if SEC has the ARC4 EU (AFEU)
1472         bit 2 = set if SEC has the DES/3DES EU (DEU)
1473         bit 3 = set if SEC has the message digest EU (MDEU)
1474         bit 4 = set if SEC has the random number generator EU (RNG)
1475         bit 5 = set if SEC has the public key EU (PKEU)
1476         bit 6 = set if SEC has the AES EU (AESU)
1477         bit 7 = set if SEC has the Kasumi EU (KEU)
1478
1479       bits 8 through 31 are reserved for future SEC EUs.
1480
1481     - descriptor-types-mask : The bitmask representing what descriptors
1482       are available. It's a single 32-bit cell. Descriptor type
1483       information should be encoded following the SEC's Descriptor
1484       Header Dword DESC_TYPE field documentation, i.e. as follows:
1485
1486         bit 0  = set if SEC supports the aesu_ctr_nonsnoop desc. type
1487         bit 1  = set if SEC supports the ipsec_esp descriptor type
1488         bit 2  = set if SEC supports the common_nonsnoop desc. type
1489         bit 3  = set if SEC supports the 802.11i AES ccmp desc. type
1490         bit 4  = set if SEC supports the hmac_snoop_no_afeu desc. type
1491         bit 5  = set if SEC supports the srtp descriptor type
1492         bit 6  = set if SEC supports the non_hmac_snoop_no_afeu desc.type
1493         bit 7  = set if SEC supports the pkeu_assemble descriptor type
1494         bit 8  = set if SEC supports the aesu_key_expand_output desc.type
1495         bit 9  = set if SEC supports the pkeu_ptmul descriptor type
1496         bit 10 = set if SEC supports the common_nonsnoop_afeu desc. type
1497         bit 11 = set if SEC supports the pkeu_ptadd_dbl descriptor type
1498
1499       ..and so on and so forth.
1500
1501    Example:
1502
1503        /* MPC8548E */
1504        crypto@30000 {
1505                device_type = "crypto";
1506                model = "SEC2";
1507                compatible = "talitos";
1508                reg = <30000 10000>;
1509                interrupts = <1d 3>;
1510                interrupt-parent = <40000>;
1511                num-channels = <4>;
1512                channel-fifo-len = <18>;
1513                exec-units-mask = <000000fe>;
1514                descriptor-types-mask = <012b0ebf>;
1515        };
1516
1517    h) Board Control and Status (BCSR)
1518
1519    Required properties:
1520
1521     - device_type : Should be "board-control"
1522     - reg : Offset and length of the register set for the device
1523
1524     Example:
1525
1526         bcsr@f8000000 {
1527                 device_type = "board-control";
1528                 reg = <f8000000 8000>;
1529         };
1530
1531    i) Freescale QUICC Engine module (QE)
1532    This represents qe module that is installed on PowerQUICC II Pro.
1533
1534    NOTE:  This is an interim binding; it should be updated to fit
1535    in with the CPM binding later in this document.
1536
1537    Basically, it is a bus of devices, that could act more or less
1538    as a complete entity (UCC, USB etc ). All of them should be siblings on
1539    the "root" qe node, using the common properties from there.
1540    The description below applies to the qe of MPC8360 and
1541    more nodes and properties would be extended in the future.
1542
1543    i) Root QE device
1544
1545    Required properties:
1546    - compatible : should be "fsl,qe";
1547    - model : precise model of the QE, Can be "QE", "CPM", or "CPM2"
1548    - reg : offset and length of the device registers.
1549    - bus-frequency : the clock frequency for QUICC Engine.
1550
1551    Recommended properties
1552    - brg-frequency : the internal clock source frequency for baud-rate
1553      generators in Hz.
1554
1555    Example:
1556         qe@e0100000 {
1557                 #address-cells = <1>;
1558                 #size-cells = <1>;
1559                 #interrupt-cells = <2>;
1560                 compatible = "fsl,qe";
1561                 ranges = <0 e0100000 00100000>;
1562                 reg = <e0100000 480>;
1563                 brg-frequency = <0>;
1564                 bus-frequency = <179A7B00>;
1565         }
1566
1567
1568    ii) SPI (Serial Peripheral Interface)
1569
1570    Required properties:
1571    - cell-index : SPI controller index.
1572    - compatible : should be "fsl,spi".
1573    - mode : the SPI operation mode, it can be "cpu" or "cpu-qe".
1574    - reg : Offset and length of the register set for the device
1575    - interrupts : <a b> where a is the interrupt number and b is a
1576      field that represents an encoding of the sense and level
1577      information for the interrupt.  This should be encoded based on
1578      the information in section 2) depending on the type of interrupt
1579      controller you have.
1580    - interrupt-parent : the phandle for the interrupt controller that
1581      services interrupts for this device.
1582
1583    Example:
1584         spi@4c0 {
1585                 cell-index = <0>;
1586                 compatible = "fsl,spi";
1587                 reg = <4c0 40>;
1588                 interrupts = <82 0>;
1589                 interrupt-parent = <700>;
1590                 mode = "cpu";
1591         };
1592
1593
1594    iii) USB (Universal Serial Bus Controller)
1595
1596    Required properties:
1597    - compatible : could be "qe_udc" or "fhci-hcd".
1598    - mode : the could be "host" or "slave".
1599    - reg : Offset and length of the register set for the device
1600    - interrupts : <a b> where a is the interrupt number and b is a
1601      field that represents an encoding of the sense and level
1602      information for the interrupt.  This should be encoded based on
1603      the information in section 2) depending on the type of interrupt
1604      controller you have.
1605    - interrupt-parent : the phandle for the interrupt controller that
1606      services interrupts for this device.
1607
1608    Example(slave):
1609         usb@6c0 {
1610                 compatible = "qe_udc";
1611                 reg = <6c0 40>;
1612                 interrupts = <8b 0>;
1613                 interrupt-parent = <700>;
1614                 mode = "slave";
1615         };
1616
1617
1618    iv) UCC (Unified Communications Controllers)
1619
1620    Required properties:
1621    - device_type : should be "network", "hldc", "uart", "transparent"
1622      "bisync", "atm", or "serial".
1623    - compatible : could be "ucc_geth" or "fsl_atm" and so on.
1624    - model : should be "UCC".
1625    - device-id : the ucc number(1-8), corresponding to UCCx in UM.
1626    - reg : Offset and length of the register set for the device
1627    - interrupts : <a b> where a is the interrupt number and b is a
1628      field that represents an encoding of the sense and level
1629      information for the interrupt.  This should be encoded based on
1630      the information in section 2) depending on the type of interrupt
1631      controller you have.
1632    - interrupt-parent : the phandle for the interrupt controller that
1633      services interrupts for this device.
1634    - pio-handle : The phandle for the Parallel I/O port configuration.
1635    - port-number : for UART drivers, the port number to use, between 0 and 3.
1636      This usually corresponds to the /dev/ttyQE device, e.g. <0> = /dev/ttyQE0.
1637      The port number is added to the minor number of the device.  Unlike the
1638      CPM UART driver, the port-number is required for the QE UART driver.
1639    - soft-uart : for UART drivers, if specified this means the QE UART device
1640      driver should use "Soft-UART" mode, which is needed on some SOCs that have
1641      broken UART hardware.  Soft-UART is provided via a microcode upload.
1642    - rx-clock-name: the UCC receive clock source
1643      "none": clock source is disabled
1644      "brg1" through "brg16": clock source is BRG1-BRG16, respectively
1645      "clk1" through "clk24": clock source is CLK1-CLK24, respectively
1646    - tx-clock-name: the UCC transmit clock source
1647      "none": clock source is disabled
1648      "brg1" through "brg16": clock source is BRG1-BRG16, respectively
1649      "clk1" through "clk24": clock source is CLK1-CLK24, respectively
1650    The following two properties are deprecated.  rx-clock has been replaced
1651    with rx-clock-name, and tx-clock has been replaced with tx-clock-name.
1652    Drivers that currently use the deprecated properties should continue to
1653    do so, in order to support older device trees, but they should be updated
1654    to check for the new properties first.
1655    - rx-clock : represents the UCC receive clock source.
1656      0x00 : clock source is disabled;
1657      0x1~0x10 : clock source is BRG1~BRG16 respectively;
1658      0x11~0x28: clock source is QE_CLK1~QE_CLK24 respectively.
1659    - tx-clock: represents the UCC transmit clock source;
1660      0x00 : clock source is disabled;
1661      0x1~0x10 : clock source is BRG1~BRG16 respectively;
1662      0x11~0x28: clock source is QE_CLK1~QE_CLK24 respectively.
1663
1664    Required properties for network device_type:
1665    - mac-address : list of bytes representing the ethernet address.
1666    - phy-handle : The phandle for the PHY connected to this controller.
1667
1668    Recommended properties:
1669    - linux,network-index : This is the intended "index" of this
1670      network device.  This is used by the bootwrapper to interpret
1671      MAC addresses passed by the firmware when no information other
1672      than indices is available to associate an address with a device.
1673    - phy-connection-type : a string naming the controller/PHY interface type,
1674      i.e., "mii" (default), "rmii", "gmii", "rgmii", "rgmii-id" (Internal
1675      Delay), "rgmii-txid" (delay on TX only), "rgmii-rxid" (delay on RX only),
1676      "tbi", or "rtbi".
1677
1678    Example:
1679         ucc@2000 {
1680                 device_type = "network";
1681                 compatible = "ucc_geth";
1682                 model = "UCC";
1683                 device-id = <1>;
1684                 reg = <2000 200>;
1685                 interrupts = <a0 0>;
1686                 interrupt-parent = <700>;
1687                 mac-address = [ 00 04 9f 00 23 23 ];
1688                 rx-clock = "none";
1689                 tx-clock = "clk9";
1690                 phy-handle = <212000>;
1691                 phy-connection-type = "gmii";
1692                 pio-handle = <140001>;
1693         };
1694
1695
1696    v) Parallel I/O Ports
1697
1698    This node configures Parallel I/O ports for CPUs with QE support.
1699    The node should reside in the "soc" node of the tree.  For each
1700    device that using parallel I/O ports, a child node should be created.
1701    See the definition of the Pin configuration nodes below for more
1702    information.
1703
1704    Required properties:
1705    - device_type : should be "par_io".
1706    - reg : offset to the register set and its length.
1707    - num-ports : number of Parallel I/O ports
1708
1709    Example:
1710         par_io@1400 {
1711                 reg = <1400 100>;
1712                 #address-cells = <1>;
1713                 #size-cells = <0>;
1714                 device_type = "par_io";
1715                 num-ports = <7>;
1716                 ucc_pin@01 {
1717                         ......
1718                 };
1719
1720
1721    vi) Pin configuration nodes
1722
1723    Required properties:
1724    - linux,phandle : phandle of this node; likely referenced by a QE
1725      device.
1726    - pio-map : array of pin configurations.  Each pin is defined by 6
1727      integers.  The six numbers are respectively: port, pin, dir,
1728      open_drain, assignment, has_irq.
1729      - port : port number of the pin; 0-6 represent port A-G in UM.
1730      - pin : pin number in the port.
1731      - dir : direction of the pin, should encode as follows:
1732
1733         0 = The pin is disabled
1734         1 = The pin is an output
1735         2 = The pin is an input
1736         3 = The pin is I/O
1737
1738      - open_drain : indicates the pin is normal or wired-OR:
1739
1740         0 = The pin is actively driven as an output
1741         1 = The pin is an open-drain driver. As an output, the pin is
1742             driven active-low, otherwise it is three-stated.
1743
1744      - assignment : function number of the pin according to the Pin Assignment
1745        tables in User Manual.  Each pin can have up to 4 possible functions in
1746        QE and two options for CPM.
1747      - has_irq : indicates if the pin is used as source of external
1748        interrupts.
1749
1750    Example:
1751         ucc_pin@01 {
1752                 linux,phandle = <140001>;
1753                 pio-map = <
1754                 /* port  pin  dir  open_drain  assignment  has_irq */
1755                         0  3  1  0  1  0        /* TxD0 */
1756                         0  4  1  0  1  0        /* TxD1 */
1757                         0  5  1  0  1  0        /* TxD2 */
1758                         0  6  1  0  1  0        /* TxD3 */
1759                         1  6  1  0  3  0        /* TxD4 */
1760                         1  7  1  0  1  0        /* TxD5 */
1761                         1  9  1  0  2  0        /* TxD6 */
1762                         1  a  1  0  2  0        /* TxD7 */
1763                         0  9  2  0  1  0        /* RxD0 */
1764                         0  a  2  0  1  0        /* RxD1 */
1765                         0  b  2  0  1  0        /* RxD2 */
1766                         0  c  2  0  1  0        /* RxD3 */
1767                         0  d  2  0  1  0        /* RxD4 */
1768                         1  1  2  0  2  0        /* RxD5 */
1769                         1  0  2  0  2  0        /* RxD6 */
1770                         1  4  2  0  2  0        /* RxD7 */
1771                         0  7  1  0  1  0        /* TX_EN */
1772                         0  8  1  0  1  0        /* TX_ER */
1773                         0  f  2  0  1  0        /* RX_DV */
1774                         0  10 2  0  1  0        /* RX_ER */
1775                         0  0  2  0  1  0        /* RX_CLK */
1776                         2  9  1  0  3  0        /* GTX_CLK - CLK10 */
1777                         2  8  2  0  1  0>;      /* GTX125 - CLK9 */
1778         };
1779
1780    vii) Multi-User RAM (MURAM)
1781
1782    Required properties:
1783    - compatible : should be "fsl,qe-muram", "fsl,cpm-muram".
1784    - mode : the could be "host" or "slave".
1785    - ranges : Should be defined as specified in 1) to describe the
1786       translation of MURAM addresses.
1787    - data-only : sub-node which defines the address area under MURAM
1788       bus that can be allocated as data/parameter
1789
1790    Example:
1791
1792         muram@10000 {
1793                 compatible = "fsl,qe-muram", "fsl,cpm-muram";
1794                 ranges = <0 00010000 0000c000>;
1795
1796                 data-only@0{
1797                         compatible = "fsl,qe-muram-data",
1798                                      "fsl,cpm-muram-data";
1799                         reg = <0 c000>;
1800                 };
1801         };
1802
1803    viii) Uploaded QE firmware
1804
1805          If a new firwmare has been uploaded to the QE (usually by the
1806          boot loader), then a 'firmware' child node should be added to the QE
1807          node.  This node provides information on the uploaded firmware that
1808          device drivers may need.
1809
1810          Required properties:
1811          - id: The string name of the firmware.  This is taken from the 'id'
1812                member of the qe_firmware structure of the uploaded firmware.
1813                Device drivers can search this string to determine if the
1814                firmware they want is already present.
1815          - extended-modes: The Extended Modes bitfield, taken from the
1816                            firmware binary.  It is a 64-bit number represented
1817                            as an array of two 32-bit numbers.
1818          - virtual-traps: The virtual traps, taken from the firmware binary.
1819                           It is an array of 8 32-bit numbers.
1820
1821          Example:
1822
1823                 firmware {
1824                         id = "Soft-UART";
1825                         extended-modes = <0 0>;
1826                         virtual-traps = <0 0 0 0 0 0 0 0>;
1827                 }
1828
1829    j) CFI or JEDEC memory-mapped NOR flash
1830
1831     Flash chips (Memory Technology Devices) are often used for solid state
1832     file systems on embedded devices.
1833
1834      - compatible : should contain the specific model of flash chip(s)
1835        used, if known, followed by either "cfi-flash" or "jedec-flash"
1836      - reg : Address range of the flash chip
1837      - bank-width : Width (in bytes) of the flash bank.  Equal to the
1838        device width times the number of interleaved chips.
1839      - device-width : (optional) Width of a single flash chip.  If
1840        omitted, assumed to be equal to 'bank-width'.
1841      - #address-cells, #size-cells : Must be present if the flash has
1842        sub-nodes representing partitions (see below).  In this case
1843        both #address-cells and #size-cells must be equal to 1.
1844
1845     For JEDEC compatible devices, the following additional properties
1846     are defined:
1847
1848      - vendor-id : Contains the flash chip's vendor id (1 byte).
1849      - device-id : Contains the flash chip's device id (1 byte).
1850
1851     In addition to the information on the flash bank itself, the
1852     device tree may optionally contain additional information
1853     describing partitions of the flash address space.  This can be
1854     used on platforms which have strong conventions about which
1855     portions of the flash are used for what purposes, but which don't
1856     use an on-flash partition table such as RedBoot.
1857
1858     Each partition is represented as a sub-node of the flash device.
1859     Each node's name represents the name of the corresponding
1860     partition of the flash device.
1861
1862     Flash partitions
1863      - reg : The partition's offset and size within the flash bank.
1864      - label : (optional) The label / name for this flash partition.
1865        If omitted, the label is taken from the node name (excluding
1866        the unit address).
1867      - read-only : (optional) This parameter, if present, is a hint to
1868        Linux that this flash partition should only be mounted
1869        read-only.  This is usually used for flash partitions
1870        containing early-boot firmware images or data which should not
1871        be clobbered.
1872
1873     Example:
1874
1875         flash@ff000000 {
1876                 compatible = "amd,am29lv128ml", "cfi-flash";
1877                 reg = <ff000000 01000000>;
1878                 bank-width = <4>;
1879                 device-width = <1>;
1880                 #address-cells = <1>;
1881                 #size-cells = <1>;
1882                 fs@0 {
1883                         label = "fs";
1884                         reg = <0 f80000>;
1885                 };
1886                 firmware@f80000 {
1887                         label ="firmware";
1888                         reg = <f80000 80000>;
1889                         read-only;
1890                 };
1891         };
1892
1893    k) Global Utilities Block
1894
1895    The global utilities block controls power management, I/O device
1896    enabling, power-on-reset configuration monitoring, general-purpose
1897    I/O signal configuration, alternate function selection for multiplexed
1898    signals, and clock control.
1899
1900    Required properties:
1901
1902     - compatible : Should define the compatible device type for
1903       global-utilities.
1904     - reg : Offset and length of the register set for the device.
1905
1906   Recommended properties:
1907
1908     - fsl,has-rstcr : Indicates that the global utilities register set
1909       contains a functioning "reset control register" (i.e. the board
1910       is wired to reset upon setting the HRESET_REQ bit in this register).
1911
1912     Example:
1913
1914         global-utilities@e0000 {        /* global utilities block */
1915                 compatible = "fsl,mpc8548-guts";
1916                 reg = <e0000 1000>;
1917                 fsl,has-rstcr;
1918         };
1919
1920    l) Freescale Communications Processor Module
1921
1922    NOTE: This is an interim binding, and will likely change slightly,
1923    as more devices are supported.  The QE bindings especially are
1924    incomplete.
1925
1926    i) Root CPM node
1927
1928    Properties:
1929    - compatible : "fsl,cpm1", "fsl,cpm2", or "fsl,qe".
1930    - reg : A 48-byte region beginning with CPCR.
1931
1932    Example:
1933         cpm@119c0 {
1934                 #address-cells = <1>;
1935                 #size-cells = <1>;
1936                 #interrupt-cells = <2>;
1937                 compatible = "fsl,mpc8272-cpm", "fsl,cpm2";
1938                 reg = <119c0 30>;
1939         }
1940
1941    ii) Properties common to mulitple CPM/QE devices
1942
1943    - fsl,cpm-command : This value is ORed with the opcode and command flag
1944                        to specify the device on which a CPM command operates.
1945
1946    - fsl,cpm-brg : Indicates which baud rate generator the device
1947                    is associated with.  If absent, an unused BRG
1948                    should be dynamically allocated.  If zero, the
1949                    device uses an external clock rather than a BRG.
1950
1951    - reg : Unless otherwise specified, the first resource represents the
1952            scc/fcc/ucc registers, and the second represents the device's
1953            parameter RAM region (if it has one).
1954
1955    iii) Serial
1956
1957    Currently defined compatibles:
1958    - fsl,cpm1-smc-uart
1959    - fsl,cpm2-smc-uart
1960    - fsl,cpm1-scc-uart
1961    - fsl,cpm2-scc-uart
1962    - fsl,qe-uart
1963
1964    Example:
1965
1966         serial@11a00 {
1967                 device_type = "serial";
1968                 compatible = "fsl,mpc8272-scc-uart",
1969                              "fsl,cpm2-scc-uart";
1970                 reg = <11a00 20 8000 100>;
1971                 interrupts = <28 8>;
1972                 interrupt-parent = <&PIC>;
1973                 fsl,cpm-brg = <1>;
1974                 fsl,cpm-command = <00800000>;
1975         };
1976
1977    iii) Network
1978
1979    Currently defined compatibles:
1980    - fsl,cpm1-scc-enet
1981    - fsl,cpm2-scc-enet
1982    - fsl,cpm1-fec-enet
1983    - fsl,cpm2-fcc-enet (third resource is GFEMR)
1984    - fsl,qe-enet
1985
1986    Example:
1987
1988         ethernet@11300 {
1989                 device_type = "network";
1990                 compatible = "fsl,mpc8272-fcc-enet",
1991                              "fsl,cpm2-fcc-enet";
1992                 reg = <11300 20 8400 100 11390 1>;
1993                 local-mac-address = [ 00 00 00 00 00 00 ];
1994                 interrupts = <20 8>;
1995                 interrupt-parent = <&PIC>;
1996                 phy-handle = <&PHY0>;
1997                 linux,network-index = <0>;
1998                 fsl,cpm-command = <12000300>;
1999         };
2000
2001    iv) MDIO
2002
2003    Currently defined compatibles:
2004    fsl,pq1-fec-mdio (reg is same as first resource of FEC device)
2005    fsl,cpm2-mdio-bitbang (reg is port C registers)
2006
2007    Properties for fsl,cpm2-mdio-bitbang:
2008    fsl,mdio-pin : pin of port C controlling mdio data
2009    fsl,mdc-pin : pin of port C controlling mdio clock
2010
2011    Example:
2012
2013         mdio@10d40 {
2014                 device_type = "mdio";
2015                 compatible = "fsl,mpc8272ads-mdio-bitbang",
2016                              "fsl,mpc8272-mdio-bitbang",
2017                              "fsl,cpm2-mdio-bitbang";
2018                 reg = <10d40 14>;
2019                 #address-cells = <1>;
2020                 #size-cells = <0>;
2021                 fsl,mdio-pin = <12>;
2022                 fsl,mdc-pin = <13>;
2023         };
2024
2025    v) Baud Rate Generators
2026
2027    Currently defined compatibles:
2028    fsl,cpm-brg
2029    fsl,cpm1-brg
2030    fsl,cpm2-brg
2031
2032    Properties:
2033    - reg : There may be an arbitrary number of reg resources; BRG
2034      numbers are assigned to these in order.
2035    - clock-frequency : Specifies the base frequency driving
2036      the BRG.
2037
2038    Example:
2039
2040         brg@119f0 {
2041                 compatible = "fsl,mpc8272-brg",
2042                              "fsl,cpm2-brg",
2043                              "fsl,cpm-brg";
2044                 reg = <119f0 10 115f0 10>;
2045                 clock-frequency = <d#25000000>;
2046         };
2047
2048    vi) Interrupt Controllers
2049
2050    Currently defined compatibles:
2051    - fsl,cpm1-pic
2052      - only one interrupt cell
2053    - fsl,pq1-pic
2054    - fsl,cpm2-pic
2055      - second interrupt cell is level/sense:
2056        - 2 is falling edge
2057        - 8 is active low
2058
2059    Example:
2060
2061         interrupt-controller@10c00 {
2062                 #interrupt-cells = <2>;
2063                 interrupt-controller;
2064                 reg = <10c00 80>;
2065                 compatible = "mpc8272-pic", "fsl,cpm2-pic";
2066         };
2067
2068    vii) USB (Universal Serial Bus Controller)
2069
2070    Properties:
2071    - compatible : "fsl,cpm1-usb", "fsl,cpm2-usb", "fsl,qe-usb"
2072
2073    Example:
2074         usb@11bc0 {
2075                 #address-cells = <1>;
2076                 #size-cells = <0>;
2077                 compatible = "fsl,cpm2-usb";
2078                 reg = <11b60 18 8b00 100>;
2079                 interrupts = <b 8>;
2080                 interrupt-parent = <&PIC>;
2081                 fsl,cpm-command = <2e600000>;
2082         };
2083
2084    viii) Multi-User RAM (MURAM)
2085
2086    The multi-user/dual-ported RAM is expressed as a bus under the CPM node.
2087
2088    Ranges must be set up subject to the following restrictions:
2089
2090    - Children's reg nodes must be offsets from the start of all muram, even
2091      if the user-data area does not begin at zero.
2092    - If multiple range entries are used, the difference between the parent
2093      address and the child address must be the same in all, so that a single
2094      mapping can cover them all while maintaining the ability to determine
2095      CPM-side offsets with pointer subtraction.  It is recommended that
2096      multiple range entries not be used.
2097    - A child address of zero must be translatable, even if no reg resources
2098      contain it.
2099
2100    A child "data" node must exist, compatible with "fsl,cpm-muram-data", to
2101    indicate the portion of muram that is usable by the OS for arbitrary
2102    purposes.  The data node may have an arbitrary number of reg resources,
2103    all of which contribute to the allocatable muram pool.
2104
2105    Example, based on mpc8272:
2106
2107         muram@0 {
2108                 #address-cells = <1>;
2109                 #size-cells = <1>;
2110                 ranges = <0 0 10000>;
2111
2112                 data@0 {
2113                         compatible = "fsl,cpm-muram-data";
2114                         reg = <0 2000 9800 800>;
2115                 };
2116         };
2117
2118    m) Chipselect/Local Bus
2119
2120    Properties:
2121    - name : Should be localbus
2122    - #address-cells : Should be either two or three.  The first cell is the
2123                       chipselect number, and the remaining cells are the
2124                       offset into the chipselect.
2125    - #size-cells : Either one or two, depending on how large each chipselect
2126                    can be.
2127    - ranges : Each range corresponds to a single chipselect, and cover
2128               the entire access window as configured.
2129
2130    Example:
2131         localbus@f0010100 {
2132                 compatible = "fsl,mpc8272-localbus",
2133                              "fsl,pq2-localbus";
2134                 #address-cells = <2>;
2135                 #size-cells = <1>;
2136                 reg = <f0010100 40>;
2137
2138                 ranges = <0 0 fe000000 02000000
2139                           1 0 f4500000 00008000>;
2140
2141                 flash@0,0 {
2142                         compatible = "jedec-flash";
2143                         reg = <0 0 2000000>;
2144                         bank-width = <4>;
2145                         device-width = <1>;
2146                 };
2147
2148                 board-control@1,0 {
2149                         reg = <1 0 20>;
2150                         compatible = "fsl,mpc8272ads-bcsr";
2151                 };
2152         };
2153
2154
2155     n) 4xx/Axon EMAC ethernet nodes
2156
2157     The EMAC ethernet controller in IBM and AMCC 4xx chips, and also
2158     the Axon bridge.  To operate this needs to interact with a ths
2159     special McMAL DMA controller, and sometimes an RGMII or ZMII
2160     interface.  In addition to the nodes and properties described
2161     below, the node for the OPB bus on which the EMAC sits must have a
2162     correct clock-frequency property.
2163
2164       i) The EMAC node itself
2165
2166     Required properties:
2167     - device_type       : "network"
2168
2169     - compatible        : compatible list, contains 2 entries, first is
2170                           "ibm,emac-CHIP" where CHIP is the host ASIC (440gx,
2171                           405gp, Axon) and second is either "ibm,emac" or
2172                           "ibm,emac4".  For Axon, thus, we have: "ibm,emac-axon",
2173                           "ibm,emac4"
2174     - interrupts        : <interrupt mapping for EMAC IRQ and WOL IRQ>
2175     - interrupt-parent  : optional, if needed for interrupt mapping
2176     - reg               : <registers mapping>
2177     - local-mac-address : 6 bytes, MAC address
2178     - mal-device        : phandle of the associated McMAL node
2179     - mal-tx-channel    : 1 cell, index of the tx channel on McMAL associated
2180                           with this EMAC
2181     - mal-rx-channel    : 1 cell, index of the rx channel on McMAL associated
2182                           with this EMAC
2183     - cell-index        : 1 cell, hardware index of the EMAC cell on a given
2184                           ASIC (typically 0x0 and 0x1 for EMAC0 and EMAC1 on
2185                           each Axon chip)
2186     - max-frame-size    : 1 cell, maximum frame size supported in bytes
2187     - rx-fifo-size      : 1 cell, Rx fifo size in bytes for 10 and 100 Mb/sec
2188                           operations.
2189                           For Axon, 2048
2190     - tx-fifo-size      : 1 cell, Tx fifo size in bytes for 10 and 100 Mb/sec
2191                           operations.
2192                           For Axon, 2048.
2193     - fifo-entry-size   : 1 cell, size of a fifo entry (used to calculate
2194                           thresholds).
2195                           For Axon, 0x00000010
2196     - mal-burst-size    : 1 cell, MAL burst size (used to calculate thresholds)
2197                           in bytes.
2198                           For Axon, 0x00000100 (I think ...)
2199     - phy-mode          : string, mode of operations of the PHY interface.
2200                           Supported values are: "mii", "rmii", "smii", "rgmii",
2201                           "tbi", "gmii", rtbi", "sgmii".
2202                           For Axon on CAB, it is "rgmii"
2203     - mdio-device       : 1 cell, required iff using shared MDIO registers
2204                           (440EP).  phandle of the EMAC to use to drive the
2205                           MDIO lines for the PHY used by this EMAC.
2206     - zmii-device       : 1 cell, required iff connected to a ZMII.  phandle of
2207                           the ZMII device node
2208     - zmii-channel      : 1 cell, required iff connected to a ZMII.  Which ZMII
2209                           channel or 0xffffffff if ZMII is only used for MDIO.
2210     - rgmii-device      : 1 cell, required iff connected to an RGMII. phandle
2211                           of the RGMII device node.
2212                           For Axon: phandle of plb5/plb4/opb/rgmii
2213     - rgmii-channel     : 1 cell, required iff connected to an RGMII.  Which
2214                           RGMII channel is used by this EMAC.
2215                           Fox Axon: present, whatever value is appropriate for each
2216                           EMAC, that is the content of the current (bogus) "phy-port"
2217                           property.
2218
2219     Recommended properties:
2220     - linux,network-index : This is the intended "index" of this
2221       network device.  This is used by the bootwrapper to interpret
2222       MAC addresses passed by the firmware when no information other
2223       than indices is available to associate an address with a device.
2224
2225     Optional properties:
2226     - phy-address       : 1 cell, optional, MDIO address of the PHY. If absent,
2227                           a search is performed.
2228     - phy-map           : 1 cell, optional, bitmap of addresses to probe the PHY
2229                           for, used if phy-address is absent. bit 0x00000001 is
2230                           MDIO address 0.
2231                           For Axon it can be absent, thouugh my current driver
2232                           doesn't handle phy-address yet so for now, keep
2233                           0x00ffffff in it.
2234     - rx-fifo-size-gige : 1 cell, Rx fifo size in bytes for 1000 Mb/sec
2235                           operations (if absent the value is the same as
2236                           rx-fifo-size).  For Axon, either absent or 2048.
2237     - tx-fifo-size-gige : 1 cell, Tx fifo size in bytes for 1000 Mb/sec
2238                           operations (if absent the value is the same as
2239                           tx-fifo-size). For Axon, either absent or 2048.
2240     - tah-device        : 1 cell, optional. If connected to a TAH engine for
2241                           offload, phandle of the TAH device node.
2242     - tah-channel       : 1 cell, optional. If appropriate, channel used on the
2243                           TAH engine.
2244
2245     Example:
2246
2247         EMAC0: ethernet@40000800 {
2248                 linux,network-index = <0>;
2249                 device_type = "network";
2250                 compatible = "ibm,emac-440gp", "ibm,emac";
2251                 interrupt-parent = <&UIC1>;
2252                 interrupts = <1c 4 1d 4>;
2253                 reg = <40000800 70>;
2254                 local-mac-address = [00 04 AC E3 1B 1E];
2255                 mal-device = <&MAL0>;
2256                 mal-tx-channel = <0 1>;
2257                 mal-rx-channel = <0>;
2258                 cell-index = <0>;
2259                 max-frame-size = <5dc>;
2260                 rx-fifo-size = <1000>;
2261                 tx-fifo-size = <800>;
2262                 phy-mode = "rmii";
2263                 phy-map = <00000001>;
2264                 zmii-device = <&ZMII0>;
2265                 zmii-channel = <0>;
2266         };
2267
2268       ii) McMAL node
2269
2270     Required properties:
2271     - device_type        : "dma-controller"
2272     - compatible         : compatible list, containing 2 entries, first is
2273                            "ibm,mcmal-CHIP" where CHIP is the host ASIC (like
2274                            emac) and the second is either "ibm,mcmal" or
2275                            "ibm,mcmal2".
2276                            For Axon, "ibm,mcmal-axon","ibm,mcmal2"
2277     - interrupts         : <interrupt mapping for the MAL interrupts sources:
2278                            5 sources: tx_eob, rx_eob, serr, txde, rxde>.
2279                            For Axon: This is _different_ from the current
2280                            firmware.  We use the "delayed" interrupts for txeob
2281                            and rxeob. Thus we end up with mapping those 5 MPIC
2282                            interrupts, all level positive sensitive: 10, 11, 32,
2283                            33, 34 (in decimal)
2284     - dcr-reg            : < DCR registers range >
2285     - dcr-parent         : if needed for dcr-reg
2286     - num-tx-chans       : 1 cell, number of Tx channels
2287     - num-rx-chans       : 1 cell, number of Rx channels
2288
2289       iii) ZMII node
2290
2291     Required properties:
2292     - compatible         : compatible list, containing 2 entries, first is
2293                            "ibm,zmii-CHIP" where CHIP is the host ASIC (like
2294                            EMAC) and the second is "ibm,zmii".
2295                            For Axon, there is no ZMII node.
2296     - reg                : <registers mapping>
2297
2298       iv) RGMII node
2299
2300     Required properties:
2301     - compatible         : compatible list, containing 2 entries, first is
2302                            "ibm,rgmii-CHIP" where CHIP is the host ASIC (like
2303                            EMAC) and the second is "ibm,rgmii".
2304                            For Axon, "ibm,rgmii-axon","ibm,rgmii"
2305     - reg                : <registers mapping>
2306     - revision           : as provided by the RGMII new version register if
2307                            available.
2308                            For Axon: 0x0000012a
2309
2310    o) Xilinx IP cores
2311
2312    The Xilinx EDK toolchain ships with a set of IP cores (devices) for use
2313    in Xilinx Spartan and Virtex FPGAs.  The devices cover the whole range
2314    of standard device types (network, serial, etc.) and miscellanious
2315    devices (gpio, LCD, spi, etc).  Also, since these devices are
2316    implemented within the fpga fabric every instance of the device can be
2317    synthesised with different options that change the behaviour.
2318
2319    Each IP-core has a set of parameters which the FPGA designer can use to
2320    control how the core is synthesized.  Historically, the EDK tool would
2321    extract the device parameters relevant to device drivers and copy them
2322    into an 'xparameters.h' in the form of #define symbols.  This tells the
2323    device drivers how the IP cores are configured, but it requres the kernel
2324    to be recompiled every time the FPGA bitstream is resynthesized.
2325
2326    The new approach is to export the parameters into the device tree and
2327    generate a new device tree each time the FPGA bitstream changes.  The
2328    parameters which used to be exported as #defines will now become
2329    properties of the device node.  In general, device nodes for IP-cores
2330    will take the following form:
2331
2332         (name): (generic-name)@(base-address) {
2333                 compatible = "xlnx,(ip-core-name)-(HW_VER)"
2334                              [, (list of compatible devices), ...];
2335                 reg = <(baseaddr) (size)>;
2336                 interrupt-parent = <&interrupt-controller-phandle>;
2337                 interrupts = < ... >;
2338                 xlnx,(parameter1) = "(string-value)";
2339                 xlnx,(parameter2) = <(int-value)>;
2340         };
2341
2342         (generic-name):   an open firmware-style name that describes the
2343                         generic class of device.  Preferably, this is one word, such
2344                         as 'serial' or 'ethernet'.
2345         (ip-core-name): the name of the ip block (given after the BEGIN
2346                         directive in system.mhs).  Should be in lowercase
2347                         and all underscores '_' converted to dashes '-'.
2348         (name):         is derived from the "PARAMETER INSTANCE" value.
2349         (parameter#):   C_* parameters from system.mhs.  The C_ prefix is
2350                         dropped from the parameter name, the name is converted
2351                         to lowercase and all underscore '_' characters are
2352                         converted to dashes '-'.
2353         (baseaddr):     the baseaddr parameter value (often named C_BASEADDR).
2354         (HW_VER):       from the HW_VER parameter.
2355         (size):         the address range size (often C_HIGHADDR - C_BASEADDR + 1).
2356
2357    Typically, the compatible list will include the exact IP core version
2358    followed by an older IP core version which implements the same
2359    interface or any other device with the same interface.
2360
2361    'reg', 'interrupt-parent' and 'interrupts' are all optional properties.
2362
2363    For example, the following block from system.mhs:
2364
2365         BEGIN opb_uartlite
2366                 PARAMETER INSTANCE = opb_uartlite_0
2367                 PARAMETER HW_VER = 1.00.b
2368                 PARAMETER C_BAUDRATE = 115200
2369                 PARAMETER C_DATA_BITS = 8
2370                 PARAMETER C_ODD_PARITY = 0
2371                 PARAMETER C_USE_PARITY = 0
2372                 PARAMETER C_CLK_FREQ = 50000000
2373                 PARAMETER C_BASEADDR = 0xEC100000
2374                 PARAMETER C_HIGHADDR = 0xEC10FFFF
2375                 BUS_INTERFACE SOPB = opb_7
2376                 PORT OPB_Clk = CLK_50MHz
2377                 PORT Interrupt = opb_uartlite_0_Interrupt
2378                 PORT RX = opb_uartlite_0_RX
2379                 PORT TX = opb_uartlite_0_TX
2380                 PORT OPB_Rst = sys_bus_reset_0
2381         END
2382
2383    becomes the following device tree node:
2384
2385         opb_uartlite_0: serial@ec100000 {
2386                 device_type = "serial";
2387                 compatible = "xlnx,opb-uartlite-1.00.b";
2388                 reg = <ec100000 10000>;
2389                 interrupt-parent = <&opb_intc_0>;
2390                 interrupts = <1 0>; // got this from the opb_intc parameters
2391                 current-speed = <d#115200>;     // standard serial device prop
2392                 clock-frequency = <d#50000000>; // standard serial device prop
2393                 xlnx,data-bits = <8>;
2394                 xlnx,odd-parity = <0>;
2395                 xlnx,use-parity = <0>;
2396         };
2397
2398    Some IP cores actually implement 2 or more logical devices.  In
2399    this case, the device should still describe the whole IP core with
2400    a single node and add a child node for each logical device.  The
2401    ranges property can be used to translate from parent IP-core to the
2402    registers of each device.  In addition, the parent node should be
2403    compatible with the bus type 'xlnx,compound', and should contain
2404    #address-cells and #size-cells, as with any other bus.  (Note: this
2405    makes the assumption that both logical devices have the same bus
2406    binding.  If this is not true, then separate nodes should be used
2407    for each logical device).  The 'cell-index' property can be used to
2408    enumerate logical devices within an IP core.  For example, the
2409    following is the system.mhs entry for the dual ps2 controller found
2410    on the ml403 reference design.
2411
2412         BEGIN opb_ps2_dual_ref
2413                 PARAMETER INSTANCE = opb_ps2_dual_ref_0
2414                 PARAMETER HW_VER = 1.00.a
2415                 PARAMETER C_BASEADDR = 0xA9000000
2416                 PARAMETER C_HIGHADDR = 0xA9001FFF
2417                 BUS_INTERFACE SOPB = opb_v20_0
2418                 PORT Sys_Intr1 = ps2_1_intr
2419                 PORT Sys_Intr2 = ps2_2_intr
2420                 PORT Clkin1 = ps2_clk_rx_1
2421                 PORT Clkin2 = ps2_clk_rx_2
2422                 PORT Clkpd1 = ps2_clk_tx_1
2423                 PORT Clkpd2 = ps2_clk_tx_2
2424                 PORT Rx1 = ps2_d_rx_1
2425                 PORT Rx2 = ps2_d_rx_2
2426                 PORT Txpd1 = ps2_d_tx_1
2427                 PORT Txpd2 = ps2_d_tx_2
2428         END
2429
2430    It would result in the following device tree nodes:
2431
2432         opb_ps2_dual_ref_0: opb-ps2-dual-ref@a9000000 {
2433                 #address-cells = <1>;
2434                 #size-cells = <1>;
2435                 compatible = "xlnx,compound";
2436                 ranges = <0 a9000000 2000>;
2437                 // If this device had extra parameters, then they would
2438                 // go here.
2439                 ps2@0 {
2440                         compatible = "xlnx,opb-ps2-dual-ref-1.00.a";
2441                         reg = <0 40>;
2442                         interrupt-parent = <&opb_intc_0>;
2443                         interrupts = <3 0>;
2444                         cell-index = <0>;
2445                 };
2446                 ps2@1000 {
2447                         compatible = "xlnx,opb-ps2-dual-ref-1.00.a";
2448                         reg = <1000 40>;
2449                         interrupt-parent = <&opb_intc_0>;
2450                         interrupts = <3 0>;
2451                         cell-index = <0>;
2452                 };
2453         };
2454
2455    Also, the system.mhs file defines bus attachments from the processor
2456    to the devices.  The device tree structure should reflect the bus
2457    attachments.  Again an example; this system.mhs fragment:
2458
2459         BEGIN ppc405_virtex4
2460                 PARAMETER INSTANCE = ppc405_0
2461                 PARAMETER HW_VER = 1.01.a
2462                 BUS_INTERFACE DPLB = plb_v34_0
2463                 BUS_INTERFACE IPLB = plb_v34_0
2464         END
2465
2466         BEGIN opb_intc
2467                 PARAMETER INSTANCE = opb_intc_0
2468                 PARAMETER HW_VER = 1.00.c
2469                 PARAMETER C_BASEADDR = 0xD1000FC0
2470                 PARAMETER C_HIGHADDR = 0xD1000FDF
2471                 BUS_INTERFACE SOPB = opb_v20_0
2472         END
2473
2474         BEGIN opb_uart16550
2475                 PARAMETER INSTANCE = opb_uart16550_0
2476                 PARAMETER HW_VER = 1.00.d
2477                 PARAMETER C_BASEADDR = 0xa0000000
2478                 PARAMETER C_HIGHADDR = 0xa0001FFF
2479                 BUS_INTERFACE SOPB = opb_v20_0
2480         END
2481
2482         BEGIN plb_v34
2483                 PARAMETER INSTANCE = plb_v34_0
2484                 PARAMETER HW_VER = 1.02.a
2485         END
2486
2487         BEGIN plb_bram_if_cntlr
2488                 PARAMETER INSTANCE = plb_bram_if_cntlr_0
2489                 PARAMETER HW_VER = 1.00.b
2490                 PARAMETER C_BASEADDR = 0xFFFF0000
2491                 PARAMETER C_HIGHADDR = 0xFFFFFFFF
2492                 BUS_INTERFACE SPLB = plb_v34_0
2493         END
2494
2495         BEGIN plb2opb_bridge
2496                 PARAMETER INSTANCE = plb2opb_bridge_0
2497                 PARAMETER HW_VER = 1.01.a
2498                 PARAMETER C_RNG0_BASEADDR = 0x20000000
2499                 PARAMETER C_RNG0_HIGHADDR = 0x3FFFFFFF
2500                 PARAMETER C_RNG1_BASEADDR = 0x60000000
2501                 PARAMETER C_RNG1_HIGHADDR = 0x7FFFFFFF
2502                 PARAMETER C_RNG2_BASEADDR = 0x80000000
2503                 PARAMETER C_RNG2_HIGHADDR = 0xBFFFFFFF
2504                 PARAMETER C_RNG3_BASEADDR = 0xC0000000
2505                 PARAMETER C_RNG3_HIGHADDR = 0xDFFFFFFF
2506                 BUS_INTERFACE SPLB = plb_v34_0
2507                 BUS_INTERFACE MOPB = opb_v20_0
2508         END
2509
2510    Gives this device tree (some properties removed for clarity):
2511
2512         plb@0 {
2513                 #address-cells = <1>;
2514                 #size-cells = <1>;
2515                 compatible = "xlnx,plb-v34-1.02.a";
2516                 device_type = "ibm,plb";
2517                 ranges; // 1:1 translation
2518
2519                 plb_bram_if_cntrl_0: bram@ffff0000 {
2520                         reg = <ffff0000 10000>;
2521                 }
2522
2523                 opb@20000000 {
2524                         #address-cells = <1>;
2525                         #size-cells = <1>;
2526                         ranges = <20000000 20000000 20000000
2527                                   60000000 60000000 20000000
2528                                   80000000 80000000 40000000
2529                                   c0000000 c0000000 20000000>;
2530
2531                         opb_uart16550_0: serial@a0000000 {
2532                                 reg = <a00000000 2000>;
2533                         };
2534
2535                         opb_intc_0: interrupt-controller@d1000fc0 {
2536                                 reg = <d1000fc0 20>;
2537                         };
2538                 };
2539         };
2540
2541    That covers the general approach to binding xilinx IP cores into the
2542    device tree.  The following are bindings for specific devices:
2543
2544       i) Xilinx ML300 Framebuffer
2545
2546       Simple framebuffer device from the ML300 reference design (also on the
2547       ML403 reference design as well as others).
2548
2549       Optional properties:
2550        - resolution = <xres yres> : pixel resolution of framebuffer.  Some
2551                                     implementations use a different resolution.
2552                                     Default is <d#640 d#480>
2553        - virt-resolution = <xvirt yvirt> : Size of framebuffer in memory.
2554                                            Default is <d#1024 d#480>.
2555        - rotate-display (empty) : rotate display 180 degrees.
2556
2557       ii) Xilinx SystemACE
2558
2559       The Xilinx SystemACE device is used to program FPGAs from an FPGA
2560       bitstream stored on a CF card.  It can also be used as a generic CF
2561       interface device.
2562
2563       Optional properties:
2564        - 8-bit (empty) : Set this property for SystemACE in 8 bit mode
2565
2566       iii) Xilinx EMAC and Xilinx TEMAC
2567
2568       Xilinx Ethernet devices.  In addition to general xilinx properties
2569       listed above, nodes for these devices should include a phy-handle
2570       property, and may include other common network device properties
2571       like local-mac-address.
2572       
2573       iv) Xilinx Uartlite
2574
2575       Xilinx uartlite devices are simple fixed speed serial ports.
2576
2577       Requred properties:
2578        - current-speed : Baud rate of uartlite
2579
2580       v) Xilinx hwicap
2581
2582                 Xilinx hwicap devices provide access to the configuration logic
2583                 of the FPGA through the Internal Configuration Access Port
2584                 (ICAP).  The ICAP enables partial reconfiguration of the FPGA,
2585                 readback of the configuration information, and some control over
2586                 'warm boots' of the FPGA fabric.
2587
2588                 Required properties:
2589                 - xlnx,family : The family of the FPGA, necessary since the
2590                       capabilities of the underlying ICAP hardware
2591                       differ between different families.  May be
2592                       'virtex2p', 'virtex4', or 'virtex5'.
2593
2594     p) Freescale Synchronous Serial Interface
2595
2596        The SSI is a serial device that communicates with audio codecs.  It can
2597        be programmed in AC97, I2S, left-justified, or right-justified modes.
2598
2599        Required properties:
2600        - compatible       : compatible list, containing "fsl,ssi"
2601        - cell-index       : the SSI, <0> = SSI1, <1> = SSI2, and so on
2602        - reg              : offset and length of the register set for the device
2603        - interrupts       : <a b> where a is the interrupt number and b is a
2604                             field that represents an encoding of the sense and
2605                             level information for the interrupt.  This should be
2606                             encoded based on the information in section 2)
2607                             depending on the type of interrupt controller you
2608                             have.
2609        - interrupt-parent : the phandle for the interrupt controller that
2610                             services interrupts for this device.
2611        - fsl,mode         : the operating mode for the SSI interface
2612                             "i2s-slave" - I2S mode, SSI is clock slave
2613                             "i2s-master" - I2S mode, SSI is clock master
2614                             "lj-slave" - left-justified mode, SSI is clock slave
2615                             "lj-master" - l.j. mode, SSI is clock master
2616                             "rj-slave" - right-justified mode, SSI is clock slave
2617                             "rj-master" - r.j., SSI is clock master
2618                             "ac97-slave" - AC97 mode, SSI is clock slave
2619                             "ac97-master" - AC97 mode, SSI is clock master
2620
2621        Optional properties:
2622        - codec-handle     : phandle to a 'codec' node that defines an audio
2623                             codec connected to this SSI.  This node is typically
2624                             a child of an I2C or other control node.
2625
2626        Child 'codec' node required properties:
2627        - compatible       : compatible list, contains the name of the codec
2628
2629        Child 'codec' node optional properties:
2630        - clock-frequency  : The frequency of the input clock, which typically
2631                             comes from an on-board dedicated oscillator.
2632
2633     * Freescale 83xx DMA Controller
2634
2635     Freescale PowerPC 83xx have on chip general purpose DMA controllers.
2636
2637     Required properties:
2638
2639     - compatible        : compatible list, contains 2 entries, first is
2640                          "fsl,CHIP-dma", where CHIP is the processor
2641                          (mpc8349, mpc8360, etc.) and the second is
2642                          "fsl,elo-dma"
2643     - reg               : <registers mapping for DMA general status reg>
2644     - ranges            : Should be defined as specified in 1) to describe the
2645                           DMA controller channels.
2646     - cell-index        : controller index.  0 for controller @ 0x8100
2647     - interrupts        : <interrupt mapping for DMA IRQ>
2648     - interrupt-parent  : optional, if needed for interrupt mapping
2649
2650
2651     - DMA channel nodes:
2652             - compatible        : compatible list, contains 2 entries, first is
2653                                  "fsl,CHIP-dma-channel", where CHIP is the processor
2654                                  (mpc8349, mpc8350, etc.) and the second is
2655                                  "fsl,elo-dma-channel"
2656             - reg               : <registers mapping for channel>
2657             - cell-index        : dma channel index starts at 0.
2658
2659     Optional properties:
2660             - interrupts        : <interrupt mapping for DMA channel IRQ>
2661                                   (on 83xx this is expected to be identical to
2662                                    the interrupts property of the parent node)
2663             - interrupt-parent  : optional, if needed for interrupt mapping
2664
2665   Example:
2666         dma@82a8 {
2667                 #address-cells = <1>;
2668                 #size-cells = <1>;
2669                 compatible = "fsl,mpc8349-dma", "fsl,elo-dma";
2670                 reg = <82a8 4>;
2671                 ranges = <0 8100 1a4>;
2672                 interrupt-parent = <&ipic>;
2673                 interrupts = <47 8>;
2674                 cell-index = <0>;
2675                 dma-channel@0 {
2676                         compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel";
2677                         cell-index = <0>;
2678                         reg = <0 80>;
2679                 };
2680                 dma-channel@80 {
2681                         compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel";
2682                         cell-index = <1>;
2683                         reg = <80 80>;
2684                 };
2685                 dma-channel@100 {
2686                         compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel";
2687                         cell-index = <2>;
2688                         reg = <100 80>;
2689                 };
2690                 dma-channel@180 {
2691                         compatible = "fsl,mpc8349-dma-channel", "fsl,elo-dma-channel";
2692                         cell-index = <3>;
2693                         reg = <180 80>;
2694                 };
2695         };
2696
2697    * Freescale 85xx/86xx DMA Controller
2698
2699     Freescale PowerPC 85xx/86xx have on chip general purpose DMA controllers.
2700
2701     Required properties:
2702
2703     - compatible        : compatible list, contains 2 entries, first is
2704                          "fsl,CHIP-dma", where CHIP is the processor
2705                          (mpc8540, mpc8540, etc.) and the second is
2706                          "fsl,eloplus-dma"
2707     - reg               : <registers mapping for DMA general status reg>
2708     - cell-index        : controller index.  0 for controller @ 0x21000,
2709                                              1 for controller @ 0xc000
2710     - ranges            : Should be defined as specified in 1) to describe the
2711                           DMA controller channels.
2712
2713     - DMA channel nodes:
2714             - compatible        : compatible list, contains 2 entries, first is
2715                                  "fsl,CHIP-dma-channel", where CHIP is the processor
2716                                  (mpc8540, mpc8560, etc.) and the second is
2717                                  "fsl,eloplus-dma-channel"
2718             - cell-index        : dma channel index starts at 0.
2719             - reg               : <registers mapping for channel>
2720             - interrupts        : <interrupt mapping for DMA channel IRQ>
2721             - interrupt-parent  : optional, if needed for interrupt mapping
2722
2723   Example:
2724         dma@21300 {
2725                 #address-cells = <1>;
2726                 #size-cells = <1>;
2727                 compatible = "fsl,mpc8540-dma", "fsl,eloplus-dma";
2728                 reg = <21300 4>;
2729                 ranges = <0 21100 200>;
2730                 cell-index = <0>;
2731                 dma-channel@0 {
2732                         compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel";
2733                         reg = <0 80>;
2734                         cell-index = <0>;
2735                         interrupt-parent = <&mpic>;
2736                         interrupts = <14 2>;
2737                 };
2738                 dma-channel@80 {
2739                         compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel";
2740                         reg = <80 80>;
2741                         cell-index = <1>;
2742                         interrupt-parent = <&mpic>;
2743                         interrupts = <15 2>;
2744                 };
2745                 dma-channel@100 {
2746                         compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel";
2747                         reg = <100 80>;
2748                         cell-index = <2>;
2749                         interrupt-parent = <&mpic>;
2750                         interrupts = <16 2>;
2751                 };
2752                 dma-channel@180 {
2753                         compatible = "fsl,mpc8540-dma-channel", "fsl,eloplus-dma-channel";
2754                         reg = <180 80>;
2755                         cell-index = <3>;
2756                         interrupt-parent = <&mpic>;
2757                         interrupts = <17 2>;
2758                 };
2759         };
2760
2761     * Freescale 8xxx/3.0 Gb/s SATA nodes
2762
2763     SATA nodes are defined to describe on-chip Serial ATA controllers.
2764     Each SATA port should have its own node.
2765
2766     Required properties:
2767     - compatible        : compatible list, contains 2 entries, first is
2768                          "fsl,CHIP-sata", where CHIP is the processor
2769                          (mpc8315, mpc8379, etc.) and the second is
2770                          "fsl,pq-sata"
2771     - interrupts        : <interrupt mapping for SATA IRQ>
2772     - cell-index        : controller index.
2773                               1 for controller @ 0x18000
2774                               2 for controller @ 0x19000
2775                               3 for controller @ 0x1a000
2776                               4 for controller @ 0x1b000
2777
2778     Optional properties:
2779     - interrupt-parent  : optional, if needed for interrupt mapping
2780     - reg               : <registers mapping>
2781
2782    Example:
2783
2784         sata@18000 {
2785                 compatible = "fsl,mpc8379-sata", "fsl,pq-sata";
2786                 reg = <0x18000 0x1000>;
2787                 cell-index = <1>;
2788                 interrupts = <2c 8>;
2789                 interrupt-parent = < &ipic >;
2790         };
2791
2792    More devices will be defined as this spec matures.
2793
2794 VII - Specifying interrupt information for devices
2795 ===================================================
2796
2797 The device tree represents the busses and devices of a hardware
2798 system in a form similar to the physical bus topology of the
2799 hardware.
2800
2801 In addition, a logical 'interrupt tree' exists which represents the
2802 hierarchy and routing of interrupts in the hardware.
2803
2804 The interrupt tree model is fully described in the
2805 document "Open Firmware Recommended Practice: Interrupt
2806 Mapping Version 0.9".  The document is available at:
2807 <http://playground.sun.com/1275/practice>.
2808
2809 1) interrupts property
2810 ----------------------
2811
2812 Devices that generate interrupts to a single interrupt controller
2813 should use the conventional OF representation described in the
2814 OF interrupt mapping documentation.
2815
2816 Each device which generates interrupts must have an 'interrupt'
2817 property.  The interrupt property value is an arbitrary number of
2818 of 'interrupt specifier' values which describe the interrupt or
2819 interrupts for the device.
2820
2821 The encoding of an interrupt specifier is determined by the
2822 interrupt domain in which the device is located in the
2823 interrupt tree.  The root of an interrupt domain specifies in
2824 its #interrupt-cells property the number of 32-bit cells
2825 required to encode an interrupt specifier.  See the OF interrupt
2826 mapping documentation for a detailed description of domains.
2827
2828 For example, the binding for the OpenPIC interrupt controller
2829 specifies  an #interrupt-cells value of 2 to encode the interrupt
2830 number and level/sense information. All interrupt children in an
2831 OpenPIC interrupt domain use 2 cells per interrupt in their interrupts
2832 property.
2833
2834 The PCI bus binding specifies a #interrupt-cell value of 1 to encode
2835 which interrupt pin (INTA,INTB,INTC,INTD) is used.
2836
2837 2) interrupt-parent property
2838 ----------------------------
2839
2840 The interrupt-parent property is specified to define an explicit
2841 link between a device node and its interrupt parent in
2842 the interrupt tree.  The value of interrupt-parent is the
2843 phandle of the parent node.
2844
2845 If the interrupt-parent property is not defined for a node, it's
2846 interrupt parent is assumed to be an ancestor in the node's
2847 _device tree_ hierarchy.
2848
2849 3) OpenPIC Interrupt Controllers
2850 --------------------------------
2851
2852 OpenPIC interrupt controllers require 2 cells to encode
2853 interrupt information.  The first cell defines the interrupt
2854 number.  The second cell defines the sense and level
2855 information.
2856
2857 Sense and level information should be encoded as follows:
2858
2859         0 = low to high edge sensitive type enabled
2860         1 = active low level sensitive type enabled
2861         2 = active high level sensitive type enabled
2862         3 = high to low edge sensitive type enabled
2863
2864 4) ISA Interrupt Controllers
2865 ----------------------------
2866
2867 ISA PIC interrupt controllers require 2 cells to encode
2868 interrupt information.  The first cell defines the interrupt
2869 number.  The second cell defines the sense and level
2870 information.
2871
2872 ISA PIC interrupt controllers should adhere to the ISA PIC
2873 encodings listed below:
2874
2875         0 =  active low level sensitive type enabled
2876         1 =  active high level sensitive type enabled
2877         2 =  high to low edge sensitive type enabled
2878         3 =  low to high edge sensitive type enabled
2879
2880
2881 Appendix A - Sample SOC node for MPC8540
2882 ========================================
2883
2884 Note that the #address-cells and #size-cells for the SoC node
2885 in this example have been explicitly listed; these are likely
2886 not necessary as they are usually the same as the root node.
2887
2888         soc8540@e0000000 {
2889                 #address-cells = <1>;
2890                 #size-cells = <1>;
2891                 #interrupt-cells = <2>;
2892                 device_type = "soc";
2893                 ranges = <00000000 e0000000 00100000>
2894                 reg = <e0000000 00003000>;
2895                 bus-frequency = <0>;
2896
2897                 mdio@24520 {
2898                         reg = <24520 20>;
2899                         device_type = "mdio";
2900                         compatible = "gianfar";
2901
2902                         ethernet-phy@0 {
2903                                 linux,phandle = <2452000>
2904                                 interrupt-parent = <40000>;
2905                                 interrupts = <35 1>;
2906                                 reg = <0>;
2907                                 device_type = "ethernet-phy";
2908                         };
2909
2910                         ethernet-phy@1 {
2911                                 linux,phandle = <2452001>
2912                                 interrupt-parent = <40000>;
2913                                 interrupts = <35 1>;
2914                                 reg = <1>;
2915                                 device_type = "ethernet-phy";
2916                         };
2917
2918                         ethernet-phy@3 {
2919                                 linux,phandle = <2452002>
2920                                 interrupt-parent = <40000>;
2921                                 interrupts = <35 1>;
2922                                 reg = <3>;
2923                                 device_type = "ethernet-phy";
2924                         };
2925
2926                 };
2927
2928                 ethernet@24000 {
2929                         #size-cells = <0>;
2930                         device_type = "network";
2931                         model = "TSEC";