The source tree contains the Device Tree Compiler (dtc) toolchain for
working with device tree source and binary files and also libfdt, a
utility library for reading and manipulating the binary format.

DTC and LIBFDT are maintained by:

David Gibson <david@gibson.dropbear.id.au>
Jon Loeliger <loeliger@gmail.com>


Python library
--------------

A Python library is also available. To build this you will need to install
swig and Python development files. On Debian distributions:

   sudo apt-get install swig python3-dev

The library provides an Fdt class which you can use like this:

$ PYTHONPATH=../pylibfdt python3
>>> import libfdt
>>> fdt = libfdt.Fdt(open('test_tree1.dtb', mode='rb').read())
>>> node = fdt.path_offset('/subnode@1')
>>> print(node)
124
>>> prop_offset = fdt.first_property_offset(node)
>>> prop = fdt.get_property_by_offset(prop_offset)
>>> print('%s=%s' % (prop.name, prop.as_str()))
compatible=subnode1
>>> node2 = fdt.path_offset('/')
>>> print(fdt.getprop(node2, 'compatible').as_str())
test_tree1

You will find tests in tests/pylibfdt_tests.py showing how to use each
method. Help is available using the Python help command, e.g.:

    $ cd pylibfdt
    $ python3 -c "import libfdt; help(libfdt)"

If you add new features, please check code coverage:

    $ sudo apt-get install python3-coverage
    $ cd tests
    # It's just 'coverage' on most other distributions
    $ python3-coverage run pylibfdt_tests.py
    $ python3-coverage html
    # Open 'htmlcov/index.html' in your browser


The library can be installed with pip from a local source tree:

    pip install . [--user|--prefix=/path/to/install_dir]

Or directly from a remote git repo:

    pip install git+git://git.kernel.org/pub/scm/utils/dtc/dtc.git@main

The install depends on libfdt shared library being installed on the host system
first. Generally, using --user or --prefix is not necessary and pip will use the
default location for the Python installation which varies if the user is root or
not.

You can also install everything via make if you like, but pip is recommended.

To install both libfdt and pylibfdt you can use:

    make install [PREFIX=/path/to/install_dir]

To disable building the python library, even if swig and Python are available,
use:

    make NO_PYTHON=1


More work remains to support all of libfdt, including access to numeric
values.


Adding a new function to libfdt.h
---------------------------------

The shared library uses libfdt/version.lds to list the exported functions, so
add your new function there. Check that your function works with pylibfdt. If
it cannot be supported, put the declaration in libfdt.h behind #ifndef SWIG so
that swig ignores it.


Tests
-----

Test files are kept in the tests/ directory. Use 'make check' to build and run
all tests.

If you want to adjust a test file, be aware that tree_tree1.dts is compiled
and checked against a binary tree from assembler macros in trees.S. So
if you change that file you must change tree.S also.


Mailing list
------------
The following list is for discussion about dtc and libfdt implementation
mailto:devicetree-compiler@vger.kernel.org

Core device tree bindings are discussed on the devicetree-spec list:
mailto:devicetree-spec@vger.kernel.org

Licensing and contribution policy of dtc and libfdt
===================================================

This dtc package contains two pieces of software: dtc itself, and
libfdt which comprises the files in the libfdt/ subdirectory.  These
two pieces of software, although closely related, are quite distinct.
dtc does not incorporate or rely on libfdt for its operation, nor vice
versa.  It is important that these two pieces of software have
different license conditions.

As SPDX license tags in each source file attest, dtc is licensed
under the GNU GPL.  The full text of the GPL can be found in the file
entitled 'GPL' which should be included in this package.  dtc code,
therefore, may not be incorporated into works which do not have a GPL
compatible license.

libfdt, however, is GPL/BSD dual-licensed.  That is, it may be used
either under the terms of the GPL, or under the terms of the 2-clause
BSD license (aka the ISC license).  The full terms of that license can
be found are in the file entitled 'BSD-2-Clause'. This is, in
practice, equivalent to being BSD licensed, since the terms of the BSD
license are strictly more permissive than the GPL.

I made the decision to license libfdt in this way because I want to
encourage widespread and correct usage of flattened device trees,
including by proprietary or otherwise GPL-incompatible firmware or
tools.  Allowing libfdt to be used under the terms of the BSD license
makes that it easier for vendors or authors of such software to do so.

This does mean that libfdt code could be "stolen" - say, included in a
proprietary fimware and extended without contributing those extensions
back to the libfdt mainline.  While I hope that doesn't happen, I
believe the goal of allowing libfdt to be widely used is more
important than avoiding that.  libfdt is quite small, and hardly
rocket science; so the incentive for such impolite behaviour is small,
and the inconvenience caused thereby is not dire.

Licenses such as the LGPL which would allow code to be used in non-GPL
software, but also require contributions to be returned were
considered.  However, libfdt is designed to be used in firmwares and
other environments with unusual technical constraints.  It's difficult
to anticipate all possible changes which might be needed to meld
libfdt into such environments and so difficult to suitably word a
license that puts the boundary between what is and isn't permitted in
the intended place.  Again, I judged encouraging widespread use of
libfdt by keeping the license terms simple and familiar to be the more
important goal.

**IMPORTANT** It's intended that all of libfdt as released remain
permissively licensed this way.  Therefore only contributions which
are released under these terms can be merged into the libfdt mainline.


David Gibson <david@gibson.dropbear.id.au>
(principal original author of dtc and libfdt)
2 November 2007

URL: https://git.kernel.org/cgit/utils/dtc/dtc.git/commit/?id=120775eb1cf39f8dcecd695c3ff1cfef8aeb669d
Version: 1.4.2 plus bugfixes
Owners: cphoenix