Convert some DT documentation files to ReST
Subsystems (7)
v2 cover Convert some DT documentation files to ReST
While most of the devicetree stuff has its own format (with is now being converted to YAML format), some documents there are actually describing the DT concepts and how to contribute to it.
IMHO, those documents would fit perfectly as part of the documentation body, as part of the firmare documents set.
This patch series manually converts some DT documents that, on my opinion, would belong to it.
If you want to see how this would show at the documentation body, a sneak peak of this series (together with the other pending doc patches from me) is available at:
https://www.infradead.org/~mchehab/kernel_docs/devicetree/index.html
This series is available on this devel branch:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=dt-docs-20200228
and it is based on next-20200228
-
v2: Fixed my email address and removed extra wrong SoB on all patches.
Mauro Carvalho Chehab (12):
docs: dt: add an index.rst file for devicetree
docs: dt: convert usage-model.txt to ReST
docs: dt: usage_model.rst: fix link for DT usage
docs: dt: convert booting-without-of.txt to ReST format
docs: dt: convert changesets to ReST
docs: dt: convert dynamic-resolution-notes.txt to ReST
docs: dt: convert of_unittest.txt to ReST
docs: dt: convert overlay-notes.txt to ReST format
docs: dt: minor adjustments at writing-schema.rst
docs: dt: convert ABI.txt to ReST format
docs: dt: convert submitting-patches.txt to ReST format
docs: dt: convert writing-bindings.txt to ReST
Documentation/arm/booting.rst | 2 +-
Documentation/arm/microchip.rst | 2 +-
.../devicetree/bindings/{ABI.txt => ABI.rst} | 5 +-
.../devicetree/bindings/arm/amlogic.yaml | 2 +-
.../devicetree/bindings/arm/syna.txt | 2 +-
Documentation/devicetree/bindings/index.rst | 12 +
...ing-patches.txt => submitting-patches.rst} | 12 +-
...ting-bindings.txt => writing-bindings.rst} | 9 +-
...-without-of.txt => booting-without-of.rst} | 299 ++++++++++--------
.../{changesets.txt => changesets.rst} | 24 +-
...notes.txt => dynamic-resolution-notes.rst} | 5 +-
Documentation/devicetree/index.rst | 18 ++
.../{of_unittest.txt => of_unittest.rst} | 186 +++++------
.../{overlay-notes.txt => overlay-notes.rst} | 143 +++++----
.../{usage-model.txt => usage-model.rst} | 35 +-
Documentation/devicetree/writing-schema.rst | 9 +-
Documentation/index.rst | 3 +
Documentation/process/submitting-patches.rst | 2 +-
.../it_IT/process/submitting-patches.rst | 2 +-
Documentation/translations/zh_CN/arm/Booting | 2 +-
MAINTAINERS | 4 +-
include/linux/mfd/core.h | 2 +-
scripts/checkpatch.pl | 2 +-
23 files changed, 446 insertions(+), 336 deletions(-)
rename Documentation/devicetree/bindings/{ABI.txt => ABI.rst} (94%)
create mode 100644 Documentation/devicetree/bindings/index.rst
rename Documentation/devicetree/bindings/{submitting-patches.txt => submitting-patches.rst} (92%)
rename Documentation/devicetree/bindings/{writing-bindings.txt => writing-bindings.rst} (89%)
rename Documentation/devicetree/{booting-without-of.txt => booting-without-of.rst} (90%)
rename Documentation/devicetree/{changesets.txt => changesets.rst} (59%)
rename Documentation/devicetree/{dynamic-resolution-notes.txt => dynamic-resolution-notes.rst} (90%)
create mode 100644 Documentation/devicetree/index.rst
rename Documentation/devicetree/{of_unittest.txt => of_unittest.rst} (54%)
rename Documentation/devicetree/{overlay-notes.txt => overlay-notes.rst} (56%)
rename Documentation/devicetree/{usage-model.txt => usage-model.rst} (97%)Signature · 1 line
2.21.1
PATCH v2 1/12 docs: dt: add an index.rst file for devicetree
There are some device tree documentation under Documentation/devicetree. Add a top index file for it and add the already-existing ReST file on it.
--- Documentation/devicetree/index.rst | 10 ++++++++++ Documentation/index.rst | 3 +++ 2 files changed, 13 insertions(+) create mode 100644 Documentation/devicetree/index.rst
Documentation/devicetree/index.rst new file +10 -0
@@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================= +Open Firmware and Device Tree +============================= + +.. toctree:: + :maxdepth: 1 + + writing-schema
Documentation/index.rst +3 -0
@@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + .. The Linux Kernel documentation master file, created by sphinx-quickstart on Fri Feb 12 13:51:46 2016.
@@ -46,6 +48,7 @@ platform firmwares. :maxdepth: 2 firmware-guide/index + devicetree/index Application-developer documentation -----------------------------------
Signature · 1 line
2.21.1
PATCH v2 2/12 docs: dt: convert usage-model.txt to ReST
In reply to Mauro Carvalho Chehab- 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.
---
Documentation/devicetree/index.rst | 1 +
Documentation/devicetree/of_unittest.txt | 2 +-
.../{usage-model.txt => usage-model.rst} | 35 +++++++++++--------
include/linux/mfd/core.h | 2 +-
4 files changed, 23 insertions(+), 17 deletions(-)
rename Documentation/devicetree/{usage-model.txt => usage-model.rst} (97%)Documentation/devicetree/index.rst +1 -0
@@ -7,4 +7,5 @@ Open Firmware and Device Tree .. toctree:: :maxdepth: 1 + usage-model writing-schema
Documentation/devicetree/of_unittest.txt +1 -1
@@ -11,7 +11,7 @@ architecture. 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 OF Selftest has been designed to test the interface (include/linux/of.h)
Documentation/devicetree/usage-model.rst renamed from Documentation/devicetree/usage-model.txt +20 -15
@@ -1,14 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= Linux and the Device Tree -------------------------- +========================= + The Linux usage model for device tree data -Author: Grant Likely <[email protected]> +:Author: Grant Likely <[email protected]> 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 -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 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 blob without requiring a real Open Firmware implementation. U-Boot, 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 -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 existing non-DT aware firmware.
@@ -68,7 +72,7 @@ out of mainline (nios) have some level of DT support. 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.... 2.1 High Level View
@@ -88,6 +92,7 @@ duplication and make it easier to support a wide range of hardware with a single kernel image. Linux uses DT data for three major purposes: + 1) platform identification, 2) runtime configuration, and 3) device population.
@@ -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 boards it is compatible with sorted from most compatible to least. For 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-xm", "ti,omap3450", "ti,omap3";
@@ -183,7 +188,7 @@ configuration data like the kernel parameters string and the location of an initrd image. 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 { bootargs = "console=ttyS0,115200 loglevel=8";
@@ -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. 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"; #address-cells = <1>; #size-cells = <1>;
@@ -313,7 +318,7 @@ device tree for the NVIDIA Tegra board. i2s-controller = <&i2s1>; i2s-codec = <&wm8903>; }; -}; + }; At .init_machine() time, Tegra board support code will need to look at 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 simpler. The second argument to of_platform_populate() is an 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 -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); -} + } "simple-bus" is defined in the Devicetree Specification as a property meaning a simple memory mapped bus, so the of_platform_populate() code
include/linux/mfd/core.h +1 -1
@@ -74,7 +74,7 @@ struct mfd_cell {/* * 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;
Signature · 1 line
2.21.1
Re: [PATCH v2 02/12] docs: dt: convert usage-model.txt to ReST
Quoted 7 lines · Mauro Carvalho Chehab
- Add a SPDX header;
- Adjust document title;
- Use footnoote markups;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it todevicetree/index.rst.
Quoted 7 lines
Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/devicetree/index.rst | 1 + Documentation/devicetree/of_unittest.txt | 2 +- .../{usage-model.txt => usage-model.rst} | 35 +++++++++++--------include/linux/mfd/core.h | 2 +-
Quoted 2 lines
4 files changed, 23 insertions(+), 17 deletions(-)
rename Documentation/devicetree/{usage-model.txt => usage-model.rst} (97%)Signature · 4 lines
Lee Jones [李琼斯] Linaro Services Technical Lead Linaro.org │ Open source software for ARM SoCs Follow Linaro: Facebook | Twitter | Blog
Re: [PATCH v2 02/12] docs: dt: convert usage-model.txt to ReST
In reply to Mauro Carvalho ChehabQuoted 31 lines · Mauro Carvalho Chehab
- Add a SPDX header;
- Adjust document title;
- Use footnoote markups;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it todevicetree/index.rst.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/devicetree/index.rst | 1 + Documentation/devicetree/of_unittest.txt | 2 +- .../{usage-model.txt => usage-model.rst} | 35 +++++++++++-------- include/linux/mfd/core.h | 2 +- 4 files changed, 23 insertions(+), 17 deletions(-) rename Documentation/devicetree/{usage-model.txt => usage-model.rst} (97%)Documentation/devicetree/index.rst +1
-0@@ -7,4 +7,5 @@ Open Firmware and Device Tree .. toctree:: :maxdepth: 1 + usage-model writing-schemaDocumentation/devicetree/of_unittest.txt +0
-0
Documentation/devicetree/of_unittest.txt architecture. · line 15
Quoted 6 lines
Documentation/devicetree/of_unittest.txt +1
-1@@ -11,7 +11,7 @@ architecture. 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
You caught this in 03/12. The file has moved to:
Quoted 19 lines
Documentation/devicetree/of_unittest.txt +0
-0OF Selftest has been designed to test the interface (include/linux/of.h)Documentation/devicetree/usage-model.rst renamed from Documentation/devicetree/usage-model.txt +5
-1@@ -1,14 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= Linux and the Device Tree -------------------------- +========================= + The Linux usage model for device tree data
Documentation/devicetree/usage-model.rst line 15
Quoted 10 lines
Documentation/devicetree/usage-model.rst renamed from Documentation/devicetree/usage-model.txt +3
-3-Author: Grant Likely <[email protected]> +:Author: Grant Likely <[email protected]> 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 -at devicetree.org[1]. +at devicetree.org\ [1]_. -[1] http://devicetree.org/Device_Tree_Usage +.. [1] http://devicetree.org/Device_Tree_Usage
And same moved location here.
-Frank
Quoted 100 lines
Documentation/devicetree/usage-model.rst renamed from Documentation/devicetree/usage-model.txt +12
-11The "Open Firmware Device Tree", or simply Device Tree (DT), is a data 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 blob without requiring a real Open Firmware implementation. U-Boot, 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 -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 existing non-DT aware firmware.@@ -68,7 +72,7 @@ out of mainline (nios) have some level of DT support. 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.... 2.1 High Level View@@ -88,6 +92,7 @@ duplication and make it easier to support a wide range of hardware with a single kernel image. Linux uses DT data for three major purposes: + 1) platform identification, 2) runtime configuration, and 3) device population.@@ -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 boards it is compatible with sorted from most compatible to least. For 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-xm", "ti,omap3450", "ti,omap3";@@ -183,7 +188,7 @@ configuration data like the kernel parameters string and the location of an initrd image. 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 { bootargs = "console=ttyS0,115200 loglevel=8";@@ -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. 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"; #address-cells = <1>; #size-cells = <1>;@@ -313,7 +318,7 @@ device tree for the NVIDIA Tegra board. i2s-controller = <&i2s1>; i2s-codec = <&wm8903>; }; -}; + }; At .init_machine() time, Tegra board support code will need to look at 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 simpler. The second argument to of_platform_populate() is an 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 -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); -} + } "simple-bus" is defined in the Devicetree Specification as a property meaning a simple memory mapped bus, so the of_platform_populate() codeinclude/linux/mfd/core.h +1
-1@@ -74,7 +74,7 @@ struct mfd_cell {/* * 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;
Re: [PATCH v2 02/12] docs: dt: convert usage-model.txt to ReST
Em Mon, 2 Mar 2020 15:11:07 -0600
Frank Rowand <[email protected]> escreveu:
Quoted 35 lines · Mauro Carvalho Chehab
Quoted 34 lines
- Add a SPDX header;
- Adjust document title;
- Use footnoote markups;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it todevicetree/index.rst.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/devicetree/index.rst | 1 + Documentation/devicetree/of_unittest.txt | 2 +- .../{usage-model.txt => usage-model.rst} | 35 +++++++++++-------- include/linux/mfd/core.h | 2 +- 4 files changed, 23 insertions(+), 17 deletions(-) rename Documentation/devicetree/{usage-model.txt => usage-model.rst} (97%)Documentation/devicetree/index.rst +1
-0@@ -7,4 +7,5 @@ Open Firmware and Device Tree .. toctree:: :maxdepth: 1 + usage-model writing-schemaDocumentation/devicetree/of_unittest.txt +0
-0@@ -11,7 +11,7 @@ architecture. It is recommended to read the following documents before moving ahead.
Quoted 7 lines
Documentation/devicetree/of_unittest.txt architecture. · line 15
Quoted 3 lines
Documentation/devicetree/of_unittest.txt +1
-1-[1] Documentation/devicetree/usage-model.txt +[1] Documentation/devicetree/usage-model.rst [2] http://www.devicetree.org/Device_Tree_UsageYou caught this in 03/12. The file has moved to:
Thanks for noticing it!
In order to make the changelogs clearer, instead of modifying this patch, I'll add an extra hook on patch 03/12 also changing this one.
Quoted 28 lines
Quoted 28 lines
Documentation/devicetree/of_unittest.txt +0
-0OF Selftest has been designed to test the interface (include/linux/of.h)Documentation/devicetree/usage-model.rst renamed from Documentation/devicetree/usage-model.txt +7
-3@@ -1,14 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= Linux and the Device Tree -------------------------- +========================= + The Linux usage model for device tree data -Author: Grant Likely <[email protected]> +:Author: Grant Likely <[email protected]> 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 -at devicetree.org[1]. +at devicetree.org\ [1]_.
Quoted 4 lines
Documentation/devicetree/usage-model.rst line 15
Quoted 2 lines
Documentation/devicetree/usage-model.rst renamed from Documentation/devicetree/usage-model.txt +1
-1-[1] http://devicetree.org/Device_Tree_Usage +.. [1] http://devicetree.org/Device_Tree_UsageAnd same moved location here.
And this one too.
Quoted 2 lines
-Frank
Re: [PATCH v2 02/12] docs: dt: convert usage-model.txt to ReST
In reply to Mauro Carvalho ChehabQuoted 56 lines · Mauro Carvalho Chehab
- Add a SPDX header;
- Adjust document title;
- Use footnoote markups;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it todevicetree/index.rst.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/devicetree/index.rst | 1 + Documentation/devicetree/of_unittest.txt | 2 +- .../{usage-model.txt => usage-model.rst} | 35 +++++++++++-------- include/linux/mfd/core.h | 2 +- 4 files changed, 23 insertions(+), 17 deletions(-) rename Documentation/devicetree/{usage-model.txt => usage-model.rst} (97%)Documentation/devicetree/index.rst +1
-0@@ -7,4 +7,5 @@ Open Firmware and Device Tree .. toctree:: :maxdepth: 1 + usage-model writing-schemaDocumentation/devicetree/of_unittest.txt +1
-1@@ -11,7 +11,7 @@ architecture. 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 OF Selftest has been designed to test the interface (include/linux/of.h)Documentation/devicetree/usage-model.rst renamed from Documentation/devicetree/usage-model.txt +5
-1@@ -1,14 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= Linux and the Device Tree -------------------------- +========================= + The Linux usage model for device tree data
Documentation/devicetree/usage-model.rst line 15
Quoted 10 lines
Documentation/devicetree/usage-model.rst renamed from Documentation/devicetree/usage-model.txt +3
-3-Author: Grant Likely <[email protected]> +:Author: Grant Likely <[email protected]> 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 -at devicetree.org[1]. +at devicetree.org\ [1]_. -[1] http://devicetree.org/Device_Tree_Usage +.. [1] http://devicetree.org/Device_Tree_Usage
I don't know the proper ReST syntax for footnotes, but on the html page you kindly provided in 00/12, '.. [1]' is shown as '1(1,2)'.
-Frank
Quoted 100 lines
Documentation/devicetree/usage-model.rst renamed from Documentation/devicetree/usage-model.txt +12
-11The "Open Firmware Device Tree", or simply Device Tree (DT), is a data 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 blob without requiring a real Open Firmware implementation. U-Boot, 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 -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 existing non-DT aware firmware.@@ -68,7 +72,7 @@ out of mainline (nios) have some level of DT support. 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.... 2.1 High Level View@@ -88,6 +92,7 @@ duplication and make it easier to support a wide range of hardware with a single kernel image. Linux uses DT data for three major purposes: + 1) platform identification, 2) runtime configuration, and 3) device population.@@ -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 boards it is compatible with sorted from most compatible to least. For 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-xm", "ti,omap3450", "ti,omap3";@@ -183,7 +188,7 @@ configuration data like the kernel parameters string and the location of an initrd image. 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 { bootargs = "console=ttyS0,115200 loglevel=8";@@ -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. 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"; #address-cells = <1>; #size-cells = <1>;@@ -313,7 +318,7 @@ device tree for the NVIDIA Tegra board. i2s-controller = <&i2s1>; i2s-codec = <&wm8903>; }; -}; + }; At .init_machine() time, Tegra board support code will need to look at 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 simpler. The second argument to of_platform_populate() is an 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 -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); -} + } "simple-bus" is defined in the Devicetree Specification as a property meaning a simple memory mapped bus, so the of_platform_populate() codeinclude/linux/mfd/core.h +1
-1@@ -74,7 +74,7 @@ struct mfd_cell {/* * 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;
Re: [PATCH v2 02/12] docs: dt: convert usage-model.txt to ReST
Em Mon, 2 Mar 2020 15:18:51 -0600
Frank Rowand <[email protected]> escreveu:
Quoted 65 lines · Mauro Carvalho Chehab
Quoted 64 lines
- Add a SPDX header;
- Adjust document title;
- Use footnoote markups;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it todevicetree/index.rst.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/devicetree/index.rst | 1 + Documentation/devicetree/of_unittest.txt | 2 +- .../{usage-model.txt => usage-model.rst} | 35 +++++++++++-------- include/linux/mfd/core.h | 2 +- 4 files changed, 23 insertions(+), 17 deletions(-) rename Documentation/devicetree/{usage-model.txt => usage-model.rst} (97%)Documentation/devicetree/index.rst +1
-0@@ -7,4 +7,5 @@ Open Firmware and Device Tree .. toctree:: :maxdepth: 1 + usage-model writing-schemaDocumentation/devicetree/of_unittest.txt +1
-1@@ -11,7 +11,7 @@ architecture. 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 OF Selftest has been designed to test the interface (include/linux/of.h)Documentation/devicetree/usage-model.rst renamed from Documentation/devicetree/usage-model.txt +7
-3@@ -1,14 +1,18 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= Linux and the Device Tree -------------------------- +========================= + The Linux usage model for device tree data -Author: Grant Likely <[email protected]> +:Author: Grant Likely <[email protected]> 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 -at devicetree.org[1]. +at devicetree.org\ [1]_.
Quoted 7 lines
Documentation/devicetree/usage-model.rst line 15
Quoted 2 lines
Documentation/devicetree/usage-model.rst renamed from Documentation/devicetree/usage-model.txt +1
-1-[1] http://devicetree.org/Device_Tree_Usage +.. [1] http://devicetree.org/Device_Tree_UsageI don't know the proper ReST syntax for footnotes, but on the html page you kindly provided in 00/12, '.. [1]' is shown as '1(1,2)'.
-Frank
The syntax is simple: just add an underline at the end, when referencing it, like [1]_. The definitions should start with "..", like ".. [1] something".
Sphinx will automatically generate the reverse reference(s) at the html output.
Yet, sometimes (like the above), it needs to be escaped by a "\ ", as ReST would recognize "foo[1]_" as something else.
Ps.: it also accepts an "auto-numbered" references like [#]_, but such syntax require some care, in order to avoid wrong cross-references.
Regards,
Mauro
PATCH v2 3/12 docs: dt: usage_model.rst: fix link for DT usage
In reply to Mauro Carvalho ChehabThe devicetree.org doesn't host the Device_Tree_Usage page anymore. So, fix the link to point to a new address.
--- Documentation/devicetree/usage-model.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/devicetree/usage-model.rst +1 -1
@@ -12,7 +12,7 @@ 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 at devicetree.org\ [1]_. -.. [1] http://devicetree.org/Device_Tree_Usage +.. [1] https://elinux.org/Device_Tree_Usage The "Open Firmware Device Tree", or simply Device Tree (DT), is a data structure and language for describing hardware. More specifically, it
Signature · 1 line
2.21.1
Re: [PATCH v2 03/12] docs: dt: usage_model.rst: fix link for DT usage
Quoted 13 lines · Mauro Carvalho Chehab
The devicetree.org doesn't host the
Device_Tree_Usagepage anymore. So, fix the link to point to a new address.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/devicetree/usage-model.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Documentation/devicetree/usage-model.rst +0
-0
Documentation/devicetree/usage-model.rst This article describes how Linux uses the device tree. An overview of · line 13
Quoted 2 lines
Documentation/devicetree/usage-model.rst +0
-0@@ -12,7 +12,7 @@ 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 at devicetree.org\ [1]_.
s/devicetree.org/elinux.org/
Quoted 7 lines
Documentation/devicetree/usage-model.rst +1
-1-.. [1] http://devicetree.org/Device_Tree_Usage +.. [1] https://elinux.org/Device_Tree_Usage The "Open Firmware Device Tree", or simply Device Tree (DT), is a data structure and language for describing hardware. More specifically, it
Re: [PATCH v2 03/12] docs: dt: usage_model.rst: fix link for DT usage
Quoted 10 lines · Frank Rowand
Quoted 8 lines · Mauro Carvalho Chehab
The devicetree.org doesn't host the
Device_Tree_Usagepage anymore. So, fix the link to point to a new address.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/devicetree/usage-model.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Quoted 9 lines
Documentation/devicetree/usage-model.rst This article describes how Linux uses the device tree. An overview of · line 13
Quoted 7 lines
Documentation/devicetree/usage-model.rst +0
-0@@ -12,7 +12,7 @@ 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 at devicetree.org\ [1]_.s/devicetree.org/elinux.org/
I wonder if we should make the devicetree.org link work again instead. Primarily just to avoid the appearance of it being Linux specific.
The website is hosted on github[1] and I'd assume there's a way to do redirects as a start.
Rob
Re: [PATCH v2 03/12] docs: dt: usage_model.rst: fix link for DT usage
Em Mon, 2 Mar 2020 15:40:37 -0600
Rob Herring <[email protected]> escreveu:
Quoted 21 lines · Frank Rowand
Quoted 10 lines · Mauro Carvalho Chehab
Quoted 8 lines
The devicetree.org doesn't host the
Device_Tree_Usagepage anymore. So, fix the link to point to a new address.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/devicetree/usage-model.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)Quoted 9 lines
Documentation/devicetree/usage-model.rst This article describes how Linux uses the device tree. An overview of · line 13
Quoted 7 lines
Documentation/devicetree/usage-model.rst +0
-0@@ -12,7 +12,7 @@ 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 at devicetree.org\ [1]_.s/devicetree.org/elinux.org/
Quoted 2 lines
I wonder if we should make the devicetree.org link work again instead. Primarily just to avoid the appearance of it being Linux specific.
Makes sense to me. Another alternative would be to convert this file to ReST and add to the Kernel docs (it should be easy to convert with pandoc).
Yet, as those references are part of the Linux Kernel documentation, it doesn't sound wrong to me to have them pointing to a linux-specific site.
In any case, I'll update this patch, placing all such changes altogether. This way, if you decide to re-add this at devicetree.org, we could simply drop (or revert) it.
Quoted 7 lines
The website is hosted on github[1] and I'd assume there's a way to do redirects as a start.
Rob
PATCH v2 4/12 docs: dt: convert booting-without-of.txt to ReST format
In reply to Mauro Carvalho Chehab- Add a SPDX header;
- Use copyright symbol;
- Adjust document title;
- Adjust document and section titles;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it to devicetree/index.rst.
---
Documentation/arm/booting.rst | 2 +-
...-without-of.txt => booting-without-of.rst} | 299 ++++++++++--------
Documentation/devicetree/index.rst | 1 +
Documentation/translations/zh_CN/arm/Booting | 2 +-
4 files changed, 169 insertions(+), 135 deletions(-)
rename Documentation/devicetree/{booting-without-of.txt => booting-without-of.rst} (90%)Documentation/arm/booting.rst +1 -1
@@ -128,7 +128,7 @@ it. The recommended placement is in the first 16KiB of RAM. The boot loader must load a device tree image (dtb) into system ram at a 64bit aligned address and initialize it with the boot data. The -dtb format is documented in Documentation/devicetree/booting-without-of.txt. +dtb format is documented in Documentation/devicetree/booting-without-of.rst. The kernel will look for the dtb magic value of 0xd00dfeed at the dtb physical address to determine if a dtb has been passed instead of a tagged list.
Documentation/devicetree/booting-without-of.rst renamed from Documentation/devicetree/booting-without-of.txt +166 -133
553 lines not on this page · raw message
Documentation/devicetree/index.rst +1 -0
@@ -9,3 +9,4 @@ Open Firmware and Device Tree usage-model writing-schema + booting-without-of
Documentation/translations/zh_CN/arm/Booting +1 -1
@@ -124,7 +124,7 @@ bootloader 必须传递一个系统内存的位置和最小值,以及根文件 bootloader 必须以 64bit 地址对齐的形式加载一个设备树映像(dtb)到系统 RAM 中,并用启动数据初始化它。dtb 格式在文档 -Documentation/devicetree/booting-without-of.txt 中。内核将会在 +Documentation/devicetree/booting-without-of.rst 中。内核将会在 dtb 物理地址处查找 dtb 魔数值(0xd00dfeed),以确定 dtb 是否已经代替 标签列表被传递进来。
Signature · 1 line
2.21.1
Re: [PATCH v2 04/12] docs: dt: convert booting-without-of.txt to ReST format
Quoted 9 lines · Mauro Carvalho Chehab
- Add a SPDX header;
- Use copyright symbol;
- Adjust document title;
- Adjust document and section titles;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it todevicetree/index.rst.
Let's skip this doc. It's been on my todo to remove it. It's pretty stale and 15 years old. Much of this document is now covered by what's in the DT spec. There's a few pieces that aren't which we need to find new homes for.
Quoted 8 lines
Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/arm/booting.rst | 2 +- ...-without-of.txt => booting-without-of.rst} | 299 ++++++++++-------- Documentation/devicetree/index.rst | 1 + Documentation/translations/zh_CN/arm/Booting | 2 +- 4 files changed, 169 insertions(+), 135 deletions(-) rename Documentation/devicetree/{booting-without-of.txt => booting-without-of.rst} (90%)
Re: [PATCH v2 04/12] docs: dt: convert booting-without-of.txt to ReST format
Quoted 5 lines · Rob Herring
Let's skip this doc. It's been on my todo to remove it. It's pretty stale and 15 years old. Much of this document is now covered by what's in the DT spec. There's a few pieces that aren't which we need to find new homes for.
Happy to see a old doc getting update! :)
PATCH v2 5/12 docs: dt: convert changesets to ReST
In reply to Mauro Carvalho Chehab- Add a SPDX header;
- Add a document title;
- Some whitespace fixes and new line breaks;
- Add it to devicetree/index.rst.
---
.../{changesets.txt => changesets.rst} | 24 ++++++++++++-------
Documentation/devicetree/index.rst | 1 +
2 files changed, 16 insertions(+), 9 deletions(-)
rename Documentation/devicetree/{changesets.txt => changesets.rst} (59%)Documentation/devicetree/changesets.rst renamed from Documentation/devicetree/changesets.txt +15 -9
@@ -1,3 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============= +DT Changesets +============= + A DT changeset is a method which allows one to apply changes in the live tree in such a way that either the full set of changes will be applied, or none of them will be. If an error occurs partway
@@ -15,17 +21,17 @@ The sequence of a changeset is as follows. 1. of_changeset_init() - initializes a changeset 2. A number of DT tree change calls, of_changeset_attach_node(), -of_changeset_detach_node(), of_changeset_add_property(), -of_changeset_remove_property, of_changeset_update_property() to prepare -a set of changes. No changes to the active tree are made at this point. -All the change operations are recorded in the of_changeset 'entries' -list. + of_changeset_detach_node(), of_changeset_add_property(), + of_changeset_remove_property, of_changeset_update_property() to prepare + a set of changes. No changes to the active tree are made at this point. + All the change operations are recorded in the of_changeset 'entries' + list. 3. of_changeset_apply() - Apply the changes to the tree. Either the -entire changeset will get applied, or if there is an error the tree will -be restored to the previous state. The core ensures proper serialization -through locking. An unlocked version __of_changeset_apply is available, -if needed. + entire changeset will get applied, or if there is an error the tree will + be restored to the previous state. The core ensures proper serialization + through locking. An unlocked version __of_changeset_apply is available, + if needed. If a successfully applied changeset needs to be removed, it can be done with of_changeset_revert().
Documentation/devicetree/index.rst +1 -0
@@ -10,3 +10,4 @@ Open Firmware and Device Tree usage-model writing-schema booting-without-of + changesets
Signature · 1 line
2.21.1
PATCH v2 6/12 docs: dt: convert dynamic-resolution-notes.txt to ReST
In reply to Mauro Carvalho Chehab- Add a SPDX header;
- Adjust document title;
- Add it to devicetree/index.rst.
---
...mic-resolution-notes.txt => dynamic-resolution-notes.rst} | 5 ++++-
Documentation/devicetree/index.rst | 1 +
Documentation/devicetree/overlay-notes.txt | 2 +-
MAINTAINERS | 2 +-
4 files changed, 7 insertions(+), 3 deletions(-)
rename Documentation/devicetree/{dynamic-resolution-notes.txt => dynamic-resolution-notes.rst} (90%)Documentation/devicetree/dynamic-resolution-notes.rst renamed from Documentation/devicetree/dynamic-resolution-notes.txt +4 -1
@@ -1,5 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================== Device Tree Dynamic Resolver Notes ----------------------------------- +================================== This document describes the implementation of the in-kernel Device Tree resolver, residing in drivers/of/resolver.c
Documentation/devicetree/index.rst +1 -0
@@ -11,3 +11,4 @@ Open Firmware and Device Tree writing-schema booting-without-of changesets + dynamic-resolution-notes
Documentation/devicetree/overlay-notes.txt +1 -1
@@ -3,7 +3,7 @@ Device Tree Overlay Notes This document describes the implementation of the in-kernel device tree overlay functionality residing in drivers/of/overlay.c and is a -companion document to Documentation/devicetree/dynamic-resolution-notes.txt[1] +companion document to Documentation/devicetree/dynamic-resolution-notes.rst[1] How overlays work -----------------
MAINTAINERS +1 -1
@@ -12458,7 +12458,7 @@ M: Pantelis Antoniou <[email protected]> M: Frank Rowand <[email protected]> L: [email protected] S: Maintained -F: Documentation/devicetree/dynamic-resolution-notes.txt +F: Documentation/devicetree/dynamic-resolution-notes.rst F: Documentation/devicetree/overlay-notes.txt F: drivers/of/overlay.c F: drivers/of/resolver.c
Signature · 1 line
2.21.1
PATCH v2 7/12 docs: dt: convert of_unittest.txt to ReST
In reply to Mauro Carvalho Chehab- Add a SPDX header;
- Adjust document and section titles;
- Adjust numerated list markups;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to devicetree/index.rst.
---
Documentation/devicetree/index.rst | 1 +
.../{of_unittest.txt => of_unittest.rst} | 186 +++++++++---------
2 files changed, 98 insertions(+), 89 deletions(-)
rename Documentation/devicetree/{of_unittest.txt => of_unittest.rst} (54%)Documentation/devicetree/index.rst +1 -0
@@ -12,3 +12,4 @@ Open Firmware and Device Tree booting-without-of changesets dynamic-resolution-notes + of_unittest
Documentation/devicetree/of_unittest.rst renamed from Documentation/devicetree/of_unittest.txt +97 -89
270 lines not on this page · raw message
Signature · 1 line
2.21.1
Re: [PATCH v2 07/12] docs: dt: convert of_unittest.txt to ReST
Quoted 46 lines · Mauro Carvalho Chehab
- Add a SPDX header;
- Adjust document and section titles;
- Adjust numerated list markups;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it todevicetree/index.rst.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/devicetree/index.rst | 1 + .../{of_unittest.txt => of_unittest.rst} | 186 +++++++++--------- 2 files changed, 98 insertions(+), 89 deletions(-) rename Documentation/devicetree/{of_unittest.txt => of_unittest.rst} (54%)Documentation/devicetree/index.rst +1
-0@@ -12,3 +12,4 @@ Open Firmware and Device Tree booting-without-of changesets dynamic-resolution-notes + of_unittestDocumentation/devicetree/of_unittest.rst renamed from Documentation/devicetree/of_unittest.txt +5
-1@@ -1,9 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================== Open Firmware Device Tree Unittest ----------------------------------- +================================== Author: Gaurav Minocha <[email protected]> 1. Introduction +=============== This document explains how the test data required for executing OF unittest is attached to the live tree dynamically, independent of the machine's
Documentation/devicetree/of_unittest.rst architecture. · line 19
Quoted 7 lines
Documentation/devicetree/of_unittest.rst renamed from Documentation/devicetree/of_unittest.txt +2
-2@@ -11,8 +15,8 @@ architecture. It is recommended to read the following documents before moving ahead. -[1] Documentation/devicetree/usage-model.rst -[2] http://www.devicetree.org/Device_Tree_Usage +(1) Documentation/devicetree/usage-model.rst +(2) http://www.devicetree.org/Device_Tree_Usage
You caught this in 03/13. The file has moved to:
https://elinux.org/Device_Tree_Usage
-Frank
Quoted 256 lines
Documentation/devicetree/of_unittest.rst renamed from Documentation/devicetree/of_unittest.txt +90
-86OF Selftest has been designed to test the interface (include/linux/of.h) provided to device driver developers to fetch the device information..etc.@@ -21,79 +25,82 @@ most of the device drivers in various use cases. 2. Test-data +============ The Device Tree Source file (drivers/of/unittest-data/testcases.dts) contains the test data required for executing the unit tests automated in drivers/of/unittest.c. Currently, following Device Tree Source Include files -(.dtsi) are included in testcases.dts: +(.dtsi) are included in testcases.dts:: -drivers/of/unittest-data/tests-interrupts.dtsi -drivers/of/unittest-data/tests-platform.dtsi -drivers/of/unittest-data/tests-phandle.dtsi -drivers/of/unittest-data/tests-match.dtsi + drivers/of/unittest-data/tests-interrupts.dtsi + drivers/of/unittest-data/tests-platform.dtsi + drivers/of/unittest-data/tests-phandle.dtsi + drivers/of/unittest-data/tests-match.dtsi -When the kernel is build with OF_SELFTEST enabled, then the following make rule +When the kernel is build with OF_SELFTEST enabled, then the following make +rule:: -$(obj)/%.dtb: $(src)/%.dts FORCE - $(call if_changed_dep, dtc) + $(obj)/%.dtb: $(src)/%.dts FORCE + $(call if_changed_dep, dtc) is used to compile the DT source file (testcases.dts) into a binary blob (testcases.dtb), also referred as flattened DT. After that, using the following rule the binary blob above is wrapped as an -assembly file (testcases.dtb.S). +assembly file (testcases.dtb.S):: -$(obj)/%.dtb.S: $(obj)/%.dtb - $(call cmd, dt_S_dtb) + $(obj)/%.dtb.S: $(obj)/%.dtb + $(call cmd, dt_S_dtb) The assembly file is compiled into an object file (testcases.dtb.o), and is linked into the kernel image. 2.1. Adding the test data +------------------------- Un-flattened device tree structure: Un-flattened device tree consists of connected device_node(s) in form of a tree -structure described below. +structure described below:: -// following struct members are used to construct the tree -struct device_node { - ... - struct device_node *parent; - struct device_node *child; - struct device_node *sibling; - ... - }; + // following struct members are used to construct the tree + struct device_node { + ... + struct device_node *parent; + struct device_node *child; + struct device_node *sibling; + ... + }; Figure 1, describes a generic structure of machine's un-flattened device tree considering only child and sibling pointers. There exists another pointer, -*parent, that is used to traverse the tree in the reverse direction. So, at +``*parent``, that is used to traverse the tree in the reverse direction. So, at a particular level the child node and all the sibling nodes will have a parent pointer pointing to a common node (e.g. child1, sibling2, sibling3, sibling4's -parent points to root node) +parent points to root node):: -root ('/') - | -child1 -> sibling2 -> sibling3 -> sibling4 -> null - | | | | - | | | null - | | | - | | child31 -> sibling32 -> null - | | | | - | | null null - | | - | child21 -> sibling22 -> sibling23 -> null - | | | | - | null null null - | -child11 -> sibling12 -> sibling13 -> sibling14 -> null - | | | | - | | | null - | | | - null null child131 -> null - | - null + root ('/') + | + child1 -> sibling2 -> sibling3 -> sibling4 -> null + | | | | + | | | null + | | | + | | child31 -> sibling32 -> null + | | | | + | | null null + | | + | child21 -> sibling22 -> sibling23 -> null + | | | | + | null null null + | + child11 -> sibling12 -> sibling13 -> sibling14 -> null + | | | | + | | | null + | | | + null null child131 -> null + | + null Figure 1: Generic structure of un-flattened device tree@@ -101,10 +108,10 @@ Figure 1: Generic structure of un-flattened device tree Before executing OF unittest, it is required to attach the test data to machine's device tree (if present). So, when selftest_data_add() is called, at first it reads the flattened device tree data linked into the kernel image -via the following kernel symbols: +via the following kernel symbols:: -__dtb_testcases_begin - address marking the start of test data blob -__dtb_testcases_end - address marking the end of test data blob + __dtb_testcases_begin - address marking the start of test data blob + __dtb_testcases_end - address marking the end of test data blob Secondly, it calls of_fdt_unflatten_tree() to unflatten the flattened blob. And finally, if the machine's device tree (i.e live tree) is present,@@ -113,15 +120,15 @@ attaches itself as a live device tree. attach_node_and_children() uses of_attach_node() to attach the nodes into the live tree as explained below. To explain the same, the test data tree described - in Figure 2 is attached to the live tree described in Figure 1. +in Figure 2 is attached to the live tree described in Figure 1:: -root ('/') - | - testcase-data - | - test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null - | | | | - test-child01 null null null + root ('/') + | + testcase-data + | + test-child0 -> test-sibling1 -> test-sibling2 -> test-sibling3 -> null + | | | | + test-child01 null null null Figure 2: Example test data tree to be attached to live tree.@@ -134,39 +141,39 @@ In the function of_attach_node(), the new node is attached as the child of the given parent in live tree. But, if parent already has a child then the new node replaces the current child and turns it into its sibling. So, when the testcase data node is attached to the live tree above (Figure 1), the final structure is - as shown in Figure 3. +as shown in Figure 3:: -root ('/') - | -testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null - | | | | | - (...) | | | null - | | child31 -> sibling32 -> null - | | | | - | | null null - | | - | child21 -> sibling22 -> sibling23 -> null - | | | | - | null null null - | - child11 -> sibling12 -> sibling13 -> sibling14 -> null - | | | | - null null | null - | - child131 -> null - | - null ------------------------------------------------------------------------ + root ('/') + | + testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null + | | | | | + (...) | | | null + | | child31 -> sibling32 -> null + | | | | + | | null null + | | + | child21 -> sibling22 -> sibling23 -> null + | | | | + | null null null + | + child11 -> sibling12 -> sibling13 -> sibling14 -> null + | | | | + null null | null + | + child131 -> null + | + null + ----------------------------------------------------------------------- -root ('/') - | -testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null - | | | | | - | (...) (...) (...) null - | -test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null - | | | | - null null null test-child01 + root ('/') + | + testcase-data -> child1 -> sibling2 -> sibling3 -> sibling4 -> null + | | | | | + | (...) (...) (...) null + | + test-sibling3 -> test-sibling2 -> test-sibling1 -> test-child0 -> null + | | | | + null null null test-child01 Figure 3: Live device tree structure after attaching the testcase-data.@@ -176,7 +183,7 @@ Astute readers would have noticed that test-child0 node becomes the last sibling compared to the earlier structure (Figure 2). After attaching first test-child0 the test-sibling1 is attached that pushes the child node (i.e. test-child0) to become a sibling and makes itself a child node, - as mentioned above. +as mentioned above. If a duplicate node is found (i.e. if a node with same full_name property is already present in the live tree), then the node isn't attached rather its@@ -185,6 +192,7 @@ update_node_properties(). 2.2. Removing the test data +--------------------------- Once the test case execution is complete, selftest_data_remove is called in order to remove the device nodes attached initially (first the leaf nodes are
Re: [PATCH v2 07/12] docs: dt: convert of_unittest.txt to ReST
Em Mon, 2 Mar 2020 15:11:42 -0600
Frank Rowand <[email protected]> escreveu:
Quoted 50 lines · Mauro Carvalho Chehab
Quoted 49 lines
- Add a SPDX header;
- Adjust document and section titles;
- Adjust numerated list markups;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it todevicetree/index.rst.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/devicetree/index.rst | 1 + .../{of_unittest.txt => of_unittest.rst} | 186 +++++++++--------- 2 files changed, 98 insertions(+), 89 deletions(-) rename Documentation/devicetree/{of_unittest.txt => of_unittest.rst} (54%)Documentation/devicetree/index.rst +1
-0@@ -12,3 +12,4 @@ Open Firmware and Device Tree booting-without-of changesets dynamic-resolution-notes + of_unittestDocumentation/devicetree/of_unittest.rst renamed from Documentation/devicetree/of_unittest.txt +5
-1@@ -1,9 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================== Open Firmware Device Tree Unittest ----------------------------------- +================================== Author: Gaurav Minocha <[email protected]> 1. Introduction +=============== This document explains how the test data required for executing OF unittest is attached to the live tree dynamically, independent of the machine's@@ -11,8 +15,8 @@ architecture. It is recommended to read the following documents before moving ahead.
Quoted 9 lines
Documentation/devicetree/of_unittest.rst architecture. · line 19
Quoted 4 lines
Documentation/devicetree/of_unittest.rst renamed from Documentation/devicetree/of_unittest.txt +2
-2-[1] Documentation/devicetree/usage-model.rst -[2] http://www.devicetree.org/Device_Tree_Usage +(1) Documentation/devicetree/usage-model.rst +(2) http://www.devicetree.org/Device_Tree_UsageYou caught this in 03/13. The file has moved to:
Thanks for noticing. I'll move patch 03/12 to the end and fix all those references altogether there.
Regards,
Mauro
PATCH v2 8/12 docs: dt: convert overlay-notes.txt to ReST format
In reply to Mauro Carvalho Chehab- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to devicetree/index.rst.
---
Documentation/devicetree/index.rst | 1 +
.../{overlay-notes.txt => overlay-notes.rst} | 141 +++++++++---------
MAINTAINERS | 2 +-
3 files changed, 74 insertions(+), 70 deletions(-)
rename Documentation/devicetree/{overlay-notes.txt => overlay-notes.rst} (56%)Documentation/devicetree/index.rst +1 -0
@@ -13,3 +13,4 @@ Open Firmware and Device Tree changesets dynamic-resolution-notes of_unittest + overlay-notes
Documentation/devicetree/overlay-notes.rst renamed from Documentation/devicetree/overlay-notes.txt +72 -69
172 lines not on this page · raw message
MAINTAINERS +1 -1
@@ -12459,7 +12459,7 @@ M: Frank Rowand <[email protected]> L: [email protected] S: Maintained F: Documentation/devicetree/dynamic-resolution-notes.rst -F: Documentation/devicetree/overlay-notes.txt +F: Documentation/devicetree/overlay-notes.rst F: drivers/of/overlay.c F: drivers/of/resolver.c K: of_overlay_notifier_
Signature · 1 line
2.21.1
Re: [PATCH v2 08/12] docs: dt: convert overlay-notes.txt to ReST format
Documentation/devicetree/overlay-notes.rst
Quoted 30 lines · Mauro Carvalho Chehab
- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it todevicetree/index.rst.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/devicetree/index.rst | 1 + .../{overlay-notes.txt => overlay-notes.rst} | 141 +++++++++--------- MAINTAINERS | 2 +- 3 files changed, 74 insertions(+), 70 deletions(-) rename Documentation/devicetree/{overlay-notes.txt => overlay-notes.rst} (56%)Documentation/devicetree/index.rst +1
-0@@ -13,3 +13,4 @@ Open Firmware and Device Tree changesets dynamic-resolution-notes of_unittest + overlay-notesDocumentation/devicetree/overlay-notes.rst renamed from Documentation/devicetree/overlay-notes.txt +0
-0
There is a collision between 08/12 and a patch I sent a couple of days ago:
https://lore.kernel.org/r/[email protected]
-Frank
Quoted 191 lines
Documentation/devicetree/overlay-notes.rst renamed from Documentation/devicetree/overlay-notes.txt +72
-69@@ -1,5 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= Device Tree Overlay Notes -------------------------- +========================= This document describes the implementation of the in-kernel device tree overlay functionality residing in drivers/of/overlay.c and is a@@ -15,68 +18,68 @@ Since the kernel mainly deals with devices, any new device node that result in an active device should have it created while if the device node is either disabled or removed all together, the affected device should be deregistered. -Lets take an example where we have a foo board with the following base tree: - ----- foo.dts ----------------------------------------------------------------- - /* FOO platform */ - / { - compatible = "corp,foo"; - - /* shared resources */ - res: res { - }; - - /* On chip peripherals */ - ocp: ocp { - /* peripherals that are always instantiated */ - peripheral1 { ... }; - } - }; ----- foo.dts ----------------------------------------------------------------- - -The overlay bar.dts, when loaded (and resolved as described in [1]) should - ----- bar.dts ----------------------------------------------------------------- -/plugin/; /* allow undefined label references and record them */ -/ { - .... /* various properties for loader use; i.e. part id etc. */ - fragment@0 { - target = <&ocp>; - __overlay__ { - /* bar peripheral */ - bar { - compatible = "corp,bar"; - ... /* various properties and child nodes */ - } - }; - }; -}; ----- bar.dts ----------------------------------------------------------------- - -result in foo+bar.dts - ----- foo+bar.dts ------------------------------------------------------------- - /* FOO platform + bar peripheral */ - / { - compatible = "corp,foo"; - - /* shared resources */ - res: res { - }; - - /* On chip peripherals */ - ocp: ocp { - /* peripherals that are always instantiated */ - peripheral1 { ... }; - - /* bar peripheral */ - bar { - compatible = "corp,bar"; - ... /* various properties and child nodes */ - } - } - }; ----- foo+bar.dts ------------------------------------------------------------- +Lets take an example where we have a foo board with the following base tree:: + + ---- foo.dts -------------------------------------------------------------- + /* FOO platform */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + } + }; + ---- foo.dts -------------------------------------------------------------- + +The overlay bar.dts, when loaded (and resolved as described in [1]) should:: + + ---- bar.dts -------------------------------------------------------------- + /plugin/; /* allow undefined label references and record them */ + / { + .... /* various properties for loader use; i.e. part id etc. */ + fragment@0 { + target = <&ocp>; + __overlay__ { + /* bar peripheral */ + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + } + }; + }; + }; + ---- bar.dts -------------------------------------------------------------- + +result in foo+bar.dts:: + + ---- foo+bar.dts ---------------------------------------------------------- + /* FOO platform + bar peripheral */ + / { + compatible = "corp,foo"; + + /* shared resources */ + res: res { + }; + + /* On chip peripherals */ + ocp: ocp { + /* peripherals that are always instantiated */ + peripheral1 { ... }; + + /* bar peripheral */ + bar { + compatible = "corp,bar"; + ... /* various properties and child nodes */ + } + } + }; + ---- foo+bar.dts ---------------------------------------------------------- As a result of the overlay, a new device node (bar) has been created so a bar platform device will be registered and if a matching device driver@@ -88,11 +91,11 @@ Overlay in-kernel API The API is quite easy to use. 1. Call of_overlay_fdt_apply() to create and apply an overlay changeset. The -return value is an error or a cookie identifying this overlay. + return value is an error or a cookie identifying this overlay. 2. Call of_overlay_remove() to remove and cleanup the overlay changeset -previously created via the call to of_overlay_fdt_apply(). Removal of an -overlay changeset that is stacked by another will not be permitted. + previously created via the call to of_overlay_fdt_apply(). Removal of an + overlay changeset that is stacked by another will not be permitted. Finally, if you need to remove all overlays in one-go, just call of_overlay_remove_all() which will remove every single one in the correct@@ -109,9 +112,9 @@ respective node it received. Overlay DTS Format ------------------ -The DTS of an overlay should have the following format: +The DTS of an overlay should have the following format:: -{ + { /* ignored properties by the overlay */ fragment@0 { /* first child node */@@ -131,7 +134,7 @@ The DTS of an overlay should have the following format: }; /* more fragments follow */ -} + } Using the non-phandle based target method allows one to use a base DT which does not contain a __symbols__ node, i.e. it was not compiled with the -@ option.MAINTAINERS +1
-1@@ -12459,7 +12459,7 @@ M: Frank Rowand <[email protected]> L: [email protected] S: Maintained F: Documentation/devicetree/dynamic-resolution-notes.rst -F: Documentation/devicetree/overlay-notes.txt +F: Documentation/devicetree/overlay-notes.rst F: drivers/of/overlay.c F: drivers/of/resolver.c K: of_overlay_notifier_
Re: [PATCH v2 08/12] docs: dt: convert overlay-notes.txt to ReST format
Em Mon, 2 Mar 2020 15:13:21 -0600
Frank Rowand <[email protected]> escreveu:
Quoted 34 lines · Mauro Carvalho Chehab
Documentation/devicetree/overlay-notes.rst
Quoted 30 lines
- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it todevicetree/index.rst.Signed-off-by Mauro Carvalho Chehab <[email protected]>--- Documentation/devicetree/index.rst | 1 + .../{overlay-notes.txt => overlay-notes.rst} | 141 +++++++++--------- MAINTAINERS | 2 +- 3 files changed, 74 insertions(+), 70 deletions(-) rename Documentation/devicetree/{overlay-notes.txt => overlay-notes.rst} (56%)Documentation/devicetree/index.rst +1
-0@@ -13,3 +13,4 @@ Open Firmware and Device Tree changesets dynamic-resolution-notes of_unittest + overlay-notesDocumentation/devicetree/overlay-notes.rst renamed from Documentation/devicetree/overlay-notes.txt +0
-0There is a collision between 08/12 and a patch I sent a couple of days ago:
Quoted 1 line
https://lore.kernel.org/r/[email protected]
Thanks for pointing it! I'll rebase on the top of linux-next tomorrow and add your patch on my tree before my series, if not merged on -next before that.
Regards,
Mauro
PATCH v2 9/12 docs: dt: minor adjustments at writing-schema.rst
In reply to Mauro Carvalho ChehabThere are two literal blocks that aren't mark as such. Mark them, in order to make the document to produce a better html output.
While here, also add a SPDX header to it.
--- Documentation/devicetree/writing-schema.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-)
Documentation/devicetree/writing-schema.rst +6 -3
@@ -1,4 +1,4 @@ -:orphan: +.. SPDX-License-Identifier: GPL-2.0 Writing DeviceTree Bindings in json-schema ==========================================
@@ -124,9 +124,12 @@ dtc must also be built with YAML output support enabled. This requires that libyaml and its headers be installed on the host system. For some distributions that involves installing the development package, such as: -Debian: +Debian:: + apt-get install libyaml-dev -Fedora: + +Fedora:: + dnf -y install libyaml-devel Running checks
Signature · 1 line
2.21.1
PATCH v2 10/12 docs: dt: convert ABI.txt to ReST format
In reply to Mauro Carvalho ChehabThis file only requires a properly-formatted title to be recognized as a ReST file.
As there will be more files under bindings/ that will be included at the documentation body, add a new index.rst file there.
---
Documentation/arm/microchip.rst | 2 +-
Documentation/devicetree/bindings/{ABI.txt => ABI.rst} | 5 ++++-
Documentation/devicetree/bindings/arm/amlogic.yaml | 2 +-
Documentation/devicetree/bindings/arm/syna.txt | 2 +-
Documentation/devicetree/bindings/index.rst | 10 ++++++++++
Documentation/devicetree/index.rst | 2 ++
6 files changed, 19 insertions(+), 4 deletions(-)
rename Documentation/devicetree/bindings/{ABI.txt => ABI.rst} (94%)
create mode 100644 Documentation/devicetree/bindings/index.rstDocumentation/arm/microchip.rst +1 -1
@@ -192,7 +192,7 @@ Device Tree files and Device Tree bindings that apply to AT91 SoCs and boards ar considered as "Unstable". To be completely clear, any at91 binding can change at any time. So, be sure to use a Device Tree Binary and a Kernel Image generated from the same source tree. -Please refer to the Documentation/devicetree/bindings/ABI.txt file for a +Please refer to the Documentation/devicetree/bindings/ABI.rst file for a definition of a "Stable" binding/ABI. This statement will be removed by AT91 MAINTAINERS when appropriate.
Documentation/devicetree/bindings/ABI.rst renamed from Documentation/devicetree/bindings/ABI.txt +4 -1
@@ -1,5 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 - Devicetree (DT) ABI +=================== +Devicetree (DT) ABI +=================== I. Regarding stable bindings/ABI, we quote from the 2013 ARM mini-summit summary document:
Documentation/devicetree/bindings/arm/amlogic.yaml +1 -1
@@ -17,7 +17,7 @@ description: |+ any time. Be sure to use a device tree binary and a kernel image generated from the same source tree. - Please refer to Documentation/devicetree/bindings/ABI.txt for a definition of a + Please refer to Documentation/devicetree/bindings/ABI.rst for a definition of a stable binding/ABI. properties:
Documentation/devicetree/bindings/arm/syna.txt +1 -1
@@ -13,7 +13,7 @@ considered "unstable". Any Marvell Berlin device tree binding may change at any time. Be sure to use a device tree binary and a kernel image generated from the same source tree. -Please refer to Documentation/devicetree/bindings/ABI.txt for a definition of a +Please refer to Documentation/devicetree/bindings/ABI.rst for a definition of a stable binding/ABI. ---------------------------------------------------------------
Documentation/devicetree/bindings/index.rst new file +10 -0
@@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========== +Device Tree +=========== + +.. toctree:: + :maxdepth: 1 + + ABI
Documentation/devicetree/index.rst +2 -0
@@ -14,3 +14,5 @@ Open Firmware and Device Tree dynamic-resolution-notes of_unittest overlay-notes + + bindings/index
Signature · 1 line
2.21.1
PATCH v2 11/12 docs: dt: convert submitting-patches.txt to ReST format
In reply to Mauro Carvalho Chehab- Add a SPDX header;
- Adjust document and section titles;
- Mark literal blocks as such;
- Add it to bindings/index.rst.
---
Documentation/devicetree/bindings/index.rst | 1 +
...submitting-patches.txt => submitting-patches.rst} | 12 +++++++++---
.../devicetree/bindings/writing-bindings.txt | 2 +-
Documentation/process/submitting-patches.rst | 2 +-
.../it_IT/process/submitting-patches.rst | 2 +-
scripts/checkpatch.pl | 2 +-
6 files changed, 14 insertions(+), 7 deletions(-)
rename Documentation/devicetree/bindings/{submitting-patches.txt => submitting-patches.rst} (92%)Documentation/devicetree/bindings/index.rst +1 -0
@@ -8,3 +8,4 @@ Device Tree :maxdepth: 1 ABI + submitting-patches
Documentation/devicetree/bindings/submitting-patches.rst renamed from Documentation/devicetree/bindings/submitting-patches.txt +9 -3
@@ -1,13 +1,17 @@ +.. SPDX-License-Identifier: GPL-2.0 - Submitting devicetree (DT) binding patches +========================================== +Submitting devicetree (DT) binding patches +========================================== I. For patch submitters +======================= 0) Normal patch submission rules from Documentation/process/submitting-patches.rst applies. 1) The Documentation/ and include/dt-bindings/ portion of the patch should - be a separate patch. The preferred subject prefix for binding patches is: + be a separate patch. The preferred subject prefix for binding patches is:: "dt-bindings: <binding dir>: ..."
@@ -17,7 +21,7 @@ I. For patch submitters 2) DT binding files are written in DT schema format using json-schema vocabulary and YAML file format. The DT binding files must pass validation - by running: + by running:: make dt_binding_check
@@ -60,6 +64,7 @@ I. For patch submitters II. For kernel maintainers +========================== 1) If you aren't comfortable reviewing a given binding, reply to it and ask the devicetree maintainers for guidance. This will help them prioritize
@@ -76,6 +81,7 @@ II. For kernel maintainers kept with the driver using the binding. III. Notes +========== 0) Please see ...bindings/ABI.txt for details regarding devicetree ABI.
Documentation/devicetree/bindings/writing-bindings.txt +1 -1
@@ -4,7 +4,7 @@ This is a list of common review feedback items focused on binding design. With every rule, there are exceptions and bindings have many gray areas. For guidelines related to patches, see -Documentation/devicetree/bindings/submitting-patches.txt +Documentation/devicetree/bindings/submitting-patches.rst Overall design
Documentation/process/submitting-patches.rst +1 -1
@@ -16,7 +16,7 @@ for a list of items to check before submitting code. If you are submitting a driver, also read :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`; for device tree binding patches, read -Documentation/devicetree/bindings/submitting-patches.txt. +Documentation/devicetree/bindings/submitting-patches.rst. Many of these steps describe the default behavior of the ``git`` version control system; if you use ``git`` to prepare your patches, you'll find much
Documentation/translations/it_IT/process/submitting-patches.rst +1 -1
@@ -21,7 +21,7 @@ Leggete anche :ref:`Documentation/translations/it_IT/process/submit-checklist.rs per una lista di punti da verificare prima di inviare del codice. Se state inviando un driver, allora leggete anche :ref:`Documentation/translations/it_IT/process/submitting-drivers.rst <it_submittingdrivers>`; per delle patch relative alle associazioni per Device Tree leggete -Documentation/devicetree/bindings/submitting-patches.txt. +Documentation/devicetree/bindings/submitting-patches.rst. Molti di questi passi descrivono il comportamento di base del sistema di controllo di versione ``git``; se utilizzate ``git`` per preparare le vostre
scripts/checkpatch.pl +1 -1
@@ -2607,7 +2607,7 @@ sub process { if (($last_binding_patch != -1) && ($last_binding_patch ^ $is_binding_patch)) { WARN("DT_SPLIT_BINDING_PATCH", - "DT binding docs and includes should be a separate patch. See: Documentation/devicetree/bindings/submitting-patches.txt\n"); + "DT binding docs and includes should be a separate patch. See: Documentation/devicetree/bindings/submitting-patches.rst\n"); } }
Signature · 1 line
2.21.1
PATCH v2 12/12 docs: dt: convert writing-bindings.txt to ReST
In reply to Mauro Carvalho Chehab- Add a SPDX header;
- Adjust document and section titles;
- Mark literal blocks as such;
- Add it to bindings/index.rst.
---
Documentation/devicetree/bindings/index.rst | 1 +
.../{writing-bindings.txt => writing-bindings.rst} | 7 +++++++
2 files changed, 8 insertions(+)
rename Documentation/devicetree/bindings/{writing-bindings.txt => writing-bindings.rst} (92%)Documentation/devicetree/bindings/index.rst +1 -0
@@ -9,3 +9,4 @@ Device Tree ABI submitting-patches + writing-bindings
Documentation/devicetree/bindings/writing-bindings.rst renamed from Documentation/devicetree/bindings/writing-bindings.txt +7 -0
@@ -1,4 +1,8 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================================ DOs and DON'Ts for designing and writing Devicetree bindings +============================================================ This is a list of common review feedback items focused on binding design. With every rule, there are exceptions and bindings have many gray areas.
@@ -8,6 +12,7 @@ Documentation/devicetree/bindings/submitting-patches.rst Overall design +============== - DO attempt to make bindings complete even if a driver doesn't support some features. For example, if a device has an interrupt, then include the
@@ -32,6 +37,7 @@ Overall design Properties +========== - DO make 'compatible' properties specific. DON'T use wildcards in compatible strings. DO use fallback compatibles when devices are the same as or a subset
@@ -53,6 +59,7 @@ Properties Board/SoC .dts Files +==================== - DO put all MMIO devices under a bus node and not at the top-level.
Signature · 1 line
2.21.1
Jonathan Corbet
maintainerQuoted 9 lines · On Mon, 2 Mar 2020 08:59:25 +0100 Mauro Carvalho Chehab…
While most of the devicetree stuff has its own format (with is now being converted to YAML format), some documents there are actually describing the DT concepts and how to contribute to it.
IMHO, those documents would fit perfectly as part of the documentation body, as part of the firmare documents set.
This patch series manually converts some DT documents that, on my opinion, would belong to it.
Did you consider putting this stuff into the firmware-guide while you were at it? It's not a perfect fit, I guess, but it doesn't seem too awkward either.
It also seems like it would be good to CC the devicetree folks, or at least the devicetree mailing list?
Thanks,
jon
Em Mon, 2 Mar 2020 12:35:54 -0700
Jonathan Corbet <[email protected]> escreveu:
Quoted 10 lines
Quoted 7 lines · On Mon, 2 Mar 2020 08:59:25 +0100 Mauro Carvalho Chehab…
While most of the devicetree stuff has its own format (with is now being converted to YAML format), some documents there are actually describing the DT concepts and how to contribute to it.
IMHO, those documents would fit perfectly as part of the documentation body, as part of the firmare documents set.
Quoted 6 lines
Quoted 2 lines
This patch series manually converts some DT documents that, on my opinion, would belong to it.
Did you consider putting this stuff into the firmware-guide while you were at it? It's not a perfect fit, I guess, but it doesn't seem too awkward either.
I placed it just below the firmware-guide at the main index file.
I have split thoughts about moving the files to there, though. From one side, it may fit better from the PoV of organizing the documentation.
From other side, newcomers working with DT may expect looking at the text files inside Documentation/devicetree/.
Maybe I could add an extra patch at the end of this series with the move, adding a "RFC" on his title. This way, we can better discuss it, and either merge the last one or not depending on the comments.
Quoted 3 lines
It also seems like it would be good to CC the devicetree folks, or at least the devicetree mailing list?
Yeah, that would make sense. I'm using get-maintainers script to prepare the c/c list, as it is simply too much work to find the right maintainers by hand, for every single patch.
I just noticed today that there's just *one entry* at MAINTAINERS file for Documentation/devicetree, and that points to you:
DOCUMENTATION
M: Jonathan Corbet <[email protected]>
L: [email protected]
S: Maintained
F: Documentation/
F: scripts/documentation-file-ref-check
F: scripts/kernel-doc
F: scripts/sphinx-pre-install
X: Documentation/ABI/
X: Documentation/firmware-guide/acpi/
X: Documentation/devicetree/
So, perhaps we should add something like this to MAINTAINERS:
MAINTAINERS +5 -0
@@ -12394,6 +12394,11 @@ L: [email protected] S: Supported F: drivers/infiniband/ulp/opa_vnic +OPEN FIRMWARE +L: [email protected] +S: Maintained +F: Documentation/devicetree + OPEN FIRMWARE AND DEVICE TREE OVERLAYS M: Pantelis Antoniou <[email protected]> M: Frank Rowand <[email protected]>
Rob Herring
maintainerQuoted 26 lines · Mauro Carvalho Chehab
Em Mon, 2 Mar 2020 12:35:54 -0700
Jonathan Corbet <[email protected]> escreveu:Quoted 10 lines
Quoted 7 lines · On Mon, 2 Mar 2020 08:59:25 +0100 Mauro Carvalho Chehab…
While most of the devicetree stuff has its own format (with is now being converted to YAML format), some documents there are actually describing the DT concepts and how to contribute to it.
IMHO, those documents would fit perfectly as part of the documentation body, as part of the firmare documents set.
Quoted 6 lines
Quoted 2 lines
This patch series manually converts some DT documents that, on my opinion, would belong to it.
Did you consider putting this stuff into the firmware-guide while you were at it? It's not a perfect fit, I guess, but it doesn't seem too awkward either.
I placed it just below the firmware-guide at the main index file.
I have split thoughts about moving the files to there, though. From one side, it may fit better from the PoV of organizing the documentation.
Quoted 6 lines
From other side, newcomers working with DT may expect looking at the text files inside
Documentation/devicetree/.Maybe I could add an extra patch at the end of this series with the move, adding a "RFC" on his title. This way, we can better discuss it, and either merge the last one or not depending on the comments.
Keep in mind that we generate a standalone DT only tree[1] with the documentation, dts files and headers. So things should be structured such that all the DT documentation could be built by itself without dependencies on the 'kernel documentation'. I'm not asking for that to be done in this series, but just don't do anything to make that harder. I don't *think* have, but just want to make sure that's clear.
Quoted 2 lines
Quoted 2 lines
It also seems like it would be good to CC the devicetree folks, or at least the devicetree mailing list?
I was wondering what happened to the cover letter on v2...
Quoted 7 lines
Yeah, that would make sense. I'm using get-maintainers script to prepare the c/c list, as it is simply too much work to find the right maintainers by hand, for every single patch.
I just noticed today that there's just *one entry* at
MAINTAINERSfile forDocumentation/devicetree, and that points to you:
Quoted 11 lines
DOCUMENTATION
M: Jonathan Corbet <[email protected]>
L: [email protected]
S: Maintained
F:Documentation/
F:scripts/documentation-file-ref-check
F:scripts/kernel-doc
F:scripts/sphinx-pre-install
X:Documentation/ABI/
X:Documentation/firmware-guide/acpi/
X:Documentation/devicetree/
You mean doesn't point to Jon as 'X' is exclude. You missed this entry:
OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS
M: Rob Herring <[email protected]> M: Mark Rutland <[email protected]> L: [email protected] T: git git://git.kernel.org/pub/scm/linux/kernel/git/robh/linux.git Q: http://patchwork.ozlabs.org/project/devicetree-bindings/list/ S: Maintained F: Documentation/devicetree/ F: arch/*/boot/dts/ F: include/dt-bindings/
Rob
[1] https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git/
Em Tue, 3 Mar 2020 10:20:25 -0600
Rob Herring <[email protected]> escreveu:
Quoted 35 lines
Quoted 26 lines · Mauro Carvalho Chehab
Em Mon, 2 Mar 2020 12:35:54 -0700
Jonathan Corbet <[email protected]> escreveu:Quoted 10 lines
Quoted 7 lines · On Mon, 2 Mar 2020 08:59:25 +0100 Mauro Carvalho Chehab…
While most of the devicetree stuff has its own format (with is now being converted to YAML format), some documents there are actually describing the DT concepts and how to contribute to it.
IMHO, those documents would fit perfectly as part of the documentation body, as part of the firmare documents set.
Quoted 6 lines
Quoted 2 lines
This patch series manually converts some DT documents that, on my opinion, would belong to it.
Did you consider putting this stuff into the firmware-guide while you were at it? It's not a perfect fit, I guess, but it doesn't seem too awkward either.
I placed it just below the firmware-guide at the main index file.
I have split thoughts about moving the files to there, though. From one side, it may fit better from the PoV of organizing the documentation.
Quoted 6 lines
From other side, newcomers working with DT may expect looking at the text files inside
Documentation/devicetree/.Maybe I could add an extra patch at the end of this series with the move, adding a "RFC" on his title. This way, we can better discuss it, and either merge the last one or not depending on the comments.
Quoted 6 lines
Keep in mind that we generate a standalone DT only tree[1] with the documentation, dts files and headers. So things should be structured such that all the DT documentation could be built by itself without dependencies on the 'kernel documentation'. I'm not asking for that to be done in this series, but just don't do anything to make that harder. I don't *think* have, but just want to make sure that's clear.
So, I guess it is better to keep the .rst files under Documentation/devicetree, instead of moving them to Documentation/firmware-guide.
Well, if moved, I guess it would be easy to modify the scripts that produce the documentation to also parse something a new directory inside Documentation/firmware-guide.
Quoted 28 lines
Quoted 3 lines
Quoted 3 lines
It also seems like it would be good to CC the devicetree folks, or at least the devicetree mailing list?
I was wondering what happened to the cover letter on v2...
Quoted 7 lines
Yeah, that would make sense. I'm using get-maintainers script to prepare the c/c list, as it is simply too much work to find the right maintainers by hand, for every single patch.
I just noticed today that there's just *one entry* at
MAINTAINERSfile forDocumentation/devicetree, and that points to you:Quoted 11 lines
DOCUMENTATION
M: Jonathan Corbet <[email protected]>
L: [email protected]
S: Maintained
F:Documentation/
F:scripts/documentation-file-ref-check
F:scripts/kernel-doc
F:scripts/sphinx-pre-install
X:Documentation/ABI/
X:Documentation/firmware-guide/acpi/
X:Documentation/devicetree/You mean doesn't point to Jon as 'X' is exclude. You missed this entry:
OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS
Quoted 9 lines
M: Rob Herring <[email protected]> M: Mark Rutland <[email protected]> L: [email protected] T: git git://git.kernel.org/pub/scm/linux/kernel/git/robh/linux.git Q: http://patchwork.ozlabs.org/project/devicetree-bindings/list/ S: Maintained F: Documentation/devicetree/ F: arch/*/boot/dts/ F: include/dt-bindings/
Yeah, I remember I saw something like the above in the past. However, I'm not seeing this entry at the MAINTAINERS file at next-20200303 anymore.
Did someone removed such entry?
Quoted 5 lines
Rob
[1] https://git.kernel.org/pub/scm/linux/kernel/git/devicetree/devicetree-rebasing.git/
Em Tue, 3 Mar 2020 18:01:09 +0100
Mauro Carvalho Chehab <[email protected]> escreveu:
Quoted 90 lines
Em Tue, 3 Mar 2020 10:20:25 -0600
Rob Herring <[email protected]> escreveu:Quoted 35 lines
Quoted 26 lines · Mauro Carvalho Chehab
Em Mon, 2 Mar 2020 12:35:54 -0700
Jonathan Corbet <[email protected]> escreveu:Quoted 10 lines
Quoted 7 lines · On Mon, 2 Mar 2020 08:59:25 +0100 Mauro Carvalho Chehab…
While most of the devicetree stuff has its own format (with is now being converted to YAML format), some documents there are actually describing the DT concepts and how to contribute to it.
IMHO, those documents would fit perfectly as part of the documentation body, as part of the firmare documents set.
Quoted 6 lines
Quoted 2 lines
This patch series manually converts some DT documents that, on my opinion, would belong to it.
Did you consider putting this stuff into the firmware-guide while you were at it? It's not a perfect fit, I guess, but it doesn't seem too awkward either.
I placed it just below the firmware-guide at the main index file.
I have split thoughts about moving the files to there, though. From one side, it may fit better from the PoV of organizing the documentation.
Quoted 6 lines
From other side, newcomers working with DT may expect looking at the text files inside
Documentation/devicetree/.Maybe I could add an extra patch at the end of this series with the move, adding a "RFC" on his title. This way, we can better discuss it, and either merge the last one or not depending on the comments.
Quoted 6 lines
Keep in mind that we generate a standalone DT only tree[1] with the documentation, dts files and headers. So things should be structured such that all the DT documentation could be built by itself without dependencies on the 'kernel documentation'. I'm not asking for that to be done in this series, but just don't do anything to make that harder. I don't *think* have, but just want to make sure that's clear.
So, I guess it is better to keep the .rst files under
Documentation/devicetree, instead of moving them toDocumentation/firmware-guide.Well, if moved, I guess it would be easy to modify the scripts that produce the documentation to also parse something a new directory inside
Documentation/firmware-guide.Quoted 28 lines
Quoted 3 lines
Quoted 3 lines
It also seems like it would be good to CC the devicetree folks, or at least the devicetree mailing list?
I was wondering what happened to the cover letter on v2...
Quoted 7 lines
Yeah, that would make sense. I'm using get-maintainers script to prepare the c/c list, as it is simply too much work to find the right maintainers by hand, for every single patch.
I just noticed today that there's just *one entry* at
MAINTAINERSfile forDocumentation/devicetree, and that points to you:Quoted 11 lines
DOCUMENTATION
M: Jonathan Corbet <[email protected]>
L: [email protected]
S: Maintained
F:Documentation/
F:scripts/documentation-file-ref-check
F:scripts/kernel-doc
F:scripts/sphinx-pre-install
X:Documentation/ABI/
X:Documentation/firmware-guide/acpi/
X:Documentation/devicetree/You mean doesn't point to Jon as 'X' is exclude. You missed this entry:
OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS
Quoted 9 lines
M: Rob Herring <[email protected]> M: Mark Rutland <[email protected]> L: [email protected] T: git git://git.kernel.org/pub/scm/linux/kernel/git/robh/linux.git Q: http://patchwork.ozlabs.org/project/devicetree-bindings/list/ S: Maintained F: Documentation/devicetree/ F: arch/*/boot/dts/ F: include/dt-bindings/
Quoted 4 lines
Yeah, I remember I saw something like the above in the past. However, I'm not seeing this entry at the
MAINTAINERSfile at next-20200303 anymore.Did someone removed such entry?
Sorry, false alarm.
It is there at next.
I guess it is time for call it a day.
That doesn't explain why I didn't add DT ML to the c/c. I'll try to verify what's going on tomorrow.
Regards,
Mauro
Hi Mauro,
Quoted 14 lines · Mauro Carvalho Chehab
While most of the devicetree stuff has its own format (with is now being converted to YAML format), some documents there are actually describing the DT concepts and how to contribute to it.
IMHO, those documents would fit perfectly as part of the documentation body, as part of the firmare documents set.
This patch series manually converts some DT documents that, on my opinion, would belong to it.
If you want to see how this would show at the documentation body, a sneak peak of this series (together with the other pending doc patches from me) is available at:
Quoted 7 lines
https://www.infradead.org/~mchehab/kernel_docs/devicetree/index.html
This series is available on this devel branch:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=dt-docs-20200228and it is based on next-20200228
Thanks for doing all of this work! It llooks nice.
-Frank
Quoted 56 lines
-
v2: Fixed my email address and removed extra wrong SoB on all patches.
Mauro Carvalho Chehab (12):
docs: dt: add anindex.rstfile for devicetree
docs: dt: convert usage-model.txt to ReST
docs: dt:usage_model.rst: fix link for DT usage
docs: dt: convert booting-without-of.txt to ReST format
docs: dt: convert changesets to ReST
docs: dt: convert dynamic-resolution-notes.txt to ReST
docs: dt: convert of_unittest.txt to ReST
docs: dt: convert overlay-notes.txt to ReST format
docs: dt: minor adjustments atwriting-schema.rst
docs: dt: convert ABI.txt to ReST format
docs: dt: convert submitting-patches.txt to ReST format
docs: dt: convert writing-bindings.txt to ReSTDocumentation/arm/booting.rst | 2 +- Documentation/arm/microchip.rst | 2 +- .../devicetree/bindings/{ABI.txt => ABI.rst} | 5 +- .../devicetree/bindings/arm/amlogic.yaml | 2 +- .../devicetree/bindings/arm/syna.txt | 2 +- Documentation/devicetree/bindings/index.rst | 12 + ...ing-patches.txt => submitting-patches.rst} | 12 +- ...ting-bindings.txt => writing-bindings.rst} | 9 +- ...-without-of.txt => booting-without-of.rst} | 299 ++++++++++-------- .../{changesets.txt => changesets.rst} | 24 +- ...notes.txt => dynamic-resolution-notes.rst} | 5 +- Documentation/devicetree/index.rst | 18 ++ .../{of_unittest.txt => of_unittest.rst} | 186 +++++------ .../{overlay-notes.txt => overlay-notes.rst} | 143 +++++---- .../{usage-model.txt => usage-model.rst} | 35 +- Documentation/devicetree/writing-schema.rst | 9 +- Documentation/index.rst | 3 + Documentation/process/submitting-patches.rst | 2 +- .../it_IT/process/submitting-patches.rst | 2 +- Documentation/translations/zh_CN/arm/Booting | 2 +- MAINTAINERS | 4 +- include/linux/mfd/core.h | 2 +- scripts/checkpatch.pl | 2 +- 23 files changed, 446 insertions(+), 336 deletions(-) rename Documentation/devicetree/bindings/{ABI.txt => ABI.rst} (94%) create mode 100644 Documentation/devicetree/bindings/index.rst rename Documentation/devicetree/bindings/{submitting-patches.txt => submitting-patches.rst} (92%) rename Documentation/devicetree/bindings/{writing-bindings.txt => writing-bindings.rst} (89%) rename Documentation/devicetree/{booting-without-of.txt => booting-without-of.rst} (90%) rename Documentation/devicetree/{changesets.txt => changesets.rst} (59%) rename Documentation/devicetree/{dynamic-resolution-notes.txt => dynamic-resolution-notes.rst} (90%) create mode 100644 Documentation/devicetree/index.rst rename Documentation/devicetree/{of_unittest.txt => of_unittest.rst} (54%) rename Documentation/devicetree/{overlay-notes.txt => overlay-notes.rst} (56%) rename Documentation/devicetree/{usage-model.txt => usage-model.rst} (97%)