Lines Matching +full:container +full:- +full:rules
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
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
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
81 June 1, 2005: Rev 0.4 - Correct confusion between OF_DT_END and
83 - Change version 16 format to always align
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
122 IBM pSeries/iSeries pair, it was decided to enforce some strict rules
123 regarding the kernel entry and bootloader <-> kernel interfaces, in
126 legacy iSeries platform breaks those rules as it predates this scheme,
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
131 required to use these rules as well.
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 ---------
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
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
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
529 which isn't only a virtual "container" for more nodes, like "/cpus"
544 The "phandle" property is a 32-bit value that uniquely
550 Here is an example of a simple device-tree. In this example, an "o"
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
603 significance of the #address-cells and #size-cells properties will be
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
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
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.
752 -------------------------------------
762 -------------------------------
783 -------------------------------------------------------
785 While Open Firmware provides more flexible usage of 8859-1, this
786 specification enforces more strict rules. Nodes and properties should
788 '9', ',', '.', '_', '+', '#', '?', and '-'. Node names additionally
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,
834 #address-cells = <00000001>
835 #size-cells = <00000000>
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
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
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.
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,
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
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
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
1089 * numerical 32-bit value (hexadecimal)
1094 * numerical 32-bit values (cells) in
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 ---------------------------------
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
1194 memory-mapped register file.
1206 ----------------------------------------------------------
1217 VII - Specifying interrupt information for devices
1233 ----------------------
1247 its #interrupt-cells property the number of 32-bit cells
1252 specifies an #interrupt-cells value of 2 to encode the interrupt
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
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
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";