Lines Matching +full:enabled +full:- +full:strings
2 --------------------------------------------------
7 Freescale Semiconductor, FSL SOC and 32-bit additions
14 I - Introduction
21 II - The DT block format
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
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
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
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
157 ---------------------------
174 b) Entry with a flattened device-tree block. Firmware loads the
185 r2 : physical pointer to the device-tree block
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
238 in case you are entering the kernel with MMU enabled
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
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
326 inter-operate with old bootloaders must either use a builtin DTB or
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 ---------
363 u32 off_dt_strings; /* offset to strings */
373 u32 size_dt_strings; /* size of the strings 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
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
442 Version 3 adds the size of the strings block, allowing the kernel
454 - last_comp_version
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
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)
520 ---------------------------
522 This device-tree itself is separated in two different blocks, a
523 structure block and a strings block. Both need to be aligned to a 4
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
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
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
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>
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
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
690 4) Device tree "strings" block
693 are stored separately in the "strings" block. This block is simply the
694 whole bunch of zero terminated strings for all property names
695 concatenated together. The device-tree property definitions in the
697 strings block.
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
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
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
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 -------------------------------
827 -------------------------------------------------------
829 While Open Firmware provides more flexible usage of 8859-1, this
832 '9', ',', '.', '_', '+', '#', '?', and '-'. Node names additionally
846 --------------------------------
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
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
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.
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
1127 uniqueness of linux, phandle properties, validity of strings, etc...
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
1171 Strings support common escape sequences from C: "\n", "\t", "\r",
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
1204 re-flattens the tree when booting the kernel. The former is a bit
1212 - An example of code for iterating nodes & retrieving properties
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 ---------------------------------
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
1249 memory-mapped register file.
1261 ----------------------------------------------------------
1272 VII - Specifying interrupt information for devices
1285 <http://www.devicetree.org/open-firmware/practice/>
1288 ----------------------
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
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 --------------------------------
1337 0 = low to high edge sensitive type enabled
1338 1 = active low level sensitive type enabled
1339 2 = active high level sensitive type enabled
1340 3 = high to low edge sensitive type enabled
1343 ----------------------------
1353 0 = active low level sensitive type enabled
1354 1 = active high level sensitive type enabled
1355 2 = high to low edge sensitive type enabled
1356 3 = low to high edge sensitive type enabled
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
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
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";