Date: Mon, 27 Jan 2014 06:31:37 +0000 (UTC) From: Warner Losh <imp@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-vendor@freebsd.org Subject: svn commit: r261204 - in vendor/dtc/dtc-6a15eb23: . Documentation libfdt tests Message-ID: <201401270631.s0R6Vb6s056713@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: imp Date: Mon Jan 27 06:31:37 2014 New Revision: 261204 URL: http://svnweb.freebsd.org/changeset/base/261204 Log: Copy dtc post 6a15eb2350426d285130e4c9d84c0bdb6575547a import Added: vendor/dtc/dtc-6a15eb23/ - copied from r261201, vendor/dtc/dist/ vendor/dtc/dtc-6a15eb23/tests/delete_reinstate_multilabel.dts - copied unchanged from r261203, vendor/dtc/dist/tests/delete_reinstate_multilabel.dts vendor/dtc/dtc-6a15eb23/tests/delete_reinstate_multilabel_ref.dts - copied unchanged from r261203, vendor/dtc/dist/tests/delete_reinstate_multilabel_ref.dts vendor/dtc/dtc-6a15eb23/tests/line_directives.dts - copied unchanged from r261203, vendor/dtc/dist/tests/line_directives.dts vendor/dtc/dtc-6a15eb23/tests/propname_escapes.c - copied unchanged from r261203, vendor/dtc/dist/tests/propname_escapes.c vendor/dtc/dtc-6a15eb23/tests/propname_escapes.dts - copied unchanged from r261203, vendor/dtc/dist/tests/propname_escapes.dts vendor/dtc/dtc-6a15eb23/tests/subnode_iterate.c - copied unchanged from r261203, vendor/dtc/dist/tests/subnode_iterate.c vendor/dtc/dtc-6a15eb23/tests/subnode_iterate.dts - copied unchanged from r261203, vendor/dtc/dist/tests/subnode_iterate.dts vendor/dtc/dtc-6a15eb23/tests/sw_tree1.supp - copied unchanged from r261203, vendor/dtc/dist/tests/sw_tree1.supp vendor/dtc/dtc-6a15eb23/tests/test_tree1_body.dtsi - copied unchanged from r261203, vendor/dtc/dist/tests/test_tree1_body.dtsi vendor/dtc/dtc-6a15eb23/tests/test_tree1_delete.dts - copied unchanged from r261203, vendor/dtc/dist/tests/test_tree1_delete.dts Replaced: vendor/dtc/dtc-6a15eb23/Documentation/manual.txt - copied unchanged from r261202, vendor/dtc/dist/Documentation/manual.txt vendor/dtc/dtc-6a15eb23/Makefile - copied unchanged from r261202, vendor/dtc/dist/Makefile vendor/dtc/dtc-6a15eb23/checks.c - copied unchanged from r261202, vendor/dtc/dist/checks.c vendor/dtc/dtc-6a15eb23/convert-dtsv0-lexer.l - copied unchanged from r261202, vendor/dtc/dist/convert-dtsv0-lexer.l vendor/dtc/dtc-6a15eb23/data.c - copied unchanged from r261202, vendor/dtc/dist/data.c vendor/dtc/dtc-6a15eb23/dtc-lexer.l - copied unchanged from r261202, vendor/dtc/dist/dtc-lexer.l vendor/dtc/dtc-6a15eb23/dtc-parser.y - copied unchanged from r261202, vendor/dtc/dist/dtc-parser.y vendor/dtc/dtc-6a15eb23/dtc.c - copied unchanged from r261202, vendor/dtc/dist/dtc.c vendor/dtc/dtc-6a15eb23/dtc.h - copied unchanged from r261202, vendor/dtc/dist/dtc.h vendor/dtc/dtc-6a15eb23/fdtdump.c - copied unchanged from r261202, vendor/dtc/dist/fdtdump.c vendor/dtc/dtc-6a15eb23/fdtget.c - copied unchanged from r261202, vendor/dtc/dist/fdtget.c vendor/dtc/dtc-6a15eb23/fdtput.c - copied unchanged from r261202, vendor/dtc/dist/fdtput.c vendor/dtc/dtc-6a15eb23/flattree.c - copied unchanged from r261202, vendor/dtc/dist/flattree.c vendor/dtc/dtc-6a15eb23/libfdt/Makefile.libfdt - copied unchanged from r261202, vendor/dtc/dist/libfdt/Makefile.libfdt vendor/dtc/dtc-6a15eb23/libfdt/fdt.c - copied unchanged from r261202, vendor/dtc/dist/libfdt/fdt.c vendor/dtc/dtc-6a15eb23/libfdt/fdt.h - copied unchanged from r261202, vendor/dtc/dist/libfdt/fdt.h vendor/dtc/dtc-6a15eb23/libfdt/fdt_ro.c - copied unchanged from r261202, vendor/dtc/dist/libfdt/fdt_ro.c vendor/dtc/dtc-6a15eb23/libfdt/fdt_rw.c - copied unchanged from r261202, vendor/dtc/dist/libfdt/fdt_rw.c vendor/dtc/dtc-6a15eb23/libfdt/fdt_sw.c - copied unchanged from r261202, vendor/dtc/dist/libfdt/fdt_sw.c vendor/dtc/dtc-6a15eb23/libfdt/fdt_wip.c - copied unchanged from r261202, vendor/dtc/dist/libfdt/fdt_wip.c vendor/dtc/dtc-6a15eb23/libfdt/libfdt.h - copied unchanged from r261202, vendor/dtc/dist/libfdt/libfdt.h vendor/dtc/dtc-6a15eb23/libfdt/libfdt_env.h - copied unchanged from r261202, vendor/dtc/dist/libfdt/libfdt_env.h vendor/dtc/dtc-6a15eb23/libfdt/version.lds - copied unchanged from r261202, vendor/dtc/dist/libfdt/version.lds vendor/dtc/dtc-6a15eb23/livetree.c - copied unchanged from r261202, vendor/dtc/dist/livetree.c vendor/dtc/dtc-6a15eb23/srcpos.c - copied unchanged from r261202, vendor/dtc/dist/srcpos.c vendor/dtc/dtc-6a15eb23/srcpos.h - copied unchanged from r261202, vendor/dtc/dist/srcpos.h vendor/dtc/dtc-6a15eb23/tests/Makefile.tests - copied unchanged from r261202, vendor/dtc/dist/tests/Makefile.tests vendor/dtc/dtc-6a15eb23/tests/add_subnode_with_nops.c - copied unchanged from r261202, vendor/dtc/dist/tests/add_subnode_with_nops.c vendor/dtc/dtc-6a15eb23/tests/aliases.dts - copied unchanged from r261202, vendor/dtc/dist/tests/aliases.dts vendor/dtc/dtc-6a15eb23/tests/appendprop1.c - copied unchanged from r261202, vendor/dtc/dist/tests/appendprop1.c vendor/dtc/dtc-6a15eb23/tests/appendprop2.c - copied unchanged from r261202, vendor/dtc/dist/tests/appendprop2.c vendor/dtc/dtc-6a15eb23/tests/asm_tree_dump.c - copied unchanged from r261202, vendor/dtc/dist/tests/asm_tree_dump.c vendor/dtc/dtc-6a15eb23/tests/boot-cpuid.c - copied unchanged from r261202, vendor/dtc/dist/tests/boot-cpuid.c vendor/dtc/dtc-6a15eb23/tests/char_literal.c - copied unchanged from r261202, vendor/dtc/dist/tests/char_literal.c vendor/dtc/dtc-6a15eb23/tests/del_node.c - copied unchanged from r261202, vendor/dtc/dist/tests/del_node.c vendor/dtc/dtc-6a15eb23/tests/del_property.c - copied unchanged from r261202, vendor/dtc/dist/tests/del_property.c vendor/dtc/dtc-6a15eb23/tests/dtb_reverse.c - copied unchanged from r261202, vendor/dtc/dist/tests/dtb_reverse.c vendor/dtc/dtc-6a15eb23/tests/dtbs_equal_ordered.c - copied unchanged from r261202, vendor/dtc/dist/tests/dtbs_equal_ordered.c vendor/dtc/dtc-6a15eb23/tests/dtbs_equal_unordered.c - copied unchanged from r261202, vendor/dtc/dist/tests/dtbs_equal_unordered.c vendor/dtc/dtc-6a15eb23/tests/dumptrees.c - copied unchanged from r261202, vendor/dtc/dist/tests/dumptrees.c vendor/dtc/dtc-6a15eb23/tests/extra-terminating-null.c - copied unchanged from r261202, vendor/dtc/dist/tests/extra-terminating-null.c vendor/dtc/dtc-6a15eb23/tests/fdtget-runtest.sh - copied unchanged from r261202, vendor/dtc/dist/tests/fdtget-runtest.sh vendor/dtc/dtc-6a15eb23/tests/find_property.c - copied unchanged from r261202, vendor/dtc/dist/tests/find_property.c vendor/dtc/dtc-6a15eb23/tests/get_alias.c - copied unchanged from r261202, vendor/dtc/dist/tests/get_alias.c vendor/dtc/dtc-6a15eb23/tests/get_mem_rsv.c - copied unchanged from r261202, vendor/dtc/dist/tests/get_mem_rsv.c vendor/dtc/dtc-6a15eb23/tests/get_name.c - copied unchanged from r261202, vendor/dtc/dist/tests/get_name.c vendor/dtc/dtc-6a15eb23/tests/get_path.c - copied unchanged from r261202, vendor/dtc/dist/tests/get_path.c vendor/dtc/dtc-6a15eb23/tests/get_phandle.c - copied unchanged from r261202, vendor/dtc/dist/tests/get_phandle.c vendor/dtc/dtc-6a15eb23/tests/getprop.c - copied unchanged from r261202, vendor/dtc/dist/tests/getprop.c vendor/dtc/dtc-6a15eb23/tests/incbin.c - copied unchanged from r261202, vendor/dtc/dist/tests/incbin.c vendor/dtc/dtc-6a15eb23/tests/include1.dts - copied unchanged from r261202, vendor/dtc/dist/tests/include1.dts vendor/dtc/dtc-6a15eb23/tests/include7.dts - copied unchanged from r261202, vendor/dtc/dist/tests/include7.dts vendor/dtc/dtc-6a15eb23/tests/include8.dts - copied unchanged from r261202, vendor/dtc/dist/tests/include8.dts vendor/dtc/dtc-6a15eb23/tests/integer-expressions.c - copied unchanged from r261202, vendor/dtc/dist/tests/integer-expressions.c vendor/dtc/dtc-6a15eb23/tests/mangle-layout.c - copied unchanged from r261202, vendor/dtc/dist/tests/mangle-layout.c vendor/dtc/dtc-6a15eb23/tests/move_and_save.c - copied unchanged from r261202, vendor/dtc/dist/tests/move_and_save.c vendor/dtc/dtc-6a15eb23/tests/node_check_compatible.c - copied unchanged from r261202, vendor/dtc/dist/tests/node_check_compatible.c vendor/dtc/dtc-6a15eb23/tests/node_offset_by_compatible.c - copied unchanged from r261202, vendor/dtc/dist/tests/node_offset_by_compatible.c vendor/dtc/dtc-6a15eb23/tests/node_offset_by_phandle.c - copied unchanged from r261202, vendor/dtc/dist/tests/node_offset_by_phandle.c vendor/dtc/dtc-6a15eb23/tests/node_offset_by_prop_value.c - copied unchanged from r261202, vendor/dtc/dist/tests/node_offset_by_prop_value.c vendor/dtc/dtc-6a15eb23/tests/nop_node.c - copied unchanged from r261202, vendor/dtc/dist/tests/nop_node.c vendor/dtc/dtc-6a15eb23/tests/nop_property.c - copied unchanged from r261202, vendor/dtc/dist/tests/nop_property.c vendor/dtc/dtc-6a15eb23/tests/nopulate.c - copied unchanged from r261202, vendor/dtc/dist/tests/nopulate.c vendor/dtc/dtc-6a15eb23/tests/notfound.c - copied unchanged from r261202, vendor/dtc/dist/tests/notfound.c vendor/dtc/dtc-6a15eb23/tests/open_pack.c - copied unchanged from r261202, vendor/dtc/dist/tests/open_pack.c vendor/dtc/dtc-6a15eb23/tests/parent_offset.c - copied unchanged from r261202, vendor/dtc/dist/tests/parent_offset.c vendor/dtc/dtc-6a15eb23/tests/path-references.c - copied unchanged from r261202, vendor/dtc/dist/tests/path-references.c vendor/dtc/dtc-6a15eb23/tests/path_offset.c - copied unchanged from r261202, vendor/dtc/dist/tests/path_offset.c vendor/dtc/dtc-6a15eb23/tests/path_offset_aliases.c - copied unchanged from r261202, vendor/dtc/dist/tests/path_offset_aliases.c vendor/dtc/dtc-6a15eb23/tests/phandle_format.c - copied unchanged from r261202, vendor/dtc/dist/tests/phandle_format.c vendor/dtc/dtc-6a15eb23/tests/references.c - copied unchanged from r261202, vendor/dtc/dist/tests/references.c vendor/dtc/dtc-6a15eb23/tests/root_node.c - copied unchanged from r261202, vendor/dtc/dist/tests/root_node.c vendor/dtc/dtc-6a15eb23/tests/run_tests.sh - copied unchanged from r261202, vendor/dtc/dist/tests/run_tests.sh vendor/dtc/dtc-6a15eb23/tests/rw_tree1.c - copied unchanged from r261202, vendor/dtc/dist/tests/rw_tree1.c vendor/dtc/dtc-6a15eb23/tests/set_name.c - copied unchanged from r261202, vendor/dtc/dist/tests/set_name.c vendor/dtc/dtc-6a15eb23/tests/setprop.c - copied unchanged from r261202, vendor/dtc/dist/tests/setprop.c vendor/dtc/dtc-6a15eb23/tests/setprop_inplace.c - copied unchanged from r261202, vendor/dtc/dist/tests/setprop_inplace.c vendor/dtc/dtc-6a15eb23/tests/sized_cells.c - copied unchanged from r261202, vendor/dtc/dist/tests/sized_cells.c vendor/dtc/dtc-6a15eb23/tests/string_escapes.c - copied unchanged from r261202, vendor/dtc/dist/tests/string_escapes.c vendor/dtc/dtc-6a15eb23/tests/subnode_offset.c - copied unchanged from r261202, vendor/dtc/dist/tests/subnode_offset.c vendor/dtc/dtc-6a15eb23/tests/supernode_atdepth_offset.c - copied unchanged from r261202, vendor/dtc/dist/tests/supernode_atdepth_offset.c vendor/dtc/dtc-6a15eb23/tests/sw_tree1.c - copied unchanged from r261202, vendor/dtc/dist/tests/sw_tree1.c vendor/dtc/dtc-6a15eb23/tests/test_tree1.dts - copied unchanged from r261202, vendor/dtc/dist/tests/test_tree1.dts vendor/dtc/dtc-6a15eb23/tests/test_tree1_merge.dts - copied unchanged from r261202, vendor/dtc/dist/tests/test_tree1_merge.dts vendor/dtc/dtc-6a15eb23/tests/test_tree1_merge_labelled.dts - copied unchanged from r261202, vendor/dtc/dist/tests/test_tree1_merge_labelled.dts vendor/dtc/dtc-6a15eb23/tests/test_tree1_merge_path.dts - copied unchanged from r261202, vendor/dtc/dist/tests/test_tree1_merge_path.dts vendor/dtc/dtc-6a15eb23/tests/test_tree1_wrong1.dts - copied unchanged from r261202, vendor/dtc/dist/tests/test_tree1_wrong1.dts vendor/dtc/dtc-6a15eb23/tests/test_tree1_wrong2.dts - copied unchanged from r261202, vendor/dtc/dist/tests/test_tree1_wrong2.dts vendor/dtc/dtc-6a15eb23/tests/test_tree1_wrong3.dts - copied unchanged from r261202, vendor/dtc/dist/tests/test_tree1_wrong3.dts vendor/dtc/dtc-6a15eb23/tests/test_tree1_wrong4.dts - copied unchanged from r261202, vendor/dtc/dist/tests/test_tree1_wrong4.dts vendor/dtc/dtc-6a15eb23/tests/test_tree1_wrong5.dts - copied unchanged from r261202, vendor/dtc/dist/tests/test_tree1_wrong5.dts vendor/dtc/dtc-6a15eb23/tests/test_tree1_wrong6.dts - copied unchanged from r261202, vendor/dtc/dist/tests/test_tree1_wrong6.dts vendor/dtc/dtc-6a15eb23/tests/test_tree1_wrong7.dts - copied unchanged from r261202, vendor/dtc/dist/tests/test_tree1_wrong7.dts vendor/dtc/dtc-6a15eb23/tests/test_tree1_wrong8.dts - copied unchanged from r261202, vendor/dtc/dist/tests/test_tree1_wrong8.dts vendor/dtc/dtc-6a15eb23/tests/test_tree1_wrong9.dts - copied unchanged from r261202, vendor/dtc/dist/tests/test_tree1_wrong9.dts vendor/dtc/dtc-6a15eb23/tests/trees.S - copied unchanged from r261202, vendor/dtc/dist/tests/trees.S vendor/dtc/dtc-6a15eb23/tests/truncated_property.c - copied unchanged from r261202, vendor/dtc/dist/tests/truncated_property.c vendor/dtc/dtc-6a15eb23/tests/utilfdt_test.c - copied unchanged from r261202, vendor/dtc/dist/tests/utilfdt_test.c vendor/dtc/dtc-6a15eb23/tests/value-labels.c - copied unchanged from r261202, vendor/dtc/dist/tests/value-labels.c vendor/dtc/dtc-6a15eb23/treesource.c - copied unchanged from r261202, vendor/dtc/dist/treesource.c vendor/dtc/dtc-6a15eb23/util.c - copied unchanged from r261202, vendor/dtc/dist/util.c vendor/dtc/dtc-6a15eb23/util.h - copied unchanged from r261202, vendor/dtc/dist/util.h Copied: vendor/dtc/dtc-6a15eb23/Documentation/manual.txt (from r261202, vendor/dtc/dist/Documentation/manual.txt) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ vendor/dtc/dtc-6a15eb23/Documentation/manual.txt Mon Jan 27 06:31:37 2014 (r261204, copy of r261202, vendor/dtc/dist/Documentation/manual.txt) @@ -0,0 +1,660 @@ +Device Tree Compiler Manual +=========================== + +I - "dtc", the device tree compiler + 1) Obtaining Sources + 1.1) Submitting Patches + 2) Description + 3) Command Line + 4) Source File + 4.1) Overview + 4.2) Properties + 4.3) Labels and References + +II - The DT block format + 1) Header + 2) Device tree generalities + 3) Device tree "structure" block + 4) Device tree "strings" block + + +III - libfdt + +IV - Utility Tools + 1) convert-dtsv0 -- Conversion to Version 1 + 1) fdtdump + + +I - "dtc", the device tree compiler +=================================== + +1) Sources + +Source code for the Device Tree Compiler can be found at jdl.com. +The gitweb interface is: + + http://git.jdl.com/gitweb/ + +The repository is here: + + git://www.jdl.com/software/dtc.git + http://www.jdl.com/software/dtc.git + +Tarballs of the 1.0.0 and latest releases are here: + + http://www.jdl.com/software/dtc-v1.2.0.tgz + http://www.jdl.com/software/dtc-latest.tgz + +1.1) Submitting Patches + +Patches should be sent to jdl@jdl.com, and CC'ed to +devicetree-discuss@lists.ozlabs.org. + +2) Description + +The Device Tree Compiler, dtc, takes as input a device-tree in +a given format and outputs a device-tree in another format. +Typically, the input format is "dts", a human readable source +format, and creates a "dtb", or binary format as output. + +The currently supported Input Formats are: + + - "dtb": "blob" format. A flattened device-tree block with + header in one binary blob. + + - "dts": "source" format. A text file containing a "source" + for a device-tree. + + - "fs" format. A representation equivalent to the output of + /proc/device-tree where nodes are directories and + properties are files. + +The currently supported Output Formats are: + + - "dtb": "blob" format + + - "dts": "source" format + + - "asm": assembly language file. A file that can be sourced + by gas to generate a device-tree "blob". That file can + then simply be added to your Makefile. Additionally, the + assembly file exports some symbols that can be used. + + +3) Command Line + +The syntax of the dtc command line is: + + dtc [options] [<input_filename>] + +Options: + + <input_filename> + The name of the input source file. If no <input_filename> + or "-" is given, stdin is used. + + -b <number> + Set the physical boot cpu. + + -f + Force. Try to produce output even if the input tree has errors. + + -h + Emit a brief usage and help message. + + -I <input_format> + The source input format, as listed above. + + -o <output_filename> + The name of the generated output file. Use "-" for stdout. + + -O <output_format> + The generated output format, as listed above. + + -d <dependency_filename> + Generate a dependency file during compilation. + + -q + Quiet: -q suppress warnings, -qq errors, -qqq all + + -R <number> + Make space for <number> reserve map entries + Relevant for dtb and asm output only. + + -S <bytes> + Ensure the blob at least <bytes> long, adding additional + space if needed. + + -v + Print DTC version and exit. + + -V <output_version> + Generate output conforming to the given <output_version>. + By default the most recent version is generated. + Relevant for dtb and asm output only. + + +The <output_version> defines what version of the "blob" format will be +generated. Supported versions are 1, 2, 3, 16 and 17. The default is +always the most recent version and is likely the highest number. + +Additionally, dtc performs various sanity checks on the tree. + + +4) Device Tree Source file + +4.1) Overview + +Here is a very rough overview of the layout of a DTS source file: + + + sourcefile: list_of_memreserve devicetree + + memreserve: label 'memreserve' ADDR ADDR ';' + | label 'memreserve' ADDR '-' ADDR ';' + + devicetree: '/' nodedef + + nodedef: '{' list_of_property list_of_subnode '}' ';' + + property: label PROPNAME '=' propdata ';' + + propdata: STRING + | '<' list_of_cells '>' + | '[' list_of_bytes ']' + + subnode: label nodename nodedef + +That structure forms a hierarchical layout of nodes and properties +rooted at an initial node as: + + / { + } + +Both classic C style and C++ style comments are supported. + +Source files may be directly included using the syntax: + + /include/ "filename" + + +4.2) Properties + +Properties are named, possibly labeled, values. Each value +is one of: + + - A null-teminated C-like string, + - A numeric value fitting in 32 bits, + - A list of 32-bit values + - A byte sequence + +Here are some example property definitions: + + - A property containing a 0 terminated string + + property1 = "string_value"; + + - A property containing a numerical 32-bit hexadecimal value + + property2 = <1234abcd>; + + - A property containing 3 numerical 32-bit hexadecimal values + + property3 = <12345678 12345678 deadbeef>; + + - A property whose content is an arbitrary array of bytes + + property4 = [0a 0b 0c 0d de ea ad be ef]; + + +Node may contain sub-nodes to obtain a hierarchical structure. +For example: + + - A child node named "childnode" whose unit name is + "childnode at address". It it turn has a string property + called "childprop". + + childnode@addresss { + childprop = "hello\n"; + }; + + +By default, all numeric values are hexadecimal. Alternate bases +may be specified using a prefix "d#" for decimal, "b#" for binary, +and "o#" for octal. + +Strings support common escape sequences from C: "\n", "\t", "\r", +"\(octal value)", "\x(hex value)". + + +4.3) Labels and References + +Labels may be applied to nodes or properties. Labels appear +before a node name, and are referenced using an ampersand: &label. +Absolute node path names are also allowed in node references. + +In this exmaple, a node is labled "mpic" and then referenced: + + mpic: interrupt-controller@40000 { + ... + }; + + ethernet-phy@3 { + interrupt-parent = <&mpic>; + ... + }; + +And used in properties, lables may appear before or after any value: + + randomnode { + prop: string = data: "mystring\n" data_end: ; + ... + }; + + + +II - The DT block format +======================== + +This chapter defines the format of the flattened device-tree +passed to the kernel. The actual content of the device tree +are described in the kernel documentation in the file + + linux-2.6/Documentation/powerpc/booting-without-of.txt + +You can find example of code manipulating that format within +the kernel. For example, the file: + + including arch/powerpc/kernel/prom_init.c + +will generate a flattened device-tree from the Open Firmware +representation. Other utilities such as fs2dt, which is part of +the kexec tools, will generate one from a filesystem representation. +Some bootloaders such as U-Boot provide a bit more support by +using the libfdt code. + +For booting the kernel, the device tree block has to be in main memory. +It has to be accessible in both real mode and virtual mode with no +mapping other than main memory. If you are writing a simple flash +bootloader, it should copy the block to RAM before passing it to +the kernel. + + +1) Header +--------- + +The kernel is entered with r3 pointing to an area of memory that is +roughly described in include/asm-powerpc/prom.h by the structure +boot_param_header: + + struct boot_param_header { + u32 magic; /* magic word OF_DT_HEADER */ + u32 totalsize; /* total size of DT block */ + u32 off_dt_struct; /* offset to structure */ + u32 off_dt_strings; /* offset to strings */ + u32 off_mem_rsvmap; /* offset to memory reserve map */ + u32 version; /* format version */ + u32 last_comp_version; /* last compatible version */ + + /* version 2 fields below */ + u32 boot_cpuid_phys; /* Which physical CPU id we're + booting on */ + /* version 3 fields below */ + u32 size_dt_strings; /* size of the strings block */ + + /* version 17 fields below */ + u32 size_dt_struct; /* size of the DT structure block */ + }; + +Along with the constants: + + /* Definitions used by the flattened device tree */ + #define OF_DT_HEADER 0xd00dfeed /* 4: version, + 4: total size */ + #define OF_DT_BEGIN_NODE 0x1 /* Start node: full name + */ + #define OF_DT_END_NODE 0x2 /* End node */ + #define OF_DT_PROP 0x3 /* Property: name off, + size, content */ + #define OF_DT_END 0x9 + +All values in this header are in big endian format, the various +fields in this header are defined more precisely below. All "offset" +values are in bytes from the start of the header; that is from the +value of r3. + + - magic + + This is a magic value that "marks" the beginning of the + device-tree block header. It contains the value 0xd00dfeed and is + defined by the constant OF_DT_HEADER + + - totalsize + + This is the total size of the DT block including the header. The + "DT" block should enclose all data structures defined in this + chapter (who are pointed to by offsets in this header). That is, + the device-tree structure, strings, and the memory reserve map. + + - off_dt_struct + + This is an offset from the beginning of the header to the start + of the "structure" part the device tree. (see 2) device tree) + + - off_dt_strings + + This is an offset from the beginning of the header to the start + of the "strings" part of the device-tree + + - off_mem_rsvmap + + This is an offset from the beginning of the header to the start + of the reserved memory map. This map is a list of pairs of 64- + bit integers. Each pair is a physical address and a size. The + list is terminated by an entry of size 0. This map provides the + kernel with a list of physical memory areas that are "reserved" + and thus not to be used for memory allocations, especially during + early initialization. The kernel needs to allocate memory during + boot for things like un-flattening the device-tree, allocating an + MMU hash table, etc... Those allocations must be done in such a + way to avoid overriding critical things like, on Open Firmware + capable machines, the RTAS instance, or on some pSeries, the TCE + tables used for the iommu. Typically, the reserve map should + contain _at least_ this DT block itself (header,total_size). If + you are passing an initrd to the kernel, you should reserve it as + well. You do not need to reserve the kernel image itself. The map + should be 64-bit aligned. + + - version + + This is the version of this structure. Version 1 stops + here. Version 2 adds an additional field boot_cpuid_phys. + Version 3 adds the size of the strings block, allowing the kernel + to reallocate it easily at boot and free up the unused flattened + structure after expansion. Version 16 introduces a new more + "compact" format for the tree itself that is however not backward + compatible. Version 17 adds an additional field, size_dt_struct, + allowing it to be reallocated or moved more easily (this is + particularly useful for bootloaders which need to make + adjustments to a device tree based on probed information). You + should always generate a structure of the highest version defined + at the time of your implementation. Currently that is version 17, + unless you explicitly aim at being backward compatible. + + - last_comp_version + + Last compatible version. This indicates down to what version of + the DT block you are backward compatible. For example, version 2 + is backward compatible with version 1 (that is, a kernel build + for version 1 will be able to boot with a version 2 format). You + should put a 1 in this field if you generate a device tree of + version 1 to 3, or 16 if you generate a tree of version 16 or 17 + using the new unit name format. + + - boot_cpuid_phys + + This field only exist on version 2 headers. It indicate which + physical CPU ID is calling the kernel entry point. This is used, + among others, by kexec. If you are on an SMP system, this value + should match the content of the "reg" property of the CPU node in + the device-tree corresponding to the CPU calling the kernel entry + point (see further chapters for more informations on the required + device-tree contents) + + - size_dt_strings + + This field only exists on version 3 and later headers. It + gives the size of the "strings" section of the device tree (which + starts at the offset given by off_dt_strings). + + - size_dt_struct + + This field only exists on version 17 and later headers. It gives + the size of the "structure" section of the device tree (which + starts at the offset given by off_dt_struct). + +So the typical layout of a DT block (though the various parts don't +need to be in that order) looks like this (addresses go from top to +bottom): + + ------------------------------ + r3 -> | struct boot_param_header | + ------------------------------ + | (alignment gap) (*) | + ------------------------------ + | memory reserve map | + ------------------------------ + | (alignment gap) | + ------------------------------ + | | + | device-tree structure | + | | + ------------------------------ + | (alignment gap) | + ------------------------------ + | | + | device-tree strings | + | | + -----> ------------------------------ + | + | + --- (r3 + totalsize) + + (*) The alignment gaps are not necessarily present; their presence + and size are dependent on the various alignment requirements of + the individual data blocks. + + +2) Device tree generalities +--------------------------- + +This device-tree itself is separated in two different blocks, a +structure block and a strings block. Both need to be aligned to a 4 +byte boundary. + +First, let's quickly describe the device-tree concept before detailing +the storage format. This chapter does _not_ describe the detail of the +required types of nodes & properties for the kernel, this is done +later in chapter III. + +The device-tree layout is strongly inherited from the definition of +the Open Firmware IEEE 1275 device-tree. It's basically a tree of +nodes, each node having two or more named properties. A property can +have a value or not. + +It is a tree, so each node has one and only one parent except for the +root node who has no parent. + +A node has 2 names. The actual node name is generally contained in a +property of type "name" in the node property list whose value is a +zero terminated string and is mandatory for version 1 to 3 of the +format definition (as it is in Open Firmware). Version 16 makes it +optional as it can generate it from the unit name defined below. + +There is also a "unit name" that is used to differentiate nodes with +the same name at the same level, it is usually made of the node +names, the "@" sign, and a "unit address", which definition is +specific to the bus type the node sits on. + +The unit name doesn't exist as a property per-se but is included in +the device-tree structure. It is typically used to represent "path" in +the device-tree. More details about the actual format of these will be +below. + +The kernel powerpc generic code does not make any formal use of the +unit address (though some board support code may do) so the only real +requirement here for the unit address is to ensure uniqueness of +the node unit name at a given level of the tree. Nodes with no notion +of address and no possible sibling of the same name (like /memory or +/cpus) may omit the unit address in the context of this specification, +or use the "@0" default unit address. The unit name is used to define +a node "full path", which is the concatenation of all parent node +unit names separated with "/". + +The root node doesn't have a defined name, and isn't required to have +a name property either if you are using version 3 or earlier of the +format. It also has no unit address (no @ symbol followed by a unit +address). The root node unit name is thus an empty string. The full +path to the root node is "/". + +Every node which actually represents an actual device (that is, a node +which isn't only a virtual "container" for more nodes, like "/cpus" +is) is also required to have a "device_type" property indicating the +type of node . + +Finally, every node that can be referenced from a property in another +node is required to have a "linux,phandle" property. Real open +firmware implementations provide a unique "phandle" value for every +node that the "prom_init()" trampoline code turns into +"linux,phandle" properties. However, this is made optional if the +flattened device tree is used directly. An example of a node +referencing another node via "phandle" is when laying out the +interrupt tree which will be described in a further version of this +document. + +This "linux, phandle" property is a 32-bit value that uniquely +identifies a node. You are free to use whatever values or system of +values, internal pointers, or whatever to generate these, the only +requirement is that every node for which you provide that property has +a unique value for it. + +Here is an example of a simple device-tree. In this example, an "o" +designates a node followed by the node unit name. Properties are +presented with their name followed by their content. "content" +represents an ASCII string (zero terminated) value, while <content> +represents a 32-bit hexadecimal value. The various nodes in this +example will be discussed in a later chapter. At this point, it is +only meant to give you a idea of what a device-tree looks like. I have +purposefully kept the "name" and "linux,phandle" properties which +aren't necessary in order to give you a better idea of what the tree +looks like in practice. + + / o device-tree + |- name = "device-tree" + |- model = "MyBoardName" + |- compatible = "MyBoardFamilyName" + |- #address-cells = <2> + |- #size-cells = <2> + |- linux,phandle = <0> + | + o cpus + | | - name = "cpus" + | | - linux,phandle = <1> + | | - #address-cells = <1> + | | - #size-cells = <0> + | | + | o PowerPC,970@0 + | |- name = "PowerPC,970" + | |- device_type = "cpu" + | |- reg = <0> + | |- clock-frequency = <5f5e1000> + | |- 64-bit + | |- linux,phandle = <2> + | + o memory@0 + | |- name = "memory" + | |- device_type = "memory" + | |- reg = <00000000 00000000 00000000 20000000> + | |- linux,phandle = <3> + | + o chosen + |- name = "chosen" + |- bootargs = "root=/dev/sda2" + |- linux,phandle = <4> + +This tree is almost a minimal tree. It pretty much contains the +minimal set of required nodes and properties to boot a linux kernel; +that is, some basic model informations at the root, the CPUs, and the +physical memory layout. It also includes misc information passed +through /chosen, like in this example, the platform type (mandatory) +and the kernel command line arguments (optional). + +The /cpus/PowerPC,970@0/64-bit property is an example of a +property without a value. All other properties have a value. The +significance of the #address-cells and #size-cells properties will be +explained in chapter IV which defines precisely the required nodes and +properties and their content. + + +3) Device tree "structure" block + +The structure of the device tree is a linearized tree structure. The +"OF_DT_BEGIN_NODE" token starts a new node, and the "OF_DT_END_NODE" +ends that node definition. Child nodes are simply defined before +"OF_DT_END_NODE" (that is nodes within the node). A 'token' is a 32 +bit value. The tree has to be "finished" with a OF_DT_END token + +Here's the basic structure of a single node: + + * token OF_DT_BEGIN_NODE (that is 0x00000001) + * for version 1 to 3, this is the node full path as a zero + terminated string, starting with "/". For version 16 and later, + this is the node unit name only (or an empty string for the + root node) + * [align gap to next 4 bytes boundary] + * for each property: + * token OF_DT_PROP (that is 0x00000003) + * 32-bit value of property value size in bytes (or 0 if no + value) + * 32-bit value of offset in string block of property name + * property value data if any + * [align gap to next 4 bytes boundary] + * [child nodes if any] + * token OF_DT_END_NODE (that is 0x00000002) + +So the node content can be summarized as a start token, a full path, +a list of properties, a list of child nodes, and an end token. Every +child node is a full node structure itself as defined above. + +NOTE: The above definition requires that all property definitions for +a particular node MUST precede any subnode definitions for that node. +Although the structure would not be ambiguous if properties and +subnodes were intermingled, the kernel parser requires that the +properties come first (up until at least 2.6.22). Any tools +manipulating a flattened tree must take care to preserve this +constraint. + +4) Device tree "strings" block + +In order to save space, property names, which are generally redundant, +are stored separately in the "strings" block. This block is simply the +whole bunch of zero terminated strings for all property names +concatenated together. The device-tree property definitions in the +structure block will contain offset values from the beginning of the +strings block. + + +III - libfdt +============ + +This library should be merged into dtc proper. +This library should likely be worked into U-Boot and the kernel. + + +IV - Utility Tools +================== + +1) convert-dtsv0 -- Conversion to Version 1 + +convert-dtsv0 is a small utility program which converts (DTS) +Device Tree Source from the obsolete version 0 to version 1. + +Version 1 DTS files are marked by line "/dts-v1/;" at the top of the file. + +The syntax of the convert-dtsv0 command line is: + + convert-dtsv0 [<input_filename ... >] + +Each file passed will be converted to the new /dts-v1/ version by creating +a new file with a "v1" appended the filename. + +Comments, empty lines, etc. are preserved. + + +2) fdtdump -- Flat Device Tree dumping utility + +The fdtdump program prints a readable version of a flat device tree file. + +The syntax of the fdtdump command line is: + + fdtdump <DTB-file-name> Copied: vendor/dtc/dtc-6a15eb23/Makefile (from r261202, vendor/dtc/dist/Makefile) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ vendor/dtc/dtc-6a15eb23/Makefile Mon Jan 27 06:31:37 2014 (r261204, copy of r261202, vendor/dtc/dist/Makefile) @@ -0,0 +1,271 @@ +# +# Device Tree Compiler +# + +# +# Version information will be constructed in this order: +# EXTRAVERSION might be "-rc", for example. +# LOCAL_VERSION is likely from command line. +# CONFIG_LOCALVERSION from some future config system. +# +VERSION = 1 +PATCHLEVEL = 4 +SUBLEVEL = 0 +EXTRAVERSION = +LOCAL_VERSION = +CONFIG_LOCALVERSION = + +CPPFLAGS = -I libfdt -I . +WARNINGS = -Werror -Wall -Wpointer-arith -Wcast-qual -Wnested-externs \ + -Wstrict-prototypes -Wmissing-prototypes -Wredundant-decls +CFLAGS = -g -Os -fPIC -Werror $(WARNINGS) + +BISON = bison +LEX = flex + +INSTALL = /usr/bin/install +DESTDIR = +PREFIX = $(HOME) +BINDIR = $(PREFIX)/bin +LIBDIR = $(PREFIX)/lib +INCLUDEDIR = $(PREFIX)/include + +HOSTOS := $(shell uname -s | tr '[:upper:]' '[:lower:]' | \ + sed -e 's/\(cygwin\).*/cygwin/') + +ifeq ($(HOSTOS),darwin) +SHAREDLIB_EXT=dylib +SHAREDLIB_LINK_OPTIONS=-dynamiclib -Wl,-install_name -Wl, +else +SHAREDLIB_EXT=so +SHAREDLIB_LINK_OPTIONS=-shared -Wl,--version-script=$(LIBFDT_version) -Wl,-soname, +endif + +# +# Overall rules +# +ifdef V +VECHO = : +else +VECHO = echo " " +ARFLAGS = rc +.SILENT: +endif + +NODEPTARGETS = clean +ifeq ($(MAKECMDGOALS),) +DEPTARGETS = all +else +DEPTARGETS = $(filter-out $(NODEPTARGETS),$(MAKECMDGOALS)) +endif + +# +# Rules for versioning +# + +DTC_VERSION = $(VERSION).$(PATCHLEVEL).$(SUBLEVEL)$(EXTRAVERSION) +VERSION_FILE = version_gen.h + +CONFIG_SHELL := $(shell if [ -x "$$BASH" ]; then echo $$BASH; \ + else if [ -x /bin/bash ]; then echo /bin/bash; \ + else echo sh; fi ; fi) + +nullstring := +space := $(nullstring) # end of line + +localver_config = $(subst $(space),, $(string) \ + $(patsubst "%",%,$(CONFIG_LOCALVERSION))) + +localver_cmd = $(subst $(space),, $(string) \ + $(patsubst "%",%,$(LOCALVERSION))) + +localver_scm = $(shell $(CONFIG_SHELL) ./scripts/setlocalversion) +localver_full = $(localver_config)$(localver_cmd)$(localver_scm) + +dtc_version = $(DTC_VERSION)$(localver_full) + +# Contents of the generated version file. +define filechk_version + (echo "#define DTC_VERSION \"DTC $(dtc_version)\""; ) +endef + +define filechk + set -e; \ + echo ' CHK $@'; \ + mkdir -p $(dir $@); \ + $(filechk_$(1)) < $< > $@.tmp; \ + if [ -r $@ ] && cmp -s $@ $@.tmp; then \ + rm -f $@.tmp; \ + else \ + echo ' UPD $@'; \ + mv -f $@.tmp $@; \ + fi; +endef + + +include Makefile.convert-dtsv0 +include Makefile.dtc +include Makefile.utils + +BIN += convert-dtsv0 +BIN += dtc +BIN += fdtdump +BIN += fdtget +BIN += fdtput + +SCRIPTS = dtdiff + +all: $(BIN) libfdt + + +ifneq ($(DEPTARGETS),) +-include $(DTC_OBJS:%.o=%.d) +-include $(CONVERT_OBJS:%.o=%.d) +-include $(FDTDUMP_OBJS:%.o=%.d) +-include $(FDTGET_OBJS:%.o=%.d) +-include $(FDTPUT_OBJS:%.o=%.d) +endif + + + +# +# Rules for libfdt +# +LIBFDT_objdir = libfdt +LIBFDT_srcdir = libfdt +LIBFDT_archive = $(LIBFDT_objdir)/libfdt.a +LIBFDT_lib = $(LIBFDT_objdir)/libfdt-$(DTC_VERSION).$(SHAREDLIB_EXT) +LIBFDT_include = $(addprefix $(LIBFDT_srcdir)/,$(LIBFDT_INCLUDES)) +LIBFDT_version = $(addprefix $(LIBFDT_srcdir)/,$(LIBFDT_VERSION)) + +include $(LIBFDT_srcdir)/Makefile.libfdt + +.PHONY: libfdt +libfdt: $(LIBFDT_archive) $(LIBFDT_lib) + +$(LIBFDT_archive): $(addprefix $(LIBFDT_objdir)/,$(LIBFDT_OBJS)) +$(LIBFDT_lib): $(addprefix $(LIBFDT_objdir)/,$(LIBFDT_OBJS)) + +libfdt_clean: + @$(VECHO) CLEAN "(libfdt)" + rm -f $(addprefix $(LIBFDT_objdir)/,$(STD_CLEANFILES)) + rm -f $(LIBFDT_objdir)/*.so + +ifneq ($(DEPTARGETS),) +-include $(LIBFDT_OBJS:%.o=$(LIBFDT_objdir)/%.d) +endif + +# This stops make from generating the lex and bison output during +# auto-dependency computation, but throwing them away as an +# intermediate target and building them again "for real" +.SECONDARY: $(DTC_GEN_SRCS) $(CONVERT_GEN_SRCS) + +install-bin: all $(SCRIPTS) + @$(VECHO) INSTALL-BIN + $(INSTALL) -d $(DESTDIR)$(BINDIR) + $(INSTALL) $(BIN) $(SCRIPTS) $(DESTDIR)$(BINDIR) + +install-lib: all + @$(VECHO) INSTALL-LIB + $(INSTALL) -d $(DESTDIR)$(LIBDIR) + $(INSTALL) $(LIBFDT_lib) $(DESTDIR)$(LIBDIR) + ln -sf $(notdir $(LIBFDT_lib)) $(DESTDIR)$(LIBDIR)/$(LIBFDT_soname) + ln -sf $(LIBFDT_soname) $(DESTDIR)$(LIBDIR)/libfdt.$(SHAREDLIB_EXT) + $(INSTALL) -m 644 $(LIBFDT_archive) $(DESTDIR)$(LIBDIR) + +install-includes: + @$(VECHO) INSTALL-INC + $(INSTALL) -d $(DESTDIR)$(INCLUDEDIR) + $(INSTALL) -m 644 $(LIBFDT_include) $(DESTDIR)$(INCLUDEDIR) + +install: install-bin install-lib install-includes + +$(VERSION_FILE): Makefile FORCE + $(call filechk,version) + + +dtc: $(DTC_OBJS) + +convert-dtsv0: $(CONVERT_OBJS) + @$(VECHO) LD $@ + $(LINK.c) -o $@ $^ + +fdtdump: $(FDTDUMP_OBJS) + +fdtget: $(FDTGET_OBJS) $(LIBFDT_archive) + +fdtput: $(FDTPUT_OBJS) $(LIBFDT_archive) + + +# +# Testsuite rules +# +TESTS_PREFIX=tests/ + +TESTS_BIN += dtc +TESTS_BIN += convert-dtsv0 +TESTS_BIN += fdtput +TESTS_BIN += fdtget + +include tests/Makefile.tests + +# +# Clean rules +# +STD_CLEANFILES = *~ *.o *.$(SHAREDLIB_EXT) *.d *.a *.i *.s core a.out vgcore.* \ + *.tab.[ch] *.lex.c *.output + +clean: libfdt_clean tests_clean + @$(VECHO) CLEAN + rm -f $(STD_CLEANFILES) + rm -f $(VERSION_FILE) + rm -f $(BIN) + +# +# Generic compile rules +# +%: %.o + @$(VECHO) LD $@ + $(LINK.c) -o $@ $^ + +%.o: %.c + @$(VECHO) CC $@ + $(CC) $(CPPFLAGS) $(CFLAGS) -o $@ -c $< + +%.o: %.S + @$(VECHO) AS $@ + $(CC) $(CPPFLAGS) $(AFLAGS) -D__ASSEMBLY__ -o $@ -c $< + +%.d: %.c + @$(VECHO) DEP $< + $(CC) $(CPPFLAGS) -MM -MG -MT "$*.o $@" $< > $@ + +%.d: %.S + @$(VECHO) DEP $< + $(CC) $(CPPFLAGS) -MM -MG -MT "$*.o $@" $< > $@ + +%.i: %.c + @$(VECHO) CPP $@ + $(CC) $(CPPFLAGS) -E $< > $@ + +%.s: %.c + @$(VECHO) CC -S $@ + $(CC) $(CPPFLAGS) $(CFLAGS) -o $@ -S $< + +%.a: + @$(VECHO) AR $@ + $(AR) $(ARFLAGS) $@ $^ + +$(LIBFDT_lib): + @$(VECHO) LD $@ + $(CC) $(LDFLAGS) -fPIC $(SHAREDLIB_LINK_OPTIONS)$(LIBFDT_soname) -o $(LIBFDT_lib) $^ + +%.lex.c: %.l + @$(VECHO) LEX $@ + $(LEX) -o$@ $< + +%.tab.c %.tab.h %.output: %.y + @$(VECHO) BISON $@ + $(BISON) -d $< + +FORCE: Copied: vendor/dtc/dtc-6a15eb23/checks.c (from r261202, vendor/dtc/dist/checks.c) ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ vendor/dtc/dtc-6a15eb23/checks.c Mon Jan 27 06:31:37 2014 (r261204, copy of r261202, vendor/dtc/dist/checks.c) @@ -0,0 +1,759 @@ +/* + * (C) Copyright David Gibson <dwg@au1.ibm.com>, IBM Corporation. 2007. + * + * + * This program is free software; you can redistribute it and/or + * modify it under the terms of the GNU General Public License as + * published by the Free Software Foundation; either version 2 of the + * License, or (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 + * USA + */ + +#include "dtc.h" + +#ifdef TRACE_CHECKS +#define TRACE(c, ...) \ + do { \ + fprintf(stderr, "=== %s: ", (c)->name); \ + fprintf(stderr, __VA_ARGS__); \ + fprintf(stderr, "\n"); \ + } while (0) +#else +#define TRACE(c, fmt, ...) do { } while (0) +#endif + +enum checkstatus { + UNCHECKED = 0, + PREREQ, + PASSED, + FAILED, +}; + +struct check; + +typedef void (*tree_check_fn)(struct check *c, struct node *dt); +typedef void (*node_check_fn)(struct check *c, struct node *dt, struct node *node); +typedef void (*prop_check_fn)(struct check *c, struct node *dt, + struct node *node, struct property *prop); + +struct check { + const char *name; + tree_check_fn tree_fn; + node_check_fn node_fn; + prop_check_fn prop_fn; + void *data; + bool warn, error; + enum checkstatus status; + bool inprogress; + int num_prereqs; + struct check **prereq; +}; + *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201401270631.s0R6Vb6s056713>