aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/devicetree/booting-without-of.txt165
1 files changed, 54 insertions, 111 deletions
diff --git a/Documentation/devicetree/booting-without-of.txt b/Documentation/devicetree/booting-without-of.txt
index 7400d7555dc..28b1c9d3d35 100644
--- a/Documentation/devicetree/booting-without-of.txt
+++ b/Documentation/devicetree/booting-without-of.txt
@@ -13,7 +13,6 @@ Table of Contents
13 13
14 I - Introduction 14 I - Introduction
15 1) Entry point for arch/powerpc 15 1) Entry point for arch/powerpc
16 2) Board support
17 16
18 II - The DT block format 17 II - The DT block format
19 1) Header 18 1) Header
@@ -41,13 +40,6 @@ Table of Contents
41 VI - System-on-a-chip devices and nodes 40 VI - System-on-a-chip devices and nodes
42 1) Defining child nodes of an SOC 41 1) Defining child nodes of an SOC
43 2) Representing devices without a current OF specification 42 2) Representing devices without a current OF specification
44 a) PHY nodes
45 b) Interrupt controllers
46 c) 4xx/Axon EMAC ethernet nodes
47 d) Xilinx IP cores
48 e) USB EHCI controllers
49 f) MDIO on GPIOs
50 g) SPI busses
51 43
52 VII - Specifying interrupt information for devices 44 VII - Specifying interrupt information for devices
53 1) interrupts property 45 1) interrupts property
@@ -123,7 +115,7 @@ Revision Information
123I - Introduction 115I - Introduction
124================ 116================
125 117
126During the recent development of the Linux/ppc64 kernel, and more 118During the development of the Linux/ppc64 kernel, and more
127specifically, the addition of new platform types outside of the old 119specifically, the addition of new platform types outside of the old
128IBM pSeries/iSeries pair, it was decided to enforce some strict rules 120IBM pSeries/iSeries pair, it was decided to enforce some strict rules
129regarding the kernel entry and bootloader <-> kernel interfaces, in 121regarding the kernel entry and bootloader <-> kernel interfaces, in
@@ -146,7 +138,7 @@ section III, but, for example, the kernel does not require you to
146create a node for every PCI device in the system. It is a requirement 138create a node for every PCI device in the system. It is a requirement
147to have a node for PCI host bridges in order to provide interrupt 139to have a node for PCI host bridges in order to provide interrupt
148routing informations and memory/IO ranges, among others. It is also 140routing informations and memory/IO ranges, among others. It is also
149recommended to define nodes for on chip devices and other busses that 141recommended to define nodes for on chip devices and other buses that
150don't specifically fit in an existing OF specification. This creates a 142don't specifically fit in an existing OF specification. This creates a
151great flexibility in the way the kernel can then probe those and match 143great flexibility in the way the kernel can then probe those and match
152drivers to device, without having to hard code all sorts of tables. It 144drivers to device, without having to hard code all sorts of tables. It
@@ -158,7 +150,7 @@ it with special cases.
1581) Entry point for arch/powerpc 1501) Entry point for arch/powerpc
159------------------------------- 151-------------------------------
160 152
161 There is one and one single entry point to the kernel, at the start 153 There is one single entry point to the kernel, at the start
162 of the kernel image. That entry point supports two calling 154 of the kernel image. That entry point supports two calling
163 conventions: 155 conventions:
164 156
@@ -210,12 +202,6 @@ it with special cases.
210 with all CPUs. The way to do that with method b) will be 202 with all CPUs. The way to do that with method b) will be
211 described in a later revision of this document. 203 described in a later revision of this document.
212 204
213
2142) Board support
215----------------
216
21764-bit kernels:
218
219 Board supports (platforms) are not exclusive config options. An 205 Board supports (platforms) are not exclusive config options. An
220 arbitrary set of board supports can be built in a single kernel 206 arbitrary set of board supports can be built in a single kernel
221 image. The kernel will "know" what set of functions to use for a 207 image. The kernel will "know" what set of functions to use for a
@@ -234,48 +220,11 @@ it with special cases.
234 containing the various callbacks that the generic code will 220 containing the various callbacks that the generic code will
235 use to get to your platform specific code 221 use to get to your platform specific code
236 222
237 c) Add a reference to your "ppc_md" structure in the 223 A kernel image may support multiple platforms, but only if the
238 "machines" table in arch/powerpc/kernel/setup_64.c if you are
239 a 64-bit platform.
240
241 d) request and get assigned a platform number (see PLATFORM_*
242 constants in arch/powerpc/include/asm/processor.h
243
24432-bit embedded kernels:
245
246 Currently, board support is essentially an exclusive config option.
247 The kernel is configured for a single platform. Part of the reason
248 for this is to keep kernels on embedded systems small and efficient;
249 part of this is due to the fact the code is already that way. In the
250 future, a kernel may support multiple platforms, but only if the
251 platforms feature the same core architecture. A single kernel build 224 platforms feature the same core architecture. A single kernel build
252 cannot support both configurations with Book E and configurations 225 cannot support both configurations with Book E and configurations
253 with classic Powerpc architectures. 226 with classic Powerpc architectures.
254 227
255 32-bit embedded platforms that are moved into arch/powerpc using a
256 flattened device tree should adopt the merged tree practice of
257 setting ppc_md up dynamically, even though the kernel is currently
258 built with support for only a single platform at a time. This allows
259 unification of the setup code, and will make it easier to go to a
260 multiple-platform-support model in the future.
261
262NOTE: I believe the above will be true once Ben's done with the merge
263of the boot sequences.... someone speak up if this is wrong!
264
265 To add a 32-bit embedded platform support, follow the instructions
266 for 64-bit platforms above, with the exception that the Kconfig
267 option should be set up such that the kernel builds exclusively for
268 the platform selected. The processor type for the platform should
269 enable another config option to select the specific board
270 supported.
271
272NOTE: If Ben doesn't merge the setup files, may need to change this to
273point to setup_32.c
274
275
276 I will describe later the boot process and various callbacks that
277 your platform should implement.
278
279 228
280II - The DT block format 229II - The DT block format
281======================== 230========================
@@ -300,8 +249,8 @@ the block to RAM before passing it to the kernel.
3001) Header 2491) Header
301--------- 250---------
302 251
303 The kernel is entered with r3 pointing to an area of memory that is 252 The kernel is passed the physical address pointing to an area of memory
304 roughly described in arch/powerpc/include/asm/prom.h by the structure 253 that is roughly described in include/linux/of_fdt.h by the structure
305 boot_param_header: 254 boot_param_header:
306 255
307struct boot_param_header { 256struct boot_param_header {
@@ -339,7 +288,7 @@ struct boot_param_header {
339 All values in this header are in big endian format, the various 288 All values in this header are in big endian format, the various
340 fields in this header are defined more precisely below. All 289 fields in this header are defined more precisely below. All
341 "offset" values are in bytes from the start of the header; that is 290 "offset" values are in bytes from the start of the header; that is
342 from the value of r3. 291 from the physical base address of the device tree block.
343 292
344 - magic 293 - magic
345 294
@@ -437,7 +386,7 @@ struct boot_param_header {
437 386
438 387
439 ------------------------------ 388 ------------------------------
440 r3 -> | struct boot_param_header | 389 base -> | struct boot_param_header |
441 ------------------------------ 390 ------------------------------
442 | (alignment gap) (*) | 391 | (alignment gap) (*) |
443 ------------------------------ 392 ------------------------------
@@ -457,7 +406,7 @@ struct boot_param_header {
457 -----> ------------------------------ 406 -----> ------------------------------
458 | 407 |
459 | 408 |
460 --- (r3 + totalsize) 409 --- (base + totalsize)
461 410
462 (*) The alignment gaps are not necessarily present; their presence 411 (*) The alignment gaps are not necessarily present; their presence
463 and size are dependent on the various alignment requirements of 412 and size are dependent on the various alignment requirements of
@@ -500,7 +449,7 @@ the device-tree structure. It is typically used to represent "path" in
500the device-tree. More details about the actual format of these will be 449the device-tree. More details about the actual format of these will be
501below. 450below.
502 451
503The kernel powerpc generic code does not make any formal use of the 452The kernel generic code does not make any formal use of the
504unit address (though some board support code may do) so the only real 453unit address (though some board support code may do) so the only real
505requirement here for the unit address is to ensure uniqueness of 454requirement here for the unit address is to ensure uniqueness of
506the node unit name at a given level of the tree. Nodes with no notion 455the node unit name at a given level of the tree. Nodes with no notion
@@ -518,20 +467,21 @@ path to the root node is "/".
518 467
519Every node which actually represents an actual device (that is, a node 468Every node which actually represents an actual device (that is, a node
520which isn't only a virtual "container" for more nodes, like "/cpus" 469which isn't only a virtual "container" for more nodes, like "/cpus"
521is) is also required to have a "device_type" property indicating the 470is) is also required to have a "compatible" property indicating the
522type of node . 471specific hardware and an optional list of devices it is fully
472backwards compatible with.
523 473
524Finally, every node that can be referenced from a property in another 474Finally, every node that can be referenced from a property in another
525node is required to have a "linux,phandle" property. Real open 475node is required to have either a "phandle" or a "linux,phandle"
526firmware implementations provide a unique "phandle" value for every 476property. Real Open Firmware implementations provide a unique
527node that the "prom_init()" trampoline code turns into 477"phandle" value for every node that the "prom_init()" trampoline code
528"linux,phandle" properties. However, this is made optional if the 478turns into "linux,phandle" properties. However, this is made optional
529flattened device tree is used directly. An example of a node 479if the flattened device tree is used directly. An example of a node
530referencing another node via "phandle" is when laying out the 480referencing another node via "phandle" is when laying out the
531interrupt tree which will be described in a further version of this 481interrupt tree which will be described in a further version of this
532document. 482document.
533 483
534This "linux, phandle" property is a 32-bit value that uniquely 484The "phandle" property is a 32-bit value that uniquely
535identifies a node. You are free to use whatever values or system of 485identifies a node. You are free to use whatever values or system of
536values, internal pointers, or whatever to generate these, the only 486values, internal pointers, or whatever to generate these, the only
537requirement is that every node for which you provide that property has 487requirement is that every node for which you provide that property has
@@ -694,7 +644,7 @@ made of 3 cells, the bottom two containing the actual address itself
694while the top cell contains address space indication, flags, and pci 644while the top cell contains address space indication, flags, and pci
695bus & device numbers. 645bus & device numbers.
696 646
697For busses that support dynamic allocation, it's the accepted practice 647For buses that support dynamic allocation, it's the accepted practice
698to then not provide the address in "reg" (keep it 0) though while 648to then not provide the address in "reg" (keep it 0) though while
699providing a flag indicating the address is dynamically allocated, and 649providing a flag indicating the address is dynamically allocated, and
700then, to provide a separate "assigned-addresses" property that 650then, to provide a separate "assigned-addresses" property that
@@ -711,7 +661,7 @@ prom_parse.c file of the recent kernels for your bus type.
711The "reg" property only defines addresses and sizes (if #size-cells is 661The "reg" property only defines addresses and sizes (if #size-cells is
712non-0) within a given bus. In order to translate addresses upward 662non-0) within a given bus. In order to translate addresses upward
713(that is into parent bus addresses, and possibly into CPU physical 663(that is into parent bus addresses, and possibly into CPU physical
714addresses), all busses must contain a "ranges" property. If the 664addresses), all buses must contain a "ranges" property. If the
715"ranges" property is missing at a given level, it's assumed that 665"ranges" property is missing at a given level, it's assumed that
716translation isn't possible, i.e., the registers are not visible on the 666translation isn't possible, i.e., the registers are not visible on the
717parent bus. The format of the "ranges" property for a bus is a list 667parent bus. The format of the "ranges" property for a bus is a list
@@ -727,9 +677,9 @@ example, for a PCI host controller, that would be a CPU address. For a
727PCI<->ISA bridge, that would be a PCI address. It defines the base 677PCI<->ISA bridge, that would be a PCI address. It defines the base
728address in the parent bus where the beginning of that range is mapped. 678address in the parent bus where the beginning of that range is mapped.
729 679
730For a new 64-bit powerpc board, I recommend either the 2/2 format or 680For new 64-bit board support, I recommend either the 2/2 format or
731Apple's 2/1 format which is slightly more compact since sizes usually 681Apple's 2/1 format which is slightly more compact since sizes usually
732fit in a single 32-bit word. New 32-bit powerpc boards should use a 682fit in a single 32-bit word. New 32-bit board support should use a
7331/1 format, unless the processor supports physical addresses greater 6831/1 format, unless the processor supports physical addresses greater
734than 32-bits, in which case a 2/1 format is recommended. 684than 32-bits, in which case a 2/1 format is recommended.
735 685
@@ -754,7 +704,7 @@ of their actual names.
754While earlier users of Open Firmware like OldWorld macintoshes tended 704While earlier users of Open Firmware like OldWorld macintoshes tended
755to use the actual device name for the "name" property, it's nowadays 705to use the actual device name for the "name" property, it's nowadays
756considered a good practice to use a name that is closer to the device 706considered a good practice to use a name that is closer to the device
757class (often equal to device_type). For example, nowadays, ethernet 707class (often equal to device_type). For example, nowadays, Ethernet
758controllers are named "ethernet", an additional "model" property 708controllers are named "ethernet", an additional "model" property
759defining precisely the chip type/model, and "compatible" property 709defining precisely the chip type/model, and "compatible" property
760defining the family in case a single driver can driver more than one 710defining the family in case a single driver can driver more than one
@@ -772,7 +722,7 @@ is present).
7724) Note about node and property names and character set 7224) Note about node and property names and character set
773------------------------------------------------------- 723-------------------------------------------------------
774 724
775While open firmware provides more flexible usage of 8859-1, this 725While Open Firmware provides more flexible usage of 8859-1, this
776specification enforces more strict rules. Nodes and properties should 726specification enforces more strict rules. Nodes and properties should
777be comprised only of ASCII characters 'a' to 'z', '0' to 727be comprised only of ASCII characters 'a' to 'z', '0' to
778'9', ',', '.', '_', '+', '#', '?', and '-'. Node names additionally 728'9', ',', '.', '_', '+', '#', '?', and '-'. Node names additionally
@@ -792,7 +742,7 @@ address which can extend beyond that limit.
792-------------------------------- 742--------------------------------
793 These are all that are currently required. However, it is strongly 743 These are all that are currently required. However, it is strongly
794 recommended that you expose PCI host bridges as documented in the 744 recommended that you expose PCI host bridges as documented in the
795 PCI binding to open firmware, and your interrupt tree as documented 745 PCI binding to Open Firmware, and your interrupt tree as documented
796 in OF interrupt tree specification. 746 in OF interrupt tree specification.
797 747
798 a) The root node 748 a) The root node
@@ -802,20 +752,12 @@ address which can extend beyond that limit.
802 - model : this is your board name/model 752 - model : this is your board name/model
803 - #address-cells : address representation for "root" devices 753 - #address-cells : address representation for "root" devices
804 - #size-cells: the size representation for "root" devices 754 - #size-cells: the size representation for "root" devices
805 - device_type : This property shouldn't be necessary. However, if
806 you decide to create a device_type for your root node, make sure it
807 is _not_ "chrp" unless your platform is a pSeries or PAPR compliant
808 one for 64-bit, or a CHRP-type machine for 32-bit as this will
809 matched by the kernel this way.
810
811 Additionally, some recommended properties are:
812
813 - compatible : the board "family" generally finds its way here, 755 - compatible : the board "family" generally finds its way here,
814 for example, if you have 2 board models with a similar layout, 756 for example, if you have 2 board models with a similar layout,
815 that typically get driven by the same platform code in the 757 that typically get driven by the same platform code in the
816 kernel, you would use a different "model" property but put a 758 kernel, you would specify the exact board model in the
817 value in "compatible". The kernel doesn't directly use that 759 compatible property followed by an entry that represents the SoC
818 value but it is generally useful. 760 model.
819 761
820 The root node is also generally where you add additional properties 762 The root node is also generally where you add additional properties
821 specific to your board like the serial number if any, that sort of 763 specific to your board like the serial number if any, that sort of
@@ -841,8 +783,11 @@ address which can extend beyond that limit.
841 783
842 So under /cpus, you are supposed to create a node for every CPU on 784 So under /cpus, you are supposed to create a node for every CPU on
843 the machine. There is no specific restriction on the name of the 785 the machine. There is no specific restriction on the name of the
844 CPU, though It's common practice to call it PowerPC,<name>. For 786 CPU, though it's common to call it <architecture>,<core>. For
845 example, Apple uses PowerPC,G5 while IBM uses PowerPC,970FX. 787 example, Apple uses PowerPC,G5 while IBM uses PowerPC,970FX.
788 However, the Generic Names convention suggests that it would be
789 better to simply use 'cpu' for each cpu node and use the compatible
790 property to identify the specific cpu core.
846 791
847 Required properties: 792 Required properties:
848 793
@@ -923,7 +868,7 @@ compatibility.
923 868
924 e) The /chosen node 869 e) The /chosen node
925 870
926 This node is a bit "special". Normally, that's where open firmware 871 This node is a bit "special". Normally, that's where Open Firmware
927 puts some variable environment information, like the arguments, or 872 puts some variable environment information, like the arguments, or
928 the default input/output devices. 873 the default input/output devices.
929 874
@@ -940,11 +885,7 @@ compatibility.
940 console device if any. Typically, if you have serial devices on 885 console device if any. Typically, if you have serial devices on
941 your board, you may want to put the full path to the one set as 886 your board, you may want to put the full path to the one set as
942 the default console in the firmware here, for the kernel to pick 887 the default console in the firmware here, for the kernel to pick
943 it up as its own default console. If you look at the function 888 it up as its own default console.
944 set_preferred_console() in arch/ppc64/kernel/setup.c, you'll see
945 that the kernel tries to find out the default console and has
946 knowledge of various types like 8250 serial ports. You may want
947 to extend this function to add your own.
948 889
949 Note that u-boot creates and fills in the chosen node for platforms 890 Note that u-boot creates and fills in the chosen node for platforms
950 that use it. 891 that use it.
@@ -955,23 +896,23 @@ compatibility.
955 896
956 f) the /soc<SOCname> node 897 f) the /soc<SOCname> node
957 898
958 This node is used to represent a system-on-a-chip (SOC) and must be 899 This node is used to represent a system-on-a-chip (SoC) and must be
959 present if the processor is a SOC. The top-level soc node contains 900 present if the processor is a SoC. The top-level soc node contains
960 information that is global to all devices on the SOC. The node name 901 information that is global to all devices on the SoC. The node name
961 should contain a unit address for the SOC, which is the base address 902 should contain a unit address for the SoC, which is the base address
962 of the memory-mapped register set for the SOC. The name of an soc 903 of the memory-mapped register set for the SoC. The name of an SoC
963 node should start with "soc", and the remainder of the name should 904 node should start with "soc", and the remainder of the name should
964 represent the part number for the soc. For example, the MPC8540's 905 represent the part number for the soc. For example, the MPC8540's
965 soc node would be called "soc8540". 906 soc node would be called "soc8540".
966 907
967 Required properties: 908 Required properties:
968 909
969 - device_type : Should be "soc"
970 - ranges : Should be defined as specified in 1) to describe the 910 - ranges : Should be defined as specified in 1) to describe the
971 translation of SOC addresses for memory mapped SOC registers. 911 translation of SoC addresses for memory mapped SoC registers.
972 - bus-frequency: Contains the bus frequency for the SOC node. 912 - bus-frequency: Contains the bus frequency for the SoC node.
973 Typically, the value of this field is filled in by the boot 913 Typically, the value of this field is filled in by the boot
974 loader. 914 loader.
915 - compatible : Exact model of the SoC
975 916
976 917
977 Recommended properties: 918 Recommended properties:
@@ -1155,12 +1096,13 @@ while all this has been defined and implemented.
1155 1096
1156 - An example of code for iterating nodes & retrieving properties 1097 - An example of code for iterating nodes & retrieving properties
1157 directly from the flattened tree format can be found in the kernel 1098 directly from the flattened tree format can be found in the kernel
1158 file arch/ppc64/kernel/prom.c, look at scan_flat_dt() function, 1099 file drivers/of/fdt.c. Look at the of_scan_flat_dt() function,
1159 its usage in early_init_devtree(), and the corresponding various 1100 its usage in early_init_devtree(), and the corresponding various
1160 early_init_dt_scan_*() callbacks. That code can be re-used in a 1101 early_init_dt_scan_*() callbacks. That code can be re-used in a
1161 GPL bootloader, and as the author of that code, I would be happy 1102 GPL bootloader, and as the author of that code, I would be happy
1162 to discuss possible free licensing to any vendor who wishes to 1103 to discuss possible free licensing to any vendor who wishes to
1163 integrate all or part of this code into a non-GPL bootloader. 1104 integrate all or part of this code into a non-GPL bootloader.
1105 (reference needed; who is 'I' here? ---gcl Jan 31, 2011)
1164 1106
1165 1107
1166 1108
@@ -1203,18 +1145,19 @@ MPC8540.
12032) Representing devices without a current OF specification 11452) Representing devices without a current OF specification
1204---------------------------------------------------------- 1146----------------------------------------------------------
1205 1147
1206Currently, there are many devices on SOCs that do not have a standard 1148Currently, there are many devices on SoCs that do not have a standard
1207representation pre-defined as part of the open firmware 1149representation defined as part of the Open Firmware specifications,
1208specifications, mainly because the boards that contain these SOCs are 1150mainly because the boards that contain these SoCs are not currently
1209not currently booted using open firmware. This section contains 1151booted using Open Firmware. Binding documentation for new devices
1210descriptions for the SOC devices for which new nodes have been 1152should be added to the Documentation/devicetree/bindings directory.
1211defined; this list will expand as more and more SOC-containing 1153That directory will expand as device tree support is added to more and
1212platforms are moved over to use the flattened-device-tree model. 1154more SoCs.
1155
1213 1156
1214VII - Specifying interrupt information for devices 1157VII - Specifying interrupt information for devices
1215=================================================== 1158===================================================
1216 1159
1217The device tree represents the busses and devices of a hardware 1160The device tree represents the buses and devices of a hardware
1218system in a form similar to the physical bus topology of the 1161system in a form similar to the physical bus topology of the
1219hardware. 1162hardware.
1220 1163