[PATCH v2 49/79] docs: arm: convert docs to ReST and rename to *.rst

[PATCH v2 49/79] docs: arm: convert docs to ReST and rename to *.rst

[Mauro Carvalho Chehab]

Converts ARM the text files to ReST, preparing them to be an
architecture book.

The conversion is actually:
  - add blank lines and identation in order to identify paragraphs;
  - fix tables markups;
  - add some lists markups;
  - mark literal blocks;
  - adjust title markups.

At its new index.rst, let's add a :orphan: while this is not linked to
the main index.rst file, in order to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/arm/Marvell/README              | 395 --------------
 Documentation/arm/Netwinder                   |  78 ---
 Documentation/arm/SA1100/FreeBird             |  21 -
 Documentation/arm/SA1100/empeg                |   2 -
 Documentation/arm/SA1100/serial_UART          |  47 --
 Documentation/arm/{README => arm.rst}         |  50 +-
 Documentation/arm/{Booting => booting.rst}    |  71 ++-
 ...ance.txt => cluster-pm-race-avoidance.rst} | 177 ++++---
 .../arm/{firmware.txt => firmware.rst}        |  14 +-
 Documentation/arm/index.rst                   |  80 +++
 .../arm/{Interrupts => interrupts.rst}        |  86 +--
 Documentation/arm/{IXP4xx => ixp4xx.rst}      |  61 +--
 ...nel_mode_neon.txt => kernel_mode_neon.rst} |   3 +
 ...er_helpers.txt => kernel_user_helpers.rst} |  79 +--
 .../keystone/{knav-qmss.txt => knav-qmss.rst} |   6 +-
 .../keystone/{Overview.txt => overview.rst}   |  47 +-
 Documentation/arm/marvel.rst                  | 488 ++++++++++++++++++
 .../arm/{mem_alignment => mem_alignment.rst}  |  11 +-
 Documentation/arm/{memory.txt => memory.rst}  |   9 +-
 .../arm/{Microchip/README => microchip.rst}   |  63 ++-
 Documentation/arm/netwinder.rst               |  85 +++
 Documentation/arm/nwfpe/index.rst             |  11 +
 .../nwfpe/{README.FPE => netwinder-fpe.rst}   |  24 +-
 Documentation/arm/nwfpe/{NOTES => notes.rst}  |   3 +
 Documentation/arm/nwfpe/{README => nwfpe.rst} |  10 +-
 Documentation/arm/nwfpe/{TODO => todo.rst}    |  47 +-
 Documentation/arm/{OMAP/DSS => omap/dss.rst}  | 112 ++--
 Documentation/arm/omap/index.rst              |  10 +
 .../arm/{OMAP/README => omap/omap.rst}        |   7 +
 .../arm/{OMAP/omap_pm => omap/omap_pm.rst}    |  55 +-
 Documentation/arm/{Porting => porting.rst}    |  14 +-
 Documentation/arm/pxa/{mfp.txt => mfp.rst}    | 106 ++--
 .../{SA1100/ADSBitsy => sa1100/adsbitsy.rst}  |  14 +-
 .../{SA1100/Assabet => sa1100/assabet.rst}    | 185 +++----
 .../arm/{SA1100/Brutus => sa1100/brutus.rst}  |  45 +-
 .../arm/{SA1100/CERF => sa1100/cerf.rst}      |  10 +-
 Documentation/arm/sa1100/freebird.rst         |  25 +
 .../graphicsclient.rst}                       |  46 +-
 .../graphicsmaster.rst}                       |  13 +-
 .../HUW_WEBPANEL => sa1100/huw_webpanel.rst}  |   8 +-
 Documentation/arm/sa1100/index.rst            |  23 +
 .../arm/{SA1100/Itsy => sa1100/itsy.rst}      |  14 +-
 .../arm/{SA1100/LART => sa1100/lart.rst}      |   3 +-
 .../nanoEngine => sa1100/nanoengine.rst}      |   6 +-
 .../{SA1100/Pangolin => sa1100/pangolin.rst}  |  10 +-
 .../arm/{SA1100/PLEB => sa1100/pleb.rst}      |   6 +-
 Documentation/arm/sa1100/serial_uart.rst      |  51 ++
 .../arm/{SA1100/Tifon => sa1100/tifon.rst}    |   4 +-
 .../arm/{SA1100/Yopy => sa1100/yopy.rst}      |   5 +-
 .../cpufreq.rst}                              |   5 +-
 .../eb2410itx.rst}                            |   5 +-
 .../GPIO.txt => samsung-s3c24xx/gpio.rst}     |  23 +-
 .../H1940.txt => samsung-s3c24xx/h1940.rst}   |   5 +-
 Documentation/arm/samsung-s3c24xx/index.rst   |  18 +
 .../NAND.txt => samsung-s3c24xx/nand.rst}     |   6 +-
 .../overview.rst}                             |  21 +-
 .../s3c2412.rst}                              |   5 +-
 .../s3c2413.rst}                              |   7 +-
 .../smdk2440.rst}                             |   5 +-
 .../suspend.rst}                              |  20 +-
 .../usb-host.rst}                             |  16 +-
 .../bootloader-interface.rst}                 |  27 +-
 .../clksrc-change-registers.awk               |   0
 .../{Samsung/GPIO.txt => samsung/gpio.rst}    |   7 +-
 Documentation/arm/samsung/index.rst           |  10 +
 .../Overview.txt => samsung/overview.rst}     |  15 +-
 Documentation/arm/{Setup => setup.rst}        |  49 +-
 .../arm/{SH-Mobile => sh-mobile}/.gitignore   |   0
 .../overview.txt => spear/overview.rst}       |  20 +-
 .../arm/sti/{overview.txt => overview.rst}    |  21 +-
 ...h407-overview.txt => stih407-overview.rst} |   9 +-
 ...h415-overview.txt => stih415-overview.rst} |   8 +-
 ...h416-overview.txt => stih416-overview.rst} |   5 +-
 ...h418-overview.txt => stih418-overview.rst} |   9 +-
 .../arm/stm32/stm32f429-overview.rst          |   5 +-
 .../arm/stm32/stm32f746-overview.rst          |   5 +-
 .../arm/stm32/stm32f769-overview.rst          |   5 +-
 .../arm/stm32/stm32h743-overview.rst          |   5 +-
 .../arm/stm32/stm32mp157-overview.rst         |   1 +
 Documentation/arm/{sunxi/README => sunxi.rst} |  98 +++-
 .../arm/sunxi/{clocks.txt => clocks.rst}      |   7 +-
 .../arm/{swp_emulation => swp_emulation.rst}  |  24 +-
 Documentation/arm/{tcm.txt => tcm.rst}        |  54 +-
 Documentation/arm/{uefi.txt => uefi.rst}      |  39 +-
 .../release-notes.rst}                        |   4 +-
 Documentation/arm/{vlocks.txt => vlocks.rst}  |   9 +-
 Documentation/devicetree/bindings/arm/xen.txt |   2 +-
 .../devicetree/booting-without-of.txt         |   4 +-
 Documentation/index.rst                       |   1 +
 Documentation/translations/zh_CN/arm/Booting  |   4 +-
 .../zh_CN/arm/kernel_user_helpers.txt         |   4 +-
 MAINTAINERS                                   |   4 +-
 arch/arm/Kconfig                              |   2 +-
 arch/arm/common/mcpm_entry.c                  |   2 +-
 arch/arm/common/mcpm_head.S                   |   2 +-
 arch/arm/common/vlock.S                       |   2 +-
 arch/arm/include/asm/setup.h                  |   2 +-
 arch/arm/include/uapi/asm/setup.h             |   2 +-
 arch/arm/kernel/entry-armv.S                  |   2 +-
 arch/arm/mach-exynos/common.h                 |   2 +-
 arch/arm/mach-ixp4xx/Kconfig                  |  14 +-
 arch/arm/mach-s3c24xx/pm.c                    |   2 +-
 arch/arm/mm/Kconfig                           |   4 +-
 arch/arm/plat-samsung/Kconfig                 |   6 +-
 arch/arm/tools/mach-types                     |   2 +-
 arch/arm64/kernel/kuser32.S                   |   2 +-
 arch/mips/bmips/setup.c                       |   2 +-
 drivers/crypto/sunxi-ss/sun4i-ss-cipher.c     |   2 +-
 drivers/crypto/sunxi-ss/sun4i-ss-core.c       |   2 +-
 drivers/crypto/sunxi-ss/sun4i-ss-hash.c       |   2 +-
 drivers/crypto/sunxi-ss/sun4i-ss.h            |   2 +-
 drivers/input/touchscreen/sun4i-ts.c          |   2 +-
 drivers/tty/serial/Kconfig                    |   2 +-
 113 files changed, 1984 insertions(+), 1407 deletions(-)
 delete mode 100644 Documentation/arm/Marvell/README
 delete mode 100644 Documentation/arm/Netwinder
 delete mode 100644 Documentation/arm/SA1100/FreeBird
 delete mode 100644 Documentation/arm/SA1100/empeg
 delete mode 100644 Documentation/arm/SA1100/serial_UART
 rename Documentation/arm/{README => arm.rst} (88%)
 rename Documentation/arm/{Booting => booting.rst} (89%)
 rename Documentation/arm/{cluster-pm-race-avoidance.txt => cluster-pm-race-avoidance.rst} (84%)
 rename Documentation/arm/{firmware.txt => firmware.rst} (86%)
 create mode 100644 Documentation/arm/index.rst
 rename Documentation/arm/{Interrupts => interrupts.rst} (81%)
 rename Documentation/arm/{IXP4xx => ixp4xx.rst} (84%)
 rename Documentation/arm/{kernel_mode_neon.txt => kernel_mode_neon.rst} (99%)
 rename Documentation/arm/{kernel_user_helpers.txt => kernel_user_helpers.rst} (78%)
 rename Documentation/arm/keystone/{knav-qmss.txt => knav-qmss.rst} (92%)
 rename Documentation/arm/keystone/{Overview.txt => overview.rst} (59%)
 create mode 100644 Documentation/arm/marvel.rst
 rename Documentation/arm/{mem_alignment => mem_alignment.rst} (89%)
 rename Documentation/arm/{memory.txt => memory.rst} (90%)
 rename Documentation/arm/{Microchip/README => microchip.rst} (92%)
 create mode 100644 Documentation/arm/netwinder.rst
 create mode 100644 Documentation/arm/nwfpe/index.rst
 rename Documentation/arm/nwfpe/{README.FPE => netwinder-fpe.rst} (94%)
 rename Documentation/arm/nwfpe/{NOTES => notes.rst} (99%)
 rename Documentation/arm/nwfpe/{README => nwfpe.rst} (98%)
 rename Documentation/arm/nwfpe/{TODO => todo.rst} (75%)
 rename Documentation/arm/{OMAP/DSS => omap/dss.rst} (86%)
 create mode 100644 Documentation/arm/omap/index.rst
 rename Documentation/arm/{OMAP/README => omap/omap.rst} (62%)
 rename Documentation/arm/{OMAP/omap_pm => omap/omap_pm.rst} (83%)
 rename Documentation/arm/{Porting => porting.rst} (94%)
 rename Documentation/arm/pxa/{mfp.txt => mfp.rst} (83%)
 rename Documentation/arm/{SA1100/ADSBitsy => sa1100/adsbitsy.rst} (90%)
 rename Documentation/arm/{SA1100/Assabet => sa1100/assabet.rst} (62%)
 rename Documentation/arm/{SA1100/Brutus => sa1100/brutus.rst} (75%)
 rename Documentation/arm/{SA1100/CERF => sa1100/cerf.rst} (91%)
 create mode 100644 Documentation/arm/sa1100/freebird.rst
 rename Documentation/arm/{SA1100/GraphicsClient => sa1100/graphicsclient.rst} (87%)
 rename Documentation/arm/{SA1100/GraphicsMaster => sa1100/graphicsmaster.rst} (92%)
 rename Documentation/arm/{SA1100/HUW_WEBPANEL => sa1100/huw_webpanel.rst} (78%)
 create mode 100644 Documentation/arm/sa1100/index.rst
 rename Documentation/arm/{SA1100/Itsy => sa1100/itsy.rst} (88%)
 rename Documentation/arm/{SA1100/LART => sa1100/lart.rst} (90%)
 rename Documentation/arm/{SA1100/nanoEngine => sa1100/nanoengine.rst} (74%)
 rename Documentation/arm/{SA1100/Pangolin => sa1100/pangolin.rst} (81%)
 rename Documentation/arm/{SA1100/PLEB => sa1100/pleb.rst} (95%)
 create mode 100644 Documentation/arm/sa1100/serial_uart.rst
 rename Documentation/arm/{SA1100/Tifon => sa1100/tifon.rst} (88%)
 rename Documentation/arm/{SA1100/Yopy => sa1100/yopy.rst} (74%)
 rename Documentation/arm/{Samsung-S3C24XX/CPUfreq.txt => samsung-s3c24xx/cpufreq.rst} (96%)
 rename Documentation/arm/{Samsung-S3C24XX/EB2410ITX.txt => samsung-s3c24xx/eb2410itx.rst} (92%)
 rename Documentation/arm/{Samsung-S3C24XX/GPIO.txt => samsung-s3c24xx/gpio.rst} (89%)
 rename Documentation/arm/{Samsung-S3C24XX/H1940.txt => samsung-s3c24xx/h1940.rst} (94%)
 create mode 100644 Documentation/arm/samsung-s3c24xx/index.rst
 rename Documentation/arm/{Samsung-S3C24XX/NAND.txt => samsung-s3c24xx/nand.rst} (92%)
 rename Documentation/arm/{Samsung-S3C24XX/Overview.txt => samsung-s3c24xx/overview.rst} (94%)
 rename Documentation/arm/{Samsung-S3C24XX/S3C2412.txt => samsung-s3c24xx/s3c2412.rst} (96%)
 rename Documentation/arm/{Samsung-S3C24XX/S3C2413.txt => samsung-s3c24xx/s3c2413.rst} (77%)
 rename Documentation/arm/{Samsung-S3C24XX/SMDK2440.txt => samsung-s3c24xx/smdk2440.rst} (94%)
 rename Documentation/arm/{Samsung-S3C24XX/Suspend.txt => samsung-s3c24xx/suspend.rst} (94%)
 rename Documentation/arm/{Samsung-S3C24XX/USB-Host.txt => samsung-s3c24xx/usb-host.rst} (94%)
 rename Documentation/arm/{Samsung/Bootloader-interface.txt => samsung/bootloader-interface.rst} (72%)
 rename Documentation/arm/{Samsung => samsung}/clksrc-change-registers.awk (100%)
 rename Documentation/arm/{Samsung/GPIO.txt => samsung/gpio.rst} (87%)
 create mode 100644 Documentation/arm/samsung/index.rst
 rename Documentation/arm/{Samsung/Overview.txt => samsung/overview.rst} (86%)
 rename Documentation/arm/{Setup => setup.rst} (87%)
 rename Documentation/arm/{SH-Mobile => sh-mobile}/.gitignore (100%)
 rename Documentation/arm/{SPEAr/overview.txt => spear/overview.rst} (91%)
 rename Documentation/arm/sti/{overview.txt => overview.rst} (82%)
 rename Documentation/arm/sti/{stih407-overview.txt => stih407-overview.rst} (82%)
 rename Documentation/arm/sti/{stih415-overview.txt => stih415-overview.rst} (79%)
 rename Documentation/arm/sti/{stih416-overview.txt => stih416-overview.rst} (83%)
 rename Documentation/arm/sti/{stih418-overview.txt => stih418-overview.rst} (83%)
 rename Documentation/arm/{sunxi/README => sunxi.rst} (83%)
 rename Documentation/arm/sunxi/{clocks.txt => clocks.rst} (92%)
 rename Documentation/arm/{swp_emulation => swp_emulation.rst} (63%)
 rename Documentation/arm/{tcm.txt => tcm.rst} (86%)
 rename Documentation/arm/{uefi.txt => uefi.rst} (63%)
 rename Documentation/arm/{VFP/release-notes.txt => vfp/release-notes.rst} (92%)
 rename Documentation/arm/{vlocks.txt => vlocks.rst} (98%)

diff --git a/Documentation/arm/Marvell/README b/Documentation/arm/Marvell/README
deleted file mode 100644
index 56ada27c53be..000000000000
--- a/Documentation/arm/Marvell/README
+++ /dev/null
@@ -1,395 +0,0 @@
-ARM Marvell SoCs
-================
-
-This document lists all the ARM Marvell SoCs that are currently
-supported in mainline by the Linux kernel. As the Marvell families of
-SoCs are large and complex, it is hard to understand where the support
-for a particular SoC is available in the Linux kernel. This document
-tries to help in understanding where those SoCs are supported, and to
-match them with their corresponding public datasheet, when available.
-
-Orion family
-------------
-
-  Flavors:
-        88F5082
-        88F5181
-        88F5181L
-        88F5182
-               Datasheet               : http://www.embeddedarm.com/documentation/third-party/MV88F5182-datasheet.pdf
-               Programmer's User Guide : http://www.embeddedarm.com/documentation/third-party/MV88F5182-opensource-manual.pdf
-               User Manual             : http://www.embeddedarm.com/documentation/third-party/MV88F5182-usermanual.pdf
-        88F5281
-               Datasheet               : http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf
-        88F6183
-  Core: Feroceon 88fr331 (88f51xx) or 88fr531-vd (88f52xx) ARMv5 compatible
-  Linux kernel mach directory: arch/arm/mach-orion5x
-  Linux kernel plat directory: arch/arm/plat-orion
-
-Kirkwood family
----------------
-
-  Flavors:
-        88F6282 a.k.a Armada 300
-                Product Brief  : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf
-        88F6283 a.k.a Armada 310
-                Product Brief  : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf
-        88F6190
-                Product Brief  : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6190-003_WEB.pdf
-                Hardware Spec  : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf
-                Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf
-        88F6192
-                Product Brief  : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6192-003_ver1.pdf
-                Hardware Spec  : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf
-                Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf
-        88F6182
-        88F6180
-                Product Brief  : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6180-003_ver1.pdf
-                Hardware Spec  : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6180_OpenSource.pdf
-                Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf
-        88F6281
-                Product Brief  : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6281-004_ver1.pdf
-                Hardware Spec  : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6281_OpenSource.pdf
-                Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf
-  Homepage: http://www.marvell.com/embedded-processors/kirkwood/
-  Core: Feroceon 88fr131 ARMv5 compatible
-  Linux kernel mach directory: arch/arm/mach-mvebu
-  Linux kernel plat directory: none
-
-Discovery family
-----------------
-
-  Flavors:
-        MV78100
-                Product Brief  : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78100-003_WEB.pdf
-                Hardware Spec  : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78100_OpenSource.pdf
-                Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf
-        MV78200
-                Product Brief  : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78200-002_WEB.pdf
-                Hardware Spec  : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78200_OpenSource.pdf
-                Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf
-        MV76100
-                Not supported by the Linux kernel.
-
-  Core: Feroceon 88fr571-vd ARMv5 compatible
-
-  Linux kernel mach directory: arch/arm/mach-mv78xx0
-  Linux kernel plat directory: arch/arm/plat-orion
-
-EBU Armada family
------------------
-
-  Armada 370 Flavors:
-        88F6710
-        88F6707
-        88F6W11
-    Product Brief:   http://www.marvell.com/embedded-processors/armada-300/assets/Marvell_ARMADA_370_SoC.pdf
-    Hardware Spec:   http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-datasheet.pdf
-    Functional Spec: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-FunctionalSpec-datasheet.pdf
-    Core: Sheeva ARMv7 compatible PJ4B
-
-  Armada 375 Flavors:
-	88F6720
-    Product Brief: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA_375_SoC-01_product_brief.pdf
-    Core: ARM Cortex-A9
-
-  Armada 38x Flavors:
-	88F6810	Armada 380
-	88F6820 Armada 385
-	88F6828 Armada 388
-    Product infos:   http://www.marvell.com/embedded-processors/armada-38x/
-    Functional Spec: https://marvellcorp.wufoo.com/forms/marvell-armada-38x-functional-specifications/
-    Core: ARM Cortex-A9
-
-  Armada 39x Flavors:
-	88F6920 Armada 390
-	88F6928 Armada 398
-    Product infos: http://www.marvell.com/embedded-processors/armada-39x/
-    Core: ARM Cortex-A9
-
-  Armada XP Flavors:
-        MV78230
-        MV78260
-        MV78460
-    NOTE: not to be confused with the non-SMP 78xx0 SoCs
-    Product Brief: http://www.marvell.com/embedded-processors/armada-xp/assets/Marvell-ArmadaXP-SoC-product%20brief.pdf
-    Functional Spec: http://www.marvell.com/embedded-processors/armada-xp/assets/ARMADA-XP-Functional-SpecDatasheet.pdf
-    Hardware Specs:
-      http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78230_OS.PDF
-      http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78260_OS.PDF
-      http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78460_OS.PDF
-    Core: Sheeva ARMv7 compatible Dual-core or Quad-core PJ4B-MP
-
-  Linux kernel mach directory: arch/arm/mach-mvebu
-  Linux kernel plat directory: none
-
-EBU Armada family ARMv8
------------------------
-
-  Armada 3710/3720 Flavors:
-	88F3710
-	88F3720
-	Core: ARM Cortex A53 (ARMv8)
-
-	Homepage: http://www.marvell.com/embedded-processors/armada-3700/
-	Product Brief: http://www.marvell.com/embedded-processors/assets/PB-88F3700-FNL.pdf
-	Device tree files: arch/arm64/boot/dts/marvell/armada-37*
-
-  Armada 7K Flavors:
-	88F7020 (AP806 Dual + one CP110)
-	88F7040 (AP806 Quad + one CP110)
-	Core: ARM Cortex A72
-
-	Homepage: http://www.marvell.com/embedded-processors/armada-70xx/
-	Product Brief: http://www.marvell.com/embedded-processors/assets/Armada7020PB-Jan2016.pdf
-		       http://www.marvell.com/embedded-processors/assets/Armada7040PB-Jan2016.pdf
-	Device tree files: arch/arm64/boot/dts/marvell/armada-70*
-
-  Armada 8K Flavors:
-	88F8020 (AP806 Dual + two CP110)
-	88F8040 (AP806 Quad + two CP110)
-	Core: ARM Cortex A72
-
-	Homepage: http://www.marvell.com/embedded-processors/armada-80xx/
-	Product Brief: http://www.marvell.com/embedded-processors/assets/Armada8020PB-Jan2016.pdf
-		       http://www.marvell.com/embedded-processors/assets/Armada8040PB-Jan2016.pdf
-	Device tree files: arch/arm64/boot/dts/marvell/armada-80*
-
-Avanta family
--------------
-
-  Flavors:
-       88F6510
-       88F6530P
-       88F6550
-       88F6560
-  Homepage     : http://www.marvell.com/broadband/
-  Product Brief: http://www.marvell.com/broadband/assets/Marvell_Avanta_88F6510_305_060-001_product_brief.pdf
-  No public datasheet available.
-
-  Core: ARMv5 compatible
-
-  Linux kernel mach directory: no code in mainline yet, planned for the future
-  Linux kernel plat directory: no code in mainline yet, planned for the future
-
-Storage family
---------------
-
-  Armada SP:
-	88RC1580
-    Product infos: http://www.marvell.com/storage/armada-sp/
-    Core: Sheeva ARMv7 comatible Quad-core PJ4C
-    (not supported in upstream Linux kernel)
-
-Dove family (application processor)
------------------------------------
-
-  Flavors:
-        88AP510 a.k.a Armada 510
-                Product Brief   : http://www.marvell.com/application-processors/armada-500/assets/Marvell_Armada510_SoC.pdf
-                Hardware Spec   : http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Hardware-Spec.pdf
-                Functional Spec : http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Functional-Spec.pdf
-  Homepage: http://www.marvell.com/application-processors/armada-500/
-  Core: ARMv7 compatible
-
-  Directory: arch/arm/mach-mvebu (DT enabled platforms)
-             arch/arm/mach-dove (non-DT enabled platforms)
-
-PXA 2xx/3xx/93x/95x family
---------------------------
-
-  Flavors:
-        PXA21x, PXA25x, PXA26x
-             Application processor only
-             Core: ARMv5 XScale1 core
-        PXA270, PXA271, PXA272
-             Product Brief         : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_pb.pdf
-             Design guide          : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_design_guide.pdf
-             Developers manual     : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_dev_man.pdf
-             Specification         : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_emts.pdf
-             Specification update  : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_spec_update.pdf
-             Application processor only
-             Core: ARMv5 XScale2 core
-        PXA300, PXA310, PXA320
-             PXA 300 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA300_PB_R4.pdf
-             PXA 310 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA310_PB_R4.pdf
-             PXA 320 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA320_PB_R4.pdf
-             Design guide          : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Design_Guide.pdf
-             Developers manual     : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Developers_Manual.zip
-             Specifications        : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_EMTS.pdf
-             Specification Update  : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Spec_Update.zip
-             Reference Manual      : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_TavorP_BootROM_Ref_Manual.pdf
-             Application processor only
-             Core: ARMv5 XScale3 core
-        PXA930, PXA935
-             Application processor with Communication processor
-             Core: ARMv5 XScale3 core
-        PXA955
-             Application processor with Communication processor
-             Core: ARMv7 compatible Sheeva PJ4 core
-
-   Comments:
-
-    * This line of SoCs originates from the XScale family developed by
-      Intel and acquired by Marvell in ~2006. The PXA21x, PXA25x,
-      PXA26x, PXA27x, PXA3xx and PXA93x were developed by Intel, while
-      the later PXA95x were developed by Marvell.
-
-    * Due to their XScale origin, these SoCs have virtually nothing in
-      common with the other (Kirkwood, Dove, etc.) families of Marvell
-      SoCs, except with the MMP/MMP2 family of SoCs.
-
-   Linux kernel mach directory: arch/arm/mach-pxa
-   Linux kernel plat directory: arch/arm/plat-pxa
-
-MMP/MMP2/MMP3 family (communication processor)
------------------------------------------
-
-   Flavors:
-        PXA168, a.k.a Armada 168
-             Homepage             : http://www.marvell.com/application-processors/armada-100/armada-168.jsp
-             Product brief        : http://www.marvell.com/application-processors/armada-100/assets/pxa_168_pb.pdf
-             Hardware manual      : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_datasheet.pdf
-             Software manual      : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_software_manual.pdf
-             Specification update : http://www.marvell.com/application-processors/armada-100/assets/ARMADA16x_Spec_update.pdf
-             Boot ROM manual      : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_ref_manual.pdf
-             App node package     : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_app_note_package.pdf
-             Application processor only
-             Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk)
-        PXA910/PXA920
-             Homepage             : http://www.marvell.com/communication-processors/pxa910/
-             Product Brief        : http://www.marvell.com/communication-processors/pxa910/assets/Marvell_PXA910_Platform-001_PB_final.pdf
-             Application processor with Communication processor
-             Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk)
-        PXA688, a.k.a. MMP2, a.k.a Armada 610
-             Product Brief        : http://www.marvell.com/application-processors/armada-600/assets/armada610_pb.pdf
-             Application processor only
-             Core: ARMv7 compatible Sheeva PJ4 88sv581x core
-	PXA2128, a.k.a. MMP3 (OLPC XO4, Linux support not upstream)
-	     Product Brief	  : http://www.marvell.com/application-processors/armada/pxa2128/assets/Marvell-ARMADA-PXA2128-SoC-PB.pdf
-	     Application processor only
-	     Core: Dual-core ARMv7 compatible Sheeva PJ4C core
-	PXA960/PXA968/PXA978 (Linux support not upstream)
-	     Application processor with Communication Processor
-	     Core: ARMv7 compatible Sheeva PJ4 core
-	PXA986/PXA988 (Linux support not upstream)
-	     Application processor with Communication Processor
-	     Core: Dual-core ARMv7 compatible Sheeva PJ4B-MP core
-	PXA1088/PXA1920 (Linux support not upstream)
-	     Application processor with Communication Processor
-	     Core: quad-core ARMv7 Cortex-A7
-	PXA1908/PXA1928/PXA1936
-	     Application processor with Communication Processor
-	     Core: multi-core ARMv8 Cortex-A53
-
-   Comments:
-
-    * This line of SoCs originates from the XScale family developed by
-      Intel and acquired by Marvell in ~2006. All the processors of
-      this MMP/MMP2 family were developed by Marvell.
-
-    * Due to their XScale origin, these SoCs have virtually nothing in
-      common with the other (Kirkwood, Dove, etc.) families of Marvell
-      SoCs, except with the PXA family of SoCs listed above.
-
-   Linux kernel mach directory: arch/arm/mach-mmp
-   Linux kernel plat directory: arch/arm/plat-pxa
-
-Berlin family (Multimedia Solutions)
--------------------------------------
-
-  Flavors:
-	88DE3010, Armada 1000 (no Linux support)
-		Core:		Marvell PJ1 (ARMv5TE), Dual-core
-		Product Brief:	http://www.marvell.com.cn/digital-entertainment/assets/armada_1000_pb.pdf
-	88DE3005, Armada 1500 Mini
-		Design name:	BG2CD
-		Core:		ARM Cortex-A9, PL310 L2CC
-	88DE3006, Armada 1500 Mini Plus
-		Design name:	BG2CDP
-		Core:		Dual Core ARM Cortex-A7
-	88DE3100, Armada 1500
-		Design name:	BG2
-		Core:		Marvell PJ4B-MP (ARMv7), Tauros3 L2CC
-	88DE3114, Armada 1500 Pro
-		Design name:	BG2Q
-		Core:		Quad Core ARM Cortex-A9, PL310 L2CC
-	88DE3214, Armada 1500 Pro 4K
-		Design name:	BG3
-		Core:		ARM Cortex-A15, CA15 integrated L2CC
-	88DE3218, ARMADA 1500 Ultra
-		Core:		ARM Cortex-A53
-
-  Homepage: https://www.synaptics.com/products/multimedia-solutions
-  Directory: arch/arm/mach-berlin
-
-  Comments:
-
-   * This line of SoCs is based on Marvell Sheeva or ARM Cortex CPUs
-     with Synopsys DesignWare (IRQ, GPIO, Timers, ...) and PXA IP (SDHCI, USB, ETH, ...).
-
-   * The Berlin family was acquired by Synaptics from Marvell in 2017.
-
-CPU Cores
----------
-
-The XScale cores were designed by Intel, and shipped by Marvell in the older
-PXA processors. Feroceon is a Marvell designed core that developed in-house,
-and that evolved into Sheeva. The XScale and Feroceon cores were phased out
-over time and replaced with Sheeva cores in later products, which subsequently
-got replaced with licensed ARM Cortex-A cores.
-
-  XScale 1
-	CPUID 0x69052xxx
-	ARMv5, iWMMXt
-  XScale 2
-	CPUID 0x69054xxx
-	ARMv5, iWMMXt
-  XScale 3
-	CPUID 0x69056xxx or 0x69056xxx
-	ARMv5, iWMMXt
-  Feroceon-1850 88fr331 "Mohawk"
-	CPUID 0x5615331x or 0x41xx926x
-	ARMv5TE, single issue
-  Feroceon-2850 88fr531-vd "Jolteon"
-	CPUID 0x5605531x or 0x41xx926x
-	ARMv5TE, VFP, dual-issue
-  Feroceon 88fr571-vd "Jolteon"
-	CPUID 0x5615571x
-	ARMv5TE, VFP, dual-issue
-  Feroceon 88fr131 "Mohawk-D"
-	CPUID 0x5625131x
-	ARMv5TE, single-issue in-order
-  Sheeva PJ1 88sv331 "Mohawk"
-	CPUID 0x561584xx
-	ARMv5, single-issue iWMMXt v2
-  Sheeva PJ4 88sv581x "Flareon"
-	CPUID 0x560f581x
-	ARMv7, idivt, optional iWMMXt v2
-  Sheeva PJ4B 88sv581x
-	CPUID 0x561f581x
-	ARMv7, idivt, optional iWMMXt v2
-  Sheeva PJ4B-MP / PJ4C
-	CPUID 0x562f584x
-	ARMv7, idivt/idiva, LPAE, optional iWMMXt v2 and/or NEON
-
-Long-term plans
----------------
-
- * Unify the mach-dove/, mach-mv78xx0/, mach-orion5x/ into the
-   mach-mvebu/ to support all SoCs from the Marvell EBU (Engineering
-   Business Unit) in a single mach-<foo> directory. The plat-orion/
-   would therefore disappear.
-
- * Unify the mach-mmp/ and mach-pxa/ into the same mach-pxa
-   directory. The plat-pxa/ would therefore disappear.
-
-Credits
--------
-
- Maen Suleiman <maen@marvell.com>
- Lior Amsalem <alior@marvell.com>
- Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
- Andrew Lunn <andrew@lunn.ch>
- Nicolas Pitre <nico@fluxnic.net>
- Eric Miao <eric.y.miao@gmail.com>
diff --git a/Documentation/arm/Netwinder b/Documentation/arm/Netwinder
deleted file mode 100644
index f1b457fbd3de..000000000000
--- a/Documentation/arm/Netwinder
+++ /dev/null
@@ -1,78 +0,0 @@
-NetWinder specific documentation
-================================
-
-The NetWinder is a small low-power computer, primarily designed
-to run Linux.  It is based around the StrongARM RISC processor,
-DC21285 PCI bridge, with PC-type hardware glued around it.
-
-Port usage
-==========
-
-Min    - Max	Description
----------------------------
-0x0000 - 0x000f	DMA1
-0x0020 - 0x0021	PIC1
-0x0060 - 0x006f	Keyboard
-0x0070 - 0x007f	RTC
-0x0080 - 0x0087	DMA1
-0x0088 - 0x008f	DMA2
-0x00a0 - 0x00a3	PIC2
-0x00c0 - 0x00df	DMA2
-0x0180 - 0x0187	IRDA
-0x01f0 - 0x01f6	ide0
-0x0201		Game port
-0x0203		RWA010 configuration read
-0x0220 - ?	SoundBlaster
-0x0250 - ?	WaveArtist
-0x0279		RWA010 configuration index
-0x02f8 - 0x02ff	Serial ttyS1
-0x0300 - 0x031f	Ether10
-0x0338		GPIO1
-0x033a		GPIO2
-0x0370 - 0x0371	W83977F configuration registers
-0x0388 - ?	AdLib
-0x03c0 - 0x03df	VGA
-0x03f6		ide0
-0x03f8 - 0x03ff	Serial ttyS0
-0x0400 - 0x0408	DC21143
-0x0480 - 0x0487	DMA1
-0x0488 - 0x048f	DMA2
-0x0a79		RWA010 configuration write
-0xe800 - 0xe80f	ide0/ide1 BM DMA
-
-
-Interrupt usage
-===============
-
-IRQ	type	Description
----------------------------
- 0	ISA	100Hz timer
- 1	ISA	Keyboard
- 2	ISA	cascade
- 3	ISA	Serial ttyS1
- 4	ISA	Serial ttyS0
- 5	ISA	PS/2 mouse
- 6	ISA	IRDA
- 7	ISA	Printer
- 8	ISA	RTC alarm
- 9	ISA
-10	ISA	GP10 (Orange reset button)
-11	ISA
-12	ISA	WaveArtist
-13	ISA
-14	ISA	hda1
-15	ISA
-
-DMA usage
-=========
-
-DMA	type	Description
----------------------------
- 0	ISA	IRDA
- 1	ISA
- 2	ISA	cascade
- 3	ISA	WaveArtist
- 4	ISA
- 5	ISA
- 6	ISA
- 7	ISA	WaveArtist
diff --git a/Documentation/arm/SA1100/FreeBird b/Documentation/arm/SA1100/FreeBird
deleted file mode 100644
index ab9193663b2b..000000000000
--- a/Documentation/arm/SA1100/FreeBird
+++ /dev/null
@@ -1,21 +0,0 @@
-Freebird-1.1 is produced by Legend(C), Inc.
-http://web.archive.org/web/*/http://www.legend.com.cn
-and software/linux maintained by Coventive(C), Inc.
-(http://www.coventive.com)
-
-Based on the Nicolas's strongarm kernel tree.
-
-===============================================================
-Maintainer:
-
-Chester Kuo <chester@coventive.com>
-	    <chester@linux.org.tw>
-
-Author :
-Tim wu <timwu@coventive.com>
-CIH <cih@coventive.com>
-Eric Peng <ericpeng@coventive.com>
-Jeff Lee <jeff_lee@coventive.com>
-Allen Cheng
-Tony Liu <tonyliu@coventive.com>
-
diff --git a/Documentation/arm/SA1100/empeg b/Documentation/arm/SA1100/empeg
deleted file mode 100644
index 4ece4849a42c..000000000000
--- a/Documentation/arm/SA1100/empeg
+++ /dev/null
@@ -1,2 +0,0 @@
-See ../empeg/README
-
diff --git a/Documentation/arm/SA1100/serial_UART b/Documentation/arm/SA1100/serial_UART
deleted file mode 100644
index a63966f1d083..000000000000
--- a/Documentation/arm/SA1100/serial_UART
+++ /dev/null
@@ -1,47 +0,0 @@
-The SA1100 serial port had its major/minor numbers officially assigned:
-
-> Date: Sun, 24 Sep 2000 21:40:27 -0700
-> From: H. Peter Anvin <hpa@transmeta.com>
-> To: Nicolas Pitre <nico@CAM.ORG>
-> Cc: Device List Maintainer <device@lanana.org>
-> Subject: Re: device
-> 
-> Okay.  Note that device numbers 204 and 205 are used for "low density
-> serial devices", so you will have a range of minors on those majors (the
-> tty device layer handles this just fine, so you don't have to worry about
-> doing anything special.)
-> 
-> So your assignments are:
-> 
-> 204 char        Low-density serial ports
->                   5 = /dev/ttySA0               SA1100 builtin serial port 0
->                   6 = /dev/ttySA1               SA1100 builtin serial port 1
->                   7 = /dev/ttySA2               SA1100 builtin serial port 2
-> 
-> 205 char        Low-density serial ports (alternate device)
->                   5 = /dev/cusa0                Callout device for ttySA0
->                   6 = /dev/cusa1                Callout device for ttySA1
->                   7 = /dev/cusa2                Callout device for ttySA2
->
-
-You must create those inodes in /dev on the root filesystem used
-by your SA1100-based device:
-
-	mknod ttySA0 c 204 5
-	mknod ttySA1 c 204 6
-	mknod ttySA2 c 204 7
-	mknod cusa0 c 205 5
-	mknod cusa1 c 205 6
-	mknod cusa2 c 205 7
-
-In addition to the creation of the appropriate device nodes above, you
-must ensure your user space applications make use of the correct device
-name. The classic example is the content of the /etc/inittab file where
-you might have a getty process started on ttyS0.  In this case:
-
-- replace occurrences of ttyS0 with ttySA0, ttyS1 with ttySA1, etc.
-
-- don't forget to add 'ttySA0', 'console', or the appropriate tty name
-  in /etc/securetty for root to be allowed to login as well.
-
-
diff --git a/Documentation/arm/README b/Documentation/arm/arm.rst
similarity index 88%
rename from Documentation/arm/README
rename to Documentation/arm/arm.rst
index 9d1e5b2c92e6..2edc509df92a 100644
--- a/Documentation/arm/README
+++ b/Documentation/arm/arm.rst
@@ -1,5 +1,6 @@
-			   ARM Linux 2.6
-			   =============
+=======================
+ARM Linux 2.6 and upper
+=======================
 
     Please check <ftp://ftp.arm.linux.org.uk/pub/armlinux> for
     updates.
@@ -18,22 +19,28 @@ Compilation of kernel
   line as detailed below.
 
   If you wish to cross-compile, then alter the following lines in the top
-  level make file:
+  level make file::
 
     ARCH = <whatever>
-	with
+
+  with::
+
     ARCH = arm
 
-	and
+  and::
 
     CROSS_COMPILE=
-	to
+
+  to::
+
     CROSS_COMPILE=<your-path-to-your-compiler-without-gcc>
-	eg.
+
+  eg.::
+
     CROSS_COMPILE=arm-linux-
 
-  Do a 'make config', followed by 'make Image' to build the kernel 
-  (arch/arm/boot/Image).  A compressed image can be built by doing a 
+  Do a 'make config', followed by 'make Image' to build the kernel
+  (arch/arm/boot/Image).  A compressed image can be built by doing a
   'make zImage' instead of 'make Image'.
 
 
@@ -46,7 +53,7 @@ Bug reports etc
 
   Bug reports should be sent to linux-arm-kernel@lists.arm.linux.org.uk,
   or submitted through the web form at
-  http://www.arm.linux.org.uk/developer/ 
+  http://www.arm.linux.org.uk/developer/
 
   When sending bug reports, please ensure that they contain all relevant
   information, eg. the kernel messages that were printed before/during
@@ -60,11 +67,13 @@ Include files
   which are there to reduce the clutter in the top-level directory.  These
   directories, and their purpose is listed below:
 
-   arch-*	machine/platform specific header files
-   hardware	driver-internal ARM specific data structures/definitions
-   mach		descriptions of generic ARM to specific machine interfaces
-   proc-*	processor dependent header files (currently only two
+  ============= ==========================================================
+   `arch-*`	machine/platform specific header files
+   `hardware`	driver-internal ARM specific data structures/definitions
+   `mach`	descriptions of generic ARM to specific machine interfaces
+   `proc-*`	processor dependent header files (currently only two
 		categories)
+  ============= ==========================================================
 
 
 Machine/Platform support
@@ -129,7 +138,7 @@ ST506 hard drives
   HDC base to the source.
 
   As of 31/3/96 it works with two drives (you should get the ADFS
-  *configure harddrive set to 2). I've got an internal 20MB and a great
+  `*configure` harddrive set to 2). I've got an internal 20MB and a great
   big external 5.25" FH 64MB drive (who could ever want more :-) ).
 
   I've just got 240K/s off it (a dd with bs=128k); thats about half of what
@@ -149,13 +158,13 @@ ST506 hard drives
   are welcome.
 
 
-CONFIG_MACH_ and CONFIG_ARCH_
------------------------------
+`CONFIG_MACH_` and `CONFIG_ARCH_`
+---------------------------------
   A change was made in 2003 to the macro names for new machines.
-  Historically, CONFIG_ARCH_ was used for the bonafide architecture,
+  Historically, `CONFIG_ARCH_` was used for the bonafide architecture,
   e.g. SA1100, as well as implementations of the architecture,
   e.g. Assabet.  It was decided to change the implementation macros
-  to read CONFIG_MACH_ for clarity.  Moreover, a retroactive fixup has
+  to read `CONFIG_MACH_` for clarity.  Moreover, a retroactive fixup has
   not been made because it would complicate patching.
 
   Previous registrations may be found online.
@@ -163,7 +172,7 @@ CONFIG_MACH_ and CONFIG_ARCH_
     <http://www.arm.linux.org.uk/developer/machines/>
 
 Kernel entry (head.S)
---------------------------
+---------------------
   The initial entry into the kernel is via head.S, which uses machine
   independent code.  The machine is selected by the value of 'r1' on
   entry, which must be kept unique.
@@ -201,4 +210,5 @@ Kernel entry (head.S)
   platform is DT-only, you do not need a registered machine type.
 
 ---
+
 Russell King (15/03/2004)
diff --git a/Documentation/arm/Booting b/Documentation/arm/booting.rst
similarity index 89%
rename from Documentation/arm/Booting
rename to Documentation/arm/booting.rst
index f1f965ce93d6..4babb6c6ae1e 100644
--- a/Documentation/arm/Booting
+++ b/Documentation/arm/booting.rst
@@ -1,7 +1,9 @@
-			Booting ARM Linux
-			=================
+=================
+Booting ARM Linux
+=================
 
 Author:	Russell King
+
 Date  : 18 May 2002
 
 The following documentation is relevant to 2.4.18-rmk6 and beyond.
@@ -25,8 +27,10 @@ following:
 1. Setup and initialise RAM
 ---------------------------
 
-Existing boot loaders:		MANDATORY
-New boot loaders:		MANDATORY
+Existing boot loaders:
+	MANDATORY
+New boot loaders:
+	MANDATORY
 
 The boot loader is expected to find and initialise all RAM that the
 kernel will use for volatile data storage in the system.  It performs
@@ -39,8 +43,10 @@ sees fit.)
 2. Initialise one serial port
 -----------------------------
 
-Existing boot loaders:		OPTIONAL, RECOMMENDED
-New boot loaders:		OPTIONAL, RECOMMENDED
+Existing boot loaders:
+	OPTIONAL, RECOMMENDED
+New boot loaders:
+	OPTIONAL, RECOMMENDED
 
 The boot loader should initialise and enable one serial port on the
 target.  This allows the kernel serial driver to automatically detect
@@ -57,8 +63,10 @@ serial format options as described in
 3. Detect the machine type
 --------------------------
 
-Existing boot loaders:		OPTIONAL
-New boot loaders:		MANDATORY except for DT-only platforms
+Existing boot loaders:
+	OPTIONAL
+New boot loaders:
+	MANDATORY except for DT-only platforms
 
 The boot loader should detect the machine type its running on by some
 method.  Whether this is a hard coded value or some algorithm that
@@ -74,8 +82,10 @@ necessary, but assures that it will not match any existing types.
 4. Setup boot data
 ------------------
 
-Existing boot loaders:		OPTIONAL, HIGHLY RECOMMENDED
-New boot loaders:		MANDATORY
+Existing boot loaders:
+	OPTIONAL, HIGHLY RECOMMENDED
+New boot loaders:
+	MANDATORY
 
 The boot loader must provide either a tagged list or a dtb image for
 passing configuration data to the kernel.  The physical address of the
@@ -97,15 +107,15 @@ entirety; some tags behave as the former, others the latter.
 
 The boot loader must pass at a minimum the size and location of
 the system memory, and root filesystem location.  Therefore, the
-minimum tagged list should look:
+minimum tagged list should look::
 
-	+-----------+
-base ->	| ATAG_CORE |  |
-	+-----------+  |
-	| ATAG_MEM  |  | increasing address
-	+-----------+  |
-	| ATAG_NONE |  |
-	+-----------+  v
+		+-----------+
+  base ->	| ATAG_CORE |  |
+		+-----------+  |
+		| ATAG_MEM  |  | increasing address
+		+-----------+  |
+		| ATAG_NONE |  |
+		+-----------+  v
 
 The tagged list should be stored in system RAM.
 
@@ -134,8 +144,10 @@ A safe location is just above the 128MiB boundary from start of RAM.
 5. Load initramfs.
 ------------------
 
-Existing boot loaders:		OPTIONAL
-New boot loaders:		OPTIONAL
+Existing boot loaders:
+	OPTIONAL
+New boot loaders:
+	OPTIONAL
 
 If an initramfs is in use then, as with the dtb, it must be placed in
 a region of memory where the kernel decompressor will not overwrite it
@@ -149,8 +161,10 @@ recommended above.
 6. Calling the kernel image
 ---------------------------
 
-Existing boot loaders:		MANDATORY
-New boot loaders:		MANDATORY
+Existing boot loaders:
+	MANDATORY
+New boot loaders:
+	MANDATORY
 
 There are two options for calling the kernel zImage.  If the zImage
 is stored in flash, and is linked correctly to be run from flash,
@@ -174,12 +188,14 @@ In any case, the following conditions must be met:
   you many hours of debug.
 
 - CPU register settings
-  r0 = 0,
-  r1 = machine type number discovered in (3) above.
-  r2 = physical address of tagged list in system RAM, or
-       physical address of device tree block (dtb) in system RAM
+
+  - r0 = 0,
+  - r1 = machine type number discovered in (3) above.
+  - r2 = physical address of tagged list in system RAM, or
+    physical address of device tree block (dtb) in system RAM
 
 - CPU mode
+
   All forms of interrupts must be disabled (IRQs and FIQs)
 
   For CPUs which do not include the ARM virtualization extensions, the
@@ -195,8 +211,11 @@ In any case, the following conditions must be met:
   entered in SVC mode.
 
 - Caches, MMUs
+
   The MMU must be off.
+
   Instruction cache may be on or off.
+
   Data cache must be off.
 
   If the kernel is entered in HYP mode, the above requirements apply to
diff --git a/Documentation/arm/cluster-pm-race-avoidance.txt b/Documentation/arm/cluster-pm-race-avoidance.rst
similarity index 84%
rename from Documentation/arm/cluster-pm-race-avoidance.txt
rename to Documentation/arm/cluster-pm-race-avoidance.rst
index 750b6fc24af9..aa58603d3f28 100644
--- a/Documentation/arm/cluster-pm-race-avoidance.txt
+++ b/Documentation/arm/cluster-pm-race-avoidance.rst
@@ -1,3 +1,4 @@
+=========================================================
 Cluster-wide Power-up/power-down race avoidance algorithm
 =========================================================
 
@@ -46,10 +47,12 @@ Basic model
 
 Each cluster and CPU is assigned a state, as follows:
 
-	DOWN
-	COMING_UP
-	UP
-	GOING_DOWN
+	- DOWN
+	- COMING_UP
+	- UP
+	- GOING_DOWN
+
+::
 
 	    +---------> UP ----------+
 	    |                        v
@@ -60,18 +63,22 @@ Each cluster and CPU is assigned a state, as follows:
 	    +--------- DOWN <--------+
 
 
-DOWN:	The CPU or cluster is not coherent, and is either powered off or
+DOWN:
+	The CPU or cluster is not coherent, and is either powered off or
 	suspended, or is ready to be powered off or suspended.
 
-COMING_UP: The CPU or cluster has committed to moving to the UP state.
+COMING_UP:
+	The CPU or cluster has committed to moving to the UP state.
 	It may be part way through the process of initialisation and
 	enabling coherency.
 
-UP:	The CPU or cluster is active and coherent at the hardware
+UP:
+	The CPU or cluster is active and coherent at the hardware
 	level.  A CPU in this state is not necessarily being used
 	actively by the kernel.
 
-GOING_DOWN: The CPU or cluster has committed to moving to the DOWN
+GOING_DOWN:
+	The CPU or cluster has committed to moving to the DOWN
 	state.  It may be part way through the process of teardown and
 	coherency exit.
 
@@ -86,8 +93,8 @@ CPUs in the cluster simultaneously modifying the state.  The cluster-
 level states are described in the "Cluster state" section.
 
 To help distinguish the CPU states from cluster states in this
-discussion, the state names are given a CPU_ prefix for the CPU states,
-and a CLUSTER_ or INBOUND_ prefix for the cluster states.
+discussion, the state names are given a `CPU_` prefix for the CPU states,
+and a `CLUSTER_` or `INBOUND_` prefix for the cluster states.
 
 
 CPU state
@@ -101,10 +108,12 @@ This means that CPUs fit the basic model closely.
 
 The algorithm defines the following states for each CPU in the system:
 
-	CPU_DOWN
-	CPU_COMING_UP
-	CPU_UP
-	CPU_GOING_DOWN
+	- CPU_DOWN
+	- CPU_COMING_UP
+	- CPU_UP
+	- CPU_GOING_DOWN
+
+::
 
 	 cluster setup and
 	CPU setup complete          policy decision
@@ -130,17 +139,17 @@ requirement for any external event to happen.
 
 
 CPU_DOWN:
-
 	A CPU reaches the CPU_DOWN state when it is ready for
 	power-down.  On reaching this state, the CPU will typically
 	power itself down or suspend itself, via a WFI instruction or a
 	firmware call.
 
-	Next state:	CPU_COMING_UP
-	Conditions:	none
+	Next state:
+		CPU_COMING_UP
+	Conditions:
+		none
 
 	Trigger events:
-
 		a) an explicit hardware power-up operation, resulting
 		   from a policy decision on another CPU;
 
@@ -148,15 +157,17 @@ CPU_DOWN:
 
 
 CPU_COMING_UP:
-
 	A CPU cannot start participating in hardware coherency until the
 	cluster is set up and coherent.  If the cluster is not ready,
 	then the CPU will wait in the CPU_COMING_UP state until the
 	cluster has been set up.
 
-	Next state:	CPU_UP
-	Conditions:	The CPU's parent cluster must be in CLUSTER_UP.
-	Trigger events:	Transition of the parent cluster to CLUSTER_UP.
+	Next state:
+		CPU_UP
+	Conditions:
+		The CPU's parent cluster must be in CLUSTER_UP.
+	Trigger events:
+		Transition of the parent cluster to CLUSTER_UP.
 
 	Refer to the "Cluster state" section for a description of the
 	CLUSTER_UP state.
@@ -178,20 +189,25 @@ CPU_UP:
 	The CPU remains in this state until an explicit policy decision
 	is made to shut down or suspend the CPU.
 
-	Next state:	CPU_GOING_DOWN
-	Conditions:	none
-	Trigger events:	explicit policy decision
+	Next state:
+		CPU_GOING_DOWN
+	Conditions:
+		none
+	Trigger events:
+		explicit policy decision
 
 
 CPU_GOING_DOWN:
-
 	While in this state, the CPU exits coherency, including any
 	operations required to achieve this (such as cleaning data
 	caches).
 
-	Next state:	CPU_DOWN
-	Conditions:	local CPU teardown complete
-	Trigger events:	(spontaneous)
+	Next state:
+		CPU_DOWN
+	Conditions:
+		local CPU teardown complete
+	Trigger events:
+		(spontaneous)
 
 
 Cluster state
@@ -212,20 +228,20 @@ independently of the CPU which is tearing down the cluster.  For this
 reason, the cluster state is split into two parts:
 
 	"cluster" state: The global state of the cluster; or the state
-		on the outbound side:
+	on the outbound side:
 
-		CLUSTER_DOWN
-		CLUSTER_UP
-		CLUSTER_GOING_DOWN
+		- CLUSTER_DOWN
+		- CLUSTER_UP
+		- CLUSTER_GOING_DOWN
 
 	"inbound" state: The state of the cluster on the inbound side.
 
-		INBOUND_NOT_COMING_UP
-		INBOUND_COMING_UP
+		- INBOUND_NOT_COMING_UP
+		- INBOUND_COMING_UP
 
 
 	The different pairings of these states results in six possible
-	states for the cluster as a whole:
+	states for the cluster as a whole::
 
 	                            CLUSTER_UP
 	          +==========> INBOUND_NOT_COMING_UP -------------+
@@ -284,11 +300,12 @@ reason, the cluster state is split into two parts:
 
 
 CLUSTER_DOWN/INBOUND_NOT_COMING_UP:
+	Next state:
+		CLUSTER_DOWN/INBOUND_COMING_UP (inbound)
+	Conditions:
+		none
 
-	Next state:	CLUSTER_DOWN/INBOUND_COMING_UP (inbound)
-	Conditions:	none
 	Trigger events:
-
 		a) an explicit hardware power-up operation, resulting
 		   from a policy decision on another CPU;
 
@@ -306,9 +323,12 @@ CLUSTER_DOWN/INBOUND_COMING_UP:
 	setup to enable other CPUs in the cluster to enter coherency
 	safely.
 
-	Next state:	CLUSTER_UP/INBOUND_COMING_UP (inbound)
-	Conditions:	cluster-level setup and hardware coherency complete
-	Trigger events:	(spontaneous)
+	Next state:
+		CLUSTER_UP/INBOUND_COMING_UP (inbound)
+	Conditions:
+		cluster-level setup and hardware coherency complete
+	Trigger events:
+		(spontaneous)
 
 
 CLUSTER_UP/INBOUND_COMING_UP:
@@ -321,9 +341,12 @@ CLUSTER_UP/INBOUND_COMING_UP:
 	CLUSTER_UP/INBOUND_NOT_COMING_UP.  All other CPUs on the cluster
 	should consider treat these two states as equivalent.
 
-	Next state:	CLUSTER_UP/INBOUND_NOT_COMING_UP (inbound)
-	Conditions:	none
-	Trigger events:	(spontaneous)
+	Next state:
+		CLUSTER_UP/INBOUND_NOT_COMING_UP (inbound)
+	Conditions:
+		none
+	Trigger events:
+		(spontaneous)
 
 
 CLUSTER_UP/INBOUND_NOT_COMING_UP:
@@ -335,9 +358,12 @@ CLUSTER_UP/INBOUND_NOT_COMING_UP:
 	The cluster will remain in this state until a policy decision is
 	made to power the cluster down.
 
-	Next state:	CLUSTER_GOING_DOWN/INBOUND_NOT_COMING_UP (outbound)
-	Conditions:	none
-	Trigger events:	policy decision to power down the cluster
+	Next state:
+		CLUSTER_GOING_DOWN/INBOUND_NOT_COMING_UP (outbound)
+	Conditions:
+		none
+	Trigger events:
+		policy decision to power down the cluster
 
 
 CLUSTER_GOING_DOWN/INBOUND_NOT_COMING_UP:
@@ -359,13 +385,16 @@ CLUSTER_GOING_DOWN/INBOUND_NOT_COMING_UP:
 	Next states:
 
 	CLUSTER_DOWN/INBOUND_NOT_COMING_UP (outbound)
-		Conditions:	cluster torn down and ready to power off
-		Trigger events:	(spontaneous)
+		Conditions:
+			cluster torn down and ready to power off
+		Trigger events:
+			(spontaneous)
 
 	CLUSTER_GOING_DOWN/INBOUND_COMING_UP (inbound)
-		Conditions:	none
-		Trigger events:
+		Conditions:
+			none
 
+		Trigger events:
 			a) an explicit hardware power-up operation,
 			   resulting from a policy decision on another
 			   CPU;
@@ -396,13 +425,19 @@ CLUSTER_GOING_DOWN/INBOUND_COMING_UP:
 	Next states:
 
 	CLUSTER_UP/INBOUND_COMING_UP (outbound)
-		Conditions:	cluster-level setup and hardware
+		Conditions:
+				cluster-level setup and hardware
 				coherency complete
-		Trigger events:	(spontaneous)
+
+		Trigger events:
+				(spontaneous)
 
 	CLUSTER_DOWN/INBOUND_COMING_UP (outbound)
-		Conditions:	cluster torn down and ready to power off
-		Trigger events:	(spontaneous)
+		Conditions:
+			cluster torn down and ready to power off
+
+		Trigger events:
+			(spontaneous)
 
 
 Last man and First man selection
@@ -452,30 +487,30 @@ Implementation:
 	arch/arm/common/mcpm_entry.c (everything else):
 
 	__mcpm_cpu_going_down() signals the transition of a CPU to the
-		CPU_GOING_DOWN state.
+	CPU_GOING_DOWN state.
 
 	__mcpm_cpu_down() signals the transition of a CPU to the CPU_DOWN
-		state.
+	state.
 
 	A CPU transitions to CPU_COMING_UP and then to CPU_UP via the
-		low-level power-up code in mcpm_head.S.  This could
-		involve CPU-specific setup code, but in the current
-		implementation it does not.
+	low-level power-up code in mcpm_head.S.  This could
+	involve CPU-specific setup code, but in the current
+	implementation it does not.
 
 	__mcpm_outbound_enter_critical() and __mcpm_outbound_leave_critical()
-		handle transitions from CLUSTER_UP to CLUSTER_GOING_DOWN
-		and from there to CLUSTER_DOWN or back to CLUSTER_UP (in
-		the case of an aborted cluster power-down).
+	handle transitions from CLUSTER_UP to CLUSTER_GOING_DOWN
+	and from there to CLUSTER_DOWN or back to CLUSTER_UP (in
+	the case of an aborted cluster power-down).
 
-		These functions are more complex than the __mcpm_cpu_*()
-		functions due to the extra inter-CPU coordination which
-		is needed for safe transitions at the cluster level.
+	These functions are more complex than the __mcpm_cpu_*()
+	functions due to the extra inter-CPU coordination which
+	is needed for safe transitions at the cluster level.
 
 	A cluster transitions from CLUSTER_DOWN back to CLUSTER_UP via
-		the low-level power-up code in mcpm_head.S.  This
-		typically involves platform-specific setup code,
-		provided by the platform-specific power_up_setup
-		function registered via mcpm_sync_init.
+	the low-level power-up code in mcpm_head.S.  This
+	typically involves platform-specific setup code,
+	provided by the platform-specific power_up_setup
+	function registered via mcpm_sync_init.
 
 Deep topologies:
 
diff --git a/Documentation/arm/firmware.txt b/Documentation/arm/firmware.rst
similarity index 86%
rename from Documentation/arm/firmware.txt
rename to Documentation/arm/firmware.rst
index 7f175dbb427e..efd844baec1d 100644
--- a/Documentation/arm/firmware.txt
+++ b/Documentation/arm/firmware.rst
@@ -1,5 +1,7 @@
-Interface for registering and calling firmware-specific operations for ARM.
-----
+==========================================================================
+Interface for registering and calling firmware-specific operations for ARM
+==========================================================================
+
 Written by Tomasz Figa <t.figa@samsung.com>
 
 Some boards are running with secure firmware running in TrustZone secure
@@ -9,7 +11,7 @@ operations and call them when needed.
 
 Firmware operations can be specified by filling in a struct firmware_ops
 with appropriate callbacks and then registering it with register_firmware_ops()
-function.
+function::
 
 	void register_firmware_ops(const struct firmware_ops *ops)
 
@@ -19,7 +21,7 @@ and its members can be found in arch/arm/include/asm/firmware.h header.
 There is a default, empty set of operations provided, so there is no need to
 set anything if platform does not require firmware operations.
 
-To call a firmware operation, a helper macro is provided
+To call a firmware operation, a helper macro is provided::
 
 	#define call_firmware_op(op, ...)				\
 		((firmware_ops->op) ? firmware_ops->op(__VA_ARGS__) : (-ENOSYS))
@@ -28,7 +30,7 @@ the macro checks if the operation is provided and calls it or otherwise returns
 -ENOSYS to signal that given operation is not available (for example, to allow
 fallback to legacy operation).
 
-Example of registering firmware operations:
+Example of registering firmware operations::
 
 	/* board file */
 
@@ -56,7 +58,7 @@ Example of registering firmware operations:
 		register_firmware_ops(&platformX_firmware_ops);
 	}
 
-Example of using a firmware operation:
+Example of using a firmware operation::
 
 	/* some platform code, e.g. SMP initialization */
 
diff --git a/Documentation/arm/index.rst b/Documentation/arm/index.rst
new file mode 100644
index 000000000000..bd316d1a1802
--- /dev/null
+++ b/Documentation/arm/index.rst
@@ -0,0 +1,80 @@
+:orphan:
+
+================
+ARM Architecture
+================
+
+.. toctree::
+   :maxdepth: 1
+
+   arm
+   booting
+   cluster-pm-race-avoidance
+   firmware
+   interrupts
+   kernel_mode_neon
+   kernel_user_helpers
+   memory
+   mem_alignment
+   tcm
+   setup
+   swp_emulation
+   uefi
+   vlocks
+   porting
+
+SoC-specific documents
+======================
+
+.. toctree::
+   :maxdepth: 1
+
+   ixp4xx
+
+   marvel
+   microchip
+
+   netwinder
+   nwfpe/index
+
+   keystone/overview
+   keystone/knav-qmss
+
+   omap/index
+
+   pxa/mfp
+
+
+   sa1100/index
+
+   stm32/stm32f746-overview
+   stm32/overview
+   stm32/stm32h743-overview
+   stm32/stm32f769-overview
+   stm32/stm32f429-overview
+   stm32/stm32mp157-overview
+
+   sunxi
+
+   samsung/index
+   samsung-s3c24xx/index
+
+   sunxi/clocks
+
+   spear/overview
+
+   sti/stih416-overview
+   sti/stih407-overview
+   sti/stih418-overview
+   sti/overview
+   sti/stih415-overview
+
+   vfp/release-notes
+
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/arm/Interrupts b/Documentation/arm/interrupts.rst
similarity index 81%
rename from Documentation/arm/Interrupts
rename to Documentation/arm/interrupts.rst
index f09ab1b90ef1..2ae70e0e9732 100644
--- a/Documentation/arm/Interrupts
+++ b/Documentation/arm/interrupts.rst
@@ -1,8 +1,10 @@
-2.5.2-rmk5
-----------
+==========
+Interrupts
+==========
 
-This is the first kernel that contains a major shake up of some of the
-major architecture-specific subsystems.
+2.5.2-rmk5:
+  This is the first kernel that contains a major shake up of some of the
+  major architecture-specific subsystems.
 
 Firstly, it contains some pretty major changes to the way we handle the
 MMU TLB.  Each MMU TLB variant is now handled completely separately -
@@ -18,7 +20,7 @@ Unfortunately, this means that machine types that touch the irq_desc[]
 array (basically all machine types) will break, and this means every
 machine type that we currently have.
 
-Lets take an example.  On the Assabet with Neponset, we have:
+Lets take an example.  On the Assabet with Neponset, we have::
 
                   GPIO25                 IRR:2
         SA1100 ------------> Neponset -----------> SA1111
@@ -48,42 +50,47 @@ the irqdesc array).  This doesn't have to be a real "IC"; indeed the
 SA11x0 IRQs are handled by two separate "chip" structures, one for
 GPIO0-10, and another for all the rest.  It is just a container for
 the various operations (maybe this'll change to a better name).
-This structure has the following operations:
+This structure has the following operations::
 
-struct irqchip {
-        /*
-         * Acknowledge the IRQ.
-         * If this is a level-based IRQ, then it is expected to mask the IRQ
-         * as well.
-         */
-        void (*ack)(unsigned int irq);
-        /*
-         * Mask the IRQ in hardware.
-         */
-        void (*mask)(unsigned int irq);
-        /*
-         * Unmask the IRQ in hardware.
-         */
-        void (*unmask)(unsigned int irq);
-        /*
-         * Re-run the IRQ
-         */
-        void (*rerun)(unsigned int irq);
-        /*
-         * Set the type of the IRQ.
-         */
-        int (*type)(unsigned int irq, unsigned int, type);
-};
+  struct irqchip {
+          /*
+           * Acknowledge the IRQ.
+           * If this is a level-based IRQ, then it is expected to mask the IRQ
+           * as well.
+           */
+          void (*ack)(unsigned int irq);
+          /*
+           * Mask the IRQ in hardware.
+           */
+          void (*mask)(unsigned int irq);
+          /*
+           * Unmask the IRQ in hardware.
+           */
+          void (*unmask)(unsigned int irq);
+          /*
+           * Re-run the IRQ
+           */
+          void (*rerun)(unsigned int irq);
+          /*
+           * Set the type of the IRQ.
+           */
+          int (*type)(unsigned int irq, unsigned int, type);
+  };
 
-ack    - required.  May be the same function as mask for IRQs
+ack
+       - required.  May be the same function as mask for IRQs
          handled by do_level_IRQ.
-mask   - required.
-unmask - required.
-rerun  - optional.  Not required if you're using do_level_IRQ for all
+mask
+       - required.
+unmask
+       - required.
+rerun
+       - optional.  Not required if you're using do_level_IRQ for all
          IRQs that use this 'irqchip'.  Generally expected to re-trigger
          the hardware IRQ if possible.  If not, may call the handler
 	 directly.
-type   - optional.  If you don't support changing the type of an IRQ,
+type
+       - optional.  If you don't support changing the type of an IRQ,
          it should be null so people can detect if they are unable to
          set the IRQ type.
 
@@ -109,6 +116,7 @@ manipulation, nor state tracking.  This is useful for things like the
 SMC9196 and USAR above.
 
 So, what's changed?
+===================
 
 1. Machine implementations must not write to the irqdesc array.
 
@@ -118,24 +126,19 @@ So, what's changed?
    absolutely necessary.
 
         set_irq_chip(irq,chip)
-
                 Set the mask/unmask methods for handling this IRQ
 
         set_irq_handler(irq,handler)
-
                 Set the handler for this IRQ (level, edge, simple)
 
         set_irq_chained_handler(irq,handler)
-
                 Set a "chained" handler for this IRQ - automatically
                 enables this IRQ (eg, Neponset and SA1111 handlers).
 
         set_irq_flags(irq,flags)
-
                 Set the valid/probe/noautoenable flags.
 
         set_irq_type(irq,type)
-
                 Set active the IRQ edge(s)/level.  This replaces the
                 SA1111 INTPOL manipulation, and the set_GPIO_IRQ_edge()
                 function.  Type should be one of IRQ_TYPE_xxx defined in
@@ -158,10 +161,9 @@ So, what's changed?
    be re-checked for pending events.  (see the Neponset IRQ handler for
    details).
 
-7. fixup_irq() is gone, as is arch/arm/mach-*/include/mach/irq.h
+7. fixup_irq() is gone, as is `arch/arm/mach-*/include/mach/irq.h`
 
 Please note that this will not solve all problems - some of them are
 hardware based.  Mixing level-based and edge-based IRQs on the same
 parent signal (eg neponset) is one such area where a software based
 solution can't provide the full answer to low IRQ latency.
-
diff --git a/Documentation/arm/IXP4xx b/Documentation/arm/ixp4xx.rst
similarity index 84%
rename from Documentation/arm/IXP4xx
rename to Documentation/arm/ixp4xx.rst
index e48b74de6ac0..a57235616294 100644
--- a/Documentation/arm/IXP4xx
+++ b/Documentation/arm/ixp4xx.rst
@@ -1,6 +1,6 @@
-
--------------------------------------------------------------------------
+===========================================================
 Release Notes for Linux on Intel's IXP4xx Network Processor
+===========================================================
 
 Maintained by Deepak Saxena <dsaxena@plexity.net>
 -------------------------------------------------------------------------
@@ -8,7 +8,7 @@ Maintained by Deepak Saxena <dsaxena@plexity.net>
 1. Overview
 
 Intel's IXP4xx network processor is a highly integrated SOC that
-is targeted for network applications, though it has become popular 
+is targeted for network applications, though it has become popular
 in industrial control and other areas due to low cost and power
 consumption. The IXP4xx family currently consists of several processors
 that support different network offload functions such as encryption,
@@ -20,7 +20,7 @@ For more information on the various versions of the CPU, see:
 
    http://developer.intel.com/design/network/products/npfamily/ixp4xx.htm
 
-Intel also made the IXCP1100 CPU for sometime which is an IXP4xx 
+Intel also made the IXCP1100 CPU for sometime which is an IXP4xx
 stripped of much of the network intelligence.
 
 2. Linux Support
@@ -31,7 +31,7 @@ Linux currently supports the following features on the IXP4xx chips:
 - PCI interface
 - Flash access (MTD/JFFS)
 - I2C through GPIO on IXP42x
-- GPIO for input/output/interrupts 
+- GPIO for input/output/interrupts
   See arch/arm/mach-ixp4xx/include/mach/platform.h for access functions.
 - Timers (watchdog, OS)
 
@@ -45,7 +45,7 @@ require the use of Intel's proprietary CSR software:
 If you need to use any of the above, you need to download Intel's
 software from:
 
-   http://developer.intel.com/design/network/products/npfamily/ixp425.htm    
+   http://developer.intel.com/design/network/products/npfamily/ixp425.htm
 
 DO NOT POST QUESTIONS TO THE LINUX MAILING LISTS REGARDING THE PROPRIETARY
 SOFTWARE.
@@ -53,14 +53,14 @@ SOFTWARE.
 There are several websites that provide directions/pointers on using
 Intel's software:
 
-   http://sourceforge.net/projects/ixp4xx-osdg/
-   Open Source Developer's Guide for using uClinux and the Intel libraries 
+   - http://sourceforge.net/projects/ixp4xx-osdg/
+     Open Source Developer's Guide for using uClinux and the Intel libraries
 
-http://gatewaymaker.sourceforge.net/ 
-   Simple one page summary of building a gateway using an IXP425 and Linux
+   - http://gatewaymaker.sourceforge.net/
+     Simple one page summary of building a gateway using an IXP425 and Linux
 
-http://ixp425.sourceforge.net/
-   ATM device driver for IXP425 that relies on Intel's libraries
+   - http://ixp425.sourceforge.net/
+     ATM device driver for IXP425 that relies on Intel's libraries
 
 3. Known Issues/Limitations
 
@@ -70,7 +70,7 @@ The IXP4xx family allows for up to 256MB of memory but the PCI interface
 can only expose 64MB of that memory to the PCI bus. This means that if
 you are running with > 64MB, all PCI buffers outside of the accessible
 range will be bounced using the routines in arch/arm/common/dmabounce.c.
-   
+
 3b. Limited outbound PCI window
 
 IXP4xx provides two methods of accessing PCI memory space:
@@ -79,15 +79,15 @@ IXP4xx provides two methods of accessing PCI memory space:
    To access PCI via this space, we simply ioremap() the BAR
    into the kernel and we can use the standard read[bwl]/write[bwl]
    macros. This is the preffered method due to speed but it
-   limits the system to just 64MB of PCI memory. This can be 
+   limits the system to just 64MB of PCI memory. This can be
    problamatic if using video cards and other memory-heavy devices.
-          
-2) If > 64MB of memory space is required, the IXP4xx can be 
-   configured to use indirect registers to access PCI This allows 
-   for up to 128MB (0x48000000 to 0x4fffffff) of memory on the bus. 
-   The disadvantage of this is that every PCI access requires 
-   three local register accesses plus a spinlock, but in some 
-   cases the performance hit is acceptable. In addition, you cannot 
+
+2) If > 64MB of memory space is required, the IXP4xx can be
+   configured to use indirect registers to access PCI This allows
+   for up to 128MB (0x48000000 to 0x4fffffff) of memory on the bus.
+   The disadvantage of this is that every PCI access requires
+   three local register accesses plus a spinlock, but in some
+   cases the performance hit is acceptable. In addition, you cannot
    mmap() PCI devices in this case due to the indirect nature
    of the PCI window.
 
@@ -96,14 +96,14 @@ you need more PCI memory, enable the IXP4XX_INDIRECT_PCI config option.
 
 3c. GPIO as Interrupts
 
-Currently the code only handles level-sensitive GPIO interrupts 
+Currently the code only handles level-sensitive GPIO interrupts
 
 4. Supported platforms
 
 ADI Engineering Coyote Gateway Reference Platform
 http://www.adiengineering.com/productsCoyote.html
 
-   The ADI Coyote platform is reference design for those building 
+   The ADI Coyote platform is reference design for those building
    small residential/office gateways. One NPE is connected to a 10/100
    interface, one to 4-port 10/100 switch, and the third to and ADSL
    interface. In addition, it also supports to POTs interfaces connected
@@ -119,9 +119,9 @@ http://www.gateworks.com/support/overview.php
    the expansion bus.
 
 Intel IXDP425 Development Platform
-http://www.intel.com/design/network/products/npfamily/ixdpg425.htm  
+http://www.intel.com/design/network/products/npfamily/ixdpg425.htm
 
-   This is Intel's standard reference platform for the IXDP425 and is 
+   This is Intel's standard reference platform for the IXDP425 and is
    also known as the Richfield board. It contains 4 PCI slots, 16MB
    of flash, two 10/100 ports and one ADSL port.
 
@@ -161,11 +161,12 @@ The IXP4xx work has been funded by Intel Corp. and MontaVista Software, Inc.
 
 The following people have contributed patches/comments/etc:
 
-Lennerty Buytenhek
-Lutz Jaenicke
-Justin Mayfield
-Robert E. Ranslam
-[I know I've forgotten others, please email me to be added] 
+- Lennerty Buytenhek
+- Lutz Jaenicke
+- Justin Mayfield
+- Robert E. Ranslam
+
+[I know I've forgotten others, please email me to be added]
 
 -------------------------------------------------------------------------
 
diff --git a/Documentation/arm/kernel_mode_neon.txt b/Documentation/arm/kernel_mode_neon.rst
similarity index 99%
rename from Documentation/arm/kernel_mode_neon.txt
rename to Documentation/arm/kernel_mode_neon.rst
index b9e060c5b61e..9bfb71a2a9b9 100644
--- a/Documentation/arm/kernel_mode_neon.txt
+++ b/Documentation/arm/kernel_mode_neon.rst
@@ -1,3 +1,4 @@
+================
 Kernel mode NEON
 ================
 
@@ -86,6 +87,7 @@ instructions appearing in unexpected places if no special care is taken.
 
 Therefore, the recommended and only supported way of using NEON/VFP in the
 kernel is by adhering to the following rules:
+
 * isolate the NEON code in a separate compilation unit and compile it with
   '-march=armv7-a -mfpu=neon -mfloat-abi=softfp';
 * issue the calls to kernel_neon_begin(), kernel_neon_end() as well as the calls
@@ -115,6 +117,7 @@ NEON intrinsics
 NEON intrinsics are also supported. However, as code using NEON intrinsics
 relies on the GCC header <arm_neon.h>, (which #includes <stdint.h>), you should
 observe the following in addition to the rules above:
+
 * Compile the unit containing the NEON intrinsics with '-ffreestanding' so GCC
   uses its builtin version of <stdint.h> (this is a C99 header which the kernel
   does not supply);
diff --git a/Documentation/arm/kernel_user_helpers.txt b/Documentation/arm/kernel_user_helpers.rst
similarity index 78%
rename from Documentation/arm/kernel_user_helpers.txt
rename to Documentation/arm/kernel_user_helpers.rst
index 5673594717cf..eb6f3d916622 100644
--- a/Documentation/arm/kernel_user_helpers.txt
+++ b/Documentation/arm/kernel_user_helpers.rst
@@ -1,3 +1,4 @@
+============================
 Kernel-provided User Helpers
 ============================
 
@@ -43,7 +44,7 @@ kuser_helper_version
 
 Location:	0xffff0ffc
 
-Reference declaration:
+Reference declaration::
 
   extern int32_t __kuser_helper_version;
 
@@ -53,17 +54,17 @@ Definition:
   running kernel.  User space may read this to determine the availability
   of a particular helper.
 
-Usage example:
+Usage example::
 
-#define __kuser_helper_version (*(int32_t *)0xffff0ffc)
+  #define __kuser_helper_version (*(int32_t *)0xffff0ffc)
 
-void check_kuser_version(void)
-{
+  void check_kuser_version(void)
+  {
 	if (__kuser_helper_version < 2) {
 		fprintf(stderr, "can't do atomic operations, kernel too old\n");
 		abort();
 	}
-}
+  }
 
 Notes:
 
@@ -77,7 +78,7 @@ kuser_get_tls
 
 Location:	0xffff0fe0
 
-Reference prototype:
+Reference prototype::
 
   void * __kuser_get_tls(void);
 
@@ -97,16 +98,16 @@ Definition:
 
   Get the TLS value as previously set via the __ARM_NR_set_tls syscall.
 
-Usage example:
+Usage example::
 
-typedef void * (__kuser_get_tls_t)(void);
-#define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0)
+  typedef void * (__kuser_get_tls_t)(void);
+  #define __kuser_get_tls (*(__kuser_get_tls_t *)0xffff0fe0)
 
-void foo()
-{
+  void foo()
+  {
 	void *tls = __kuser_get_tls();
 	printf("TLS = %p\n", tls);
-}
+  }
 
 Notes:
 
@@ -117,7 +118,7 @@ kuser_cmpxchg
 
 Location:	0xffff0fc0
 
-Reference prototype:
+Reference prototype::
 
   int __kuser_cmpxchg(int32_t oldval, int32_t newval, volatile int32_t *ptr);
 
@@ -139,18 +140,18 @@ Clobbered registers:
 
 Definition:
 
-  Atomically store newval in *ptr only if *ptr is equal to oldval.
-  Return zero if *ptr was changed or non-zero if no exchange happened.
-  The C flag is also set if *ptr was changed to allow for assembly
+  Atomically store newval in `*ptr` only if `*ptr` is equal to oldval.
+  Return zero if `*ptr` was changed or non-zero if no exchange happened.
+  The C flag is also set if `*ptr` was changed to allow for assembly
   optimization in the calling code.
 
-Usage example:
+Usage example::
 
-typedef int (__kuser_cmpxchg_t)(int oldval, int newval, volatile int *ptr);
-#define __kuser_cmpxchg (*(__kuser_cmpxchg_t *)0xffff0fc0)
+  typedef int (__kuser_cmpxchg_t)(int oldval, int newval, volatile int *ptr);
+  #define __kuser_cmpxchg (*(__kuser_cmpxchg_t *)0xffff0fc0)
 
-int atomic_add(volatile int *ptr, int val)
-{
+  int atomic_add(volatile int *ptr, int val)
+  {
 	int old, new;
 
 	do {
@@ -159,7 +160,7 @@ int atomic_add(volatile int *ptr, int val)
 	} while(__kuser_cmpxchg(old, new, ptr));
 
 	return new;
-}
+  }
 
 Notes:
 
@@ -172,7 +173,7 @@ kuser_memory_barrier
 
 Location:	0xffff0fa0
 
-Reference prototype:
+Reference prototype::
 
   void __kuser_memory_barrier(void);
 
@@ -193,10 +194,10 @@ Definition:
   Apply any needed memory barrier to preserve consistency with data modified
   manually and __kuser_cmpxchg usage.
 
-Usage example:
+Usage example::
 
-typedef void (__kuser_dmb_t)(void);
-#define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0)
+  typedef void (__kuser_dmb_t)(void);
+  #define __kuser_dmb (*(__kuser_dmb_t *)0xffff0fa0)
 
 Notes:
 
@@ -207,7 +208,7 @@ kuser_cmpxchg64
 
 Location:	0xffff0f60
 
-Reference prototype:
+Reference prototype::
 
   int __kuser_cmpxchg64(const int64_t *oldval,
                         const int64_t *newval,
@@ -231,22 +232,22 @@ Clobbered registers:
 
 Definition:
 
-  Atomically store the 64-bit value pointed by *newval in *ptr only if *ptr
-  is equal to the 64-bit value pointed by *oldval.  Return zero if *ptr was
+  Atomically store the 64-bit value pointed by `*newval` in `*ptr` only if `*ptr`
+  is equal to the 64-bit value pointed by `*oldval`.  Return zero if `*ptr` was
   changed or non-zero if no exchange happened.
 
-  The C flag is also set if *ptr was changed to allow for assembly
+  The C flag is also set if `*ptr` was changed to allow for assembly
   optimization in the calling code.
 
-Usage example:
+Usage example::
 
-typedef int (__kuser_cmpxchg64_t)(const int64_t *oldval,
-                                  const int64_t *newval,
-                                  volatile int64_t *ptr);
-#define __kuser_cmpxchg64 (*(__kuser_cmpxchg64_t *)0xffff0f60)
+  typedef int (__kuser_cmpxchg64_t)(const int64_t *oldval,
+                                    const int64_t *newval,
+                                    volatile int64_t *ptr);
+  #define __kuser_cmpxchg64 (*(__kuser_cmpxchg64_t *)0xffff0f60)
 
-int64_t atomic_add64(volatile int64_t *ptr, int64_t val)
-{
+  int64_t atomic_add64(volatile int64_t *ptr, int64_t val)
+  {
 	int64_t old, new;
 
 	do {
@@ -255,7 +256,7 @@ int64_t atomic_add64(volatile int64_t *ptr, int64_t val)
 	} while(__kuser_cmpxchg64(&old, &new, ptr));
 
 	return new;
-}
+  }
 
 Notes:
 
diff --git a/Documentation/arm/keystone/knav-qmss.txt b/Documentation/arm/keystone/knav-qmss.rst
similarity index 92%
rename from Documentation/arm/keystone/knav-qmss.txt
rename to Documentation/arm/keystone/knav-qmss.rst
index fcdb9fd5f53a..7f7638d80b42 100644
--- a/Documentation/arm/keystone/knav-qmss.txt
+++ b/Documentation/arm/keystone/knav-qmss.rst
@@ -1,4 +1,6 @@
-* Texas Instruments Keystone Navigator Queue Management SubSystem driver
+======================================================================
+Texas Instruments Keystone Navigator Queue Management SubSystem driver
+======================================================================
 
 Driver source code path
   drivers/soc/ti/knav_qmss.c
@@ -34,11 +36,13 @@ driver that interface with the accumulator PDSP. This configures
 accumulator channels defined in DTS (example in DT documentation) to monitor
 1 or 32 queues per channel. More description on the firmware is available in
 CPPI/QMSS Low Level Driver document (docs/CPPI_QMSS_LLD_SDS.pdf) at
+
 	git://git.ti.com/keystone-rtos/qmss-lld.git
 
 k2_qmss_pdsp_acc48_k2_le_1_0_0_9.bin firmware supports upto 48 accumulator
 channels. This firmware is available under ti-keystone folder of
 firmware.git at
+
    git://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git
 
 To use copy the firmware image to lib/firmware folder of the initramfs or
diff --git a/Documentation/arm/keystone/Overview.txt b/Documentation/arm/keystone/overview.rst
similarity index 59%
rename from Documentation/arm/keystone/Overview.txt
rename to Documentation/arm/keystone/overview.rst
index 400c0c270d2e..cd90298c493c 100644
--- a/Documentation/arm/keystone/Overview.txt
+++ b/Documentation/arm/keystone/overview.rst
@@ -1,5 +1,6 @@
-		TI Keystone Linux Overview
-		--------------------------
+==========================
+TI Keystone Linux Overview
+==========================
 
 Introduction
 ------------
@@ -9,47 +10,65 @@ for users to run Linux on Keystone based EVMs from Texas Instruments.
 
 Following SoCs  & EVMs are currently supported:-
 
------------- K2HK SoC and EVM --------------------------------------------------
+K2HK SoC and EVM
+=================
 
 a.k.a Keystone 2 Hawking/Kepler SoC
 TCI6636K2H & TCI6636K2K: See documentation at
+
 	http://www.ti.com/product/tci6638k2k
 	http://www.ti.com/product/tci6638k2h
 
 EVM:
-http://www.advantech.com/Support/TI-EVM/EVMK2HX_sd.aspx
+  http://www.advantech.com/Support/TI-EVM/EVMK2HX_sd.aspx
 
------------- K2E SoC and EVM ---------------------------------------------------
+K2E SoC and EVM
+===============
 
 a.k.a Keystone 2 Edison SoC
-K2E  -  66AK2E05: See documentation at
+
+K2E  -  66AK2E05:
+
+See documentation at
+
 	http://www.ti.com/product/66AK2E05/technicaldocuments
 
 EVM:
-https://www.einfochips.com/index.php/partnerships/texas-instruments/k2e-evm.html
+   https://www.einfochips.com/index.php/partnerships/texas-instruments/k2e-evm.html
 
------------- K2L SoC and EVM ---------------------------------------------------
+K2L SoC and EVM
+===============
 
 a.k.a Keystone 2 Lamarr SoC
-K2L  -  TCI6630K2L: See documentation at
+
+K2L  -  TCI6630K2L:
+
+See documentation at
 	http://www.ti.com/product/TCI6630K2L/technicaldocuments
+
 EVM:
-https://www.einfochips.com/index.php/partnerships/texas-instruments/k2l-evm.html
+  https://www.einfochips.com/index.php/partnerships/texas-instruments/k2l-evm.html
 
 Configuration
 -------------
 
 All of the K2 SoCs/EVMs share a common defconfig, keystone_defconfig and same
 image is used to boot on individual EVMs. The platform configuration is
-specified through DTS. Following are the DTS used:-
-	K2HK EVM : k2hk-evm.dts
-	K2E EVM  : k2e-evm.dts
-	K2L EVM  : k2l-evm.dts
+specified through DTS. Following are the DTS used:
+
+	K2HK EVM:
+		k2hk-evm.dts
+	K2E EVM:
+		k2e-evm.dts
+	K2L EVM:
+		k2l-evm.dts
 
 The device tree documentation for the keystone machines are located at
+
         Documentation/devicetree/bindings/arm/keystone/keystone.txt
 
 Document Author
 ---------------
 Murali Karicheri <m-karicheri2@ti.com>
+
 Copyright 2015 Texas Instruments
diff --git a/Documentation/arm/marvel.rst b/Documentation/arm/marvel.rst
new file mode 100644
index 000000000000..16ab2eb085b8
--- /dev/null
+++ b/Documentation/arm/marvel.rst
@@ -0,0 +1,488 @@
+================
+ARM Marvell SoCs
+================
+
+This document lists all the ARM Marvell SoCs that are currently
+supported in mainline by the Linux kernel. As the Marvell families of
+SoCs are large and complex, it is hard to understand where the support
+for a particular SoC is available in the Linux kernel. This document
+tries to help in understanding where those SoCs are supported, and to
+match them with their corresponding public datasheet, when available.
+
+Orion family
+------------
+
+  Flavors:
+        - 88F5082
+        - 88F5181
+        - 88F5181L
+        - 88F5182
+
+               - Datasheet: http://www.embeddedarm.com/documentation/third-party/MV88F5182-datasheet.pdf
+               - Programmer's User Guide: http://www.embeddedarm.com/documentation/third-party/MV88F5182-opensource-manual.pdf
+               - User Manual: http://www.embeddedarm.com/documentation/third-party/MV88F5182-usermanual.pdf
+        - 88F5281
+
+               - Datasheet: http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf
+        - 88F6183
+  Core:
+	Feroceon 88fr331 (88f51xx) or 88fr531-vd (88f52xx) ARMv5 compatible
+  Linux kernel mach directory:
+	arch/arm/mach-orion5x
+  Linux kernel plat directory:
+	arch/arm/plat-orion
+
+Kirkwood family
+---------------
+
+  Flavors:
+        - 88F6282 a.k.a Armada 300
+
+                - Product Brief  : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf
+        - 88F6283 a.k.a Armada 310
+
+                - Product Brief  : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf
+        - 88F6190
+
+                - Product Brief  : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6190-003_WEB.pdf
+                - Hardware Spec  : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf
+                - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf
+        - 88F6192
+
+                - Product Brief  : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6192-003_ver1.pdf
+                - Hardware Spec  : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf
+                - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf
+        - 88F6182
+        - 88F6180
+
+                - Product Brief  : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6180-003_ver1.pdf
+                - Hardware Spec  : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6180_OpenSource.pdf
+                - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf
+        - 88F6281
+
+                - Product Brief  : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6281-004_ver1.pdf
+                - Hardware Spec  : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6281_OpenSource.pdf
+                - Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf
+  Homepage:
+	http://www.marvell.com/embedded-processors/kirkwood/
+  Core:
+	Feroceon 88fr131 ARMv5 compatible
+  Linux kernel mach directory:
+	arch/arm/mach-mvebu
+  Linux kernel plat directory:
+	none
+
+Discovery family
+----------------
+
+  Flavors:
+        - MV78100
+
+                - Product Brief  : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78100-003_WEB.pdf
+                - Hardware Spec  : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78100_OpenSource.pdf
+                - Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf
+        - MV78200
+
+                - Product Brief  : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78200-002_WEB.pdf
+                - Hardware Spec  : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78200_OpenSource.pdf
+                - Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf
+        - MV76100
+
+                Not supported by the Linux kernel.
+
+  Core:
+	Feroceon 88fr571-vd ARMv5 compatible
+
+  Linux kernel mach directory:
+	arch/arm/mach-mv78xx0
+  Linux kernel plat directory:
+	arch/arm/plat-orion
+
+EBU Armada family
+-----------------
+
+  Armada 370 Flavors:
+        - 88F6710
+        - 88F6707
+        - 88F6W11
+
+    - Product Brief:   http://www.marvell.com/embedded-processors/armada-300/assets/Marvell_ARMADA_370_SoC.pdf
+    - Hardware Spec:   http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-datasheet.pdf
+    - Functional Spec: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA370-FunctionalSpec-datasheet.pdf
+
+  Core:
+	Sheeva ARMv7 compatible PJ4B
+
+  Armada 375 Flavors:
+	- 88F6720
+
+    - Product Brief: http://www.marvell.com/embedded-processors/armada-300/assets/ARMADA_375_SoC-01_product_brief.pdf
+
+  Core:
+	ARM Cortex-A9
+
+  Armada 38x Flavors:
+	- 88F6810	Armada 380
+	- 88F6820 Armada 385
+	- 88F6828 Armada 388
+
+    - Product infos:   http://www.marvell.com/embedded-processors/armada-38x/
+    - Functional Spec: https://marvellcorp.wufoo.com/forms/marvell-armada-38x-functional-specifications/
+
+  Core:
+	ARM Cortex-A9
+
+  Armada 39x Flavors:
+	- 88F6920 Armada 390
+	- 88F6928 Armada 398
+
+    - Product infos: http://www.marvell.com/embedded-processors/armada-39x/
+
+  Core:
+	ARM Cortex-A9
+
+  Armada XP Flavors:
+        - MV78230
+        - MV78260
+        - MV78460
+
+    NOTE:
+	not to be confused with the non-SMP 78xx0 SoCs
+
+    Product Brief:
+	http://www.marvell.com/embedded-processors/armada-xp/assets/Marvell-ArmadaXP-SoC-product%20brief.pdf
+
+    Functional Spec:
+	http://www.marvell.com/embedded-processors/armada-xp/assets/ARMADA-XP-Functional-SpecDatasheet.pdf
+
+    - Hardware Specs:
+
+        - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78230_OS.PDF
+        - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78260_OS.PDF
+        - http://www.marvell.com/embedded-processors/armada-xp/assets/HW_MV78460_OS.PDF
+
+  Core:
+	Sheeva ARMv7 compatible Dual-core or Quad-core PJ4B-MP
+
+  Linux kernel mach directory:
+	arch/arm/mach-mvebu
+  Linux kernel plat directory:
+	none
+
+EBU Armada family ARMv8
+-----------------------
+
+  Armada 3710/3720 Flavors:
+	- 88F3710
+	- 88F3720
+
+  Core:
+	ARM Cortex A53 (ARMv8)
+
+  Homepage:
+	http://www.marvell.com/embedded-processors/armada-3700/
+
+  Product Brief:
+	http://www.marvell.com/embedded-processors/assets/PB-88F3700-FNL.pdf
+
+  Device tree files:
+	arch/arm64/boot/dts/marvell/armada-37*
+
+  Armada 7K Flavors:
+	  - 88F7020 (AP806 Dual + one CP110)
+	  - 88F7040 (AP806 Quad + one CP110)
+
+  Core: ARM Cortex A72
+
+  Homepage:
+	http://www.marvell.com/embedded-processors/armada-70xx/
+
+  Product Brief:
+	  - http://www.marvell.com/embedded-processors/assets/Armada7020PB-Jan2016.pdf
+	  - http://www.marvell.com/embedded-processors/assets/Armada7040PB-Jan2016.pdf
+
+  Device tree files:
+	arch/arm64/boot/dts/marvell/armada-70*
+
+  Armada 8K Flavors:
+	- 88F8020 (AP806 Dual + two CP110)
+	- 88F8040 (AP806 Quad + two CP110)
+  Core:
+	ARM Cortex A72
+
+  Homepage:
+	http://www.marvell.com/embedded-processors/armada-80xx/
+
+  Product Brief:
+	  - http://www.marvell.com/embedded-processors/assets/Armada8020PB-Jan2016.pdf
+	  - http://www.marvell.com/embedded-processors/assets/Armada8040PB-Jan2016.pdf
+
+  Device tree files:
+	arch/arm64/boot/dts/marvell/armada-80*
+
+Avanta family
+-------------
+
+  Flavors:
+       - 88F6510
+       - 88F6530P
+       - 88F6550
+       - 88F6560
+
+  Homepage:
+	http://www.marvell.com/broadband/
+
+  Product Brief:
+	http://www.marvell.com/broadband/assets/Marvell_Avanta_88F6510_305_060-001_product_brief.pdf
+
+  No public datasheet available.
+
+  Core:
+	ARMv5 compatible
+
+  Linux kernel mach directory:
+	no code in mainline yet, planned for the future
+  Linux kernel plat directory:
+	no code in mainline yet, planned for the future
+
+Storage family
+--------------
+
+  Armada SP:
+	- 88RC1580
+
+  Product infos:
+	http://www.marvell.com/storage/armada-sp/
+
+  Core:
+	Sheeva ARMv7 comatible Quad-core PJ4C
+
+  (not supported in upstream Linux kernel)
+
+Dove family (application processor)
+-----------------------------------
+
+  Flavors:
+        - 88AP510 a.k.a Armada 510
+
+   Product Brief:
+	http://www.marvell.com/application-processors/armada-500/assets/Marvell_Armada510_SoC.pdf
+
+   Hardware Spec:
+	http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Hardware-Spec.pdf
+
+  Functional Spec:
+	http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Functional-Spec.pdf
+
+  Homepage:
+	http://www.marvell.com/application-processors/armada-500/
+
+  Core:
+	ARMv7 compatible
+
+  Directory:
+	- arch/arm/mach-mvebu (DT enabled platforms)
+        - arch/arm/mach-dove (non-DT enabled platforms)
+
+PXA 2xx/3xx/93x/95x family
+--------------------------
+
+  Flavors:
+        - PXA21x, PXA25x, PXA26x
+             - Application processor only
+             - Core: ARMv5 XScale1 core
+        - PXA270, PXA271, PXA272
+             - Product Brief         : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_pb.pdf
+             - Design guide          : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_design_guide.pdf
+             - Developers manual     : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_dev_man.pdf
+             - Specification         : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_emts.pdf
+             - Specification update  : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_spec_update.pdf
+             - Application processor only
+             - Core: ARMv5 XScale2 core
+        - PXA300, PXA310, PXA320
+             - PXA 300 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA300_PB_R4.pdf
+             - PXA 310 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA310_PB_R4.pdf
+             - PXA 320 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA320_PB_R4.pdf
+             - Design guide          : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Design_Guide.pdf
+             - Developers manual     : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Developers_Manual.zip
+             - Specifications        : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_EMTS.pdf
+             - Specification Update  : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Spec_Update.zip
+             - Reference Manual      : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_TavorP_BootROM_Ref_Manual.pdf
+             - Application processor only
+             - Core: ARMv5 XScale3 core
+        - PXA930, PXA935
+             - Application processor with Communication processor
+             - Core: ARMv5 XScale3 core
+        - PXA955
+             - Application processor with Communication processor
+             - Core: ARMv7 compatible Sheeva PJ4 core
+
+   Comments:
+
+    * This line of SoCs originates from the XScale family developed by
+      Intel and acquired by Marvell in ~2006. The PXA21x, PXA25x,
+      PXA26x, PXA27x, PXA3xx and PXA93x were developed by Intel, while
+      the later PXA95x were developed by Marvell.
+
+    * Due to their XScale origin, these SoCs have virtually nothing in
+      common with the other (Kirkwood, Dove, etc.) families of Marvell
+      SoCs, except with the MMP/MMP2 family of SoCs.
+
+   Linux kernel mach directory:
+	arch/arm/mach-pxa
+   Linux kernel plat directory:
+	arch/arm/plat-pxa
+
+MMP/MMP2/MMP3 family (communication processor)
+----------------------------------------------
+
+   Flavors:
+        - PXA168, a.k.a Armada 168
+             - Homepage             : http://www.marvell.com/application-processors/armada-100/armada-168.jsp
+             - Product brief        : http://www.marvell.com/application-processors/armada-100/assets/pxa_168_pb.pdf
+             - Hardware manual      : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_datasheet.pdf
+             - Software manual      : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_software_manual.pdf
+             - Specification update : http://www.marvell.com/application-processors/armada-100/assets/ARMADA16x_Spec_update.pdf
+             - Boot ROM manual      : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_ref_manual.pdf
+             - App node package     : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_app_note_package.pdf
+             - Application processor only
+             - Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk)
+        - PXA910/PXA920
+             - Homepage             : http://www.marvell.com/communication-processors/pxa910/
+             - Product Brief        : http://www.marvell.com/communication-processors/pxa910/assets/Marvell_PXA910_Platform-001_PB_final.pdf
+             - Application processor with Communication processor
+             - Core: ARMv5 compatible Marvell PJ1 88sv331 (Mohawk)
+        - PXA688, a.k.a. MMP2, a.k.a Armada 610
+             - Product Brief        : http://www.marvell.com/application-processors/armada-600/assets/armada610_pb.pdf
+             - Application processor only
+             - Core: ARMv7 compatible Sheeva PJ4 88sv581x core
+	- PXA2128, a.k.a. MMP3 (OLPC XO4, Linux support not upstream)
+	     - Product Brief	  : http://www.marvell.com/application-processors/armada/pxa2128/assets/Marvell-ARMADA-PXA2128-SoC-PB.pdf
+	     - Application processor only
+	     - Core: Dual-core ARMv7 compatible Sheeva PJ4C core
+	- PXA960/PXA968/PXA978 (Linux support not upstream)
+	     - Application processor with Communication Processor
+	     - Core: ARMv7 compatible Sheeva PJ4 core
+	- PXA986/PXA988 (Linux support not upstream)
+	     - Application processor with Communication Processor
+	     - Core: Dual-core ARMv7 compatible Sheeva PJ4B-MP core
+	- PXA1088/PXA1920 (Linux support not upstream)
+	     - Application processor with Communication Processor
+	     - Core: quad-core ARMv7 Cortex-A7
+	- PXA1908/PXA1928/PXA1936
+	     - Application processor with Communication Processor
+	     - Core: multi-core ARMv8 Cortex-A53
+
+   Comments:
+
+    * This line of SoCs originates from the XScale family developed by
+      Intel and acquired by Marvell in ~2006. All the processors of
+      this MMP/MMP2 family were developed by Marvell.
+
+    * Due to their XScale origin, these SoCs have virtually nothing in
+      common with the other (Kirkwood, Dove, etc.) families of Marvell
+      SoCs, except with the PXA family of SoCs listed above.
+
+   Linux kernel mach directory:
+	arch/arm/mach-mmp
+   Linux kernel plat directory:
+	arch/arm/plat-pxa
+
+Berlin family (Multimedia Solutions)
+-------------------------------------
+
+  - Flavors:
+	- 88DE3010, Armada 1000 (no Linux support)
+		- Core:		Marvell PJ1 (ARMv5TE), Dual-core
+		- Product Brief:	http://www.marvell.com.cn/digital-entertainment/assets/armada_1000_pb.pdf
+	- 88DE3005, Armada 1500 Mini
+		- Design name:	BG2CD
+		- Core:		ARM Cortex-A9, PL310 L2CC
+	- 88DE3006, Armada 1500 Mini Plus
+		- Design name:	BG2CDP
+		- Core:		Dual Core ARM Cortex-A7
+	- 88DE3100, Armada 1500
+		- Design name:	BG2
+		- Core:		Marvell PJ4B-MP (ARMv7), Tauros3 L2CC
+	- 88DE3114, Armada 1500 Pro
+		- Design name:	BG2Q
+		- Core:		Quad Core ARM Cortex-A9, PL310 L2CC
+	- 88DE3214, Armada 1500 Pro 4K
+		- Design name:	BG3
+		- Core:		ARM Cortex-A15, CA15 integrated L2CC
+	- 88DE3218, ARMADA 1500 Ultra
+		- Core:		ARM Cortex-A53
+
+  Homepage: https://www.synaptics.com/products/multimedia-solutions
+  Directory: arch/arm/mach-berlin
+
+  Comments:
+
+   * This line of SoCs is based on Marvell Sheeva or ARM Cortex CPUs
+     with Synopsys DesignWare (IRQ, GPIO, Timers, ...) and PXA IP (SDHCI, USB, ETH, ...).
+
+   * The Berlin family was acquired by Synaptics from Marvell in 2017.
+
+CPU Cores
+---------
+
+The XScale cores were designed by Intel, and shipped by Marvell in the older
+PXA processors. Feroceon is a Marvell designed core that developed in-house,
+and that evolved into Sheeva. The XScale and Feroceon cores were phased out
+over time and replaced with Sheeva cores in later products, which subsequently
+got replaced with licensed ARM Cortex-A cores.
+
+  XScale 1
+	CPUID 0x69052xxx
+	ARMv5, iWMMXt
+  XScale 2
+	CPUID 0x69054xxx
+	ARMv5, iWMMXt
+  XScale 3
+	CPUID 0x69056xxx or 0x69056xxx
+	ARMv5, iWMMXt
+  Feroceon-1850 88fr331 "Mohawk"
+	CPUID 0x5615331x or 0x41xx926x
+	ARMv5TE, single issue
+  Feroceon-2850 88fr531-vd "Jolteon"
+	CPUID 0x5605531x or 0x41xx926x
+	ARMv5TE, VFP, dual-issue
+  Feroceon 88fr571-vd "Jolteon"
+	CPUID 0x5615571x
+	ARMv5TE, VFP, dual-issue
+  Feroceon 88fr131 "Mohawk-D"
+	CPUID 0x5625131x
+	ARMv5TE, single-issue in-order
+  Sheeva PJ1 88sv331 "Mohawk"
+	CPUID 0x561584xx
+	ARMv5, single-issue iWMMXt v2
+  Sheeva PJ4 88sv581x "Flareon"
+	CPUID 0x560f581x
+	ARMv7, idivt, optional iWMMXt v2
+  Sheeva PJ4B 88sv581x
+	CPUID 0x561f581x
+	ARMv7, idivt, optional iWMMXt v2
+  Sheeva PJ4B-MP / PJ4C
+	CPUID 0x562f584x
+	ARMv7, idivt/idiva, LPAE, optional iWMMXt v2 and/or NEON
+
+Long-term plans
+---------------
+
+ * Unify the mach-dove/, mach-mv78xx0/, mach-orion5x/ into the
+   mach-mvebu/ to support all SoCs from the Marvell EBU (Engineering
+   Business Unit) in a single mach-<foo> directory. The plat-orion/
+   would therefore disappear.
+
+ * Unify the mach-mmp/ and mach-pxa/ into the same mach-pxa
+   directory. The plat-pxa/ would therefore disappear.
+
+Credits
+-------
+
+- Maen Suleiman <maen@marvell.com>
+- Lior Amsalem <alior@marvell.com>
+- Thomas Petazzoni <thomas.petazzoni@free-electrons.com>
+- Andrew Lunn <andrew@lunn.ch>
+- Nicolas Pitre <nico@fluxnic.net>
+- Eric Miao <eric.y.miao@gmail.com>
diff --git a/Documentation/arm/mem_alignment b/Documentation/arm/mem_alignment.rst
similarity index 89%
rename from Documentation/arm/mem_alignment
rename to Documentation/arm/mem_alignment.rst
index 6335fcacbba9..7bef27367c9a 100644
--- a/Documentation/arm/mem_alignment
+++ b/Documentation/arm/mem_alignment.rst
@@ -1,3 +1,7 @@
+================
+Memory alignment
+================
+
 Too many problems poped up because of unnoticed misaligned memory access in
 kernel code lately.  Therefore the alignment fixup is now unconditionally
 configured in for SA11x0 based targets.  According to Alan Cox, this is a
@@ -26,9 +30,9 @@ space, and might cause programs to fail unexpectedly.
 To change the alignment trap behavior, simply echo a number into
 /proc/cpu/alignment.  The number is made up from various bits:
 
+===		========================================================
 bit		behavior when set
----		-----------------
-
+===		========================================================
 0		A user process performing an unaligned memory access
 		will cause the kernel to print a message indicating
 		process name, pid, pc, instruction, address, and the
@@ -41,12 +45,13 @@ bit		behavior when set
 
 2		The kernel will send a SIGBUS signal to the user process
 		performing the unaligned access.
+===		========================================================
 
 Note that not all combinations are supported - only values 0 through 5.
 (6 and 7 don't make sense).
 
 For example, the following will turn on the warnings, but without
-fixing up or sending SIGBUS signals:
+fixing up or sending SIGBUS signals::
 
 	echo 1 > /proc/cpu/alignment
 
diff --git a/Documentation/arm/memory.txt b/Documentation/arm/memory.rst
similarity index 90%
rename from Documentation/arm/memory.txt
rename to Documentation/arm/memory.rst
index 546a39048eb0..0521b4ce5c96 100644
--- a/Documentation/arm/memory.txt
+++ b/Documentation/arm/memory.rst
@@ -1,6 +1,9 @@
-		Kernel Memory Layout on ARM Linux
+=================================
+Kernel Memory Layout on ARM Linux
+=================================
 
 		Russell King <rmk@arm.linux.org.uk>
+
 		     November 17, 2005 (2.6.15)
 
 This document describes the virtual memory layout which the Linux
@@ -15,8 +18,9 @@ As the ARM architecture matures, it becomes necessary to reserve
 certain regions of VM space for use for new facilities; therefore
 this document may reserve more VM space over time.
 
+=============== =============== ===============================================
 Start		End		Use
---------------------------------------------------------------------------
+=============== =============== ===============================================
 ffff8000	ffffffff	copy_user_page / clear_user_page use.
 				For SA11xx and Xscale, this is used to
 				setup a minicache mapping.
@@ -77,6 +81,7 @@ MODULES_VADDR	MODULES_END-1	Kernel module space
 				place their vector page here.  NULL pointer
 				dereferences by both the kernel and user
 				space are also caught via this mapping.
+=============== =============== ===============================================
 
 Please note that mappings which collide with the above areas may result
 in a non-bootable kernel, or may cause the kernel to (eventually) panic
diff --git a/Documentation/arm/Microchip/README b/Documentation/arm/microchip.rst
similarity index 92%
rename from Documentation/arm/Microchip/README
rename to Documentation/arm/microchip.rst
index a366f37d38f1..c9a44c98e868 100644
--- a/Documentation/arm/Microchip/README
+++ b/Documentation/arm/microchip.rst
@@ -1,3 +1,4 @@
+=============================
 ARM Microchip SoCs (aka AT91)
 =============================
 
@@ -22,32 +23,46 @@ the Microchip website: http://www.microchip.com.
   Flavors:
     * ARM 920 based SoC
       - at91rm9200
-        + Datasheet
+
+          * Datasheet
+
           http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-1768-32-bit-ARM920T-Embedded-Microprocessor-AT91RM9200_Datasheet.pdf
 
     * ARM 926 based SoCs
       - at91sam9260
-        + Datasheet
+
+          * Datasheet
+
           http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6221-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9260_Datasheet.pdf
 
       - at91sam9xe
-        + Datasheet
+
+          * Datasheet
+
           http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6254-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9XE_Datasheet.pdf
 
       - at91sam9261
-        + Datasheet
+
+          * Datasheet
+
           http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6062-ARM926EJ-S-Microprocessor-SAM9261_Datasheet.pdf
 
       - at91sam9263
-        + Datasheet
+
+          * Datasheet
+
           http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6249-32-bit-ARM926EJ-S-Embedded-Microprocessor-SAM9263_Datasheet.pdf
 
       - at91sam9rl
-        + Datasheet
+
+          * Datasheet
+
           http://ww1.microchip.com/downloads/en/DeviceDoc/doc6289.pdf
 
       - at91sam9g20
-        + Datasheet
+
+          * Datasheet
+
           http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001516A.pdf
 
       - at91sam9g45 family
@@ -55,7 +70,9 @@ the Microchip website: http://www.microchip.com.
         - at91sam9g46
         - at91sam9m10
         - at91sam9m11 (device superset)
-        + Datasheet
+
+          * Datasheet
+
           http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-6437-32-bit-ARM926-Embedded-Microprocessor-SAM9M11_Datasheet.pdf
 
       - at91sam9x5 family (aka "The 5 series")
@@ -64,33 +81,44 @@ the Microchip website: http://www.microchip.com.
         - at91sam9g35
         - at91sam9x25
         - at91sam9x35
-        + Datasheet (can be considered as covering the whole family)
+
+          * Datasheet (can be considered as covering the whole family)
+
           http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-11055-32-bit-ARM926EJ-S-Microcontroller-SAM9X35_Datasheet.pdf
 
       - at91sam9n12
-        + Datasheet
+
+          * Datasheet
+
           http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001517A.pdf
 
     * ARM Cortex-A5 based SoCs
       - sama5d3 family
+
         - sama5d31
         - sama5d33
         - sama5d34
         - sama5d35
         - sama5d36 (device superset)
-        + Datasheet
+
+          * Datasheet
+
           http://ww1.microchip.com/downloads/en/DeviceDoc/Atmel-11121-32-bit-Cortex-A5-Microcontroller-SAMA5D3_Datasheet.pdf
 
     * ARM Cortex-A5 + NEON based SoCs
       - sama5d4 family
+
         - sama5d41
         - sama5d42
         - sama5d43
         - sama5d44 (device superset)
-        + Datasheet
+
+          * Datasheet
+
           http://ww1.microchip.com/downloads/en/DeviceDoc/60001525A.pdf
 
       - sama5d2 family
+
         - sama5d21
         - sama5d22
         - sama5d23
@@ -98,11 +126,14 @@ the Microchip website: http://www.microchip.com.
         - sama5d26
         - sama5d27 (device superset)
         - sama5d28 (device superset + environmental monitors)
-        + Datasheet
+
+          * Datasheet
+
           http://ww1.microchip.com/downloads/en/DeviceDoc/DS60001476B.pdf
 
     * ARM Cortex-M7 MCUs
       - sams70 family
+
         - sams70j19
         - sams70j20
         - sams70j21
@@ -114,6 +145,7 @@ the Microchip website: http://www.microchip.com.
         - sams70q21
 
       - samv70 family
+
         - samv70j19
         - samv70j20
         - samv70n19
@@ -122,6 +154,7 @@ the Microchip website: http://www.microchip.com.
         - samv70q20
 
       - samv71 family
+
         - samv71j19
         - samv71j20
         - samv71j21
@@ -132,7 +165,8 @@ the Microchip website: http://www.microchip.com.
         - samv71q20
         - samv71q21
 
-        + Datasheet
+          * Datasheet
+
           http://ww1.microchip.com/downloads/en/DeviceDoc/60001527A.pdf
 
 
@@ -157,6 +191,7 @@ definition of a "Stable" binding/ABI.
 This statement will be removed by AT91 MAINTAINERS when appropriate.
 
 Naming conventions and best practice:
+
 - SoCs Device Tree Source Include files are named after the official name of
   the product (at91sam9g20.dtsi or sama5d33.dtsi for instance).
 - Device Tree Source Include files (.dtsi) are used to collect common nodes that can be
diff --git a/Documentation/arm/netwinder.rst b/Documentation/arm/netwinder.rst
new file mode 100644
index 000000000000..8eab66caa2ac
--- /dev/null
+++ b/Documentation/arm/netwinder.rst
@@ -0,0 +1,85 @@
+================================
+NetWinder specific documentation
+================================
+
+The NetWinder is a small low-power computer, primarily designed
+to run Linux.  It is based around the StrongARM RISC processor,
+DC21285 PCI bridge, with PC-type hardware glued around it.
+
+Port usage
+==========
+
+=======  ====== ===============================
+Min      Max	Description
+=======  ====== ===============================
+0x0000   0x000f	DMA1
+0x0020   0x0021	PIC1
+0x0060   0x006f	Keyboard
+0x0070   0x007f	RTC
+0x0080   0x0087	DMA1
+0x0088   0x008f	DMA2
+0x00a0   0x00a3	PIC2
+0x00c0   0x00df	DMA2
+0x0180   0x0187	IRDA
+0x01f0   0x01f6	ide0
+0x0201		Game port
+0x0203		RWA010 configuration read
+0x0220   ?	SoundBlaster
+0x0250   ?	WaveArtist
+0x0279		RWA010 configuration index
+0x02f8   0x02ff	Serial ttyS1
+0x0300   0x031f	Ether10
+0x0338		GPIO1
+0x033a		GPIO2
+0x0370   0x0371	W83977F configuration registers
+0x0388   ?	AdLib
+0x03c0   0x03df	VGA
+0x03f6		ide0
+0x03f8   0x03ff	Serial ttyS0
+0x0400   0x0408	DC21143
+0x0480   0x0487	DMA1
+0x0488   0x048f	DMA2
+0x0a79		RWA010 configuration write
+0xe800   0xe80f	ide0/ide1 BM DMA
+=======  ====== ===============================
+
+
+Interrupt usage
+===============
+
+======= ======= ========================
+IRQ	type	Description
+======= ======= ========================
+ 0	ISA	100Hz timer
+ 1	ISA	Keyboard
+ 2	ISA	cascade
+ 3	ISA	Serial ttyS1
+ 4	ISA	Serial ttyS0
+ 5	ISA	PS/2 mouse
+ 6	ISA	IRDA
+ 7	ISA	Printer
+ 8	ISA	RTC alarm
+ 9	ISA
+10	ISA	GP10 (Orange reset button)
+11	ISA
+12	ISA	WaveArtist
+13	ISA
+14	ISA	hda1
+15	ISA
+======= ======= ========================
+
+DMA usage
+=========
+
+======= ======= ===========
+DMA	type	Description
+======= ======= ===========
+ 0	ISA	IRDA
+ 1	ISA
+ 2	ISA	cascade
+ 3	ISA	WaveArtist
+ 4	ISA
+ 5	ISA
+ 6	ISA
+ 7	ISA	WaveArtist
+======= ======= ===========
diff --git a/Documentation/arm/nwfpe/index.rst b/Documentation/arm/nwfpe/index.rst
new file mode 100644
index 000000000000..21fa8ce192ae
--- /dev/null
+++ b/Documentation/arm/nwfpe/index.rst
@@ -0,0 +1,11 @@
+===================================
+NetWinder's floating point emulator
+===================================
+
+.. toctree::
+   :maxdepth: 1
+
+   nwfpe
+   netwinder-fpe
+   notes
+   todo
diff --git a/Documentation/arm/nwfpe/README.FPE b/Documentation/arm/nwfpe/netwinder-fpe.rst
similarity index 94%
rename from Documentation/arm/nwfpe/README.FPE
rename to Documentation/arm/nwfpe/netwinder-fpe.rst
index 26f5d7bb9a41..cbb320960fc4 100644
--- a/Documentation/arm/nwfpe/README.FPE
+++ b/Documentation/arm/nwfpe/netwinder-fpe.rst
@@ -1,12 +1,18 @@
+=============
+Current State
+=============
+
 The following describes the current state of the NetWinder's floating point
 emulator.
 
 In the following nomenclature is used to describe the floating point
 instructions.  It follows the conventions in the ARM manual.
 
-<S|D|E> = <single|double|extended>, no default
-{P|M|Z} = {round to +infinity,round to -infinity,round to zero},
-          default = round to nearest
+::
+
+  <S|D|E> = <single|double|extended>, no default
+  {P|M|Z} = {round to +infinity,round to -infinity,round to zero},
+            default = round to nearest
 
 Note: items enclosed in {} are optional.
 
@@ -32,10 +38,10 @@ Form 2 syntax:
 <LFM|SFM>{cond}<FD,EA> Fd, <count>, [Rn]{!}
 
 These instructions are fully implemented.  They store/load three words
-for each floating point register into the memory location given in the 
+for each floating point register into the memory location given in the
 instruction.  The format in memory is unlikely to be compatible with
 other implementations, in particular the actual hardware.  Specific
-mention of this is made in the ARM manuals.  
+mention of this is made in the ARM manuals.
 
 Floating Point Coprocessor Register Transfer Instructions (CPRT)
 ----------------------------------------------------------------
@@ -123,7 +129,7 @@ RPW{cond}<S|D|E>{P,M,Z} Fd, Fn, <Fm,#value> - reverse power
 POL{cond}<S|D|E>{P,M,Z} Fd, Fn, <Fm,#value> - polar angle (arctan2)
 
 LOG{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - logarithm to base 10
-LGN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - logarithm to base e 
+LGN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - logarithm to base e
 EXP{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - exponent
 SIN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - sine
 COS{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - cosine
@@ -134,7 +140,7 @@ ATN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - arctangent
 
 These are not implemented.  They are not currently issued by the compiler,
 and are handled by routines in libc.  These are not implemented by the FPA11
-hardware, but are handled by the floating point support code.  They should 
+hardware, but are handled by the floating point support code.  They should
 be implemented in future versions.
 
 Signalling:
@@ -147,10 +153,10 @@ current_set[0] correctly.
 The kernel provided with this distribution (vmlinux-nwfpe-0.93) contains
 a fix for this problem and also incorporates the current version of the
 emulator directly.  It is possible to run with no floating point module
-loaded with this kernel.  It is provided as a demonstration of the 
+loaded with this kernel.  It is provided as a demonstration of the
 technology and for those who want to do floating point work that depends
 on signals.  It is not strictly necessary to use the module.
 
-A module (either the one provided by Russell King, or the one in this 
+A module (either the one provided by Russell King, or the one in this
 distribution) can be loaded to replace the functionality of the emulator
 built into the kernel.
diff --git a/Documentation/arm/nwfpe/NOTES b/Documentation/arm/nwfpe/notes.rst
similarity index 99%
rename from Documentation/arm/nwfpe/NOTES
rename to Documentation/arm/nwfpe/notes.rst
index 40577b5a49d3..102e55af8439 100644
--- a/Documentation/arm/nwfpe/NOTES
+++ b/Documentation/arm/nwfpe/notes.rst
@@ -1,3 +1,6 @@
+Notes
+=====
+
 There seems to be a problem with exp(double) and our emulator.  I haven't
 been able to track it down yet.  This does not occur with the emulator
 supplied by Russell King.
diff --git a/Documentation/arm/nwfpe/README b/Documentation/arm/nwfpe/nwfpe.rst
similarity index 98%
rename from Documentation/arm/nwfpe/README
rename to Documentation/arm/nwfpe/nwfpe.rst
index 771871de0c8b..35cd90dacbff 100644
--- a/Documentation/arm/nwfpe/README
+++ b/Documentation/arm/nwfpe/nwfpe.rst
@@ -1,4 +1,7 @@
-This directory contains the version 0.92 test release of the NetWinder 
+Introduction
+============
+
+This directory contains the version 0.92 test release of the NetWinder
 Floating Point Emulator.
 
 The majority of the code was written by me, Scott Bambrough It is
@@ -31,7 +34,7 @@ SoftFloat to the ARM was done by Phil Blundell, based on an earlier
 port of SoftFloat version 1 by Neil Carson for NetBSD/arm32.
 
 The file README.FPE contains a description of what has been implemented
-so far in the emulator.  The file TODO contains a information on what 
+so far in the emulator.  The file TODO contains a information on what
 remains to be done, and other ideas for the emulator.
 
 Bug reports, comments, suggestions should be directed to me at
@@ -48,10 +51,11 @@ Legal Notices
 
 The NetWinder Floating Point Emulator is free software.  Everything Rebel.com
 has written is provided under the GNU GPL.  See the file COPYING for copying
-conditions.  Excluded from the above is the SoftFloat code.  John Hauser's 
+conditions.  Excluded from the above is the SoftFloat code.  John Hauser's
 legal notice for SoftFloat is included below.
 
 -------------------------------------------------------------------------------
+
 SoftFloat Legal Notice
 
 SoftFloat was written by John R. Hauser.  This work was made possible in
diff --git a/Documentation/arm/nwfpe/TODO b/Documentation/arm/nwfpe/todo.rst
similarity index 75%
rename from Documentation/arm/nwfpe/TODO
rename to Documentation/arm/nwfpe/todo.rst
index 8027061b60eb..393f11b14540 100644
--- a/Documentation/arm/nwfpe/TODO
+++ b/Documentation/arm/nwfpe/todo.rst
@@ -1,39 +1,42 @@
 TODO LIST
----------
+=========
 
-POW{cond}<S|D|E>{P,M,Z} Fd, Fn, <Fm,#value> - power
-RPW{cond}<S|D|E>{P,M,Z} Fd, Fn, <Fm,#value> - reverse power
-POL{cond}<S|D|E>{P,M,Z} Fd, Fn, <Fm,#value> - polar angle (arctan2)
+::
 
-LOG{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - logarithm to base 10
-LGN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - logarithm to base e 
-EXP{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - exponent
-SIN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - sine
-COS{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - cosine
-TAN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - tangent
-ASN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - arcsine
-ACS{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - arccosine
-ATN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - arctangent
+  POW{cond}<S|D|E>{P,M,Z} Fd, Fn, <Fm,#value> - power
+  RPW{cond}<S|D|E>{P,M,Z} Fd, Fn, <Fm,#value> - reverse power
+  POL{cond}<S|D|E>{P,M,Z} Fd, Fn, <Fm,#value> - polar angle (arctan2)
+
+  LOG{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - logarithm to base 10
+  LGN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - logarithm to base e
+  EXP{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - exponent
+  SIN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - sine
+  COS{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - cosine
+  TAN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - tangent
+  ASN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - arcsine
+  ACS{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - arccosine
+  ATN{cond}<S|D|E>{P,M,Z} Fd, <Fm,#value> - arctangent
 
 These are not implemented.  They are not currently issued by the compiler,
 and are handled by routines in libc.  These are not implemented by the FPA11
-hardware, but are handled by the floating point support code.  They should 
+hardware, but are handled by the floating point support code.  They should
 be implemented in future versions.
 
 There are a couple of ways to approach the implementation of these.  One
-method would be to use accurate table methods for these routines.  I have 
+method would be to use accurate table methods for these routines.  I have
 a couple of papers by S. Gal from IBM's research labs in Haifa, Israel that
 seem to promise extreme accuracy (in the order of 99.8%) and reasonable speed.
 These methods are used in GLIBC for some of the transcendental functions.
 
 Another approach, which I know little about is CORDIC.  This stands for
-Coordinate Rotation Digital Computer, and is a method of computing 
+Coordinate Rotation Digital Computer, and is a method of computing
 transcendental functions using mostly shifts and adds and a few
 multiplications and divisions.  The ARM excels at shifts and adds,
-so such a method could be promising, but requires more research to 
+so such a method could be promising, but requires more research to
 determine if it is feasible.
 
 Rounding Methods
+----------------
 
 The IEEE standard defines 4 rounding modes.  Round to nearest is the
 default, but rounding to + or - infinity or round to zero are also allowed.
@@ -42,8 +45,8 @@ in a control register.  Not so with the ARM FPA11 architecture.  To change
 the rounding mode one must specify it with each instruction.
 
 This has made porting some benchmarks difficult.  It is possible to
-introduce such a capability into the emulator.  The FPCR contains 
-bits describing the rounding mode.  The emulator could be altered to 
+introduce such a capability into the emulator.  The FPCR contains
+bits describing the rounding mode.  The emulator could be altered to
 examine a flag, which if set forced it to ignore the rounding mode in
 the instruction, and use the mode specified in the bits in the FPCR.
 
@@ -52,7 +55,8 @@ in the FPCR.  This requires a kernel call in ArmLinux, as WFC/RFC are
 supervisor only instructions.  If anyone has any ideas or comments I
 would like to hear them.
 
-[NOTE: pulled out from some docs on ARM floating point, specifically
+NOTE:
+ pulled out from some docs on ARM floating point, specifically
  for the Acorn FPE, but not limited to it:
 
  The floating point control register (FPCR) may only be present in some
@@ -64,4 +68,5 @@ would like to hear them.
 
  Hence, the answer is yes, you could do this, but then you will run a high
  risk of becoming isolated if and when hardware FP emulation comes out
-		-- Russell].
+
+		-- Russell.
diff --git a/Documentation/arm/OMAP/DSS b/Documentation/arm/omap/dss.rst
similarity index 86%
rename from Documentation/arm/OMAP/DSS
rename to Documentation/arm/omap/dss.rst
index 4484e021290e..a40c4d9c717a 100644
--- a/Documentation/arm/OMAP/DSS
+++ b/Documentation/arm/omap/dss.rst
@@ -1,5 +1,6 @@
+=========================
 OMAP2/3 Display Subsystem
--------------------------
+=========================
 
 This is an almost total rewrite of the OMAP FB driver in drivers/video/omap
 (let's call it DSS1). The main differences between DSS1 and DSS2 are DSI,
@@ -190,6 +191,8 @@ trans_key_value			transparency color key (RGB24)
 default_color			default background color (RGB24)
 
 /sys/devices/platform/omapdss/display? directory:
+
+=============== =============================================================
 ctrl_name	Controller name
 mirror		0=off, 1=on
 update_mode	0=off, 1=auto, 2=manual
@@ -202,6 +205,7 @@ timings		Display timings (pixclock,xres/hfp/hbp/hsw,yres/vfp/vbp/vsw)
 panel_name
 tear_elim	Tearing elimination 0=off, 1=on
 output_type	Output type (video encoder only): "composite" or "svideo"
+=============== =============================================================
 
 There are also some debugfs files at <debugfs>/omapdss/ which show information
 about clocks and registers.
@@ -209,22 +213,22 @@ about clocks and registers.
 Examples
 --------
 
-The following definitions have been made for the examples below:
+The following definitions have been made for the examples below::
 
-ovl0=/sys/devices/platform/omapdss/overlay0
-ovl1=/sys/devices/platform/omapdss/overlay1
-ovl2=/sys/devices/platform/omapdss/overlay2
+	ovl0=/sys/devices/platform/omapdss/overlay0
+	ovl1=/sys/devices/platform/omapdss/overlay1
+	ovl2=/sys/devices/platform/omapdss/overlay2
 
-mgr0=/sys/devices/platform/omapdss/manager0
-mgr1=/sys/devices/platform/omapdss/manager1
+	mgr0=/sys/devices/platform/omapdss/manager0
+	mgr1=/sys/devices/platform/omapdss/manager1
 
-lcd=/sys/devices/platform/omapdss/display0
-dvi=/sys/devices/platform/omapdss/display1
-tv=/sys/devices/platform/omapdss/display2
+	lcd=/sys/devices/platform/omapdss/display0
+	dvi=/sys/devices/platform/omapdss/display1
+	tv=/sys/devices/platform/omapdss/display2
 
-fb0=/sys/class/graphics/fb0
-fb1=/sys/class/graphics/fb1
-fb2=/sys/class/graphics/fb2
+	fb0=/sys/class/graphics/fb0
+	fb1=/sys/class/graphics/fb1
+	fb2=/sys/class/graphics/fb2
 
 Default setup on OMAP3 SDP
 --------------------------
@@ -232,55 +236,59 @@ Default setup on OMAP3 SDP
 Here's the default setup on OMAP3 SDP board. All planes go to LCD. DVI
 and TV-out are not in use. The columns from left to right are:
 framebuffers, overlays, overlay managers, displays. Framebuffers are
-handled by omapfb, and the rest by the DSS.
+handled by omapfb, and the rest by the DSS::
 
-FB0 --- GFX  -\            DVI
-FB1 --- VID1 --+- LCD ---- LCD
-FB2 --- VID2 -/   TV ----- TV
+	FB0 --- GFX  -\            DVI
+	FB1 --- VID1 --+- LCD ---- LCD
+	FB2 --- VID2 -/   TV ----- TV
 
 Example: Switch from LCD to DVI
-----------------------
-
-w=`cat $dvi/timings | cut -d "," -f 2 | cut -d "/" -f 1`
-h=`cat $dvi/timings | cut -d "," -f 3 | cut -d "/" -f 1`
-
-echo "0" > $lcd/enabled
-echo "" > $mgr0/display
-fbset -fb /dev/fb0 -xres $w -yres $h -vxres $w -vyres $h
-# at this point you have to switch the dvi/lcd dip-switch from the omap board
-echo "dvi" > $mgr0/display
-echo "1" > $dvi/enabled
-
-After this the configuration looks like:
-
-FB0 --- GFX  -\         -- DVI
-FB1 --- VID1 --+- LCD -/   LCD
-FB2 --- VID2 -/   TV ----- TV
-
-Example: Clone GFX overlay to LCD and TV
 -------------------------------
 
-w=`cat $tv/timings | cut -d "," -f 2 | cut -d "/" -f 1`
-h=`cat $tv/timings | cut -d "," -f 3 | cut -d "/" -f 1`
+::
 
-echo "0" > $ovl0/enabled
-echo "0" > $ovl1/enabled
+	w=`cat $dvi/timings | cut -d "," -f 2 | cut -d "/" -f 1`
+	h=`cat $dvi/timings | cut -d "," -f 3 | cut -d "/" -f 1`
 
-echo "" > $fb1/overlays
-echo "0,1" > $fb0/overlays
+	echo "0" > $lcd/enabled
+	echo "" > $mgr0/display
+	fbset -fb /dev/fb0 -xres $w -yres $h -vxres $w -vyres $h
+	# at this point you have to switch the dvi/lcd dip-switch from the omap board
+	echo "dvi" > $mgr0/display
+	echo "1" > $dvi/enabled
 
-echo "$w,$h" > $ovl1/output_size
-echo "tv" > $ovl1/manager
+After this the configuration looks like:::
 
-echo "1" > $ovl0/enabled
-echo "1" > $ovl1/enabled
+	FB0 --- GFX  -\         -- DVI
+	FB1 --- VID1 --+- LCD -/   LCD
+	FB2 --- VID2 -/   TV ----- TV
 
-echo "1" > $tv/enabled
+Example: Clone GFX overlay to LCD and TV
+----------------------------------------
 
-After this the configuration looks like (only relevant parts shown):
+::
 
-FB0 +-- GFX  ---- LCD ---- LCD
-     \- VID1 ---- TV  ---- TV
+	w=`cat $tv/timings | cut -d "," -f 2 | cut -d "/" -f 1`
+	h=`cat $tv/timings | cut -d "," -f 3 | cut -d "/" -f 1`
+
+	echo "0" > $ovl0/enabled
+	echo "0" > $ovl1/enabled
+
+	echo "" > $fb1/overlays
+	echo "0,1" > $fb0/overlays
+
+	echo "$w,$h" > $ovl1/output_size
+	echo "tv" > $ovl1/manager
+
+	echo "1" > $ovl0/enabled
+	echo "1" > $ovl1/enabled
+
+	echo "1" > $tv/enabled
+
+After this the configuration looks like (only relevant parts shown)::
+
+	FB0 +-- GFX  ---- LCD ---- LCD
+	\- VID1 ---- TV  ---- TV
 
 Misc notes
 ----------
@@ -351,12 +359,14 @@ TODO
 DSS locking
 
 Error checking
+
 - Lots of checks are missing or implemented just as BUG()
 
 System DMA update for DSI
+
 - Can be used for RGB16 and RGB24P modes. Probably not for RGB24U (how
   to skip the empty byte?)
 
 OMAP1 support
+
 - Not sure if needed
-
diff --git a/Documentation/arm/omap/index.rst b/Documentation/arm/omap/index.rst
new file mode 100644
index 000000000000..442aecc6f617
--- /dev/null
+++ b/Documentation/arm/omap/index.rst
@@ -0,0 +1,10 @@
+=======
+TI OMAP
+=======
+
+.. toctree::
+   :maxdepth: 1
+
+   omap.rst
+   omap_pm.rst
+   dss.rst
diff --git a/Documentation/arm/OMAP/README b/Documentation/arm/omap/omap.rst
similarity index 62%
rename from Documentation/arm/OMAP/README
rename to Documentation/arm/omap/omap.rst
index 90c6c57d61e8..f440c0f4613f 100644
--- a/Documentation/arm/OMAP/README
+++ b/Documentation/arm/omap/omap.rst
@@ -1,7 +1,13 @@
+============
+OMAP history
+============
+
 This file contains documentation for running mainline
 kernel on omaps.
 
+======		======================================================
 KERNEL		NEW DEPENDENCIES
+======		======================================================
 v4.3+		Update is needed for custom .config files to make sure
 		CONFIG_REGULATOR_PBIAS is enabled for MMC1 to work
 		properly.
@@ -9,3 +15,4 @@ v4.3+		Update is needed for custom .config files to make sure
 v4.18+		Update is needed for custom .config files to make sure
 		CONFIG_MMC_SDHCI_OMAP is enabled for all MMC instances
 		to work in DRA7 and K2G based boards.
+======		======================================================
diff --git a/Documentation/arm/OMAP/omap_pm b/Documentation/arm/omap/omap_pm.rst
similarity index 83%
rename from Documentation/arm/OMAP/omap_pm
rename to Documentation/arm/omap/omap_pm.rst
index 4ae915a9f899..a335e4c8ce2c 100644
--- a/Documentation/arm/OMAP/omap_pm
+++ b/Documentation/arm/omap/omap_pm.rst
@@ -1,4 +1,4 @@
-
+=====================
 The OMAP PM interface
 =====================
 
@@ -31,19 +31,24 @@ Drivers need to express PM parameters which:
 This document proposes the OMAP PM interface, including the following
 five power management functions for driver code:
 
-1. Set the maximum MPU wakeup latency:
+1. Set the maximum MPU wakeup latency::
+
    (*pdata->set_max_mpu_wakeup_lat)(struct device *dev, unsigned long t)
 
-2. Set the maximum device wakeup latency:
+2. Set the maximum device wakeup latency::
+
    (*pdata->set_max_dev_wakeup_lat)(struct device *dev, unsigned long t)
 
-3. Set the maximum system DMA transfer start latency (CORE pwrdm):
+3. Set the maximum system DMA transfer start latency (CORE pwrdm)::
+
    (*pdata->set_max_sdma_lat)(struct device *dev, long t)
 
-4. Set the minimum bus throughput needed by a device:
+4. Set the minimum bus throughput needed by a device::
+
    (*pdata->set_min_bus_tput)(struct device *dev, u8 agent_id, unsigned long r)
 
-5. Return the number of times the device has lost context
+5. Return the number of times the device has lost context::
+
    (*pdata->get_dev_context_loss_count)(struct device *dev)
 
 
@@ -65,12 +70,13 @@ Driver usage of the OMAP PM functions
 
 As the 'pdata' in the above examples indicates, these functions are
 exposed to drivers through function pointers in driver .platform_data
-structures.  The function pointers are initialized by the board-*.c
+structures.  The function pointers are initialized by the `board-*.c`
 files to point to the corresponding OMAP PM functions:
-.set_max_dev_wakeup_lat will point to
-omap_pm_set_max_dev_wakeup_lat(), etc.  Other architectures which do
-not support these functions should leave these function pointers set
-to NULL.  Drivers should use the following idiom:
+
+- set_max_dev_wakeup_lat will point to
+  omap_pm_set_max_dev_wakeup_lat(), etc.  Other architectures which do
+  not support these functions should leave these function pointers set
+  to NULL.  Drivers should use the following idiom::
 
         if (pdata->set_max_dev_wakeup_lat)
             (*pdata->set_max_dev_wakeup_lat)(dev, t);
@@ -81,7 +87,7 @@ becomes accessible.  To accomplish this, driver writers should use the
 set_max_mpu_wakeup_lat() function to constrain the MPU wakeup
 latency, and the set_max_dev_wakeup_lat() function to constrain the
 device wakeup latency (from clk_enable() to accessibility).  For
-example,
+example::
 
         /* Limit MPU wakeup latency */
         if (pdata->set_max_mpu_wakeup_lat)
@@ -116,17 +122,17 @@ specialized cases to convert that input information (OPPs/MPU
 frequency) into the form that the underlying power management
 implementation needs:
 
-6. (*pdata->dsp_get_opp_table)(void)
+6. `(*pdata->dsp_get_opp_table)(void)`
 
-7. (*pdata->dsp_set_min_opp)(u8 opp_id)
+7. `(*pdata->dsp_set_min_opp)(u8 opp_id)`
 
-8. (*pdata->dsp_get_opp)(void)
+8. `(*pdata->dsp_get_opp)(void)`
 
-9. (*pdata->cpu_get_freq_table)(void)
+9. `(*pdata->cpu_get_freq_table)(void)`
 
-10. (*pdata->cpu_set_freq)(unsigned long f)
+10. `(*pdata->cpu_set_freq)(unsigned long f)`
 
-11. (*pdata->cpu_get_freq)(void)
+11. `(*pdata->cpu_get_freq)(void)`
 
 Customizing OPP for platform
 ============================
@@ -134,12 +140,15 @@ Defining CONFIG_PM should enable OPP layer for the silicon
 and the registration of OPP table should take place automatically.
 However, in special cases, the default OPP table may need to be
 tweaked, for e.g.:
+
  * enable default OPPs which are disabled by default, but which
    could be enabled on a platform
  * Disable an unsupported OPP on the platform
  * Define and add a custom opp table entry
-in these cases, the board file needs to do additional steps as follows:
-arch/arm/mach-omapx/board-xyz.c
+   in these cases, the board file needs to do additional steps as follows:
+
+arch/arm/mach-omapx/board-xyz.c::
+
 	#include "pm.h"
 	....
 	static void __init omap_xyz_init_irq(void)
@@ -150,5 +159,7 @@ arch/arm/mach-omapx/board-xyz.c
 		/* Do customization to the defaults */
 		....
 	}
-NOTE: omapx_opp_init will be omap3_opp_init or as required
-based on the omap family.
+
+NOTE:
+  omapx_opp_init will be omap3_opp_init or as required
+  based on the omap family.
diff --git a/Documentation/arm/Porting b/Documentation/arm/porting.rst
similarity index 94%
rename from Documentation/arm/Porting
rename to Documentation/arm/porting.rst
index a492233931b9..bd21958bdb2d 100644
--- a/Documentation/arm/Porting
+++ b/Documentation/arm/porting.rst
@@ -1,3 +1,7 @@
+=======
+Porting
+=======
+
 Taken from list archive at http://lists.arm.linux.org.uk/pipermail/linux-arm-kernel/2001-July/004064.html
 
 Initial definitions
@@ -89,8 +93,7 @@ DATAADDR
 	Virtual address for the kernel data segment.  Must not be defined
 	when using the decompressor.
 
-VMALLOC_START
-VMALLOC_END
+VMALLOC_START / VMALLOC_END
 	Virtual addresses bounding the vmalloc() area.  There must not be
 	any static mappings in this area; vmalloc will overwrite them.
 	The addresses must also be in the kernel segment (see above).
@@ -107,13 +110,13 @@ Architecture Specific Macros
 ----------------------------
 
 BOOT_MEM(pram,pio,vio)
-	`pram' specifies the physical start address of RAM.  Must always
+	`pram` specifies the physical start address of RAM.  Must always
 	be present, and should be the same as PHYS_OFFSET.
 
-	`pio' is the physical address of an 8MB region containing IO for
+	`pio` is the physical address of an 8MB region containing IO for
 	use with the debugging macros in arch/arm/kernel/debug-armv.S.
 
-	`vio' is the virtual address of the 8MB debugging region.
+	`vio` is the virtual address of the 8MB debugging region.
 
 	It is expected that the debugging region will be re-initialised
 	by the architecture specific code later in the code (via the
@@ -132,4 +135,3 @@ MAPIO(func)
 
 INITIRQ(func)
 	Machine specific function to initialise interrupts.
-
diff --git a/Documentation/arm/pxa/mfp.txt b/Documentation/arm/pxa/mfp.rst
similarity index 83%
rename from Documentation/arm/pxa/mfp.txt
rename to Documentation/arm/pxa/mfp.rst
index 0b7cab978c02..ac34e5d7ee44 100644
--- a/Documentation/arm/pxa/mfp.txt
+++ b/Documentation/arm/pxa/mfp.rst
@@ -1,4 +1,6 @@
-                 MFP Configuration for PXA2xx/PXA3xx Processors
+==============================================
+MFP Configuration for PXA2xx/PXA3xx Processors
+==============================================
 
 			Eric Miao <eric.miao@marvell.com>
 
@@ -6,15 +8,15 @@ MFP stands for Multi-Function Pin, which is the pin-mux logic on PXA3xx and
 later PXA series processors.  This document describes the existing MFP API,
 and how board/platform driver authors could make use of it.
 
- Basic Concept
-===============
+Basic Concept
+=============
 
 Unlike the GPIO alternate function settings on PXA25x and PXA27x, a new MFP
 mechanism is introduced from PXA3xx to completely move the pin-mux functions
 out of the GPIO controller. In addition to pin-mux configurations, the MFP
 also controls the low power state, driving strength, pull-up/down and event
 detection of each pin.  Below is a diagram of internal connections between
-the MFP logic and the remaining SoC peripherals:
+the MFP logic and the remaining SoC peripherals::
 
  +--------+
  |        |--(GPIO19)--+
@@ -69,8 +71,8 @@ NOTE: with such a clear separation of MFP and GPIO, by GPIO<xx> we normally
 mean it is a GPIO signal, and by MFP<xxx> or pin xxx, we mean a physical
 pad (or ball).
 
- MFP API Usage
-===============
+MFP API Usage
+=============
 
 For board code writers, here are some guidelines:
 
@@ -94,9 +96,9 @@ For board code writers, here are some guidelines:
    PXA310 supporting some additional ones), thus the difference is actually
    covered in a single mfp-pxa300.h.
 
-2. prepare an array for the initial pin configurations, e.g.:
+2. prepare an array for the initial pin configurations, e.g.::
 
-   static unsigned long mainstone_pin_config[] __initdata = {
+     static unsigned long mainstone_pin_config[] __initdata = {
 	/* Chip Select */
 	GPIO15_nCS_1,
 
@@ -116,7 +118,7 @@ For board code writers, here are some guidelines:
 
 	/* GPIO */
 	GPIO1_GPIO | WAKEUP_ON_EDGE_BOTH,
-   };
+     };
 
    a) once the pin configurations are passed to pxa{2xx,3xx}_mfp_config(),
    and written to the actual registers, they are useless and may discard,
@@ -143,17 +145,17 @@ For board code writers, here are some guidelines:
    d) although PXA3xx MFP supports edge detection on each pin, the
    internal logic will only wakeup the system when those specific bits
    in ADxER registers are set, which can be well mapped to the
-   corresponding peripheral, thus set_irq_wake() can be called with 
+   corresponding peripheral, thus set_irq_wake() can be called with
    the peripheral IRQ to enable the wakeup.
 
 
- MFP on PXA3xx
-===============
+MFP on PXA3xx
+=============
 
 Every external I/O pad on PXA3xx (excluding those for special purpose) has
 one MFP logic associated, and is controlled by one MFP register (MFPR).
 
-The MFPR has the following bit definitions (for PXA300/PXA310/PXA320):
+The MFPR has the following bit definitions (for PXA300/PXA310/PXA320)::
 
  31                        16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
   +-------------------------+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
@@ -183,8 +185,8 @@ The MFPR has the following bit definitions (for PXA300/PXA310/PXA320):
 			0b006 - slow 10mA
 			0b007 - fast 10mA
 
- MFP Design for PXA2xx/PXA3xx
-==============================
+MFP Design for PXA2xx/PXA3xx
+============================
 
 Due to the difference of pin-mux handling between PXA2xx and PXA3xx, a unified
 MFP API is introduced to cover both series of processors.
@@ -194,11 +196,11 @@ configurations, these definitions are processor and platform independent, and
 the actual API invoked to convert these definitions into register settings and
 make them effective there-after.
 
-  Files Involved
-  --------------
+Files Involved
+--------------
 
   - arch/arm/mach-pxa/include/mach/mfp.h
-  
+
   for
     1. Unified pin definitions - enum constants for all configurable pins
     2. processor-neutral bit definitions for a possible MFP configuration
@@ -226,42 +228,42 @@ make them effective there-after.
   for implementation of the pin configuration to take effect for the actual
   processor.
 
-  Pin Configuration
-  -----------------
+Pin Configuration
+-----------------
 
   The following comments are copied from mfp.h (see the actual source code
-  for most updated info)
-  
-  /*
-   * a possible MFP configuration is represented by a 32-bit integer
-   *
-   * bit  0.. 9 - MFP Pin Number (1024 Pins Maximum)
-   * bit 10..12 - Alternate Function Selection
-   * bit 13..15 - Drive Strength
-   * bit 16..18 - Low Power Mode State
-   * bit 19..20 - Low Power Mode Edge Detection
-   * bit 21..22 - Run Mode Pull State
-   *
-   * to facilitate the definition, the following macros are provided
-   *
-   * MFP_CFG_DEFAULT - default MFP configuration value, with
-   * 		  alternate function = 0,
-   * 		  drive strength = fast 3mA (MFP_DS03X)
-   * 		  low power mode = default
-   * 		  edge detection = none
-   *
-   * MFP_CFG	- default MFPR value with alternate function
-   * MFP_CFG_DRV	- default MFPR value with alternate function and
-   * 		  pin drive strength
-   * MFP_CFG_LPM	- default MFPR value with alternate function and
-   * 		  low power mode
-   * MFP_CFG_X	- default MFPR value with alternate function,
-   * 		  pin drive strength and low power mode
-   */
+  for most updated info)::
 
-   Examples of pin configurations are:
+    /*
+     * a possible MFP configuration is represented by a 32-bit integer
+     *
+     * bit  0.. 9 - MFP Pin Number (1024 Pins Maximum)
+     * bit 10..12 - Alternate Function Selection
+     * bit 13..15 - Drive Strength
+     * bit 16..18 - Low Power Mode State
+     * bit 19..20 - Low Power Mode Edge Detection
+     * bit 21..22 - Run Mode Pull State
+     *
+     * to facilitate the definition, the following macros are provided
+     *
+     * MFP_CFG_DEFAULT - default MFP configuration value, with
+     * 		  alternate function = 0,
+     * 		  drive strength = fast 3mA (MFP_DS03X)
+     * 		  low power mode = default
+     * 		  edge detection = none
+     *
+     * MFP_CFG	- default MFPR value with alternate function
+     * MFP_CFG_DRV	- default MFPR value with alternate function and
+     * 		  pin drive strength
+     * MFP_CFG_LPM	- default MFPR value with alternate function and
+     * 		  low power mode
+     * MFP_CFG_X	- default MFPR value with alternate function,
+     * 		  pin drive strength and low power mode
+     */
 
-   #define GPIO94_SSP3_RXD		MFP_CFG_X(GPIO94, AF1, DS08X, FLOAT)
+   Examples of pin configurations are::
+
+     #define GPIO94_SSP3_RXD		MFP_CFG_X(GPIO94, AF1, DS08X, FLOAT)
 
    which reads GPIO94 can be configured as SSP3_RXD, with alternate function
    selection of 1, driving strength of 0b101, and a float state in low power
@@ -272,8 +274,8 @@ make them effective there-after.
    do so, simply because this default setting is usually carefully encoded,
    and is supposed to work in most cases.
 
-  Register Settings
-  -----------------
+Register Settings
+-----------------
 
    Register settings on PXA3xx for a pin configuration is actually very
    straight-forward, most bits can be converted directly into MFPR value
diff --git a/Documentation/arm/SA1100/ADSBitsy b/Documentation/arm/sa1100/adsbitsy.rst
similarity index 90%
rename from Documentation/arm/SA1100/ADSBitsy
rename to Documentation/arm/sa1100/adsbitsy.rst
index f9f62e8c0719..c179cb26b682 100644
--- a/Documentation/arm/SA1100/ADSBitsy
+++ b/Documentation/arm/sa1100/adsbitsy.rst
@@ -1,4 +1,7 @@
+===============================
 ADS Bitsy Single Board Computer
+===============================
+
 (It is different from Bitsy(iPAQ) of Compaq)
 
 For more details, contact Applied Data Systems or see
@@ -15,7 +18,9 @@ The kernel zImage is linked to be loaded and executed at 0xc0400000.
 Linux can  be used with the ADS BootLoader that ships with the
 newer rev boards. See their documentation on how to load Linux.
 
-Supported peripherals:
+Supported peripherals
+=====================
+
 - SA1100 LCD frame buffer (8/16bpp...sort of)
 - SA1111 USB Master
 - SA1100 serial port
@@ -25,10 +30,13 @@ Supported peripherals:
 - serial ports (ttyS[0-2])
   - ttyS0 is default for serial console
 
-To do:
+To do
+=====
+
 - everything else!  :-)
 
-Notes:
+Notes
+=====
 
 - The flash on board is divided into 3 partitions.
   You should be careful to use flash on board.
diff --git a/Documentation/arm/SA1100/Assabet b/Documentation/arm/sa1100/assabet.rst
similarity index 62%
rename from Documentation/arm/SA1100/Assabet
rename to Documentation/arm/sa1100/assabet.rst
index e08a6739e72c..3e704831c311 100644
--- a/Documentation/arm/SA1100/Assabet
+++ b/Documentation/arm/sa1100/assabet.rst
@@ -1,3 +1,4 @@
+============================================
 The Intel Assabet (SA-1110 evaluation) board
 ============================================
 
@@ -11,7 +12,7 @@ http://www.cs.cmu.edu/~wearable/software/assabet.html
 Building the kernel
 -------------------
 
-To build the kernel with current defaults:
+To build the kernel with current defaults::
 
 	make assabet_config
 	make oldconfig
@@ -51,9 +52,9 @@ Brief examples on how to boot Linux with RedBoot are shown below.  But first
 you need to have RedBoot installed in your flash memory.  A known to work
 precompiled RedBoot binary is available from the following location:
 
-ftp://ftp.netwinder.org/users/n/nico/
-ftp://ftp.arm.linux.org.uk/pub/linux/arm/people/nico/
-ftp://ftp.handhelds.org/pub/linux/arm/sa-1100-patches/
+- ftp://ftp.netwinder.org/users/n/nico/
+- ftp://ftp.arm.linux.org.uk/pub/linux/arm/people/nico/
+- ftp://ftp.handhelds.org/pub/linux/arm/sa-1100-patches/
 
 Look for redboot-assabet*.tgz.  Some installation infos are provided in
 redboot-assabet*.txt.
@@ -71,12 +72,12 @@ Socket Communications Inc.), you should strongly consider using it for TFTP
 file transfers.  You must insert it before RedBoot runs since it can't detect
 it dynamically.
 
-To initialize the flash directory:
+To initialize the flash directory::
 
 	fis init -f
 
 To initialize the non-volatile settings, like whether you want to use BOOTP or
-a static IP address, etc, use this command:
+a static IP address, etc, use this command::
 
 	fconfig -i
 
@@ -85,15 +86,15 @@ Writing a kernel image into flash
 ---------------------------------
 
 First, the kernel image must be loaded into RAM.  If you have the zImage file
-available on a TFTP server:
+available on a TFTP server::
 
 	load zImage -r -b 0x100000
 
-If you rather want to use Y-Modem upload over the serial port:
+If you rather want to use Y-Modem upload over the serial port::
 
 	load -m ymodem -r -b 0x100000
 
-To write it to flash:
+To write it to flash::
 
 	fis create "Linux kernel" -b 0x100000 -l 0xc0000
 
@@ -102,18 +103,18 @@ Booting the kernel
 ------------------
 
 The kernel still requires a filesystem to boot.  A ramdisk image can be loaded
-as follows:
+as follows::
 
 	load ramdisk_image.gz -r -b 0x800000
 
 Again, Y-Modem upload can be used instead of TFTP by replacing the file name
 by '-y ymodem'.
 
-Now the kernel can be retrieved from flash like this:
+Now the kernel can be retrieved from flash like this::
 
 	fis load "Linux kernel"
 
-or loaded as described previously.  To boot the kernel:
+or loaded as described previously.  To boot the kernel::
 
 	exec -b 0x100000 -l 0xc0000
 
@@ -134,35 +135,35 @@ creating JFFS/JFFS2 images is available from the same site.
 For instance, a sample JFFS2 image can be retrieved from the same FTP sites
 mentioned below for the precompiled RedBoot image.
 
-To load this file:
+To load this file::
 
 	load sample_img.jffs2 -r -b 0x100000
 
-The result should look like:
+The result should look like::
 
-RedBoot> load sample_img.jffs2 -r -b 0x100000
-Raw file loaded 0x00100000-0x00377424
+	RedBoot> load sample_img.jffs2 -r -b 0x100000
+	Raw file loaded 0x00100000-0x00377424
 
-Now we must know the size of the unallocated flash:
+Now we must know the size of the unallocated flash::
 
 	fis free
 
-Result:
+Result::
 
-RedBoot> fis free
-  0x500E0000 .. 0x503C0000
+	RedBoot> fis free
+	  0x500E0000 .. 0x503C0000
 
 The values above may be different depending on the size of the filesystem and
 the type of flash.  See their usage below as an example and take care of
 substituting yours appropriately.
 
-We must determine some values:
+We must determine some values::
 
-size of unallocated flash:	0x503c0000 - 0x500e0000 = 0x2e0000
-size of the filesystem image:	0x00377424 - 0x00100000 = 0x277424
+	size of unallocated flash:	0x503c0000 - 0x500e0000 = 0x2e0000
+	size of the filesystem image:	0x00377424 - 0x00100000 = 0x277424
 
 We want to fit the filesystem image of course, but we also want to give it all
-the remaining flash space as well.  To write it:
+the remaining flash space as well.  To write it::
 
 	fis unlock -f 0x500E0000 -l 0x2e0000
 	fis erase -f 0x500E0000 -l 0x2e0000
@@ -171,32 +172,32 @@ the remaining flash space as well.  To write it:
 
 Now the filesystem is associated to a MTD "partition" once Linux has discovered
 what they are in the boot process.  From Redboot, the 'fis list' command
-displays them:
+displays them::
 
-RedBoot> fis list
-Name              FLASH addr  Mem addr    Length      Entry point
-RedBoot           0x50000000  0x50000000  0x00020000  0x00000000
-RedBoot config    0x503C0000  0x503C0000  0x00020000  0x00000000
-FIS directory     0x503E0000  0x503E0000  0x00020000  0x00000000
-Linux kernel      0x50020000  0x00100000  0x000C0000  0x00000000
-JFFS2             0x500E0000  0x500E0000  0x002E0000  0x00000000
+	RedBoot> fis list
+	Name              FLASH addr  Mem addr    Length      Entry point
+	RedBoot           0x50000000  0x50000000  0x00020000  0x00000000
+	RedBoot config    0x503C0000  0x503C0000  0x00020000  0x00000000
+	FIS directory     0x503E0000  0x503E0000  0x00020000  0x00000000
+	Linux kernel      0x50020000  0x00100000  0x000C0000  0x00000000
+	JFFS2             0x500E0000  0x500E0000  0x002E0000  0x00000000
 
-However Linux should display something like:
+However Linux should display something like::
 
-SA1100 flash: probing 32-bit flash bus
-SA1100 flash: Found 2 x16 devices at 0x0 in 32-bit mode
-Using RedBoot partition definition
-Creating 5 MTD partitions on "SA1100 flash":
-0x00000000-0x00020000 : "RedBoot"
-0x00020000-0x000e0000 : "Linux kernel"
-0x000e0000-0x003c0000 : "JFFS2"
-0x003c0000-0x003e0000 : "RedBoot config"
-0x003e0000-0x00400000 : "FIS directory"
+	SA1100 flash: probing 32-bit flash bus
+	SA1100 flash: Found 2 x16 devices at 0x0 in 32-bit mode
+	Using RedBoot partition definition
+	Creating 5 MTD partitions on "SA1100 flash":
+	0x00000000-0x00020000 : "RedBoot"
+	0x00020000-0x000e0000 : "Linux kernel"
+	0x000e0000-0x003c0000 : "JFFS2"
+	0x003c0000-0x003e0000 : "RedBoot config"
+	0x003e0000-0x00400000 : "FIS directory"
 
 What's important here is the position of the partition we are interested in,
 which is the third one.  Within Linux, this correspond to /dev/mtdblock2.
 Therefore to boot Linux with the kernel and its root filesystem in flash, we
-need this RedBoot command:
+need this RedBoot command::
 
 	fis load "Linux kernel"
 	exec -b 0x100000 -l 0xc0000 -c "root=/dev/mtdblock2"
@@ -218,21 +219,21 @@ time the Assabet is rebooted.  Therefore it's possible to automate the boot
 process using RedBoot's scripting capability.
 
 For example, I use this to boot Linux with both the kernel and the ramdisk
-images retrieved from a TFTP server on the network:
+images retrieved from a TFTP server on the network::
 
-RedBoot> fconfig
-Run script at boot: false true
-Boot script:
-Enter script, terminate with empty line
->> load zImage -r -b 0x100000
->> load ramdisk_ks.gz -r -b 0x800000
->> exec -b 0x100000 -l 0xc0000
->>
-Boot script timeout (1000ms resolution): 3
-Use BOOTP for network configuration: true
-GDB connection port: 9000
-Network debug at boot time: false
-Update RedBoot non-volatile configuration - are you sure (y/n)? y
+	RedBoot> fconfig
+	Run script at boot: false true
+	Boot script:
+	Enter script, terminate with empty line
+	>> load zImage -r -b 0x100000
+	>> load ramdisk_ks.gz -r -b 0x800000
+	>> exec -b 0x100000 -l 0xc0000
+	>>
+	Boot script timeout (1000ms resolution): 3
+	Use BOOTP for network configuration: true
+	GDB connection port: 9000
+	Network debug at boot time: false
+	Update RedBoot non-volatile configuration - are you sure (y/n)? y
 
 Then, rebooting the Assabet is just a matter of waiting for the login prompt.
 
@@ -240,6 +241,7 @@ Then, rebooting the Assabet is just a matter of waiting for the login prompt.
 
 Nicolas Pitre
 nico@fluxnic.net
+
 June 12, 2001
 
 
@@ -249,52 +251,51 @@ Status of peripherals in -rmk tree (updated 14/10/2001)
 Assabet:
  Serial ports:
   Radio:		TX, RX, CTS, DSR, DCD, RI
-   PM:			Not tested.
-  COM:			TX, RX, CTS, DSR, DCD, RTS, DTR, PM
-   PM:			Not tested.
-  I2C:			Implemented, not fully tested.
-  L3:			Fully tested, pass.
-   PM:			Not tested.
+   - PM:		Not tested.
+   - COM:		TX, RX, CTS, DSR, DCD, RTS, DTR, PM
+   - PM:		Not tested.
+   - I2C:		Implemented, not fully tested.
+   - L3:		Fully tested, pass.
+   - PM:		Not tested.
 
  Video:
-  LCD:			Fully tested.  PM
-			(LCD doesn't like being blanked with
-			 neponset connected)
-  Video out:		Not fully
+  - LCD:		Fully tested.  PM
+
+   (LCD doesn't like being blanked with neponset connected)
+
+  - Video out:		Not fully
 
  Audio:
   UDA1341:
-   Playback:		Fully tested, pass.
-   Record:		Implemented, not tested.
-   PM:			Not tested.
+  -  Playback:		Fully tested, pass.
+  -  Record:		Implemented, not tested.
+  -  PM:			Not tested.
 
   UCB1200:
-   Audio play:		Implemented, not heavily tested.
-   Audio rec:		Implemented, not heavily tested.
-   Telco audio play:	Implemented, not heavily tested.
-   Telco audio rec:	Implemented, not heavily tested.
-   POTS control:	No
-   Touchscreen:		Yes
-   PM:			Not tested.
+  -  Audio play:	Implemented, not heavily tested.
+  -  Audio rec:		Implemented, not heavily tested.
+  -  Telco audio play:	Implemented, not heavily tested.
+  -  Telco audio rec:	Implemented, not heavily tested.
+  -  POTS control:	No
+  -  Touchscreen:	Yes
+  -  PM:		Not tested.
 
  Other:
-  PCMCIA:
-   LPE:			Fully tested, pass.
-  USB:			No
-  IRDA:
-   SIR:			Fully tested, pass.
-   FIR:			Fully tested, pass.
-   PM:			Not tested.
+  - PCMCIA:
+  - LPE:		Fully tested, pass.
+  - USB:		No
+  - IRDA:
+  - SIR:		Fully tested, pass.
+  - FIR:		Fully tested, pass.
+  - PM:			Not tested.
 
 Neponset:
  Serial ports:
-  COM1,2:	TX, RX, CTS, DSR, DCD, RTS, DTR
-   PM:			Not tested.
-  USB:			Implemented, not heavily tested.
-  PCMCIA:		Implemented, not heavily tested.
-   PM:			Not tested.
-  CF:			Implemented, not heavily tested.
-   PM:			Not tested.
+  - COM1,2:		TX, RX, CTS, DSR, DCD, RTS, DTR
+  - PM:			Not tested.
+  - USB:		Implemented, not heavily tested.
+  - PCMCIA:		Implemented, not heavily tested.
+  - CF:			Implemented, not heavily tested.
+  - PM:			Not tested.
 
 More stuff can be found in the -np (Nicolas Pitre's) tree.
-
diff --git a/Documentation/arm/SA1100/Brutus b/Documentation/arm/sa1100/brutus.rst
similarity index 75%
rename from Documentation/arm/SA1100/Brutus
rename to Documentation/arm/sa1100/brutus.rst
index 6a3aa95e9bfd..e1a23bee6d44 100644
--- a/Documentation/arm/SA1100/Brutus
+++ b/Documentation/arm/sa1100/brutus.rst
@@ -1,9 +1,13 @@
-Brutus is an evaluation platform for the SA1100 manufactured by Intel.  
+======
+Brutus
+======
+
+Brutus is an evaluation platform for the SA1100 manufactured by Intel.
 For more details, see:
 
 http://developer.intel.com
 
-To compile for Brutus, you must issue the following commands:
+To compile for Brutus, you must issue the following commands::
 
 	make brutus_config
 	make config
@@ -16,25 +20,23 @@ must be loaded at 0xc0008000 in Brutus's memory and execution started at
 entry.
 
 But prior to execute the kernel, a ramdisk image must also be loaded in
-memory.  Use memory address 0xd8000000 for this.  Note that the file 
+memory.  Use memory address 0xd8000000 for this.  Note that the file
 containing the (compressed) ramdisk image must not exceed 4 MB.
 
 Typically, you'll need angelboot to load the kernel.
-The following angelboot.opt file should be used:
+The following angelboot.opt file should be used::
 
------ begin angelboot.opt -----
-base 0xc0008000
-entry 0xc0008000
-r0 0x00000000
-r1 0x00000010
-device /dev/ttyS0
-options "9600 8N1"
-baud 115200
-otherfile ramdisk_img.gz
-otherbase 0xd8000000
------ end angelboot.opt -----
+	base 0xc0008000
+	entry 0xc0008000
+	r0 0x00000000
+	r1 0x00000010
+	device /dev/ttyS0
+	options "9600 8N1"
+	baud 115200
+	otherfile ramdisk_img.gz
+	otherbase 0xd8000000
 
-Then load the kernel and ramdisk with:
+Then load the kernel and ramdisk with::
 
 	angelboot -f angelboot.opt zImage
 
@@ -44,14 +46,16 @@ console is provided through the second Brutus serial port. To access it,
 you may use minicom configured with /dev/ttyS1, 9600 baud, 8N1, no flow
 control.
 
-Currently supported:
+Currently supported
+===================
+
 	- RS232 serial ports
 	- audio output
 	- LCD screen
 	- keyboard
-	
-The actual Brutus support may not be complete without extra patches. 
-If such patches exist, they should be found from 
+
+The actual Brutus support may not be complete without extra patches.
+If such patches exist, they should be found from
 ftp.netwinder.org/users/n/nico.
 
 A full PCMCIA support is still missing, although it's possible to hack
@@ -63,4 +67,3 @@ Any contribution is welcome.
 Please send patches to nico@fluxnic.net
 
 Have Fun !
-
diff --git a/Documentation/arm/SA1100/CERF b/Documentation/arm/sa1100/cerf.rst
similarity index 91%
rename from Documentation/arm/SA1100/CERF
rename to Documentation/arm/sa1100/cerf.rst
index b3d845301ef1..7fa71b609bf9 100644
--- a/Documentation/arm/SA1100/CERF
+++ b/Documentation/arm/sa1100/cerf.rst
@@ -1,3 +1,7 @@
+==============
+CerfBoard/Cube
+==============
+
 *** The StrongARM version of the CerfBoard/Cube has been discontinued ***
 
 The Intrinsyc CerfBoard is a StrongARM 1110-based computer on a board
@@ -9,7 +13,9 @@ Intrinsyc website, http://www.intrinsyc.com.
 This document describes the support in the Linux kernel for the
 Intrinsyc CerfBoard.
 
-Supported in this version:
+Supported in this version
+=========================
+
    - CompactFlash+ slot (select PCMCIA in General Setup and any options
      that may be required)
    - Onboard Crystal CS8900 Ethernet controller (Cerf CS8900A support in
@@ -19,7 +25,7 @@ Supported in this version:
 In order to get this kernel onto your Cerf, you need a server that runs
 both BOOTP and TFTP. Detailed instructions should have come with your
 evaluation kit on how to use the bootloader. This series of commands
-will suffice:
+will suffice::
 
    make ARCH=arm CROSS_COMPILE=arm-linux- cerfcube_defconfig
    make ARCH=arm CROSS_COMPILE=arm-linux- zImage
diff --git a/Documentation/arm/sa1100/freebird.rst b/Documentation/arm/sa1100/freebird.rst
new file mode 100644
index 000000000000..81043d0c6d64
--- /dev/null
+++ b/Documentation/arm/sa1100/freebird.rst
@@ -0,0 +1,25 @@
+========
+Freebird
+========
+
+Freebird-1.1 is produced by Legend(C), Inc.
+`http://web.archive.org/web/*/http://www.legend.com.cn`
+and software/linux maintained by Coventive(C), Inc.
+(http://www.coventive.com)
+
+Based on the Nicolas's strongarm kernel tree.
+
+Maintainer:
+
+Chester Kuo
+	- <chester@coventive.com>
+	- <chester@linux.org.tw>
+
+Author:
+
+- Tim wu <timwu@coventive.com>
+- CIH <cih@coventive.com>
+- Eric Peng <ericpeng@coventive.com>
+- Jeff Lee <jeff_lee@coventive.com>
+- Allen Cheng
+- Tony Liu <tonyliu@coventive.com>
diff --git a/Documentation/arm/SA1100/GraphicsClient b/Documentation/arm/sa1100/graphicsclient.rst
similarity index 87%
rename from Documentation/arm/SA1100/GraphicsClient
rename to Documentation/arm/sa1100/graphicsclient.rst
index 867bb35943af..a73d61c3ce91 100644
--- a/Documentation/arm/SA1100/GraphicsClient
+++ b/Documentation/arm/sa1100/graphicsclient.rst
@@ -1,9 +1,11 @@
+=============================================
 ADS GraphicsClient Plus Single Board Computer
+=============================================
 
 For more details, contact Applied Data Systems or see
 http://www.applieddata.net/products.html
 
-The original Linux support for this product has been provided by 
+The original Linux support for this product has been provided by
 Nicolas Pitre <nico@fluxnic.net>. Continued development work by
 Woojung Huh <whuh@applieddata.net>
 
@@ -14,8 +16,8 @@ board supports MTD/JFFS, so you could also mount something on there.
 Use 'make graphicsclient_config' before any 'make config'.  This will set up
 defaults for GraphicsClient Plus support.
 
-The kernel zImage is linked to be loaded and executed at 0xc0200000.  
-Also the following registers should have the specified values upon entry:
+The kernel zImage is linked to be loaded and executed at 0xc0200000.
+Also the following registers should have the specified values upon entry::
 
 	r0 = 0
 	r1 = 29	(this is the GraphicsClient architecture number)
@@ -31,23 +33,21 @@ as outlined below.  In any case, if you're planning on deploying
 something en masse, you should probably get the newer board.
 
 If using Angel on the older boards, here is a typical angel.opt option file
-if the kernel is loaded through the Angel Debug Monitor:
+if the kernel is loaded through the Angel Debug Monitor::
 
------ begin angelboot.opt -----
-base 0xc0200000
-entry 0xc0200000
-r0 0x00000000
-r1 0x0000001d
-device /dev/ttyS1
-options "38400 8N1"
-baud 115200
-#otherfile ramdisk.gz
-#otherbase 0xc0800000
-exec minicom
------ end angelboot.opt -----
+	base 0xc0200000
+	entry 0xc0200000
+	r0 0x00000000
+	r1 0x0000001d
+	device /dev/ttyS1
+	options "38400 8N1"
+	baud 115200
+	#otherfile ramdisk.gz
+	#otherbase 0xc0800000
+	exec minicom
 
 Then the kernel (and ramdisk if otherfile/otherbase lines above are
-uncommented) would be loaded with:
+uncommented) would be loaded with::
 
 	angelboot -f angelboot.opt zImage
 
@@ -59,7 +59,9 @@ If any other bootloader is used, ensure it accomplish the same, especially
 for r0/r1 register values before jumping into the kernel.
 
 
-Supported peripherals:
+Supported peripherals
+=====================
+
 - SA1100 LCD frame buffer (8/16bpp...sort of)
 - on-board SMC 92C96 ethernet NIC
 - SA1100 serial port
@@ -74,11 +76,14 @@ Supported peripherals:
   See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation
   and example user space code. ps/2 keybd is multiplexed through this driver
 
-To do:
+To do
+=====
+
 - UCB1200 audio with new ucb_generic layer
 - everything else!  :-)
 
-Notes:
+Notes
+=====
 
 - The flash on board is divided into 3 partitions.  mtd0 is where
   the ADS boot ROM and zImage is stored.  It's been marked as
@@ -95,4 +100,3 @@ Notes:
   fixed soon.
 
 Any contribution can be sent to nico@fluxnic.net and will be greatly welcome!
-
diff --git a/Documentation/arm/SA1100/GraphicsMaster b/Documentation/arm/sa1100/graphicsmaster.rst
similarity index 92%
rename from Documentation/arm/SA1100/GraphicsMaster
rename to Documentation/arm/sa1100/graphicsmaster.rst
index 9145088a0ba2..e39892514f0c 100644
--- a/Documentation/arm/SA1100/GraphicsMaster
+++ b/Documentation/arm/sa1100/graphicsmaster.rst
@@ -1,4 +1,6 @@
+========================================
 ADS GraphicsMaster Single Board Computer
+========================================
 
 For more details, contact Applied Data Systems or see
 http://www.applieddata.net/products.html
@@ -15,7 +17,9 @@ The kernel zImage is linked to be loaded and executed at 0xc0400000.
 Linux can  be used with the ADS BootLoader that ships with the
 newer rev boards. See their documentation on how to load Linux.
 
-Supported peripherals:
+Supported peripherals
+=====================
+
 - SA1100 LCD frame buffer (8/16bpp...sort of)
 - SA1111 USB Master
 - on-board SMC 92C96 ethernet NIC
@@ -31,10 +35,13 @@ Supported peripherals:
   See http://www.eurotech-inc.com/linux-sbc.asp for IOCTL documentation
   and example user space code. ps/2 keybd is multiplexed through this driver
 
-To do:
+To do
+=====
+
 - everything else!  :-)
 
-Notes:
+Notes
+=====
 
 - The flash on board is divided into 3 partitions.  mtd0 is where
   the zImage is stored.  It's been marked as read-only to keep you
diff --git a/Documentation/arm/SA1100/HUW_WEBPANEL b/Documentation/arm/sa1100/huw_webpanel.rst
similarity index 78%
rename from Documentation/arm/SA1100/HUW_WEBPANEL
rename to Documentation/arm/sa1100/huw_webpanel.rst
index fd56b48d4833..1dc7ccb165f0 100644
--- a/Documentation/arm/SA1100/HUW_WEBPANEL
+++ b/Documentation/arm/sa1100/huw_webpanel.rst
@@ -1,9 +1,14 @@
+=======================
+Hoeft & Wessel Webpanel
+=======================
+
 The HUW_WEBPANEL is a product of the german company Hoeft & Wessel AG
 
 If you want more information, please visit
 http://www.hoeft-wessel.de
 
-To build the kernel:
+To build the kernel::
+
 	make huw_webpanel_config
 	make oldconfig
 	[accept all defaults]
@@ -14,4 +19,3 @@ Roman Jordan         jor@hoeft-wessel.de
 Christoph Schulz    schu@hoeft-wessel.de
 
 2000/12/18/
-
diff --git a/Documentation/arm/sa1100/index.rst b/Documentation/arm/sa1100/index.rst
new file mode 100644
index 000000000000..fb2385b3accf
--- /dev/null
+++ b/Documentation/arm/sa1100/index.rst
@@ -0,0 +1,23 @@
+====================
+Intel StrongARM 1100
+====================
+
+.. toctree::
+    :maxdepth: 1
+
+    adsbitsy
+    assabet
+    brutus
+    cerf
+    freebird
+    graphicsclient
+    graphicsmaster
+    huw_webpanel
+    itsy
+    lart
+    nanoengine
+    pangolin
+    pleb
+    serial_uart
+    tifon
+    yopy
diff --git a/Documentation/arm/SA1100/Itsy b/Documentation/arm/sa1100/itsy.rst
similarity index 88%
rename from Documentation/arm/SA1100/Itsy
rename to Documentation/arm/sa1100/itsy.rst
index 44b94997fa0d..f49896ba3ef1 100644
--- a/Documentation/arm/SA1100/Itsy
+++ b/Documentation/arm/sa1100/itsy.rst
@@ -1,3 +1,7 @@
+====
+Itsy
+====
+
 Itsy is a research project done by the Western Research Lab, and Systems
 Research Center in Palo Alto, CA. The Itsy project is one of several
 research projects at Compaq that are related to pocket computing.
@@ -7,6 +11,7 @@ For more information, see:
 	http://www.hpl.hp.com/downloads/crl/itsy/
 
 Notes on initial 2.4 Itsy support (8/27/2000) :
+
 The port was done on an Itsy version 1.5 machine with a daughtercard with
 64 Meg of DRAM and 32 Meg of Flash. The initial work includes support for
 serial console (to see what you're doing).  No other devices have been
@@ -18,8 +23,10 @@ Finally, you will need to cd to arch/arm/boot/tools and execute a make there
 to build the params-itsy program used to boot the kernel.
 
 In order to install the port of 2.4 to the itsy, You will need to set the
-configuration parameters in the monitor as follows:
-Arg 1:0x08340000, Arg2: 0xC0000000, Arg3:18 (0x12), Arg4:0
+configuration parameters in the monitor as follows::
+
+	Arg 1:0x08340000, Arg2: 0xC0000000, Arg3:18 (0x12), Arg4:0
+
 Make sure the start-routine address is set to 0x00060000.
 
 Next, flash the params-itsy program to 0x00060000 ("p 1 0x00060000" in the
@@ -29,7 +36,8 @@ flash menu)  Flash the kernel in arch/arm/boot/zImage into 0x08340000
 handhelds.org.
 
 The serial connection we established was at:
- 8-bit data, no parity, 1 stop bit(s), 115200.00 b/s. in the monitor, in the
+
+8-bit data, no parity, 1 stop bit(s), 115200.00 b/s. in the monitor, in the
 params-itsy program, and in the kernel itself.  This can be changed, but
 not easily. The monitor parameters are easily changed, the params program
 setup is assembly outl's, and the kernel is a configuration item specific to
diff --git a/Documentation/arm/SA1100/LART b/Documentation/arm/sa1100/lart.rst
similarity index 90%
rename from Documentation/arm/SA1100/LART
rename to Documentation/arm/sa1100/lart.rst
index 6d412b685598..94c0568d1095 100644
--- a/Documentation/arm/SA1100/LART
+++ b/Documentation/arm/sa1100/lart.rst
@@ -1,5 +1,6 @@
+====================================
 Linux Advanced Radio Terminal (LART)
-------------------------------------
+====================================
 
 The LART is a small (7.5 x 10cm) SA-1100 board, designed for embedded
 applications. It has 32 MB DRAM, 4MB Flash ROM, double RS232 and all
diff --git a/Documentation/arm/SA1100/nanoEngine b/Documentation/arm/sa1100/nanoengine.rst
similarity index 74%
rename from Documentation/arm/SA1100/nanoEngine
rename to Documentation/arm/sa1100/nanoengine.rst
index 48a7934f95f6..47f1a14cf98a 100644
--- a/Documentation/arm/SA1100/nanoEngine
+++ b/Documentation/arm/sa1100/nanoengine.rst
@@ -1,11 +1,11 @@
+==========
 nanoEngine
-----------
+==========
 
-"nanoEngine" is a SA1110 based single board computer from 
+"nanoEngine" is a SA1110 based single board computer from
 Bright Star Engineering Inc.  See www.brightstareng.com/arm
 for more info.
 (Ref: Stuart Adams <sja@brightstareng.com>)
 
 Also visit Larry Doolittle's "Linux for the nanoEngine" site:
 http://www.brightstareng.com/arm/nanoeng.htm
-
diff --git a/Documentation/arm/SA1100/Pangolin b/Documentation/arm/sa1100/pangolin.rst
similarity index 81%
rename from Documentation/arm/SA1100/Pangolin
rename to Documentation/arm/sa1100/pangolin.rst
index 077a6120e129..f0c5c1618553 100644
--- a/Documentation/arm/SA1100/Pangolin
+++ b/Documentation/arm/sa1100/pangolin.rst
@@ -1,16 +1,22 @@
+========
+Pangolin
+========
+
 Pangolin is a StrongARM 1110-based evaluation platform produced
 by Dialogue Technology (http://www.dialogue.com.tw/).
 It has EISA slots for ease of configuration with SDRAM/Flash
 memory card, USB/Serial/Audio card, Compact Flash card,
 PCMCIA/IDE card and TFT-LCD card.
 
-To compile for Pangolin, you must issue the following commands:
+To compile for Pangolin, you must issue the following commands::
 
 	make pangolin_config
 	make oldconfig
 	make zImage
 
-Supported peripherals:
+Supported peripherals
+=====================
+
 - SA1110 serial port (UART1/UART2/UART3)
 - flash memory access
 - compact flash driver
diff --git a/Documentation/arm/SA1100/PLEB b/Documentation/arm/sa1100/pleb.rst
similarity index 95%
rename from Documentation/arm/SA1100/PLEB
rename to Documentation/arm/sa1100/pleb.rst
index b9c8a631a351..d5b732967aa3 100644
--- a/Documentation/arm/SA1100/PLEB
+++ b/Documentation/arm/sa1100/pleb.rst
@@ -1,3 +1,7 @@
+====
+PLEB
+====
+
 The PLEB project was started as a student initiative at the School of
 Computer Science and Engineering, University of New South Wales to make a
 pocket computer capable of running the Linux Kernel.
@@ -7,5 +11,3 @@ PLEB support has yet to be fully integrated.
 For more information, see:
 
 	http://www.cse.unsw.edu.au
-
-
diff --git a/Documentation/arm/sa1100/serial_uart.rst b/Documentation/arm/sa1100/serial_uart.rst
new file mode 100644
index 000000000000..ea983642b9be
--- /dev/null
+++ b/Documentation/arm/sa1100/serial_uart.rst
@@ -0,0 +1,51 @@
+==================
+SA1100 serial port
+==================
+
+The SA1100 serial port had its major/minor numbers officially assigned::
+
+  > Date: Sun, 24 Sep 2000 21:40:27 -0700
+  > From: H. Peter Anvin <hpa@transmeta.com>
+  > To: Nicolas Pitre <nico@CAM.ORG>
+  > Cc: Device List Maintainer <device@lanana.org>
+  > Subject: Re: device
+  >
+  > Okay.  Note that device numbers 204 and 205 are used for "low density
+  > serial devices", so you will have a range of minors on those majors (the
+  > tty device layer handles this just fine, so you don't have to worry about
+  > doing anything special.)
+  >
+  > So your assignments are:
+  >
+  > 204 char        Low-density serial ports
+  >                   5 = /dev/ttySA0               SA1100 builtin serial port 0
+  >                   6 = /dev/ttySA1               SA1100 builtin serial port 1
+  >                   7 = /dev/ttySA2               SA1100 builtin serial port 2
+  >
+  > 205 char        Low-density serial ports (alternate device)
+  >                   5 = /dev/cusa0                Callout device for ttySA0
+  >                   6 = /dev/cusa1                Callout device for ttySA1
+  >                   7 = /dev/cusa2                Callout device for ttySA2
+  >
+
+You must create those inodes in /dev on the root filesystem used
+by your SA1100-based device::
+
+	mknod ttySA0 c 204 5
+	mknod ttySA1 c 204 6
+	mknod ttySA2 c 204 7
+	mknod cusa0 c 205 5
+	mknod cusa1 c 205 6
+	mknod cusa2 c 205 7
+
+In addition to the creation of the appropriate device nodes above, you
+must ensure your user space applications make use of the correct device
+name. The classic example is the content of the /etc/inittab file where
+you might have a getty process started on ttyS0.
+
+In this case:
+
+- replace occurrences of ttyS0 with ttySA0, ttyS1 with ttySA1, etc.
+
+- don't forget to add 'ttySA0', 'console', or the appropriate tty name
+  in /etc/securetty for root to be allowed to login as well.
diff --git a/Documentation/arm/SA1100/Tifon b/Documentation/arm/sa1100/tifon.rst
similarity index 88%
rename from Documentation/arm/SA1100/Tifon
rename to Documentation/arm/sa1100/tifon.rst
index dd1934d9c851..c26e910b9ea7 100644
--- a/Documentation/arm/SA1100/Tifon
+++ b/Documentation/arm/sa1100/tifon.rst
@@ -1,7 +1,7 @@
+=====
 Tifon
------
+=====
 
 More info has to come...
 
 Contact: Peter Danielsson <peter.danielsson@era-t.ericsson.se>
-
diff --git a/Documentation/arm/SA1100/Yopy b/Documentation/arm/sa1100/yopy.rst
similarity index 74%
rename from Documentation/arm/SA1100/Yopy
rename to Documentation/arm/sa1100/yopy.rst
index e14f16d836ac..5b35a5f61a44 100644
--- a/Documentation/arm/SA1100/Yopy
+++ b/Documentation/arm/sa1100/yopy.rst
@@ -1,2 +1,5 @@
-See http://www.yopydeveloper.org for more.
+====
+Yopy
+====
 
+See http://www.yopydeveloper.org for more.
diff --git a/Documentation/arm/Samsung-S3C24XX/CPUfreq.txt b/Documentation/arm/samsung-s3c24xx/cpufreq.rst
similarity index 96%
rename from Documentation/arm/Samsung-S3C24XX/CPUfreq.txt
rename to Documentation/arm/samsung-s3c24xx/cpufreq.rst
index fa968aa99d67..2ddc26c03b1f 100644
--- a/Documentation/arm/Samsung-S3C24XX/CPUfreq.txt
+++ b/Documentation/arm/samsung-s3c24xx/cpufreq.rst
@@ -1,5 +1,6 @@
-		S3C24XX CPUfreq support
-		=======================
+=======================
+S3C24XX CPUfreq support
+=======================
 
 Introduction
 ------------
diff --git a/Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt b/Documentation/arm/samsung-s3c24xx/eb2410itx.rst
similarity index 92%
rename from Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt
rename to Documentation/arm/samsung-s3c24xx/eb2410itx.rst
index b87292e05f2f..7863c93652f8 100644
--- a/Documentation/arm/Samsung-S3C24XX/EB2410ITX.txt
+++ b/Documentation/arm/samsung-s3c24xx/eb2410itx.rst
@@ -1,5 +1,6 @@
-		Simtec Electronics EB2410ITX (BAST)
-		===================================
+===================================
+Simtec Electronics EB2410ITX (BAST)
+===================================
 
 	http://www.simtec.co.uk/products/EB2410ITX/
 
diff --git a/Documentation/arm/Samsung-S3C24XX/GPIO.txt b/Documentation/arm/samsung-s3c24xx/gpio.rst
similarity index 89%
rename from Documentation/arm/Samsung-S3C24XX/GPIO.txt
rename to Documentation/arm/samsung-s3c24xx/gpio.rst
index e8f918b96123..f7c3d7d011a2 100644
--- a/Documentation/arm/Samsung-S3C24XX/GPIO.txt
+++ b/Documentation/arm/samsung-s3c24xx/gpio.rst
@@ -1,5 +1,6 @@
-			S3C24XX GPIO Control
-			====================
+====================
+S3C24XX GPIO Control
+====================
 
 Introduction
 ------------
@@ -12,7 +13,7 @@ Introduction
   of the s3c2410 GPIO system, please read the Samsung provided
   data-sheet/users manual to find out the complete list.
 
-  See Documentation/arm/Samsung/GPIO.txt for the core implementation.
+  See Documentation/arm/samsung/gpio.rst for the core implementation.
 
 
 GPIOLIB
@@ -26,16 +27,16 @@ GPIOLIB
   listed below will be removed (they may be marked as __deprecated
   in the near future).
 
-  The following functions now either have a s3c_ specific variant
+  The following functions now either have a `s3c_` specific variant
   or are merged into gpiolib. See the definitions in
   arch/arm/plat-samsung/include/plat/gpio-cfg.h:
 
-  s3c2410_gpio_setpin()		gpio_set_value() or gpio_direction_output()
-  s3c2410_gpio_getpin()		gpio_get_value() or gpio_direction_input()
-  s3c2410_gpio_getirq()		gpio_to_irq()
-  s3c2410_gpio_cfgpin()		s3c_gpio_cfgpin()
-  s3c2410_gpio_getcfg()		s3c_gpio_getcfg()
-  s3c2410_gpio_pullup()		s3c_gpio_setpull()
+  - s3c2410_gpio_setpin()	gpio_set_value() or gpio_direction_output()
+  - s3c2410_gpio_getpin()	gpio_get_value() or gpio_direction_input()
+  - s3c2410_gpio_getirq()	gpio_to_irq()
+  - s3c2410_gpio_cfgpin()	s3c_gpio_cfgpin()
+  - s3c2410_gpio_getcfg()	s3c_gpio_getcfg()
+  - s3c2410_gpio_pullup()	s3c_gpio_setpull()
 
 
 GPIOLIB conversion
@@ -77,7 +78,7 @@ out s3c2410 API, then here are some notes on the process.
 6) s3c2410_gpio_getirq() should be directly replaceable with the
    gpio_to_irq() call.
 
-The s3c2410_gpio and gpio_ calls have always operated on the same gpio
+The s3c2410_gpio and `gpio_` calls have always operated on the same gpio
 numberspace, so there is no problem with converting the gpio numbering
 between the calls.
 
diff --git a/Documentation/arm/Samsung-S3C24XX/H1940.txt b/Documentation/arm/samsung-s3c24xx/h1940.rst
similarity index 94%
rename from Documentation/arm/Samsung-S3C24XX/H1940.txt
rename to Documentation/arm/samsung-s3c24xx/h1940.rst
index b738859b1fc0..62a562c178e3 100644
--- a/Documentation/arm/Samsung-S3C24XX/H1940.txt
+++ b/Documentation/arm/samsung-s3c24xx/h1940.rst
@@ -1,5 +1,6 @@
-		HP IPAQ H1940
-		=============
+=============
+HP IPAQ H1940
+=============
 
 http://www.handhelds.org/projects/h1940.html
 
diff --git a/Documentation/arm/samsung-s3c24xx/index.rst b/Documentation/arm/samsung-s3c24xx/index.rst
new file mode 100644
index 000000000000..6c7b241cbf37
--- /dev/null
+++ b/Documentation/arm/samsung-s3c24xx/index.rst
@@ -0,0 +1,18 @@
+==========================
+Samsung S3C24XX SoC Family
+==========================
+
+.. toctree::
+   :maxdepth: 1
+
+   h1940
+   gpio
+   cpufreq
+   suspend
+   usb-host
+   s3c2412
+   eb2410itx
+   nand
+   smdk2440
+   s3c2413
+   overview
diff --git a/Documentation/arm/Samsung-S3C24XX/NAND.txt b/Documentation/arm/samsung-s3c24xx/nand.rst
similarity index 92%
rename from Documentation/arm/Samsung-S3C24XX/NAND.txt
rename to Documentation/arm/samsung-s3c24xx/nand.rst
index bc478a3409b8..938995694ee7 100644
--- a/Documentation/arm/Samsung-S3C24XX/NAND.txt
+++ b/Documentation/arm/samsung-s3c24xx/nand.rst
@@ -1,5 +1,6 @@
-			S3C24XX NAND Support
-			====================
+====================
+S3C24XX NAND Support
+====================
 
 Introduction
 ------------
@@ -27,4 +28,3 @@ Document Author
 ---------------
 
 Ben Dooks, Copyright 2007 Simtec Electronics
-
diff --git a/Documentation/arm/Samsung-S3C24XX/Overview.txt b/Documentation/arm/samsung-s3c24xx/overview.rst
similarity index 94%
rename from Documentation/arm/Samsung-S3C24XX/Overview.txt
rename to Documentation/arm/samsung-s3c24xx/overview.rst
index 00d3c3141e21..e9a1dc7276b5 100644
--- a/Documentation/arm/Samsung-S3C24XX/Overview.txt
+++ b/Documentation/arm/samsung-s3c24xx/overview.rst
@@ -1,5 +1,6 @@
-			S3C24XX ARM Linux Overview
-			==========================
+==========================
+S3C24XX ARM Linux Overview
+==========================
 
 
 
@@ -182,7 +183,7 @@ NAND
   controller. If there are any problems the latest linux-mtd
   code can be found from http://www.linux-mtd.infradead.org/
 
-  For more information see Documentation/arm/Samsung-S3C24XX/NAND.txt
+  For more information see Documentation/arm/samsung-s3c24xx/nand.rst
 
 
 SD/MMC
@@ -221,8 +222,8 @@ GPIO
   As of v2.6.34, the move towards using gpiolib support is almost
   complete, and very little of the old calls are left.
 
-  See Documentation/arm/Samsung-S3C24XX/GPIO.txt for the S3C24XX specific
-  support and Documentation/arm/Samsung/GPIO.txt for the core Samsung
+  See Documentation/arm/samsung-s3c24xx/gpio.rst for the S3C24XX specific
+  support and Documentation/arm/samsung/gpio.rst for the core Samsung
   implementation.
 
 
@@ -276,18 +277,18 @@ Platform Data
        kmalloc()s an area of memory, and copies the __initdata
        and then sets the relevant device's platform data. Making
        the function `__init` takes care of ensuring it is discarded
-       with the rest of the initialisation code
+       with the rest of the initialisation code::
 
-       static __init void s3c24xx_xxx_set_platdata(struct xxx_data *pd)
-       {
-           struct s3c2410_xxx_mach_info *npd;
+         static __init void s3c24xx_xxx_set_platdata(struct xxx_data *pd)
+         {
+             struct s3c2410_xxx_mach_info *npd;
 
 	   npd = kmalloc(sizeof(struct s3c2410_xxx_mach_info), GFP_KERNEL);
 	   if (npd) {
 	      memcpy(npd, pd, sizeof(struct s3c2410_xxx_mach_info));
 	      s3c_device_xxx.dev.platform_data = npd;
 	   } else {
-              printk(KERN_ERR "no memory for xxx platform data\n");
+                printk(KERN_ERR "no memory for xxx platform data\n");
 	   }
 	}
 
diff --git a/Documentation/arm/Samsung-S3C24XX/S3C2412.txt b/Documentation/arm/samsung-s3c24xx/s3c2412.rst
similarity index 96%
rename from Documentation/arm/Samsung-S3C24XX/S3C2412.txt
rename to Documentation/arm/samsung-s3c24xx/s3c2412.rst
index dc1fd362d3c1..68b985fc6bf4 100644
--- a/Documentation/arm/Samsung-S3C24XX/S3C2412.txt
+++ b/Documentation/arm/samsung-s3c24xx/s3c2412.rst
@@ -1,5 +1,6 @@
-		S3C2412 ARM Linux Overview
-		==========================
+==========================
+S3C2412 ARM Linux Overview
+==========================
 
 Introduction
 ------------
diff --git a/Documentation/arm/Samsung-S3C24XX/S3C2413.txt b/Documentation/arm/samsung-s3c24xx/s3c2413.rst
similarity index 77%
rename from Documentation/arm/Samsung-S3C24XX/S3C2413.txt
rename to Documentation/arm/samsung-s3c24xx/s3c2413.rst
index 909bdc7dd7b5..1f51e207fc46 100644
--- a/Documentation/arm/Samsung-S3C24XX/S3C2413.txt
+++ b/Documentation/arm/samsung-s3c24xx/s3c2413.rst
@@ -1,5 +1,6 @@
-		S3C2413 ARM Linux Overview
-		==========================
+==========================
+S3C2413 ARM Linux Overview
+==========================
 
 Introduction
 ------------
@@ -10,7 +11,7 @@ Introduction
 
 
 Camera Interface
----------------
+----------------
 
   This block is currently not supported.
 
diff --git a/Documentation/arm/Samsung-S3C24XX/SMDK2440.txt b/Documentation/arm/samsung-s3c24xx/smdk2440.rst
similarity index 94%
rename from Documentation/arm/Samsung-S3C24XX/SMDK2440.txt
rename to Documentation/arm/samsung-s3c24xx/smdk2440.rst
index 429390bd4684..524fd0b4afaf 100644
--- a/Documentation/arm/Samsung-S3C24XX/SMDK2440.txt
+++ b/Documentation/arm/samsung-s3c24xx/smdk2440.rst
@@ -1,5 +1,6 @@
-		Samsung/Meritech SMDK2440
-		=========================
+=========================
+Samsung/Meritech SMDK2440
+=========================
 
 Introduction
 ------------
diff --git a/Documentation/arm/Samsung-S3C24XX/Suspend.txt b/Documentation/arm/samsung-s3c24xx/suspend.rst
similarity index 94%
rename from Documentation/arm/Samsung-S3C24XX/Suspend.txt
rename to Documentation/arm/samsung-s3c24xx/suspend.rst
index cb4f0c0cdf9d..b4f3ae9fe76e 100644
--- a/Documentation/arm/Samsung-S3C24XX/Suspend.txt
+++ b/Documentation/arm/samsung-s3c24xx/suspend.rst
@@ -1,5 +1,6 @@
-			S3C24XX Suspend Support
-			=======================
+=======================
+S3C24XX Suspend Support
+=======================
 
 
 Introduction
@@ -57,16 +58,16 @@ Machine Support
   and will end up initialising all compiled machines' pm init!
 
   The following is an example of code used for testing wakeup from
-  an falling edge on IRQ_EINT0:
+  an falling edge on IRQ_EINT0::
 
 
-static irqreturn_t button_irq(int irq, void *pw)
-{
+    static irqreturn_t button_irq(int irq, void *pw)
+    {
 	return IRQ_HANDLED;
-}
+    }
 
-statuc void __init machine_init(void)
-{
+    statuc void __init machine_init(void)
+    {
 	...
 
 	request_irq(IRQ_EINT0, button_irq, IRQF_TRIGGER_FALLING,
@@ -75,7 +76,7 @@ statuc void __init machine_init(void)
 	enable_irq_wake(IRQ_EINT0);
 
 	s3c_pm_init();
-}
+    }
 
 
 Debugging
@@ -134,4 +135,3 @@ Document Author
 ---------------
 
 Ben Dooks, Copyright 2004 Simtec Electronics
-
diff --git a/Documentation/arm/Samsung-S3C24XX/USB-Host.txt b/Documentation/arm/samsung-s3c24xx/usb-host.rst
similarity index 94%
rename from Documentation/arm/Samsung-S3C24XX/USB-Host.txt
rename to Documentation/arm/samsung-s3c24xx/usb-host.rst
index f82b1faefad5..c84268bd1884 100644
--- a/Documentation/arm/Samsung-S3C24XX/USB-Host.txt
+++ b/Documentation/arm/samsung-s3c24xx/usb-host.rst
@@ -1,5 +1,6 @@
-			S3C24XX USB Host support
-			========================
+========================
+S3C24XX USB Host support
+========================
 
 
 
@@ -13,7 +14,7 @@ Configuration
 
   Enable at least the following kernel options:
 
-  menuconfig:
+  menuconfig::
 
    Device Drivers  --->
      USB support  --->
@@ -22,8 +23,9 @@ Configuration
 
 
   .config:
-    CONFIG_USB
-    CONFIG_USB_OHCI_HCD
+
+    - CONFIG_USB
+    - CONFIG_USB_OHCI_HCD
 
 
   Once these options are configured, the standard set of USB device
@@ -60,17 +62,14 @@ Platform Data
   The ports are numbered 0 and 1.
 
   power_control:
-
     Called to enable or disable the power on the port.
 
   enable_oc:
-
     Called to enable or disable the over-current monitoring.
     This should claim or release the resources being used to
     check the power condition on the port, such as an IRQ.
 
   report_oc:
-
     The OHCI driver fills this field in for the over-current code
     to call when there is a change to the over-current state on
     an port. The ports argument is a bitmask of 1 bit per port,
@@ -80,7 +79,6 @@ Platform Data
     ensure this is called correctly.
 
   port[x]:
-
     This is struct describes each port, 0 or 1. The platform driver
     should set the flags field of each port to S3C_HCDFLG_USED if
     the port is enabled.
diff --git a/Documentation/arm/Samsung/Bootloader-interface.txt b/Documentation/arm/samsung/bootloader-interface.rst
similarity index 72%
rename from Documentation/arm/Samsung/Bootloader-interface.txt
rename to Documentation/arm/samsung/bootloader-interface.rst
index d17ed518a7ea..a56f325dae78 100644
--- a/Documentation/arm/Samsung/Bootloader-interface.txt
+++ b/Documentation/arm/samsung/bootloader-interface.rst
@@ -1,7 +1,9 @@
-      Interface between kernel and boot loaders on Exynos boards
-      ==========================================================
+==========================================================
+Interface between kernel and boot loaders on Exynos boards
+==========================================================
 
 Author: Krzysztof Kozlowski
+
 Date  : 6 June 2015
 
 The document tries to describe currently used interface between Linux kernel
@@ -17,8 +19,10 @@ executing kernel.
 1. Non-Secure mode
 
 Address:      sysram_ns_base_addr
+
+============= ============================================ ==================
 Offset        Value                                        Purpose
-=============================================================================
+============= ============================================ ==================
 0x08          exynos_cpu_resume_ns, mcpm_entry_point       System suspend
 0x0c          0x00000bad (Magic cookie)                    System suspend
 0x1c          exynos4_secondary_startup                    Secondary CPU boot
@@ -27,22 +31,28 @@ Offset        Value                                        Purpose
 0x24          exynos_cpu_resume_ns                         AFTR
 0x28 + 4*cpu  0x8 (Magic cookie, Exynos3250)               AFTR
 0x28          0x0 or last value during resume (Exynos542x) System suspend
+============= ============================================ ==================
 
 
 2. Secure mode
 
 Address:      sysram_base_addr
+
+============= ============================================ ==================
 Offset        Value                                        Purpose
-=============================================================================
+============= ============================================ ==================
 0x00          exynos4_secondary_startup                    Secondary CPU boot
 0x04          exynos4_secondary_startup (Exynos542x)       Secondary CPU boot
 4*cpu         exynos4_secondary_startup (Exynos4412)       Secondary CPU boot
 0x20          exynos_cpu_resume (Exynos4210 r1.0)          AFTR
 0x24          0xfcba0d10 (Magic cookie, Exynos4210 r1.0)   AFTR
+============= ============================================ ==================
 
 Address:      pmu_base_addr
+
+============= ============================================ ==================
 Offset        Value                                        Purpose
-=============================================================================
+============= ============================================ ==================
 0x0800        exynos_cpu_resume                            AFTR, suspend
 0x0800        mcpm_entry_point (Exynos542x with MCPM)      AFTR, suspend
 0x0804        0xfcba0d10 (Magic cookie)                    AFTR
@@ -50,15 +60,18 @@ Offset        Value                                        Purpose
 0x0814        exynos4_secondary_startup (Exynos4210 r1.1)  Secondary CPU boot
 0x0818        0xfcba0d10 (Magic cookie, Exynos4210 r1.1)   AFTR
 0x081C        exynos_cpu_resume (Exynos4210 r1.1)          AFTR
-
+============= ============================================ ==================
 
 3. Other (regardless of secure/non-secure mode)
 
 Address:      pmu_base_addr
+
+============= =============================== ===============================
 Offset        Value                           Purpose
-=============================================================================
+============= =============================== ===============================
 0x0908        Non-zero                        Secondary CPU boot up indicator
                                               on Exynos3250 and Exynos542x
+============= =============================== ===============================
 
 
 4. Glossary
diff --git a/Documentation/arm/Samsung/clksrc-change-registers.awk b/Documentation/arm/samsung/clksrc-change-registers.awk
similarity index 100%
rename from Documentation/arm/Samsung/clksrc-change-registers.awk
rename to Documentation/arm/samsung/clksrc-change-registers.awk
diff --git a/Documentation/arm/Samsung/GPIO.txt b/Documentation/arm/samsung/gpio.rst
similarity index 87%
rename from Documentation/arm/Samsung/GPIO.txt
rename to Documentation/arm/samsung/gpio.rst
index 795adfd88081..5f7cadd7159e 100644
--- a/Documentation/arm/Samsung/GPIO.txt
+++ b/Documentation/arm/samsung/gpio.rst
@@ -1,5 +1,6 @@
-		Samsung GPIO implementation
-		===========================
+===========================
+Samsung GPIO implementation
+===========================
 
 Introduction
 ------------
@@ -11,7 +12,7 @@ specific calls provided alongside the drivers/gpio core.
 S3C24XX (Legacy)
 ----------------
 
-See Documentation/arm/Samsung-S3C24XX/GPIO.txt for more information
+See Documentation/arm/samsung-s3c24xx/gpio.rst for more information
 about these devices. Their implementation has been brought into line
 with the core samsung implementation described in this document.
 
diff --git a/Documentation/arm/samsung/index.rst b/Documentation/arm/samsung/index.rst
new file mode 100644
index 000000000000..f54d95734362
--- /dev/null
+++ b/Documentation/arm/samsung/index.rst
@@ -0,0 +1,10 @@
+===========
+Samsung SoC
+===========
+
+.. toctree::
+   :maxdepth: 1
+
+   gpio
+   bootloader-interface
+   overview
diff --git a/Documentation/arm/Samsung/Overview.txt b/Documentation/arm/samsung/overview.rst
similarity index 86%
rename from Documentation/arm/Samsung/Overview.txt
rename to Documentation/arm/samsung/overview.rst
index 8f7309bad460..e74307897416 100644
--- a/Documentation/arm/Samsung/Overview.txt
+++ b/Documentation/arm/samsung/overview.rst
@@ -1,5 +1,6 @@
-		Samsung ARM Linux Overview
-		==========================
+==========================
+Samsung ARM Linux Overview
+==========================
 
 Introduction
 ------------
@@ -11,7 +12,7 @@ Introduction
 
   The currently supported SoCs are:
 
-  - S3C24XX: See Documentation/arm/Samsung-S3C24XX/Overview.txt for full list
+  - S3C24XX: See Documentation/arm/samsung-s3c24xx/overview.rst for full list
   - S3C64XX: S3C6400 and S3C6410
   - S5PC110 / S5PV210
 
@@ -22,7 +23,7 @@ S3C24XX Systems
   There is still documentation in Documnetation/arm/Samsung-S3C24XX/ which
   deals with the architecture and drivers specific to these devices.
 
-  See Documentation/arm/Samsung-S3C24XX/Overview.txt for more information
+  See Documentation/arm/samsung-s3c24xx/overview.rst for more information
   on the implementation details and specific support.
 
 
@@ -32,8 +33,10 @@ Configuration
   A number of configurations are supplied, as there is no current way of
   unifying all the SoCs into one kernel.
 
-  s5pc110_defconfig - S5PC110 specific default configuration
-  s5pv210_defconfig - S5PV210 specific default configuration
+  s5pc110_defconfig
+	- S5PC110 specific default configuration
+  s5pv210_defconfig
+	- S5PV210 specific default configuration
 
 
 Layout
diff --git a/Documentation/arm/Setup b/Documentation/arm/setup.rst
similarity index 87%
rename from Documentation/arm/Setup
rename to Documentation/arm/setup.rst
index 0cb1e64bde80..8e12ef3fb9a7 100644
--- a/Documentation/arm/Setup
+++ b/Documentation/arm/setup.rst
@@ -1,5 +1,6 @@
+=============================================
 Kernel initialisation parameters on ARM Linux
----------------------------------------------
+=============================================
 
 The following document describes the kernel initialisation parameter
 structure, otherwise known as 'struct param_struct' which is used
@@ -14,12 +15,10 @@ There are a lot of parameters listed in there, and they are described
 below:
 
  page_size
-
    This parameter must be set to the page size of the machine, and
    will be checked by the kernel.
 
  nr_pages
-
    This is the total number of pages of memory in the system.  If
    the memory is banked, then this should contain the total number
    of pages in the system.
@@ -28,24 +27,22 @@ below:
    include this information.
 
  ramdisk_size
-
    This is now obsolete, and should not be used.
 
  flags
-
    Various kernel flags, including:
-    bit 0 - 1 = mount root read only
-    bit 1 - unused
-    bit 2 - 0 = load ramdisk
-    bit 3 - 0 = prompt for ramdisk
+
+    =====   ========================
+    bit 0   1 = mount root read only
+    bit 1   unused
+    bit 2   0 = load ramdisk
+    bit 3   0 = prompt for ramdisk
+    =====   ========================
 
  rootdev
-
    major/minor number pair of device to mount as the root filesystem.
 
- video_num_cols
- video_num_rows
-
+ video_num_cols / video_num_rows
    These two together describe the character size of the dummy console,
    or VGA console character size.  They should not be used for any other
    purpose.
@@ -54,66 +51,50 @@ below:
    the equivalent character size of your fbcon display.  This then allows
    all the bootup messages to be displayed correctly.
 
- video_x
- video_y
-
+ video_x / video_y
    This describes the character position of cursor on VGA console, and
    is otherwise unused. (should not be used for other console types, and
    should not be used for other purposes).
 
  memc_control_reg
-
    MEMC chip control register for Acorn Archimedes and Acorn A5000
    based machines.  May be used differently by different architectures.
 
  sounddefault
-
    Default sound setting on Acorn machines.  May be used differently by
    different architectures.
 
  adfsdrives
-
    Number of ADFS/MFM disks.  May be used differently by different
    architectures.
 
- bytes_per_char_h
- bytes_per_char_v
-
+ bytes_per_char_h / bytes_per_char_v
    These are now obsolete, and should not be used.
 
  pages_in_bank[4]
-
    Number of pages in each bank of the systems memory (used for RiscPC).
    This is intended to be used on systems where the physical memory
    is non-contiguous from the processors point of view.
 
  pages_in_vram
-
    Number of pages in VRAM (used on Acorn RiscPC).  This value may also
    be used by loaders if the size of the video RAM can't be obtained
    from the hardware.
 
- initrd_start
- initrd_size
-
+ initrd_start / initrd_size
    This describes the kernel virtual start address and size of the
    initial ramdisk.
 
  rd_start
-
    Start address in sectors of the ramdisk image on a floppy disk.
 
  system_rev
-
    system revision number.
 
- system_serial_low
- system_serial_high
-
+ system_serial_low / system_serial_high
    system 64-bit serial number
 
  mem_fclk_21285
-
    The speed of the external oscillator to the 21285 (footbridge),
    which control's the speed of the memory bus, timer & serial port.
    Depending upon the speed of the cpu its value can be between
@@ -121,9 +102,7 @@ below:
    then a value of 50 Mhz is the default on 21285 architectures.
 
  paths[8][128]
-
    These are now obsolete, and should not be used.
 
  commandline
-
    Kernel command line parameters.  Details can be found elsewhere.
diff --git a/Documentation/arm/SH-Mobile/.gitignore b/Documentation/arm/sh-mobile/.gitignore
similarity index 100%
rename from Documentation/arm/SH-Mobile/.gitignore
rename to Documentation/arm/sh-mobile/.gitignore
diff --git a/Documentation/arm/SPEAr/overview.txt b/Documentation/arm/spear/overview.rst
similarity index 91%
rename from Documentation/arm/SPEAr/overview.txt
rename to Documentation/arm/spear/overview.rst
index 1b049be6c84f..8a1a87aca427 100644
--- a/Documentation/arm/SPEAr/overview.txt
+++ b/Documentation/arm/spear/overview.rst
@@ -1,5 +1,6 @@
-			SPEAr ARM Linux Overview
-			==========================
+========================
+SPEAr ARM Linux Overview
+========================
 
 Introduction
 ------------
@@ -30,17 +31,18 @@ Introduction
 		- SPEAr1340 (SOC)
 			- SPEAr1340 Evaluation Board
 
-  Configuration
-  -------------
+Configuration
+-------------
 
   A generic configuration is provided for each machine, and can be used as the
-  default by
+  default by::
+
 	make spear13xx_defconfig
 	make spear3xx_defconfig
 	make spear6xx_defconfig
 
-  Layout
-  ------
+Layout
+------
 
   The common files for multiple machine families (SPEAr3xx, SPEAr6xx and
   SPEAr13xx) are located in the platform code contained in arch/arm/plat-spear
@@ -57,7 +59,7 @@ Introduction
   support Flattened Device Tree.
 
 
-  Document Author
-  ---------------
+Document Author
+---------------
 
   Viresh Kumar <vireshk@kernel.org>, (c) 2010-2012 ST Microelectronics
diff --git a/Documentation/arm/sti/overview.txt b/Documentation/arm/sti/overview.rst
similarity index 82%
rename from Documentation/arm/sti/overview.txt
rename to Documentation/arm/sti/overview.rst
index 1a4e93d6027f..70743617a74f 100644
--- a/Documentation/arm/sti/overview.txt
+++ b/Documentation/arm/sti/overview.rst
@@ -1,5 +1,6 @@
-			STi ARM Linux Overview
-			==========================
+======================
+STi ARM Linux Overview
+======================
 
 Introduction
 ------------
@@ -10,15 +11,17 @@ Introduction
   B2000 and B2020 Reference boards.
 
 
-  configuration
-  -------------
+configuration
+-------------
 
   A generic configuration is provided for both STiH415/416, and can be used as the
-  default by
+  default by::
+
 	make stih41x_defconfig
 
-  Layout
-  ------
+Layout
+------
+
   All the files for multiple machine families (STiH415, STiH416, and STiG125)
   are located in the platform code contained in arch/arm/mach-sti
 
@@ -27,7 +30,7 @@ Introduction
   Device Trees.
 
 
-  Document Author
-  ---------------
+Document Author
+---------------
 
   Srinivas Kandagatla <srinivas.kandagatla@st.com>, (c) 2013 ST Microelectronics
diff --git a/Documentation/arm/sti/stih407-overview.txt b/Documentation/arm/sti/stih407-overview.rst
similarity index 82%
rename from Documentation/arm/sti/stih407-overview.txt
rename to Documentation/arm/sti/stih407-overview.rst
index 3343f32f58bc..027e75bc7b7c 100644
--- a/Documentation/arm/sti/stih407-overview.txt
+++ b/Documentation/arm/sti/stih407-overview.rst
@@ -1,5 +1,6 @@
-			STiH407 Overview
-			================
+================
+STiH407 Overview
+================
 
 Introduction
 ------------
@@ -12,7 +13,7 @@ Introduction
     - ARM Cortex-A9 1.5 GHz dual core CPU (28nm)
     - SATA2, USB 3.0, PCIe, Gbit Ethernet
 
-  Document Author
-  ---------------
+Document Author
+---------------
 
   Maxime Coquelin <maxime.coquelin@st.com>, (c) 2014 ST Microelectronics
diff --git a/Documentation/arm/sti/stih415-overview.txt b/Documentation/arm/sti/stih415-overview.rst
similarity index 79%
rename from Documentation/arm/sti/stih415-overview.txt
rename to Documentation/arm/sti/stih415-overview.rst
index 1383e33f265d..b67452d610c4 100644
--- a/Documentation/arm/sti/stih415-overview.txt
+++ b/Documentation/arm/sti/stih415-overview.rst
@@ -1,5 +1,6 @@
-			STiH415 Overview
-			================
+================
+STiH415 Overview
+================
 
 Introduction
 ------------
@@ -7,6 +8,7 @@ Introduction
     The STiH415 is the next generation of HD, AVC set-top box processors
     for satellite, cable, terrestrial and IP-STB markets.
 
-    Features
+    Features:
+
     - ARM Cortex-A9 1.0 GHz, dual-core CPU
     - SATA2x2,USB 2.0x3, PCIe, Gbit Ethernet MACx2
diff --git a/Documentation/arm/sti/stih416-overview.txt b/Documentation/arm/sti/stih416-overview.rst
similarity index 83%
rename from Documentation/arm/sti/stih416-overview.txt
rename to Documentation/arm/sti/stih416-overview.rst
index 558444c201c6..93f17d74d8db 100644
--- a/Documentation/arm/sti/stih416-overview.txt
+++ b/Documentation/arm/sti/stih416-overview.rst
@@ -1,5 +1,6 @@
-			STiH416 Overview
-			================
+================
+STiH416 Overview
+================
 
 Introduction
 ------------
diff --git a/Documentation/arm/sti/stih418-overview.txt b/Documentation/arm/sti/stih418-overview.rst
similarity index 83%
rename from Documentation/arm/sti/stih418-overview.txt
rename to Documentation/arm/sti/stih418-overview.rst
index 1cd8fc80646d..b563c1f4fe5a 100644
--- a/Documentation/arm/sti/stih418-overview.txt
+++ b/Documentation/arm/sti/stih418-overview.rst
@@ -1,5 +1,6 @@
-			STiH418 Overview
-			================
+================
+STiH418 Overview
+================
 
 Introduction
 ------------
@@ -14,7 +15,7 @@ Introduction
     - HEVC L5.1 Main 10
     - VP9
 
-  Document Author
-  ---------------
+Document Author
+---------------
 
   Maxime Coquelin <maxime.coquelin@st.com>, (c) 2015 ST Microelectronics
diff --git a/Documentation/arm/stm32/stm32f429-overview.rst b/Documentation/arm/stm32/stm32f429-overview.rst
index 18feda97f483..a7ebe8ea6697 100644
--- a/Documentation/arm/stm32/stm32f429-overview.rst
+++ b/Documentation/arm/stm32/stm32f429-overview.rst
@@ -1,3 +1,4 @@
+==================
 STM32F429 Overview
 ==================
 
@@ -21,6 +22,4 @@ Datasheet and reference manual are publicly available on ST website (STM32F429_)
 
 .. _STM32F429: http://www.st.com/web/en/catalog/mmc/FM141/SC1169/SS1577/LN1806?ecmp=stm32f429-439_pron_pr-ces2014_nov2013
 
-:Authors:
-
-Maxime Coquelin <mcoquelin.stm32@gmail.com>
+:Authors: Maxime Coquelin <mcoquelin.stm32@gmail.com>
diff --git a/Documentation/arm/stm32/stm32f746-overview.rst b/Documentation/arm/stm32/stm32f746-overview.rst
index b5f4b6ce7656..78befddc7740 100644
--- a/Documentation/arm/stm32/stm32f746-overview.rst
+++ b/Documentation/arm/stm32/stm32f746-overview.rst
@@ -1,3 +1,4 @@
+==================
 STM32F746 Overview
 ==================
 
@@ -28,6 +29,4 @@ Datasheet and reference manual are publicly available on ST website (STM32F746_)
 
 .. _STM32F746: http://www.st.com/content/st_com/en/products/microcontrollers/stm32-32-bit-arm-cortex-mcus/stm32f7-series/stm32f7x6/stm32f746ng.html
 
-:Authors:
-
-Alexandre Torgue <alexandre.torgue@st.com>
+:Authors: Alexandre Torgue <alexandre.torgue@st.com>
diff --git a/Documentation/arm/stm32/stm32f769-overview.rst b/Documentation/arm/stm32/stm32f769-overview.rst
index 228656ced2fe..e482980ddf21 100644
--- a/Documentation/arm/stm32/stm32f769-overview.rst
+++ b/Documentation/arm/stm32/stm32f769-overview.rst
@@ -1,3 +1,4 @@
+==================
 STM32F769 Overview
 ==================
 
@@ -30,6 +31,4 @@ Datasheet and reference manual are publicly available on ST website (STM32F769_)
 
 .. _STM32F769: http://www.st.com/content/st_com/en/products/microcontrollers/stm32-32-bit-arm-cortex-mcus/stm32-high-performance-mcus/stm32f7-series/stm32f7x9/stm32f769ni.html
 
-:Authors:
-
-Alexandre Torgue <alexandre.torgue@st.com>
+:Authors: Alexandre Torgue <alexandre.torgue@st.com>
diff --git a/Documentation/arm/stm32/stm32h743-overview.rst b/Documentation/arm/stm32/stm32h743-overview.rst
index 3458dc00095d..4e15f1a42730 100644
--- a/Documentation/arm/stm32/stm32h743-overview.rst
+++ b/Documentation/arm/stm32/stm32h743-overview.rst
@@ -1,3 +1,4 @@
+==================
 STM32H743 Overview
 ==================
 
@@ -29,6 +30,4 @@ Datasheet and reference manual are publicly available on ST website (STM32H743_)
 
 .. _STM32H743: http://www.st.com/en/microcontrollers/stm32h7x3.html?querycriteria=productId=LN2033
 
-:Authors:
-
-Alexandre Torgue <alexandre.torgue@st.com>
+:Authors: Alexandre Torgue <alexandre.torgue@st.com>
diff --git a/Documentation/arm/stm32/stm32mp157-overview.rst b/Documentation/arm/stm32/stm32mp157-overview.rst
index 62e176d47ca7..f62fdc8e7d8d 100644
--- a/Documentation/arm/stm32/stm32mp157-overview.rst
+++ b/Documentation/arm/stm32/stm32mp157-overview.rst
@@ -1,3 +1,4 @@
+===================
 STM32MP157 Overview
 ===================
 
diff --git a/Documentation/arm/sunxi/README b/Documentation/arm/sunxi.rst
similarity index 83%
rename from Documentation/arm/sunxi/README
rename to Documentation/arm/sunxi.rst
index f8efc21998bf..b037428aee98 100644
--- a/Documentation/arm/sunxi/README
+++ b/Documentation/arm/sunxi.rst
@@ -1,3 +1,4 @@
+==================
 ARM Allwinner SoCs
 ==================
 
@@ -10,93 +11,140 @@ SunXi family
   Linux kernel mach directory: arch/arm/mach-sunxi
 
   Flavors:
+
     * ARM926 based SoCs
       - Allwinner F20 (sun3i)
-        + Not Supported
+
+        * Not Supported
 
     * ARM Cortex-A8 based SoCs
       - Allwinner A10 (sun4i)
-        + Datasheet
+
+        * Datasheet
+
 	  http://dl.linux-sunxi.org/A10/A10%20Datasheet%20-%20v1.21%20%282012-04-06%29.pdf
-	+ User Manual
+	* User Manual
+
 	  http://dl.linux-sunxi.org/A10/A10%20User%20Manual%20-%20v1.20%20%282012-04-09%2c%20DECRYPTED%29.pdf
 
       - Allwinner A10s (sun5i)
-        + Datasheet
+
+        * Datasheet
+
           http://dl.linux-sunxi.org/A10s/A10s%20Datasheet%20-%20v1.20%20%282012-03-27%29.pdf
 
       - Allwinner A13 / R8 (sun5i)
-        + Datasheet
+
+        * Datasheet
+
 	  http://dl.linux-sunxi.org/A13/A13%20Datasheet%20-%20v1.12%20%282012-03-29%29.pdf
-        + User Manual
+        * User Manual
+
           http://dl.linux-sunxi.org/A13/A13%20User%20Manual%20-%20v1.2%20%282013-01-08%29.pdf
 
       - Next Thing Co GR8 (sun5i)
 
     * Single ARM Cortex-A7 based SoCs
       - Allwinner V3s (sun8i)
-        + Datasheet
+
+        * Datasheet
+
           http://linux-sunxi.org/File:Allwinner_V3s_Datasheet_V1.0.pdf
 
     * Dual ARM Cortex-A7 based SoCs
       - Allwinner A20 (sun7i)
-        + User Manual
+
+        * User Manual
+
           http://dl.linux-sunxi.org/A20/A20%20User%20Manual%202013-03-22.pdf
 
       - Allwinner A23 (sun8i)
-        + Datasheet
+
+        * Datasheet
+
           http://dl.linux-sunxi.org/A23/A23%20Datasheet%20V1.0%2020130830.pdf
-        + User Manual
+
+        * User Manual
+
           http://dl.linux-sunxi.org/A23/A23%20User%20Manual%20V1.0%2020130830.pdf
 
     * Quad ARM Cortex-A7 based SoCs
       - Allwinner A31 (sun6i)
-        + Datasheet
+
+        * Datasheet
+
           http://dl.linux-sunxi.org/A31/A3x_release_document/A31/IC/A31%20datasheet%20V1.3%2020131106.pdf
-        + User Manual
+
+        * User Manual
+
           http://dl.linux-sunxi.org/A31/A3x_release_document/A31/IC/A31%20user%20manual%20V1.1%2020130630.pdf
 
       - Allwinner A31s (sun6i)
-        + Datasheet
+
+        * Datasheet
+
           http://dl.linux-sunxi.org/A31/A3x_release_document/A31s/IC/A31s%20datasheet%20V1.3%2020131106.pdf
-        + User Manual
+
+        * User Manual
+
           http://dl.linux-sunxi.org/A31/A3x_release_document/A31s/IC/A31s%20User%20Manual%20%20V1.0%2020130322.pdf
 
       - Allwinner A33 (sun8i)
-        + Datasheet
+
+        * Datasheet
+
           http://dl.linux-sunxi.org/A33/A33%20Datasheet%20release%201.1.pdf
-        + User Manual
+
+        * User Manual
+
           http://dl.linux-sunxi.org/A33/A33%20user%20manual%20release%201.1.pdf
 
       - Allwinner H2+ (sun8i)
-        + No document available now, but is known to be working properly with
+
+        * No document available now, but is known to be working properly with
           H3 drivers and memory map.
 
       - Allwinner H3 (sun8i)
-        + Datasheet
+
+        * Datasheet
+
           http://dl.linux-sunxi.org/H3/Allwinner_H3_Datasheet_V1.0.pdf
 
       - Allwinner R40 (sun8i)
-        + Datasheet
+
+        * Datasheet
+
           https://github.com/tinalinux/docs/raw/r40-v1.y/R40_Datasheet_V1.0.pdf
-        + User Manual
+
+        * User Manual
+
           https://github.com/tinalinux/docs/raw/r40-v1.y/Allwinner_R40_User_Manual_V1.0.pdf
 
     * Quad ARM Cortex-A15, Quad ARM Cortex-A7 based SoCs
       - Allwinner A80
-        + Datasheet
+
+        * Datasheet
+
 	  http://dl.linux-sunxi.org/A80/A80_Datasheet_Revision_1.0_0404.pdf
 
     * Octa ARM Cortex-A7 based SoCs
       - Allwinner A83T
-        + Datasheet
+
+        * Datasheet
+
           https://github.com/allwinner-zh/documents/raw/master/A83T/A83T_Datasheet_v1.3_20150510.pdf
-        + User Manual
+
+        * User Manual
+
           https://github.com/allwinner-zh/documents/raw/master/A83T/A83T_User_Manual_v1.5.1_20150513.pdf
 
     * Quad ARM Cortex-A53 based SoCs
       - Allwinner A64
-        + Datasheet
+
+        * Datasheet
+
           http://dl.linux-sunxi.org/A64/A64_Datasheet_V1.1.pdf
-        + User Manual
+
+        * User Manual
+
           http://dl.linux-sunxi.org/A64/Allwinner%20A64%20User%20Manual%20v1.0.pdf
diff --git a/Documentation/arm/sunxi/clocks.txt b/Documentation/arm/sunxi/clocks.rst
similarity index 92%
rename from Documentation/arm/sunxi/clocks.txt
rename to Documentation/arm/sunxi/clocks.rst
index e09a88aa3136..23bd03f3e21f 100644
--- a/Documentation/arm/sunxi/clocks.txt
+++ b/Documentation/arm/sunxi/clocks.rst
@@ -1,3 +1,4 @@
+=======================================================
 Frequently asked questions about the sunxi clock system
 =======================================================
 
@@ -12,7 +13,7 @@ A: The 24MHz oscillator allows gating to save power. Indeed, if gated
    steps, one can gate it and keep the system running. Consider this
    simplified suspend example:
 
-   While the system is operational, you would see something like
+   While the system is operational, you would see something like::
 
       24MHz         32kHz
        |
@@ -23,7 +24,7 @@ A: The 24MHz oscillator allows gating to save power. Indeed, if gated
            [CPU]
 
    When you are about to suspend, you switch the CPU Mux to the 32kHz
-   oscillator:
+   oscillator::
 
       24Mhz         32kHz
        |              |
@@ -33,7 +34,7 @@ A: The 24MHz oscillator allows gating to save power. Indeed, if gated
              |
            [CPU]
 
-    Finally you can gate the main oscillator
+    Finally you can gate the main oscillator::
 
                     32kHz
                       |
diff --git a/Documentation/arm/swp_emulation b/Documentation/arm/swp_emulation.rst
similarity index 63%
rename from Documentation/arm/swp_emulation
rename to Documentation/arm/swp_emulation.rst
index af903d22fd93..6a608a9c3715 100644
--- a/Documentation/arm/swp_emulation
+++ b/Documentation/arm/swp_emulation.rst
@@ -11,17 +11,17 @@ sequence. If a memory access fault (an abort) occurs, a segmentation fault is
 signalled to the triggering process.
 
 /proc/cpu/swp_emulation holds some statistics/information, including the PID of
-the last process to trigger the emulation to be invocated. For example:
----
-Emulated SWP:		12
-Emulated SWPB:		0
-Aborted SWP{B}:		1
-Last process:		314
----
+the last process to trigger the emulation to be invocated. For example::
 
-NOTE: when accessing uncached shared regions, LDREX/STREX rely on an external
-transaction monitoring block called a global monitor to maintain update
-atomicity. If your system does not implement a global monitor, this option can
-cause programs that perform SWP operations to uncached memory to deadlock, as
-the STREX operation will always fail.
+  Emulated SWP:		12
+  Emulated SWPB:		0
+  Aborted SWP{B}:		1
+  Last process:		314
 
+
+NOTE:
+  when accessing uncached shared regions, LDREX/STREX rely on an external
+  transaction monitoring block called a global monitor to maintain update
+  atomicity. If your system does not implement a global monitor, this option can
+  cause programs that perform SWP operations to uncached memory to deadlock, as
+  the STREX operation will always fail.
diff --git a/Documentation/arm/tcm.txt b/Documentation/arm/tcm.rst
similarity index 86%
rename from Documentation/arm/tcm.txt
rename to Documentation/arm/tcm.rst
index 7c15871c1885..effd9c7bc968 100644
--- a/Documentation/arm/tcm.txt
+++ b/Documentation/arm/tcm.rst
@@ -1,5 +1,7 @@
+==================================================
 ARM TCM (Tightly-Coupled Memory) handling in Linux
-----
+==================================================
+
 Written by Linus Walleij <linus.walleij@stericsson.com>
 
 Some ARM SoC:s have a so-called TCM (Tightly-Coupled Memory).
@@ -85,46 +87,50 @@ to have functions called locally inside the TCM without
 wasting space, there is also the __tcmlocalfunc prefix that
 will make the call relative.
 
-Variables to go into dtcm can be tagged like this:
-int __tcmdata foo;
+Variables to go into dtcm can be tagged like this::
 
-Constants can be tagged like this:
-int __tcmconst foo;
+  int __tcmdata foo;
+
+Constants can be tagged like this::
+
+  int __tcmconst foo;
+
+To put assembler into TCM just use::
+
+  .section ".tcm.text" or .section ".tcm.data"
 
-To put assembler into TCM just use
-.section ".tcm.text" or .section ".tcm.data"
 respectively.
 
-Example code:
+Example code::
 
-#include <asm/tcm.h>
+  #include <asm/tcm.h>
 
-/* Uninitialized data */
-static u32 __tcmdata tcmvar;
-/* Initialized data */
-static u32 __tcmdata tcmassigned = 0x2BADBABEU;
-/* Constant */
-static const u32 __tcmconst tcmconst = 0xCAFEBABEU;
+  /* Uninitialized data */
+  static u32 __tcmdata tcmvar;
+  /* Initialized data */
+  static u32 __tcmdata tcmassigned = 0x2BADBABEU;
+  /* Constant */
+  static const u32 __tcmconst tcmconst = 0xCAFEBABEU;
 
-static void __tcmlocalfunc tcm_to_tcm(void)
-{
+  static void __tcmlocalfunc tcm_to_tcm(void)
+  {
 	int i;
 	for (i = 0; i < 100; i++)
 		tcmvar ++;
-}
+  }
 
-static void __tcmfunc hello_tcm(void)
-{
+  static void __tcmfunc hello_tcm(void)
+  {
 	/* Some abstract code that runs in ITCM */
 	int i;
 	for (i = 0; i < 100; i++) {
 		tcmvar ++;
 	}
 	tcm_to_tcm();
-}
+  }
 
-static void __init test_tcm(void)
-{
+  static void __init test_tcm(void)
+  {
 	u32 *tcmem;
 	int i;
 
@@ -152,4 +158,4 @@ static void __init test_tcm(void)
 			printk("TCM tcmem[%d] = %08x\n", i, tcmem[i]);
 		tcm_free(tcmem, 20);
 	}
-}
+  }
diff --git a/Documentation/arm/uefi.txt b/Documentation/arm/uefi.rst
similarity index 63%
rename from Documentation/arm/uefi.txt
rename to Documentation/arm/uefi.rst
index 6543a0adea8a..f868330df6be 100644
--- a/Documentation/arm/uefi.txt
+++ b/Documentation/arm/uefi.rst
@@ -1,3 +1,7 @@
+================================================
+The Unified Extensible Firmware Interface (UEFI)
+================================================
+
 UEFI, the Unified Extensible Firmware Interface, is a specification
 governing the behaviours of compatible firmware interfaces. It is
 maintained by the UEFI Forum - http://www.uefi.org/.
@@ -11,11 +15,13 @@ UEFI support in Linux
 =====================
 Booting on a platform with firmware compliant with the UEFI specification
 makes it possible for the kernel to support additional features:
+
 - UEFI Runtime Services
 - Retrieving various configuration information through the standardised
   interface of UEFI configuration tables. (ACPI, SMBIOS, ...)
 
 For actually enabling [U]EFI support, enable:
+
 - CONFIG_EFI=y
 - CONFIG_EFI_VARS=y or m
 
@@ -42,19 +48,20 @@ Instead, the kernel reads the UEFI memory map.
 
 The stub populates the FDT /chosen node with (and the kernel scans for) the
 following parameters:
-________________________________________________________________________________
-Name                      | Size   | Description
-================================================================================
-linux,uefi-system-table   | 64-bit | Physical address of the UEFI System Table.
---------------------------------------------------------------------------------
-linux,uefi-mmap-start     | 64-bit | Physical address of the UEFI memory map,
-                          |        | populated by the UEFI GetMemoryMap() call.
---------------------------------------------------------------------------------
-linux,uefi-mmap-size      | 32-bit | Size in bytes of the UEFI memory map
-                          |        | pointed to in previous entry.
---------------------------------------------------------------------------------
-linux,uefi-mmap-desc-size | 32-bit | Size in bytes of each entry in the UEFI
-                          |        | memory map.
---------------------------------------------------------------------------------
-linux,uefi-mmap-desc-ver  | 32-bit | Version of the mmap descriptor format.
---------------------------------------------------------------------------------
+
+==========================  ======   ===========================================
+Name                        Size     Description
+==========================  ======   ===========================================
+linux,uefi-system-table     64-bit   Physical address of the UEFI System Table.
+
+linux,uefi-mmap-start       64-bit   Physical address of the UEFI memory map,
+                                     populated by the UEFI GetMemoryMap() call.
+
+linux,uefi-mmap-size        32-bit   Size in bytes of the UEFI memory map
+                                     pointed to in previous entry.
+
+linux,uefi-mmap-desc-size   32-bit   Size in bytes of each entry in the UEFI
+                                     memory map.
+
+linux,uefi-mmap-desc-ver    32-bit   Version of the mmap descriptor format.
+==========================  ======   ===========================================
diff --git a/Documentation/arm/VFP/release-notes.txt b/Documentation/arm/vfp/release-notes.rst
similarity index 92%
rename from Documentation/arm/VFP/release-notes.txt
rename to Documentation/arm/vfp/release-notes.rst
index 28a2795705ca..c6b04937cee3 100644
--- a/Documentation/arm/VFP/release-notes.txt
+++ b/Documentation/arm/vfp/release-notes.rst
@@ -1,7 +1,9 @@
+===============================================
 Release notes for Linux Kernel VFP support code
------------------------------------------------
+===============================================
 
 Date: 	20 May 2004
+
 Author:	Russell King
 
 This is the first release of the Linux Kernel VFP support code.  It
diff --git a/Documentation/arm/vlocks.txt b/Documentation/arm/vlocks.rst
similarity index 98%
rename from Documentation/arm/vlocks.txt
rename to Documentation/arm/vlocks.rst
index 45731672c564..a40a1742110b 100644
--- a/Documentation/arm/vlocks.txt
+++ b/Documentation/arm/vlocks.rst
@@ -1,3 +1,4 @@
+======================================
 vlocks for Bare-Metal Mutual Exclusion
 ======================================
 
@@ -26,7 +27,7 @@ started yet.
 Algorithm
 ---------
 
-The easiest way to explain the vlocks algorithm is with some pseudo-code:
+The easiest way to explain the vlocks algorithm is with some pseudo-code::
 
 
 	int currently_voting[NR_CPUS] = { 0, };
@@ -93,7 +94,7 @@ Features and limitations
    number of CPUs.
 
    vlocks can be cascaded in a voting hierarchy to permit better scaling
-   if necessary, as in the following hypothetical example for 4096 CPUs:
+   if necessary, as in the following hypothetical example for 4096 CPUs::
 
 	/* first level: local election */
 	my_town = towns[(this_cpu >> 4) & 0xf];
@@ -127,12 +128,12 @@ the basic algorithm:
    reduces the number of round-trips required to external memory.
 
    In the ARM implementation, this means that we can use a single load
-   and comparison:
+   and comparison::
 
 	LDR	Rt, [Rn]
 	CMP	Rt, #0
 
-   ...in place of code equivalent to:
+   ...in place of code equivalent to::
 
 	LDRB	Rt, [Rn]
 	CMP	Rt, #0
diff --git a/Documentation/devicetree/bindings/arm/xen.txt b/Documentation/devicetree/bindings/arm/xen.txt
index c9b9321434ea..db5c56db30ec 100644
--- a/Documentation/devicetree/bindings/arm/xen.txt
+++ b/Documentation/devicetree/bindings/arm/xen.txt
@@ -54,7 +54,7 @@ hypervisor {
 };
 
 The format and meaning of the "xen,uefi-*" parameters are similar to those in
-Documentation/arm/uefi.txt, which are provided by the regular UEFI stub. However
+Documentation/arm/uefi.rst, which are provided by the regular UEFI stub. However
 they differ because they are provided by the Xen hypervisor, together with a set
 of UEFI runtime services implemented via hypercalls, see
 http://xenbits.xen.org/docs/unstable/hypercall/x86_64/include,public,platform.h.html.
diff --git a/Documentation/devicetree/booting-without-of.txt b/Documentation/devicetree/booting-without-of.txt
index e86bd2f64117..a8d363d32088 100644
--- a/Documentation/devicetree/booting-without-of.txt
+++ b/Documentation/devicetree/booting-without-of.txt
@@ -160,7 +160,7 @@ it with special cases.
    of the kernel image. That entry point supports two calling
    conventions.  A summary of the interface is described here.  A full
    description of the boot requirements is documented in
-   Documentation/arm/Booting
+   Documentation/arm/booting.rst
 
         a) ATAGS interface.  Minimal information is passed from firmware
         to the kernel with a tagged list of predefined parameters.
@@ -174,7 +174,7 @@ it with special cases.
         b) Entry with a flattened device-tree block.  Firmware loads the
         physical address of the flattened device tree block (dtb) into r2,
         r1 is not used, but it is considered good practice to use a valid
-        machine number as described in Documentation/arm/Booting.
+        machine number as described in Documentation/arm/booting.rst.
 
                 r0 : 0
 
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 3a710dc24fc8..dbfc124bb865 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -1,3 +1,4 @@
+
 .. The Linux Kernel documentation master file, created by
    sphinx-quickstart on Fri Feb 12 13:51:46 2016.
    You can adapt this file completely to your liking, but it should at least
diff --git a/Documentation/translations/zh_CN/arm/Booting b/Documentation/translations/zh_CN/arm/Booting
index 1fe866f8218f..562e9a2957e6 100644
--- a/Documentation/translations/zh_CN/arm/Booting
+++ b/Documentation/translations/zh_CN/arm/Booting
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/arm/Booting
+Chinese translated version of Documentation/arm/booting.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -9,7 +9,7 @@ or if there is a problem with the translation.
 Maintainer: Russell King <linux@arm.linux.org.uk>
 Chinese maintainer: Fu Wei <tekkamanninja@gmail.com>
 ---------------------------------------------------------------------
-Documentation/arm/Booting 的中文翻译
+Documentation/arm/booting.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt b/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt
index cd7fc8f34cf9..99af4363984d 100644
--- a/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt
+++ b/Documentation/translations/zh_CN/arm/kernel_user_helpers.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/arm/kernel_user_helpers.txt
+Chinese translated version of Documentation/arm/kernel_user_helpers.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -10,7 +10,7 @@ Maintainer: Nicolas Pitre <nicolas.pitre@linaro.org>
 		Dave Martin <dave.martin@linaro.org>
 Chinese maintainer: Fu Wei <tekkamanninja@gmail.com>
 ---------------------------------------------------------------------
-Documentation/arm/kernel_user_helpers.txt 的中文翻译
+Documentation/arm/kernel_user_helpers.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/MAINTAINERS b/MAINTAINERS
index f67d86aad5f0..10cac0512711 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2132,7 +2132,7 @@ F:	drivers/*/*s3c64xx*
 F:	drivers/*/*s5pv210*
 F:	drivers/memory/samsung/*
 F:	drivers/soc/samsung/*
-F:	Documentation/arm/Samsung/
+F:	Documentation/arm/samsung/
 F:	Documentation/devicetree/bindings/arm/samsung/
 F:	Documentation/devicetree/bindings/sram/samsung-sram.txt
 F:	Documentation/devicetree/bindings/power/pd-samsung.txt
@@ -11294,7 +11294,7 @@ L:	linux-omap@vger.kernel.org
 L:	linux-fbdev@vger.kernel.org
 S:	Orphan
 F:	drivers/video/fbdev/omap2/
-F:	Documentation/arm/OMAP/DSS
+F:	Documentation/arm/omap/dss.rst
 
 OMAP FRAMEBUFFER SUPPORT
 L:	linux-fbdev@vger.kernel.org
diff --git a/arch/arm/Kconfig b/arch/arm/Kconfig
index c81ee94e8256..c6c424466f8a 100644
--- a/arch/arm/Kconfig
+++ b/arch/arm/Kconfig
@@ -2113,7 +2113,7 @@ config VFP
 	  Say Y to include VFP support code in the kernel. This is needed
 	  if your hardware includes a VFP unit.
 
-	  Please see <file:Documentation/arm/VFP/release-notes.txt> for
+	  Please see <file:Documentation/arm/vfp/release-notes.rst> for
 	  release notes and additional status information.
 
 	  Say N if your target does not have VFP hardware.
diff --git a/arch/arm/common/mcpm_entry.c b/arch/arm/common/mcpm_entry.c
index 1b1b82b37ce0..ef3d407475b7 100644
--- a/arch/arm/common/mcpm_entry.c
+++ b/arch/arm/common/mcpm_entry.c
@@ -24,7 +24,7 @@
 /*
  * The public API for this code is documented in arch/arm/include/asm/mcpm.h.
  * For a comprehensive description of the main algorithm used here, please
- * see Documentation/arm/cluster-pm-race-avoidance.txt.
+ * see Documentation/arm/cluster-pm-race-avoidance.rst.
  */
 
 struct sync_struct mcpm_sync;
diff --git a/arch/arm/common/mcpm_head.S b/arch/arm/common/mcpm_head.S
index 08b3bb9bc6a2..008c95f0b409 100644
--- a/arch/arm/common/mcpm_head.S
+++ b/arch/arm/common/mcpm_head.S
@@ -9,7 +9,7 @@
  * published by the Free Software Foundation.
  *
  *
- * Refer to Documentation/arm/cluster-pm-race-avoidance.txt
+ * Refer to Documentation/arm/cluster-pm-race-avoidance.rst
  * for details of the synchronisation algorithms used here.
  */
 
diff --git a/arch/arm/common/vlock.S b/arch/arm/common/vlock.S
index 8b7df283fedf..3a6d1366b67a 100644
--- a/arch/arm/common/vlock.S
+++ b/arch/arm/common/vlock.S
@@ -15,7 +15,7 @@
  *
  *
  * This algorithm is described in more detail in
- * Documentation/arm/vlocks.txt.
+ * Documentation/arm/vlocks.rst.
  */
 
 #include <linux/linkage.h>
diff --git a/arch/arm/include/asm/setup.h b/arch/arm/include/asm/setup.h
index 3613d7e9fc40..96392cdae861 100644
--- a/arch/arm/include/asm/setup.h
+++ b/arch/arm/include/asm/setup.h
@@ -8,7 +8,7 @@
  * published by the Free Software Foundation.
  *
  *  Structure passed to kernel to tell it about the
- *  hardware it's running on.  See Documentation/arm/Setup
+ *  hardware it's running on.  See Documentation/arm/setup.rst
  *  for more info.
  */
 #ifndef __ASMARM_SETUP_H
diff --git a/arch/arm/include/uapi/asm/setup.h b/arch/arm/include/uapi/asm/setup.h
index 6b335a9ff8c8..25ceda63b284 100644
--- a/arch/arm/include/uapi/asm/setup.h
+++ b/arch/arm/include/uapi/asm/setup.h
@@ -9,7 +9,7 @@
  * published by the Free Software Foundation.
  *
  *  Structure passed to kernel to tell it about the
- *  hardware it's running on.  See Documentation/arm/Setup
+ *  hardware it's running on.  See Documentation/arm/setup.rst
  *  for more info.
  */
 #ifndef _UAPI__ASMARM_SETUP_H
diff --git a/arch/arm/kernel/entry-armv.S b/arch/arm/kernel/entry-armv.S
index ce4aea57130a..57516333496f 100644
--- a/arch/arm/kernel/entry-armv.S
+++ b/arch/arm/kernel/entry-armv.S
@@ -829,7 +829,7 @@ ENDPROC(__switch_to)
  * existing ones.  This mechanism should be used only for things that are
  * really small and justified, and not be abused freely.
  *
- * See Documentation/arm/kernel_user_helpers.txt for formal definitions.
+ * See Documentation/arm/kernel_user_helpers.rst for formal definitions.
  */
  THUMB(	.arm	)
 
diff --git a/arch/arm/mach-exynos/common.h b/arch/arm/mach-exynos/common.h
index c93356a8d662..56411bb63d45 100644
--- a/arch/arm/mach-exynos/common.h
+++ b/arch/arm/mach-exynos/common.h
@@ -106,7 +106,7 @@ void exynos_firmware_init(void);
 #define C2_STATE	(1 << 3)
 /*
  * Magic values for bootloader indicating chosen low power mode.
- * See also Documentation/arm/Samsung/Bootloader-interface.txt
+ * See also Documentation/arm/samsung/bootloader-interface.rst
  */
 #define EXYNOS_SLEEP_MAGIC	0x00000bad
 #define EXYNOS_AFTR_MAGIC	0xfcba0d10
diff --git a/arch/arm/mach-ixp4xx/Kconfig b/arch/arm/mach-ixp4xx/Kconfig
index fea008123eb1..0ee437a25981 100644
--- a/arch/arm/mach-ixp4xx/Kconfig
+++ b/arch/arm/mach-ixp4xx/Kconfig
@@ -19,7 +19,7 @@ config MACH_AVILA
 	help
 	  Say 'Y' here if you want your kernel to support the Gateworks
 	  Avila Network Platform. For more information on this platform,
-	  see <file:Documentation/arm/IXP4xx>.
+	  see <file:Documentation/arm/ixp4xx.rst>.
 
 config MACH_LOFT
     bool "Loft"
@@ -35,7 +35,7 @@ config ARCH_ADI_COYOTE
 	help
 	  Say 'Y' here if you want your kernel to support the ADI 
 	  Engineering Coyote Gateway Reference Platform. For more
-	  information on this platform, see <file:Documentation/arm/IXP4xx>.
+	  information on this platform, see <file:Documentation/arm/ixp4xx.rst>.
 
 config MACH_GATEWAY7001
 	bool "Gateway 7001"
@@ -58,21 +58,21 @@ config ARCH_IXDP425
 	help
 	  Say 'Y' here if you want your kernel to support Intel's 
 	  IXDP425 Development Platform (Also known as Richfield).  
-	  For more information on this platform, see <file:Documentation/arm/IXP4xx>.
+	  For more information on this platform, see <file:Documentation/arm/ixp4xx.rst>.
 
 config MACH_IXDPG425
 	bool "IXDPG425"
 	help
 	  Say 'Y' here if you want your kernel to support Intel's
 	  IXDPG425 Development Platform (Also known as Montajade).
-	  For more information on this platform, see <file:Documentation/arm/IXP4xx>.
+	  For more information on this platform, see <file:Documentation/arm/ixp4xx.rst>.
 
 config MACH_IXDP465
 	bool "IXDP465"
 	help
 	  Say 'Y' here if you want your kernel to support Intel's
 	  IXDP465 Development Platform (Also known as BMP).
-	  For more information on this platform, see <file:Documentation/arm/IXP4xx>.
+	  For more information on this platform, see <file:Documentation/arm/ixp4xx.rst>.
 
 config MACH_GORAMO_MLR
 	bool "GORAMO Multi Link Router"
@@ -85,7 +85,7 @@ config MACH_KIXRP435
 	help
 	  Say 'Y' here if you want your kernel to support Intel's
 	  KIXRP435 Reference Platform.
-	  For more information on this platform, see <file:Documentation/arm/IXP4xx>.
+	  For more information on this platform, see <file:Documentation/arm/ixp4xx.rst>.
 
 #
 # IXCDP1100 is the exact same HW as IXDP425, but with a different machine 
@@ -102,7 +102,7 @@ config ARCH_PRPMC1100
 	help
 	  Say 'Y' here if you want your kernel to support the Motorola
 	  PrPCM1100 Processor Mezanine Module. For more information on
-	  this platform, see <file:Documentation/arm/IXP4xx>.
+	  this platform, see <file:Documentation/arm/ixp4xx.rst>.
 
 config MACH_NAS100D
 	bool
diff --git a/arch/arm/mach-s3c24xx/pm.c b/arch/arm/mach-s3c24xx/pm.c
index adcb90645460..c64988c609ad 100644
--- a/arch/arm/mach-s3c24xx/pm.c
+++ b/arch/arm/mach-s3c24xx/pm.c
@@ -5,7 +5,7 @@
 //
 // S3C24XX Power Manager (Suspend-To-RAM) support
 //
-// See Documentation/arm/Samsung-S3C24XX/Suspend.txt for more information
+// See Documentation/arm/samsung-s3c24xx/suspend.rst for more information
 //
 // Parts based on arch/arm/mach-pxa/pm.c
 //
diff --git a/arch/arm/mm/Kconfig b/arch/arm/mm/Kconfig
index b169e580bf82..28f11246de41 100644
--- a/arch/arm/mm/Kconfig
+++ b/arch/arm/mm/Kconfig
@@ -709,7 +709,7 @@ config ARM_VIRT_EXT
 	  assistance.
 
 	  A compliant bootloader is required in order to make maximum
-	  use of this feature.  Refer to Documentation/arm/Booting for
+	  use of this feature.  Refer to Documentation/arm/booting.rst for
 	  details.
 
 config SWP_EMULATE
@@ -867,7 +867,7 @@ config KUSER_HELPERS
 	  the CPU type fitted to the system.  This permits binaries to be
 	  run on ARMv4 through to ARMv7 without modification.
 
-	  See Documentation/arm/kernel_user_helpers.txt for details.
+	  See Documentation/arm/kernel_user_helpers.rst for details.
 
 	  However, the fixed address nature of these helpers can be used
 	  by ROP (return orientated programming) authors when creating
diff --git a/arch/arm/plat-samsung/Kconfig b/arch/arm/plat-samsung/Kconfig
index 53da57fba39c..301e572651c0 100644
--- a/arch/arm/plat-samsung/Kconfig
+++ b/arch/arm/plat-samsung/Kconfig
@@ -243,7 +243,7 @@ config SAMSUNG_PM_DEBUG
 	depends on DEBUG_EXYNOS_UART || DEBUG_S3C24XX_UART || DEBUG_S3C2410_UART
 	help
 	  Say Y here if you want verbose debugging from the PM Suspend and
-	  Resume code. See <file:Documentation/arm/Samsung-S3C24XX/Suspend.txt>
+	  Resume code. See <file:Documentation/arm/samsung-s3c24xx/suspend.rst>
 	  for more information.
 
 config S3C_PM_DEBUG_LED_SMDK
@@ -268,7 +268,7 @@ config SAMSUNG_PM_CHECK
 	  Note, this can take several seconds depending on memory size
 	  and CPU speed.
 
-	  See <file:Documentation/arm/Samsung-S3C24XX/Suspend.txt>
+	  See <file:Documentation/arm/samsung-s3c24xx/suspend.rst>
 
 config SAMSUNG_PM_CHECK_CHUNKSIZE
 	int "S3C2410 PM Suspend CRC Chunksize (KiB)"
@@ -280,7 +280,7 @@ config SAMSUNG_PM_CHECK_CHUNKSIZE
 	  the CRC data block will take more memory, but will identify any
 	  faults with better precision.
 
-	  See <file:Documentation/arm/Samsung-S3C24XX/Suspend.txt>
+	  See <file:Documentation/arm/samsung-s3c24xx/suspend.rst>
 
 config SAMSUNG_WAKEMASK
 	bool
diff --git a/arch/arm/tools/mach-types b/arch/arm/tools/mach-types
index 4eac94c1eb6f..9e74c7ff6b04 100644
--- a/arch/arm/tools/mach-types
+++ b/arch/arm/tools/mach-types
@@ -7,7 +7,7 @@
 #   http://www.arm.linux.org.uk/developer/machines/download.php
 #
 # Please do not send patches to this file; it is automatically generated!
-# To add an entry into this database, please see Documentation/arm/README,
+# To add an entry into this database, please see Documentation/arm/arm.rst,
 # or visit:
 #
 #   http://www.arm.linux.org.uk/developer/machines/?action=new
diff --git a/arch/arm64/kernel/kuser32.S b/arch/arm64/kernel/kuser32.S
index 997e6b27ff6a..14b8b685eabb 100644
--- a/arch/arm64/kernel/kuser32.S
+++ b/arch/arm64/kernel/kuser32.S
@@ -25,7 +25,7 @@
  * existing ones.  This mechanism should be used only for things that are
  * really small and justified, and not be abused freely.
  *
- * See Documentation/arm/kernel_user_helpers.txt for formal definitions.
+ * See Documentation/arm/kernel_user_helpers.rst for formal definitions.
  */
 
 #include <asm/unistd.h>
diff --git a/arch/mips/bmips/setup.c b/arch/mips/bmips/setup.c
index 1738a06396f9..2f81a94c71a6 100644
--- a/arch/mips/bmips/setup.c
+++ b/arch/mips/bmips/setup.c
@@ -162,7 +162,7 @@ void __init plat_mem_setup(void)
 	ioport_resource.start = 0;
 	ioport_resource.end = ~0;
 
-	/* intended to somewhat resemble ARM; see Documentation/arm/Booting */
+	/* intended to somewhat resemble ARM; see Documentation/arm/booting.rst */
 	if (fw_arg0 == 0 && fw_arg1 == 0xffffffff)
 		dtb = phys_to_virt(fw_arg2);
 	else if (fw_passed_dtb) /* UHI interface or appended dtb */
diff --git a/drivers/crypto/sunxi-ss/sun4i-ss-cipher.c b/drivers/crypto/sunxi-ss/sun4i-ss-cipher.c
index 54fd714d53ca..5b19e1287ae7 100644
--- a/drivers/crypto/sunxi-ss/sun4i-ss-cipher.c
+++ b/drivers/crypto/sunxi-ss/sun4i-ss-cipher.c
@@ -7,7 +7,7 @@
  * keysize in CBC and ECB mode.
  * Add support also for DES and 3DES in CBC and ECB mode.
  *
- * You could find the datasheet in Documentation/arm/sunxi/README
+ * You could find the datasheet in Documentation/arm/sunxi.rst
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
diff --git a/drivers/crypto/sunxi-ss/sun4i-ss-core.c b/drivers/crypto/sunxi-ss/sun4i-ss-core.c
index 89adf9e0fed2..1d0bc6e72635 100644
--- a/drivers/crypto/sunxi-ss/sun4i-ss-core.c
+++ b/drivers/crypto/sunxi-ss/sun4i-ss-core.c
@@ -5,7 +5,7 @@
  *
  * Core file which registers crypto algorithms supported by the SS.
  *
- * You could find a link for the datasheet in Documentation/arm/sunxi/README
+ * You could find a link for the datasheet in Documentation/arm/sunxi.rst
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
diff --git a/drivers/crypto/sunxi-ss/sun4i-ss-hash.c b/drivers/crypto/sunxi-ss/sun4i-ss-hash.c
index a4b5ff2b72f8..f11149ccbe6c 100644
--- a/drivers/crypto/sunxi-ss/sun4i-ss-hash.c
+++ b/drivers/crypto/sunxi-ss/sun4i-ss-hash.c
@@ -5,7 +5,7 @@
  *
  * This file add support for MD5 and SHA1.
  *
- * You could find the datasheet in Documentation/arm/sunxi/README
+ * You could find the datasheet in Documentation/arm/sunxi.rst
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
diff --git a/drivers/crypto/sunxi-ss/sun4i-ss.h b/drivers/crypto/sunxi-ss/sun4i-ss.h
index f3ac90692ac6..4a1e90d437d5 100644
--- a/drivers/crypto/sunxi-ss/sun4i-ss.h
+++ b/drivers/crypto/sunxi-ss/sun4i-ss.h
@@ -7,7 +7,7 @@
  * Support MD5 and SHA1 hash algorithms.
  * Support DES and 3DES
  *
- * You could find the datasheet in Documentation/arm/sunxi/README
+ * You could find the datasheet in Documentation/arm/sunxi.rst
  *
  * Licensed under the GPL-2.
  */
diff --git a/drivers/input/touchscreen/sun4i-ts.c b/drivers/input/touchscreen/sun4i-ts.c
index d2e14d9e5975..d238fea3d6c4 100644
--- a/drivers/input/touchscreen/sun4i-ts.c
+++ b/drivers/input/touchscreen/sun4i-ts.c
@@ -31,7 +31,7 @@
  * in the kernel). So this driver offers straight forward, reliable single
  * touch functionality only.
  *
- * s.a. A20 User Manual "1.15 TP" (Documentation/arm/sunxi/README)
+ * s.a. A20 User Manual "1.15 TP" (Documentation/arm/sunxi.rst)
  * (looks like the description in the A20 User Manual v1.3 is better
  * than the one in the A10 User Manual v.1.5)
  */
diff --git a/drivers/tty/serial/Kconfig b/drivers/tty/serial/Kconfig
index a5032e58c737..f9af05bcce21 100644
--- a/drivers/tty/serial/Kconfig
+++ b/drivers/tty/serial/Kconfig
@@ -515,7 +515,7 @@ config SERIAL_SA1100
 	help
 	  If you have a machine based on a SA1100/SA1110 StrongARM(R) CPU you
 	  can enable its onboard serial port by enabling this option.
-	  Please read <file:Documentation/arm/SA1100/serial_UART> for further
+	  Please read <file:Documentation/arm/sa1100/serial_uart.rst> for further
 	  info.
 
 config SERIAL_SA1100_CONSOLE
-- 
2.20.1

[PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mauro Carvalho Chehab]

Those files are actually at ReST format. Ok, currently, they
don't belong to any place yet at the organized book series,
but we don't want patches to break them as ReST files. So,
rename them and add a :orphan: in order to shut up warning
messages like those:

...
    Documentation/svga.rst: WARNING: document isn't included in any toctree
    Documentation/switchtec.rst: WARNING: document isn't included in any toctree
...

Later patches will move them to a better place and remove the
:orphan: markup.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/ABI/removed/sysfs-class-rfkill  |  2 +-
 Documentation/ABI/stable/sysfs-class-rfkill   |  2 +-
 Documentation/ABI/stable/sysfs-devices-node   |  2 +-
 Documentation/ABI/testing/procfs-diskstats    |  2 +-
 Documentation/ABI/testing/sysfs-block         |  2 +-
 .../ABI/testing/sysfs-class-switchtec         |  2 +-
 .../ABI/testing/sysfs-devices-system-cpu      |  4 +-
 .../{DMA-API-HOWTO.txt => DMA-API-HOWTO.rst}  |  2 +
 Documentation/{DMA-API.txt => DMA-API.rst}    |  8 ++-
 .../{DMA-ISA-LPC.txt => DMA-ISA-LPC.rst}      |  4 +-
 ...{DMA-attributes.txt => DMA-attributes.rst} |  2 +
 Documentation/{IPMI.txt => IPMI.rst}          |  2 +
 .../{IRQ-affinity.txt => IRQ-affinity.rst}    |  2 +
 .../{IRQ-domain.txt => IRQ-domain.rst}        |  2 +
 Documentation/{IRQ.txt => IRQ.rst}            |  2 +
 .../{Intel-IOMMU.txt => Intel-IOMMU.rst}      |  2 +
 Documentation/PCI/pci.txt                     |  8 +--
 Documentation/{SAK.txt => SAK.rst}            |  2 +
 Documentation/{SM501.txt => SM501.rst}        |  2 +
 .../admin-guide/kernel-parameters.txt         |  6 +-
 Documentation/admin-guide/l1tf.rst            |  2 +-
 .../{atomic_bitops.txt => atomic_bitops.rst}  |  2 +
 Documentation/block/biodoc.txt                |  2 +-
 .../{bt8xxgpio.txt => bt8xxgpio.rst}          |  2 +
 Documentation/{btmrvl.txt => btmrvl.rst}      |  2 +
 ...-mapping.txt => bus-virt-phys-mapping.rst} |  4 +-
 ...g-warn-once.txt => clearing-warn-once.rst} |  2 +
 Documentation/{cpu-load.txt => cpu-load.rst}  |  2 +
 .../{cputopology.txt => cputopology.rst}      |  2 +
 Documentation/{crc32.txt => crc32.rst}        |  2 +
 Documentation/{dcdbas.txt => dcdbas.rst}      |  2 +
 ...ging-modules.txt => debugging-modules.rst} |  2 +
 ...hci1394.txt => debugging-via-ohci1394.rst} |  2 +
 Documentation/{dell_rbu.txt => dell_rbu.rst}  |  2 +
 Documentation/device-mapper/statistics.rst    |  4 +-
 .../devicetree/bindings/phy/phy-bindings.txt  |  2 +-
 Documentation/{digsig.txt => digsig.rst}      |  2 +
 Documentation/driver-api/usb/dma.rst          |  6 +-
 Documentation/driver-model/device.rst         |  2 +-
 Documentation/{efi-stub.txt => efi-stub.rst}  |  2 +
 Documentation/{eisa.txt => eisa.rst}          |  2 +
 Documentation/fb/vesafb.rst                   |  2 +-
 Documentation/filesystems/sysfs.txt           |  2 +-
 ...ex-requeue-pi.txt => futex-requeue-pi.rst} |  2 +
 .../{gcc-plugins.txt => gcc-plugins.rst}      |  2 +
 Documentation/gpu/drm-mm.rst                  |  2 +-
 Documentation/{highuid.txt => highuid.rst}    |  2 +
 .../{hw_random.txt => hw_random.rst}          |  2 +
 .../{hwspinlock.txt => hwspinlock.rst}        |  2 +
 Documentation/ia64/IRQ-redir.txt              |  2 +-
 .../{intel_txt.txt => intel_txt.rst}          |  2 +
 .../{io-mapping.txt => io-mapping.rst}        |  2 +
 .../{io_ordering.txt => io_ordering.rst}      |  2 +
 Documentation/{iostats.txt => iostats.rst}    |  2 +
 ...flags-tracing.txt => irqflags-tracing.rst} |  2 +
 Documentation/{isa.txt => isa.rst}            |  2 +
 Documentation/{isapnp.txt => isapnp.rst}      |  2 +
 ...hreads.txt => kernel-per-CPU-kthreads.rst} |  4 +-
 Documentation/{kobject.txt => kobject.rst}    |  4 +-
 Documentation/{kprobes.txt => kprobes.rst}    |  2 +
 Documentation/{kref.txt => kref.rst}          |  2 +
 Documentation/laptops/thinkpad-acpi.txt       |  6 +-
 Documentation/{ldm.txt => ldm.rst}            |  2 +
 Documentation/locking/rt-mutex.rst            |  2 +-
 ...kup-watchdogs.txt => lockup-watchdogs.rst} |  2 +
 Documentation/{lsm.txt => lsm.rst}            |  2 +
 Documentation/{lzo.txt => lzo.rst}            |  2 +
 Documentation/{mailbox.txt => mailbox.rst}    |  2 +
 Documentation/memory-barriers.txt             |  6 +-
 ...hameleon-bus.txt => men-chameleon-bus.rst} |  2 +
 Documentation/networking/scaling.rst          |  4 +-
 .../{nommu-mmap.txt => nommu-mmap.rst}        |  2 +
 Documentation/{ntb.txt => ntb.rst}            |  2 +
 Documentation/{numastat.txt => numastat.rst}  |  2 +
 Documentation/{padata.txt => padata.rst}      |  2 +
 ...port-lowlevel.txt => parport-lowlevel.rst} |  2 +
 ...-semaphore.txt => percpu-rw-semaphore.rst} |  2 +
 Documentation/{phy.txt => phy.rst}            |  2 +
 Documentation/{pi-futex.txt => pi-futex.rst}  |  2 +
 Documentation/{pnp.txt => pnp.rst}            |  2 +
 ...reempt-locking.txt => preempt-locking.rst} |  2 +
 Documentation/{pwm.txt => pwm.rst}            |  2 +
 Documentation/{rbtree.txt => rbtree.rst}      |  2 +
 .../{remoteproc.txt => remoteproc.rst}        |  4 +-
 Documentation/{rfkill.txt => rfkill.rst}      |  2 +
 ...ust-futex-ABI.txt => robust-futex-ABI.rst} |  2 +
 ...{robust-futexes.txt => robust-futexes.rst} |  2 +
 Documentation/{rpmsg.txt => rpmsg.rst}        |  2 +
 Documentation/{rtc.txt => rtc.rst}            |  2 +
 Documentation/s390/vfio-ccw.rst               |  6 +-
 Documentation/{sgi-ioc4.txt => sgi-ioc4.rst}  |  2 +
 Documentation/{siphash.txt => siphash.rst}    |  2 +
 .../{smsc_ece1099.txt => smsc_ece1099.rst}    |  2 +
 .../{speculation.txt => speculation.rst}      |  2 +
 .../{static-keys.txt => static-keys.rst}      |  2 +
 Documentation/{svga.txt => svga.rst}          |  2 +
 .../{switchtec.txt => switchtec.rst}          |  4 +-
 .../{sync_file.txt => sync_file.rst}          |  2 +
 Documentation/sysctl/kernel.txt               |  4 +-
 Documentation/sysctl/vm.txt                   |  2 +-
 Documentation/{tee.txt => tee.rst}            |  2 +
 .../{this_cpu_ops.txt => this_cpu_ops.rst}    |  2 +
 Documentation/trace/kprobetrace.rst           |  2 +-
 .../translations/ko_KR/memory-barriers.txt    |  6 +-
 Documentation/translations/zh_CN/IRQ.txt      |  4 +-
 .../translations/zh_CN/filesystems/sysfs.txt  |  2 +-
 .../translations/zh_CN/io_ordering.txt        |  4 +-
 ...access.txt => unaligned-memory-access.rst} |  2 +
 ...ed-device.txt => vfio-mediated-device.rst} |  4 +-
 Documentation/{vfio.txt => vfio.rst}          |  2 +
 .../{video-output.txt => video-output.rst}    |  2 +
 Documentation/watchdog/hpwdt.rst              |  2 +-
 Documentation/x86/topology.txt                |  2 +-
 Documentation/{xillybus.txt => xillybus.rst}  |  2 +
 Documentation/{xz.txt => xz.rst}              |  2 +
 Documentation/{zorro.txt => zorro.rst}        |  2 +
 MAINTAINERS                                   | 56 +++++++++----------
 arch/Kconfig                                  |  4 +-
 arch/arm/Kconfig                              |  4 +-
 arch/ia64/hp/common/sba_iommu.c               | 12 ++--
 arch/ia64/sn/pci/pci_dma.c                    |  4 +-
 arch/parisc/Kconfig                           |  2 +-
 arch/parisc/kernel/pci-dma.c                  |  2 +-
 arch/sh/Kconfig                               |  2 +-
 arch/sparc/Kconfig                            |  2 +-
 arch/unicore32/include/asm/io.h               |  2 +-
 arch/x86/Kconfig                              |  4 +-
 arch/x86/include/asm/dma-mapping.h            |  4 +-
 arch/x86/kernel/amd_gart_64.c                 |  2 +-
 block/partitions/Kconfig                      |  2 +-
 drivers/base/core.c                           |  2 +-
 drivers/char/Kconfig                          |  4 +-
 drivers/char/hw_random/core.c                 |  2 +-
 drivers/char/ipmi/Kconfig                     |  2 +-
 drivers/char/ipmi/ipmi_si_hotmod.c            |  2 +-
 drivers/char/ipmi/ipmi_si_intf.c              |  2 +-
 drivers/dma-buf/Kconfig                       |  2 +-
 drivers/gpio/Kconfig                          |  2 +-
 drivers/parisc/sba_iommu.c                    | 16 +++---
 drivers/pci/switch/Kconfig                    |  2 +-
 drivers/platform/x86/Kconfig                  |  4 +-
 drivers/platform/x86/dcdbas.c                 |  2 +-
 drivers/platform/x86/dell_rbu.c               |  2 +-
 drivers/pnp/isapnp/Kconfig                    |  2 +-
 drivers/vfio/Kconfig                          |  2 +-
 drivers/vfio/mdev/Kconfig                     |  2 +-
 include/asm-generic/bitops/atomic.h           |  2 +-
 include/linux/dma-mapping.h                   |  2 +-
 include/linux/hw_random.h                     |  2 +-
 include/linux/io-mapping.h                    |  2 +-
 include/linux/jump_label.h                    |  2 +-
 include/linux/kobject.h                       |  2 +-
 include/linux/kobject_ns.h                    |  2 +-
 include/linux/rbtree.h                        |  2 +-
 include/linux/rbtree_augmented.h              |  2 +-
 include/media/videobuf-dma-sg.h               |  2 +-
 init/Kconfig                                  |  2 +-
 kernel/dma/debug.c                            |  2 +-
 kernel/padata.c                               |  2 +-
 lib/Kconfig                                   |  2 +-
 lib/Kconfig.debug                             |  2 +-
 lib/crc32.c                                   |  2 +-
 lib/kobject.c                                 |  4 +-
 lib/lzo/lzo1x_decompress_safe.c               |  2 +-
 lib/xz/Kconfig                                |  2 +-
 mm/Kconfig                                    |  2 +-
 mm/nommu.c                                    |  2 +-
 samples/kprobes/kprobe_example.c              |  2 +-
 samples/kprobes/kretprobe_example.c           |  2 +-
 scripts/gcc-plugins/Kconfig                   |  2 +-
 security/Kconfig                              |  2 +-
 tools/include/linux/rbtree.h                  |  2 +-
 tools/include/linux/rbtree_augmented.h        |  2 +-
 173 files changed, 334 insertions(+), 168 deletions(-)
 rename Documentation/{DMA-API-HOWTO.txt => DMA-API-HOWTO.rst} (99%)
 rename Documentation/{DMA-API.txt => DMA-API.rst} (99%)
 rename Documentation/{DMA-ISA-LPC.txt => DMA-ISA-LPC.rst} (98%)
 rename Documentation/{DMA-attributes.txt => DMA-attributes.rst} (99%)
 rename Documentation/{IPMI.txt => IPMI.rst} (99%)
 rename Documentation/{IRQ-affinity.txt => IRQ-affinity.rst} (99%)
 rename Documentation/{IRQ-domain.txt => IRQ-domain.rst} (99%)
 rename Documentation/{IRQ.txt => IRQ.rst} (99%)
 rename Documentation/{Intel-IOMMU.txt => Intel-IOMMU.rst} (99%)
 rename Documentation/{SAK.txt => SAK.rst} (99%)
 rename Documentation/{SM501.txt => SM501.rst} (99%)
 rename Documentation/{atomic_bitops.txt => atomic_bitops.rst} (99%)
 rename Documentation/{bt8xxgpio.txt => bt8xxgpio.rst} (99%)
 rename Documentation/{btmrvl.txt => btmrvl.rst} (99%)
 rename Documentation/{bus-virt-phys-mapping.txt => bus-virt-phys-mapping.rst} (99%)
 rename Documentation/{clearing-warn-once.txt => clearing-warn-once.rst} (96%)
 rename Documentation/{cpu-load.txt => cpu-load.rst} (99%)
 rename Documentation/{cputopology.txt => cputopology.rst} (99%)
 rename Documentation/{crc32.txt => crc32.rst} (99%)
 rename Documentation/{dcdbas.txt => dcdbas.rst} (99%)
 rename Documentation/{debugging-modules.txt => debugging-modules.rst} (98%)
 rename Documentation/{debugging-via-ohci1394.txt => debugging-via-ohci1394.rst} (99%)
 rename Documentation/{dell_rbu.txt => dell_rbu.rst} (99%)
 rename Documentation/{digsig.txt => digsig.rst} (99%)
 rename Documentation/{efi-stub.txt => efi-stub.rst} (99%)
 rename Documentation/{eisa.txt => eisa.rst} (99%)
 rename Documentation/{futex-requeue-pi.txt => futex-requeue-pi.rst} (99%)
 rename Documentation/{gcc-plugins.txt => gcc-plugins.rst} (99%)
 rename Documentation/{highuid.txt => highuid.rst} (99%)
 rename Documentation/{hw_random.txt => hw_random.rst} (99%)
 rename Documentation/{hwspinlock.txt => hwspinlock.rst} (99%)
 rename Documentation/{intel_txt.txt => intel_txt.rst} (99%)
 rename Documentation/{io-mapping.txt => io-mapping.rst} (99%)
 rename Documentation/{io_ordering.txt => io_ordering.rst} (99%)
 rename Documentation/{iostats.txt => iostats.rst} (99%)
 rename Documentation/{irqflags-tracing.txt => irqflags-tracing.rst} (99%)
 rename Documentation/{isa.txt => isa.rst} (99%)
 rename Documentation/{isapnp.txt => isapnp.rst} (98%)
 rename Documentation/{kernel-per-CPU-kthreads.txt => kernel-per-CPU-kthreads.rst} (99%)
 rename Documentation/{kobject.txt => kobject.rst} (99%)
 rename Documentation/{kprobes.txt => kprobes.rst} (99%)
 rename Documentation/{kref.txt => kref.rst} (99%)
 rename Documentation/{ldm.txt => ldm.rst} (99%)
 rename Documentation/{lockup-watchdogs.txt => lockup-watchdogs.rst} (99%)
 rename Documentation/{lsm.txt => lsm.rst} (99%)
 rename Documentation/{lzo.txt => lzo.rst} (99%)
 rename Documentation/{mailbox.txt => mailbox.rst} (99%)
 rename Documentation/{men-chameleon-bus.txt => men-chameleon-bus.rst} (99%)
 rename Documentation/{nommu-mmap.txt => nommu-mmap.rst} (99%)
 rename Documentation/{ntb.txt => ntb.rst} (99%)
 rename Documentation/{numastat.txt => numastat.rst} (99%)
 rename Documentation/{padata.txt => padata.rst} (99%)
 rename Documentation/{parport-lowlevel.txt => parport-lowlevel.rst} (99%)
 rename Documentation/{percpu-rw-semaphore.txt => percpu-rw-semaphore.rst} (99%)
 rename Documentation/{phy.txt => phy.rst} (99%)
 rename Documentation/{pi-futex.txt => pi-futex.rst} (99%)
 rename Documentation/{pnp.txt => pnp.rst} (99%)
 rename Documentation/{preempt-locking.txt => preempt-locking.rst} (99%)
 rename Documentation/{pwm.txt => pwm.rst} (99%)
 rename Documentation/{rbtree.txt => rbtree.rst} (99%)
 rename Documentation/{remoteproc.txt => remoteproc.rst} (99%)
 rename Documentation/{rfkill.txt => rfkill.rst} (99%)
 rename Documentation/{robust-futex-ABI.txt => robust-futex-ABI.rst} (99%)
 rename Documentation/{robust-futexes.txt => robust-futexes.rst} (99%)
 rename Documentation/{rpmsg.txt => rpmsg.rst} (99%)
 rename Documentation/{rtc.txt => rtc.rst} (99%)
 rename Documentation/{sgi-ioc4.txt => sgi-ioc4.rst} (99%)
 rename Documentation/{siphash.txt => siphash.rst} (99%)
 rename Documentation/{smsc_ece1099.txt => smsc_ece1099.rst} (99%)
 rename Documentation/{speculation.txt => speculation.rst} (99%)
 rename Documentation/{static-keys.txt => static-keys.rst} (99%)
 rename Documentation/{svga.txt => svga.rst} (99%)
 rename Documentation/{switchtec.txt => switchtec.rst} (98%)
 rename Documentation/{sync_file.txt => sync_file.rst} (99%)
 rename Documentation/{tee.txt => tee.rst} (99%)
 rename Documentation/{this_cpu_ops.txt => this_cpu_ops.rst} (99%)
 rename Documentation/{unaligned-memory-access.txt => unaligned-memory-access.rst} (99%)
 rename Documentation/{vfio-mediated-device.txt => vfio-mediated-device.rst} (99%)
 rename Documentation/{vfio.txt => vfio.rst} (99%)
 rename Documentation/{video-output.txt => video-output.rst} (99%)
 rename Documentation/{xillybus.txt => xillybus.rst} (99%)
 rename Documentation/{xz.txt => xz.rst} (99%)
 rename Documentation/{zorro.txt => zorro.rst} (99%)

diff --git a/Documentation/ABI/removed/sysfs-class-rfkill b/Documentation/ABI/removed/sysfs-class-rfkill
index 3ce6231f20b2..1652b2381dda 100644
--- a/Documentation/ABI/removed/sysfs-class-rfkill
+++ b/Documentation/ABI/removed/sysfs-class-rfkill
@@ -1,6 +1,6 @@
 rfkill - radio frequency (RF) connector kill switch support
 
-For details to this subsystem look at Documentation/rfkill.txt.
+For details to this subsystem look at Documentation/rfkill.rst.
 
 What:		/sys/class/rfkill/rfkill[0-9]+/claim
 Date:		09-Jul-2007
diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill
index 80151a409d67..68fd0afdad0d 100644
--- a/Documentation/ABI/stable/sysfs-class-rfkill
+++ b/Documentation/ABI/stable/sysfs-class-rfkill
@@ -1,6 +1,6 @@
 rfkill - radio frequency (RF) connector kill switch support
 
-For details to this subsystem look at Documentation/rfkill.txt.
+For details to this subsystem look at Documentation/rfkill.rst.
 
 For the deprecated /sys/class/rfkill/*/claim knobs of this interface look in
 Documentation/ABI/removed/sysfs-class-rfkill.
diff --git a/Documentation/ABI/stable/sysfs-devices-node b/Documentation/ABI/stable/sysfs-devices-node
index f7ce68fbd4b9..de1d022c0864 100644
--- a/Documentation/ABI/stable/sysfs-devices-node
+++ b/Documentation/ABI/stable/sysfs-devices-node
@@ -61,7 +61,7 @@ Date:		October 2002
 Contact:	Linux Memory Management list <linux-mm@kvack.org>
 Description:
 		The node's hit/miss statistics, in units of pages.
-		See Documentation/numastat.txt
+		See Documentation/numastat.rst
 
 What:		/sys/devices/system/node/nodeX/distance
 Date:		October 2002
diff --git a/Documentation/ABI/testing/procfs-diskstats b/Documentation/ABI/testing/procfs-diskstats
index abac31d216de..26661dd5188b 100644
--- a/Documentation/ABI/testing/procfs-diskstats
+++ b/Documentation/ABI/testing/procfs-diskstats
@@ -29,4 +29,4 @@ Description:
 		17 - sectors discarded
 		18 - time spent discarding
 
-		For more details refer to Documentation/iostats.txt
+		For more details refer to Documentation/iostats.rst
diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block
index dfad7427817c..d300a6b9d17c 100644
--- a/Documentation/ABI/testing/sysfs-block
+++ b/Documentation/ABI/testing/sysfs-block
@@ -15,7 +15,7 @@ Description:
 		 9 - I/Os currently in progress
 		10 - time spent doing I/Os (ms)
 		11 - weighted time spent doing I/Os (ms)
-		For more details refer Documentation/iostats.txt
+		For more details refer Documentation/iostats.rst
 
 
 What:		/sys/block/<disk>/<part>/stat
diff --git a/Documentation/ABI/testing/sysfs-class-switchtec b/Documentation/ABI/testing/sysfs-class-switchtec
index 48cb4c15e430..c8d80db1e32c 100644
--- a/Documentation/ABI/testing/sysfs-class-switchtec
+++ b/Documentation/ABI/testing/sysfs-class-switchtec
@@ -1,6 +1,6 @@
 switchtec - Microsemi Switchtec PCI Switch Management Endpoint
 
-For details on this subsystem look at Documentation/switchtec.txt.
+For details on this subsystem look at Documentation/switchtec.rst.
 
 What: 		/sys/class/switchtec
 Date:		05-Jan-2017
diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index 4fb76c0e8d30..4ee760342c62 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -34,7 +34,7 @@ Description:	CPU topology files that describe kernel limits related to
 		present: cpus that have been identified as being present in
 		the system.
 
-		See Documentation/cputopology.txt for more information.
+		See Documentation/cputopology.rst for more information.
 
 
 What:		/sys/devices/system/cpu/probe
@@ -103,7 +103,7 @@ Description:	CPU topology files that describe a logical CPU's relationship
 		thread_siblings_list: human-readable list of cpu#'s hardware
 		threads within the same core as cpu#
 
-		See Documentation/cputopology.txt for more information.
+		See Documentation/cputopology.rst for more information.
 
 
 What:		/sys/devices/system/cpu/cpuidle/current_driver
diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.rst
similarity index 99%
rename from Documentation/DMA-API-HOWTO.txt
rename to Documentation/DMA-API-HOWTO.rst
index cb712a02f59f..0b72bf9051ed 100644
--- a/Documentation/DMA-API-HOWTO.txt
+++ b/Documentation/DMA-API-HOWTO.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =========================
 Dynamic DMA mapping Guide
 =========================
diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.rst
similarity index 99%
rename from Documentation/DMA-API.txt
rename to Documentation/DMA-API.rst
index 0076150fdccb..ede74c6ae87d 100644
--- a/Documentation/DMA-API.txt
+++ b/Documentation/DMA-API.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ============================================
 Dynamic DMA mapping using the generic device
 ============================================
@@ -5,7 +7,7 @@ Dynamic DMA mapping using the generic device
 :Author: James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
 
 This document describes the DMA API.  For a more gentle introduction
-of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt.
+of the API (and actual examples), see Documentation/DMA-API-HOWTO.rst.
 
 This API is split into two pieces.  Part I describes the basic API.
 Part II describes extensions for supporting non-consistent memory
@@ -463,7 +465,7 @@ without the _attrs suffixes, except that they pass an optional
 dma_attrs.
 
 The interpretation of DMA attributes is architecture-specific, and
-each attribute should be documented in Documentation/DMA-attributes.txt.
+each attribute should be documented in Documentation/DMA-attributes.rst.
 
 If dma_attrs are 0, the semantics of each of these functions
 is identical to those of the corresponding function
@@ -476,7 +478,7 @@ for DMA::
 
 	#include <linux/dma-mapping.h>
 	/* DMA_ATTR_FOO should be defined in linux/dma-mapping.h and
-	* documented in Documentation/DMA-attributes.txt */
+	* documented in Documentation/DMA-attributes.rst */
 	...
 
 		unsigned long attr;
diff --git a/Documentation/DMA-ISA-LPC.txt b/Documentation/DMA-ISA-LPC.rst
similarity index 98%
rename from Documentation/DMA-ISA-LPC.txt
rename to Documentation/DMA-ISA-LPC.rst
index b1ec7b16c21f..205a379c2d62 100644
--- a/Documentation/DMA-ISA-LPC.txt
+++ b/Documentation/DMA-ISA-LPC.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ============================
 DMA with ISA and LPC devices
 ============================
@@ -17,7 +19,7 @@ To do ISA style DMA you need to include two headers::
 	#include <asm/dma.h>
 
 The first is the generic DMA API used to convert virtual addresses to
-bus addresses (see Documentation/DMA-API.txt for details).
+bus addresses (see Documentation/DMA-API.rst for details).
 
 The second contains the routines specific to ISA DMA transfers. Since
 this is not present on all platforms make sure you construct your
diff --git a/Documentation/DMA-attributes.txt b/Documentation/DMA-attributes.rst
similarity index 99%
rename from Documentation/DMA-attributes.txt
rename to Documentation/DMA-attributes.rst
index 8f8d97f65d73..471c5c38f9d9 100644
--- a/Documentation/DMA-attributes.txt
+++ b/Documentation/DMA-attributes.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==============
 DMA attributes
 ==============
diff --git a/Documentation/IPMI.txt b/Documentation/IPMI.rst
similarity index 99%
rename from Documentation/IPMI.txt
rename to Documentation/IPMI.rst
index 5ef1047e2e66..f6c2d11710fe 100644
--- a/Documentation/IPMI.txt
+++ b/Documentation/IPMI.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =====================
 The Linux IPMI Driver
 =====================
diff --git a/Documentation/IRQ-affinity.txt b/Documentation/IRQ-affinity.rst
similarity index 99%
rename from Documentation/IRQ-affinity.txt
rename to Documentation/IRQ-affinity.rst
index 29da5000836a..49ba271349d6 100644
--- a/Documentation/IRQ-affinity.txt
+++ b/Documentation/IRQ-affinity.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ================
 SMP IRQ affinity
 ================
diff --git a/Documentation/IRQ-domain.txt b/Documentation/IRQ-domain.rst
similarity index 99%
rename from Documentation/IRQ-domain.txt
rename to Documentation/IRQ-domain.rst
index 507775cce753..a610a8ea9a92 100644
--- a/Documentation/IRQ-domain.txt
+++ b/Documentation/IRQ-domain.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===============================================
 The irq_domain interrupt number mapping library
 ===============================================
diff --git a/Documentation/IRQ.txt b/Documentation/IRQ.rst
similarity index 99%
rename from Documentation/IRQ.txt
rename to Documentation/IRQ.rst
index 4273806a606b..a9f3e192c2cb 100644
--- a/Documentation/IRQ.txt
+++ b/Documentation/IRQ.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===============
 What is an IRQ?
 ===============
diff --git a/Documentation/Intel-IOMMU.txt b/Documentation/Intel-IOMMU.rst
similarity index 99%
rename from Documentation/Intel-IOMMU.txt
rename to Documentation/Intel-IOMMU.rst
index 9dae6b47e398..b001104c25c8 100644
--- a/Documentation/Intel-IOMMU.txt
+++ b/Documentation/Intel-IOMMU.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===================
 Linux IOMMU Support
 ===================
diff --git a/Documentation/PCI/pci.txt b/Documentation/PCI/pci.txt
index bbbae19f10b0..8f0009b6ea1d 100644
--- a/Documentation/PCI/pci.txt
+++ b/Documentation/PCI/pci.txt
@@ -295,7 +295,7 @@ from the PCI device config space. Use the values in the pci_dev structure
 as the PCI "bus address" might have been remapped to a "host physical"
 address by the arch/chip-set specific kernel support.
 
-See Documentation/io-mapping.txt for how to access device registers
+See Documentation/io-mapping.rst for how to access device registers
 or device memory.
 
 The device driver needs to call pci_request_region() to verify
@@ -319,7 +319,7 @@ Also see pci_request_selected_regions() below.
 3.3 Set the DMA mask size
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 [ If anything below doesn't make sense, please refer to
-  Documentation/DMA-API.txt. This section is just a reminder that
+  Documentation/DMA-API.rst. This section is just a reminder that
   drivers need to indicate DMA capabilities of the device and is not
   an authoritative source for DMA interfaces. ]
 
@@ -345,7 +345,7 @@ Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
 3.4 Setup shared control data
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
-memory.  See Documentation/DMA-API.txt for a full description of
+memory.  See Documentation/DMA-API.rst for a full description of
 the DMA APIs. This section is just a reminder that it needs to be done
 before enabling DMA on the device.
 
@@ -475,7 +475,7 @@ owners if there is one.
 
 Then clean up "consistent" buffers which contain the control data.
 
-See Documentation/DMA-API.txt for details on unmapping interfaces.
+See Documentation/DMA-API.rst for details on unmapping interfaces.
 
 
 4.5 Unregister from other subsystems
diff --git a/Documentation/SAK.txt b/Documentation/SAK.rst
similarity index 99%
rename from Documentation/SAK.txt
rename to Documentation/SAK.rst
index 260e1d3687bd..c6fe715f5518 100644
--- a/Documentation/SAK.txt
+++ b/Documentation/SAK.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =========================================
 Linux Secure Attention Key (SAK) handling
 =========================================
diff --git a/Documentation/SM501.txt b/Documentation/SM501.rst
similarity index 99%
rename from Documentation/SM501.txt
rename to Documentation/SM501.rst
index 882507453ba4..772a9b5c7d49 100644
--- a/Documentation/SM501.txt
+++ b/Documentation/SM501.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. include:: <isonum.txt>
 
 ============
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 4a2260eac131..bf6d34fb7180 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -3077,7 +3077,7 @@
 			See Documentation/sysctl/vm.txt for details.
 
 	ohci1394_dma=early	[HW] enable debugging via the ohci1394 driver.
-			See Documentation/debugging-via-ohci1394.txt for more
+			See Documentation/debugging-via-ohci1394.rst for more
 			info.
 
 	olpc_ec_timeout= [OLPC] ms delay when issuing EC commands
@@ -4986,8 +4986,8 @@
 			Can be used multiple times for multiple devices.
 
 	vga=		[BOOT,X86-32] Select a particular video mode
-			See Documentation/x86/boot.txt and
-			Documentation/svga.txt.
+			See Documentation/x86/boot.rst and
+			Documentation/svga.rst.
 			Use vga=ask for menu.
 			This is actually a boot loader parameter; the value is
 			passed to the kernel using a special protocol.
diff --git a/Documentation/admin-guide/l1tf.rst b/Documentation/admin-guide/l1tf.rst
index f5b2a54a0dc2..ab162d65e178 100644
--- a/Documentation/admin-guide/l1tf.rst
+++ b/Documentation/admin-guide/l1tf.rst
@@ -268,7 +268,7 @@ Guest mitigation mechanisms
    /proc/irq/$NR/smp_affinity[_list] files. Limited documentation is
    available at:
 
-   https://www.kernel.org/doc/Documentation/IRQ-affinity.txt
+   https://www.kernel.org/doc/Documentation/IRQ-affinity.rst
 
 .. _smt_control:
 
diff --git a/Documentation/atomic_bitops.txt b/Documentation/atomic_bitops.rst
similarity index 99%
rename from Documentation/atomic_bitops.txt
rename to Documentation/atomic_bitops.rst
index 093cdaefdb37..ca90f2d16602 100644
--- a/Documentation/atomic_bitops.txt
+++ b/Documentation/atomic_bitops.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =============
 Atomic bitops
 =============
diff --git a/Documentation/block/biodoc.txt b/Documentation/block/biodoc.txt
index ac18b488cb5e..ac504de0cb93 100644
--- a/Documentation/block/biodoc.txt
+++ b/Documentation/block/biodoc.txt
@@ -184,7 +184,7 @@ a virtual address mapping (unlike the earlier scheme of virtual address
 do not have a corresponding kernel virtual address space mapping) and
 low-memory pages.
 
-Note: Please refer to Documentation/DMA-API-HOWTO.txt for a discussion
+Note: Please refer to Documentation/DMA-API-HOWTO.rst for a discussion
 on PCI high mem DMA aspects and mapping of scatter gather lists, and support
 for 64 bit PCI.
 
diff --git a/Documentation/bt8xxgpio.txt b/Documentation/bt8xxgpio.rst
similarity index 99%
rename from Documentation/bt8xxgpio.txt
rename to Documentation/bt8xxgpio.rst
index a845feb074de..efda63a77f18 100644
--- a/Documentation/bt8xxgpio.txt
+++ b/Documentation/bt8xxgpio.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===================================================================
 A driver for a selfmade cheap BT8xx based PCI GPIO-card (bt8xxgpio)
 ===================================================================
diff --git a/Documentation/btmrvl.txt b/Documentation/btmrvl.rst
similarity index 99%
rename from Documentation/btmrvl.txt
rename to Documentation/btmrvl.rst
index ec57740ead0c..e6dd1c96e842 100644
--- a/Documentation/btmrvl.txt
+++ b/Documentation/btmrvl.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =============
 btmrvl driver
 =============
diff --git a/Documentation/bus-virt-phys-mapping.txt b/Documentation/bus-virt-phys-mapping.rst
similarity index 99%
rename from Documentation/bus-virt-phys-mapping.txt
rename to Documentation/bus-virt-phys-mapping.rst
index 4bb07c2f3e7d..0f22390b980a 100644
--- a/Documentation/bus-virt-phys-mapping.txt
+++ b/Documentation/bus-virt-phys-mapping.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==========================================================
 How to access I/O mapped memory from within device drivers
 ==========================================================
@@ -8,7 +10,7 @@ How to access I/O mapped memory from within device drivers
 
 	The virt_to_bus() and bus_to_virt() functions have been
 	superseded by the functionality provided by the PCI DMA interface
-	(see Documentation/DMA-API-HOWTO.txt).  They continue
+	(see Documentation/DMA-API-HOWTO.rst).  They continue
 	to be documented below for historical purposes, but new code
 	must not use them. --davidm 00/12/12
 
diff --git a/Documentation/clearing-warn-once.txt b/Documentation/clearing-warn-once.rst
similarity index 96%
rename from Documentation/clearing-warn-once.txt
rename to Documentation/clearing-warn-once.rst
index 211fd926cf00..cdfa892c7fdf 100644
--- a/Documentation/clearing-warn-once.txt
+++ b/Documentation/clearing-warn-once.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Clearing WARN_ONCE
 ------------------
 
diff --git a/Documentation/cpu-load.txt b/Documentation/cpu-load.rst
similarity index 99%
rename from Documentation/cpu-load.txt
rename to Documentation/cpu-load.rst
index 2d01ce43d2a2..6b2815b78683 100644
--- a/Documentation/cpu-load.txt
+++ b/Documentation/cpu-load.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ========
 CPU load
 ========
diff --git a/Documentation/cputopology.txt b/Documentation/cputopology.rst
similarity index 99%
rename from Documentation/cputopology.txt
rename to Documentation/cputopology.rst
index c6e7e9196a8b..cce9cedd2996 100644
--- a/Documentation/cputopology.txt
+++ b/Documentation/cputopology.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========================================
 How CPU topology info is exported via sysfs
 ===========================================
diff --git a/Documentation/crc32.txt b/Documentation/crc32.rst
similarity index 99%
rename from Documentation/crc32.txt
rename to Documentation/crc32.rst
index 8a6860f33b4e..f7c73d713a35 100644
--- a/Documentation/crc32.txt
+++ b/Documentation/crc32.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =================================
 brief tutorial on CRC computation
 =================================
diff --git a/Documentation/dcdbas.txt b/Documentation/dcdbas.rst
similarity index 99%
rename from Documentation/dcdbas.txt
rename to Documentation/dcdbas.rst
index 309cc57a7c1c..abbc2bfd58a7 100644
--- a/Documentation/dcdbas.txt
+++ b/Documentation/dcdbas.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===================================
 Dell Systems Management Base Driver
 ===================================
diff --git a/Documentation/debugging-modules.txt b/Documentation/debugging-modules.rst
similarity index 98%
rename from Documentation/debugging-modules.txt
rename to Documentation/debugging-modules.rst
index 172ad4aec493..994f4b021a81 100644
--- a/Documentation/debugging-modules.txt
+++ b/Documentation/debugging-modules.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Debugging Modules after 2.6.3
 -----------------------------
 
diff --git a/Documentation/debugging-via-ohci1394.txt b/Documentation/debugging-via-ohci1394.rst
similarity index 99%
rename from Documentation/debugging-via-ohci1394.txt
rename to Documentation/debugging-via-ohci1394.rst
index 981ad4f89fd3..ead0196d94b7 100644
--- a/Documentation/debugging-via-ohci1394.txt
+++ b/Documentation/debugging-via-ohci1394.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========================================================================
 Using physical DMA provided by OHCI-1394 FireWire controllers for debugging
 ===========================================================================
diff --git a/Documentation/dell_rbu.txt b/Documentation/dell_rbu.rst
similarity index 99%
rename from Documentation/dell_rbu.txt
rename to Documentation/dell_rbu.rst
index 5d1ce7bcd04d..1104726616a1 100644
--- a/Documentation/dell_rbu.txt
+++ b/Documentation/dell_rbu.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =============================================================
 Usage of the new open sourced rbu (Remote BIOS Update) driver
 =============================================================
diff --git a/Documentation/device-mapper/statistics.rst b/Documentation/device-mapper/statistics.rst
index 3d80a9f850cc..39f74af35abb 100644
--- a/Documentation/device-mapper/statistics.rst
+++ b/Documentation/device-mapper/statistics.rst
@@ -13,7 +13,7 @@ the range specified.
 
 The I/O statistics counters for each step-sized area of a region are
 in the same format as `/sys/block/*/stat` or `/proc/diskstats` (see:
-Documentation/iostats.txt).  But two extra counters (12 and 13) are
+Documentation/iostats.rst).  But two extra counters (12 and 13) are
 provided: total time spent reading and writing.  When the histogram
 argument is used, the 14th parameter is reported that represents the
 histogram of latencies.  All these counters may be accessed by sending
@@ -151,7 +151,7 @@ Messages
 	  The first 11 counters have the same meaning as
 	  `/sys/block/*/stat or /proc/diskstats`.
 
-	  Please refer to Documentation/iostats.txt for details.
+	  Please refer to Documentation/iostats.rst for details.
 
 	  1. the number of reads completed
 	  2. the number of reads merged
diff --git a/Documentation/devicetree/bindings/phy/phy-bindings.txt b/Documentation/devicetree/bindings/phy/phy-bindings.txt
index a403b81d0679..5e2a53bcba0e 100644
--- a/Documentation/devicetree/bindings/phy/phy-bindings.txt
+++ b/Documentation/devicetree/bindings/phy/phy-bindings.txt
@@ -1,5 +1,5 @@
 This document explains only the device tree data binding. For general
-information about PHY subsystem refer to Documentation/phy.txt
+information about PHY subsystem refer to Documentation/phy.rst
 
 PHY device node
 ===============
diff --git a/Documentation/digsig.txt b/Documentation/digsig.rst
similarity index 99%
rename from Documentation/digsig.txt
rename to Documentation/digsig.rst
index f6a8902d3ef7..3597711d0df1 100644
--- a/Documentation/digsig.txt
+++ b/Documentation/digsig.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==================================
 Digital Signature Verification API
 ==================================
diff --git a/Documentation/driver-api/usb/dma.rst b/Documentation/driver-api/usb/dma.rst
index 59d5aee89e37..12955a77c7fe 100644
--- a/Documentation/driver-api/usb/dma.rst
+++ b/Documentation/driver-api/usb/dma.rst
@@ -10,7 +10,7 @@ API overview
 
 The big picture is that USB drivers can continue to ignore most DMA issues,
 though they still must provide DMA-ready buffers (see
-``Documentation/DMA-API-HOWTO.txt``).  That's how they've worked through
+``Documentation/DMA-API-HOWTO.rst``).  That's how they've worked through
 the 2.4 (and earlier) kernels, or they can now be DMA-aware.
 
 DMA-aware usb drivers:
@@ -60,7 +60,7 @@ and effects like cache-trashing can impose subtle penalties.
   force a consistent memory access ordering by using memory barriers.  It's
   not using a streaming DMA mapping, so it's good for small transfers on
   systems where the I/O would otherwise thrash an IOMMU mapping.  (See
-  ``Documentation/DMA-API-HOWTO.txt`` for definitions of "coherent" and
+  ``Documentation/DMA-API-HOWTO.rst`` for definitions of "coherent" and
   "streaming" DMA mappings.)
 
   Asking for 1/Nth of a page (as well as asking for N pages) is reasonably
@@ -91,7 +91,7 @@ Working with existing buffers
 Existing buffers aren't usable for DMA without first being mapped into the
 DMA address space of the device.  However, most buffers passed to your
 driver can safely be used with such DMA mapping.  (See the first section
-of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?")
+of Documentation/DMA-API-HOWTO.rst, titled "What memory is DMA-able?")
 
 - When you're using scatterlists, you can map everything at once.  On some
   systems, this kicks in an IOMMU and turns the scatterlists into single
diff --git a/Documentation/driver-model/device.rst b/Documentation/driver-model/device.rst
index 2b868d49d349..17bcc483c4b1 100644
--- a/Documentation/driver-model/device.rst
+++ b/Documentation/driver-model/device.rst
@@ -53,7 +53,7 @@ Attributes of devices can be exported by a device driver through sysfs.
 Please see Documentation/filesystems/sysfs.txt for more information
 on how sysfs works.
 
-As explained in Documentation/kobject.txt, device attributes must be
+As explained in Documentation/kobject.rst, device attributes must be
 created before the KOBJ_ADD uevent is generated. The only way to realize
 that is by defining an attribute group.
 
diff --git a/Documentation/efi-stub.txt b/Documentation/efi-stub.rst
similarity index 99%
rename from Documentation/efi-stub.txt
rename to Documentation/efi-stub.rst
index 833edb0d0bc4..29256cad8af3 100644
--- a/Documentation/efi-stub.txt
+++ b/Documentation/efi-stub.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =================
 The EFI Boot Stub
 =================
diff --git a/Documentation/eisa.txt b/Documentation/eisa.rst
similarity index 99%
rename from Documentation/eisa.txt
rename to Documentation/eisa.rst
index f388545a85a7..d98949908405 100644
--- a/Documentation/eisa.txt
+++ b/Documentation/eisa.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ================
 EISA bus support
 ================
diff --git a/Documentation/fb/vesafb.rst b/Documentation/fb/vesafb.rst
index 2ed0dfb661cf..a0b658091b07 100644
--- a/Documentation/fb/vesafb.rst
+++ b/Documentation/fb/vesafb.rst
@@ -30,7 +30,7 @@ How to use it?
 ==============
 
 Switching modes is done using the vga=... boot parameter.  Read
-Documentation/svga.txt for details.
+Documentation/svga.rst for details.
 
 You should compile in both vgacon (for text mode) and vesafb (for
 graphics mode). Which of them takes over the console depends on
diff --git a/Documentation/filesystems/sysfs.txt b/Documentation/filesystems/sysfs.txt
index 5b5311f9358d..d159826c5cf3 100644
--- a/Documentation/filesystems/sysfs.txt
+++ b/Documentation/filesystems/sysfs.txt
@@ -16,7 +16,7 @@ a means to export kernel data structures, their attributes, and the
 linkages between them to userspace. 
 
 sysfs is tied inherently to the kobject infrastructure. Please read
-Documentation/kobject.txt for more information concerning the kobject
+Documentation/kobject.rst for more information concerning the kobject
 interface. 
 
 
diff --git a/Documentation/futex-requeue-pi.txt b/Documentation/futex-requeue-pi.rst
similarity index 99%
rename from Documentation/futex-requeue-pi.txt
rename to Documentation/futex-requeue-pi.rst
index 14ab5787b9a7..a90dbff26629 100644
--- a/Documentation/futex-requeue-pi.txt
+++ b/Documentation/futex-requeue-pi.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ================
 Futex Requeue PI
 ================
diff --git a/Documentation/gcc-plugins.txt b/Documentation/gcc-plugins.rst
similarity index 99%
rename from Documentation/gcc-plugins.txt
rename to Documentation/gcc-plugins.rst
index 8502f24396fb..e08d013c6de2 100644
--- a/Documentation/gcc-plugins.txt
+++ b/Documentation/gcc-plugins.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =========================
 GCC plugin infrastructure
 =========================
diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
index 54a696d961a7..adadaf796dce 100644
--- a/Documentation/gpu/drm-mm.rst
+++ b/Documentation/gpu/drm-mm.rst
@@ -321,7 +321,7 @@ struct :c:type:`struct file_operations <file_operations>` get_unmapped_area
 field with a pointer on :c:func:`drm_gem_cma_get_unmapped_area`.
 
 More detailed information about get_unmapped_area can be found in
-Documentation/nommu-mmap.txt
+Documentation/nommu-mmap.rst
 
 Memory Coherency
 ----------------
diff --git a/Documentation/highuid.txt b/Documentation/highuid.rst
similarity index 99%
rename from Documentation/highuid.txt
rename to Documentation/highuid.rst
index 6ee70465c0ea..f2fcf729f64c 100644
--- a/Documentation/highuid.txt
+++ b/Documentation/highuid.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===================================================
 Notes on the change from 16-bit UIDs to 32-bit UIDs
 ===================================================
diff --git a/Documentation/hw_random.txt b/Documentation/hw_random.rst
similarity index 99%
rename from Documentation/hw_random.txt
rename to Documentation/hw_random.rst
index 121de96e395e..fb5e32fae384 100644
--- a/Documentation/hw_random.txt
+++ b/Documentation/hw_random.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==========================================================
 Linux support for random number generator in i8xx chipsets
 ==========================================================
diff --git a/Documentation/hwspinlock.txt b/Documentation/hwspinlock.rst
similarity index 99%
rename from Documentation/hwspinlock.txt
rename to Documentation/hwspinlock.rst
index ed640a278185..68297473647c 100644
--- a/Documentation/hwspinlock.txt
+++ b/Documentation/hwspinlock.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========================
 Hardware Spinlock Framework
 ===========================
diff --git a/Documentation/ia64/IRQ-redir.txt b/Documentation/ia64/IRQ-redir.txt
index f7bd72261283..364ce9879f54 100644
--- a/Documentation/ia64/IRQ-redir.txt
+++ b/Documentation/ia64/IRQ-redir.txt
@@ -5,7 +5,7 @@ IRQ affinity on IA64 platforms
 
 By writing to /proc/irq/IRQ#/smp_affinity the interrupt routing can be
 controlled. The behavior on IA64 platforms is slightly different from
-that described in Documentation/IRQ-affinity.txt for i386 systems.
+that described in Documentation/IRQ-affinity.rst for i386 systems.
 
 Because of the usage of SAPIC mode and physical destination mode the
 IRQ target is one particular CPU and cannot be a mask of several
diff --git a/Documentation/intel_txt.txt b/Documentation/intel_txt.rst
similarity index 99%
rename from Documentation/intel_txt.txt
rename to Documentation/intel_txt.rst
index d83c1a2122c9..5a55007ecf08 100644
--- a/Documentation/intel_txt.txt
+++ b/Documentation/intel_txt.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =====================
 Intel(R) TXT Overview
 =====================
diff --git a/Documentation/io-mapping.txt b/Documentation/io-mapping.rst
similarity index 99%
rename from Documentation/io-mapping.txt
rename to Documentation/io-mapping.rst
index a966239f04e4..82a2cacf9a29 100644
--- a/Documentation/io-mapping.txt
+++ b/Documentation/io-mapping.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ========================
 The io_mapping functions
 ========================
diff --git a/Documentation/io_ordering.txt b/Documentation/io_ordering.rst
similarity index 99%
rename from Documentation/io_ordering.txt
rename to Documentation/io_ordering.rst
index 2ab303ce9a0d..18ef889c100e 100644
--- a/Documentation/io_ordering.txt
+++ b/Documentation/io_ordering.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==============================================
 Ordering I/O writes to memory-mapped addresses
 ==============================================
diff --git a/Documentation/iostats.txt b/Documentation/iostats.rst
similarity index 99%
rename from Documentation/iostats.txt
rename to Documentation/iostats.rst
index 49df45f90e8a..d2489cb8e1b3 100644
--- a/Documentation/iostats.txt
+++ b/Documentation/iostats.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =====================
 I/O statistics fields
 =====================
diff --git a/Documentation/irqflags-tracing.txt b/Documentation/irqflags-tracing.rst
similarity index 99%
rename from Documentation/irqflags-tracing.txt
rename to Documentation/irqflags-tracing.rst
index bdd208259fb3..b9c2acd5e835 100644
--- a/Documentation/irqflags-tracing.txt
+++ b/Documentation/irqflags-tracing.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =======================
 IRQ-flags state tracing
 =======================
diff --git a/Documentation/isa.txt b/Documentation/isa.rst
similarity index 99%
rename from Documentation/isa.txt
rename to Documentation/isa.rst
index def4a7b690b5..f3a412d266b0 100644
--- a/Documentation/isa.txt
+++ b/Documentation/isa.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========
 ISA Drivers
 ===========
diff --git a/Documentation/isapnp.txt b/Documentation/isapnp.rst
similarity index 98%
rename from Documentation/isapnp.txt
rename to Documentation/isapnp.rst
index 8d0840ac847b..136a5e92be27 100644
--- a/Documentation/isapnp.txt
+++ b/Documentation/isapnp.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==========================================================
 ISA Plug & Play support by Jaroslav Kysela <perex@suse.cz>
 ==========================================================
diff --git a/Documentation/kernel-per-CPU-kthreads.txt b/Documentation/kernel-per-CPU-kthreads.rst
similarity index 99%
rename from Documentation/kernel-per-CPU-kthreads.txt
rename to Documentation/kernel-per-CPU-kthreads.rst
index 5623b9916411..765c7b9bd7fd 100644
--- a/Documentation/kernel-per-CPU-kthreads.txt
+++ b/Documentation/kernel-per-CPU-kthreads.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==========================================
 Reducing OS jitter due to per-cpu kthreads
 ==========================================
@@ -10,7 +12,7 @@ them to a "housekeeping" CPU dedicated to such work.
 References
 ==========
 
--	Documentation/IRQ-affinity.txt:  Binding interrupts to sets of CPUs.
+-	Documentation/IRQ-affinity.rst:  Binding interrupts to sets of CPUs.
 
 -	Documentation/cgroup-v1:  Using cgroups to bind tasks to sets of CPUs.
 
diff --git a/Documentation/kobject.txt b/Documentation/kobject.rst
similarity index 99%
rename from Documentation/kobject.txt
rename to Documentation/kobject.rst
index ff4c25098119..09cd1fc3e9e0 100644
--- a/Documentation/kobject.txt
+++ b/Documentation/kobject.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =====================================================================
 Everything you never wanted to know about kobjects, ksets, and ktypes
 =====================================================================
@@ -210,7 +212,7 @@ statically and will warn the developer of this improper usage.
 If all that you want to use a kobject for is to provide a reference counter
 for your structure, please use the struct kref instead; a kobject would be
 overkill.  For more information on how to use struct kref, please see the
-file Documentation/kref.txt in the Linux kernel source tree.
+file Documentation/kref.rst in the Linux kernel source tree.
 
 
 Creating "simple" kobjects
diff --git a/Documentation/kprobes.txt b/Documentation/kprobes.rst
similarity index 99%
rename from Documentation/kprobes.txt
rename to Documentation/kprobes.rst
index 8baab8832c5b..ba15bd08a84a 100644
--- a/Documentation/kprobes.txt
+++ b/Documentation/kprobes.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =======================
 Kernel Probes (Kprobes)
 =======================
diff --git a/Documentation/kref.txt b/Documentation/kref.rst
similarity index 99%
rename from Documentation/kref.txt
rename to Documentation/kref.rst
index 3af384156d7e..470e3c1bacdc 100644
--- a/Documentation/kref.txt
+++ b/Documentation/kref.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===================================================
 Adding reference counters (krefs) to kernel objects
 ===================================================
diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/laptops/thinkpad-acpi.txt
index 6cced88de6da..3de3c95f01f6 100644
--- a/Documentation/laptops/thinkpad-acpi.txt
+++ b/Documentation/laptops/thinkpad-acpi.txt
@@ -610,7 +610,7 @@ Sysfs notes:
 	2010.
 
 	rfkill controller switch "tpacpi_bluetooth_sw": refer to
-	Documentation/rfkill.txt for details.
+	Documentation/rfkill.rst for details.
 
 
 Video output control -- /proc/acpi/ibm/video
@@ -1338,7 +1338,7 @@ Sysfs notes:
 	2010.
 
 	rfkill controller switch "tpacpi_wwan_sw": refer to
-	Documentation/rfkill.txt for details.
+	Documentation/rfkill.rst for details.
 
 
 EXPERIMENTAL: UWB
@@ -1357,7 +1357,7 @@ present and enabled in the BIOS.
 Sysfs notes:
 
 	rfkill controller switch "tpacpi_uwb_sw": refer to
-	Documentation/rfkill.txt for details.
+	Documentation/rfkill.rst for details.
 
 Adaptive keyboard
 -----------------
diff --git a/Documentation/ldm.txt b/Documentation/ldm.rst
similarity index 99%
rename from Documentation/ldm.txt
rename to Documentation/ldm.rst
index 12c571368e73..33fa13db5f67 100644
--- a/Documentation/ldm.txt
+++ b/Documentation/ldm.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==========================================
 LDM - Logical Disk Manager (Dynamic Disks)
 ==========================================
diff --git a/Documentation/locking/rt-mutex.rst b/Documentation/locking/rt-mutex.rst
index c365dc302081..6e3dcff802f9 100644
--- a/Documentation/locking/rt-mutex.rst
+++ b/Documentation/locking/rt-mutex.rst
@@ -4,7 +4,7 @@ RT-mutex subsystem with PI support
 
 RT-mutexes with priority inheritance are used to support PI-futexes,
 which enable pthread_mutex_t priority inheritance attributes
-(PTHREAD_PRIO_INHERIT). [See Documentation/pi-futex.txt for more details
+(PTHREAD_PRIO_INHERIT). [See Documentation/pi-futex.rst for more details
 about PI-futexes.]
 
 This technology was developed in the -rt tree and streamlined for
diff --git a/Documentation/lockup-watchdogs.txt b/Documentation/lockup-watchdogs.rst
similarity index 99%
rename from Documentation/lockup-watchdogs.txt
rename to Documentation/lockup-watchdogs.rst
index 290840c160af..a60598bfd50f 100644
--- a/Documentation/lockup-watchdogs.txt
+++ b/Documentation/lockup-watchdogs.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===============================================================
 Softlockup detector and hardlockup detector (aka nmi_watchdog)
 ===============================================================
diff --git a/Documentation/lsm.txt b/Documentation/lsm.rst
similarity index 99%
rename from Documentation/lsm.txt
rename to Documentation/lsm.rst
index ad4dfd020e0d..4f0b1a6ea76c 100644
--- a/Documentation/lsm.txt
+++ b/Documentation/lsm.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ========================================================
 Linux Security Modules: General Security Hooks for Linux
 ========================================================
diff --git a/Documentation/lzo.txt b/Documentation/lzo.rst
similarity index 99%
rename from Documentation/lzo.txt
rename to Documentation/lzo.rst
index ca983328976b..36965db785af 100644
--- a/Documentation/lzo.txt
+++ b/Documentation/lzo.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========================================================
 LZO stream format as understood by Linux's LZO decompressor
 ===========================================================
diff --git a/Documentation/mailbox.txt b/Documentation/mailbox.rst
similarity index 99%
rename from Documentation/mailbox.txt
rename to Documentation/mailbox.rst
index 0ed95009cc30..02e754db3567 100644
--- a/Documentation/mailbox.txt
+++ b/Documentation/mailbox.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ============================
 The Common Mailbox Framework
 ============================
diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
index 9d8146b6de73..ce301317680c 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -549,8 +549,8 @@ There are certain things that the Linux kernel memory barriers do not guarantee:
 	[*] For information on bus mastering DMA and coherency please read:
 
 	    Documentation/PCI/pci.txt
-	    Documentation/DMA-API-HOWTO.txt
-	    Documentation/DMA-API.txt
+	    Documentation/DMA-API-HOWTO.rst
+	    Documentation/DMA-API.rst
 
 
 DATA DEPENDENCY BARRIERS (HISTORICAL)
@@ -1953,7 +1953,7 @@ There are some more advanced barrier functions:
      here.
 
      See the subsection "Kernel I/O barrier effects" for more information on
-     relaxed I/O accessors and the Documentation/DMA-API.txt file for more
+     relaxed I/O accessors and the Documentation/DMA-API.rst file for more
      information on consistent memory.
 
 
diff --git a/Documentation/men-chameleon-bus.txt b/Documentation/men-chameleon-bus.rst
similarity index 99%
rename from Documentation/men-chameleon-bus.txt
rename to Documentation/men-chameleon-bus.rst
index 1b1f048aa748..2d6175229e58 100644
--- a/Documentation/men-chameleon-bus.txt
+++ b/Documentation/men-chameleon-bus.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =================
 MEN Chameleon Bus
 =================
diff --git a/Documentation/networking/scaling.rst b/Documentation/networking/scaling.rst
index f78d7bf27ff5..05f0feb99320 100644
--- a/Documentation/networking/scaling.rst
+++ b/Documentation/networking/scaling.rst
@@ -81,7 +81,7 @@ of queues to IRQs can be determined from /proc/interrupts. By default,
 an IRQ may be handled on any CPU. Because a non-negligible part of packet
 processing takes place in receive interrupt handling, it is advantageous
 to spread receive interrupts between CPUs. To manually adjust the IRQ
-affinity of each interrupt see Documentation/IRQ-affinity.txt. Some systems
+affinity of each interrupt see Documentation/IRQ-affinity.rst. Some systems
 will be running irqbalance, a daemon that dynamically optimizes IRQ
 assignments and as a result may override any manual settings.
 
@@ -160,7 +160,7 @@ can be configured for each receive queue using a sysfs file entry::
 
 This file implements a bitmap of CPUs. RPS is disabled when it is zero
 (the default), in which case packets are processed on the interrupting
-CPU. Documentation/IRQ-affinity.txt explains how CPUs are assigned to
+CPU. Documentation/IRQ-affinity.rst explains how CPUs are assigned to
 the bitmap.
 
 
diff --git a/Documentation/nommu-mmap.txt b/Documentation/nommu-mmap.rst
similarity index 99%
rename from Documentation/nommu-mmap.txt
rename to Documentation/nommu-mmap.rst
index 530fed08de2c..f7f75813dc9c 100644
--- a/Documentation/nommu-mmap.txt
+++ b/Documentation/nommu-mmap.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =============================
 No-MMU memory mapping support
 =============================
diff --git a/Documentation/ntb.txt b/Documentation/ntb.rst
similarity index 99%
rename from Documentation/ntb.txt
rename to Documentation/ntb.rst
index 074a423c853c..1fa60198fd83 100644
--- a/Documentation/ntb.txt
+++ b/Documentation/ntb.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========
 NTB Drivers
 ===========
diff --git a/Documentation/numastat.txt b/Documentation/numastat.rst
similarity index 99%
rename from Documentation/numastat.txt
rename to Documentation/numastat.rst
index aaf1667489f8..61f4c9ffb138 100644
--- a/Documentation/numastat.txt
+++ b/Documentation/numastat.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===============================
 Numa policy hit/miss statistics
 ===============================
diff --git a/Documentation/padata.txt b/Documentation/padata.rst
similarity index 99%
rename from Documentation/padata.txt
rename to Documentation/padata.rst
index b103d0c82000..f8369d18c846 100644
--- a/Documentation/padata.txt
+++ b/Documentation/padata.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =======================================
 The padata parallel execution mechanism
 =======================================
diff --git a/Documentation/parport-lowlevel.txt b/Documentation/parport-lowlevel.rst
similarity index 99%
rename from Documentation/parport-lowlevel.txt
rename to Documentation/parport-lowlevel.rst
index 0633d70ffda7..b8574d83d328 100644
--- a/Documentation/parport-lowlevel.txt
+++ b/Documentation/parport-lowlevel.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===============================
 PARPORT interface documentation
 ===============================
diff --git a/Documentation/percpu-rw-semaphore.txt b/Documentation/percpu-rw-semaphore.rst
similarity index 99%
rename from Documentation/percpu-rw-semaphore.txt
rename to Documentation/percpu-rw-semaphore.rst
index 247de6410855..5c39c88d3719 100644
--- a/Documentation/percpu-rw-semaphore.txt
+++ b/Documentation/percpu-rw-semaphore.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ====================
 Percpu rw semaphores
 ====================
diff --git a/Documentation/phy.txt b/Documentation/phy.rst
similarity index 99%
rename from Documentation/phy.txt
rename to Documentation/phy.rst
index 457c3e0f86d6..129a45ccc857 100644
--- a/Documentation/phy.txt
+++ b/Documentation/phy.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =============
 PHY subsystem
 =============
diff --git a/Documentation/pi-futex.txt b/Documentation/pi-futex.rst
similarity index 99%
rename from Documentation/pi-futex.txt
rename to Documentation/pi-futex.rst
index c33ba2befbf8..884ba7f2aa10 100644
--- a/Documentation/pi-futex.txt
+++ b/Documentation/pi-futex.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ======================
 Lightweight PI-futexes
 ======================
diff --git a/Documentation/pnp.txt b/Documentation/pnp.rst
similarity index 99%
rename from Documentation/pnp.txt
rename to Documentation/pnp.rst
index bab2d10631f0..a66f19b2833c 100644
--- a/Documentation/pnp.txt
+++ b/Documentation/pnp.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =================================
 Linux Plug and Play Documentation
 =================================
diff --git a/Documentation/preempt-locking.txt b/Documentation/preempt-locking.rst
similarity index 99%
rename from Documentation/preempt-locking.txt
rename to Documentation/preempt-locking.rst
index dce336134e54..e9ccd412df59 100644
--- a/Documentation/preempt-locking.txt
+++ b/Documentation/preempt-locking.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========================================================================
 Proper Locking Under a Preemptible Kernel: Keeping Kernel Code Preempt-Safe
 ===========================================================================
diff --git a/Documentation/pwm.txt b/Documentation/pwm.rst
similarity index 99%
rename from Documentation/pwm.txt
rename to Documentation/pwm.rst
index 8fbf0aa3ba2d..78d06b7f5427 100644
--- a/Documentation/pwm.txt
+++ b/Documentation/pwm.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ======================================
 Pulse Width Modulation (PWM) interface
 ======================================
diff --git a/Documentation/rbtree.txt b/Documentation/rbtree.rst
similarity index 99%
rename from Documentation/rbtree.txt
rename to Documentation/rbtree.rst
index 523d54b60087..5d39f696eaab 100644
--- a/Documentation/rbtree.txt
+++ b/Documentation/rbtree.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =================================
 Red-black Trees (rbtree) in Linux
 =================================
diff --git a/Documentation/remoteproc.txt b/Documentation/remoteproc.rst
similarity index 99%
rename from Documentation/remoteproc.txt
rename to Documentation/remoteproc.rst
index 77fb03acdbb4..71eb7728fcf3 100644
--- a/Documentation/remoteproc.txt
+++ b/Documentation/remoteproc.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==========================
 Remote Processor Framework
 ==========================
@@ -22,7 +24,7 @@ for remote processors that supports this kind of communication. This way,
 platform-specific remoteproc drivers only need to provide a few low-level
 handlers, and then all rpmsg drivers will then just work
 (for more information about the virtio-based rpmsg bus and its drivers,
-please read Documentation/rpmsg.txt).
+please read Documentation/rpmsg.rst).
 Registration of other types of virtio devices is now also possible. Firmwares
 just need to publish what kind of virtio devices do they support, and then
 remoteproc will add those devices. This makes it possible to reuse the
diff --git a/Documentation/rfkill.txt b/Documentation/rfkill.rst
similarity index 99%
rename from Documentation/rfkill.txt
rename to Documentation/rfkill.rst
index 7d3684e81df6..4da9994e9bb4 100644
--- a/Documentation/rfkill.txt
+++ b/Documentation/rfkill.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===============================
 rfkill - RF kill switch support
 ===============================
diff --git a/Documentation/robust-futex-ABI.txt b/Documentation/robust-futex-ABI.rst
similarity index 99%
rename from Documentation/robust-futex-ABI.txt
rename to Documentation/robust-futex-ABI.rst
index 8a5d34abf726..6d359b46610c 100644
--- a/Documentation/robust-futex-ABI.txt
+++ b/Documentation/robust-futex-ABI.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ====================
 The robust futex ABI
 ====================
diff --git a/Documentation/robust-futexes.txt b/Documentation/robust-futexes.rst
similarity index 99%
rename from Documentation/robust-futexes.txt
rename to Documentation/robust-futexes.rst
index 6c42c75103eb..f60ef0e78687 100644
--- a/Documentation/robust-futexes.txt
+++ b/Documentation/robust-futexes.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ========================================
 A description of what robust futexes are
 ========================================
diff --git a/Documentation/rpmsg.txt b/Documentation/rpmsg.rst
similarity index 99%
rename from Documentation/rpmsg.txt
rename to Documentation/rpmsg.rst
index 24b7a9e1a5f9..ad53931f3e43 100644
--- a/Documentation/rpmsg.txt
+++ b/Documentation/rpmsg.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ============================================
 Remote Processor Messaging (rpmsg) Framework
 ============================================
diff --git a/Documentation/rtc.txt b/Documentation/rtc.rst
similarity index 99%
rename from Documentation/rtc.txt
rename to Documentation/rtc.rst
index 688c95b11919..b79daa10c7a1 100644
--- a/Documentation/rtc.txt
+++ b/Documentation/rtc.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =======================================
 Real Time Clock (RTC) Drivers for Linux
 =======================================
diff --git a/Documentation/s390/vfio-ccw.rst b/Documentation/s390/vfio-ccw.rst
index 1f6d0b56d53e..87b5bb49b2f3 100644
--- a/Documentation/s390/vfio-ccw.rst
+++ b/Documentation/s390/vfio-ccw.rst
@@ -38,7 +38,7 @@ every detail. More information/reference could be found here:
   qemu/hw/s390x/css.c
 
 For vfio mediated device framework:
-- Documentation/vfio-mediated-device.txt
+- Documentation/vfio-mediated-device.rst
 
 Motivation of vfio-ccw
 ----------------------
@@ -322,5 +322,5 @@ Reference
 2. ESA/390 Common I/O Device Commands manual (IBM Form. No. SA22-7204)
 3. https://en.wikipedia.org/wiki/Channel_I/O
 4. Documentation/s390/cds.rst
-5. Documentation/vfio.txt
-6. Documentation/vfio-mediated-device.txt
+5. Documentation/vfio.rst
+6. Documentation/vfio-mediated-device.rst
diff --git a/Documentation/sgi-ioc4.txt b/Documentation/sgi-ioc4.rst
similarity index 99%
rename from Documentation/sgi-ioc4.txt
rename to Documentation/sgi-ioc4.rst
index 72709222d3c0..e6ed2e9b055b 100644
--- a/Documentation/sgi-ioc4.txt
+++ b/Documentation/sgi-ioc4.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ====================================
 SGI IOC4 PCI (multi function) device
 ====================================
diff --git a/Documentation/siphash.txt b/Documentation/siphash.rst
similarity index 99%
rename from Documentation/siphash.txt
rename to Documentation/siphash.rst
index 9965821ab333..833eef3a7956 100644
--- a/Documentation/siphash.txt
+++ b/Documentation/siphash.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========================
 SipHash - a short input PRF
 ===========================
diff --git a/Documentation/smsc_ece1099.txt b/Documentation/smsc_ece1099.rst
similarity index 99%
rename from Documentation/smsc_ece1099.txt
rename to Documentation/smsc_ece1099.rst
index 079277421eaf..a403fcd7c64d 100644
--- a/Documentation/smsc_ece1099.txt
+++ b/Documentation/smsc_ece1099.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =================================================
 Msc Keyboard Scan Expansion/GPIO Expansion device
 =================================================
diff --git a/Documentation/speculation.txt b/Documentation/speculation.rst
similarity index 99%
rename from Documentation/speculation.txt
rename to Documentation/speculation.rst
index 50d7ea857cff..e240f01b0983 100644
--- a/Documentation/speculation.txt
+++ b/Documentation/speculation.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 This document explains potential effects of speculation, and how undesirable
 effects can be mitigated portably using common APIs.
 
diff --git a/Documentation/static-keys.txt b/Documentation/static-keys.rst
similarity index 99%
rename from Documentation/static-keys.txt
rename to Documentation/static-keys.rst
index 9803e14639bf..bdf545e3a37f 100644
--- a/Documentation/static-keys.txt
+++ b/Documentation/static-keys.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===========
 Static Keys
 ===========
diff --git a/Documentation/svga.txt b/Documentation/svga.rst
similarity index 99%
rename from Documentation/svga.txt
rename to Documentation/svga.rst
index b6c2f9acca92..1bfd54d9fb59 100644
--- a/Documentation/svga.txt
+++ b/Documentation/svga.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. include:: <isonum.txt>
 
 =================================
diff --git a/Documentation/switchtec.txt b/Documentation/switchtec.rst
similarity index 98%
rename from Documentation/switchtec.txt
rename to Documentation/switchtec.rst
index 30d6a64e53f7..6879c92de8e2 100644
--- a/Documentation/switchtec.txt
+++ b/Documentation/switchtec.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ========================
 Linux Switchtec Support
 ========================
@@ -97,6 +99,6 @@ the following configuration settings:
 NT EP BAR 2 will be dynamically configured as a Direct Window, and
 the configuration file does not need to configure it explicitly.
 
-Please refer to Documentation/ntb.txt in Linux source tree for an overall
+Please refer to Documentation/ntb.rst in Linux source tree for an overall
 understanding of the Linux NTB stack. ntb_hw_switchtec works as an NTB
 Hardware Driver in this stack.
diff --git a/Documentation/sync_file.txt b/Documentation/sync_file.rst
similarity index 99%
rename from Documentation/sync_file.txt
rename to Documentation/sync_file.rst
index 496fb2c3b3e6..a65a67cc06fa 100644
--- a/Documentation/sync_file.txt
+++ b/Documentation/sync_file.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===================
 Sync File API Guide
 ===================
diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt
index f0c86fbb3b48..86fd3e35afa7 100644
--- a/Documentation/sysctl/kernel.txt
+++ b/Documentation/sysctl/kernel.txt
@@ -44,7 +44,7 @@ show up in /proc/sys/kernel:
 - kexec_load_disabled
 - kptr_restrict
 - l2cr                        [ PPC only ]
-- modprobe                    ==> Documentation/debugging-modules.txt
+- modprobe                    ==> Documentation/debugging-modules.rst
 - modules_disabled
 - msg_next_id		      [ sysv ipc ]
 - msgmax
@@ -327,7 +327,7 @@ when a hard lockup is detected.
    0 - don't panic on hard lockup
    1 - panic on hard lockup
 
-See Documentation/lockup-watchdogs.txt for more information.  This can
+See Documentation/lockup-watchdogs.rst for more information.  This can
 also be set using the nmi_watchdog kernel parameter.
 
 ==============================================================
diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt
index 690b3247ab23..6758767c85a8 100644
--- a/Documentation/sysctl/vm.txt
+++ b/Documentation/sysctl/vm.txt
@@ -566,7 +566,7 @@ trimming of allocations is initiated.
 
 The default value is 1.
 
-See Documentation/nommu-mmap.txt for more information.
+See Documentation/nommu-mmap.rst for more information.
 
 ==============================================================
 
diff --git a/Documentation/tee.txt b/Documentation/tee.rst
similarity index 99%
rename from Documentation/tee.txt
rename to Documentation/tee.rst
index 56ea85ffebf2..b04ec6804fb1 100644
--- a/Documentation/tee.txt
+++ b/Documentation/tee.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =============
 TEE subsystem
 =============
diff --git a/Documentation/this_cpu_ops.txt b/Documentation/this_cpu_ops.rst
similarity index 99%
rename from Documentation/this_cpu_ops.txt
rename to Documentation/this_cpu_ops.rst
index 5cb8b883ae83..a489d25ff549 100644
--- a/Documentation/this_cpu_ops.txt
+++ b/Documentation/this_cpu_ops.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ===================
 this_cpu operations
 ===================
diff --git a/Documentation/trace/kprobetrace.rst b/Documentation/trace/kprobetrace.rst
index 235ce2ab131a..af7ed1ca8273 100644
--- a/Documentation/trace/kprobetrace.rst
+++ b/Documentation/trace/kprobetrace.rst
@@ -40,7 +40,7 @@ Synopsis of kprobe_events
  MEMADDR	: Address where the probe is inserted.
  MAXACTIVE	: Maximum number of instances of the specified function that
 		  can be probed simultaneously, or 0 for the default value
-		  as defined in Documentation/kprobes.txt section 1.3.1.
+		  as defined in Documentation/kprobes.rst section 1.3.1.
 
  FETCHARGS	: Arguments. Each probe can have up to 128 args.
   %REG		: Fetch register REG
diff --git a/Documentation/translations/ko_KR/memory-barriers.txt b/Documentation/translations/ko_KR/memory-barriers.txt
index db0b9d8619f1..f6ca27920b92 100644
--- a/Documentation/translations/ko_KR/memory-barriers.txt
+++ b/Documentation/translations/ko_KR/memory-barriers.txt
@@ -570,8 +570,8 @@ ACQUIRE 는 해당 오퍼레이션의 로드 부분에만 적용되고 RELEASE 
 	[*] 버스 마스터링 DMA 와 일관성에 대해서는 다음을 참고하시기 바랍니다:
 
 	    Documentation/PCI/pci.txt
-	    Documentation/DMA-API-HOWTO.txt
-	    Documentation/DMA-API.txt
+	    Documentation/DMA-API-HOWTO.rst
+	    Documentation/DMA-API.rst
 
 
 데이터 의존성 배리어 (역사적)
@@ -1904,7 +1904,7 @@ Mandatory 배리어들은 SMP 시스템에서도 UP 시스템에서도 SMP 효
 
      writel_relaxed() 와 같은 완화된 I/O 접근자들에 대한 자세한 내용을 위해서는
      "커널 I/O 배리어의 효과" 섹션을, consistent memory 에 대한 자세한 내용을
-     위해선 Documentation/DMA-API.txt 문서를 참고하세요.
+     위해선 Documentation/DMA-API.rst 문서를 참고하세요.
 
 
 MMIO 쓰기 배리어
diff --git a/Documentation/translations/zh_CN/IRQ.txt b/Documentation/translations/zh_CN/IRQ.txt
index 956026d5cf82..0d9ec142e185 100644
--- a/Documentation/translations/zh_CN/IRQ.txt
+++ b/Documentation/translations/zh_CN/IRQ.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/IRQ.txt
+Chinese translated version of Documentation/IRQ.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -9,7 +9,7 @@ or if there is a problem with the translation.
 Maintainer: Eric W. Biederman <ebiederman@xmission.com>
 Chinese maintainer: Fu Wei <tekkamanninja@gmail.com>
 ---------------------------------------------------------------------
-Documentation/IRQ.txt 的中文翻译
+Documentation/IRQ.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/translations/zh_CN/filesystems/sysfs.txt b/Documentation/translations/zh_CN/filesystems/sysfs.txt
index 452271dda141..f5482e082399 100644
--- a/Documentation/translations/zh_CN/filesystems/sysfs.txt
+++ b/Documentation/translations/zh_CN/filesystems/sysfs.txt
@@ -40,7 +40,7 @@ sysfs 是一个最初基于 ramfs 且位于内存的文件系统。它提供导
 数据结构及其属性，以及它们之间的关联到用户空间的方法。
 
 sysfs 始终与 kobject 的底层结构紧密相关。请阅读
-Documentation/kobject.txt 文档以获得更多关于 kobject 接口的
+Documentation/kobject.rst 文档以获得更多关于 kobject 接口的
 信息。
 
 
diff --git a/Documentation/translations/zh_CN/io_ordering.txt b/Documentation/translations/zh_CN/io_ordering.txt
index 1f8127bdd415..4e9727990c10 100644
--- a/Documentation/translations/zh_CN/io_ordering.txt
+++ b/Documentation/translations/zh_CN/io_ordering.txt
@@ -1,4 +1,4 @@
-Chinese translated version of Documentation/io_ordering.txt
+Chinese translated version of Documentation/io_ordering.rst
 
 If you have any comment or update to the content, please contact the
 original document maintainer directly.  However, if you have a problem
@@ -8,7 +8,7 @@ or if there is a problem with the translation.
 
 Chinese maintainer: Lin Yongting <linyongting@gmail.com>
 ---------------------------------------------------------------------
-Documentation/io_ordering.txt 的中文翻译
+Documentation/io_ordering.rst 的中文翻译
 
 如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文
 交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻
diff --git a/Documentation/unaligned-memory-access.txt b/Documentation/unaligned-memory-access.rst
similarity index 99%
rename from Documentation/unaligned-memory-access.txt
rename to Documentation/unaligned-memory-access.rst
index 1ee82419d8aa..848013a8bc10 100644
--- a/Documentation/unaligned-memory-access.txt
+++ b/Documentation/unaligned-memory-access.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 =========================
 Unaligned Memory Accesses
 =========================
diff --git a/Documentation/vfio-mediated-device.txt b/Documentation/vfio-mediated-device.rst
similarity index 99%
rename from Documentation/vfio-mediated-device.txt
rename to Documentation/vfio-mediated-device.rst
index c3f69bcaf96e..0ea57427e7e6 100644
--- a/Documentation/vfio-mediated-device.txt
+++ b/Documentation/vfio-mediated-device.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 .. include:: <isonum.txt>
 
 =====================
@@ -408,7 +410,7 @@ card.
 References
 ==========
 
-1. See Documentation/vfio.txt for more information on VFIO.
+1. See Documentation/vfio.rst for more information on VFIO.
 2. struct mdev_driver in include/linux/mdev.h
 3. struct mdev_parent_ops in include/linux/mdev.h
 4. struct vfio_iommu_driver_ops in include/linux/vfio.h
diff --git a/Documentation/vfio.txt b/Documentation/vfio.rst
similarity index 99%
rename from Documentation/vfio.txt
rename to Documentation/vfio.rst
index f1a4d3c3ba0b..8a3fbd7d96f0 100644
--- a/Documentation/vfio.txt
+++ b/Documentation/vfio.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==================================
 VFIO - "Virtual Function I/O" [1]_
 ==================================
diff --git a/Documentation/video-output.txt b/Documentation/video-output.rst
similarity index 99%
rename from Documentation/video-output.txt
rename to Documentation/video-output.rst
index 56d6fa2e2368..5f7e3a9faea6 100644
--- a/Documentation/video-output.txt
+++ b/Documentation/video-output.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 Video Output Switcher Control
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/Documentation/watchdog/hpwdt.rst b/Documentation/watchdog/hpwdt.rst
index 94a96371113e..f4ba329f011f 100644
--- a/Documentation/watchdog/hpwdt.rst
+++ b/Documentation/watchdog/hpwdt.rst
@@ -44,7 +44,7 @@ Last reviewed: 08/20/2018
  NOTE:
        More information about watchdog drivers in general, including the ioctl
        interface to /dev/watchdog can be found in
-       Documentation/watchdog/watchdog-api.rst and Documentation/IPMI.txt.
+       Documentation/watchdog/watchdog-api.rst and Documentation/IPMI.rst.
 
  Due to limitations in the iLO hardware, the NMI pretimeout if enabled,
  can only be set to 9 seconds.  Attempts to set pretimeout to other
diff --git a/Documentation/x86/topology.txt b/Documentation/x86/topology.txt
index 2953e3ec9a02..5d67136a7866 100644
--- a/Documentation/x86/topology.txt
+++ b/Documentation/x86/topology.txt
@@ -6,7 +6,7 @@ representation in the kernel. Update/change when doing changes to the
 respective code.
 
 The architecture-agnostic topology definitions are in
-Documentation/cputopology.txt. This file holds x86-specific
+Documentation/cputopology.rst. This file holds x86-specific
 differences/specialities which must not necessarily apply to the generic
 definitions. Thus, the way to read up on Linux topology on x86 is to start
 with the generic one and look at this one in parallel for the x86 specifics.
diff --git a/Documentation/xillybus.txt b/Documentation/xillybus.rst
similarity index 99%
rename from Documentation/xillybus.txt
rename to Documentation/xillybus.rst
index 2446ee303c09..d99f4a37e8b6 100644
--- a/Documentation/xillybus.txt
+++ b/Documentation/xillybus.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ==========================================
 Xillybus driver for generic FPGA interface
 ==========================================
diff --git a/Documentation/xz.txt b/Documentation/xz.rst
similarity index 99%
rename from Documentation/xz.txt
rename to Documentation/xz.rst
index b2220d03aa50..205edc6646d5 100644
--- a/Documentation/xz.txt
+++ b/Documentation/xz.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ============================
 XZ data compression in Linux
 ============================
diff --git a/Documentation/zorro.txt b/Documentation/zorro.rst
similarity index 99%
rename from Documentation/zorro.txt
rename to Documentation/zorro.rst
index 664072b017e3..1cf45d879c49 100644
--- a/Documentation/zorro.txt
+++ b/Documentation/zorro.rst
@@ -1,3 +1,5 @@
+:orphan:
+
 ========================================
 Writing Device Drivers for Zorro Devices
 ========================================
diff --git a/MAINTAINERS b/MAINTAINERS
index 9c99c5f47381..66bcec263dbf 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4513,7 +4513,7 @@ DELL SYSTEMS MANAGEMENT BASE DRIVER (dcdbas)
 M:	Stuart Hayes <stuart.w.hayes@gmail.com>
 L:	platform-driver-x86@vger.kernel.org
 S:	Maintained
-F:	Documentation/dcdbas.txt
+F:	Documentation/dcdbas.rst
 F:	drivers/platform/x86/dcdbas.*
 
 DELL WMI NOTIFICATIONS DRIVER
@@ -4889,7 +4889,7 @@ M:	Greg Kroah-Hartman <gregkh@linuxfoundation.org>
 R:	"Rafael J. Wysocki" <rafael@kernel.org>
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/driver-core.git
 S:	Supported
-F:	Documentation/kobject.txt
+F:	Documentation/kobject.rst
 F:	drivers/base/
 F:	fs/debugfs/
 F:	fs/sysfs/
@@ -5948,7 +5948,7 @@ M:	Ard Biesheuvel <ard.biesheuvel@linaro.org>
 L:	linux-efi@vger.kernel.org
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/efi/efi.git
 S:	Maintained
-F:	Documentation/efi-stub.txt
+F:	Documentation/efi-stub.rst
 F:	arch/*/kernel/efi.c
 F:	arch/x86/boot/compressed/eboot.[ch]
 F:	arch/*/include/asm/efi.h
@@ -6494,7 +6494,7 @@ S:	Maintained
 F:	scripts/gcc-plugins/
 F:	scripts/gcc-plugin.sh
 F:	scripts/Makefile.gcc-plugins
-F:	Documentation/gcc-plugins.txt
+F:	Documentation/gcc-plugins.rst
 
 GASKET DRIVER FRAMEWORK
 M:	Rob Springer <rspringer@google.com>
@@ -6908,7 +6908,7 @@ M:	Herbert Xu <herbert@gondor.apana.org.au>
 L:	linux-crypto@vger.kernel.org
 S:	Odd fixes
 F:	Documentation/devicetree/bindings/rng/
-F:	Documentation/hw_random.txt
+F:	Documentation/hw_random.rst
 F:	drivers/char/hw_random/
 F:	include/linux/hw_random.h
 
@@ -6924,7 +6924,7 @@ L:	linux-remoteproc@vger.kernel.org
 S:	Maintained
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/ohad/hwspinlock.git
 F:	Documentation/devicetree/bindings/hwlock/
-F:	Documentation/hwspinlock.txt
+F:	Documentation/hwspinlock.rst
 F:	drivers/hwspinlock/
 F:	include/linux/hwspinlock.h
 
@@ -8107,7 +8107,7 @@ L:	tboot-devel@lists.sourceforge.net
 W:	http://tboot.sourceforge.net
 T:	hg http://tboot.hg.sourceforge.net:8000/hgroot/tboot/tboot
 S:	Supported
-F:	Documentation/intel_txt.txt
+F:	Documentation/intel_txt.rst
 F:	include/linux/tboot.h
 F:	arch/x86/kernel/tboot.c
 
@@ -8191,7 +8191,7 @@ L:	openipmi-developer@lists.sourceforge.net (moderated for non-subscribers)
 W:	http://openipmi.sourceforge.net/
 S:	Supported
 F:	Documentation/devicetree/bindings/ipmi/
-F:	Documentation/IPMI.txt
+F:	Documentation/IPMI.rst
 F:	drivers/char/ipmi/
 F:	include/linux/ipmi*
 F:	include/uapi/linux/ipmi*
@@ -8232,7 +8232,7 @@ IRQ DOMAINS (IRQ NUMBER MAPPING LIBRARY)
 M:	Marc Zyngier <marc.zyngier@arm.com>
 S:	Maintained
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip.git irq/core
-F:	Documentation/IRQ-domain.txt
+F:	Documentation/IRQ-domain.rst
 F:	include/linux/irqdomain.h
 F:	kernel/irq/irqdomain.c
 F:	kernel/irq/msi.c
@@ -8257,7 +8257,7 @@ F:	drivers/irqchip/
 ISA
 M:	William Breathitt Gray <vilhelm.gray@gmail.com>
 S:	Maintained
-F:	Documentation/isa.txt
+F:	Documentation/isa.rst
 F:	drivers/base/isa.c
 F:	include/linux/isa.h
 
@@ -8272,7 +8272,7 @@ F:	drivers/media/radio/radio-isa*
 ISAPNP
 M:	Jaroslav Kysela <perex@perex.cz>
 S:	Maintained
-F:	Documentation/isapnp.txt
+F:	Documentation/isapnp.rst
 F:	drivers/pnp/isapnp/
 F:	include/linux/isapnp.h
 
@@ -8711,7 +8711,7 @@ M:	Anil S Keshavamurthy <anil.s.keshavamurthy@intel.com>
 M:	"David S. Miller" <davem@davemloft.net>
 M:	Masami Hiramatsu <mhiramat@kernel.org>
 S:	Maintained
-F:	Documentation/kprobes.txt
+F:	Documentation/kprobes.rst
 F:	include/linux/kprobes.h
 F:	include/asm-generic/kprobes.h
 F:	kernel/kprobes.c
@@ -9069,7 +9069,7 @@ L:	linux-arch@vger.kernel.org
 S:	Supported
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git dev
 F:	tools/memory-model/
-F:	Documentation/atomic_bitops.txt
+F:	Documentation/atomic_bitops.rst
 F:	Documentation/atomic_t.txt
 F:	Documentation/core-api/atomic_ops.rst
 F:	Documentation/core-api/refcount-vs-atomic.rst
@@ -9183,7 +9183,7 @@ M:	"Richard Russon (FlatCap)" <ldm@flatcap.org>
 L:	linux-ntfs-dev@lists.sourceforge.net
 W:	http://www.linux-ntfs.org/content/view/19/37/
 S:	Maintained
-F:	Documentation/ldm.txt
+F:	Documentation/ldm.rst
 F:	block/partitions/ldm.*
 
 LSILOGIC MPT FUSION DRIVERS (FC/SAS/SPI)
@@ -10109,7 +10109,7 @@ M:	Johannes Thumshirn <morbidrsa@gmail.com>
 S:	Maintained
 F:	drivers/mcb/
 F:	include/linux/mcb.h
-F:	Documentation/men-chameleon-bus.txt
+F:	Documentation/men-chameleon-bus.rst
 
 MEN F21BMC (Board Management Controller)
 M:	Andreas Werner <andreas.werner@men.de>
@@ -11761,7 +11761,7 @@ L:	linux-crypto@vger.kernel.org
 S:	Maintained
 F:	kernel/padata.c
 F:	include/linux/padata.h
-F:	Documentation/padata.txt
+F:	Documentation/padata.rst
 
 PANASONIC LAPTOP ACPI EXTRAS DRIVER
 M:	Harald Welte <laforge@gnumonks.org>
@@ -11785,7 +11785,7 @@ F:	drivers/parport/
 F:	include/linux/parport*.h
 F:	drivers/char/ppdev.c
 F:	include/uapi/linux/ppdev.h
-F:	Documentation/parport*.txt
+F:	Documentation/parport*.rst
 
 PARAVIRT_OPS INTERFACE
 M:	Juergen Gross <jgross@suse.com>
@@ -11960,7 +11960,7 @@ M:	Kurt Schwemmer <kurt.schwemmer@microsemi.com>
 M:	Logan Gunthorpe <logang@deltatee.com>
 L:	linux-pci@vger.kernel.org
 S:	Maintained
-F:	Documentation/switchtec.txt
+F:	Documentation/switchtec.rst
 F:	Documentation/ABI/testing/sysfs-class-switchtec
 F:	drivers/pci/switch/switchtec*
 F:	include/uapi/linux/switchtec_ioctl.h
@@ -12715,7 +12715,7 @@ M:	Thierry Reding <thierry.reding@gmail.com>
 L:	linux-pwm@vger.kernel.org
 S:	Maintained
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/thierry.reding/linux-pwm.git
-F:	Documentation/pwm.txt
+F:	Documentation/pwm.rst
 F:	Documentation/devicetree/bindings/pwm/
 F:	include/linux/pwm.h
 F:	drivers/pwm/
@@ -13186,7 +13186,7 @@ Q:	http://patchwork.ozlabs.org/project/rtc-linux/list/
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/abelloni/linux.git
 S:	Maintained
 F:	Documentation/devicetree/bindings/rtc/
-F:	Documentation/rtc.txt
+F:	Documentation/rtc.rst
 F:	drivers/rtc/
 F:	include/linux/rtc.h
 F:	include/uapi/linux/rtc.h
@@ -13236,7 +13236,7 @@ L:	linux-remoteproc@vger.kernel.org
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/ohad/remoteproc.git
 S:	Maintained
 F:	Documentation/devicetree/bindings/remoteproc/
-F:	Documentation/remoteproc.txt
+F:	Documentation/remoteproc.rst
 F:	drivers/remoteproc/
 F:	include/linux/remoteproc.h
 
@@ -13247,7 +13247,7 @@ L:	linux-remoteproc@vger.kernel.org
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/ohad/rpmsg.git
 S:	Maintained
 F:	drivers/rpmsg/
-F:	Documentation/rpmsg.txt
+F:	Documentation/rpmsg.rst
 F:	include/linux/rpmsg.h
 F:	include/linux/rpmsg/
 
@@ -13327,7 +13327,7 @@ W:	http://wireless.kernel.org/
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/jberg/mac80211.git
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/jberg/mac80211-next.git
 S:	Maintained
-F:	Documentation/rfkill.txt
+F:	Documentation/rfkill.rst
 F:	Documentation/ABI/stable/sysfs-class-rfkill
 F:	net/rfkill/
 F:	include/linux/rfkill.h
@@ -14966,7 +14966,7 @@ SVGA HANDLING
 M:	Martin Mares <mj@ucw.cz>
 L:	linux-video@atrey.karlin.mff.cuni.cz
 S:	Maintained
-F:	Documentation/svga.txt
+F:	Documentation/svga.rst
 F:	arch/x86/boot/video*
 
 SWIOTLB SUBSYSTEM
@@ -15003,7 +15003,7 @@ F:	drivers/dma-buf/dma-fence*
 F:	drivers/dma-buf/sw_sync.c
 F:	include/linux/sync_file.h
 F:	include/uapi/linux/sync_file.h
-F:	Documentation/sync_file.txt
+F:	Documentation/sync_file.rst
 T:	git git://anongit.freedesktop.org/drm/drm-misc
 
 SYNOPSYS ARC ARCHITECTURE
@@ -15329,7 +15329,7 @@ S:	Maintained
 F:	include/linux/tee_drv.h
 F:	include/uapi/linux/tee.h
 F:	drivers/tee/
-F:	Documentation/tee.txt
+F:	Documentation/tee.rst
 
 TEGRA ARCHITECTURE SUPPORT
 M:	Thierry Reding <thierry.reding@gmail.com>
@@ -16484,7 +16484,7 @@ M:	Alex Williamson <alex.williamson@redhat.com>
 L:	kvm@vger.kernel.org
 T:	git git://github.com/awilliam/linux-vfio.git
 S:	Maintained
-F:	Documentation/vfio.txt
+F:	Documentation/vfio.rst
 F:	drivers/vfio/
 F:	include/linux/vfio.h
 F:	include/uapi/linux/vfio.h
@@ -16493,7 +16493,7 @@ VFIO MEDIATED DEVICE DRIVERS
 M:	Kirti Wankhede <kwankhede@nvidia.com>
 L:	kvm@vger.kernel.org
 S:	Maintained
-F:	Documentation/vfio-mediated-device.txt
+F:	Documentation/vfio-mediated-device.rst
 F:	drivers/vfio/mdev/
 F:	include/linux/mdev.h
 F:	samples/vfio-mdev/
diff --git a/arch/Kconfig b/arch/Kconfig
index ed382b01209b..ba0a53b543e3 100644
--- a/arch/Kconfig
+++ b/arch/Kconfig
@@ -141,7 +141,7 @@ config HAVE_64BIT_ALIGNED_ACCESS
 	  accesses are required to be 64 bit aligned in this way even
 	  though it is not a 64 bit architecture.
 
-	  See Documentation/unaligned-memory-access.txt for more
+	  See Documentation/unaligned-memory-access.rst for more
 	  information on the topic of unaligned memory accesses.
 
 config HAVE_EFFICIENT_UNALIGNED_ACCESS
@@ -160,7 +160,7 @@ config HAVE_EFFICIENT_UNALIGNED_ACCESS
 	  problems with received packets if doing so would not help
 	  much.
 
-	  See Documentation/unaligned-memory-access.txt for more
+	  See Documentation/unaligned-memory-access.rst for more
 	  information on the topic of unaligned memory accesses.
 
 config ARCH_USE_BUILTIN_BSWAP
diff --git a/arch/arm/Kconfig b/arch/arm/Kconfig
index c6c424466f8a..7b905429626b 100644
--- a/arch/arm/Kconfig
+++ b/arch/arm/Kconfig
@@ -1260,8 +1260,8 @@ config SMP
 	  uniprocessor machines. On a uniprocessor machine, the kernel
 	  will run faster if you say N here.
 
-	  See also <file:Documentation/x86/i386/IO-APIC.txt>,
-	  <file:Documentation/lockup-watchdogs.txt> and the SMP-HOWTO available at
+	  See also <file:Documentation/x86/i386/IO-APIC.rst>,
+	  <file:Documentation/lockup-watchdogs.rst> and the SMP-HOWTO available at
 	  <http://tldp.org/HOWTO/SMP-HOWTO.html>.
 
 	  If you don't know what to do here, say N.
diff --git a/arch/ia64/hp/common/sba_iommu.c b/arch/ia64/hp/common/sba_iommu.c
index 5a361e51cb1e..0334db406d68 100644
--- a/arch/ia64/hp/common/sba_iommu.c
+++ b/arch/ia64/hp/common/sba_iommu.c
@@ -915,7 +915,7 @@ sba_mark_invalid(struct ioc *ioc, dma_addr_t iova, size_t byte_cnt)
  * @dir: dma direction
  * @attrs: optional dma attributes
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static dma_addr_t sba_map_page(struct device *dev, struct page *page,
 			       unsigned long poff, size_t size,
@@ -1036,7 +1036,7 @@ sba_mark_clean(struct ioc *ioc, dma_addr_t iova, size_t size)
  * @dir:  R/W or both.
  * @attrs: optional dma attributes
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static void sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
 			   enum dma_data_direction dir, unsigned long attrs)
@@ -1113,7 +1113,7 @@ static void sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
  * @size:  number of bytes mapped in driver buffer.
  * @dma_handle:  IOVA of new buffer.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static void *
 sba_alloc_coherent(struct device *dev, size_t size, dma_addr_t *dma_handle,
@@ -1170,7 +1170,7 @@ sba_alloc_coherent(struct device *dev, size_t size, dma_addr_t *dma_handle,
  * @vaddr:  virtual address IOVA of "consistent" buffer.
  * @dma_handler:  IO virtual address of "consistent" buffer.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static void sba_free_coherent(struct device *dev, size_t size, void *vaddr,
 			      dma_addr_t dma_handle, unsigned long attrs)
@@ -1433,7 +1433,7 @@ static void sba_unmap_sg_attrs(struct device *dev, struct scatterlist *sglist,
  * @dir:  R/W or both.
  * @attrs: optional dma attributes
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static int sba_map_sg_attrs(struct device *dev, struct scatterlist *sglist,
 			    int nents, enum dma_data_direction dir,
@@ -1532,7 +1532,7 @@ static int sba_map_sg_attrs(struct device *dev, struct scatterlist *sglist,
  * @dir:  R/W or both.
  * @attrs: optional dma attributes
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static void sba_unmap_sg_attrs(struct device *dev, struct scatterlist *sglist,
 			       int nents, enum dma_data_direction dir,
diff --git a/arch/ia64/sn/pci/pci_dma.c b/arch/ia64/sn/pci/pci_dma.c
index b7d42e4edc1f..f475fccea152 100644
--- a/arch/ia64/sn/pci/pci_dma.c
+++ b/arch/ia64/sn/pci/pci_dma.c
@@ -5,7 +5,7 @@
  *
  * Copyright (C) 2000,2002-2005 Silicon Graphics, Inc. All rights reserved.
  *
- * Routines for PCI DMA mapping.  See Documentation/DMA-API.txt for
+ * Routines for PCI DMA mapping.  See Documentation/DMA-API.rst for
  * a description of how these routines should be used.
  */
 
@@ -72,7 +72,7 @@ EXPORT_SYMBOL(sn_dma_set_mask);
  * that @dma_handle will have the %PCIIO_DMA_CMD flag set.
  *
  * This interface is usually used for "command" streams (e.g. the command
- * queue for a SCSI controller).  See Documentation/DMA-API.txt for
+ * queue for a SCSI controller).  See Documentation/DMA-API.rst for
  * more information.
  */
 static void *sn_dma_alloc_coherent(struct device *dev, size_t size,
diff --git a/arch/parisc/Kconfig b/arch/parisc/Kconfig
index f996a6b2df40..e1189b9df371 100644
--- a/arch/parisc/Kconfig
+++ b/arch/parisc/Kconfig
@@ -273,7 +273,7 @@ config SMP
 	  machines, but will use only one CPU of a multiprocessor machine.
 	  On a uniprocessor machine, the kernel will run faster if you say N.
 
-	  See also <file:Documentation/lockup-watchdogs.txt> and the SMP-HOWTO
+	  See also <file:Documentation/lockup-watchdogs.rst> and the SMP-HOWTO
 	  available at <http://www.tldp.org/docs.html#howto>.
 
 	  If you don't know what to do here, say N.
diff --git a/arch/parisc/kernel/pci-dma.c b/arch/parisc/kernel/pci-dma.c
index 239162355b58..2bb63062f6c3 100644
--- a/arch/parisc/kernel/pci-dma.c
+++ b/arch/parisc/kernel/pci-dma.c
@@ -3,7 +3,7 @@
 ** PARISC 1.1 Dynamic DMA mapping support.
 ** This implementation is for PA-RISC platforms that do not support
 ** I/O TLBs (aka DMA address translation hardware).
-** See Documentation/DMA-API-HOWTO.txt for interface definitions.
+** See Documentation/DMA-API-HOWTO.rst for interface definitions.
 **
 **      (c) Copyright 1999,2000 Hewlett-Packard Company
 **      (c) Copyright 2000 Grant Grundler
diff --git a/arch/sh/Kconfig b/arch/sh/Kconfig
index 9883516e682c..a72f4f9e91f3 100644
--- a/arch/sh/Kconfig
+++ b/arch/sh/Kconfig
@@ -677,7 +677,7 @@ config SMP
 	  People using multiprocessor machines who say Y here should also say
 	  Y to "Enhanced Real Time Clock Support", below.
 
-	  See also <file:Documentation/lockup-watchdogs.txt> and the SMP-HOWTO
+	  See also <file:Documentation/lockup-watchdogs.rst> and the SMP-HOWTO
 	  available at <http://www.tldp.org/docs.html#howto>.
 
 	  If you don't know what to do here, say N.
diff --git a/arch/sparc/Kconfig b/arch/sparc/Kconfig
index 7c93f3121ee6..6391fdc4a98e 100644
--- a/arch/sparc/Kconfig
+++ b/arch/sparc/Kconfig
@@ -178,7 +178,7 @@ config SMP
 	  Y to "Enhanced Real Time Clock Support", below. The "Advanced Power
 	  Management" code will be disabled if you say Y here.
 
-	  See also <file:Documentation/lockup-watchdogs.txt> and the SMP-HOWTO
+	  See also <file:Documentation/lockup-watchdogs.rst> and the SMP-HOWTO
 	  available at <http://www.tldp.org/docs.html#howto>.
 
 	  If you don't know what to do here, say N.
diff --git a/arch/unicore32/include/asm/io.h b/arch/unicore32/include/asm/io.h
index cb1d8fd2b16b..86877df4b1ee 100644
--- a/arch/unicore32/include/asm/io.h
+++ b/arch/unicore32/include/asm/io.h
@@ -31,7 +31,7 @@ extern void __uc32_iounmap(volatile void __iomem *addr);
  * ioremap and friends.
  *
  * ioremap takes a PCI memory address, as specified in
- * Documentation/io-mapping.txt.
+ * Documentation/io-mapping.rst.
  *
  */
 #define ioremap(cookie, size)		__uc32_ioremap(cookie, size)
diff --git a/arch/x86/Kconfig b/arch/x86/Kconfig
index bf8cb068acf8..24edda6eac18 100644
--- a/arch/x86/Kconfig
+++ b/arch/x86/Kconfig
@@ -392,7 +392,7 @@ config SMP
 	  Management" code will be disabled if you say Y here.
 
 	  See also <file:Documentation/x86/i386/IO-APIC.txt>,
-	  <file:Documentation/lockup-watchdogs.txt> and the SMP-HOWTO available at
+	  <file:Documentation/lockup-watchdogs.rst> and the SMP-HOWTO available at
 	  <http://www.tldp.org/docs.html#howto>.
 
 	  If you don't know what to do here, say N.
@@ -1940,7 +1940,7 @@ config EFI_STUB
           This kernel feature allows a bzImage to be loaded directly
 	  by EFI firmware without the use of a bootloader.
 
-	  See Documentation/efi-stub.txt for more information.
+	  See Documentation/efi-stub.rst for more information.
 
 config EFI_MIXED
 	bool "EFI mixed-mode support"
diff --git a/arch/x86/include/asm/dma-mapping.h b/arch/x86/include/asm/dma-mapping.h
index 6b15a24930e0..dfa443fe17c2 100644
--- a/arch/x86/include/asm/dma-mapping.h
+++ b/arch/x86/include/asm/dma-mapping.h
@@ -3,8 +3,8 @@
 #define _ASM_X86_DMA_MAPPING_H
 
 /*
- * IOMMU interface. See Documentation/DMA-API-HOWTO.txt and
- * Documentation/DMA-API.txt for documentation.
+ * IOMMU interface. See Documentation/DMA-API-HOWTO.rst and
+ * Documentation/DMA-API.rst for documentation.
  */
 
 #include <linux/scatterlist.h>
diff --git a/arch/x86/kernel/amd_gart_64.c b/arch/x86/kernel/amd_gart_64.c
index bf7f13ea3c64..46d555c0c234 100644
--- a/arch/x86/kernel/amd_gart_64.c
+++ b/arch/x86/kernel/amd_gart_64.c
@@ -5,7 +5,7 @@
  * This allows to use PCI devices that only support 32bit addresses on systems
  * with more than 4GB.
  *
- * See Documentation/DMA-API-HOWTO.txt for the interface specification.
+ * See Documentation/DMA-API-HOWTO.rst for the interface specification.
  *
  * Copyright 2002 Andi Kleen, SuSE Labs.
  * Subject to the GNU General Public License v2 only.
diff --git a/block/partitions/Kconfig b/block/partitions/Kconfig
index 37b9710cc80a..51b28e1e225d 100644
--- a/block/partitions/Kconfig
+++ b/block/partitions/Kconfig
@@ -194,7 +194,7 @@ config LDM_PARTITION
 	  Normal partitions are now called Basic Disks under Windows 2000, XP,
 	  and Vista.
 
-	  For a fuller description read <file:Documentation/ldm.txt>.
+	  For a fuller description read <file:Documentation/ldm.rst>.
 
 	  If unsure, say N.
 
diff --git a/drivers/base/core.c b/drivers/base/core.c
index 4aeaa0c92bda..47abfd0d06aa 100644
--- a/drivers/base/core.c
+++ b/drivers/base/core.c
@@ -1063,7 +1063,7 @@ static void device_release(struct kobject *kobj)
 	else if (dev->class && dev->class->dev_release)
 		dev->class->dev_release(dev);
 	else
-		WARN(1, KERN_ERR "Device '%s' does not have a release() function, it is broken and must be fixed. See Documentation/kobject.txt.\n",
+		WARN(1, KERN_ERR "Device '%s' does not have a release() function, it is broken and must be fixed. See Documentation/kobject.rst.\n",
 			dev_name(dev));
 	kfree(p);
 }
diff --git a/drivers/char/Kconfig b/drivers/char/Kconfig
index 466ebd84ad17..110824a27510 100644
--- a/drivers/char/Kconfig
+++ b/drivers/char/Kconfig
@@ -291,7 +291,7 @@ config RTC
 	  and set the RTC in an SMP compatible fashion.
 
 	  If you think you have a use for such a device (such as periodic data
-	  sampling), then say Y here, and read <file:Documentation/rtc.txt>
+	  sampling), then say Y here, and read <file:Documentation/rtc.rst>
 	  for details.
 
 	  To compile this driver as a module, choose M here: the
@@ -313,7 +313,7 @@ config JS_RTC
 	  /dev/rtc.
 
 	  If you think you have a use for such a device (such as periodic data
-	  sampling), then say Y here, and read <file:Documentation/rtc.txt>
+	  sampling), then say Y here, and read <file:Documentation/rtc.rst>
 	  for details.
 
 	  To compile this driver as a module, choose M here: the
diff --git a/drivers/char/hw_random/core.c b/drivers/char/hw_random/core.c
index 95be7228f327..41acde92bedc 100644
--- a/drivers/char/hw_random/core.c
+++ b/drivers/char/hw_random/core.c
@@ -4,7 +4,7 @@
  * Copyright 2006 Michael Buesch <m@bues.ch>
  * Copyright 2005 (c) MontaVista Software, Inc.
  *
- * Please read Documentation/hw_random.txt for details on use.
+ * Please read Documentation/hw_random.rst for details on use.
  *
  * This software may be used and distributed according to the terms
  * of the GNU General Public License, incorporated herein by reference.
diff --git a/drivers/char/ipmi/Kconfig b/drivers/char/ipmi/Kconfig
index 94719fc6ff9d..df47923e5119 100644
--- a/drivers/char/ipmi/Kconfig
+++ b/drivers/char/ipmi/Kconfig
@@ -13,7 +13,7 @@ menuconfig IPMI_HANDLER
          IPMI is a standard for managing sensors (temperature,
          voltage, etc.) in a system.
 
-         See <file:Documentation/IPMI.txt> for more details on the driver.
+         See <file:Documentation/IPMI.rst> for more details on the driver.
 
 	 If unsure, say N.
 
diff --git a/drivers/char/ipmi/ipmi_si_hotmod.c b/drivers/char/ipmi/ipmi_si_hotmod.c
index 03140f6cdf6f..bcf84522d5ef 100644
--- a/drivers/char/ipmi/ipmi_si_hotmod.c
+++ b/drivers/char/ipmi/ipmi_si_hotmod.c
@@ -18,7 +18,7 @@ static int hotmod_handler(const char *val, const struct kernel_param *kp);
 
 module_param_call(hotmod, hotmod_handler, NULL, NULL, 0200);
 MODULE_PARM_DESC(hotmod, "Add and remove interfaces.  See"
-		 " Documentation/IPMI.txt in the kernel sources for the"
+		 " Documentation/IPMI.rst in the kernel sources for the"
 		 " gory details.");
 
 /*
diff --git a/drivers/char/ipmi/ipmi_si_intf.c b/drivers/char/ipmi/ipmi_si_intf.c
index f124a2d2bb9f..5efb5c2ee78e 100644
--- a/drivers/char/ipmi/ipmi_si_intf.c
+++ b/drivers/char/ipmi/ipmi_si_intf.c
@@ -977,7 +977,7 @@ static inline int ipmi_thread_busy_wait(enum si_sm_result smi_result,
  * that are not BT and do not have interrupts.  It starts spinning
  * when an operation is complete or until max_busy tells it to stop
  * (if that is enabled).  See the paragraph on kimid_max_busy_us in
- * Documentation/IPMI.txt for details.
+ * Documentation/IPMI.rst for details.
  */
 static int ipmi_thread(void *data)
 {
diff --git a/drivers/dma-buf/Kconfig b/drivers/dma-buf/Kconfig
index 2e5a0faa2cb1..ae3c798ea787 100644
--- a/drivers/dma-buf/Kconfig
+++ b/drivers/dma-buf/Kconfig
@@ -15,7 +15,7 @@ config SYNC_FILE
 	  associated with a buffer. When a job is submitted to the GPU a fence
 	  is attached to the buffer and is transferred via userspace, using Sync
 	  Files fds, to the DRM driver for example. More details at
-	  Documentation/sync_file.txt.
+	  Documentation/sync_file.rst.
 
 config SW_SYNC
 	bool "Sync File Validation Framework"
diff --git a/drivers/gpio/Kconfig b/drivers/gpio/Kconfig
index 50020cacf1b4..bd2ff8333172 100644
--- a/drivers/gpio/Kconfig
+++ b/drivers/gpio/Kconfig
@@ -1284,7 +1284,7 @@ config GPIO_BT8XX
 	  The card needs to be physically altered for using it as a
 	  GPIO card. For more information on how to build a GPIO card
 	  from a BT8xx TV card, see the documentation file at
-	  Documentation/bt8xxgpio.txt
+	  Documentation/bt8xxgpio.rst
 
 	  If unsure, say N.
 
diff --git a/drivers/parisc/sba_iommu.c b/drivers/parisc/sba_iommu.c
index afaf8e6aefe6..00a2675db798 100644
--- a/drivers/parisc/sba_iommu.c
+++ b/drivers/parisc/sba_iommu.c
@@ -670,7 +670,7 @@ sba_mark_invalid(struct ioc *ioc, dma_addr_t iova, size_t byte_cnt)
  * @dev: instance of PCI owned by the driver that's asking
  * @mask:  number of address bits this PCI device can handle
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static int sba_dma_supported( struct device *dev, u64 mask)
 {
@@ -682,7 +682,7 @@ static int sba_dma_supported( struct device *dev, u64 mask)
 		return(0);
 	}
 
-	/* Documentation/DMA-API-HOWTO.txt tells drivers to try 64-bit
+	/* Documentation/DMA-API-HOWTO.rst tells drivers to try 64-bit
 	 * first, then fall back to 32-bit if that fails.
 	 * We are just "encouraging" 32-bit DMA masks here since we can
 	 * never allow IOMMU bypass unless we add special support for ZX1.
@@ -710,7 +710,7 @@ static int sba_dma_supported( struct device *dev, u64 mask)
  * @size:  number of bytes to map in driver buffer.
  * @direction:  R/W or both.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static dma_addr_t
 sba_map_single(struct device *dev, void *addr, size_t size,
@@ -800,7 +800,7 @@ sba_map_page(struct device *dev, struct page *page, unsigned long offset,
  * @size:  number of bytes mapped in driver buffer.
  * @direction:  R/W or both.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static void
 sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
@@ -879,7 +879,7 @@ sba_unmap_page(struct device *dev, dma_addr_t iova, size_t size,
  * @size:  number of bytes mapped in driver buffer.
  * @dma_handle:  IOVA of new buffer.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static void *sba_alloc(struct device *hwdev, size_t size, dma_addr_t *dma_handle,
 		gfp_t gfp, unsigned long attrs)
@@ -910,7 +910,7 @@ static void *sba_alloc(struct device *hwdev, size_t size, dma_addr_t *dma_handle
  * @vaddr:  virtual address IOVA of "consistent" buffer.
  * @dma_handler:  IO virtual address of "consistent" buffer.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static void
 sba_free(struct device *hwdev, size_t size, void *vaddr,
@@ -945,7 +945,7 @@ int dump_run_sg = 0;
  * @nents:  number of entries in list
  * @direction:  R/W or both.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static int
 sba_map_sg(struct device *dev, struct scatterlist *sglist, int nents,
@@ -1029,7 +1029,7 @@ sba_map_sg(struct device *dev, struct scatterlist *sglist, int nents,
  * @nents:  number of entries in list
  * @direction:  R/W or both.
  *
- * See Documentation/DMA-API-HOWTO.txt
+ * See Documentation/DMA-API-HOWTO.rst
  */
 static void 
 sba_unmap_sg(struct device *dev, struct scatterlist *sglist, int nents,
diff --git a/drivers/pci/switch/Kconfig b/drivers/pci/switch/Kconfig
index aee28a5bb98f..c1f5226cd0e5 100644
--- a/drivers/pci/switch/Kconfig
+++ b/drivers/pci/switch/Kconfig
@@ -9,7 +9,7 @@ config PCI_SW_SWITCHTEC
 	 Enables support for the management interface for the MicroSemi
 	 Switchtec series of PCIe switches. Supports userspace access
 	 to submit MRPC commands to the switch via /dev/switchtecX
-	 devices. See <file:Documentation/switchtec.txt> for more
+	 devices. See <file:Documentation/switchtec.rst> for more
 	 information.
 
 endmenu
diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
index a1ed13183559..91b63cd4d48d 100644
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -117,7 +117,7 @@ config DCDBAS
 	  Interrupts (SMIs) and Host Control Actions (system power cycle or
 	  power off after OS shutdown) on certain Dell systems.
 
-	  See <file:Documentation/dcdbas.txt> for more details on the driver
+	  See <file:Documentation/dcdbas.rst> for more details on the driver
 	  and the Dell systems on which Dell systems management software makes
 	  use of this driver.
 
@@ -258,7 +258,7 @@ config DELL_RBU
 	 DELL system. Note you need a Dell OpenManage or Dell Update package (DUP)
 	 supporting application to communicate with the BIOS regarding the new
 	 image for the image update to take effect.
-	 See <file:Documentation/dell_rbu.txt> for more details on the driver.
+	 See <file:Documentation/dell_rbu.rst> for more details on the driver.
 
 
 config FUJITSU_LAPTOP
diff --git a/drivers/platform/x86/dcdbas.c b/drivers/platform/x86/dcdbas.c
index 88bd7efafe14..cc21295fa972 100644
--- a/drivers/platform/x86/dcdbas.c
+++ b/drivers/platform/x86/dcdbas.c
@@ -6,7 +6,7 @@
  *  and Host Control Actions (power cycle or power off after OS shutdown) on
  *  Dell systems.
  *
- *  See Documentation/dcdbas.txt for more information.
+ *  See Documentation/dcdbas.rst for more information.
  *
  *  Copyright (C) 1995-2006 Dell Inc.
  *
diff --git a/drivers/platform/x86/dell_rbu.c b/drivers/platform/x86/dell_rbu.c
index 031c68903583..9beb45bcffee 100644
--- a/drivers/platform/x86/dell_rbu.c
+++ b/drivers/platform/x86/dell_rbu.c
@@ -23,7 +23,7 @@
  * on every time the packet data is written. This driver requires an
  * application to break the BIOS image in to fixed sized packet chunks.
  *
- * See Documentation/dell_rbu.txt for more info.
+ * See Documentation/dell_rbu.rst for more info.
  *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License v2.0 as published by
diff --git a/drivers/pnp/isapnp/Kconfig b/drivers/pnp/isapnp/Kconfig
index a1af146d2d90..740607146e42 100644
--- a/drivers/pnp/isapnp/Kconfig
+++ b/drivers/pnp/isapnp/Kconfig
@@ -6,6 +6,6 @@ config ISAPNP
 	depends on ISA || COMPILE_TEST
 	help
 	  Say Y here if you would like support for ISA Plug and Play devices.
-	  Some information is in <file:Documentation/isapnp.txt>.
+	  Some information is in <file:Documentation/isapnp.rst>.
 
 	  If unsure, say Y.
diff --git a/drivers/vfio/Kconfig b/drivers/vfio/Kconfig
index 9de5ed38da83..edf824e6433e 100644
--- a/drivers/vfio/Kconfig
+++ b/drivers/vfio/Kconfig
@@ -25,7 +25,7 @@ menuconfig VFIO
 	select ANON_INODES
 	help
 	  VFIO provides a framework for secure userspace device drivers.
-	  See Documentation/vfio.txt for more details.
+	  See Documentation/vfio.rst for more details.
 
 	  If you don't know what to do here, say N.
 
diff --git a/drivers/vfio/mdev/Kconfig b/drivers/vfio/mdev/Kconfig
index 14fdb106a827..fd310018a0c2 100644
--- a/drivers/vfio/mdev/Kconfig
+++ b/drivers/vfio/mdev/Kconfig
@@ -5,7 +5,7 @@ config VFIO_MDEV
 	default n
 	help
 	  Provides a framework to virtualize devices.
-	  See Documentation/vfio-mediated-device.txt for more details.
+	  See Documentation/vfio-mediated-device.rst for more details.
 
 	  If you don't know what do here, say N.
 
diff --git a/include/asm-generic/bitops/atomic.h b/include/asm-generic/bitops/atomic.h
index dd90c9792909..6ee11717bb65 100644
--- a/include/asm-generic/bitops/atomic.h
+++ b/include/asm-generic/bitops/atomic.h
@@ -8,7 +8,7 @@
 
 /*
  * Implementation of atomic bitops using atomic-fetch ops.
- * See Documentation/atomic_bitops.txt for details.
+ * See Documentation/atomic_bitops.rst for details.
  */
 
 static inline void set_bit(unsigned int nr, volatile unsigned long *p)
diff --git a/include/linux/dma-mapping.h b/include/linux/dma-mapping.h
index 6309a721394b..7ff3fcd73cec 100644
--- a/include/linux/dma-mapping.h
+++ b/include/linux/dma-mapping.h
@@ -14,7 +14,7 @@
 
 /**
  * List of possible attributes associated with a DMA mapping. The semantics
- * of each attribute should be defined in Documentation/DMA-attributes.txt.
+ * of each attribute should be defined in Documentation/DMA-attributes.rst.
  *
  * DMA_ATTR_WRITE_BARRIER: DMA to a memory region with this attribute
  * forces all pending DMA writes to complete.
diff --git a/include/linux/hw_random.h b/include/linux/hw_random.h
index c0b93e0ff0c0..e533eac9942b 100644
--- a/include/linux/hw_random.h
+++ b/include/linux/hw_random.h
@@ -1,7 +1,7 @@
 /*
 	Hardware Random Number Generator
 
-	Please read Documentation/hw_random.txt for details on use.
+	Please read Documentation/hw_random.rst for details on use.
 
 	----------------------------------------------------------
 	This software may be used and distributed according to the terms
diff --git a/include/linux/io-mapping.h b/include/linux/io-mapping.h
index 58df02bd93c9..b90c540696a4 100644
--- a/include/linux/io-mapping.h
+++ b/include/linux/io-mapping.h
@@ -28,7 +28,7 @@
  * The io_mapping mechanism provides an abstraction for mapping
  * individual pages from an io device to the CPU in an efficient fashion.
  *
- * See Documentation/io-mapping.txt
+ * See Documentation/io-mapping.rst
  */
 
 struct io_mapping {
diff --git a/include/linux/jump_label.h b/include/linux/jump_label.h
index 3e113a1fa0f1..c3947cab2d27 100644
--- a/include/linux/jump_label.h
+++ b/include/linux/jump_label.h
@@ -68,7 +68,7 @@
  * Lacking toolchain and or architecture support, static keys fall back to a
  * simple conditional branch.
  *
- * Additional babbling in: Documentation/static-keys.txt
+ * Additional babbling in: Documentation/static-keys.rst
  */
 
 #ifndef __ASSEMBLY__
diff --git a/include/linux/kobject.h b/include/linux/kobject.h
index 1ab0d624fb36..07c3f4329df0 100644
--- a/include/linux/kobject.h
+++ b/include/linux/kobject.h
@@ -7,7 +7,7 @@
  * Copyright (c) 2006-2008 Greg Kroah-Hartman <greg@kroah.com>
  * Copyright (c) 2006-2008 Novell Inc.
  *
- * Please read Documentation/kobject.txt before using the kobject
+ * Please read Documentation/kobject.rst before using the kobject
  * interface, ESPECIALLY the parts about reference counts and object
  * destructors.
  */
diff --git a/include/linux/kobject_ns.h b/include/linux/kobject_ns.h
index 069aa2ebef90..8c86c4641739 100644
--- a/include/linux/kobject_ns.h
+++ b/include/linux/kobject_ns.h
@@ -8,7 +8,7 @@
  *
  * Split from kobject.h by David Howells (dhowells@redhat.com)
  *
- * Please read Documentation/kobject.txt before using the kobject
+ * Please read Documentation/kobject.rst before using the kobject
  * interface, ESPECIALLY the parts about reference counts and object
  * destructors.
  */
diff --git a/include/linux/rbtree.h b/include/linux/rbtree.h
index fcbeed4053ef..ba33f7068c50 100644
--- a/include/linux/rbtree.h
+++ b/include/linux/rbtree.h
@@ -23,7 +23,7 @@
   I know it's not the cleaner way,  but in C (not in C++) to get
   performances and genericity...
 
-  See Documentation/rbtree.txt for documentation and samples.
+  See Documentation/rbtree.rst for documentation and samples.
 */
 
 #ifndef	_LINUX_RBTREE_H
diff --git a/include/linux/rbtree_augmented.h b/include/linux/rbtree_augmented.h
index 9510c677ac70..36dfacd9905c 100644
--- a/include/linux/rbtree_augmented.h
+++ b/include/linux/rbtree_augmented.h
@@ -33,7 +33,7 @@
  * rb_insert_augmented() and rb_erase_augmented() are intended to be public.
  * The rest are implementation details you are not expected to depend on.
  *
- * See Documentation/rbtree.txt for documentation and samples.
+ * See Documentation/rbtree.rst for documentation and samples.
  */
 
 struct rb_augment_callbacks {
diff --git a/include/media/videobuf-dma-sg.h b/include/media/videobuf-dma-sg.h
index 01bd142b979d..50a549e5b477 100644
--- a/include/media/videobuf-dma-sg.h
+++ b/include/media/videobuf-dma-sg.h
@@ -34,7 +34,7 @@
  *	does memory allocation too using vmalloc_32().
  *
  * videobuf_dma_*()
- *	see Documentation/DMA-API-HOWTO.txt, these functions to
+ *	see Documentation/DMA-API-HOWTO.rst, these functions to
  *	basically the same.  The map function does also build a
  *	scatterlist for the buffer (and unmap frees it ...)
  *
diff --git a/init/Kconfig b/init/Kconfig
index 70fa2d57ef49..448f8daa1204 100644
--- a/init/Kconfig
+++ b/init/Kconfig
@@ -1807,7 +1807,7 @@ config MMAP_ALLOW_UNINITIALIZED
 	  userspace.  Since that isn't generally a problem on no-MMU systems,
 	  it is normally safe to say Y here.
 
-	  See Documentation/nommu-mmap.txt for more information.
+	  See Documentation/nommu-mmap.rst for more information.
 
 config SYSTEM_DATA_VERIFICATION
 	def_bool n
diff --git a/kernel/dma/debug.c b/kernel/dma/debug.c
index a218e43cc382..37f33cfb7da2 100644
--- a/kernel/dma/debug.c
+++ b/kernel/dma/debug.c
@@ -1083,7 +1083,7 @@ static void check_unmap(struct dma_debug_entry *ref)
 	/*
 	 * Drivers should use dma_mapping_error() to check the returned
 	 * addresses of dma_map_single() and dma_map_page().
-	 * If not, print this warning message. See Documentation/DMA-API.txt.
+	 * If not, print this warning message. See Documentation/DMA-API.rst.
 	 */
 	if (entry->map_err_type == MAP_ERR_NOT_CHECKED) {
 		err_printk(ref->dev, entry,
diff --git a/kernel/padata.c b/kernel/padata.c
index 3e2633ae3bca..35123a3e9059 100644
--- a/kernel/padata.c
+++ b/kernel/padata.c
@@ -2,7 +2,7 @@
 /*
  * padata.c - generic interface to process data streams in parallel
  *
- * See Documentation/padata.txt for an api documentation.
+ * See Documentation/padata.rst for an api documentation.
  *
  * Copyright (C) 2008, 2009 secunet Security Networks AG
  * Copyright (C) 2008, 2009 Steffen Klassert <steffen.klassert@secunet.com>
diff --git a/lib/Kconfig b/lib/Kconfig
index fb453afff32e..7e050a759b3e 100644
--- a/lib/Kconfig
+++ b/lib/Kconfig
@@ -402,7 +402,7 @@ config INTERVAL_TREE
 
 	  See:
 
-		Documentation/rbtree.txt
+		Documentation/rbtree.rst
 
 	  for more information.
 
diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index aa05f47f5762..1c9edf887951 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -1662,7 +1662,7 @@ config PROVIDE_OHCI1394_DMA_INIT
 	  This code (~1k) is freed after boot. By then, the firewire stack
 	  in charge of the OHCI-1394 controllers should be used instead.
 
-	  See Documentation/debugging-via-ohci1394.txt for more information.
+	  See Documentation/debugging-via-ohci1394.rst for more information.
 
 menuconfig RUNTIME_TESTING_MENU
 	bool "Runtime Testing"
diff --git a/lib/crc32.c b/lib/crc32.c
index 4a20455d1f61..0de37ccc70dd 100644
--- a/lib/crc32.c
+++ b/lib/crc32.c
@@ -24,7 +24,7 @@
  * Version 2.  See the file COPYING for more details.
  */
 
-/* see: Documentation/crc32.txt for a description of algorithms */
+/* see: Documentation/crc32.rst for a description of algorithms */
 
 #include <linux/crc32.h>
 #include <linux/crc32poly.h>
diff --git a/lib/kobject.c b/lib/kobject.c
index aa89edcd2b63..c5870fae4ff3 100644
--- a/lib/kobject.c
+++ b/lib/kobject.c
@@ -6,7 +6,7 @@
  * Copyright (c) 2006-2007 Greg Kroah-Hartman <greg@kroah.com>
  * Copyright (c) 2006-2007 Novell Inc.
  *
- * Please see the file Documentation/kobject.txt for critical information
+ * Please see the file Documentation/kobject.rst for critical information
  * about using the kobject interface.
  */
 
@@ -639,7 +639,7 @@ static void kobject_cleanup(struct kobject *kobj)
 		 kobject_name(kobj), kobj, __func__, kobj->parent);
 
 	if (t && !t->release)
-		pr_debug("kobject: '%s' (%p): does not have a release() function, it is broken and must be fixed. See Documentation/kobject.txt.\n",
+		pr_debug("kobject: '%s' (%p): does not have a release() function, it is broken and must be fixed. See Documentation/kobject.rst.\n",
 			 kobject_name(kobj), kobj);
 
 	/* send "remove" if the caller did not do it but sent "add" */
diff --git a/lib/lzo/lzo1x_decompress_safe.c b/lib/lzo/lzo1x_decompress_safe.c
index 9e07e9ef1aad..a05ca85a64f9 100644
--- a/lib/lzo/lzo1x_decompress_safe.c
+++ b/lib/lzo/lzo1x_decompress_safe.c
@@ -31,7 +31,7 @@
  * depending on the base count. Since the base count is taken from a u8
  * and a few bits, it is safe to assume that it will always be lower than
  * or equal to 2*255, thus we can always prevent any overflow by accepting
- * two less 255 steps. See Documentation/lzo.txt for more information.
+ * two less 255 steps. See Documentation/lzo.rst for more information.
  */
 #define MAX_255_COUNT      ((((size_t)~0) / 255) - 2)
 
diff --git a/lib/xz/Kconfig b/lib/xz/Kconfig
index 12d2d777f36b..74f643b19f6a 100644
--- a/lib/xz/Kconfig
+++ b/lib/xz/Kconfig
@@ -4,7 +4,7 @@ config XZ_DEC
 	help
 	  LZMA2 compression algorithm and BCJ filters are supported using
 	  the .xz file format as the container. For integrity checking,
-	  CRC32 is supported. See Documentation/xz.txt for more information.
+	  CRC32 is supported. See Documentation/xz.rst for more information.
 
 if XZ_DEC
 
diff --git a/mm/Kconfig b/mm/Kconfig
index 96d199aa55fb..254246e66fba 100644
--- a/mm/Kconfig
+++ b/mm/Kconfig
@@ -370,7 +370,7 @@ config NOMMU_INITIAL_TRIM_EXCESS
 	  This option specifies the initial value of this option.  The default
 	  of 1 says that all excess pages should be trimmed.
 
-	  See Documentation/nommu-mmap.txt for more information.
+	  See Documentation/nommu-mmap.rst for more information.
 
 config TRANSPARENT_HUGEPAGE
 	bool "Transparent Hugepage Support"
diff --git a/mm/nommu.c b/mm/nommu.c
index b492fd1fcf9f..d7cf834b0746 100644
--- a/mm/nommu.c
+++ b/mm/nommu.c
@@ -4,7 +4,7 @@
  *  Replacement code for mm functions to support CPU's that don't
  *  have any form of memory management unit (thus no virtual memory).
  *
- *  See Documentation/nommu-mmap.txt
+ *  See Documentation/nommu-mmap.rst
  *
  *  Copyright (c) 2004-2008 David Howells <dhowells@redhat.com>
  *  Copyright (c) 2000-2003 David McCullough <davidm@snapgear.com>
diff --git a/samples/kprobes/kprobe_example.c b/samples/kprobes/kprobe_example.c
index 02be8984c32f..3be113db45fe 100644
--- a/samples/kprobes/kprobe_example.c
+++ b/samples/kprobes/kprobe_example.c
@@ -4,7 +4,7 @@
  * stack trace and selected registers when _do_fork() is called.
  *
  * For more information on theory of operation of kprobes, see
- * Documentation/kprobes.txt
+ * Documentation/kprobes.rst
  *
  * You will see the trace data in /var/log/messages and on the console
  * whenever _do_fork() is invoked to create a new process.
diff --git a/samples/kprobes/kretprobe_example.c b/samples/kprobes/kretprobe_example.c
index 7f9060f435cd..710889e7e5c0 100644
--- a/samples/kprobes/kretprobe_example.c
+++ b/samples/kprobes/kretprobe_example.c
@@ -10,7 +10,7 @@
  * If no func_name is specified, _do_fork is instrumented
  *
  * For more information on theory of operation of kretprobes, see
- * Documentation/kprobes.txt
+ * Documentation/kprobes.rst
  *
  * Build and insert the kernel module as done in the kprobe example.
  * You will see the trace data in /var/log/messages and on the console
diff --git a/scripts/gcc-plugins/Kconfig b/scripts/gcc-plugins/Kconfig
index 74271dba4f94..a58e83d3d64c 100644
--- a/scripts/gcc-plugins/Kconfig
+++ b/scripts/gcc-plugins/Kconfig
@@ -21,7 +21,7 @@ menuconfig GCC_PLUGINS
 	  GCC plugins are loadable modules that provide extra features to the
 	  compiler. They are useful for runtime instrumentation and static analysis.
 
-	  See Documentation/gcc-plugins.txt for details.
+	  See Documentation/gcc-plugins.rst for details.
 
 if GCC_PLUGINS
 
diff --git a/security/Kconfig b/security/Kconfig
index 353cfef71d4e..775f5bfe2cd3 100644
--- a/security/Kconfig
+++ b/security/Kconfig
@@ -120,7 +120,7 @@ config INTEL_TXT
 	  See <http://www.intel.com/technology/security/> for more information
 	  about Intel(R) TXT.
 	  See <http://tboot.sourceforge.net> for more information about tboot.
-	  See Documentation/intel_txt.txt for a description of how to enable
+	  See Documentation/intel_txt.rst for a description of how to enable
 	  Intel TXT support in a kernel boot.
 
 	  If you are unsure as to whether this is required, answer N.
diff --git a/tools/include/linux/rbtree.h b/tools/include/linux/rbtree.h
index 8e9ed4786269..617c4adb2caf 100644
--- a/tools/include/linux/rbtree.h
+++ b/tools/include/linux/rbtree.h
@@ -23,7 +23,7 @@
   I know it's not the cleaner way,  but in C (not in C++) to get
   performances and genericity...
 
-  See Documentation/rbtree.txt for documentation and samples.
+  See Documentation/rbtree.rst for documentation and samples.
 */
 
 #ifndef __TOOLS_LINUX_PERF_RBTREE_H
diff --git a/tools/include/linux/rbtree_augmented.h b/tools/include/linux/rbtree_augmented.h
index d008e1404580..ca544b017bc0 100644
--- a/tools/include/linux/rbtree_augmented.h
+++ b/tools/include/linux/rbtree_augmented.h
@@ -35,7 +35,7 @@
  * rb_insert_augmented() and rb_erase_augmented() are intended to be public.
  * The rest are implementation details you are not expected to depend on.
  *
- * See Documentation/rbtree.txt for documentation and samples.
+ * See Documentation/rbtree.rst for documentation and samples.
  */
 
 struct rb_augment_callbacks {
-- 
2.20.1

_______________________________________________
iommu mailing list
iommu@lists.linux-foundation.org
https://lists.linuxfoundation.org/mailman/listinfo/iommu

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Logan Gunthorpe]

On 2019-04-22 7:27 a.m., Mauro Carvalho Chehab wrote:

> 
> Later patches will move them to a better place and remove the
> :orphan: markup.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>
> ---
>  Documentation/ABI/removed/sysfs-class-rfkill  |  2 +-
>  Documentation/ABI/stable/sysfs-class-rfkill   |  2 +-
>  Documentation/ABI/stable/sysfs-devices-node   |  2 +-
>  Documentation/ABI/testing/procfs-diskstats    |  2 +-
>  Documentation/ABI/testing/sysfs-block         |  2 +-
>  .../ABI/testing/sysfs-class-switchtec         |  2 +-
>  .../ABI/testing/sysfs-devices-system-cpu      |  4 +-
>  .../{DMA-API-HOWTO.txt => DMA-API-HOWTO.rst}  |  2 +
>  Documentation/{DMA-API.txt => DMA-API.rst}    |  8 ++-
>  .../{DMA-ISA-LPC.txt => DMA-ISA-LPC.rst}      |  4 +-
>  ...{DMA-attributes.txt => DMA-attributes.rst} |  2 +
>  Documentation/{IPMI.txt => IPMI.rst}          |  2 +
>  .../{IRQ-affinity.txt => IRQ-affinity.rst}    |  2 +
>  .../{IRQ-domain.txt => IRQ-domain.rst}        |  2 +
>  Documentation/{IRQ.txt => IRQ.rst}            |  2 +
>  .../{Intel-IOMMU.txt => Intel-IOMMU.rst}      |  2 +
>  Documentation/PCI/pci.txt                     |  8 +--
>  Documentation/{SAK.txt => SAK.rst}            |  2 +
>  Documentation/{SM501.txt => SM501.rst}        |  2 +
>  .../admin-guide/kernel-parameters.txt         |  6 +-
>  Documentation/admin-guide/l1tf.rst            |  2 +-
>  .../{atomic_bitops.txt => atomic_bitops.rst}  |  2 +
>  Documentation/block/biodoc.txt                |  2 +-
>  .../{bt8xxgpio.txt => bt8xxgpio.rst}          |  2 +
>  Documentation/{btmrvl.txt => btmrvl.rst}      |  2 +
>  ...-mapping.txt => bus-virt-phys-mapping.rst} |  4 +-
>  ...g-warn-once.txt => clearing-warn-once.rst} |  2 +
>  Documentation/{cpu-load.txt => cpu-load.rst}  |  2 +
>  .../{cputopology.txt => cputopology.rst}      |  2 +
>  Documentation/{crc32.txt => crc32.rst}        |  2 +
>  Documentation/{dcdbas.txt => dcdbas.rst}      |  2 +
>  ...ging-modules.txt => debugging-modules.rst} |  2 +
>  ...hci1394.txt => debugging-via-ohci1394.rst} |  2 +
>  Documentation/{dell_rbu.txt => dell_rbu.rst}  |  2 +
>  Documentation/device-mapper/statistics.rst    |  4 +-
>  .../devicetree/bindings/phy/phy-bindings.txt  |  2 +-
>  Documentation/{digsig.txt => digsig.rst}      |  2 +
>  Documentation/driver-api/usb/dma.rst          |  6 +-
>  Documentation/driver-model/device.rst         |  2 +-
>  Documentation/{efi-stub.txt => efi-stub.rst}  |  2 +
>  Documentation/{eisa.txt => eisa.rst}          |  2 +
>  Documentation/fb/vesafb.rst                   |  2 +-
>  Documentation/filesystems/sysfs.txt           |  2 +-
>  ...ex-requeue-pi.txt => futex-requeue-pi.rst} |  2 +
>  .../{gcc-plugins.txt => gcc-plugins.rst}      |  2 +
>  Documentation/gpu/drm-mm.rst                  |  2 +-
>  Documentation/{highuid.txt => highuid.rst}    |  2 +
>  .../{hw_random.txt => hw_random.rst}          |  2 +
>  .../{hwspinlock.txt => hwspinlock.rst}        |  2 +
>  Documentation/ia64/IRQ-redir.txt              |  2 +-
>  .../{intel_txt.txt => intel_txt.rst}          |  2 +
>  .../{io-mapping.txt => io-mapping.rst}        |  2 +
>  .../{io_ordering.txt => io_ordering.rst}      |  2 +
>  Documentation/{iostats.txt => iostats.rst}    |  2 +
>  ...flags-tracing.txt => irqflags-tracing.rst} |  2 +
>  Documentation/{isa.txt => isa.rst}            |  2 +
>  Documentation/{isapnp.txt => isapnp.rst}      |  2 +
>  ...hreads.txt => kernel-per-CPU-kthreads.rst} |  4 +-
>  Documentation/{kobject.txt => kobject.rst}    |  4 +-
>  Documentation/{kprobes.txt => kprobes.rst}    |  2 +
>  Documentation/{kref.txt => kref.rst}          |  2 +
>  Documentation/laptops/thinkpad-acpi.txt       |  6 +-
>  Documentation/{ldm.txt => ldm.rst}            |  2 +
>  Documentation/locking/rt-mutex.rst            |  2 +-
>  ...kup-watchdogs.txt => lockup-watchdogs.rst} |  2 +
>  Documentation/{lsm.txt => lsm.rst}            |  2 +
>  Documentation/{lzo.txt => lzo.rst}            |  2 +
>  Documentation/{mailbox.txt => mailbox.rst}    |  2 +
>  Documentation/memory-barriers.txt             |  6 +-
>  ...hameleon-bus.txt => men-chameleon-bus.rst} |  2 +
>  Documentation/networking/scaling.rst          |  4 +-
>  .../{nommu-mmap.txt => nommu-mmap.rst}        |  2 +
>  Documentation/{ntb.txt => ntb.rst}            |  2 +
>  Documentation/{numastat.txt => numastat.rst}  |  2 +
>  Documentation/{padata.txt => padata.rst}      |  2 +
>  ...port-lowlevel.txt => parport-lowlevel.rst} |  2 +
>  ...-semaphore.txt => percpu-rw-semaphore.rst} |  2 +
>  Documentation/{phy.txt => phy.rst}            |  2 +
>  Documentation/{pi-futex.txt => pi-futex.rst}  |  2 +
>  Documentation/{pnp.txt => pnp.rst}            |  2 +
>  ...reempt-locking.txt => preempt-locking.rst} |  2 +
>  Documentation/{pwm.txt => pwm.rst}            |  2 +
>  Documentation/{rbtree.txt => rbtree.rst}      |  2 +
>  .../{remoteproc.txt => remoteproc.rst}        |  4 +-
>  Documentation/{rfkill.txt => rfkill.rst}      |  2 +
>  ...ust-futex-ABI.txt => robust-futex-ABI.rst} |  2 +
>  ...{robust-futexes.txt => robust-futexes.rst} |  2 +
>  Documentation/{rpmsg.txt => rpmsg.rst}        |  2 +
>  Documentation/{rtc.txt => rtc.rst}            |  2 +
>  Documentation/s390/vfio-ccw.rst               |  6 +-
>  Documentation/{sgi-ioc4.txt => sgi-ioc4.rst}  |  2 +
>  Documentation/{siphash.txt => siphash.rst}    |  2 +
>  .../{smsc_ece1099.txt => smsc_ece1099.rst}    |  2 +
>  .../{speculation.txt => speculation.rst}      |  2 +
>  .../{static-keys.txt => static-keys.rst}      |  2 +
>  Documentation/{svga.txt => svga.rst}          |  2 +
>  .../{switchtec.txt => switchtec.rst}          |  4 +-

For all the switchtec changes:

Acked-by: Logan Gunthorpe <logang-OTvnGxWRz7hWk0Htik3J/w@public.gmane.org>

Thanks,

Logan

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Peter Zijlstra]

On Mon, Apr 22, 2019 at 10:27:45AM -0300, Mauro Carvalho Chehab wrote:

>  .../{atomic_bitops.txt => atomic_bitops.rst}  |  2 +

What's happend to atomic_t.txt, also NAK, I still occationally touch
these files.

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mike Snitzer]

On Tue, Apr 23 2019 at  4:31am -0400,
Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:

> On Mon, Apr 22, 2019 at 10:27:45AM -0300, Mauro Carvalho Chehab wrote:
> 
> >  .../{atomic_bitops.txt => atomic_bitops.rst}  |  2 +
> 
> What's happend to atomic_t.txt, also NAK, I still occationally touch
> these files.

Seems Mauro's point is in the future we need to touch these .rst files
in terms of ReST compatible changes.

I'm dreading DM documentation changes in the future.. despite Mauro and
Jon Corbet informing me that ReST is simple, etc.

Mike

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Peter Zijlstra]

On Tue, Apr 23, 2019 at 08:55:19AM -0400, Mike Snitzer wrote:
> On Tue, Apr 23 2019 at  4:31am -0400,
> Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:
> 
> > On Mon, Apr 22, 2019 at 10:27:45AM -0300, Mauro Carvalho Chehab wrote:
> > 
> > >  .../{atomic_bitops.txt => atomic_bitops.rst}  |  2 +
> > 
> > What's happend to atomic_t.txt, also NAK, I still occationally touch
> > these files.
> 
> Seems Mauro's point is in the future we need to touch these .rst files
> in terms of ReST compatible changes.
> 
> I'm dreading DM documentation changes in the future.. despite Mauro and
> Jon Corbet informing me that ReST is simple, etc.

Well, it _can_ be simple, I've seen examples of rst that were not far
from generated HTML contents. And I must give Jon credit for not
accepting that atrocious crap.

But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
give me anything in return. There is no upside, only worse text files :/

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mike Snitzer]

On Tue, Apr 23 2019 at  9:01am -0400,
Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:

> On Tue, Apr 23, 2019 at 08:55:19AM -0400, Mike Snitzer wrote:
> > On Tue, Apr 23 2019 at  4:31am -0400,
> > Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:
> > 
> > > On Mon, Apr 22, 2019 at 10:27:45AM -0300, Mauro Carvalho Chehab wrote:
> > > 
> > > >  .../{atomic_bitops.txt => atomic_bitops.rst}  |  2 +
> > > 
> > > What's happend to atomic_t.txt, also NAK, I still occationally touch
> > > these files.
> > 
> > Seems Mauro's point is in the future we need to touch these .rst files
> > in terms of ReST compatible changes.
> > 
> > I'm dreading DM documentation changes in the future.. despite Mauro and
> > Jon Corbet informing me that ReST is simple, etc.
> 
> Well, it _can_ be simple, I've seen examples of rst that were not far
> from generated HTML contents. And I must give Jon credit for not
> accepting that atrocious crap.
> 
> But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
> give me anything in return. There is no upside, only worse text files :/

Right, but these changes aren't meant for our benefit.  They are for
users who get cleaner web accessible Linux kernel docs.  Seems the
decision has been made that the users' benefit, and broader
modernization of Linux docs, outweighs the inconvenience for engineers
who maintain the content of said documentation.

This kind of thing happens a lot these days: pile on engineers, they can
take it :/

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mauro Carvalho Chehab]

Em Tue, 23 Apr 2019 09:21:00 -0400
Mike Snitzer <snitzer-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org> escreveu:

> On Tue, Apr 23 2019 at  9:01am -0400,
> Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:
> 
> > On Tue, Apr 23, 2019 at 08:55:19AM -0400, Mike Snitzer wrote:  
> > > On Tue, Apr 23 2019 at  4:31am -0400,
> > > Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:
> > >   
> > > > On Mon, Apr 22, 2019 at 10:27:45AM -0300, Mauro Carvalho Chehab wrote:
> > > >   
> > > > >  .../{atomic_bitops.txt => atomic_bitops.rst}  |  2 +  
> > > > 
> > > > What's happend to atomic_t.txt, also NAK, I still occationally touch
> > > > these files.  
> > > 
> > > Seems Mauro's point is in the future we need to touch these .rst files
> > > in terms of ReST compatible changes.
> > > 
> > > I'm dreading DM documentation changes in the future.. despite Mauro and
> > > Jon Corbet informing me that ReST is simple, etc.  

ReST is simple[1], and neither Jon or me wants to burden developers to
use complex documents all over the Kernel tree. ReST is just a way to 
make the documents with similar visual. The main advantage of ReST is
that documents can be better organized, as they will be inside some
index.rst file.

[1] Ok, as any document, you could write an easy or hard to read stuff.
The way we're using on most places is to be just a coding style with
benefits. I wrote a quick 101 guide to ReST at the end, with all you
probably need to know about it.

So, for example, in the specific case of atomic_bitops, all it takes for
it to be parsed by Sphinx is to rename it to .rst. With that, it can be
added into an index.rst file, like at Documentation/driver-api/index.rst.

The document, as is, will be displayed like this:

	https://www.infradead.org/~mchehab/rst_conversion/driver-api/atomic_bitops.html?highlight=atomic_t

And the original text file can also be seen from the output data:

	https://www.infradead.org/~mchehab/rst_conversion/_sources/driver-api/atomic_bitops.rst.txt

> > 
> > Well, it _can_ be simple, I've seen examples of rst that were not far
> > from generated HTML contents. And I must give Jon credit for not
> > accepting that atrocious crap.
> > 
> > But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
> > give me anything in return. There is no upside, only worse text files :/  
> 
> Right, but these changes aren't meant for our benefit.  They are for
> users who get cleaner web accessible Linux kernel docs.  Seems the
> decision has been made that the users' benefit, and broader
> modernization of Linux docs, outweighs the inconvenience for engineers
> who maintain the content of said documentation.

> This kind of thing happens a lot these days: pile on engineers, they can
> take it :/

Yes, that's the main goal: ensure that more people will see the
documents and write less crappy code. So, overall, reducing the
time we spent with reviews of bad code.


----

=================================
My 101 ReST quick reference guide
=================================

Basically, a "quick" ReST guide for those that don't want to learn it
and like to have an easy to read text document would be

1) to format documents like:

	=========
	Doc Title
	=========

	foo chapter
	===========

	bar section
	-----------

	foobar sub-section
	^^^^^^^^^^^^^^^^^^

	foobarzeta sub-sub-section
	..........................

(the actual character used to mark the titles can be different,
provided that you use the same character for the same title
level - the above is just the way *I* use, as it makes easier for
me to remember the title level).

2) remember that ReST considers new lines with same indentation as
   belonging to the same paragraph. So,

	foo
	bar

is identical to:

	foo bar

while
	foo
	   bar

will make "foo" bold, and write bar on the next line. So, if you
want to have them on two separate lines on its output, it should
be either write it as:

	foo

	bar

or you could use a list:

	- foo
	- bar

Btw, *a lot* of Kernel documents already have the above format.

3) literal values should be either inside ``foo``, `foo` or on an
   indented line after a ::, like:

	example::

		# some_command_to_be_typed

If you follow those three simple rules, your document will be properly
parsed. The above covers 90% of what we normally use.

Tables are also easy to write there, as it recognizes two ways to write
ascii tables, with are already popular ways to write them.

So, those are valid tables:

Without a title:

	===   ===============
	foo   foo description
	bar   bar description
	===   ===============


	+-------+-----------------+
	| foo   | foo description |
	+-------+-----------------+
	| bar   | bar description |
	+-------+-----------------+

(both will produce exactly the same output)

With a title:

	===== ===============
	field description
	===== ===============
	foo   foo description
	bar   bar description
	===   ===============

	+-------+-----------------+
	| field | description     |
	+=======+=================+
	| foo   | foo description |
	+-------+-----------------+
	| bar   | bar description |
	+-------+-----------------+

(both will produce exactly the same output)

This is not too different on what we usually do on documents - except that
some documents sometimes use UTF8, or a different character set to mark the
table lines. So the "conversion" is simply to follow one of the above
styles.

Thanks,
Mauro

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Jonathan Corbet]

On Tue, 23 Apr 2019 15:01:32 +0200
Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:

> But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
> give me anything in return. There is no upside, only worse text files :/

So I believe it gives even you one thing in return: documentation that is
more accessible for both readers and authors.  More readable docs should
lead to more educated developers who understand the code better.  More
writable docs will bring more people in to help to improve them.  The
former effect has been reported in the GPU community, where they say that
the quality of submissions has improved along with the docs.  The latter
can be observed in the increased number of people working on the docs
overall, something that Linus noted in the 5.1-rc1 announcement.

Hopefully that's worth something :)

Thanks,

jon

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Peter Zijlstra]

On Tue, Apr 23, 2019 at 10:30:53AM -0600, Jonathan Corbet wrote:
> On Tue, 23 Apr 2019 15:01:32 +0200
> Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:
> 
> > But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
> > give me anything in return. There is no upside, only worse text files :/
> 
> So I believe it gives even you one thing in return: documentation that is
> more accessible for both readers and authors.

I know I'm an odd duck; but no. They're _less_ accessible for me, as
both a reader and author. They look 'funny' when read as a text file
(the only way it makes sense to read them; I spend 99% of my time on a
computer looking at monospace text interfaces; mutt, vim and console, in
that approximate order).

When writing, I now have to be bothered about this format crap over just
trying to write a coherent document.

Look at crap like this:

"The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`,
:c:func:`kmem_cache_alloc` and"

That should've been written like:

"The memory allocations via kmalloc(), vmalloc(), kmem_cache_alloc()
and"

Heck, that paragraph isn't even properly flowed.

Then there's the endless stuck ':' key, and the mysterious "''" because
\" isn't a character, oh wait.

Bah..

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Borislav Petkov]

On Tue, Apr 23, 2019 at 07:11:58PM +0200, Peter Zijlstra wrote:
> I know I'm an odd duck; but no. They're _less_ accessible for me, as
> both a reader and author. They look 'funny' when read as a text file
> (the only way it makes sense to read them; I spend 99% of my time on a
> computer looking at monospace text interfaces; mutt, vim and console, in
> that approximate order).

+1

It is probably fine to stare at them here
https://www.kernel.org/doc/html/latest/ and the end result is good
for showing them in browsers but after this conversion, it is
getting more and more painful to work with those files. For example,
Documentation/x86/x86_64/mm.txt we use a lot. I'd hate it if I had to go
sort out rest muck first just so that I can read it.

I think we can simply leave some text files be text files and be done
with it.

-- 
Regards/Gruss,
    Boris.

Good mailing practices for 400: avoid top-posting and trim the reply.

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mauro Carvalho Chehab]

Em Tue, 23 Apr 2019 19:20:06 +0200
Borislav Petkov <bp-Gina5bIWoIWzQB+pC5nmwQ@public.gmane.org> escreveu:

> On Tue, Apr 23, 2019 at 07:11:58PM +0200, Peter Zijlstra wrote:
> > I know I'm an odd duck; but no. They're _less_ accessible for me, as
> > both a reader and author. They look 'funny' when read as a text file
> > (the only way it makes sense to read them; I spend 99% of my time on a
> > computer looking at monospace text interfaces; mutt, vim and console, in
> > that approximate order).  
> 
> +1
> 
> It is probably fine to stare at them here
> https://www.kernel.org/doc/html/latest/ and the end result is good
> for showing them in browsers but after this conversion, it is
> getting more and more painful to work with those files. For example,
> Documentation/x86/x86_64/mm.txt we use a lot. I'd hate it if I had to go
> sort out rest muck first just so that I can read it.

That's my view about how that specific file would be after
converted to ReST:

	https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/x86/x86_64/mm.rst?h=convert_rst_renames

I don't have any troubles reading/understanding it as a plain text
file, and its html output is also nice (although Sphinx 1.7.8 seems to
have some issues when parsing some cells - probably due to some bug):

	https://www.infradead.org/~mchehab/rst_conversion/x86/x86_64/mm.html

> 
> I think we can simply leave some text files be text files and be done
> with it.

Changbin's approach was somewhat close to what you want. He simply
prepended the tables with ::, in order to show them as plain old
ascii:

	https://lore.kernel.org/lkml/20190423162932.21428-60-changbin.du-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org/

Both equally works, from ReST conversion PoV. I'm fine ether way.

I prefer my approach, as, IMHO, it is visually nicer on both text and
html versions, but his approach is likely easier to maintain, as doing
ascii artwork by hand is sometimes painful.

Thanks,
Mauro

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Borislav Petkov]

On Tue, Apr 23, 2019 at 05:05:02PM -0300, Mauro Carvalho Chehab wrote:
> That's my view about how that specific file would be after
> converted to ReST:
> 
> 	https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/x86/x86_64/mm.rst?h=convert_rst_renames
> 
> I don't have any troubles reading/understanding it as a plain text
> file,

If that is all the changes it would need, then I guess that's ok. Btw,
those rst-conversion patches don't really show what got changed. Dunno
if git can even show that properly. I diffed the two files by hand to
see what got changed, see end of mail.

So I guess if table in rst means, one needs to draw rows and columns, I
guess that's ok. It's not like I have to do it every day.

But exactly this - *having* to do rst formatting would mean a lot of
getting used to and people writing something which is not necessarily
correct rst and someone else fixing up after them.

Another pain point is changing the file paths. Without cscope I would've
been cursing each time I'm looking for kernel-parameters.txt, for
example. First of all, it is in Documentation/admin-guide/ now and then
there's Documentation/admin-guide/kernel-parameters.rst too.

I guess the .rst sucks in the .txt file and shows it monospaced. Oh
well.

So* I'd suggest having as less markup in those files as possible and if
it is needed, automate adding the needed markup, as Jon suggested.

The perfect example was the one which Peter gave and I had to paste in a
thread today:

"The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`,
:c:func:`kmem_cache_alloc` and"

That is very unreadable.

Anyway, stuff like that. Just giving my feedback here in case you're
interested. :-)

> and its html output is also nice (although Sphinx 1.7.8 seems to
> have some issues when parsing some cells - probably due to some bug):
> 
> 	https://www.infradead.org/~mchehab/rst_conversion/x86/x86_64/mm.html

I don't know how that looks in your browser but in mine those addresses
are not in monospaced font and there's no properly reading them.

And yap, the cells parsing fun I see too.

> Changbin's approach was somewhat close to what you want. He simply
> prepended the tables with ::, in order to show them as plain old
> ascii:
> 
> 	https://lore.kernel.org/lkml/20190423162932.21428-60-changbin.du-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org/

Yap, that's better.

I mean, the file is just as readable in plain old ASCII, if not even
more so. At least to me but I prefer simple things so...

> 
> Both equally works, from ReST conversion PoV. I'm fine ether way.
> 
> I prefer my approach, as, IMHO, it is visually nicer on both text and
> html versions, but his approach is likely easier to maintain, as doing
> ascii artwork by hand is sometimes painful.

Yap.

Thx.

---
--- mm.old	2019-04-23 23:18:55.954335784 +0200
+++ mm.new	2019-04-23 23:18:48.122335821 +0200
@@ -18,51 +18,68 @@ Notes:
    notation than "16 EB", which few will recognize at first sight as 16 exabytes.
    It also shows it nicely how incredibly large 64-bit address space is.
 
-========================================================================================================================
-    Start addr    |   Offset   |     End addr     |  Size   | VM area description
-========================================================================================================================
-                  |            |                  |         |
- 0000000000000000 |    0       | 00007fffffffffff |  128 TB | user-space virtual memory, different per mm
-__________________|____________|__________________|_________|___________________________________________________________
-                  |            |                  |         |
- 0000800000000000 | +128    TB | ffff7fffffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical
-                  |            |                  |         |     virtual memory addresses up to the -128 TB
-                  |            |                  |         |     starting offset of kernel mappings.
-__________________|____________|__________________|_________|___________________________________________________________
-                                                            |
-                                                            | Kernel-space virtual memory, shared between all processes:
-____________________________________________________________|___________________________________________________________
-                  |            |                  |         |
- ffff800000000000 | -128    TB | ffff87ffffffffff |    8 TB | ... guard hole, also reserved for hypervisor
- ffff880000000000 | -120    TB | ffff887fffffffff |  0.5 TB | LDT remap for PTI
- ffff888000000000 | -119.5  TB | ffffc87fffffffff |   64 TB | direct mapping of all physical memory (page_offset_base)
- ffffc88000000000 |  -55.5  TB | ffffc8ffffffffff |  0.5 TB | ... unused hole
- ffffc90000000000 |  -55    TB | ffffe8ffffffffff |   32 TB | vmalloc/ioremap space (vmalloc_base)
- ffffe90000000000 |  -23    TB | ffffe9ffffffffff |    1 TB | ... unused hole
- ffffea0000000000 |  -22    TB | ffffeaffffffffff |    1 TB | virtual memory map (vmemmap_base)
- ffffeb0000000000 |  -21    TB | ffffebffffffffff |    1 TB | ... unused hole
- ffffec0000000000 |  -20    TB | fffffbffffffffff |   16 TB | KASAN shadow memory
-__________________|____________|__________________|_________|____________________________________________________________
-                                                            |
-                                                            | Identical layout to the 56-bit one from here on:
-____________________________________________________________|____________________________________________________________
-                  |            |                  |         |
- fffffc0000000000 |   -4    TB | fffffdffffffffff |    2 TB | ... unused hole
-                  |            |                  |         | vaddr_end for KASLR
- fffffe0000000000 |   -2    TB | fffffe7fffffffff |  0.5 TB | cpu_entry_area mapping
- fffffe8000000000 |   -1.5  TB | fffffeffffffffff |  0.5 TB | ... unused hole
- ffffff0000000000 |   -1    TB | ffffff7fffffffff |  0.5 TB | %esp fixup stacks
- ffffff8000000000 | -512    GB | ffffffeeffffffff |  444 GB | ... unused hole
- ffffffef00000000 |  -68    GB | fffffffeffffffff |   64 GB | EFI region mapping space
- ffffffff00000000 |   -4    GB | ffffffff7fffffff |    2 GB | ... unused hole
- ffffffff80000000 |   -2    GB | ffffffff9fffffff |  512 MB | kernel text mapping, mapped to physical address 0
- ffffffff80000000 |-2048    MB |                  |         |
- ffffffffa0000000 |-1536    MB | fffffffffeffffff | 1520 MB | module mapping space
- ffffffffff000000 |  -16    MB |                  |         |
-    FIXADDR_START | ~-11    MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset
- ffffffffff600000 |  -10    MB | ffffffffff600fff |    4 kB | legacy vsyscall ABI
- ffffffffffe00000 |   -2    MB | ffffffffffffffff |    2 MB | ... unused hole
-__________________|____________|__________________|_________|___________________________________________________________
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|   Start addr    |   Offset   |     End addr     |  Size   | VM area description                                       |
++=================+============+==================+=========+===========================================================+
+|                 |            |                  |         |                                                           |
+|0000000000000000 |    0       | 00007fffffffffff |  128 TB | user-space virtual memory, different per mm               |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|                 |            |                  |         |                                                           |
+|0000800000000000 | +128    TB | ffff7fffffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical       |
+|                 |            |                  |         | virtual memory addresses up to the -128 TB                |
+|                 |            |                  |         | starting offset of kernel mappings.                       |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|                      **Kernel-space virtual memory, shared between all processes:**                                   |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffff800000000000 | -128    TB | ffff87ffffffffff |    8 TB | ... guard hole, also reserved for hypervisor              |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffff880000000000 | -120    TB | ffff887fffffffff |  0.5 TB | LDT remap for PTI                                         |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffff888000000000 | -119.5  TB | ffffc87fffffffff |   64 TB | direct mapping of all physical memory (page_offset_base)  |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffc88000000000 |  -55.5  TB | ffffc8ffffffffff |  0.5 TB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffc90000000000 |  -55    TB | ffffe8ffffffffff |   32 TB | vmalloc/ioremap space (vmalloc_base)                      |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffe90000000000 |  -23    TB | ffffe9ffffffffff |    1 TB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffea0000000000 |  -22    TB | ffffeaffffffffff |    1 TB | virtual memory map (vmemmap_base)                         |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffeb0000000000 |  -21    TB | ffffebffffffffff |    1 TB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffec0000000000 |  -20    TB | fffffbffffffffff |   16 TB | KASAN shadow memory                                       |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|                         **Identical layout to the 56-bit one from here on:**                                          |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|fffffc0000000000 |   -4    TB | fffffdffffffffff |    2 TB | ... unused hole                                           |
+|                 |            |                  |         | vaddr_end for KASLR                                       |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|fffffe0000000000 |   -2    TB | fffffe7fffffffff |  0.5 TB | cpu_entry_area mapping                                    |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|fffffe8000000000 |   -1.5  TB | fffffeffffffffff |  0.5 TB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffff0000000000 |   -1    TB | ffffff7fffffffff |  0.5 TB | %esp fixup stacks                                         |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffff8000000000 | -512    GB | ffffffeeffffffff |  444 GB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffef00000000 |  -68    GB | fffffffeffffffff |   64 GB | EFI region mapping space                                  |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffff00000000 |   -4    GB | ffffffff7fffffff |    2 GB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffff80000000 |   -2    GB | ffffffff9fffffff |  512 MB | kernel text mapping, mapped to physical address 0         |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffff80000000 |-2048    MB |                  |         |                                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffffa0000000 |-1536    MB | fffffffffeffffff | 1520 MB | module mapping space                                      |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffffff000000 |  -16    MB |                  |         |                                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|   FIXADDR_START | ~-11    MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset    |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffffff600000 |  -10    MB | ffffffffff600fff |    4 kB | legacy vsyscall ABI                                       |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffffffe00000 |   -2    MB | ffffffffffffffff |    2 MB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
 
 
 ====================================================
@@ -76,51 +93,66 @@ Notes:
    offset and many of the regions expand to support the much larger physical
    memory supported.
 
-========================================================================================================================
-    Start addr    |   Offset   |     End addr     |  Size   | VM area description
-========================================================================================================================
-                  |            |                  |         |
- 0000000000000000 |    0       | 00ffffffffffffff |   64 PB | user-space virtual memory, different per mm
-__________________|____________|__________________|_________|___________________________________________________________
-                  |            |                  |         |
- 0100000000000000 |  +64    PB | feffffffffffffff | ~16K PB | ... huge, still almost 64 bits wide hole of non-canonical
-                  |            |                  |         |     virtual memory addresses up to the -64 PB
-                  |            |                  |         |     starting offset of kernel mappings.
-__________________|____________|__________________|_________|___________________________________________________________
-                                                            |
-                                                            | Kernel-space virtual memory, shared between all processes:
-____________________________________________________________|___________________________________________________________
-                  |            |                  |         |
- ff00000000000000 |  -64    PB | ff0fffffffffffff |    4 PB | ... guard hole, also reserved for hypervisor
- ff10000000000000 |  -60    PB | ff10ffffffffffff | 0.25 PB | LDT remap for PTI
- ff11000000000000 |  -59.75 PB | ff90ffffffffffff |   32 PB | direct mapping of all physical memory (page_offset_base)
- ff91000000000000 |  -27.75 PB | ff9fffffffffffff | 3.75 PB | ... unused hole
- ffa0000000000000 |  -24    PB | ffd1ffffffffffff | 12.5 PB | vmalloc/ioremap space (vmalloc_base)
- ffd2000000000000 |  -11.5  PB | ffd3ffffffffffff |  0.5 PB | ... unused hole
- ffd4000000000000 |  -11    PB | ffd5ffffffffffff |  0.5 PB | virtual memory map (vmemmap_base)
- ffd6000000000000 |  -10.5  PB | ffdeffffffffffff | 2.25 PB | ... unused hole
- ffdf000000000000 |   -8.25 PB | fffffbffffffffff |   ~8 PB | KASAN shadow memory
-__________________|____________|__________________|_________|____________________________________________________________
-                                                            |
-                                                            | Identical layout to the 47-bit one from here on:
-____________________________________________________________|____________________________________________________________
-                  |            |                  |         |
- fffffc0000000000 |   -4    TB | fffffdffffffffff |    2 TB | ... unused hole
-                  |            |                  |         | vaddr_end for KASLR
- fffffe0000000000 |   -2    TB | fffffe7fffffffff |  0.5 TB | cpu_entry_area mapping
- fffffe8000000000 |   -1.5  TB | fffffeffffffffff |  0.5 TB | ... unused hole
- ffffff0000000000 |   -1    TB | ffffff7fffffffff |  0.5 TB | %esp fixup stacks
- ffffff8000000000 | -512    GB | ffffffeeffffffff |  444 GB | ... unused hole
- ffffffef00000000 |  -68    GB | fffffffeffffffff |   64 GB | EFI region mapping space
- ffffffff00000000 |   -4    GB | ffffffff7fffffff |    2 GB | ... unused hole
- ffffffff80000000 |   -2    GB | ffffffff9fffffff |  512 MB | kernel text mapping, mapped to physical address 0
- ffffffff80000000 |-2048    MB |                  |         |
- ffffffffa0000000 |-1536    MB | fffffffffeffffff | 1520 MB | module mapping space
- ffffffffff000000 |  -16    MB |                  |         |
-    FIXADDR_START | ~-11    MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset
- ffffffffff600000 |  -10    MB | ffffffffff600fff |    4 kB | legacy vsyscall ABI
- ffffffffffe00000 |   -2    MB | ffffffffffffffff |    2 MB | ... unused hole
-__________________|____________|__________________|_________|___________________________________________________________
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|   Start addr    |   Offset   |     End addr     |  Size   | VM area description                                       |
++=================+============+==================+=========+===========================================================+
+|0000000000000000 |    0       | 00ffffffffffffff |   64 PB | user-space virtual memory, different per mm               |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|0100000000000000 |  +64    PB | feffffffffffffff | ~16K PB | ... huge, still almost 64 bits wide hole of non-canonical |
+|                 |            |                  |         | virtual memory addresses up to the -64 PB                 |
+|                 |            |                  |         | starting offset of kernel mappings.                       |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|                       **Kernel-space virtual memory, shared between all processes:**                                  |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ff00000000000000 |  -64    PB | ff0fffffffffffff |    4 PB | ... guard hole, also reserved for hypervisor              |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ff10000000000000 |  -60    PB | ff10ffffffffffff | 0.25 PB | LDT remap for PTI                                         |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ff11000000000000 |  -59.75 PB | ff90ffffffffffff |   32 PB | direct mapping of all physical memory (page_offset_base)  |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ff91000000000000 |  -27.75 PB | ff9fffffffffffff | 3.75 PB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffa0000000000000 |  -24    PB | ffd1ffffffffffff | 12.5 PB | vmalloc/ioremap space (vmalloc_base)                      |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffd2000000000000 |  -11.5  PB | ffd3ffffffffffff |  0.5 PB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffd4000000000000 |  -11    PB | ffd5ffffffffffff |  0.5 PB | virtual memory map (vmemmap_base)                         |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffd6000000000000 |  -10.5  PB | ffdeffffffffffff | 2.25 PB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffdf000000000000 |   -8.25 PB | fffffbffffffffff |   ~8 PB | KASAN shadow memory                                       |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|                           **Identical layout to the 47-bit one from here on:**                                        |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|fffffc0000000000 |   -4    TB | fffffdffffffffff |    2 TB | ... unused hole                                           |
+|                 |            |                  |         | vaddr_end for KASLR                                       |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|fffffe0000000000 |   -2    TB | fffffe7fffffffff |  0.5 TB | cpu_entry_area mapping                                    |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|fffffe8000000000 |   -1.5  TB | fffffeffffffffff |  0.5 TB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffff0000000000 |   -1    TB | ffffff7fffffffff |  0.5 TB | %esp fixup stacks                                         |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffff8000000000 | -512    GB | ffffffeeffffffff |  444 GB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffef00000000 |  -68    GB | fffffffeffffffff |   64 GB | EFI region mapping space                                  |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffff00000000 |   -4    GB | ffffffff7fffffff |    2 GB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffff80000000 |   -2    GB | ffffffff9fffffff |  512 MB | kernel text mapping, mapped to physical address 0         |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffff80000000 |-2048    MB |                  |         |                                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffffa0000000 |-1536    MB | fffffffffeffffff | 1520 MB | module mapping space                                      |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffffff000000 |  -16    MB |                  |         |                                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|   FIXADDR_START | ~-11    MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset    |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffffff600000 |  -10    MB | ffffffffff600fff |    4 kB | legacy vsyscall ABI                                       |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
+|ffffffffffe00000 |   -2    MB | ffffffffffffffff |    2 MB | ... unused hole                                           |
++-----------------+------------+------------------+---------+-----------------------------------------------------------+
 
 Architecture defines a 64-bit virtual address. Implementations can support
 less. Currently supported are 48- and 57-bit virtual addresses. Bits 63

-- 
Regards/Gruss,
    Boris.

Good mailing practices for 400: avoid top-posting and trim the reply.

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Jonathan Corbet]

On Tue, 23 Apr 2019 23:38:16 +0200
Borislav Petkov <bp-Gina5bIWoIWzQB+pC5nmwQ@public.gmane.org> wrote:

> But exactly this - *having* to do rst formatting would mean a lot of
> getting used to and people writing something which is not necessarily
> correct rst and someone else fixing up after them.

Remember that most of our docs are 99% RST even though they were written
by people who had never even heard of RST.  I really don't think it's a
big deal - a far smaller cognitive load than trying to keep up with any
given subsystem's variable-declaration-ordering rules, for example :)

> Another pain point is changing the file paths. Without cscope I would've
> been cursing each time I'm looking for kernel-parameters.txt, for
> example. First of all, it is in Documentation/admin-guide/ now and then
> there's Documentation/admin-guide/kernel-parameters.rst too.

Moving of files has nothing to do with RST, of course.  That you can
blame entirely on me trying to bring some order to Documentation/.  As a
predecessor of mine once put it (https://lkml.org/lkml/2007/7/3/422):

	Documentation/* is a gigantic mess, currently organized based on
	where random passers-by put things down last.

When other parts of the kernel tree turn out to be organized in
less-than-useful ways, we move things around.  I'm trying to do the same
in Documentation/, with an attempt to be sympathetic toward our readers,
sort things by intended audience, and create (someday) a coherent whole.
I agree that moving docs is a short-term annoyance, but I'm hoping that
it brings a long-term benefit.

> So* I'd suggest having as less markup in those files as possible and if
> it is needed, automate adding the needed markup, as Jon suggested.

Minimal markup is the policy (it's even documented :).  Automating stuff
that can be automated is an area that has definitely not received
enough attention; hopefully some things can be done there in the very
near future.

Thanks,

jon

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Borislav Petkov]

On Tue, Apr 23, 2019 at 04:06:40PM -0600, Jonathan Corbet wrote:
> Remember that most of our docs are 99% RST even though they were written
> by people who had never even heard of RST.  I really don't think it's a
> big deal - a far smaller cognitive load than trying to keep up with any
> given subsystem's variable-declaration-ordering rules, for example :)

Tztztz, this thing seems to have hit a nerve with people. Which means, I
will enforce that even more now so that I annoy submitters more! :-P

See, I can do my own "RST" too. :-P

Srsly: ok, good. Sounds like we're on the same page then.

>  I'm trying to do the same in Documentation/, with an attempt to be
> sympathetic toward our readers, sort things by intended audience,
> and create (someday) a coherent whole. I agree that moving docs is
> a short-term annoyance, but I'm hoping that it brings a long-term
> benefit.

Ok, that's fair. I've been moving files too, in the past.

> Minimal markup is the policy (it's even documented :).  Automating stuff
> that can be automated is an area that has definitely not received
> enough attention; hopefully some things can be done there in the very
> near future.

Sounds nice, thanks Jon!

-- 
Regards/Gruss,
    Boris.

Good mailing practices for 400: avoid top-posting and trim the reply.

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Peter Zijlstra]

On Tue, Apr 23, 2019 at 11:38:16PM +0200, Borislav Petkov wrote:
> If that is all the changes it would need, then I guess that's ok. Btw,
> those rst-conversion patches don't really show what got changed. Dunno
> if git can even show that properly. I diffed the two files by hand to
> see what got changed, see end of mail.

That is not a happy diff; that table has gotten waay worse to read due
to all that extra table crap.

> ---
> --- mm.old	2019-04-23 23:18:55.954335784 +0200
> +++ mm.new	2019-04-23 23:18:48.122335821 +0200
> @@ -18,51 +18,68 @@ Notes:
>     notation than "16 EB", which few will recognize at first sight as 16 exabytes.
>     It also shows it nicely how incredibly large 64-bit address space is.
>  
> -========================================================================================================================
> -    Start addr    |   Offset   |     End addr     |  Size   | VM area description
> -========================================================================================================================
> -                  |            |                  |         |
> - 0000000000000000 |    0       | 00007fffffffffff |  128 TB | user-space virtual memory, different per mm
> -__________________|____________|__________________|_________|___________________________________________________________
> -                  |            |                  |         |
> - 0000800000000000 | +128    TB | ffff7fffffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical
> -                  |            |                  |         |     virtual memory addresses up to the -128 TB
> -                  |            |                  |         |     starting offset of kernel mappings.
> -__________________|____________|__________________|_________|___________________________________________________________
> -                                                            |
> -                                                            | Kernel-space virtual memory, shared between all processes:
> -____________________________________________________________|___________________________________________________________
> -                  |            |                  |         |
> - ffff800000000000 | -128    TB | ffff87ffffffffff |    8 TB | ... guard hole, also reserved for hypervisor
> - ffff880000000000 | -120    TB | ffff887fffffffff |  0.5 TB | LDT remap for PTI
> - ffff888000000000 | -119.5  TB | ffffc87fffffffff |   64 TB | direct mapping of all physical memory (page_offset_base)
> - ffffc88000000000 |  -55.5  TB | ffffc8ffffffffff |  0.5 TB | ... unused hole
> - ffffc90000000000 |  -55    TB | ffffe8ffffffffff |   32 TB | vmalloc/ioremap space (vmalloc_base)
> - ffffe90000000000 |  -23    TB | ffffe9ffffffffff |    1 TB | ... unused hole
> - ffffea0000000000 |  -22    TB | ffffeaffffffffff |    1 TB | virtual memory map (vmemmap_base)
> - ffffeb0000000000 |  -21    TB | ffffebffffffffff |    1 TB | ... unused hole
> - ffffec0000000000 |  -20    TB | fffffbffffffffff |   16 TB | KASAN shadow memory
> -__________________|____________|__________________|_________|____________________________________________________________
> -                                                            |
> -                                                            | Identical layout to the 56-bit one from here on:
> -____________________________________________________________|____________________________________________________________
> -                  |            |                  |         |
> - fffffc0000000000 |   -4    TB | fffffdffffffffff |    2 TB | ... unused hole
> -                  |            |                  |         | vaddr_end for KASLR
> - fffffe0000000000 |   -2    TB | fffffe7fffffffff |  0.5 TB | cpu_entry_area mapping
> - fffffe8000000000 |   -1.5  TB | fffffeffffffffff |  0.5 TB | ... unused hole
> - ffffff0000000000 |   -1    TB | ffffff7fffffffff |  0.5 TB | %esp fixup stacks
> - ffffff8000000000 | -512    GB | ffffffeeffffffff |  444 GB | ... unused hole
> - ffffffef00000000 |  -68    GB | fffffffeffffffff |   64 GB | EFI region mapping space
> - ffffffff00000000 |   -4    GB | ffffffff7fffffff |    2 GB | ... unused hole
> - ffffffff80000000 |   -2    GB | ffffffff9fffffff |  512 MB | kernel text mapping, mapped to physical address 0
> - ffffffff80000000 |-2048    MB |                  |         |
> - ffffffffa0000000 |-1536    MB | fffffffffeffffff | 1520 MB | module mapping space
> - ffffffffff000000 |  -16    MB |                  |         |
> -    FIXADDR_START | ~-11    MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset
> - ffffffffff600000 |  -10    MB | ffffffffff600fff |    4 kB | legacy vsyscall ABI
> - ffffffffffe00000 |   -2    MB | ffffffffffffffff |    2 MB | ... unused hole
> -__________________|____________|__________________|_________|___________________________________________________________
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|   Start addr    |   Offset   |     End addr     |  Size   | VM area description                                       |
> ++=================+============+==================+=========+===========================================================+
> +|                 |            |                  |         |                                                           |
> +|0000000000000000 |    0       | 00007fffffffffff |  128 TB | user-space virtual memory, different per mm               |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|                 |            |                  |         |                                                           |
> +|0000800000000000 | +128    TB | ffff7fffffffffff | ~16M TB | ... huge, almost 64 bits wide hole of non-canonical       |
> +|                 |            |                  |         | virtual memory addresses up to the -128 TB                |
> +|                 |            |                  |         | starting offset of kernel mappings.                       |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|                      **Kernel-space virtual memory, shared between all processes:**                                   |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffff800000000000 | -128    TB | ffff87ffffffffff |    8 TB | ... guard hole, also reserved for hypervisor              |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffff880000000000 | -120    TB | ffff887fffffffff |  0.5 TB | LDT remap for PTI                                         |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffff888000000000 | -119.5  TB | ffffc87fffffffff |   64 TB | direct mapping of all physical memory (page_offset_base)  |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffc88000000000 |  -55.5  TB | ffffc8ffffffffff |  0.5 TB | ... unused hole                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffc90000000000 |  -55    TB | ffffe8ffffffffff |   32 TB | vmalloc/ioremap space (vmalloc_base)                      |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffe90000000000 |  -23    TB | ffffe9ffffffffff |    1 TB | ... unused hole                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffea0000000000 |  -22    TB | ffffeaffffffffff |    1 TB | virtual memory map (vmemmap_base)                         |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffeb0000000000 |  -21    TB | ffffebffffffffff |    1 TB | ... unused hole                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffec0000000000 |  -20    TB | fffffbffffffffff |   16 TB | KASAN shadow memory                                       |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|                         **Identical layout to the 56-bit one from here on:**                                          |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|fffffc0000000000 |   -4    TB | fffffdffffffffff |    2 TB | ... unused hole                                           |
> +|                 |            |                  |         | vaddr_end for KASLR                                       |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|fffffe0000000000 |   -2    TB | fffffe7fffffffff |  0.5 TB | cpu_entry_area mapping                                    |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|fffffe8000000000 |   -1.5  TB | fffffeffffffffff |  0.5 TB | ... unused hole                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffff0000000000 |   -1    TB | ffffff7fffffffff |  0.5 TB | %esp fixup stacks                                         |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffff8000000000 | -512    GB | ffffffeeffffffff |  444 GB | ... unused hole                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffffef00000000 |  -68    GB | fffffffeffffffff |   64 GB | EFI region mapping space                                  |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffffff00000000 |   -4    GB | ffffffff7fffffff |    2 GB | ... unused hole                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffffff80000000 |   -2    GB | ffffffff9fffffff |  512 MB | kernel text mapping, mapped to physical address 0         |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffffff80000000 |-2048    MB |                  |         |                                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffffffa0000000 |-1536    MB | fffffffffeffffff | 1520 MB | module mapping space                                      |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffffffff000000 |  -16    MB |                  |         |                                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|   FIXADDR_START | ~-11    MB | ffffffffff5fffff | ~0.5 MB | kernel-internal fixmap range, variable size and offset    |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffffffff600000 |  -10    MB | ffffffffff600fff |    4 kB | legacy vsyscall ABI                                       |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+
> +|ffffffffffe00000 |   -2    MB | ffffffffffffffff |    2 MB | ... unused hole                                           |
> ++-----------------+------------+------------------+---------+-----------------------------------------------------------+

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mauro Carvalho Chehab]

Em Wed, 24 Apr 2019 08:52:09 +0200
Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> escreveu:

> On Tue, Apr 23, 2019 at 11:38:16PM +0200, Borislav Petkov wrote:
> > If that is all the changes it would need, then I guess that's ok. Btw,
> > those rst-conversion patches don't really show what got changed. Dunno
> > if git can even show that properly. I diffed the two files by hand to
> > see what got changed, see end of mail.  
> 
> That is not a happy diff; that table has gotten waay worse to read due
> to all that extra table crap.

Not that I'm proposing such change, but, as a reference, I just discovered 
today that there's a way to make it even lighter than it is while still
showing it as a table:

=================  ======== ==   ================  ===== ==  ===========================================================
    Start addr        Offset        End addr         Size    VM area description
-----------------  -----------   ----------------  --------  -----------------------------------------------------------
 0000000000000000      0         00007fffffffffff    128 TB   user-space virtual memory, different per mm

 0000800000000000   +128    TB   ffff7fffffffffff   ~16M TB   ... huge, almost 64 bits wide hole of non-canonical
                                                                  virtual memory addresses up to the -128 TB
                                                                  starting offset of kernel mappings.

-----------------  -------- --   ----------------  ----- --  -----------------------------------------------------------
-                                                            Kernel-space virtual memory, shared between all processes:
-----------------  -----------   ----------------  --------  -----------------------------------------------------------

 ffff800000000000   -128    TB   ffff87ffffffffff      8 TB   ... guard hole, also reserved for hypervisor
 ffff880000000000   -120    TB   ffff887fffffffff    0.5 TB   LDT remap for PTI
 ffff888000000000   -119.5  TB   ffffc87fffffffff     64 TB   direct mapping of all physical memory (page_offset_base)
 ffffc88000000000    -55.5  TB   ffffc8ffffffffff    0.5 TB   ... unused hole
 ffffc90000000000    -55    TB   ffffe8ffffffffff     32 TB   vmalloc/ioremap space (vmalloc_base)
 ffffe90000000000    -23    TB   ffffe9ffffffffff      1 TB   ... unused hole
 ffffea0000000000    -22    TB   ffffeaffffffffff      1 TB   virtual memory map (vmemmap_base)
 ffffeb0000000000    -21    TB   ffffebffffffffff      1 TB   ... unused hole
 ffffec0000000000    -20    TB   fffffbffffffffff     16 TB   KASAN shadow memory
-----------------  -------- --   ----------------  ----- --  -----------------------------------------------------------
-                                                            Identical layout to the 56-bit one from here on:
-----------------  -----------   ----------------  --------  -----------------------------------------------------------

 fffffc0000000000     -4    TB   fffffdffffffffff      2 TB   ... unused hole
                                                              vaddr_end for KASLR
 fffffe0000000000     -2    TB   fffffe7fffffffff    0.5 TB   cpu_entry_area mapping
 fffffe8000000000     -1.5  TB   fffffeffffffffff    0.5 TB   ... unused hole
 ffffff0000000000     -1    TB   ffffff7fffffffff    0.5 TB   %esp fixup stacks
 ffffff8000000000   -512    GB   ffffffeeffffffff    444 GB   ... unused hole
 ffffffef00000000    -68    GB   fffffffeffffffff     64 GB   EFI region mapping space
 ffffffff00000000     -4    GB   ffffffff7fffffff      2 GB   ... unused hole
 ffffffff80000000     -2    GB   ffffffff9fffffff    512 MB   kernel text mapping, mapped to physical address 0
 ffffffff80000000  -2048    MB
 ffffffffa0000000  -1536    MB   fffffffffeffffff   1520 MB   module mapping space
 ffffffffff000000    -16    MB
    FIXADDR_START   ~-11    MB   ffffffffff5fffff   ~0.5 MB   kernel-internal fixmap range, variable size and offset
 ffffffffff600000    -10    MB   ffffffffff600fff      4 kB   legacy vsyscall ABI
 ffffffffffe00000     -2    MB   ffffffffffffffff      2 MB   ... unused hole
=================  ======== ==   ================  ===== ==  ===========================================================

If one wants the table headers as such, an extra line is required:


=================  ======== ==   ================  ===== ==  ===========================================================
    Start addr        Offset        End addr         Size    VM area description
-----------------  -----------   ----------------  --------  -----------------------------------------------------------
=================  ======== ==   ================  ===== ==  ===========================================================

<snip/>

=================  ======== ==   ================  ===== ==  ===========================================================


The output using this approach and a markup to use mono-spaced cells
e. g. either using ..raw or using .. cssclass as commented before in
this thread is at:

	https://www.infradead.org/~mchehab/rst_conversion/x86/x86_64/mm_alternative.html

Just converted the first table, keeping the other as a literal block.

Thanks,
Mauro

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mauro Carvalho Chehab]

Em Tue, 23 Apr 2019 23:38:16 +0200
Borislav Petkov <bp-Gina5bIWoIWzQB+pC5nmwQ@public.gmane.org> escreveu:

> On Tue, Apr 23, 2019 at 05:05:02PM -0300, Mauro Carvalho Chehab wrote:
> > That's my view about how that specific file would be after
> > converted to ReST:
> > 
> > 	https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/x86/x86_64/mm.rst?h=convert_rst_renames
> > 
> > I don't have any troubles reading/understanding it as a plain text
> > file,  
> 
> If that is all the changes it would need, then I guess that's ok. Btw,
> those rst-conversion patches don't really show what got changed. Dunno
> if git can even show that properly. I diffed the two files by hand to
> see what got changed, see end of mail.

Well, you can use git show -M01 and it will likely show what
changed. The thing is that plain diff is not very good showing
diffs on text files. I suspect that using some tool like wdiff
would give a better view of such changes.

> So I guess if table in rst means, one needs to draw rows and columns, I
> guess that's ok. It's not like I have to do it every day.

Yes, for complex tables, one needs to draw rows/columns. For simple
tables, all you need to do is something like:

  ====== ========   ====    ========    ===
  -      CONT PTE    PMD    CONT PMD    PUD
  ====== ========   ====    ========    ===
  4K:         64K     2M         32M     1G
  16K:         2M    32M          1G
  64K:         2M   512M         16G
  ====== ========   ====    ========    ===

in order to teach Sphinx where each column starts/stops, and
(optionally) show the table titles in bold.

(that's from Documentation/arm64/hugetlbpage.rst conversion)

> But exactly this - *having* to do rst formatting would mean a lot of
> getting used to and people writing something which is not necessarily
> correct rst and someone else fixing up after them.

Yeah, one has to take the conversion effort, but once done, it should be
easy to keep it updated.

> > and its html output is also nice (although Sphinx 1.7.8 seems to
> > have some issues when parsing some cells - probably due to some bug):
> > 
> > 	https://www.infradead.org/~mchehab/rst_conversion/x86/x86_64/mm.html  
> 
> I don't know how that looks in your browser but in mine those addresses
> are not in monospaced font and there's no properly reading them.
> 
> And yap, the cells parsing fun I see too.

Font selection is one of the things would require some markup, as a
plain text file doesn't have font changes.

There are several ways to make it use a monospaced font.

The straight forward way would be to place everything that it is
monospaced inside ``double quotes``, with is the ReST way to mark
a literal block inside a text. IMHO, that would add too much
"noise" at the tables.

Another possibility would be to do:

	.. raw:: html

	       <head><style>td { font-family: monospace, monospace; }</style></head>

(the double monospace here is not a mistake - it is due to a known
bug^H^H^Hfeature on some browsers[1])

[1] https://stackoverflow.com/questions/38781089/font-family-monospace-monospace

IMO, the best alternative would be to add a new class to the css file,
and use it whenever we need a table with monospaced font, e. g.:

diff --git a/Documentation/sphinx-static/theme_overrides.css b/Documentation/sphinx-static/theme_overrides.css
index e21e36cd6761..0948de6651f8 100644
--- a/Documentation/sphinx-static/theme_overrides.css
+++ b/Documentation/sphinx-static/theme_overrides.css
@@ -125,3 +125,7 @@ div[class^="highlight"] pre {
         color: inherit;
     }
 }
+
+table.monospaced {
+	font-family: monospace, monospace;
+}
diff --git a/Documentation/x86/x86_64/mm.rst b/Documentation/x86/x86_64/mm.rst
index e8a92fa0f9b2..704bad5c5130 100644
--- a/Documentation/x86/x86_64/mm.rst
+++ b/Documentation/x86/x86_64/mm.rst
@@ -18,6 +18,8 @@ Notes:
    notation than "16 EB", which few will recognize at first sight as 16 exabytes.
    It also shows it nicely how incredibly large 64-bit address space is.
 
+.. cssclass:: monospaced
+
 +-----------------+------------+------------------+---------+-----------------------------------------------------------+
 |   Start addr    |   Offset   |     End addr     |  Size   | VM area description                                       |
 +=================+============+==================+=========+===========================================================+

(patch on the top of this tree
https://git.linuxtv.org/mchehab/experimental.git/tree/Documentation/x86/x86_64/mm.rst?h=convert_rst_renames)

The ..cssclass:: markup on the above example will be applied just to
the table below it. So, with that, it is possible to have normal and
monospaced tables mixed (if you apply the above patch, you'll see
that just the first table will use monospaced fonts).

- 

Personally, I don't care much with monospaced fonts on this table. After
all, if I want to see it monospaced, I can simply click at the
"View page source" at the browser, and it will display the file as a
plain old monospaced text file.

Thanks,
Mauro

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Borislav Petkov]

On Wed, Apr 24, 2019 at 07:40:07AM -0300, Mauro Carvalho Chehab wrote:
> Personally, I don't care much with monospaced fonts on this table. After
> all, if I want to see it monospaced, I can simply click at the
> "View page source" at the browser, and it will display the file as a
> plain old monospaced text file.

Goes to show why kernel people wouldn't want to look at that in
the browser. Long hex numbers are hard to read as it is - that's
why there's even the 4-digit separator in some docs, for example:
0xffff_ffff_8100_0000.

Not having it monospaced makes the whole thing even less readable.

That's why it is important for the markup not to get in the way of
people looking at those files in an editor.

-- 
Regards/Gruss,
    Boris.

Good mailing practices for 400: avoid top-posting and trim the reply.

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mauro Carvalho Chehab]

Em Wed, 24 Apr 2019 16:54:10 +0200
Borislav Petkov <bp-Gina5bIWoIWzQB+pC5nmwQ@public.gmane.org> escreveu:

> On Wed, Apr 24, 2019 at 07:40:07AM -0300, Mauro Carvalho Chehab wrote:
> > Personally, I don't care much with monospaced fonts on this table. After
> > all, if I want to see it monospaced, I can simply click at the
> > "View page source" at the browser, and it will display the file as a
> > plain old monospaced text file.  
> 
> Goes to show why kernel people wouldn't want to look at that in
> the browser. Long hex numbers are hard to read as it is - that's
> why there's even the 4-digit separator in some docs, for example:
> 0xffff_ffff_8100_0000.

IMHO, even the 0x and _ would make it harder to read. This is a way
more easy for my eyes:

	ffff ffff 8100 0000

> Not having it monospaced makes the whole thing even less readable.

Yeah, I see your point and agree with it.

Just saying that, if all I want is to check if addresses that start
with ffff80 belongs to the guard hole, or just to copy a value from 
a table into some C code, the font doesn't matter much, and, if
I care, a simple click would show it in monospaced fonts.

Looking from your PoV, something like:


|ffffffff80000000 |   -2    GB | ffffffff9fffffff |  512 MB | kernel text mapping, mapped to physical address 0         |


is very hard to be parsed by a human eye, even with monospaced fonts.
In order to make it easier, I would replace it by:

|ffff ffff 8000 0000 |   -2    GB | ffff ffff 9fff ffff |  512 MB | kernel text mapping, mapped to physical address 0         |


> 
> That's why it is important for the markup not to get in the way of
> people looking at those files in an editor.

Fully agreed. the markups should make things easier and not
harder for people to read its contents.

Thanks,
Mauro

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Jonathan Corbet]

On Tue, 23 Apr 2019 19:11:58 +0200
Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:

> When writing, I now have to be bothered about this format crap over just
> trying to write a coherent document.

Just write text, it'll all work out in the end :)

> Look at crap like this:
> 
> "The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`,
> :c:func:`kmem_cache_alloc` and"
> 
> That should've been written like:
> 
> "The memory allocations via kmalloc(), vmalloc(), kmem_cache_alloc()
> and"

Yeah, I get it.  That markup generates cross-references, which can be
seriously useful for readers - we want that.  But I do wonder if we
couldn't do it automatically with just a little bit of scripting work.
It's not to hard to recognize this_is_a_function(), after all.  I'll look
into that, it would definitely help to remove some gunk from the source
docs.

jon

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Peter Zijlstra]

On Tue, Apr 23, 2019 at 11:53:49AM -0600, Jonathan Corbet wrote:
> > Look at crap like this:
> > 
> > "The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`,
> > :c:func:`kmem_cache_alloc` and"
> > 
> > That should've been written like:
> > 
> > "The memory allocations via kmalloc(), vmalloc(), kmem_cache_alloc()
> > and"
> 
> Yeah, I get it.  That markup generates cross-references, which can be
> seriously useful for readers - we want that.

The funny thing is; that sentence continues (on a new line) like:

"friends are traced and the pointers, together with additional"

So while it then has cross-references to a few functions, all 'friends'
are left dangling. So what's the point of the cross-references?

Also, 'make ctags' and follow tag (ctrl-] for fellow vim users) will get
you to the function, no magic markup required.

> But I do wonder if we
> couldn't do it automatically with just a little bit of scripting work.
> It's not to hard to recognize this_is_a_function(), after all.  I'll look
> into that, it would definitely help to remove some gunk from the source
> docs.

That would be good; less markup is more.

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Mauro Carvalho Chehab]

Em Tue, 23 Apr 2019 11:53:49 -0600
Jonathan Corbet <corbet-T1hC0tSOHrs@public.gmane.org> escreveu:

> On Tue, 23 Apr 2019 19:11:58 +0200
> Peter Zijlstra <peterz-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org> wrote:
> 

> > Look at crap like this:
> > 
> > "The memory allocations via :c:func:`kmalloc`, :c:func:`vmalloc`,
> > :c:func:`kmem_cache_alloc` and"
> > 
> > That should've been written like:
> > 
> > "The memory allocations via kmalloc(), vmalloc(), kmem_cache_alloc()
> > and"  
> 
> Yeah, I get it.  That markup generates cross-references, which can be
> seriously useful for readers - we want that.  But I do wonder if we
> couldn't do it automatically with just a little bit of scripting work.
> It's not to hard to recognize this_is_a_function(), after all.  I'll look
> into that, it would definitely help to remove some gunk from the source
> docs.

While on it, one thing that I noticed on several documents is that
they reference other documents by their names. On this conversion,
I avoided replacing that by a :ref:`` tag or a :doc:`` tag. I only
added cross references on two cases:

	- a latex file that got converted to ReST and had such
	  cross-references already;

	- one of the document sets that seemed to be using some other
	  markup language very close to ReST, but with a different
	  cross-reference markup. So, I just converted it to use
	  the syntax that Sphinx would recognize.

Anyway, one of the things that occurred to me is that maybe
some scripting work or a ReST extension could do something to parse
"Documentation/foo" as :doc:`Documentation/foo` without needing to 
explicitly use any ReST specific tags.

Thanks,
Mauro

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Jonathan Corbet]

On Tue, 23 Apr 2019 17:19:44 -0300
Mauro Carvalho Chehab <mchehab+samsung-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org> wrote:

> Anyway, one of the things that occurred to me is that maybe
> some scripting work or a ReST extension could do something to parse
> "Documentation/foo" as :doc:`Documentation/foo` without needing to 
> explicitly use any ReST specific tags.

That probably makes sense too.  People do want to link to specific
subsections within documents, though; maybe we could allow
"Documentation/foo#bar" for that.  Such "markup" could even be useful for
people reading the plain-text files.

Thanks,

jon

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Wes Turner]

[-- Attachment #1: Type: text/plain, Size: 6607 bytes --]

- Accessible, usable docs are worth something in ROI
  - https://www.writethedocs.org/
  - https://read-the-docs.readthedocs.io/en/latest/
  -
https://github.com/rtfd/readthedocs-docker-images/issues/47#issuecomment-485712800
    - Dockerfile that extends from readthedocs/build:latest (which has the
GBs of latex necessary to run `make latexpdf` for all you PDF lovers out
there)

- https://github.com/yoloseem/awesome-sphinxdoc
  - There are various Sphinx extensions for optionally including generated
API docs for various languages
  - If you add the extensions you want installed to your requirements.txt
or environment.yml, ReadTheDocs will install those for every build. You can
also create (and maintain) a custom Docker image with all of the docs
building dependencies installed (e.g. requirements_dev.txt and/or
docs/requirements.txt)

- https://kernel.readthedocs.io/en/latest/kernel-documentation.html
  - This says "Copyright 2016"? That's set in conf.py

I keep a tools doc in ReST:
- https://westurner.github.io/tools/#sphinx
- https://westurner.github.io/tools/#docutils

I'll just CC those sections here:

```rst

.. index:: Docutils
.. _docutils:

Docutils
~~~~~~~~~~~~~~~~~~~
| Homepage: http://docutils.sourceforge.net
| PyPI: https://pypi.python.org/pypi/docutils
| Docs: http://docutils.sourceforge.net/docs/
| Docs: http://docutils.sourceforge.net/rst.html
| Docs: http://docutils.sourceforge.net/docs/ref/doctree.html
| Docs: https://docutils.readthedocs.io/en/sphinx-docs/
| Docs:
https://docutils.readthedocs.io/en/sphinx-docs/ref/rst/restructuredtext.html
| Src: svn http://svn.code.sf.net/p/docutils/code/trunk

Docutils is a :ref:`Python` library which 'parses" :ref:`ReStructuredText`
lightweight markup language into a doctree (~DOM)
which can be serialized into
HTML, ePub, MOBI, LaTeX, man pages,
Open Document files,
XML, JSON, and a number of other formats.

.. index:: Sphinx
.. _sphinx:

Sphinx
~~~~~~~~~~~~~~~~~
| Wikipedia: `<
https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)>`_
| Homepage: https://pypi.python.org/pypi/Sphinx
| Src: git https://github.com/sphinx-doc/sphinx
| Pypi: https://pypi.python.org/pypi/Sphinx
| Docs: http://sphinx-doc.org/contents.html
| Docs: http://sphinx-doc.org/markup/code.html
| Docs: http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role
| Docs: http://pygments.org/docs/lexers/
| Docs: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
| Docs: https://github.com/yoloseem/awesome-sphinxdoc


Sphinx is a tool for working with
:ref:`ReStructuredText` documentation trees
and rendering them into HTML, PDF, LaTeX, ePub,
and a number of other formats.

Sphinx extends :ref:`Docutils` with a number of useful markup behaviors
which are not supported by other ReStructuredText parsers.

Most other ReStructuredText parsers do not support Sphinx directives;
so, for example,

* GitHub and BitBucket do not support Sphinx but do support ReStructuredText
  so ``README.rst`` containing Sphinx tags renders in plaintext or raises
errors.

  For example, the index page of this
  :ref:`Sphinx` documentation set is generated from
  a file named ``index.rst`` that referenced by ``docs/conf.py``,
  which is utilized by ``sphinx-build`` in the ``Makefile``.

  * Input:

    .. code:: bash

      _indexrst="$WORKON_HOME/src/westurner/tools/index.rst"
      e $_indexrst

      # with westurner/dotfiles.venv
      mkvirtualenv westurner
      we westurner tools; mkdir -p $_SRC
      git clone ssh://git@github.com/westurner/tools
      cdw; e index.rst    # ew index.rst

    https://github.com/westurner/tools/blob/master/index.rst

    https://raw.githubusercontent.com/westurner/tools/master/index.rst



  * Output:

    .. code:: bash

      cd $_WRD                        # cdwrd; cdw
      git status; make <tab>          # gitw status; makew <tab>
      make html singlehtml            # make docs
      web ./_build/html/index.html    # make open

      make gh-pages       # ghp-import -n -p ./_build/html/ -b gh-pages
      make push           # gitw push <origin> <destbranch>

    https://github.com/westurner/tools/blob/gh-pages/index.html

    https://westurner.github.io/tools/


    * RawGit:

      dev/test: https://rawgit.com/westurner/tools/gh-pages/index.html

      CDN: https://cdn.rawgit.com/westurner/tools/gh-pages/index.html

  * Output: *ReadTheDocs*:

    https://<projectname>.readthedocs.io/en/<version>/

    https://read-the-docs.readthedocs.io/en/latest/


.. glossary::

   Sphinx Builder
      A Sphinx Builder transforms :ref:`ReStructuredText` into various
      output forms:

         * HTML
         * LaTeX
         * PDF
         * ePub
         * MOBI
         * JSON
         * OpenDocument (OpenOffice)
         * Office Open XML (MS Word)

      See: `Sphinx Builders <http://sphinx-doc.org/builders.html>`_

   Sphinx ReStructuredText
      Sphinx extends :ref:`ReStructuredText` with roles and directives
      which only work with Sphinx.

   Sphinx Directive
      Sphinx extensions of :ref:`Docutils` :ref:`ReStructuredText`
directives.

      Most other ReStructuredText parsers do not support Sphinx directives.

      .. code-block:: rest

         .. toctree::

            readme
            installation
            usage

      See: `Sphinx Directives <http://sphinx-doc.org/rest.html#directives>`_

   Sphinx Role
      Sphinx extensions of :ref:`Docutils` :ref:`RestructuredText` roles

      Most other ReStructuredText parsers do not support Sphinx directives.

      .. code-block:: rest

            .. _anchor-name:

            A link to :ref:`anchor <anchor-name>`.

```

On Tue, Apr 23, 2019 at 12:31 PM Jonathan Corbet <corbet@lwn.net> wrote:

> On Tue, 23 Apr 2019 15:01:32 +0200
> Peter Zijlstra <peterz@infradead.org> wrote:
>
> > But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
> > give me anything in return. There is no upside, only worse text files :/
>
> So I believe it gives even you one thing in return: documentation that is
> more accessible for both readers and authors.  More readable docs should
> lead to more educated developers who understand the code better.  More
> writable docs will bring more people in to help to improve them.  The
> former effect has been reported in the GPU community, where they say that
> the quality of submissions has improved along with the docs.  The latter
> can be observed in the increased number of people working on the docs
> overall, something that Linus noted in the 5.1-rc1 announcement.
>
> Hopefully that's worth something :)
>
> Thanks,
>
> jon
>

[-- Attachment #2: Type: text/html, Size: 10658 bytes --]

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Peter Zijlstra]

A: Because it messes up the order in which people normally read text.
Q: Why is top-posting such a bad thing?
A: Top-posting.
Q: What is the most annoying thing in e-mail?

Re: [PATCH v2 56/79] docs: Documentation/*.txt: rename all ReST files to *.rst

[Wes Turner]

[-- Attachment #1: Type: text/plain, Size: 4606 bytes --]

- Accessible, usable docs are worth something in ROI
  - https://www.writethedocs.org/
  - https://read-the-docs.readthedocs.io/en/latest/
  -
https://github.com/rtfd/readthedocs-docker-images/issues/47#issuecomment-485712800
    - Dockerfile that extends from readthedocs/build:latest (which has the
GBs of latex necessary to run `make latexpdf` for all you PDF lovers out
there)

- https://github.com/yoloseem/awesome-sphinxdoc
  - There are various Sphinx extensions for optionally including generated
API docs for various languages
  - If you add the extensions you want installed to your requirements.txt
or environment.yml, ReadTheDocs will install those for every build. You can
also create (and maintain) a custom Docker image with all of the docs
building dependencies installed (e.g. requirements_dev.txt and/or
docs/requirements.txt)

- https://kernel.readthedocs.io/en/latest/kernel-documentation.html
  - This says "Copyright 2016"? That's set in conf.py

I keep a tools doc in ReST:
- https://westurner.github.io/tools/#sphinx
- https://westurner.github.io/tools/#docutils

I'll just CC those sections here
wrapped in a Markdown fenced code block

```rst

.. index:: Docutils
.. _docutils:

Docutils
~~~~~~~~~~~~~~~~~~~
| Homepage: http://docutils.sourceforge.net
| PyPI: https://pypi.python.org/pypi/docutils
| Docs: http://docutils.sourceforge.net/docs/
| Docs: http://docutils.sourceforge.net/rst.html
| Docs: http://docutils.sourceforge.net/docs/ref/doctree.html
| Docs: https://docutils.readthedocs.io/en/sphinx-docs/
| Docs:
https://docutils.readthedocs.io/en/sphinx-docs/ref/rst/restructuredtext.html
| Src: svn http://svn.code.sf.net/p/docutils/code/trunk

Docutils is a :ref:`Python` library which 'parses" :ref:`ReStructuredText`
lightweight markup language into a doctree (~DOM)
which can be serialized into
HTML, ePub, MOBI, LaTeX, man pages,
Open Document files,
XML, JSON, and a number of other formats.


.. index:: Sphinx
.. _sphinx:

Sphinx
~~~~~~~~~~~~~~~~~
| Wikipedia: `<
https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)>`_
| Homepage: https://pypi.python.org/pypi/Sphinx
| Src: git https://github.com/sphinx-doc/sphinx
| Pypi: https://pypi.python.org/pypi/Sphinx
| Docs: http://sphinx-doc.org/contents.html
| Docs: http://sphinx-doc.org/markup/code.html
| Docs: http://www.sphinx-doc.org/en/stable/markup/inline.html#ref-role
| Docs: http://pygments.org/docs/lexers/
| Docs: http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
| Docs: https://github.com/yoloseem/awesome-sphinxdoc

Sphinx is a tool for working with
:ref:`ReStructuredText` documentation trees
and rendering them into HTML, PDF, LaTeX, ePub,
and a number of other formats.

[...]

```

FWIW, ReadTheDocs can host multiple versions of the docs according to the
repo
tags you specify in the web admin.
There may be a way to use the RTD JS UI for selecting versions
with the docs hosted on your own server?
Such as https://www.kernel.org/doc/html/latest/

- https://github.com/torvalds/linux/blob/master/Documentation/conf.py
- https://github.com/torvalds/linux/blob/master/Documentation/Makefile

-
https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/index.rst
-
https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/sphinx.rst
-
https://github.com/torvalds/linux/blob/master/Documentation/doc-guide/kernel-doc.rst

- https://www.kernel.org/doc/html/latest/
- https://www.kernel.org/doc/html/latest/doc-guide/
-
https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#sphinx-install
-
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#writing-kernel-doc-comments


On Tue, Apr 23, 2019 at 12:31 PM Jonathan Corbet <corbet@lwn.net> wrote:

> On Tue, 23 Apr 2019 15:01:32 +0200
> Peter Zijlstra <peterz@infradead.org> wrote:
>
> > But yes, I have 0 motivation to learn or abide by rst. It simply doesn't
> > give me anything in return. There is no upside, only worse text files :/
>
> So I believe it gives even you one thing in return: documentation that is
> more accessible for both readers and authors.  More readable docs should
> lead to more educated developers who understand the code better.  More
> writable docs will bring more people in to help to improve them.  The
> former effect has been reported in the GPU community, where they say that
> the quality of submissions has improved along with the docs.  The latter
> can be observed in the increased number of people working on the docs
> overall, something that Linus noted in the 5.1-rc1 announcement.
>
> Hopefully that's worth something :)
>
> Thanks,
>
> jon
>

[-- Attachment #2: Type: text/html, Size: 7705 bytes --]