[PATCH 1/3] doc: Move devicetree control doc to rST

Simon Glass sjg at chromium.org
Sun Jul 25 18:43:58 CEST 2021


Move this to rST format, largely unchanged to start with. Add an index
for this topic, as well as an empty intro.

Signed-off-by: Simon Glass <sjg at chromium.org>
---

 .../devicetree/control.rst}                   | 50 +++++++++----------
 doc/develop/devicetree/index.rst              | 13 +++++
 doc/develop/devicetree/intro.rst              |  4 ++
 doc/develop/index.rst                         |  1 +
 4 files changed, 43 insertions(+), 25 deletions(-)
 rename doc/{README.fdt-control => develop/devicetree/control.rst} (89%)
 create mode 100644 doc/develop/devicetree/index.rst
 create mode 100644 doc/develop/devicetree/intro.rst

diff --git a/doc/README.fdt-control b/doc/develop/devicetree/control.rst
similarity index 89%
rename from doc/README.fdt-control
rename to doc/develop/devicetree/control.rst
index 424d13fc5b1..1289b6156fe 100644
--- a/doc/README.fdt-control
+++ b/doc/develop/devicetree/control.rst
@@ -1,6 +1,5 @@
-# SPDX-License-Identifier: GPL-2.0+
-#
-# Copyright (c) 2011 The Chromium OS Authors.
+.. SPDX-License-Identifier: GPL-2.0+
+.. sectionauthor:: Copyright 2011 The Chromium OS Authors
 
 Device Tree Control in U-Boot
 =============================
@@ -37,9 +36,7 @@ What is a Flat Device Tree?
 ---------------------------
 
 An fdt can be specified in source format as a text file. To read about
-the fdt syntax, take a look at the specification here:
-
-https://www.power.org/resources/downloads/Power_ePAPR_APPROVED_v1.0.pdf
+the fdt syntax, take a look at the specification (dtspec_).
 
 You also might find this section of the Linux kernel documentation
 useful: (access this in the Linux kernel source code)
@@ -60,18 +57,18 @@ To use this feature you will need to get the device tree compiler. This is
 provided by U-Boot automatically. If you have a system version of dtc
 (typically in the 'device-tree-compiler' package), it is currently not used.
 
-If you want to build your own dtc, it is kept here:
+If you want to build your own dtc, it is kept here::
 
 	git://git.kernel.org/pub/scm/utils/dtc/dtc.git
 
-For example:
+For example::
 
 	$ git clone git://git.kernel.org/pub/scm/utils/dtc/dtc.git
 	$ cd dtc
 	$ make
 	$ sudo make install
 
-Then run the compiler (your version will vary):
+Then run the compiler (your version will vary)::
 
 	$ dtc -v
 	Version: DTC 1.2.0-g2cb4b51f
@@ -105,14 +102,14 @@ Failing that, you could write one from scratch yourself!
 Configuration
 -------------
 
-Use:
+Use::
 
-#define CONFIG_DEFAULT_DEVICE_TREE	"<name>"
+   #define CONFIG_DEFAULT_DEVICE_TREE	"<name>"
 
 to set the filename of the device tree source. Then put your device tree
-file into
+file into::
 
-	board/<vendor>/dts/<name>.dts
+   board/<vendor>/dts/<name>.dts
 
 This should include your CPU or SOC's device tree file, placed in
 arch/<arch>/dts, and then make any adjustments required.
@@ -123,9 +120,9 @@ and development only and is not recommended for production devices.
 
 If CONFIG_OF_SEPARATE is defined, then it will be built and placed in
 a u-boot.dtb file alongside u-boot-nodtb.bin. A common approach is then to
-join the two:
+join the two::
 
-	cat u-boot-nodtb.bin u-boot.dtb >image.bin
+   cat u-boot-nodtb.bin u-boot.dtb >image.bin
 
 and then flash image.bin onto your board. Note that U-Boot creates
 u-boot-dtb.bin which does the above step for you also. Resulting
@@ -144,9 +141,9 @@ specify the file to read.
 You cannot use more than one of these options at the same time.
 
 To use a device tree file that you have compiled yourself, pass
-EXT_DTB=<filename> to 'make', as in:
+EXT_DTB=<filename> to 'make', as in::
 
-	make EXT_DTB=boot/am335x-boneblack-pubkey.dtb
+   make EXT_DTB=boot/am335x-boneblack-pubkey.dtb
 
 Then U-Boot will copy that file to u-boot.dtb, put it in the .img file
 if used, and u-boot-dtb.bin.
@@ -162,16 +159,21 @@ variable will be set to the address of the newly relocated fdt blob.
 It is read-only and cannot be changed. It can optionally be used to
 control the boot process of Linux with bootm/bootz commands.
 
-To use this, put something like this in your board header file:
+To use this, put something like this in your board header file::
 
-#define CONFIG_EXTRA_ENV_SETTINGS	"fdtcontroladdr=10000\0"
+   #define CONFIG_EXTRA_ENV_SETTINGS	"fdtcontroladdr=10000\0"
 
 Build:
 
-After board configuration is done, fdt supported u-boot can be build in two ways:
-1)  build the default dts which is defined from CONFIG_DEFAULT_DEVICE_TREE
+After board configuration is done, fdt supported u-boot can be build in two
+ways:
+
+#  build the default dts which is defined from CONFIG_DEFAULT_DEVICE_TREE::
+
     $ make
-2)  build the user specified dts file
+
+#  build the user specified dts file::
+
     $ make DEVICE_TREE=<dts-file-name>
 
 
@@ -225,6 +227,4 @@ but can use the fdt to specific the UART clock, peripheral address, etc.
 In very broad terms, the CONFIG options in general control *what* driver
 files are pulled in, and the fdt controls *how* those files work.
 
---
-Simon Glass <sjg at chromium.org>
-1-Sep-11
+.. _dtspec: https://www.power.org/resources/downloads/Power_ePAPR_APPROVED_v1.0.pdf
diff --git a/doc/develop/devicetree/index.rst b/doc/develop/devicetree/index.rst
new file mode 100644
index 00000000000..fa5db3eb76e
--- /dev/null
+++ b/doc/develop/devicetree/index.rst
@@ -0,0 +1,13 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Devicetree in U-Boot
+====================
+
+The following holds information on how U-Boot makes use of devicetree for
+build-time and runtime configuration.
+
+.. toctree::
+   :maxdepth: 2
+
+   intro
+   control
diff --git a/doc/develop/devicetree/intro.rst b/doc/develop/devicetree/intro.rst
new file mode 100644
index 00000000000..344851327c7
--- /dev/null
+++ b/doc/develop/devicetree/intro.rst
@@ -0,0 +1,4 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+Devicetree Introduction
+=======================
diff --git a/doc/develop/index.rst b/doc/develop/index.rst
index 54e14dd77b5..1b904189945 100644
--- a/doc/develop/index.rst
+++ b/doc/develop/index.rst
@@ -10,6 +10,7 @@ Implementation
    :maxdepth: 1
 
    commands
+   devicetree/index
    driver-model/index
    global_data
    logging
-- 
2.32.0.432.gabb21c7263-goog



More information about the U-Boot mailing list