README
1The source tree contains the Device Tree Compiler (dtc) toolchain for
2working with device tree source and binary files and also libfdt, a
3utility library for reading and manipulating the binary format.
4
5DTC and LIBFDT are maintained by:
6
7David Gibson <david@gibson.dropbear.id.au>
8Jon Loeliger <jdl@jdl.com>
9
10
11Python library
12--------------
13
14A Python library is also available. To build this you will need to install
15swig and Python development files. On Debian distributions:
16
17 sudo apt-get install swig python-dev
18
19The library provides an Fdt class which you can use like this:
20
21$ PYTHONPATH=../pylibfdt python
22>>> import libfdt
23>>> fdt = libfdt.Fdt(open('test_tree1.dtb').read())
24>>> node = fdt.path_offset('/subnode@1')
25>>> print node
26124
27>>> prop_offset = fdt.first_property_offset(node)
28>>> prop = fdt.get_property_by_offset(prop_offset)
29>>> print '%s=%r' % (prop.name, prop.value)
30compatible=bytearray(b'subnode1\x00')
31>>> print '%s=%s' % (prop.name, prop.value)
32compatible=subnode1
33>>> node2 = fdt.path_offset('/')
34>>> print fdt.getprop(node2, 'compatible')
35test_tree1
36
37You will find tests in tests/pylibfdt_tests.py showing how to use each
38method. Help is available using the Python help command, e.g.:
39
40 $ cd pylibfdt
41 $ python -c "import libfdt; help(libfdt)"
42
43If you add new features, please check code coverage:
44
45 $ sudo apt-get install python-pip python-pytest
46 $ sudo pip install coverage
47 $ cd tests
48 $ coverage run pylibfdt_tests.py
49 $ coverage html
50 # Open 'htmlcov/index.html' in your browser
51
52
53To install the library via the normal setup.py method, use:
54
55 ./pylibfdt/setup.py [--prefix=/path/to/install_dir]
56
57If --prefix is not provided, the default prefix is used, typically '/usr'
58or '/usr/local'. See Python's distutils documentation for details. You can
59also install via the Makefile if you like, but the above is more common.
60
61To install both libfdt and pylibfdt you can use:
62
63 make install [SETUP_PREFIX=/path/to/install_dir] \
64 [PREFIX=/path/to/install_dir]
65
66To disable building the python library, even if swig and Python are available,
67use:
68
69 make NO_PYTHON=1
70
71
72More work remains to support all of libfdt, including access to numeric
73values.
74
75
76Mailing list
77------------
78The following list is for discussion about dtc and libfdt implementation
79mailto:devicetree-compiler@vger.kernel.org
80
81Core device tree bindings are discussed on the devicetree-spec list:
82mailto:devicetree-spec@vger.kernel.org
83
README.license
1Licensing and contribution policy of dtc and libfdt
2===================================================
3
4This dtc package contains two pieces of software: dtc itself, and
5libfdt which comprises the files in the libfdt/ subdirectory. These
6two pieces of software, although closely related, are quite distinct.
7dtc does not incoporate or rely on libfdt for its operation, nor vice
8versa. It is important that these two pieces of software have
9different license conditions.
10
11As the copyright banners in each source file attest, dtc is licensed
12under the GNU GPL. The full text of the GPL can be found in the file
13entitled 'GPL' which should be included in this package. dtc code,
14therefore, may not be incorporated into works which do not have a GPL
15compatible license.
16
17libfdt, however, is GPL/BSD dual-licensed. That is, it may be used
18either under the terms of the GPL, or under the terms of the 2-clause
19BSD license (aka the ISC license). The full terms of that license are
20given in the copyright banners of each of the libfdt source files.
21This is, in practice, equivalent to being BSD licensed, since the
22terms of the BSD license are strictly more permissive than the GPL.
23
24I made the decision to license libfdt in this way because I want to
25encourage widespread and correct usage of flattened device trees,
26including by proprietary or otherwise GPL-incompatible firmware or
27tools. Allowing libfdt to be used under the terms of the BSD license
28makes that it easier for vendors or authors of such software to do so.
29
30This does mean that libfdt code could be "stolen" - say, included in a
31proprietary fimware and extended without contributing those extensions
32back to the libfdt mainline. While I hope that doesn't happen, I
33believe the goal of allowing libfdt to be widely used is more
34important than avoiding that. libfdt is quite small, and hardly
35rocket science; so the incentive for such impolite behaviour is small,
36and the inconvenience caused therby is not dire.
37
38Licenses such as the LGPL which would allow code to be used in non-GPL
39software, but also require contributions to be returned were
40considered. However, libfdt is designed to be used in firmwares and
41other environments with unusual technical constraints. It's difficult
42to anticipate all possible changes which might be needed to meld
43libfdt into such environments and so difficult to suitably word a
44license that puts the boundary between what is and isn't permitted in
45the intended place. Again, I judged encouraging widespread use of
46libfdt by keeping the license terms simple and familiar to be the more
47important goal.
48
49**IMPORTANT** It's intended that all of libfdt as released remain
50permissively licensed this way. Therefore only contributions which
51are released under these terms can be merged into the libfdt mainline.
52
53
54David Gibson <david@gibson.dropbear.id.au>
55(principal original author of dtc and libfdt)
562 November 2007
57
README.version