Commit d8e81bc3 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Rob Herring

docs: dt: convert usage-model.txt to ReST

- Add a SPDX header;
- Adjust document title;
- Use footnoote markups;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to devicetree/index.rst.
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: default avatarLee Jones <lee.jones@linaro.org>
Signed-off-by: default avatarRob Herring <robh@kernel.org>
parent 4ef7f57e
...@@ -7,4 +7,5 @@ Open Firmware and Device Tree ...@@ -7,4 +7,5 @@ Open Firmware and Device Tree
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
usage-model
writing-schema writing-schema
...@@ -11,7 +11,7 @@ architecture. ...@@ -11,7 +11,7 @@ architecture.
It is recommended to read the following documents before moving ahead. It is recommended to read the following documents before moving ahead.
[1] Documentation/devicetree/usage-model.txt [1] Documentation/devicetree/usage-model.rst
[2] http://www.devicetree.org/Device_Tree_Usage [2] http://www.devicetree.org/Device_Tree_Usage
OF Selftest has been designed to test the interface (include/linux/of.h) OF Selftest has been designed to test the interface (include/linux/of.h)
......
.. SPDX-License-Identifier: GPL-2.0
=========================
Linux and the Device Tree Linux and the Device Tree
------------------------- =========================
The Linux usage model for device tree data The Linux usage model for device tree data
Author: Grant Likely <grant.likely@secretlab.ca> :Author: Grant Likely <grant.likely@secretlab.ca>
This article describes how Linux uses the device tree. An overview of This article describes how Linux uses the device tree. An overview of
the device tree data format can be found on the device tree usage page the device tree data format can be found on the device tree usage page
at devicetree.org[1]. at devicetree.org\ [1]_.
[1] http://devicetree.org/Device_Tree_Usage .. [1] http://devicetree.org/Device_Tree_Usage
The "Open Firmware Device Tree", or simply Device Tree (DT), is a data The "Open Firmware Device Tree", or simply Device Tree (DT), is a data
structure and language for describing hardware. More specifically, it structure and language for describing hardware. More specifically, it
...@@ -57,7 +61,7 @@ Tree (FDT) was created which could be passed to the kernel as a binary ...@@ -57,7 +61,7 @@ Tree (FDT) was created which could be passed to the kernel as a binary
blob without requiring a real Open Firmware implementation. U-Boot, blob without requiring a real Open Firmware implementation. U-Boot,
kexec, and other bootloaders were modified to support both passing a kexec, and other bootloaders were modified to support both passing a
Device Tree Binary (dtb) and to modify a dtb at boot time. DT was Device Tree Binary (dtb) and to modify a dtb at boot time. DT was
also added to the PowerPC boot wrapper (arch/powerpc/boot/*) so that also added to the PowerPC boot wrapper (``arch/powerpc/boot/*``) so that
a dtb could be wrapped up with the kernel image to support booting a dtb could be wrapped up with the kernel image to support booting
existing non-DT aware firmware. existing non-DT aware firmware.
...@@ -68,7 +72,7 @@ out of mainline (nios) have some level of DT support. ...@@ -68,7 +72,7 @@ out of mainline (nios) have some level of DT support.
2. Data Model 2. Data Model
------------- -------------
If you haven't already read the Device Tree Usage[1] page, If you haven't already read the Device Tree Usage\ [1]_ page,
then go read it now. It's okay, I'll wait.... then go read it now. It's okay, I'll wait....
2.1 High Level View 2.1 High Level View
...@@ -88,6 +92,7 @@ duplication and make it easier to support a wide range of hardware ...@@ -88,6 +92,7 @@ duplication and make it easier to support a wide range of hardware
with a single kernel image. with a single kernel image.
Linux uses DT data for three major purposes: Linux uses DT data for three major purposes:
1) platform identification, 1) platform identification,
2) runtime configuration, and 2) runtime configuration, and
3) device population. 3) device population.
...@@ -117,7 +122,7 @@ The 'compatible' property contains a sorted list of strings starting ...@@ -117,7 +122,7 @@ The 'compatible' property contains a sorted list of strings starting
with the exact name of the machine, followed by an optional list of with the exact name of the machine, followed by an optional list of
boards it is compatible with sorted from most compatible to least. For boards it is compatible with sorted from most compatible to least. For
example, the root compatible properties for the TI BeagleBoard and its example, the root compatible properties for the TI BeagleBoard and its
successor, the BeagleBoard xM board might look like, respectively: successor, the BeagleBoard xM board might look like, respectively::
compatible = "ti,omap3-beagleboard", "ti,omap3450", "ti,omap3"; compatible = "ti,omap3-beagleboard", "ti,omap3450", "ti,omap3";
compatible = "ti,omap3-beagleboard-xm", "ti,omap3450", "ti,omap3"; compatible = "ti,omap3-beagleboard-xm", "ti,omap3450", "ti,omap3";
...@@ -183,7 +188,7 @@ configuration data like the kernel parameters string and the location ...@@ -183,7 +188,7 @@ configuration data like the kernel parameters string and the location
of an initrd image. of an initrd image.
Most of this data is contained in the /chosen node, and when booting Most of this data is contained in the /chosen node, and when booting
Linux it will look something like this: Linux it will look something like this::
chosen { chosen {
bootargs = "console=ttyS0,115200 loglevel=8"; bootargs = "console=ttyS0,115200 loglevel=8";
...@@ -251,9 +256,9 @@ platform devices roughly correspond to device nodes at the root of the ...@@ -251,9 +256,9 @@ platform devices roughly correspond to device nodes at the root of the
tree and children of simple memory mapped bus nodes. tree and children of simple memory mapped bus nodes.
About now is a good time to lay out an example. Here is part of the About now is a good time to lay out an example. Here is part of the
device tree for the NVIDIA Tegra board. device tree for the NVIDIA Tegra board::
/{ /{
compatible = "nvidia,harmony", "nvidia,tegra20"; compatible = "nvidia,harmony", "nvidia,tegra20";
#address-cells = <1>; #address-cells = <1>;
#size-cells = <1>; #size-cells = <1>;
...@@ -313,7 +318,7 @@ device tree for the NVIDIA Tegra board. ...@@ -313,7 +318,7 @@ device tree for the NVIDIA Tegra board.
i2s-controller = <&i2s1>; i2s-controller = <&i2s1>;
i2s-codec = <&wm8903>; i2s-codec = <&wm8903>;
}; };
}; };
At .init_machine() time, Tegra board support code will need to look at At .init_machine() time, Tegra board support code will need to look at
this DT and decide which nodes to create platform_devices for. this DT and decide which nodes to create platform_devices for.
...@@ -379,13 +384,13 @@ device tree support code reflects that and makes the above example ...@@ -379,13 +384,13 @@ device tree support code reflects that and makes the above example
simpler. The second argument to of_platform_populate() is an simpler. The second argument to of_platform_populate() is an
of_device_id table, and any node that matches an entry in that table of_device_id table, and any node that matches an entry in that table
will also get its child nodes registered. In the Tegra case, the code will also get its child nodes registered. In the Tegra case, the code
can look something like this: can look something like this::
static void __init harmony_init_machine(void) static void __init harmony_init_machine(void)
{ {
/* ... */ /* ... */
of_platform_populate(NULL, of_default_bus_match_table, NULL, NULL); of_platform_populate(NULL, of_default_bus_match_table, NULL, NULL);
} }
"simple-bus" is defined in the Devicetree Specification as a property "simple-bus" is defined in the Devicetree Specification as a property
meaning a simple memory mapped bus, so the of_platform_populate() code meaning a simple memory mapped bus, so the of_platform_populate() code
......
...@@ -74,7 +74,7 @@ struct mfd_cell { ...@@ -74,7 +74,7 @@ struct mfd_cell {
/* /*
* Device Tree compatible string * Device Tree compatible string
* See: Documentation/devicetree/usage-model.txt Chapter 2.2 for details * See: Documentation/devicetree/usage-model.rst Chapter 2.2 for details
*/ */
const char *of_compatible; const char *of_compatible;
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment