[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