From owner-svn-src-all@freebsd.org Fri Mar 10 03:28:45 2017 Return-Path: Delivered-To: svn-src-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 21DEFD05F3C; Fri, 10 Mar 2017 03:28:45 +0000 (UTC) (envelope-from gonzo@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id DA2371D60; Fri, 10 Mar 2017 03:28:44 +0000 (UTC) (envelope-from gonzo@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id v2A3SicD014120; Fri, 10 Mar 2017 03:28:44 GMT (envelope-from gonzo@FreeBSD.org) Received: (from gonzo@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v2A3Sh9V014114; Fri, 10 Mar 2017 03:28:43 GMT (envelope-from gonzo@FreeBSD.org) Message-Id: <201703100328.v2A3Sh9V014114@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: gonzo set sender to gonzo@FreeBSD.org using -f From: Oleksandr Tymoshenko Date: Fri, 10 Mar 2017 03:28:43 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-vendor@freebsd.org Subject: svn commit: r314985 - in vendor/dtc/dist: . Documentation libfdt scripts tests X-SVN-Group: vendor MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 10 Mar 2017 03:28:45 -0000 Author: gonzo Date: Fri Mar 10 03:28:43 2017 New Revision: 314985 URL: https://svnweb.freebsd.org/changeset/base/314985 Log: Import dtc 1.4.3 Obtained from: https://www.kernel.org/pub/software/utils/dtc/dtc-1.4.3.tar.gz Added: vendor/dtc/dist/Documentation/dt-object-internal.txt (contents, props changed) vendor/dtc/dist/README vendor/dtc/dist/libfdt/fdt_addresses.c (contents, props changed) vendor/dtc/dist/libfdt/fdt_overlay.c (contents, props changed) vendor/dtc/dist/scripts/kup-dtc (contents, props changed) vendor/dtc/dist/tests/addr_size_cells.c (contents, props changed) vendor/dtc/dist/tests/addresses.dts (contents, props changed) vendor/dtc/dist/tests/bad-octal-literal.dts (contents, props changed) vendor/dtc/dist/tests/bad-size-cells.dts (contents, props changed) vendor/dtc/dist/tests/check_path.c (contents, props changed) vendor/dtc/dist/tests/division-by-zero.dts (contents, props changed) vendor/dtc/dist/tests/embedded_nul.dts (contents, props changed) vendor/dtc/dist/tests/embedded_nul_equiv.dts (contents, props changed) vendor/dtc/dist/tests/fdtdump-runtest.sh (contents, props changed) vendor/dtc/dist/tests/fdtdump.dts (contents, props changed) vendor/dtc/dist/tests/nul-in-escape.dts (contents, props changed) vendor/dtc/dist/tests/nul-in-line-info1.dts (contents, props changed) vendor/dtc/dist/tests/nul-in-line-info2.dts (contents, props changed) vendor/dtc/dist/tests/overlay.c (contents, props changed) vendor/dtc/dist/tests/overlay_bad_fixup.c (contents, props changed) vendor/dtc/dist/tests/overlay_bad_fixup_bad_index.dts (contents, props changed) vendor/dtc/dist/tests/overlay_bad_fixup_base.dtsi (contents, props changed) vendor/dtc/dist/tests/overlay_bad_fixup_empty.dts (contents, props changed) vendor/dtc/dist/tests/overlay_bad_fixup_empty_index.dts (contents, props changed) vendor/dtc/dist/tests/overlay_bad_fixup_index_trailing.dts (contents, props changed) vendor/dtc/dist/tests/overlay_bad_fixup_path_empty_prop.dts (contents, props changed) vendor/dtc/dist/tests/overlay_bad_fixup_path_only.dts (contents, props changed) vendor/dtc/dist/tests/overlay_bad_fixup_path_only_sep.dts (contents, props changed) vendor/dtc/dist/tests/overlay_bad_fixup_path_prop.dts (contents, props changed) vendor/dtc/dist/tests/overlay_base.dts (contents, props changed) vendor/dtc/dist/tests/overlay_base_manual_symbols.dts (contents, props changed) vendor/dtc/dist/tests/overlay_overlay.dts (contents, props changed) vendor/dtc/dist/tests/overlay_overlay_manual_fixups.dts (contents, props changed) vendor/dtc/dist/tests/overlay_overlay_no_fixups.dts (contents, props changed) vendor/dtc/dist/tests/overlay_overlay_simple.dts (contents, props changed) vendor/dtc/dist/tests/property_iterate.c (contents, props changed) vendor/dtc/dist/tests/property_iterate.dts (contents, props changed) vendor/dtc/dist/tests/reg-without-unit-addr.dts (contents, props changed) vendor/dtc/dist/tests/sourceoutput.dts (contents, props changed) vendor/dtc/dist/tests/stringlist.c (contents, props changed) vendor/dtc/dist/tests/stringlist.dts (contents, props changed) vendor/dtc/dist/tests/test_label_ref.dts (contents, props changed) vendor/dtc/dist/tests/test_tree1_label_noderef.dts (contents, props changed) vendor/dtc/dist/tests/unit-addr-without-reg.dts (contents, props changed) Deleted: vendor/dtc/dist/Makefile.ftdump vendor/dtc/dist/ftdump.c vendor/dtc/dist/tests/references_dts0.dts vendor/dtc/dist/tests/test_tree1_body.dtsi vendor/dtc/dist/tests/test_tree1_dts0.dts Modified: vendor/dtc/dist/Documentation/manual.txt vendor/dtc/dist/Makefile vendor/dtc/dist/checks.c vendor/dtc/dist/convert-dtsv0-lexer.l vendor/dtc/dist/data.c vendor/dtc/dist/dtc-lexer.l vendor/dtc/dist/dtc-parser.y vendor/dtc/dist/dtc.c vendor/dtc/dist/dtc.h vendor/dtc/dist/fdtdump.c vendor/dtc/dist/fdtget.c vendor/dtc/dist/fdtput.c vendor/dtc/dist/flattree.c vendor/dtc/dist/fstree.c vendor/dtc/dist/libfdt/Makefile.libfdt vendor/dtc/dist/libfdt/fdt.c vendor/dtc/dist/libfdt/fdt_ro.c vendor/dtc/dist/libfdt/fdt_rw.c vendor/dtc/dist/libfdt/fdt_strerror.c vendor/dtc/dist/libfdt/fdt_wip.c vendor/dtc/dist/libfdt/libfdt.h vendor/dtc/dist/libfdt/libfdt_env.h vendor/dtc/dist/libfdt/libfdt_internal.h vendor/dtc/dist/libfdt/version.lds vendor/dtc/dist/livetree.c vendor/dtc/dist/srcpos.c vendor/dtc/dist/srcpos.h vendor/dtc/dist/tests/Makefile.tests vendor/dtc/dist/tests/dumptrees.c vendor/dtc/dist/tests/get_phandle.c vendor/dtc/dist/tests/line_directives.dts vendor/dtc/dist/tests/multilabel.dts vendor/dtc/dist/tests/multilabel_merge.dts vendor/dtc/dist/tests/path-references.c vendor/dtc/dist/tests/path-references.dts vendor/dtc/dist/tests/path_offset.c vendor/dtc/dist/tests/references.c vendor/dtc/dist/tests/references.dts vendor/dtc/dist/tests/run_tests.sh vendor/dtc/dist/tests/setprop.c vendor/dtc/dist/tests/setprop_inplace.c vendor/dtc/dist/tests/subnode_iterate.c vendor/dtc/dist/tests/test_tree1.dts vendor/dtc/dist/tests/test_tree1_delete.dts vendor/dtc/dist/tests/testdata.h vendor/dtc/dist/tests/tests.sh vendor/dtc/dist/tests/testutils.c vendor/dtc/dist/tests/trees.S vendor/dtc/dist/treesource.c vendor/dtc/dist/util.c vendor/dtc/dist/util.h Added: vendor/dtc/dist/Documentation/dt-object-internal.txt ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ vendor/dtc/dist/Documentation/dt-object-internal.txt Fri Mar 10 03:28:43 2017 (r314985) @@ -0,0 +1,310 @@ +Device Tree Dynamic Object format internals +------------------------------------------- + +The Device Tree for most platforms is a static representation of +the hardware capabilities. This is insufficient for platforms +that need to dynamically insert Device Tree fragments into the +live tree. + +This document explains the the Device Tree object format and +modifications made to the Device Tree compiler, which make it possible. + +1. Simplified Problem Definition +-------------------------------- + +Assume we have a platform which boots using following simplified Device Tree. + +---- foo.dts ----------------------------------------------------------------- + /* FOO platform */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + }; + }; +---- foo.dts ----------------------------------------------------------------- + +We have a number of peripherals that after probing (using some undefined method) +should result in different Device Tree configuration. + +We cannot boot with this static tree because due to the configuration of the +foo platform there exist multiple conficting peripherals DT fragments. + +So for the bar peripheral we would have this: + +---- foo+bar.dts ------------------------------------------------------------- + /* FOO platform + bar peripheral */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + + /* bar peripheral */ + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + }; + }; + }; +---- foo+bar.dts ------------------------------------------------------------- + +While for the baz peripheral we would have this: + +---- foo+baz.dts ------------------------------------------------------------- + /* FOO platform + baz peripheral */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + /* baz resources */ + baz_res: res_baz { ... }; + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + + /* baz peripheral */ + baz { + compatible = "corp,baz"; + /* reference to another point in the tree */ + ref-to-res = <&baz_res>; + ... /* various properties and child nodes */ + }; + }; + }; +---- foo+baz.dts ------------------------------------------------------------- + +We note that the baz case is more complicated, since the baz peripheral needs to +reference another node in the DT tree. + +2. Device Tree Object Format Requirements +----------------------------------------- + +Since the Device Tree is used for booting a number of very different hardware +platforms it is imperative that we tread very carefully. + +2.a) No changes to the Device Tree binary format for the base tree. We cannot +modify the tree format at all and all the information we require should be +encoded using Device Tree itself. We can add nodes that can be safely ignored +by both bootloaders and the kernel. The plugin dtbs are optionally tagged +with a different magic number in the header but otherwise they're simple +blobs. + +2.b) Changes to the DTS source format should be absolutely minimal, and should +only be needed for the DT fragment definitions, and not the base boot DT. + +2.c) An explicit option should be used to instruct DTC to generate the required +information needed for object resolution. Platforms that don't use the +dynamic object format can safely ignore it. + +2.d) Finally, DT syntax changes should be kept to a minimum. It should be +possible to express everything using the existing DT syntax. + +3. Implementation +----------------- + +The basic unit of addressing in Device Tree is the phandle. Turns out it's +relatively simple to extend the way phandles are generated and referenced +so that it's possible to dynamically convert symbolic references (labels) +to phandle values. This is a valid assumption as long as the author uses +reference syntax and does not assign phandle values manually (which might +be a problem with decompiled source files). + +We can roughly divide the operation into two steps. + +3.a) Compilation of the base board DTS file using the '-@' option +generates a valid DT blob with an added __symbols__ node at the root node, +containing a list of all nodes that are marked with a label. + +Using the foo.dts file above the following node will be generated; + +$ dtc -@ -O dtb -o foo.dtb -b 0 foo.dts +$ fdtdump foo.dtb +... +/ { + ... + res { + ... + phandle = <0x00000001>; + ... + }; + ocp { + ... + phandle = <0x00000002>; + ... + }; + __symbols__ { + res="/res"; + ocp="/ocp"; + }; +}; + +Notice that all the nodes that had a label have been recorded, and that +phandles have been generated for them. + +This blob can be used to boot the board normally, the __symbols__ node will +be safely ignored both by the bootloader and the kernel (the only loss will +be a few bytes of memory and disk space). + +We generate a __symbols__ node to record nodes that had labels in the base +tree (or subsequent loaded overlays) so that they can be matched up with +references made to them in Device Tree objects. + +3.b) The Device Tree fragments must be compiled with the same option but they +must also have a tag (/plugin/) that allows undefined references to nodes +that are not present at compilation time to be recorded so that the runtime +loader can fix them. + +So the bar peripheral's DTS format would be of the form: + +/dts-v1/; +/plugin/; /* allow undefined references and record them */ +/ { + .... /* various properties for loader use; i.e. part id etc. */ + fragment@0 { + target = <&ocp>; + __overlay__ { + /* bar peripheral */ + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + } + }; + }; +}; + +Note that there's a target property that specifies the location where the +contents of the overlay node will be placed, and it references the node +in the foo.dts file. + +$ dtc -@ -O dtb -o bar.dtbo -b 0 bar.dts +$ fdtdump bar.dtbo +... +/ { + ... /* properties */ + fragment@0 { + target = <0xffffffff>; + __overlay__ { + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + } + }; + }; + __fixups__ { + ocp = "/fragment@0:target:0"; + }; +}; + +No __symbols__ node has been generated (no label in bar.dts). +Note that the target's ocp label is undefined, so the phandle +value is filled with the illegal value '0xffffffff', while a __fixups__ +node has been generated, which marks the location in the tree where +the label lookup should store the runtime phandle value of the ocp node. + +The format of the __fixups__ node entry is + +