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 <loeliger@gmail.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 python3-dev
18
19The library provides an Fdt class which you can use like this:
20
21$ PYTHONPATH=../pylibfdt python3
22>>> import libfdt
23>>> fdt = libfdt.Fdt(open('test_tree1.dtb', mode='rb').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=%s' % (prop.name, prop.as_str()))
30compatible=subnode1
31>>> node2 = fdt.path_offset('/')
32>>> print(fdt.getprop(node2, 'compatible').as_str())
33test_tree1
34
35You will find tests in tests/pylibfdt_tests.py showing how to use each
36method. Help is available using the Python help command, e.g.:
37
38    $ cd pylibfdt
39    $ python3 -c "import libfdt; help(libfdt)"
40
41If you add new features, please check code coverage:
42
43    $ sudo apt-get install python3-coverage
44    $ cd tests
45    # It's just 'coverage' on most other distributions
46    $ python3-coverage run pylibfdt_tests.py
47    $ python3-coverage html
48    # Open 'htmlcov/index.html' in your browser
49
50
51The library can be installed with pip from a local source tree:
52
53    pip install . [--user|--prefix=/path/to/install_dir]
54
55Or directly from a remote git repo:
56
57    pip install git+git://git.kernel.org/pub/scm/utils/dtc/dtc.git@main
58
59The install depends on libfdt shared library being installed on the host system
60first. Generally, using --user or --prefix is not necessary and pip will use the
61default location for the Python installation which varies if the user is root or
62not.
63
64You can also install everything via make if you like, but pip is recommended.
65
66To install both libfdt and pylibfdt you can use:
67
68    make install [PREFIX=/path/to/install_dir]
69
70To disable building the python library, even if swig and Python are available,
71use:
72
73    make NO_PYTHON=1
74
75
76More work remains to support all of libfdt, including access to numeric
77values.
78
79
80Adding a new function to libfdt.h
81---------------------------------
82
83The shared library uses libfdt/version.lds to list the exported functions, so
84add your new function there. Check that your function works with pylibfdt. If
85it cannot be supported, put the declaration in libfdt.h behind #ifndef SWIG so
86that swig ignores it.
87
88
89Tests
90-----
91
92Test files are kept in the tests/ directory. Use 'make check' to build and run
93all tests.
94
95If you want to adjust a test file, be aware that tree_tree1.dts is compiled
96and checked against a binary tree from assembler macros in trees.S. So
97if you change that file you must change tree.S also.
98
99
100Mailing list
101------------
102The following list is for discussion about dtc and libfdt implementation
103mailto:devicetree-compiler@vger.kernel.org
104
105Core device tree bindings are discussed on the devicetree-spec list:
106mailto:devicetree-spec@vger.kernel.org
107