Skip to contentSkip to conversation

Start conversion of PowerPC docs

PATCH In review Tobin C. Harding 4 participants 6 messages Feb 7, 2019 – Feb 8, 2019 Documentation

lore
Share & tools
lore
#0 lore raw

cover Start conversion of PowerPC docs

Hi Michael,

As discussed at LCA here is the start to the docs conversion for PowerPC to RST.

This applies cleanly on top of the mainline (5.20-rc5) and Jon's tree (docs-next branch).

I'm guessing it should go in through the PowerPC tree because I doubt you want to review this Jon, it's one big single patch (all blame for that falls on mpe ;)

This patch converts all the files that do _not_ contain ASCII art - I'm not sure how to go about doing those, suggestions please.

From the commit message:

- Add SPDX license identifier to each new RST file.

    .. SPDX-License-Identifier: GPL-2.0

- User correct heading adornments.

- Make all lines < 72 characters in width.

- Use correct indentation for code blocks, add syntax highlighting

- Sparingly use double ticks if it makes the files easier to parse both in text and on the web.

- Fix any super obvious typos (lean towards not making changes so that we don't introduce errors).

Edited as text files (obviously) and formatted as HTML to verify rendering, no other formats verified.

thanks,
Tobin.

Tobin C. Harding (1):
docs: powerpc: Convert docs to RST format.

 Documentation/index.rst                       |   1 +
 Documentation/powerpc/DAWR-POWER9.rst         |  60 ++++
 Documentation/powerpc/DAWR-POWER9.txt         |  58 ---
 Documentation/powerpc/bootwrapper.rst         | 140 ++++++++
 Documentation/powerpc/bootwrapper.txt         | 141 --------
 Documentation/powerpc/conf.py                 |  10 +
 Documentation/powerpc/cpu_features.rst        |  62 ++++
 Documentation/powerpc/cpu_features.txt        |  56 ---
 .../powerpc/eeh-pci-error-recovery.rst        | 319 +++++++++++++++++
 .../powerpc/eeh-pci-error-recovery.txt        | 334 ------------------
 Documentation/powerpc/index.rst               |  21 ++
 Documentation/powerpc/isa-versions.rst        | 234 ++++++++----
 Documentation/powerpc/mpc52xx.rst             |  52 +++
 Documentation/powerpc/mpc52xx.txt             |  39 --
 Documentation/powerpc/pmu-ebb.rst             | 148 ++++++++
 Documentation/powerpc/pmu-ebb.txt             | 137 -------
 Documentation/powerpc/ptrace.rst              | 177 ++++++++++
 Documentation/powerpc/ptrace.txt              | 151 --------
 .../{syscall64-abi.txt => syscall64-abi.rst}  |  80 +++--
 .../powerpc/transactional_memory.rst          | 259 ++++++++++++++
 .../powerpc/transactional_memory.txt          | 244 -------------
 21 files changed, 1460 insertions(+), 1263 deletions(-)
 create mode 100644 Documentation/powerpc/DAWR-POWER9.rst
 delete mode 100644 Documentation/powerpc/DAWR-POWER9.txt
 create mode 100644 Documentation/powerpc/bootwrapper.rst
 delete mode 100644 Documentation/powerpc/bootwrapper.txt
 create mode 100644 Documentation/powerpc/conf.py
 create mode 100644 Documentation/powerpc/cpu_features.rst
 delete mode 100644 Documentation/powerpc/cpu_features.txt
 create mode 100644 Documentation/powerpc/eeh-pci-error-recovery.rst
 delete mode 100644 Documentation/powerpc/eeh-pci-error-recovery.txt
 create mode 100644 Documentation/powerpc/index.rst
 create mode 100644 Documentation/powerpc/mpc52xx.rst
 delete mode 100644 Documentation/powerpc/mpc52xx.txt
 create mode 100644 Documentation/powerpc/pmu-ebb.rst
 delete mode 100644 Documentation/powerpc/pmu-ebb.txt
 create mode 100644 Documentation/powerpc/ptrace.rst
 delete mode 100644 Documentation/powerpc/ptrace.txt
 rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (58%)
 create mode 100644 Documentation/powerpc/transactional_memory.rst
 delete mode 100644 Documentation/powerpc/transactional_memory.txt
Signature · 1 line
2.20.1
#1 lore raw

PATCH 1/1 docs: powerpc: Convert to RST format

The PowerPC docs have yet to be converted to RST format. Let's kick it off by doing all the files that _don't_ contain ASCII art.

- Add SPDX license identifier to each new RST file.

    .. SPDX-License-Identifier: GPL-2.0

- User correct heading adornments.

- Make all lines < 72 characters in width.

- Use correct indentation for code blocks, add syntax highlighting

- Sparingly use double ticks if it makes the files easier to parse both in text and on the web.

- Fix any super obvious typos (lean towards not making changes so that we don't introduce errors).

Edited as text files (obviously) and formatted as HTML to verify rendering, no other formats verified.

Convert docs to RST format, adding license.

---
 Documentation/index.rst                       |   1 +
 Documentation/powerpc/DAWR-POWER9.rst         |  60 ++++
 Documentation/powerpc/DAWR-POWER9.txt         |  58 ---
 Documentation/powerpc/bootwrapper.rst         | 140 ++++++++
 Documentation/powerpc/bootwrapper.txt         | 141 --------
 Documentation/powerpc/conf.py                 |  10 +
 Documentation/powerpc/cpu_features.rst        |  62 ++++
 Documentation/powerpc/cpu_features.txt        |  56 ---
 .../powerpc/eeh-pci-error-recovery.rst        | 319 +++++++++++++++++
 .../powerpc/eeh-pci-error-recovery.txt        | 334 ------------------
 Documentation/powerpc/index.rst               |  21 ++
 Documentation/powerpc/isa-versions.rst        | 234 ++++++++----
 Documentation/powerpc/mpc52xx.rst             |  52 +++
 Documentation/powerpc/mpc52xx.txt             |  39 --
 Documentation/powerpc/pmu-ebb.rst             | 148 ++++++++
 Documentation/powerpc/pmu-ebb.txt             | 137 -------
 Documentation/powerpc/ptrace.rst              | 177 ++++++++++
 Documentation/powerpc/ptrace.txt              | 151 --------
 .../{syscall64-abi.txt => syscall64-abi.rst}  |  80 +++--
 .../powerpc/transactional_memory.rst          | 259 ++++++++++++++
 .../powerpc/transactional_memory.txt          | 244 -------------
 21 files changed, 1460 insertions(+), 1263 deletions(-)
 create mode 100644 Documentation/powerpc/DAWR-POWER9.rst
 delete mode 100644 Documentation/powerpc/DAWR-POWER9.txt
 create mode 100644 Documentation/powerpc/bootwrapper.rst
 delete mode 100644 Documentation/powerpc/bootwrapper.txt
 create mode 100644 Documentation/powerpc/conf.py
 create mode 100644 Documentation/powerpc/cpu_features.rst
 delete mode 100644 Documentation/powerpc/cpu_features.txt
 create mode 100644 Documentation/powerpc/eeh-pci-error-recovery.rst
 delete mode 100644 Documentation/powerpc/eeh-pci-error-recovery.txt
 create mode 100644 Documentation/powerpc/index.rst
 create mode 100644 Documentation/powerpc/mpc52xx.rst
 delete mode 100644 Documentation/powerpc/mpc52xx.txt
 create mode 100644 Documentation/powerpc/pmu-ebb.rst
 delete mode 100644 Documentation/powerpc/pmu-ebb.txt
 create mode 100644 Documentation/powerpc/ptrace.rst
 delete mode 100644 Documentation/powerpc/ptrace.txt
 rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (58%)
 create mode 100644 Documentation/powerpc/transactional_memory.rst
 delete mode 100644 Documentation/powerpc/transactional_memory.txt
Documentation/index.rst +1 -0
index c858c2e66e36..e0cf2e4a78cf 100644
@@ -101,6 +101,7 @@ implementation.
    :maxdepth: 2
 
    sh/index
+   powerpc/index
 
 Filesystem Documentation
 ------------------------
Documentation/powerpc/DAWR-POWER9.rst new file +60 -0

60 lines not on this page · raw message

Documentation/powerpc/DAWR-POWER9.txt deleted +0 -58

58 lines not on this page · raw message

Documentation/powerpc/bootwrapper.rst new file +140 -0

140 lines not on this page · raw message

Documentation/powerpc/bootwrapper.txt deleted +0 -141

141 lines not on this page · raw message

Documentation/powerpc/conf.py new file +10 -0
new file mode 100644
index 000000000000..aba67e9e8235
@@ -0,0 +1,10 @@
+# -*- coding: utf-8; mode: python -*-
+
+project = 'PowerPC Documentation'
+
+tags.add("subproject")
+
+latex_documents = [
+    ('index', 'powerpc.tex', 'Linux Kernel Development Documentation',
+     'The kernel development community', 'manual'),
+]
Documentation/powerpc/cpu_features.rst new file +62 -0

62 lines not on this page · raw message

Documentation/powerpc/cpu_features.txt deleted +0 -56

56 lines not on this page · raw message

Documentation/powerpc/eeh-pci-error-recovery.rst new file +319 -0

319 lines not on this page · raw message

Documentation/powerpc/eeh-pci-error-recovery.txt deleted +0 -334

334 lines not on this page · raw message

Documentation/powerpc/index.rst new file +21 -0
new file mode 100644
index 000000000000..21e05d09bb42
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
+PowerPC Documentation
+=====================
+
+Documentation relating to the PowerPC architecture.
+
+.. toctree::
+   :maxdepth: 2
+
+   DAWR-POWER9
+   bootwrapper
+   cpu_features
+   eeh-pci-error-recovery
+   isa-versions
+   mpc52xx
+   pmu-ebb
+   ptrace
+   syscall64-abi
+   transactional_memory
Documentation/powerpc/isa-versions.rst +168 -66

242 lines not on this page · raw message

Documentation/powerpc/mpc52xx.rst new file +52 -0

52 lines not on this page · raw message

Documentation/powerpc/mpc52xx.txt deleted +0 -39
deleted file mode 100644
index 0d540a31ea1a..000000000000
@@ -1,39 +0,0 @@
-Linux 2.6.x on MPC52xx family
------------------------------
-
-For the latest info, go to http://www.246tNt.com/mpc52xx/
-
-To compile/use :
-
-  - U-Boot:
-     # <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
-        if you wish to ).
-     # make lite5200_defconfig
-     # make uImage
-
-     then, on U-boot:
-     => tftpboot 200000 uImage
-     => tftpboot 400000 pRamdisk
-     => bootm 200000 400000
-
-  - DBug:
-     # <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
-        if you wish to ).
-     # make lite5200_defconfig
-     # cp your_initrd.gz arch/ppc/boot/images/ramdisk.image.gz
-     # make zImage.initrd
-     # make
-
-     then in DBug:
-     DBug> dn -i zImage.initrd.lite5200
-
-
-Some remarks :
- - The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100
-   is not supported, and I'm not sure anyone is interesting in working on it
-   so. I didn't took 5xxx because there's apparently a lot of 5xxx that have
-   nothing to do with the MPC5200. I also included the 'MPC' for the same
-   reason.
- - Of course, I inspired myself from the 2.4 port. If you think I forgot to
-   mention you/your company in the copyright of some code, I'll correct it
-   ASAP.
Documentation/powerpc/pmu-ebb.rst new file +148 -0

