[PATCH 6/6] Documentation: document barebox device tree handling

[Ahmad Fatoum <a.fatoum@pengutronix.de>]

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>
---
 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@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox