scripts/dtc/README

   1 The source tree contains the Device Tree Compiler (dtc) toolchain for
   2 working with device tree source and binary files and also libfdt, a
   3 utility library for reading and manipulating the binary format.
   4
   5 DTC and LIBFDT are maintained by:
   6
   7 David Gibson <[email protected]>
   8 Jon Loeliger <[email protected]>
   9
  10
  11 Python library
  12 --------------
  13
  14 A Python library is also available. To build this you will need to install
  15 swig and Python development files. On Debian distributions:
  16
  17    sudo apt-get install swig python3-dev
  18
  19 The 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)
  26 124
  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()))
  30 compatible=subnode1
  31 >>> node2 = fdt.path_offset('/')
  32 >>> print(fdt.getprop(node2, 'compatible').as_str())
  33 test_tree1
  34
  35 You will find tests in tests/pylibfdt_tests.py showing how to use each
  36 method. Help is available using the Python help command, e.g.:
  37
  38     $ cd pylibfdt
  39     $ python3 -c "import libfdt; help(libfdt)"
  40
  41 If 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
  51 The library can be installed with pip from a local source tree:
  52
  53     pip install . [--user|--prefix=/path/to/install_dir]
  54
  55 Or directly from a remote git repo:
  56
  57     pip install git+git://git.kernel.org/pub/scm/utils/dtc/dtc.git@main
  58
  59 The install depends on libfdt shared library being installed on the host system
  60 first. Generally, using --user or --prefix is not necessary and pip will use the
  61 default location for the Python installation which varies if the user is root or
  62 not.
  63
  64 You can also install everything via make if you like, but pip is recommended.
  65
  66 To install both libfdt and pylibfdt you can use:
  67
  68     make install [PREFIX=/path/to/install_dir]
  69
  70 To disable building the python library, even if swig and Python are available,
  71 use:
  72
  73     make NO_PYTHON=1
  74
  75
  76 More work remains to support all of libfdt, including access to numeric
  77 values.
  78
  79
  80 Adding a new function to libfdt.h
  81 ---------------------------------
  82
  83 The shared library uses libfdt/version.lds to list the exported functions, so
  84 add your new function there. Check that your function works with pylibfdt. If
  85 it cannot be supported, put the declaration in libfdt.h behind #ifndef SWIG so
  86 that swig ignores it.
  87
  88
  89 Tests
  90 -----
  91
  92 Test files are kept in the tests/ directory. Use 'make check' to build and run
  93 all tests.
  94
  95 If you want to adjust a test file, be aware that tree_tree1.dts is compiled
  96 and checked against a binary tree from assembler macros in trees.S. So
  97 if you change that file you must change tree.S also.
  98
  99
 100 Mailing list
 101 ------------
 102 The following list is for discussion about dtc and libfdt implementation
 103 mailto:[email protected]
 104
 105 Core device tree bindings are discussed on the devicetree-spec list:
 106 mailto:[email protected]