1204431SrajDevice Tree Source Format (version 1) 2204431Sraj===================================== 3204431Sraj 4204431SrajThe Device Tree Source (DTS) format is a textual representation of a 5204431Srajdevice tree in a form that can be processed by dtc into a binary 6204431Srajdevice tree in the form expected by the kernel. The description below 7204431Srajis not a formal syntax definition of DTS, but describes the basic 8204431Srajconstructs used to represent device trees. 9204431Sraj 10204431SrajNode and property definitions 11204431Sraj----------------------------- 12204431Sraj 13204431SrajDevice tree nodes are defined with a node name and unit address with 14204431Srajbraces marking the start and end of the node definition. They may be 15204431Srajpreceded by a label. 16204431Sraj 17204431Sraj [label:] node-name[@unit-address] { 18204431Sraj [properties definitions] 19204431Sraj [child nodes] 20204431Sraj } 21204431Sraj 22204431SrajNodes may contain property definitions and/or child node 23204431Srajdefinitions. If both are present, properties must come before child 24204431Srajnodes. 25204431Sraj 26204431SrajProperty definitions are name value pairs in the form: 27204431Sraj [label:] property-name = value; 28204431Srajexcept for properties with empty (zero length) value which have the 29204431Srajform: 30204431Sraj [label:] property-name; 31204431Sraj 32238742SimpProperty values may be defined as an array of 8, 16, 32, or 64-bit integer 33238742Simpelements, as NUL-terminated strings, as bytestrings or a combination of these. 34204431Sraj 35238742Simp* Arrays are represented by angle brackets surrounding a space separated list 36238742Simp of C-style integers or character literals. Array elements default to 32-bits 37238742Simp in size. An array of 32-bit elements is also known as a cell list or a list 38238742Simp of cells. A cell being an unsigned 32-bit integer. 39204431Sraj 40204431Sraj e.g. interrupts = <17 0xc>; 41204431Sraj 42238742Simp* A 64-bit value can be represented with two 32-bit elements. 43204431Sraj 44204431Sraj e.g. clock-frequency = <0x00000001 0x00000000>; 45204431Sraj 46238742Simp* The storage size of an element can be changed using the /bits/ prefix. The 47238742Simp /bits/ prefix allows for the creation of 8, 16, 32, and 64-bit elements. 48238742Simp The resulting array will not be padded to a multiple of the default 32-bit 49238742Simp element size. 50238742Simp 51238742Simp e.g. interrupts = /bits/ 8 <17 0xc>; 52238742Simp e.g. clock-frequency = /bits/ 64 <0x0000000100000000>; 53238742Simp 54204431Sraj* A NUL-terminated string value is represented using double quotes 55204431Sraj (the property value is considered to include the terminating NUL 56204431Sraj character). 57204431Sraj 58204431Sraj e.g. compatible = "simple-bus"; 59204431Sraj 60204431Sraj* A bytestring is enclosed in square brackets [] with each byte 61204431Sraj represented by two hexadecimal digits. Spaces between each byte are 62204431Sraj optional. 63204431Sraj 64204431Sraj e.g. local-mac-address = [00 00 12 34 56 78]; or equivalently 65204431Sraj local-mac-address = [000012345678]; 66204431Sraj 67204431Sraj* Values may have several comma-separated components, which are 68204431Sraj concatenated together. 69204431Sraj e.g. compatible = "ns16550", "ns8250"; 70204431Sraj example = <0xf00f0000 19>, "a strange property format"; 71204431Sraj 72238742Simp* In an array a reference to another node will be expanded to that node's 73238742Simp phandle. References may by '&' followed by a node's label: 74204431Sraj e.g. interrupt-parent = < &mpic >; 75204431Sraj or they may be '&' followed by a node's full path in braces: 76204431Sraj e.g. interrupt-parent = < &{/soc/interrupt-controller@40000} >; 77238742Simp References are only permitted in arrays that have an element size of 78238742Simp 32-bits. 79204431Sraj 80238742Simp* Outside an array, a reference to another node will be expanded to that 81238742Simp node's full path. 82204431Sraj e.g. ethernet0 = &EMAC0; 83204431Sraj 84204431Sraj* Labels may also appear before or after any component of a property 85238742Simp value, or between elements of an array, or between bytes of a bytestring. 86204431Sraj e.g. reg = reglabel: <0 sizelabel: 0x1000000>; 87204431Sraj e.g. prop = [ab cd ef byte4: 00 ff fe]; 88204431Sraj e.g. str = start: "string value" end: ; 89204431Sraj 90204431Sraj 91204431SrajFile layout 92204431Sraj----------- 93204431Sraj 94204431SrajVersion 1 DTS files have the overall layout: 95204431Sraj /dts-v1/; 96204431Sraj 97204431Sraj [memory reservations] 98204431Sraj 99204431Sraj / { 100204431Sraj [property definitions] 101204431Sraj [child nodes] 102204431Sraj }; 103204431Sraj 104204431Sraj* The "/dts-v1/;" must be present to identify the file as a version 1 105204431Sraj DTS (dts files without this tag will be treated by dtc as being in 106204431Sraj the obsolete "version 0", which uses a different format for integers 107204431Sraj amongst other small but incompatible changes). 108204431Sraj 109204431Sraj* Memory reservations define an entry for the device tree blob's 110204431Sraj memory reservation table. They have the form: 111204431Sraj e.g. /memreserve/ <address> <length>; 112204431Sraj Where <address> and <length> are 64-bit C-style integers. 113204431Sraj 114204431Sraj* The / { ... }; section defines the root node of the device tree. 115204431Sraj 116204431Sraj* C style (/* ... */) and C++ style (// ...) comments are supported. 117204431Sraj 118204431Sraj 119204431Sraj 120204431Sraj -- David Gibson <david@gibson.dropbear.id.au> 121204431Sraj -- Yoder Stuart <stuart.yoder@freescale.com> 122238742Simp -- Anton Staaf <robotboy@chromium.org> 123