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 <david@gibson.dropbear.id.au>
This commit is contained in:
David Gibson
parent
7ad60734b1
commit
b33a73c62c
2 changed files with 120 additions and 106 deletions
106
README
106
README
|
|
@ -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 <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
|
||||
120
README.md
Normal file
120
README.md
Normal file
|
|
@ -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 `<david@gibson.dropbear.id.au>`](mailto:david@gibson.dropbear.id.au)
|
||||
* [Jon Loeliger `<loeliger@gmail.com>`](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.
|
||||
|
||||
Loading…
Reference in a new issue