From b33a73c62c1cd1e6062dc5416037accdc8a90b5e Mon Sep 17 00:00:00 2001 From: David Gibson Date: Thu, 28 Jul 2022 15:51:32 +1000 Subject: [PATCH] Convert README to README.md Let's move vaguely into the twenty-first century by converting our old plain text README file to Markdown. While we're updating the formatting, make some small polish changes to the content. Signed-off-by: David Gibson --- README | 106 ----------------------------------------------- README.md | 120 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 120 insertions(+), 106 deletions(-) delete mode 100644 README create mode 100644 README.md diff --git a/README b/README deleted file mode 100644 index a48312a..0000000 --- a/README +++ /dev/null @@ -1,106 +0,0 @@ -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 -Jon Loeliger - - -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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..30212bc --- /dev/null +++ b/README.md @@ -0,0 +1,120 @@ +# Device Tree Compiler and libfdt + +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 ``](mailto:david@gibson.dropbear.id.au) +* [Jon Loeliger ``](mailto:loeliger@gmail.com) + +## Python library + +A Python library wrapping libfdt 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 lists + +* The [devicetree-compiler](mailto:devicetree-compiler@vger.kernel.org) + list is for discussion about dtc and libfdt implementation. +* Core device tree bindings are discussed on the + [devicetree-spec](mailto:devicetree-spec@vger.kernel.org) list. +