aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/powerpc/booting-without-of.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/powerpc/booting-without-of.txt')
-rw-r--r--Documentation/powerpc/booting-without-of.txt270
1 files changed, 170 insertions, 100 deletions
diff --git a/Documentation/powerpc/booting-without-of.txt b/Documentation/powerpc/booting-without-of.txt
index 3b514672b80e..033a3f3b3ab7 100644
--- a/Documentation/powerpc/booting-without-of.txt
+++ b/Documentation/powerpc/booting-without-of.txt
@@ -39,7 +39,7 @@
39 and property data. The old style variable 39 and property data. The old style variable
40 alignment would make it impossible to do 40 alignment would make it impossible to do
41 "simple" insertion of properties using 41 "simple" insertion of properties using
42 memove (thanks Milton for 42 memmove (thanks Milton for
43 noticing). Updated kernel patch as well 43 noticing). Updated kernel patch as well
44 - Correct a few more alignment constraints 44 - Correct a few more alignment constraints
45 - Add a chapter about the device-tree 45 - Add a chapter about the device-tree
@@ -55,7 +55,7 @@
55 55
56 ToDo: 56 ToDo:
57 - Add some definitions of interrupt tree (simple/complex) 57 - Add some definitions of interrupt tree (simple/complex)
58 - Add some definitions for pci host bridges 58 - Add some definitions for PCI host bridges
59 - Add some common address format examples 59 - Add some common address format examples
60 - Add definitions for standard properties and "compatible" 60 - Add definitions for standard properties and "compatible"
61 names for cells that are not already defined by the existing 61 names for cells that are not already defined by the existing
@@ -114,7 +114,7 @@ it with special cases.
114 forth words isn't required), you can enter the kernel with: 114 forth words isn't required), you can enter the kernel with:
115 115
116 r5 : OF callback pointer as defined by IEEE 1275 116 r5 : OF callback pointer as defined by IEEE 1275
117 bindings to powerpc. Only the 32 bit client interface 117 bindings to powerpc. Only the 32-bit client interface
118 is currently supported 118 is currently supported
119 119
120 r3, r4 : address & length of an initrd if any or 0 120 r3, r4 : address & length of an initrd if any or 0
@@ -194,7 +194,7 @@ it with special cases.
194 for this is to keep kernels on embedded systems small and efficient; 194 for this is to keep kernels on embedded systems small and efficient;
195 part of this is due to the fact the code is already that way. In the 195 part of this is due to the fact the code is already that way. In the
196 future, a kernel may support multiple platforms, but only if the 196 future, a kernel may support multiple platforms, but only if the
197 platforms feature the same core architectire. A single kernel build 197 platforms feature the same core architecture. A single kernel build
198 cannot support both configurations with Book E and configurations 198 cannot support both configurations with Book E and configurations
199 with classic Powerpc architectures. 199 with classic Powerpc architectures.
200 200
@@ -215,7 +215,7 @@ of the boot sequences.... someone speak up if this is wrong!
215 enable another config option to select the specific board 215 enable another config option to select the specific board
216 supported. 216 supported.
217 217
218NOTE: If ben doesn't merge the setup files, may need to change this to 218NOTE: If Ben doesn't merge the setup files, may need to change this to
219point to setup_32.c 219point to setup_32.c
220 220
221 221
@@ -256,7 +256,7 @@ struct boot_param_header {
256 u32 off_dt_struct; /* offset to structure */ 256 u32 off_dt_struct; /* offset to structure */
257 u32 off_dt_strings; /* offset to strings */ 257 u32 off_dt_strings; /* offset to strings */
258 u32 off_mem_rsvmap; /* offset to memory reserve map 258 u32 off_mem_rsvmap; /* offset to memory reserve map
259*/ 259 */
260 u32 version; /* format version */ 260 u32 version; /* format version */
261 u32 last_comp_version; /* last compatible version */ 261 u32 last_comp_version; /* last compatible version */
262 262
@@ -265,6 +265,9 @@ struct boot_param_header {
265 booting on */ 265 booting on */
266 /* version 3 fields below */ 266 /* version 3 fields below */
267 u32 size_dt_strings; /* size of the strings block */ 267 u32 size_dt_strings; /* size of the strings block */
268
269 /* version 17 fields below */
270 u32 size_dt_struct; /* size of the DT structure block */
268}; 271};
269 272
270 Along with the constants: 273 Along with the constants:
@@ -273,7 +276,7 @@ struct boot_param_header {
273#define OF_DT_HEADER 0xd00dfeed /* 4: version, 276#define OF_DT_HEADER 0xd00dfeed /* 4: version,
274 4: total size */ 277 4: total size */
275#define OF_DT_BEGIN_NODE 0x1 /* Start node: full name 278#define OF_DT_BEGIN_NODE 0x1 /* Start node: full name
276*/ 279 */
277#define OF_DT_END_NODE 0x2 /* End node */ 280#define OF_DT_END_NODE 0x2 /* End node */
278#define OF_DT_PROP 0x3 /* Property: name off, 281#define OF_DT_PROP 0x3 /* Property: name off,
279 size, content */ 282 size, content */
@@ -310,9 +313,8 @@ struct boot_param_header {
310 - off_mem_rsvmap 313 - off_mem_rsvmap
311 314
312 This is an offset from the beginning of the header to the start 315 This is an offset from the beginning of the header to the start
313 of the reserved memory map. This map is a list of pairs of 64 316 of the reserved memory map. This map is a list of pairs of 64-
314 bit integers. Each pair is a physical address and a size. The 317 bit integers. Each pair is a physical address and a size. The
315
316 list is terminated by an entry of size 0. This map provides the 318 list is terminated by an entry of size 0. This map provides the
317 kernel with a list of physical memory areas that are "reserved" 319 kernel with a list of physical memory areas that are "reserved"
318 and thus not to be used for memory allocations, especially during 320 and thus not to be used for memory allocations, especially during
@@ -325,7 +327,7 @@ struct boot_param_header {
325 contain _at least_ this DT block itself (header,total_size). If 327 contain _at least_ this DT block itself (header,total_size). If
326 you are passing an initrd to the kernel, you should reserve it as 328 you are passing an initrd to the kernel, you should reserve it as
327 well. You do not need to reserve the kernel image itself. The map 329 well. You do not need to reserve the kernel image itself. The map
328 should be 64 bit aligned. 330 should be 64-bit aligned.
329 331
330 - version 332 - version
331 333
@@ -335,10 +337,13 @@ struct boot_param_header {
335 to reallocate it easily at boot and free up the unused flattened 337 to reallocate it easily at boot and free up the unused flattened
336 structure after expansion. Version 16 introduces a new more 338 structure after expansion. Version 16 introduces a new more
337 "compact" format for the tree itself that is however not backward 339 "compact" format for the tree itself that is however not backward
338 compatible. You should always generate a structure of the highest 340 compatible. Version 17 adds an additional field, size_dt_struct,
339 version defined at the time of your implementation. Currently 341 allowing it to be reallocated or moved more easily (this is
340 that is version 16, unless you explicitly aim at being backward 342 particularly useful for bootloaders which need to make
341 compatible. 343 adjustments to a device tree based on probed information). You
344 should always generate a structure of the highest version defined
345 at the time of your implementation. Currently that is version 17,
346 unless you explicitly aim at being backward compatible.
342 347
343 - last_comp_version 348 - last_comp_version
344 349
@@ -347,7 +352,7 @@ struct boot_param_header {
347 is backward compatible with version 1 (that is, a kernel build 352 is backward compatible with version 1 (that is, a kernel build
348 for version 1 will be able to boot with a version 2 format). You 353 for version 1 will be able to boot with a version 2 format). You
349 should put a 1 in this field if you generate a device tree of 354 should put a 1 in this field if you generate a device tree of
350 version 1 to 3, or 0x10 if you generate a tree of version 0x10 355 version 1 to 3, or 16 if you generate a tree of version 16 or 17
351 using the new unit name format. 356 using the new unit name format.
352 357
353 - boot_cpuid_phys 358 - boot_cpuid_phys
@@ -360,6 +365,17 @@ struct boot_param_header {
360 point (see further chapters for more informations on the required 365 point (see further chapters for more informations on the required
361 device-tree contents) 366 device-tree contents)
362 367
368 - size_dt_strings
369
370 This field only exists on version 3 and later headers. It
371 gives the size of the "strings" section of the device tree (which
372 starts at the offset given by off_dt_strings).
373
374 - size_dt_struct
375
376 This field only exists on version 17 and later headers. It gives
377 the size of the "structure" section of the device tree (which
378 starts at the offset given by off_dt_struct).
363 379
364 So the typical layout of a DT block (though the various parts don't 380 So the typical layout of a DT block (though the various parts don't
365 need to be in that order) looks like this (addresses go from top to 381 need to be in that order) looks like this (addresses go from top to
@@ -417,7 +433,7 @@ root node who has no parent.
417A node has 2 names. The actual node name is generally contained in a 433A node has 2 names. The actual node name is generally contained in a
418property of type "name" in the node property list whose value is a 434property of type "name" in the node property list whose value is a
419zero terminated string and is mandatory for version 1 to 3 of the 435zero terminated string and is mandatory for version 1 to 3 of the
420format definition (as it is in Open Firmware). Version 0x10 makes it 436format definition (as it is in Open Firmware). Version 16 makes it
421optional as it can generate it from the unit name defined below. 437optional as it can generate it from the unit name defined below.
422 438
423There is also a "unit name" that is used to differentiate nodes with 439There is also a "unit name" that is used to differentiate nodes with
@@ -461,7 +477,7 @@ referencing another node via "phandle" is when laying out the
461interrupt tree which will be described in a further version of this 477interrupt tree which will be described in a further version of this
462document. 478document.
463 479
464This "linux, phandle" property is a 32 bit value that uniquely 480This "linux, phandle" property is a 32-bit value that uniquely
465identifies a node. You are free to use whatever values or system of 481identifies a node. You are free to use whatever values or system of
466values, internal pointers, or whatever to generate these, the only 482values, internal pointers, or whatever to generate these, the only
467requirement is that every node for which you provide that property has 483requirement is that every node for which you provide that property has
@@ -471,7 +487,7 @@ Here is an example of a simple device-tree. In this example, an "o"
471designates a node followed by the node unit name. Properties are 487designates a node followed by the node unit name. Properties are
472presented with their name followed by their content. "content" 488presented with their name followed by their content. "content"
473represents an ASCII string (zero terminated) value, while <content> 489represents an ASCII string (zero terminated) value, while <content>
474represents a 32 bit hexadecimal value. The various nodes in this 490represents a 32-bit hexadecimal value. The various nodes in this
475example will be discussed in a later chapter. At this point, it is 491example will be discussed in a later chapter. At this point, it is
476only meant to give you a idea of what a device-tree looks like. I have 492only meant to give you a idea of what a device-tree looks like. I have
477purposefully kept the "name" and "linux,phandle" properties which 493purposefully kept the "name" and "linux,phandle" properties which
@@ -497,7 +513,7 @@ looks like in practice.
497 | |- device_type = "cpu" 513 | |- device_type = "cpu"
498 | |- reg = <0> 514 | |- reg = <0>
499 | |- clock-frequency = <5f5e1000> 515 | |- clock-frequency = <5f5e1000>
500 | |- linux,boot-cpu 516 | |- 64-bit
501 | |- linux,phandle = <2> 517 | |- linux,phandle = <2>
502 | 518 |
503 o memory@0 519 o memory@0
@@ -509,7 +525,6 @@ looks like in practice.
509 o chosen 525 o chosen
510 |- name = "chosen" 526 |- name = "chosen"
511 |- bootargs = "root=/dev/sda2" 527 |- bootargs = "root=/dev/sda2"
512 |- linux,platform = <00000600>
513 |- linux,phandle = <4> 528 |- linux,phandle = <4>
514 529
515This tree is almost a minimal tree. It pretty much contains the 530This tree is almost a minimal tree. It pretty much contains the
@@ -519,7 +534,7 @@ physical memory layout. It also includes misc information passed
519through /chosen, like in this example, the platform type (mandatory) 534through /chosen, like in this example, the platform type (mandatory)
520and the kernel command line arguments (optional). 535and the kernel command line arguments (optional).
521 536
522The /cpus/PowerPC,970@0/linux,boot-cpu property is an example of a 537The /cpus/PowerPC,970@0/64-bit property is an example of a
523property without a value. All other properties have a value. The 538property without a value. All other properties have a value. The
524significance of the #address-cells and #size-cells properties will be 539significance of the #address-cells and #size-cells properties will be
525explained in chapter IV which defines precisely the required nodes and 540explained in chapter IV which defines precisely the required nodes and
@@ -544,15 +559,15 @@ Here's the basic structure of a single node:
544 * [align gap to next 4 bytes boundary] 559 * [align gap to next 4 bytes boundary]
545 * for each property: 560 * for each property:
546 * token OF_DT_PROP (that is 0x00000003) 561 * token OF_DT_PROP (that is 0x00000003)
547 * 32 bit value of property value size in bytes (or 0 of no 562 * 32-bit value of property value size in bytes (or 0 if no
548 * value) 563 value)
549 * 32 bit value of offset in string block of property name 564 * 32-bit value of offset in string block of property name
550 * property value data if any 565 * property value data if any
551 * [align gap to next 4 bytes boundary] 566 * [align gap to next 4 bytes boundary]
552 * [child nodes if any] 567 * [child nodes if any]
553 * token OF_DT_END_NODE (that is 0x00000002) 568 * token OF_DT_END_NODE (that is 0x00000002)
554 569
555So the node content can be summarised as a start token, a full path, 570So the node content can be summarized as a start token, a full path,
556a list of properties, a list of child nodes, and an end token. Every 571a list of properties, a list of child nodes, and an end token. Every
557child node is a full node structure itself as defined above. 572child node is a full node structure itself as defined above.
558 573
@@ -584,7 +599,7 @@ provide those properties yourself.
584---------------------------------------------- 599----------------------------------------------
585 600
586The general rule is documented in the various Open Firmware 601The general rule is documented in the various Open Firmware
587documentations. If you chose to describe a bus with the device-tree 602documentations. If you choose to describe a bus with the device-tree
588and there exist an OF bus binding, then you should follow the 603and there exist an OF bus binding, then you should follow the
589specification. However, the kernel does not require every single 604specification. However, the kernel does not require every single
590device or bus to be described by the device tree. 605device or bus to be described by the device tree.
@@ -597,9 +612,9 @@ those properties defining addresses format for devices directly mapped
597on the processor bus. 612on the processor bus.
598 613
599Those 2 properties define 'cells' for representing an address and a 614Those 2 properties define 'cells' for representing an address and a
600size. A "cell" is a 32 bit number. For example, if both contain 2 615size. A "cell" is a 32-bit number. For example, if both contain 2
601like the example tree given above, then an address and a size are both 616like the example tree given above, then an address and a size are both
602composed of 2 cells, and each is a 64 bit number (cells are 617composed of 2 cells, and each is a 64-bit number (cells are
603concatenated and expected to be in big endian format). Another example 618concatenated and expected to be in big endian format). Another example
604is the way Apple firmware defines them, with 2 cells for an address 619is the way Apple firmware defines them, with 2 cells for an address
605and one cell for a size. Most 32-bit implementations should define 620and one cell for a size. Most 32-bit implementations should define
@@ -633,7 +648,7 @@ prom_parse.c file of the recent kernels for your bus type.
633 648
634The "reg" property only defines addresses and sizes (if #size-cells 649The "reg" property only defines addresses and sizes (if #size-cells
635is non-0) within a given bus. In order to translate addresses upward 650is non-0) within a given bus. In order to translate addresses upward
636(that is into parent bus addresses, and possibly into cpu physical 651(that is into parent bus addresses, and possibly into CPU physical
637addresses), all busses must contain a "ranges" property. If the 652addresses), all busses must contain a "ranges" property. If the
638"ranges" property is missing at a given level, it's assumed that 653"ranges" property is missing at a given level, it's assumed that
639translation isn't possible. The format of the "ranges" property for a 654translation isn't possible. The format of the "ranges" property for a
@@ -649,9 +664,9 @@ example, for a PCI host controller, that would be a CPU address. For a
649PCI<->ISA bridge, that would be a PCI address. It defines the base 664PCI<->ISA bridge, that would be a PCI address. It defines the base
650address in the parent bus where the beginning of that range is mapped. 665address in the parent bus where the beginning of that range is mapped.
651 666
652For a new 64 bit powerpc board, I recommend either the 2/2 format or 667For a new 64-bit powerpc board, I recommend either the 2/2 format or
653Apple's 2/1 format which is slightly more compact since sizes usually 668Apple's 2/1 format which is slightly more compact since sizes usually
654fit in a single 32 bit word. New 32 bit powerpc boards should use a 669fit in a single 32-bit word. New 32-bit powerpc boards should use a
6551/1 format, unless the processor supports physical addresses greater 6701/1 format, unless the processor supports physical addresses greater
656than 32-bits, in which case a 2/1 format is recommended. 671than 32-bits, in which case a 2/1 format is recommended.
657 672
@@ -733,8 +748,7 @@ address which can extend beyond that limit.
733 that typically get driven by the same platform code in the 748 that typically get driven by the same platform code in the
734 kernel, you would use a different "model" property but put a 749 kernel, you would use a different "model" property but put a
735 value in "compatible". The kernel doesn't directly use that 750 value in "compatible". The kernel doesn't directly use that
736 value (see /chosen/linux,platform for how the kernel chooses a 751 value but it is generally useful.
737 platform type) but it is generally useful.
738 752
739 The root node is also generally where you add additional properties 753 The root node is also generally where you add additional properties
740 specific to your board like the serial number if any, that sort of 754 specific to your board like the serial number if any, that sort of
@@ -766,7 +780,7 @@ address which can extend beyond that limit.
766 Required properties: 780 Required properties:
767 781
768 - device_type : has to be "cpu" 782 - device_type : has to be "cpu"
769 - reg : This is the physical cpu number, it's a single 32 bit cell 783 - reg : This is the physical CPU number, it's a single 32-bit cell
770 and is also used as-is as the unit number for constructing the 784 and is also used as-is as the unit number for constructing the
771 unit name in the full path. For example, with 2 CPUs, you would 785 unit name in the full path. For example, with 2 CPUs, you would
772 have the full path: 786 have the full path:
@@ -778,7 +792,6 @@ address which can extend beyond that limit.
778 bytes 792 bytes
779 - d-cache-size : one cell, size of L1 data cache in bytes 793 - d-cache-size : one cell, size of L1 data cache in bytes
780 - i-cache-size : one cell, size of L1 instruction cache in bytes 794 - i-cache-size : one cell, size of L1 instruction cache in bytes
781 - linux, boot-cpu : Should be defined if this cpu is the boot cpu.
782 795
783 Recommended properties: 796 Recommended properties:
784 797
@@ -788,7 +801,7 @@ address which can extend beyond that limit.
788 the kernel timebase/decrementer calibration based on this 801 the kernel timebase/decrementer calibration based on this
789 value. 802 value.
790 - clock-frequency : a cell indicating the CPU core clock frequency 803 - clock-frequency : a cell indicating the CPU core clock frequency
791 in Hz. A new property will be defined for 64 bit values, but if 804 in Hz. A new property will be defined for 64-bit values, but if
792 your frequency is < 4Ghz, one cell is enough. Here as well as 805 your frequency is < 4Ghz, one cell is enough. Here as well as
793 for the above, the common code doesn't use that property, but 806 for the above, the common code doesn't use that property, but
794 you are welcome to re-use the pSeries or Maple one. A future 807 you are welcome to re-use the pSeries or Maple one. A future
@@ -835,19 +848,13 @@ address which can extend beyond that limit.
835 848
836 This node is a bit "special". Normally, that's where open firmware 849 This node is a bit "special". Normally, that's where open firmware
837 puts some variable environment information, like the arguments, or 850 puts some variable environment information, like the arguments, or
838 phandle pointers to nodes like the main interrupt controller, or the 851 the default input/output devices.
839 default input/output devices.
840 852
841 This specification makes a few of these mandatory, but also defines 853 This specification makes a few of these mandatory, but also defines
842 some linux-specific properties that would be normally constructed by 854 some linux-specific properties that would be normally constructed by
843 the prom_init() trampoline when booting with an OF client interface, 855 the prom_init() trampoline when booting with an OF client interface,
844 but that you have to provide yourself when using the flattened format. 856 but that you have to provide yourself when using the flattened format.
845 857
846 Required properties:
847
848 - linux,platform : This is your platform number as assigned by the
849 architecture maintainers
850
851 Recommended properties: 858 Recommended properties:
852 859
853 - bootargs : This zero-terminated string is passed as the kernel 860 - bootargs : This zero-terminated string is passed as the kernel
@@ -861,14 +868,14 @@ address which can extend beyond that limit.
861 that the kernel tries to find out the default console and has 868 that the kernel tries to find out the default console and has
862 knowledge of various types like 8250 serial ports. You may want 869 knowledge of various types like 8250 serial ports. You may want
863 to extend this function to add your own. 870 to extend this function to add your own.
864 - interrupt-controller : This is one cell containing a phandle
865 value that matches the "linux,phandle" property of your main
866 interrupt controller node. May be used for interrupt routing.
867
868 871
869 Note that u-boot creates and fills in the chosen node for platforms 872 Note that u-boot creates and fills in the chosen node for platforms
870 that use it. 873 that use it.
871 874
875 (Note: a practice that is now obsolete was to include a property
876 under /chosen called interrupt-controller which had a phandle value
877 that pointed to the main interrupt controller)
878
872 f) the /soc<SOCname> node 879 f) the /soc<SOCname> node
873 880
874 This node is used to represent a system-on-a-chip (SOC) and must be 881 This node is used to represent a system-on-a-chip (SOC) and must be
@@ -916,8 +923,7 @@ address which can extend beyond that limit.
916 The SOC node may contain child nodes for each SOC device that the 923 The SOC node may contain child nodes for each SOC device that the
917 platform uses. Nodes should not be created for devices which exist 924 platform uses. Nodes should not be created for devices which exist
918 on the SOC but are not used by a particular platform. See chapter VI 925 on the SOC but are not used by a particular platform. See chapter VI
919 for more information on how to specify devices that are part of an 926 for more information on how to specify devices that are part of a SOC.
920SOC.
921 927
922 Example SOC node for the MPC8540: 928 Example SOC node for the MPC8540:
923 929
@@ -980,7 +986,7 @@ The syntax of the dtc tool is
980 [-o output-filename] [-V output_version] input_filename 986 [-o output-filename] [-V output_version] input_filename
981 987
982 988
983The "output_version" defines what versio of the "blob" format will be 989The "output_version" defines what version of the "blob" format will be
984generated. Supported versions are 1,2,3 and 16. The default is 990generated. Supported versions are 1,2,3 and 16. The default is
985currently version 3 but that may change in the future to version 16. 991currently version 3 but that may change in the future to version 16.
986 992
@@ -1002,12 +1008,12 @@ supported currently at the toplevel.
1002 */ 1008 */
1003 1009
1004 property2 = <1234abcd>; /* define a property containing a 1010 property2 = <1234abcd>; /* define a property containing a
1005 * numerical 32 bits value (hexadecimal) 1011 * numerical 32-bit value (hexadecimal)
1006 */ 1012 */
1007 1013
1008 property3 = <12345678 12345678 deadbeef>; 1014 property3 = <12345678 12345678 deadbeef>;
1009 /* define a property containing 3 1015 /* define a property containing 3
1010 * numerical 32 bits values (cells) in 1016 * numerical 32-bit values (cells) in
1011 * hexadecimal 1017 * hexadecimal
1012 */ 1018 */
1013 property4 = [0a 0b 0c 0d de ea ad be ef]; 1019 property4 = [0a 0b 0c 0d de ea ad be ef];
@@ -1076,7 +1082,7 @@ while all this has been defined and implemented.
1076 its usage in early_init_devtree(), and the corresponding various 1082 its usage in early_init_devtree(), and the corresponding various
1077 early_init_dt_scan_*() callbacks. That code can be re-used in a 1083 early_init_dt_scan_*() callbacks. That code can be re-used in a
1078 GPL bootloader, and as the author of that code, I would be happy 1084 GPL bootloader, and as the author of that code, I would be happy
1079 to discuss possible free licencing to any vendor who wishes to 1085 to discuss possible free licensing to any vendor who wishes to
1080 integrate all or part of this code into a non-GPL bootloader. 1086 integrate all or part of this code into a non-GPL bootloader.
1081 1087
1082 1088
@@ -1085,7 +1091,7 @@ VI - System-on-a-chip devices and nodes
1085======================================= 1091=======================================
1086 1092
1087Many companies are now starting to develop system-on-a-chip 1093Many companies are now starting to develop system-on-a-chip
1088processors, where the processor core (cpu) and many peripheral devices 1094processors, where the processor core (CPU) and many peripheral devices
1089exist on a single piece of silicon. For these SOCs, an SOC node 1095exist on a single piece of silicon. For these SOCs, an SOC node
1090should be used that defines child nodes for the devices that make 1096should be used that defines child nodes for the devices that make
1091up the SOC. While platforms are not required to use this model in 1097up the SOC. While platforms are not required to use this model in
@@ -1117,42 +1123,7 @@ See appendix A for an example partial SOC node definition for the
1117MPC8540. 1123MPC8540.
1118 1124
1119 1125
11202) Specifying interrupt information for SOC devices 11262) Representing devices without a current OF specification
1121---------------------------------------------------
1122
1123Each device that is part of an SOC and which generates interrupts
1124should have the following properties:
1125
1126 - interrupt-parent : contains the phandle of the interrupt
1127 controller which handles interrupts for this device
1128 - interrupts : a list of tuples representing the interrupt
1129 number and the interrupt sense and level for each interrupt
1130 for this device.
1131
1132This information is used by the kernel to build the interrupt table
1133for the interrupt controllers in the system.
1134
1135Sense and level information should be encoded as follows:
1136
1137 Devices connected to openPIC-compatible controllers should encode
1138 sense and polarity as follows:
1139
1140 0 = low to high edge sensitive type enabled
1141 1 = active low level sensitive type enabled
1142 2 = active high level sensitive type enabled
1143 3 = high to low edge sensitive type enabled
1144
1145 ISA PIC interrupt controllers should adhere to the ISA PIC
1146 encodings listed below:
1147
1148 0 = active low level sensitive type enabled
1149 1 = active high level sensitive type enabled
1150 2 = high to low edge sensitive type enabled
1151 3 = low to high edge sensitive type enabled
1152
1153
1154
11553) Representing devices without a current OF specification
1156---------------------------------------------------------- 1127----------------------------------------------------------
1157 1128
1158Currently, there are many devices on SOCs that do not have a standard 1129Currently, there are many devices on SOCs that do not have a standard
@@ -1209,6 +1180,13 @@ platforms are moved over to use the flattened-device-tree model.
1209 - phy-handle : The phandle for the PHY connected to this ethernet 1180 - phy-handle : The phandle for the PHY connected to this ethernet
1210 controller. 1181 controller.
1211 1182
1183 Recommended properties:
1184
1185 - linux,network-index : This is the intended "index" of this
1186 network device. This is used by the bootwrapper to interpret
1187 MAC addresses passed by the firmware when no information other
1188 than indices is available to associate an address with a device.
1189
1212 Example: 1190 Example:
1213 1191
1214 ethernet@24000 { 1192 ethernet@24000 {
@@ -1320,10 +1298,10 @@ platforms are moved over to use the flattened-device-tree model.
1320 and additions : 1298 and additions :
1321 1299
1322 Required properties : 1300 Required properties :
1323 - compatible : Should be "fsl-usb2-mph" for multi port host usb 1301 - compatible : Should be "fsl-usb2-mph" for multi port host USB
1324 controllers, or "fsl-usb2-dr" for dual role usb controllers 1302 controllers, or "fsl-usb2-dr" for dual role USB controllers
1325 - phy_type : For multi port host usb controllers, should be one of 1303 - phy_type : For multi port host USB controllers, should be one of
1326 "ulpi", or "serial". For dual role usb controllers, should be 1304 "ulpi", or "serial". For dual role USB controllers, should be
1327 one of "ulpi", "utmi", "utmi_wide", or "serial". 1305 one of "ulpi", "utmi", "utmi_wide", or "serial".
1328 - reg : Offset and length of the register set for the device 1306 - reg : Offset and length of the register set for the device
1329 - port0 : boolean; if defined, indicates port0 is connected for 1307 - port0 : boolean; if defined, indicates port0 is connected for
@@ -1347,7 +1325,7 @@ platforms are moved over to use the flattened-device-tree model.
1347 - interrupt-parent : the phandle for the interrupt controller that 1325 - interrupt-parent : the phandle for the interrupt controller that
1348 services interrupts for this device. 1326 services interrupts for this device.
1349 1327
1350 Example multi port host usb controller device node : 1328 Example multi port host USB controller device node :
1351 usb@22000 { 1329 usb@22000 {
1352 device_type = "usb"; 1330 device_type = "usb";
1353 compatible = "fsl-usb2-mph"; 1331 compatible = "fsl-usb2-mph";
@@ -1361,7 +1339,7 @@ platforms are moved over to use the flattened-device-tree model.
1361 port1; 1339 port1;
1362 }; 1340 };
1363 1341
1364 Example dual role usb controller device node : 1342 Example dual role USB controller device node :
1365 usb@23000 { 1343 usb@23000 {
1366 device_type = "usb"; 1344 device_type = "usb";
1367 compatible = "fsl-usb2-dr"; 1345 compatible = "fsl-usb2-dr";
@@ -1395,7 +1373,7 @@ platforms are moved over to use the flattened-device-tree model.
1395 - channel-fifo-len : An integer representing the number of 1373 - channel-fifo-len : An integer representing the number of
1396 descriptor pointers each channel fetch fifo can hold. 1374 descriptor pointers each channel fetch fifo can hold.
1397 - exec-units-mask : The bitmask representing what execution units 1375 - exec-units-mask : The bitmask representing what execution units
1398 (EUs) are available. It's a single 32 bit cell. EU information 1376 (EUs) are available. It's a single 32-bit cell. EU information
1399 should be encoded following the SEC's Descriptor Header Dword 1377 should be encoded following the SEC's Descriptor Header Dword
1400 EU_SEL0 field documentation, i.e. as follows: 1378 EU_SEL0 field documentation, i.e. as follows:
1401 1379
@@ -1411,7 +1389,7 @@ platforms are moved over to use the flattened-device-tree model.
1411 bits 8 through 31 are reserved for future SEC EUs. 1389 bits 8 through 31 are reserved for future SEC EUs.
1412 1390
1413 - descriptor-types-mask : The bitmask representing what descriptors 1391 - descriptor-types-mask : The bitmask representing what descriptors
1414 are available. It's a single 32 bit cell. Descriptor type 1392 are available. It's a single 32-bit cell. Descriptor type
1415 information should be encoded following the SEC's Descriptor 1393 information should be encoded following the SEC's Descriptor
1416 Header Dword DESC_TYPE field documentation, i.e. as follows: 1394 Header Dword DESC_TYPE field documentation, i.e. as follows:
1417 1395
@@ -1500,7 +1478,7 @@ platforms are moved over to use the flattened-device-tree model.
1500 Required properties: 1478 Required properties:
1501 - device_type : should be "spi". 1479 - device_type : should be "spi".
1502 - compatible : should be "fsl_spi". 1480 - compatible : should be "fsl_spi".
1503 - mode : the spi operation mode, it can be "cpu" or "qe". 1481 - mode : the SPI operation mode, it can be "cpu" or "qe".
1504 - reg : Offset and length of the register set for the device 1482 - reg : Offset and length of the register set for the device
1505 - interrupts : <a b> where a is the interrupt number and b is a 1483 - interrupts : <a b> where a is the interrupt number and b is a
1506 field that represents an encoding of the sense and level 1484 field that represents an encoding of the sense and level
@@ -1577,6 +1555,12 @@ platforms are moved over to use the flattened-device-tree model.
1577 - mac-address : list of bytes representing the ethernet address. 1555 - mac-address : list of bytes representing the ethernet address.
1578 - phy-handle : The phandle for the PHY connected to this controller. 1556 - phy-handle : The phandle for the PHY connected to this controller.
1579 1557
1558 Recommended properties:
1559 - linux,network-index : This is the intended "index" of this
1560 network device. This is used by the bootwrapper to interpret
1561 MAC addresses passed by the firmware when no information other
1562 than indices is available to associate an address with a device.
1563
1580 Example: 1564 Example:
1581 ucc@2000 { 1565 ucc@2000 {
1582 device_type = "network"; 1566 device_type = "network";
@@ -1720,7 +1704,7 @@ platforms are moved over to use the flattened-device-tree model.
1720 - partitions : Several pairs of 32-bit values where the first value is 1704 - partitions : Several pairs of 32-bit values where the first value is
1721 partition's offset from the start of the device and the second one is 1705 partition's offset from the start of the device and the second one is
1722 partition size in bytes with LSB used to signify a read only 1706 partition size in bytes with LSB used to signify a read only
1723 partition (so, the parition size should always be an even number). 1707 partition (so, the partition size should always be an even number).
1724 - partition-names : The list of concatenated zero terminated strings 1708 - partition-names : The list of concatenated zero terminated strings
1725 representing the partition names. 1709 representing the partition names.
1726 - probe-type : The type of probe which should be done for the chip 1710 - probe-type : The type of probe which should be done for the chip
@@ -1741,6 +1725,92 @@ platforms are moved over to use the flattened-device-tree model.
1741 1725
1742 More devices will be defined as this spec matures. 1726 More devices will be defined as this spec matures.
1743 1727
1728VII - Specifying interrupt information for devices
1729===================================================
1730
1731The device tree represents the busses and devices of a hardware
1732system in a form similar to the physical bus topology of the
1733hardware.
1734
1735In addition, a logical 'interrupt tree' exists which represents the
1736hierarchy and routing of interrupts in the hardware.
1737
1738The interrupt tree model is fully described in the
1739document "Open Firmware Recommended Practice: Interrupt
1740Mapping Version 0.9". The document is available at:
1741<http://playground.sun.com/1275/practice>.
1742
17431) interrupts property
1744----------------------
1745
1746Devices that generate interrupts to a single interrupt controller
1747should use the conventional OF representation described in the
1748OF interrupt mapping documentation.
1749
1750Each device which generates interrupts must have an 'interrupt'
1751property. The interrupt property value is an arbitrary number of
1752of 'interrupt specifier' values which describe the interrupt or
1753interrupts for the device.
1754
1755The encoding of an interrupt specifier is determined by the
1756interrupt domain in which the device is located in the
1757interrupt tree. The root of an interrupt domain specifies in
1758its #interrupt-cells property the number of 32-bit cells
1759required to encode an interrupt specifier. See the OF interrupt
1760mapping documentation for a detailed description of domains.
1761
1762For example, the binding for the OpenPIC interrupt controller
1763specifies an #interrupt-cells value of 2 to encode the interrupt
1764number and level/sense information. All interrupt children in an
1765OpenPIC interrupt domain use 2 cells per interrupt in their interrupts
1766property.
1767
1768The PCI bus binding specifies a #interrupt-cell value of 1 to encode
1769which interrupt pin (INTA,INTB,INTC,INTD) is used.
1770
17712) interrupt-parent property
1772----------------------------
1773
1774The interrupt-parent property is specified to define an explicit
1775link between a device node and its interrupt parent in
1776the interrupt tree. The value of interrupt-parent is the
1777phandle of the parent node.
1778
1779If the interrupt-parent property is not defined for a node, it's
1780interrupt parent is assumed to be an ancestor in the node's
1781_device tree_ hierarchy.
1782
17833) OpenPIC Interrupt Controllers
1784--------------------------------
1785
1786OpenPIC interrupt controllers require 2 cells to encode
1787interrupt information. The first cell defines the interrupt
1788number. The second cell defines the sense and level
1789information.
1790
1791Sense and level information should be encoded as follows:
1792
1793 0 = low to high edge sensitive type enabled
1794 1 = active low level sensitive type enabled
1795 2 = active high level sensitive type enabled
1796 3 = high to low edge sensitive type enabled
1797
17984) ISA Interrupt Controllers
1799----------------------------
1800
1801ISA PIC interrupt controllers require 2 cells to encode
1802interrupt information. The first cell defines the interrupt
1803number. The second cell defines the sense and level
1804information.
1805
1806ISA PIC interrupt controllers should adhere to the ISA PIC
1807encodings listed below:
1808
1809 0 = active low level sensitive type enabled
1810 1 = active high level sensitive type enabled
1811 2 = high to low edge sensitive type enabled
1812 3 = low to high edge sensitive type enabled
1813
1744 1814
1745Appendix A - Sample SOC node for MPC8540 1815Appendix A - Sample SOC node for MPC8540
1746======================================== 1816========================================