diff options
Diffstat (limited to 'Documentation/powerpc/booting-without-of.txt')
-rw-r--r-- | Documentation/powerpc/booting-without-of.txt | 270 |
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 | ||
218 | NOTE: If ben doesn't merge the setup files, may need to change this to | 218 | NOTE: If Ben doesn't merge the setup files, may need to change this to |
219 | point to setup_32.c | 219 | point 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. | |||
417 | A node has 2 names. The actual node name is generally contained in a | 433 | A node has 2 names. The actual node name is generally contained in a |
418 | property of type "name" in the node property list whose value is a | 434 | property of type "name" in the node property list whose value is a |
419 | zero terminated string and is mandatory for version 1 to 3 of the | 435 | zero terminated string and is mandatory for version 1 to 3 of the |
420 | format definition (as it is in Open Firmware). Version 0x10 makes it | 436 | format definition (as it is in Open Firmware). Version 16 makes it |
421 | optional as it can generate it from the unit name defined below. | 437 | optional as it can generate it from the unit name defined below. |
422 | 438 | ||
423 | There is also a "unit name" that is used to differentiate nodes with | 439 | There 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 | |||
461 | interrupt tree which will be described in a further version of this | 477 | interrupt tree which will be described in a further version of this |
462 | document. | 478 | document. |
463 | 479 | ||
464 | This "linux, phandle" property is a 32 bit value that uniquely | 480 | This "linux, phandle" property is a 32-bit value that uniquely |
465 | identifies a node. You are free to use whatever values or system of | 481 | identifies a node. You are free to use whatever values or system of |
466 | values, internal pointers, or whatever to generate these, the only | 482 | values, internal pointers, or whatever to generate these, the only |
467 | requirement is that every node for which you provide that property has | 483 | requirement 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" | |||
471 | designates a node followed by the node unit name. Properties are | 487 | designates a node followed by the node unit name. Properties are |
472 | presented with their name followed by their content. "content" | 488 | presented with their name followed by their content. "content" |
473 | represents an ASCII string (zero terminated) value, while <content> | 489 | represents an ASCII string (zero terminated) value, while <content> |
474 | represents a 32 bit hexadecimal value. The various nodes in this | 490 | represents a 32-bit hexadecimal value. The various nodes in this |
475 | example will be discussed in a later chapter. At this point, it is | 491 | example will be discussed in a later chapter. At this point, it is |
476 | only meant to give you a idea of what a device-tree looks like. I have | 492 | only meant to give you a idea of what a device-tree looks like. I have |
477 | purposefully kept the "name" and "linux,phandle" properties which | 493 | purposefully 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 | ||
515 | This tree is almost a minimal tree. It pretty much contains the | 530 | This tree is almost a minimal tree. It pretty much contains the |
@@ -519,7 +534,7 @@ physical memory layout. It also includes misc information passed | |||
519 | through /chosen, like in this example, the platform type (mandatory) | 534 | through /chosen, like in this example, the platform type (mandatory) |
520 | and the kernel command line arguments (optional). | 535 | and the kernel command line arguments (optional). |
521 | 536 | ||
522 | The /cpus/PowerPC,970@0/linux,boot-cpu property is an example of a | 537 | The /cpus/PowerPC,970@0/64-bit property is an example of a |
523 | property without a value. All other properties have a value. The | 538 | property without a value. All other properties have a value. The |
524 | significance of the #address-cells and #size-cells properties will be | 539 | significance of the #address-cells and #size-cells properties will be |
525 | explained in chapter IV which defines precisely the required nodes and | 540 | explained 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 | ||
555 | So the node content can be summarised as a start token, a full path, | 570 | So the node content can be summarized as a start token, a full path, |
556 | a list of properties, a list of child nodes, and an end token. Every | 571 | a list of properties, a list of child nodes, and an end token. Every |
557 | child node is a full node structure itself as defined above. | 572 | child node is a full node structure itself as defined above. |
558 | 573 | ||
@@ -584,7 +599,7 @@ provide those properties yourself. | |||
584 | ---------------------------------------------- | 599 | ---------------------------------------------- |
585 | 600 | ||
586 | The general rule is documented in the various Open Firmware | 601 | The general rule is documented in the various Open Firmware |
587 | documentations. If you chose to describe a bus with the device-tree | 602 | documentations. If you choose to describe a bus with the device-tree |
588 | and there exist an OF bus binding, then you should follow the | 603 | and there exist an OF bus binding, then you should follow the |
589 | specification. However, the kernel does not require every single | 604 | specification. However, the kernel does not require every single |
590 | device or bus to be described by the device tree. | 605 | device or bus to be described by the device tree. |
@@ -597,9 +612,9 @@ those properties defining addresses format for devices directly mapped | |||
597 | on the processor bus. | 612 | on the processor bus. |
598 | 613 | ||
599 | Those 2 properties define 'cells' for representing an address and a | 614 | Those 2 properties define 'cells' for representing an address and a |
600 | size. A "cell" is a 32 bit number. For example, if both contain 2 | 615 | size. A "cell" is a 32-bit number. For example, if both contain 2 |
601 | like the example tree given above, then an address and a size are both | 616 | like the example tree given above, then an address and a size are both |
602 | composed of 2 cells, and each is a 64 bit number (cells are | 617 | composed of 2 cells, and each is a 64-bit number (cells are |
603 | concatenated and expected to be in big endian format). Another example | 618 | concatenated and expected to be in big endian format). Another example |
604 | is the way Apple firmware defines them, with 2 cells for an address | 619 | is the way Apple firmware defines them, with 2 cells for an address |
605 | and one cell for a size. Most 32-bit implementations should define | 620 | and 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 | ||
634 | The "reg" property only defines addresses and sizes (if #size-cells | 649 | The "reg" property only defines addresses and sizes (if #size-cells |
635 | is non-0) within a given bus. In order to translate addresses upward | 650 | is 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 |
637 | addresses), all busses must contain a "ranges" property. If the | 652 | addresses), 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 |
639 | translation isn't possible. The format of the "ranges" property for a | 654 | translation 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 | |||
649 | PCI<->ISA bridge, that would be a PCI address. It defines the base | 664 | PCI<->ISA bridge, that would be a PCI address. It defines the base |
650 | address in the parent bus where the beginning of that range is mapped. | 665 | address in the parent bus where the beginning of that range is mapped. |
651 | 666 | ||
652 | For a new 64 bit powerpc board, I recommend either the 2/2 format or | 667 | For a new 64-bit powerpc board, I recommend either the 2/2 format or |
653 | Apple's 2/1 format which is slightly more compact since sizes usually | 668 | Apple's 2/1 format which is slightly more compact since sizes usually |
654 | fit in a single 32 bit word. New 32 bit powerpc boards should use a | 669 | fit in a single 32-bit word. New 32-bit powerpc boards should use a |
655 | 1/1 format, unless the processor supports physical addresses greater | 670 | 1/1 format, unless the processor supports physical addresses greater |
656 | than 32-bits, in which case a 2/1 format is recommended. | 671 | than 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. |
920 | SOC. | ||
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 | ||
983 | The "output_version" defines what versio of the "blob" format will be | 989 | The "output_version" defines what version of the "blob" format will be |
984 | generated. Supported versions are 1,2,3 and 16. The default is | 990 | generated. Supported versions are 1,2,3 and 16. The default is |
985 | currently version 3 but that may change in the future to version 16. | 991 | currently 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 | ||
1087 | Many companies are now starting to develop system-on-a-chip | 1093 | Many companies are now starting to develop system-on-a-chip |
1088 | processors, where the processor core (cpu) and many peripheral devices | 1094 | processors, where the processor core (CPU) and many peripheral devices |
1089 | exist on a single piece of silicon. For these SOCs, an SOC node | 1095 | exist on a single piece of silicon. For these SOCs, an SOC node |
1090 | should be used that defines child nodes for the devices that make | 1096 | should be used that defines child nodes for the devices that make |
1091 | up the SOC. While platforms are not required to use this model in | 1097 | up 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 | |||
1117 | MPC8540. | 1123 | MPC8540. |
1118 | 1124 | ||
1119 | 1125 | ||
1120 | 2) Specifying interrupt information for SOC devices | 1126 | 2) Representing devices without a current OF specification |
1121 | --------------------------------------------------- | ||
1122 | |||
1123 | Each device that is part of an SOC and which generates interrupts | ||
1124 | should 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 | |||
1132 | This information is used by the kernel to build the interrupt table | ||
1133 | for the interrupt controllers in the system. | ||
1134 | |||
1135 | Sense 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 | |||
1155 | 3) Representing devices without a current OF specification | ||
1156 | ---------------------------------------------------------- | 1127 | ---------------------------------------------------------- |
1157 | 1128 | ||
1158 | Currently, there are many devices on SOCs that do not have a standard | 1129 | Currently, 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 | ||
1728 | VII - Specifying interrupt information for devices | ||
1729 | =================================================== | ||
1730 | |||
1731 | The device tree represents the busses and devices of a hardware | ||
1732 | system in a form similar to the physical bus topology of the | ||
1733 | hardware. | ||
1734 | |||
1735 | In addition, a logical 'interrupt tree' exists which represents the | ||
1736 | hierarchy and routing of interrupts in the hardware. | ||
1737 | |||
1738 | The interrupt tree model is fully described in the | ||
1739 | document "Open Firmware Recommended Practice: Interrupt | ||
1740 | Mapping Version 0.9". The document is available at: | ||
1741 | <http://playground.sun.com/1275/practice>. | ||
1742 | |||
1743 | 1) interrupts property | ||
1744 | ---------------------- | ||
1745 | |||
1746 | Devices that generate interrupts to a single interrupt controller | ||
1747 | should use the conventional OF representation described in the | ||
1748 | OF interrupt mapping documentation. | ||
1749 | |||
1750 | Each device which generates interrupts must have an 'interrupt' | ||
1751 | property. The interrupt property value is an arbitrary number of | ||
1752 | of 'interrupt specifier' values which describe the interrupt or | ||
1753 | interrupts for the device. | ||
1754 | |||
1755 | The encoding of an interrupt specifier is determined by the | ||
1756 | interrupt domain in which the device is located in the | ||
1757 | interrupt tree. The root of an interrupt domain specifies in | ||
1758 | its #interrupt-cells property the number of 32-bit cells | ||
1759 | required to encode an interrupt specifier. See the OF interrupt | ||
1760 | mapping documentation for a detailed description of domains. | ||
1761 | |||
1762 | For example, the binding for the OpenPIC interrupt controller | ||
1763 | specifies an #interrupt-cells value of 2 to encode the interrupt | ||
1764 | number and level/sense information. All interrupt children in an | ||
1765 | OpenPIC interrupt domain use 2 cells per interrupt in their interrupts | ||
1766 | property. | ||
1767 | |||
1768 | The PCI bus binding specifies a #interrupt-cell value of 1 to encode | ||
1769 | which interrupt pin (INTA,INTB,INTC,INTD) is used. | ||
1770 | |||
1771 | 2) interrupt-parent property | ||
1772 | ---------------------------- | ||
1773 | |||
1774 | The interrupt-parent property is specified to define an explicit | ||
1775 | link between a device node and its interrupt parent in | ||
1776 | the interrupt tree. The value of interrupt-parent is the | ||
1777 | phandle of the parent node. | ||
1778 | |||
1779 | If the interrupt-parent property is not defined for a node, it's | ||
1780 | interrupt parent is assumed to be an ancestor in the node's | ||
1781 | _device tree_ hierarchy. | ||
1782 | |||
1783 | 3) OpenPIC Interrupt Controllers | ||
1784 | -------------------------------- | ||
1785 | |||
1786 | OpenPIC interrupt controllers require 2 cells to encode | ||
1787 | interrupt information. The first cell defines the interrupt | ||
1788 | number. The second cell defines the sense and level | ||
1789 | information. | ||
1790 | |||
1791 | Sense 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 | |||
1798 | 4) ISA Interrupt Controllers | ||
1799 | ---------------------------- | ||
1800 | |||
1801 | ISA PIC interrupt controllers require 2 cells to encode | ||
1802 | interrupt information. The first cell defines the interrupt | ||
1803 | number. The second cell defines the sense and level | ||
1804 | information. | ||
1805 | |||
1806 | ISA PIC interrupt controllers should adhere to the ISA PIC | ||
1807 | encodings 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 | ||
1745 | Appendix A - Sample SOC node for MPC8540 | 1815 | Appendix A - Sample SOC node for MPC8540 |
1746 | ======================================== | 1816 | ======================================== |