Lines Matching +full:device +full:- +full:tree
2 --------------------------------------------------
7 Freescale Semiconductor, FSL SOC and 32-bit additions
14 I - Introduction
21 II - The DT block format
23 2) Device tree generalities
24 3) Device tree "structure" block
25 4) Device tree "strings" block
27 III - Required content of the device tree
40 IV - "dtc", the device tree compiler
42 V - Recommendations for a bootloader
44 VI - System-on-a-chip devices and nodes
48 VII - Specifying interrupt information for devices
50 2) interrupt-parent property
54 VIII - Specifying device power management information (sleep property)
56 IX - Specifying dma bus information
58 Appendix A - Sample SOC node for MPC8540
64 May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet.
66 May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or
69 small device tree, though it is encouraged
72 May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM
73 - Misc fixes
74 - Define version 3 and new format version 16
85 June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and
87 - Change version 16 format to always align
96 - Correct a few more alignment constraints
97 - Add a chapter about the device-tree
99 the tree that can be "compiled" by dtc.
102 - Additions/generalizations for 32-bit
103 - Changed to reflect the new arch/powerpc
105 - Added chapter VI
109 - Add some definitions of interrupt tree (simple/complex)
110 - Add some definitions for PCI host bridges
111 - Add some common address format examples
112 - Add definitions for standard properties and "compatible"
115 - Compare FSL SOC use of PCI to standard and make sure no new
117 - Add more information about node definitions for SOC devices
121 I - Introduction
127 regarding the kernel entry and bootloader <-> kernel interfaces, in
131 but no new board support will be accepted in the main tree that
133 arch/powerpc merged architecture for ppc32 and ppc64, new 32-bit
134 platforms and 32-bit platforms which move into arch/powerpc will be
138 the presence of a device-tree whose format is defined after Open
140 to embedded board vendors, the kernel doesn't require the device-tree
141 to represent every device in the system and only requires some nodes
144 create a node for every PCI device in the system. It is a requirement
150 drivers to device, without having to hard code all sorts of tables. It
157 ---------------------------
174 b) Entry with a flattened device-tree block. Firmware loads the
175 physical address of the flattened device tree block (dtb) into r2,
181 r1 : Valid machine type number. When using a device tree,
185 r2 : physical pointer to the device-tree block
186 (defined in chapter II) in RAM. Device tree can be located
190 The kernel will differentiate between ATAGS and device tree booting by
192 device tree block magic value (0xd00dfeed) or the ATAG_CORE value at
196 -------------------------------
208 bindings to powerpc. Only the 32-bit client interface
215 extract the device-tree and other information from open
216 firmware and build a flattened device-tree as described
217 in b). prom_init() will then re-enter the kernel using
222 b) Direct entry with a flattened device-tree block. This entry
233 r3 : physical pointer to the device-tree block
239 and a non-1:1 mapping.
253 given platform based on the content of the device-tree. Thus, you
274 -------------------------------
281 The physical pointer to the device-tree block (defined in chapter II)
287 This device-tree is used as an extension to the "boot page". As such it
294 ----------------------------------
301 Similar to the arch/arm case (b), a DT-aware bootloader is expected to
308 a2 : Physical pointer to the device tree block (defined in chapter
309 II) in RAM. The device tree can be located anywhere in the first
310 512MB of the physical address space (0x00000000 - 0x1fffffff),
317 This convention is defined for 32-bit systems only, as there are not
318 currently any 64-bit BMIPS implementations.
321 --------------------------
323 Device-tree-compatible SH bootloaders are expected to provide the physical
324 address of the device tree blob in r4. Since legacy bootloaders did not
326 inter-operate with old bootloaders must either use a builtin DTB or
328 that does not use device tree. Support for the latter is being phased out
329 in favor of device tree.
332 II - The DT block format
336 This chapter defines the actual format of the flattened device-tree
340 which will generate a flattened device-tree from the Open Firmware
353 ---------
381 /* Definitions used by the flattened device tree */
394 from the physical base address of the device tree block.
396 - magic
399 device-tree block header. It contains the value 0xd00dfeed and is
402 - totalsize
407 the device-tree structure, strings, and the memory reserve map.
409 - off_dt_struct
412 of the "structure" part the device tree. (see 2) device tree)
414 - off_dt_strings
417 of the "strings" part of the device-tree
419 - off_mem_rsvmap
422 of the reserved memory map. This map is a list of pairs of 64-
428 boot for things like un-flattening the device-tree, allocating an
436 should be 64-bit aligned.
438 - version
445 "compact" format for the tree itself that is however not backward
449 adjustments to a device tree based on probed information). You
454 - last_comp_version
460 should put a 1 in this field if you generate a device tree of
461 version 1 to 3, or 16 if you generate a tree of version 16 or 17
464 - boot_cpuid_phys
470 the device-tree corresponding to the CPU calling the kernel entry
472 device-tree contents)
474 - size_dt_strings
477 gives the size of the "strings" section of the device tree (which
480 - size_dt_struct
483 the size of the "structure" section of the device tree (which
491 ------------------------------
492 base -> | struct boot_param_header |
493 ------------------------------
495 ------------------------------
497 ------------------------------
499 ------------------------------
501 | device-tree structure |
503 ------------------------------
505 ------------------------------
507 | device-tree strings |
509 -----> ------------------------------
512 --- (base + totalsize)
519 2) Device tree generalities
520 ---------------------------
522 This device-tree itself is separated in two different blocks, a
526 First, let's quickly describe the device-tree concept before detailing
531 The device-tree layout is strongly inherited from the definition of
532 the Open Firmware IEEE 1275 device-tree. It's basically a tree of
536 It is a tree, so each node has one and only one parent except for the
550 The unit name doesn't exist as a property per-se but is included in
551 the device-tree structure. It is typically used to represent "path" in
552 the device-tree. More details about the actual format of these will be
558 the node unit name at a given level of the tree. Nodes with no notion
571 Every node which actually represents an actual device (that is, a node
582 if the flattened device tree is used directly. An example of a node
584 interrupt tree which will be described in a further version of this
587 The "phandle" property is a 32-bit value that uniquely
593 Here is an example of a simple device-tree. In this example, an "o"
597 represents a 32-bit value, specified in decimal or hexadecimal (the
600 you a idea of what a device-tree looks like. I have purposefully kept
602 order to give you a better idea of what the tree looks like in
605 / o device-tree
606 |- name = "device-tree"
607 |- model = "MyBoardName"
608 |- compatible = "MyBoardFamilyName"
609 |- #address-cells = <2>
610 |- #size-cells = <2>
611 |- linux,phandle = <0>
614 | | - name = "cpus"
615 | | - linux,phandle = <1>
616 | | - #address-cells = <1>
617 | | - #size-cells = <0>
620 | |- name = "PowerPC,970"
621 | |- device_type = "cpu"
622 | |- reg = <0>
623 | |- clock-frequency = <0x5f5e1000>
624 | |- 64-bit
625 | |- linux,phandle = <2>
628 | |- name = "memory"
629 | |- device_type = "memory"
630 | |- reg = <0x00000000 0x00000000 0x00000000 0x20000000>
631 | |- linux,phandle = <3>
634 |- name = "chosen"
635 |- bootargs = "root=/dev/sda2"
636 |- linux,phandle = <4>
638 This tree is almost a minimal tree. It pretty much contains the
645 The /cpus/PowerPC,970@0/64-bit property is an example of a
647 significance of the #address-cells and #size-cells properties will be
652 3) Device tree "structure" block
654 The structure of the device tree is a linearized tree structure. The
658 bit value. The tree has to be "finished" with a OF_DT_END token
670 * 32-bit value of property value size in bytes (or 0 if no
672 * 32-bit value of offset in string block of property name
687 manipulating a flattened tree must take care to preserve this
690 4) Device tree "strings" block
695 concatenated together. The device-tree property definitions in the
700 III - Required content of the device tree
704 to a flattened device-tree. If your platform uses a real
709 set the platform number. However, when using the flattened device-tree
715 ----------------------------------------------
718 documentations. If you choose to describe a bus with the device-tree
721 device or bus to be described by the device tree.
723 In general, the format of an address for a device is defined by the
724 parent bus type, based on the #address-cells and #size-cells
725 properties. Note that the parent's parent definitions of #address-cells
726 and #size-cells are not inherited so every node with children must specify
731 size. A "cell" is a 32-bit number. For example, if both contain 2
732 like the example tree given above, then an address and a size are both
733 composed of 2 cells, and each is a 64-bit number (cells are
736 and one cell for a size. Most 32-bit implementations should define
737 #address-cells and #size-cells to 1, which represents a 32-bit value.
738 Some 32-bit processors allow for physical addresses greater than 32
739 bits; these processors should define #address-cells as 2.
743 #address-cells and #size-cells. When a bus supports various address
749 bus & device numbers.
754 then, to provide a separate "assigned-addresses" property that
765 The "reg" property only defines addresses and sizes (if #size-cells is
766 non-0) within a given bus. In order to translate addresses upward
781 PCI<->ISA bridge, that would be a PCI address. It defines the base
784 For new 64-bit board support, I recommend either the 2/2 format or
786 fit in a single 32-bit word. New 32-bit board support should use a
788 than 32-bits, in which case a 2/1 format is recommended.
796 -------------------------------------
800 zero terminated strings. They allow a device to express its
806 -------------------------------
809 to use the actual device name for the "name" property, it's nowadays
810 considered a good practice to use a name that is closer to the device
827 -------------------------------------------------------
829 While Open Firmware provides more flexible usage of 8859-1, this
832 '9', ',', '.', '_', '+', '#', '?', and '-'. Node names additionally
846 --------------------------------
849 PCI binding to Open Firmware, and your interrupt tree as documented
850 in OF interrupt tree specification.
856 - model : this is your board name/model
857 - #address-cells : address representation for "root" devices
858 - #size-cells: the size representation for "root" devices
859 - compatible : the board "family" generally finds its way here,
874 - serial-number : a string representing the device's serial number
882 #address-cells = <00000001>
883 #size-cells = <00000000>
902 - device_type : has to be "cpu"
903 - reg : This is the physical CPU number, it's a single 32-bit cell
904 and is also used as-is as the unit number for constructing the
910 - d-cache-block-size : one cell, L1 data cache block size in bytes (*)
911 - i-cache-block-size : one cell, L1 instruction cache block size in
913 - d-cache-size : one cell, size of L1 data cache in bytes
914 - i-cache-size : one cell, size of L1 instruction cache in bytes
924 - timebase-frequency : a cell indicating the frequency of the
929 - clock-frequency : a cell indicating the CPU core clock frequency
930 in Hz. A new property will be defined for 64-bit values, but if
933 you are welcome to re-use the pSeries or Maple one. A future
935 - d-cache-line-size : one cell, L1 data cache line size in bytes
937 - i-cache-line-size : one cell, L1 instruction cache line size in
941 like some information about the mechanism used to soft-reset the
943 lines in there as a "soft-reset" property since they start secondary
944 CPUs by soft-resetting them.
959 - device_type : has to be "memory"
960 - reg : This property contains all the physical memory ranges of
963 #address-cells and #size-cells of the root node. For example,
979 - hotpluggable : The presence of this property provides an explicit
991 some linux-specific properties that would be normally constructed by
997 - bootargs : This zero-terminated string is passed as the kernel
999 - linux,stdout-path : This is the full path to your standard
1000 console device if any. Typically, if you have serial devices on
1005 Note that u-boot creates and fills in the chosen node for platforms
1009 under /chosen called interrupt-controller which had a phandle value
1014 This node is used to represent a system-on-a-chip (SoC) and must be
1015 present if the processor is a SoC. The top-level soc node contains
1018 of the memory-mapped register set for the SoC. The name of an SoC
1025 - ranges : Should be defined as specified in 1) to describe the
1027 - bus-frequency: Contains the bus frequency for the SoC node.
1030 - compatible : Exact model of the SoC
1035 - reg : This property defines the address and size of the
1036 memory-mapped registers that are used for the SOC node itself.
1037 It does not include the child device registers - these will be
1040 - #address-cells : Address representation for "soc" devices. The
1042 device registers are memory mapped. For memory mapped
1047 See 1) above for more details on defining #address-cells.
1048 - #size-cells : Size representation for "soc" devices
1049 - #interrupt-cells : Defines the width of cells used to represent
1051 32-bit number that represents the interrupt number, and a
1052 32-bit number that represents the interrupt sense and level.
1056 The SOC node may contain child nodes for each SOC device that the
1064 #address-cells = <1>;
1065 #size-cells = <1>;
1066 #interrupt-cells = <2>;
1070 bus-frequency = <0>;
1075 IV - "dtc", the device tree compiler
1083 resulting device-tree "blobs" have not yet been validated with the
1089 dtc basically takes a device-tree in a given format and outputs a
1090 device-tree in another format. The currently supported formats are:
1093 -------------
1095 - "dtb": "blob" format, that is a flattened device-tree block
1098 - "dts": "source" format. This is a text file containing a
1099 "source" for a device-tree. The format is defined later in this
1101 - "fs" format. This is a representation equivalent to the
1102 output of /proc/device-tree, that is nodes are directories and
1106 ---------------
1108 - "dtb": "blob" format
1109 - "dts": "source" format
1110 - "asm": assembly language file. This is a file that can be
1111 sourced by gas to generate a device-tree "blob". That file can
1118 dtc [-I <input-format>] [-O <output-format>]
1119 [-o output-filename] [-V output_version] input_filename
1126 Additionally, dtc performs various sanity checks on the tree, like the
1135 The above is the "device-tree" definition. It's the only statement
1144 * numerical 32-bit value (hexadecimal)
1149 * numerical 32-bit values (cells) in
1169 structure of the tree.
1180 you link the device-tree with), label or path instead of numeric value
1191 V - Recommendations for a bootloader
1198 - The bootloader may want to be able to use the device-tree itself
1202 flattened format, or the bootloader has its own internal tree
1204 re-flattens the tree when booting the kernel. The former is a bit
1206 more code to handle the tree structure. Note that the structure
1212 - An example of code for iterating nodes & retrieving properties
1213 directly from the flattened tree format can be found in the kernel
1216 early_init_dt_scan_*() callbacks. That code can be re-used in a
1219 integrate all or part of this code into a non-GPL bootloader.
1220 (reference needed; who is 'I' here? ---gcl Jan 31, 2011)
1224 VI - System-on-a-chip devices and nodes
1227 Many companies are now starting to develop system-on-a-chip
1233 implementations define as complete a flat-device-tree as possible to
1239 ---------------------------------
1241 Each device that is part of an SOC may have its own node entry inside
1242 the SOC node. For each device that is included in the SOC, the unit
1243 address property represents the address offset for this device's
1244 memory-mapped registers in the parent's address space. The parent's
1245 address space is defined by the "ranges" property in the top-level soc
1248 to the parent SOC address space and the size of the device's
1249 memory-mapped register file.
1252 specifications for the format of the device tree node. All SOC child
1261 ----------------------------------------------------------
1268 That directory will expand as device tree support is added to more and
1272 VII - Specifying interrupt information for devices
1275 The device tree represents the buses and devices of a hardware
1279 In addition, a logical 'interrupt tree' exists which represents the
1282 The interrupt tree model is fully described in the
1285 <http://www.devicetree.org/open-firmware/practice/>
1288 ----------------------
1294 Each device which generates interrupts must have an 'interrupt'
1297 interrupts for the device.
1300 interrupt domain in which the device is located in the
1301 interrupt tree. The root of an interrupt domain specifies in
1302 its #interrupt-cells property the number of 32-bit cells
1307 specifies an #interrupt-cells value of 2 to encode the interrupt
1312 The PCI bus binding specifies a #interrupt-cells value of 1 to encode
1315 2) interrupt-parent property
1316 ----------------------------
1318 The interrupt-parent property is specified to define an explicit
1319 link between a device node and its interrupt parent in
1320 the interrupt tree. The value of interrupt-parent is the
1323 If the interrupt-parent property is not defined for a node, its
1328 --------------------------------
1343 ----------------------------
1358 VIII - Specifying Device Power Management Information (sleep property)
1361 Devices on SOCs often have mechanisms for placing devices into low-power
1363 this information is more complicated than a cell-index property can
1364 reasonably describe. Thus, each device controlled in such a manner
1369 controller-specific sleep specifier of zero or more cells.
1375 - Dynamic: The device may be disabled or enabled at any time.
1376 - System Suspend: The device may request to be disabled or remain
1378 - Permanent: The device is disabled permanently (until the next hard
1387 sleep-map should wait until its necessity is demonstrated).
1389 IX - Specifying dma bus information
1394 - RAM range: [0x8 0000 0000, 0x8 FFFF FFFF]
1395 - DMA range: [ 0x8000 0000, 0xFFFF FFFF]
1399 and DMA addresses. The "dma-ranges" property is intended to be used
1402 In addition, each DMA master device on the DMA bus may or may not support
1403 coherent DMA operations. The "dma-coherent" property is intended to be used
1408 - dma-ranges: <prop-encoded-array> encoded as arbitrary number of triplets of
1409 (child-bus-address, parent-bus-address, length). Each triplet specified
1411 The dma-ranges property is used to describe the direct memory access (DMA)
1412 structure of a memory-mapped bus whose device tree parent can be accessed
1420 - dma-ranges: <empty> value. if present - It means that DMA addresses
1421 translation has to be enabled for this device.
1422 - dma-coherent: Present if dma operations are coherent
1426 compatible = "ti,keystone","simple-bus";
1428 dma-ranges = <0x80000000 0x8 0x00000000 0x80000000>;
1433 compatible = "ti,keystone-dwc3";
1436 dma-coherent;
1440 Appendix A - Sample SOC node for MPC8540
1444 #address-cells = <1>;
1445 #size-cells = <1>;
1446 compatible = "fsl,mpc8540-ccsr", "simple-bus";
1449 bus-frequency = <0>;
1450 interrupt-parent = <&pic>;
1453 #address-cells = <1>;
1454 #size-cells = <1>;
1457 compatible = "gianfar", "simple-bus";
1459 local-mac-address = [ 0x00 0xE0 0x0C 0x00 0x73 0x00 ];
1461 phy-handle = <&phy0>;
1467 compatible = "fsl,gianfar-mdio";
1469 phy0: ethernet-phy@0 {
1474 phy1: ethernet-phy@1 {
1479 phy3: ethernet-phy@3 {
1491 local-mac-address = [ 0x00 0xE0 0x0C 0x00 0x73 0x01 ];
1493 phy-handle = <&phy1>;
1502 local-mac-address = [ 0x00 0xE0 0x0C 0x00 0x73 0x02 ];
1504 phy-handle = <&phy3>;
1509 #address-cells = <1>;
1510 #size-cells = <1>;
1511 compatible = "fsl,mpc8540-duart", "simple-bus";
1519 clock-frequency = <0>;
1527 clock-frequency = <0>;
1533 interrupt-controller;
1534 #address-cells = <0>;
1535 #interrupt-cells = <2>;
1537 compatible = "chrp,open-pic";
1538 device_type = "open-pic";
1544 compatible = "fsl-i2c";
1550 compatible = "fsl,mpc8540-pmc", "fsl,mpc8548-pmc";