diff options
author | Ahmad Fatoum <a.fatoum@pengutronix.de> | 2019-09-23 14:10:18 +0200 |
---|---|---|
committer | Sascha Hauer <s.hauer@pengutronix.de> | 2019-10-02 08:48:03 +0200 |
commit | ca61d55f8e4a4ce1e2ebf850699c756a19324d83 (patch) | |
tree | 93cc8562637b0b1dad5f2f8f40464e6cc80c8397 /Documentation/devicetree/index.rst | |
parent | 9d0469550097b84c7b0cae5179e6297f0ce9b34c (diff) | |
download | barebox-ca61d55f8e4a4ce1e2ebf850699c756a19324d83.tar.gz barebox-ca61d55f8e4a4ce1e2ebf850699c756a19324d83.tar.xz |
Documentation: document barebox device tree handling
The way barebox handles the Linux device trees and the device tree
compiler source included in the source tree may not be obvious
to new developers. Add a basic high-level documentation.
Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
Signed-off-by: Sascha Hauer <s.hauer@pengutronix.de>
Diffstat (limited to 'Documentation/devicetree/index.rst')
-rw-r--r-- | Documentation/devicetree/index.rst | 59 |
1 files changed, 57 insertions, 2 deletions
diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index c6309defdf..908652642b 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -1,5 +1,60 @@ -Barebox specific devicetree bindings -==================================== +Barebox devicetree handling and bindings +======================================== + +The preferred way of adding board support to barebox is to have devices +on non-enumerable buses probed from device tree. +barebox imports the Linux OpenFirmware ``of_*``-API functions for device tree +parsing, which makes porting the device tree specific bits from device drivers +very straight forward. + +Additionally, barebox has support for programmatically fixing up device trees +it passes to the kernel, either directly via ``of_register_fixup`` or via device +tree overlays. + +Upstream Device Trees +--------------------- + +barebox regularly synchronizes with the Linux kernel device tree definitions +via the `kernel.org Split device-tree repository`_. +They are located under the top-level ``dts/`` directory. + +Patches against ``dts/`` and its subdirectories are not accepted upstream. + +.. _kernel.org Split device-tree repository: https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git/ + +barebox Device Trees +-------------------- + +For supporting architectures, barebox device trees are located in +``arch/$ARCH/dts``. Usually the barebox ``board.dts`` imports the upstream +device tree under ``dts/src/$ARCH`` with ``#include "$ARCH/board.dts"`` and +then extends it with barebox-specifics like :ref:`barebox,state`, +environment or boot-time device configuration. + +Device Tree Compiler +-------------------- + +barebox makes use of the ``dtc`` and ``fdtget`` and the underlying ``libfdt`` +from the `Device-Tree Compiler`_ project. + +.. _Device-Tree Compiler: https://git.kernel.org/pub/scm/utils/dtc/dtc.git + +These utilities are built as part of the barebox build process. Additionally, +libfdt is compiled once more as part of the ``CONFIG_BOARD_ARM_GENERIC_DT`` +if selected. + +Steps to update ``scripts/dtc``: + +* Place a ``git-checkout`` of the upstream ``dtc`` directory in the parent + directory of your barebox ``git-checkout``. +* Run ``scripts/dtc/update-dtc-source.sh`` from the top-level barebox directory. +* Wait till ``dtc`` build, test, install and commit conclude. +* Compile-test with ``CONFIG_BOARD_ARM_GENERIC_DT=y``. +* If ``scripts/dtc/Makefile`` or barebox include file changes are necessary, + apply them manually in a commit preceding the ``dtc`` update. + +barebox-specific Bindings +------------------------- Contents: |