diff --git a/scripts/dtc/README b/scripts/dtc/README new file mode 100644 index 0000000000..a48312a422 --- /dev/null +++ b/scripts/dtc/README @@ -0,0 +1,106 @@ +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/scripts/dtc/pylibfdt/Makefile b/scripts/dtc/pylibfdt/Makefile index a7579f0c5f..e442d5c242 100644 --- a/scripts/dtc/pylibfdt/Makefile +++ b/scripts/dtc/pylibfdt/Makefile @@ -13,11 +13,14 @@ include $(LIBFDT_srcdir)/Makefile.libfdt PYLIBFDT_srcs = $(addprefix $(LIBFDT_srcdir)/,$(LIBFDT_SRCS)) \ $(obj)/libfdt.i +# create a version string compliant with PEP 440 +PEP_VERSION = $(VERSION)$(if $(PATCHLEVEL),.$(PATCHLEVEL)$(if $(SUBLEVEL),.$(SUBLEVEL)))$(subst -,,$(EXTRAVERSION)) + quiet_cmd_pymod = PYMOD $@ cmd_pymod = unset CROSS_COMPILE; unset CFLAGS; \ CC="$(HOSTCC)" LDSHARED="$(HOSTCC) -shared " \ LDFLAGS="$(HOSTLDFLAGS)" \ - VERSION="$(UBOOTVERSION)" \ + VERSION="$(PEP_VERSION)" \ CPPFLAGS="$(HOSTCFLAGS) -I$(LIBFDT_srcdir)" OBJDIR=$(obj) \ SOURCES="$(PYLIBFDT_srcs)" \ SWIG_OPTS="-I$(LIBFDT_srcdir) -I$(LIBFDT_srcdir)/.." \ diff --git a/scripts/dtc/pylibfdt/setup.py b/scripts/dtc/pylibfdt/setup.py index 992cdec30f..ec1fc5002b 100755 --- a/scripts/dtc/pylibfdt/setup.py +++ b/scripts/dtc/pylibfdt/setup.py @@ -1,11 +1,13 @@ #!/usr/bin/env python3 +# SPDX-License-Identifier: (GPL-2.0-or-later OR BSD-2-Clause) """ setup.py file for SWIG libfdt Copyright (C) 2017 Google, Inc. Written by Simon Glass -SPDX-License-Identifier: GPL-2.0+ BSD-2-Clause +This script is modified from the upstream version, to fit in with the U-Boot +build system. Files to be built into the extension are provided in SOURCES C flags to use are provided in CPPFLAGS @@ -18,14 +20,29 @@ allows this script to be run stand-alone, e.g.: ./pylibfdt/setup.py install [--prefix=...] """ -from distutils.core import setup, Extension +from setuptools import setup, Extension +from setuptools.command.build_py import build_py as _build_py import os import re import sys +srcdir = os.path.dirname(__file__) + +with open(os.path.join(srcdir, "../README"), "r") as fh: + long_description = fh.read() + # Decodes a Makefile assignment line into key and value (and plus for +=) RE_KEY_VALUE = re.compile('(?P\w+) *(?P[+])?= *(?P.*)$') +def get_top_builddir(): + if '--top-builddir' in sys.argv: + index = sys.argv.index('--top-builddir') + sys.argv.pop(index) + return sys.argv.pop(index) + else: + return os.path.join(srcdir, '..') + +top_builddir = get_top_builddir() def ParseMakefile(fname): """Parse a Makefile to obtain its variables. @@ -86,7 +103,7 @@ def GetEnvFromMakefiles(): makevars = ParseMakefile(os.path.join(basedir, 'libfdt', 'Makefile.libfdt')) files = makevars['LIBFDT_SRCS'].split() files = [os.path.join(basedir, 'libfdt', fname) for fname in files] - files.append('pylibfdt/libfdt.i') + files.append('libfdt.i') cflags = ['-I%s' % basedir, '-I%s/libfdt' % basedir] objdir = '' return swig_opts, version, files, cflags, objdir @@ -107,17 +124,39 @@ if not all((swig_opts, version, files, cflags, objdir)): libfdt_module = Extension( '_libfdt', - sources = files, - extra_compile_args = cflags, - swig_opts = swig_opts, + sources=files, + include_dirs=[os.path.join(srcdir, 'libfdt')], + library_dirs=[os.path.join(top_builddir, 'libfdt')], + swig_opts=swig_opts, ) +class build_py(_build_py): + def run(self): + self.run_command("build_ext") + return super().run() + setup( name='libfdt', - version= version, - author='Simon Glass ', + version=version, + cmdclass = {'build_py' : build_py}, + author='Simon Glass', + author_email='sjg@chromium.org', description='Python binding for libfdt', ext_modules=[libfdt_module], package_dir={'': objdir}, - py_modules=['pylibfdt/libfdt'], + py_modules=['libfdt'], + + long_description=long_description, + long_description_content_type="text/plain", + url="https://git.kernel.org/pub/scm/utils/dtc/dtc.git", + license="BSD", + license_files=["GPL", "BSD-2-Clause"], + + classifiers=[ + "Programming Language :: Python :: 3", + "License :: OSI Approved :: BSD License", + "License :: OSI Approved :: GNU General Public License v2 or later (GPLv2+)", + "Operating System :: OS Independent", + ], + )