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@xxxxxxxxxxxxxx> --- Documentation/devicetree/index.rst | 56 ++++++++++++++++++++++++++++-- 1 file changed, 54 insertions(+), 2 deletions(-) diff --git a/Documentation/devicetree/index.rst b/Documentation/devicetree/index.rst index c6309defdf03..3b911c5a9d42 100644 --- a/Documentation/devicetree/index.rst +++ b/Documentation/devicetree/index.rst @@ -1,5 +1,57 @@ -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 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`` utilities 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. + +Steps to update ``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. +* If ``scripts/dtc/Makefile`` changes are necessary, apply them manually in + a commit preceding the ``dtc`` update. + +barebox-specific Bindings +------------------------- Contents: -- 2.23.0 _______________________________________________ barebox mailing list barebox@xxxxxxxxxxxxxxxxxxx http://lists.infradead.org/mailman/listinfo/barebox