148 lines not on this page · raw message

Documentation/powerpc/pmu-ebb.txt deleted +0 -137

137 lines not on this page · raw message

Documentation/powerpc/ptrace.rst new file +177 -0

177 lines not on this page · raw message

Documentation/powerpc/ptrace.txt deleted +0 -151

151 lines not on this page · raw message

Documentation/powerpc/syscall64-abi.rst renamed from Documentation/powerpc/syscall64-abi.txt +43 -37

129 lines not on this page · raw message

Documentation/powerpc/transactional_memory.rst new file +259 -0

259 lines not on this page · raw message

Documentation/powerpc/transactional_memory.txt deleted +0 -244

244 lines not on this page · raw message

Signature · 1 line
2.20.1
reviewer Acked-by Tested-by on v1 1/1
#2 lore raw

Re: [PATCH 1/1] docs: powerpc: Convert to RST format

Quoted 19 lines · Tobin C. Harding

The PowerPC docs have yet to be converted to RST format. Let's kick it off by doing all the files that _don't_ contain ASCII art.

- Add SPDX license identifier to each new RST file.

    .. SPDX-License-Identifier: GPL-2.0

- User correct heading adornments.

- Make all lines < 72 characters in width.

- Use correct indentation for code blocks, add syntax highlighting

- Sparingly use double ticks if it makes the files easier to parse both in text and on the web.

