Skip to contentSkip to conversation

Convert some DT documentation files to ReST

PATCH In review Mauro Carvalho Chehab 3 participants 15 messages Apr 15, 2020 – May 5, 2020

Subsystems (7)
lore
Share & tools
lore
#0 lore raw

v3 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

-

v3:
- rebased on the top of next-20200414

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.25.2
#1 lore raw

PATCH v3 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
new file mode 100644
index 000000000000..a11efe26f205
@@ -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
index 9599c0f3eea8..c7f89cb204d1 100644
@@ -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.25.2
#2 lore raw

PATCH v3 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
index a11efe26f205..7a6aad7d384a 100644
@@ -7,4 +7,5 @@ Open Firmware and Device Tree
 .. toctree::
    :maxdepth: 1
 
+   usage-model
    writing-schema
Documentation/devicetree/of_unittest.txt +1 -1
index 3e4e7d48ae93..9fdd2de9b770 100644
@@ -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
similarity index 97%
rename from Documentation/devicetree/usage-model.txt
rename to Documentation/devicetree/usage-model.rst
index 33a8aaac02a8..326d7af10c5b 100644
@@ -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
index d01d1299e49d..21718c8b2b48 100644
@@ -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.25.2
Acked-by on v3 2/12
#3 lore raw

Re: [PATCH v3 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 to devicetree/index.rst.

Quoted 7 lines
---
 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
#4 lore raw

PATCH v3 3/12 docs: dt: usage_model.rst: fix link for DT usage

In reply to Mauro Carvalho Chehab

The 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
index 326d7af10c5b..e1b42dc63f01 100644
@@ -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.25.2
#5 lore raw

PATCH v3 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
index 4babb6c6ae1e..a2263451dc2c 100644
@@ -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
index 7a6aad7d384a..6b4daf252375 100644
@@ -9,3 +9,4 @@ Open Firmware and Device Tree
 
    usage-model
    writing-schema
+   booting-without-of
Documentation/translations/zh_CN/arm/Booting +1 -1
index 562e9a2957e6..c3d26ce5f6de 100644
@@ -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.25.2
#6 lore raw

PATCH v3 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
similarity index 59%
rename from Documentation/devicetree/changesets.txt
rename to Documentation/devicetree/changesets.rst
index cb488eeb6353..c7fd8cd6a270 100644
@@ -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
index 6b4daf252375..64c78c3ffea6 100644
@@ -10,3 +10,4 @@ Open Firmware and Device Tree
    usage-model
    writing-schema
    booting-without-of
+   changesets
Signature · 1 line
2.25.2
#7 lore raw

PATCH v3 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
similarity index 90%
rename from Documentation/devicetree/dynamic-resolution-notes.txt
rename to Documentation/devicetree/dynamic-resolution-notes.rst
index c24ec366c5dc..570b7e1f39eb 100644
@@ -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
index 64c78c3ffea6..308cac9d7021 100644
@@ -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
index 725fb8d255c1..3f20a39e4bc2 100644
@@ -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
index 58725773cec4..12fb85313e1b 100644
@@ -12553,7 +12553,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.25.2
#8 lore raw

PATCH v3 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
index 308cac9d7021..ca83258fbba5 100644
@@ -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.25.2
#9 lore raw

PATCH v3 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
index ca83258fbba5..0669a53fc617 100644
@@ -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
index 12fb85313e1b..4da583422186 100644
@@ -12554,7 +12554,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.25.2
#10 lore raw

PATCH v3 9/12 docs: dt: minor adjustments at writing-schema.rst

In reply to Mauro Carvalho Chehab

There 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
index 220cf464ed77..8c74a99f95e2 100644
@@ -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.25.2
#11 lore raw

PATCH v3 10/12 docs: dt: convert ABI.txt to ReST format

In reply to Mauro Carvalho Chehab

This 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.rst
Documentation/arm/microchip.rst +1 -1
index 05e5f2dfb814..9c013299fd3b 100644
@@ -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
similarity index 94%
rename from Documentation/devicetree/bindings/ABI.txt
rename to Documentation/devicetree/bindings/ABI.rst
index d25f8d379680..a885713cf184 100644
@@ -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
index f74aba48cec1..a21ce4ad63f6 100644
@@ -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
index 2face46a5f64..d8b48f2edf1b 100644
@@ -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
new file mode 100644
index 000000000000..98ebdab24b51
@@ -0,0 +1,10 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========
+Device Tree
+===========
+
+.. toctree::
+   :maxdepth: 1
+
+   ABI
Documentation/devicetree/index.rst +2 -0
index 0669a53fc617..2f2c93c75713 100644
@@ -14,3 +14,5 @@ Open Firmware and Device Tree
    dynamic-resolution-notes
    of_unittest
    overlay-notes
+
+   bindings/index
Signature · 1 line
2.25.2
#12 lore raw

PATCH v3 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
index 98ebdab24b51..6b87875a049c 100644
@@ -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
similarity index 92%
rename from Documentation/devicetree/bindings/submitting-patches.txt
rename to Documentation/devicetree/bindings/submitting-patches.rst
index 98bee6240b65..0aab2b3f16d0 100644
@@ -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
index 27dfd2d8016e..ca024b9c7433 100644
@@ -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
index ba5e944c7a63..1699b7f8e63a 100644
@@ -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
index cba1f8cb61ed..7c23c08e4401 100644
@@ -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
index d64c67b67e3c..7d237a4598ae 100755
@@ -2594,7 +2594,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.25.2
#13 lore raw

PATCH v3 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
index 6b87875a049c..3837b17c234f 100644
@@ -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
similarity index 92%
rename from Documentation/devicetree/bindings/writing-bindings.txt
rename to Documentation/devicetree/bindings/writing-bindings.rst
index ca024b9c7433..45ff426d0019 100644
@@ -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.25.2
#14 lore raw
In reply to Mauro Carvalho Chehab
Quoted 22 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:

https://www.infradead.org/~mchehab/kernel_docs/devicetree/index.html

-

v3:
- rebased on the top of next-20200414

Quoted 13 lines

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

I've applied all but patch 4 as I'm working on just removing it.

Rob