Lines Matching +full:string +full:- +full:array +full:- +full:property
2 --------------------------------------------------
7 Freescale Semiconductor, FSL SOC and 32-bit additions
14 I - Introduction
19 II - The DT block format
25 III - Required content of the device tree
29 4) Note about node and property names and character set
38 IV - "dtc", the device tree compiler
40 V - Recommendations for a bootloader
42 VI - System-on-a-chip devices and nodes
46 VII - Specifying interrupt information for devices
47 1) interrupts property
48 2) interrupt-parent property
52 VIII - Specifying device power management information (sleep property)
54 Appendix A - Sample SOC node for MPC8540
60 May 18, 2005: Rev 0.1 - Initial draft, no chapter III yet.
62 May 19, 2005: Rev 0.2 - Add chapter III and bits & pieces here or
68 May 24, 2005: Rev 0.3 - Precise that DT block has to be in RAM
69 - Misc fixes
70 - Define version 3 and new format version 16
73 String block now has a size, and full path
78 "name" property is now automatically
81 June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and
83 - Change version 16 format to always align
84 property data to 4 bytes. Since tokens are
86 required alignment between property size
87 and property data. The old style variable
92 - Correct a few more alignment constraints
93 - Add a chapter about the device-tree
98 - Additions/generalizations for 32-bit
99 - Changed to reflect the new arch/powerpc
101 - Added chapter VI
105 - Add some definitions of interrupt tree (simple/complex)
106 - Add some definitions for PCI host bridges
107 - Add some common address format examples
108 - Add definitions for standard properties and "compatible"
111 - Compare FSL SOC use of PCI to standard and make sure no new
113 - Add more information about node definitions for SOC devices
117 I - Introduction
123 regarding the kernel entry and bootloader <-> kernel interfaces, in
129 arch/powerpc merged architecture for ppc32 and ppc64, new 32-bit
130 platforms and 32-bit platforms which move into arch/powerpc will be
134 the presence of a device-tree whose format is defined after Open
136 to embedded board vendors, the kernel doesn't require the device-tree
153 ---------------------------
170 b) Entry with a flattened device-tree block. Firmware loads the
181 r2 : physical pointer to the device-tree block
192 -------------------------------
204 bindings to powerpc. Only the 32-bit client interface
211 extract the device-tree and other information from open
212 firmware and build a flattened device-tree as described
213 in b). prom_init() will then re-enter the kernel using
218 b) Direct entry with a flattened device-tree block. This entry
229 r3 : physical pointer to the device-tree block
235 and a non-1:1 mapping.
249 given platform based on the content of the device-tree. Thus, you
270 -------------------------------
277 The physical pointer to the device-tree block (defined in chapter II)
283 This device-tree is used as an extension to the "boot page". As such it
289 II - The DT block format
293 This chapter defines the actual format of the flattened device-tree
297 which will generate a flattened device-tree from the Open Firmware
310 ---------
344 #define OF_DT_PROP 0x3 /* Property: name off,
353 - magic
356 device-tree block header. It contains the value 0xd00dfeed and is
359 - totalsize
364 the device-tree structure, strings, and the memory reserve map.
366 - off_dt_struct
371 - off_dt_strings
374 of the "strings" part of the device-tree
376 - off_mem_rsvmap
379 of the reserved memory map. This map is a list of pairs of 64-
385 boot for things like un-flattening the device-tree, allocating an
393 should be 64-bit aligned.
395 - version
411 - last_comp_version
421 - boot_cpuid_phys
426 should match the content of the "reg" property of the CPU node in
427 the device-tree corresponding to the CPU calling the kernel entry
429 device-tree contents)
431 - size_dt_strings
437 - size_dt_struct
448 ------------------------------
449 base -> | struct boot_param_header |
450 ------------------------------
452 ------------------------------
454 ------------------------------
456 ------------------------------
458 | device-tree structure |
460 ------------------------------
462 ------------------------------
464 | device-tree strings |
466 -----> ------------------------------
469 --- (base + totalsize)
477 ---------------------------
479 This device-tree itself is separated in two different blocks, a
483 First, let's quickly describe the device-tree concept before detailing
488 The device-tree layout is strongly inherited from the definition of
489 the Open Firmware IEEE 1275 device-tree. It's basically a tree of
490 nodes, each node having two or more named properties. A property can
497 property of type "name" in the node property list whose value is a
498 zero terminated string and is mandatory for version 1 to 3 of the
507 The unit name doesn't exist as a property per-se but is included in
508 the device-tree structure. It is typically used to represent "path" in
509 the device-tree. More details about the actual format of these will be
523 a name property either if you are using version 3 or earlier of the
525 address). The root node unit name is thus an empty string. The full
530 is) is also required to have a "compatible" property indicating the
534 Finally, every node that can be referenced from a property in another
536 property. Real Open Firmware implementations provide a unique
544 The "phandle" property is a 32-bit value that uniquely
547 requirement is that every node for which you provide that property has
550 Here is an example of a simple device-tree. In this example, an "o"
553 represents an ASCII string (zero terminated) value, while <content>
554 represents a 32-bit hexadecimal value. The various nodes in this
556 only meant to give you a idea of what a device-tree looks like. I have
561 / o device-tree
562 |- name = "device-tree"
563 |- model = "MyBoardName"
564 |- compatible = "MyBoardFamilyName"
565 |- #address-cells = <2>
566 |- #size-cells = <2>
567 |- linux,phandle = <0>
570 | | - name = "cpus"
571 | | - linux,phandle = <1>
572 | | - #address-cells = <1>
573 | | - #size-cells = <0>
576 | |- name = "PowerPC,970"
577 | |- device_type = "cpu"
578 | |- reg = <0>
579 | |- clock-frequency = <5f5e1000>
580 | |- 64-bit
581 | |- linux,phandle = <2>
584 | |- name = "memory"
585 | |- device_type = "memory"
586 | |- reg = <00000000 00000000 00000000 20000000>
587 | |- linux,phandle = <3>
590 |- name = "chosen"
591 |- bootargs = "root=/dev/sda2"
592 |- linux,phandle = <4>
601 The /cpus/PowerPC,970@0/64-bit property is an example of a
602 property without a value. All other properties have a value. The
603 significance of the #address-cells and #size-cells properties will be
620 terminated string, starting with "/". For version 16 and later,
621 this is the node unit name only (or an empty string for the
624 * for each property:
626 * 32-bit value of property value size in bytes (or 0 if no
628 * 32-bit value of offset in string block of property name
629 * property value data if any
638 NOTE: The above definition requires that all property definitions for
648 In order to save space, property names, which are generally redundant,
650 whole bunch of zero terminated strings for all property names
651 concatenated together. The device-tree property definitions in the
656 III - Required content of the device tree
660 to a flattened device-tree. If your platform uses a real
665 set the platform number. However, when using the flattened device-tree
671 ----------------------------------------------
674 documentations. If you choose to describe a bus with the device-tree
680 parent bus type, based on the #address-cells and #size-cells
681 properties. Note that the parent's parent definitions of #address-cells
682 and #size-cells are not inherited so every node with children must specify
687 size. A "cell" is a 32-bit number. For example, if both contain 2
689 composed of 2 cells, and each is a 64-bit number (cells are
692 and one cell for a size. Most 32-bit implementations should define
693 #address-cells and #size-cells to 1, which represents a 32-bit value.
694 Some 32-bit processors allow for physical addresses greater than 32
695 bits; these processors should define #address-cells as 2.
699 #address-cells and #size-cells. When a bus supports various address
710 then, to provide a separate "assigned-addresses" property that
721 The "reg" property only defines addresses and sizes (if #size-cells is
722 non-0) within a given bus. In order to translate addresses upward
724 addresses), all buses must contain a "ranges" property. If the
725 "ranges" property is missing at a given level, it's assumed that
727 parent bus. The format of the "ranges" property for a bus is a list
737 PCI<->ISA bridge, that would be a PCI address. It defines the base
740 For new 64-bit board support, I recommend either the 2/2 format or
742 fit in a single 32-bit word. New 32-bit board support should use a
744 than 32-bits, in which case a 2/1 format is recommended.
746 Alternatively, the "ranges" property may be empty, indicating that the
752 -------------------------------------
755 node. The format of a "compatible" property is a list of concatenated
762 -------------------------------
765 to use the actual device name for the "name" property, it's nowadays
768 controllers are named "ethernet", an additional "model" property
769 defining precisely the chip type/model, and "compatible" property
772 restriction on the "name" property; it is simply considered good
776 Note also that the new format version 16 makes the "name" property
782 4) Note about node and property names and character set
783 -------------------------------------------------------
785 While Open Firmware provides more flexible usage of 8859-1, this
788 '9', ',', '.', '_', '+', '#', '?', and '-'. Node names additionally
789 allow uppercase characters 'A' to 'Z' (property names should be
791 irrelevant here). Additionally, node and property names should always
795 The maximum number of characters for both nodes and property names
797 a unit name (the pure "name" property), it doesn't include the unit
802 --------------------------------
812 - model : this is your board name/model
813 - #address-cells : address representation for "root" devices
814 - #size-cells: the size representation for "root" devices
815 - compatible : the board "family" generally finds its way here,
819 compatible property followed by an entry that represents the SoC
824 thing. It is recommended that if you add any "custom" property whose
834 #address-cells = <00000001>
835 #size-cells = <00000000>
850 property to identify the specific cpu core.
854 - device_type : has to be "cpu"
855 - reg : This is the physical CPU number, it's a single 32-bit cell
856 and is also used as-is as the unit number for constructing the
862 - d-cache-block-size : one cell, L1 data cache block size in bytes (*)
863 - i-cache-block-size : one cell, L1 instruction cache block size in
865 - d-cache-size : one cell, size of L1 data cache in bytes
866 - i-cache-size : one cell, size of L1 instruction cache in bytes
876 - timebase-frequency : a cell indicating the frequency of the
881 - clock-frequency : a cell indicating the CPU core clock frequency
882 in Hz. A new property will be defined for 64-bit values, but if
884 for the above, the common code doesn't use that property, but
885 you are welcome to re-use the pSeries or Maple one. A future
887 - d-cache-line-size : one cell, L1 data cache line size in bytes
889 - i-cache-line-size : one cell, L1 instruction cache line size in
892 You are welcome to add any property you find relevant to your board,
893 like some information about the mechanism used to soft-reset the
895 lines in there as a "soft-reset" property since they start secondary
896 CPUs by soft-resetting them.
903 node with all memory ranges in its reg property, or you can create
911 - device_type : has to be "memory"
912 - reg : This property contains all the physical memory ranges of
915 #address-cells and #size-cells of the root node. For example,
918 have a "reg" property here that looks like:
936 some linux-specific properties that would be normally constructed by
942 - bootargs : This zero-terminated string is passed as the kernel
944 - linux,stdout-path : This is the full path to your standard
950 Note that u-boot creates and fills in the chosen node for platforms
953 (Note: a practice that is now obsolete was to include a property
954 under /chosen called interrupt-controller which had a phandle value
959 This node is used to represent a system-on-a-chip (SoC) and must be
960 present if the processor is a SoC. The top-level soc node contains
963 of the memory-mapped register set for the SoC. The name of an SoC
970 - ranges : Should be defined as specified in 1) to describe the
972 - bus-frequency: Contains the bus frequency for the SoC node.
975 - compatible : Exact model of the SoC
980 - reg : This property defines the address and size of the
981 memory-mapped registers that are used for the SOC node itself.
982 It does not include the child device registers - these will be
984 "reg" property should match the unit address of the SOC node.
985 - #address-cells : Address representation for "soc" devices. The
992 See 1) above for more details on defining #address-cells.
993 - #size-cells : Size representation for "soc" devices
994 - #interrupt-cells : Defines the width of cells used to represent
996 32-bit number that represents the interrupt number, and a
997 32-bit number that represents the interrupt sense and level.
1009 #address-cells = <1>;
1010 #size-cells = <1>;
1011 #interrupt-cells = <2>;
1015 bus-frequency = <0>;
1020 IV - "dtc", the device tree compiler
1028 resulting device-tree "blobs" have not yet been validated with the
1034 dtc basically takes a device-tree in a given format and outputs a
1035 device-tree in another format. The currently supported formats are:
1038 -------------
1040 - "dtb": "blob" format, that is a flattened device-tree block
1043 - "dts": "source" format. This is a text file containing a
1044 "source" for a device-tree. The format is defined later in this
1046 - "fs" format. This is a representation equivalent to the
1047 output of /proc/device-tree, that is nodes are directories and
1051 ---------------
1053 - "dtb": "blob" format
1054 - "dts": "source" format
1055 - "asm": assembly language file. This is a file that can be
1056 sourced by gas to generate a device-tree "blob". That file can
1063 dtc [-I <input-format>] [-O <output-format>]
1064 [-o output-filename] [-V output_version] input_filename
1080 The above is the "device-tree" definition. It's the only statement
1084 property1 = "string_value"; /* define a property containing a 0
1085 * terminated string
1088 property2 = <1234abcd>; /* define a property containing a
1089 * numerical 32-bit value (hexadecimal)
1093 /* define a property containing 3
1094 * numerical 32-bit values (cells) in
1098 /* define a property whose content is
1099 * an arbitrary array of bytes
1107 childprop = "hello\n"; /* define a property "childprop" of
1108 * childnode (in this case, a string)
1124 you can point to a property content and change it easily from whatever
1125 you link the device-tree with), label or path instead of numeric value
1136 V - Recommendations for a bootloader
1143 - The bootloader may want to be able to use the device-tree itself
1149 re-flattens the tree when booting the kernel. The former is a bit
1157 - An example of code for iterating nodes & retrieving properties
1161 early_init_dt_scan_*() callbacks. That code can be re-used in a
1164 integrate all or part of this code into a non-GPL bootloader.
1165 (reference needed; who is 'I' here? ---gcl Jan 31, 2011)
1169 VI - System-on-a-chip devices and nodes
1172 Many companies are now starting to develop system-on-a-chip
1178 implementations define as complete a flat-device-tree as possible to
1184 ---------------------------------
1188 address property represents the address offset for this device's
1189 memory-mapped registers in the parent's address space. The parent's
1190 address space is defined by the "ranges" property in the top-level soc
1191 node. The "reg" property for each node that exists directly under the
1194 memory-mapped register file.
1206 ----------------------------------------------------------
1217 VII - Specifying interrupt information for devices
1232 1) interrupts property
1233 ----------------------
1240 property. The interrupt property value is an arbitrary number of
1247 its #interrupt-cells property the number of 32-bit cells
1252 specifies an #interrupt-cells value of 2 to encode the interrupt
1255 property.
1257 The PCI bus binding specifies a #interrupt-cell value of 1 to encode
1260 2) interrupt-parent property
1261 ----------------------------
1263 The interrupt-parent property is specified to define an explicit
1265 the interrupt tree. The value of interrupt-parent is the
1268 If the interrupt-parent property is not defined for a node, its
1273 --------------------------------
1288 ----------------------------
1303 VIII - Specifying Device Power Management Information (sleep property)
1306 Devices on SOCs often have mechanisms for placing devices into low-power
1308 this information is more complicated than a cell-index property can
1310 may contain a "sleep" property which describes these connections.
1312 The sleep property consists of one or more sleep resources, each of
1314 controller-specific sleep specifier of zero or more cells.
1320 - Dynamic: The device may be disabled or enabled at any time.
1321 - System Suspend: The device may request to be disabled or remain
1323 - Permanent: The device is disabled permanently (until the next hard
1329 property. If the clock domain is shared among devices that cannot be
1332 sleep-map should wait until its necessity is demonstrated).
1334 Appendix A - Sample SOC node for MPC8540
1338 #address-cells = <1>;
1339 #size-cells = <1>;
1340 compatible = "fsl,mpc8540-ccsr", "simple-bus";
1343 bus-frequency = <0>;
1344 interrupt-parent = <&pic>;
1347 #address-cells = <1>;
1348 #size-cells = <1>;
1351 compatible = "gianfar", "simple-bus";
1353 local-mac-address = [ 00 E0 0C 00 73 00 ];
1355 phy-handle = <&phy0>;
1361 compatible = "fsl,gianfar-mdio";
1363 phy0: ethernet-phy@0 {
1366 device_type = "ethernet-phy";
1369 phy1: ethernet-phy@1 {
1372 device_type = "ethernet-phy";
1375 phy3: ethernet-phy@3 {
1378 device_type = "ethernet-phy";
1388 local-mac-address = [ 00 E0 0C 00 73 01 ];
1390 phy-handle = <&phy1>;
1399 local-mac-address = [ 00 E0 0C 00 73 02 ];
1401 phy-handle = <&phy3>;
1406 #address-cells = <1>;
1407 #size-cells = <1>;
1408 compatible = "fsl,mpc8540-duart", "simple-bus";
1416 clock-frequency = <0>;
1424 clock-frequency = <0>;
1430 interrupt-controller;
1431 #address-cells = <0>;
1432 #interrupt-cells = <2>;
1434 compatible = "chrp,open-pic";
1435 device_type = "open-pic";
1441 compatible = "fsl-i2c";
1447 compatible = "fsl,mpc8540-pmc", "fsl,mpc8548-pmc";