- Fix any super obvious typos (lean towards not making changes so that we don't introduce errors).

Quoted 6 lines

Edited as text files (obviously) and formatted as HTML to verify rendering, no other formats verified.

Convert docs to RST format, adding license.

thanks.

Quoted 42 lines
---
 Documentation/index.rst                       |   1 +
 Documentation/powerpc/DAWR-POWER9.rst         |  60 ++++
 Documentation/powerpc/DAWR-POWER9.txt         |  58 ---
 Documentation/powerpc/bootwrapper.rst         | 140 ++++++++
 Documentation/powerpc/bootwrapper.txt         | 141 --------
 Documentation/powerpc/conf.py                 |  10 +
 Documentation/powerpc/cpu_features.rst        |  62 ++++
 Documentation/powerpc/cpu_features.txt        |  56 ---
 .../powerpc/eeh-pci-error-recovery.rst        | 319 +++++++++++++++++
 .../powerpc/eeh-pci-error-recovery.txt        | 334 ------------------
 Documentation/powerpc/index.rst               |  21 ++
 Documentation/powerpc/isa-versions.rst        | 234 ++++++++----
 Documentation/powerpc/mpc52xx.rst             |  52 +++
 Documentation/powerpc/mpc52xx.txt             |  39 --
 Documentation/powerpc/pmu-ebb.rst             | 148 ++++++++
 Documentation/powerpc/pmu-ebb.txt             | 137 -------
 Documentation/powerpc/ptrace.rst              | 177 ++++++++++
 Documentation/powerpc/ptrace.txt              | 151 --------
 .../{syscall64-abi.txt => syscall64-abi.rst}  |  80 +++--
 .../powerpc/transactional_memory.rst          | 259 ++++++++++++++
 .../powerpc/transactional_memory.txt          | 244 -------------
 21 files changed, 1460 insertions(+), 1263 deletions(-)
 create mode 100644 Documentation/powerpc/DAWR-POWER9.rst
 delete mode 100644 Documentation/powerpc/DAWR-POWER9.txt
 create mode 100644 Documentation/powerpc/bootwrapper.rst
 delete mode 100644 Documentation/powerpc/bootwrapper.txt
 create mode 100644 Documentation/powerpc/conf.py
 create mode 100644 Documentation/powerpc/cpu_features.rst
 delete mode 100644 Documentation/powerpc/cpu_features.txt
 create mode 100644 Documentation/powerpc/eeh-pci-error-recovery.rst
 delete mode 100644 Documentation/powerpc/eeh-pci-error-recovery.txt
 create mode 100644 Documentation/powerpc/index.rst
 create mode 100644 Documentation/powerpc/mpc52xx.rst
 delete mode 100644 Documentation/powerpc/mpc52xx.txt
 create mode 100644 Documentation/powerpc/pmu-ebb.rst
 delete mode 100644 Documentation/powerpc/pmu-ebb.txt
 create mode 100644 Documentation/powerpc/ptrace.rst
 delete mode 100644 Documentation/powerpc/ptrace.txt
 rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (58%)
 create mode 100644 Documentation/powerpc/transactional_memory.rst
 delete mode 100644 Documentation/powerpc/transactional_memory.txt
Signature · 1 line
~Randy
maintainer
#3 lore raw
In reply to Tobin C. Harding
Quoted 9 lines · On Thu, 7 Feb 2019 17:03:15 +1100 "Tobin C. Harding" <[email protected]> wrote:

As discussed at LCA here is the start to the docs conversion for PowerPC to RST.

This applies cleanly on top of the mainline (5.20-rc5) and Jon's tree (docs-next branch).

I'm guessing it should go in through the PowerPC tree because I doubt you want to review this Jon, it's one big single patch (all blame for that falls on mpe ;)

Well, I went and took a look anyway, being a glutton for punishment. So naturally I do have some comments...

- I don't think this should be a top-level directory full of docs; the top level is already rather overpopulated. At worst, we should create an arch/ directory for architecture-specific docs. I kind of think that this should be thought through a bit more, though, with an eye toward who the audience is. Some of it is clearly developer documentation, and some of it is aimed at admins; ptrace.rst is user-space API stuff. Nobody ever welcomes me saying this, but we should really split things into the appropriate manuals according to audience.

- It would be good to know how much of this stuff is still relevant. bootwrapper.txt hasn't been modified since it was added in 2008. cpu_features.txt predates the git era, as does mpc52xx.txt; hvcs.txt is nearly as old. And so on. Can we perhaps stop dragging some of those docs around?

- The use of flat-table in isa-versions.rst totally wrecks the readability of those tables in the plain-text version. Said tables are pretty close to being RST in their original form; it would be far better to just fix anything needing fixing but to keep that form.

- I'm glad you're adding SPDX lines, but do you know that the license is correct in each case? It's best to be careful with such things.

Thanks,

jon

#4 lore raw
Quoted 13 lines · Jonathan Corbet
Quoted 9 lines · On Thu, 7 Feb 2019 17:03:15 +1100 "Tobin C. Harding" <[email protected]> wrote:

As discussed at LCA here is the start to the docs conversion for PowerPC to RST.

This applies cleanly on top of the mainline (5.20-rc5) and Jon's tree (docs-next branch).

I'm guessing it should go in through the PowerPC tree because I doubt you want to review this Jon, it's one big single patch (all blame for that falls on mpe ;)

Quoted 6 lines

Well, I went and took a look anyway, being a glutton for punishment. So naturally I do have some comments...

- I don't think this should be a top-level directory full of docs; the top level is already rather overpopulated. At worst, we should create an arch/ directory for architecture-specific docs.

We currently have arch specific directories for arm, arm64, ia64, m68k, nios2, openrisc, parisc, powerpc, s390, sh, sparc, x86, xtensa.

Do you mean they should all be moved to Documentation/arch ?

Quoted 6 lines

I kind of think that
this should be thought through a bit more, though, with an eye toward who the audience is. Some of it is clearly developer documentation, and some of it is aimed at admins; ptrace.rst is user-space API stuff. Nobody ever welcomes me saying this, but we should really split things into the appropriate manuals according to audience.

I don't think any of it's aimed at admins, but I haven't read every word. I see it as aimed at kernel devs or people writing directly to the kernel API, eg. gdb developers reading ptrace.rst.

If Documentation/ wants to be more user focused and nicely curated perhaps we need arch/foo/docs/ for these developer centric docs?

Quoted 2 lines

- It would be good to know how much of this stuff is still relevant. bootwrapper.txt hasn't been modified since it was added in 2008.

It hasn't been modified but AFAIK it's still pretty much accurate and definitely something we want to have documented.

Quoted 1 line

cpu_features.txt predates the git era

But so does the code it's documenting.

Quoted 2 lines

as does mpc52xx.txt; hvcs.txt is nearly as old. And so on. Can we perhaps stop dragging some of those docs around?

We support some hardware that is ~25 years old, so we have some old documentation too, and I'd rather we didn't drop things just because they're old.

Quoted 4 lines

- The use of flat-table in isa-versions.rst totally wrecks the readability of those tables in the plain-text version. Said tables are pretty close to being RST in their original form; it would be far better to just fix anything needing fixing but to keep that form.

Yes agree, I'd like the docs to be as readable as possible as plain text.

Quoted 2 lines

- I'm glad you're adding SPDX lines, but do you know that the license is correct in each case? It's best to be careful with such things.

None of the files have licenses so I think we just fall back to COPYING don't we? In which case GPL-2.0 is correct for all files.

cheers

maintainer
#5 lore raw
Quoted 8 lines · On Fri, 08 Feb 2019 14:40:28 +1100 Michael Ellerman <[email protected]> wrote:
Quoted 3 lines

- I don't think this should be a top-level directory full of docs; the top level is already rather overpopulated. At worst, we should create an arch/ directory for architecture-specific docs.

We currently have arch specific directories for arm, arm64, ia64, m68k, nios2, openrisc, parisc, powerpc, s390, sh, sparc, x86, xtensa.

Do you mean they should all be moved to Documentation/arch ?

Over time I'm really trying to bring some organization to Documentation/, and to have that reflected in an RST tree that looks like somebody actually thought about it. So yes, I would eventually like to see something like Documentation/arch, just like we have arch/ in the top-level directory.

Quoted 7 lines
Quoted 6 lines

I kind of think that
this should be thought through a bit more, though, with an eye toward who the audience is. Some of it is clearly developer documentation, and some of it is aimed at admins; ptrace.rst is user-space API stuff. Nobody ever welcomes me saying this, but we should really split things into the appropriate manuals according to audience.

Quoted 6 lines

I don't think any of it's aimed at admins, but I haven't read every word. I see it as aimed at kernel devs or people writing directly to the kernel API, eg. gdb developers reading ptrace.rst.

If Documentation/ wants to be more user focused and nicely curated perhaps we need arch/foo/docs/ for these developer centric docs?

Stuff for GDB developers is best placed in the userspace-api docbook; we're trying to concentrate that there. Stuff for kernel developers is a bit more diffuse still; arch/foo/docs may end up being the best place for it in the end, yes.

Quoted 5 lines
Quoted 2 lines

- It would be good to know how much of this stuff is still relevant. bootwrapper.txt hasn't been modified since it was added in 2008.

It hasn't been modified but AFAIK it's still pretty much accurate and definitely something we want to have documented.

That's fine for this (and all the others); I'm just hoping that somebody has thought about it. We're carrying a *lot* of dusty old stuff that, IMO, can only serve to confuse those who read it. If these files don't fall into that category, that's great.

Quoted 3 lines

We support some hardware that is ~25 years old, so we have some old documentation too, and I'd rather we didn't drop things just because they're old.

I agree, as long as they remain correct and relevant.

Quoted 5 lines
Quoted 2 lines

- I'm glad you're adding SPDX lines, but do you know that the license is correct in each case? It's best to be careful with such things.

None of the files have licenses so I think we just fall back to COPYING don't we? In which case GPL-2.0 is correct for all files.

That's often the best choice, though some people have resorted to some rather more in-depth archeology to try to figure out what the original author actually intended. Again, I'm just asking so that we're sure it's the best choice.

Thanks,

jon