[PATCH v2 00/29] Convert files to ReST - part 2

[PATCH v2 00/29] Convert files to ReST - part 2

[Mauro Carvalho Chehab]

This is the second part of a series I wrote sometime ago where I manually
convert lots of files to be properly parsed by Sphinx as ReST files.

As it touches on lot of stuff, this series is based on today's linux-next, 
at tag next-20190617.

The first version of this series had 57 patches. The first part with 28 patches
were already merged. Right now, there are still ~76  patches pending applying
(including this series), and that's because I opted to do ~1 patch per converted
 directory.

That sounds too much to be send on a single round. So, I'm opting to split
it on 3 parts for the conversion, plus a final patch adding orphaned books
to existing ones. 

Those patches should probably be good to be merged either by subsystem
maintainers or via the docs tree.

I opted to mark new files not included yet to the main index.rst (directly or
indirectly) with the :orphan: tag, in order to avoid adding warnings to the
build system. This should be removed after we find a "home" for all
the converted files within the new document tree arrangement, after I
submit the third part.

Both this series and  the other parts of this work are on my devel git tree,
at:

	https://git.linuxtv.org/mchehab/experimental.git/log/?h=convert_rst_renames_v5.1

The final output in html (after all patches I currently have, including 
the upcoming series) can be seen at:

	https://www.infradead.org/~mchehab/rst_conversion/

It contains all pending work from my side related to the conversion, plus
the patches I finished a first version today with contains the renaming 
patches and de-orphan changes.

---

Version 2:

- Removed patches merged via other trees;
- rebased on the top of today's linux-next (next-20190617);
- Fix a typo on one patch's description;
- Added received acks.


Mauro Carvalho Chehab (29):
  docs: connector: convert to ReST and rename to connector.rst
  docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst
  docs: lp855x-driver.txt: convert to ReST and move to kernel-api
  docs: m68k: convert docs to ReST and rename to *.rst
  docs: cma/debugfs.txt: convert docs to ReST and rename to *.rst
  docs: console.txt: convert docs to ReST and rename to *.rst
  docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst
  docs: early-userspace: convert docs to ReST and rename to *.rst
  docs: driver-model: convert docs to ReST and rename to *.rst
  docs: arm: convert docs to ReST and rename to *.rst
  docs: memory-devices: convert ti-emif.txt to ReST
  docs: xen-tpmfront.txt: convert it to .rst
  docs: bus-devices: ti-gpmc.rst: convert it to ReST
  docs: nvmem: convert docs to ReST and rename to *.rst
  docs: phy: convert samsung-usb2.txt to ReST format
  docs: rbtree.txt: fix Sphinx build warnings
  docs: DMA-API-HOWTO.txt: fix an unmarked code block
  docs: accounting: convert to ReST
  docs: ia64: convert to ReST
  docs: leds: convert to ReST
  docs: laptops: convert to ReST
  docs: iio: convert to ReST
  docs: namespaces: convert to ReST
  docs: nfc: convert to ReST
  docs: md: convert to ReST
  docs: mtd: convert to ReST
  docs: nvdimm: convert to ReST
  docs: xtensa: convert to ReST
  docs: mmc: convert to ReST

 Documentation/ABI/testing/sysfs-block-device  |   2 +-
 .../ABI/testing/sysfs-platform-asus-laptop    |   2 +-
 Documentation/DMA-API-HOWTO.txt               |   2 +-
 .../{cgroupstats.txt => cgroupstats.rst}      |  14 +-
 ...ay-accounting.txt => delay-accounting.rst} |  61 ++-
 Documentation/accounting/index.rst            |  14 +
 Documentation/accounting/{psi.txt => psi.rst} |  40 +-
 ...kstats-struct.txt => taskstats-struct.rst} |  79 ++-
 .../{taskstats.txt => taskstats.rst}          |  15 +-
 Documentation/admin-guide/cgroup-v2.rst       |   6 +-
 .../admin-guide/kernel-parameters.rst         |   2 +-
 .../admin-guide/kernel-parameters.txt         |   2 +-
 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 +-
 Documentation/arm/stm32/overview.rst          |   2 -
 .../arm/stm32/stm32f429-overview.rst          |   7 +-
 .../arm/stm32/stm32f746-overview.rst          |   7 +-
 .../arm/stm32/stm32f769-overview.rst          |   7 +-
 .../arm/stm32/stm32h743-overview.rst          |   7 +-
 .../arm/stm32/stm32mp157-overview.rst         |   3 +-
 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 +-
 ...cd-panel-cgram.txt => lcd-panel-cgram.rst} |   9 +-
 Documentation/backlight/lp855x-driver.rst     |  83 +++
 Documentation/backlight/lp855x-driver.txt     |  66 ---
 .../bus-devices/{ti-gpmc.txt => ti-gpmc.rst}  | 159 ++++--
 .../cma/{debugfs.txt => debugfs.rst}          |   8 +-
 .../{connector.txt => connector.rst}          | 130 ++---
 .../console/{console.txt => console.rst}      |  63 ++-
 Documentation/devicetree/bindings/arm/xen.txt |   2 +-
 .../devicetree/booting-without-of.txt         |   4 +-
 Documentation/driver-api/gpio/driver.rst      |   2 +-
 .../driver-model/{binding.txt => binding.rst} |  20 +-
 .../driver-model/{bus.txt => bus.rst}         |  69 +--
 .../driver-model/{class.txt => class.rst}     |  74 +--
 ...esign-patterns.txt => design-patterns.rst} | 106 ++--
 .../driver-model/{device.txt => device.rst}   |  57 +-
 .../driver-model/{devres.txt => devres.rst}   |  50 +-
 .../driver-model/{driver.txt => driver.rst}   | 112 ++--
 Documentation/driver-model/index.rst          |  26 +
 .../{overview.txt => overview.rst}            |  37 +-
 .../{platform.txt => platform.rst}            |  30 +-
 .../driver-model/{porting.txt => porting.rst} | 333 +++++------
 .../{buffer-format.txt => buffer-format.rst}  |  19 +-
 .../{README => early_userspace_support.rst}   |   3 +
 Documentation/early-userspace/index.rst       |  18 +
 Documentation/eisa.txt                        |   4 +-
 Documentation/fb/fbcon.rst                    |   4 +-
 Documentation/filesystems/nfs/nfsroot.txt     |   2 +-
 .../filesystems/ramfs-rootfs-initramfs.txt    |   4 +-
 Documentation/hwmon/submitting-patches.rst    |   2 +-
 .../ia64/{aliasing.txt => aliasing.rst}       |  73 ++-
 Documentation/ia64/{efirtc.txt => efirtc.rst} | 118 ++--
 .../ia64/{err_inject.txt => err_inject.rst}   | 349 ++++++------
 Documentation/ia64/{fsys.txt => fsys.rst}     | 127 +++--
 Documentation/ia64/{README => ia64.rst}       |  26 +-
 Documentation/ia64/index.rst                  |  18 +
 .../ia64/{IRQ-redir.txt => irq-redir.rst}     |  31 +-
 Documentation/ia64/{mca.txt => mca.rst}       |  10 +-
 Documentation/ia64/{serial.txt => serial.rst} |  36 +-
 Documentation/ia64/xen.rst                    | 206 +++++++
 Documentation/ia64/xen.txt                    | 183 -------
 .../iio/{ep93xx_adc.txt => ep93xx_adc.rst}    |  15 +-
 .../{iio_configfs.txt => iio_configfs.rst}    |  52 +-
 Documentation/iio/index.rst                   |  12 +
 Documentation/index.rst                       |   1 +
 .../{asus-laptop.txt => asus-laptop.rst}      |  92 ++--
 ...otection.txt => disk-shock-protection.rst} |  32 +-
 Documentation/laptops/index.rst               |  17 +
 .../{laptop-mode.txt => laptop-mode.rst}      | 509 +++++++++--------
 .../{sony-laptop.txt => sony-laptop.rst}      |  58 +-
 .../laptops/{sonypi.txt => sonypi.rst}        |  28 +-
 .../{thinkpad-acpi.txt => thinkpad-acpi.rst}  | 367 ++++++++-----
 .../{toshiba_haps.txt => toshiba_haps.rst}    |  47 +-
 Documentation/leds/index.rst                  |  25 +
 .../leds/{leds-blinkm.txt => leds-blinkm.rst} |  64 ++-
 ...s-class-flash.txt => leds-class-flash.rst} |  49 +-
 .../leds/{leds-class.txt => leds-class.rst}   |  15 +-
 .../leds/{leds-lm3556.txt => leds-lm3556.rst} | 100 +++-
 .../leds/{leds-lp3944.txt => leds-lp3944.rst} |  23 +-
 Documentation/leds/leds-lp5521.rst            | 115 ++++
 Documentation/leds/leds-lp5521.txt            | 101 ----
 Documentation/leds/leds-lp5523.rst            | 147 +++++
 Documentation/leds/leds-lp5523.txt            | 130 -----
 Documentation/leds/leds-lp5562.rst            | 137 +++++
 Documentation/leds/leds-lp5562.txt            | 120 ----
 Documentation/leds/leds-lp55xx.rst            | 224 ++++++++
 Documentation/leds/leds-lp55xx.txt            | 194 -------
 Documentation/leds/leds-mlxcpld.rst           | 118 ++++
 Documentation/leds/leds-mlxcpld.txt           | 110 ----
 ...edtrig-oneshot.txt => ledtrig-oneshot.rst} |  11 +-
 ...ig-transient.txt => ledtrig-transient.rst} |  63 ++-
 ...edtrig-usbport.txt => ledtrig-usbport.rst} |  11 +-
 Documentation/leds/{uleds.txt => uleds.rst}   |   5 +-
 Documentation/m68k/index.rst                  |  17 +
 ...{kernel-options.txt => kernel-options.rst} | 319 ++++++-----
 Documentation/md/index.rst                    |  12 +
 .../md/{md-cluster.txt => md-cluster.rst}     | 188 ++++---
 .../md/{raid5-cache.txt => raid5-cache.rst}   |  28 +-
 .../md/{raid5-ppl.txt => raid5-ppl.rst}       |   2 +
 .../{ti-emif.txt => ti-emif.rst}              |  27 +-
 Documentation/mmc/index.rst                   |  13 +
 .../{mmc-async-req.txt => mmc-async-req.rst}  |  53 +-
 .../{mmc-dev-attrs.txt => mmc-dev-attrs.rst}  |  32 +-
 .../{mmc-dev-parts.txt => mmc-dev-parts.rst}  |  13 +-
 .../mmc/{mmc-tools.txt => mmc-tools.rst}      |   5 +-
 Documentation/mtd/index.rst                   |  12 +
 .../mtd/{intel-spi.txt => intel-spi.rst}      |  46 +-
 .../mtd/{nand_ecc.txt => nand_ecc.rst}        | 481 ++++++++--------
 .../mtd/{spi-nor.txt => spi-nor.rst}          |   7 +-
 ...bility-list.txt => compatibility-list.rst} |  10 +-
 Documentation/namespaces/index.rst            |  11 +
 ...ource-control.txt => resource-control.rst} |   4 +
 Documentation/nfc/index.rst                   |  11 +
 .../nfc/{nfc-hci.txt => nfc-hci.rst}          | 163 +++---
 .../nfc/{nfc-pn544.txt => nfc-pn544.rst}      |   6 +-
 Documentation/nvdimm/{btt.txt => btt.rst}     | 140 ++---
 Documentation/nvdimm/index.rst                |  12 +
 .../nvdimm/{nvdimm.txt => nvdimm.rst}         | 518 ++++++++++--------
 .../nvdimm/{security.txt => security.rst}     |   4 +-
 Documentation/nvmem/{nvmem.txt => nvmem.rst}  | 112 ++--
 .../{samsung-usb2.txt => samsung-usb2.rst}    |  62 ++-
 Documentation/pti/pti_intel_mid.rst           | 106 ++++
 Documentation/pti/pti_intel_mid.txt           |  99 ----
 Documentation/rbtree.txt                      |   6 +-
 .../{xen-tpmfront.txt => xen-tpmfront.rst}    | 103 ++--
 Documentation/sysctl/vm.txt                   |   4 +-
 Documentation/translations/zh_CN/arm/Booting  |   4 +-
 .../zh_CN/arm/kernel_user_helpers.txt         |   4 +-
 .../xtensa/{atomctl.txt => atomctl.rst}       |  13 +-
 .../xtensa/{booting.txt => booting.rst}       |   5 +-
 Documentation/xtensa/index.rst                |  12 +
 Documentation/xtensa/mmu.rst                  | 195 +++++++
 Documentation/xtensa/mmu.txt                  | 189 -------
 MAINTAINERS                                   |  16 +-
 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/Kconfig                            |   2 +-
 arch/arm64/kernel/kuser32.S                   |   2 +-
 arch/ia64/kernel/efi.c                        |   2 +-
 arch/ia64/kernel/fsys.S                       |   2 +-
 arch/ia64/mm/ioremap.c                        |   2 +-
 arch/ia64/pci/pci.c                           |   2 +-
 arch/mips/bmips/setup.c                       |   2 +-
 arch/xtensa/include/asm/initialize_mmu.h      |   2 +-
 drivers/base/platform.c                       |   2 +-
 drivers/char/Kconfig                          |   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/gpio/gpio-cs5535.c                    |   2 +-
 drivers/iio/Kconfig                           |   2 +-
 drivers/input/touchscreen/sun4i-ts.c          |   2 +-
 drivers/leds/trigger/Kconfig                  |   2 +-
 drivers/leds/trigger/ledtrig-transient.c      |   2 +-
 drivers/mtd/nand/raw/nand_ecc.c               |   2 +-
 drivers/net/ethernet/intel/ice/ice_main.c     |   2 +-
 drivers/nvdimm/Kconfig                        |   2 +-
 drivers/platform/x86/Kconfig                  |   4 +-
 drivers/tty/Kconfig                           |   2 +-
 drivers/tty/serial/Kconfig                    |   2 +-
 drivers/w1/Kconfig                            |   2 +-
 include/linux/connector.h                     |  63 ++-
 init/Kconfig                                  |   2 +-
 net/netfilter/Kconfig                         |   2 +-
 samples/Kconfig                               |   2 +-
 scripts/coccinelle/free/devm_free.cocci       |   2 +-
 usr/Kconfig                                   |   2 +-
 257 files changed, 7122 insertions(+), 5341 deletions(-)
 rename Documentation/accounting/{cgroupstats.txt => cgroupstats.rst} (77%)
 rename Documentation/accounting/{delay-accounting.txt => delay-accounting.rst} (77%)
 create mode 100644 Documentation/accounting/index.rst
 rename Documentation/accounting/{psi.txt => psi.rst} (91%)
 rename Documentation/accounting/{taskstats-struct.txt => taskstats-struct.rst} (78%)
 rename Documentation/accounting/{taskstats.txt => taskstats.rst} (95%)
 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%)
 rename Documentation/auxdisplay/{lcd-panel-cgram.txt => lcd-panel-cgram.rst} (88%)
 create mode 100644 Documentation/backlight/lp855x-driver.rst
 delete mode 100644 Documentation/backlight/lp855x-driver.txt
 rename Documentation/bus-devices/{ti-gpmc.txt => ti-gpmc.rst} (58%)
 rename Documentation/cma/{debugfs.txt => debugfs.rst} (91%)
 rename Documentation/connector/{connector.txt => connector.rst} (57%)
 rename Documentation/console/{console.txt => console.rst} (80%)
 rename Documentation/driver-model/{binding.txt => binding.rst} (92%)
 rename Documentation/driver-model/{bus.txt => bus.rst} (76%)
 rename Documentation/driver-model/{class.txt => class.rst} (75%)
 rename Documentation/driver-model/{design-patterns.txt => design-patterns.rst} (59%)
 rename Documentation/driver-model/{device.txt => device.rst} (71%)
 rename Documentation/driver-model/{devres.txt => devres.rst} (93%)
 rename Documentation/driver-model/{driver.txt => driver.rst} (75%)
 create mode 100644 Documentation/driver-model/index.rst
 rename Documentation/driver-model/{overview.txt => overview.rst} (90%)
 rename Documentation/driver-model/{platform.txt => platform.rst} (95%)
 rename Documentation/driver-model/{porting.txt => porting.rst} (62%)
 rename Documentation/early-userspace/{buffer-format.txt => buffer-format.rst} (91%)
 rename Documentation/early-userspace/{README => early_userspace_support.rst} (99%)
 create mode 100644 Documentation/early-userspace/index.rst
 rename Documentation/ia64/{aliasing.txt => aliasing.rst} (83%)
 rename Documentation/ia64/{efirtc.txt => efirtc.rst} (70%)
 rename Documentation/ia64/{err_inject.txt => err_inject.rst} (82%)
 rename Documentation/ia64/{fsys.txt => fsys.rst} (76%)
 rename Documentation/ia64/{README => ia64.rst} (61%)
 create mode 100644 Documentation/ia64/index.rst
 rename Documentation/ia64/{IRQ-redir.txt => irq-redir.rst} (86%)
 rename Documentation/ia64/{mca.txt => mca.rst} (96%)
 rename Documentation/ia64/{serial.txt => serial.rst} (87%)
 create mode 100644 Documentation/ia64/xen.rst
 delete mode 100644 Documentation/ia64/xen.txt
 rename Documentation/iio/{ep93xx_adc.txt => ep93xx_adc.rst} (71%)
 rename Documentation/iio/{iio_configfs.txt => iio_configfs.rst} (73%)
 create mode 100644 Documentation/iio/index.rst
 rename Documentation/laptops/{asus-laptop.txt => asus-laptop.rst} (84%)
 rename Documentation/laptops/{disk-shock-protection.txt => disk-shock-protection.rst} (91%)
 create mode 100644 Documentation/laptops/index.rst
 rename Documentation/laptops/{laptop-mode.txt => laptop-mode.rst} (62%)
 rename Documentation/laptops/{sony-laptop.txt => sony-laptop.rst} (85%)
 rename Documentation/laptops/{sonypi.txt => sonypi.rst} (87%)
 rename Documentation/laptops/{thinkpad-acpi.txt => thinkpad-acpi.rst} (89%)
 rename Documentation/laptops/{toshiba_haps.txt => toshiba_haps.rst} (60%)
 create mode 100644 Documentation/leds/index.rst
 rename Documentation/leds/{leds-blinkm.txt => leds-blinkm.rst} (57%)
 rename Documentation/leds/{leds-class-flash.txt => leds-class-flash.rst} (74%)
 rename Documentation/leds/{leds-class.txt => leds-class.rst} (92%)
 rename Documentation/leds/{leds-lm3556.txt => leds-lm3556.rst} (70%)
 rename Documentation/leds/{leds-lp3944.txt => leds-lp3944.rst} (78%)
 create mode 100644 Documentation/leds/leds-lp5521.rst
 delete mode 100644 Documentation/leds/leds-lp5521.txt
 create mode 100644 Documentation/leds/leds-lp5523.rst
 delete mode 100644 Documentation/leds/leds-lp5523.txt
 create mode 100644 Documentation/leds/leds-lp5562.rst
 delete mode 100644 Documentation/leds/leds-lp5562.txt
 create mode 100644 Documentation/leds/leds-lp55xx.rst
 delete mode 100644 Documentation/leds/leds-lp55xx.txt
 create mode 100644 Documentation/leds/leds-mlxcpld.rst
 delete mode 100644 Documentation/leds/leds-mlxcpld.txt
 rename Documentation/leds/{ledtrig-oneshot.txt => ledtrig-oneshot.rst} (90%)
 rename Documentation/leds/{ledtrig-transient.txt => ledtrig-transient.rst} (81%)
 rename Documentation/leds/{ledtrig-usbport.txt => ledtrig-usbport.rst} (86%)
 rename Documentation/leds/{uleds.txt => uleds.rst} (95%)
 create mode 100644 Documentation/m68k/index.rst
 rename Documentation/m68k/{kernel-options.txt => kernel-options.rst} (78%)
 create mode 100644 Documentation/md/index.rst
 rename Documentation/md/{md-cluster.txt => md-cluster.rst} (68%)
 rename Documentation/md/{raid5-cache.txt => raid5-cache.rst} (92%)
 rename Documentation/md/{raid5-ppl.txt => raid5-ppl.rst} (98%)
 rename Documentation/memory-devices/{ti-emif.txt => ti-emif.rst} (81%)
 create mode 100644 Documentation/mmc/index.rst
 rename Documentation/mmc/{mmc-async-req.txt => mmc-async-req.rst} (75%)
 rename Documentation/mmc/{mmc-dev-attrs.txt => mmc-dev-attrs.rst} (73%)
 rename Documentation/mmc/{mmc-dev-parts.txt => mmc-dev-parts.rst} (83%)
 rename Documentation/mmc/{mmc-tools.txt => mmc-tools.rst} (92%)
 create mode 100644 Documentation/mtd/index.rst
 rename Documentation/mtd/{intel-spi.txt => intel-spi.rst} (71%)
 rename Documentation/mtd/{nand_ecc.txt => nand_ecc.rst} (67%)
 rename Documentation/mtd/{spi-nor.txt => spi-nor.rst} (94%)
 rename Documentation/namespaces/{compatibility-list.txt => compatibility-list.rst} (86%)
 create mode 100644 Documentation/namespaces/index.rst
 rename Documentation/namespaces/{resource-control.txt => resource-control.rst} (89%)
 create mode 100644 Documentation/nfc/index.rst
 rename Documentation/nfc/{nfc-hci.txt => nfc-hci.rst} (71%)
 rename Documentation/nfc/{nfc-pn544.txt => nfc-pn544.rst} (82%)
 rename Documentation/nvdimm/{btt.txt => btt.rst} (71%)
 create mode 100644 Documentation/nvdimm/index.rst
 rename Documentation/nvdimm/{nvdimm.txt => nvdimm.rst} (60%)
 rename Documentation/nvdimm/{security.txt => security.rst} (99%)
 rename Documentation/nvmem/{nvmem.txt => nvmem.rst} (62%)
 rename Documentation/phy/{samsung-usb2.txt => samsung-usb2.rst} (77%)
 create mode 100644 Documentation/pti/pti_intel_mid.rst
 delete mode 100644 Documentation/pti/pti_intel_mid.txt
 rename Documentation/security/tpm/{xen-tpmfront.txt => xen-tpmfront.rst} (66%)
 rename Documentation/xtensa/{atomctl.txt => atomctl.rst} (81%)
 rename Documentation/xtensa/{booting.txt => booting.rst} (91%)
 create mode 100644 Documentation/xtensa/index.rst
 create mode 100644 Documentation/xtensa/mmu.rst
 delete mode 100644 Documentation/xtensa/mmu.txt

-- 
2.21.0

[PATCH v2 01/29] docs: connector: convert to ReST and rename to connector.rst

[Mauro Carvalho Chehab]

As it has some function definitions, move them to connector.h.

The remaining 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>
---
 .../{connector.txt => connector.rst}          | 130 ++++++------------
 drivers/w1/Kconfig                            |   2 +-
 include/linux/connector.h                     |  63 ++++++++-
 samples/Kconfig                               |   2 +-
 4 files changed, 109 insertions(+), 88 deletions(-)
 rename Documentation/connector/{connector.txt => connector.rst} (57%)

diff --git a/Documentation/connector/connector.txt b/Documentation/connector/connector.rst
similarity index 57%
rename from Documentation/connector/connector.txt
rename to Documentation/connector/connector.rst
index ab7ca897fab7..24e26dc22dbf 100644
--- a/Documentation/connector/connector.txt
+++ b/Documentation/connector/connector.rst
@@ -1,6 +1,8 @@
-/*****************************************/
-Kernel Connector.
-/*****************************************/
+:orphan:
+
+================
+Kernel Connector
+================
 
 Kernel connector - new netlink based userspace <-> kernel space easy
 to use communication module.
@@ -12,94 +14,55 @@ identifier, the appropriate callback will be called.
 
 From the userspace point of view it's quite straightforward:
 
-	socket();
-	bind();
-	send();
-	recv();
+	- socket();
+	- bind();
+	- send();
+	- recv();
 
 But if kernelspace wants to use the full power of such connections, the
 driver writer must create special sockets, must know about struct sk_buff
 handling, etc...  The Connector driver allows any kernelspace agents to use
 netlink based networking for inter-process communication in a significantly
-easier way:
+easier way::
 
-int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
-void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
-void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask);
+  int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
+  void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
+  void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask);
 
-struct cb_id
-{
+  struct cb_id
+  {
 	__u32			idx;
 	__u32			val;
-};
+  };
 
 idx and val are unique identifiers which must be registered in the
-connector.h header for in-kernel usage.  void (*callback) (void *) is a
+connector.h header for in-kernel usage.  `void (*callback) (void *)` is a
 callback function which will be called when a message with above idx.val
 is received by the connector core.  The argument for that function must
-be dereferenced to struct cn_msg *.
+be dereferenced to `struct cn_msg *`::
 
-struct cn_msg
-{
+  struct cn_msg
+  {
 	struct cb_id		id;
 
 	__u32			seq;
 	__u32			ack;
 
-	__u32			len;		/* Length of the following data */
+	__u32			len;	/* Length of the following data */
 	__u8			data[0];
-};
+  };
 
-/*****************************************/
-Connector interfaces.
-/*****************************************/
+Connector interfaces
+====================
 
-int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
+ .. kernel-doc:: include/linux/connector.h
 
- Registers new callback with connector core.
+ Note:
+   When registering new callback user, connector core assigns
+   netlink group to the user which is equal to its id.idx.
 
- struct cb_id *id		- unique connector's user identifier.
-				  It must be registered in connector.h for legal in-kernel users.
- char *name			- connector's callback symbolic name.
- void (*callback) (struct cn..)	- connector's callback.
-				  cn_msg and the sender's credentials
-
-
-void cn_del_callback(struct cb_id *id);
-
- Unregisters new callback with connector core.
-
- struct cb_id *id		- unique connector's user identifier.
-
-
-int cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __groups, int gfp_mask);
-int cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __groups, int gfp_mask);
-
- Sends message to the specified groups.  It can be safely called from
- softirq context, but may silently fail under strong memory pressure.
- If there are no listeners for given group -ESRCH can be returned.
-
- struct cn_msg *		- message header(with attached data).
- u16 len			- for *_multi multiple cn_msg messages can be sent
- u32 port			- destination port.
- 				  If non-zero the message will be sent to the
-				  given port, which should be set to the
-				  original sender.
- u32 __group			- destination group.
-				  If port and __group is zero, then appropriate group will
-				  be searched through all registered connector users,
-				  and message will be delivered to the group which was
-				  created for user with the same ID as in msg.
-				  If __group is not zero, then message will be delivered
-				  to the specified group.
- int gfp_mask			- GFP mask.
-
- Note: When registering new callback user, connector core assigns
- netlink group to the user which is equal to its id.idx.
-
-/*****************************************/
-Protocol description.
-/*****************************************/
+Protocol description
+====================
 
 The current framework offers a transport layer with fixed headers.  The
 recommended protocol which uses such a header is as following:
@@ -132,9 +95,8 @@ driver (it also registers itself with id={-1, -1}).
 As example of this usage can be found in the cn_test.c module which
 uses the connector to request notification and to send messages.
 
-/*****************************************/
-Reliability.
-/*****************************************/
+Reliability
+===========
 
 Netlink itself is not a reliable protocol.  That means that messages can
 be lost due to memory pressure or process' receiving queue overflowed,
@@ -142,32 +104,31 @@ so caller is warned that it must be prepared.  That is why the struct
 cn_msg [main connector's message header] contains u32 seq and u32 ack
 fields.
 
-/*****************************************/
-Userspace usage.
-/*****************************************/
+Userspace usage
+===============
 
 2.6.14 has a new netlink socket implementation, which by default does not
 allow people to send data to netlink groups other than 1.
 So, if you wish to use a netlink socket (for example using connector)
 with a different group number, the userspace application must subscribe to
-that group first.  It can be achieved by the following pseudocode:
+that group first.  It can be achieved by the following pseudocode::
 
-s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR);
+  s = socket(PF_NETLINK, SOCK_DGRAM, NETLINK_CONNECTOR);
 
-l_local.nl_family = AF_NETLINK;
-l_local.nl_groups = 12345;
-l_local.nl_pid = 0;
+  l_local.nl_family = AF_NETLINK;
+  l_local.nl_groups = 12345;
+  l_local.nl_pid = 0;
 
-if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) {
+  if (bind(s, (struct sockaddr *)&l_local, sizeof(struct sockaddr_nl)) == -1) {
 	perror("bind");
 	close(s);
 	return -1;
-}
+  }
 
-{
+  {
 	int on = l_local.nl_groups;
 	setsockopt(s, 270, 1, &on, sizeof(on));
-}
+  }
 
 Where 270 above is SOL_NETLINK, and 1 is a NETLINK_ADD_MEMBERSHIP socket
 option.  To drop a multicast subscription, one should call the above socket
@@ -180,16 +141,15 @@ group number 12345, you must increment CN_NETLINK_USERS to that number.
 Additional 0xf numbers are allocated to be used by non-in-kernel users.
 
 Due to this limitation, group 0xffffffff does not work now, so one can
-not use add/remove connector's group notifications, but as far as I know, 
+not use add/remove connector's group notifications, but as far as I know,
 only cn_test.c test module used it.
 
 Some work in netlink area is still being done, so things can be changed in
 2.6.15 timeframe, if it will happen, documentation will be updated for that
 kernel.
 
-/*****************************************/
 Code samples
-/*****************************************/
+============
 
 Sample code for a connector test module and user space can be found
 in samples/connector/. To build this code, enable CONFIG_CONNECTOR
diff --git a/drivers/w1/Kconfig b/drivers/w1/Kconfig
index 03dd57581df7..160053c0baea 100644
--- a/drivers/w1/Kconfig
+++ b/drivers/w1/Kconfig
@@ -19,7 +19,7 @@ config W1_CON
 	default y
 	---help---
 	  This allows to communicate with userspace using connector. For more
-	  information see <file:Documentation/connector/connector.txt>.
+	  information see <file:Documentation/connector/connector.rst>.
 	  There are three types of messages between w1 core and userspace:
 	  1. Events. They are generated each time new master or slave device found
 		either due to automatic or requested search.
diff --git a/include/linux/connector.h b/include/linux/connector.h
index 1d72ef76f24f..6b6c7396a584 100644
--- a/include/linux/connector.h
+++ b/include/linux/connector.h
@@ -55,10 +55,71 @@ struct cn_dev {
 	struct cn_queue_dev *cbdev;
 };
 
+/**
+ * cn_add_callback() - Registers new callback with connector core.
+ *
+ * @id:		unique connector's user identifier.
+ *		It must be registered in connector.h for legal
+ *		in-kernel users.
+ * @name:	connector's callback symbolic name.
+ * @callback:	connector's callback.
+ * 		parameters are %cn_msg and the sender's credentials
+ */
 int cn_add_callback(struct cb_id *id, const char *name,
 		    void (*callback)(struct cn_msg *, struct netlink_skb_parms *));
-void cn_del_callback(struct cb_id *);
+/**
+ * cn_del_callback() - Unregisters new callback with connector core.
+ *
+ * @id:		unique connector's user identifier.
+ */
+void cn_del_callback(struct cb_id *id);
+
+
+/**
+ * cn_netlink_send_mult - Sends message to the specified groups.
+ *
+ * @msg: 	message header(with attached data).
+ * @len:	Number of @msg to be sent.
+ * @portid:	destination port.
+ *		If non-zero the message will be sent to the given port,
+ *		which should be set to the original sender.
+ * @group:	destination group.
+ * 		If @portid and @group is zero, then appropriate group will
+ *		be searched through all registered connector users, and
+ *		message will be delivered to the group which was created
+ *		for user with the same ID as in @msg.
+ *		If @group is not zero, then message will be delivered
+ *		to the specified group.
+ * @gfp_mask:	GFP mask.
+ *
+ * It can be safely called from softirq context, but may silently
+ * fail under strong memory pressure.
+ *
+ * If there are no listeners for given group %-ESRCH can be returned.
+ */
 int cn_netlink_send_mult(struct cn_msg *msg, u16 len, u32 portid, u32 group, gfp_t gfp_mask);
+
+/**
+ * cn_netlink_send_mult - Sends message to the specified groups.
+ *
+ * @msg:	message header(with attached data).
+ * @portid:	destination port.
+ *		If non-zero the message will be sent to the given port,
+ *		which should be set to the original sender.
+ * @group:	destination group.
+ * 		If @portid and @group is zero, then appropriate group will
+ *		be searched through all registered connector users, and
+ *		message will be delivered to the group which was created
+ *		for user with the same ID as in @msg.
+ *		If @group is not zero, then message will be delivered
+ *		to the specified group.
+ * @gfp_mask:	GFP mask.
+ *
+ * It can be safely called from softirq context, but may silently
+ * fail under strong memory pressure.
+ *
+ * If there are no listeners for given group %-ESRCH can be returned.
+ */
 int cn_netlink_send(struct cn_msg *msg, u32 portid, u32 group, gfp_t gfp_mask);
 
 int cn_queue_add_callback(struct cn_queue_dev *dev, const char *name,
diff --git a/samples/Kconfig b/samples/Kconfig
index d63cc8a3e0df..9ec524b2e003 100644
--- a/samples/Kconfig
+++ b/samples/Kconfig
@@ -100,7 +100,7 @@ config SAMPLE_CONNECTOR
 	  When enabled, this builds both a sample kernel module for
 	  the connector interface and a user space tool to communicate
 	  with it.
-	  See also Documentation/connector/connector.txt
+	  See also Documentation/connector/connector.rst
 
 config SAMPLE_SECCOMP
 	bool "Build seccomp sample code"
-- 
2.21.0

[PATCH v2 02/29] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst

[Mauro Carvalho Chehab]

This small text file describes the usage of parallel port LCD
displays from userspace PoV. So, a good candidate for the
admin guide.

While this is not part of the admin-guide book, mark it as
:orphan:, in order to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 .../{lcd-panel-cgram.txt => lcd-panel-cgram.rst}         | 9 +++++++--
 MAINTAINERS                                              | 2 +-
 2 files changed, 8 insertions(+), 3 deletions(-)
 rename Documentation/auxdisplay/{lcd-panel-cgram.txt => lcd-panel-cgram.rst} (88%)

diff --git a/Documentation/auxdisplay/lcd-panel-cgram.txt b/Documentation/auxdisplay/lcd-panel-cgram.rst
similarity index 88%
rename from Documentation/auxdisplay/lcd-panel-cgram.txt
rename to Documentation/auxdisplay/lcd-panel-cgram.rst
index 7f82c905763d..dfef50286018 100644
--- a/Documentation/auxdisplay/lcd-panel-cgram.txt
+++ b/Documentation/auxdisplay/lcd-panel-cgram.rst
@@ -1,3 +1,9 @@
+:orphan:
+
+======================================
+Parallel port LCD/Keypad Panel support
+======================================
+
 Some LCDs allow you to define up to 8 characters, mapped to ASCII
 characters 0 to 7. The escape code to define a new character is
 '\e[LG' followed by one digit from 0 to 7, representing the character
@@ -7,7 +13,7 @@ illuminated pixel with LSB on the right. Lines are numbered from the
 top of the character to the bottom. On a 5x7 matrix, only the 5 lower
 bits of the 7 first bytes are used for each character. If the string
 is incomplete, only complete lines will be redefined. Here are some
-examples :
+examples::
 
   printf "\e[LG0010101050D1F0C04;"  => 0 = [enter]
   printf "\e[LG1040E1F0000000000;"  => 1 = [up]
@@ -21,4 +27,3 @@ examples :
   printf "\e[LG00002061E1E060200;"  => small speaker
 
 Willy
-
diff --git a/MAINTAINERS b/MAINTAINERS
index e20a1762ec0b..d64d8bb46323 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11935,7 +11935,7 @@ PARALLEL LCD/KEYPAD PANEL DRIVER
 M:	Willy Tarreau <willy@haproxy.com>
 M:	Ksenija Stanojevic <ksenija.stanojevic@gmail.com>
 S:	Odd Fixes
-F:	Documentation/auxdisplay/lcd-panel-cgram.txt
+F:	Documentation/auxdisplay/lcd-panel-cgram.rst
 F:	drivers/auxdisplay/panel.c
 
 PARALLEL PORT SUBSYSTEM
-- 
2.21.0

Re: [PATCH v2 02/29] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst

[Miguel Ojeda]

On Tue, Jun 18, 2019 at 10:56 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> This small text file describes the usage of parallel port LCD
> displays from userspace PoV. So, a good candidate for the
> admin guide.
>
> While this is not part of the admin-guide book, mark it as
> :orphan:, in order to avoid build warnings.

If we are going to move everything else to `.rst` too, even things
outside the guide, then ack.

Cheers,
Miguel

Re: [PATCH v2 02/29] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst

[Mauro Carvalho Chehab]

Em Tue, 18 Jun 2019 23:14:01 +0200
Miguel Ojeda <miguel.ojeda.sandonis@gmail.com> escreveu:

> On Tue, Jun 18, 2019 at 10:56 PM Mauro Carvalho Chehab
> <mchehab+samsung@kernel.org> wrote:
> >
> > This small text file describes the usage of parallel port LCD
> > displays from userspace PoV. So, a good candidate for the
> > admin guide.
> >
> > While this is not part of the admin-guide book, mark it as
> > :orphan:, in order to avoid build warnings.  
> 
> If we are going to move everything else to `.rst` too, even things
> outside the guide, then ack.

Yeah, the plan is to move all text files inside Documentation/ to .rst[1].

[1] There are some exceptions: for ABI and features, the current plan
is to have a script that parses their strict formats and produce
a ReST output.


Btw, Still pending to be sent, I have already a patch removing the
:orphan: from this file and adding it to the admin guide:

	https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_renames_v5.1&id=eae5b48cab115c83be8dd59ee99b9e45f8142134

And the corresponding output, after the patches I currently have:

	https://www.infradead.org/~mchehab/rst_conversion/admin-guide/lcd-panel-cgram.html

Thanks,
Mauro

Re: [PATCH v2 02/29] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst

[Miguel Ojeda]

On Wed, Jun 19, 2019 at 1:15 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> Yeah, the plan is to move all text files inside Documentation/ to .rst[1].
>
> [1] There are some exceptions: for ABI and features, the current plan
> is to have a script that parses their strict formats and produce
> a ReST output.
>
>
> Btw, Still pending to be sent, I have already a patch removing the
> :orphan: from this file and adding it to the admin guide:
>
>         https://git.linuxtv.org/mchehab/experimental.git/commit/?h=convert_rst_renames_v5.1&id=eae5b48cab115c83be8dd59ee99b9e45f8142134
>
> And the corresponding output, after the patches I currently have:
>
>         https://www.infradead.org/~mchehab/rst_conversion/admin-guide/lcd-panel-cgram.html

Thanks for the pointers! I guess you will take all these
patches/series on your tree(s), but if you want maintainers to do it,
please let me know!

Cheers,
Miguel

[PATCH v2 03/29] docs: lp855x-driver.txt: convert to ReST and move to kernel-api

[Mauro Carvalho Chehab]

This small file seems to be an attempt to start documenting
backlight drivers.

It contains descriptions of the controls for the driver
with could sound as an somewhat user-faced description, but
it's main focus is to describe, instead, the data that should
be passed via platform data and some driver-specific stuff.

While this is not part of the driver-api book, mark it as
:orphan:, in order to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/backlight/lp855x-driver.rst | 83 +++++++++++++++++++++++
 Documentation/backlight/lp855x-driver.txt | 66 ------------------
 MAINTAINERS                               |  2 +-
 3 files changed, 84 insertions(+), 67 deletions(-)
 create mode 100644 Documentation/backlight/lp855x-driver.rst
 delete mode 100644 Documentation/backlight/lp855x-driver.txt

diff --git a/Documentation/backlight/lp855x-driver.rst b/Documentation/backlight/lp855x-driver.rst
new file mode 100644
index 000000000000..62b7ed847a77
--- /dev/null
+++ b/Documentation/backlight/lp855x-driver.rst
@@ -0,0 +1,83 @@
+:orphan:
+
+====================
+Kernel driver lp855x
+====================
+
+Backlight driver for LP855x ICs
+
+Supported chips:
+
+	Texas Instruments LP8550, LP8551, LP8552, LP8553, LP8555, LP8556 and
+	LP8557
+
+Author: Milo(Woogyom) Kim <milo.kim@ti.com>
+
+Description
+-----------
+
+* Brightness control
+
+  Brightness can be controlled by the pwm input or the i2c command.
+  The lp855x driver supports both cases.
+
+* Device attributes
+
+  1) bl_ctl_mode
+
+  Backlight control mode.
+
+  Value: pwm based or register based
+
+  2) chip_id
+
+  The lp855x chip id.
+
+  Value: lp8550/lp8551/lp8552/lp8553/lp8555/lp8556/lp8557
+
+Platform data for lp855x
+------------------------
+
+For supporting platform specific data, the lp855x platform data can be used.
+
+* name:
+	Backlight driver name. If it is not defined, default name is set.
+* device_control:
+	Value of DEVICE CONTROL register.
+* initial_brightness:
+	Initial value of backlight brightness.
+* period_ns:
+	Platform specific PWM period value. unit is nano.
+	Only valid when brightness is pwm input mode.
+* size_program:
+	Total size of lp855x_rom_data.
+* rom_data:
+	List of new eeprom/eprom registers.
+
+Examples
+========
+
+1) lp8552 platform data: i2c register mode with new eeprom data::
+
+    #define EEPROM_A5_ADDR	0xA5
+    #define EEPROM_A5_VAL	0x4f	/* EN_VSYNC=0 */
+
+    static struct lp855x_rom_data lp8552_eeprom_arr[] = {
+	{EEPROM_A5_ADDR, EEPROM_A5_VAL},
+    };
+
+    static struct lp855x_platform_data lp8552_pdata = {
+	.name = "lcd-bl",
+	.device_control = I2C_CONFIG(LP8552),
+	.initial_brightness = INITIAL_BRT,
+	.size_program = ARRAY_SIZE(lp8552_eeprom_arr),
+	.rom_data = lp8552_eeprom_arr,
+    };
+
+2) lp8556 platform data: pwm input mode with default rom data::
+
+    static struct lp855x_platform_data lp8556_pdata = {
+	.device_control = PWM_CONFIG(LP8556),
+	.initial_brightness = INITIAL_BRT,
+	.period_ns = 1000000,
+    };
diff --git a/Documentation/backlight/lp855x-driver.txt b/Documentation/backlight/lp855x-driver.txt
deleted file mode 100644
index 01bce243d3d7..000000000000
--- a/Documentation/backlight/lp855x-driver.txt
+++ /dev/null
@@ -1,66 +0,0 @@
-Kernel driver lp855x
-====================
-
-Backlight driver for LP855x ICs
-
-Supported chips:
-	Texas Instruments LP8550, LP8551, LP8552, LP8553, LP8555, LP8556 and
-	LP8557
-
-Author: Milo(Woogyom) Kim <milo.kim@ti.com>
-
-Description
------------
-
-* Brightness control
-
-Brightness can be controlled by the pwm input or the i2c command.
-The lp855x driver supports both cases.
-
-* Device attributes
-
-1) bl_ctl_mode
-Backlight control mode.
-Value : pwm based or register based
-
-2) chip_id
-The lp855x chip id.
-Value : lp8550/lp8551/lp8552/lp8553/lp8555/lp8556/lp8557
-
-Platform data for lp855x
-------------------------
-
-For supporting platform specific data, the lp855x platform data can be used.
-
-* name : Backlight driver name. If it is not defined, default name is set.
-* device_control : Value of DEVICE CONTROL register.
-* initial_brightness : Initial value of backlight brightness.
-* period_ns : Platform specific PWM period value. unit is nano.
-	     Only valid when brightness is pwm input mode.
-* size_program : Total size of lp855x_rom_data.
-* rom_data : List of new eeprom/eprom registers.
-
-example 1) lp8552 platform data : i2c register mode with new eeprom data
-
-#define EEPROM_A5_ADDR	0xA5
-#define EEPROM_A5_VAL	0x4f	/* EN_VSYNC=0 */
-
-static struct lp855x_rom_data lp8552_eeprom_arr[] = {
-	{EEPROM_A5_ADDR, EEPROM_A5_VAL},
-};
-
-static struct lp855x_platform_data lp8552_pdata = {
-	.name = "lcd-bl",
-	.device_control = I2C_CONFIG(LP8552),
-	.initial_brightness = INITIAL_BRT,
-	.size_program = ARRAY_SIZE(lp8552_eeprom_arr),
-	.rom_data = lp8552_eeprom_arr,
-};
-
-example 2) lp8556 platform data : pwm input mode with default rom data
-
-static struct lp855x_platform_data lp8556_pdata = {
-	.device_control = PWM_CONFIG(LP8556),
-	.initial_brightness = INITIAL_BRT,
-	.period_ns = 1000000,
-};
diff --git a/MAINTAINERS b/MAINTAINERS
index d64d8bb46323..3e43c7ab3d6a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15831,7 +15831,7 @@ F:	sound/soc/codecs/isabelle*
 TI LP855x BACKLIGHT DRIVER
 M:	Milo Kim <milo.kim@ti.com>
 S:	Maintained
-F:	Documentation/backlight/lp855x-driver.txt
+F:	Documentation/backlight/lp855x-driver.rst
 F:	drivers/video/backlight/lp855x_bl.c
 F:	include/linux/platform_data/lp855x.h
 
-- 
2.21.0

[PATCH v2 04/29] docs: m68k: convert docs to ReST and rename to *.rst

[Mauro Carvalho Chehab]

Convert the m68k kernel-options.txt file to ReST.

The conversion is trivial, as the document is already on a format
close enough to ReST. Just some small adjustments were needed in
order to make it both good for being parsed while keeping it on
a good txt shape.

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>
---
 .../admin-guide/kernel-parameters.rst         |   2 +-
 Documentation/m68k/index.rst                  |  17 +
 ...{kernel-options.txt => kernel-options.rst} | 319 ++++++++++--------
 3 files changed, 191 insertions(+), 147 deletions(-)
 create mode 100644 Documentation/m68k/index.rst
 rename Documentation/m68k/{kernel-options.txt => kernel-options.rst} (78%)

diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst
index 8d3273e32eb1..006196bd763a 100644
--- a/Documentation/admin-guide/kernel-parameters.rst
+++ b/Documentation/admin-guide/kernel-parameters.rst
@@ -118,7 +118,7 @@ parameter is applicable::
 	LOOP	Loopback device support is enabled.
 	M68k	M68k architecture is enabled.
 			These options have more detailed description inside of
-			Documentation/m68k/kernel-options.txt.
+			Documentation/m68k/kernel-options.rst.
 	MDA	MDA console support is enabled.
 	MIPS	MIPS architecture is enabled.
 	MOUSE	Appropriate mouse support is enabled.
diff --git a/Documentation/m68k/index.rst b/Documentation/m68k/index.rst
new file mode 100644
index 000000000000..f3273ec075c3
--- /dev/null
+++ b/Documentation/m68k/index.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+=================
+m68k Architecture
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   kernel-options
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/m68k/kernel-options.txt b/Documentation/m68k/kernel-options.rst
similarity index 78%
rename from Documentation/m68k/kernel-options.txt
rename to Documentation/m68k/kernel-options.rst
index 79d21246c75a..cabd9419740d 100644
--- a/Documentation/m68k/kernel-options.txt
+++ b/Documentation/m68k/kernel-options.rst
@@ -1,22 +1,24 @@
-
-
-				  Command Line Options for Linux/m68k
-				  ===================================
+===================================
+Command Line Options for Linux/m68k
+===================================
 
 Last Update: 2 May 1999
+
 Linux/m68k version: 2.2.6
+
 Author: Roman.Hodek@informatik.uni-erlangen.de (Roman Hodek)
+
 Update: jds@kom.auc.dk (Jes Sorensen) and faq@linux-m68k.org (Chris Lawrence)
 
 0) Introduction
 ===============
 
-  Often I've been asked which command line options the Linux/m68k
+Often I've been asked which command line options the Linux/m68k
 kernel understands, or how the exact syntax for the ... option is, or
 ... about the option ... . I hope, this document supplies all the
 answers...
 
-  Note that some options might be outdated, their descriptions being
+Note that some options might be outdated, their descriptions being
 incomplete or missing. Please update the information and send in the
 patches.
 
@@ -38,11 +40,11 @@ argument contains an '=', it is of class 2, and the definition is put
 into init's environment. All other arguments are passed to init as
 command line options.
 
-  This document describes the valid kernel options for Linux/m68k in
+This document describes the valid kernel options for Linux/m68k in
 the version mentioned at the start of this file. Later revisions may
 add new such options, and some may be missing in older versions.
 
-  In general, the value (the part after the '=') of an option is a
+In general, the value (the part after the '=') of an option is a
 list of values separated by commas. The interpretation of these values
 is up to the driver that "owns" the option. This association of
 options with drivers is also the reason that some are further
@@ -55,21 +57,21 @@ subdivided.
 2.1) root=
 ----------
 
-Syntax: root=/dev/<device>
-    or: root=<hex_number>
+:Syntax: root=/dev/<device>
+:or:     root=<hex_number>
 
 This tells the kernel which device it should mount as the root
 filesystem. The device must be a block device with a valid filesystem
 on it.
 
-  The first syntax gives the device by name. These names are converted
+The first syntax gives the device by name. These names are converted
 into a major/minor number internally in the kernel in an unusual way.
 Normally, this "conversion" is done by the device files in /dev, but
 this isn't possible here, because the root filesystem (with /dev)
 isn't mounted yet... So the kernel parses the name itself, with some
 hardcoded name to number mappings. The name must always be a
 combination of two or three letters, followed by a decimal number.
-Valid names are:
+Valid names are::
 
   /dev/ram: -> 0x0100 (initial ramdisk)
   /dev/hda: -> 0x0300 (first IDE disk)
@@ -81,7 +83,7 @@ Valid names are:
   /dev/sde: -> 0x0840 (fifth SCSI disk)
   /dev/fd : -> 0x0200 (floppy disk)
 
-  The name must be followed by a decimal number, that stands for the
+The name must be followed by a decimal number, that stands for the
 partition number. Internally, the value of the number is just
 added to the device number mentioned in the table above. The
 exceptions are /dev/ram and /dev/fd, where /dev/ram refers to an
@@ -100,12 +102,12 @@ the kernel command line.
 
 [Strange and maybe uninteresting stuff ON]
 
-  This unusual translation of device names has some strange
+This unusual translation of device names has some strange
 consequences: If, for example, you have a symbolic link from /dev/fd
 to /dev/fd0D720 as an abbreviation for floppy driver #0 in DD format,
 you cannot use this name for specifying the root device, because the
 kernel cannot see this symlink before mounting the root FS and it
-isn't in the table above. If you use it, the root device will not be 
+isn't in the table above. If you use it, the root device will not be
 set at all, without an error message. Another example: You cannot use a
 partition on e.g. the sixth SCSI disk as the root filesystem, if you
 want to specify it by name. This is, because only the devices up to
@@ -118,7 +120,7 @@ knowledge that each disk uses 16 minors, and write "root=/dev/sde17"
 
 [Strange and maybe uninteresting stuff OFF]
 
-  If the device containing your root partition isn't in the table
+If the device containing your root partition isn't in the table
 above, you can also specify it by major and minor numbers. These are
 written in hex, with no prefix and no separator between. E.g., if you
 have a CD with contents appropriate as a root filesystem in the first
@@ -136,6 +138,7 @@ known partition UUID as the starting point.  For example,
 if partition 5 of the device has the UUID of
 00112233-4455-6677-8899-AABBCCDDEEFF then partition 3 may be found as
 follows:
+
   PARTUUID=00112233-4455-6677-8899-AABBCCDDEEFF/PARTNROFF=-2
 
 Authoritative information can be found in
@@ -145,8 +148,8 @@ Authoritative information can be found in
 2.2) ro, rw
 -----------
 
-Syntax: ro
-    or: rw
+:Syntax: ro
+:or:     rw
 
 These two options tell the kernel whether it should mount the root
 filesystem read-only or read-write. The default is read-only, except
@@ -156,7 +159,7 @@ for ramdisks, which default to read-write.
 2.3) debug
 ----------
 
-Syntax: debug
+:Syntax: debug
 
 This raises the kernel log level to 10 (the default is 7). This is the
 same level as set by the "dmesg" command, just that the maximum level
@@ -166,7 +169,7 @@ selectable by dmesg is 8.
 2.4) debug=
 -----------
 
-Syntax: debug=<device>
+:Syntax: debug=<device>
 
 This option causes certain kernel messages be printed to the selected
 debugging device. This can aid debugging the kernel, since the
@@ -175,7 +178,7 @@ devices are possible depends on the machine type. There are no checks
 for the validity of the device name. If the device isn't implemented,
 nothing happens.
 
-  Messages logged this way are in general stack dumps after kernel
+Messages logged this way are in general stack dumps after kernel
 memory faults or bad kernel traps, and kernel panics. To be exact: all
 messages of level 0 (panic messages) and all messages printed while
 the log level is 8 or more (their level doesn't matter). Before stack
@@ -185,19 +188,27 @@ at least 8 can also be set by the "debug" command line option (see
 
 Devices possible for Amiga:
 
- - "ser": built-in serial port; parameters: 9600bps, 8N1
- - "mem": Save the messages to a reserved area in chip mem. After
+ - "ser":
+	  built-in serial port; parameters: 9600bps, 8N1
+ - "mem":
+	  Save the messages to a reserved area in chip mem. After
           rebooting, they can be read under AmigaOS with the tool
           'dmesg'.
 
 Devices possible for Atari:
 
- - "ser1": ST-MFP serial port ("Modem1"); parameters: 9600bps, 8N1
- - "ser2": SCC channel B serial port ("Modem2"); parameters: 9600bps, 8N1
- - "ser" : default serial port
+ - "ser1":
+	   ST-MFP serial port ("Modem1"); parameters: 9600bps, 8N1
+ - "ser2":
+	   SCC channel B serial port ("Modem2"); parameters: 9600bps, 8N1
+ - "ser" :
+	   default serial port
            This is "ser2" for a Falcon, and "ser1" for any other machine
- - "midi": The MIDI port; parameters: 31250bps, 8N1
- - "par" : parallel port
+ - "midi":
+	   The MIDI port; parameters: 31250bps, 8N1
+ - "par" :
+	   parallel port
+
            The printing routine for this implements a timeout for the
            case there's no printer connected (else the kernel would
            lock up). The timeout is not exact, but usually a few
@@ -205,26 +216,29 @@ Devices possible for Atari:
 
 
 2.6) ramdisk_size=
--------------
+------------------
 
-Syntax: ramdisk_size=<size>
+:Syntax: ramdisk_size=<size>
 
-  This option instructs the kernel to set up a ramdisk of the given
+This option instructs the kernel to set up a ramdisk of the given
 size in KBytes. Do not use this option if the ramdisk contents are
 passed by bootstrap! In this case, the size is selected automatically
 and should not be overwritten.
 
-  The only application is for root filesystems on floppy disks, that
+The only application is for root filesystems on floppy disks, that
 should be loaded into memory. To do that, select the corresponding
 size of the disk as ramdisk size, and set the root device to the disk
 drive (with "root=").
 
 
 2.7) swap=
+
+  I can't find any sign of this option in 2.2.6.
+
 2.8) buff=
 -----------
 
-  I can't find any sign of these options in 2.2.6.
+  I can't find any sign of this option in 2.2.6.
 
 
 3) General Device Options (Amiga and Atari)
@@ -233,13 +247,13 @@ drive (with "root=").
 3.1) ether=
 -----------
 
-Syntax: ether=[<irq>[,<base_addr>[,<mem_start>[,<mem_end>]]]],<dev-name>
+:Syntax: ether=[<irq>[,<base_addr>[,<mem_start>[,<mem_end>]]]],<dev-name>
 
-  <dev-name> is the name of a net driver, as specified in
+<dev-name> is the name of a net driver, as specified in
 drivers/net/Space.c in the Linux source. Most prominent are eth0, ...
 eth3, sl0, ... sl3, ppp0, ..., ppp3, dummy, and lo.
 
-  The non-ethernet drivers (sl, ppp, dummy, lo) obviously ignore the
+The non-ethernet drivers (sl, ppp, dummy, lo) obviously ignore the
 settings by this options. Also, the existing ethernet drivers for
 Linux/m68k (ariadne, a2065, hydra) don't use them because Zorro boards
 are really Plug-'n-Play, so the "ether=" option is useless altogether
@@ -249,9 +263,9 @@ for Linux/m68k.
 3.2) hd=
 --------
 
-Syntax: hd=<cylinders>,<heads>,<sectors>
+:Syntax: hd=<cylinders>,<heads>,<sectors>
 
-  This option sets the disk geometry of an IDE disk. The first hd=
+This option sets the disk geometry of an IDE disk. The first hd=
 option is for the first IDE disk, the second for the second one.
 (I.e., you can give this option twice.) In most cases, you won't have
 to use this option, since the kernel can obtain the geometry data
@@ -262,9 +276,9 @@ disks.
 3.3) max_scsi_luns=
 -------------------
 
-Syntax: max_scsi_luns=<n>
+:Syntax: max_scsi_luns=<n>
 
-  Sets the maximum number of LUNs (logical units) of SCSI devices to
+Sets the maximum number of LUNs (logical units) of SCSI devices to
 be scanned. Valid values for <n> are between 1 and 8. Default is 8 if
 "Probe all LUNs on each SCSI device" was selected during the kernel
 configuration, else 1.
@@ -273,9 +287,9 @@ configuration, else 1.
 3.4) st=
 --------
 
-Syntax: st=<buffer_size>,[<write_thres>,[<max_buffers>]]
+:Syntax: st=<buffer_size>,[<write_thres>,[<max_buffers>]]
 
-  Sets several parameters of the SCSI tape driver. <buffer_size> is
+Sets several parameters of the SCSI tape driver. <buffer_size> is
 the number of 512-byte buffers reserved for tape operations for each
 device. <write_thres> sets the number of blocks which must be filled
 to start an actual write operation to the tape. Maximum value is the
@@ -286,9 +300,9 @@ buffers allocated for all tape devices.
 3.5) dmasound=
 --------------
 
-Syntax: dmasound=[<buffers>,<buffer-size>[,<catch-radius>]]
+:Syntax: dmasound=[<buffers>,<buffer-size>[,<catch-radius>]]
 
-  This option controls some configurations of the Linux/m68k DMA sound
+This option controls some configurations of the Linux/m68k DMA sound
 driver (Amiga and Atari): <buffers> is the number of buffers you want
 to use (minimum 4, default 4), <buffer-size> is the size of each
 buffer in kilobytes (minimum 4, default 32) and <catch-radius> says
@@ -305,20 +319,22 @@ don't need to expand the sound.
 4.1) video=
 -----------
 
-Syntax: video=<fbname>:<sub-options...>
+:Syntax: video=<fbname>:<sub-options...>
 
 The <fbname> parameter specifies the name of the frame buffer,
-eg. most atari users will want to specify `atafb' here. The
+eg. most atari users will want to specify `atafb` here. The
 <sub-options> is a comma-separated list of the sub-options listed
 below.
 
-NB: Please notice that this option was renamed from `atavideo' to
-    `video' during the development of the 1.3.x kernels, thus you
+NB:
+    Please notice that this option was renamed from `atavideo` to
+    `video` during the development of the 1.3.x kernels, thus you
     might need to update your boot-scripts if upgrading to 2.x from
     an 1.2.x kernel.
 
-NBB: The behavior of video= was changed in 2.1.57 so the recommended
-option is to specify the name of the frame buffer.
+NBB:
+    The behavior of video= was changed in 2.1.57 so the recommended
+    option is to specify the name of the frame buffer.
 
 4.1.1) Video Mode
 -----------------
@@ -341,11 +357,11 @@ mode, if the hardware allows. Currently defined names are:
  - falh2           : 896x608x1, Falcon only
  - falh16          : 896x608x4, Falcon only
 
-  If no video mode is given on the command line, the kernel tries the
+If no video mode is given on the command line, the kernel tries the
 modes names "default<n>" in turn, until one is possible with the
 hardware in use.
 
-  A video mode setting doesn't make sense, if the external driver is
+A video mode setting doesn't make sense, if the external driver is
 activated by a "external:" sub-option.
 
 4.1.2) inverse
@@ -358,17 +374,17 @@ option, you can make the background white.
 4.1.3) font
 -----------
 
-Syntax: font:<fontname>
+:Syntax: font:<fontname>
 
 Specify the font to use in text modes. Currently you can choose only
-between `VGA8x8', `VGA8x16' and `PEARL8x8'. `VGA8x8' is default, if the
+between `VGA8x8`, `VGA8x16` and `PEARL8x8`. `VGA8x8` is default, if the
 vertical size of the display is less than 400 pixel rows. Otherwise, the
-`VGA8x16' font is the default.
+`VGA8x16` font is the default.
 
-4.1.4) hwscroll_
-----------------
+4.1.4) `hwscroll_`
+------------------
 
-Syntax: hwscroll_<n>
+:Syntax: `hwscroll_<n>`
 
 The number of additional lines of video memory to reserve for
 speeding up the scrolling ("hardware scrolling"). Hardware scrolling
@@ -378,7 +394,7 @@ possible with plain STs and graphics cards (The former because the
 base address must be on a 256 byte boundary there, the latter because
 the kernel doesn't know how to set the base address at all.)
 
-  By default, <n> is set to the number of visible text lines on the
+By default, <n> is set to the number of visible text lines on the
 display. Thus, the amount of video memory is doubled, compared to no
 hardware scrolling. You can turn off the hardware scrolling altogether
 by setting <n> to 0.
@@ -386,31 +402,31 @@ by setting <n> to 0.
 4.1.5) internal:
 ----------------
 
-Syntax: internal:<xres>;<yres>[;<xres_max>;<yres_max>;<offset>]
+:Syntax: internal:<xres>;<yres>[;<xres_max>;<yres_max>;<offset>]
 
 This option specifies the capabilities of some extended internal video
 hardware, like e.g. OverScan. <xres> and <yres> give the (extended)
 dimensions of the screen.
 
-  If your OverScan needs a black border, you have to write the last
+If your OverScan needs a black border, you have to write the last
 three arguments of the "internal:". <xres_max> is the maximum line
 length the hardware allows, <yres_max> the maximum number of lines.
 <offset> is the offset of the visible part of the screen memory to its
 physical start, in bytes.
 
-  Often, extended interval video hardware has to be activated somehow.
+Often, extended interval video hardware has to be activated somehow.
 For this, see the "sw_*" options below.
 
 4.1.6) external:
 ----------------
 
-Syntax:
-  external:<xres>;<yres>;<depth>;<org>;<scrmem>[;<scrlen>[;<vgabase>\
-           [;<colw>[;<coltype>[;<xres_virtual>]]]]]
+:Syntax:
+  external:<xres>;<yres>;<depth>;<org>;<scrmem>[;<scrlen>[;<vgabase>
+  [;<colw>[;<coltype>[;<xres_virtual>]]]]]
 
-[I had to break this line...]
+.. I had to break this line...
 
-  This is probably the most complicated parameter... It specifies that
+This is probably the most complicated parameter... It specifies that
 you have some external video hardware (a graphics board), and how to
 use it under Linux/m68k. The kernel cannot know more about the hardware
 than you tell it here! The kernel also is unable to set or change any
@@ -418,38 +434,44 @@ video modes, since it doesn't know about any board internal. So, you
 have to switch to that video mode before you start Linux, and cannot
 switch to another mode once Linux has started.
 
-  The first 3 parameters of this sub-option should be obvious: <xres>,
+The first 3 parameters of this sub-option should be obvious: <xres>,
 <yres> and <depth> give the dimensions of the screen and the number of
 planes (depth). The depth is the logarithm to base 2 of the number
 of colors possible. (Or, the other way round: The number of colors is
 2^depth).
 
-  You have to tell the kernel furthermore how the video memory is
+You have to tell the kernel furthermore how the video memory is
 organized. This is done by a letter as <org> parameter:
 
- 'n': "normal planes", i.e. one whole plane after another
- 'i': "interleaved planes", i.e. 16 bit of the first plane, than 16 bit
+ 'n':
+      "normal planes", i.e. one whole plane after another
+ 'i':
+      "interleaved planes", i.e. 16 bit of the first plane, than 16 bit
       of the next, and so on... This mode is used only with the
-	  built-in Atari video modes, I think there is no card that
-	  supports this mode.
- 'p': "packed pixels", i.e. <depth> consecutive bits stand for all
-	  planes of one pixel; this is the most common mode for 8 planes
-	  (256 colors) on graphic cards
- 't': "true color" (more or less packed pixels, but without a color
-	  lookup table); usually depth is 24
+      built-in Atari video modes, I think there is no card that
+      supports this mode.
+ 'p':
+      "packed pixels", i.e. <depth> consecutive bits stand for all
+      planes of one pixel; this is the most common mode for 8 planes
+      (256 colors) on graphic cards
+ 't':
+      "true color" (more or less packed pixels, but without a color
+      lookup table); usually depth is 24
 
 For monochrome modes (i.e., <depth> is 1), the <org> letter has a
 different meaning:
 
- 'n': normal colors, i.e. 0=white, 1=black
- 'i': inverted colors, i.e. 0=black, 1=white
+ 'n':
+      normal colors, i.e. 0=white, 1=black
+ 'i':
+      inverted colors, i.e. 0=black, 1=white
 
-  The next important information about the video hardware is the base
+The next important information about the video hardware is the base
 address of the video memory. That is given in the <scrmem> parameter,
 as a hexadecimal number with a "0x" prefix. You have to find out this
 address in the documentation of your hardware.
 
-  The next parameter, <scrlen>, tells the kernel about the size of the
+The next parameter, <scrlen>, tells the kernel about the size of the
 video memory. If it's missing, the size is calculated from <xres>,
 <yres>, and <depth>. For now, it is not useful to write a value here.
 It would be used only for hardware scrolling (which isn't possible
@@ -460,7 +482,7 @@ empty, either by ending the "external:" after the video address or by
 writing two consecutive semicolons, if you want to give a <vgabase>
 (it is allowed to leave this parameter empty).
 
-  The <vgabase> parameter is optional. If it is not given, the kernel
+The <vgabase> parameter is optional. If it is not given, the kernel
 cannot read or write any color registers of the video hardware, and
 thus you have to set appropriate colors before you start Linux. But if
 your card is somehow VGA compatible, you can tell the kernel the base
@@ -472,18 +494,18 @@ uses the addresses vgabase+0x3c7...vgabase+0x3c9. The <vgabase>
 parameter is written in hexadecimal with a "0x" prefix, just as
 <scrmem>.
 
-  <colw> is meaningful only if <vgabase> is specified. It tells the
+<colw> is meaningful only if <vgabase> is specified. It tells the
 kernel how wide each of the color register is, i.e. the number of bits
 per single color (red/green/blue). Default is 6, another quite usual
 value is 8.
 
-  Also <coltype> is used together with <vgabase>. It tells the kernel
+Also <coltype> is used together with <vgabase>. It tells the kernel
 about the color register model of your gfx board. Currently, the types
 "vga" (which is also the default) and "mv300" (SANG MV300) are
 implemented.
 
-  Parameter <xres_virtual> is required for ProMST or ET4000 cards where
-the physical linelength differs from the visible length. With ProMST, 
+Parameter <xres_virtual> is required for ProMST or ET4000 cards where
+the physical linelength differs from the visible length. With ProMST,
 xres_virtual must be set to 2048. For ET4000, xres_virtual depends on the
 initialisation of the video-card.
 If you're missing a corresponding yres_virtual: the external part is legacy,
@@ -499,13 +521,13 @@ currently works only with the ScreenWonder!
 4.1.8) monitorcap:
 -------------------
 
-Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
+:Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
 
 This describes the capabilities of a multisync monitor. Don't use it
 with a fixed-frequency monitor! For now, only the Falcon frame buffer
 uses the settings of "monitorcap:".
 
-  <vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
+<vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
 your monitor can work with, in Hz. <hmin> and <hmax> are the same for
 the horizontal frequency, in kHz.
 
@@ -520,28 +542,28 @@ If this option is given, the framebuffer device doesn't do any video
 mode calculations and settings on its own. The only Atari fb device
 that does this currently is the Falcon.
 
-  What you reach with this: Settings for unknown video extensions
+What you reach with this: Settings for unknown video extensions
 aren't overridden by the driver, so you can still use the mode found
 when booting, when the driver doesn't know to set this mode itself.
 But this also means, that you can't switch video modes anymore...
 
-  An example where you may want to use "keep" is the ScreenBlaster for
+An example where you may want to use "keep" is the ScreenBlaster for
 the Falcon.
 
 
 4.2) atamouse=
 --------------
 
-Syntax: atamouse=<x-threshold>,[<y-threshold>]
+:Syntax: atamouse=<x-threshold>,[<y-threshold>]
 
-  With this option, you can set the mouse movement reporting threshold.
+With this option, you can set the mouse movement reporting threshold.
 This is the number of pixels of mouse movement that have to accumulate
 before the IKBD sends a new mouse packet to the kernel. Higher values
 reduce the mouse interrupt load and thus reduce the chance of keyboard
 overruns. Lower values give a slightly faster mouse responses and
 slightly better mouse tracking.
 
-  You can set the threshold in x and y separately, but usually this is
+You can set the threshold in x and y separately, but usually this is
 of little practical use. If there's just one number in the option, it
 is used for both dimensions. The default value is 2 for both
 thresholds.
@@ -550,7 +572,7 @@ thresholds.
 4.3) ataflop=
 -------------
 
-Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]]
+:Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]]
 
    The drive type may be 0, 1, or 2, for DD, HD, and ED, resp. This
    setting affects how many buffers are reserved and which formats are
@@ -563,15 +585,15 @@ Syntax: ataflop=<drive type>[,<trackbuffering>[,<steprateA>[,<steprateB>]]]
    no for the Medusa and yes for all others.
 
    With the two following parameters, you can change the default
-   steprate used for drive A and B, resp. 
+   steprate used for drive A and B, resp.
 
 
 4.4) atascsi=
 -------------
 
-Syntax: atascsi=<can_queue>[,<cmd_per_lun>[,<scat-gat>[,<host-id>[,<tagged>]]]]
+:Syntax: atascsi=<can_queue>[,<cmd_per_lun>[,<scat-gat>[,<host-id>[,<tagged>]]]]
 
-  This option sets some parameters for the Atari native SCSI driver.
+This option sets some parameters for the Atari native SCSI driver.
 Generally, any number of arguments can be omitted from the end. And
 for each of the numbers, a negative value means "use default". The
 defaults depend on whether TT-style or Falcon-style SCSI is used.
@@ -597,11 +619,14 @@ ignored (others aren't affected).
     32). Default: 8/1. (Note: Values > 1 seem to cause problems on a
     Falcon, cause not yet known.)
 
-      The <cmd_per_lun> value at a great part determines the amount of
+    The <cmd_per_lun> value at a great part determines the amount of
     memory SCSI reserves for itself. The formula is rather
     complicated, but I can give you some hints:
-      no scatter-gather  : cmd_per_lun * 232 bytes
-      full scatter-gather: cmd_per_lun * approx. 17 Kbytes
+
+      no scatter-gather:
+	cmd_per_lun * 232 bytes
+      full scatter-gather:
+	cmd_per_lun * approx. 17 Kbytes
 
   <scat-gat>:
     Size of the scatter-gather table, i.e. the number of requests
@@ -634,19 +659,23 @@ ignored (others aren't affected).
 4.5 switches=
 -------------
 
-Syntax: switches=<list of switches>
+:Syntax: switches=<list of switches>
 
-  With this option you can switch some hardware lines that are often
+With this option you can switch some hardware lines that are often
 used to enable/disable certain hardware extensions. Examples are
 OverScan, overclocking, ...
 
-  The <list of switches> is a comma-separated list of the following
+The <list of switches> is a comma-separated list of the following
 items:
 
-  ikbd: set RTS of the keyboard ACIA high
-  midi: set RTS of the MIDI ACIA high
-  snd6: set bit 6 of the PSG port A
-  snd7: set bit 6 of the PSG port A
+  ikbd:
+	set RTS of the keyboard ACIA high
+  midi:
+	set RTS of the MIDI ACIA high
+  snd6:
+	set bit 6 of the PSG port A
+  snd7:
+	set bit 6 of the PSG port A
 
 It doesn't make sense to mention a switch more than once (no
 difference to only once), but you can give as many switches as you
@@ -654,16 +683,16 @@ want to enable different features. The switch lines are set as early
 as possible during kernel initialization (even before determining the
 present hardware.)
 
-  All of the items can also be prefixed with "ov_", i.e. "ov_ikbd",
-"ov_midi", ... These options are meant for switching on an OverScan
+All of the items can also be prefixed with `ov_`, i.e. `ov_ikbd`,
+`ov_midi`, ... These options are meant for switching on an OverScan
 video extension. The difference to the bare option is that the
 switch-on is done after video initialization, and somehow synchronized
 to the HBLANK. A speciality is that ov_ikbd and ov_midi are switched
 off before rebooting, so that OverScan is disabled and TOS boots
 correctly.
 
-  If you give an option both, with and without the "ov_" prefix, the
-earlier initialization ("ov_"-less) takes precedence. But the
+If you give an option both, with and without the `ov_` prefix, the
+earlier initialization (`ov_`-less) takes precedence. But the
 switching-off on reset still happens in this case.
 
 5) Options for Amiga Only:
@@ -672,10 +701,10 @@ switching-off on reset still happens in this case.
 5.1) video=
 -----------
 
-Syntax: video=<fbname>:<sub-options...>
+:Syntax: video=<fbname>:<sub-options...>
 
 The <fbname> parameter specifies the name of the frame buffer, valid
-options are `amifb', `cyber', 'virge', `retz3' and `clgen', provided
+options are `amifb`, `cyber`, 'virge', `retz3` and `clgen`, provided
 that the respective frame buffer devices have been compiled into the
 kernel (or compiled as loadable modules). The behavior of the <fbname>
 option was changed in 2.1.57 so it is now recommended to specify this
@@ -697,9 +726,11 @@ predefined video modes are available:
 NTSC modes:
  - ntsc            : 640x200, 15 kHz, 60 Hz
  - ntsc-lace       : 640x400, 15 kHz, 60 Hz interlaced
+
 PAL modes:
  - pal             : 640x256, 15 kHz, 50 Hz
  - pal-lace        : 640x512, 15 kHz, 50 Hz interlaced
+
 ECS modes:
  - multiscan       : 640x480, 29 kHz, 57 Hz
  - multiscan-lace  : 640x960, 29 kHz, 57 Hz interlaced
@@ -715,6 +746,7 @@ ECS modes:
  - dblpal-lace     : 640x1024, 27 kHz, 47 Hz interlaced
  - dblntsc         : 640x200, 27 kHz, 57 Hz doublescan
  - dblpal          : 640x256, 27 kHz, 47 Hz doublescan
+
 VGA modes:
  - vga             : 640x480, 31 kHz, 60 Hz
  - vga70           : 640x400, 31 kHz, 70 Hz
@@ -726,7 +758,7 @@ chipset and 8-bit color for the AGA chipset.
 5.1.2) depth
 ------------
 
-Syntax: depth:<nr. of bit-planes>
+:Syntax: depth:<nr. of bit-planes>
 
 Specify the number of bit-planes for the selected video-mode.
 
@@ -739,32 +771,32 @@ Use inverted display (black on white). Functionally the same as the
 5.1.4) font
 -----------
 
-Syntax: font:<fontname>
+:Syntax: font:<fontname>
 
 Specify the font to use in text modes. Functionally the same as the
-"font" sub-option for the Atari, except that `PEARL8x8' is used instead
-of `VGA8x8' if the vertical size of the display is less than 400 pixel
+"font" sub-option for the Atari, except that `PEARL8x8` is used instead
+of `VGA8x8` if the vertical size of the display is less than 400 pixel
 rows.
 
 5.1.5) monitorcap:
 -------------------
 
-Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
+:Syntax: monitorcap:<vmin>;<vmax>;<hmin>;<hmax>
 
 This describes the capabilities of a multisync monitor. For now, only
 the color frame buffer uses the settings of "monitorcap:".
 
-  <vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
+<vmin> and <vmax> are the minimum and maximum, resp., vertical frequencies
 your monitor can work with, in Hz. <hmin> and <hmax> are the same for
 the horizontal frequency, in kHz.
 
-  The defaults are 50;90;15;38 (Generic Amiga multisync monitor).
+The defaults are 50;90;15;38 (Generic Amiga multisync monitor).
 
 
 5.2) fd_def_df0=
 ----------------
 
-Syntax: fd_def_df0=<value>
+:Syntax: fd_def_df0=<value>
 
 Sets the df0 value for "silent" floppy drives. The value should be in
 hexadecimal with "0x" prefix.
@@ -773,7 +805,7 @@ hexadecimal with "0x" prefix.
 5.3) wd33c93=
 -------------
 
-Syntax: wd33c93=<sub-options...>
+:Syntax: wd33c93=<sub-options...>
 
 These options affect the A590/A2091, A3000 and GVP Series II SCSI
 controllers.
@@ -784,9 +816,9 @@ below.
 5.3.1) nosync
 -------------
 
-Syntax: nosync:bitmask
+:Syntax: nosync:bitmask
 
-  bitmask is a byte where the 1st 7 bits correspond with the 7
+bitmask is a byte where the 1st 7 bits correspond with the 7
 possible SCSI devices. Set a bit to prevent sync negotiation on that
 device. To maintain backwards compatibility, a command-line such as
 "wd33c93=255" will be automatically translated to
@@ -796,35 +828,35 @@ all devices, eg. nosync:0xff.
 5.3.2) period
 -------------
 
-Syntax: period:ns
+:Syntax: period:ns
 
-  `ns' is the minimum # of nanoseconds in a SCSI data transfer
+`ns` is the minimum # of nanoseconds in a SCSI data transfer
 period. Default is 500; acceptable values are 250 - 1000.
 
 5.3.3) disconnect
 -----------------
 
-Syntax: disconnect:x
+:Syntax: disconnect:x
 
-  Specify x = 0 to never allow disconnects, 2 to always allow them.
+Specify x = 0 to never allow disconnects, 2 to always allow them.
 x = 1 does 'adaptive' disconnects, which is the default and generally
 the best choice.
 
 5.3.4) debug
 ------------
 
-Syntax: debug:x
+:Syntax: debug:x
 
-  If `DEBUGGING_ON' is defined, x is a bit mask that causes various
+If `DEBUGGING_ON` is defined, x is a bit mask that causes various
 types of debug output to printed - see the DB_xxx defines in
 wd33c93.h.
 
 5.3.5) clock
 ------------
 
-Syntax: clock:x
+:Syntax: clock:x
 
-  x = clock input in MHz for WD33c93 chip. Normal values would be from
+x = clock input in MHz for WD33c93 chip. Normal values would be from
 8 through 20. The default value depends on your hostadapter(s),
 default for the A3000 internal controller is 14, for the A2091 it's 8
 and for the GVP hostadapters it's either 8 or 14, depending on the
@@ -834,15 +866,15 @@ hostadapters.
 5.3.6) next
 -----------
 
-  No argument. Used to separate blocks of keywords when there's more
+No argument. Used to separate blocks of keywords when there's more
 than one wd33c93-based host adapter in the system.
 
 5.3.7) nodma
 ------------
 
-Syntax: nodma:x
+:Syntax: nodma:x
 
-  If x is 1 (or if the option is just written as "nodma"), the WD33c93
+If x is 1 (or if the option is just written as "nodma"), the WD33c93
 controller will not use DMA (= direct memory access) to access the
 Amiga's memory.  This is useful for some systems (like A3000's and
 A4000's with the A3640 accelerator, revision 3.0) that have problems
@@ -853,32 +885,27 @@ possible.
 5.4) gvp11=
 -----------
 
-Syntax: gvp11=<addr-mask>
+:Syntax: gvp11=<addr-mask>
 
-  The earlier versions of the GVP driver did not handle DMA
+The earlier versions of the GVP driver did not handle DMA
 address-mask settings correctly which made it necessary for some
 people to use this option, in order to get their GVP controller
 running under Linux. These problems have hopefully been solved and the
 use of this option is now highly unrecommended!
 
-  Incorrect use can lead to unpredictable behavior, so please only use
+Incorrect use can lead to unpredictable behavior, so please only use
 this option if you *know* what you are doing and have a reason to do
 so. In any case if you experience problems and need to use this
 option, please inform us about it by mailing to the Linux/68k kernel
 mailing list.
 
-  The address mask set by this option specifies which addresses are
+The address mask set by this option specifies which addresses are
 valid for DMA with the GVP Series II SCSI controller. An address is
 valid, if no bits are set except the bits that are set in the mask,
 too.
 
-  Some versions of the GVP can only DMA into a 24 bit address range,
+Some versions of the GVP can only DMA into a 24 bit address range,
 some can address a 25 bit address range while others can use the whole
 32 bit address range for DMA. The correct setting depends on your
 controller and should be autodetected by the driver. An example is the
 24 bit region which is specified by a mask of 0x00fffffe.
-
-
-/* Local Variables: */
-/* mode: text       */
-/* End:             */
-- 
2.21.0

[PATCH v2 05/29] docs: cma/debugfs.txt: convert docs to ReST and rename to *.rst

[Mauro Carvalho Chehab]

The debugfs interface for CMA should be there together with other
mm-related documents.

Convert this small file to ReST and move it to its rightful place.

The conversion is actually quite simple: just add a title for the
document. In order to make it to look better for the audience,
also mark the "echo" command as a literal block.

While this is not part of any book, mark it as :orphan:,
in order to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/cma/{debugfs.txt => debugfs.rst} | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)
 rename Documentation/cma/{debugfs.txt => debugfs.rst} (91%)

diff --git a/Documentation/cma/debugfs.txt b/Documentation/cma/debugfs.rst
similarity index 91%
rename from Documentation/cma/debugfs.txt
rename to Documentation/cma/debugfs.rst
index 6cef20a8cedc..518fe401b5ee 100644
--- a/Documentation/cma/debugfs.txt
+++ b/Documentation/cma/debugfs.rst
@@ -1,3 +1,9 @@
+:orphan:
+
+=====================
+CMA Debugfs Interface
+=====================
+
 The CMA debugfs interface is useful to retrieve basic information out of the
 different CMA areas and to test allocation/release in each of the areas.
 
@@ -12,7 +18,7 @@ The structure of the files created under that directory is as follows:
  - [RO] count: Amount of memory in the CMA area.
  - [RO] order_per_bit: Order of pages represented by one bit.
  - [RO] bitmap: The bitmap of page states in the zone.
- - [WO] alloc: Allocate N pages from that CMA area. For example:
+ - [WO] alloc: Allocate N pages from that CMA area. For example::
 
 	echo 5 > <debugfs>/cma/cma-2/alloc
 
-- 
2.21.0

[PATCH v2 06/29] docs: console.txt: convert docs to ReST and rename to *.rst

[Mauro Carvalho Chehab]

Convert this small file to ReST in preparation for adding it to
the driver-api book.

While this is not part of the driver-api book, mark it as
:orphan:, in order to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 .../console/{console.txt => console.rst}      | 63 ++++++++++---------
 Documentation/fb/fbcon.rst                    |  4 +-
 drivers/tty/Kconfig                           |  2 +-
 3 files changed, 38 insertions(+), 31 deletions(-)
 rename Documentation/console/{console.txt => console.rst} (80%)

diff --git a/Documentation/console/console.txt b/Documentation/console/console.rst
similarity index 80%
rename from Documentation/console/console.txt
rename to Documentation/console/console.rst
index d73c2ab4beda..b374141b027e 100644
--- a/Documentation/console/console.txt
+++ b/Documentation/console/console.rst
@@ -1,3 +1,6 @@
+:orphan:
+
+===============
 Console Drivers
 ===============
 
@@ -17,25 +20,26 @@ of driver occupying the consoles.) They can only take over the console that is
 occupied by the system driver. In the same token, if the modular driver is
 released by the console, the system driver will take over.
 
-Modular drivers, from the programmer's point of view, have to call:
+Modular drivers, from the programmer's point of view, have to call::
 
 	 do_take_over_console() - load and bind driver to console layer
 	 give_up_console() - unload driver; it will only work if driver
 			     is fully unbound
 
-In newer kernels, the following are also available:
+In newer kernels, the following are also available::
 
 	 do_register_con_driver()
 	 do_unregister_con_driver()
 
 If sysfs is enabled, the contents of /sys/class/vtconsole can be
 examined. This shows the console backends currently registered by the
-system which are named vtcon<n> where <n> is an integer from 0 to 15. Thus:
+system which are named vtcon<n> where <n> is an integer from 0 to 15.
+Thus::
 
        ls /sys/class/vtconsole
        .  ..  vtcon0  vtcon1
 
-Each directory in /sys/class/vtconsole has 3 files:
+Each directory in /sys/class/vtconsole has 3 files::
 
      ls /sys/class/vtconsole/vtcon0
      .  ..  bind  name  uevent
@@ -46,27 +50,29 @@ What do these files signify?
         read, or acts to bind or unbind the driver to the virtual consoles
         when written to. The possible values are:
 
-	0 - means the driver is not bound and if echo'ed, commands the driver
+	0
+	  - means the driver is not bound and if echo'ed, commands the driver
 	    to unbind
 
-        1 - means the driver is bound and if echo'ed, commands the driver to
+        1
+	  - means the driver is bound and if echo'ed, commands the driver to
 	    bind
 
-     2. name - read-only file. Shows the name of the driver in this format:
+     2. name - read-only file. Shows the name of the driver in this format::
 
-	cat /sys/class/vtconsole/vtcon0/name
-	(S) VGA+
+	  cat /sys/class/vtconsole/vtcon0/name
+	  (S) VGA+
 
-	    '(S)' stands for a (S)ystem driver, i.e., it cannot be directly
-	    commanded to bind or unbind
+	      '(S)' stands for a (S)ystem driver, i.e., it cannot be directly
+	      commanded to bind or unbind
 
-	    'VGA+' is the name of the driver
+	      'VGA+' is the name of the driver
 
-	cat /sys/class/vtconsole/vtcon1/name
-	(M) frame buffer device
+	  cat /sys/class/vtconsole/vtcon1/name
+	  (M) frame buffer device
 
-	    In this case, '(M)' stands for a (M)odular driver, one that can be
-	    directly commanded to bind or unbind.
+	      In this case, '(M)' stands for a (M)odular driver, one that can be
+	      directly commanded to bind or unbind.
 
      3. uevent - ignore this file
 
@@ -75,14 +81,17 @@ driver takes over the consoles vacated by the driver. Binding, on the other
 hand, will bind the driver to the consoles that are currently occupied by a
 system driver.
 
-NOTE1: Binding and unbinding must be selected in Kconfig. It's under:
+NOTE1:
+  Binding and unbinding must be selected in Kconfig. It's under::
 
-Device Drivers -> Character devices -> Support for binding and unbinding
-console drivers
+    Device Drivers ->
+	Character devices ->
+		Support for binding and unbinding console drivers
 
-NOTE2: If any of the virtual consoles are in KD_GRAPHICS mode, then binding or
-unbinding will not succeed. An example of an application that sets the console
-to KD_GRAPHICS is X.
+NOTE2:
+  If any of the virtual consoles are in KD_GRAPHICS mode, then binding or
+  unbinding will not succeed. An example of an application that sets the
+  console to KD_GRAPHICS is X.
 
 How useful is this feature? This is very useful for console driver
 developers. By unbinding the driver from the console layer, one can unload the
@@ -92,10 +101,10 @@ framebuffer console to VGA console and vice versa, this feature also makes
 this possible. (NOTE NOTE NOTE: Please read fbcon.txt under Documentation/fb
 for more details.)
 
-Notes for developers:
-=====================
+Notes for developers
+====================
 
-do_take_over_console() is now broken up into:
+do_take_over_console() is now broken up into::
 
      do_register_con_driver()
      do_bind_con_driver() - private function
@@ -104,7 +113,7 @@ give_up_console() is a wrapper to do_unregister_con_driver(), and a driver must
 be fully unbound for this call to succeed. con_is_bound() will check if the
 driver is bound or not.
 
-Guidelines for console driver writers:
+Guidelines for console driver writers
 =====================================
 
 In order for binding to and unbinding from the console to properly work,
@@ -140,6 +149,4 @@ The current crop of console drivers should still work correctly, but binding
 and unbinding them may cause problems. With minimal fixes, these drivers can
 be made to work correctly.
 
-==========================
 Antonino Daplas <adaplas@pol.net>
-
diff --git a/Documentation/fb/fbcon.rst b/Documentation/fb/fbcon.rst
index cfb9f7c38f18..22112718dd5d 100644
--- a/Documentation/fb/fbcon.rst
+++ b/Documentation/fb/fbcon.rst
@@ -187,7 +187,7 @@ the hardware. Thus, in a VGA console::
 Assuming the VGA driver can be unloaded, one must first unbind the VGA driver
 from the console layer before unloading the driver.  The VGA driver cannot be
 unloaded if it is still bound to the console layer. (See
-Documentation/console/console.txt for more information).
+Documentation/console/console.rst for more information).
 
 This is more complicated in the case of the framebuffer console (fbcon),
 because fbcon is an intermediate layer between the console and the drivers::
@@ -204,7 +204,7 @@ fbcon. Thus, there is no need to explicitly unbind the fbdev drivers from
 fbcon.
 
 So, how do we unbind fbcon from the console? Part of the answer is in
-Documentation/console/console.txt. To summarize:
+Documentation/console/console.rst. To summarize:
 
 Echo a value to the bind file that represents the framebuffer console
 driver. So assuming vtcon1 represents fbcon, then::
diff --git a/drivers/tty/Kconfig b/drivers/tty/Kconfig
index 0e3e4dacbc12..1cb50f19d58c 100644
--- a/drivers/tty/Kconfig
+++ b/drivers/tty/Kconfig
@@ -93,7 +93,7 @@ config VT_HW_CONSOLE_BINDING
          select the console driver that will serve as the backend for the
          virtual terminals.
 
-	 See <file:Documentation/console/console.txt> for more
+	 See <file:Documentation/console/console.rst> for more
 	 information. For framebuffer console users, please refer to
 	 <file:Documentation/fb/fbcon.rst>.
 
-- 
2.21.0

Re: [PATCH v2 06/29] docs: console.txt: convert docs to ReST and rename to *.rst

[Greg Kroah-Hartman]

On Tue, Jun 18, 2019 at 05:53:24PM -0300, Mauro Carvalho Chehab wrote:
> Convert this small file to ReST in preparation for adding it to
> the driver-api book.
> 
> While this is not part of the driver-api book, mark it as
> :orphan:, in order to avoid build warnings.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>

[PATCH v2 07/29] docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst

[Mauro Carvalho Chehab]

Convert this small file to ReST format and rename it.

Most of the conversion were related to adjusting whitespaces
in order for each section to be properly parsed.

While this is not part of any book, mark it as :orphan:, in order
to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/pti/pti_intel_mid.rst | 106 ++++++++++++++++++++++++++++
 Documentation/pti/pti_intel_mid.txt |  99 --------------------------
 2 files changed, 106 insertions(+), 99 deletions(-)
 create mode 100644 Documentation/pti/pti_intel_mid.rst
 delete mode 100644 Documentation/pti/pti_intel_mid.txt

diff --git a/Documentation/pti/pti_intel_mid.rst b/Documentation/pti/pti_intel_mid.rst
new file mode 100644
index 000000000000..ea05725174cb
--- /dev/null
+++ b/Documentation/pti/pti_intel_mid.rst
@@ -0,0 +1,106 @@
+:orphan:
+
+=============
+Intel MID PTI
+=============
+
+The Intel MID PTI project is HW implemented in Intel Atom
+system-on-a-chip designs based on the Parallel Trace
+Interface for MIPI P1149.7 cJTAG standard.  The kernel solution
+for this platform involves the following files::
+
+	./include/linux/pti.h
+	./drivers/.../n_tracesink.h
+	./drivers/.../n_tracerouter.c
+	./drivers/.../n_tracesink.c
+	./drivers/.../pti.c
+
+pti.c is the driver that enables various debugging features
+popular on platforms from certain mobile manufacturers.
+n_tracerouter.c and n_tracesink.c allow extra system information to
+be collected and routed to the pti driver, such as trace
+debugging data from a modem.  Although n_tracerouter
+and n_tracesink are a part of the complete PTI solution,
+these two line disciplines can work separately from
+pti.c and route any data stream from one /dev/tty node
+to another /dev/tty node via kernel-space.  This provides
+a stable, reliable connection that will not break unless
+the user-space application shuts down (plus avoids
+kernel->user->kernel context switch overheads of routing
+data).
+
+An example debugging usage for this driver system:
+
+  * Hook /dev/ttyPTI0 to syslogd.  Opening this port will also start
+    a console device to further capture debugging messages to PTI.
+  * Hook /dev/ttyPTI1 to modem debugging data to write to PTI HW.
+    This is where n_tracerouter and n_tracesink are used.
+  * Hook /dev/pti to a user-level debugging application for writing
+    to PTI HW.
+  * `Use mipi_` Kernel Driver API in other device drivers for
+    debugging to PTI by first requesting a PTI write address via
+    mipi_request_masterchannel(1).
+
+Below is example pseudo-code on how a 'privileged' application
+can hook up n_tracerouter and n_tracesink to any tty on
+a system.  'Privileged' means the application has enough
+privileges to successfully manipulate the ldisc drivers
+but is not just blindly executing as 'root'. Keep in mind
+the use of ioctl(,TIOCSETD,) is not specific to the n_tracerouter
+and n_tracesink line discpline drivers but is a generic
+operation for a program to use a line discpline driver
+on a tty port other than the default n_tty::
+
+  /////////// To hook up n_tracerouter and n_tracesink /////////
+
+  // Note that n_tracerouter depends on n_tracesink.
+  #include <errno.h>
+  #define ONE_TTY "/dev/ttyOne"
+  #define TWO_TTY "/dev/ttyTwo"
+
+  // needed global to hand onto ldisc connection
+  static int g_fd_source = -1;
+  static int g_fd_sink  = -1;
+
+  // these two vars used to grab LDISC values from loaded ldisc drivers
+  // in OS.  Look at /proc/tty/ldiscs to get the right numbers from
+  // the ldiscs loaded in the system.
+  int source_ldisc_num, sink_ldisc_num = -1;
+  int retval;
+
+  g_fd_source = open(ONE_TTY, O_RDWR); // must be R/W
+  g_fd_sink   = open(TWO_TTY, O_RDWR); // must be R/W
+
+  if (g_fd_source <= 0) || (g_fd_sink <= 0) {
+     // doubt you'll want to use these exact error lines of code
+     printf("Error on open(). errno: %d\n",errno);
+     return errno;
+  }
+
+  retval = ioctl(g_fd_sink, TIOCSETD, &sink_ldisc_num);
+  if (retval < 0) {
+     printf("Error on ioctl().  errno: %d\n", errno);
+     return errno;
+  }
+
+  retval = ioctl(g_fd_source, TIOCSETD, &source_ldisc_num);
+  if (retval < 0) {
+     printf("Error on ioctl().  errno: %d\n", errno);
+     return errno;
+  }
+
+  /////////// To disconnect n_tracerouter and n_tracesink ////////
+
+  // First make sure data through the ldiscs has stopped.
+
+  // Second, disconnect ldiscs.  This provides a
+  // little cleaner shutdown on tty stack.
+  sink_ldisc_num = 0;
+  source_ldisc_num = 0;
+  ioctl(g_fd_uart, TIOCSETD, &sink_ldisc_num);
+  ioctl(g_fd_gadget, TIOCSETD, &source_ldisc_num);
+
+  // Three, program closes connection, and cleanup:
+  close(g_fd_uart);
+  close(g_fd_gadget);
+  g_fd_uart = g_fd_gadget = NULL;
diff --git a/Documentation/pti/pti_intel_mid.txt b/Documentation/pti/pti_intel_mid.txt
deleted file mode 100644
index e7a5b6d1f7a9..000000000000
--- a/Documentation/pti/pti_intel_mid.txt
+++ /dev/null
@@ -1,99 +0,0 @@
-The Intel MID PTI project is HW implemented in Intel Atom
-system-on-a-chip designs based on the Parallel Trace
-Interface for MIPI P1149.7 cJTAG standard.  The kernel solution
-for this platform involves the following files:
-
-./include/linux/pti.h
-./drivers/.../n_tracesink.h
-./drivers/.../n_tracerouter.c
-./drivers/.../n_tracesink.c
-./drivers/.../pti.c
-
-pti.c is the driver that enables various debugging features
-popular on platforms from certain mobile manufacturers.
-n_tracerouter.c and n_tracesink.c allow extra system information to
-be collected and routed to the pti driver, such as trace
-debugging data from a modem.  Although n_tracerouter
-and n_tracesink are a part of the complete PTI solution,
-these two line disciplines can work separately from
-pti.c and route any data stream from one /dev/tty node
-to another /dev/tty node via kernel-space.  This provides
-a stable, reliable connection that will not break unless
-the user-space application shuts down (plus avoids
-kernel->user->kernel context switch overheads of routing
-data).
-
-An example debugging usage for this driver system:
-   *Hook /dev/ttyPTI0 to syslogd.  Opening this port will also start
-    a console device to further capture debugging messages to PTI.
-   *Hook /dev/ttyPTI1 to modem debugging data to write to PTI HW.
-    This is where n_tracerouter and n_tracesink are used.
-   *Hook /dev/pti to a user-level debugging application for writing
-    to PTI HW.
-   *Use mipi_* Kernel Driver API in other device drivers for
-    debugging to PTI by first requesting a PTI write address via
-    mipi_request_masterchannel(1).
-
-Below is example pseudo-code on how a 'privileged' application
-can hook up n_tracerouter and n_tracesink to any tty on
-a system.  'Privileged' means the application has enough
-privileges to successfully manipulate the ldisc drivers
-but is not just blindly executing as 'root'. Keep in mind
-the use of ioctl(,TIOCSETD,) is not specific to the n_tracerouter
-and n_tracesink line discpline drivers but is a generic
-operation for a program to use a line discpline driver
-on a tty port other than the default n_tty.
-
-/////////// To hook up n_tracerouter and n_tracesink /////////
-
-// Note that n_tracerouter depends on n_tracesink.
-#include <errno.h>
-#define ONE_TTY "/dev/ttyOne"
-#define TWO_TTY "/dev/ttyTwo"
-
-// needed global to hand onto ldisc connection
-static int g_fd_source = -1;
-static int g_fd_sink  = -1;
-
-// these two vars used to grab LDISC values from loaded ldisc drivers
-// in OS.  Look at /proc/tty/ldiscs to get the right numbers from
-// the ldiscs loaded in the system.
-int source_ldisc_num, sink_ldisc_num = -1;
-int retval;
-
-g_fd_source = open(ONE_TTY, O_RDWR); // must be R/W
-g_fd_sink   = open(TWO_TTY, O_RDWR); // must be R/W
-
-if (g_fd_source <= 0) || (g_fd_sink <= 0) {
-   // doubt you'll want to use these exact error lines of code
-   printf("Error on open(). errno: %d\n",errno);
-   return errno;
-}
-
-retval = ioctl(g_fd_sink, TIOCSETD, &sink_ldisc_num);
-if (retval < 0) {
-   printf("Error on ioctl().  errno: %d\n", errno);
-   return errno;
-}
-
-retval = ioctl(g_fd_source, TIOCSETD, &source_ldisc_num);
-if (retval < 0) {
-   printf("Error on ioctl().  errno: %d\n", errno);
-   return errno;
-}
-
-/////////// To disconnect n_tracerouter and n_tracesink ////////
-
-// First make sure data through the ldiscs has stopped.
-
-// Second, disconnect ldiscs.  This provides a
-// little cleaner shutdown on tty stack.
-sink_ldisc_num = 0;
-source_ldisc_num = 0;
-ioctl(g_fd_uart, TIOCSETD, &sink_ldisc_num);
-ioctl(g_fd_gadget, TIOCSETD, &source_ldisc_num);
-
-// Three, program closes connection, and cleanup:
-close(g_fd_uart);
-close(g_fd_gadget);
-g_fd_uart = g_fd_gadget = NULL;
-- 
2.21.0

[PATCH v2 08/29] docs: early-userspace: convert docs to ReST and rename to *.rst

[Mauro Carvalho Chehab]

The two files there describes a Kernel API feature, used to
support early userspace stuff. Prepare for moving them to
the kernel API book by converting to ReST format.

The conversion itself was quite trivial: just add/mark a few
titles as such, add a literal block markup, add a table markup
and a few blank lines, in order to make Sphinx to properly parse it.

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>
---
 .../{buffer-format.txt => buffer-format.rst}  | 19 +++++++++++++------
 .../{README => early_userspace_support.rst}   |  3 +++
 Documentation/early-userspace/index.rst       | 18 ++++++++++++++++++
 Documentation/filesystems/nfs/nfsroot.txt     |  2 +-
 .../filesystems/ramfs-rootfs-initramfs.txt    |  4 ++--
 usr/Kconfig                                   |  2 +-
 6 files changed, 38 insertions(+), 10 deletions(-)
 rename Documentation/early-userspace/{buffer-format.txt => buffer-format.rst} (91%)
 rename Documentation/early-userspace/{README => early_userspace_support.rst} (99%)
 create mode 100644 Documentation/early-userspace/index.rst

diff --git a/Documentation/early-userspace/buffer-format.txt b/Documentation/early-userspace/buffer-format.rst
similarity index 91%
rename from Documentation/early-userspace/buffer-format.txt
rename to Documentation/early-userspace/buffer-format.rst
index e1fd7f9dad16..7f74e301fdf3 100644
--- a/Documentation/early-userspace/buffer-format.txt
+++ b/Documentation/early-userspace/buffer-format.rst
@@ -1,8 +1,10 @@
-		       initramfs buffer format
-		       -----------------------
+=======================
+initramfs buffer format
+=======================
 
-		       Al Viro, H. Peter Anvin
-		      Last revision: 2002-01-13
+Al Viro, H. Peter Anvin
+
+Last revision: 2002-01-13
 
 Starting with kernel 2.5.x, the old "initial ramdisk" protocol is
 getting {replaced/complemented} with the new "initial ramfs"
@@ -18,7 +20,8 @@ archive can be compressed using gzip(1).  One valid version of an
 initramfs buffer is thus a single .cpio.gz file.
 
 The full format of the initramfs buffer is defined by the following
-grammar, where:
+grammar, where::
+
 	*	is used to indicate "0 or more occurrences of"
 	(|)	indicates alternatives
 	+	indicates concatenation
@@ -49,7 +52,9 @@ hexadecimal ASCII numbers fully padded with '0' on the left to the
 full width of the field, for example, the integer 4780 is represented
 by the ASCII string "000012ac"):
 
+============= ================== ==============================================
 Field name    Field size	 Meaning
+============= ================== ==============================================
 c_magic	      6 bytes		 The string "070701" or "070702"
 c_ino	      8 bytes		 File inode number
 c_mode	      8 bytes		 File mode and permissions
@@ -65,6 +70,7 @@ c_rmin	      8 bytes		 Minor part of device node reference
 c_namesize    8 bytes		 Length of filename, including final \0
 c_chksum      8 bytes		 Checksum of data field if c_magic is 070702;
 				 otherwise zero
+============= ================== ==============================================
 
 The c_mode field matches the contents of st_mode returned by stat(2)
 on Linux, and encodes the file type and file permissions.
@@ -82,7 +88,8 @@ If the filename is "TRAILER!!!" this is actually an end-of-archive
 marker; the c_filesize for an end-of-archive marker must be zero.
 
 
-*** Handling of hard links
+Handling of hard links
+======================
 
 When a nondirectory with c_nlink > 1 is seen, the (c_maj,c_min,c_ino)
 tuple is looked up in a tuple buffer.  If not found, it is entered in
diff --git a/Documentation/early-userspace/README b/Documentation/early-userspace/early_userspace_support.rst
similarity index 99%
rename from Documentation/early-userspace/README
rename to Documentation/early-userspace/early_userspace_support.rst
index 955d667dc87e..3deefb34046b 100644
--- a/Documentation/early-userspace/README
+++ b/Documentation/early-userspace/early_userspace_support.rst
@@ -1,3 +1,4 @@
+=======================
 Early userspace support
 =======================
 
@@ -26,6 +27,7 @@ archive to be used as the image or have the kernel build process build
 the image from specifications.
 
 CPIO ARCHIVE method
+-------------------
 
 You can create a cpio archive that contains the early userspace image.
 Your cpio archive should be specified in CONFIG_INITRAMFS_SOURCE and it
@@ -34,6 +36,7 @@ CONFIG_INITRAMFS_SOURCE and directory and file names are not allowed in
 combination with a cpio archive.
 
 IMAGE BUILDING method
+---------------------
 
 The kernel build process can also build an early userspace image from
 source parts rather than supplying a cpio archive.  This method provides
diff --git a/Documentation/early-userspace/index.rst b/Documentation/early-userspace/index.rst
new file mode 100644
index 000000000000..2b8eb6132058
--- /dev/null
+++ b/Documentation/early-userspace/index.rst
@@ -0,0 +1,18 @@
+:orphan:
+
+===============
+Early Userspace
+===============
+
+.. toctree::
+    :maxdepth: 1
+
+    early_userspace_support
+    buffer-format
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/filesystems/nfs/nfsroot.txt b/Documentation/filesystems/nfs/nfsroot.txt
index d2963123eb1c..4862d3d77e27 100644
--- a/Documentation/filesystems/nfs/nfsroot.txt
+++ b/Documentation/filesystems/nfs/nfsroot.txt
@@ -239,7 +239,7 @@ rdinit=<executable file>
   A description of the process of mounting the root file system can be
   found in:
 
-    Documentation/early-userspace/README
+    Documentation/early-userspace/early_userspace_support.rst
 
 
 
diff --git a/Documentation/filesystems/ramfs-rootfs-initramfs.txt b/Documentation/filesystems/ramfs-rootfs-initramfs.txt
index 79637d227e85..fa985909dbca 100644
--- a/Documentation/filesystems/ramfs-rootfs-initramfs.txt
+++ b/Documentation/filesystems/ramfs-rootfs-initramfs.txt
@@ -105,7 +105,7 @@ All this differs from the old initrd in several ways:
   - The old initrd file was a gzipped filesystem image (in some file format,
     such as ext2, that needed a driver built into the kernel), while the new
     initramfs archive is a gzipped cpio archive (like tar only simpler,
-    see cpio(1) and Documentation/early-userspace/buffer-format.txt).  The
+    see cpio(1) and Documentation/early-userspace/buffer-format.rst).  The
     kernel's cpio extraction code is not only extremely small, it's also
     __init text and data that can be discarded during the boot process.
 
@@ -159,7 +159,7 @@ One advantage of the configuration file is that root access is not required to
 set permissions or create device nodes in the new archive.  (Note that those
 two example "file" entries expect to find files named "init.sh" and "busybox" in
 a directory called "initramfs", under the linux-2.6.* directory.  See
-Documentation/early-userspace/README for more details.)
+Documentation/early-userspace/early_userspace_support.rst for more details.)
 
 The kernel does not depend on external cpio tools.  If you specify a
 directory instead of a configuration file, the kernel's build infrastructure
diff --git a/usr/Kconfig b/usr/Kconfig
index 43658b8a975e..86e37e297278 100644
--- a/usr/Kconfig
+++ b/usr/Kconfig
@@ -18,7 +18,7 @@ config INITRAMFS_SOURCE
 	  When multiple directories and files are specified then the
 	  initramfs image will be the aggregate of all of them.
 
-	  See <file:Documentation/early-userspace/README> for more details.
+	  See <file:Documentation/early-userspace/early_userspace_support.rst> for more details.
 
 	  If you are not sure, leave it blank.
 
-- 
2.21.0

[PATCH v2 09/29] docs: driver-model: convert docs to ReST and rename to *.rst

[Mauro Carvalho Chehab]

Convert the various documents at the driver-model, preparing
them to be part of the driver-api 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>
Acked-by: Jeff Kirsher <jeffrey.t.kirsher@intel.com> # ice
---
 Documentation/driver-api/gpio/driver.rst      |   2 +-
 .../driver-model/{binding.txt => binding.rst} |  20 +-
 .../driver-model/{bus.txt => bus.rst}         |  69 ++--
 .../driver-model/{class.txt => class.rst}     |  74 ++--
 ...esign-patterns.txt => design-patterns.rst} | 106 +++---
 .../driver-model/{device.txt => device.rst}   |  57 +--
 .../driver-model/{devres.txt => devres.rst}   |  50 +--
 .../driver-model/{driver.txt => driver.rst}   | 112 +++---
 Documentation/driver-model/index.rst          |  26 ++
 .../{overview.txt => overview.rst}            |  37 +-
 .../{platform.txt => platform.rst}            |  30 +-
 .../driver-model/{porting.txt => porting.rst} | 333 +++++++++---------
 Documentation/eisa.txt                        |   4 +-
 Documentation/hwmon/submitting-patches.rst    |   2 +-
 drivers/base/platform.c                       |   2 +-
 drivers/gpio/gpio-cs5535.c                    |   2 +-
 drivers/net/ethernet/intel/ice/ice_main.c     |   2 +-
 scripts/coccinelle/free/devm_free.cocci       |   2 +-
 18 files changed, 489 insertions(+), 441 deletions(-)
 rename Documentation/driver-model/{binding.txt => binding.rst} (92%)
 rename Documentation/driver-model/{bus.txt => bus.rst} (76%)
 rename Documentation/driver-model/{class.txt => class.rst} (75%)
 rename Documentation/driver-model/{design-patterns.txt => design-patterns.rst} (59%)
 rename Documentation/driver-model/{device.txt => device.rst} (71%)
 rename Documentation/driver-model/{devres.txt => devres.rst} (93%)
 rename Documentation/driver-model/{driver.txt => driver.rst} (75%)
 create mode 100644 Documentation/driver-model/index.rst
 rename Documentation/driver-model/{overview.txt => overview.rst} (90%)
 rename Documentation/driver-model/{platform.txt => platform.rst} (95%)
 rename Documentation/driver-model/{porting.txt => porting.rst} (62%)

diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst
index 4af9aae724f0..349f2dc33029 100644
--- a/Documentation/driver-api/gpio/driver.rst
+++ b/Documentation/driver-api/gpio/driver.rst
@@ -399,7 +399,7 @@ symbol:
   will pass the struct gpio_chip* for the chip to all IRQ callbacks, so the
   callbacks need to embed the gpio_chip in its state container and obtain a
   pointer to the container using container_of().
-  (See Documentation/driver-model/design-patterns.txt)
+  (See Documentation/driver-model/design-patterns.rst)
 
 - gpiochip_irqchip_add_nested(): adds a nested cascaded irqchip to a gpiochip,
   as discussed above regarding different types of cascaded irqchips. The
diff --git a/Documentation/driver-model/binding.txt b/Documentation/driver-model/binding.rst
similarity index 92%
rename from Documentation/driver-model/binding.txt
rename to Documentation/driver-model/binding.rst
index abfc8e290d53..7ea1d7a41e1d 100644
--- a/Documentation/driver-model/binding.txt
+++ b/Documentation/driver-model/binding.rst
@@ -1,5 +1,6 @@
-
+==============
 Driver Binding
+==============
 
 Driver binding is the process of associating a device with a device
 driver that can control it. Bus drivers have typically handled this
@@ -25,7 +26,7 @@ device_register
 When a new device is added, the bus's list of drivers is iterated over
 to find one that supports it. In order to determine that, the device
 ID of the device must match one of the device IDs that the driver
-supports. The format and semantics for comparing IDs is bus-specific. 
+supports. The format and semantics for comparing IDs is bus-specific.
 Instead of trying to derive a complex state machine and matching
 algorithm, it is up to the bus driver to provide a callback to compare
 a device against the IDs of a driver. The bus returns 1 if a match was
@@ -36,14 +37,14 @@ int match(struct device * dev, struct device_driver * drv);
 If a match is found, the device's driver field is set to the driver
 and the driver's probe callback is called. This gives the driver a
 chance to verify that it really does support the hardware, and that
-it's in a working state. 
+it's in a working state.
 
 Device Class
 ~~~~~~~~~~~~
 
 Upon the successful completion of probe, the device is registered with
 the class to which it belongs. Device drivers belong to one and only one
-class, and that is set in the driver's devclass field. 
+class, and that is set in the driver's devclass field.
 devclass_add_device is called to enumerate the device within the class
 and actually register it with the class, which happens with the
 class's register_dev callback.
@@ -53,7 +54,7 @@ Driver
 ~~~~~~
 
 When a driver is attached to a device, the device is inserted into the
-driver's list of devices. 
+driver's list of devices.
 
 
 sysfs
@@ -67,18 +68,18 @@ to the device's directory in the physical hierarchy.
 
 A directory for the device is created in the class's directory. A
 symlink is created in that directory that points to the device's
-physical location in the sysfs tree. 
+physical location in the sysfs tree.
 
 A symlink can be created (though this isn't done yet) in the device's
 physical directory to either its class directory, or the class's
 top-level directory. One can also be created to point to its driver's
-directory also. 
+directory also.
 
 
 driver_register
 ~~~~~~~~~~~~~~~
 
-The process is almost identical for when a new driver is added. 
+The process is almost identical for when a new driver is added.
 The bus's list of devices is iterated over to find a match. Devices
 that already have a driver are skipped. All the devices are iterated
 over, to bind as many devices as possible to the driver.
@@ -94,5 +95,4 @@ of the driver is decremented. All symlinks between the two are removed.
 
 When a driver is removed, the list of devices that it supports is
 iterated over, and the driver's remove callback is called for each
-one. The device is removed from that list and the symlinks removed. 
-
+one. The device is removed from that list and the symlinks removed.
diff --git a/Documentation/driver-model/bus.txt b/Documentation/driver-model/bus.rst
similarity index 76%
rename from Documentation/driver-model/bus.txt
rename to Documentation/driver-model/bus.rst
index c247b488a567..016b15a6e8ea 100644
--- a/Documentation/driver-model/bus.txt
+++ b/Documentation/driver-model/bus.rst
@@ -1,5 +1,6 @@
-
-Bus Types 
+=========
+Bus Types
+=========
 
 Definition
 ~~~~~~~~~~
@@ -13,12 +14,12 @@ Declaration
 
 Each bus type in the kernel (PCI, USB, etc) should declare one static
 object of this type. They must initialize the name field, and may
-optionally initialize the match callback.
+optionally initialize the match callback::
 
-struct bus_type pci_bus_type = {
-       .name	= "pci",
-       .match	= pci_bus_match,
-};
+   struct bus_type pci_bus_type = {
+          .name	= "pci",
+          .match	= pci_bus_match,
+   };
 
 The structure should be exported to drivers in a header file:
 
@@ -30,8 +31,8 @@ Registration
 
 When a bus driver is initialized, it calls bus_register. This
 initializes the rest of the fields in the bus object and inserts it
-into a global list of bus types. Once the bus object is registered, 
-the fields in it are usable by the bus driver. 
+into a global list of bus types. Once the bus object is registered,
+the fields in it are usable by the bus driver.
 
 
 Callbacks
@@ -43,17 +44,17 @@ match(): Attaching Drivers to Devices
 The format of device ID structures and the semantics for comparing
 them are inherently bus-specific. Drivers typically declare an array
 of device IDs of devices they support that reside in a bus-specific
-driver structure. 
+driver structure.
 
 The purpose of the match callback is to give the bus an opportunity to
 determine if a particular driver supports a particular device by
 comparing the device IDs the driver supports with the device ID of a
 particular device, without sacrificing bus-specific functionality or
-type-safety. 
+type-safety.
 
 When a driver is registered with the bus, the bus's list of devices is
 iterated over, and the match callback is called for each device that
-does not have a driver associated with it. 
+does not have a driver associated with it.
 
 
 
@@ -64,22 +65,23 @@ The lists of devices and drivers are intended to replace the local
 lists that many buses keep. They are lists of struct devices and
 struct device_drivers, respectively. Bus drivers are free to use the
 lists as they please, but conversion to the bus-specific type may be
-necessary. 
+necessary.
 
-The LDM core provides helper functions for iterating over each list.
+The LDM core provides helper functions for iterating over each list::
 
-int bus_for_each_dev(struct bus_type * bus, struct device * start, void * data,
-		     int (*fn)(struct device *, void *));
+  int bus_for_each_dev(struct bus_type * bus, struct device * start,
+		       void * data,
+		       int (*fn)(struct device *, void *));
 
-int bus_for_each_drv(struct bus_type * bus, struct device_driver * start, 
-		     void * data, int (*fn)(struct device_driver *, void *));
+  int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
+		       void * data, int (*fn)(struct device_driver *, void *));
 
 These helpers iterate over the respective list, and call the callback
 for each device or driver in the list. All list accesses are
 synchronized by taking the bus's lock (read currently). The reference
 count on each object in the list is incremented before the callback is
 called; it is decremented after the next object has been obtained. The
-lock is not held when calling the callback. 
+lock is not held when calling the callback.
 
 
 sysfs
@@ -87,14 +89,14 @@ sysfs
 There is a top-level directory named 'bus'.
 
 Each bus gets a directory in the bus directory, along with two default
-directories:
+directories::
 
 	/sys/bus/pci/
 	|-- devices
 	`-- drivers
 
 Drivers registered with the bus get a directory in the bus's drivers
-directory:
+directory::
 
 	/sys/bus/pci/
 	|-- devices
@@ -106,7 +108,7 @@ directory:
 
 Each device that is discovered on a bus of that type gets a symlink in
 the bus's devices directory to the device's directory in the physical
-hierarchy:
+hierarchy::
 
 	/sys/bus/pci/
 	|-- devices
@@ -118,26 +120,27 @@ hierarchy:
 
 Exporting Attributes
 ~~~~~~~~~~~~~~~~~~~~
-struct bus_attribute {
+
+::
+
+  struct bus_attribute {
 	struct attribute	attr;
 	ssize_t (*show)(struct bus_type *, char * buf);
 	ssize_t (*store)(struct bus_type *, const char * buf, size_t count);
-};
+  };
 
 Bus drivers can export attributes using the BUS_ATTR_RW macro that works
 similarly to the DEVICE_ATTR_RW macro for devices. For example, a
-definition like this:
+definition like this::
 
-static BUS_ATTR_RW(debug);
+	static BUS_ATTR_RW(debug);
 
-is equivalent to declaring:
+is equivalent to declaring::
 
-static bus_attribute bus_attr_debug;
+	static bus_attribute bus_attr_debug;
 
 This can then be used to add and remove the attribute from the bus's
-sysfs directory using:
-
-int bus_create_file(struct bus_type *, struct bus_attribute *);
-void bus_remove_file(struct bus_type *, struct bus_attribute *);
-
+sysfs directory using::
 
+	int bus_create_file(struct bus_type *, struct bus_attribute *);
+	void bus_remove_file(struct bus_type *, struct bus_attribute *);
diff --git a/Documentation/driver-model/class.txt b/Documentation/driver-model/class.rst
similarity index 75%
rename from Documentation/driver-model/class.txt
rename to Documentation/driver-model/class.rst
index 1fefc480a80b..fff55b80e86a 100644
--- a/Documentation/driver-model/class.txt
+++ b/Documentation/driver-model/class.rst
@@ -1,6 +1,6 @@
-
+==============
 Device Classes
-
+==============
 
 Introduction
 ~~~~~~~~~~~~
@@ -13,37 +13,37 @@ device. The following device classes have been identified:
 Each device class defines a set of semantics and a programming interface
 that devices of that class adhere to. Device drivers are the
 implementation of that programming interface for a particular device on
-a particular bus. 
+a particular bus.
 
 Device classes are agnostic with respect to what bus a device resides
-on. 
+on.
 
 
 Programming Interface
 ~~~~~~~~~~~~~~~~~~~~~
-The device class structure looks like: 
+The device class structure looks like::
 
 
-typedef int (*devclass_add)(struct device *);
-typedef void (*devclass_remove)(struct device *);
+  typedef int (*devclass_add)(struct device *);
+  typedef void (*devclass_remove)(struct device *);
 
 See the kerneldoc for the struct class.
 
-A typical device class definition would look like: 
+A typical device class definition would look like::
 
-struct device_class input_devclass = {
+  struct device_class input_devclass = {
         .name		= "input",
         .add_device	= input_add_device,
 	.remove_device	= input_remove_device,
-};
+  };
 
 Each device class structure should be exported in a header file so it
 can be used by drivers, extensions and interfaces.
 
-Device classes are registered and unregistered with the core using: 
+Device classes are registered and unregistered with the core using::
 
-int devclass_register(struct device_class * cls);
-void devclass_unregister(struct device_class * cls);
+  int devclass_register(struct device_class * cls);
+  void devclass_unregister(struct device_class * cls);
 
 
 Devices
@@ -52,16 +52,16 @@ As devices are bound to drivers, they are added to the device class
 that the driver belongs to. Before the driver model core, this would
 typically happen during the driver's probe() callback, once the device
 has been initialized. It now happens after the probe() callback
-finishes from the core. 
+finishes from the core.
 
 The device is enumerated in the class. Each time a device is added to
 the class, the class's devnum field is incremented and assigned to the
 device. The field is never decremented, so if the device is removed
 from the class and re-added, it will receive a different enumerated
-value. 
+value.
 
 The class is allowed to create a class-specific structure for the
-device and store it in the device's class_data pointer. 
+device and store it in the device's class_data pointer.
 
 There is no list of devices in the device class. Each driver has a
 list of devices that it supports. The device class has a list of
@@ -73,15 +73,15 @@ Device Drivers
 ~~~~~~~~~~~~~~
 Device drivers are added to device classes when they are registered
 with the core. A driver specifies the class it belongs to by setting
-the struct device_driver::devclass field. 
+the struct device_driver::devclass field.
 
 
 sysfs directory structure
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There is a top-level sysfs directory named 'class'. 
+There is a top-level sysfs directory named 'class'.
 
 Each class gets a directory in the class directory, along with two
-default subdirectories:
+default subdirectories::
 
         class/
         `-- input
@@ -89,8 +89,8 @@ default subdirectories:
             `-- drivers
 
 
-Drivers registered with the class get a symlink in the drivers/ directory 
-that points to the driver's directory (under its bus directory):
+Drivers registered with the class get a symlink in the drivers/ directory
+that points to the driver's directory (under its bus directory)::
 
    class/
    `-- input
@@ -99,8 +99,8 @@ that points to the driver's directory (under its bus directory):
            `-- usb:usb_mouse -> ../../../bus/drivers/usb_mouse/
 
 
-Each device gets a symlink in the devices/ directory that points to the 
-device's directory in the physical hierarchy:
+Each device gets a symlink in the devices/ directory that points to the
+device's directory in the physical hierarchy::
 
    class/
    `-- input
@@ -111,37 +111,39 @@ device's directory in the physical hierarchy:
 
 Exporting Attributes
 ~~~~~~~~~~~~~~~~~~~~
-struct devclass_attribute {
+
+::
+
+  struct devclass_attribute {
         struct attribute        attr;
         ssize_t (*show)(struct device_class *, char * buf, size_t count, loff_t off);
         ssize_t (*store)(struct device_class *, const char * buf, size_t count, loff_t off);
-};
+  };
 
 Class drivers can export attributes using the DEVCLASS_ATTR macro that works
-similarly to the DEVICE_ATTR macro for devices. For example, a definition 
-like this:
+similarly to the DEVICE_ATTR macro for devices. For example, a definition
+like this::
 
-static DEVCLASS_ATTR(debug,0644,show_debug,store_debug);
+  static DEVCLASS_ATTR(debug,0644,show_debug,store_debug);
 
-is equivalent to declaring:
+is equivalent to declaring::
 
-static devclass_attribute devclass_attr_debug;
+  static devclass_attribute devclass_attr_debug;
 
 The bus driver can add and remove the attribute from the class's
-sysfs directory using:
+sysfs directory using::
 
-int devclass_create_file(struct device_class *, struct devclass_attribute *);
-void devclass_remove_file(struct device_class *, struct devclass_attribute *);
+  int devclass_create_file(struct device_class *, struct devclass_attribute *);
+  void devclass_remove_file(struct device_class *, struct devclass_attribute *);
 
 In the example above, the file will be named 'debug' in placed in the
-class's directory in sysfs. 
+class's directory in sysfs.
 
 
 Interfaces
 ~~~~~~~~~~
 There may exist multiple mechanisms for accessing the same device of a
-particular class type. Device interfaces describe these mechanisms. 
+particular class type. Device interfaces describe these mechanisms.
 
 When a device is added to a device class, the core attempts to add it
 to every interface that is registered with the device class.
-
diff --git a/Documentation/driver-model/design-patterns.txt b/Documentation/driver-model/design-patterns.rst
similarity index 59%
rename from Documentation/driver-model/design-patterns.txt
rename to Documentation/driver-model/design-patterns.rst
index ba7b2df64904..41eb8f41f7dd 100644
--- a/Documentation/driver-model/design-patterns.txt
+++ b/Documentation/driver-model/design-patterns.rst
@@ -1,6 +1,6 @@
-
+=============================
 Device Driver Design Patterns
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=============================
 
 This document describes a few common design patterns found in device drivers.
 It is likely that subsystem maintainers will ask driver developers to
@@ -19,23 +19,23 @@ that the device the driver binds to will appear in several instances. This
 means that the probe() function and all callbacks need to be reentrant.
 
 The most common way to achieve this is to use the state container design
-pattern. It usually has this form:
+pattern. It usually has this form::
 
-struct foo {
-    spinlock_t lock; /* Example member */
-    (...)
-};
+  struct foo {
+      spinlock_t lock; /* Example member */
+      (...)
+  };
 
-static int foo_probe(...)
-{
-    struct foo *foo;
+  static int foo_probe(...)
+  {
+      struct foo *foo;
 
-    foo = devm_kzalloc(dev, sizeof(*foo), GFP_KERNEL);
-    if (!foo)
-        return -ENOMEM;
-    spin_lock_init(&foo->lock);
-    (...)
-}
+      foo = devm_kzalloc(dev, sizeof(*foo), GFP_KERNEL);
+      if (!foo)
+          return -ENOMEM;
+      spin_lock_init(&foo->lock);
+      (...)
+  }
 
 This will create an instance of struct foo in memory every time probe() is
 called. This is our state container for this instance of the device driver.
@@ -43,21 +43,21 @@ Of course it is then necessary to always pass this instance of the
 state around to all functions that need access to the state and its members.
 
 For example, if the driver is registering an interrupt handler, you would
-pass around a pointer to struct foo like this:
+pass around a pointer to struct foo like this::
 
-static irqreturn_t foo_handler(int irq, void *arg)
-{
-    struct foo *foo = arg;
-    (...)
-}
+  static irqreturn_t foo_handler(int irq, void *arg)
+  {
+      struct foo *foo = arg;
+      (...)
+  }
 
-static int foo_probe(...)
-{
-    struct foo *foo;
+  static int foo_probe(...)
+  {
+      struct foo *foo;
 
-    (...)
-    ret = request_irq(irq, foo_handler, 0, "foo", foo);
-}
+      (...)
+      ret = request_irq(irq, foo_handler, 0, "foo", foo);
+  }
 
 This way you always get a pointer back to the correct instance of foo in
 your interrupt handler.
@@ -66,38 +66,38 @@ your interrupt handler.
 2. container_of()
 ~~~~~~~~~~~~~~~~~
 
-Continuing on the above example we add an offloaded work:
+Continuing on the above example we add an offloaded work::
 
-struct foo {
-    spinlock_t lock;
-    struct workqueue_struct *wq;
-    struct work_struct offload;
-    (...)
-};
+  struct foo {
+      spinlock_t lock;
+      struct workqueue_struct *wq;
+      struct work_struct offload;
+      (...)
+  };
 
-static void foo_work(struct work_struct *work)
-{
-    struct foo *foo = container_of(work, struct foo, offload);
+  static void foo_work(struct work_struct *work)
+  {
+      struct foo *foo = container_of(work, struct foo, offload);
 
-    (...)
-}
+      (...)
+  }
 
-static irqreturn_t foo_handler(int irq, void *arg)
-{
-    struct foo *foo = arg;
+  static irqreturn_t foo_handler(int irq, void *arg)
+  {
+      struct foo *foo = arg;
 
-    queue_work(foo->wq, &foo->offload);
-    (...)
-}
+      queue_work(foo->wq, &foo->offload);
+      (...)
+  }
 
-static int foo_probe(...)
-{
-    struct foo *foo;
+  static int foo_probe(...)
+  {
+      struct foo *foo;
 
-    foo->wq = create_singlethread_workqueue("foo-wq");
-    INIT_WORK(&foo->offload, foo_work);
-    (...)
-}
+      foo->wq = create_singlethread_workqueue("foo-wq");
+      INIT_WORK(&foo->offload, foo_work);
+      (...)
+  }
 
 The design pattern is the same for an hrtimer or something similar that will
 return a single argument which is a pointer to a struct member in the
diff --git a/Documentation/driver-model/device.txt b/Documentation/driver-model/device.rst
similarity index 71%
rename from Documentation/driver-model/device.txt
rename to Documentation/driver-model/device.rst
index 2403eb856187..2b868d49d349 100644
--- a/Documentation/driver-model/device.txt
+++ b/Documentation/driver-model/device.rst
@@ -1,6 +1,6 @@
-
+==========================
 The Basic Device Structure
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+==========================
 
 See the kerneldoc for the struct device.
 
@@ -8,9 +8,9 @@ See the kerneldoc for the struct device.
 Programming Interface
 ~~~~~~~~~~~~~~~~~~~~~
 The bus driver that discovers the device uses this to register the
-device with the core:
+device with the core::
 
-int device_register(struct device * dev);
+  int device_register(struct device * dev);
 
 The bus should initialize the following fields:
 
@@ -20,30 +20,33 @@ The bus should initialize the following fields:
     - bus
 
 A device is removed from the core when its reference count goes to
-0. The reference count can be adjusted using:
+0. The reference count can be adjusted using::
 
-struct device * get_device(struct device * dev);
-void put_device(struct device * dev);
+  struct device * get_device(struct device * dev);
+  void put_device(struct device * dev);
 
 get_device() will return a pointer to the struct device passed to it
 if the reference is not already 0 (if it's in the process of being
 removed already).
 
-A driver can access the lock in the device structure using: 
+A driver can access the lock in the device structure using::
 
-void lock_device(struct device * dev);
-void unlock_device(struct device * dev);
+  void lock_device(struct device * dev);
+  void unlock_device(struct device * dev);
 
 
 Attributes
 ~~~~~~~~~~
-struct device_attribute {
+
+::
+
+  struct device_attribute {
 	struct attribute	attr;
 	ssize_t (*show)(struct device *dev, struct device_attribute *attr,
 			char *buf);
 	ssize_t (*store)(struct device *dev, struct device_attribute *attr,
 			 const char *buf, size_t count);
-};
+  };
 
 Attributes of devices can be exported by a device driver through sysfs.
 
@@ -54,39 +57,39 @@ As explained in Documentation/kobject.txt, device attributes must be
 created before the KOBJ_ADD uevent is generated. The only way to realize
 that is by defining an attribute group.
 
-Attributes are declared using a macro called DEVICE_ATTR:
+Attributes are declared using a macro called DEVICE_ATTR::
 
-#define DEVICE_ATTR(name,mode,show,store)
+  #define DEVICE_ATTR(name,mode,show,store)
 
-Example:
+Example:::
 
-static DEVICE_ATTR(type, 0444, show_type, NULL);
-static DEVICE_ATTR(power, 0644, show_power, store_power);
+  static DEVICE_ATTR(type, 0444, show_type, NULL);
+  static DEVICE_ATTR(power, 0644, show_power, store_power);
 
 This declares two structures of type struct device_attribute with respective
 names 'dev_attr_type' and 'dev_attr_power'. These two attributes can be
-organized as follows into a group:
+organized as follows into a group::
 
-static struct attribute *dev_attrs[] = {
+  static struct attribute *dev_attrs[] = {
 	&dev_attr_type.attr,
 	&dev_attr_power.attr,
 	NULL,
-};
+  };
 
-static struct attribute_group dev_attr_group = {
+  static struct attribute_group dev_attr_group = {
 	.attrs = dev_attrs,
-};
+  };
 
-static const struct attribute_group *dev_attr_groups[] = {
+  static const struct attribute_group *dev_attr_groups[] = {
 	&dev_attr_group,
 	NULL,
-};
+  };
 
 This array of groups can then be associated with a device by setting the
-group pointer in struct device before device_register() is invoked:
+group pointer in struct device before device_register() is invoked::
 
-      dev->groups = dev_attr_groups;
-      device_register(dev);
+        dev->groups = dev_attr_groups;
+        device_register(dev);
 
 The device_register() function will use the 'groups' pointer to create the
 device attributes and the device_unregister() function will use this pointer
diff --git a/Documentation/driver-model/devres.txt b/Documentation/driver-model/devres.rst
similarity index 93%
rename from Documentation/driver-model/devres.txt
rename to Documentation/driver-model/devres.rst
index 69c7fa7f616c..4ac99122b5f1 100644
--- a/Documentation/driver-model/devres.txt
+++ b/Documentation/driver-model/devres.rst
@@ -1,3 +1,4 @@
+================================
 Devres - Managed Device Resource
 ================================
 
@@ -5,17 +6,18 @@ Tejun Heo	<teheo@suse.de>
 
 First draft	10 January 2007
 
+.. contents
 
-1. Intro			: Huh? Devres?
-2. Devres			: Devres in a nutshell
-3. Devres Group			: Group devres'es and release them together
-4. Details			: Life time rules, calling context, ...
-5. Overhead			: How much do we have to pay for this?
-6. List of managed interfaces	: Currently implemented managed interfaces
+   1. Intro			: Huh? Devres?
+   2. Devres			: Devres in a nutshell
+   3. Devres Group		: Group devres'es and release them together
+   4. Details			: Life time rules, calling context, ...
+   5. Overhead			: How much do we have to pay for this?
+   6. List of managed interfaces: Currently implemented managed interfaces
 
 
-  1. Intro
-  --------
+1. Intro
+--------
 
 devres came up while trying to convert libata to use iomap.  Each
 iomapped address should be kept and unmapped on driver detach.  For
@@ -42,8 +44,8 @@ would leak resources or even cause oops when failure occurs.  iomap
 adds more to this mix.  So do msi and msix.
 
 
-  2. Devres
-  ---------
+2. Devres
+---------
 
 devres is basically linked list of arbitrarily sized memory areas
 associated with a struct device.  Each devres entry is associated with
@@ -58,7 +60,7 @@ using dma_alloc_coherent().  The managed version is called
 dmam_alloc_coherent().  It is identical to dma_alloc_coherent() except
 for the DMA memory allocated using it is managed and will be
 automatically released on driver detach.  Implementation looks like
-the following.
+the following::
 
   struct dma_devres {
 	size_t		size;
@@ -98,7 +100,7 @@ If a driver uses dmam_alloc_coherent(), the area is guaranteed to be
 freed whether initialization fails half-way or the device gets
 detached.  If most resources are acquired using managed interface, a
 driver can have much simpler init and exit code.  Init path basically
-looks like the following.
+looks like the following::
 
   my_init_one()
   {
@@ -119,7 +121,7 @@ looks like the following.
 	return register_to_upper_layer(d);
   }
 
-And exit path,
+And exit path::
 
   my_remove_one()
   {
@@ -140,13 +142,13 @@ on you. In some cases this may mean introducing checks that were not
 necessary before moving to the managed devm_* calls.
 
 
-  3. Devres group
-  ---------------
+3. Devres group
+---------------
 
 Devres entries can be grouped using devres group.  When a group is
 released, all contained normal devres entries and properly nested
 groups are released.  One usage is to rollback series of acquired
-resources on failure.  For example,
+resources on failure.  For example::
 
   if (!devres_open_group(dev, NULL, GFP_KERNEL))
 	return -ENOMEM;
@@ -172,7 +174,7 @@ like above are usually useful in midlayer driver (e.g. libata core
 layer) where interface function shouldn't have side effect on failure.
 For LLDs, just returning error code suffices in most cases.
 
-Each group is identified by void *id.  It can either be explicitly
+Each group is identified by `void *id`.  It can either be explicitly
 specified by @id argument to devres_open_group() or automatically
 created by passing NULL as @id as in the above example.  In both
 cases, devres_open_group() returns the group's id.  The returned id
@@ -180,7 +182,7 @@ can be passed to other devres functions to select the target group.
 If NULL is given to those functions, the latest open group is
 selected.
 
-For example, you can do something like the following.
+For example, you can do something like the following::
 
   int my_midlayer_create_something()
   {
@@ -199,8 +201,8 @@ For example, you can do something like the following.
   }
 
 
-  4. Details
-  ----------
+4. Details
+----------
 
 Lifetime of a devres entry begins on devres allocation and finishes
 when it is released or destroyed (removed and freed) - no reference
@@ -220,8 +222,8 @@ All devres interface functions can be called without context if the
 right gfp mask is given.
 
 
-  5. Overhead
-  -----------
+5. Overhead
+-----------
 
 Each devres bookkeeping info is allocated together with requested data
 area.  With debug option turned off, bookkeeping info occupies 16
@@ -237,8 +239,8 @@ and 400 bytes on 32bit machine after naive conversion (we can
 certainly invest a bit more effort into libata core layer).
 
 
-  6. List of managed interfaces
-  -----------------------------
+6. List of managed interfaces
+-----------------------------
 
 CLOCK
   devm_clk_get()
diff --git a/Documentation/driver-model/driver.txt b/Documentation/driver-model/driver.rst
similarity index 75%
rename from Documentation/driver-model/driver.txt
rename to Documentation/driver-model/driver.rst
index d661e6f7e6a0..11d281506a04 100644
--- a/Documentation/driver-model/driver.txt
+++ b/Documentation/driver-model/driver.rst
@@ -1,5 +1,6 @@
-
+==============
 Device Drivers
+==============
 
 See the kerneldoc for the struct device_driver.
 
@@ -26,50 +27,50 @@ Declaration
 As stated above, struct device_driver objects are statically
 allocated. Below is an example declaration of the eepro100
 driver. This declaration is hypothetical only; it relies on the driver
-being converted completely to the new model. 
+being converted completely to the new model::
 
-static struct device_driver eepro100_driver = {
-       .name		= "eepro100",
-       .bus		= &pci_bus_type,
-       
-       .probe		= eepro100_probe,
-       .remove		= eepro100_remove,
-       .suspend		= eepro100_suspend,
-       .resume		= eepro100_resume,
-};
+  static struct device_driver eepro100_driver = {
+         .name		= "eepro100",
+         .bus		= &pci_bus_type,
+
+         .probe		= eepro100_probe,
+         .remove		= eepro100_remove,
+         .suspend		= eepro100_suspend,
+         .resume		= eepro100_resume,
+  };
 
 Most drivers will not be able to be converted completely to the new
 model because the bus they belong to has a bus-specific structure with
-bus-specific fields that cannot be generalized. 
+bus-specific fields that cannot be generalized.
 
 The most common example of this are device ID structures. A driver
 typically defines an array of device IDs that it supports. The format
 of these structures and the semantics for comparing device IDs are
 completely bus-specific. Defining them as bus-specific entities would
-sacrifice type-safety, so we keep bus-specific structures around. 
+sacrifice type-safety, so we keep bus-specific structures around.
 
 Bus-specific drivers should include a generic struct device_driver in
-the definition of the bus-specific driver. Like this:
+the definition of the bus-specific driver. Like this::
 
-struct pci_driver {
-       const struct pci_device_id *id_table;
-       struct device_driver	  driver;
-};
+  struct pci_driver {
+         const struct pci_device_id *id_table;
+         struct device_driver	  driver;
+  };
 
 A definition that included bus-specific fields would look like
-(using the eepro100 driver again):
+(using the eepro100 driver again)::
 
-static struct pci_driver eepro100_driver = {
-       .id_table       = eepro100_pci_tbl,
-       .driver	       = {
+  static struct pci_driver eepro100_driver = {
+         .id_table       = eepro100_pci_tbl,
+         .driver	       = {
 		.name		= "eepro100",
 		.bus		= &pci_bus_type,
 		.probe		= eepro100_probe,
 		.remove		= eepro100_remove,
 		.suspend	= eepro100_suspend,
 		.resume		= eepro100_resume,
-       },
-};
+         },
+  };
 
 Some may find the syntax of embedded struct initialization awkward or
 even a bit ugly. So far, it's the best way we've found to do what we want...
@@ -77,12 +78,14 @@ even a bit ugly. So far, it's the best way we've found to do what we want...
 Registration
 ~~~~~~~~~~~~
 
-int driver_register(struct device_driver * drv);
+::
+
+  int driver_register(struct device_driver *drv);
 
 The driver registers the structure on startup. For drivers that have
 no bus-specific fields (i.e. don't have a bus-specific driver
 structure), they would use driver_register and pass a pointer to their
-struct device_driver object. 
+struct device_driver object.
 
 Most drivers, however, will have a bus-specific structure and will
 need to register with the bus using something like pci_driver_register.
@@ -101,7 +104,7 @@ By defining wrapper functions, the transition to the new model can be
 made easier. Drivers can ignore the generic structure altogether and
 let the bus wrapper fill in the fields. For the callbacks, the bus can
 define generic callbacks that forward the call to the bus-specific
-callbacks of the drivers. 
+callbacks of the drivers.
 
 This solution is intended to be only temporary. In order to get class
 information in the driver, the drivers must be modified anyway. Since
@@ -113,16 +116,16 @@ Access
 ~~~~~~
 
 Once the object has been registered, it may access the common fields of
-the object, like the lock and the list of devices. 
+the object, like the lock and the list of devices::
 
-int driver_for_each_dev(struct device_driver * drv, void * data, 
-		        int (*callback)(struct device * dev, void * data));
+  int driver_for_each_dev(struct device_driver *drv, void *data,
+			  int (*callback)(struct device *dev, void *data));
 
 The devices field is a list of all the devices that have been bound to
 the driver. The LDM core provides a helper function to operate on all
 the devices a driver controls. This helper locks the driver on each
 node access, and does proper reference counting on each device as it
-accesses it. 
+accesses it.
 
 
 sysfs
@@ -142,7 +145,9 @@ supports.
 Callbacks
 ~~~~~~~~~
 
-	int	(*probe)	(struct device * dev);
+::
+
+	int	(*probe)	(struct device *dev);
 
 The probe() entry is called in task context, with the bus's rwsem locked
 and the driver partially bound to the device.  Drivers commonly use
@@ -162,9 +167,9 @@ the driver to that device.
 
 A driver's probe() may return a negative errno value to indicate that
 the driver did not bind to this device, in which case it should have
-released all resources it allocated.
+released all resources it allocated::
 
-	int 	(*remove)	(struct device * dev);
+	int 	(*remove)	(struct device *dev);
 
 remove is called to unbind a driver from a device. This may be
 called if a device is physically removed from the system, if the
@@ -173,43 +178,46 @@ in other cases.
 
 It is up to the driver to determine if the device is present or
 not. It should free any resources allocated specifically for the
-device; i.e. anything in the device's driver_data field. 
+device; i.e. anything in the device's driver_data field.
 
 If the device is still present, it should quiesce the device and place
-it into a supported low-power state.
+it into a supported low-power state::
 
-	int	(*suspend)	(struct device * dev, pm_message_t state);
+	int	(*suspend)	(struct device *dev, pm_message_t state);
 
-suspend is called to put the device in a low power state.
+suspend is called to put the device in a low power state::
 
-	int	(*resume)	(struct device * dev);
+	int	(*resume)	(struct device *dev);
 
 Resume is used to bring a device back from a low power state.
 
 
 Attributes
 ~~~~~~~~~~
-struct driver_attribute {
-        struct attribute        attr;
-        ssize_t (*show)(struct device_driver *driver, char *buf);
-        ssize_t (*store)(struct device_driver *, const char * buf, size_t count);
-};
 
-Device drivers can export attributes via their sysfs directories. 
+::
+
+  struct driver_attribute {
+          struct attribute        attr;
+          ssize_t (*show)(struct device_driver *driver, char *buf);
+          ssize_t (*store)(struct device_driver *, const char *buf, size_t count);
+  };
+
+Device drivers can export attributes via their sysfs directories.
 Drivers can declare attributes using a DRIVER_ATTR_RW and DRIVER_ATTR_RO
 macro that works identically to the DEVICE_ATTR_RW and DEVICE_ATTR_RO
 macros.
 
-Example:
+Example::
 
-DRIVER_ATTR_RW(debug);
+	DRIVER_ATTR_RW(debug);
 
-This is equivalent to declaring:
+This is equivalent to declaring::
 
-struct driver_attribute driver_attr_debug;
+	struct driver_attribute driver_attr_debug;
 
 This can then be used to add and remove the attribute from the
-driver's directory using:
+driver's directory using::
 
-int driver_create_file(struct device_driver *, const struct driver_attribute *);
-void driver_remove_file(struct device_driver *, const struct driver_attribute *);
+  int driver_create_file(struct device_driver *, const struct driver_attribute *);
+  void driver_remove_file(struct device_driver *, const struct driver_attribute *);
diff --git a/Documentation/driver-model/index.rst b/Documentation/driver-model/index.rst
new file mode 100644
index 000000000000..9f85d579ce56
--- /dev/null
+++ b/Documentation/driver-model/index.rst
@@ -0,0 +1,26 @@
+:orphan:
+
+============
+Driver Model
+============
+
+.. toctree::
+   :maxdepth: 1
+
+   binding
+   bus
+   class
+   design-patterns
+   device
+   devres
+   driver
+   overview
+   platform
+   porting
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/driver-model/overview.txt b/Documentation/driver-model/overview.rst
similarity index 90%
rename from Documentation/driver-model/overview.txt
rename to Documentation/driver-model/overview.rst
index 6a8f9a8075d8..d4d1e9b40e0c 100644
--- a/Documentation/driver-model/overview.txt
+++ b/Documentation/driver-model/overview.rst
@@ -1,4 +1,6 @@
+=============================
 The Linux Kernel Device Model
+=============================
 
 Patrick Mochel	<mochel@digitalimplant.org>
 
@@ -41,14 +43,14 @@ data structure. These fields must still be accessed by the bus layers,
 and sometimes by the device-specific drivers.
 
 Other bus layers are encouraged to do what has been done for the PCI layer.
-struct pci_dev now looks like this:
+struct pci_dev now looks like this::
 
-struct pci_dev {
+  struct pci_dev {
 	...
 
 	struct device dev;     /* Generic device interface */
 	...
-};
+  };
 
 Note first that the struct device dev within the struct pci_dev is
 statically allocated. This means only one allocation on device discovery.
@@ -80,26 +82,26 @@ easy. This has been accomplished by implementing a special purpose virtual
 file system named sysfs.
 
 Almost all mainstream Linux distros mount this filesystem automatically; you
-can see some variation of the following in the output of the "mount" command:
+can see some variation of the following in the output of the "mount" command::
 
-$ mount
-...
-none on /sys type sysfs (rw,noexec,nosuid,nodev)
-...
-$
+  $ mount
+  ...
+  none on /sys type sysfs (rw,noexec,nosuid,nodev)
+  ...
+  $
 
 The auto-mounting of sysfs is typically accomplished by an entry similar to
-the following in the /etc/fstab file:
+the following in the /etc/fstab file::
 
-none     	/sys	sysfs    defaults	  	0 0
+  none     	/sys	sysfs    defaults	  	0 0
 
-or something similar in the /lib/init/fstab file on Debian-based systems:
+or something similar in the /lib/init/fstab file on Debian-based systems::
 
-none            /sys    sysfs    nodev,noexec,nosuid    0 0
+  none            /sys    sysfs    nodev,noexec,nosuid    0 0
 
-If sysfs is not automatically mounted, you can always do it manually with:
+If sysfs is not automatically mounted, you can always do it manually with::
 
-# mount -t sysfs sysfs /sys
+	# mount -t sysfs sysfs /sys
 
 Whenever a device is inserted into the tree, a directory is created for it.
 This directory may be populated at each layer of discovery - the global layer,
@@ -108,7 +110,7 @@ the bus layer, or the device layer.
 The global layer currently creates two files - 'name' and 'power'. The
 former only reports the name of the device. The latter reports the
 current power state of the device. It will also be used to set the current
-power state. 
+power state.
 
 The bus layer may also create files for the devices it finds while probing the
 bus. For example, the PCI layer currently creates 'irq' and 'resource' files
@@ -118,6 +120,5 @@ A device-specific driver may also export files in its directory to expose
 device-specific data or tunable interfaces.
 
 More information about the sysfs directory layout can be found in
-the other documents in this directory and in the file 
+the other documents in this directory and in the file
 Documentation/filesystems/sysfs.txt.
-
diff --git a/Documentation/driver-model/platform.txt b/Documentation/driver-model/platform.rst
similarity index 95%
rename from Documentation/driver-model/platform.txt
rename to Documentation/driver-model/platform.rst
index 9d9e47dfc013..334dd4071ae4 100644
--- a/Documentation/driver-model/platform.txt
+++ b/Documentation/driver-model/platform.rst
@@ -1,5 +1,7 @@
+============================
 Platform Devices and Drivers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+============================
+
 See <linux/platform_device.h> for the driver model interface to the
 platform bus:  platform_device, and platform_driver.  This pseudo-bus
 is used to connect devices on busses with minimal infrastructure,
@@ -19,15 +21,15 @@ be connected through a segment of some other kind of bus; but its
 registers will still be directly addressable.
 
 Platform devices are given a name, used in driver binding, and a
-list of resources such as addresses and IRQs.
+list of resources such as addresses and IRQs::
 
-struct platform_device {
+  struct platform_device {
 	const char	*name;
 	u32		id;
 	struct device	dev;
 	u32		num_resources;
 	struct resource	*resource;
-};
+  };
 
 
 Platform drivers
@@ -35,9 +37,9 @@ Platform drivers
 Platform drivers follow the standard driver model convention, where
 discovery/enumeration is handled outside the drivers, and drivers
 provide probe() and remove() methods.  They support power management
-and shutdown notifications using the standard conventions.
+and shutdown notifications using the standard conventions::
 
-struct platform_driver {
+  struct platform_driver {
 	int (*probe)(struct platform_device *);
 	int (*remove)(struct platform_device *);
 	void (*shutdown)(struct platform_device *);
@@ -46,25 +48,25 @@ struct platform_driver {
 	int (*resume_early)(struct platform_device *);
 	int (*resume)(struct platform_device *);
 	struct device_driver driver;
-};
+  };
 
 Note that probe() should in general verify that the specified device hardware
 actually exists; sometimes platform setup code can't be sure.  The probing
 can use device resources, including clocks, and device platform_data.
 
-Platform drivers register themselves the normal way:
+Platform drivers register themselves the normal way::
 
 	int platform_driver_register(struct platform_driver *drv);
 
 Or, in common situations where the device is known not to be hot-pluggable,
 the probe() routine can live in an init section to reduce the driver's
-runtime memory footprint:
+runtime memory footprint::
 
 	int platform_driver_probe(struct platform_driver *drv,
 			  int (*probe)(struct platform_device *))
 
 Kernel modules can be composed of several platform drivers. The platform core
-provides helpers to register and unregister an array of drivers:
+provides helpers to register and unregister an array of drivers::
 
 	int __platform_register_drivers(struct platform_driver * const *drivers,
 				      unsigned int count, struct module *owner);
@@ -73,7 +75,7 @@ provides helpers to register and unregister an array of drivers:
 
 If one of the drivers fails to register, all drivers registered up to that
 point will be unregistered in reverse order. Note that there is a convenience
-macro that passes THIS_MODULE as owner parameter:
+macro that passes THIS_MODULE as owner parameter::
 
 	#define platform_register_drivers(drivers, count)
 
@@ -81,7 +83,7 @@ macro that passes THIS_MODULE as owner parameter:
 Device Enumeration
 ~~~~~~~~~~~~~~~~~~
 As a rule, platform specific (and often board-specific) setup code will
-register platform devices:
+register platform devices::
 
 	int platform_device_register(struct platform_device *pdev);
 
@@ -133,14 +135,14 @@ tend to already have "normal" modes, such as ones using device nodes that
 were created by PNP or by platform device setup.
 
 None the less, there are some APIs to support such legacy drivers.  Avoid
-using these calls except with such hotplug-deficient drivers.
+using these calls except with such hotplug-deficient drivers::
 
 	struct platform_device *platform_device_alloc(
 			const char *name, int id);
 
 You can use platform_device_alloc() to dynamically allocate a device, which
 you will then initialize with resources and platform_device_register().
-A better solution is usually:
+A better solution is usually::
 
 	struct platform_device *platform_device_register_simple(
 			const char *name, int id,
diff --git a/Documentation/driver-model/porting.txt b/Documentation/driver-model/porting.rst
similarity index 62%
rename from Documentation/driver-model/porting.txt
rename to Documentation/driver-model/porting.rst
index 453053f1661f..ae4bf843c1d6 100644
--- a/Documentation/driver-model/porting.txt
+++ b/Documentation/driver-model/porting.rst
@@ -1,5 +1,6 @@
-
+=======================================
 Porting Drivers to the New Driver Model
+=======================================
 
 Patrick Mochel
 
@@ -8,8 +9,8 @@ Patrick Mochel
 
 Overview
 
-Please refer to Documentation/driver-model/*.txt for definitions of
-various driver types and concepts. 
+Please refer to `Documentation/driver-model/*.rst` for definitions of
+various driver types and concepts.
 
 Most of the work of porting devices drivers to the new model happens
 at the bus driver layer. This was intentional, to minimize the
@@ -18,11 +19,11 @@ of bus drivers.
 
 In a nutshell, the driver model consists of a set of objects that can
 be embedded in larger, bus-specific objects. Fields in these generic
-objects can replace fields in the bus-specific objects. 
+objects can replace fields in the bus-specific objects.
 
 The generic objects must be registered with the driver model core. By
 doing so, they will exported via the sysfs filesystem. sysfs can be
-mounted by doing 
+mounted by doing::
 
 	# mount -t sysfs sysfs /sys
 
@@ -30,108 +31,109 @@ mounted by doing
 
 The Process
 
-Step 0: Read include/linux/device.h for object and function definitions. 
+Step 0: Read include/linux/device.h for object and function definitions.
 
-Step 1: Registering the bus driver. 
+Step 1: Registering the bus driver.
 
 
-- Define a struct bus_type for the bus driver.
+- Define a struct bus_type for the bus driver::
 
-struct bus_type pci_bus_type = {
-        .name           = "pci",
-};
+    struct bus_type pci_bus_type = {
+          .name           = "pci",
+    };
 
 
 - Register the bus type.
+
   This should be done in the initialization function for the bus type,
-  which is usually the module_init(), or equivalent, function. 
+  which is usually the module_init(), or equivalent, function::
 
-static int __init pci_driver_init(void)
-{
-        return bus_register(&pci_bus_type);
-}
+    static int __init pci_driver_init(void)
+    {
+            return bus_register(&pci_bus_type);
+    }
 
-subsys_initcall(pci_driver_init);
+    subsys_initcall(pci_driver_init);
 
 
   The bus type may be unregistered (if the bus driver may be compiled
-  as a module) by doing:
+  as a module) by doing::
 
      bus_unregister(&pci_bus_type);
 
 
-- Export the bus type for others to use. 
+- Export the bus type for others to use.
 
-  Other code may wish to reference the bus type, so declare it in a 
+  Other code may wish to reference the bus type, so declare it in a
   shared header file and export the symbol.
 
-From include/linux/pci.h:
+From include/linux/pci.h::
 
-extern struct bus_type pci_bus_type;
+  extern struct bus_type pci_bus_type;
 
 
-From file the above code appears in:
+From file the above code appears in::
 
-EXPORT_SYMBOL(pci_bus_type);
+  EXPORT_SYMBOL(pci_bus_type);
 
 
 
 - This will cause the bus to show up in /sys/bus/pci/ with two
-  subdirectories: 'devices' and 'drivers'.
+  subdirectories: 'devices' and 'drivers'::
 
-# tree -d /sys/bus/pci/
-/sys/bus/pci/
-|-- devices
-`-- drivers
+    # tree -d /sys/bus/pci/
+    /sys/bus/pci/
+    |-- devices
+    `-- drivers
 
 
 
-Step 2: Registering Devices. 
+Step 2: Registering Devices.
 
 struct device represents a single device. It mainly contains metadata
-describing the relationship the device has to other entities. 
+describing the relationship the device has to other entities.
 
 
-- Embed a struct device in the bus-specific device type. 
+- Embed a struct device in the bus-specific device type::
 
 
-struct pci_dev {
-       ...
-       struct  device  dev;            /* Generic device interface */
-       ...
-};
+    struct pci_dev {
+           ...
+           struct  device  dev;            /* Generic device interface */
+           ...
+    };
 
-  It is recommended that the generic device not be the first item in 
+  It is recommended that the generic device not be the first item in
   the struct to discourage programmers from doing mindless casts
   between the object types. Instead macros, or inline functions,
-  should be created to convert from the generic object type.
+  should be created to convert from the generic object type::
 
 
-#define to_pci_dev(n) container_of(n, struct pci_dev, dev)
+    #define to_pci_dev(n) container_of(n, struct pci_dev, dev)
 
-or 
+    or
 
-static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
-{
+    static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
+    {
 	return container_of(n, struct pci_dev, dev);
-}
+    }
 
-  This allows the compiler to verify type-safety of the operations 
+  This allows the compiler to verify type-safety of the operations
   that are performed (which is Good).
 
 
 - Initialize the device on registration.
 
-  When devices are discovered or registered with the bus type, the 
+  When devices are discovered or registered with the bus type, the
   bus driver should initialize the generic device. The most important
   things to initialize are the bus_id, parent, and bus fields.
 
   The bus_id is an ASCII string that contains the device's address on
   the bus. The format of this string is bus-specific. This is
-  necessary for representing devices in sysfs. 
+  necessary for representing devices in sysfs.
 
   parent is the physical parent of the device. It is important that
-  the bus driver sets this field correctly. 
+  the bus driver sets this field correctly.
 
   The driver model maintains an ordered list of devices that it uses
   for power management. This list must be in order to guarantee that
@@ -140,13 +142,13 @@ static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
   devices.
 
   Also, the location of the device's sysfs directory depends on a
-  device's parent. sysfs exports a directory structure that mirrors 
+  device's parent. sysfs exports a directory structure that mirrors
   the device hierarchy. Accurately setting the parent guarantees that
   sysfs will accurately represent the hierarchy.
 
   The device's bus field is a pointer to the bus type the device
   belongs to. This should be set to the bus_type that was declared
-  and initialized before. 
+  and initialized before.
 
   Optionally, the bus driver may set the device's name and release
   fields.
@@ -155,107 +157,107 @@ static inline struct pci_dev * to_pci_dev(struct kobject * kobj)
 
      "ATI Technologies Inc Radeon QD"
 
-  The release field is a callback that the driver model core calls 
-  when the device has been removed, and all references to it have 
+  The release field is a callback that the driver model core calls
+  when the device has been removed, and all references to it have
   been released. More on this in a moment.
 
 
-- Register the device. 
+- Register the device.
 
   Once the generic device has been initialized, it can be registered
-  with the driver model core by doing:
+  with the driver model core by doing::
 
        device_register(&dev->dev);
 
-  It can later be unregistered by doing: 
+  It can later be unregistered by doing::
 
        device_unregister(&dev->dev);
 
-  This should happen on buses that support hotpluggable devices. 
+  This should happen on buses that support hotpluggable devices.
   If a bus driver unregisters a device, it should not immediately free
-  it. It should instead wait for the driver model core to call the 
-  device's release method, then free the bus-specific object. 
+  it. It should instead wait for the driver model core to call the
+  device's release method, then free the bus-specific object.
   (There may be other code that is currently referencing the device
-  structure, and it would be rude to free the device while that is 
+  structure, and it would be rude to free the device while that is
   happening).
 
 
-  When the device is registered, a directory in sysfs is created. 
-  The PCI tree in sysfs looks like: 
+  When the device is registered, a directory in sysfs is created.
+  The PCI tree in sysfs looks like::
 
-/sys/devices/pci0/
-|-- 00:00.0
-|-- 00:01.0
-|   `-- 01:00.0
-|-- 00:02.0
-|   `-- 02:1f.0
-|       `-- 03:00.0
-|-- 00:1e.0
-|   `-- 04:04.0
-|-- 00:1f.0
-|-- 00:1f.1
-|   |-- ide0
-|   |   |-- 0.0
-|   |   `-- 0.1
-|   `-- ide1
-|       `-- 1.0
-|-- 00:1f.2
-|-- 00:1f.3
-`-- 00:1f.5
+    /sys/devices/pci0/
+    |-- 00:00.0
+    |-- 00:01.0
+    |   `-- 01:00.0
+    |-- 00:02.0
+    |   `-- 02:1f.0
+    |       `-- 03:00.0
+    |-- 00:1e.0
+    |   `-- 04:04.0
+    |-- 00:1f.0
+    |-- 00:1f.1
+    |   |-- ide0
+    |   |   |-- 0.0
+    |   |   `-- 0.1
+    |   `-- ide1
+    |       `-- 1.0
+    |-- 00:1f.2
+    |-- 00:1f.3
+    `-- 00:1f.5
 
   Also, symlinks are created in the bus's 'devices' directory
-  that point to the device's directory in the physical hierarchy. 
+  that point to the device's directory in the physical hierarchy::
 
-/sys/bus/pci/devices/
-|-- 00:00.0 -> ../../../devices/pci0/00:00.0
-|-- 00:01.0 -> ../../../devices/pci0/00:01.0
-|-- 00:02.0 -> ../../../devices/pci0/00:02.0
-|-- 00:1e.0 -> ../../../devices/pci0/00:1e.0
-|-- 00:1f.0 -> ../../../devices/pci0/00:1f.0
-|-- 00:1f.1 -> ../../../devices/pci0/00:1f.1
-|-- 00:1f.2 -> ../../../devices/pci0/00:1f.2
-|-- 00:1f.3 -> ../../../devices/pci0/00:1f.3
-|-- 00:1f.5 -> ../../../devices/pci0/00:1f.5
-|-- 01:00.0 -> ../../../devices/pci0/00:01.0/01:00.0
-|-- 02:1f.0 -> ../../../devices/pci0/00:02.0/02:1f.0
-|-- 03:00.0 -> ../../../devices/pci0/00:02.0/02:1f.0/03:00.0
-`-- 04:04.0 -> ../../../devices/pci0/00:1e.0/04:04.0
+    /sys/bus/pci/devices/
+    |-- 00:00.0 -> ../../../devices/pci0/00:00.0
+    |-- 00:01.0 -> ../../../devices/pci0/00:01.0
+    |-- 00:02.0 -> ../../../devices/pci0/00:02.0
+    |-- 00:1e.0 -> ../../../devices/pci0/00:1e.0
+    |-- 00:1f.0 -> ../../../devices/pci0/00:1f.0
+    |-- 00:1f.1 -> ../../../devices/pci0/00:1f.1
+    |-- 00:1f.2 -> ../../../devices/pci0/00:1f.2
+    |-- 00:1f.3 -> ../../../devices/pci0/00:1f.3
+    |-- 00:1f.5 -> ../../../devices/pci0/00:1f.5
+    |-- 01:00.0 -> ../../../devices/pci0/00:01.0/01:00.0
+    |-- 02:1f.0 -> ../../../devices/pci0/00:02.0/02:1f.0
+    |-- 03:00.0 -> ../../../devices/pci0/00:02.0/02:1f.0/03:00.0
+    `-- 04:04.0 -> ../../../devices/pci0/00:1e.0/04:04.0
 
 
 
 Step 3: Registering Drivers.
 
 struct device_driver is a simple driver structure that contains a set
-of operations that the driver model core may call. 
+of operations that the driver model core may call.
 
 
-- Embed a struct device_driver in the bus-specific driver. 
+- Embed a struct device_driver in the bus-specific driver.
 
-  Just like with devices, do something like:
+  Just like with devices, do something like::
 
-struct pci_driver {
-       ...
-       struct device_driver    driver;
-};
+    struct pci_driver {
+           ...
+           struct device_driver    driver;
+    };
 
 
-- Initialize the generic driver structure. 
+- Initialize the generic driver structure.
 
   When the driver registers with the bus (e.g. doing pci_register_driver()),
   initialize the necessary fields of the driver: the name and bus
-  fields. 
+  fields.
 
 
 - Register the driver.
 
-  After the generic driver has been initialized, call
+  After the generic driver has been initialized, call::
 
 	driver_register(&drv->driver);
 
   to register the driver with the core.
 
   When the driver is unregistered from the bus, unregister it from the
-  core by doing:
+  core by doing::
 
         driver_unregister(&drv->driver);
 
@@ -265,15 +267,15 @@ struct pci_driver {
 
 - Sysfs representation.
 
-  Drivers are exported via sysfs in their bus's 'driver's directory. 
-  For example:
+  Drivers are exported via sysfs in their bus's 'driver's directory.
+  For example::
 
-/sys/bus/pci/drivers/
-|-- 3c59x
-|-- Ensoniq AudioPCI
-|-- agpgart-amdk7
-|-- e100
-`-- serial
+    /sys/bus/pci/drivers/
+    |-- 3c59x
+    |-- Ensoniq AudioPCI
+    |-- agpgart-amdk7
+    |-- e100
+    `-- serial
 
 
 Step 4: Define Generic Methods for Drivers.
@@ -281,30 +283,30 @@ Step 4: Define Generic Methods for Drivers.
 struct device_driver defines a set of operations that the driver model
 core calls. Most of these operations are probably similar to
 operations the bus already defines for drivers, but taking different
-parameters. 
+parameters.
 
 It would be difficult and tedious to force every driver on a bus to
 simultaneously convert their drivers to generic format. Instead, the
 bus driver should define single instances of the generic methods that
-forward call to the bus-specific drivers. For instance: 
+forward call to the bus-specific drivers. For instance::
 
 
-static int pci_device_remove(struct device * dev)
-{
-        struct pci_dev * pci_dev = to_pci_dev(dev);
-        struct pci_driver * drv = pci_dev->driver;
+  static int pci_device_remove(struct device * dev)
+  {
+          struct pci_dev * pci_dev = to_pci_dev(dev);
+          struct pci_driver * drv = pci_dev->driver;
 
-        if (drv) {
-                if (drv->remove)
-                        drv->remove(pci_dev);
-                pci_dev->driver = NULL;
-        }
-        return 0;
-}
+          if (drv) {
+                  if (drv->remove)
+                          drv->remove(pci_dev);
+                  pci_dev->driver = NULL;
+          }
+          return 0;
+  }
 
 
 The generic driver should be initialized with these methods before it
-is registered. 
+is registered::
 
         /* initialize common driver fields */
         drv->driver.name = drv->name;
@@ -320,23 +322,23 @@ is registered.
 
 Ideally, the bus should only initialize the fields if they are not
 already set. This allows the drivers to implement their own generic
-methods. 
+methods.
 
 
-Step 5: Support generic driver binding. 
+Step 5: Support generic driver binding.
 
 The model assumes that a device or driver can be dynamically
 registered with the bus at any time. When registration happens,
 devices must be bound to a driver, or drivers must be bound to all
-devices that it supports. 
+devices that it supports.
 
 A driver typically contains a list of device IDs that it supports. The
-bus driver compares these IDs to the IDs of devices registered with it. 
+bus driver compares these IDs to the IDs of devices registered with it.
 The format of the device IDs, and the semantics for comparing them are
-bus-specific, so the generic model does attempt to generalize them. 
+bus-specific, so the generic model does attempt to generalize them.
 
 Instead, a bus may supply a method in struct bus_type that does the
-comparison: 
+comparison::
 
   int (*match)(struct device * dev, struct device_driver * drv);
 
@@ -346,59 +348,59 @@ and zero otherwise. It may also return error code (for example
 not possible.
 
 When a device is registered, the bus's list of drivers is iterated
-over. bus->match() is called for each one until a match is found. 
+over. bus->match() is called for each one until a match is found.
 
 When a driver is registered, the bus's list of devices is iterated
 over. bus->match() is called for each device that is not already
-claimed by a driver. 
+claimed by a driver.
 
 When a device is successfully bound to a driver, device->driver is
 set, the device is added to a per-driver list of devices, and a
 symlink is created in the driver's sysfs directory that points to the
-device's physical directory:
+device's physical directory::
 
-/sys/bus/pci/drivers/
-|-- 3c59x
-|   `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0
-|-- Ensoniq AudioPCI
-|-- agpgart-amdk7
-|   `-- 00:00.0 -> ../../../../devices/pci0/00:00.0
-|-- e100
-|   `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0
-`-- serial
+  /sys/bus/pci/drivers/
+  |-- 3c59x
+  |   `-- 00:0b.0 -> ../../../../devices/pci0/00:0b.0
+  |-- Ensoniq AudioPCI
+  |-- agpgart-amdk7
+  |   `-- 00:00.0 -> ../../../../devices/pci0/00:00.0
+  |-- e100
+  |   `-- 00:0c.0 -> ../../../../devices/pci0/00:0c.0
+  `-- serial
 
 
 This driver binding should replace the existing driver binding
-mechanism the bus currently uses. 
+mechanism the bus currently uses.
 
 
 Step 6: Supply a hotplug callback.
 
 Whenever a device is registered with the driver model core, the
-userspace program /sbin/hotplug is called to notify userspace. 
+userspace program /sbin/hotplug is called to notify userspace.
 Users can define actions to perform when a device is inserted or
-removed. 
+removed.
 
 The driver model core passes several arguments to userspace via
 environment variables, including
 
 - ACTION: set to 'add' or 'remove'
-- DEVPATH: set to the device's physical path in sysfs. 
+- DEVPATH: set to the device's physical path in sysfs.
 
 A bus driver may also supply additional parameters for userspace to
 consume. To do this, a bus must implement the 'hotplug' method in
-struct bus_type:
+struct bus_type::
 
-     int (*hotplug) (struct device *dev, char **envp, 
+     int (*hotplug) (struct device *dev, char **envp,
                      int num_envp, char *buffer, int buffer_size);
 
-This is called immediately before /sbin/hotplug is executed. 
+This is called immediately before /sbin/hotplug is executed.
 
 
 Step 7: Cleaning up the bus driver.
 
 The generic bus, device, and driver structures provide several fields
-that can replace those defined privately to the bus driver. 
+that can replace those defined privately to the bus driver.
 
 - Device list.
 
@@ -407,36 +409,36 @@ type. This includes all devices on all instances of that bus type.
 An internal list that the bus uses may be removed, in favor of using
 this one.
 
-The core provides an iterator to access these devices. 
+The core provides an iterator to access these devices::
 
-int bus_for_each_dev(struct bus_type * bus, struct device * start, 
-                     void * data, int (*fn)(struct device *, void *));
+  int bus_for_each_dev(struct bus_type * bus, struct device * start,
+                       void * data, int (*fn)(struct device *, void *));
 
 
 - Driver list.
 
 struct bus_type also contains a list of all drivers registered with
-it. An internal list of drivers that the bus driver maintains may 
-be removed in favor of using the generic one. 
+it. An internal list of drivers that the bus driver maintains may
+be removed in favor of using the generic one.
 
-The drivers may be iterated over, like devices: 
+The drivers may be iterated over, like devices::
 
-int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
-                     void * data, int (*fn)(struct device_driver *, void *));
+  int bus_for_each_drv(struct bus_type * bus, struct device_driver * start,
+                       void * data, int (*fn)(struct device_driver *, void *));
 
 
 Please see drivers/base/bus.c for more information.
 
 
-- rwsem 
+- rwsem
 
 struct bus_type contains an rwsem that protects all core accesses to
 the device and driver lists. This can be used by the bus driver
 internally, and should be used when accessing the device or driver
-lists the bus maintains. 
+lists the bus maintains.
 
 
-- Device and driver fields. 
+- Device and driver fields.
 
 Some of the fields in struct device and struct device_driver duplicate
 fields in the bus-specific representations of these objects. Feel free
@@ -444,4 +446,3 @@ to remove the bus-specific ones and favor the generic ones. Note
 though, that this will likely mean fixing up all the drivers that
 reference the bus-specific fields (though those should all be 1-line
 changes).
-
diff --git a/Documentation/eisa.txt b/Documentation/eisa.txt
index 2806e5544e43..f388545a85a7 100644
--- a/Documentation/eisa.txt
+++ b/Documentation/eisa.txt
@@ -103,7 +103,7 @@ id_table	an array of NULL terminated EISA id strings,
 		(driver_data).
 
 driver		a generic driver, such as described in
-		Documentation/driver-model/driver.txt. Only .name,
+		Documentation/driver-model/driver.rst. Only .name,
 		.probe and .remove members are mandatory.
 =============== ====================================================
 
@@ -152,7 +152,7 @@ state    set of flags indicating the state of the device. Current
 	 flags are EISA_CONFIG_ENABLED and EISA_CONFIG_FORCED.
 res	 set of four 256 bytes I/O regions allocated to this device
 dma_mask DMA mask set from the parent device.
-dev	 generic device (see Documentation/driver-model/device.txt)
+dev	 generic device (see Documentation/driver-model/device.rst)
 ======== ============================================================
 
 You can get the 'struct eisa_device' from 'struct device' using the
diff --git a/Documentation/hwmon/submitting-patches.rst b/Documentation/hwmon/submitting-patches.rst
index f9796b9d9db6..d5b05d3e54ba 100644
--- a/Documentation/hwmon/submitting-patches.rst
+++ b/Documentation/hwmon/submitting-patches.rst
@@ -89,7 +89,7 @@ increase the chances of your change being accepted.
   console. Excessive logging can seriously affect system performance.
 
 * Use devres functions whenever possible to allocate resources. For rationale
-  and supported functions, please see Documentation/driver-model/devres.txt.
+  and supported functions, please see Documentation/driver-model/devres.rst.
   If a function is not supported by devres, consider using devm_add_action().
 
 * If the driver has a detect function, make sure it is silent. Debug messages
diff --git a/drivers/base/platform.c b/drivers/base/platform.c
index 4d1729853d1a..713903290385 100644
--- a/drivers/base/platform.c
+++ b/drivers/base/platform.c
@@ -5,7 +5,7 @@
  * Copyright (c) 2002-3 Patrick Mochel
  * Copyright (c) 2002-3 Open Source Development Labs
  *
- * Please see Documentation/driver-model/platform.txt for more
+ * Please see Documentation/driver-model/platform.rst for more
  * information.
  */
 
diff --git a/drivers/gpio/gpio-cs5535.c b/drivers/gpio/gpio-cs5535.c
index 6314225dbed0..3611a0571667 100644
--- a/drivers/gpio/gpio-cs5535.c
+++ b/drivers/gpio/gpio-cs5535.c
@@ -41,7 +41,7 @@ MODULE_PARM_DESC(mask, "GPIO channel mask.");
 
 /*
  * FIXME: convert this singleton driver to use the state container
- * design pattern, see Documentation/driver-model/design-patterns.txt
+ * design pattern, see Documentation/driver-model/design-patterns.rst
  */
 static struct cs5535_gpio_chip {
 	struct gpio_chip chip;
diff --git a/drivers/net/ethernet/intel/ice/ice_main.c b/drivers/net/ethernet/intel/ice/ice_main.c
index 28ec0d57941d..41c90f2ddb31 100644
--- a/drivers/net/ethernet/intel/ice/ice_main.c
+++ b/drivers/net/ethernet/intel/ice/ice_main.c
@@ -2286,7 +2286,7 @@ ice_probe(struct pci_dev *pdev, const struct pci_device_id __always_unused *ent)
 	struct ice_hw *hw;
 	int err;
 
-	/* this driver uses devres, see Documentation/driver-model/devres.txt */
+	/* this driver uses devres, see Documentation/driver-model/devres.rst */
 	err = pcim_enable_device(pdev);
 	if (err)
 		return err;
diff --git a/scripts/coccinelle/free/devm_free.cocci b/scripts/coccinelle/free/devm_free.cocci
index b2a2cf8bf81f..e32236a979a8 100644
--- a/scripts/coccinelle/free/devm_free.cocci
+++ b/scripts/coccinelle/free/devm_free.cocci
@@ -2,7 +2,7 @@
 /// functions.  Values allocated using the devm_functions are freed when
 /// the device is detached, and thus the use of the standard freeing
 /// function would cause a double free.
-/// See Documentation/driver-model/devres.txt for more information.
+/// See Documentation/driver-model/devres.rst for more information.
 ///
 /// A difficulty of detecting this problem is that the standard freeing
 /// function might be called from a different function than the one
-- 
2.21.0

Re: [PATCH v2 09/29] docs: driver-model: convert docs to ReST and rename to *.rst

[Greg Kroah-Hartman]

On Tue, Jun 18, 2019 at 05:53:27PM -0300, Mauro Carvalho Chehab wrote:
> Convert the various documents at the driver-model, preparing
> them to be part of the driver-api 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>
> Acked-by: Jeff Kirsher <jeffrey.t.kirsher@intel.com> # ice

Now applied, thanks.

greg k-h

[PATCH v2 11/29] docs: memory-devices: convert ti-emif.txt to ReST

[Mauro Carvalho Chehab]

Prepare this file to be moved to a kernel book by converting
it to ReST format and renaming it to ti-emif.rst.

While this is not part of any book, mark it as :orphan:, in order
to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 .../{ti-emif.txt => ti-emif.rst}              | 27 ++++++++++++-------
 1 file changed, 17 insertions(+), 10 deletions(-)
 rename Documentation/memory-devices/{ti-emif.txt => ti-emif.rst} (81%)

diff --git a/Documentation/memory-devices/ti-emif.txt b/Documentation/memory-devices/ti-emif.rst
similarity index 81%
rename from Documentation/memory-devices/ti-emif.txt
rename to Documentation/memory-devices/ti-emif.rst
index f4ad9a7d0f4b..c9242294e63c 100644
--- a/Documentation/memory-devices/ti-emif.txt
+++ b/Documentation/memory-devices/ti-emif.rst
@@ -1,20 +1,24 @@
-TI EMIF SDRAM Controller Driver:
+:orphan:
+
+===============================
+TI EMIF SDRAM Controller Driver
+===============================
 
 Author
-========
+======
 Aneesh V <aneesh@ti.com>
 
 Location
-============
+========
 driver/memory/emif.c
 
 Supported SoCs:
-===================
+===============
 TI OMAP44xx
 TI OMAP54xx
 
 Menuconfig option:
-==========================
+==================
 Device Drivers
 	Memory devices
 		Texas Instruments EMIF driver
@@ -29,10 +33,11 @@ functions of the driver includes re-configuring AC timing
 parameters and other settings during frequency, voltage and
 temperature changes
 
-Platform Data (see include/linux/platform_data/emif_plat.h):
-=====================================================================
+Platform Data (see include/linux/platform_data/emif_plat.h)
+===========================================================
 DDR device details and other board dependent and SoC dependent
 information can be passed through platform data (struct emif_platform_data)
+
 - DDR device details: 'struct ddr_device_info'
 - Device AC timings: 'struct lpddr2_timings' and 'struct lpddr2_min_tck'
 - Custom configurations: customizable policy options through
@@ -40,17 +45,19 @@ information can be passed through platform data (struct emif_platform_data)
 - IP revision
 - PHY type
 
-Interface to the external world:
-================================
+Interface to the external world
+===============================
 EMIF driver registers notifiers for voltage and frequency changes
 affecting EMIF and takes appropriate actions when these are invoked.
+
 - freq_pre_notify_handling()
 - freq_post_notify_handling()
 - volt_notify_handling()
 
 Debugfs
-========
+=======
 The driver creates two debugfs entries per device.
+
 - regcache_dump : dump of register values calculated and saved for all
   frequencies used so far.
 - mr4 : last polled value of MR4 register in the LPDDR2 device. MR4
-- 
2.21.0

[PATCH v2 12/29] docs: xen-tpmfront.txt: convert it to .rst

[Mauro Carvalho Chehab]

In order to be able to add this file to the security book,
we need first to convert it to reST.

While this is not part of any book, mark it as :orphan:, in order
to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 .../{xen-tpmfront.txt => xen-tpmfront.rst}    | 103 ++++++++++--------
 1 file changed, 58 insertions(+), 45 deletions(-)
 rename Documentation/security/tpm/{xen-tpmfront.txt => xen-tpmfront.rst} (66%)

diff --git a/Documentation/security/tpm/xen-tpmfront.txt b/Documentation/security/tpm/xen-tpmfront.rst
similarity index 66%
rename from Documentation/security/tpm/xen-tpmfront.txt
rename to Documentation/security/tpm/xen-tpmfront.rst
index 69346de87ff3..98a16ab87360 100644
--- a/Documentation/security/tpm/xen-tpmfront.txt
+++ b/Documentation/security/tpm/xen-tpmfront.rst
@@ -1,4 +1,8 @@
+:orphan:
+
+=============================
 Virtual TPM interface for Xen
+=============================
 
 Authors: Matthew Fioravante (JHUAPL), Daniel De Graaf (NSA)
 
@@ -6,7 +10,8 @@ This document describes the virtual Trusted Platform Module (vTPM) subsystem for
 Xen. The reader is assumed to have familiarity with building and installing Xen,
 Linux, and a basic understanding of the TPM and vTPM concepts.
 
-INTRODUCTION
+Introduction
+------------
 
 The goal of this work is to provide a TPM functionality to a virtual guest
 operating system (in Xen terms, a DomU).  This allows programs to interact with
@@ -24,81 +29,89 @@ This mini-os vTPM subsystem was built on top of the previous vTPM work done by
 IBM and Intel corporation.
 
 
-DESIGN OVERVIEW
+Design Overview
 ---------------
 
-The architecture of vTPM is described below:
+The architecture of vTPM is described below::
 
-+------------------+
-|    Linux DomU    | ...
-|       |  ^       |
-|       v  |       |
-|   xen-tpmfront   |
-+------------------+
-        |  ^
-        v  |
-+------------------+
-| mini-os/tpmback  |
-|       |  ^       |
-|       v  |       |
-|  vtpm-stubdom    | ...
-|       |  ^       |
-|       v  |       |
-| mini-os/tpmfront |
-+------------------+
-        |  ^
-        v  |
-+------------------+
-| mini-os/tpmback  |
-|       |  ^       |
-|       v  |       |
-| vtpmmgr-stubdom  |
-|       |  ^       |
-|       v  |       |
-| mini-os/tpm_tis  |
-+------------------+
-        |  ^
-        v  |
-+------------------+
-|   Hardware TPM   |
-+------------------+
+  +------------------+
+  |    Linux DomU    | ...
+  |       |  ^       |
+  |       v  |       |
+  |   xen-tpmfront   |
+  +------------------+
+          |  ^
+          v  |
+  +------------------+
+  | mini-os/tpmback  |
+  |       |  ^       |
+  |       v  |       |
+  |  vtpm-stubdom    | ...
+  |       |  ^       |
+  |       v  |       |
+  | mini-os/tpmfront |
+  +------------------+
+          |  ^
+          v  |
+  +------------------+
+  | mini-os/tpmback  |
+  |       |  ^       |
+  |       v  |       |
+  | vtpmmgr-stubdom  |
+  |       |  ^       |
+  |       v  |       |
+  | mini-os/tpm_tis  |
+  +------------------+
+          |  ^
+          v  |
+  +------------------+
+  |   Hardware TPM   |
+  +------------------+
 
- * Linux DomU: The Linux based guest that wants to use a vTPM. There may be
+* Linux DomU:
+	       The Linux based guest that wants to use a vTPM. There may be
 	       more than one of these.
 
- * xen-tpmfront.ko: Linux kernel virtual TPM frontend driver. This driver
+* xen-tpmfront.ko:
+		    Linux kernel virtual TPM frontend driver. This driver
                     provides vTPM access to a Linux-based DomU.
 
- * mini-os/tpmback: Mini-os TPM backend driver. The Linux frontend driver
+* mini-os/tpmback:
+		    Mini-os TPM backend driver. The Linux frontend driver
 		    connects to this backend driver to facilitate communications
 		    between the Linux DomU and its vTPM. This driver is also
 		    used by vtpmmgr-stubdom to communicate with vtpm-stubdom.
 
- * vtpm-stubdom: A mini-os stub domain that implements a vTPM. There is a
+* vtpm-stubdom:
+		 A mini-os stub domain that implements a vTPM. There is a
 		 one to one mapping between running vtpm-stubdom instances and
                  logical vtpms on the system. The vTPM Platform Configuration
                  Registers (PCRs) are normally all initialized to zero.
 
- * mini-os/tpmfront: Mini-os TPM frontend driver. The vTPM mini-os domain
+* mini-os/tpmfront:
+		     Mini-os TPM frontend driver. The vTPM mini-os domain
 		     vtpm-stubdom uses this driver to communicate with
 		     vtpmmgr-stubdom. This driver is also used in mini-os
 		     domains such as pv-grub that talk to the vTPM domain.
 
- * vtpmmgr-stubdom: A mini-os domain that implements the vTPM manager. There is
+* vtpmmgr-stubdom:
+		    A mini-os domain that implements the vTPM manager. There is
 		    only one vTPM manager and it should be running during the
 		    entire lifetime of the machine.  This domain regulates
 		    access to the physical TPM on the system and secures the
 		    persistent state of each vTPM.
 
- * mini-os/tpm_tis: Mini-os TPM version 1.2 TPM Interface Specification (TIS)
+* mini-os/tpm_tis:
+		    Mini-os TPM version 1.2 TPM Interface Specification (TIS)
                     driver. This driver used by vtpmmgr-stubdom to talk directly to
                     the hardware TPM. Communication is facilitated by mapping
                     hardware memory pages into vtpmmgr-stubdom.
 
- * Hardware TPM: The physical TPM that is soldered onto the motherboard.
+* Hardware TPM:
+		The physical TPM that is soldered onto the motherboard.
 
 
-INTEGRATION WITH XEN
+Integration With Xen
 --------------------
 
 Support for the vTPM driver was added in Xen using the libxl toolstack in Xen
-- 
2.21.0

[PATCH v2 13/29] docs: bus-devices: ti-gpmc.rst: convert it to ReST

[Mauro Carvalho Chehab]

In order to be able to add this file to a book, it needs
first to be converted to ReST and renamed.

While this is not part of any book, mark it as :orphan:, in order
to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 .../bus-devices/{ti-gpmc.txt => ti-gpmc.rst}  | 159 ++++++++++++------
 1 file changed, 108 insertions(+), 51 deletions(-)
 rename Documentation/bus-devices/{ti-gpmc.txt => ti-gpmc.rst} (58%)

diff --git a/Documentation/bus-devices/ti-gpmc.txt b/Documentation/bus-devices/ti-gpmc.rst
similarity index 58%
rename from Documentation/bus-devices/ti-gpmc.txt
rename to Documentation/bus-devices/ti-gpmc.rst
index cc9ce57e0a26..87c366e418be 100644
--- a/Documentation/bus-devices/ti-gpmc.txt
+++ b/Documentation/bus-devices/ti-gpmc.rst
@@ -1,8 +1,12 @@
-GPMC (General Purpose Memory Controller):
-=========================================
+:orphan:
+
+========================================
+GPMC (General Purpose Memory Controller)
+========================================
 
 GPMC is an unified memory controller dedicated to interfacing external
 memory devices like
+
  * Asynchronous SRAM like memories and application specific integrated
    circuit devices.
  * Asynchronous, synchronous, and page mode burst NOR flash devices
@@ -48,75 +52,128 @@ most of the datasheets & hardware (to be exact none of those supported
 in mainline having custom timing routine) and by simulation.
 
 gpmc timing dependency on peripheral timings:
+
 [<gpmc_timing>: <peripheral timing1>, <peripheral timing2> ...]
 
 1. common
-cs_on: t_ceasu
-adv_on: t_avdasu, t_ceavd
+
+cs_on:
+	t_ceasu
+adv_on:
+	t_avdasu, t_ceavd
 
 2. sync common
-sync_clk: clk
-page_burst_access: t_bacc
-clk_activation: t_ces, t_avds
+
+sync_clk:
+	clk
+page_burst_access:
+	t_bacc
+clk_activation:
+	t_ces, t_avds
 
 3. read async muxed
-adv_rd_off: t_avdp_r
-oe_on: t_oeasu, t_aavdh
-access: t_iaa, t_oe, t_ce, t_aa
-rd_cycle: t_rd_cycle, t_cez_r, t_oez
+
+adv_rd_off:
+	t_avdp_r
+oe_on:
+	t_oeasu, t_aavdh
+access:
+	t_iaa, t_oe, t_ce, t_aa
+rd_cycle:
+	t_rd_cycle, t_cez_r, t_oez
 
 4. read async non-muxed
-adv_rd_off: t_avdp_r
-oe_on: t_oeasu
-access: t_iaa, t_oe, t_ce, t_aa
-rd_cycle: t_rd_cycle, t_cez_r, t_oez
+
+adv_rd_off:
+	t_avdp_r
+oe_on:
+	t_oeasu
+access:
+	t_iaa, t_oe, t_ce, t_aa
+rd_cycle:
+	t_rd_cycle, t_cez_r, t_oez
 
 5. read sync muxed
-adv_rd_off: t_avdp_r, t_avdh
-oe_on: t_oeasu, t_ach, cyc_aavdh_oe
-access: t_iaa, cyc_iaa, cyc_oe
-rd_cycle: t_cez_r, t_oez, t_ce_rdyz
+
+adv_rd_off:
+	t_avdp_r, t_avdh
+oe_on:
+	t_oeasu, t_ach, cyc_aavdh_oe
+access:
+	t_iaa, cyc_iaa, cyc_oe
+rd_cycle:
+	t_cez_r, t_oez, t_ce_rdyz
 
 6. read sync non-muxed
-adv_rd_off: t_avdp_r
-oe_on: t_oeasu
-access: t_iaa, cyc_iaa, cyc_oe
-rd_cycle: t_cez_r, t_oez, t_ce_rdyz
+
+adv_rd_off:
+	t_avdp_r
+oe_on:
+	t_oeasu
+access:
+	t_iaa, cyc_iaa, cyc_oe
+rd_cycle:
+	t_cez_r, t_oez, t_ce_rdyz
 
 7. write async muxed
-adv_wr_off: t_avdp_w
-we_on, wr_data_mux_bus: t_weasu, t_aavdh, cyc_aavhd_we
-we_off: t_wpl
-cs_wr_off: t_wph
-wr_cycle: t_cez_w, t_wr_cycle
+
+adv_wr_off:
+	t_avdp_w
+we_on, wr_data_mux_bus:
+	t_weasu, t_aavdh, cyc_aavhd_we
+we_off:
+	t_wpl
+cs_wr_off:
+	t_wph
+wr_cycle:
+	t_cez_w, t_wr_cycle
 
 8. write async non-muxed
-adv_wr_off: t_avdp_w
-we_on, wr_data_mux_bus: t_weasu
-we_off: t_wpl
-cs_wr_off: t_wph
-wr_cycle: t_cez_w, t_wr_cycle
+
+adv_wr_off:
+	t_avdp_w
+we_on, wr_data_mux_bus:
+	t_weasu
+we_off:
+	t_wpl
+cs_wr_off:
+	t_wph
+wr_cycle:
+	t_cez_w, t_wr_cycle
 
 9. write sync muxed
-adv_wr_off: t_avdp_w, t_avdh
-we_on, wr_data_mux_bus: t_weasu, t_rdyo, t_aavdh, cyc_aavhd_we
-we_off: t_wpl, cyc_wpl
-cs_wr_off: t_wph
-wr_cycle: t_cez_w, t_ce_rdyz
+
+adv_wr_off:
+	t_avdp_w, t_avdh
+we_on, wr_data_mux_bus:
+	t_weasu, t_rdyo, t_aavdh, cyc_aavhd_we
+we_off:
+	t_wpl, cyc_wpl
+cs_wr_off:
+	t_wph
+wr_cycle:
+	t_cez_w, t_ce_rdyz
 
 10. write sync non-muxed
-adv_wr_off: t_avdp_w
-we_on, wr_data_mux_bus: t_weasu, t_rdyo
-we_off: t_wpl, cyc_wpl
-cs_wr_off: t_wph
-wr_cycle: t_cez_w, t_ce_rdyz
 
+adv_wr_off:
+	t_avdp_w
+we_on, wr_data_mux_bus:
+	t_weasu, t_rdyo
+we_off:
+	t_wpl, cyc_wpl
+cs_wr_off:
+	t_wph
+wr_cycle:
+	t_cez_w, t_ce_rdyz
 
-Note: Many of gpmc timings are dependent on other gpmc timings (a few
-gpmc timings purely dependent on other gpmc timings, a reason that
-some of the gpmc timings are missing above), and it will result in
-indirect dependency of peripheral timings to gpmc timings other than
-mentioned above, refer timing routine for more details. To know what
-these peripheral timings correspond to, please see explanations in
-struct gpmc_device_timings definition. And for gpmc timings refer
-IP details (link above).
+
+Note:
+  Many of gpmc timings are dependent on other gpmc timings (a few
+  gpmc timings purely dependent on other gpmc timings, a reason that
+  some of the gpmc timings are missing above), and it will result in
+  indirect dependency of peripheral timings to gpmc timings other than
+  mentioned above, refer timing routine for more details. To know what
+  these peripheral timings correspond to, please see explanations in
+  struct gpmc_device_timings definition. And for gpmc timings refer
+  IP details (link above).
-- 
2.21.0

[PATCH v2 14/29] docs: nvmem: convert docs to ReST and rename to *.rst

[Mauro Carvalho Chehab]

In order to be able to add it into a doc book, we need first
convert it to ReST.

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

While this is not part of any book, mark it as :orphan:, in order
to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/nvmem/{nvmem.txt => nvmem.rst} | 112 ++++++++++---------
 1 file changed, 59 insertions(+), 53 deletions(-)
 rename Documentation/nvmem/{nvmem.txt => nvmem.rst} (62%)

diff --git a/Documentation/nvmem/nvmem.txt b/Documentation/nvmem/nvmem.rst
similarity index 62%
rename from Documentation/nvmem/nvmem.txt
rename to Documentation/nvmem/nvmem.rst
index fc2fe4b18655..3866b6e066d5 100644
--- a/Documentation/nvmem/nvmem.txt
+++ b/Documentation/nvmem/nvmem.rst
@@ -1,5 +1,10 @@
-			    NVMEM SUBSYSTEM
-	  Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
+:orphan:
+
+===============
+NVMEM Subsystem
+===============
+
+ Srinivas Kandagatla <srinivas.kandagatla@linaro.org>
 
 This document explains the NVMEM Framework along with the APIs provided,
 and how to use it.
@@ -40,54 +45,54 @@ nvmem_device pointer.
 
 nvmem_unregister(nvmem) is used to unregister a previously registered provider.
 
-For example, a simple qfprom case:
+For example, a simple qfprom case::
 
-static struct nvmem_config econfig = {
+  static struct nvmem_config econfig = {
 	.name = "qfprom",
 	.owner = THIS_MODULE,
-};
+  };
 
-static int qfprom_probe(struct platform_device *pdev)
-{
+  static int qfprom_probe(struct platform_device *pdev)
+  {
 	...
 	econfig.dev = &pdev->dev;
 	nvmem = nvmem_register(&econfig);
 	...
-}
+  }
 
 It is mandatory that the NVMEM provider has a regmap associated with its
 struct device. Failure to do would return error code from nvmem_register().
 
 Users of board files can define and register nvmem cells using the
-nvmem_cell_table struct:
+nvmem_cell_table struct::
 
-static struct nvmem_cell_info foo_nvmem_cells[] = {
+  static struct nvmem_cell_info foo_nvmem_cells[] = {
 	{
 		.name		= "macaddr",
 		.offset		= 0x7f00,
 		.bytes		= ETH_ALEN,
 	}
-};
+  };
 
-static struct nvmem_cell_table foo_nvmem_cell_table = {
+  static struct nvmem_cell_table foo_nvmem_cell_table = {
 	.nvmem_name		= "i2c-eeprom",
 	.cells			= foo_nvmem_cells,
 	.ncells			= ARRAY_SIZE(foo_nvmem_cells),
-};
+  };
 
-nvmem_add_cell_table(&foo_nvmem_cell_table);
+  nvmem_add_cell_table(&foo_nvmem_cell_table);
 
 Additionally it is possible to create nvmem cell lookup entries and register
-them with the nvmem framework from machine code as shown in the example below:
+them with the nvmem framework from machine code as shown in the example below::
 
-static struct nvmem_cell_lookup foo_nvmem_lookup = {
+  static struct nvmem_cell_lookup foo_nvmem_lookup = {
 	.nvmem_name		= "i2c-eeprom",
 	.cell_name		= "macaddr",
 	.dev_id			= "foo_mac.0",
 	.con_id			= "mac-address",
-};
+  };
 
-nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
+  nvmem_add_cell_lookups(&foo_nvmem_lookup, 1);
 
 NVMEM Consumers
 +++++++++++++++
@@ -99,43 +104,43 @@ read from and to NVMEM.
 =================================
 
 NVMEM cells are the data entries/fields in the NVMEM.
-The NVMEM framework provides 3 APIs to read/write NVMEM cells.
+The NVMEM framework provides 3 APIs to read/write NVMEM cells::
 
-struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name);
-struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
+  struct nvmem_cell *nvmem_cell_get(struct device *dev, const char *name);
+  struct nvmem_cell *devm_nvmem_cell_get(struct device *dev, const char *name);
 
-void nvmem_cell_put(struct nvmem_cell *cell);
-void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
+  void nvmem_cell_put(struct nvmem_cell *cell);
+  void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
 
-void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);
-int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len);
+  void *nvmem_cell_read(struct nvmem_cell *cell, ssize_t *len);
+  int nvmem_cell_write(struct nvmem_cell *cell, void *buf, ssize_t len);
 
-*nvmem_cell_get() apis will get a reference to nvmem cell for a given id,
+`*nvmem_cell_get()` apis will get a reference to nvmem cell for a given id,
 and nvmem_cell_read/write() can then read or write to the cell.
-Once the usage of the cell is finished the consumer should call *nvmem_cell_put()
-to free all the allocation memory for the cell.
+Once the usage of the cell is finished the consumer should call
+`*nvmem_cell_put()` to free all the allocation memory for the cell.
 
 4. Direct NVMEM device based consumer APIs
 ==========================================
 
 In some instances it is necessary to directly read/write the NVMEM.
-To facilitate such consumers NVMEM framework provides below apis.
+To facilitate such consumers NVMEM framework provides below apis::
 
-struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);
-struct nvmem_device *devm_nvmem_device_get(struct device *dev,
+  struct nvmem_device *nvmem_device_get(struct device *dev, const char *name);
+  struct nvmem_device *devm_nvmem_device_get(struct device *dev,
 					   const char *name);
-void nvmem_device_put(struct nvmem_device *nvmem);
-int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
+  void nvmem_device_put(struct nvmem_device *nvmem);
+  int nvmem_device_read(struct nvmem_device *nvmem, unsigned int offset,
 		      size_t bytes, void *buf);
-int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
+  int nvmem_device_write(struct nvmem_device *nvmem, unsigned int offset,
 		       size_t bytes, void *buf);
-int nvmem_device_cell_read(struct nvmem_device *nvmem,
+  int nvmem_device_cell_read(struct nvmem_device *nvmem,
 			   struct nvmem_cell_info *info, void *buf);
-int nvmem_device_cell_write(struct nvmem_device *nvmem,
+  int nvmem_device_cell_write(struct nvmem_device *nvmem,
 			    struct nvmem_cell_info *info, void *buf);
 
 Before the consumers can read/write NVMEM directly, it should get hold
-of nvmem_controller from one of the *nvmem_device_get() api.
+of nvmem_controller from one of the `*nvmem_device_get()` api.
 
 The difference between these apis and cell based apis is that these apis always
 take nvmem_device as parameter.
@@ -145,12 +150,12 @@ take nvmem_device as parameter.
 
 When a consumer no longer needs the NVMEM, it has to release the reference
 to the NVMEM it has obtained using the APIs mentioned in the above section.
-The NVMEM framework provides 2 APIs to release a reference to the NVMEM.
+The NVMEM framework provides 2 APIs to release a reference to the NVMEM::
 
-void nvmem_cell_put(struct nvmem_cell *cell);
-void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
-void nvmem_device_put(struct nvmem_device *nvmem);
-void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
+  void nvmem_cell_put(struct nvmem_cell *cell);
+  void devm_nvmem_cell_put(struct device *dev, struct nvmem_cell *cell);
+  void nvmem_device_put(struct nvmem_device *nvmem);
+  void devm_nvmem_device_put(struct device *dev, struct nvmem_device *nvmem);
 
 Both these APIs are used to release a reference to the NVMEM and
 devm_nvmem_cell_put and devm_nvmem_device_put destroys the devres associated
@@ -162,20 +167,21 @@ Userspace
 6. Userspace binary interface
 ==============================
 
-Userspace can read/write the raw NVMEM file located at
-/sys/bus/nvmem/devices/*/nvmem
+Userspace can read/write the raw NVMEM file located at::
 
-ex:
+	/sys/bus/nvmem/devices/*/nvmem
 
-hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+ex::
 
-0000000 0000 0000 0000 0000 0000 0000 0000 0000
-*
-00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
-0000000 0000 0000 0000 0000 0000 0000 0000 0000
-...
-*
-0001000
+  hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+
+  0000000 0000 0000 0000 0000 0000 0000 0000 0000
+  *
+  00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
+  0000000 0000 0000 0000 0000 0000 0000 0000 0000
+  ...
+  *
+  0001000
 
 7. DeviceTree Binding
 =====================
-- 
2.21.0

[PATCH v2 15/29] docs: phy: convert samsung-usb2.txt to ReST format

[Mauro Carvalho Chehab]

In order to merge it into a Sphinx book, we need first to
convert to ReST.

While this is not part of any book, mark it as :orphan:, in order
to avoid build warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 .../{samsung-usb2.txt => samsung-usb2.rst}    | 62 ++++++++++---------
 MAINTAINERS                                   |  2 +-
 2 files changed, 34 insertions(+), 30 deletions(-)
 rename Documentation/phy/{samsung-usb2.txt => samsung-usb2.rst} (77%)

diff --git a/Documentation/phy/samsung-usb2.txt b/Documentation/phy/samsung-usb2.rst
similarity index 77%
rename from Documentation/phy/samsung-usb2.txt
rename to Documentation/phy/samsung-usb2.rst
index ed12d437189d..98b5952fcb97 100644
--- a/Documentation/phy/samsung-usb2.txt
+++ b/Documentation/phy/samsung-usb2.rst
@@ -1,9 +1,11 @@
-.------------------------------------------------------------------------------+
-|			Samsung USB 2.0 PHY adaptation layer		       |
-+-----------------------------------------------------------------------------+'
+:orphan:
 
-| 1. Description
-+----------------
+====================================
+Samsung USB 2.0 PHY adaptation layer
+====================================
+
+1. Description
+--------------
 
 The architecture of the USB 2.0 PHY module in Samsung SoCs is similar
 among many SoCs. In spite of the similarities it proved difficult to
@@ -14,8 +16,8 @@ the PHY powering up process had to be altered. This adaptation layer is
 a compromise between having separate drivers and having a single driver
 with added support for many special cases.
 
-| 2. Files description
-+----------------------
+2. Files description
+--------------------
 
 - phy-samsung-usb2.c
    This is the main file of the adaptation layer. This file contains
@@ -32,44 +34,45 @@ with added support for many special cases.
    driver. In addition it should contain extern declarations for
    structures that describe particular SoCs.
 
-| 3. Supporting SoCs
-+--------------------
+3. Supporting SoCs
+------------------
 
 To support a new SoC a new file should be added to the drivers/phy
 directory. Each SoC's configuration is stored in an instance of the
-struct samsung_usb2_phy_config.
+struct samsung_usb2_phy_config::
 
-struct samsung_usb2_phy_config {
+  struct samsung_usb2_phy_config {
 	const struct samsung_usb2_common_phy *phys;
 	int (*rate_to_clk)(unsigned long, u32 *);
 	unsigned int num_phys;
 	bool has_mode_switch;
-};
+  };
 
-The num_phys is the number of phys handled by the driver. *phys is an
+The num_phys is the number of phys handled by the driver. `*phys` is an
 array that contains the configuration for each phy. The has_mode_switch
 property is a boolean flag that determines whether the SoC has USB host
 and device on a single pair of pins. If so, a special register has to
 be modified to change the internal routing of these pins between a USB
 device or host module.
 
-For example the configuration for Exynos 4210 is following:
+For example the configuration for Exynos 4210 is following::
 
-const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = {
+  const struct samsung_usb2_phy_config exynos4210_usb2_phy_config = {
 	.has_mode_switch        = 0,
 	.num_phys		= EXYNOS4210_NUM_PHYS,
 	.phys			= exynos4210_phys,
 	.rate_to_clk		= exynos4210_rate_to_clk,
-}
+  }
+
+- `int (*rate_to_clk)(unsigned long, u32 *)`
 
-- int (*rate_to_clk)(unsigned long, u32 *)
 	The rate_to_clk callback is to convert the rate of the clock
 	used as the reference clock for the PHY module to the value
 	that should be written in the hardware register.
 
-The exynos4210_phys configuration array is as follows:
+The exynos4210_phys configuration array is as follows::
 
-static const struct samsung_usb2_common_phy exynos4210_phys[] = {
+  static const struct samsung_usb2_common_phy exynos4210_phys[] = {
 	{
 		.label		= "device",
 		.id		= EXYNOS4210_DEVICE,
@@ -95,29 +98,30 @@ static const struct samsung_usb2_common_phy exynos4210_phys[] = {
 		.power_off	= exynos4210_power_off,
 	},
 	{},
-};
+  };
+
+- `int (*power_on)(struct samsung_usb2_phy_instance *);`
+  `int (*power_off)(struct samsung_usb2_phy_instance *);`
 
-- int (*power_on)(struct samsung_usb2_phy_instance *);
-- int (*power_off)(struct samsung_usb2_phy_instance *);
 	These two callbacks are used to power on and power off the phy
 	by modifying appropriate registers.
 
 Final change to the driver is adding appropriate compatible value to the
 phy-samsung-usb2.c file. In case of Exynos 4210 the following lines were
-added to the struct of_device_id samsung_usb2_phy_of_match[] array:
+added to the struct of_device_id samsung_usb2_phy_of_match[] array::
 
-#ifdef CONFIG_PHY_EXYNOS4210_USB2
+  #ifdef CONFIG_PHY_EXYNOS4210_USB2
 	{
 		.compatible = "samsung,exynos4210-usb2-phy",
 		.data = &exynos4210_usb2_phy_config,
 	},
-#endif
+  #endif
 
 To add further flexibility to the driver the Kconfig file enables to
 include support for selected SoCs in the compiled driver. The Kconfig
-entry for Exynos 4210 is following:
+entry for Exynos 4210 is following::
 
-config PHY_EXYNOS4210_USB2
+  config PHY_EXYNOS4210_USB2
 	bool "Support for Exynos 4210"
 	depends on PHY_SAMSUNG_USB2
 	depends on CPU_EXYNOS4210
@@ -128,8 +132,8 @@ config PHY_EXYNOS4210_USB2
 	  phys are available - device, host, HSCI0 and HSCI1.
 
 The newly created file that supports the new SoC has to be also added to the
-Makefile. In case of Exynos 4210 the added line is following:
+Makefile. In case of Exynos 4210 the added line is following::
 
-obj-$(CONFIG_PHY_EXYNOS4210_USB2)       += phy-exynos4210-usb2.o
+  obj-$(CONFIG_PHY_EXYNOS4210_USB2)       += phy-exynos4210-usb2.o
 
 After completing these steps the support for the new SoC should be ready.
diff --git a/MAINTAINERS b/MAINTAINERS
index 9958d322e355..8941a73880e6 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -13966,7 +13966,7 @@ M:	Sylwester Nawrocki <s.nawrocki@samsung.com>
 L:	linux-kernel@vger.kernel.org
 S:	Supported
 F:	Documentation/devicetree/bindings/phy/samsung-phy.txt
-F:	Documentation/phy/samsung-usb2.txt
+F:	Documentation/phy/samsung-usb2.rst
 F:	drivers/phy/samsung/phy-exynos4210-usb2.c
 F:	drivers/phy/samsung/phy-exynos4x12-usb2.c
 F:	drivers/phy/samsung/phy-exynos5250-usb2.c
-- 
2.21.0

[PATCH v2 16/29] docs: rbtree.txt: fix Sphinx build warnings

[Mauro Carvalho Chehab]

Ths file is already at ReST format. Yet, some recent changes
made it to produce a few warnings when building it with
Sphinx.

Those are trivially fixed by marking some literal blocks.

Fix them before adding it to the docs building system.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/rbtree.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/rbtree.txt b/Documentation/rbtree.txt
index c42a21b99046..523d54b60087 100644
--- a/Documentation/rbtree.txt
+++ b/Documentation/rbtree.txt
@@ -204,21 +204,21 @@ potentially expensive tree iterations. This is done at negligible runtime
 overhead for maintanence; albeit larger memory footprint.
 
 Similar to the rb_root structure, cached rbtrees are initialized to be
-empty via:
+empty via::
 
   struct rb_root_cached mytree = RB_ROOT_CACHED;
 
 Cached rbtree is simply a regular rb_root with an extra pointer to cache the
 leftmost node. This allows rb_root_cached to exist wherever rb_root does,
 which permits augmented trees to be supported as well as only a few extra
-interfaces:
+interfaces::
 
   struct rb_node *rb_first_cached(struct rb_root_cached *tree);
   void rb_insert_color_cached(struct rb_node *, struct rb_root_cached *, bool);
   void rb_erase_cached(struct rb_node *node, struct rb_root_cached *);
 
 Both insert and erase calls have their respective counterpart of augmented
-trees:
+trees::
 
   void rb_insert_augmented_cached(struct rb_node *node, struct rb_root_cached *,
 				  bool, struct rb_augment_callbacks *);
-- 
2.21.0

[PATCH v2 17/29] docs: DMA-API-HOWTO.txt: fix an unmarked code block

[Mauro Carvalho Chehab]

When building with Sphinx, it would produce this warning:

    docs/Documentation/DMA-API-HOWTO.rst:222: WARNING: Definition list ends without a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/DMA-API-HOWTO.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt
index cb712a02f59f..358d495456d1 100644
--- a/Documentation/DMA-API-HOWTO.txt
+++ b/Documentation/DMA-API-HOWTO.txt
@@ -212,7 +212,7 @@ The standard 64-bit addressing device would do something like this::
 
 If the device only supports 32-bit addressing for descriptors in the
 coherent allocations, but supports full 64-bits for streaming mappings
-it would look like this:
+it would look like this::
 
 	if (dma_set_mask(dev, DMA_BIT_MASK(64))) {
 		dev_warn(dev, "mydev: No suitable DMA available\n");
-- 
2.21.0

[PATCH v2 18/29] docs: accounting: convert to ReST

[Mauro Carvalho Chehab]

Rename the accounting documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

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>
---
 .../{cgroupstats.txt => cgroupstats.rst}      | 14 ++--
 ...ay-accounting.txt => delay-accounting.rst} | 61 ++++++++------
 Documentation/accounting/index.rst            | 14 ++++
 Documentation/accounting/{psi.txt => psi.rst} | 40 +++++-----
 ...kstats-struct.txt => taskstats-struct.rst} | 79 ++++++++++++-------
 .../{taskstats.txt => taskstats.rst}          | 15 ++--
 Documentation/admin-guide/cgroup-v2.rst       |  6 +-
 init/Kconfig                                  |  2 +-
 8 files changed, 139 insertions(+), 92 deletions(-)
 rename Documentation/accounting/{cgroupstats.txt => cgroupstats.rst} (77%)
 rename Documentation/accounting/{delay-accounting.txt => delay-accounting.rst} (77%)
 create mode 100644 Documentation/accounting/index.rst
 rename Documentation/accounting/{psi.txt => psi.rst} (91%)
 rename Documentation/accounting/{taskstats-struct.txt => taskstats-struct.rst} (78%)
 rename Documentation/accounting/{taskstats.txt => taskstats.rst} (95%)

diff --git a/Documentation/accounting/cgroupstats.txt b/Documentation/accounting/cgroupstats.rst
similarity index 77%
rename from Documentation/accounting/cgroupstats.txt
rename to Documentation/accounting/cgroupstats.rst
index d16a9849e60e..b9afc48f4ea2 100644
--- a/Documentation/accounting/cgroupstats.txt
+++ b/Documentation/accounting/cgroupstats.rst
@@ -1,3 +1,7 @@
+==================
+Control Groupstats
+==================
+
 Control Groupstats is inspired by the discussion at
 http://lkml.org/lkml/2007/4/11/187 and implements per cgroup statistics as
 suggested by Andrew Morton in http://lkml.org/lkml/2007/4/11/263.
@@ -19,9 +23,9 @@ about tasks blocked on I/O. If CONFIG_TASK_DELAY_ACCT is disabled, this
 information will not be available.
 
 To extract cgroup statistics a utility very similar to getdelays.c
-has been developed, the sample output of the utility is shown below
+has been developed, the sample output of the utility is shown below::
 
-~/balbir/cgroupstats # ./getdelays  -C "/sys/fs/cgroup/a"
-sleeping 1, blocked 0, running 1, stopped 0, uninterruptible 0
-~/balbir/cgroupstats # ./getdelays  -C "/sys/fs/cgroup"
-sleeping 155, blocked 0, running 1, stopped 0, uninterruptible 2
+  ~/balbir/cgroupstats # ./getdelays  -C "/sys/fs/cgroup/a"
+  sleeping 1, blocked 0, running 1, stopped 0, uninterruptible 0
+  ~/balbir/cgroupstats # ./getdelays  -C "/sys/fs/cgroup"
+  sleeping 155, blocked 0, running 1, stopped 0, uninterruptible 2
diff --git a/Documentation/accounting/delay-accounting.txt b/Documentation/accounting/delay-accounting.rst
similarity index 77%
rename from Documentation/accounting/delay-accounting.txt
rename to Documentation/accounting/delay-accounting.rst
index 042ea59b5853..7cc7f5852da0 100644
--- a/Documentation/accounting/delay-accounting.txt
+++ b/Documentation/accounting/delay-accounting.rst
@@ -1,5 +1,6 @@
+================
 Delay accounting
-----------------
+================
 
 Tasks encounter delays in execution when they wait
 for some kernel resource to become available e.g. a
@@ -39,7 +40,9 @@ in detail in a separate document in this directory. Taskstats returns a
 generic data structure to userspace corresponding to per-pid and per-tgid
 statistics. The delay accounting functionality populates specific fields of
 this structure. See
+
      include/linux/taskstats.h
+
 for a description of the fields pertaining to delay accounting.
 It will generally be in the form of counters returning the cumulative
 delay seen for cpu, sync block I/O, swapin, memory reclaim etc.
@@ -61,13 +64,16 @@ also serves as an example of using the taskstats interface.
 Usage
 -----
 
-Compile the kernel with
+Compile the kernel with::
+
 	CONFIG_TASK_DELAY_ACCT=y
 	CONFIG_TASKSTATS=y
 
 Delay accounting is enabled by default at boot up.
-To disable, add
+To disable, add::
+
    nodelayacct
+
 to the kernel boot options. The rest of the instructions
 below assume this has not been done.
 
@@ -78,40 +84,43 @@ The utility also allows a given command to be
 executed and the corresponding delays to be
 seen.
 
-General format of the getdelays command
+General format of the getdelays command::
 
-getdelays [-t tgid] [-p pid] [-c cmd...]
+	getdelays [-t tgid] [-p pid] [-c cmd...]
 
 
-Get delays, since system boot, for pid 10
-# ./getdelays -p 10
-(output similar to next case)
+Get delays, since system boot, for pid 10::
 
-Get sum of delays, since system boot, for all pids with tgid 5
-# ./getdelays -t 5
+	# ./getdelays -p 10
+	(output similar to next case)
 
+Get sum of delays, since system boot, for all pids with tgid 5::
 
-CPU	count	real total	virtual total	delay total
-	7876	92005750	100000000	24001500
-IO	count	delay total
-	0	0
-SWAP	count	delay total
-	0	0
-RECLAIM	count	delay total
-	0	0
+	# ./getdelays -t 5
 
-Get delays seen in executing a given simple command
-# ./getdelays -c ls /
 
-bin   data1  data3  data5  dev  home  media  opt   root  srv        sys  usr
-boot  data2  data4  data6  etc  lib   mnt    proc  sbin  subdomain  tmp  var
+	CPU	count	real total	virtual total	delay total
+		7876	92005750	100000000	24001500
+	IO	count	delay total
+		0	0
+	SWAP	count	delay total
+		0	0
+	RECLAIM	count	delay total
+		0	0
 
+Get delays seen in executing a given simple command::
 
-CPU	count	real total	virtual total	delay total
+  # ./getdelays -c ls /
+
+  bin   data1  data3  data5  dev  home  media  opt   root  srv        sys  usr
+  boot  data2  data4  data6  etc  lib   mnt    proc  sbin  subdomain  tmp  var
+
+
+  CPU	count	real total	virtual total	delay total
 	6	4000250		4000000		0
-IO	count	delay total
+  IO	count	delay total
 	0	0
-SWAP	count	delay total
+  SWAP	count	delay total
 	0	0
-RECLAIM	count	delay total
+  RECLAIM	count	delay total
 	0	0
diff --git a/Documentation/accounting/index.rst b/Documentation/accounting/index.rst
new file mode 100644
index 000000000000..e1f6284b5ff3
--- /dev/null
+++ b/Documentation/accounting/index.rst
@@ -0,0 +1,14 @@
+:orphan:
+
+==========
+Accounting
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   cgroupstats
+   delay-accounting
+   psi
+   taskstats
+   taskstats-struct
diff --git a/Documentation/accounting/psi.txt b/Documentation/accounting/psi.rst
similarity index 91%
rename from Documentation/accounting/psi.txt
rename to Documentation/accounting/psi.rst
index 5cbe5659e3b7..621111ce5740 100644
--- a/Documentation/accounting/psi.txt
+++ b/Documentation/accounting/psi.rst
@@ -35,14 +35,14 @@ Pressure interface
 Pressure information for each resource is exported through the
 respective file in /proc/pressure/ -- cpu, memory, and io.
 
-The format for CPU is as such:
+The format for CPU is as such::
 
-some avg10=0.00 avg60=0.00 avg300=0.00 total=0
+	some avg10=0.00 avg60=0.00 avg300=0.00 total=0
 
-and for memory and IO:
+and for memory and IO::
 
-some avg10=0.00 avg60=0.00 avg300=0.00 total=0
-full avg10=0.00 avg60=0.00 avg300=0.00 total=0
+	some avg10=0.00 avg60=0.00 avg300=0.00 total=0
+	full avg10=0.00 avg60=0.00 avg300=0.00 total=0
 
 The "some" line indicates the share of time in which at least some
 tasks are stalled on a given resource.
@@ -77,9 +77,9 @@ To register a trigger user has to open psi interface file under
 /proc/pressure/ representing the resource to be monitored and write the
 desired threshold and time window. The open file descriptor should be
 used to wait for trigger events using select(), poll() or epoll().
-The following format is used:
+The following format is used::
 
-<some|full> <stall amount in us> <time window in us>
+	<some|full> <stall amount in us> <time window in us>
 
 For example writing "some 150000 1000000" into /proc/pressure/memory
 would add 150ms threshold for partial memory stall measured within
@@ -115,18 +115,20 @@ trigger  is closed.
 Userspace monitor usage example
 ===============================
 
-#include <errno.h>
-#include <fcntl.h>
-#include <stdio.h>
-#include <poll.h>
-#include <string.h>
-#include <unistd.h>
+::
 
-/*
- * Monitor memory partial stall with 1s tracking window size
- * and 150ms threshold.
- */
-int main() {
+  #include <errno.h>
+  #include <fcntl.h>
+  #include <stdio.h>
+  #include <poll.h>
+  #include <string.h>
+  #include <unistd.h>
+
+  /*
+   * Monitor memory partial stall with 1s tracking window size
+   * and 150ms threshold.
+   */
+  int main() {
 	const char trig[] = "some 150000 1000000";
 	struct pollfd fds;
 	int n;
@@ -165,7 +167,7 @@ int main() {
 	}
 
 	return 0;
-}
+  }
 
 Cgroup2 interface
 =================
diff --git a/Documentation/accounting/taskstats-struct.txt b/Documentation/accounting/taskstats-struct.rst
similarity index 78%
rename from Documentation/accounting/taskstats-struct.txt
rename to Documentation/accounting/taskstats-struct.rst
index e7512c061c15..ca90fd489c9a 100644
--- a/Documentation/accounting/taskstats-struct.txt
+++ b/Documentation/accounting/taskstats-struct.rst
@@ -1,5 +1,6 @@
+====================
 The struct taskstats
---------------------
+====================
 
 This document contains an explanation of the struct taskstats fields.
 
@@ -10,16 +11,24 @@ There are three different groups of fields in the struct taskstats:
     the common fields and basic accounting fields are collected for
     delivery at do_exit() of a task.
 2) Delay accounting fields
-    These fields are placed between
-    /* Delay accounting fields start */
-    and
-    /* Delay accounting fields end */
+    These fields are placed between::
+
+	/* Delay accounting fields start */
+
+    and::
+
+	/* Delay accounting fields end */
+
     Their values are collected if CONFIG_TASK_DELAY_ACCT is set.
 3) Extended accounting fields
-    These fields are placed between
-    /* Extended accounting fields start */
-    and
-    /* Extended accounting fields end */
+    These fields are placed between::
+
+	/* Extended accounting fields start */
+
+    and::
+
+	/* Extended accounting fields end */
+
     Their values are collected if CONFIG_TASK_XACCT is set.
 
 4) Per-task and per-thread context switch count statistics
@@ -31,31 +40,33 @@ There are three different groups of fields in the struct taskstats:
 Future extension should add fields to the end of the taskstats struct, and
 should not change the relative position of each field within the struct.
 
+::
 
-struct taskstats {
+  struct taskstats {
+
+1) Common and basic accounting fields::
 
-1) Common and basic accounting fields:
 	/* The version number of this struct. This field is always set to
 	 * TAKSTATS_VERSION, which is defined in <linux/taskstats.h>.
 	 * Each time the struct is changed, the value should be incremented.
 	 */
 	__u16	version;
 
-  	/* The exit code of a task. */
+	/* The exit code of a task. */
 	__u32	ac_exitcode;		/* Exit status */
 
-  	/* The accounting flags of a task as defined in <linux/acct.h>
+	/* The accounting flags of a task as defined in <linux/acct.h>
 	 * Defined values are AFORK, ASU, ACOMPAT, ACORE, and AXSIG.
 	 */
 	__u8	ac_flag;		/* Record flags */
 
-  	/* The value of task_nice() of a task. */
+	/* The value of task_nice() of a task. */
 	__u8	ac_nice;		/* task_nice */
 
-  	/* The name of the command that started this task. */
+	/* The name of the command that started this task. */
 	char	ac_comm[TS_COMM_LEN];	/* Command name */
 
-  	/* The scheduling discipline as set in task->policy field. */
+	/* The scheduling discipline as set in task->policy field. */
 	__u8	ac_sched;		/* Scheduling discipline */
 
 	__u8	ac_pad[3];
@@ -64,26 +75,27 @@ struct taskstats {
 	__u32	ac_pid;			/* Process ID */
 	__u32	ac_ppid;		/* Parent process ID */
 
-  	/* The time when a task begins, in [secs] since 1970. */
+	/* The time when a task begins, in [secs] since 1970. */
 	__u32	ac_btime;		/* Begin time [sec since 1970] */
 
-  	/* The elapsed time of a task, in [usec]. */
+	/* The elapsed time of a task, in [usec]. */
 	__u64	ac_etime;		/* Elapsed time [usec] */
 
-  	/* The user CPU time of a task, in [usec]. */
+	/* The user CPU time of a task, in [usec]. */
 	__u64	ac_utime;		/* User CPU time [usec] */
 
-  	/* The system CPU time of a task, in [usec]. */
+	/* The system CPU time of a task, in [usec]. */
 	__u64	ac_stime;		/* System CPU time [usec] */
 
-  	/* The minor page fault count of a task, as set in task->min_flt. */
+	/* The minor page fault count of a task, as set in task->min_flt. */
 	__u64	ac_minflt;		/* Minor Page Fault Count */
 
 	/* The major page fault count of a task, as set in task->maj_flt. */
 	__u64	ac_majflt;		/* Major Page Fault Count */
 
 
-2) Delay accounting fields:
+2) Delay accounting fields::
+
 	/* Delay accounting fields start
 	 *
 	 * All values, until the comment "Delay accounting fields end" are
@@ -134,7 +146,8 @@ struct taskstats {
 	/* version 1 ends here */
 
 
-3) Extended accounting fields
+3) Extended accounting fields::
+
 	/* Extended accounting fields start */
 
 	/* Accumulated RSS usage in duration of a task, in MBytes-usecs.
@@ -145,15 +158,15 @@ struct taskstats {
 	 */
 	__u64	coremem;		/* accumulated RSS usage in MB-usec */
 
-  	/* Accumulated virtual memory usage in duration of a task.
+	/* Accumulated virtual memory usage in duration of a task.
 	 * Same as acct_rss_mem1 above except that we keep track of VM usage.
 	 */
 	__u64	virtmem;		/* accumulated VM usage in MB-usec */
 
-  	/* High watermark of RSS usage in duration of a task, in KBytes. */
+	/* High watermark of RSS usage in duration of a task, in KBytes. */
 	__u64	hiwater_rss;		/* High-watermark of RSS usage */
 
-  	/* High watermark of VM  usage in duration of a task, in KBytes. */
+	/* High watermark of VM  usage in duration of a task, in KBytes. */
 	__u64	hiwater_vm;		/* High-water virtual memory usage */
 
 	/* The following four fields are I/O statistics of a task. */
@@ -164,17 +177,23 @@ struct taskstats {
 
 	/* Extended accounting fields end */
 
-4) Per-task and per-thread statistics
+4) Per-task and per-thread statistics::
+
 	__u64	nvcsw;			/* Context voluntary switch counter */
 	__u64	nivcsw;			/* Context involuntary switch counter */
 
-5) Time accounting for SMT machines
+5) Time accounting for SMT machines::
+
 	__u64	ac_utimescaled;		/* utime scaled on frequency etc */
 	__u64	ac_stimescaled;		/* stime scaled on frequency etc */
 	__u64	cpu_scaled_run_real_total; /* scaled cpu_run_real_total */
 
-6) Extended delay accounting fields for memory reclaim
+6) Extended delay accounting fields for memory reclaim::
+
 	/* Delay waiting for memory reclaim */
 	__u64	freepages_count;
 	__u64	freepages_delay_total;
-}
+
+::
+
+  }
diff --git a/Documentation/accounting/taskstats.txt b/Documentation/accounting/taskstats.rst
similarity index 95%
rename from Documentation/accounting/taskstats.txt
rename to Documentation/accounting/taskstats.rst
index ff06b738bb88..2a28b7f55c10 100644
--- a/Documentation/accounting/taskstats.txt
+++ b/Documentation/accounting/taskstats.rst
@@ -1,5 +1,6 @@
+=============================
 Per-task statistics interface
------------------------------
+=============================
 
 
 Taskstats is a netlink-based interface for sending per-task and
@@ -65,7 +66,7 @@ taskstats.h file.
 
 The data exchanged between user and kernel space is a netlink message belonging
 to the NETLINK_GENERIC family and using the netlink attributes interface.
-The messages are in the format
+The messages are in the format::
 
     +----------+- - -+-------------+-------------------+
     | nlmsghdr | Pad |  genlmsghdr | taskstats payload |
@@ -167,15 +168,13 @@ extended and the number of cpus grows large.
 To avoid losing statistics, userspace should do one or more of the following:
 
 - increase the receive buffer sizes for the netlink sockets opened by
-listeners to receive exit data.
+  listeners to receive exit data.
 
 - create more listeners and reduce the number of cpus being listened to by
-each listener. In the extreme case, there could be one listener for each cpu.
-Users may also consider setting the cpu affinity of the listener to the subset
-of cpus to which it listens, especially if they are listening to just one cpu.
+  each listener. In the extreme case, there could be one listener for each cpu.
+  Users may also consider setting the cpu affinity of the listener to the subset
+  of cpus to which it listens, especially if they are listening to just one cpu.
 
 Despite these measures, if the userspace receives ENOBUFS error messages
 indicated overflow of receive buffers, it should take measures to handle the
 loss of data.
-
-----
diff --git a/Documentation/admin-guide/cgroup-v2.rst b/Documentation/admin-guide/cgroup-v2.rst
index 110c3d34df71..4b971a0bc99a 100644
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -1014,7 +1014,7 @@ All time durations are in microseconds.
 	A read-only nested-key file which exists on non-root cgroups.
 
 	Shows pressure stall information for CPU. See
-	Documentation/accounting/psi.txt for details.
+	Documentation/accounting/psi.rst for details.
 
 
 Memory
@@ -1361,7 +1361,7 @@ PAGE_SIZE multiple when read back.
 	A read-only nested-key file which exists on non-root cgroups.
 
 	Shows pressure stall information for memory. See
-	Documentation/accounting/psi.txt for details.
+	Documentation/accounting/psi.rst for details.
 
 
 Usage Guidelines
@@ -1504,7 +1504,7 @@ IO Interface Files
 	A read-only nested-key file which exists on non-root cgroups.
 
 	Shows pressure stall information for IO. See
-	Documentation/accounting/psi.txt for details.
+	Documentation/accounting/psi.rst for details.
 
 
 Writeback
diff --git a/init/Kconfig b/init/Kconfig
index 6db89d4155d8..1707cf0802a7 100644
--- a/init/Kconfig
+++ b/init/Kconfig
@@ -517,7 +517,7 @@ config PSI
 	  have cpu.pressure, memory.pressure, and io.pressure files,
 	  which aggregate pressure stalls for the grouped tasks only.
 
-	  For more details see Documentation/accounting/psi.txt.
+	  For more details see Documentation/accounting/psi.rst.
 
 	  Say N if unsure.
 
-- 
2.21.0

[PATCH v2 19/29] docs: ia64: convert to ReST

[Mauro Carvalho Chehab]

Rename the ia64 documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

There are two upper case file names. Rename them to
lower case, as we're working to avoid upper case file
names at Documentation.

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>
---
 .../ia64/{aliasing.txt => aliasing.rst}       |  73 ++--
 Documentation/ia64/{efirtc.txt => efirtc.rst} | 118 +++---
 .../ia64/{err_inject.txt => err_inject.rst}   | 349 +++++++++---------
 Documentation/ia64/{fsys.txt => fsys.rst}     | 127 ++++---
 Documentation/ia64/{README => ia64.rst}       |  26 +-
 Documentation/ia64/index.rst                  |  18 +
 .../ia64/{IRQ-redir.txt => irq-redir.rst}     |  31 +-
 Documentation/ia64/{mca.txt => mca.rst}       |  10 +-
 Documentation/ia64/{serial.txt => serial.rst} |  36 +-
 Documentation/ia64/xen.rst                    | 206 +++++++++++
 Documentation/ia64/xen.txt                    | 183 ---------
 MAINTAINERS                                   |   2 +-
 arch/ia64/kernel/efi.c                        |   2 +-
 arch/ia64/kernel/fsys.S                       |   2 +-
 arch/ia64/mm/ioremap.c                        |   2 +-
 arch/ia64/pci/pci.c                           |   2 +-
 16 files changed, 660 insertions(+), 527 deletions(-)
 rename Documentation/ia64/{aliasing.txt => aliasing.rst} (83%)
 rename Documentation/ia64/{efirtc.txt => efirtc.rst} (70%)
 rename Documentation/ia64/{err_inject.txt => err_inject.rst} (82%)
 rename Documentation/ia64/{fsys.txt => fsys.rst} (76%)
 rename Documentation/ia64/{README => ia64.rst} (61%)
 create mode 100644 Documentation/ia64/index.rst
 rename Documentation/ia64/{IRQ-redir.txt => irq-redir.rst} (86%)
 rename Documentation/ia64/{mca.txt => mca.rst} (96%)
 rename Documentation/ia64/{serial.txt => serial.rst} (87%)
 create mode 100644 Documentation/ia64/xen.rst
 delete mode 100644 Documentation/ia64/xen.txt

diff --git a/Documentation/ia64/aliasing.txt b/Documentation/ia64/aliasing.rst
similarity index 83%
rename from Documentation/ia64/aliasing.txt
rename to Documentation/ia64/aliasing.rst
index 5a4dea6abebd..a08b36aba015 100644
--- a/Documentation/ia64/aliasing.txt
+++ b/Documentation/ia64/aliasing.rst
@@ -1,20 +1,25 @@
-	         MEMORY ATTRIBUTE ALIASING ON IA-64
+==================================
+Memory Attribute Aliasing on IA-64
+==================================
 
-			   Bjorn Helgaas
-		       <bjorn.helgaas@hp.com>
-			    May 4, 2006
+Bjorn Helgaas <bjorn.helgaas@hp.com>
 
+May 4, 2006
 
-MEMORY ATTRIBUTES
+
+Memory Attributes
+=================
 
     Itanium supports several attributes for virtual memory references.
     The attribute is part of the virtual translation, i.e., it is
     contained in the TLB entry.  The ones of most interest to the Linux
     kernel are:
 
-	WB		Write-back (cacheable)
+	==		======================
+        WB		Write-back (cacheable)
 	UC		Uncacheable
 	WC		Write-coalescing
+	==		======================
 
     System memory typically uses the WB attribute.  The UC attribute is
     used for memory-mapped I/O devices.  The WC attribute is uncacheable
@@ -29,7 +34,8 @@ MEMORY ATTRIBUTES
     support either WB or UC access to main memory, while others support
     only WB access.
 
-MEMORY MAP
+Memory Map
+==========
 
     Platform firmware describes the physical memory map and the
     supported attributes for each region.  At boot-time, the kernel uses
@@ -55,7 +61,8 @@ MEMORY MAP
     The efi_memmap table is preserved unmodified because the original
     boot-time information is required for kexec.
 
-KERNEL IDENTITY MAPPINGS
+Kernel Identify Mappings
+========================
 
     Linux/ia64 identity mappings are done with large pages, currently
     either 16MB or 64MB, referred to as "granules."  Cacheable mappings
@@ -74,17 +81,20 @@ KERNEL IDENTITY MAPPINGS
     are only partially populated, or populated with a combination of UC
     and WB regions.
 
-USER MAPPINGS
+User Mappings
+=============
 
     User mappings are typically done with 16K or 64K pages.  The smaller
     page size allows more flexibility because only 16K or 64K has to be
     homogeneous with respect to memory attributes.
 
-POTENTIAL ATTRIBUTE ALIASING CASES
+Potential Attribute Aliasing Cases
+==================================
 
     There are several ways the kernel creates new mappings:
 
-    mmap of /dev/mem
+mmap of /dev/mem
+----------------
 
 	This uses remap_pfn_range(), which creates user mappings.  These
 	mappings may be either WB or UC.  If the region being mapped
@@ -98,7 +108,8 @@ POTENTIAL ATTRIBUTE ALIASING CASES
 	Since the EFI memory map does not describe MMIO on some
 	machines, this should use an uncacheable mapping as a fallback.
 
-    mmap of /sys/class/pci_bus/.../legacy_mem
+mmap of /sys/class/pci_bus/.../legacy_mem
+-----------------------------------------
 
 	This is very similar to mmap of /dev/mem, except that legacy_mem
 	only allows mmap of the one megabyte "legacy MMIO" area for a
@@ -112,9 +123,10 @@ POTENTIAL ATTRIBUTE ALIASING CASES
 
 	The /dev/mem mmap constraints apply.
 
-    mmap of /proc/bus/pci/.../??.?
+mmap of /proc/bus/pci/.../??.?
+------------------------------
 
-    	This is an MMIO mmap of PCI functions, which additionally may or
+	This is an MMIO mmap of PCI functions, which additionally may or
 	may not be requested as using the WC attribute.
 
 	If WC is requested, and the region in kern_memmap is either WC
@@ -124,7 +136,8 @@ POTENTIAL ATTRIBUTE ALIASING CASES
 	Otherwise, the user mapping must use the same attribute as the
 	kernel mapping.
 
-    read/write of /dev/mem
+read/write of /dev/mem
+----------------------
 
 	This uses copy_from_user(), which implicitly uses a kernel
 	identity mapping.  This is obviously safe for things in
@@ -138,7 +151,8 @@ POTENTIAL ATTRIBUTE ALIASING CASES
 	eight-byte accesses, and the copy_from_user() path doesn't allow
 	any control over the access size, so this would be dangerous.
 
-    ioremap()
+ioremap()
+---------
 
 	This returns a mapping for use inside the kernel.
 
@@ -155,9 +169,11 @@ POTENTIAL ATTRIBUTE ALIASING CASES
 
 	Failing all of the above, we have to fall back to a UC mapping.
 
-PAST PROBLEM CASES
+Past Problem Cases
+==================
 
-    mmap of various MMIO regions from /dev/mem by "X" on Intel platforms
+mmap of various MMIO regions from /dev/mem by "X" on Intel platforms
+--------------------------------------------------------------------
 
       The EFI memory map may not report these MMIO regions.
 
@@ -166,12 +182,16 @@ PAST PROBLEM CASES
       succeed.  It may create either WB or UC user mappings, depending
       on whether the region is in kern_memmap or the EFI memory map.
 
-    mmap of 0x0-0x9FFFF /dev/mem by "hwinfo" on HP sx1000 with VGA enabled
+mmap of 0x0-0x9FFFF /dev/mem by "hwinfo" on HP sx1000 with VGA enabled
+----------------------------------------------------------------------
 
       The EFI memory map reports the following attributes:
+
+        =============== ======= ==================
         0x00000-0x9FFFF WB only
         0xA0000-0xBFFFF UC only (VGA frame buffer)
         0xC0000-0xFFFFF WB only
+        =============== ======= ==================
 
       This mmap is done with user pages, not kernel identity mappings,
       so it is safe to use WB mappings.
@@ -182,7 +202,8 @@ PAST PROBLEM CASES
       never generate an uncacheable reference to the WB-only areas unless
       the driver explicitly touches them.
 
-    mmap of 0x0-0xFFFFF legacy_mem by "X"
+mmap of 0x0-0xFFFFF legacy_mem by "X"
+-------------------------------------
 
       If the EFI memory map reports that the entire range supports the
       same attributes, we can allow the mmap (and we will prefer WB if
@@ -197,15 +218,18 @@ PAST PROBLEM CASES
       that doesn't report the VGA frame buffer at all), we should fail the
       mmap and force the user to map just the specific region of interest.
 
-    mmap of 0xA0000-0xBFFFF legacy_mem by "X" on HP sx1000 with VGA disabled
+mmap of 0xA0000-0xBFFFF legacy_mem by "X" on HP sx1000 with VGA disabled
+------------------------------------------------------------------------
+
+      The EFI memory map reports the following attributes::
 
-      The EFI memory map reports the following attributes:
         0x00000-0xFFFFF WB only (no VGA MMIO hole)
 
       This is a special case of the previous case, and the mmap should
       fail for the same reason as above.
 
-    read of /sys/devices/.../rom
+read of /sys/devices/.../rom
+----------------------------
 
       For VGA devices, this may cause an ioremap() of 0xC0000.  This
       used to be done with a UC mapping, because the VGA frame buffer
@@ -215,7 +239,8 @@ PAST PROBLEM CASES
       We should use WB page table mappings to avoid covering the VGA
       frame buffer.
 
-NOTES
+Notes
+=====
 
     [1] SDM rev 2.2, vol 2, sec 4.4.1.
     [2] SDM rev 2.2, vol 2, sec 4.4.6.
diff --git a/Documentation/ia64/efirtc.txt b/Documentation/ia64/efirtc.rst
similarity index 70%
rename from Documentation/ia64/efirtc.txt
rename to Documentation/ia64/efirtc.rst
index 057e6bebda8f..2f7ff5026308 100644
--- a/Documentation/ia64/efirtc.txt
+++ b/Documentation/ia64/efirtc.rst
@@ -1,12 +1,16 @@
+==========================
 EFI Real Time Clock driver
--------------------------------
+==========================
+
 S. Eranian <eranian@hpl.hp.com>
+
 March 2000
 
-I/ Introduction
+1. Introduction
+===============
 
 This document describes the efirtc.c driver has provided for
-the IA-64 platform. 
+the IA-64 platform.
 
 The purpose of this driver is to supply an API for kernel and user applications
 to get access to the Time Service offered by EFI version 0.92.
@@ -16,112 +20,124 @@ SetTime(), GetWakeupTime(), SetWakeupTime() which are all supported by this
 driver. We describe those calls as well the design of the driver in the
 following sections.
 
-II/ Design Decisions
+2. Design Decisions
+===================
 
-The original ideas was to provide a very simple driver to get access to, 
-at first, the time of day service. This is required in order to access, in a 
-portable way, the CMOS clock. A program like /sbin/hwclock uses such a clock 
+The original ideas was to provide a very simple driver to get access to,
+at first, the time of day service. This is required in order to access, in a
+portable way, the CMOS clock. A program like /sbin/hwclock uses such a clock
 to initialize the system view of the time during boot.
 
 Because we wanted to minimize the impact on existing user-level apps using
 the CMOS clock, we decided to expose an API that was very similar to the one
-used today with the legacy RTC driver (driver/char/rtc.c). However, because 
+used today with the legacy RTC driver (driver/char/rtc.c). However, because
 EFI provides a simpler services, not all ioctl() are available. Also
-new ioctl()s have been introduced for things that EFI provides but not the 
+new ioctl()s have been introduced for things that EFI provides but not the
 legacy.
 
 EFI uses a slightly different way of representing the time, noticeably
 the reference date is different. Year is the using the full 4-digit format.
 The Epoch is January 1st 1998. For backward compatibility reasons we don't
-expose this new way of representing time. Instead we use something very 
+expose this new way of representing time. Instead we use something very
 similar to the struct tm, i.e. struct rtc_time, as used by hwclock.
 One of the reasons for doing it this way is to allow for EFI to still evolve
 without necessarily impacting any of the user applications. The decoupling
 enables flexibility and permits writing wrapper code is ncase things change.
 
 The driver exposes two interfaces, one via the device file and a set of
-ioctl()s. The other is read-only via the /proc filesystem. 
+ioctl()s. The other is read-only via the /proc filesystem.
 
 As of today we don't offer a /proc/sys interface.
 
 To allow for a uniform interface between the legacy RTC and EFI time service,
-we have created the include/linux/rtc.h header file to contain only the 
-"public" API of the two drivers.  The specifics of the legacy RTC are still 
+we have created the include/linux/rtc.h header file to contain only the
+"public" API of the two drivers.  The specifics of the legacy RTC are still
 in include/linux/mc146818rtc.h.
 
- 
-III/ Time of day service
+
+3. Time of day service
+======================
 
 The part of the driver gives access to the time of day service of EFI.
 Two ioctl()s, compatible with the legacy RTC calls:
 
-	Read the CMOS clock: ioctl(d, RTC_RD_TIME, &rtc);
+	Read the CMOS clock::
 
-	Write the CMOS clock: ioctl(d, RTC_SET_TIME, &rtc);
+		ioctl(d, RTC_RD_TIME, &rtc);
+
+	Write the CMOS clock::
+
+		ioctl(d, RTC_SET_TIME, &rtc);
 
 The rtc is a pointer to a data structure defined in rtc.h which is close
-to a struct tm:
+to a struct tm::
 
-struct rtc_time {
-        int tm_sec;
-        int tm_min;
-        int tm_hour;
-        int tm_mday;
-        int tm_mon;
-        int tm_year;
-        int tm_wday;
-        int tm_yday;
-        int tm_isdst;
-};
+  struct rtc_time {
+          int tm_sec;
+          int tm_min;
+          int tm_hour;
+          int tm_mday;
+          int tm_mon;
+          int tm_year;
+          int tm_wday;
+          int tm_yday;
+          int tm_isdst;
+  };
 
 The driver takes care of converting back an forth between the EFI time and
 this format.
 
 Those two ioctl()s can be exercised with the hwclock command:
 
-For reading:
-# /sbin/hwclock --show
-Mon Mar  6 15:32:32 2000  -0.910248 seconds
+For reading::
 
-For setting:
-# /sbin/hwclock --systohc
+	# /sbin/hwclock --show
+	Mon Mar  6 15:32:32 2000  -0.910248 seconds
+
+For setting::
+
+	# /sbin/hwclock --systohc
 
 Root privileges are required to be able to set the time of day.
 
-IV/ Wakeup Alarm service
+4. Wakeup Alarm service
+=======================
 
 EFI provides an API by which one can program when a machine should wakeup,
 i.e. reboot. This is very different from the alarm provided by the legacy
 RTC which is some kind of interval timer alarm. For this reason we don't use
 the same ioctl()s to get access to the service. Instead we have
-introduced 2 news ioctl()s to the interface of an RTC. 
+introduced 2 news ioctl()s to the interface of an RTC.
 
 We have added 2 new ioctl()s that are specific to the EFI driver:
 
-	Read the current state of the alarm
-	ioctl(d, RTC_WKLAM_RD, &wkt)
+	Read the current state of the alarm::
 
-	Set the alarm or change its status
-	ioctl(d, RTC_WKALM_SET, &wkt)
+		ioctl(d, RTC_WKLAM_RD, &wkt)
 
-The wkt structure encapsulates a struct rtc_time + 2 extra fields to get 
-status information:
-	
-struct rtc_wkalrm {
+	Set the alarm or change its status::
 
-        unsigned char enabled; /* =1 if alarm is enabled */
-        unsigned char pending; /* =1 if alarm is pending  */
+		ioctl(d, RTC_WKALM_SET, &wkt)
 
-        struct rtc_time time;
-} 
+The wkt structure encapsulates a struct rtc_time + 2 extra fields to get
+status information::
+
+  struct rtc_wkalrm {
+
+          unsigned char enabled; /* =1 if alarm is enabled */
+          unsigned char pending; /* =1 if alarm is pending  */
+
+          struct rtc_time time;
+  }
 
 As of today, none of the existing user-level apps supports this feature.
-However writing such a program should be hard by simply using those two 
-ioctl(). 
+However writing such a program should be hard by simply using those two
+ioctl().
 
 Root privileges are required to be able to set the alarm.
 
-V/ References.
+5. References
+=============
 
 Checkout the following Web site for more information on EFI:
 
diff --git a/Documentation/ia64/err_inject.txt b/Documentation/ia64/err_inject.rst
similarity index 82%
rename from Documentation/ia64/err_inject.txt
rename to Documentation/ia64/err_inject.rst
index 9f651c181429..900f71e93a29 100644
--- a/Documentation/ia64/err_inject.txt
+++ b/Documentation/ia64/err_inject.rst
@@ -1,4 +1,4 @@
-
+========================================
 IPF Machine Check (MC) error inject tool
 ========================================
 
@@ -32,94 +32,94 @@ Errata: Itanium 2 Processors Specification Update lists some errata against
 the pal_mc_error_inject PAL procedure. The following err.conf has been tested
 on latest Montecito PAL.
 
-err.conf:
+err.conf::
 
-#This is configuration file for err_inject_tool.
-#The format of the each line is:
-#cpu, loop, interval, err_type_info, err_struct_info, err_data_buffer
-#where
-#	cpu: logical cpu number the error will be inject in.
-#	loop: times the error will be injected.
-#	interval: In second. every so often one error is injected.
-#	err_type_info, err_struct_info: PAL parameters.
-#
-#Note: All values are hex w/o or w/ 0x prefix.
+  #This is configuration file for err_inject_tool.
+  #The format of the each line is:
+  #cpu, loop, interval, err_type_info, err_struct_info, err_data_buffer
+  #where
+  #	cpu: logical cpu number the error will be inject in.
+  #	loop: times the error will be injected.
+  #	interval: In second. every so often one error is injected.
+  #	err_type_info, err_struct_info: PAL parameters.
+  #
+  #Note: All values are hex w/o or w/ 0x prefix.
 
 
-#On cpu2, inject only total 0x10 errors, interval 5 seconds
-#corrected, data cache, hier-2, physical addr(assigned by tool code).
-#working on Montecito latest PAL.
-2, 10, 5, 4101, 95
+  #On cpu2, inject only total 0x10 errors, interval 5 seconds
+  #corrected, data cache, hier-2, physical addr(assigned by tool code).
+  #working on Montecito latest PAL.
+  2, 10, 5, 4101, 95
 
-#On cpu4, inject and consume total 0x10 errors, interval 5 seconds
-#corrected, data cache, hier-2, physical addr(assigned by tool code).
-#working on Montecito latest PAL.
-4, 10, 5, 4109, 95
+  #On cpu4, inject and consume total 0x10 errors, interval 5 seconds
+  #corrected, data cache, hier-2, physical addr(assigned by tool code).
+  #working on Montecito latest PAL.
+  4, 10, 5, 4109, 95
 
-#On cpu15, inject and consume total 0x10 errors, interval 5 seconds
-#recoverable, DTR0, hier-2.
-#working on Montecito latest PAL.
-0xf, 0x10, 5, 4249, 15
+  #On cpu15, inject and consume total 0x10 errors, interval 5 seconds
+  #recoverable, DTR0, hier-2.
+  #working on Montecito latest PAL.
+  0xf, 0x10, 5, 4249, 15
 
 The sample application source code:
 
-err_injection_tool.c:
+err_injection_tool.c::
 
-/*
- * 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
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or
- * NON INFRINGEMENT.  See the GNU General Public License for more
- * details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
- *
- * Copyright (C) 2006 Intel Co
- *	Fenghua Yu <fenghua.yu@intel.com>
- *
- */
-#include <sys/types.h>
-#include <sys/stat.h>
-#include <fcntl.h>
-#include <stdio.h>
-#include <sched.h>
-#include <unistd.h>
-#include <stdlib.h>
-#include <stdarg.h>
-#include <string.h>
-#include <errno.h>
-#include <time.h>
-#include <sys/ipc.h>
-#include <sys/sem.h>
-#include <sys/wait.h>
-#include <sys/mman.h>
-#include <sys/shm.h>
+  /*
+   * 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
+   * the Free Software Foundation; either version 2 of the License, or
+   * (at your option) any later version.
+   *
+   * This program is distributed in the hope that it will be useful, but
+   * WITHOUT ANY WARRANTY; without even the implied warranty of
+   * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, GOOD TITLE or
+   * NON INFRINGEMENT.  See the GNU General Public License for more
+   * details.
+   *
+   * You should have received a copy of the GNU General Public License
+   * along with this program; if not, write to the Free Software
+   * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
+   *
+   * Copyright (C) 2006 Intel Co
+   *	Fenghua Yu <fenghua.yu@intel.com>
+   *
+   */
+  #include <sys/types.h>
+  #include <sys/stat.h>
+  #include <fcntl.h>
+  #include <stdio.h>
+  #include <sched.h>
+  #include <unistd.h>
+  #include <stdlib.h>
+  #include <stdarg.h>
+  #include <string.h>
+  #include <errno.h>
+  #include <time.h>
+  #include <sys/ipc.h>
+  #include <sys/sem.h>
+  #include <sys/wait.h>
+  #include <sys/mman.h>
+  #include <sys/shm.h>
 
-#define MAX_FN_SIZE 		256
-#define MAX_BUF_SIZE 		256
-#define DATA_BUF_SIZE 		256
-#define NR_CPUS 		512
-#define MAX_TASK_NUM		2048
-#define MIN_INTERVAL		5	// seconds
-#define	ERR_DATA_BUFFER_SIZE 	3	// Three 8-byte.
-#define PARA_FIELD_NUM		5
-#define MASK_SIZE		(NR_CPUS/64)
-#define PATH_FORMAT "/sys/devices/system/cpu/cpu%d/err_inject/"
+  #define MAX_FN_SIZE 		256
+  #define MAX_BUF_SIZE 		256
+  #define DATA_BUF_SIZE 		256
+  #define NR_CPUS 		512
+  #define MAX_TASK_NUM		2048
+  #define MIN_INTERVAL		5	// seconds
+  #define	ERR_DATA_BUFFER_SIZE 	3	// Three 8-byte.
+  #define PARA_FIELD_NUM		5
+  #define MASK_SIZE		(NR_CPUS/64)
+  #define PATH_FORMAT "/sys/devices/system/cpu/cpu%d/err_inject/"
 
-int sched_setaffinity(pid_t pid, unsigned int len, unsigned long *mask);
+  int sched_setaffinity(pid_t pid, unsigned int len, unsigned long *mask);
 
-int verbose;
-#define vbprintf if (verbose) printf
+  int verbose;
+  #define vbprintf if (verbose) printf
 
-int log_info(int cpu, const char *fmt, ...)
-{
+  int log_info(int cpu, const char *fmt, ...)
+  {
 	FILE *log;
 	char fn[MAX_FN_SIZE];
 	char buf[MAX_BUF_SIZE];
@@ -142,12 +142,12 @@ int log_info(int cpu, const char *fmt, ...)
 	fclose(log);
 
 	return 0;
-}
+  }
 
-typedef unsigned long u64;
-typedef unsigned int  u32;
+  typedef unsigned long u64;
+  typedef unsigned int  u32;
 
-typedef union err_type_info_u {
+  typedef union err_type_info_u {
 	struct {
 		u64	mode		: 3,	/* 0-2 */
 			err_inj		: 3,	/* 3-5 */
@@ -157,9 +157,9 @@ typedef union err_type_info_u {
 			reserved	: 48;	/* 16-63 */
 	} err_type_info_u;
 	u64	err_type_info;
-} err_type_info_t;
+  } err_type_info_t;
 
-typedef union err_struct_info_u {
+  typedef union err_struct_info_u {
 	struct {
 		u64	siv		: 1,	/* 0	 */
 			c_t		: 2,	/* 1-2	 */
@@ -197,9 +197,9 @@ typedef union err_struct_info_u {
 		u64	reserved;
 	} err_struct_info_bus_processor_interconnect;
 	u64	err_struct_info;
-} err_struct_info_t;
+  } err_struct_info_t;
 
-typedef union err_data_buffer_u {
+  typedef union err_data_buffer_u {
 	struct {
 		u64	trigger_addr;		/* 0-63		*/
 		u64	inj_addr;		/* 64-127 	*/
@@ -221,9 +221,9 @@ typedef union err_data_buffer_u {
 		u64	reserved;		/* 0-63		*/
 	} err_data_buffer_bus_processor_interconnect;
 	u64 err_data_buffer[ERR_DATA_BUFFER_SIZE];
-} err_data_buffer_t;
+  } err_data_buffer_t;
 
-typedef union capabilities_u {
+  typedef union capabilities_u {
 	struct {
 		u64	i		: 1,
 			d		: 1,
@@ -276,9 +276,9 @@ typedef union capabilities_u {
 	struct {
 		u64	reserved;
 	} capabilities_bus_processor_interconnect;
-} capabilities_t;
+  } capabilities_t;
 
-typedef struct resources_s {
+  typedef struct resources_s {
 	u64	ibr0		: 1,
 		ibr2		: 1,
 		ibr4		: 1,
@@ -288,24 +288,24 @@ typedef struct resources_s {
 		dbr4		: 1,
 		dbr6		: 1,
 		reserved	: 48;
-} resources_t;
+  } resources_t;
 
 
-long get_page_size(void)
-{
+  long get_page_size(void)
+  {
 	long page_size=sysconf(_SC_PAGESIZE);
 	return page_size;
-}
+  }
 
-#define PAGE_SIZE (get_page_size()==-1?0x4000:get_page_size())
-#define SHM_SIZE (2*PAGE_SIZE*NR_CPUS)
-#define SHM_VA 0x2000000100000000
+  #define PAGE_SIZE (get_page_size()==-1?0x4000:get_page_size())
+  #define SHM_SIZE (2*PAGE_SIZE*NR_CPUS)
+  #define SHM_VA 0x2000000100000000
 
-int shmid;
-void *shmaddr;
+  int shmid;
+  void *shmaddr;
 
-int create_shm(void)
-{
+  int create_shm(void)
+  {
 	key_t key;
 	char fn[MAX_FN_SIZE];
 
@@ -343,34 +343,34 @@ int create_shm(void)
 	mlock(shmaddr, SHM_SIZE);
 
 	return 0;
-}
+  }
 
-int free_shm()
-{
+  int free_shm()
+  {
 	munlock(shmaddr, SHM_SIZE);
-        shmdt(shmaddr);
+          shmdt(shmaddr);
 	semctl(shmid, 0, IPC_RMID);
 
 	return 0;
-}
+  }
 
-#ifdef _SEM_SEMUN_UNDEFINED
-union semun
-{
+  #ifdef _SEM_SEMUN_UNDEFINED
+  union semun
+  {
 	int val;
 	struct semid_ds *buf;
 	unsigned short int *array;
 	struct seminfo *__buf;
-};
-#endif
+  };
+  #endif
 
-u32 mode=1; /* 1: physical mode; 2: virtual mode. */
-int one_lock=1;
-key_t key[NR_CPUS];
-int semid[NR_CPUS];
+  u32 mode=1; /* 1: physical mode; 2: virtual mode. */
+  int one_lock=1;
+  key_t key[NR_CPUS];
+  int semid[NR_CPUS];
 
-int create_sem(int cpu)
-{
+  int create_sem(int cpu)
+  {
 	union semun arg;
 	char fn[MAX_FN_SIZE];
 	int sid;
@@ -407,37 +407,37 @@ int create_sem(int cpu)
 	}
 
 	return 0;
-}
+  }
 
-static int lock(int cpu)
-{
+  static int lock(int cpu)
+  {
 	struct sembuf lock;
 
 	lock.sem_num = cpu;
 	lock.sem_op = 1;
 	semop(semid[cpu], &lock, 1);
 
-        return 0;
-}
+          return 0;
+  }
 
-static int unlock(int cpu)
-{
+  static int unlock(int cpu)
+  {
 	struct sembuf unlock;
 
 	unlock.sem_num = cpu;
 	unlock.sem_op = -1;
 	semop(semid[cpu], &unlock, 1);
 
-        return 0;
-}
+          return 0;
+  }
 
-void free_sem(int cpu)
-{
+  void free_sem(int cpu)
+  {
 	semctl(semid[cpu], 0, IPC_RMID);
-}
+  }
 
-int wr_multi(char *fn, unsigned long *data, int size)
-{
+  int wr_multi(char *fn, unsigned long *data, int size)
+  {
 	int fd;
 	char buf[MAX_BUF_SIZE];
 	int ret;
@@ -459,15 +459,15 @@ int wr_multi(char *fn, unsigned long *data, int size)
 	ret=write(fd, buf, sizeof(buf));
 	close(fd);
 	return ret;
-}
+  }
 
-int wr(char *fn, unsigned long data)
-{
+  int wr(char *fn, unsigned long data)
+  {
 	return wr_multi(fn, &data, 1);
-}
+  }
 
-int rd(char *fn, unsigned long *data)
-{
+  int rd(char *fn, unsigned long *data)
+  {
 	int fd;
 	char buf[MAX_BUF_SIZE];
 
@@ -480,10 +480,10 @@ int rd(char *fn, unsigned long *data)
 	*data=strtoul(buf, NULL, 16);
 	close(fd);
 	return 0;
-}
+  }
 
-int rd_status(char *path, int *status)
-{
+  int rd_status(char *path, int *status)
+  {
 	char fn[MAX_FN_SIZE];
 	sprintf(fn, "%s/status", path);
 	if (rd(fn, (u64*)status)<0) {
@@ -492,10 +492,10 @@ int rd_status(char *path, int *status)
 	}
 
 	return 0;
-}
+  }
 
-int rd_capabilities(char *path, u64 *capabilities)
-{
+  int rd_capabilities(char *path, u64 *capabilities)
+  {
 	char fn[MAX_FN_SIZE];
 	sprintf(fn, "%s/capabilities", path);
 	if (rd(fn, capabilities)<0) {
@@ -504,10 +504,10 @@ int rd_capabilities(char *path, u64 *capabilities)
 	}
 
 	return 0;
-}
+  }
 
-int rd_all(char *path)
-{
+  int rd_all(char *path)
+  {
 	unsigned long err_type_info, err_struct_info, err_data_buffer;
 	int status;
 	unsigned long capabilities, resources;
@@ -556,11 +556,11 @@ int rd_all(char *path)
 	printf("resources=%lx\n", resources);
 
 	return 0;
-}
+  }
 
-int query_capabilities(char *path, err_type_info_t err_type_info,
+  int query_capabilities(char *path, err_type_info_t err_type_info,
 			u64 *capabilities)
-{
+  {
 	char fn[MAX_FN_SIZE];
 	err_struct_info_t err_struct_info;
 	err_data_buffer_t err_data_buffer;
@@ -583,10 +583,10 @@ int query_capabilities(char *path, err_type_info_t err_type_info,
 		return -1;
 
 	return 0;
-}
+  }
 
-int query_all_capabilities()
-{
+  int query_all_capabilities()
+  {
 	int status;
 	err_type_info_t err_type_info;
 	int err_sev, err_struct, struct_hier;
@@ -629,12 +629,12 @@ int query_all_capabilities()
 	}
 
 	return 0;
-}
+  }
 
-int err_inject(int cpu, char *path, err_type_info_t err_type_info,
+  int err_inject(int cpu, char *path, err_type_info_t err_type_info,
 		err_struct_info_t err_struct_info,
 		err_data_buffer_t err_data_buffer)
-{
+  {
 	int status;
 	char fn[MAX_FN_SIZE];
 
@@ -667,13 +667,13 @@ int err_inject(int cpu, char *path, err_type_info_t err_type_info,
 	}
 
 	return status;
-}
+  }
 
-static int construct_data_buf(char *path, err_type_info_t err_type_info,
+  static int construct_data_buf(char *path, err_type_info_t err_type_info,
 		err_struct_info_t err_struct_info,
 		err_data_buffer_t *err_data_buffer,
 		void *va1)
-{
+  {
 	char fn[MAX_FN_SIZE];
 	u64 virt_addr=0, phys_addr=0;
 
@@ -710,22 +710,22 @@ static int construct_data_buf(char *path, err_type_info_t err_type_info,
 	}
 
 	return 0;
-}
+  }
 
-typedef struct {
+  typedef struct {
 	u64 cpu;
 	u64 loop;
 	u64 interval;
 	u64 err_type_info;
 	u64 err_struct_info;
 	u64 err_data_buffer[ERR_DATA_BUFFER_SIZE];
-} parameters_t;
+  } parameters_t;
 
-parameters_t line_para;
-int para;
+  parameters_t line_para;
+  int para;
 
-static int empty_data_buffer(u64 *err_data_buffer)
-{
+  static int empty_data_buffer(u64 *err_data_buffer)
+  {
 	int empty=1;
 	int i;
 
@@ -734,10 +734,10 @@ static int empty_data_buffer(u64 *err_data_buffer)
 		empty=0;
 
 	return empty;
-}
+  }
 
-int err_inj()
-{
+  int err_inj()
+  {
 	err_type_info_t err_type_info;
 	err_struct_info_t err_struct_info;
 	err_data_buffer_t err_data_buffer;
@@ -951,10 +951,10 @@ int err_inj()
 	printf("All done.\n");
 
 	return 0;
-}
+  }
 
-void help()
-{
+  void help()
+  {
 	printf("err_inject_tool:\n");
 	printf("\t-q: query all capabilities. default: off\n");
 	printf("\t-m: procedure mode. 1: physical 2: virtual. default: 1\n");
@@ -977,10 +977,10 @@ void help()
 	printf("The tool will take err.conf file as ");
 	printf("input to inject single or multiple errors ");
 	printf("on one or multiple cpus in parallel.\n");
-}
+  }
 
-int main(int argc, char **argv)
-{
+  int main(int argc, char **argv)
+  {
 	char c;
 	int do_err_inj=0;
 	int do_query_all=0;
@@ -1031,7 +1031,7 @@ int main(int argc, char **argv)
 				if (count!=PARA_FIELD_NUM+3) {
 				    line_para.err_data_buffer[0]=-1,
 				    line_para.err_data_buffer[1]=-1,
-			 	    line_para.err_data_buffer[2]=-1;
+				    line_para.err_data_buffer[2]=-1;
 				    count=sscanf(optarg, "%lx, %lx, %lx, %lx, %lx\n",
 						&line_para.cpu,
 						&line_para.loop,
@@ -1064,5 +1064,4 @@ int main(int argc, char **argv)
 		help();
 
 	return 0;
-}
-
+  }
diff --git a/Documentation/ia64/fsys.txt b/Documentation/ia64/fsys.rst
similarity index 76%
rename from Documentation/ia64/fsys.txt
rename to Documentation/ia64/fsys.rst
index 59dd689d9b86..a702d2cc94b6 100644
--- a/Documentation/ia64/fsys.txt
+++ b/Documentation/ia64/fsys.rst
@@ -1,9 +1,9 @@
--*-Mode: outline-*-
-
-		Light-weight System Calls for IA-64
-		-----------------------------------
+===================================
+Light-weight System Calls for IA-64
+===================================
 
 		        Started: 13-Jan-2003
+
 		    Last update: 27-Sep-2003
 
 	              David Mosberger-Tang
@@ -52,12 +52,13 @@ privilege level is at level 0, this means that fsys-mode requires some
 care (see below).
 
 
-* How to tell fsys-mode
+How to tell fsys-mode
+=====================
 
 Linux operates in fsys-mode when (a) the privilege level is 0 (most
 privileged) and (b) the stacks have NOT been switched to kernel memory
 yet.  For convenience, the header file <asm-ia64/ptrace.h> provides
-three macros:
+three macros::
 
 	user_mode(regs)
 	user_stack(task,regs)
@@ -70,11 +71,12 @@ to by "regs" was executing in user mode (privilege level 3).
 user_stack() returns TRUE if the state pointed to by "regs" was
 executing on the user-level stack(s).  Finally, fsys_mode() returns
 TRUE if the CPU state pointed to by "regs" was executing in fsys-mode.
-The fsys_mode() macro is equivalent to the expression:
+The fsys_mode() macro is equivalent to the expression::
 
 	!user_mode(regs) && user_stack(task,regs)
 
-* How to write an fsyscall handler
+How to write an fsyscall handler
+================================
 
 The file arch/ia64/kernel/fsys.S contains a table of fsyscall-handlers
 (fsyscall_table).  This table contains one entry for each system call.
@@ -87,66 +89,72 @@ of the getpid() system call.
 
 The entry and exit-state of an fsyscall handler is as follows:
 
-** Machine state on entry to fsyscall handler:
+Machine state on entry to fsyscall handler
+------------------------------------------
 
- - r10	  = 0
- - r11	  = saved ar.pfs (a user-level value)
- - r15	  = system call number
- - r16	  = "current" task pointer (in normal kernel-mode, this is in r13)
- - r32-r39 = system call arguments
- - b6	  = return address (a user-level value)
- - ar.pfs = previous frame-state (a user-level value)
- - PSR.be = cleared to zero (i.e., little-endian byte order is in effect)
- - all other registers may contain values passed in from user-mode
+  ========= ===============================================================
+  r10	    0
+  r11	    saved ar.pfs (a user-level value)
+  r15	    system call number
+  r16	    "current" task pointer (in normal kernel-mode, this is in r13)
+  r32-r39   system call arguments
+  b6	    return address (a user-level value)
+  ar.pfs    previous frame-state (a user-level value)
+  PSR.be    cleared to zero (i.e., little-endian byte order is in effect)
+  -         all other registers may contain values passed in from user-mode
+  ========= ===============================================================
 
-** Required machine state on exit to fsyscall handler:
+Required machine state on exit to fsyscall handler
+--------------------------------------------------
 
- - r11	  = saved ar.pfs (as passed into the fsyscall handler)
- - r15	  = system call number (as passed into the fsyscall handler)
- - r32-r39 = system call arguments (as passed into the fsyscall handler)
- - b6	  = return address (as passed into the fsyscall handler)
- - ar.pfs = previous frame-state (as passed into the fsyscall handler)
+  ========= ===========================================================
+  r11	    saved ar.pfs (as passed into the fsyscall handler)
+  r15	    system call number (as passed into the fsyscall handler)
+  r32-r39   system call arguments (as passed into the fsyscall handler)
+  b6	    return address (as passed into the fsyscall handler)
+  ar.pfs    previous frame-state (as passed into the fsyscall handler)
+  ========= ===========================================================
 
 Fsyscall handlers can execute with very little overhead, but with that
 speed comes a set of restrictions:
 
- o Fsyscall-handlers MUST check for any pending work in the flags
+ * Fsyscall-handlers MUST check for any pending work in the flags
    member of the thread-info structure and if any of the
    TIF_ALLWORK_MASK flags are set, the handler needs to fall back on
    doing a full system call (by calling fsys_fallback_syscall).
 
- o Fsyscall-handlers MUST preserve incoming arguments (r32-r39, r11,
+ * Fsyscall-handlers MUST preserve incoming arguments (r32-r39, r11,
    r15, b6, and ar.pfs) because they will be needed in case of a
    system call restart.  Of course, all "preserved" registers also
    must be preserved, in accordance to the normal calling conventions.
 
- o Fsyscall-handlers MUST check argument registers for containing a
+ * Fsyscall-handlers MUST check argument registers for containing a
    NaT value before using them in any way that could trigger a
    NaT-consumption fault.  If a system call argument is found to
    contain a NaT value, an fsyscall-handler may return immediately
    with r8=EINVAL, r10=-1.
 
- o Fsyscall-handlers MUST NOT use the "alloc" instruction or perform
+ * Fsyscall-handlers MUST NOT use the "alloc" instruction or perform
    any other operation that would trigger mandatory RSE
    (register-stack engine) traffic.
 
- o Fsyscall-handlers MUST NOT write to any stacked registers because
+ * Fsyscall-handlers MUST NOT write to any stacked registers because
    it is not safe to assume that user-level called a handler with the
    proper number of arguments.
 
- o Fsyscall-handlers need to be careful when accessing per-CPU variables:
+ * Fsyscall-handlers need to be careful when accessing per-CPU variables:
    unless proper safe-guards are taken (e.g., interruptions are avoided),
    execution may be pre-empted and resumed on another CPU at any given
    time.
 
- o Fsyscall-handlers must be careful not to leak sensitive kernel'
+ * Fsyscall-handlers must be careful not to leak sensitive kernel'
    information back to user-level.  In particular, before returning to
    user-level, care needs to be taken to clear any scratch registers
    that could contain sensitive information (note that the current
    task pointer is not considered sensitive: it's already exposed
    through ar.k6).
 
- o Fsyscall-handlers MUST NOT access user-memory without first
+ * Fsyscall-handlers MUST NOT access user-memory without first
    validating access-permission (this can be done typically via
    probe.r.fault and/or probe.w.fault) and without guarding against
    memory access exceptions (this can be done with the EX() macros
@@ -162,7 +170,8 @@ fast system call execution (while fully preserving system call
 semantics), but there is also a lot of flexibility in handling more
 complicated cases.
 
-* Signal handling
+Signal handling
+===============
 
 The delivery of (asynchronous) signals must be delayed until fsys-mode
 is exited.  This is accomplished with the help of the lower-privilege
@@ -173,7 +182,8 @@ PSR.lp and returns immediately.  When fsys-mode is exited via the
 occur.  The trap handler clears PSR.lp again and returns immediately.
 The kernel exit path then checks for and delivers any pending signals.
 
-* PSR Handling
+PSR Handling
+============
 
 The "epc" instruction doesn't change the contents of PSR at all.  This
 is in contrast to a regular interruption, which clears almost all
@@ -181,6 +191,7 @@ bits.  Because of that, some care needs to be taken to ensure things
 work as expected.  The following discussion describes how each PSR bit
 is handled.
 
+======= =======================================================================
 PSR.be	Cleared when entering fsys-mode.  A srlz.d instruction is used
 	to ensure the CPU is in little-endian mode before the first
 	load/store instruction is executed.  PSR.be is normally NOT
@@ -202,7 +213,8 @@ PSR.pp	Unchanged.
 PSR.di	Unchanged.
 PSR.si	Unchanged.
 PSR.db	Unchanged.  The kernel prevents user-level from setting a hardware
-	breakpoint that triggers at any privilege level other than 3 (user-mode).
+	breakpoint that triggers at any privilege level other than
+	3 (user-mode).
 PSR.lp	Unchanged.
 PSR.tb	Lazy redirect.  If a taken-branch trap occurs while in
 	fsys-mode, the trap-handler modifies the saved machine state
@@ -235,47 +247,52 @@ PSR.ed	Unchanged.  Note: This bit could only have an effect if an fsys-mode
 PSR.bn	Unchanged.  Note: fsys-mode handlers may clear the bit, if needed.
 	Doing so requires clearing PSR.i and PSR.ic as well.
 PSR.ia	Unchanged.  Note: the ia64 linux kernel never sets this bit.
+======= =======================================================================
 
-* Using fast system calls
+Using fast system calls
+=======================
 
 To use fast system calls, userspace applications need simply call
 __kernel_syscall_via_epc().  For example
 
 -- example fgettimeofday() call --
+
 -- fgettimeofday.S --
 
-#include <asm/asmmacro.h>
+::
 
-GLOBAL_ENTRY(fgettimeofday)
-.prologue
-.save ar.pfs, r11
-mov r11 = ar.pfs
-.body 
+  #include <asm/asmmacro.h>
 
-mov r2 = 0xa000000000020660;;  // gate address 
-			       // found by inspection of System.map for the 
+  GLOBAL_ENTRY(fgettimeofday)
+  .prologue
+  .save ar.pfs, r11
+  mov r11 = ar.pfs
+  .body
+
+  mov r2 = 0xa000000000020660;;  // gate address
+			       // found by inspection of System.map for the
 			       // __kernel_syscall_via_epc() function.  See
 			       // below for how to do this for real.
 
-mov b7 = r2
-mov r15 = 1087		       // gettimeofday syscall
-;;
-br.call.sptk.many b6 = b7
-;;
+  mov b7 = r2
+  mov r15 = 1087		       // gettimeofday syscall
+  ;;
+  br.call.sptk.many b6 = b7
+  ;;
 
-.restore sp
+  .restore sp
 
-mov ar.pfs = r11
-br.ret.sptk.many rp;;	      // return to caller
-END(fgettimeofday)
+  mov ar.pfs = r11
+  br.ret.sptk.many rp;;	      // return to caller
+  END(fgettimeofday)
 
 -- end fgettimeofday.S --
 
 In reality, getting the gate address is accomplished by two extra
 values passed via the ELF auxiliary vector (include/asm-ia64/elf.h)
 
- o AT_SYSINFO : is the address of __kernel_syscall_via_epc()
- o AT_SYSINFO_EHDR : is the address of the kernel gate ELF DSO
+ * AT_SYSINFO : is the address of __kernel_syscall_via_epc()
+ * AT_SYSINFO_EHDR : is the address of the kernel gate ELF DSO
 
 The ELF DSO is a pre-linked library that is mapped in by the kernel at
 the gate page.  It is a proper ELF shared object so, with a dynamic
diff --git a/Documentation/ia64/README b/Documentation/ia64/ia64.rst
similarity index 61%
rename from Documentation/ia64/README
rename to Documentation/ia64/ia64.rst
index aa17f2154cba..b725019a9492 100644
--- a/Documentation/ia64/README
+++ b/Documentation/ia64/ia64.rst
@@ -1,43 +1,49 @@
-        Linux kernel release 2.4.xx for the IA-64 Platform
+===========================================
+Linux kernel release for the IA-64 Platform
+===========================================
 
-   These are the release notes for Linux version 2.4 for IA-64
+   These are the release notes for Linux since version 2.4 for IA-64
    platform.  This document provides information specific to IA-64
    ONLY, to get additional information about the Linux kernel also
    read the original Linux README provided with the kernel.
 
-INSTALLING the kernel:
+Installing the Kernel
+=====================
 
  - IA-64 kernel installation is the same as the other platforms, see
    original README for details.
 
 
-SOFTWARE REQUIREMENTS
+Software Requirements
+=====================
 
    Compiling and running this kernel requires an IA-64 compliant GCC
    compiler.  And various software packages also compiled with an
    IA-64 compliant GCC compiler.
 
 
-CONFIGURING the kernel:
+Configuring the Kernel
+======================
 
    Configuration is the same, see original README for details.
 
 
-COMPILING the kernel:
+Compiling the Kernel:
 
  - Compiling this kernel doesn't differ from other platform so read
    the original README for details BUT make sure you have an IA-64
    compliant GCC compiler.
 
-IA-64 SPECIFICS
+IA-64 Specifics
+===============
 
  - General issues:
 
-    o Hardly any performance tuning has been done. Obvious targets
+    * Hardly any performance tuning has been done. Obvious targets
       include the library routines (IP checksum, etc.). Less
       obvious targets include making sure we don't flush the TLB
       needlessly, etc.
 
-    o SMP locks cleanup/optimization
+    * SMP locks cleanup/optimization
 
-    o IA32 support.  Currently experimental.  It mostly works.
+    * IA32 support.  Currently experimental.  It mostly works.
diff --git a/Documentation/ia64/index.rst b/Documentation/ia64/index.rst
new file mode 100644
index 000000000000..a3e3052ad6e2
--- /dev/null
+++ b/Documentation/ia64/index.rst
@@ -0,0 +1,18 @@
+:orphan:
+
+==================
+IA-64 Architecture
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   ia64
+   aliasing
+   efirtc
+   err_inject
+   fsys
+   irq-redir
+   mca
+   serial
+   xen
diff --git a/Documentation/ia64/IRQ-redir.txt b/Documentation/ia64/irq-redir.rst
similarity index 86%
rename from Documentation/ia64/IRQ-redir.txt
rename to Documentation/ia64/irq-redir.rst
index f7bd72261283..39bf94484a15 100644
--- a/Documentation/ia64/IRQ-redir.txt
+++ b/Documentation/ia64/irq-redir.rst
@@ -1,6 +1,8 @@
+==============================
 IRQ affinity on IA64 platforms
-------------------------------
-                           07.01.2002, Erich Focht <efocht@ess.nec.de>
+==============================
+
+07.01.2002, Erich Focht <efocht@ess.nec.de>
 
 
 By writing to /proc/irq/IRQ#/smp_affinity the interrupt routing can be
@@ -12,22 +14,27 @@ IRQ target is one particular CPU and cannot be a mask of several
 CPUs. Only the first non-zero bit is taken into account.
 
 
-Usage examples:
+Usage examples
+==============
 
 The target CPU has to be specified as a hexadecimal CPU mask. The
 first non-zero bit is the selected CPU. This format has been kept for
 compatibility reasons with i386.
 
 Set the delivery mode of interrupt 41 to fixed and route the
-interrupts to CPU #3 (logical CPU number) (2^3=0x08):
+interrupts to CPU #3 (logical CPU number) (2^3=0x08)::
+
      echo "8" >/proc/irq/41/smp_affinity
 
 Set the default route for IRQ number 41 to CPU 6 in lowest priority
-delivery mode (redirectable):
+delivery mode (redirectable)::
+
      echo "r 40" >/proc/irq/41/smp_affinity
 
-The output of the command
+The output of the command::
+
      cat /proc/irq/IRQ#/smp_affinity
+
 gives the target CPU mask for the specified interrupt vector. If the CPU
 mask is preceded by the character "r", the interrupt is redirectable
 (i.e. lowest priority mode routing is used), otherwise its route is
@@ -35,7 +42,8 @@ fixed.
 
 
 
-Initialization and default behavior:
+Initialization and default behavior
+===================================
 
 If the platform features IRQ redirection (info provided by SAL) all
 IO-SAPIC interrupts are initialized with CPU#0 as their default target
@@ -43,9 +51,11 @@ and the routing is the so called "lowest priority mode" (actually
 fixed SAPIC mode with hint). The XTP chipset registers are used as hints
 for the IRQ routing. Currently in Linux XTP registers can have three
 values:
+
 	- minimal for an idle task,
 	- normal if any other task runs,
 	- maximal if the CPU is going to be switched off.
+
 The IRQ is routed to the CPU with lowest XTP register value, the
 search begins at the default CPU. Therefore most of the interrupts
 will be handled by CPU #0.
@@ -53,12 +63,14 @@ will be handled by CPU #0.
 If the platform doesn't feature interrupt redirection IOSAPIC fixed
 routing is used. The target CPUs are distributed in a round robin
 manner. IRQs will be routed only to the selected target CPUs. Check
-with
+with::
+
         cat /proc/interrupts
 
 
 
-Comments:
+Comments
+========
 
 On large (multi-node) systems it is recommended to route the IRQs to
 the node to which the corresponding device is connected.
@@ -66,4 +78,3 @@ For systems like the NEC AzusA we get IRQ node-affinity for free. This
 is because usually the chipsets on each node redirect the interrupts
 only to their own CPUs (as they cannot see the XTP registers on the
 other nodes).
-
diff --git a/Documentation/ia64/mca.txt b/Documentation/ia64/mca.rst
similarity index 96%
rename from Documentation/ia64/mca.txt
rename to Documentation/ia64/mca.rst
index f097c60cba1b..08270bba44a4 100644
--- a/Documentation/ia64/mca.txt
+++ b/Documentation/ia64/mca.rst
@@ -1,5 +1,8 @@
-An ad-hoc collection of notes on IA64 MCA and INIT processing.  Feel
-free to update it with notes about any area that is not clear.
+=============================================================
+An ad-hoc collection of notes on IA64 MCA and INIT processing
+=============================================================
+
+Feel free to update it with notes about any area that is not clear.
 
 ---
 
@@ -82,7 +85,8 @@ if we have a choice here.
   own stack as running on that cpu.  Then a recursive error gets a
   trace of the failing handler's "task".
 
-[1] My (Keith Owens) original design called for ia64 to separate its
+[1]
+    My (Keith Owens) original design called for ia64 to separate its
     struct task and the kernel stacks.  Then the MCA/INIT data would be
     chained stacks like i386 interrupt stacks.  But that required
     radical surgery on the rest of ia64, plus extra hard wired TLB
diff --git a/Documentation/ia64/serial.txt b/Documentation/ia64/serial.rst
similarity index 87%
rename from Documentation/ia64/serial.txt
rename to Documentation/ia64/serial.rst
index a63d2c54329b..1de70c305a79 100644
--- a/Documentation/ia64/serial.txt
+++ b/Documentation/ia64/serial.rst
@@ -1,4 +1,9 @@
-SERIAL DEVICE NAMING
+==============
+Serial Devices
+==============
+
+Serial Device Naming
+====================
 
     As of 2.6.10, serial devices on ia64 are named based on the
     order of ACPI and PCI enumeration.  The first device in the
@@ -30,17 +35,21 @@ SERIAL DEVICE NAMING
     (described in the ACPI namespace) plus an MP[2] (a PCI device) has
     these ports:
 
-                                  pre-2.6.10      pre-2.6.10
-                    MMIO         (EFI console    (EFI console
-                   address        on builtin)     on MP port)    2.6.10
-                  ==========      ==========      ==========     ======
+      ==========  ==========     ============    ============   =======
+      Type        MMIO           pre-2.6.10      pre-2.6.10     2.6.10+
+		  address
+				 (EFI console    (EFI console
+                                 on builtin)     on MP port)
+      ==========  ==========     ============    ============   =======
       builtin     0xff5e0000        ttyS0           ttyS1         ttyS0
       MP UPS      0xf8031000        ttyS1           ttyS2         ttyS1
       MP Console  0xf8030000        ttyS2           ttyS0         ttyS2
       MP 2        0xf8030010        ttyS3           ttyS3         ttyS3
       MP 3        0xf8030038        ttyS4           ttyS4         ttyS4
+      ==========  ==========     ============    ============   =======
 
-CONSOLE SELECTION
+Console Selection
+=================
 
     EFI knows what your console devices are, but it doesn't tell the
     kernel quite enough to actually locate them.  The DIG64 HCDP
@@ -67,7 +76,8 @@ CONSOLE SELECTION
     entries in /etc/inittab (for getty) and /etc/securetty (to allow
     root login).
 
-EARLY SERIAL CONSOLE
+Early Serial Console
+====================
 
     The kernel can't start using a serial console until it knows where
     the device lives.  Normally this happens when the driver enumerates
@@ -80,7 +90,8 @@ EARLY SERIAL CONSOLE
     or if the EFI console path contains only a UART device and the
     firmware supplies an HCDP.
 
-TROUBLESHOOTING SERIAL CONSOLE PROBLEMS
+Troubleshooting Serial Console Problems
+=======================================
 
     No kernel output after elilo prints "Uncompressing Linux... done":
 
@@ -133,19 +144,22 @@ TROUBLESHOOTING SERIAL CONSOLE PROBLEMS
 
 
 
-[1] http://www.dig64.org/specifications/agreement 
+[1]
+    http://www.dig64.org/specifications/agreement
     The table was originally defined as the "HCDP" for "Headless
     Console/Debug Port."  The current version is the "PCDP" for
     "Primary Console and Debug Port Devices."
 
-[2] The HP MP (management processor) is a PCI device that provides
+[2]
+    The HP MP (management processor) is a PCI device that provides
     several UARTs.  One of the UARTs is often used as a console; the
     EFI Boot Manager identifies it as "Acpi(HWP0002,700)/Pci(...)/Uart".
     The external connection is usually a 25-pin connector, and a
     special dongle converts that to three 9-pin connectors, one of
     which is labelled "Console."
 
-[3] EFI console devices are configured using the EFI Boot Manager
+[3]
+    EFI console devices are configured using the EFI Boot Manager
     "Boot option maintenance" menu.  You may have to interrupt the
     boot sequence to use this menu, and you will have to reset the
     box after changing console configuration.
diff --git a/Documentation/ia64/xen.rst b/Documentation/ia64/xen.rst
new file mode 100644
index 000000000000..831339c74441
--- /dev/null
+++ b/Documentation/ia64/xen.rst
@@ -0,0 +1,206 @@
+********************************************************
+Recipe for getting/building/running Xen/ia64 with pv_ops
+********************************************************
+This recipe describes how to get xen-ia64 source and build it,
+and run domU with pv_ops.
+
+Requirements
+============
+
+  - python
+  - mercurial
+    it (aka "hg") is an open-source source code
+    management software. See the below.
+    http://www.selenic.com/mercurial/wiki/
+  - git
+  - bridge-utils
+
+Getting and Building Xen and Dom0
+=================================
+
+  My environment is:
+
+    - Machine  : Tiger4
+    - Domain0 OS  : RHEL5
+    - DomainU OS  : RHEL5
+
+ 1. Download source::
+
+	# hg clone http://xenbits.xensource.com/ext/ia64/xen-unstable.hg
+	# cd xen-unstable.hg
+	# hg clone http://xenbits.xensource.com/ext/ia64/linux-2.6.18-xen.hg
+
+ 2. # make world
+
+ 3. # make install-tools
+
+ 4. copy kernels and xen::
+
+	# cp xen/xen.gz /boot/efi/efi/redhat/
+	# cp build-linux-2.6.18-xen_ia64/vmlinux.gz \
+	/boot/efi/efi/redhat/vmlinuz-2.6.18.8-xen
+
+ 5. make initrd for Dom0/DomU::
+
+	# make -C linux-2.6.18-xen.hg ARCH=ia64 modules_install \
+          O=$(pwd)/build-linux-2.6.18-xen_ia64
+	# mkinitrd -f /boot/efi/efi/redhat/initrd-2.6.18.8-xen.img \
+	  2.6.18.8-xen --builtin mptspi --builtin mptbase \
+	  --builtin mptscsih --builtin uhci-hcd --builtin ohci-hcd \
+	  --builtin ehci-hcd
+
+Making a disk image for guest OS
+================================
+
+ 1. make file::
+
+      # dd if=/dev/zero of=/root/rhel5.img bs=1M seek=4096 count=0
+      # mke2fs -F -j /root/rhel5.img
+      # mount -o loop /root/rhel5.img /mnt
+      # cp -ax /{dev,var,etc,usr,bin,sbin,lib} /mnt
+      # mkdir /mnt/{root,proc,sys,home,tmp}
+
+      Note: You may miss some device files. If so, please create them
+      with mknod. Or you can use tar instead of cp.
+
+ 2. modify DomU's fstab::
+
+      # vi /mnt/etc/fstab
+         /dev/xvda1  /            ext3    defaults        1 1
+         none        /dev/pts     devpts  gid=5,mode=620  0 0
+         none        /dev/shm     tmpfs   defaults        0 0
+         none        /proc        proc    defaults        0 0
+         none        /sys         sysfs   defaults        0 0
+
+ 3. modify inittab
+
+    set runlevel to 3 to avoid X trying to start::
+
+      # vi /mnt/etc/inittab
+         id:3:initdefault:
+
+    Start a getty on the hvc0 console::
+
+       X0:2345:respawn:/sbin/mingetty hvc0
+
+    tty1-6 mingetty can be commented out
+
+ 4. add hvc0 into /etc/securetty::
+
+      # vi /mnt/etc/securetty (add hvc0)
+
+ 5. umount::
+
+      # umount /mnt
+
+FYI, virt-manager can also make a disk image for guest OS.
+It's GUI tools and easy to make it.
+
+Boot Xen & Domain0
+==================
+
+ 1. replace elilo
+    elilo of RHEL5 can boot Xen and Dom0.
+    If you use old elilo (e.g RHEL4), please download from the below
+    http://elilo.sourceforge.net/cgi-bin/blosxom
+    and copy into /boot/efi/efi/redhat/::
+
+      # cp elilo-3.6-ia64.efi /boot/efi/efi/redhat/elilo.efi
+
+ 2. modify elilo.conf (like the below)::
+
+      # vi /boot/efi/efi/redhat/elilo.conf
+      prompt
+      timeout=20
+      default=xen
+      relocatable
+
+      image=vmlinuz-2.6.18.8-xen
+             label=xen
+             vmm=xen.gz
+             initrd=initrd-2.6.18.8-xen.img
+             read-only
+             append=" -- rhgb root=/dev/sda2"
+
+The append options before "--" are for xen hypervisor,
+the options after "--" are for dom0.
+
+FYI, your machine may need console options like
+"com1=19200,8n1 console=vga,com1". For example,
+append="com1=19200,8n1 console=vga,com1 -- rhgb console=tty0 \
+console=ttyS0 root=/dev/sda2"
+
+Getting and Building domU with pv_ops
+=====================================
+
+ 1. get pv_ops tree::
+
+      # git clone http://people.valinux.co.jp/~yamahata/xen-ia64/linux-2.6-xen-ia64.git/
+
+ 2. git branch (if necessary)::
+
+      # cd linux-2.6-xen-ia64/
+      # git checkout -b your_branch origin/xen-ia64-domu-minimal-2008may19
+
+   Note:
+     The current branch is xen-ia64-domu-minimal-2008may19.
+     But you would find the new branch. You can see with
+     "git branch -r" to get the branch lists.
+
+       http://people.valinux.co.jp/~yamahata/xen-ia64/for_eagl/linux-2.6-ia64-pv-ops.git/
+
+     is also available.
+
+     The tree is based on
+
+      git://git.kernel.org/pub/scm/linux/kernel/git/aegl/linux-2.6 test)
+
+ 3. copy .config for pv_ops of domU::
+
+      # cp arch/ia64/configs/xen_domu_wip_defconfig .config
+
+ 4. make kernel with pv_ops::
+
+      # make oldconfig
+      # make
+
+ 5. install the kernel and initrd::
+
+      # cp vmlinux.gz /boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU
+      # make modules_install
+      # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img \
+        2.6.26-rc3xen-ia64-08941-g1b12161 --builtin mptspi \
+        --builtin mptbase --builtin mptscsih --builtin uhci-hcd \
+        --builtin ohci-hcd --builtin ehci-hcd
+
+Boot DomainU with pv_ops
+========================
+
+ 1. make config of DomU::
+
+     # vi /etc/xen/rhel5
+       kernel = "/boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU"
+       ramdisk = "/boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img"
+       vcpus = 1
+       memory = 512
+       name = "rhel5"
+       disk = [ 'file:/root/rhel5.img,xvda1,w' ]
+       root = "/dev/xvda1 ro"
+       extra= "rhgb console=hvc0"
+
+ 2. After boot xen and dom0, start xend::
+
+	# /etc/init.d/xend start
+
+   ( In the debugging case, `# XEND_DEBUG=1 xend trace_start` )
+
+ 3. start domU::
+
+	# xm create -c rhel5
+
+Reference
+=========
+- Wiki of Xen/IA64 upstream merge
+  http://wiki.xensource.com/xenwiki/XenIA64/UpstreamMerge
+
+Written by Akio Takebe <takebe_akio@jp.fujitsu.com> on 28 May 2008
diff --git a/Documentation/ia64/xen.txt b/Documentation/ia64/xen.txt
deleted file mode 100644
index a12c74ce2773..000000000000
--- a/Documentation/ia64/xen.txt
+++ /dev/null
@@ -1,183 +0,0 @@
-       Recipe for getting/building/running Xen/ia64 with pv_ops
-       --------------------------------------------------------
-
-This recipe describes how to get xen-ia64 source and build it,
-and run domU with pv_ops.
-
-============
-Requirements
-============
-
-  - python
-  - mercurial
-    it (aka "hg") is an open-source source code
-    management software. See the below.
-    http://www.selenic.com/mercurial/wiki/
-  - git
-  - bridge-utils
-
-=================================
-Getting and Building Xen and Dom0
-=================================
-
-  My environment is;
-    Machine  : Tiger4
-    Domain0 OS  : RHEL5
-    DomainU OS  : RHEL5
-
- 1. Download source
-    # hg clone http://xenbits.xensource.com/ext/ia64/xen-unstable.hg
-    # cd xen-unstable.hg
-    # hg clone http://xenbits.xensource.com/ext/ia64/linux-2.6.18-xen.hg
-
- 2. # make world
-
- 3. # make install-tools
-
- 4. copy kernels and xen
-    # cp xen/xen.gz /boot/efi/efi/redhat/
-    # cp build-linux-2.6.18-xen_ia64/vmlinux.gz \
-      /boot/efi/efi/redhat/vmlinuz-2.6.18.8-xen
-
- 5. make initrd for Dom0/DomU
-    # make -C linux-2.6.18-xen.hg ARCH=ia64 modules_install \
-      O=$(pwd)/build-linux-2.6.18-xen_ia64
-    # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6.18.8-xen.img \
-      2.6.18.8-xen --builtin mptspi --builtin mptbase \
-      --builtin mptscsih --builtin uhci-hcd --builtin ohci-hcd \
-      --builtin ehci-hcd
-
-================================
-Making a disk image for guest OS
-================================
-
- 1. make file
-    # dd if=/dev/zero of=/root/rhel5.img bs=1M seek=4096 count=0
-    # mke2fs -F -j /root/rhel5.img
-    # mount -o loop /root/rhel5.img /mnt
-    # cp -ax /{dev,var,etc,usr,bin,sbin,lib} /mnt
-    # mkdir /mnt/{root,proc,sys,home,tmp}
-
-    Note: You may miss some device files. If so, please create them
-    with mknod. Or you can use tar instead of cp.
-
- 2. modify DomU's fstab
-    # vi /mnt/etc/fstab
-       /dev/xvda1  /            ext3    defaults        1 1
-       none        /dev/pts     devpts  gid=5,mode=620  0 0
-       none        /dev/shm     tmpfs   defaults        0 0
-       none        /proc        proc    defaults        0 0
-       none        /sys         sysfs   defaults        0 0
-
- 3. modify inittab
-    set runlevel to 3 to avoid X trying to start
-    # vi /mnt/etc/inittab
-       id:3:initdefault:
-    Start a getty on the hvc0 console
-       X0:2345:respawn:/sbin/mingetty hvc0
-    tty1-6 mingetty can be commented out
-
- 4. add hvc0 into /etc/securetty
-    # vi /mnt/etc/securetty (add hvc0)
-
- 5. umount
-    # umount /mnt
-
-FYI, virt-manager can also make a disk image for guest OS.
-It's GUI tools and easy to make it.
-
-==================
-Boot Xen & Domain0
-==================
-
- 1. replace elilo
-    elilo of RHEL5 can boot Xen and Dom0.
-    If you use old elilo (e.g RHEL4), please download from the below
-    http://elilo.sourceforge.net/cgi-bin/blosxom
-    and copy into /boot/efi/efi/redhat/
-    # cp elilo-3.6-ia64.efi /boot/efi/efi/redhat/elilo.efi
-
- 2. modify elilo.conf (like the below)
-    # vi /boot/efi/efi/redhat/elilo.conf
-     prompt
-     timeout=20
-     default=xen
-     relocatable
-
-     image=vmlinuz-2.6.18.8-xen
-             label=xen
-             vmm=xen.gz
-             initrd=initrd-2.6.18.8-xen.img
-             read-only
-             append=" -- rhgb root=/dev/sda2"
-
-The append options before "--" are for xen hypervisor,
-the options after "--" are for dom0.
-
-FYI, your machine may need console options like
-"com1=19200,8n1 console=vga,com1". For example,
-append="com1=19200,8n1 console=vga,com1 -- rhgb console=tty0 \
-console=ttyS0 root=/dev/sda2"
-
-=====================================
-Getting and Building domU with pv_ops
-=====================================
-
- 1. get pv_ops tree
-    # git clone http://people.valinux.co.jp/~yamahata/xen-ia64/linux-2.6-xen-ia64.git/
-
- 2. git branch (if necessary)
-    # cd linux-2.6-xen-ia64/
-    # git checkout -b your_branch origin/xen-ia64-domu-minimal-2008may19
-    (Note: The current branch is xen-ia64-domu-minimal-2008may19.
-    But you would find the new branch. You can see with
-    "git branch -r" to get the branch lists.
-    http://people.valinux.co.jp/~yamahata/xen-ia64/for_eagl/linux-2.6-ia64-pv-ops.git/
-    is also available. The tree is based on
-    git://git.kernel.org/pub/scm/linux/kernel/git/aegl/linux-2.6 test)
-
-
- 3. copy .config for pv_ops of domU
-    # cp arch/ia64/configs/xen_domu_wip_defconfig .config
-
- 4. make kernel with pv_ops
-    # make oldconfig
-    # make
-
- 5. install the kernel and initrd
-    # cp vmlinux.gz /boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU
-    # make modules_install
-    # mkinitrd -f /boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img \
-      2.6.26-rc3xen-ia64-08941-g1b12161 --builtin mptspi \
-      --builtin mptbase --builtin mptscsih --builtin uhci-hcd \
-      --builtin ohci-hcd --builtin ehci-hcd
-
-========================
-Boot DomainU with pv_ops
-========================
-
- 1. make config of DomU
-   # vi /etc/xen/rhel5
-     kernel = "/boot/efi/efi/redhat/vmlinuz-2.6-pv_ops-xenU"
-     ramdisk = "/boot/efi/efi/redhat/initrd-2.6-pv_ops-xenU.img"
-     vcpus = 1
-     memory = 512
-     name = "rhel5"
-     disk = [ 'file:/root/rhel5.img,xvda1,w' ]
-     root = "/dev/xvda1 ro"
-     extra= "rhgb console=hvc0"
-
- 2. After boot xen and dom0, start xend
-   # /etc/init.d/xend start
-   ( In the debugging case, # XEND_DEBUG=1 xend trace_start )
-
- 3. start domU
-   # xm create -c rhel5
-
-=========
-Reference
-=========
-- Wiki of Xen/IA64 upstream merge
-  http://wiki.xensource.com/xenwiki/XenIA64/UpstreamMerge
-
-Written by Akio Takebe <takebe_akio@jp.fujitsu.com> on 28 May 2008
diff --git a/MAINTAINERS b/MAINTAINERS
index 8941a73880e6..f27f50f88638 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14266,7 +14266,7 @@ SGI SN-IA64 (Altix) SERIAL CONSOLE DRIVER
 M:	Pat Gefre <pfg@sgi.com>
 L:	linux-ia64@vger.kernel.org
 S:	Supported
-F:	Documentation/ia64/serial.txt
+F:	Documentation/ia64/serial.rst
 F:	drivers/tty/serial/ioc?_serial.c
 F:	include/linux/ioc?.h
 
diff --git a/arch/ia64/kernel/efi.c b/arch/ia64/kernel/efi.c
index 8f106638913c..3795d18276c4 100644
--- a/arch/ia64/kernel/efi.c
+++ b/arch/ia64/kernel/efi.c
@@ -852,7 +852,7 @@ valid_phys_addr_range (phys_addr_t phys_addr, unsigned long size)
 	 * /dev/mem reads and writes use copy_to_user(), which implicitly
 	 * uses a granule-sized kernel identity mapping.  It's really
 	 * only safe to do this for regions in kern_memmap.  For more
-	 * details, see Documentation/ia64/aliasing.txt.
+	 * details, see Documentation/ia64/aliasing.rst.
 	 */
 	attr = kern_mem_attribute(phys_addr, size);
 	if (attr & EFI_MEMORY_WB || attr & EFI_MEMORY_UC)
diff --git a/arch/ia64/kernel/fsys.S b/arch/ia64/kernel/fsys.S
index d80c99a5f55d..0750a716adc7 100644
--- a/arch/ia64/kernel/fsys.S
+++ b/arch/ia64/kernel/fsys.S
@@ -28,7 +28,7 @@
 #include <asm/native/inst.h>
 
 /*
- * See Documentation/ia64/fsys.txt for details on fsyscalls.
+ * See Documentation/ia64/fsys.rst for details on fsyscalls.
  *
  * On entry to an fsyscall handler:
  *   r10	= 0 (i.e., defaults to "successful syscall return")
diff --git a/arch/ia64/mm/ioremap.c b/arch/ia64/mm/ioremap.c
index 43964cde6214..c7da3376b6f8 100644
--- a/arch/ia64/mm/ioremap.c
+++ b/arch/ia64/mm/ioremap.c
@@ -45,7 +45,7 @@ ioremap (unsigned long phys_addr, unsigned long size)
 	/*
 	 * For things in kern_memmap, we must use the same attribute
 	 * as the rest of the kernel.  For more details, see
-	 * Documentation/ia64/aliasing.txt.
+	 * Documentation/ia64/aliasing.rst.
 	 */
 	attr = kern_mem_attribute(phys_addr, size);
 	if (attr & EFI_MEMORY_WB)
diff --git a/arch/ia64/pci/pci.c b/arch/ia64/pci/pci.c
index e308196c2229..165e561dc81a 100644
--- a/arch/ia64/pci/pci.c
+++ b/arch/ia64/pci/pci.c
@@ -450,7 +450,7 @@ pci_mmap_legacy_page_range(struct pci_bus *bus, struct vm_area_struct *vma,
 		return -ENOSYS;
 
 	/*
-	 * Avoid attribute aliasing.  See Documentation/ia64/aliasing.txt
+	 * Avoid attribute aliasing.  See Documentation/ia64/aliasing.rst
 	 * for more details.
 	 */
 	if (!valid_mmap_phys_addr_range(vma->vm_pgoff, size))
-- 
2.21.0

[PATCH v2 20/29] docs: leds: convert to ReST

[Mauro Carvalho Chehab]

Rename the leds documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

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/laptops/thinkpad-acpi.txt       |   4 +-
 Documentation/leds/index.rst                  |  25 ++
 .../leds/{leds-blinkm.txt => leds-blinkm.rst} |  64 ++---
 ...s-class-flash.txt => leds-class-flash.rst} |  49 ++--
 .../leds/{leds-class.txt => leds-class.rst}   |  15 +-
 .../leds/{leds-lm3556.txt => leds-lm3556.rst} | 100 ++++++--
 .../leds/{leds-lp3944.txt => leds-lp3944.rst} |  23 +-
 Documentation/leds/leds-lp5521.rst            | 115 +++++++++
 Documentation/leds/leds-lp5521.txt            | 101 --------
 Documentation/leds/leds-lp5523.rst            | 147 ++++++++++++
 Documentation/leds/leds-lp5523.txt            | 130 ----------
 Documentation/leds/leds-lp5562.rst            | 137 +++++++++++
 Documentation/leds/leds-lp5562.txt            | 120 ----------
 Documentation/leds/leds-lp55xx.rst            | 224 ++++++++++++++++++
 Documentation/leds/leds-lp55xx.txt            | 194 ---------------
 Documentation/leds/leds-mlxcpld.rst           | 118 +++++++++
 Documentation/leds/leds-mlxcpld.txt           | 110 ---------
 ...edtrig-oneshot.txt => ledtrig-oneshot.rst} |  11 +-
 ...ig-transient.txt => ledtrig-transient.rst} |  63 +++--
 ...edtrig-usbport.txt => ledtrig-usbport.rst} |  11 +-
 Documentation/leds/{uleds.txt => uleds.rst}   |   5 +-
 MAINTAINERS                                   |   2 +-
 drivers/leds/trigger/Kconfig                  |   2 +-
 drivers/leds/trigger/ledtrig-transient.c      |   2 +-
 net/netfilter/Kconfig                         |   2 +-
 25 files changed, 996 insertions(+), 778 deletions(-)
 create mode 100644 Documentation/leds/index.rst
 rename Documentation/leds/{leds-blinkm.txt => leds-blinkm.rst} (57%)
 rename Documentation/leds/{leds-class-flash.txt => leds-class-flash.rst} (74%)
 rename Documentation/leds/{leds-class.txt => leds-class.rst} (92%)
 rename Documentation/leds/{leds-lm3556.txt => leds-lm3556.rst} (70%)
 rename Documentation/leds/{leds-lp3944.txt => leds-lp3944.rst} (78%)
 create mode 100644 Documentation/leds/leds-lp5521.rst
 delete mode 100644 Documentation/leds/leds-lp5521.txt
 create mode 100644 Documentation/leds/leds-lp5523.rst
 delete mode 100644 Documentation/leds/leds-lp5523.txt
 create mode 100644 Documentation/leds/leds-lp5562.rst
 delete mode 100644 Documentation/leds/leds-lp5562.txt
 create mode 100644 Documentation/leds/leds-lp55xx.rst
 delete mode 100644 Documentation/leds/leds-lp55xx.txt
 create mode 100644 Documentation/leds/leds-mlxcpld.rst
 delete mode 100644 Documentation/leds/leds-mlxcpld.txt
 rename Documentation/leds/{ledtrig-oneshot.txt => ledtrig-oneshot.rst} (90%)
 rename Documentation/leds/{ledtrig-transient.txt => ledtrig-transient.rst} (81%)
 rename Documentation/leds/{ledtrig-usbport.txt => ledtrig-usbport.rst} (86%)
 rename Documentation/leds/{uleds.txt => uleds.rst} (95%)

diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/laptops/thinkpad-acpi.txt
index 6cced88de6da..75ef063622d2 100644
--- a/Documentation/laptops/thinkpad-acpi.txt
+++ b/Documentation/laptops/thinkpad-acpi.txt
@@ -679,7 +679,7 @@ status as "unknown". The available commands are:
 sysfs notes:
 
 The ThinkLight sysfs interface is documented by the LED class
-documentation, in Documentation/leds/leds-class.txt.  The ThinkLight LED name
+documentation, in Documentation/leds/leds-class.rst.  The ThinkLight LED name
 is "tpacpi::thinklight".
 
 Due to limitations in the sysfs LED class, if the status of the ThinkLight
@@ -779,7 +779,7 @@ All of the above can be turned on and off and can be made to blink.
 sysfs notes:
 
 The ThinkPad LED sysfs interface is described in detail by the LED class
-documentation, in Documentation/leds/leds-class.txt.
+documentation, in Documentation/leds/leds-class.rst.
 
 The LEDs are named (in LED ID order, from 0 to 12):
 "tpacpi::power", "tpacpi:orange:batt", "tpacpi:green:batt",
diff --git a/Documentation/leds/index.rst b/Documentation/leds/index.rst
new file mode 100644
index 000000000000..9885f7c1b75d
--- /dev/null
+++ b/Documentation/leds/index.rst
@@ -0,0 +1,25 @@
+:orphan:
+
+====
+LEDs
+====
+
+.. toctree::
+   :maxdepth: 1
+
+   leds-class
+   leds-class-flash
+   ledtrig-oneshot
+   ledtrig-transient
+   ledtrig-usbport
+
+   uleds
+
+   leds-blinkm
+   leds-lm3556
+   leds-lp3944
+   leds-lp5521
+   leds-lp5523
+   leds-lp5562
+   leds-lp55xx
+   leds-mlxcpld
diff --git a/Documentation/leds/leds-blinkm.txt b/Documentation/leds/leds-blinkm.rst
similarity index 57%
rename from Documentation/leds/leds-blinkm.txt
rename to Documentation/leds/leds-blinkm.rst
index 9dd92f4cf4e1..c74b5bc877b1 100644
--- a/Documentation/leds/leds-blinkm.txt
+++ b/Documentation/leds/leds-blinkm.rst
@@ -1,3 +1,7 @@
+==================
+Leds BlinkM driver
+==================
+
 The leds-blinkm driver supports the devices of the BlinkM family.
 
 They are RGB-LED modules driven by a (AT)tiny microcontroller and
@@ -14,35 +18,36 @@ The interface this driver provides is 2-fold:
 a) LED class interface for use with triggers
 ############################################
 
-The registration follows the scheme:
-blinkm-<i2c-bus-nr>-<i2c-device-nr>-<color>
+The registration follows the scheme::
 
-$ ls -h /sys/class/leds/blinkm-6-*
-/sys/class/leds/blinkm-6-9-blue:
-brightness  device  max_brightness  power  subsystem  trigger  uevent
+  blinkm-<i2c-bus-nr>-<i2c-device-nr>-<color>
 
-/sys/class/leds/blinkm-6-9-green:
-brightness  device  max_brightness  power  subsystem  trigger  uevent
+  $ ls -h /sys/class/leds/blinkm-6-*
+  /sys/class/leds/blinkm-6-9-blue:
+  brightness  device  max_brightness  power  subsystem  trigger  uevent
 
-/sys/class/leds/blinkm-6-9-red:
-brightness  device  max_brightness  power  subsystem  trigger  uevent
+  /sys/class/leds/blinkm-6-9-green:
+  brightness  device  max_brightness  power  subsystem  trigger  uevent
+
+  /sys/class/leds/blinkm-6-9-red:
+  brightness  device  max_brightness  power  subsystem  trigger  uevent
 
 (same is /sys/bus/i2c/devices/6-0009/leds)
 
 We can control the colors separated into red, green and blue and
 assign triggers on each color.
 
-E.g.:
+E.g.::
 
-$ cat blinkm-6-9-blue/brightness
-05
+  $ cat blinkm-6-9-blue/brightness
+  05
 
-$ echo 200 > blinkm-6-9-blue/brightness
-$
+  $ echo 200 > blinkm-6-9-blue/brightness
+  $
 
-$ modprobe ledtrig-heartbeat
-$ echo heartbeat > blinkm-6-9-green/trigger
-$
+  $ modprobe ledtrig-heartbeat
+  $ echo heartbeat > blinkm-6-9-green/trigger
+  $
 
 
 b) Sysfs group to control rgb, fade, hsb, scripts ...
@@ -52,29 +57,28 @@ This extended interface is available as folder blinkm
 in the sysfs folder of the I2C device.
 E.g. below /sys/bus/i2c/devices/6-0009/blinkm
 
-$ ls -h /sys/bus/i2c/devices/6-0009/blinkm/
-blue  green  red  test
+  $ ls -h /sys/bus/i2c/devices/6-0009/blinkm/
+  blue  green  red  test
 
 Currently supported is just setting red, green, blue
 and a test sequence.
 
-E.g.:
+E.g.::
 
-$ cat *
-00
-00
-00
-#Write into test to start test sequence!#
+  $ cat *
+  00
+  00
+  00
+  #Write into test to start test sequence!#
 
-$ echo 1 > test
-$
+  $ echo 1 > test
+  $
 
-$ echo 255 > red
-$
+  $ echo 255 > red
+  $
 
 
 
 as of 6/2012
 
 dl9pf <at> gmx <dot> de
-
diff --git a/Documentation/leds/leds-class-flash.txt b/Documentation/leds/leds-class-flash.rst
similarity index 74%
rename from Documentation/leds/leds-class-flash.txt
rename to Documentation/leds/leds-class-flash.rst
index 8da3c6f4b60b..6ec12c5a1a0e 100644
--- a/Documentation/leds/leds-class-flash.txt
+++ b/Documentation/leds/leds-class-flash.rst
@@ -1,9 +1,9 @@
-
+==============================
 Flash LED handling under Linux
 ==============================
 
 Some LED devices provide two modes - torch and flash. In the LED subsystem
-those modes are supported by LED class (see Documentation/leds/leds-class.txt)
+those modes are supported by LED class (see Documentation/leds/leds-class.rst)
 and LED Flash class respectively. The torch mode related features are enabled
 by default and the flash ones only if a driver declares it by setting
 LED_DEV_CAP_FLASH flag.
@@ -14,6 +14,7 @@ registered in the LED subsystem with led_classdev_flash_register function.
 
 Following sysfs attributes are exposed for controlling flash LED devices:
 (see Documentation/ABI/testing/sysfs-class-led-flash)
+
 	- flash_brightness
 	- max_flash_brightness
 	- flash_timeout
@@ -31,30 +32,46 @@ be defined in the kernel config.
 
 The driver must call the v4l2_flash_init function to get registered in the
 V4L2 subsystem. The function takes six arguments:
-- dev       : flash device, e.g. an I2C device
-- of_node   : of_node of the LED, may be NULL if the same as device's
-- fled_cdev : LED flash class device to wrap
-- iled_cdev : LED flash class device representing indicator LED associated with
-	      fled_cdev, may be NULL
-- ops : V4L2 specific ops
-	* external_strobe_set - defines the source of the flash LED strobe -
+
+- dev:
+	flash device, e.g. an I2C device
+- of_node:
+	of_node of the LED, may be NULL if the same as device's
+- fled_cdev:
+	LED flash class device to wrap
+- iled_cdev:
+	LED flash class device representing indicator LED associated with
+	fled_cdev, may be NULL
+- ops:
+	V4L2 specific ops
+
+	* external_strobe_set
+		defines the source of the flash LED strobe -
 		V4L2_CID_FLASH_STROBE control or external source, typically
 		a sensor, which makes it possible to synchronise the flash
 		strobe start with exposure start,
-	* intensity_to_led_brightness and led_brightness_to_intensity - perform
+	* intensity_to_led_brightness and led_brightness_to_intensity
+		perform
 		enum led_brightness <-> V4L2 intensity conversion in a device
 		specific manner - they can be used for devices with non-linear
 		LED current scale.
-- config : configuration for V4L2 Flash sub-device
-	* dev_name - the name of the media entity, unique in the system,
-	* flash_faults - bitmask of flash faults that the LED flash class
+- config:
+	configuration for V4L2 Flash sub-device
+
+	* dev_name
+		the name of the media entity, unique in the system,
+	* flash_faults
+		bitmask of flash faults that the LED flash class
 		device can report; corresponding LED_FAULT* bit definitions are
 		available in <linux/led-class-flash.h>,
-	* torch_intensity - constraints for the LED in TORCH mode
+	* torch_intensity
+		constraints for the LED in TORCH mode
 		in microamperes,
-	* indicator_intensity - constraints for the indicator LED
+	* indicator_intensity
+		constraints for the indicator LED
 		in microamperes,
-	* has_external_strobe - determines whether the flash strobe source
+	* has_external_strobe
+		determines whether the flash strobe source
 		can be switched to external,
 
 On remove the v4l2_flash_release function has to be called, which takes one
diff --git a/Documentation/leds/leds-class.txt b/Documentation/leds/leds-class.rst
similarity index 92%
rename from Documentation/leds/leds-class.txt
rename to Documentation/leds/leds-class.rst
index 8b39cc6b03ee..df0120a1ee3c 100644
--- a/Documentation/leds/leds-class.txt
+++ b/Documentation/leds/leds-class.rst
@@ -1,4 +1,4 @@
-
+========================
 LED handling under Linux
 ========================
 
@@ -43,7 +43,7 @@ LED Device Naming
 
 Is currently of the form:
 
-"devicename:colour:function"
+	"devicename:colour:function"
 
 There have been calls for LED properties such as colour to be exported as
 individual led class attributes. As a solution which doesn't incur as much
@@ -57,9 +57,12 @@ Brightness setting API
 
 LED subsystem core exposes following API for setting brightness:
 
-    - led_set_brightness : it is guaranteed not to sleep, passing LED_OFF stops
+    - led_set_brightness:
+		it is guaranteed not to sleep, passing LED_OFF stops
 		blinking,
-    - led_set_brightness_sync : for use cases when immediate effect is desired -
+
+    - led_set_brightness_sync:
+		for use cases when immediate effect is desired -
 		it can block the caller for the time required for accessing
 		device registers and can sleep, passing LED_OFF stops hardware
 		blinking, returns -EBUSY if software blink fallback is enabled.
@@ -70,7 +73,7 @@ LED registration API
 
 A driver wanting to register a LED classdev for use by other drivers /
 userspace needs to allocate and fill a led_classdev struct and then call
-[devm_]led_classdev_register. If the non devm version is used the driver
+`[devm_]led_classdev_register`. If the non devm version is used the driver
 must call led_classdev_unregister from its remove function before
 free-ing the led_classdev struct.
 
@@ -94,7 +97,7 @@ with brightness value LED_OFF, which should stop any software
 timers that may have been required for blinking.
 
 The blink_set() function should choose a user friendly blinking value
-if it is called with *delay_on==0 && *delay_off==0 parameters. In this
+if it is called with `*delay_on==0` && `*delay_off==0` parameters. In this
 case the driver should give back the chosen value through delay_on and
 delay_off parameters to the leds subsystem.
 
diff --git a/Documentation/leds/leds-lm3556.txt b/Documentation/leds/leds-lm3556.rst
similarity index 70%
rename from Documentation/leds/leds-lm3556.txt
rename to Documentation/leds/leds-lm3556.rst
index 62278e871b50..1ef17d7d800e 100644
--- a/Documentation/leds/leds-lm3556.txt
+++ b/Documentation/leds/leds-lm3556.rst
@@ -1,68 +1,118 @@
+========================
 Kernel driver for lm3556
 ========================
 
-*Texas Instrument:
- 1.5 A Synchronous Boost LED Flash Driver w/ High-Side Current Source
+* Texas Instrument:
+  1.5 A Synchronous Boost LED Flash Driver w/ High-Side Current Source
 * Datasheet: http://www.national.com/ds/LM/LM3556.pdf
 
 Authors:
-	Daniel Jeong
+      - Daniel Jeong
+
 	Contact:Daniel Jeong(daniel.jeong-at-ti.com, gshark.jeong-at-gmail.com)
 
 Description
 -----------
 There are 3 functions in LM3556, Flash, Torch and Indicator.
 
-FLASH MODE
+Flash Mode
+^^^^^^^^^^
+
 In Flash Mode, the LED current source(LED) provides 16 target current levels
 from 93.75 mA to 1500 mA.The Flash currents are adjusted via the CURRENT
 CONTROL REGISTER(0x09).Flash mode is activated by the ENABLE REGISTER(0x0A),
 or by pulling the STROBE pin HIGH.
+
 LM3556 Flash can be controlled through sys/class/leds/flash/brightness file
+
 * if STROBE pin is enabled, below example control brightness only, and
-ON / OFF will be controlled by STROBE pin.
+  ON / OFF will be controlled by STROBE pin.
 
 Flash Example:
-OFF     : #echo 0 > sys/class/leds/flash/brightness
-93.75 mA: #echo 1 > sys/class/leds/flash/brightness
-... .....
-1500  mA: #echo 16 > sys/class/leds/flash/brightness
 
-TORCH MODE
+OFF::
+
+	#echo 0 > sys/class/leds/flash/brightness
+
+93.75 mA::
+
+	#echo 1 > sys/class/leds/flash/brightness
+
+...
+
+1500  mA::
+
+	#echo 16 > sys/class/leds/flash/brightness
+
+Torch Mode
+^^^^^^^^^^
+
 In Torch Mode, the current source(LED) is programmed via the CURRENT CONTROL
 REGISTER(0x09).Torch Mode is activated by the ENABLE REGISTER(0x0A) or by the
 hardware TORCH input.
+
 LM3556 torch can be controlled through sys/class/leds/torch/brightness file.
 * if TORCH pin is enabled, below example control brightness only,
 and ON / OFF will be controlled by TORCH pin.
 
 Torch Example:
-OFF     : #echo 0 > sys/class/leds/torch/brightness
-46.88 mA: #echo 1 > sys/class/leds/torch/brightness
-... .....
-375 mA  : #echo 8 > sys/class/leds/torch/brightness
 
-INDICATOR MODE
+OFF::
+
+	#echo 0 > sys/class/leds/torch/brightness
+
+46.88 mA::
+
+	#echo 1 > sys/class/leds/torch/brightness
+
+...
+
+375 mA::
+
+	#echo 8 > sys/class/leds/torch/brightness
+
+Indicator Mode
+^^^^^^^^^^^^^^
+
 Indicator pattern can be set through sys/class/leds/indicator/pattern file,
 and 4 patterns are pre-defined in indicator_pattern array.
+
 According to N-lank, Pulse time and N Period values, different pattern wiill
 be generated.If you want new patterns for your own device, change
 indicator_pattern array with your own values and INDIC_PATTERN_SIZE.
+
 Please refer datasheet for more detail about N-Blank, Pulse time and N Period.
 
 Indicator pattern example:
-pattern 0: #echo 0 > sys/class/leds/indicator/pattern
-....
-pattern 3: #echo 3 > sys/class/leds/indicator/pattern
+
+pattern 0::
+
+	#echo 0 > sys/class/leds/indicator/pattern
+
+...
+
+pattern 3::
+
+	#echo 3 > sys/class/leds/indicator/pattern
 
 Indicator brightness can be controlled through
 sys/class/leds/indicator/brightness file.
 
 Example:
-OFF      : #echo 0 > sys/class/leds/indicator/brightness
-5.86 mA  : #echo 1 > sys/class/leds/indicator/brightness
-........
-46.875mA : #echo 8 > sys/class/leds/indicator/brightness
+
+OFF::
+
+	#echo 0 > sys/class/leds/indicator/brightness
+
+5.86 mA::
+
+	#echo 1 > sys/class/leds/indicator/brightness
+
+...
+
+46.875mA::
+
+	#echo 8 > sys/class/leds/indicator/brightness
 
 Notes
 -----
@@ -70,7 +120,8 @@ Driver expects it is registered using the i2c_board_info mechanism.
 To register the chip at address 0x63 on specific adapter, set the platform data
 according to include/linux/platform_data/leds-lm3556.h, set the i2c board info
 
-Example:
+Example::
+
 	static struct i2c_board_info board_i2c_ch4[] __initdata = {
 		{
 			 I2C_BOARD_INFO(LM3556_NAME, 0x63),
@@ -80,6 +131,7 @@ Example:
 
 and register it in the platform init function
 
-Example:
+Example::
+
 	board_register_i2c_bus(4, 400,
 				board_i2c_ch4, ARRAY_SIZE(board_i2c_ch4));
diff --git a/Documentation/leds/leds-lp3944.txt b/Documentation/leds/leds-lp3944.rst
similarity index 78%
rename from Documentation/leds/leds-lp3944.txt
rename to Documentation/leds/leds-lp3944.rst
index e88ac3b60c08..c2f87dc1a3a9 100644
--- a/Documentation/leds/leds-lp3944.txt
+++ b/Documentation/leds/leds-lp3944.rst
@@ -1,14 +1,20 @@
+====================
 Kernel driver lp3944
 ====================
 
   * National Semiconductor LP3944 Fun-light Chip
+
     Prefix: 'lp3944'
+
     Addresses scanned: None (see the Notes section below)
-    Datasheet: Publicly available at the National Semiconductor website
-               http://www.national.com/pf/LP/LP3944.html
+
+    Datasheet:
+
+	Publicly available at the National Semiconductor website
+	http://www.national.com/pf/LP/LP3944.html
 
 Authors:
-        Antonio Ospite <ospite@studenti.unina.it>
+	Antonio Ospite <ospite@studenti.unina.it>
 
 
 Description
@@ -19,8 +25,11 @@ is used as a led controller.
 
 The DIM modes are used to set _blink_ patterns for leds, the pattern is
 specified supplying two parameters:
-  - period: from 0s to 1.6s
-  - duty cycle: percentage of the period the led is on, from 0 to 100
+
+  - period:
+	from 0s to 1.6s
+  - duty cycle:
+	percentage of the period the led is on, from 0 to 100
 
 Setting a led in DIM0 or DIM1 mode makes it blink according to the pattern.
 See the datasheet for details.
@@ -35,7 +44,7 @@ The chip is used mainly in embedded contexts, so this driver expects it is
 registered using the i2c_board_info mechanism.
 
 To register the chip at address 0x60 on adapter 0, set the platform data
-according to include/linux/leds-lp3944.h, set the i2c board info:
+according to include/linux/leds-lp3944.h, set the i2c board info::
 
 	static struct i2c_board_info a910_i2c_board_info[] __initdata = {
 		{
@@ -44,7 +53,7 @@ according to include/linux/leds-lp3944.h, set the i2c board info:
 		},
 	};
 
-and register it in the platform init function
+and register it in the platform init function::
 
 	i2c_register_board_info(0, a910_i2c_board_info,
 			ARRAY_SIZE(a910_i2c_board_info));
diff --git a/Documentation/leds/leds-lp5521.rst b/Documentation/leds/leds-lp5521.rst
new file mode 100644
index 000000000000..0432615b083d
--- /dev/null
+++ b/Documentation/leds/leds-lp5521.rst
@@ -0,0 +1,115 @@
+========================
+Kernel driver for lp5521
+========================
+
+* National Semiconductor LP5521 led driver chip
+* Datasheet: http://www.national.com/pf/LP/LP5521.html
+
+Authors: Mathias Nyman, Yuri Zaporozhets, Samu Onkalo
+
+Contact: Samu Onkalo (samu.p.onkalo-at-nokia.com)
+
+Description
+-----------
+
+LP5521 can drive up to 3 channels. Leds can be controlled directly via
+the led class control interface. Channels have generic names:
+lp5521:channelx, where x is 0 .. 2
+
+All three channels can be also controlled using the engine micro programs.
+More details of the instructions can be found from the public data sheet.
+
+LP5521 has the internal program memory for running various LED patterns.
+There are two ways to run LED patterns.
+
+1) Legacy interface - enginex_mode and enginex_load
+   Control interface for the engines:
+
+   x is 1 .. 3
+
+   enginex_mode:
+	disabled, load, run
+   enginex_load:
+	store program (visible only in engine load mode)
+
+  Example (start to blink the channel 2 led)::
+
+	cd   /sys/class/leds/lp5521:channel2/device
+	echo "load" > engine3_mode
+	echo "037f4d0003ff6000" > engine3_load
+	echo "run" > engine3_mode
+
+  To stop the engine::
+
+	echo "disabled" > engine3_mode
+
+2) Firmware interface - LP55xx common interface
+
+For the details, please refer to 'firmware' section in leds-lp55xx.txt
+
+sysfs contains a selftest entry.
+
+The test communicates with the chip and checks that
+the clock mode is automatically set to the requested one.
+
+Each channel has its own led current settings.
+
+- /sys/class/leds/lp5521:channel0/led_current - RW
+- /sys/class/leds/lp5521:channel0/max_current - RO
+
+Format: 10x mA i.e 10 means 1.0 mA
+
+example platform data::
+
+  static struct lp55xx_led_config lp5521_led_config[] = {
+	  {
+		.name = "red",
+		  .chan_nr        = 0,
+		  .led_current    = 50,
+		.max_current    = 130,
+	  }, {
+		.name = "green",
+		  .chan_nr        = 1,
+		  .led_current    = 0,
+		.max_current    = 130,
+	  }, {
+		.name = "blue",
+		  .chan_nr        = 2,
+		  .led_current    = 0,
+		.max_current    = 130,
+	  }
+  };
+
+  static int lp5521_setup(void)
+  {
+	/* setup HW resources */
+  }
+
+  static void lp5521_release(void)
+  {
+	/* Release HW resources */
+  }
+
+  static void lp5521_enable(bool state)
+  {
+	/* Control of chip enable signal */
+  }
+
+  static struct lp55xx_platform_data lp5521_platform_data = {
+	  .led_config     = lp5521_led_config,
+	  .num_channels   = ARRAY_SIZE(lp5521_led_config),
+	  .clock_mode     = LP55XX_CLOCK_EXT,
+	  .setup_resources   = lp5521_setup,
+	  .release_resources = lp5521_release,
+	  .enable            = lp5521_enable,
+  };
+
+Note:
+  chan_nr can have values between 0 and 2.
+  The name of each channel can be configurable.
+  If the name field is not defined, the default name will be set to 'xxxx:channelN'
+  (XXXX : pdata->label or i2c client name, N : channel number)
+
+
+If the current is set to 0 in the platform data, that channel is
+disabled and it is not visible in the sysfs.
diff --git a/Documentation/leds/leds-lp5521.txt b/Documentation/leds/leds-lp5521.txt
deleted file mode 100644
index d08d8c179f85..000000000000
--- a/Documentation/leds/leds-lp5521.txt
+++ /dev/null
@@ -1,101 +0,0 @@
-Kernel driver for lp5521
-========================
-
-* National Semiconductor LP5521 led driver chip
-* Datasheet: http://www.national.com/pf/LP/LP5521.html
-
-Authors: Mathias Nyman, Yuri Zaporozhets, Samu Onkalo
-Contact: Samu Onkalo (samu.p.onkalo-at-nokia.com)
-
-Description
------------
-
-LP5521 can drive up to 3 channels. Leds can be controlled directly via
-the led class control interface. Channels have generic names:
-lp5521:channelx, where x is 0 .. 2
-
-All three channels can be also controlled using the engine micro programs.
-More details of the instructions can be found from the public data sheet.
-
-LP5521 has the internal program memory for running various LED patterns.
-There are two ways to run LED patterns.
-
-1) Legacy interface - enginex_mode and enginex_load
-  Control interface for the engines:
-  x is 1 .. 3
-  enginex_mode : disabled, load, run
-  enginex_load : store program (visible only in engine load mode)
-
-  Example (start to blink the channel 2 led):
-  cd   /sys/class/leds/lp5521:channel2/device
-  echo "load" > engine3_mode
-  echo "037f4d0003ff6000" > engine3_load
-  echo "run" > engine3_mode
-
-  To stop the engine:
-  echo "disabled" > engine3_mode
-
-2) Firmware interface - LP55xx common interface
-  For the details, please refer to 'firmware' section in leds-lp55xx.txt
-
-sysfs contains a selftest entry.
-The test communicates with the chip and checks that
-the clock mode is automatically set to the requested one.
-
-Each channel has its own led current settings.
-/sys/class/leds/lp5521:channel0/led_current - RW
-/sys/class/leds/lp5521:channel0/max_current - RO
-Format: 10x mA i.e 10 means 1.0 mA
-
-example platform data:
-
-Note: chan_nr can have values between 0 and 2.
-The name of each channel can be configurable.
-If the name field is not defined, the default name will be set to 'xxxx:channelN'
-(XXXX : pdata->label or i2c client name, N : channel number)
-
-static struct lp55xx_led_config lp5521_led_config[] = {
-        {
-		.name = "red",
-                .chan_nr        = 0,
-                .led_current    = 50,
-		.max_current    = 130,
-        }, {
-		.name = "green",
-                .chan_nr        = 1,
-                .led_current    = 0,
-		.max_current    = 130,
-        }, {
-		.name = "blue",
-                .chan_nr        = 2,
-                .led_current    = 0,
-		.max_current    = 130,
-        }
-};
-
-static int lp5521_setup(void)
-{
-	/* setup HW resources */
-}
-
-static void lp5521_release(void)
-{
-	/* Release HW resources */
-}
-
-static void lp5521_enable(bool state)
-{
-	/* Control of chip enable signal */
-}
-
-static struct lp55xx_platform_data lp5521_platform_data = {
-        .led_config     = lp5521_led_config,
-        .num_channels   = ARRAY_SIZE(lp5521_led_config),
-        .clock_mode     = LP55XX_CLOCK_EXT,
-        .setup_resources   = lp5521_setup,
-        .release_resources = lp5521_release,
-        .enable            = lp5521_enable,
-};
-
-If the current is set to 0 in the platform data, that channel is
-disabled and it is not visible in the sysfs.
diff --git a/Documentation/leds/leds-lp5523.rst b/Documentation/leds/leds-lp5523.rst
new file mode 100644
index 000000000000..7d7362a1dd57
--- /dev/null
+++ b/Documentation/leds/leds-lp5523.rst
@@ -0,0 +1,147 @@
+========================
+Kernel driver for lp5523
+========================
+
+* National Semiconductor LP5523 led driver chip
+* Datasheet: http://www.national.com/pf/LP/LP5523.html
+
+Authors: Mathias Nyman, Yuri Zaporozhets, Samu Onkalo
+Contact: Samu Onkalo (samu.p.onkalo-at-nokia.com)
+
+Description
+-----------
+LP5523 can drive up to 9 channels. Leds can be controlled directly via
+the led class control interface.
+The name of each channel is configurable in the platform data - name and label.
+There are three options to make the channel name.
+
+a) Define the 'name' in the platform data
+
+To make specific channel name, then use 'name' platform data.
+
+- /sys/class/leds/R1               (name: 'R1')
+- /sys/class/leds/B1               (name: 'B1')
+
+b) Use the 'label' with no 'name' field
+
+For one device name with channel number, then use 'label'.
+- /sys/class/leds/RGB:channelN     (label: 'RGB', N: 0 ~ 8)
+
+c) Default
+
+If both fields are NULL, 'lp5523' is used by default.
+- /sys/class/leds/lp5523:channelN  (N: 0 ~ 8)
+
+LP5523 has the internal program memory for running various LED patterns.
+There are two ways to run LED patterns.
+
+1) Legacy interface - enginex_mode, enginex_load and enginex_leds
+
+  Control interface for the engines:
+
+  x is 1 .. 3
+
+  enginex_mode:
+	disabled, load, run
+  enginex_load:
+	microcode load
+  enginex_leds:
+	led mux control
+
+  ::
+
+	cd /sys/class/leds/lp5523:channel2/device
+	echo "load" > engine3_mode
+	echo "9d80400004ff05ff437f0000" > engine3_load
+	echo "111111111" > engine3_leds
+	echo "run" > engine3_mode
+
+  To stop the engine::
+
+	echo "disabled" > engine3_mode
+
+2) Firmware interface - LP55xx common interface
+
+For the details, please refer to 'firmware' section in leds-lp55xx.txt
+
+LP5523 has three master faders. If a channel is mapped to one of
+the master faders, its output is dimmed based on the value of the master
+fader.
+
+For example::
+
+  echo "123000123" > master_fader_leds
+
+creates the following channel-fader mappings::
+
+  channel 0,6 to master_fader1
+  channel 1,7 to master_fader2
+  channel 2,8 to master_fader3
+
+Then, to have 25% of the original output on channel 0,6::
+
+  echo 64 > master_fader1
+
+To have 0% of the original output (i.e. no output) channel 1,7::
+
+  echo 0 > master_fader2
+
+To have 100% of the original output (i.e. no dimming) on channel 2,8::
+
+  echo 255 > master_fader3
+
+To clear all master fader controls::
+
+  echo "000000000" > master_fader_leds
+
+Selftest uses always the current from the platform data.
+
+Each channel contains led current settings.
+- /sys/class/leds/lp5523:channel2/led_current - RW
+- /sys/class/leds/lp5523:channel2/max_current - RO
+
+Format: 10x mA i.e 10 means 1.0 mA
+
+Example platform data::
+
+	static struct lp55xx_led_config lp5523_led_config[] = {
+		{
+			.name		= "D1",
+			.chan_nr        = 0,
+			.led_current    = 50,
+			.max_current    = 130,
+		},
+	...
+		{
+			.chan_nr        = 8,
+			.led_current    = 50,
+			.max_current    = 130,
+		}
+	};
+
+	static int lp5523_setup(void)
+	{
+		/* Setup HW resources */
+	}
+
+	static void lp5523_release(void)
+	{
+		/* Release HW resources */
+	}
+
+	static void lp5523_enable(bool state)
+	{
+		/* Control chip enable signal */
+	}
+
+	static struct lp55xx_platform_data lp5523_platform_data = {
+		.led_config     = lp5523_led_config,
+		.num_channels   = ARRAY_SIZE(lp5523_led_config),
+		.clock_mode     = LP55XX_CLOCK_EXT,
+		.setup_resources   = lp5523_setup,
+		.release_resources = lp5523_release,
+		.enable            = lp5523_enable,
+	};
+
+Note
+  chan_nr can have values between 0 and 8.
diff --git a/Documentation/leds/leds-lp5523.txt b/Documentation/leds/leds-lp5523.txt
deleted file mode 100644
index 0961a060fc4d..000000000000
--- a/Documentation/leds/leds-lp5523.txt
+++ /dev/null
@@ -1,130 +0,0 @@
-Kernel driver for lp5523
-========================
-
-* National Semiconductor LP5523 led driver chip
-* Datasheet: http://www.national.com/pf/LP/LP5523.html
-
-Authors: Mathias Nyman, Yuri Zaporozhets, Samu Onkalo
-Contact: Samu Onkalo (samu.p.onkalo-at-nokia.com)
-
-Description
------------
-LP5523 can drive up to 9 channels. Leds can be controlled directly via
-the led class control interface.
-The name of each channel is configurable in the platform data - name and label.
-There are three options to make the channel name.
-
-a) Define the 'name' in the platform data
-To make specific channel name, then use 'name' platform data.
-/sys/class/leds/R1               (name: 'R1')
-/sys/class/leds/B1               (name: 'B1')
-
-b) Use the 'label' with no 'name' field
-For one device name with channel number, then use 'label'.
-/sys/class/leds/RGB:channelN     (label: 'RGB', N: 0 ~ 8)
-
-c) Default
-If both fields are NULL, 'lp5523' is used by default.
-/sys/class/leds/lp5523:channelN  (N: 0 ~ 8)
-
-LP5523 has the internal program memory for running various LED patterns.
-There are two ways to run LED patterns.
-
-1) Legacy interface - enginex_mode, enginex_load and enginex_leds
-  Control interface for the engines:
-  x is 1 .. 3
-  enginex_mode : disabled, load, run
-  enginex_load : microcode load
-  enginex_leds : led mux control
-
-  cd /sys/class/leds/lp5523:channel2/device
-  echo "load" > engine3_mode
-  echo "9d80400004ff05ff437f0000" > engine3_load
-  echo "111111111" > engine3_leds
-  echo "run" > engine3_mode
-
-  To stop the engine:
-  echo "disabled" > engine3_mode
-
-2) Firmware interface - LP55xx common interface
-  For the details, please refer to 'firmware' section in leds-lp55xx.txt
-
-LP5523 has three master faders. If a channel is mapped to one of
-the master faders, its output is dimmed based on the value of the master
-fader.
-
-For example,
-
-  echo "123000123" > master_fader_leds
-
-creates the following channel-fader mappings:
-
-  channel 0,6 to master_fader1
-  channel 1,7 to master_fader2
-  channel 2,8 to master_fader3
-
-Then, to have 25% of the original output on channel 0,6:
-
-  echo 64 > master_fader1
-
-To have 0% of the original output (i.e. no output) channel 1,7:
-
-  echo 0 > master_fader2
-
-To have 100% of the original output (i.e. no dimming) on channel 2,8:
-
-  echo 255 > master_fader3
-
-To clear all master fader controls:
-
-  echo "000000000" > master_fader_leds
-
-Selftest uses always the current from the platform data.
-
-Each channel contains led current settings.
-/sys/class/leds/lp5523:channel2/led_current - RW
-/sys/class/leds/lp5523:channel2/max_current - RO
-Format: 10x mA i.e 10 means 1.0 mA
-
-Example platform data:
-
-Note - chan_nr can have values between 0 and 8.
-
-static struct lp55xx_led_config lp5523_led_config[] = {
-        {
-		.name		= "D1",
-                .chan_nr        = 0,
-                .led_current    = 50,
-		.max_current    = 130,
-        },
-...
-        {
-                .chan_nr        = 8,
-                .led_current    = 50,
-		.max_current    = 130,
-        }
-};
-
-static int lp5523_setup(void)
-{
-	/* Setup HW resources */
-}
-
-static void lp5523_release(void)
-{
-	/* Release HW resources */
-}
-
-static void lp5523_enable(bool state)
-{
-	/* Control chip enable signal */
-}
-
-static struct lp55xx_platform_data lp5523_platform_data = {
-        .led_config     = lp5523_led_config,
-        .num_channels   = ARRAY_SIZE(lp5523_led_config),
-        .clock_mode     = LP55XX_CLOCK_EXT,
-        .setup_resources   = lp5523_setup,
-        .release_resources = lp5523_release,
-        .enable            = lp5523_enable,
-};
diff --git a/Documentation/leds/leds-lp5562.rst b/Documentation/leds/leds-lp5562.rst
new file mode 100644
index 000000000000..79bbb2487ff6
--- /dev/null
+++ b/Documentation/leds/leds-lp5562.rst
@@ -0,0 +1,137 @@
+========================
+Kernel driver for lp5562
+========================
+
+* TI LP5562 LED Driver
+
+Author: Milo(Woogyom) Kim <milo.kim@ti.com>
+
+Description
+===========
+
+  LP5562 can drive up to 4 channels. R/G/B and White.
+  LEDs can be controlled directly via the led class control interface.
+
+  All four channels can be also controlled using the engine micro programs.
+  LP5562 has the internal program memory for running various LED patterns.
+  For the details, please refer to 'firmware' section in leds-lp55xx.txt
+
+Device attribute
+================
+
+engine_mux
+  3 Engines are allocated in LP5562, but the number of channel is 4.
+  Therefore each channel should be mapped to the engine number.
+
+  Value: RGB or W
+
+  This attribute is used for programming LED data with the firmware interface.
+  Unlike the LP5521/LP5523/55231, LP5562 has unique feature for the engine mux,
+  so additional sysfs is required
+
+  LED Map
+
+  ===== === ===============================
+  Red   ... Engine 1 (fixed)
+  Green ... Engine 2 (fixed)
+  Blue  ... Engine 3 (fixed)
+  White ... Engine 1 or 2 or 3 (selective)
+  ===== === ===============================
+
+How to load the program data using engine_mux
+=============================================
+
+  Before loading the LP5562 program data, engine_mux should be written between
+  the engine selection and loading the firmware.
+  Engine mux has two different mode, RGB and W.
+  RGB is used for loading RGB program data, W is used for W program data.
+
+  For example, run blinking green channel pattern::
+
+    echo 2 > /sys/bus/i2c/devices/xxxx/select_engine     # 2 is for green channel
+    echo "RGB" > /sys/bus/i2c/devices/xxxx/engine_mux    # engine mux for RGB
+    echo 1 > /sys/class/firmware/lp5562/loading
+    echo "4000600040FF6000" > /sys/class/firmware/lp5562/data
+    echo 0 > /sys/class/firmware/lp5562/loading
+    echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
+
+  To run a blinking white pattern::
+
+    echo 1 or 2 or 3 > /sys/bus/i2c/devices/xxxx/select_engine
+    echo "W" > /sys/bus/i2c/devices/xxxx/engine_mux
+    echo 1 > /sys/class/firmware/lp5562/loading
+    echo "4000600040FF6000" > /sys/class/firmware/lp5562/data
+    echo 0 > /sys/class/firmware/lp5562/loading
+    echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
+
+How to load the predefined patterns
+===================================
+
+  Please refer to 'leds-lp55xx.txt"
+
+Setting Current of Each Channel
+===============================
+
+  Like LP5521 and LP5523/55231, LP5562 provides LED current settings.
+  The 'led_current' and 'max_current' are used.
+
+Example of Platform data
+========================
+
+::
+
+	static struct lp55xx_led_config lp5562_led_config[] = {
+		{
+			.name 		= "R",
+			.chan_nr	= 0,
+			.led_current	= 20,
+			.max_current	= 40,
+		},
+		{
+			.name 		= "G",
+			.chan_nr	= 1,
+			.led_current	= 20,
+			.max_current	= 40,
+		},
+		{
+			.name 		= "B",
+			.chan_nr	= 2,
+			.led_current	= 20,
+			.max_current	= 40,
+		},
+		{
+			.name 		= "W",
+			.chan_nr	= 3,
+			.led_current	= 20,
+			.max_current	= 40,
+		},
+	};
+
+	static int lp5562_setup(void)
+	{
+		/* setup HW resources */
+	}
+
+	static void lp5562_release(void)
+	{
+		/* Release HW resources */
+	}
+
+	static void lp5562_enable(bool state)
+	{
+		/* Control of chip enable signal */
+	}
+
+	static struct lp55xx_platform_data lp5562_platform_data = {
+		.led_config     = lp5562_led_config,
+		.num_channels   = ARRAY_SIZE(lp5562_led_config),
+		.setup_resources   = lp5562_setup,
+		.release_resources = lp5562_release,
+		.enable            = lp5562_enable,
+	};
+
+To configure the platform specific data, lp55xx_platform_data structure is used
+
+
+If the current is set to 0 in the platform data, that channel is
+disabled and it is not visible in the sysfs.
diff --git a/Documentation/leds/leds-lp5562.txt b/Documentation/leds/leds-lp5562.txt
deleted file mode 100644
index 5a823ff6b393..000000000000
--- a/Documentation/leds/leds-lp5562.txt
+++ /dev/null
@@ -1,120 +0,0 @@
-Kernel driver for LP5562
-========================
-
-* TI LP5562 LED Driver
-
-Author: Milo(Woogyom) Kim <milo.kim@ti.com>
-
-Description
-
-  LP5562 can drive up to 4 channels. R/G/B and White.
-  LEDs can be controlled directly via the led class control interface.
-
-  All four channels can be also controlled using the engine micro programs.
-  LP5562 has the internal program memory for running various LED patterns.
-  For the details, please refer to 'firmware' section in leds-lp55xx.txt
-
-Device attribute: engine_mux
-
-  3 Engines are allocated in LP5562, but the number of channel is 4.
-  Therefore each channel should be mapped to the engine number.
-  Value : RGB or W
-
-  This attribute is used for programming LED data with the firmware interface.
-  Unlike the LP5521/LP5523/55231, LP5562 has unique feature for the engine mux,
-  so additional sysfs is required.
-
-  LED Map
-  Red   ... Engine 1 (fixed)
-  Green ... Engine 2 (fixed)
-  Blue  ... Engine 3 (fixed)
-  White ... Engine 1 or 2 or 3 (selective)
-
-How to load the program data using engine_mux
-
-  Before loading the LP5562 program data, engine_mux should be written between
-  the engine selection and loading the firmware.
-  Engine mux has two different mode, RGB and W.
-  RGB is used for loading RGB program data, W is used for W program data.
-
-  For example, run blinking green channel pattern,
-  echo 2 > /sys/bus/i2c/devices/xxxx/select_engine     # 2 is for green channel
-  echo "RGB" > /sys/bus/i2c/devices/xxxx/engine_mux    # engine mux for RGB
-  echo 1 > /sys/class/firmware/lp5562/loading
-  echo "4000600040FF6000" > /sys/class/firmware/lp5562/data
-  echo 0 > /sys/class/firmware/lp5562/loading
-  echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
-
-  To run a blinking white pattern,
-  echo 1 or 2 or 3 > /sys/bus/i2c/devices/xxxx/select_engine
-  echo "W" > /sys/bus/i2c/devices/xxxx/engine_mux
-  echo 1 > /sys/class/firmware/lp5562/loading
-  echo "4000600040FF6000" > /sys/class/firmware/lp5562/data
-  echo 0 > /sys/class/firmware/lp5562/loading
-  echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
-
-How to load the predefined patterns
-
-  Please refer to 'leds-lp55xx.txt"
-
-Setting Current of Each Channel
-
-  Like LP5521 and LP5523/55231, LP5562 provides LED current settings.
-  The 'led_current' and 'max_current' are used.
-
-(Example of Platform data)
-
-To configure the platform specific data, lp55xx_platform_data structure is used.
-
-static struct lp55xx_led_config lp5562_led_config[] = {
-	{
-		.name 		= "R",
-		.chan_nr	= 0,
-		.led_current	= 20,
-		.max_current	= 40,
-	},
-	{
-		.name 		= "G",
-		.chan_nr	= 1,
-		.led_current	= 20,
-		.max_current	= 40,
-	},
-	{
-		.name 		= "B",
-		.chan_nr	= 2,
-		.led_current	= 20,
-		.max_current	= 40,
-	},
-	{
-		.name 		= "W",
-		.chan_nr	= 3,
-		.led_current	= 20,
-		.max_current	= 40,
-	},
-};
-
-static int lp5562_setup(void)
-{
-	/* setup HW resources */
-}
-
-static void lp5562_release(void)
-{
-	/* Release HW resources */
-}
-
-static void lp5562_enable(bool state)
-{
-	/* Control of chip enable signal */
-}
-
-static struct lp55xx_platform_data lp5562_platform_data = {
-        .led_config     = lp5562_led_config,
-        .num_channels   = ARRAY_SIZE(lp5562_led_config),
-        .setup_resources   = lp5562_setup,
-        .release_resources = lp5562_release,
-        .enable            = lp5562_enable,
-};
-
-If the current is set to 0 in the platform data, that channel is
-disabled and it is not visible in the sysfs.
diff --git a/Documentation/leds/leds-lp55xx.rst b/Documentation/leds/leds-lp55xx.rst
new file mode 100644
index 000000000000..632e41cec0b5
--- /dev/null
+++ b/Documentation/leds/leds-lp55xx.rst
@@ -0,0 +1,224 @@
+=================================================
+LP5521/LP5523/LP55231/LP5562/LP8501 Common Driver
+=================================================
+
+Authors: Milo(Woogyom) Kim <milo.kim@ti.com>
+
+Description
+-----------
+LP5521, LP5523/55231, LP5562 and LP8501 have common features as below.
+
+  Register access via the I2C
+  Device initialization/deinitialization
+  Create LED class devices for multiple output channels
+  Device attributes for user-space interface
+  Program memory for running LED patterns
+
+The LP55xx common driver provides these features using exported functions.
+
+  lp55xx_init_device() / lp55xx_deinit_device()
+  lp55xx_register_leds() / lp55xx_unregister_leds()
+  lp55xx_regsister_sysfs() / lp55xx_unregister_sysfs()
+
+( Driver Structure Data )
+
+In lp55xx common driver, two different data structure is used.
+
+* lp55xx_led
+    control multi output LED channels such as led current, channel index.
+* lp55xx_chip
+    general chip control such like the I2C and platform data.
+
+For example, LP5521 has maximum 3 LED channels.
+LP5523/55231 has 9 output channels::
+
+  lp55xx_chip for LP5521 ... lp55xx_led #1
+			     lp55xx_led #2
+			     lp55xx_led #3
+
+  lp55xx_chip for LP5523 ... lp55xx_led #1
+			     lp55xx_led #2
+				   .
+				   .
+			     lp55xx_led #9
+
+( Chip Dependent Code )
+
+To support device specific configurations, special structure
+'lpxx_device_config' is used.
+
+  - Maximum number of channels
+  - Reset command, chip enable command
+  - Chip specific initialization
+  - Brightness control register access
+  - Setting LED output current
+  - Program memory address access for running patterns
+  - Additional device specific attributes
+
+( Firmware Interface )
+
+LP55xx family devices have the internal program memory for running
+various LED patterns.
+
+This pattern data is saved as a file in the user-land or
+hex byte string is written into the memory through the I2C.
+
+LP55xx common driver supports the firmware interface.
+
+LP55xx chips have three program engines.
+
+To load and run the pattern, the programming sequence is following.
+
+  (1) Select an engine number (1/2/3)
+  (2) Mode change to load
+  (3) Write pattern data into selected area
+  (4) Mode change to run
+
+The LP55xx common driver provides simple interfaces as below.
+
+select_engine:
+	Select which engine is used for running program
+run_engine:
+	Start program which is loaded via the firmware interface
+firmware:
+	Load program data
+
+In case of LP5523, one more command is required, 'enginex_leds'.
+It is used for selecting LED output(s) at each engine number.
+In more details, please refer to 'leds-lp5523.txt'.
+
+For example, run blinking pattern in engine #1 of LP5521::
+
+	echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
+	echo 1 > /sys/class/firmware/lp5521/loading
+	echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
+	echo 0 > /sys/class/firmware/lp5521/loading
+	echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
+
+For example, run blinking pattern in engine #3 of LP55231
+
+Two LEDs are configured as pattern output channels::
+
+	echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
+	echo 1 > /sys/class/firmware/lp55231/loading
+	echo "9d0740ff7e0040007e00a0010000" > /sys/class/firmware/lp55231/data
+	echo 0 > /sys/class/firmware/lp55231/loading
+	echo "000001100" > /sys/bus/i2c/devices/xxxx/engine3_leds
+	echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
+
+To start blinking patterns in engine #2 and #3 simultaneously::
+
+	for idx in 2 3
+	do
+	echo $idx > /sys/class/leds/red/device/select_engine
+	sleep 0.1
+	echo 1 > /sys/class/firmware/lp5521/loading
+	echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
+	echo 0 > /sys/class/firmware/lp5521/loading
+	done
+	echo 1 > /sys/class/leds/red/device/run_engine
+
+Here is another example for LP5523.
+
+Full LED strings are selected by 'engine2_leds'::
+
+	echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
+	echo 1 > /sys/class/firmware/lp5523/loading
+	echo "9d80400004ff05ff437f0000" > /sys/class/firmware/lp5523/data
+	echo 0 > /sys/class/firmware/lp5523/loading
+	echo "111111111" > /sys/bus/i2c/devices/xxxx/engine2_leds
+	echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
+
+As soon as 'loading' is set to 0, registered callback is called.
+Inside the callback, the selected engine is loaded and memory is updated.
+To run programmed pattern, 'run_engine' attribute should be enabled.
+
+The pattern sequence of LP8501 is similar to LP5523.
+
+However pattern data is specific.
+
+Ex 1) Engine 1 is used::
+
+	echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
+	echo 1 > /sys/class/firmware/lp8501/loading
+	echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
+	echo 0 > /sys/class/firmware/lp8501/loading
+	echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
+
+Ex 2) Engine 2 and 3 are used at the same time::
+
+	echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
+	sleep 1
+	echo 1 > /sys/class/firmware/lp8501/loading
+	echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
+	echo 0 > /sys/class/firmware/lp8501/loading
+	sleep 1
+	echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
+	sleep 1
+	echo 1 > /sys/class/firmware/lp8501/loading
+	echo "9d0340ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
+	echo 0 > /sys/class/firmware/lp8501/loading
+	sleep 1
+	echo 1 > /sys/class/leds/d1/device/run_engine
+
+( 'run_engine' and 'firmware_cb' )
+
+The sequence of running the program data is common.
+
+But each device has own specific register addresses for commands.
+
+To support this, 'run_engine' and 'firmware_cb' are configurable in each driver.
+
+run_engine:
+	Control the selected engine
+firmware_cb:
+	The callback function after loading the firmware is done.
+
+	Chip specific commands for loading and updating program memory.
+
+( Predefined pattern data )
+
+Without the firmware interface, LP55xx driver provides another method for
+loading a LED pattern. That is 'predefined' pattern.
+
+A predefined pattern is defined in the platform data and load it(or them)
+via the sysfs if needed.
+
+To use the predefined pattern concept, 'patterns' and 'num_patterns' should be
+configured.
+
+Example of predefined pattern data::
+
+  /* mode_1: blinking data */
+  static const u8 mode_1[] = {
+		0x40, 0x00, 0x60, 0x00, 0x40, 0xFF, 0x60, 0x00,
+		};
+
+  /* mode_2: always on */
+  static const u8 mode_2[] = { 0x40, 0xFF, };
+
+  struct lp55xx_predef_pattern board_led_patterns[] = {
+	{
+		.r = mode_1,
+		.size_r = ARRAY_SIZE(mode_1),
+	},
+	{
+		.b = mode_2,
+		.size_b = ARRAY_SIZE(mode_2),
+	},
+  }
+
+  struct lp55xx_platform_data lp5562_pdata = {
+  ...
+	.patterns      = board_led_patterns,
+	.num_patterns  = ARRAY_SIZE(board_led_patterns),
+  };
+
+Then, mode_1 and mode_2 can be run via through the sysfs::
+
+  echo 1 > /sys/bus/i2c/devices/xxxx/led_pattern    # red blinking LED pattern
+  echo 2 > /sys/bus/i2c/devices/xxxx/led_pattern    # blue LED always on
+
+To stop running pattern::
+
+  echo 0 > /sys/bus/i2c/devices/xxxx/led_pattern
diff --git a/Documentation/leds/leds-lp55xx.txt b/Documentation/leds/leds-lp55xx.txt
deleted file mode 100644
index e23fa91ea722..000000000000
--- a/Documentation/leds/leds-lp55xx.txt
+++ /dev/null
@@ -1,194 +0,0 @@
-LP5521/LP5523/LP55231/LP5562/LP8501 Common Driver
-=================================================
-
-Authors: Milo(Woogyom) Kim <milo.kim@ti.com>
-
-Description
------------
-LP5521, LP5523/55231, LP5562 and LP8501 have common features as below.
-
-  Register access via the I2C
-  Device initialization/deinitialization
-  Create LED class devices for multiple output channels
-  Device attributes for user-space interface
-  Program memory for running LED patterns
-
-The LP55xx common driver provides these features using exported functions.
-  lp55xx_init_device() / lp55xx_deinit_device()
-  lp55xx_register_leds() / lp55xx_unregister_leds()
-  lp55xx_regsister_sysfs() / lp55xx_unregister_sysfs()
-
-( Driver Structure Data )
-
-In lp55xx common driver, two different data structure is used.
-
-o lp55xx_led
-  control multi output LED channels such as led current, channel index.
-o lp55xx_chip
-  general chip control such like the I2C and platform data.
-
-For example, LP5521 has maximum 3 LED channels.
-LP5523/55231 has 9 output channels.
-
-lp55xx_chip for LP5521 ... lp55xx_led #1
-                           lp55xx_led #2
-                           lp55xx_led #3
-
-lp55xx_chip for LP5523 ... lp55xx_led #1
-                           lp55xx_led #2
-                                 .
-                                 .
-                           lp55xx_led #9
-
-( Chip Dependent Code )
-
-To support device specific configurations, special structure
-'lpxx_device_config' is used.
-
-  Maximum number of channels
-  Reset command, chip enable command
-  Chip specific initialization
-  Brightness control register access
-  Setting LED output current
-  Program memory address access for running patterns
-  Additional device specific attributes
-
-( Firmware Interface )
-
-LP55xx family devices have the internal program memory for running
-various LED patterns.
-This pattern data is saved as a file in the user-land or
-hex byte string is written into the memory through the I2C.
-LP55xx common driver supports the firmware interface.
-
-LP55xx chips have three program engines.
-To load and run the pattern, the programming sequence is following.
-  (1) Select an engine number (1/2/3)
-  (2) Mode change to load
-  (3) Write pattern data into selected area
-  (4) Mode change to run
-
-The LP55xx common driver provides simple interfaces as below.
-select_engine : Select which engine is used for running program
-run_engine    : Start program which is loaded via the firmware interface
-firmware      : Load program data
-
-In case of LP5523, one more command is required, 'enginex_leds'.
-It is used for selecting LED output(s) at each engine number.
-In more details, please refer to 'leds-lp5523.txt'.
-
-For example, run blinking pattern in engine #1 of LP5521
-echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
-echo 1 > /sys/class/firmware/lp5521/loading
-echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
-echo 0 > /sys/class/firmware/lp5521/loading
-echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
-
-For example, run blinking pattern in engine #3 of LP55231
-Two LEDs are configured as pattern output channels.
-echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
-echo 1 > /sys/class/firmware/lp55231/loading
-echo "9d0740ff7e0040007e00a0010000" > /sys/class/firmware/lp55231/data
-echo 0 > /sys/class/firmware/lp55231/loading
-echo "000001100" > /sys/bus/i2c/devices/xxxx/engine3_leds
-echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
-
-To start blinking patterns in engine #2 and #3 simultaneously,
-for idx in 2 3
-do
-  echo $idx > /sys/class/leds/red/device/select_engine
-  sleep 0.1
-  echo 1 > /sys/class/firmware/lp5521/loading
-  echo "4000600040FF6000" > /sys/class/firmware/lp5521/data
-  echo 0 > /sys/class/firmware/lp5521/loading
-done
-echo 1 > /sys/class/leds/red/device/run_engine
-
-Here is another example for LP5523.
-Full LED strings are selected by 'engine2_leds'.
-echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
-echo 1 > /sys/class/firmware/lp5523/loading
-echo "9d80400004ff05ff437f0000" > /sys/class/firmware/lp5523/data
-echo 0 > /sys/class/firmware/lp5523/loading
-echo "111111111" > /sys/bus/i2c/devices/xxxx/engine2_leds
-echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
-
-As soon as 'loading' is set to 0, registered callback is called.
-Inside the callback, the selected engine is loaded and memory is updated.
-To run programmed pattern, 'run_engine' attribute should be enabled.
-
-The pattern sequence of LP8501 is similar to LP5523.
-However pattern data is specific.
-Ex 1) Engine 1 is used
-echo 1 > /sys/bus/i2c/devices/xxxx/select_engine
-echo 1 > /sys/class/firmware/lp8501/loading
-echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
-echo 0 > /sys/class/firmware/lp8501/loading
-echo 1 > /sys/bus/i2c/devices/xxxx/run_engine
-
-Ex 2) Engine 2 and 3 are used at the same time
-echo 2 > /sys/bus/i2c/devices/xxxx/select_engine
-sleep 1
-echo 1 > /sys/class/firmware/lp8501/loading
-echo "9d0140ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
-echo 0 > /sys/class/firmware/lp8501/loading
-sleep 1
-echo 3 > /sys/bus/i2c/devices/xxxx/select_engine
-sleep 1
-echo 1 > /sys/class/firmware/lp8501/loading
-echo "9d0340ff7e0040007e00a001c000" > /sys/class/firmware/lp8501/data
-echo 0 > /sys/class/firmware/lp8501/loading
-sleep 1
-echo 1 > /sys/class/leds/d1/device/run_engine
-
-( 'run_engine' and 'firmware_cb' )
-The sequence of running the program data is common.
-But each device has own specific register addresses for commands.
-To support this, 'run_engine' and 'firmware_cb' are configurable in each driver.
-run_engine  : Control the selected engine
-firmware_cb : The callback function after loading the firmware is done.
-              Chip specific commands for loading and updating program memory.
-
-( Predefined pattern data )
-
-Without the firmware interface, LP55xx driver provides another method for
-loading a LED pattern. That is 'predefined' pattern.
-A predefined pattern is defined in the platform data and load it(or them)
-via the sysfs if needed.
-To use the predefined pattern concept, 'patterns' and 'num_patterns' should be
-configured.
-
-  Example of predefined pattern data:
-
-  /* mode_1: blinking data */
-  static const u8 mode_1[] = {
-		0x40, 0x00, 0x60, 0x00, 0x40, 0xFF, 0x60, 0x00,
-		};
-
-  /* mode_2: always on */
-  static const u8 mode_2[] = { 0x40, 0xFF, };
-
-  struct lp55xx_predef_pattern board_led_patterns[] = {
-	{
-		.r = mode_1,
-		.size_r = ARRAY_SIZE(mode_1),
-	},
-	{
-		.b = mode_2,
-		.size_b = ARRAY_SIZE(mode_2),
-	},
-  }
-
-  struct lp55xx_platform_data lp5562_pdata = {
-  ...
-	.patterns      = board_led_patterns,
-	.num_patterns  = ARRAY_SIZE(board_led_patterns),
-  };
-
-Then, mode_1 and mode_2 can be run via through the sysfs.
-
-  echo 1 > /sys/bus/i2c/devices/xxxx/led_pattern    # red blinking LED pattern
-  echo 2 > /sys/bus/i2c/devices/xxxx/led_pattern    # blue LED always on
-
-To stop running pattern,
-  echo 0 > /sys/bus/i2c/devices/xxxx/led_pattern
diff --git a/Documentation/leds/leds-mlxcpld.rst b/Documentation/leds/leds-mlxcpld.rst
new file mode 100644
index 000000000000..528582429e0b
--- /dev/null
+++ b/Documentation/leds/leds-mlxcpld.rst
@@ -0,0 +1,118 @@
+=======================================
+Kernel driver for Mellanox systems LEDs
+=======================================
+
+Provide system LED support for the nex Mellanox systems:
+"msx6710", "msx6720", "msb7700", "msn2700", "msx1410",
+"msn2410", "msb7800", "msn2740", "msn2100".
+
+Description
+-----------
+Driver provides the following LEDs for the systems "msx6710", "msx6720",
+"msb7700", "msn2700", "msx1410", "msn2410", "msb7800", "msn2740":
+
+  - mlxcpld:fan1:green
+  - mlxcpld:fan1:red
+  - mlxcpld:fan2:green
+  - mlxcpld:fan2:red
+  - mlxcpld:fan3:green
+  - mlxcpld:fan3:red
+  - mlxcpld:fan4:green
+  - mlxcpld:fan4:red
+  - mlxcpld:psu:green
+  - mlxcpld:psu:red
+  - mlxcpld:status:green
+  - mlxcpld:status:red
+
+ "status"
+  - CPLD reg offset: 0x20
+  - Bits [3:0]
+
+ "psu"
+  - CPLD reg offset: 0x20
+  - Bits [7:4]
+
+ "fan1"
+  - CPLD reg offset: 0x21
+  - Bits [3:0]
+
+ "fan2"
+  - CPLD reg offset: 0x21
+  - Bits [7:4]
+
+ "fan3"
+  - CPLD reg offset: 0x22
+  - Bits [3:0]
+
+ "fan4"
+  - CPLD reg offset: 0x22
+  - Bits [7:4]
+
+ Color mask for all the above LEDs:
+
+  [bit3,bit2,bit1,bit0] or
+  [bit7,bit6,bit5,bit4]:
+
+	- [0,0,0,0] = LED OFF
+	- [0,1,0,1] = Red static ON
+	- [1,1,0,1] = Green static ON
+	- [0,1,1,0] = Red blink 3Hz
+	- [1,1,1,0] = Green blink 3Hz
+	- [0,1,1,1] = Red blink 6Hz
+	- [1,1,1,1] = Green blink 6Hz
+
+Driver provides the following LEDs for the system "msn2100":
+
+  - mlxcpld:fan:green
+  - mlxcpld:fan:red
+  - mlxcpld:psu1:green
+  - mlxcpld:psu1:red
+  - mlxcpld:psu2:green
+  - mlxcpld:psu2:red
+  - mlxcpld:status:green
+  - mlxcpld:status:red
+  - mlxcpld:uid:blue
+
+ "status"
+  - CPLD reg offset: 0x20
+  - Bits [3:0]
+
+ "fan"
+  - CPLD reg offset: 0x21
+  - Bits [3:0]
+
+ "psu1"
+  - CPLD reg offset: 0x23
+  - Bits [3:0]
+
+ "psu2"
+  - CPLD reg offset: 0x23
+  - Bits [7:4]
+
+ "uid"
+  - CPLD reg offset: 0x24
+  - Bits [3:0]
+
+ Color mask for all the above LEDs, excepted uid:
+
+  [bit3,bit2,bit1,bit0] or
+  [bit7,bit6,bit5,bit4]:
+
+	- [0,0,0,0] = LED OFF
+	- [0,1,0,1] = Red static ON
+	- [1,1,0,1] = Green static ON
+	- [0,1,1,0] = Red blink 3Hz
+	- [1,1,1,0] = Green blink 3Hz
+	- [0,1,1,1] = Red blink 6Hz
+	- [1,1,1,1] = Green blink 6Hz
+
+ Color mask for uid LED:
+  [bit3,bit2,bit1,bit0]:
+
+	- [0,0,0,0] = LED OFF
+	- [1,1,0,1] = Blue static ON
+	- [1,1,1,0] = Blue blink 3Hz
+	- [1,1,1,1] = Blue blink 6Hz
+
+Driver supports HW blinking at 3Hz and 6Hz frequency (50% duty cycle).
+For 3Hz duty cylce is about 167 msec, for 6Hz is about 83 msec.
diff --git a/Documentation/leds/leds-mlxcpld.txt b/Documentation/leds/leds-mlxcpld.txt
deleted file mode 100644
index a0e8fd457117..000000000000
--- a/Documentation/leds/leds-mlxcpld.txt
+++ /dev/null
@@ -1,110 +0,0 @@
-Kernel driver for Mellanox systems LEDs
-=======================================
-
-Provide system LED support for the nex Mellanox systems:
-"msx6710", "msx6720", "msb7700", "msn2700", "msx1410",
-"msn2410", "msb7800", "msn2740", "msn2100".
-
-Description
------------
-Driver provides the following LEDs for the systems "msx6710", "msx6720",
-"msb7700", "msn2700", "msx1410", "msn2410", "msb7800", "msn2740":
-  mlxcpld:fan1:green
-  mlxcpld:fan1:red
-  mlxcpld:fan2:green
-  mlxcpld:fan2:red
-  mlxcpld:fan3:green
-  mlxcpld:fan3:red
-  mlxcpld:fan4:green
-  mlxcpld:fan4:red
-  mlxcpld:psu:green
-  mlxcpld:psu:red
-  mlxcpld:status:green
-  mlxcpld:status:red
-
- "status"
-  CPLD reg offset: 0x20
-  Bits [3:0]
-
- "psu"
-  CPLD reg offset: 0x20
-  Bits [7:4]
-
- "fan1"
-  CPLD reg offset: 0x21
-  Bits [3:0]
-
- "fan2"
-  CPLD reg offset: 0x21
-  Bits [7:4]
-
- "fan3"
-  CPLD reg offset: 0x22
-  Bits [3:0]
-
- "fan4"
-  CPLD reg offset: 0x22
-  Bits [7:4]
-
- Color mask for all the above LEDs:
-  [bit3,bit2,bit1,bit0] or
-  [bit7,bit6,bit5,bit4]:
-	[0,0,0,0] = LED OFF
-	[0,1,0,1] = Red static ON
-	[1,1,0,1] = Green static ON
-	[0,1,1,0] = Red blink 3Hz
-	[1,1,1,0] = Green blink 3Hz
-	[0,1,1,1] = Red blink 6Hz
-	[1,1,1,1] = Green blink 6Hz
-
-Driver provides the following LEDs for the system "msn2100":
-  mlxcpld:fan:green
-  mlxcpld:fan:red
-  mlxcpld:psu1:green
-  mlxcpld:psu1:red
-  mlxcpld:psu2:green
-  mlxcpld:psu2:red
-  mlxcpld:status:green
-  mlxcpld:status:red
-  mlxcpld:uid:blue
-
- "status"
-  CPLD reg offset: 0x20
-  Bits [3:0]
-
- "fan"
-  CPLD reg offset: 0x21
-  Bits [3:0]
-
- "psu1"
-  CPLD reg offset: 0x23
-  Bits [3:0]
-
- "psu2"
-  CPLD reg offset: 0x23
-  Bits [7:4]
-
- "uid"
-  CPLD reg offset: 0x24
-  Bits [3:0]
-
- Color mask for all the above LEDs, excepted uid:
-  [bit3,bit2,bit1,bit0] or
-  [bit7,bit6,bit5,bit4]:
-	[0,0,0,0] = LED OFF
-	[0,1,0,1] = Red static ON
-	[1,1,0,1] = Green static ON
-	[0,1,1,0] = Red blink 3Hz
-	[1,1,1,0] = Green blink 3Hz
-	[0,1,1,1] = Red blink 6Hz
-	[1,1,1,1] = Green blink 6Hz
-
- Color mask for uid LED:
-  [bit3,bit2,bit1,bit0]:
-	[0,0,0,0] = LED OFF
-	[1,1,0,1] = Blue static ON
-	[1,1,1,0] = Blue blink 3Hz
-	[1,1,1,1] = Blue blink 6Hz
-
-Driver supports HW blinking at 3Hz and 6Hz frequency (50% duty cycle).
-For 3Hz duty cylce is about 167 msec, for 6Hz is about 83 msec.
diff --git a/Documentation/leds/ledtrig-oneshot.txt b/Documentation/leds/ledtrig-oneshot.rst
similarity index 90%
rename from Documentation/leds/ledtrig-oneshot.txt
rename to Documentation/leds/ledtrig-oneshot.rst
index fe57474a12e2..69fa3ea1d554 100644
--- a/Documentation/leds/ledtrig-oneshot.txt
+++ b/Documentation/leds/ledtrig-oneshot.rst
@@ -1,3 +1,4 @@
+====================
 One-shot LED Trigger
 ====================
 
@@ -17,27 +18,27 @@ additional "invert" property specifies if the LED has to stay off (normal) or
 on (inverted) when not rearmed.
 
 The trigger can be activated from user space on led class devices as shown
-below:
+below::
 
   echo oneshot > trigger
 
 This adds sysfs attributes to the LED that are documented in:
 Documentation/ABI/testing/sysfs-class-led-trigger-oneshot
 
-Example use-case: network devices, initialization:
+Example use-case: network devices, initialization::
 
   echo oneshot > trigger # set trigger for this led
   echo 33 > delay_on     # blink at 1 / (33 + 33) Hz on continuous traffic
   echo 33 > delay_off
 
-interface goes up:
+interface goes up::
 
   echo 1 > invert # set led as normally-on, turn the led on
 
-packet received/transmitted:
+packet received/transmitted::
 
   echo 1 > shot # led starts blinking, ignored if already blinking
 
-interface goes down
+interface goes down::
 
   echo 0 > invert # set led as normally-off, turn the led off
diff --git a/Documentation/leds/ledtrig-transient.txt b/Documentation/leds/ledtrig-transient.rst
similarity index 81%
rename from Documentation/leds/ledtrig-transient.txt
rename to Documentation/leds/ledtrig-transient.rst
index 3bd38b487df1..d921dc830cd0 100644
--- a/Documentation/leds/ledtrig-transient.txt
+++ b/Documentation/leds/ledtrig-transient.rst
@@ -1,3 +1,4 @@
+=====================
 LED Transient Trigger
 =====================
 
@@ -62,12 +63,13 @@ non-transient state. When driver gets suspended, irrespective of the transient
 state, the LED state changes to LED_OFF.
 
 Transient trigger can be enabled and disabled from user space on led class
-devices, that support this trigger as shown below:
+devices, that support this trigger as shown below::
 
-echo transient > trigger
-echo none > trigger
+	echo transient > trigger
+	echo none > trigger
 
-NOTE: Add a new property trigger state to control the state.
+NOTE:
+	Add a new property trigger state to control the state.
 
 This trigger exports three properties, activate, state, and duration. When
 transient trigger is activated these properties are set to default values.
@@ -79,7 +81,8 @@ transient trigger is activated these properties are set to default values.
 - state allows user to specify a transient state to be held for the specified
   duration.
 
-	activate - one shot timer activate mechanism.
+	activate
+	      - one shot timer activate mechanism.
 		1 when activated, 0 when deactivated.
 		default value is zero when transient trigger is enabled,
 		to allow duration to be set.
@@ -89,12 +92,14 @@ transient trigger is activated these properties are set to default values.
 		deactivated state indicates that there is no active timer
 		running.
 
-	duration - one shot timer value. When activate is set, duration value
+	duration
+	      - one shot timer value. When activate is set, duration value
 		is used to start a timer that runs once. This value doesn't
 		get changed by the trigger unless user does a set via
 		echo new_value > duration
 
-	state - transient state to be held. It has two values 0 or 1. 0 maps
+	state
+	      - transient state to be held. It has two values 0 or 1. 0 maps
 		to LED_OFF and 1 maps to LED_FULL. The specified state is
 		held for the duration of the one shot timer and then the
 		state gets changed to the non-transient state which is the
@@ -114,39 +119,49 @@ When timer expires activate goes back to deactivated state, duration is left
 at the set value to be used when activate is set at a future time. This will
 allow user app to set the time once and activate it to run it once for the
 specified value as needed. When timer expires, state is restored to the
-non-transient state which is the inverse of the transient state.
+non-transient state which is the inverse of the transient state:
 
-	echo 1 > activate - starts timer = duration when duration is not 0.
-	echo 0 > activate - cancels currently running timer.
-	echo n > duration - stores timer value to be used upon next
-                            activate. Currently active timer if
-                            any, continues to run for the specified time.
-	echo 0 > duration - stores timer value to be used upon next
-                            activate. Currently active timer if any,
-                            continues to run for the specified time.
-	echo 1 > state    - stores desired transient state LED_FULL to be
+	=================   ===============================================
+	echo 1 > activate   starts timer = duration when duration is not 0.
+	echo 0 > activate   cancels currently running timer.
+	echo n > duration   stores timer value to be used upon next
+			    activate. Currently active timer if
+			    any, continues to run for the specified time.
+	echo 0 > duration   stores timer value to be used upon next
+			    activate. Currently active timer if any,
+			    continues to run for the specified time.
+	echo 1 > state      stores desired transient state LED_FULL to be
 			    held for the specified duration.
-	echo 0 > state    - stores desired transient state LED_OFF to be
+	echo 0 > state      stores desired transient state LED_OFF to be
 			    held for the specified duration.
+	=================   ===============================================
+
+What is not supported
+=====================
 
-What is not supported:
-======================
 - Timer activation is one shot and extending and/or shortening the timer
   is not supported.
 
-Example use-case 1:
+Examples
+========
+
+use-case 1::
+
 	echo transient > trigger
 	echo n > duration
 	echo 1 > state
-repeat the following step as needed:
+
+repeat the following step as needed::
+
 	echo 1 > activate - start timer = duration to run once
 	echo 1 > activate - start timer = duration to run once
 	echo none > trigger
 
 This trigger is intended to be used for for the following example use cases:
+
  - Control of vibrate (phones, tablets etc.) hardware by user space app.
  - Use of LED by user space app as activity indicator.
  - Use of LED by user space app as a kind of watchdog indicator -- as
-       long as the app is alive, it can keep the LED illuminated, if it dies
-       the LED will be extinguished automatically.
+   long as the app is alive, it can keep the LED illuminated, if it dies
+   the LED will be extinguished automatically.
  - Use by any user space app that needs a transient GPIO output.
diff --git a/Documentation/leds/ledtrig-usbport.txt b/Documentation/leds/ledtrig-usbport.rst
similarity index 86%
rename from Documentation/leds/ledtrig-usbport.txt
rename to Documentation/leds/ledtrig-usbport.rst
index 69f54bfb4789..37c2505bfd57 100644
--- a/Documentation/leds/ledtrig-usbport.txt
+++ b/Documentation/leds/ledtrig-usbport.rst
@@ -1,3 +1,4 @@
+====================
 USB port LED trigger
 ====================
 
@@ -10,14 +11,18 @@ listed as separated entries in a "ports" subdirectory. Selecting is handled by
 echoing "1" to a chosen port.
 
 Please note that this trigger allows selecting multiple USB ports for a single
-LED. This can be useful in two cases:
+LED.
+
+This can be useful in two cases:
 
 1) Device with single USB LED and few physical ports
+====================================================
 
 In such a case LED will be turned on as long as there is at least one connected
 USB device.
 
 2) Device with a physical port handled by few controllers
+=========================================================
 
 Some devices may have one controller per PHY standard. E.g. USB 3.0 physical
 port may be handled by ohci-platform, ehci-platform and xhci-hcd. If there is
@@ -25,14 +30,14 @@ only one LED user will most likely want to assign ports from all 3 hubs.
 
 
 This trigger can be activated from user space on led class devices as shown
-below:
+below::
 
   echo usbport > trigger
 
 This adds sysfs attributes to the LED that are documented in:
 Documentation/ABI/testing/sysfs-class-led-trigger-usbport
 
-Example use-case:
+Example use-case::
 
   echo usbport > trigger
   echo 1 > ports/usb1-port1
diff --git a/Documentation/leds/uleds.txt b/Documentation/leds/uleds.rst
similarity index 95%
rename from Documentation/leds/uleds.txt
rename to Documentation/leds/uleds.rst
index 13e375a580f9..83221098009c 100644
--- a/Documentation/leds/uleds.txt
+++ b/Documentation/leds/uleds.rst
@@ -1,3 +1,4 @@
+==============
 Userspace LEDs
 ==============
 
@@ -10,12 +11,12 @@ Usage
 
 When the driver is loaded, a character device is created at /dev/uleds. To
 create a new LED class device, open /dev/uleds and write a uleds_user_dev
-structure to it (found in kernel public header file linux/uleds.h).
+structure to it (found in kernel public header file linux/uleds.h)::
 
     #define LED_MAX_NAME_SIZE 64
 
     struct uleds_user_dev {
-        char name[LED_MAX_NAME_SIZE];
+	char name[LED_MAX_NAME_SIZE];
     };
 
 A new LED class device will be created with the name given. The name can be
diff --git a/MAINTAINERS b/MAINTAINERS
index f27f50f88638..b7d5faf95e25 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -10175,7 +10175,7 @@ L:	linux-leds@vger.kernel.org
 S:	Supported
 F:	drivers/leds/leds-mlxcpld.c
 F:	drivers/leds/leds-mlxreg.c
-F:	Documentation/leds/leds-mlxcpld.txt
+F:	Documentation/leds/leds-mlxcpld.rst
 
 MELLANOX PLATFORM DRIVER
 M:	Vadim Pasternak <vadimp@mellanox.com>
diff --git a/drivers/leds/trigger/Kconfig b/drivers/leds/trigger/Kconfig
index 7fa9d174a40c..ce9429ca6dde 100644
--- a/drivers/leds/trigger/Kconfig
+++ b/drivers/leds/trigger/Kconfig
@@ -15,7 +15,7 @@ config LEDS_TRIGGER_TIMER
 	  This allows LEDs to be controlled by a programmable timer
 	  via sysfs. Some LED hardware can be programmed to start
 	  blinking the LED without any further software interaction.
-	  For more details read Documentation/leds/leds-class.txt.
+	  For more details read Documentation/leds/leds-class.rst.
 
 	  If unsure, say Y.
 
diff --git a/drivers/leds/trigger/ledtrig-transient.c b/drivers/leds/trigger/ledtrig-transient.c
index a80bb82aacc2..80635183fac8 100644
--- a/drivers/leds/trigger/ledtrig-transient.c
+++ b/drivers/leds/trigger/ledtrig-transient.c
@@ -3,7 +3,7 @@
 // LED Kernel Transient Trigger
 //
 // Transient trigger allows one shot timer activation. Please refer to
-// Documentation/leds/ledtrig-transient.txt for details
+// Documentation/leds/ledtrig-transient.rst for details
 // Copyright (C) 2012 Shuah Khan <shuahkhan@gmail.com>
 //
 // Based on Richard Purdie's ledtrig-timer.c and Atsushi Nemoto's
diff --git a/net/netfilter/Kconfig b/net/netfilter/Kconfig
index dd2af7be3eea..1837734ce85b 100644
--- a/net/netfilter/Kconfig
+++ b/net/netfilter/Kconfig
@@ -906,7 +906,7 @@ config NETFILTER_XT_TARGET_LED
 	    echo netfilter-ssh > /sys/class/leds/<ledname>/trigger
 
 	  For more information on the LEDs available on your system, see
-	  Documentation/leds/leds-class.txt
+	  Documentation/leds/leds-class.rst
 
 config NETFILTER_XT_TARGET_LOG
 	tristate "LOG target support"
-- 
2.21.0

Re: [PATCH v2 20/29] docs: leds: convert to ReST

[Pavel Machek]

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

On Tue 2019-06-18 17:53:38, Mauro Carvalho Chehab wrote:
> Rename the leds documentation files to ReST, add an
> index for them and adjust in order to produce a nice html
> output via the Sphinx build system.
> 
> 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>

Acked-by: Pavel Machek <pavel@ucw.cz>

-- 
(english) http://www.livejournal.com/~pavelmachek
(cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 181 bytes --]

[PATCH v2 21/29] docs: laptops: convert to ReST

[Mauro Carvalho Chehab]

Rename the laptops documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

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>
Acked-by: Andy Shevchenko <andy.shevchenko@gmail.com>
---
 Documentation/ABI/testing/sysfs-block-device  |   2 +-
 .../ABI/testing/sysfs-platform-asus-laptop    |   2 +-
 .../admin-guide/kernel-parameters.txt         |   2 +-
 .../{asus-laptop.txt => asus-laptop.rst}      |  92 ++--
 ...otection.txt => disk-shock-protection.rst} |  32 +-
 Documentation/laptops/index.rst               |  17 +
 .../{laptop-mode.txt => laptop-mode.rst}      | 509 +++++++++---------
 .../{sony-laptop.txt => sony-laptop.rst}      |  58 +-
 .../laptops/{sonypi.txt => sonypi.rst}        |  28 +-
 .../{thinkpad-acpi.txt => thinkpad-acpi.rst}  | 363 ++++++++-----
 .../{toshiba_haps.txt => toshiba_haps.rst}    |  47 +-
 Documentation/sysctl/vm.txt                   |   4 +-
 MAINTAINERS                                   |   2 +-
 drivers/char/Kconfig                          |   2 +-
 drivers/platform/x86/Kconfig                  |   4 +-
 15 files changed, 660 insertions(+), 504 deletions(-)
 rename Documentation/laptops/{asus-laptop.txt => asus-laptop.rst} (84%)
 rename Documentation/laptops/{disk-shock-protection.txt => disk-shock-protection.rst} (91%)
 create mode 100644 Documentation/laptops/index.rst
 rename Documentation/laptops/{laptop-mode.txt => laptop-mode.rst} (62%)
 rename Documentation/laptops/{sony-laptop.txt => sony-laptop.rst} (85%)
 rename Documentation/laptops/{sonypi.txt => sonypi.rst} (87%)
 rename Documentation/laptops/{thinkpad-acpi.txt => thinkpad-acpi.rst} (89%)
 rename Documentation/laptops/{toshiba_haps.txt => toshiba_haps.rst} (60%)

diff --git a/Documentation/ABI/testing/sysfs-block-device b/Documentation/ABI/testing/sysfs-block-device
index 82ef6eab042d..0d57bbb4fddc 100644
--- a/Documentation/ABI/testing/sysfs-block-device
+++ b/Documentation/ABI/testing/sysfs-block-device
@@ -45,7 +45,7 @@ Description:
 		- Values below -2 are rejected with -EINVAL
 
 		For more information, see
-		Documentation/laptops/disk-shock-protection.txt
+		Documentation/laptops/disk-shock-protection.rst
 
 
 What:		/sys/block/*/device/ncq_prio_enable
diff --git a/Documentation/ABI/testing/sysfs-platform-asus-laptop b/Documentation/ABI/testing/sysfs-platform-asus-laptop
index cd9d667c3da2..d67fa4bafa70 100644
--- a/Documentation/ABI/testing/sysfs-platform-asus-laptop
+++ b/Documentation/ABI/testing/sysfs-platform-asus-laptop
@@ -31,7 +31,7 @@ Description:
 		To control the LED display, use the following :
 		    echo 0x0T000DDD > /sys/devices/platform/asus_laptop/
 		where T control the 3 letters display, and DDD the 3 digits display.
-		The DDD table can be found in Documentation/laptops/asus-laptop.txt
+		The DDD table can be found in Documentation/laptops/asus-laptop.rst
 
 What:		/sys/devices/platform/asus_laptop/bluetooth
 Date:		January 2007
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 3faf37b8b001..7abe677f8c5e 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -4356,7 +4356,7 @@
 			Format: <integer>
 
 	sonypi.*=	[HW] Sony Programmable I/O Control Device driver
-			See Documentation/laptops/sonypi.txt
+			See Documentation/laptops/sonypi.rst
 
 	spectre_v2=	[X86] Control mitigation of Spectre variant 2
 			(indirect branch speculation) vulnerability.
diff --git a/Documentation/laptops/asus-laptop.txt b/Documentation/laptops/asus-laptop.rst
similarity index 84%
rename from Documentation/laptops/asus-laptop.txt
rename to Documentation/laptops/asus-laptop.rst
index 5f2858712aa0..95176321a25a 100644
--- a/Documentation/laptops/asus-laptop.txt
+++ b/Documentation/laptops/asus-laptop.rst
@@ -1,6 +1,9 @@
+==================
 Asus Laptop Extras
+==================
 
 Version 0.1
+
 August 6, 2009
 
 Corentin Chary <corentincj@iksaif.net>
@@ -10,11 +13,12 @@ http://acpi4asus.sf.net/
  It may also support some MEDION, JVC or VICTOR laptops (such as MEDION 9675 or
  VICTOR XP7210 for example). It makes all the extra buttons generate input
  events (like keyboards).
+
  On some models adds support for changing the display brightness and output,
  switching the LCD backlight on and off, and most importantly, allows you to
  blink those fancy LEDs intended for reporting mail and wireless status.
 
-This driver supercedes the old asus_acpi driver.
+This driver supersedes the old asus_acpi driver.
 
 Requirements
 ------------
@@ -49,7 +53,7 @@ Usage
   see some lines like this :
 
       Asus Laptop Extras version 0.42
-        L2D model detected.
+        - L2D model detected.
 
   If it is not the output you have on your laptop, send it (and the laptop's
   DSDT) to me.
@@ -68,9 +72,12 @@ Usage
 LEDs
 ----
 
-  You can modify LEDs be echoing values to /sys/class/leds/asus::*/brightness :
+  You can modify LEDs be echoing values to `/sys/class/leds/asus/*/brightness`::
+
     echo 1 >  /sys/class/leds/asus::mail/brightness
+
   will switch the mail LED on.
+
   You can also know if they are on/off by reading their content and use
   kernel triggers like disk-activity or heartbeat.
 
@@ -81,7 +88,7 @@ Backlight
   /sys/class/backlight/asus-laptop/. Brightness Values are between 0 and 15.
 
 Wireless devices
----------------
+----------------
 
   You can turn the internal Bluetooth adapter on/off with the bluetooth entry
   (only on models with Bluetooth). This usually controls the associated LED.
@@ -93,18 +100,20 @@ Display switching
   Note: the display switching code is currently considered EXPERIMENTAL.
 
   Switching works for the following models:
-    L3800C
-    A2500H
-    L5800C
-    M5200N
-    W1000N (albeit with some glitches)
-    M6700R
-    A6JC
-    F3J
+
+    - L3800C
+    - A2500H
+    - L5800C
+    - M5200N
+    - W1000N (albeit with some glitches)
+    - M6700R
+    - A6JC
+    - F3J
 
   Switching doesn't work for the following:
-    M3700N
-    L2X00D (locks the laptop under certain conditions)
+
+    - M3700N
+    - L2X00D (locks the laptop under certain conditions)
 
   To switch the displays, echo values from 0 to 15 to
   /sys/devices/platform/asus-laptop/display. The significance of those values
@@ -113,48 +122,51 @@ Display switching
   +-------+-----+-----+-----+-----+-----+
   | Bin   | Val | DVI | TV  | CRT | LCD |
   +-------+-----+-----+-----+-----+-----+
-  + 0000  +   0 +     +     +     +     +
+  | 0000  |   0 |     |     |     |     |
   +-------+-----+-----+-----+-----+-----+
-  + 0001  +   1 +     +     +     +  X  +
+  | 0001  |   1 |     |     |     |  X  |
   +-------+-----+-----+-----+-----+-----+
-  + 0010  +   2 +     +     +  X  +     +
+  | 0010  |   2 |     |     |  X  |     |
   +-------+-----+-----+-----+-----+-----+
-  + 0011  +   3 +     +     +  X  +  X  +
+  | 0011  |   3 |     |     |  X  |  X  |
   +-------+-----+-----+-----+-----+-----+
-  + 0100  +   4 +     +  X  +     +     +
+  | 0100  |   4 |     |  X  |     |     |
   +-------+-----+-----+-----+-----+-----+
-  + 0101  +   5 +     +  X  +     + X   +
+  | 0101  |   5 |     |  X  |     | X   |
   +-------+-----+-----+-----+-----+-----+
-  + 0110  +   6 +     +  X  +  X  +     +
+  | 0110  |   6 |     |  X  |  X  |     |
   +-------+-----+-----+-----+-----+-----+
-  + 0111  +   7 +     +  X  +  X  +  X  +
+  | 0111  |   7 |     |  X  |  X  |  X  |
   +-------+-----+-----+-----+-----+-----+
-  + 1000  +   8 +  X  +     +     +     +
+  | 1000  |   8 |  X  |     |     |     |
   +-------+-----+-----+-----+-----+-----+
-  + 1001  +   9 +  X  +     +     +  X  +
+  | 1001  |   9 |  X  |     |     |  X  |
   +-------+-----+-----+-----+-----+-----+
-  + 1010  +  10 +  X  +     +  X  +     +
+  | 1010  |  10 |  X  |     |  X  |     |
   +-------+-----+-----+-----+-----+-----+
-  + 1011  +  11 +  X  +     +  X  +  X  +
+  | 1011  |  11 |  X  |     |  X  |  X  |
   +-------+-----+-----+-----+-----+-----+
-  + 1100  +  12 +  X  +  X  +     +     +
+  | 1100  |  12 |  X  |  X  |     |     |
   +-------+-----+-----+-----+-----+-----+
-  + 1101  +  13 +  X  +  X  +     +  X  +
+  | 1101  |  13 |  X  |  X  |     |  X  |
   +-------+-----+-----+-----+-----+-----+
-  + 1110  +  14 +  X  +  X  +  X  +     +
+  | 1110  |  14 |  X  |  X  |  X  |     |
   +-------+-----+-----+-----+-----+-----+
-  + 1111  +  15 +  X  +  X  +  X  +  X  +
+  | 1111  |  15 |  X  |  X  |  X  |  X  |
   +-------+-----+-----+-----+-----+-----+
 
   In most cases, the appropriate displays must be plugged in for the above
   combinations to work. TV-Out may need to be initialized at boot time.
 
   Debugging:
+
   1) Check whether the Fn+F8 key:
+
      a) does not lock the laptop (try a boot with noapic / nolapic if it does)
      b) generates events (0x6n, where n is the value corresponding to the
         configuration above)
      c) actually works
+
      Record the disp value at every configuration.
   2) Echo values from 0 to 15 to /sys/devices/platform/asus-laptop/display.
      Record its value, note any change. If nothing changes, try a broader range,
@@ -164,7 +176,7 @@ Display switching
 
   Note: on some machines (e.g. L3C), after the module has been loaded, only 0x6n
   events are generated and no actual switching occurs. In such a case, a line
-  like:
+  like::
 
     echo $((10#$arg-60)) > /sys/devices/platform/asus-laptop/display
 
@@ -180,15 +192,16 @@ LED display
   several items of information.
 
   LED display works for the following models:
-    W1000N
-    W1J
 
-  To control the LED display, use the following :
+    - W1000N
+    - W1J
+
+  To control the LED display, use the following::
 
     echo 0x0T000DDD > /sys/devices/platform/asus-laptop/
 
   where T control the 3 letters display, and DDD the 3 digits display,
-  according to the tables below.
+  according to the tables below::
 
          DDD (digits)
          000 to 999 = display digits
@@ -208,8 +221,8 @@ LED display
   For example "echo 0x01000001 >/sys/devices/platform/asus-laptop/ledd"
   would display "DVD001".
 
-Driver options:
----------------
+Driver options
+--------------
 
  Options can be passed to the asus-laptop driver using the standard
  module argument syntax (<param>=<value> when passing the option to the
@@ -219,6 +232,7 @@ Driver options:
 	     wapf: WAPF defines the behavior of the Fn+Fx wlan key
 		   The significance of values is yet to be found, but
 		   most of the time:
+
 		   - 0x0 should do nothing
 		   - 0x1 should allow to control the device with Fn+Fx key.
 		   - 0x4 should send an ACPI event (0x88) while pressing the Fn+Fx key
@@ -237,7 +251,7 @@ Unsupported models
  - ASUS L7300G
  - ASUS L8400
 
-Patches, Errors, Questions:
+Patches, Errors, Questions
 --------------------------
 
  I appreciate any success or failure
@@ -253,5 +267,5 @@ Patches, Errors, Questions:
  Any other comments or patches are also more than welcome.
 
  acpi4asus-user@lists.sourceforge.net
+
  http://sourceforge.net/projects/acpi4asus
-
diff --git a/Documentation/laptops/disk-shock-protection.txt b/Documentation/laptops/disk-shock-protection.rst
similarity index 91%
rename from Documentation/laptops/disk-shock-protection.txt
rename to Documentation/laptops/disk-shock-protection.rst
index 0e6ba2663834..e97c5f78d8c3 100644
--- a/Documentation/laptops/disk-shock-protection.txt
+++ b/Documentation/laptops/disk-shock-protection.rst
@@ -1,17 +1,18 @@
+==========================
 Hard disk shock protection
 ==========================
 
 Author: Elias Oltmanns <eo@nebensachen.de>
+
 Last modified: 2008-10-03
 
 
-0. Contents
------------
+.. 0. Contents
 
-1. Intro
-2. The interface
-3. References
-4. CREDITS
+   1. Intro
+   2. The interface
+   3. References
+   4. CREDITS
 
 
 1. Intro
@@ -36,8 +37,8 @@ that).
 ----------------
 
 For each ATA device, the kernel exports the file
-block/*/device/unload_heads in sysfs (here assumed to be mounted under
-/sys). Access to /sys/block/*/device/unload_heads is denied with
+`block/*/device/unload_heads` in sysfs (here assumed to be mounted under
+/sys). Access to `/sys/block/*/device/unload_heads` is denied with
 -EOPNOTSUPP if the device does not support the unload feature.
 Otherwise, writing an integer value to this file will take the heads
 of the respective drive off the platter and block all I/O operations
@@ -54,18 +55,18 @@ cancel a previously set timeout and resume normal operation
 immediately by specifying a timeout of 0. Values below -2 are rejected
 with -EINVAL (see below for the special meaning of -1 and -2). If the
 timeout specified for a recent head park request has not yet expired,
-reading from /sys/block/*/device/unload_heads will report the number
+reading from `/sys/block/*/device/unload_heads` will report the number
 of milliseconds remaining until normal operation will be resumed;
 otherwise, reading the unload_heads attribute will return 0.
 
 For example, do the following in order to park the heads of drive
-/dev/sda and stop all I/O operations for five seconds:
+/dev/sda and stop all I/O operations for five seconds::
 
-# echo 5000 > /sys/block/sda/device/unload_heads
+	# echo 5000 > /sys/block/sda/device/unload_heads
 
-A simple
+A simple::
 
-# cat /sys/block/sda/device/unload_heads
+	# cat /sys/block/sda/device/unload_heads
 
 will show you how many milliseconds are left before normal operation
 will be resumed.
@@ -112,9 +113,9 @@ unload_heads attribute. If you know that your device really does
 support the unload feature (for instance, because the vendor of your
 laptop or the hard drive itself told you so), then you can tell the
 kernel to enable the usage of this feature for that drive by writing
-the special value -1 to the unload_heads attribute:
+the special value -1 to the unload_heads attribute::
 
-# echo -1 > /sys/block/sda/device/unload_heads
+	# echo -1 > /sys/block/sda/device/unload_heads
 
 will enable the feature for /dev/sda, and giving -2 instead of -1 will
 disable it again.
@@ -135,6 +136,7 @@ for use. Please feel free to add projects that have been the victims
 of my ignorance.
 
 - http://www.thinkwiki.org/wiki/HDAPS
+
   See this page for information about Linux support of the hard disk
   active protection system as implemented in IBM/Lenovo Thinkpads.
 
diff --git a/Documentation/laptops/index.rst b/Documentation/laptops/index.rst
new file mode 100644
index 000000000000..001a30910d09
--- /dev/null
+++ b/Documentation/laptops/index.rst
@@ -0,0 +1,17 @@
+:orphan:
+
+==============
+Laptop Drivers
+==============
+
+.. toctree::
+   :maxdepth: 1
+
+   asus-laptop
+   disk-shock-protection
+   laptop-mode
+   lg-laptop
+   sony-laptop
+   sonypi
+   thinkpad-acpi
+   toshiba_haps
diff --git a/Documentation/laptops/laptop-mode.txt b/Documentation/laptops/laptop-mode.rst
similarity index 62%
rename from Documentation/laptops/laptop-mode.txt
rename to Documentation/laptops/laptop-mode.rst
index 1c707fc9b141..c984c4262f2e 100644
--- a/Documentation/laptops/laptop-mode.txt
+++ b/Documentation/laptops/laptop-mode.rst
@@ -1,8 +1,11 @@
+===============================================
 How to conserve battery power using laptop-mode
------------------------------------------------
+===============================================
 
 Document Author: Bart Samwel (bart@samwel.tk)
+
 Date created: January 2, 2004
+
 Last modified: December 06, 2004
 
 Introduction
@@ -12,17 +15,16 @@ Laptop mode is used to minimize the time that the hard disk needs to be spun up,
 to conserve battery power on laptops. It has been reported to cause significant
 power savings.
 
-Contents
---------
+.. Contents
 
-* Introduction
-* Installation
-* Caveats
-* The Details
-* Tips & Tricks
-* Control script
-* ACPI integration
-* Monitoring tool
+   * Introduction
+   * Installation
+   * Caveats
+   * The Details
+   * Tips & Tricks
+   * Control script
+   * ACPI integration
+   * Monitoring tool
 
 
 Installation
@@ -33,7 +35,7 @@ or anything. Simply install all the files included in this document, and
 laptop mode will automatically be started when you're on battery. For
 your convenience, a tarball containing an installer can be downloaded at:
 
-http://www.samwel.tk/laptop_mode/laptop_mode/
+	http://www.samwel.tk/laptop_mode/laptop_mode/
 
 To configure laptop mode, you need to edit the configuration file, which is
 located in /etc/default/laptop-mode on Debian-based systems, or in
@@ -209,7 +211,7 @@ Tips & Tricks
   this on powerbooks too. I hope that this is a piece of information that
   might be useful to the Laptop Mode patch or its users."
 
-* In syslog.conf, you can prefix entries with a dash ``-'' to omit syncing the
+* In syslog.conf, you can prefix entries with a dash `-` to omit syncing the
   file after every logging. When you're using laptop-mode and your disk doesn't
   spin down, this is a likely culprit.
 
@@ -233,83 +235,82 @@ configuration file
 It should be installed as /etc/default/laptop-mode on Debian, and as
 /etc/sysconfig/laptop-mode on Red Hat, SUSE, Mandrake, and other work-alikes.
 
---------------------CONFIG FILE BEGIN-------------------------------------------
-# Maximum time, in seconds, of hard drive spindown time that you are
-# comfortable with. Worst case, it's possible that you could lose this
-# amount of work if your battery fails you while in laptop mode.
-#MAX_AGE=600
+Config file::
 
-# Automatically disable laptop mode when the number of minutes of battery
-# that you have left goes below this threshold.
-MINIMUM_BATTERY_MINUTES=10
+  # Maximum time, in seconds, of hard drive spindown time that you are
+  # comfortable with. Worst case, it's possible that you could lose this
+  # amount of work if your battery fails you while in laptop mode.
+  #MAX_AGE=600
 
-# Read-ahead, in 512-byte sectors. You can spin down the disk while playing MP3/OGG
-# by setting the disk readahead to 8MB (READAHEAD=16384). Effectively, the disk
-# will read a complete MP3 at once, and will then spin down while the MP3/OGG is
-# playing.
-#READAHEAD=4096
+  # Automatically disable laptop mode when the number of minutes of battery
+  # that you have left goes below this threshold.
+  MINIMUM_BATTERY_MINUTES=10
 
-# Shall we remount journaled fs. with appropriate commit interval? (1=yes)
-#DO_REMOUNTS=1
+  # Read-ahead, in 512-byte sectors. You can spin down the disk while playing MP3/OGG
+  # by setting the disk readahead to 8MB (READAHEAD=16384). Effectively, the disk
+  # will read a complete MP3 at once, and will then spin down while the MP3/OGG is
+  # playing.
+  #READAHEAD=4096
 
-# And shall we add the "noatime" option to that as well? (1=yes)
-#DO_REMOUNT_NOATIME=1
+  # Shall we remount journaled fs. with appropriate commit interval? (1=yes)
+  #DO_REMOUNTS=1
 
-# Dirty synchronous ratio.  At this percentage of dirty pages the process
-# which
-# calls write() does its own writeback
-#DIRTY_RATIO=40
+  # And shall we add the "noatime" option to that as well? (1=yes)
+  #DO_REMOUNT_NOATIME=1
 
-#
-# Allowed dirty background ratio, in percent.  Once DIRTY_RATIO has been
-# exceeded, the kernel will wake flusher threads which will then reduce the
-# amount of dirty memory to dirty_background_ratio.  Set this nice and low,
-# so once some writeout has commenced, we do a lot of it.
-#
-#DIRTY_BACKGROUND_RATIO=5
+  # Dirty synchronous ratio.  At this percentage of dirty pages the process
+  # which
+  # calls write() does its own writeback
+  #DIRTY_RATIO=40
 
-# kernel default dirty buffer age
-#DEF_AGE=30
-#DEF_UPDATE=5
-#DEF_DIRTY_BACKGROUND_RATIO=10
-#DEF_DIRTY_RATIO=40
-#DEF_XFS_AGE_BUFFER=15
-#DEF_XFS_SYNC_INTERVAL=30
-#DEF_XFS_BUFD_INTERVAL=1
+  #
+  # Allowed dirty background ratio, in percent.  Once DIRTY_RATIO has been
+  # exceeded, the kernel will wake flusher threads which will then reduce the
+  # amount of dirty memory to dirty_background_ratio.  Set this nice and low,
+  # so once some writeout has commenced, we do a lot of it.
+  #
+  #DIRTY_BACKGROUND_RATIO=5
 
-# This must be adjusted manually to the value of HZ in the running kernel
-# on 2.4, until the XFS people change their 2.4 external interfaces to work in
-# centisecs. This can be automated, but it's a work in progress that still
-# needs# some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for
-# external interfaces, and that is currently always set to 100. So you don't
-# need to change this on 2.6.
-#XFS_HZ=100
+  # kernel default dirty buffer age
+  #DEF_AGE=30
+  #DEF_UPDATE=5
+  #DEF_DIRTY_BACKGROUND_RATIO=10
+  #DEF_DIRTY_RATIO=40
+  #DEF_XFS_AGE_BUFFER=15
+  #DEF_XFS_SYNC_INTERVAL=30
+  #DEF_XFS_BUFD_INTERVAL=1
 
-# Should the maximum CPU frequency be adjusted down while on battery?
-# Requires CPUFreq to be setup.
-# See Documentation/admin-guide/pm/cpufreq.rst for more info
-#DO_CPU=0
+  # This must be adjusted manually to the value of HZ in the running kernel
+  # on 2.4, until the XFS people change their 2.4 external interfaces to work in
+  # centisecs. This can be automated, but it's a work in progress that still
+  # needs# some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for
+  # external interfaces, and that is currently always set to 100. So you don't
+  # need to change this on 2.6.
+  #XFS_HZ=100
 
-# When on battery what is the maximum CPU speed that the system should
-# use? Legal values are "slowest" for the slowest speed that your
-# CPU is able to operate at, or a value listed in:
-# /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies
-# Only applicable if DO_CPU=1.
-#CPU_MAXFREQ=slowest
+  # Should the maximum CPU frequency be adjusted down while on battery?
+  # Requires CPUFreq to be setup.
+  # See Documentation/admin-guide/pm/cpufreq.rst for more info
+  #DO_CPU=0
 
-# Idle timeout for your hard drive (man hdparm for valid values, -S option)
-# Default is 2 hours on AC (AC_HD=244) and 20 seconds for battery (BATT_HD=4).
-#AC_HD=244
-#BATT_HD=4
+  # When on battery what is the maximum CPU speed that the system should
+  # use? Legal values are "slowest" for the slowest speed that your
+  # CPU is able to operate at, or a value listed in:
+  # /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies
+  # Only applicable if DO_CPU=1.
+  #CPU_MAXFREQ=slowest
 
-# The drives for which to adjust the idle timeout. Separate them by a space,
-# e.g. HD="/dev/hda /dev/hdb".
-#HD="/dev/hda"
+  # Idle timeout for your hard drive (man hdparm for valid values, -S option)
+  # Default is 2 hours on AC (AC_HD=244) and 20 seconds for battery (BATT_HD=4).
+  #AC_HD=244
+  #BATT_HD=4
 
-# Set the spindown timeout on a hard drive?
-#DO_HD=1
+  # The drives for which to adjust the idle timeout. Separate them by a space,
+  # e.g. HD="/dev/hda /dev/hdb".
+  #HD="/dev/hda"
 
---------------------CONFIG FILE END---------------------------------------------
+  # Set the spindown timeout on a hard drive?
+  #DO_HD=1
 
 
 Control script
@@ -318,125 +319,126 @@ Control script
 Please note that this control script works for the Linux 2.4 and 2.6 series (thanks
 to Kiko Piris).
 
---------------------CONTROL SCRIPT BEGIN----------------------------------------
-#!/bin/bash
+Control script::
 
-# start or stop laptop_mode, best run by a power management daemon when
-# ac gets connected/disconnected from a laptop
-#
-# install as /sbin/laptop_mode
-#
-# Contributors to this script:   Kiko Piris
-#				 Bart Samwel
-#				 Micha Feigin
-#				 Andrew Morton
-#				 Herve Eychenne
-#				 Dax Kelson
-#
-# Original Linux 2.4 version by: Jens Axboe
+  #!/bin/bash
 
-#############################################################################
+  # start or stop laptop_mode, best run by a power management daemon when
+  # ac gets connected/disconnected from a laptop
+  #
+  # install as /sbin/laptop_mode
+  #
+  # Contributors to this script:   Kiko Piris
+  #				 Bart Samwel
+  #				 Micha Feigin
+  #				 Andrew Morton
+  #				 Herve Eychenne
+  #				 Dax Kelson
+  #
+  # Original Linux 2.4 version by: Jens Axboe
 
-# Source config
-if [ -f /etc/default/laptop-mode ] ; then
+  #############################################################################
+
+  # Source config
+  if [ -f /etc/default/laptop-mode ] ; then
 	# Debian
 	. /etc/default/laptop-mode
-elif [ -f /etc/sysconfig/laptop-mode ] ; then
+  elif [ -f /etc/sysconfig/laptop-mode ] ; then
 	# Others
-        . /etc/sysconfig/laptop-mode
-fi
+          . /etc/sysconfig/laptop-mode
+  fi
 
-# Don't raise an error if the config file is incomplete
-# set defaults instead:
+  # Don't raise an error if the config file is incomplete
+  # set defaults instead:
 
-# Maximum time, in seconds, of hard drive spindown time that you are
-# comfortable with. Worst case, it's possible that you could lose this
-# amount of work if your battery fails you while in laptop mode.
-MAX_AGE=${MAX_AGE:-'600'}
+  # Maximum time, in seconds, of hard drive spindown time that you are
+  # comfortable with. Worst case, it's possible that you could lose this
+  # amount of work if your battery fails you while in laptop mode.
+  MAX_AGE=${MAX_AGE:-'600'}
 
-# Read-ahead, in kilobytes
-READAHEAD=${READAHEAD:-'4096'}
+  # Read-ahead, in kilobytes
+  READAHEAD=${READAHEAD:-'4096'}
 
-# Shall we remount journaled fs. with appropriate commit interval? (1=yes)
-DO_REMOUNTS=${DO_REMOUNTS:-'1'}
+  # Shall we remount journaled fs. with appropriate commit interval? (1=yes)
+  DO_REMOUNTS=${DO_REMOUNTS:-'1'}
 
-# And shall we add the "noatime" option to that as well? (1=yes)
-DO_REMOUNT_NOATIME=${DO_REMOUNT_NOATIME:-'1'}
+  # And shall we add the "noatime" option to that as well? (1=yes)
+  DO_REMOUNT_NOATIME=${DO_REMOUNT_NOATIME:-'1'}
 
-# Shall we adjust the idle timeout on a hard drive?
-DO_HD=${DO_HD:-'1'}
+  # Shall we adjust the idle timeout on a hard drive?
+  DO_HD=${DO_HD:-'1'}
 
-# Adjust idle timeout on which hard drive?
-HD="${HD:-'/dev/hda'}"
+  # Adjust idle timeout on which hard drive?
+  HD="${HD:-'/dev/hda'}"
 
-# spindown time for HD (hdparm -S values)
-AC_HD=${AC_HD:-'244'}
-BATT_HD=${BATT_HD:-'4'}
+  # spindown time for HD (hdparm -S values)
+  AC_HD=${AC_HD:-'244'}
+  BATT_HD=${BATT_HD:-'4'}
 
-# Dirty synchronous ratio.  At this percentage of dirty pages the process which
-# calls write() does its own writeback
-DIRTY_RATIO=${DIRTY_RATIO:-'40'}
+  # Dirty synchronous ratio.  At this percentage of dirty pages the process which
+  # calls write() does its own writeback
+  DIRTY_RATIO=${DIRTY_RATIO:-'40'}
 
-# cpu frequency scaling
-# See Documentation/admin-guide/pm/cpufreq.rst for more info
-DO_CPU=${CPU_MANAGE:-'0'}
-CPU_MAXFREQ=${CPU_MAXFREQ:-'slowest'}
+  # cpu frequency scaling
+  # See Documentation/admin-guide/pm/cpufreq.rst for more info
+  DO_CPU=${CPU_MANAGE:-'0'}
+  CPU_MAXFREQ=${CPU_MAXFREQ:-'slowest'}
 
-#
-# Allowed dirty background ratio, in percent.  Once DIRTY_RATIO has been
-# exceeded, the kernel will wake flusher threads which will then reduce the
-# amount of dirty memory to dirty_background_ratio.  Set this nice and low,
-# so once some writeout has commenced, we do a lot of it.
-#
-DIRTY_BACKGROUND_RATIO=${DIRTY_BACKGROUND_RATIO:-'5'}
+  #
+  # Allowed dirty background ratio, in percent.  Once DIRTY_RATIO has been
+  # exceeded, the kernel will wake flusher threads which will then reduce the
+  # amount of dirty memory to dirty_background_ratio.  Set this nice and low,
+  # so once some writeout has commenced, we do a lot of it.
+  #
+  DIRTY_BACKGROUND_RATIO=${DIRTY_BACKGROUND_RATIO:-'5'}
 
-# kernel default dirty buffer age
-DEF_AGE=${DEF_AGE:-'30'}
-DEF_UPDATE=${DEF_UPDATE:-'5'}
-DEF_DIRTY_BACKGROUND_RATIO=${DEF_DIRTY_BACKGROUND_RATIO:-'10'}
-DEF_DIRTY_RATIO=${DEF_DIRTY_RATIO:-'40'}
-DEF_XFS_AGE_BUFFER=${DEF_XFS_AGE_BUFFER:-'15'}
-DEF_XFS_SYNC_INTERVAL=${DEF_XFS_SYNC_INTERVAL:-'30'}
-DEF_XFS_BUFD_INTERVAL=${DEF_XFS_BUFD_INTERVAL:-'1'}
+  # kernel default dirty buffer age
+  DEF_AGE=${DEF_AGE:-'30'}
+  DEF_UPDATE=${DEF_UPDATE:-'5'}
+  DEF_DIRTY_BACKGROUND_RATIO=${DEF_DIRTY_BACKGROUND_RATIO:-'10'}
+  DEF_DIRTY_RATIO=${DEF_DIRTY_RATIO:-'40'}
+  DEF_XFS_AGE_BUFFER=${DEF_XFS_AGE_BUFFER:-'15'}
+  DEF_XFS_SYNC_INTERVAL=${DEF_XFS_SYNC_INTERVAL:-'30'}
+  DEF_XFS_BUFD_INTERVAL=${DEF_XFS_BUFD_INTERVAL:-'1'}
 
-# This must be adjusted manually to the value of HZ in the running kernel
-# on 2.4, until the XFS people change their 2.4 external interfaces to work in
-# centisecs. This can be automated, but it's a work in progress that still needs
-# some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for external
-# interfaces, and that is currently always set to 100. So you don't need to
-# change this on 2.6.
-XFS_HZ=${XFS_HZ:-'100'}
+  # This must be adjusted manually to the value of HZ in the running kernel
+  # on 2.4, until the XFS people change their 2.4 external interfaces to work in
+  # centisecs. This can be automated, but it's a work in progress that still needs
+  # some fixes. On 2.6 kernels, XFS uses USER_HZ instead of HZ for external
+  # interfaces, and that is currently always set to 100. So you don't need to
+  # change this on 2.6.
+  XFS_HZ=${XFS_HZ:-'100'}
 
-#############################################################################
+  #############################################################################
 
-KLEVEL="$(uname -r |
-             {
+  KLEVEL="$(uname -r |
+               {
 	       IFS='.' read a b c
 	       echo $a.$b
 	     }
-)"
-case "$KLEVEL" in
+  )"
+  case "$KLEVEL" in
 	"2.4"|"2.6")
 		;;
 	*)
 		echo "Unhandled kernel version: $KLEVEL ('uname -r' = '$(uname -r)')" >&2
 		exit 1
 		;;
-esac
+  esac
 
-if [ ! -e /proc/sys/vm/laptop_mode ] ; then
+  if [ ! -e /proc/sys/vm/laptop_mode ] ; then
 	echo "Kernel is not patched with laptop_mode patch." >&2
 	exit 1
-fi
+  fi
 
-if [ ! -w /proc/sys/vm/laptop_mode ] ; then
+  if [ ! -w /proc/sys/vm/laptop_mode ] ; then
 	echo "You do not have enough privileges to enable laptop_mode." >&2
 	exit 1
-fi
+  fi
 
-# Remove an option (the first parameter) of the form option=<number> from
-# a mount options string (the rest of the parameters).
-parse_mount_opts () {
+  # Remove an option (the first parameter) of the form option=<number> from
+  # a mount options string (the rest of the parameters).
+  parse_mount_opts () {
 	OPT="$1"
 	shift
 	echo ",$*," | sed		\
@@ -444,11 +446,11 @@ parse_mount_opts () {
 	 -e 's/,,*/,/g'			\
 	 -e 's/^,//'			\
 	 -e 's/,$//'
-}
+  }
 
-# Remove an option (the first parameter) without any arguments from
-# a mount option string (the rest of the parameters).
-parse_nonumber_mount_opts () {
+  # Remove an option (the first parameter) without any arguments from
+  # a mount option string (the rest of the parameters).
+  parse_nonumber_mount_opts () {
 	OPT="$1"
 	shift
 	echo ",$*," | sed		\
@@ -456,20 +458,20 @@ parse_nonumber_mount_opts () {
 	 -e 's/,,*/,/g'			\
 	 -e 's/^,//'			\
 	 -e 's/,$//'
-}
+  }
 
-# Find out the state of a yes/no option (e.g. "atime"/"noatime") in
-# fstab for a given filesystem, and use this state to replace the
-# value of the option in another mount options string. The device
-# is the first argument, the option name the second, and the default
-# value the third. The remainder is the mount options string.
-#
-# Example:
-# parse_yesno_opts_wfstab /dev/hda1 atime atime defaults,noatime
-#
-# If fstab contains, say, "rw" for this filesystem, then the result
-# will be "defaults,atime".
-parse_yesno_opts_wfstab () {
+  # Find out the state of a yes/no option (e.g. "atime"/"noatime") in
+  # fstab for a given filesystem, and use this state to replace the
+  # value of the option in another mount options string. The device
+  # is the first argument, the option name the second, and the default
+  # value the third. The remainder is the mount options string.
+  #
+  # Example:
+  # parse_yesno_opts_wfstab /dev/hda1 atime atime defaults,noatime
+  #
+  # If fstab contains, say, "rw" for this filesystem, then the result
+  # will be "defaults,atime".
+  parse_yesno_opts_wfstab () {
 	L_DEV="$1"
 	OPT="$2"
 	DEF_OPT="$3"
@@ -491,21 +493,21 @@ parse_yesno_opts_wfstab () {
 		# option not specified in fstab -- choose the default.
 		echo "$PARSEDOPTS1,$DEF_OPT"
 	fi
-}
+  }
 
-# Find out the state of a numbered option (e.g. "commit=NNN") in
-# fstab for a given filesystem, and use this state to replace the
-# value of the option in another mount options string. The device
-# is the first argument, and the option name the second. The
-# remainder is the mount options string in which the replacement
-# must be done.
-#
-# Example:
-# parse_mount_opts_wfstab /dev/hda1 commit defaults,commit=7
-#
-# If fstab contains, say, "commit=3,rw" for this filesystem, then the
-# result will be "rw,commit=3".
-parse_mount_opts_wfstab () {
+  # Find out the state of a numbered option (e.g. "commit=NNN") in
+  # fstab for a given filesystem, and use this state to replace the
+  # value of the option in another mount options string. The device
+  # is the first argument, and the option name the second. The
+  # remainder is the mount options string in which the replacement
+  # must be done.
+  #
+  # Example:
+  # parse_mount_opts_wfstab /dev/hda1 commit defaults,commit=7
+  #
+  # If fstab contains, say, "commit=3,rw" for this filesystem, then the
+  # result will be "rw,commit=3".
+  parse_mount_opts_wfstab () {
 	L_DEV="$1"
 	OPT="$2"
 	shift 2
@@ -523,9 +525,9 @@ parse_mount_opts_wfstab () {
 		# option not specified in fstab: set it to 0
 		echo "$PARSEDOPTS1,$OPT=0"
 	fi
-}
+  }
 
-deduce_fstype () {
+  deduce_fstype () {
 	MP="$1"
 	# My root filesystem unfortunately has
 	# type "unknown" in /etc/mtab. If we encounter
@@ -538,13 +540,13 @@ deduce_fstype () {
 			exit 0
 		fi
 	done
-}
+  }
 
-if [ $DO_REMOUNT_NOATIME -eq 1 ] ; then
+  if [ $DO_REMOUNT_NOATIME -eq 1 ] ; then
 	NOATIME_OPT=",noatime"
-fi
+  fi
 
-case "$1" in
+  case "$1" in
 	start)
 		AGE=$((100*$MAX_AGE))
 		XFS_AGE=$(($XFS_HZ*$MAX_AGE))
@@ -687,10 +689,9 @@ case "$1" in
 		exit 1
 		;;
 
-esac
+  esac
 
-exit 0
---------------------CONTROL SCRIPT END------------------------------------------
+  exit 0
 
 
 ACPI integration
@@ -701,78 +702,76 @@ kick off the laptop_mode script and run hdparm. The part that
 automatically disables laptop mode when the battery is low was
 written by Jan Topinski.
 
------------------/etc/acpi/events/ac_adapter BEGIN------------------------------
-event=ac_adapter
-action=/etc/acpi/actions/ac.sh %e
-----------------/etc/acpi/events/ac_adapter END---------------------------------
+/etc/acpi/events/ac_adapter::
 
+	event=ac_adapter
+	action=/etc/acpi/actions/ac.sh %e
 
------------------/etc/acpi/events/battery BEGIN---------------------------------
-event=battery.*
-action=/etc/acpi/actions/battery.sh %e
-----------------/etc/acpi/events/battery END------------------------------------
+/etc/acpi/events/battery::
 
+	event=battery.*
+	action=/etc/acpi/actions/battery.sh %e
 
-----------------/etc/acpi/actions/ac.sh BEGIN-----------------------------------
-#!/bin/bash
+/etc/acpi/actions/ac.sh::
 
-# ac on/offline event handler
+  #!/bin/bash
 
-status=`awk '/^state: / { print $2 }' /proc/acpi/ac_adapter/$2/state`
+  # ac on/offline event handler
 
-case $status in
-        "on-line")
-                /sbin/laptop_mode stop
-                exit 0
-        ;;
-        "off-line")
-                /sbin/laptop_mode start
-                exit 0
-        ;;
-esac
----------------------------/etc/acpi/actions/ac.sh END--------------------------
+  status=`awk '/^state: / { print $2 }' /proc/acpi/ac_adapter/$2/state`
 
+  case $status in
+          "on-line")
+                  /sbin/laptop_mode stop
+                  exit 0
+          ;;
+          "off-line")
+                  /sbin/laptop_mode start
+                  exit 0
+          ;;
+  esac
 
----------------------------/etc/acpi/actions/battery.sh BEGIN-------------------
-#! /bin/bash
 
-# Automatically disable laptop mode when the battery almost runs out.
+/etc/acpi/actions/battery.sh::
 
-BATT_INFO=/proc/acpi/battery/$2/state
+  #! /bin/bash
 
-if [[ -f /proc/sys/vm/laptop_mode ]]
-then
-   LM=`cat /proc/sys/vm/laptop_mode`
-   if [[ $LM -gt 0 ]]
-   then
-     if [[ -f $BATT_INFO ]]
+  # Automatically disable laptop mode when the battery almost runs out.
+
+  BATT_INFO=/proc/acpi/battery/$2/state
+
+  if [[ -f /proc/sys/vm/laptop_mode ]]
+  then
+     LM=`cat /proc/sys/vm/laptop_mode`
+     if [[ $LM -gt 0 ]]
      then
-        # Source the config file only now that we know we need
-        if [ -f /etc/default/laptop-mode ] ; then
-                # Debian
-                . /etc/default/laptop-mode
-        elif [ -f /etc/sysconfig/laptop-mode ] ; then
-                # Others
-                . /etc/sysconfig/laptop-mode
-        fi
-        MINIMUM_BATTERY_MINUTES=${MINIMUM_BATTERY_MINUTES:-'10'}
+       if [[ -f $BATT_INFO ]]
+       then
+          # Source the config file only now that we know we need
+          if [ -f /etc/default/laptop-mode ] ; then
+                  # Debian
+                  . /etc/default/laptop-mode
+          elif [ -f /etc/sysconfig/laptop-mode ] ; then
+                  # Others
+                  . /etc/sysconfig/laptop-mode
+          fi
+          MINIMUM_BATTERY_MINUTES=${MINIMUM_BATTERY_MINUTES:-'10'}
 
-        ACTION="`cat $BATT_INFO | grep charging | cut -c 26-`"
-        if [[ ACTION -eq "discharging" ]]
-        then
-           PRESENT_RATE=`cat $BATT_INFO | grep "present rate:" | sed  "s/.* \([0-9][0-9]* \).*/\1/" `
-           REMAINING=`cat $BATT_INFO | grep "remaining capacity:" | sed  "s/.* \([0-9][0-9]* \).*/\1/" `
-        fi
-        if (($REMAINING * 60 / $PRESENT_RATE < $MINIMUM_BATTERY_MINUTES))
-        then
-           /sbin/laptop_mode stop
-        fi
-     else
-       logger -p daemon.warning "You are using laptop mode and your battery interface $BATT_INFO is missing. This may lead to loss of data when the battery runs out. Check kernel ACPI support and /proc/acpi/battery folder, and edit /etc/acpi/battery.sh to set BATT_INFO to the correct path."
+          ACTION="`cat $BATT_INFO | grep charging | cut -c 26-`"
+          if [[ ACTION -eq "discharging" ]]
+          then
+             PRESENT_RATE=`cat $BATT_INFO | grep "present rate:" | sed  "s/.* \([0-9][0-9]* \).*/\1/" `
+             REMAINING=`cat $BATT_INFO | grep "remaining capacity:" | sed  "s/.* \([0-9][0-9]* \).*/\1/" `
+          fi
+          if (($REMAINING * 60 / $PRESENT_RATE < $MINIMUM_BATTERY_MINUTES))
+          then
+             /sbin/laptop_mode stop
+          fi
+       else
+         logger -p daemon.warning "You are using laptop mode and your battery interface $BATT_INFO is missing. This may lead to loss of data when the battery runs out. Check kernel ACPI support and /proc/acpi/battery folder, and edit /etc/acpi/battery.sh to set BATT_INFO to the correct path."
+       fi
      fi
-   fi
-fi
----------------------------/etc/acpi/actions/battery.sh END--------------------
+  fi
 
 
 Monitoring tool
diff --git a/Documentation/laptops/sony-laptop.txt b/Documentation/laptops/sony-laptop.rst
similarity index 85%
rename from Documentation/laptops/sony-laptop.txt
rename to Documentation/laptops/sony-laptop.rst
index 978b1e615155..9edcc7f6612f 100644
--- a/Documentation/laptops/sony-laptop.txt
+++ b/Documentation/laptops/sony-laptop.rst
@@ -1,7 +1,9 @@
+=========================================
 Sony Notebook Control Driver (SNC) Readme
------------------------------------------
-	Copyright (C) 2004- 2005 Stelian Pop <stelian@popies.net>
-	Copyright (C) 2007 Mattia Dongili <malattia@linux.it>
+=========================================
+
+	- Copyright (C) 2004- 2005 Stelian Pop <stelian@popies.net>
+	- Copyright (C) 2007 Mattia Dongili <malattia@linux.it>
 
 This mini-driver drives the SNC and SPIC device present in the ACPI BIOS of the
 Sony Vaio laptops. This driver mixes both devices functions under the same
@@ -10,6 +12,7 @@ obsoleted by sony-laptop now.
 
 Fn keys (hotkeys):
 ------------------
+
 Some models report hotkeys through the SNC or SPIC devices, such events are
 reported both through the ACPI subsystem as acpi events and through the INPUT
 subsystem. See the logs of /proc/bus/input/devices to find out what those
@@ -28,11 +31,14 @@ If your laptop model supports it, you will find sysfs files in the
 /sys/class/backlight/sony/
 directory. You will be able to query and set the current screen
 brightness:
+
+	======================	=========================================
 	brightness		get/set screen brightness (an integer
 				between 0 and 7)
 	actual_brightness	reading from this file will query the HW
 				to get real brightness value
 	max_brightness		the maximum brightness value
+	======================	=========================================
 
 
 Platform specific:
@@ -45,6 +51,8 @@ You then read/write integer values from/to those files by using
 standard UNIX tools.
 
 The files are:
+
+	======================	==========================================
 	brightness_default	screen brightness which will be set
 				when the laptop will be rebooted
 	cdpower			power on/off the internal CD drive
@@ -53,21 +61,39 @@ The files are:
 				(only in debug mode)
 	bluetoothpower		power on/off the internal bluetooth device
 	fanspeed		get/set the fan speed
+	======================	==========================================
 
 Note that some files may be missing if they are not supported
 by your particular laptop model.
 
-Example usage:
+Example usage::
+
 	# echo "1" > /sys/devices/platform/sony-laptop/brightness_default
-sets the lowest screen brightness for the next and later reboots,
+
+sets the lowest screen brightness for the next and later reboots
+
+::
+
 	# echo "8" > /sys/devices/platform/sony-laptop/brightness_default
-sets the highest screen brightness for the next and later reboots,
+
+sets the highest screen brightness for the next and later reboots
+
+::
+
 	# cat /sys/devices/platform/sony-laptop/brightness_default
-retrieves the value.
+
+retrieves the value
+
+::
 
 	# echo "0" > /sys/devices/platform/sony-laptop/audiopower
-powers off the sound card,
+
+powers off the sound card
+
+::
+
 	# echo "1" > /sys/devices/platform/sony-laptop/audiopower
+
 powers on the sound card.
 
 
@@ -76,7 +102,8 @@ RFkill control:
 More recent Vaio models expose a consistent set of ACPI methods to
 control radio frequency emitting devices. If you are a lucky owner of
 such a laptop you will find the necessary rfkill devices under
-/sys/class/rfkill. Check those starting with sony-* in
+/sys/class/rfkill. Check those starting with sony-* in::
+
 	# grep . /sys/class/rfkill/*/{state,name}
 
 
@@ -88,26 +115,29 @@ you are not afraid of any side effects doing strange things with
 your ACPI BIOS could have on your laptop), load the driver and
 pass the option 'debug=1'.
 
-REPEAT: DON'T DO THIS IF YOU DON'T LIKE RISKY BUSINESS.
+REPEAT:
+	**DON'T DO THIS IF YOU DON'T LIKE RISKY BUSINESS.**
 
 In your kernel logs you will find the list of all ACPI methods
 the SNC device has on your laptop.
 
 * For new models you will see a long list of meaningless method names,
-reading the DSDT table source should reveal that:
+  reading the DSDT table source should reveal that:
+
 (1) the SNC device uses an internal capability lookup table
 (2) SN00 is used to find values in the lookup table
 (3) SN06 and SN07 are used to call into the real methods based on
     offsets you can obtain iterating the table using SN00
 (4) SN02 used to enable events.
+
 Some values in the capability lookup table are more or less known, see
 the code for all sony_call_snc_handle calls, others are more obscure.
 
 * For old models you can see the GCDP/GCDP methods used to pwer on/off
-the CD drive, but there are others and they are usually different from
-model to model.
+  the CD drive, but there are others and they are usually different from
+  model to model.
 
-I HAVE NO IDEA WHAT THOSE METHODS DO.
+**I HAVE NO IDEA WHAT THOSE METHODS DO.**
 
 The sony-laptop driver creates, for some of those methods (the most
 current ones found on several Vaio models), an entry under
diff --git a/Documentation/laptops/sonypi.txt b/Documentation/laptops/sonypi.rst
similarity index 87%
rename from Documentation/laptops/sonypi.txt
rename to Documentation/laptops/sonypi.rst
index 606bdb9ce036..2a1975ed7ee4 100644
--- a/Documentation/laptops/sonypi.txt
+++ b/Documentation/laptops/sonypi.rst
@@ -1,11 +1,13 @@
+==================================================
 Sony Programmable I/O Control Device Driver Readme
---------------------------------------------------
-	Copyright (C) 2001-2004 Stelian Pop <stelian@popies.net>
-	Copyright (C) 2001-2002 Alcôve <www.alcove.com>
-	Copyright (C) 2001 Michael Ashley <m.ashley@unsw.edu.au>
-	Copyright (C) 2001 Junichi Morita <jun1m@mars.dti.ne.jp>
-	Copyright (C) 2000 Takaya Kinjo <t-kinjo@tc4.so-net.ne.jp>
-	Copyright (C) 2000 Andrew Tridgell <tridge@samba.org>
+==================================================
+
+	- Copyright (C) 2001-2004 Stelian Pop <stelian@popies.net>
+	- Copyright (C) 2001-2002 Alcôve <www.alcove.com>
+	- Copyright (C) 2001 Michael Ashley <m.ashley@unsw.edu.au>
+	- Copyright (C) 2001 Junichi Morita <jun1m@mars.dti.ne.jp>
+	- Copyright (C) 2000 Takaya Kinjo <t-kinjo@tc4.so-net.ne.jp>
+	- Copyright (C) 2000 Andrew Tridgell <tridge@samba.org>
 
 This driver enables access to the Sony Programmable I/O Control Device which
 can be found in many Sony Vaio laptops. Some newer Sony laptops (seems to be
@@ -14,6 +16,7 @@ sonypi device and are not supported at all by this driver.
 
 It will give access (through a user space utility) to some events those laptops
 generate, like:
+
 	- jogdial events (the small wheel on the side of Vaios)
 	- capture button events (only on Vaio Picturebook series)
 	- Fn keys
@@ -49,6 +52,7 @@ module argument syntax (<param>=<value> when passing the option to the
 module or sonypi.<param>=<value> on the kernel boot line when sonypi is
 statically linked into the kernel). Those options are:
 
+	=============== =======================================================
 	minor: 		minor number of the misc device /dev/sonypi,
 			default is -1 (automatic allocation, see /proc/misc
 			or kernel logs)
@@ -86,6 +90,8 @@ statically linked into the kernel). Those options are:
 			will be tried. You can use the following bits to
 			construct your own event mask (from
 			drivers/char/sonypi.h):
+
+				========================	======
 				SONYPI_JOGGER_MASK 		0x0001
 				SONYPI_CAPTURE_MASK 		0x0002
 				SONYPI_FNKEY_MASK 		0x0004
@@ -100,22 +106,24 @@ statically linked into the kernel). Those options are:
 				SONYPI_MEMORYSTICK_MASK		0x0800
 				SONYPI_BATTERY_MASK		0x1000
 				SONYPI_WIRELESS_MASK		0x2000
+				========================	======
 
 	useinput:	if set (which is the default) two input devices are
 			created, one which interprets the jogdial events as
 			mouse events, the other one which acts like a
 			keyboard reporting the pressing of the special keys.
+	=============== =======================================================
 
 Module use:
 -----------
 
 In order to automatically load the sonypi module on use, you can put those
-lines a configuration file in /etc/modprobe.d/:
+lines a configuration file in /etc/modprobe.d/::
 
 	alias char-major-10-250 sonypi
 	options sonypi minor=250
 
-This supposes the use of minor 250 for the sonypi device:
+This supposes the use of minor 250 for the sonypi device::
 
 	# mknod /dev/sonypi c 10 250
 
@@ -148,5 +156,5 @@ Bugs:
 	  http://www.acc.umu.se/~erikw/program/smartdimmer-0.1.tar.bz2
 
 	- since all development was done by reverse engineering, there is
-	  _absolutely no guarantee_ that this driver will not crash your
+	  *absolutely no guarantee* that this driver will not crash your
 	  laptop. Permanently.
diff --git a/Documentation/laptops/thinkpad-acpi.txt b/Documentation/laptops/thinkpad-acpi.rst
similarity index 89%
rename from Documentation/laptops/thinkpad-acpi.txt
rename to Documentation/laptops/thinkpad-acpi.rst
index 75ef063622d2..19d52fc3c5e9 100644
--- a/Documentation/laptops/thinkpad-acpi.txt
+++ b/Documentation/laptops/thinkpad-acpi.rst
@@ -1,12 +1,15 @@
-		     ThinkPad ACPI Extras Driver
+===========================
+ThinkPad ACPI Extras Driver
+===========================
 
-                            Version 0.25
-                        October 16th,  2013
+Version 0.25
 
-               Borislav Deianov <borislav@users.sf.net>
-             Henrique de Moraes Holschuh <hmh@hmh.eng.br>
-                      http://ibm-acpi.sf.net/
+October 16th,  2013
 
+- Borislav Deianov <borislav@users.sf.net>
+- Henrique de Moraes Holschuh <hmh@hmh.eng.br>
+
+http://ibm-acpi.sf.net/
 
 This is a Linux driver for the IBM and Lenovo ThinkPad laptops. It
 supports various features of these laptops which are accessible
@@ -91,7 +94,8 @@ yet ready or stabilized, it is expected that this interface will change,
 and any and all userspace programs must deal with it.
 
 
-Notes about the sysfs interface:
+Notes about the sysfs interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Unlike what was done with the procfs interface, correctness when talking
 to the sysfs interfaces will be enforced, as will correctness in the
@@ -129,6 +133,7 @@ Driver version
 --------------
 
 procfs: /proc/acpi/ibm/driver
+
 sysfs driver attribute: version
 
 The driver name and version. No commands can be written to this file.
@@ -141,9 +146,13 @@ sysfs driver attribute: interface_version
 
 Version of the thinkpad-acpi sysfs interface, as an unsigned long
 (output in hex format: 0xAAAABBCC), where:
-	AAAA - major revision
-	BB - minor revision
-	CC - bugfix revision
+
+	AAAA
+	  - major revision
+	BB
+	  - minor revision
+	CC
+	  - bugfix revision
 
 The sysfs interface version changelog for the driver can be found at the
 end of this document.  Changes to the sysfs interface done by the kernel
@@ -170,6 +179,7 @@ Hot keys
 --------
 
 procfs: /proc/acpi/ibm/hotkey
+
 sysfs device attribute: hotkey_*
 
 In a ThinkPad, the ACPI HKEY handler is responsible for communicating
@@ -181,7 +191,7 @@ firmware will behave in many situations.
 The driver enables the HKEY ("hot key") event reporting automatically
 when loaded, and disables it when it is removed.
 
-The driver will report HKEY events in the following format:
+The driver will report HKEY events in the following format::
 
 	ibm/hotkey HKEY 00000080 0000xxxx
 
@@ -217,9 +227,10 @@ ThinkPads, it is still possible to support some extra hotkeys by
 polling the "CMOS NVRAM" at least 10 times per second.  The driver
 attempts to enables this functionality automatically when required.
 
-procfs notes:
+procfs notes
+^^^^^^^^^^^^
 
-The following commands can be written to the /proc/acpi/ibm/hotkey file:
+The following commands can be written to the /proc/acpi/ibm/hotkey file::
 
 	echo 0xffffffff > /proc/acpi/ibm/hotkey -- enable all hot keys
 	echo 0 > /proc/acpi/ibm/hotkey -- disable all possible hot keys
@@ -227,7 +238,7 @@ The following commands can be written to the /proc/acpi/ibm/hotkey file:
 	echo reset > /proc/acpi/ibm/hotkey -- restore the recommended mask
 
 The following commands have been deprecated and will cause the kernel
-to log a warning:
+to log a warning::
 
 	echo enable > /proc/acpi/ibm/hotkey -- does nothing
 	echo disable > /proc/acpi/ibm/hotkey -- returns an error
@@ -237,7 +248,8 @@ maintain maximum bug-to-bug compatibility, it does not report any masks,
 nor does it allow one to manipulate the hot key mask when the firmware
 does not support masks at all, even if NVRAM polling is in use.
 
-sysfs notes:
+sysfs notes
+^^^^^^^^^^^
 
 	hotkey_bios_enabled:
 		DEPRECATED, WILL BE REMOVED SOON.
@@ -349,7 +361,8 @@ sysfs notes:
 
 		This attribute has poll()/select() support.
 
-input layer notes:
+input layer notes
+^^^^^^^^^^^^^^^^^
 
 A Hot key is mapped to a single input layer EV_KEY event, possibly
 followed by an EV_MSC MSC_SCAN event that shall contain that key's scan
@@ -362,11 +375,13 @@ remapping KEY_UNKNOWN keys.
 
 The events are available in an input device, with the following id:
 
-	Bus:		BUS_HOST
-	vendor:		0x1014 (PCI_VENDOR_ID_IBM)  or
+	==============  ==============================
+	Bus		BUS_HOST
+	vendor		0x1014 (PCI_VENDOR_ID_IBM)  or
 			0x17aa (PCI_VENDOR_ID_LENOVO)
-	product:	0x5054 ("TP")
-	version:	0x4101
+	product		0x5054 ("TP")
+	version		0x4101
+	==============  ==============================
 
 The version will have its LSB incremented if the keymap changes in a
 backwards-compatible way.  The MSB shall always be 0x41 for this input
@@ -380,9 +395,10 @@ backwards-compatible change for this input device.
 
 Thinkpad-acpi Hot Key event map (version 0x4101):
 
+=======	=======	==============	==============================================
 ACPI	Scan
 event	code	Key		Notes
-
+=======	=======	==============	==============================================
 0x1001	0x00	FN+F1		-
 
 0x1002	0x01	FN+F2		IBM: battery (rare)
@@ -426,7 +442,9 @@ event	code	Key		Notes
 				or toggle screen expand
 
 0x1009	0x08	FN+F9		-
-	..	..		..
+
+...	...	...		...
+
 0x100B	0x0A	FN+F11		-
 
 0x100C	0x0B	FN+F12		Sleep to disk.  You are always
@@ -480,8 +498,11 @@ event	code	Key		Notes
 0x1018	0x17	THINKPAD	ThinkPad/Access IBM/Lenovo key
 
 0x1019	0x18	unknown
-..	..	..
+
+...	...	...
+
 0x1020	0x1F	unknown
+=======	=======	==============	==============================================
 
 The ThinkPad firmware does not allow one to differentiate when most hot
 keys are pressed or released (either that, or we don't know how to, yet).
@@ -499,14 +520,17 @@ generate input device EV_KEY events.
 In addition to the EV_KEY events, thinkpad-acpi may also issue EV_SW
 events for switches:
 
+==============	==============================================
 SW_RFKILL_ALL	T60 and later hardware rfkill rocker switch
 SW_TABLET_MODE	Tablet ThinkPads HKEY events 0x5009 and 0x500A
+==============	==============================================
 
-Non hotkey ACPI HKEY event map:
--------------------------------
+Non hotkey ACPI HKEY event map
+------------------------------
 
 Events that are never propagated by the driver:
 
+======		==================================================
 0x2304		System is waking up from suspend to undock
 0x2305		System is waking up from suspend to eject bay
 0x2404		System is waking up from hibernation to undock
@@ -519,10 +543,12 @@ Events that are never propagated by the driver:
 0x6000		KEYBOARD: Numlock key pressed
 0x6005		KEYBOARD: Fn key pressed (TO BE VERIFIED)
 0x7000		Radio Switch may have changed state
+======		==================================================
 
 
 Events that are propagated by the driver to userspace:
 
+======		=====================================================
 0x2313		ALARM: System is waking up from suspend because
 		the battery is nearly empty
 0x2413		ALARM: System is waking up from hibernation because
@@ -544,6 +570,7 @@ Events that are propagated by the driver to userspace:
 0x6040		Nvidia Optimus/AC adapter related (TO BE VERIFIED)
 0x60C0		X1 Yoga 2016, Tablet mode status changed
 0x60F0		Thermal Transformation changed (GMTS, Windows)
+======		=====================================================
 
 Battery nearly empty alarms are a last resort attempt to get the
 operating system to hibernate or shutdown cleanly (0x2313), or shutdown
@@ -562,7 +589,8 @@ cycle, or a system shutdown.  Obviously, something is very wrong if this
 happens.
 
 
-Brightness hotkey notes:
+Brightness hotkey notes
+^^^^^^^^^^^^^^^^^^^^^^^
 
 Don't mess with the brightness hotkeys in a Thinkpad.  If you want
 notifications for OSD, use the sysfs backlight class event support.
@@ -579,7 +607,9 @@ Bluetooth
 ---------
 
 procfs: /proc/acpi/ibm/bluetooth
+
 sysfs device attribute: bluetooth_enable (deprecated)
+
 sysfs rfkill class: switch "tpacpi_bluetooth_sw"
 
 This feature shows the presence and current state of a ThinkPad
@@ -588,22 +618,25 @@ Bluetooth device in the internal ThinkPad CDC slot.
 If the ThinkPad supports it, the Bluetooth state is stored in NVRAM,
 so it is kept across reboots and power-off.
 
-Procfs notes:
+Procfs notes
+^^^^^^^^^^^^
 
-If Bluetooth is installed, the following commands can be used:
+If Bluetooth is installed, the following commands can be used::
 
 	echo enable > /proc/acpi/ibm/bluetooth
 	echo disable > /proc/acpi/ibm/bluetooth
 
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
 
 	If the Bluetooth CDC card is installed, it can be enabled /
 	disabled through the "bluetooth_enable" thinkpad-acpi device
 	attribute, and its current status can also be queried.
 
 	enable:
-		0: disables Bluetooth / Bluetooth is disabled
-		1: enables Bluetooth / Bluetooth is enabled.
+
+		- 0: disables Bluetooth / Bluetooth is disabled
+		- 1: enables Bluetooth / Bluetooth is enabled.
 
 	Note: this interface has been superseded by the	generic rfkill
 	class.  It has been deprecated, and it will be removed in year
@@ -617,7 +650,7 @@ Video output control -- /proc/acpi/ibm/video
 --------------------------------------------
 
 This feature allows control over the devices used for video output -
-LCD, CRT or DVI (if available). The following commands are available:
+LCD, CRT or DVI (if available). The following commands are available::
 
 	echo lcd_enable > /proc/acpi/ibm/video
 	echo lcd_disable > /proc/acpi/ibm/video
@@ -630,9 +663,10 @@ LCD, CRT or DVI (if available). The following commands are available:
 	echo expand_toggle > /proc/acpi/ibm/video
 	echo video_switch > /proc/acpi/ibm/video
 
-NOTE: Access to this feature is restricted to processes owning the
-CAP_SYS_ADMIN capability for safety reasons, as it can interact badly
-enough with some versions of X.org to crash it.
+NOTE:
+  Access to this feature is restricted to processes owning the
+  CAP_SYS_ADMIN capability for safety reasons, as it can interact badly
+  enough with some versions of X.org to crash it.
 
 Each video output device can be enabled or disabled individually.
 Reading /proc/acpi/ibm/video shows the status of each device.
@@ -665,18 +699,21 @@ ThinkLight control
 ------------------
 
 procfs: /proc/acpi/ibm/light
+
 sysfs attributes: as per LED class, for the "tpacpi::thinklight" LED
 
-procfs notes:
+procfs notes
+^^^^^^^^^^^^
 
 The ThinkLight status can be read and set through the procfs interface.  A
 few models which do not make the status available will show the ThinkLight
-status as "unknown". The available commands are:
+status as "unknown". The available commands are::
 
 	echo on  > /proc/acpi/ibm/light
 	echo off > /proc/acpi/ibm/light
 
-sysfs notes:
+sysfs notes
+^^^^^^^^^^^
 
 The ThinkLight sysfs interface is documented by the LED class
 documentation, in Documentation/leds/leds-class.rst.  The ThinkLight LED name
@@ -691,6 +728,7 @@ CMOS/UCMS control
 -----------------
 
 procfs: /proc/acpi/ibm/cmos
+
 sysfs device attribute: cmos_command
 
 This feature is mostly used internally by the ACPI firmware to keep the legacy
@@ -707,16 +745,16 @@ The range of valid cmos command numbers is 0 to 21, but not all have an
 effect and the behavior varies from model to model.  Here is the behavior
 on the X40 (tpb is the ThinkPad Buttons utility):
 
-	0 - Related to "Volume down" key press
-	1 - Related to "Volume up" key press
-	2 - Related to "Mute on" key press
-	3 - Related to "Access IBM" key press
-	4 - Related to "LCD brightness up" key press
-	5 - Related to "LCD brightness down" key press
-	11 - Related to "toggle screen expansion" key press/function
-	12 - Related to "ThinkLight on"
-	13 - Related to "ThinkLight off"
-	14 - Related to "ThinkLight" key press (toggle ThinkLight)
+	- 0 - Related to "Volume down" key press
+	- 1 - Related to "Volume up" key press
+	- 2 - Related to "Mute on" key press
+	- 3 - Related to "Access IBM" key press
+	- 4 - Related to "LCD brightness up" key press
+	- 5 - Related to "LCD brightness down" key press
+	- 11 - Related to "toggle screen expansion" key press/function
+	- 12 - Related to "ThinkLight on"
+	- 13 - Related to "ThinkLight off"
+	- 14 - Related to "ThinkLight" key press (toggle ThinkLight)
 
 The cmos command interface is prone to firmware split-brain problems, as
 in newer ThinkPads it is just a compatibility layer.  Do not use it, it is
@@ -748,9 +786,10 @@ are aware of the consequences are welcome to enabling it.
 Audio mute and microphone mute LEDs are supported, but currently not
 visible to userspace. They are used by the snd-hda-intel audio driver.
 
-procfs notes:
+procfs notes
+^^^^^^^^^^^^
 
-The available commands are:
+The available commands are::
 
 	echo '<LED number> on' >/proc/acpi/ibm/led
 	echo '<LED number> off' >/proc/acpi/ibm/led
@@ -760,23 +799,24 @@ The <LED number> range is 0 to 15. The set of LEDs that can be
 controlled varies from model to model. Here is the common ThinkPad
 mapping:
 
-	0 - power
-	1 - battery (orange)
-	2 - battery (green)
-	3 - UltraBase/dock
-	4 - UltraBay
-	5 - UltraBase battery slot
-	6 - (unknown)
-	7 - standby
-	8 - dock status 1
-	9 - dock status 2
-	10, 11 - (unknown)
-	12 - thinkvantage
-	13, 14, 15 - (unknown)
+	- 0 - power
+	- 1 - battery (orange)
+	- 2 - battery (green)
+	- 3 - UltraBase/dock
+	- 4 - UltraBay
+	- 5 - UltraBase battery slot
+	- 6 - (unknown)
+	- 7 - standby
+	- 8 - dock status 1
+	- 9 - dock status 2
+	- 10, 11 - (unknown)
+	- 12 - thinkvantage
+	- 13, 14, 15 - (unknown)
 
 All of the above can be turned on and off and can be made to blink.
 
-sysfs notes:
+sysfs notes
+^^^^^^^^^^^
 
 The ThinkPad LED sysfs interface is described in detail by the LED class
 documentation, in Documentation/leds/leds-class.rst.
@@ -815,7 +855,7 @@ The BEEP method is used internally by the ACPI firmware to provide
 audible alerts in various situations. This feature allows the same
 sounds to be triggered manually.
 
-The commands are non-negative integer numbers:
+The commands are non-negative integer numbers::
 
 	echo <number> >/proc/acpi/ibm/beep
 
@@ -823,25 +863,26 @@ The valid <number> range is 0 to 17. Not all numbers trigger sounds
 and the sounds vary from model to model. Here is the behavior on the
 X40:
 
-	0 - stop a sound in progress (but use 17 to stop 16)
-	2 - two beeps, pause, third beep ("low battery")
-	3 - single beep
-	4 - high, followed by low-pitched beep ("unable")
-	5 - single beep
-	6 - very high, followed by high-pitched beep ("AC/DC")
-	7 - high-pitched beep
-	9 - three short beeps
-	10 - very long beep
-	12 - low-pitched beep
-	15 - three high-pitched beeps repeating constantly, stop with 0
-	16 - one medium-pitched beep repeating constantly, stop with 17
-	17 - stop 16
+	- 0 - stop a sound in progress (but use 17 to stop 16)
+	- 2 - two beeps, pause, third beep ("low battery")
+	- 3 - single beep
+	- 4 - high, followed by low-pitched beep ("unable")
+	- 5 - single beep
+	- 6 - very high, followed by high-pitched beep ("AC/DC")
+	- 7 - high-pitched beep
+	- 9 - three short beeps
+	- 10 - very long beep
+	- 12 - low-pitched beep
+	- 15 - three high-pitched beeps repeating constantly, stop with 0
+	- 16 - one medium-pitched beep repeating constantly, stop with 17
+	- 17 - stop 16
 
 
 Temperature sensors
 -------------------
 
 procfs: /proc/acpi/ibm/thermal
+
 sysfs device attributes: (hwmon "thinkpad") temp*_input
 
 Most ThinkPads include six or more separate temperature sensors but only
@@ -850,10 +891,14 @@ feature shows readings from up to eight different sensors on older
 ThinkPads, and up to sixteen different sensors on newer ThinkPads.
 
 For example, on the X40, a typical output may be:
-temperatures:   42 42 45 41 36 -128 33 -128
+
+temperatures:
+	42 42 45 41 36 -128 33 -128
 
 On the T43/p, a typical output may be:
-temperatures:   48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128
+
+temperatures:
+	48 48 36 52 38 -128 31 -128 48 52 48 -128 -128 -128 -128 -128
 
 The mapping of thermal sensors to physical locations varies depending on
 system-board model (and thus, on ThinkPad model).
@@ -863,46 +908,53 @@ tries to track down these locations for various models.
 
 Most (newer?) models seem to follow this pattern:
 
-1:  CPU
-2:  (depends on model)
-3:  (depends on model)
-4:  GPU
-5:  Main battery: main sensor
-6:  Bay battery: main sensor
-7:  Main battery: secondary sensor
-8:  Bay battery: secondary sensor
-9-15: (depends on model)
+- 1:  CPU
+- 2:  (depends on model)
+- 3:  (depends on model)
+- 4:  GPU
+- 5:  Main battery: main sensor
+- 6:  Bay battery: main sensor
+- 7:  Main battery: secondary sensor
+- 8:  Bay battery: secondary sensor
+- 9-15: (depends on model)
 
 For the R51 (source: Thomas Gruber):
-2:  Mini-PCI
-3:  Internal HDD
+
+- 2:  Mini-PCI
+- 3:  Internal HDD
 
 For the T43, T43/p (source: Shmidoax/Thinkwiki.org)
 http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_T43.2C_T43p
-2:  System board, left side (near PCMCIA slot), reported as HDAPS temp
-3:  PCMCIA slot
-9:  MCH (northbridge) to DRAM Bus
-10: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI
-    card, under touchpad
-11: Power regulator, underside of system board, below F2 key
+
+- 2:  System board, left side (near PCMCIA slot), reported as HDAPS temp
+- 3:  PCMCIA slot
+- 9:  MCH (northbridge) to DRAM Bus
+- 10: Clock-generator, mini-pci card and ICH (southbridge), under Mini-PCI
+      card, under touchpad
+- 11: Power regulator, underside of system board, below F2 key
 
 The A31 has a very atypical layout for the thermal sensors
 (source: Milos Popovic, http://thinkwiki.org/wiki/Thermal_Sensors#ThinkPad_A31)
-1:  CPU
-2:  Main Battery: main sensor
-3:  Power Converter
-4:  Bay Battery: main sensor
-5:  MCH (northbridge)
-6:  PCMCIA/ambient
-7:  Main Battery: secondary sensor
-8:  Bay Battery: secondary sensor
 
+- 1:  CPU
+- 2:  Main Battery: main sensor
+- 3:  Power Converter
+- 4:  Bay Battery: main sensor
+- 5:  MCH (northbridge)
+- 6:  PCMCIA/ambient
+- 7:  Main Battery: secondary sensor
+- 8:  Bay Battery: secondary sensor
+
+
+Procfs notes
+^^^^^^^^^^^^
 
-Procfs notes:
 	Readings from sensors that are not available return -128.
 	No commands can be written to this file.
 
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
+
 	Sensors that are not available return the ENXIO error.  This
 	status may change at runtime, as there are hotplug thermal
 	sensors, like those inside the batteries and docks.
@@ -921,6 +973,7 @@ ftp://ftp.suse.com/pub/people/trenn/sources/ec
 
 Use it to determine the register holding the fan
 speed on some models. To do that, do the following:
+
 	- make sure the battery is fully charged
 	- make sure the fan is running
 	- use above mentioned tool to read out the EC
@@ -941,6 +994,7 @@ LCD brightness control
 ----------------------
 
 procfs: /proc/acpi/ibm/brightness
+
 sysfs backlight device "thinkpad_screen"
 
 This feature allows software control of the LCD brightness on ThinkPad
@@ -985,15 +1039,17 @@ brightness_enable=0 forces it to be disabled.  brightness_enable=1
 forces it to be enabled when available, even if the standard ACPI
 interface is also available.
 
-Procfs notes:
+Procfs notes
+^^^^^^^^^^^^
 
-	The available commands are:
+The available commands are::
 
 	echo up   >/proc/acpi/ibm/brightness
 	echo down >/proc/acpi/ibm/brightness
 	echo 'level <level>' >/proc/acpi/ibm/brightness
 
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
 
 The interface is implemented through the backlight sysfs class, which is
 poorly documented at this time.
@@ -1038,6 +1094,7 @@ Volume control (Console Audio control)
 --------------------------------------
 
 procfs: /proc/acpi/ibm/volume
+
 ALSA: "ThinkPad Console Audio Control", default ID: "ThinkPadEC"
 
 NOTE: by default, the volume control interface operates in read-only
@@ -1053,7 +1110,8 @@ Software volume control should be done only in the main AC97/HDA
 mixer.
 
 
-About the ThinkPad Console Audio control:
+About the ThinkPad Console Audio control
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ThinkPads have a built-in amplifier and muting circuit that drives the
 console headphone and speakers.  This circuit is after the main AC97
@@ -1092,13 +1150,14 @@ normal key presses to the operating system (thinkpad-acpi is not
 involved).
 
 
-The ThinkPad-ACPI volume control:
+The ThinkPad-ACPI volume control
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The preferred way to interact with the Console Audio control is the
 ALSA interface.
 
 The legacy procfs interface allows one to read the current state,
-and if volume control is enabled, accepts the following commands:
+and if volume control is enabled, accepts the following commands::
 
 	echo up   >/proc/acpi/ibm/volume
 	echo down >/proc/acpi/ibm/volume
@@ -1137,13 +1196,15 @@ Fan control and monitoring: fan speed, fan enable/disable
 ---------------------------------------------------------
 
 procfs: /proc/acpi/ibm/fan
-sysfs device attributes: (hwmon "thinkpad") fan1_input, pwm1,
-			  pwm1_enable, fan2_input
+
+sysfs device attributes: (hwmon "thinkpad") fan1_input, pwm1, pwm1_enable, fan2_input
+
 sysfs hwmon driver attributes: fan_watchdog
 
-NOTE NOTE NOTE: fan control operations are disabled by default for
-safety reasons.  To enable them, the module parameter "fan_control=1"
-must be given to thinkpad-acpi.
+NOTE NOTE NOTE:
+   fan control operations are disabled by default for
+   safety reasons.  To enable them, the module parameter "fan_control=1"
+   must be given to thinkpad-acpi.
 
 This feature attempts to show the current fan speed, control mode and
 other fan data that might be available.  The speed is read directly
@@ -1154,7 +1215,8 @@ value on other models.
 Some Lenovo ThinkPads support a secondary fan.  This fan cannot be
 controlled separately, it shares the main fan control.
 
-Fan levels:
+Fan levels
+^^^^^^^^^^
 
 Most ThinkPad fans work in "levels" at the firmware interface.  Level 0
 stops the fan.  The higher the level, the higher the fan speed, although
@@ -1209,9 +1271,10 @@ therefore, not suitable to protect against fan mode changes made through
 means other than the "enable", "disable", and "level" procfs fan
 commands, or the hwmon fan control sysfs interface.
 
-Procfs notes:
+Procfs notes
+^^^^^^^^^^^^
 
-The fan may be enabled or disabled with the following commands:
+The fan may be enabled or disabled with the following commands::
 
 	echo enable  >/proc/acpi/ibm/fan
 	echo disable >/proc/acpi/ibm/fan
@@ -1219,7 +1282,7 @@ The fan may be enabled or disabled with the following commands:
 Placing a fan on level 0 is the same as disabling it.  Enabling a fan
 will try to place it in a safe level if it is too slow or disabled.
 
-The fan level can be controlled with the command:
+The fan level can be controlled with the command::
 
 	echo 'level <level>' > /proc/acpi/ibm/fan
 
@@ -1231,7 +1294,7 @@ compatibility.
 
 On the X31 and X40 (and ONLY on those models), the fan speed can be
 controlled to a certain degree.  Once the fan is running, it can be
-forced to run faster or slower with the following command:
+forced to run faster or slower with the following command::
 
 	echo 'speed <speed>' > /proc/acpi/ibm/fan
 
@@ -1241,13 +1304,14 @@ effect or the fan speed eventually settles somewhere in that range.  The
 fan cannot be stopped or started with this command.  This functionality
 is incomplete, and not available through the sysfs interface.
 
-To program the safety watchdog, use the "watchdog" command.
+To program the safety watchdog, use the "watchdog" command::
 
 	echo 'watchdog <interval in seconds>' > /proc/acpi/ibm/fan
 
 If you want to disable the watchdog, use 0 as the interval.
 
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
 
 The sysfs interface follows the hwmon subsystem guidelines for the most
 part, and the exception is the fan safety watchdog.
@@ -1261,10 +1325,10 @@ to the firmware).
 Features not yet implemented by the driver return ENOSYS.
 
 hwmon device attribute pwm1_enable:
-	0: PWM offline (fan is set to full-speed mode)
-	1: Manual PWM control (use pwm1 to set fan level)
-	2: Hardware PWM control (EC "auto" mode)
-	3: reserved (Software PWM control, not implemented yet)
+	- 0: PWM offline (fan is set to full-speed mode)
+	- 1: Manual PWM control (use pwm1 to set fan level)
+	- 2: Hardware PWM control (EC "auto" mode)
+	- 3: reserved (Software PWM control, not implemented yet)
 
 	Modes 0 and 2 are not supported by all ThinkPads, and the
 	driver is not always able to detect this.  If it does know a
@@ -1304,7 +1368,9 @@ WAN
 ---
 
 procfs: /proc/acpi/ibm/wan
+
 sysfs device attribute: wwan_enable (deprecated)
+
 sysfs rfkill class: switch "tpacpi_wwan_sw"
 
 This feature shows the presence and current state of the built-in
@@ -1316,22 +1382,24 @@ so it is kept across reboots and power-off.
 It was tested on a Lenovo ThinkPad X60. It should probably work on other
 ThinkPad models which come with this module installed.
 
-Procfs notes:
+Procfs notes
+^^^^^^^^^^^^
 
-If the W-WAN card is installed, the following commands can be used:
+If the W-WAN card is installed, the following commands can be used::
 
 	echo enable > /proc/acpi/ibm/wan
 	echo disable > /proc/acpi/ibm/wan
 
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
 
 	If the W-WAN card is installed, it can be enabled /
 	disabled through the "wwan_enable" thinkpad-acpi device
 	attribute, and its current status can also be queried.
 
 	enable:
-		0: disables WWAN card / WWAN card is disabled
-		1: enables WWAN card / WWAN card is enabled.
+		- 0: disables WWAN card / WWAN card is disabled
+		- 1: enables WWAN card / WWAN card is enabled.
 
 	Note: this interface has been superseded by the	generic rfkill
 	class.  It has been deprecated, and it will be removed in year
@@ -1354,7 +1422,8 @@ sysfs rfkill class: switch "tpacpi_uwb_sw"
 This feature exports an rfkill controller for the UWB device, if one is
 present and enabled in the BIOS.
 
-Sysfs notes:
+Sysfs notes
+^^^^^^^^^^^
 
 	rfkill controller switch "tpacpi_uwb_sw": refer to
 	Documentation/rfkill.txt for details.
@@ -1368,11 +1437,11 @@ This sysfs attribute controls the keyboard "face" that will be shown on the
 Lenovo X1 Carbon 2nd gen (2014)'s adaptive keyboard. The value can be read
 and set.
 
-1 = Home mode
-2 = Web-browser mode
-3 = Web-conference mode
-4 = Function mode
-5 = Layflat mode
+- 1 = Home mode
+- 2 = Web-browser mode
+- 3 = Web-conference mode
+- 4 = Function mode
+- 5 = Layflat mode
 
 For more details about which buttons will appear depending on the mode, please
 review the laptop's user guide:
@@ -1382,13 +1451,13 @@ Multiple Commands, Module Parameters
 ------------------------------------
 
 Multiple commands can be written to the proc files in one shot by
-separating them with commas, for example:
+separating them with commas, for example::
 
 	echo enable,0xffff > /proc/acpi/ibm/hotkey
 	echo lcd_disable,crt_enable > /proc/acpi/ibm/video
 
 Commands can also be specified when loading the thinkpad-acpi module,
-for example:
+for example::
 
 	modprobe thinkpad_acpi hotkey=enable,0xffff video=auto_disable
 
@@ -1397,14 +1466,16 @@ Enabling debugging output
 -------------------------
 
 The module takes a debug parameter which can be used to selectively
-enable various classes of debugging output, for example:
+enable various classes of debugging output, for example::
 
 	 modprobe thinkpad_acpi debug=0xffff
 
 will enable all debugging output classes.  It takes a bitmask, so
 to enable more than one output class, just add their values.
 
+	=============		======================================
 	Debug bitmask		Description
+	=============		======================================
 	0x8000			Disclose PID of userspace programs
 				accessing some functions of the driver
 	0x0001			Initialization and probing
@@ -1415,6 +1486,7 @@ to enable more than one output class, just add their values.
 	0x0010			Fan control
 	0x0020			Backlight brightness
 	0x0040			Audio mixer/volume control
+	=============		======================================
 
 There is also a kernel build option to enable more debugging
 information, which may be necessary to debug driver problems.
@@ -1432,8 +1504,10 @@ the module parameter force_load=1.  Regardless of whether this works or
 not, please contact ibm-acpi-devel@lists.sourceforge.net with a report.
 
 
-Sysfs interface changelog:
+Sysfs interface changelog
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
+=========	===============================================================
 0x000100:	Initial sysfs support, as a single platform driver and
 		device.
 0x000200:	Hot key support for 32 hot keys, and radio slider switch
@@ -1485,3 +1559,4 @@ Sysfs interface changelog:
 0x030000:	Thermal and fan sysfs attributes were moved to the hwmon
 		device instead of being attached to the backing platform
 		device.
+=========	===============================================================
diff --git a/Documentation/laptops/toshiba_haps.txt b/Documentation/laptops/toshiba_haps.rst
similarity index 60%
rename from Documentation/laptops/toshiba_haps.txt
rename to Documentation/laptops/toshiba_haps.rst
index 0c1d88dedbde..11dfc428c080 100644
--- a/Documentation/laptops/toshiba_haps.txt
+++ b/Documentation/laptops/toshiba_haps.rst
@@ -1,18 +1,19 @@
-Kernel driver toshiba_haps
+====================================
 Toshiba HDD Active Protection Sensor
 ====================================
 
+Kernel driver: toshiba_haps
+
 Author: Azael Avalos <coproscefalo@gmail.com>
 
 
-0. Contents
------------
+.. 0. Contents
 
-1. Description
-2. Interface
-3. Accelerometer axes
-4. Supported devices
-5. Usage
+   1. Description
+   2. Interface
+   3. Accelerometer axes
+   4. Supported devices
+   5. Usage
 
 
 1. Description
@@ -32,17 +33,20 @@ file to set the desired protection level or sensor sensibility.
 ------------
 
 This device comes with 3 methods:
-_STA -  Checks existence of the device, returning Zero if the device does not
+
+====	=====================================================================
+_STA    Checks existence of the device, returning Zero if the device does not
 	exists or is not supported.
-PTLV -  Sets the desired protection level.
-RSSS -  Shuts down the HDD protection interface for a few seconds,
+PTLV    Sets the desired protection level.
+RSSS    Shuts down the HDD protection interface for a few seconds,
 	then restores normal operation.
+====	=====================================================================
 
 Note:
-The presence of Solid State Drives (SSD) can make this driver to fail loading,
-given the fact that such drives have no movable parts, and thus, not requiring
-any "protection" as well as failing during the evaluation of the _STA method
-found under this device.
+  The presence of Solid State Drives (SSD) can make this driver to fail loading,
+  given the fact that such drives have no movable parts, and thus, not requiring
+  any "protection" as well as failing during the evaluation of the _STA method
+  found under this device.
 
 
 3. Accelerometer axes
@@ -66,11 +70,18 @@ conventional HDD and not only SSD, or a combination of both HDD and SSD.
 --------
 
 The sysfs files under /sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS620A:00/ are:
-protection_level - The protection_level is readable and writeable, and
+
+================   ============================================================
+protection_level   The protection_level is readable and writeable, and
 		   provides a way to let userspace query the current protection
 		   level, as well as set the desired protection level, the
 		   available protection levels are:
-		   0 - Disabled | 1 - Low | 2 - Medium | 3 - High
-reset_protection - The reset_protection entry is writeable only, being "1"
+
+		   ============   =======   ==========   ========
+		   0 - Disabled   1 - Low   2 - Medium   3 - High
+		   ============   =======   ==========   ========
+
+reset_protection   The reset_protection entry is writeable only, being "1"
 		   the only parameter it accepts, it is used to trigger
 		   a reset of the protection interface.
+================   ============================================================
diff --git a/Documentation/sysctl/vm.txt b/Documentation/sysctl/vm.txt
index 749322060f10..c5f0d44433a2 100644
--- a/Documentation/sysctl/vm.txt
+++ b/Documentation/sysctl/vm.txt
@@ -102,7 +102,7 @@ Changing this takes effect whenever an application requests memory.
 block_dump
 
 block_dump enables block I/O debugging when set to a nonzero value. More
-information on block I/O debugging is in Documentation/laptops/laptop-mode.txt.
+information on block I/O debugging is in Documentation/laptops/laptop-mode.rst.
 
 ==============================================================
 
@@ -286,7 +286,7 @@ shared memory segment using hugetlb page.
 laptop_mode
 
 laptop_mode is a knob that controls "laptop mode". All the things that are
-controlled by this knob are discussed in Documentation/laptops/laptop-mode.txt.
+controlled by this knob are discussed in Documentation/laptops/laptop-mode.rst.
 
 ==============================================================
 
diff --git a/MAINTAINERS b/MAINTAINERS
index b7d5faf95e25..58e103015dea 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14756,7 +14756,7 @@ M:	Mattia Dongili <malattia@linux.it>
 L:	platform-driver-x86@vger.kernel.org
 W:	http://www.linux.it/~malattia/wiki/index.php/Sony_drivers
 S:	Maintained
-F:	Documentation/laptops/sony-laptop.txt
+F:	Documentation/laptops/sony-laptop.rst
 F:	drivers/char/sonypi.c
 F:	drivers/platform/x86/sony-laptop.c
 F:	include/linux/sony-laptop.h
diff --git a/drivers/char/Kconfig b/drivers/char/Kconfig
index 466ebd84ad17..bb734066075f 100644
--- a/drivers/char/Kconfig
+++ b/drivers/char/Kconfig
@@ -382,7 +382,7 @@ config SONYPI
 	  Device which can be found in many (all ?) Sony Vaio laptops.
 
 	  If you have one of those laptops, read
-	  <file:Documentation/laptops/sonypi.txt>, and say Y or M here.
+	  <file:Documentation/laptops/sonypi.rst>, and say Y or M here.
 
 	  To compile this driver as a module, choose M here: the
 	  module will be called sonypi.
diff --git a/drivers/platform/x86/Kconfig b/drivers/platform/x86/Kconfig
index bd15b47abcb4..abae73f72e75 100644
--- a/drivers/platform/x86/Kconfig
+++ b/drivers/platform/x86/Kconfig
@@ -451,7 +451,7 @@ config SONY_LAPTOP
 	  screen brightness control, Fn keys and allows powering on/off some
 	  devices.
 
-	  Read <file:Documentation/laptops/sony-laptop.txt> for more information.
+	  Read <file:Documentation/laptops/sony-laptop.rst> for more information.
 
 config SONYPI_COMPAT
 	bool "Sonypi compatibility"
@@ -503,7 +503,7 @@ config THINKPAD_ACPI
 	  support for Fn-Fx key combinations, Bluetooth control, video
 	  output switching, ThinkLight control, UltraBay eject and more.
 	  For more information about this driver see
-	  <file:Documentation/laptops/thinkpad-acpi.txt> and
+	  <file:Documentation/laptops/thinkpad-acpi.rst> and
 	  <http://ibm-acpi.sf.net/> .
 
 	  This driver was formerly known as ibm-acpi.
-- 
2.21.0

[PATCH v2 22/29] docs: iio: convert to ReST

[Mauro Carvalho Chehab]

Rename the iio documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

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>
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
---
 .../iio/{ep93xx_adc.txt => ep93xx_adc.rst}    | 15 +++++-
 .../{iio_configfs.txt => iio_configfs.rst}    | 52 +++++++++++--------
 Documentation/iio/index.rst                   | 12 +++++
 drivers/iio/Kconfig                           |  2 +-
 4 files changed, 56 insertions(+), 25 deletions(-)
 rename Documentation/iio/{ep93xx_adc.txt => ep93xx_adc.rst} (71%)
 rename Documentation/iio/{iio_configfs.txt => iio_configfs.rst} (73%)
 create mode 100644 Documentation/iio/index.rst

diff --git a/Documentation/iio/ep93xx_adc.txt b/Documentation/iio/ep93xx_adc.rst
similarity index 71%
rename from Documentation/iio/ep93xx_adc.txt
rename to Documentation/iio/ep93xx_adc.rst
index 23053e7817bd..4fd8dea3f6b8 100644
--- a/Documentation/iio/ep93xx_adc.txt
+++ b/Documentation/iio/ep93xx_adc.rst
@@ -1,12 +1,16 @@
-Cirrus Logic EP93xx ADC driver.
+==============================
+Cirrus Logic EP93xx ADC driver
+==============================
 
 1. Overview
+===========
 
 The driver is intended to work on both low-end (EP9301, EP9302) devices with
 5-channel ADC and high-end (EP9307, EP9312, EP9315) devices with 10-channel
 touchscreen/ADC module.
 
 2. Channel numbering
+====================
 
 Numbering scheme for channels 0..4 is defined in EP9301 and EP9302 datasheets.
 EP9307, EP9312 and EP9312 have 3 channels more (total 8), but the numbering is
@@ -17,13 +21,20 @@ Assuming ep93xx_adc is IIO device0, you'd find the following entries under
 
   +-----------------+---------------+
   | sysfs entry     | ball/pin name |
-  +-----------------+---------------+
+  +=================+===============+
   | in_voltage0_raw | YM            |
+  +-----------------+---------------+
   | in_voltage1_raw | SXP           |
+  +-----------------+---------------+
   | in_voltage2_raw | SXM           |
+  +-----------------+---------------+
   | in_voltage3_raw | SYP           |
+  +-----------------+---------------+
   | in_voltage4_raw | SYM           |
+  +-----------------+---------------+
   | in_voltage5_raw | XP            |
+  +-----------------+---------------+
   | in_voltage6_raw | XM            |
+  +-----------------+---------------+
   | in_voltage7_raw | YP            |
   +-----------------+---------------+
diff --git a/Documentation/iio/iio_configfs.txt b/Documentation/iio/iio_configfs.rst
similarity index 73%
rename from Documentation/iio/iio_configfs.txt
rename to Documentation/iio/iio_configfs.rst
index 4e5f101837a8..ecbfdb3afef7 100644
--- a/Documentation/iio/iio_configfs.txt
+++ b/Documentation/iio/iio_configfs.rst
@@ -1,6 +1,9 @@
+===============================
 Industrial IIO configfs support
+===============================
 
 1. Overview
+===========
 
 Configfs is a filesystem-based manager of kernel objects. IIO uses some
 objects that could be easily configured using configfs (e.g.: devices,
@@ -10,20 +13,22 @@ See Documentation/filesystems/configfs/configfs.txt for more information
 about how configfs works.
 
 2. Usage
+========
 
 In order to use configfs support in IIO we need to select it at compile
 time via CONFIG_IIO_CONFIGFS config option.
 
-Then, mount the configfs filesystem (usually under /config directory):
+Then, mount the configfs filesystem (usually under /config directory)::
 
-$ mkdir /config
-$ mount -t configfs none /config
+  $ mkdir /config
+  $ mount -t configfs none /config
 
 At this point, all default IIO groups will be created and can be accessed
 under /config/iio. Next chapters will describe available IIO configuration
 objects.
 
 3. Software triggers
+====================
 
 One of the IIO default configfs groups is the "triggers" group. It is
 automagically accessible when the configfs is mounted and can be found
@@ -31,40 +36,40 @@ under /config/iio/triggers.
 
 IIO software triggers implementation offers support for creating multiple
 trigger types. A new trigger type is usually implemented as a separate
-kernel module following the interface in include/linux/iio/sw_trigger.h:
+kernel module following the interface in include/linux/iio/sw_trigger.h::
 
-/*
- * drivers/iio/trigger/iio-trig-sample.c
- * sample kernel module implementing a new trigger type
- */
-#include <linux/iio/sw_trigger.h>
+  /*
+   * drivers/iio/trigger/iio-trig-sample.c
+   * sample kernel module implementing a new trigger type
+   */
+  #include <linux/iio/sw_trigger.h>
 
 
-static struct iio_sw_trigger *iio_trig_sample_probe(const char *name)
-{
+  static struct iio_sw_trigger *iio_trig_sample_probe(const char *name)
+  {
 	/*
 	 * This allocates and registers an IIO trigger plus other
 	 * trigger type specific initialization.
 	 */
-}
+  }
 
-static int iio_trig_hrtimer_remove(struct iio_sw_trigger *swt)
-{
+  static int iio_trig_hrtimer_remove(struct iio_sw_trigger *swt)
+  {
 	/*
 	 * This undoes the actions in iio_trig_sample_probe
 	 */
-}
+  }
 
-static const struct iio_sw_trigger_ops iio_trig_sample_ops = {
+  static const struct iio_sw_trigger_ops iio_trig_sample_ops = {
 	.probe		= iio_trig_sample_probe,
 	.remove		= iio_trig_sample_remove,
-};
+  };
 
-static struct iio_sw_trigger_type iio_trig_sample = {
+  static struct iio_sw_trigger_type iio_trig_sample = {
 	.name = "trig-sample",
 	.owner = THIS_MODULE,
 	.ops = &iio_trig_sample_ops,
-};
+  };
 
 module_iio_sw_trigger_driver(iio_trig_sample);
 
@@ -73,21 +78,24 @@ iio-trig-sample module will create 'trig-sample' trigger type directory
 /config/iio/triggers/trig-sample.
 
 We support the following interrupt sources (trigger types):
+
 	* hrtimer, uses high resolution timers as interrupt source
 
 3.1 Hrtimer triggers creation and destruction
+---------------------------------------------
 
 Loading iio-trig-hrtimer module will register hrtimer trigger types allowing
 users to create hrtimer triggers under /config/iio/triggers/hrtimer.
 
-e.g:
+e.g::
 
-$ mkdir /config/iio/triggers/hrtimer/instance1
-$ rmdir /config/iio/triggers/hrtimer/instance1
+  $ mkdir /config/iio/triggers/hrtimer/instance1
+  $ rmdir /config/iio/triggers/hrtimer/instance1
 
 Each trigger can have one or more attributes specific to the trigger type.
 
 3.2 "hrtimer" trigger types attributes
+--------------------------------------
 
 "hrtimer" trigger type doesn't have any configurable attribute from /config dir.
 It does introduce the sampling_frequency attribute to trigger directory.
diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
new file mode 100644
index 000000000000..0593dca89a94
--- /dev/null
+++ b/Documentation/iio/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+==============
+Industrial I/O
+==============
+
+.. toctree::
+   :maxdepth: 1
+
+   iio_configfs
+
+   ep93xx_adc
diff --git a/drivers/iio/Kconfig b/drivers/iio/Kconfig
index 1d736a4952ab..5bd51853b15e 100644
--- a/drivers/iio/Kconfig
+++ b/drivers/iio/Kconfig
@@ -28,7 +28,7 @@ config IIO_CONFIGFS
 	help
 	  This allows configuring various IIO bits through configfs
 	  (e.g. software triggers). For more info see
-	  Documentation/iio/iio_configfs.txt.
+	  Documentation/iio/iio_configfs.rst.
 
 config IIO_TRIGGER
 	bool "Enable triggered sampling support"
-- 
2.21.0

Re: [PATCH v2 22/29] docs: iio: convert to ReST

[Jonathan Cameron]

On Tue, 18 Jun 2019 17:53:40 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> Rename the iio documentation files to ReST, add an
> index for them and adjust in order to produce a nice html
> output via the Sphinx build system.
> 
> 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>
> Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
I'll take this via IIO.

Applied to the togreg branch of iio.git and pushed out as testing.
I'll probably do a pull request to Greg tomorrow and these will hopefully
turn up in linux-next not long after that.

Thanks Mauro!

Jonathan

> ---
>  .../iio/{ep93xx_adc.txt => ep93xx_adc.rst}    | 15 +++++-
>  .../{iio_configfs.txt => iio_configfs.rst}    | 52 +++++++++++--------
>  Documentation/iio/index.rst                   | 12 +++++
>  drivers/iio/Kconfig                           |  2 +-
>  4 files changed, 56 insertions(+), 25 deletions(-)
>  rename Documentation/iio/{ep93xx_adc.txt => ep93xx_adc.rst} (71%)
>  rename Documentation/iio/{iio_configfs.txt => iio_configfs.rst} (73%)
>  create mode 100644 Documentation/iio/index.rst
> 
> diff --git a/Documentation/iio/ep93xx_adc.txt b/Documentation/iio/ep93xx_adc.rst
> similarity index 71%
> rename from Documentation/iio/ep93xx_adc.txt
> rename to Documentation/iio/ep93xx_adc.rst
> index 23053e7817bd..4fd8dea3f6b8 100644
> --- a/Documentation/iio/ep93xx_adc.txt
> +++ b/Documentation/iio/ep93xx_adc.rst
> @@ -1,12 +1,16 @@
> -Cirrus Logic EP93xx ADC driver.
> +==============================
> +Cirrus Logic EP93xx ADC driver
> +==============================
>  
>  1. Overview
> +===========
>  
>  The driver is intended to work on both low-end (EP9301, EP9302) devices with
>  5-channel ADC and high-end (EP9307, EP9312, EP9315) devices with 10-channel
>  touchscreen/ADC module.
>  
>  2. Channel numbering
> +====================
>  
>  Numbering scheme for channels 0..4 is defined in EP9301 and EP9302 datasheets.
>  EP9307, EP9312 and EP9312 have 3 channels more (total 8), but the numbering is
> @@ -17,13 +21,20 @@ Assuming ep93xx_adc is IIO device0, you'd find the following entries under
>  
>    +-----------------+---------------+
>    | sysfs entry     | ball/pin name |
> -  +-----------------+---------------+
> +  +=================+===============+
>    | in_voltage0_raw | YM            |
> +  +-----------------+---------------+
>    | in_voltage1_raw | SXP           |
> +  +-----------------+---------------+
>    | in_voltage2_raw | SXM           |
> +  +-----------------+---------------+
>    | in_voltage3_raw | SYP           |
> +  +-----------------+---------------+
>    | in_voltage4_raw | SYM           |
> +  +-----------------+---------------+
>    | in_voltage5_raw | XP            |
> +  +-----------------+---------------+
>    | in_voltage6_raw | XM            |
> +  +-----------------+---------------+
>    | in_voltage7_raw | YP            |
>    +-----------------+---------------+
> diff --git a/Documentation/iio/iio_configfs.txt b/Documentation/iio/iio_configfs.rst
> similarity index 73%
> rename from Documentation/iio/iio_configfs.txt
> rename to Documentation/iio/iio_configfs.rst
> index 4e5f101837a8..ecbfdb3afef7 100644
> --- a/Documentation/iio/iio_configfs.txt
> +++ b/Documentation/iio/iio_configfs.rst
> @@ -1,6 +1,9 @@
> +===============================
>  Industrial IIO configfs support
> +===============================
>  
>  1. Overview
> +===========
>  
>  Configfs is a filesystem-based manager of kernel objects. IIO uses some
>  objects that could be easily configured using configfs (e.g.: devices,
> @@ -10,20 +13,22 @@ See Documentation/filesystems/configfs/configfs.txt for more information
>  about how configfs works.
>  
>  2. Usage
> +========
>  
>  In order to use configfs support in IIO we need to select it at compile
>  time via CONFIG_IIO_CONFIGFS config option.
>  
> -Then, mount the configfs filesystem (usually under /config directory):
> +Then, mount the configfs filesystem (usually under /config directory)::
>  
> -$ mkdir /config
> -$ mount -t configfs none /config
> +  $ mkdir /config
> +  $ mount -t configfs none /config
>  
>  At this point, all default IIO groups will be created and can be accessed
>  under /config/iio. Next chapters will describe available IIO configuration
>  objects.
>  
>  3. Software triggers
> +====================
>  
>  One of the IIO default configfs groups is the "triggers" group. It is
>  automagically accessible when the configfs is mounted and can be found
> @@ -31,40 +36,40 @@ under /config/iio/triggers.
>  
>  IIO software triggers implementation offers support for creating multiple
>  trigger types. A new trigger type is usually implemented as a separate
> -kernel module following the interface in include/linux/iio/sw_trigger.h:
> +kernel module following the interface in include/linux/iio/sw_trigger.h::
>  
> -/*
> - * drivers/iio/trigger/iio-trig-sample.c
> - * sample kernel module implementing a new trigger type
> - */
> -#include <linux/iio/sw_trigger.h>
> +  /*
> +   * drivers/iio/trigger/iio-trig-sample.c
> +   * sample kernel module implementing a new trigger type
> +   */
> +  #include <linux/iio/sw_trigger.h>
>  
>  
> -static struct iio_sw_trigger *iio_trig_sample_probe(const char *name)
> -{
> +  static struct iio_sw_trigger *iio_trig_sample_probe(const char *name)
> +  {
>  	/*
>  	 * This allocates and registers an IIO trigger plus other
>  	 * trigger type specific initialization.
>  	 */
> -}
> +  }
>  
> -static int iio_trig_hrtimer_remove(struct iio_sw_trigger *swt)
> -{
> +  static int iio_trig_hrtimer_remove(struct iio_sw_trigger *swt)
> +  {
>  	/*
>  	 * This undoes the actions in iio_trig_sample_probe
>  	 */
> -}
> +  }
>  
> -static const struct iio_sw_trigger_ops iio_trig_sample_ops = {
> +  static const struct iio_sw_trigger_ops iio_trig_sample_ops = {
>  	.probe		= iio_trig_sample_probe,
>  	.remove		= iio_trig_sample_remove,
> -};
> +  };
>  
> -static struct iio_sw_trigger_type iio_trig_sample = {
> +  static struct iio_sw_trigger_type iio_trig_sample = {
>  	.name = "trig-sample",
>  	.owner = THIS_MODULE,
>  	.ops = &iio_trig_sample_ops,
> -};
> +  };
>  
>  module_iio_sw_trigger_driver(iio_trig_sample);
>  
> @@ -73,21 +78,24 @@ iio-trig-sample module will create 'trig-sample' trigger type directory
>  /config/iio/triggers/trig-sample.
>  
>  We support the following interrupt sources (trigger types):
> +
>  	* hrtimer, uses high resolution timers as interrupt source
>  
>  3.1 Hrtimer triggers creation and destruction
> +---------------------------------------------
>  
>  Loading iio-trig-hrtimer module will register hrtimer trigger types allowing
>  users to create hrtimer triggers under /config/iio/triggers/hrtimer.
>  
> -e.g:
> +e.g::
>  
> -$ mkdir /config/iio/triggers/hrtimer/instance1
> -$ rmdir /config/iio/triggers/hrtimer/instance1
> +  $ mkdir /config/iio/triggers/hrtimer/instance1
> +  $ rmdir /config/iio/triggers/hrtimer/instance1
>  
>  Each trigger can have one or more attributes specific to the trigger type.
>  
>  3.2 "hrtimer" trigger types attributes
> +--------------------------------------
>  
>  "hrtimer" trigger type doesn't have any configurable attribute from /config dir.
>  It does introduce the sampling_frequency attribute to trigger directory.
> diff --git a/Documentation/iio/index.rst b/Documentation/iio/index.rst
> new file mode 100644
> index 000000000000..0593dca89a94
> --- /dev/null
> +++ b/Documentation/iio/index.rst
> @@ -0,0 +1,12 @@
> +:orphan:
> +
> +==============
> +Industrial I/O
> +==============
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   iio_configfs
> +
> +   ep93xx_adc
> diff --git a/drivers/iio/Kconfig b/drivers/iio/Kconfig
> index 1d736a4952ab..5bd51853b15e 100644
> --- a/drivers/iio/Kconfig
> +++ b/drivers/iio/Kconfig
> @@ -28,7 +28,7 @@ config IIO_CONFIGFS
>  	help
>  	  This allows configuring various IIO bits through configfs
>  	  (e.g. software triggers). For more info see
> -	  Documentation/iio/iio_configfs.txt.
> +	  Documentation/iio/iio_configfs.rst.
>  
>  config IIO_TRIGGER
>  	bool "Enable triggered sampling support"

[PATCH v2 23/29] docs: namespaces: convert to ReST

[Mauro Carvalho Chehab]

Rename the namespaces documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

There are two upper case file names. Rename them to
lower case, as we're working to avoid upper case file
names at Documentation.

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>
---
 ...{compatibility-list.txt => compatibility-list.rst} | 10 +++++++---
 Documentation/namespaces/index.rst                    | 11 +++++++++++
 .../{resource-control.txt => resource-control.rst}    |  4 ++++
 3 files changed, 22 insertions(+), 3 deletions(-)
 rename Documentation/namespaces/{compatibility-list.txt => compatibility-list.rst} (86%)
 create mode 100644 Documentation/namespaces/index.rst
 rename Documentation/namespaces/{resource-control.txt => resource-control.rst} (89%)

diff --git a/Documentation/namespaces/compatibility-list.txt b/Documentation/namespaces/compatibility-list.rst
similarity index 86%
rename from Documentation/namespaces/compatibility-list.txt
rename to Documentation/namespaces/compatibility-list.rst
index defc5589bfcd..318800b2a943 100644
--- a/Documentation/namespaces/compatibility-list.txt
+++ b/Documentation/namespaces/compatibility-list.rst
@@ -1,4 +1,6 @@
-	Namespaces compatibility list
+=============================
+Namespaces compatibility list
+=============================
 
 This document contains the information about the problems user
 may have when creating tasks living in different namespaces.
@@ -7,13 +9,16 @@ Here's the summary. This matrix shows the known problems, that
 occur when tasks share some namespace (the columns) while living
 in different other namespaces (the rows):
 
-	UTS	IPC	VFS	PID	User	Net
+====	===	===	===	===	====	===
+-	UTS	IPC	VFS	PID	User	Net
+====	===	===	===	===	====	===
 UTS	 X
 IPC		 X	 1
 VFS			 X
 PID		 1	 1	 X
 User		 2	 2		 X
 Net						 X
+====	===	===	===	===	====	===
 
 1. Both the IPC and the PID namespaces provide IDs to address
    object inside the kernel. E.g. semaphore with IPCID or
@@ -36,4 +41,3 @@ Net						 X
    even having equal UIDs.
 
    But currently this is not so.
-
diff --git a/Documentation/namespaces/index.rst b/Documentation/namespaces/index.rst
new file mode 100644
index 000000000000..bf40625dd11a
--- /dev/null
+++ b/Documentation/namespaces/index.rst
@@ -0,0 +1,11 @@
+:orphan:
+
+==========
+Namespaces
+==========
+
+.. toctree::
+   :maxdepth: 1
+
+   compatibility-list
+   resource-control
diff --git a/Documentation/namespaces/resource-control.txt b/Documentation/namespaces/resource-control.rst
similarity index 89%
rename from Documentation/namespaces/resource-control.txt
rename to Documentation/namespaces/resource-control.rst
index abc13c394738..369556e00f0c 100644
--- a/Documentation/namespaces/resource-control.txt
+++ b/Documentation/namespaces/resource-control.rst
@@ -1,3 +1,7 @@
+===========================
+Namespaces research control
+===========================
+
 There are a lot of kinds of objects in the kernel that don't have
 individual limits or that have limits that are ineffective when a set
 of processes is allowed to switch user ids.  With user namespaces
-- 
2.21.0

[PATCH v2 24/29] docs: nfc: convert to ReST

[Mauro Carvalho Chehab]

Rename the nfc documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

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/nfc/index.rst                   |  11 ++
 .../nfc/{nfc-hci.txt => nfc-hci.rst}          | 163 ++++++++++--------
 .../nfc/{nfc-pn544.txt => nfc-pn544.rst}      |   6 +-
 3 files changed, 107 insertions(+), 73 deletions(-)
 create mode 100644 Documentation/nfc/index.rst
 rename Documentation/nfc/{nfc-hci.txt => nfc-hci.rst} (71%)
 rename Documentation/nfc/{nfc-pn544.txt => nfc-pn544.rst} (82%)

diff --git a/Documentation/nfc/index.rst b/Documentation/nfc/index.rst
new file mode 100644
index 000000000000..4f4947fce80d
--- /dev/null
+++ b/Documentation/nfc/index.rst
@@ -0,0 +1,11 @@
+:orphan:
+
+========================
+Near Field Communication
+========================
+
+.. toctree::
+   :maxdepth: 1
+
+   nfc-hci
+   nfc-pn544
diff --git a/Documentation/nfc/nfc-hci.txt b/Documentation/nfc/nfc-hci.rst
similarity index 71%
rename from Documentation/nfc/nfc-hci.txt
rename to Documentation/nfc/nfc-hci.rst
index 0dc078cab972..eb8a1a14e919 100644
--- a/Documentation/nfc/nfc-hci.txt
+++ b/Documentation/nfc/nfc-hci.rst
@@ -1,7 +1,9 @@
+========================
 HCI backend for NFC Core
+========================
 
-Author: Eric Lapuyade, Samuel Ortiz
-Contact: eric.lapuyade@intel.com, samuel.ortiz@intel.com
+- Author: Eric Lapuyade, Samuel Ortiz
+- Contact: eric.lapuyade@intel.com, samuel.ortiz@intel.com
 
 General
 -------
@@ -24,12 +26,13 @@ HCI events can also be received from the host controller. They will be handled
 and a translation will be forwarded to NFC Core as needed. There are hooks to
 let the HCI driver handle proprietary events or override standard behavior.
 HCI uses 2 execution contexts:
+
 - one for executing commands : nfc_hci_msg_tx_work(). Only one command
-can be executing at any given moment.
+  can be executing at any given moment.
 - one for dispatching received events and commands : nfc_hci_msg_rx_work().
 
-HCI Session initialization:
----------------------------
+HCI Session initialization
+--------------------------
 
 The Session initialization is an HCI standard which must unfortunately
 support proprietary gates. This is the reason why the driver will pass a list
@@ -58,9 +61,9 @@ HCI Management
 --------------
 
 A driver would normally register itself with HCI and provide the following
-entry points:
+entry points::
 
-struct nfc_hci_ops {
+  struct nfc_hci_ops {
 	int (*open)(struct nfc_hci_dev *hdev);
 	void (*close)(struct nfc_hci_dev *hdev);
 	int (*hci_ready) (struct nfc_hci_dev *hdev);
@@ -82,38 +85,38 @@ struct nfc_hci_ops {
 			      struct nfc_target *target);
 	int (*event_received)(struct nfc_hci_dev *hdev, u8 gate, u8 event,
 			      struct sk_buff *skb);
-};
+  };
 
 - open() and close() shall turn the hardware on and off.
 - hci_ready() is an optional entry point that is called right after the hci
-session has been set up. The driver can use it to do additional initialization
-that must be performed using HCI commands.
+  session has been set up. The driver can use it to do additional initialization
+  that must be performed using HCI commands.
 - xmit() shall simply write a frame to the physical link.
 - start_poll() is an optional entrypoint that shall set the hardware in polling
-mode. This must be implemented only if the hardware uses proprietary gates or a
-mechanism slightly different from the HCI standard.
+  mode. This must be implemented only if the hardware uses proprietary gates or a
+  mechanism slightly different from the HCI standard.
 - dep_link_up() is called after a p2p target has been detected, to finish
-the p2p connection setup with hardware parameters that need to be passed back
-to nfc core.
+  the p2p connection setup with hardware parameters that need to be passed back
+  to nfc core.
 - dep_link_down() is called to bring the p2p link down.
 - target_from_gate() is an optional entrypoint to return the nfc protocols
-corresponding to a proprietary gate.
+  corresponding to a proprietary gate.
 - complete_target_discovered() is an optional entry point to let the driver
-perform additional proprietary processing necessary to auto activate the
-discovered target.
+  perform additional proprietary processing necessary to auto activate the
+  discovered target.
 - im_transceive() must be implemented by the driver if proprietary HCI commands
-are required to send data to the tag. Some tag types will require custom
-commands, others can be written to using the standard HCI commands. The driver
-can check the tag type and either do proprietary processing, or return 1 to ask
-for standard processing. The data exchange command itself must be sent
-asynchronously.
+  are required to send data to the tag. Some tag types will require custom
+  commands, others can be written to using the standard HCI commands. The driver
+  can check the tag type and either do proprietary processing, or return 1 to ask
+  for standard processing. The data exchange command itself must be sent
+  asynchronously.
 - tm_send() is called to send data in the case of a p2p connection
 - check_presence() is an optional entry point that will be called regularly
-by the core to check that an activated tag is still in the field. If this is
-not implemented, the core will not be able to push tag_lost events to the user
-space
+  by the core to check that an activated tag is still in the field. If this is
+  not implemented, the core will not be able to push tag_lost events to the user
+  space
 - event_received() is called to handle an event coming from the chip. Driver
-can handle the event or return 1 to let HCI attempt standard processing.
+  can handle the event or return 1 to let HCI attempt standard processing.
 
 On the rx path, the driver is responsible to push incoming HCP frames to HCI
 using nfc_hci_recv_frame(). HCI will take care of re-aggregation and handling
@@ -122,20 +125,23 @@ This must be done from a context that can sleep.
 PHY Management
 --------------
 
-The physical link (i2c, ...) management is defined by the following structure:
+The physical link (i2c, ...) management is defined by the following structure::
 
-struct nfc_phy_ops {
+  struct nfc_phy_ops {
 	int (*write)(void *dev_id, struct sk_buff *skb);
 	int (*enable)(void *dev_id);
 	void (*disable)(void *dev_id);
-};
+  };
 
-enable(): turn the phy on (power on), make it ready to transfer data
-disable(): turn the phy off
-write(): Send a data frame to the chip. Note that to enable higher
-layers such as an llc to store the frame for re-emission, this function must
-not alter the skb. It must also not return a positive result (return 0 for
-success, negative for failure).
+enable():
+	turn the phy on (power on), make it ready to transfer data
+disable():
+	turn the phy off
+write():
+	Send a data frame to the chip. Note that to enable higher
+	layers such as an llc to store the frame for re-emission, this
+	function must not alter the skb. It must also not return a positive
+	result (return 0 for success, negative for failure).
 
 Data coming from the chip shall be sent directly to nfc_hci_recv_frame().
 
@@ -145,9 +151,9 @@ LLC
 Communication between the CPU and the chip often requires some link layer
 protocol. Those are isolated as modules managed by the HCI layer. There are
 currently two modules : nop (raw transfert) and shdlc.
-A new llc must implement the following functions:
+A new llc must implement the following functions::
 
-struct nfc_llc_ops {
+  struct nfc_llc_ops {
 	void *(*init) (struct nfc_hci_dev *hdev, xmit_to_drv_t xmit_to_drv,
 		       rcv_to_hci_t rcv_to_hci, int tx_headroom,
 		       int tx_tailroom, int *rx_headroom, int *rx_tailroom,
@@ -157,17 +163,25 @@ struct nfc_llc_ops {
 	int (*stop) (struct nfc_llc *llc);
 	void (*rcv_from_drv) (struct nfc_llc *llc, struct sk_buff *skb);
 	int (*xmit_from_hci) (struct nfc_llc *llc, struct sk_buff *skb);
-};
+  };
 
-- init() : allocate and init your private storage
-- deinit() : cleanup
-- start() : establish the logical connection
-- stop () : terminate the logical connection
-- rcv_from_drv() : handle data coming from the chip, going to HCI
-- xmit_from_hci() : handle data sent by HCI, going to the chip
+init():
+	allocate and init your private storage
+deinit():
+	cleanup
+start():
+	establish the logical connection
+stop ():
+	terminate the logical connection
+rcv_from_drv():
+	handle data coming from the chip, going to HCI
+xmit_from_hci():
+	handle data sent by HCI, going to the chip
 
 The llc must be registered with nfc before it can be used. Do that by
-calling nfc_llc_register(const char *name, struct nfc_llc_ops *ops);
+calling::
+
+	nfc_llc_register(const char *name, struct nfc_llc_ops *ops);
 
 Again, note that the llc does not handle the physical link. It is thus very
 easy to mix any physical link with any llc for a given chip driver.
@@ -187,26 +201,32 @@ fast, cannot sleep. sends incoming frames to HCI where they are passed to
 the current llc. In case of shdlc, the frame is queued in shdlc rx queue.
 
 - SHDLC State Machine worker (SMW)
-Only when llc_shdlc is used: handles shdlc rx & tx queues.
-Dispatches HCI cmd responses.
+
+  Only when llc_shdlc is used: handles shdlc rx & tx queues.
+
+  Dispatches HCI cmd responses.
 
 - HCI Tx Cmd worker (MSGTXWQ)
-Serializes execution of HCI commands. Completes execution in case of response
-timeout.
+
+  Serializes execution of HCI commands.
+
+  Completes execution in case of response timeout.
 
 - HCI Rx worker (MSGRXWQ)
-Dispatches incoming HCI commands or events.
+
+  Dispatches incoming HCI commands or events.
 
 - Syscall context from a userspace call (SYSCALL)
-Any entrypoint in HCI called from NFC Core
+
+  Any entrypoint in HCI called from NFC Core
 
 Workflow executing an HCI command (using shdlc)
 -----------------------------------------------
 
 Executing an HCI command can easily be performed synchronously using the
-following API:
+following API::
 
-int nfc_hci_send_cmd (struct nfc_hci_dev *hdev, u8 gate, u8 cmd,
+  int nfc_hci_send_cmd (struct nfc_hci_dev *hdev, u8 gate, u8 cmd,
 			const u8 *param, size_t param_len, struct sk_buff **skb)
 
 The API must be invoked from a context that can sleep. Most of the time, this
@@ -234,11 +254,11 @@ waiting command execution. Response processing involves invoking the completion
 callback that was provided by nfc_hci_msg_tx_work() when it sent the command.
 The completion callback will then wake the syscall context.
 
-It is also possible to execute the command asynchronously using this API:
+It is also possible to execute the command asynchronously using this API::
 
-static int nfc_hci_execute_cmd_async(struct nfc_hci_dev *hdev, u8 pipe, u8 cmd,
-			       const u8 *param, size_t param_len,
-			       data_exchange_cb_t cb, void *cb_context)
+  static int nfc_hci_execute_cmd_async(struct nfc_hci_dev *hdev, u8 pipe, u8 cmd,
+				       const u8 *param, size_t param_len,
+				       data_exchange_cb_t cb, void *cb_context)
 
 The workflow is the same, except that the API call returns immediately, and
 the callback will be called with the result from the SMW context.
@@ -268,23 +288,24 @@ went wrong below and know that expected events will probably never happen.
 Handling of these errors is done as follows:
 
 - driver (pn544) fails to deliver an incoming frame: it stores the error such
-that any subsequent call to the driver will result in this error. Then it calls
-the standard nfc_shdlc_recv_frame() with a NULL argument to report the problem
-above. shdlc stores a EREMOTEIO sticky status, which will trigger SMW to
-report above in turn.
+  that any subsequent call to the driver will result in this error. Then it
+  calls the standard nfc_shdlc_recv_frame() with a NULL argument to report the
+  problem above. shdlc stores a EREMOTEIO sticky status, which will trigger
+  SMW to report above in turn.
 
 - SMW is basically a background thread to handle incoming and outgoing shdlc
-frames. This thread will also check the shdlc sticky status and report to HCI
-when it discovers it is not able to run anymore because of an unrecoverable
-error that happened within shdlc or below. If the problem occurs during shdlc
-connection, the error is reported through the connect completion.
+  frames. This thread will also check the shdlc sticky status and report to HCI
+  when it discovers it is not able to run anymore because of an unrecoverable
+  error that happened within shdlc or below. If the problem occurs during shdlc
+  connection, the error is reported through the connect completion.
 
 - HCI: if an internal HCI error happens (frame is lost), or HCI is reported an
-error from a lower layer, HCI will either complete the currently executing
-command with that error, or notify NFC Core directly if no command is executing.
+  error from a lower layer, HCI will either complete the currently executing
+  command with that error, or notify NFC Core directly if no command is
+  executing.
 
 - NFC Core: when NFC Core is notified of an error from below and polling is
-active, it will send a tag discovered event with an empty tag list to the user
-space to let it know that the poll operation will never be able to detect a tag.
-If polling is not active and the error was sticky, lower levels will return it
-at next invocation.
+  active, it will send a tag discovered event with an empty tag list to the user
+  space to let it know that the poll operation will never be able to detect a
+  tag. If polling is not active and the error was sticky, lower levels will
+  return it at next invocation.
diff --git a/Documentation/nfc/nfc-pn544.txt b/Documentation/nfc/nfc-pn544.rst
similarity index 82%
rename from Documentation/nfc/nfc-pn544.txt
rename to Documentation/nfc/nfc-pn544.rst
index b36ca14ca2d6..6b2d8aae0c4e 100644
--- a/Documentation/nfc/nfc-pn544.txt
+++ b/Documentation/nfc/nfc-pn544.rst
@@ -1,5 +1,7 @@
-Kernel driver for the NXP Semiconductors PN544 Near Field
-Communication chip
+============================================================================
+Kernel driver for the NXP Semiconductors PN544 Near Field Communication chip
+============================================================================
+
 
 General
 -------
-- 
2.21.0

[PATCH v2 25/29] docs: md: convert to ReST

[Mauro Carvalho Chehab]

Rename the md documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

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/md/index.rst                    |  12 ++
 .../md/{md-cluster.txt => md-cluster.rst}     | 188 ++++++++++++------
 .../md/{raid5-cache.txt => raid5-cache.rst}   |  28 +--
 .../md/{raid5-ppl.txt => raid5-ppl.rst}       |   2 +
 4 files changed, 153 insertions(+), 77 deletions(-)
 create mode 100644 Documentation/md/index.rst
 rename Documentation/md/{md-cluster.txt => md-cluster.rst} (68%)
 rename Documentation/md/{raid5-cache.txt => raid5-cache.rst} (92%)
 rename Documentation/md/{raid5-ppl.txt => raid5-ppl.rst} (98%)

diff --git a/Documentation/md/index.rst b/Documentation/md/index.rst
new file mode 100644
index 000000000000..c4db34ed327d
--- /dev/null
+++ b/Documentation/md/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+====
+RAID
+====
+
+.. toctree::
+   :maxdepth: 1
+
+   md-cluster
+   raid5-cache
+   raid5-ppl
diff --git a/Documentation/md/md-cluster.txt b/Documentation/md/md-cluster.rst
similarity index 68%
rename from Documentation/md/md-cluster.txt
rename to Documentation/md/md-cluster.rst
index e1055f105cf5..96eb52cec7eb 100644
--- a/Documentation/md/md-cluster.txt
+++ b/Documentation/md/md-cluster.rst
@@ -1,19 +1,24 @@
+==========
+MD Cluster
+==========
+
 The cluster MD is a shared-device RAID for a cluster, it supports
 two levels: raid1 and raid10 (limited support).
 
 
 1. On-disk format
+=================
 
 Separate write-intent-bitmaps are used for each cluster node.
 The bitmaps record all writes that may have been started on that node,
-and may not yet have finished. The on-disk layout is:
+and may not yet have finished. The on-disk layout is::
 
-0                    4k                     8k                    12k
--------------------------------------------------------------------
-| idle                | md super            | bm super [0] + bits |
-| bm bits[0, contd]   | bm super[1] + bits  | bm bits[1, contd]   |
-| bm super[2] + bits  | bm bits [2, contd]  | bm super[3] + bits  |
-| bm bits [3, contd]  |                     |                     |
+  0                    4k                     8k                    12k
+  -------------------------------------------------------------------
+  | idle                | md super            | bm super [0] + bits |
+  | bm bits[0, contd]   | bm super[1] + bits  | bm bits[1, contd]   |
+  | bm super[2] + bits  | bm bits [2, contd]  | bm super[3] + bits  |
+  | bm bits [3, contd]  |                     |                     |
 
 During "normal" functioning we assume the filesystem ensures that only
 one node writes to any given block at a time, so a write request will
@@ -28,10 +33,12 @@ node) is writing.
 
 
 2. DLM Locks for management
+===========================
 
 There are three groups of locks for managing the device:
 
 2.1 Bitmap lock resource (bm_lockres)
+-------------------------------------
 
  The bm_lockres protects individual node bitmaps. They are named in
  the form bitmap000 for node 1, bitmap001 for node 2 and so on. When a
@@ -48,6 +55,7 @@ There are three groups of locks for managing the device:
  joins the cluster.
 
 2.2 Message passing locks
+-------------------------
 
  Each node has to communicate with other nodes when starting or ending
  resync, and for metadata superblock updates.  This communication is
@@ -55,116 +63,155 @@ There are three groups of locks for managing the device:
  with the Lock Value Block (LVB) of one of the "message" lock.
 
 2.3 new-device management
+-------------------------
 
  A single lock: "no-new-dev" is used to co-ordinate the addition of
  new devices - this must be synchronized across the array.
  Normally all nodes hold a concurrent-read lock on this device.
 
 3. Communication
+================
 
  Messages can be broadcast to all nodes, and the sender waits for all
  other nodes to acknowledge the message before proceeding.  Only one
  message can be processed at a time.
 
 3.1 Message Types
+-----------------
 
  There are six types of messages which are passed:
 
- 3.1.1 METADATA_UPDATED: informs other nodes that the metadata has
+3.1.1 METADATA_UPDATED
+^^^^^^^^^^^^^^^^^^^^^^
+
+   informs other nodes that the metadata has
    been updated, and the node must re-read the md superblock. This is
    performed synchronously. It is primarily used to signal device
    failure.
 
- 3.1.2 RESYNCING: informs other nodes that a resync is initiated or
+3.1.2 RESYNCING
+^^^^^^^^^^^^^^^
+   informs other nodes that a resync is initiated or
    ended so that each node may suspend or resume the region.  Each
    RESYNCING message identifies a range of the devices that the
    sending node is about to resync. This overrides any previous
    notification from that node: only one ranged can be resynced at a
    time per-node.
 
- 3.1.3 NEWDISK: informs other nodes that a device is being added to
+3.1.3 NEWDISK
+^^^^^^^^^^^^^
+
+   informs other nodes that a device is being added to
    the array. Message contains an identifier for that device.  See
    below for further details.
 
- 3.1.4 REMOVE: A failed or spare device is being removed from the
+3.1.4 REMOVE
+^^^^^^^^^^^^
+
+   A failed or spare device is being removed from the
    array. The slot-number of the device is included in the message.
 
- 3.1.5 RE_ADD: A failed device is being re-activated - the assumption
+ 3.1.5 RE_ADD:
+
+   A failed device is being re-activated - the assumption
    is that it has been determined to be working again.
 
- 3.1.6 BITMAP_NEEDS_SYNC: if a node is stopped locally but the bitmap
+ 3.1.6 BITMAP_NEEDS_SYNC:
+
+   If a node is stopped locally but the bitmap
    isn't clean, then another node is informed to take the ownership of
    resync.
 
 3.2 Communication mechanism
+---------------------------
 
  The DLM LVB is used to communicate within nodes of the cluster. There
  are three resources used for the purpose:
 
-  3.2.1 token: The resource which protects the entire communication
+3.2.1 token
+^^^^^^^^^^^
+   The resource which protects the entire communication
    system. The node having the token resource is allowed to
    communicate.
 
-  3.2.2 message: The lock resource which carries the data to
-   communicate.
+3.2.2 message
+^^^^^^^^^^^^^
+   The lock resource which carries the data to communicate.
 
-  3.2.3 ack: The resource, acquiring which means the message has been
+3.2.3 ack
+^^^^^^^^^
+
+   The resource, acquiring which means the message has been
    acknowledged by all nodes in the cluster. The BAST of the resource
    is used to inform the receiving node that a node wants to
    communicate.
 
 The algorithm is:
 
- 1. receive status - all nodes have concurrent-reader lock on "ack".
+ 1. receive status - all nodes have concurrent-reader lock on "ack"::
 
-   sender                         receiver                 receiver
-   "ack":CR                       "ack":CR                 "ack":CR
+	sender                         receiver                 receiver
+	"ack":CR                       "ack":CR                 "ack":CR
 
- 2. sender get EX on "token"
-    sender get EX on "message"
-    sender                        receiver                 receiver
-    "token":EX                    "ack":CR                 "ack":CR
-    "message":EX
-    "ack":CR
+ 2. sender get EX on "token",
+    sender get EX on "message"::
+
+	sender                        receiver                 receiver
+	"token":EX                    "ack":CR                 "ack":CR
+	"message":EX
+	"ack":CR
 
     Sender checks that it still needs to send a message. Messages
     received or other events that happened while waiting for the
     "token" may have made this message inappropriate or redundant.
 
- 3. sender writes LVB.
+ 3. sender writes LVB
+
     sender down-convert "message" from EX to CW
+
     sender try to get EX of "ack"
-    [ wait until all receivers have *processed* the "message" ]
-
-                                     [ triggered by bast of "ack" ]
-                                     receiver get CR on "message"
-                                     receiver read LVB
-                                     receiver processes the message
-                                     [ wait finish ]
-                                     receiver releases "ack"
-                                     receiver tries to get PR on "message"
-
-   sender                         receiver                  receiver
-   "token":EX                     "message":CR              "message":CR
-   "message":CW
-   "ack":EX
+
+    ::
+
+      [ wait until all receivers have *processed* the "message" ]
+
+                                       [ triggered by bast of "ack" ]
+                                       receiver get CR on "message"
+                                       receiver read LVB
+                                       receiver processes the message
+                                       [ wait finish ]
+                                       receiver releases "ack"
+                                       receiver tries to get PR on "message"
+
+     sender                         receiver                  receiver
+     "token":EX                     "message":CR              "message":CR
+     "message":CW
+     "ack":EX
 
  4. triggered by grant of EX on "ack" (indicating all receivers
     have processed message)
+
     sender down-converts "ack" from EX to CR
+
     sender releases "message"
+
     sender releases "token"
-                               receiver upconvert to PR on "message"
-                               receiver get CR of "ack"
-                               receiver release "message"
 
-   sender                      receiver                   receiver
-   "ack":CR                    "ack":CR                   "ack":CR
+    ::
+
+                                 receiver upconvert to PR on "message"
+                                 receiver get CR of "ack"
+                                 receiver release "message"
+
+     sender                      receiver                   receiver
+     "ack":CR                    "ack":CR                   "ack":CR
 
 
 4. Handling Failures
+====================
 
 4.1 Node Failure
+----------------
 
  When a node fails, the DLM informs the cluster with the slot
  number. The node starts a cluster recovery thread. The cluster
@@ -177,11 +224,11 @@ The algorithm is:
 	- cleans the bitmap of the failed node
 	- releases bitmap<number> lock of the failed node
 	- initiates resync of the bitmap on the current node
-		md_check_recovery is invoked within recover_bitmaps,
-		then md_check_recovery -> metadata_update_start/finish,
-		it will lock the communication by lock_comm.
-		Which means when one node is resyncing it blocks all
-		other nodes from writing anywhere on the array.
+	  md_check_recovery is invoked within recover_bitmaps,
+	  then md_check_recovery -> metadata_update_start/finish,
+	  it will lock the communication by lock_comm.
+	  Which means when one node is resyncing it blocks all
+	  other nodes from writing anywhere on the array.
 
  The resync process is the regular md resync. However, in a clustered
  environment when a resync is performed, it needs to tell other nodes
@@ -198,6 +245,7 @@ The algorithm is:
  particular I/O range should be suspended or not.
 
 4.2 Device Failure
+==================
 
  Device failures are handled and communicated with the metadata update
  routine.  When a node detects a device failure it does not allow
@@ -205,38 +253,41 @@ The algorithm is:
  acknowledged by all other nodes.
 
 5. Adding a new Device
+----------------------
 
  For adding a new device, it is necessary that all nodes "see" the new
  device to be added. For this, the following algorithm is used:
 
-    1. Node 1 issues mdadm --manage /dev/mdX --add /dev/sdYY which issues
+   1.  Node 1 issues mdadm --manage /dev/mdX --add /dev/sdYY which issues
        ioctl(ADD_NEW_DISK with disc.state set to MD_DISK_CLUSTER_ADD)
-    2. Node 1 sends a NEWDISK message with uuid and slot number
-    3. Other nodes issue kobject_uevent_env with uuid and slot number
+   2.  Node 1 sends a NEWDISK message with uuid and slot number
+   3.  Other nodes issue kobject_uevent_env with uuid and slot number
        (Steps 4,5 could be a udev rule)
-    4. In userspace, the node searches for the disk, perhaps
+   4.  In userspace, the node searches for the disk, perhaps
        using blkid -t SUB_UUID=""
-    5. Other nodes issue either of the following depending on whether
+   5.  Other nodes issue either of the following depending on whether
        the disk was found:
        ioctl(ADD_NEW_DISK with disc.state set to MD_DISK_CANDIDATE and
-             disc.number set to slot number)
+       disc.number set to slot number)
        ioctl(CLUSTERED_DISK_NACK)
-    6. Other nodes drop lock on "no-new-devs" (CR) if device is found
-    7. Node 1 attempts EX lock on "no-new-dev"
-    8. If node 1 gets the lock, it sends METADATA_UPDATED after
+   6.  Other nodes drop lock on "no-new-devs" (CR) if device is found
+   7.  Node 1 attempts EX lock on "no-new-dev"
+   8.  If node 1 gets the lock, it sends METADATA_UPDATED after
        unmarking the disk as SpareLocal
-    9. If not (get "no-new-dev" lock), it fails the operation and sends
+   9.  If not (get "no-new-dev" lock), it fails the operation and sends
        METADATA_UPDATED.
    10. Other nodes get the information whether a disk is added or not
        by the following METADATA_UPDATED.
 
-6. Module interface.
+6. Module interface
+===================
 
  There are 17 call-backs which the md core can make to the cluster
  module.  Understanding these can give a good overview of the whole
  process.
 
 6.1 join(nodes) and leave()
+---------------------------
 
  These are called when an array is started with a clustered bitmap,
  and when the array is stopped.  join() ensures the cluster is
@@ -244,11 +295,13 @@ The algorithm is:
  Only the first 'nodes' nodes in the cluster can use the array.
 
 6.2 slot_number()
+-----------------
 
  Reports the slot number advised by the cluster infrastructure.
  Range is from 0 to nodes-1.
 
 6.3 resync_info_update()
+------------------------
 
  This updates the resync range that is stored in the bitmap lock.
  The starting point is updated as the resync progresses.  The
@@ -256,6 +309,7 @@ The algorithm is:
  It does *not* send a RESYNCING message.
 
 6.4 resync_start(), resync_finish()
+-----------------------------------
 
  These are called when resync/recovery/reshape starts or stops.
  They update the resyncing range in the bitmap lock and also
@@ -265,8 +319,8 @@ The algorithm is:
  resync_finish() also sends a BITMAP_NEEDS_SYNC message which
  allows some other node to take over.
 
-6.5 metadata_update_start(), metadata_update_finish(),
-    metadata_update_cancel().
+6.5 metadata_update_start(), metadata_update_finish(), metadata_update_cancel()
+-------------------------------------------------------------------------------
 
  metadata_update_start is used to get exclusive access to
  the metadata.  If a change is still needed once that access is
@@ -275,6 +329,7 @@ The algorithm is:
  can be used to release the lock.
 
 6.6 area_resyncing()
+--------------------
 
  This combines two elements of functionality.
 
@@ -289,6 +344,7 @@ The algorithm is:
  a node failure.
 
 6.7 add_new_disk_start(), add_new_disk_finish(), new_disk_ack()
+---------------------------------------------------------------
 
  These are used to manage the new-disk protocol described above.
  When a new device is added, add_new_disk_start() is called before
@@ -300,17 +356,20 @@ The algorithm is:
  new_disk_ack() is called.
 
 6.8 remove_disk()
+-----------------
 
  This is called when a spare or failed device is removed from
  the array.  It causes a REMOVE message to be send to other nodes.
 
 6.9 gather_bitmaps()
+--------------------
 
  This sends a RE_ADD message to all other nodes and then
  gathers bitmap information from all bitmaps.  This combined
  bitmap is then used to recovery the re-added device.
 
 6.10 lock_all_bitmaps() and unlock_all_bitmaps()
+------------------------------------------------
 
  These are called when change bitmap to none. If a node plans
  to clear the cluster raid's bitmap, it need to make sure no other
@@ -319,6 +378,7 @@ The algorithm is:
  accordingly.
 
 7. Unsupported features
+=======================
 
 There are somethings which are not supported by cluster MD yet.
 
diff --git a/Documentation/md/raid5-cache.txt b/Documentation/md/raid5-cache.rst
similarity index 92%
rename from Documentation/md/raid5-cache.txt
rename to Documentation/md/raid5-cache.rst
index 2b210f295786..d7a15f44a7c3 100644
--- a/Documentation/md/raid5-cache.txt
+++ b/Documentation/md/raid5-cache.rst
@@ -1,4 +1,6 @@
-RAID5 cache
+================
+RAID 4/5/6 cache
+================
 
 Raid 4/5/6 could include an extra disk for data cache besides normal RAID
 disks. The role of RAID disks isn't changed with the cache disk. The cache disk
@@ -6,19 +8,19 @@ caches data to the RAID disks. The cache can be in write-through (supported
 since 4.4) or write-back mode (supported since 4.10). mdadm (supported since
 3.4) has a new option '--write-journal' to create array with cache. Please
 refer to mdadm manual for details. By default (RAID array starts), the cache is
-in write-through mode. A user can switch it to write-back mode by:
+in write-through mode. A user can switch it to write-back mode by::
 
-echo "write-back" > /sys/block/md0/md/journal_mode
+	echo "write-back" > /sys/block/md0/md/journal_mode
 
-And switch it back to write-through mode by:
+And switch it back to write-through mode by::
 
-echo "write-through" > /sys/block/md0/md/journal_mode
+	echo "write-through" > /sys/block/md0/md/journal_mode
 
 In both modes, all writes to the array will hit cache disk first. This means
 the cache disk must be fast and sustainable.
 
--------------------------------------
-write-through mode:
+write-through mode
+==================
 
 This mode mainly fixes the 'write hole' issue. For RAID 4/5/6 array, an unclean
 shutdown can cause data in some stripes to not be in consistent state, eg, data
@@ -42,8 +44,8 @@ exposed to 'write hole' again.
 In write-through mode, the cache disk isn't required to be big. Several
 hundreds megabytes are enough.
 
---------------------------------------
-write-back mode:
+write-back mode
+===============
 
 write-back mode fixes the 'write hole' issue too, since all write data is
 cached on cache disk. But the main goal of 'write-back' cache is to speed up
@@ -64,16 +66,16 @@ data loss.
 In write-back mode, MD also caches data in memory. The memory cache includes
 the same data stored on cache disk, so a power loss doesn't cause data loss.
 The memory cache size has performance impact for the array. It's recommended
-the size is big. A user can configure the size by:
+the size is big. A user can configure the size by::
 
-echo "2048" > /sys/block/md0/md/stripe_cache_size
+	echo "2048" > /sys/block/md0/md/stripe_cache_size
 
 Too small cache disk will make the write aggregation less efficient in this
 mode depending on the workloads. It's recommended to use a cache disk with at
 least several gigabytes size in write-back mode.
 
---------------------------------------
-The implementation:
+The implementation
+==================
 
 The write-through and write-back cache use the same disk format. The cache disk
 is organized as a simple write log. The log consists of 'meta data' and 'data'
diff --git a/Documentation/md/raid5-ppl.txt b/Documentation/md/raid5-ppl.rst
similarity index 98%
rename from Documentation/md/raid5-ppl.txt
rename to Documentation/md/raid5-ppl.rst
index bfa092589e00..357e5515bc55 100644
--- a/Documentation/md/raid5-ppl.txt
+++ b/Documentation/md/raid5-ppl.rst
@@ -1,4 +1,6 @@
+==================
 Partial Parity Log
+==================
 
 Partial Parity Log (PPL) is a feature available for RAID5 arrays. The issue
 addressed by PPL is that after a dirty shutdown, parity of a particular stripe
-- 
2.21.0

[PATCH v2 26/29] docs: mtd: convert to ReST

[Mauro Carvalho Chehab]

Rename the mtd documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

It should be noticed that Sphinx doesn't handle very well
URLs with dots in the middle. Thankfully, internally, the '.'
char is translated to %2E, so we can jus use %2E instead of
dots, and this will work fine on both text and processed files.

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/mtd/index.rst                   |  12 +
 .../mtd/{intel-spi.txt => intel-spi.rst}      |  46 +-
 .../mtd/{nand_ecc.txt => nand_ecc.rst}        | 481 ++++++++++--------
 .../mtd/{spi-nor.txt => spi-nor.rst}          |   7 +-
 drivers/mtd/nand/raw/nand_ecc.c               |   2 +-
 5 files changed, 306 insertions(+), 242 deletions(-)
 create mode 100644 Documentation/mtd/index.rst
 rename Documentation/mtd/{intel-spi.txt => intel-spi.rst} (71%)
 rename Documentation/mtd/{nand_ecc.txt => nand_ecc.rst} (67%)
 rename Documentation/mtd/{spi-nor.txt => spi-nor.rst} (94%)

diff --git a/Documentation/mtd/index.rst b/Documentation/mtd/index.rst
new file mode 100644
index 000000000000..4fdae418ac97
--- /dev/null
+++ b/Documentation/mtd/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+==============================
+Memory Technology Device (MTD)
+==============================
+
+.. toctree::
+   :maxdepth: 1
+
+   intel-spi
+   nand_ecc
+   spi-nor
diff --git a/Documentation/mtd/intel-spi.txt b/Documentation/mtd/intel-spi.rst
similarity index 71%
rename from Documentation/mtd/intel-spi.txt
rename to Documentation/mtd/intel-spi.rst
index bc357729c2cb..0e6d9cd5388d 100644
--- a/Documentation/mtd/intel-spi.txt
+++ b/Documentation/mtd/intel-spi.rst
@@ -1,5 +1,6 @@
+==============================
 Upgrading BIOS using intel-spi
-------------------------------
+==============================
 
 Many Intel CPUs like Baytrail and Braswell include SPI serial flash host
 controller which is used to hold BIOS and other platform specific data.
@@ -36,45 +37,45 @@ Linux.
     module parameter to modprobe).
 
  4) Once the board is up and running again, find the right MTD partition
-    (it is named as "BIOS"):
+    (it is named as "BIOS")::
 
-    # cat /proc/mtd
-    dev:    size   erasesize  name
-    mtd0: 00800000 00001000 "BIOS"
+	# cat /proc/mtd
+	dev:    size   erasesize  name
+	mtd0: 00800000 00001000 "BIOS"
 
     So here it will be /dev/mtd0 but it may vary.
 
- 5) Make backup of the existing image first:
+ 5) Make backup of the existing image first::
 
-    # dd if=/dev/mtd0ro of=bios.bak
-    16384+0 records in
-    16384+0 records out
-    8388608 bytes (8.4 MB) copied, 10.0269 s, 837 kB/s
+	# dd if=/dev/mtd0ro of=bios.bak
+	16384+0 records in
+	16384+0 records out
+	8388608 bytes (8.4 MB) copied, 10.0269 s, 837 kB/s
 
- 6) Verify the backup
+ 6) Verify the backup:
 
-    # sha1sum /dev/mtd0ro bios.bak
-    fdbb011920572ca6c991377c4b418a0502668b73  /dev/mtd0ro
-    fdbb011920572ca6c991377c4b418a0502668b73  bios.bak
+	# sha1sum /dev/mtd0ro bios.bak
+	fdbb011920572ca6c991377c4b418a0502668b73  /dev/mtd0ro
+	fdbb011920572ca6c991377c4b418a0502668b73  bios.bak
 
     The SHA1 sums must match. Otherwise do not continue any further!
 
  7) Erase the SPI serial flash. After this step, do not reboot the
-    board! Otherwise it will not start anymore.
+    board! Otherwise it will not start anymore::
 
-    # flash_erase /dev/mtd0 0 0
-    Erasing 4 Kibyte @ 7ff000 -- 100 % complete
+	# flash_erase /dev/mtd0 0 0
+	Erasing 4 Kibyte @ 7ff000 -- 100 % complete
 
  8) Once completed without errors you can write the new BIOS image:
 
     # dd if=MNW2MAX1.X64.0092.R01.1605221712.bin of=/dev/mtd0
 
  9) Verify that the new content of the SPI serial flash matches the new
-    BIOS image:
+    BIOS image::
 
-    # sha1sum /dev/mtd0ro MNW2MAX1.X64.0092.R01.1605221712.bin
-    9b4df9e4be2057fceec3a5529ec3d950836c87a2  /dev/mtd0ro
-    9b4df9e4be2057fceec3a5529ec3d950836c87a2 MNW2MAX1.X64.0092.R01.1605221712.bin
+	# sha1sum /dev/mtd0ro MNW2MAX1.X64.0092.R01.1605221712.bin
+	9b4df9e4be2057fceec3a5529ec3d950836c87a2  /dev/mtd0ro
+	9b4df9e4be2057fceec3a5529ec3d950836c87a2 MNW2MAX1.X64.0092.R01.1605221712.bin
 
     The SHA1 sums should match.
 
@@ -84,5 +85,6 @@ Linux.
 References
 ----------
 
-[1] https://firmware.intel.com/sites/default/files/MinnowBoard.MAX_.X64.92.R01.zip
+[1] https://firmware.intel.com/sites/default/files/MinnowBoard%2EMAX_%2EX64%2E92%2ER01%2Ezip
+
 [2] http://www.linux-mtd.infradead.org/
diff --git a/Documentation/mtd/nand_ecc.txt b/Documentation/mtd/nand_ecc.rst
similarity index 67%
rename from Documentation/mtd/nand_ecc.txt
rename to Documentation/mtd/nand_ecc.rst
index f8c3284bf6a7..e8d3c53a5056 100644
--- a/Documentation/mtd/nand_ecc.txt
+++ b/Documentation/mtd/nand_ecc.rst
@@ -1,3 +1,7 @@
+==========================
+NAND Error-correction Code
+==========================
+
 Introduction
 ============
 
@@ -37,63 +41,79 @@ sometimes also referred to as xor. In C the operator for xor is ^
 Back to ecc.
 Let's give a small figure:
 
+=========  ==== ==== ==== ==== ==== ==== ==== ====   === === === === ====
 byte   0:  bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0   rp0 rp2 rp4 ... rp14
 byte   1:  bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0   rp1 rp2 rp4 ... rp14
 byte   2:  bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0   rp0 rp3 rp4 ... rp14
 byte   3:  bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0   rp1 rp3 rp4 ... rp14
 byte   4:  bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0   rp0 rp2 rp5 ... rp14
-....
+...
 byte 254:  bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0   rp0 rp3 rp5 ... rp15
 byte 255:  bit7 bit6 bit5 bit4 bit3 bit2 bit1 bit0   rp1 rp3 rp5 ... rp15
            cp1  cp0  cp1  cp0  cp1  cp0  cp1  cp0
            cp3  cp3  cp2  cp2  cp3  cp3  cp2  cp2
            cp5  cp5  cp5  cp5  cp4  cp4  cp4  cp4
+=========  ==== ==== ==== ==== ==== ==== ==== ====   === === === === ====
 
 This figure represents a sector of 256 bytes.
 cp is my abbreviation for column parity, rp for row parity.
 
 Let's start to explain column parity.
-cp0 is the parity that belongs to all bit0, bit2, bit4, bit6.
-so the sum of all bit0, bit2, bit4 and bit6 values + cp0 itself is even.
+
+- cp0 is the parity that belongs to all bit0, bit2, bit4, bit6.
+
+  so the sum of all bit0, bit2, bit4 and bit6 values + cp0 itself is even.
+
 Similarly cp1 is the sum of all bit1, bit3, bit5 and bit7.
-cp2 is the parity over bit0, bit1, bit4 and bit5
-cp3 is the parity over bit2, bit3, bit6 and bit7.
-cp4 is the parity over bit0, bit1, bit2 and bit3.
-cp5 is the parity over bit4, bit5, bit6 and bit7.
+
+- cp2 is the parity over bit0, bit1, bit4 and bit5
+- cp3 is the parity over bit2, bit3, bit6 and bit7.
+- cp4 is the parity over bit0, bit1, bit2 and bit3.
+- cp5 is the parity over bit4, bit5, bit6 and bit7.
+
 Note that each of cp0 .. cp5 is exactly one bit.
 
 Row parity actually works almost the same.
-rp0 is the parity of all even bytes (0, 2, 4, 6, ... 252, 254)
-rp1 is the parity of all odd bytes (1, 3, 5, 7, ..., 253, 255)
-rp2 is the parity of all bytes 0, 1, 4, 5, 8, 9, ...
-(so handle two bytes, then skip 2 bytes).
-rp3 is covers the half rp2 does not cover (bytes 2, 3, 6, 7, 10, 11, ...)
-for rp4 the rule is cover 4 bytes, skip 4 bytes, cover 4 bytes, skip 4 etc.
-so rp4 calculates parity over bytes 0, 1, 2, 3, 8, 9, 10, 11, 16, ...)
-and rp5 covers the other half, so bytes 4, 5, 6, 7, 12, 13, 14, 15, 20, ..
+
+- rp0 is the parity of all even bytes (0, 2, 4, 6, ... 252, 254)
+- rp1 is the parity of all odd bytes (1, 3, 5, 7, ..., 253, 255)
+- rp2 is the parity of all bytes 0, 1, 4, 5, 8, 9, ...
+  (so handle two bytes, then skip 2 bytes).
+- rp3 is covers the half rp2 does not cover (bytes 2, 3, 6, 7, 10, 11, ...)
+- for rp4 the rule is cover 4 bytes, skip 4 bytes, cover 4 bytes, skip 4 etc.
+
+  so rp4 calculates parity over bytes 0, 1, 2, 3, 8, 9, 10, 11, 16, ...)
+- and rp5 covers the other half, so bytes 4, 5, 6, 7, 12, 13, 14, 15, 20, ..
+
 The story now becomes quite boring. I guess you get the idea.
-rp6 covers 8 bytes then skips 8 etc
-rp7 skips 8 bytes then covers 8 etc
-rp8 covers 16 bytes then skips 16 etc
-rp9 skips 16 bytes then covers 16 etc
-rp10 covers 32 bytes then skips 32 etc
-rp11 skips 32 bytes then covers 32 etc
-rp12 covers 64 bytes then skips 64 etc
-rp13 skips 64 bytes then covers 64 etc
-rp14 covers 128 bytes then skips 128
-rp15 skips 128 bytes then covers 128
+
+- rp6 covers 8 bytes then skips 8 etc
+- rp7 skips 8 bytes then covers 8 etc
+- rp8 covers 16 bytes then skips 16 etc
+- rp9 skips 16 bytes then covers 16 etc
+- rp10 covers 32 bytes then skips 32 etc
+- rp11 skips 32 bytes then covers 32 etc
+- rp12 covers 64 bytes then skips 64 etc
+- rp13 skips 64 bytes then covers 64 etc
+- rp14 covers 128 bytes then skips 128
+- rp15 skips 128 bytes then covers 128
 
 In the end the parity bits are grouped together in three bytes as
 follows:
+
+=====  ===== ===== ===== ===== ===== ===== ===== =====
 ECC    Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0
+=====  ===== ===== ===== ===== ===== ===== ===== =====
 ECC 0   rp07  rp06  rp05  rp04  rp03  rp02  rp01  rp00
 ECC 1   rp15  rp14  rp13  rp12  rp11  rp10  rp09  rp08
 ECC 2   cp5   cp4   cp3   cp2   cp1   cp0      1     1
+=====  ===== ===== ===== ===== ===== ===== ===== =====
 
 I detected after writing this that ST application note AN1823
 (http://www.st.com/stonline/) gives a much
 nicer picture.(but they use line parity as term where I use row parity)
 Oh well, I'm graphically challenged, so suffer with me for a moment :-)
+
 And I could not reuse the ST picture anyway for copyright reasons.
 
 
@@ -101,9 +121,10 @@ Attempt 0
 =========
 
 Implementing the parity calculation is pretty simple.
-In C pseudocode:
-for (i = 0; i < 256; i++)
-{
+In C pseudocode::
+
+  for (i = 0; i < 256; i++)
+  {
     if (i & 0x01)
        rp1 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ bit3 ^ bit2 ^ bit1 ^ bit0 ^ rp1;
     else
@@ -142,7 +163,7 @@ for (i = 0; i < 256; i++)
     cp3 = bit7 ^ bit6 ^ bit3 ^ bit2 ^ cp3
     cp4 = bit3 ^ bit2 ^ bit1 ^ bit0 ^ cp4
     cp5 = bit7 ^ bit6 ^ bit5 ^ bit4 ^ cp5
-}
+  }
 
 
 Analysis 0
@@ -167,82 +188,84 @@ This leads to:
 Attempt 1
 =========
 
-const char parity[256] = {
-    0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
-    1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
-    1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
-    0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
-    1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
-    0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
-    0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
-    1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
-    1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
-    0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
-    0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
-    1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
-    0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
-    1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
-    1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
-    0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0
-};
+::
 
-void ecc1(const unsigned char *buf, unsigned char *code)
-{
-    int i;
-    const unsigned char *bp = buf;
-    unsigned char cur;
-    unsigned char rp0, rp1, rp2, rp3, rp4, rp5, rp6, rp7;
-    unsigned char rp8, rp9, rp10, rp11, rp12, rp13, rp14, rp15;
-    unsigned char par;
+  const char parity[256] = {
+      0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
+      1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
+      1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
+      0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
+      1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
+      0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
+      0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
+      1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
+      1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
+      0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
+      0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
+      1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
+      0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0,
+      1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
+      1, 0, 0, 1, 0, 1, 1, 0, 0, 1, 1, 0, 1, 0, 0, 1,
+      0, 1, 1, 0, 1, 0, 0, 1, 1, 0, 0, 1, 0, 1, 1, 0
+  };
 
-    par = 0;
-    rp0 = 0; rp1 = 0; rp2 = 0; rp3 = 0;
-    rp4 = 0; rp5 = 0; rp6 = 0; rp7 = 0;
-    rp8 = 0; rp9 = 0; rp10 = 0; rp11 = 0;
-    rp12 = 0; rp13 = 0; rp14 = 0; rp15 = 0;
+  void ecc1(const unsigned char *buf, unsigned char *code)
+  {
+      int i;
+      const unsigned char *bp = buf;
+      unsigned char cur;
+      unsigned char rp0, rp1, rp2, rp3, rp4, rp5, rp6, rp7;
+      unsigned char rp8, rp9, rp10, rp11, rp12, rp13, rp14, rp15;
+      unsigned char par;
 
-    for (i = 0; i < 256; i++)
-    {
-        cur = *bp++;
-        par ^= cur;
-        if (i & 0x01) rp1 ^= cur; else rp0 ^= cur;
-        if (i & 0x02) rp3 ^= cur; else rp2 ^= cur;
-        if (i & 0x04) rp5 ^= cur; else rp4 ^= cur;
-        if (i & 0x08) rp7 ^= cur; else rp6 ^= cur;
-        if (i & 0x10) rp9 ^= cur; else rp8 ^= cur;
-        if (i & 0x20) rp11 ^= cur; else rp10 ^= cur;
-        if (i & 0x40) rp13 ^= cur; else rp12 ^= cur;
-        if (i & 0x80) rp15 ^= cur; else rp14 ^= cur;
-    }
-    code[0] =
-        (parity[rp7] << 7) |
-        (parity[rp6] << 6) |
-        (parity[rp5] << 5) |
-        (parity[rp4] << 4) |
-        (parity[rp3] << 3) |
-        (parity[rp2] << 2) |
-        (parity[rp1] << 1) |
-        (parity[rp0]);
-    code[1] =
-        (parity[rp15] << 7) |
-        (parity[rp14] << 6) |
-        (parity[rp13] << 5) |
-        (parity[rp12] << 4) |
-        (parity[rp11] << 3) |
-        (parity[rp10] << 2) |
-        (parity[rp9]  << 1) |
-        (parity[rp8]);
-    code[2] =
-        (parity[par & 0xf0] << 7) |
-        (parity[par & 0x0f] << 6) |
-        (parity[par & 0xcc] << 5) |
-        (parity[par & 0x33] << 4) |
-        (parity[par & 0xaa] << 3) |
-        (parity[par & 0x55] << 2);
-    code[0] = ~code[0];
-    code[1] = ~code[1];
-    code[2] = ~code[2];
-}
+      par = 0;
+      rp0 = 0; rp1 = 0; rp2 = 0; rp3 = 0;
+      rp4 = 0; rp5 = 0; rp6 = 0; rp7 = 0;
+      rp8 = 0; rp9 = 0; rp10 = 0; rp11 = 0;
+      rp12 = 0; rp13 = 0; rp14 = 0; rp15 = 0;
+
+      for (i = 0; i < 256; i++)
+      {
+          cur = *bp++;
+          par ^= cur;
+          if (i & 0x01) rp1 ^= cur; else rp0 ^= cur;
+          if (i & 0x02) rp3 ^= cur; else rp2 ^= cur;
+          if (i & 0x04) rp5 ^= cur; else rp4 ^= cur;
+          if (i & 0x08) rp7 ^= cur; else rp6 ^= cur;
+          if (i & 0x10) rp9 ^= cur; else rp8 ^= cur;
+          if (i & 0x20) rp11 ^= cur; else rp10 ^= cur;
+          if (i & 0x40) rp13 ^= cur; else rp12 ^= cur;
+          if (i & 0x80) rp15 ^= cur; else rp14 ^= cur;
+      }
+      code[0] =
+          (parity[rp7] << 7) |
+          (parity[rp6] << 6) |
+          (parity[rp5] << 5) |
+          (parity[rp4] << 4) |
+          (parity[rp3] << 3) |
+          (parity[rp2] << 2) |
+          (parity[rp1] << 1) |
+          (parity[rp0]);
+      code[1] =
+          (parity[rp15] << 7) |
+          (parity[rp14] << 6) |
+          (parity[rp13] << 5) |
+          (parity[rp12] << 4) |
+          (parity[rp11] << 3) |
+          (parity[rp10] << 2) |
+          (parity[rp9]  << 1) |
+          (parity[rp8]);
+      code[2] =
+          (parity[par & 0xf0] << 7) |
+          (parity[par & 0x0f] << 6) |
+          (parity[par & 0xcc] << 5) |
+          (parity[par & 0x33] << 4) |
+          (parity[par & 0xaa] << 3) |
+          (parity[par & 0x55] << 2);
+      code[0] = ~code[0];
+      code[1] = ~code[1];
+      code[2] = ~code[2];
+  }
 
 Still pretty straightforward. The last three invert statements are there to
 give a checksum of 0xff 0xff 0xff for an empty flash. In an empty flash
@@ -293,88 +316,90 @@ Let's give it a try...
 Attempt 2
 =========
 
-extern const char parity[256];
+::
 
-void ecc2(const unsigned char *buf, unsigned char *code)
-{
-    int i;
-    const unsigned long *bp = (unsigned long *)buf;
-    unsigned long cur;
-    unsigned long rp0, rp1, rp2, rp3, rp4, rp5, rp6, rp7;
-    unsigned long rp8, rp9, rp10, rp11, rp12, rp13, rp14, rp15;
-    unsigned long par;
+  extern const char parity[256];
 
-    par = 0;
-    rp0 = 0; rp1 = 0; rp2 = 0; rp3 = 0;
-    rp4 = 0; rp5 = 0; rp6 = 0; rp7 = 0;
-    rp8 = 0; rp9 = 0; rp10 = 0; rp11 = 0;
-    rp12 = 0; rp13 = 0; rp14 = 0; rp15 = 0;
+  void ecc2(const unsigned char *buf, unsigned char *code)
+  {
+      int i;
+      const unsigned long *bp = (unsigned long *)buf;
+      unsigned long cur;
+      unsigned long rp0, rp1, rp2, rp3, rp4, rp5, rp6, rp7;
+      unsigned long rp8, rp9, rp10, rp11, rp12, rp13, rp14, rp15;
+      unsigned long par;
 
-    for (i = 0; i < 64; i++)
-    {
-        cur = *bp++;
-        par ^= cur;
-        if (i & 0x01) rp5 ^= cur; else rp4 ^= cur;
-        if (i & 0x02) rp7 ^= cur; else rp6 ^= cur;
-        if (i & 0x04) rp9 ^= cur; else rp8 ^= cur;
-        if (i & 0x08) rp11 ^= cur; else rp10 ^= cur;
-        if (i & 0x10) rp13 ^= cur; else rp12 ^= cur;
-        if (i & 0x20) rp15 ^= cur; else rp14 ^= cur;
-    }
-    /*
-       we need to adapt the code generation for the fact that rp vars are now
-       long; also the column parity calculation needs to be changed.
-       we'll bring rp4 to 15 back to single byte entities by shifting and
-       xoring
-    */
-    rp4 ^= (rp4 >> 16); rp4 ^= (rp4 >> 8); rp4 &= 0xff;
-    rp5 ^= (rp5 >> 16); rp5 ^= (rp5 >> 8); rp5 &= 0xff;
-    rp6 ^= (rp6 >> 16); rp6 ^= (rp6 >> 8); rp6 &= 0xff;
-    rp7 ^= (rp7 >> 16); rp7 ^= (rp7 >> 8); rp7 &= 0xff;
-    rp8 ^= (rp8 >> 16); rp8 ^= (rp8 >> 8); rp8 &= 0xff;
-    rp9 ^= (rp9 >> 16); rp9 ^= (rp9 >> 8); rp9 &= 0xff;
-    rp10 ^= (rp10 >> 16); rp10 ^= (rp10 >> 8); rp10 &= 0xff;
-    rp11 ^= (rp11 >> 16); rp11 ^= (rp11 >> 8); rp11 &= 0xff;
-    rp12 ^= (rp12 >> 16); rp12 ^= (rp12 >> 8); rp12 &= 0xff;
-    rp13 ^= (rp13 >> 16); rp13 ^= (rp13 >> 8); rp13 &= 0xff;
-    rp14 ^= (rp14 >> 16); rp14 ^= (rp14 >> 8); rp14 &= 0xff;
-    rp15 ^= (rp15 >> 16); rp15 ^= (rp15 >> 8); rp15 &= 0xff;
-    rp3 = (par >> 16); rp3 ^= (rp3 >> 8); rp3 &= 0xff;
-    rp2 = par & 0xffff; rp2 ^= (rp2 >> 8); rp2 &= 0xff;
-    par ^= (par >> 16);
-    rp1 = (par >> 8); rp1 &= 0xff;
-    rp0 = (par & 0xff);
-    par ^= (par >> 8); par &= 0xff;
+      par = 0;
+      rp0 = 0; rp1 = 0; rp2 = 0; rp3 = 0;
+      rp4 = 0; rp5 = 0; rp6 = 0; rp7 = 0;
+      rp8 = 0; rp9 = 0; rp10 = 0; rp11 = 0;
+      rp12 = 0; rp13 = 0; rp14 = 0; rp15 = 0;
 
-    code[0] =
-        (parity[rp7] << 7) |
-        (parity[rp6] << 6) |
-        (parity[rp5] << 5) |
-        (parity[rp4] << 4) |
-        (parity[rp3] << 3) |
-        (parity[rp2] << 2) |
-        (parity[rp1] << 1) |
-        (parity[rp0]);
-    code[1] =
-        (parity[rp15] << 7) |
-        (parity[rp14] << 6) |
-        (parity[rp13] << 5) |
-        (parity[rp12] << 4) |
-        (parity[rp11] << 3) |
-        (parity[rp10] << 2) |
-        (parity[rp9]  << 1) |
-        (parity[rp8]);
-    code[2] =
-        (parity[par & 0xf0] << 7) |
-        (parity[par & 0x0f] << 6) |
-        (parity[par & 0xcc] << 5) |
-        (parity[par & 0x33] << 4) |
-        (parity[par & 0xaa] << 3) |
-        (parity[par & 0x55] << 2);
-    code[0] = ~code[0];
-    code[1] = ~code[1];
-    code[2] = ~code[2];
-}
+      for (i = 0; i < 64; i++)
+      {
+          cur = *bp++;
+          par ^= cur;
+          if (i & 0x01) rp5 ^= cur; else rp4 ^= cur;
+          if (i & 0x02) rp7 ^= cur; else rp6 ^= cur;
+          if (i & 0x04) rp9 ^= cur; else rp8 ^= cur;
+          if (i & 0x08) rp11 ^= cur; else rp10 ^= cur;
+          if (i & 0x10) rp13 ^= cur; else rp12 ^= cur;
+          if (i & 0x20) rp15 ^= cur; else rp14 ^= cur;
+      }
+      /*
+         we need to adapt the code generation for the fact that rp vars are now
+         long; also the column parity calculation needs to be changed.
+         we'll bring rp4 to 15 back to single byte entities by shifting and
+         xoring
+      */
+      rp4 ^= (rp4 >> 16); rp4 ^= (rp4 >> 8); rp4 &= 0xff;
+      rp5 ^= (rp5 >> 16); rp5 ^= (rp5 >> 8); rp5 &= 0xff;
+      rp6 ^= (rp6 >> 16); rp6 ^= (rp6 >> 8); rp6 &= 0xff;
+      rp7 ^= (rp7 >> 16); rp7 ^= (rp7 >> 8); rp7 &= 0xff;
+      rp8 ^= (rp8 >> 16); rp8 ^= (rp8 >> 8); rp8 &= 0xff;
+      rp9 ^= (rp9 >> 16); rp9 ^= (rp9 >> 8); rp9 &= 0xff;
+      rp10 ^= (rp10 >> 16); rp10 ^= (rp10 >> 8); rp10 &= 0xff;
+      rp11 ^= (rp11 >> 16); rp11 ^= (rp11 >> 8); rp11 &= 0xff;
+      rp12 ^= (rp12 >> 16); rp12 ^= (rp12 >> 8); rp12 &= 0xff;
+      rp13 ^= (rp13 >> 16); rp13 ^= (rp13 >> 8); rp13 &= 0xff;
+      rp14 ^= (rp14 >> 16); rp14 ^= (rp14 >> 8); rp14 &= 0xff;
+      rp15 ^= (rp15 >> 16); rp15 ^= (rp15 >> 8); rp15 &= 0xff;
+      rp3 = (par >> 16); rp3 ^= (rp3 >> 8); rp3 &= 0xff;
+      rp2 = par & 0xffff; rp2 ^= (rp2 >> 8); rp2 &= 0xff;
+      par ^= (par >> 16);
+      rp1 = (par >> 8); rp1 &= 0xff;
+      rp0 = (par & 0xff);
+      par ^= (par >> 8); par &= 0xff;
+
+      code[0] =
+          (parity[rp7] << 7) |
+          (parity[rp6] << 6) |
+          (parity[rp5] << 5) |
+          (parity[rp4] << 4) |
+          (parity[rp3] << 3) |
+          (parity[rp2] << 2) |
+          (parity[rp1] << 1) |
+          (parity[rp0]);
+      code[1] =
+          (parity[rp15] << 7) |
+          (parity[rp14] << 6) |
+          (parity[rp13] << 5) |
+          (parity[rp12] << 4) |
+          (parity[rp11] << 3) |
+          (parity[rp10] << 2) |
+          (parity[rp9]  << 1) |
+          (parity[rp8]);
+      code[2] =
+          (parity[par & 0xf0] << 7) |
+          (parity[par & 0x0f] << 6) |
+          (parity[par & 0xcc] << 5) |
+          (parity[par & 0x33] << 4) |
+          (parity[par & 0xaa] << 3) |
+          (parity[par & 0x55] << 2);
+      code[0] = ~code[0];
+      code[1] = ~code[1];
+      code[2] = ~code[2];
+  }
 
 The parity array is not shown any more. Note also that for these
 examples I kinda deviated from my regular programming style by allowing
@@ -403,28 +428,32 @@ lookups
 Attempt 3
 =========
 
-Odd replaced:
-        if (i & 0x01) rp5 ^= cur; else rp4 ^= cur;
-        if (i & 0x02) rp7 ^= cur; else rp6 ^= cur;
-        if (i & 0x04) rp9 ^= cur; else rp8 ^= cur;
-        if (i & 0x08) rp11 ^= cur; else rp10 ^= cur;
-        if (i & 0x10) rp13 ^= cur; else rp12 ^= cur;
-        if (i & 0x20) rp15 ^= cur; else rp14 ^= cur;
-with
-        if (i & 0x01) rp5 ^= cur;
-        if (i & 0x02) rp7 ^= cur;
-        if (i & 0x04) rp9 ^= cur;
-        if (i & 0x08) rp11 ^= cur;
-        if (i & 0x10) rp13 ^= cur;
-        if (i & 0x20) rp15 ^= cur;
+Odd replaced::
 
-        and outside the loop added:
-        rp4  = par ^ rp5;
-        rp6  = par ^ rp7;
-        rp8  = par ^ rp9;
-        rp10  = par ^ rp11;
-        rp12  = par ^ rp13;
-        rp14  = par ^ rp15;
+          if (i & 0x01) rp5 ^= cur; else rp4 ^= cur;
+          if (i & 0x02) rp7 ^= cur; else rp6 ^= cur;
+          if (i & 0x04) rp9 ^= cur; else rp8 ^= cur;
+          if (i & 0x08) rp11 ^= cur; else rp10 ^= cur;
+          if (i & 0x10) rp13 ^= cur; else rp12 ^= cur;
+          if (i & 0x20) rp15 ^= cur; else rp14 ^= cur;
+
+with::
+
+          if (i & 0x01) rp5 ^= cur;
+          if (i & 0x02) rp7 ^= cur;
+          if (i & 0x04) rp9 ^= cur;
+          if (i & 0x08) rp11 ^= cur;
+          if (i & 0x10) rp13 ^= cur;
+          if (i & 0x20) rp15 ^= cur;
+
+and outside the loop added::
+
+          rp4  = par ^ rp5;
+          rp6  = par ^ rp7;
+          rp8  = par ^ rp9;
+          rp10  = par ^ rp11;
+          rp12  = par ^ rp13;
+          rp14  = par ^ rp15;
 
 And after that the code takes about 30% more time, although the number of
 statements is reduced. This is also reflected in the assembly code.
@@ -448,7 +477,7 @@ Attempt 4
 =========
 
 Unrolled the loop 1, 2, 3 and 4 times.
-For 4 the code starts with:
+For 4 the code starts with::
 
     for (i = 0; i < 4; i++)
     {
@@ -471,8 +500,11 @@ Analysis 4
 ==========
 
 Unrolling once gains about 15%
+
 Unrolling twice keeps the gain at about 15%
+
 Unrolling three times gives a gain of 30% compared to attempt 2.
+
 Unrolling four times gives a marginal improvement compared to unrolling
 three times.
 
@@ -492,8 +524,10 @@ Attempt 5
 
 Effectively so all odd digit rp assignments in the loop were removed.
 This included the else clause of the if statements.
-Of course after the loop we need to correct things by adding code like:
+Of course after the loop we need to correct things by adding code like::
+
     rp5 = par ^ rp4;
+
 Also the initial assignments (rp5 = 0; etc) could be removed.
 Along the line I also removed the initialisation of rp0/1/2/3.
 
@@ -513,7 +547,7 @@ statement. Time for yet another version!
 Attempt 6
 =========
 
-THe code within the for loop was changed to:
+THe code within the for loop was changed to::
 
     for (i = 0; i < 4; i++)
     {
@@ -564,13 +598,17 @@ million iterations in order not to lose too much accuracy. This one
 definitely seemed to be the jackpot!
 
 There is a little bit more room for improvement though. There are three
-places with statements:
-rp4 ^= cur; rp6 ^= cur;
+places with statements::
+
+	rp4 ^= cur; rp6 ^= cur;
+
 It seems more efficient to also maintain a variable rp4_6 in the while
 loop; This eliminates 3 statements per loop. Of course after the loop we
-need to correct by adding:
-    rp4 ^= rp4_6;
-    rp6 ^= rp4_6
+need to correct by adding::
+
+	rp4 ^= rp4_6;
+	rp6 ^= rp4_6
+
 Furthermore there are 4 sequential assignments to rp8. This can be
 encoded slightly more efficiently by saving tmppar before those 4 lines
 and later do rp8 = rp8 ^ tmppar ^ notrp8;
@@ -582,7 +620,7 @@ Time for a new test!
 Attempt 7
 =========
 
-The new code now looks like:
+The new code now looks like::
 
     for (i = 0; i < 4; i++)
     {
@@ -644,9 +682,12 @@ Although it seems that the code within the loop cannot be optimised
 further there is still room to optimize the generation of the ecc codes.
 We can simply calculate the total parity. If this is 0 then rp4 = rp5
 etc. If the parity is 1, then rp4 = !rp5;
+
 But if rp4 = rp5 we do not need rp5 etc. We can just write the even bits
-in the result byte and then do something like
+in the result byte and then do something like::
+
     code[0] |= (code[0] << 1);
+
 Lets test this.
 
 
@@ -657,11 +698,13 @@ Changed the code but again this slightly degrades performance. Tried all
 kind of other things, like having dedicated parity arrays to avoid the
 shift after parity[rp7] << 7; No gain.
 Change the lookup using the parity array by using shift operators (e.g.
-replace parity[rp7] << 7 with:
-rp7 ^= (rp7 << 4);
-rp7 ^= (rp7 << 2);
-rp7 ^= (rp7 << 1);
-rp7 &= 0x80;
+replace parity[rp7] << 7 with::
+
+	rp7 ^= (rp7 << 4);
+	rp7 ^= (rp7 << 2);
+	rp7 ^= (rp7 << 1);
+	rp7 &= 0x80;
+
 No gain.
 
 The only marginal change was inverting the parity bits, so we can remove
@@ -683,13 +726,16 @@ Correcting errors
 
 For correcting errors I again used the ST application note as a starter,
 but I also peeked at the existing code.
+
 The algorithm itself is pretty straightforward. Just xor the given and
 the calculated ecc. If all bytes are 0 there is no problem. If 11 bits
 are 1 we have one correctable bit error. If there is 1 bit 1, we have an
 error in the given ecc code.
+
 It proved to be fastest to do some table lookups. Performance gain
 introduced by this is about a factor 2 on my system when a repair had to
 be done, and 1% or so if no repair had to be done.
+
 Code size increased from 330 bytes to 686 bytes for this function.
 (gcc 4.2, -O3)
 
@@ -700,8 +746,10 @@ Conclusion
 The gain when calculating the ecc is tremendous. Om my development hardware
 a speedup of a factor of 18 for ecc calculation was achieved. On a test on an
 embedded system with a MIPS core a factor 7 was obtained.
+
 On a test with a Linksys NSLU2 (ARMv5TE processor) the speedup was a factor
 5 (big endian mode, gcc 4.1.2, -O3)
+
 For correction not much gain could be obtained (as bitflips are rare). Then
 again there are also much less cycles spent there.
 
@@ -711,4 +759,5 @@ out of it with an assembler program, but due to pipeline behaviour etc
 this is very tricky (at least for intel hw).
 
 Author: Frans Meulenbroeks
+
 Copyright (C) 2008 Koninklijke Philips Electronics NV.
diff --git a/Documentation/mtd/spi-nor.txt b/Documentation/mtd/spi-nor.rst
similarity index 94%
rename from Documentation/mtd/spi-nor.txt
rename to Documentation/mtd/spi-nor.rst
index da1fbff5a24c..f5333e3bf486 100644
--- a/Documentation/mtd/spi-nor.txt
+++ b/Documentation/mtd/spi-nor.rst
@@ -1,5 +1,6 @@
-                          SPI NOR framework
-               ============================================
+=================
+SPI NOR framework
+=================
 
 Part I - Why do we need this framework?
 ---------------------------------------
@@ -23,7 +24,7 @@ This framework just adds a new layer between the MTD and the SPI bus driver.
 With this new layer, the SPI NOR controller driver does not depend on the
 m25p80 code anymore.
 
-   Before this framework, the layer is like:
+Before this framework, the layer is like::
 
                    MTD
          ------------------------
diff --git a/drivers/mtd/nand/raw/nand_ecc.c b/drivers/mtd/nand/raw/nand_ecc.c
index 223fbd8052b3..f6a7808db818 100644
--- a/drivers/mtd/nand/raw/nand_ecc.c
+++ b/drivers/mtd/nand/raw/nand_ecc.c
@@ -11,7 +11,7 @@
  *   Thomas Gleixner (tglx@linutronix.de)
  *
  * Information on how this algorithm works and how it was developed
- * can be found in Documentation/mtd/nand_ecc.txt
+ * can be found in Documentation/mtd/nand_ecc.rst
  */
 
 #include <linux/types.h>
-- 
2.21.0

[PATCH v2 27/29] docs: nvdimm: convert to ReST

[Mauro Carvalho Chehab]

Rename the nvdimm documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

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/nvdimm/{btt.txt => btt.rst}     | 140 ++---
 Documentation/nvdimm/index.rst                |  12 +
 .../nvdimm/{nvdimm.txt => nvdimm.rst}         | 518 ++++++++++--------
 .../nvdimm/{security.txt => security.rst}     |   4 +-
 drivers/nvdimm/Kconfig                        |   2 +-
 5 files changed, 387 insertions(+), 289 deletions(-)
 rename Documentation/nvdimm/{btt.txt => btt.rst} (71%)
 create mode 100644 Documentation/nvdimm/index.rst
 rename Documentation/nvdimm/{nvdimm.txt => nvdimm.rst} (60%)
 rename Documentation/nvdimm/{security.txt => security.rst} (99%)

diff --git a/Documentation/nvdimm/btt.txt b/Documentation/nvdimm/btt.rst
similarity index 71%
rename from Documentation/nvdimm/btt.txt
rename to Documentation/nvdimm/btt.rst
index e293fb664924..2d8269f834bd 100644
--- a/Documentation/nvdimm/btt.txt
+++ b/Documentation/nvdimm/btt.rst
@@ -1,9 +1,10 @@
+=============================
 BTT - Block Translation Table
 =============================
 
 
 1. Introduction
----------------
+===============
 
 Persistent memory based storage is able to perform IO at byte (or more
 accurately, cache line) granularity. However, we often want to expose such
@@ -25,7 +26,7 @@ provides atomic sector updates.
 
 
 2. Static Layout
-----------------
+================
 
 The underlying storage on which a BTT can be laid out is not limited in any way.
 The BTT, however, splits the available space into chunks of up to 512 GiB,
@@ -33,43 +34,43 @@ called "Arenas".
 
 Each arena follows the same layout for its metadata, and all references in an
 arena are internal to it (with the exception of one field that points to the
-next arena). The following depicts the "On-disk" metadata layout:
+next arena). The following depicts the "On-disk" metadata layout::
 
 
-  Backing Store     +------->  Arena
-+---------------+   |   +------------------+
-|               |   |   | Arena info block |
-|    Arena 0    +---+   |       4K         |
-|     512G      |       +------------------+
-|               |       |                  |
-+---------------+       |                  |
-|               |       |                  |
-|    Arena 1    |       |   Data Blocks    |
-|     512G      |       |                  |
-|               |       |                  |
-+---------------+       |                  |
-|       .       |       |                  |
-|       .       |       |                  |
-|       .       |       |                  |
-|               |       |                  |
-|               |       |                  |
-+---------------+       +------------------+
-                        |                  |
-                        |     BTT Map      |
-                        |                  |
-                        |                  |
-                        +------------------+
-                        |                  |
-                        |     BTT Flog     |
-                        |                  |
-                        +------------------+
-                        | Info block copy  |
-                        |       4K         |
-                        +------------------+
+    Backing Store     +------->  Arena
+  +---------------+   |   +------------------+
+  |               |   |   | Arena info block |
+  |    Arena 0    +---+   |       4K         |
+  |     512G      |       +------------------+
+  |               |       |                  |
+  +---------------+       |                  |
+  |               |       |                  |
+  |    Arena 1    |       |   Data Blocks    |
+  |     512G      |       |                  |
+  |               |       |                  |
+  +---------------+       |                  |
+  |       .       |       |                  |
+  |       .       |       |                  |
+  |       .       |       |                  |
+  |               |       |                  |
+  |               |       |                  |
+  +---------------+       +------------------+
+                          |                  |
+                          |     BTT Map      |
+                          |                  |
+                          |                  |
+                          +------------------+
+                          |                  |
+                          |     BTT Flog     |
+                          |                  |
+                          +------------------+
+                          | Info block copy  |
+                          |       4K         |
+                          +------------------+
 
 
 3. Theory of Operation
-----------------------
+======================
 
 
 a. The BTT Map
@@ -79,31 +80,37 @@ The map is a simple lookup/indirection table that maps an LBA to an internal
 block. Each map entry is 32 bits. The two most significant bits are special
 flags, and the remaining form the internal block number.
 
+======== =============================================================
 Bit      Description
-31 - 30	: Error and Zero flags - Used in the following way:
-	 Bit		      Description
-	31 30
-	-----------------------------------------------------------------------
-	 00	Initial state. Reads return zeroes; Premap = Postmap
-	 01	Zero state: Reads return zeroes
-	 10	Error state: Reads fail; Writes clear 'E' bit
-	 11	Normal Block – has valid postmap
+======== =============================================================
+31 - 30	 Error and Zero flags - Used in the following way:
 
+	   == ==  ====================================================
+	   31 30  Description
+	   == ==  ====================================================
+	   0  0	  Initial state. Reads return zeroes; Premap = Postmap
+	   0  1	  Zero state: Reads return zeroes
+	   1  0	  Error state: Reads fail; Writes clear 'E' bit
+	   1  1	  Normal Block – has valid postmap
+	   == ==  ====================================================
 
-29 - 0	: Mappings to internal 'postmap' blocks
+29 - 0	 Mappings to internal 'postmap' blocks
+======== =============================================================
 
 
 Some of the terminology that will be subsequently used:
 
-External LBA  : LBA as made visible to upper layers.
-ABA           : Arena Block Address - Block offset/number within an arena
-Premap ABA    : The block offset into an arena, which was decided upon by range
+============	================================================================
+External LBA	LBA as made visible to upper layers.
+ABA		Arena Block Address - Block offset/number within an arena
+Premap ABA	The block offset into an arena, which was decided upon by range
 		checking the External LBA
-Postmap ABA   : The block number in the "Data Blocks" area obtained after
+Postmap ABA	The block number in the "Data Blocks" area obtained after
 		indirection from the map
-nfree	      : The number of free blocks that are maintained at any given time.
+nfree		The number of free blocks that are maintained at any given time.
 		This is the number of concurrent writes that can happen to the
 		arena.
+============	================================================================
 
 
 For example, after adding a BTT, we surface a disk of 1024G. We get a read for
@@ -121,19 +128,21 @@ i.e. Every write goes to a "free" block. A running list of free blocks is
 maintained in the form of the BTT flog. 'Flog' is a combination of the words
 "free list" and "log". The flog contains 'nfree' entries, and an entry contains:
 
-lba     : The premap ABA that is being written to
-old_map : The old postmap ABA - after 'this' write completes, this will be a
+========  =====================================================================
+lba       The premap ABA that is being written to
+old_map   The old postmap ABA - after 'this' write completes, this will be a
 	  free block.
-new_map : The new postmap ABA. The map will up updated to reflect this
+new_map   The new postmap ABA. The map will up updated to reflect this
 	  lba->postmap_aba mapping, but we log it here in case we have to
 	  recover.
-seq	: Sequence number to mark which of the 2 sections of this flog entry is
+seq	  Sequence number to mark which of the 2 sections of this flog entry is
 	  valid/newest. It cycles between 01->10->11->01 (binary) under normal
 	  operation, with 00 indicating an uninitialized state.
-lba'	: alternate lba entry
-old_map': alternate old postmap entry
-new_map': alternate new postmap entry
-seq'	: alternate sequence number.
+lba'	  alternate lba entry
+old_map'  alternate old postmap entry
+new_map'  alternate new postmap entry
+seq'	  alternate sequence number.
+========  =====================================================================
 
 Each of the above fields is 32-bit, making one entry 32 bytes. Entries are also
 padded to 64 bytes to avoid cache line sharing or aliasing. Flog updates are
@@ -147,8 +156,10 @@ c. The concept of lanes
 
 While 'nfree' describes the number of concurrent IOs an arena can process
 concurrently, 'nlanes' is the number of IOs the BTT device as a whole can
-process.
- nlanes = min(nfree, num_cpus)
+process::
+
+	nlanes = min(nfree, num_cpus)
+
 A lane number is obtained at the start of any IO, and is used for indexing into
 all the on-disk and in-memory data structures for the duration of the IO. If
 there are more CPUs than the max number of available lanes, than lanes are
@@ -180,10 +191,10 @@ e. In-memory data structure: map locks
 --------------------------------------
 
 Consider a case where two writer threads are writing to the same LBA. There can
-be a race in the following sequence of steps:
+be a race in the following sequence of steps::
 
-free[lane] = map[premap_aba]
-map[premap_aba] = postmap_aba
+	free[lane] = map[premap_aba]
+	map[premap_aba] = postmap_aba
 
 Both threads can update their respective free[lane] with the same old, freed
 postmap_aba. This has made the layout inconsistent by losing a free entry, and
@@ -202,6 +213,7 @@ On startup, we analyze the BTT flog to create our list of free blocks. We walk
 through all the entries, and for each lane, of the set of two possible
 'sections', we always look at the most recent one only (based on the sequence
 number). The reconstruction rules/steps are simple:
+
 - Read map[log_entry.lba].
 - If log_entry.new matches the map entry, then log_entry.old is free.
 - If log_entry.new does not match the map entry, then log_entry.new is free.
@@ -228,7 +240,7 @@ Write:
 1.  Convert external LBA to Arena number + pre-map ABA
 2.  Get a lane (and take lane_lock)
 3.  Use lane to index into in-memory free list and obtain a new block, next flog
-        index, next sequence number
+    index, next sequence number
 4.  Scan the RTT to check if free block is present, and spin/wait if it is.
 5.  Write data to this free block
 6.  Read map to get the existing post-map ABA entry for this pre-map ABA
@@ -245,6 +257,7 @@ Write:
 An arena would be in an error state if any of the metadata is corrupted
 irrecoverably, either due to a bug or a media error. The following conditions
 indicate an error:
+
 - Info block checksum does not match (and recovering from the copy also fails)
 - All internal available blocks are not uniquely and entirely addressed by the
   sum of mapped blocks and free blocks (from the BTT flog).
@@ -263,11 +276,10 @@ The BTT can be set up on any disk (namespace) exposed by the libnvdimm subsystem
 (pmem, or blk mode). The easiest way to set up such a namespace is using the
 'ndctl' utility [1]:
 
-For example, the ndctl command line to setup a btt with a 4k sector size is:
+For example, the ndctl command line to setup a btt with a 4k sector size is::
 
     ndctl create-namespace -f -e namespace0.0 -m sector -l 4k
 
 See ndctl create-namespace --help for more options.
 
 [1]: https://github.com/pmem/ndctl
-
diff --git a/Documentation/nvdimm/index.rst b/Documentation/nvdimm/index.rst
new file mode 100644
index 000000000000..1a3402d3775e
--- /dev/null
+++ b/Documentation/nvdimm/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+===================================
+Non-Volatile Memory Device (NVDIMM)
+===================================
+
+.. toctree::
+   :maxdepth: 1
+
+   nvdimm
+   btt
+   security
diff --git a/Documentation/nvdimm/nvdimm.txt b/Documentation/nvdimm/nvdimm.rst
similarity index 60%
rename from Documentation/nvdimm/nvdimm.txt
rename to Documentation/nvdimm/nvdimm.rst
index 1669f626b037..08f855cbb4e6 100644
--- a/Documentation/nvdimm/nvdimm.txt
+++ b/Documentation/nvdimm/nvdimm.rst
@@ -1,8 +1,14 @@
-			  LIBNVDIMM: Non-Volatile Devices
-	      libnvdimm - kernel / libndctl - userspace helper library
-			   linux-nvdimm@lists.01.org
-				      v13
+===============================
+LIBNVDIMM: Non-Volatile Devices
+===============================
 
+libnvdimm - kernel / libndctl - userspace helper library
+
+linux-nvdimm@lists.01.org
+
+Version 13
+
+.. contents:
 
 	Glossary
 	Overview
@@ -40,49 +46,57 @@
 
 
 Glossary
---------
-
-PMEM: A system-physical-address range where writes are persistent.  A
-block device composed of PMEM is capable of DAX.  A PMEM address range
-may span an interleave of several DIMMs.
-
-BLK: A set of one or more programmable memory mapped apertures provided
-by a DIMM to access its media.  This indirection precludes the
-performance benefit of interleaving, but enables DIMM-bounded failure
-modes.
-
-DPA: DIMM Physical Address, is a DIMM-relative offset.  With one DIMM in
-the system there would be a 1:1 system-physical-address:DPA association.
-Once more DIMMs are added a memory controller interleave must be
-decoded to determine the DPA associated with a given
-system-physical-address.  BLK capacity always has a 1:1 relationship
-with a single-DIMM's DPA range.
-
-DAX: File system extensions to bypass the page cache and block layer to
-mmap persistent memory, from a PMEM block device, directly into a
-process address space.
-
-DSM: Device Specific Method: ACPI method to to control specific
-device - in this case the firmware.
-
-DCR: NVDIMM Control Region Structure defined in ACPI 6 Section 5.2.25.5.
-It defines a vendor-id, device-id, and interface format for a given DIMM.
-
-BTT: Block Translation Table: Persistent memory is byte addressable.
-Existing software may have an expectation that the power-fail-atomicity
-of writes is at least one sector, 512 bytes.  The BTT is an indirection
-table with atomic update semantics to front a PMEM/BLK block device
-driver and present arbitrary atomic sector sizes.
-
-LABEL: Metadata stored on a DIMM device that partitions and identifies
-(persistently names) storage between PMEM and BLK.  It also partitions
-BLK storage to host BTTs with different parameters per BLK-partition.
-Note that traditional partition tables, GPT/MBR, are layered on top of a
-BLK or PMEM device.
+========
+
+PMEM:
+  A system-physical-address range where writes are persistent.  A
+  block device composed of PMEM is capable of DAX.  A PMEM address range
+  may span an interleave of several DIMMs.
+
+BLK:
+  A set of one or more programmable memory mapped apertures provided
+  by a DIMM to access its media.  This indirection precludes the
+  performance benefit of interleaving, but enables DIMM-bounded failure
+  modes.
+
+DPA:
+  DIMM Physical Address, is a DIMM-relative offset.  With one DIMM in
+  the system there would be a 1:1 system-physical-address:DPA association.
+  Once more DIMMs are added a memory controller interleave must be
+  decoded to determine the DPA associated with a given
+  system-physical-address.  BLK capacity always has a 1:1 relationship
+  with a single-DIMM's DPA range.
+
+DAX:
+  File system extensions to bypass the page cache and block layer to
+  mmap persistent memory, from a PMEM block device, directly into a
+  process address space.
+
+DSM:
+  Device Specific Method: ACPI method to to control specific
+  device - in this case the firmware.
+
+DCR:
+  NVDIMM Control Region Structure defined in ACPI 6 Section 5.2.25.5.
+  It defines a vendor-id, device-id, and interface format for a given DIMM.
+
+BTT:
+  Block Translation Table: Persistent memory is byte addressable.
+  Existing software may have an expectation that the power-fail-atomicity
+  of writes is at least one sector, 512 bytes.  The BTT is an indirection
+  table with atomic update semantics to front a PMEM/BLK block device
+  driver and present arbitrary atomic sector sizes.
+
+LABEL:
+  Metadata stored on a DIMM device that partitions and identifies
+  (persistently names) storage between PMEM and BLK.  It also partitions
+  BLK storage to host BTTs with different parameters per BLK-partition.
+  Note that traditional partition tables, GPT/MBR, are layered on top of a
+  BLK or PMEM device.
 
 
 Overview
---------
+========
 
 The LIBNVDIMM subsystem provides support for three types of NVDIMMs, namely,
 PMEM, BLK, and NVDIMM devices that can simultaneously support both PMEM
@@ -96,19 +110,30 @@ accessible via BLK.  When that occurs a LABEL is needed to reserve DPA
 for exclusive access via one mode a time.
 
 Supporting Documents
-ACPI 6: http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf
-NVDIMM Namespace: http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf
-DSM Interface Example: http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf
-Driver Writer's Guide: http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf
+--------------------
+
+ACPI 6:
+	http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf
+NVDIMM Namespace:
+	http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf
+DSM Interface Example:
+	http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf
+Driver Writer's Guide:
+	http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf
 
 Git Trees
-LIBNVDIMM: https://git.kernel.org/cgit/linux/kernel/git/djbw/nvdimm.git
-LIBNDCTL: https://github.com/pmem/ndctl.git
-PMEM: https://github.com/01org/prd
+---------
+
+LIBNVDIMM:
+	https://git.kernel.org/cgit/linux/kernel/git/djbw/nvdimm.git
+LIBNDCTL:
+	https://github.com/pmem/ndctl.git
+PMEM:
+	https://github.com/01org/prd
 
 
 LIBNVDIMM PMEM and BLK
-------------------
+======================
 
 Prior to the arrival of the NFIT, non-volatile memory was described to a
 system in various ad-hoc ways.  Usually only the bare minimum was
@@ -122,38 +147,39 @@ For each NVDIMM access method (PMEM, BLK), LIBNVDIMM provides a block
 device driver:
 
     1. PMEM (nd_pmem.ko): Drives a system-physical-address range.  This
-    range is contiguous in system memory and may be interleaved (hardware
-    memory controller striped) across multiple DIMMs.  When interleaved the
-    platform may optionally provide details of which DIMMs are participating
-    in the interleave.
+       range is contiguous in system memory and may be interleaved (hardware
+       memory controller striped) across multiple DIMMs.  When interleaved the
+       platform may optionally provide details of which DIMMs are participating
+       in the interleave.
 
-    Note that while LIBNVDIMM describes system-physical-address ranges that may
-    alias with BLK access as ND_NAMESPACE_PMEM ranges and those without
-    alias as ND_NAMESPACE_IO ranges, to the nd_pmem driver there is no
-    distinction.  The different device-types are an implementation detail
-    that userspace can exploit to implement policies like "only interface
-    with address ranges from certain DIMMs".  It is worth noting that when
-    aliasing is present and a DIMM lacks a label, then no block device can
-    be created by default as userspace needs to do at least one allocation
-    of DPA to the PMEM range.  In contrast ND_NAMESPACE_IO ranges, once
-    registered, can be immediately attached to nd_pmem.
+       Note that while LIBNVDIMM describes system-physical-address ranges that may
+       alias with BLK access as ND_NAMESPACE_PMEM ranges and those without
+       alias as ND_NAMESPACE_IO ranges, to the nd_pmem driver there is no
+       distinction.  The different device-types are an implementation detail
+       that userspace can exploit to implement policies like "only interface
+       with address ranges from certain DIMMs".  It is worth noting that when
+       aliasing is present and a DIMM lacks a label, then no block device can
+       be created by default as userspace needs to do at least one allocation
+       of DPA to the PMEM range.  In contrast ND_NAMESPACE_IO ranges, once
+       registered, can be immediately attached to nd_pmem.
 
     2. BLK (nd_blk.ko): This driver performs I/O using a set of platform
-    defined apertures.  A set of apertures will access just one DIMM.
-    Multiple windows (apertures) allow multiple concurrent accesses, much like
-    tagged-command-queuing, and would likely be used by different threads or
-    different CPUs.
+       defined apertures.  A set of apertures will access just one DIMM.
+       Multiple windows (apertures) allow multiple concurrent accesses, much like
+       tagged-command-queuing, and would likely be used by different threads or
+       different CPUs.
 
-    The NFIT specification defines a standard format for a BLK-aperture, but
-    the spec also allows for vendor specific layouts, and non-NFIT BLK
-    implementations may have other designs for BLK I/O.  For this reason
-    "nd_blk" calls back into platform-specific code to perform the I/O.
-    One such implementation is defined in the "Driver Writer's Guide" and "DSM
-    Interface Example".
+       The NFIT specification defines a standard format for a BLK-aperture, but
+       the spec also allows for vendor specific layouts, and non-NFIT BLK
+       implementations may have other designs for BLK I/O.  For this reason
+       "nd_blk" calls back into platform-specific code to perform the I/O.
+
+       One such implementation is defined in the "Driver Writer's Guide" and "DSM
+       Interface Example".
 
 
 Why BLK?
---------
+========
 
 While PMEM provides direct byte-addressable CPU-load/store access to
 NVDIMM storage, it does not provide the best system RAS (recovery,
@@ -162,12 +188,15 @@ system-physical-address address causes a CPU exception while an access
 to a corrupted address through an BLK-aperture causes that block window
 to raise an error status in a register.  The latter is more aligned with
 the standard error model that host-bus-adapter attached disks present.
+
 Also, if an administrator ever wants to replace a memory it is easier to
 service a system at DIMM module boundaries.  Compare this to PMEM where
 data could be interleaved in an opaque hardware specific manner across
 several DIMMs.
 
 PMEM vs BLK
+-----------
+
 BLK-apertures solve these RAS problems, but their presence is also the
 major contributing factor to the complexity of the ND subsystem.  They
 complicate the implementation because PMEM and BLK alias in DPA space.
@@ -185,13 +214,14 @@ carved into an arbitrary number of BLK devices with discontiguous
 extents.
 
 BLK-REGIONs, PMEM-REGIONs, Atomic Sectors, and DAX
---------------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 One of the few
 reasons to allow multiple BLK namespaces per REGION is so that each
 BLK-namespace can be configured with a BTT with unique atomic sector
 sizes.  While a PMEM device can host a BTT the LABEL specification does
 not provide for a sector size to be specified for a PMEM namespace.
+
 This is due to the expectation that the primary usage model for PMEM is
 via DAX, and the BTT is incompatible with DAX.  However, for the cases
 where an application or filesystem still needs atomic sector update
@@ -200,52 +230,52 @@ LIBNVDIMM/NDCTL: Block Translation Table "btt"
 
 
 Example NVDIMM Platform
------------------------
+=======================
 
 For the remainder of this document the following diagram will be
-referenced for any example sysfs layouts.
+referenced for any example sysfs layouts::
 
 
-                             (a)               (b)           DIMM   BLK-REGION
-          +-------------------+--------+--------+--------+
-+------+  |       pm0.0       | blk2.0 | pm1.0  | blk2.1 |    0      region2
-| imc0 +--+- - - region0- - - +--------+        +--------+
-+--+---+  |       pm0.0       | blk3.0 | pm1.0  | blk3.1 |    1      region3
-   |      +-------------------+--------v        v--------+
-+--+---+                               |                 |
-| cpu0 |                                     region1
-+--+---+                               |                 |
-   |      +----------------------------^        ^--------+
-+--+---+  |           blk4.0           | pm1.0  | blk4.0 |    2      region4
-| imc1 +--+----------------------------|        +--------+
-+------+  |           blk5.0           | pm1.0  | blk5.0 |    3      region5
-          +----------------------------+--------+--------+
+                               (a)               (b)           DIMM   BLK-REGION
+            +-------------------+--------+--------+--------+
+  +------+  |       pm0.0       | blk2.0 | pm1.0  | blk2.1 |    0      region2
+  | imc0 +--+- - - region0- - - +--------+        +--------+
+  +--+---+  |       pm0.0       | blk3.0 | pm1.0  | blk3.1 |    1      region3
+     |      +-------------------+--------v        v--------+
+  +--+---+                               |                 |
+  | cpu0 |                                     region1
+  +--+---+                               |                 |
+     |      +----------------------------^        ^--------+
+  +--+---+  |           blk4.0           | pm1.0  | blk4.0 |    2      region4
+  | imc1 +--+----------------------------|        +--------+
+  +------+  |           blk5.0           | pm1.0  | blk5.0 |    3      region5
+            +----------------------------+--------+--------+
 
 In this platform we have four DIMMs and two memory controllers in one
 socket.  Each unique interface (BLK or PMEM) to DPA space is identified
 by a region device with a dynamically assigned id (REGION0 - REGION5).
 
     1. The first portion of DIMM0 and DIMM1 are interleaved as REGION0. A
-    single PMEM namespace is created in the REGION0-SPA-range that spans most
-    of DIMM0 and DIMM1 with a user-specified name of "pm0.0". Some of that
-    interleaved system-physical-address range is reclaimed as BLK-aperture
-    accessed space starting at DPA-offset (a) into each DIMM.  In that
-    reclaimed space we create two BLK-aperture "namespaces" from REGION2 and
-    REGION3 where "blk2.0" and "blk3.0" are just human readable names that
-    could be set to any user-desired name in the LABEL.
+       single PMEM namespace is created in the REGION0-SPA-range that spans most
+       of DIMM0 and DIMM1 with a user-specified name of "pm0.0". Some of that
+       interleaved system-physical-address range is reclaimed as BLK-aperture
+       accessed space starting at DPA-offset (a) into each DIMM.  In that
+       reclaimed space we create two BLK-aperture "namespaces" from REGION2 and
+       REGION3 where "blk2.0" and "blk3.0" are just human readable names that
+       could be set to any user-desired name in the LABEL.
 
     2. In the last portion of DIMM0 and DIMM1 we have an interleaved
-    system-physical-address range, REGION1, that spans those two DIMMs as
-    well as DIMM2 and DIMM3.  Some of REGION1 is allocated to a PMEM namespace
-    named "pm1.0", the rest is reclaimed in 4 BLK-aperture namespaces (for
-    each DIMM in the interleave set), "blk2.1", "blk3.1", "blk4.0", and
-    "blk5.0".
+       system-physical-address range, REGION1, that spans those two DIMMs as
+       well as DIMM2 and DIMM3.  Some of REGION1 is allocated to a PMEM namespace
+       named "pm1.0", the rest is reclaimed in 4 BLK-aperture namespaces (for
+       each DIMM in the interleave set), "blk2.1", "blk3.1", "blk4.0", and
+       "blk5.0".
 
     3. The portion of DIMM2 and DIMM3 that do not participate in the REGION1
-    interleaved system-physical-address range (i.e. the DPA address past
-    offset (b) are also included in the "blk4.0" and "blk5.0" namespaces.
-    Note, that this example shows that BLK-aperture namespaces don't need to
-    be contiguous in DPA-space.
+       interleaved system-physical-address range (i.e. the DPA address past
+       offset (b) are also included in the "blk4.0" and "blk5.0" namespaces.
+       Note, that this example shows that BLK-aperture namespaces don't need to
+       be contiguous in DPA-space.
 
     This bus is provided by the kernel under the device
     /sys/devices/platform/nfit_test.0 when CONFIG_NFIT_TEST is enabled and
@@ -254,7 +284,7 @@ by a region device with a dynamically assigned id (REGION0 - REGION5).
 
 
 LIBNVDIMM Kernel Device Model and LIBNDCTL Userspace API
-----------------------------------------------------
+========================================================
 
 What follows is a description of the LIBNVDIMM sysfs layout and a
 corresponding object hierarchy diagram as viewed through the LIBNDCTL
@@ -263,12 +293,18 @@ NVDIMM Platform which is also the LIBNVDIMM bus used in the LIBNDCTL unit
 test.
 
 LIBNDCTL: Context
+-----------------
+
 Every API call in the LIBNDCTL library requires a context that holds the
 logging parameters and other library instance state.  The library is
 based on the libabc template:
-https://git.kernel.org/cgit/linux/kernel/git/kay/libabc.git
+
+	https://git.kernel.org/cgit/linux/kernel/git/kay/libabc.git
 
 LIBNDCTL: instantiate a new library context example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
 
 	struct ndctl_ctx *ctx;
 
@@ -278,7 +314,7 @@ LIBNDCTL: instantiate a new library context example
 		return NULL;
 
 LIBNVDIMM/LIBNDCTL: Bus
--------------------
+-----------------------
 
 A bus has a 1:1 relationship with an NFIT.  The current expectation for
 ACPI based systems is that there is only ever one platform-global NFIT.
@@ -288,9 +324,10 @@ we use this capability to test multiple NFIT configurations in the unit
 test.
 
 LIBNVDIMM: control class device in /sys/class
+---------------------------------------------
 
 This character device accepts DSM messages to be passed to DIMM
-identified by its NFIT handle.
+identified by its NFIT handle::
 
 	/sys/class/nd/ndctl0
 	|-- dev
@@ -300,10 +337,15 @@ identified by its NFIT handle.
 
 
 LIBNVDIMM: bus
+--------------
+
+::
 
 	struct nvdimm_bus *nvdimm_bus_register(struct device *parent,
 	       struct nvdimm_bus_descriptor *nfit_desc);
 
+::
+
 	/sys/devices/platform/nfit_test.0/ndbus0
 	|-- commands
 	|-- nd
@@ -324,7 +366,9 @@ LIBNVDIMM: bus
 	`-- wait_probe
 
 LIBNDCTL: bus enumeration example
-Find the bus handle that describes the bus from Example NVDIMM Platform
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Find the bus handle that describes the bus from Example NVDIMM Platform::
 
 	static struct ndctl_bus *get_bus_by_provider(struct ndctl_ctx *ctx,
 			const char *provider)
@@ -342,7 +386,7 @@ Find the bus handle that describes the bus from Example NVDIMM Platform
 
 
 LIBNVDIMM/LIBNDCTL: DIMM (NMEM)
----------------------------
+-------------------------------
 
 The DIMM device provides a character device for sending commands to
 hardware, and it is a container for LABELs.  If the DIMM is defined by
@@ -355,11 +399,16 @@ Range Mapping Structure", and there is no requirement that they actually
 be physical DIMMs, so we use a more generic name.
 
 LIBNVDIMM: DIMM (NMEM)
+^^^^^^^^^^^^^^^^^^^^^^
+
+::
 
 	struct nvdimm *nvdimm_create(struct nvdimm_bus *nvdimm_bus, void *provider_data,
 			const struct attribute_group **groups, unsigned long flags,
 			unsigned long *dsm_mask);
 
+::
+
 	/sys/devices/platform/nfit_test.0/ndbus0
 	|-- nmem0
 	|   |-- available_slots
@@ -384,15 +433,20 @@ LIBNVDIMM: DIMM (NMEM)
 
 
 LIBNDCTL: DIMM enumeration example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Note, in this example we are assuming NFIT-defined DIMMs which are
 identified by an "nfit_handle" a 32-bit value where:
-Bit 3:0 DIMM number within the memory channel
-Bit 7:4 memory channel number
-Bit 11:8 memory controller ID
-Bit 15:12 socket ID (within scope of a Node controller if node controller is present)
-Bit 27:16 Node Controller ID
-Bit 31:28 Reserved
+
+   - Bit 3:0 DIMM number within the memory channel
+   - Bit 7:4 memory channel number
+   - Bit 11:8 memory controller ID
+   - Bit 15:12 socket ID (within scope of a Node controller if node
+     controller is present)
+   - Bit 27:16 Node Controller ID
+   - Bit 31:28 Reserved
+
+::
 
 	static struct ndctl_dimm *get_dimm_by_handle(struct ndctl_bus *bus,
 	       unsigned int handle)
@@ -413,7 +467,7 @@ Bit 31:28 Reserved
 	dimm = get_dimm_by_handle(bus, DIMM_HANDLE(0, 0, 0, 0, 0));
 
 LIBNVDIMM/LIBNDCTL: Region
-----------------------
+--------------------------
 
 A generic REGION device is registered for each PMEM range or BLK-aperture
 set.  Per the example there are 6 regions: 2 PMEM and 4 BLK-aperture
@@ -435,13 +489,15 @@ emits, "devtype" duplicates the DEVTYPE variable stored by udev at the
 at the 'add' event, and finally, the optional "spa_index" is provided in
 the case where the region is defined by a SPA.
 
-LIBNVDIMM: region
+LIBNVDIMM: region::
 
 	struct nd_region *nvdimm_pmem_region_create(struct nvdimm_bus *nvdimm_bus,
 			struct nd_region_desc *ndr_desc);
 	struct nd_region *nvdimm_blk_region_create(struct nvdimm_bus *nvdimm_bus,
 			struct nd_region_desc *ndr_desc);
 
+::
+
 	/sys/devices/platform/nfit_test.0/ndbus0
 	|-- region0
 	|   |-- available_size
@@ -468,10 +524,11 @@ LIBNVDIMM: region
 	[..]
 
 LIBNDCTL: region enumeration example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Sample region retrieval routines based on NFIT-unique data like
 "spa_index" (interleave set id) for PMEM and "nfit_handle" (dimm id) for
-BLK.
+BLK::
 
 	static struct ndctl_region *get_pmem_region_by_spa_index(struct ndctl_bus *bus,
 			unsigned int spa_index)
@@ -518,33 +575,33 @@ REGION name generic and expects userspace to always consider the
 region-attributes for four reasons:
 
     1. There are already more than two REGION and "namespace" types.  For
-    PMEM there are two subtypes.  As mentioned previously we have PMEM where
-    the constituent DIMM devices are known and anonymous PMEM.  For BLK
-    regions the NFIT specification already anticipates vendor specific
-    implementations.  The exact distinction of what a region contains is in
-    the region-attributes not the region-name or the region-devtype.
+       PMEM there are two subtypes.  As mentioned previously we have PMEM where
+       the constituent DIMM devices are known and anonymous PMEM.  For BLK
+       regions the NFIT specification already anticipates vendor specific
+       implementations.  The exact distinction of what a region contains is in
+       the region-attributes not the region-name or the region-devtype.
 
     2. A region with zero child-namespaces is a possible configuration.  For
-    example, the NFIT allows for a DCR to be published without a
-    corresponding BLK-aperture.  This equates to a DIMM that can only accept
-    control/configuration messages, but no i/o through a descendant block
-    device.  Again, this "type" is advertised in the attributes ('mappings'
-    == 0) and the name does not tell you much.
+       example, the NFIT allows for a DCR to be published without a
+       corresponding BLK-aperture.  This equates to a DIMM that can only accept
+       control/configuration messages, but no i/o through a descendant block
+       device.  Again, this "type" is advertised in the attributes ('mappings'
+       == 0) and the name does not tell you much.
 
     3. What if a third major interface type arises in the future?  Outside
-    of vendor specific implementations, it's not difficult to envision a
-    third class of interface type beyond BLK and PMEM.  With a generic name
-    for the REGION level of the device-hierarchy old userspace
-    implementations can still make sense of new kernel advertised
-    region-types.  Userspace can always rely on the generic region
-    attributes like "mappings", "size", etc and the expected child devices
-    named "namespace".  This generic format of the device-model hierarchy
-    allows the LIBNVDIMM and LIBNDCTL implementations to be more uniform and
-    future-proof.
+       of vendor specific implementations, it's not difficult to envision a
+       third class of interface type beyond BLK and PMEM.  With a generic name
+       for the REGION level of the device-hierarchy old userspace
+       implementations can still make sense of new kernel advertised
+       region-types.  Userspace can always rely on the generic region
+       attributes like "mappings", "size", etc and the expected child devices
+       named "namespace".  This generic format of the device-model hierarchy
+       allows the LIBNVDIMM and LIBNDCTL implementations to be more uniform and
+       future-proof.
 
     4. There are more robust mechanisms for determining the major type of a
-    region than a device name.  See the next section, How Do I Determine the
-    Major Type of a Region?
+       region than a device name.  See the next section, How Do I Determine the
+       Major Type of a Region?
 
 How Do I Determine the Major Type of a Region?
 ----------------------------------------------
@@ -553,7 +610,8 @@ Outside of the blanket recommendation of "use libndctl", or simply
 looking at the kernel header (/usr/include/linux/ndctl.h) to decode the
 "nstype" integer attribute, here are some other options.
 
-    1. module alias lookup:
+1. module alias lookup
+^^^^^^^^^^^^^^^^^^^^^^
 
     The whole point of region/namespace device type differentiation is to
     decide which block-device driver will attach to a given LIBNVDIMM namespace.
@@ -569,28 +627,31 @@ looking at the kernel header (/usr/include/linux/ndctl.h) to decode the
     the resulting namespaces.  The output from module resolution is more
     accurate than a region-name or region-devtype.
 
-    2. udev:
+2. udev
+^^^^^^^
 
-    The kernel "devtype" is registered in the udev database
-    # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region0
-    P: /devices/platform/nfit_test.0/ndbus0/region0
-    E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region0
-    E: DEVTYPE=nd_pmem
-    E: MODALIAS=nd:t2
-    E: SUBSYSTEM=nd
+    The kernel "devtype" is registered in the udev database::
 
-    # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region4
-    P: /devices/platform/nfit_test.0/ndbus0/region4
-    E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region4
-    E: DEVTYPE=nd_blk
-    E: MODALIAS=nd:t3
-    E: SUBSYSTEM=nd
+	# udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region0
+	P: /devices/platform/nfit_test.0/ndbus0/region0
+	E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region0
+	E: DEVTYPE=nd_pmem
+	E: MODALIAS=nd:t2
+	E: SUBSYSTEM=nd
+
+	# udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region4
+	P: /devices/platform/nfit_test.0/ndbus0/region4
+	E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region4
+	E: DEVTYPE=nd_blk
+	E: MODALIAS=nd:t3
+	E: SUBSYSTEM=nd
 
     ...and is available as a region attribute, but keep in mind that the
     "devtype" does not indicate sub-type variations and scripts should
     really be understanding the other attributes.
 
-    3. type specific attributes:
+3. type specific attributes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
     As it currently stands a BLK-aperture region will never have a
     "nfit/spa_index" attribute, but neither will a non-NFIT PMEM region.  A
@@ -600,7 +661,7 @@ looking at the kernel header (/usr/include/linux/ndctl.h) to decode the
 
 
 LIBNVDIMM/LIBNDCTL: Namespace
--------------------------
+-----------------------------
 
 A REGION, after resolving DPA aliasing and LABEL specified boundaries,
 surfaces one or more "namespace" devices.  The arrival of a "namespace"
@@ -608,12 +669,14 @@ device currently triggers either the nd_blk or nd_pmem driver to load
 and register a disk/block device.
 
 LIBNVDIMM: namespace
+^^^^^^^^^^^^^^^^^^^^
+
 Here is a sample layout from the three major types of NAMESPACE where
 namespace0.0 represents DIMM-info-backed PMEM (note that it has a 'uuid'
 attribute), namespace2.0 represents a BLK namespace (note it has a
 'sector_size' attribute) that, and namespace6.0 represents an anonymous
 PMEM namespace (note that has no 'uuid' attribute due to not support a
-LABEL).
+LABEL)::
 
 	/sys/devices/platform/nfit_test.0/ndbus0/region0/namespace0.0
 	|-- alt_name
@@ -656,76 +719,84 @@ LABEL).
 	`-- uevent
 
 LIBNDCTL: namespace enumeration example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Namespaces are indexed relative to their parent region, example below.
 These indexes are mostly static from boot to boot, but subsystem makes
 no guarantees in this regard.  For a static namespace identifier use its
 'uuid' attribute.
 
-static struct ndctl_namespace *get_namespace_by_id(struct ndctl_region *region,
-                unsigned int id)
-{
-        struct ndctl_namespace *ndns;
+::
 
-        ndctl_namespace_foreach(region, ndns)
-                if (ndctl_namespace_get_id(ndns) == id)
-                        return ndns;
+  static struct ndctl_namespace
+  *get_namespace_by_id(struct ndctl_region *region, unsigned int id)
+  {
+          struct ndctl_namespace *ndns;
 
-        return NULL;
-}
+          ndctl_namespace_foreach(region, ndns)
+                  if (ndctl_namespace_get_id(ndns) == id)
+                          return ndns;
+
+          return NULL;
+  }
 
 LIBNDCTL: namespace creation example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Idle namespaces are automatically created by the kernel if a given
 region has enough available capacity to create a new namespace.
 Namespace instantiation involves finding an idle namespace and
 configuring it.  For the most part the setting of namespace attributes
 can occur in any order, the only constraint is that 'uuid' must be set
 before 'size'.  This enables the kernel to track DPA allocations
-internally with a static identifier.
+internally with a static identifier::
 
-static int configure_namespace(struct ndctl_region *region,
-                struct ndctl_namespace *ndns,
-                struct namespace_parameters *parameters)
-{
-        char devname[50];
+  static int configure_namespace(struct ndctl_region *region,
+                  struct ndctl_namespace *ndns,
+                  struct namespace_parameters *parameters)
+  {
+          char devname[50];
 
-        snprintf(devname, sizeof(devname), "namespace%d.%d",
-                        ndctl_region_get_id(region), paramaters->id);
+          snprintf(devname, sizeof(devname), "namespace%d.%d",
+                          ndctl_region_get_id(region), paramaters->id);
 
-        ndctl_namespace_set_alt_name(ndns, devname);
-        /* 'uuid' must be set prior to setting size! */
-        ndctl_namespace_set_uuid(ndns, paramaters->uuid);
-        ndctl_namespace_set_size(ndns, paramaters->size);
-        /* unlike pmem namespaces, blk namespaces have a sector size */
-        if (parameters->lbasize)
-                ndctl_namespace_set_sector_size(ndns, parameters->lbasize);
-        ndctl_namespace_enable(ndns);
-}
+          ndctl_namespace_set_alt_name(ndns, devname);
+          /* 'uuid' must be set prior to setting size! */
+          ndctl_namespace_set_uuid(ndns, paramaters->uuid);
+          ndctl_namespace_set_size(ndns, paramaters->size);
+          /* unlike pmem namespaces, blk namespaces have a sector size */
+          if (parameters->lbasize)
+                  ndctl_namespace_set_sector_size(ndns, parameters->lbasize);
+          ndctl_namespace_enable(ndns);
+  }
 
 
 Why the Term "namespace"?
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
     1. Why not "volume" for instance?  "volume" ran the risk of confusing
-    ND (libnvdimm subsystem) to a volume manager like device-mapper.
+       ND (libnvdimm subsystem) to a volume manager like device-mapper.
 
     2. The term originated to describe the sub-devices that can be created
-    within a NVME controller (see the nvme specification:
-    http://www.nvmexpress.org/specifications/), and NFIT namespaces are
-    meant to parallel the capabilities and configurability of
-    NVME-namespaces.
+       within a NVME controller (see the nvme specification:
+       http://www.nvmexpress.org/specifications/), and NFIT namespaces are
+       meant to parallel the capabilities and configurability of
+       NVME-namespaces.
 
 
 LIBNVDIMM/LIBNDCTL: Block Translation Table "btt"
----------------------------------------------
+-------------------------------------------------
 
 A BTT (design document: http://pmem.io/2014/09/23/btt.html) is a stacked
 block device driver that fronts either the whole block device or a
 partition of a block device emitted by either a PMEM or BLK NAMESPACE.
 
 LIBNVDIMM: btt layout
+^^^^^^^^^^^^^^^^^^^^^
+
 Every region will start out with at least one BTT device which is the
 seed device.  To activate it set the "namespace", "uuid", and
 "sector_size" attributes and then bind the device to the nd_pmem or
-nd_blk driver depending on the region type.
+nd_blk driver depending on the region type::
 
 	/sys/devices/platform/nfit_test.1/ndbus0/region0/btt0/
 	|-- namespace
@@ -739,10 +810,12 @@ nd_blk driver depending on the region type.
 	`-- uuid
 
 LIBNDCTL: btt creation example
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Similar to namespaces an idle BTT device is automatically created per
 region.  Each time this "seed" btt device is configured and enabled a new
 seed is created.  Creating a BTT configuration involves two steps of
-finding and idle BTT and assigning it to consume a PMEM or BLK namespace.
+finding and idle BTT and assigning it to consume a PMEM or BLK namespace::
 
 	static struct ndctl_btt *get_idle_btt(struct ndctl_region *region)
 	{
@@ -787,29 +860,28 @@ Summary LIBNDCTL Diagram
 ------------------------
 
 For the given example above, here is the view of the objects as seen by the
-LIBNDCTL API:
-            +---+
-            |CTX|    +---------+   +--------------+  +---------------+
-            +-+-+  +-> REGION0 +---> NAMESPACE0.0 +--> PMEM8 "pm0.0" |
-              |    | +---------+   +--------------+  +---------------+
-+-------+     |    | +---------+   +--------------+  +---------------+
-| DIMM0 <-+   |    +-> REGION1 +---> NAMESPACE1.0 +--> PMEM6 "pm1.0" |
-+-------+ |   |    | +---------+   +--------------+  +---------------+
-| DIMM1 <-+ +-v--+ | +---------+   +--------------+  +---------------+
-+-------+ +-+BUS0+---> REGION2 +-+-> NAMESPACE2.0 +--> ND6  "blk2.0" |
-| DIMM2 <-+ +----+ | +---------+ | +--------------+  +----------------------+
-+-------+ |        |             +-> NAMESPACE2.1 +--> ND5  "blk2.1" | BTT2 |
-| DIMM3 <-+        |               +--------------+  +----------------------+
-+-------+          | +---------+   +--------------+  +---------------+
-                   +-> REGION3 +-+-> NAMESPACE3.0 +--> ND4  "blk3.0" |
-                   | +---------+ | +--------------+  +----------------------+
-                   |             +-> NAMESPACE3.1 +--> ND3  "blk3.1" | BTT1 |
-                   |               +--------------+  +----------------------+
-                   | +---------+   +--------------+  +---------------+
-                   +-> REGION4 +---> NAMESPACE4.0 +--> ND2  "blk4.0" |
-                   | +---------+   +--------------+  +---------------+
-                   | +---------+   +--------------+  +----------------------+
-                   +-> REGION5 +---> NAMESPACE5.0 +--> ND1  "blk5.0" | BTT0 |
-                     +---------+   +--------------+  +---------------+------+
-
+LIBNDCTL API::
 
+              +---+
+              |CTX|    +---------+   +--------------+  +---------------+
+              +-+-+  +-> REGION0 +---> NAMESPACE0.0 +--> PMEM8 "pm0.0" |
+                |    | +---------+   +--------------+  +---------------+
+  +-------+     |    | +---------+   +--------------+  +---------------+
+  | DIMM0 <-+   |    +-> REGION1 +---> NAMESPACE1.0 +--> PMEM6 "pm1.0" |
+  +-------+ |   |    | +---------+   +--------------+  +---------------+
+  | DIMM1 <-+ +-v--+ | +---------+   +--------------+  +---------------+
+  +-------+ +-+BUS0+---> REGION2 +-+-> NAMESPACE2.0 +--> ND6  "blk2.0" |
+  | DIMM2 <-+ +----+ | +---------+ | +--------------+  +----------------------+
+  +-------+ |        |             +-> NAMESPACE2.1 +--> ND5  "blk2.1" | BTT2 |
+  | DIMM3 <-+        |               +--------------+  +----------------------+
+  +-------+          | +---------+   +--------------+  +---------------+
+                     +-> REGION3 +-+-> NAMESPACE3.0 +--> ND4  "blk3.0" |
+                     | +---------+ | +--------------+  +----------------------+
+                     |             +-> NAMESPACE3.1 +--> ND3  "blk3.1" | BTT1 |
+                     |               +--------------+  +----------------------+
+                     | +---------+   +--------------+  +---------------+
+                     +-> REGION4 +---> NAMESPACE4.0 +--> ND2  "blk4.0" |
+                     | +---------+   +--------------+  +---------------+
+                     | +---------+   +--------------+  +----------------------+
+                     +-> REGION5 +---> NAMESPACE5.0 +--> ND1  "blk5.0" | BTT0 |
+                       +---------+   +--------------+  +---------------+------+
diff --git a/Documentation/nvdimm/security.txt b/Documentation/nvdimm/security.rst
similarity index 99%
rename from Documentation/nvdimm/security.txt
rename to Documentation/nvdimm/security.rst
index 4c36c05ca98e..ad9dea099b34 100644
--- a/Documentation/nvdimm/security.txt
+++ b/Documentation/nvdimm/security.rst
@@ -1,4 +1,5 @@
-NVDIMM SECURITY
+===============
+NVDIMM Security
 ===============
 
 1. Introduction
@@ -138,4 +139,5 @@ This command is only available when the master security is enabled, indicated
 by the extended security status.
 
 [1]: http://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf
+
 [2]: http://www.t13.org/documents/UploadedDocuments/docs2006/e05179r4-ACS-SecurityClarifications.pdf
diff --git a/drivers/nvdimm/Kconfig b/drivers/nvdimm/Kconfig
index 54500798f23a..e89c1c332407 100644
--- a/drivers/nvdimm/Kconfig
+++ b/drivers/nvdimm/Kconfig
@@ -33,7 +33,7 @@ config BLK_DEV_PMEM
 	  Documentation/admin-guide/kernel-parameters.rst).  This driver converts
 	  these persistent memory ranges into block devices that are
 	  capable of DAX (direct-access) file system mappings.  See
-	  Documentation/nvdimm/nvdimm.txt for more details.
+	  Documentation/nvdimm/nvdimm.rst for more details.
 
 	  Say Y if you want to use an NVDIMM
 
-- 
2.21.0

[PATCH v2 28/29] docs: xtensa: convert to ReST

[Mauro Carvalho Chehab]

Rename the xtensa documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

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>
---
 .../xtensa/{atomctl.txt => atomctl.rst}       |  13 +-
 .../xtensa/{booting.txt => booting.rst}       |   5 +-
 Documentation/xtensa/index.rst                |  12 ++
 Documentation/xtensa/mmu.rst                  | 195 ++++++++++++++++++
 Documentation/xtensa/mmu.txt                  | 189 -----------------
 arch/xtensa/include/asm/initialize_mmu.h      |   2 +-
 6 files changed, 222 insertions(+), 194 deletions(-)
 rename Documentation/xtensa/{atomctl.txt => atomctl.rst} (81%)
 rename Documentation/xtensa/{booting.txt => booting.rst} (91%)
 create mode 100644 Documentation/xtensa/index.rst
 create mode 100644 Documentation/xtensa/mmu.rst
 delete mode 100644 Documentation/xtensa/mmu.txt

diff --git a/Documentation/xtensa/atomctl.txt b/Documentation/xtensa/atomctl.rst
similarity index 81%
rename from Documentation/xtensa/atomctl.txt
rename to Documentation/xtensa/atomctl.rst
index 1da783ac200c..1ecbd0ba9a2e 100644
--- a/Documentation/xtensa/atomctl.txt
+++ b/Documentation/xtensa/atomctl.rst
@@ -1,3 +1,7 @@
+===========================================
+Atomic Operation Control (ATOMCTL) Register
+===========================================
+
 We Have Atomic Operation Control (ATOMCTL) Register.
 This register determines the effect of using a S32C1I instruction
 with various combinations of:
@@ -8,7 +12,7 @@ with various combinations of:
      2. With and without An Intelligent Memory Controller which
         can do Atomic Transactions itself.
 
-The Core comes up with a default value of for the three types of cache ops:
+The Core comes up with a default value of for the three types of cache ops::
 
       0x28: (WB: Internal, WT: Internal, BY:Exception)
 
@@ -30,15 +34,18 @@ CUSTOMER-WARNING:
 Developers might find using RCW in Bypass mode convenient when testing
 with the cache being bypassed; for example studying cache alias problems.
 
-See Section 4.3.12.4 of ISA; Bits:
+See Section 4.3.12.4 of ISA; Bits::
 
                              WB     WT      BY
                            5   4 | 3   2 | 1   0
+
+=========    ==================      ==================      ===============
   2 Bit
   Field
   Values     WB - Write Back         WT - Write Thru         BY - Bypass
----------    ---------------         -----------------     ----------------
+=========    ==================      ==================      ===============
     0        Exception               Exception               Exception
     1        RCW Transaction         RCW Transaction         RCW Transaction
     2        Internal Operation      Internal Operation      Reserved
     3        Reserved                Reserved                Reserved
+=========    ==================      ==================      ===============
diff --git a/Documentation/xtensa/booting.txt b/Documentation/xtensa/booting.rst
similarity index 91%
rename from Documentation/xtensa/booting.txt
rename to Documentation/xtensa/booting.rst
index 402b33a2619f..e1b83707e5b6 100644
--- a/Documentation/xtensa/booting.txt
+++ b/Documentation/xtensa/booting.rst
@@ -1,10 +1,13 @@
-Passing boot parameters to the kernel.
+=====================================
+Passing boot parameters to the kernel
+=====================================
 
 Boot parameters are represented as a TLV list in the memory. Please see
 arch/xtensa/include/asm/bootparam.h for definition of the bp_tag structure and
 tag value constants. First entry in the list must have type BP_TAG_FIRST, last
 entry must have type BP_TAG_LAST. The address of the first list entry is
 passed to the kernel in the register a2. The address type depends on MMU type:
+
 - For configurations without MMU, with region protection or with MPU the
   address must be the physical address.
 - For configurations with region translarion MMU or with MMUv3 and CONFIG_MMU=n
diff --git a/Documentation/xtensa/index.rst b/Documentation/xtensa/index.rst
new file mode 100644
index 000000000000..5a24e365e35f
--- /dev/null
+++ b/Documentation/xtensa/index.rst
@@ -0,0 +1,12 @@
+:orphan:
+
+===================
+Xtensa Architecture
+===================
+
+.. toctree::
+   :maxdepth: 1
+
+   atomctl
+   booting
+   mmu
diff --git a/Documentation/xtensa/mmu.rst b/Documentation/xtensa/mmu.rst
new file mode 100644
index 000000000000..e52a12960fdc
--- /dev/null
+++ b/Documentation/xtensa/mmu.rst
@@ -0,0 +1,195 @@
+=============================
+MMUv3 initialization sequence
+=============================
+
+The code in the initialize_mmu macro sets up MMUv3 memory mapping
+identically to MMUv2 fixed memory mapping. Depending on
+CONFIG_INITIALIZE_XTENSA_MMU_INSIDE_VMLINUX symbol this code is
+located in addresses it was linked for (symbol undefined), or not
+(symbol defined), so it needs to be position-independent.
+
+The code has the following assumptions:
+
+  - This code fragment is run only on an MMU v3.
+  - TLBs are in their reset state.
+  - ITLBCFG and DTLBCFG are zero (reset state).
+  - RASID is 0x04030201 (reset state).
+  - PS.RING is zero (reset state).
+  - LITBASE is zero (reset state, PC-relative literals); required to be PIC.
+
+TLB setup proceeds along the following steps.
+
+  Legend:
+
+    - VA = virtual address (two upper nibbles of it);
+    - PA = physical address (two upper nibbles of it);
+    - pc = physical range that contains this code;
+
+After step 2, we jump to virtual address in the range 0x40000000..0x5fffffff
+or 0x00000000..0x1fffffff, depending on whether the kernel was loaded below
+0x40000000 or above. That address corresponds to next instruction to execute
+in this code. After step 4, we jump to intended (linked) address of this code.
+The scheme below assumes that the kernel is loaded below 0x40000000.
+
+ ====== =====  =====  =====  =====   ====== =====  =====
+ -      Step0  Step1  Step2  Step3          Step4  Step5
+
+   VA      PA     PA     PA     PA     VA      PA     PA
+ ====== =====  =====  =====  =====   ====== =====  =====
+ E0..FF -> E0  -> E0  -> E0          F0..FF -> F0  -> F0
+ C0..DF -> C0  -> C0  -> C0          E0..EF -> F0  -> F0
+ A0..BF -> A0  -> A0  -> A0          D8..DF -> 00  -> 00
+ 80..9F -> 80  -> 80  -> 80          D0..D7 -> 00  -> 00
+ 60..7F -> 60  -> 60  -> 60
+ 40..5F -> 40         -> pc  -> pc   40..5F -> pc
+ 20..3F -> 20  -> 20  -> 20
+ 00..1F -> 00  -> 00  -> 00
+ ====== =====  =====  =====  =====   ====== =====  =====
+
+The default location of IO peripherals is above 0xf0000000. This may be changed
+using a "ranges" property in a device tree simple-bus node. See the Devicetree
+Specification, section 4.5 for details on the syntax and semantics of
+simple-bus nodes. The following limitations apply:
+
+1. Only top level simple-bus nodes are considered
+
+2. Only one (first) simple-bus node is considered
+
+3. Empty "ranges" properties are not supported
+
+4. Only the first triplet in the "ranges" property is considered
+
+5. The parent-bus-address value is rounded down to the nearest 256MB boundary
+
+6. The IO area covers the entire 256MB segment of parent-bus-address; the
+   "ranges" triplet length field is ignored
+
+
+MMUv3 address space layouts.
+============================
+
+Default MMUv2-compatible layout::
+
+                        Symbol                   VADDR       Size
+  +------------------+
+  | Userspace        |                           0x00000000  TASK_SIZE
+  +------------------+                           0x40000000
+  +------------------+
+  | Page table       |  XCHAL_PAGE_TABLE_VADDR   0x80000000  XCHAL_PAGE_TABLE_SIZE
+  +------------------+
+  | KASAN shadow map |  KASAN_SHADOW_START       0x80400000  KASAN_SHADOW_SIZE
+  +------------------+                           0x8e400000
+  +------------------+
+  | VMALLOC area     |  VMALLOC_START            0xc0000000  128MB - 64KB
+  +------------------+  VMALLOC_END
+  | Cache aliasing   |  TLBTEMP_BASE_1           0xc7ff0000  DCACHE_WAY_SIZE
+  | remap area 1     |
+  +------------------+
+  | Cache aliasing   |  TLBTEMP_BASE_2                       DCACHE_WAY_SIZE
+  | remap area 2     |
+  +------------------+
+  +------------------+
+  | KMAP area        |  PKMAP_BASE                           PTRS_PER_PTE *
+  |                  |                                       DCACHE_N_COLORS *
+  |                  |                                       PAGE_SIZE
+  |                  |                                       (4MB * DCACHE_N_COLORS)
+  +------------------+
+  | Atomic KMAP area |  FIXADDR_START                        KM_TYPE_NR *
+  |                  |                                       NR_CPUS *
+  |                  |                                       DCACHE_N_COLORS *
+  |                  |                                       PAGE_SIZE
+  +------------------+  FIXADDR_TOP              0xcffff000
+  +------------------+
+  | Cached KSEG      |  XCHAL_KSEG_CACHED_VADDR  0xd0000000  128MB
+  +------------------+
+  | Uncached KSEG    |  XCHAL_KSEG_BYPASS_VADDR  0xd8000000  128MB
+  +------------------+
+  | Cached KIO       |  XCHAL_KIO_CACHED_VADDR   0xe0000000  256MB
+  +------------------+
+  | Uncached KIO     |  XCHAL_KIO_BYPASS_VADDR   0xf0000000  256MB
+  +------------------+
+
+
+256MB cached + 256MB uncached layout::
+
+                        Symbol                   VADDR       Size
+  +------------------+
+  | Userspace        |                           0x00000000  TASK_SIZE
+  +------------------+                           0x40000000
+  +------------------+
+  | Page table       |  XCHAL_PAGE_TABLE_VADDR   0x80000000  XCHAL_PAGE_TABLE_SIZE
+  +------------------+
+  | KASAN shadow map |  KASAN_SHADOW_START       0x80400000  KASAN_SHADOW_SIZE
+  +------------------+                           0x8e400000
+  +------------------+
+  | VMALLOC area     |  VMALLOC_START            0xa0000000  128MB - 64KB
+  +------------------+  VMALLOC_END
+  | Cache aliasing   |  TLBTEMP_BASE_1           0xa7ff0000  DCACHE_WAY_SIZE
+  | remap area 1     |
+  +------------------+
+  | Cache aliasing   |  TLBTEMP_BASE_2                       DCACHE_WAY_SIZE
+  | remap area 2     |
+  +------------------+
+  +------------------+
+  | KMAP area        |  PKMAP_BASE                           PTRS_PER_PTE *
+  |                  |                                       DCACHE_N_COLORS *
+  |                  |                                       PAGE_SIZE
+  |                  |                                       (4MB * DCACHE_N_COLORS)
+  +------------------+
+  | Atomic KMAP area |  FIXADDR_START                        KM_TYPE_NR *
+  |                  |                                       NR_CPUS *
+  |                  |                                       DCACHE_N_COLORS *
+  |                  |                                       PAGE_SIZE
+  +------------------+  FIXADDR_TOP              0xaffff000
+  +------------------+
+  | Cached KSEG      |  XCHAL_KSEG_CACHED_VADDR  0xb0000000  256MB
+  +------------------+
+  | Uncached KSEG    |  XCHAL_KSEG_BYPASS_VADDR  0xc0000000  256MB
+  +------------------+
+  +------------------+
+  | Cached KIO       |  XCHAL_KIO_CACHED_VADDR   0xe0000000  256MB
+  +------------------+
+  | Uncached KIO     |  XCHAL_KIO_BYPASS_VADDR   0xf0000000  256MB
+  +------------------+
+
+
+512MB cached + 512MB uncached layout::
+
+                        Symbol                   VADDR       Size
+  +------------------+
+  | Userspace        |                           0x00000000  TASK_SIZE
+  +------------------+                           0x40000000
+  +------------------+
+  | Page table       |  XCHAL_PAGE_TABLE_VADDR   0x80000000  XCHAL_PAGE_TABLE_SIZE
+  +------------------+
+  | KASAN shadow map |  KASAN_SHADOW_START       0x80400000  KASAN_SHADOW_SIZE
+  +------------------+                           0x8e400000
+  +------------------+
+  | VMALLOC area     |  VMALLOC_START            0x90000000  128MB - 64KB
+  +------------------+  VMALLOC_END
+  | Cache aliasing   |  TLBTEMP_BASE_1           0x97ff0000  DCACHE_WAY_SIZE
+  | remap area 1     |
+  +------------------+
+  | Cache aliasing   |  TLBTEMP_BASE_2                       DCACHE_WAY_SIZE
+  | remap area 2     |
+  +------------------+
+  +------------------+
+  | KMAP area        |  PKMAP_BASE                           PTRS_PER_PTE *
+  |                  |                                       DCACHE_N_COLORS *
+  |                  |                                       PAGE_SIZE
+  |                  |                                       (4MB * DCACHE_N_COLORS)
+  +------------------+
+  | Atomic KMAP area |  FIXADDR_START                        KM_TYPE_NR *
+  |                  |                                       NR_CPUS *
+  |                  |                                       DCACHE_N_COLORS *
+  |                  |                                       PAGE_SIZE
+  +------------------+  FIXADDR_TOP              0x9ffff000
+  +------------------+
+  | Cached KSEG      |  XCHAL_KSEG_CACHED_VADDR  0xa0000000  512MB
+  +------------------+
+  | Uncached KSEG    |  XCHAL_KSEG_BYPASS_VADDR  0xc0000000  512MB
+  +------------------+
+  | Cached KIO       |  XCHAL_KIO_CACHED_VADDR   0xe0000000  256MB
+  +------------------+
+  | Uncached KIO     |  XCHAL_KIO_BYPASS_VADDR   0xf0000000  256MB
+  +------------------+
diff --git a/Documentation/xtensa/mmu.txt b/Documentation/xtensa/mmu.txt
deleted file mode 100644
index 318114de63f3..000000000000
--- a/Documentation/xtensa/mmu.txt
+++ /dev/null
@@ -1,189 +0,0 @@
-MMUv3 initialization sequence.
-
-The code in the initialize_mmu macro sets up MMUv3 memory mapping
-identically to MMUv2 fixed memory mapping. Depending on
-CONFIG_INITIALIZE_XTENSA_MMU_INSIDE_VMLINUX symbol this code is
-located in addresses it was linked for (symbol undefined), or not
-(symbol defined), so it needs to be position-independent.
-
-The code has the following assumptions:
-  This code fragment is run only on an MMU v3.
-  TLBs are in their reset state.
-  ITLBCFG and DTLBCFG are zero (reset state).
-  RASID is 0x04030201 (reset state).
-  PS.RING is zero (reset state).
-  LITBASE is zero (reset state, PC-relative literals); required to be PIC.
-
-TLB setup proceeds along the following steps.
-
-  Legend:
-    VA = virtual address (two upper nibbles of it);
-    PA = physical address (two upper nibbles of it);
-    pc = physical range that contains this code;
-
-After step 2, we jump to virtual address in the range 0x40000000..0x5fffffff
-or 0x00000000..0x1fffffff, depending on whether the kernel was loaded below
-0x40000000 or above. That address corresponds to next instruction to execute
-in this code. After step 4, we jump to intended (linked) address of this code.
-The scheme below assumes that the kernel is loaded below 0x40000000.
-
-        Step0  Step1  Step2  Step3          Step4  Step5
-        =====  =====  =====  =====          =====  =====
-   VA      PA     PA     PA     PA     VA      PA     PA
- ------    --     --     --     --   ------    --     --
- E0..FF -> E0  -> E0  -> E0          F0..FF -> F0  -> F0
- C0..DF -> C0  -> C0  -> C0          E0..EF -> F0  -> F0
- A0..BF -> A0  -> A0  -> A0          D8..DF -> 00  -> 00
- 80..9F -> 80  -> 80  -> 80          D0..D7 -> 00  -> 00
- 60..7F -> 60  -> 60  -> 60
- 40..5F -> 40         -> pc  -> pc   40..5F -> pc
- 20..3F -> 20  -> 20  -> 20
- 00..1F -> 00  -> 00  -> 00
-
-The default location of IO peripherals is above 0xf0000000. This may be changed
-using a "ranges" property in a device tree simple-bus node. See the Devicetree
-Specification, section 4.5 for details on the syntax and semantics of
-simple-bus nodes. The following limitations apply:
-
-1. Only top level simple-bus nodes are considered
-
-2. Only one (first) simple-bus node is considered
-
-3. Empty "ranges" properties are not supported
-
-4. Only the first triplet in the "ranges" property is considered
-
-5. The parent-bus-address value is rounded down to the nearest 256MB boundary
-
-6. The IO area covers the entire 256MB segment of parent-bus-address; the
-   "ranges" triplet length field is ignored
-
-
-MMUv3 address space layouts.
-============================
-
-Default MMUv2-compatible layout.
-
-                      Symbol                   VADDR       Size
-+------------------+
-| Userspace        |                           0x00000000  TASK_SIZE
-+------------------+                           0x40000000
-+------------------+
-| Page table       |  XCHAL_PAGE_TABLE_VADDR   0x80000000  XCHAL_PAGE_TABLE_SIZE
-+------------------+
-| KASAN shadow map |  KASAN_SHADOW_START       0x80400000  KASAN_SHADOW_SIZE
-+------------------+                           0x8e400000
-+------------------+
-| VMALLOC area     |  VMALLOC_START            0xc0000000  128MB - 64KB
-+------------------+  VMALLOC_END
-| Cache aliasing   |  TLBTEMP_BASE_1           0xc7ff0000  DCACHE_WAY_SIZE
-| remap area 1     |
-+------------------+
-| Cache aliasing   |  TLBTEMP_BASE_2                       DCACHE_WAY_SIZE
-| remap area 2     |
-+------------------+
-+------------------+
-| KMAP area        |  PKMAP_BASE                           PTRS_PER_PTE *
-|                  |                                       DCACHE_N_COLORS *
-|                  |                                       PAGE_SIZE
-|                  |                                       (4MB * DCACHE_N_COLORS)
-+------------------+
-| Atomic KMAP area |  FIXADDR_START                        KM_TYPE_NR *
-|                  |                                       NR_CPUS *
-|                  |                                       DCACHE_N_COLORS *
-|                  |                                       PAGE_SIZE
-+------------------+  FIXADDR_TOP              0xcffff000
-+------------------+
-| Cached KSEG      |  XCHAL_KSEG_CACHED_VADDR  0xd0000000  128MB
-+------------------+
-| Uncached KSEG    |  XCHAL_KSEG_BYPASS_VADDR  0xd8000000  128MB
-+------------------+
-| Cached KIO       |  XCHAL_KIO_CACHED_VADDR   0xe0000000  256MB
-+------------------+
-| Uncached KIO     |  XCHAL_KIO_BYPASS_VADDR   0xf0000000  256MB
-+------------------+
-
-
-256MB cached + 256MB uncached layout.
-
-                      Symbol                   VADDR       Size
-+------------------+
-| Userspace        |                           0x00000000  TASK_SIZE
-+------------------+                           0x40000000
-+------------------+
-| Page table       |  XCHAL_PAGE_TABLE_VADDR   0x80000000  XCHAL_PAGE_TABLE_SIZE
-+------------------+
-| KASAN shadow map |  KASAN_SHADOW_START       0x80400000  KASAN_SHADOW_SIZE
-+------------------+                           0x8e400000
-+------------------+
-| VMALLOC area     |  VMALLOC_START            0xa0000000  128MB - 64KB
-+------------------+  VMALLOC_END
-| Cache aliasing   |  TLBTEMP_BASE_1           0xa7ff0000  DCACHE_WAY_SIZE
-| remap area 1     |
-+------------------+
-| Cache aliasing   |  TLBTEMP_BASE_2                       DCACHE_WAY_SIZE
-| remap area 2     |
-+------------------+
-+------------------+
-| KMAP area        |  PKMAP_BASE                           PTRS_PER_PTE *
-|                  |                                       DCACHE_N_COLORS *
-|                  |                                       PAGE_SIZE
-|                  |                                       (4MB * DCACHE_N_COLORS)
-+------------------+
-| Atomic KMAP area |  FIXADDR_START                        KM_TYPE_NR *
-|                  |                                       NR_CPUS *
-|                  |                                       DCACHE_N_COLORS *
-|                  |                                       PAGE_SIZE
-+------------------+  FIXADDR_TOP              0xaffff000
-+------------------+
-| Cached KSEG      |  XCHAL_KSEG_CACHED_VADDR  0xb0000000  256MB
-+------------------+
-| Uncached KSEG    |  XCHAL_KSEG_BYPASS_VADDR  0xc0000000  256MB
-+------------------+
-+------------------+
-| Cached KIO       |  XCHAL_KIO_CACHED_VADDR   0xe0000000  256MB
-+------------------+
-| Uncached KIO     |  XCHAL_KIO_BYPASS_VADDR   0xf0000000  256MB
-+------------------+
-
-
-512MB cached + 512MB uncached layout.
-
-                      Symbol                   VADDR       Size
-+------------------+
-| Userspace        |                           0x00000000  TASK_SIZE
-+------------------+                           0x40000000
-+------------------+
-| Page table       |  XCHAL_PAGE_TABLE_VADDR   0x80000000  XCHAL_PAGE_TABLE_SIZE
-+------------------+
-| KASAN shadow map |  KASAN_SHADOW_START       0x80400000  KASAN_SHADOW_SIZE
-+------------------+                           0x8e400000
-+------------------+
-| VMALLOC area     |  VMALLOC_START            0x90000000  128MB - 64KB
-+------------------+  VMALLOC_END
-| Cache aliasing   |  TLBTEMP_BASE_1           0x97ff0000  DCACHE_WAY_SIZE
-| remap area 1     |
-+------------------+
-| Cache aliasing   |  TLBTEMP_BASE_2                       DCACHE_WAY_SIZE
-| remap area 2     |
-+------------------+
-+------------------+
-| KMAP area        |  PKMAP_BASE                           PTRS_PER_PTE *
-|                  |                                       DCACHE_N_COLORS *
-|                  |                                       PAGE_SIZE
-|                  |                                       (4MB * DCACHE_N_COLORS)
-+------------------+
-| Atomic KMAP area |  FIXADDR_START                        KM_TYPE_NR *
-|                  |                                       NR_CPUS *
-|                  |                                       DCACHE_N_COLORS *
-|                  |                                       PAGE_SIZE
-+------------------+  FIXADDR_TOP              0x9ffff000
-+------------------+
-| Cached KSEG      |  XCHAL_KSEG_CACHED_VADDR  0xa0000000  512MB
-+------------------+
-| Uncached KSEG    |  XCHAL_KSEG_BYPASS_VADDR  0xc0000000  512MB
-+------------------+
-| Cached KIO       |  XCHAL_KIO_CACHED_VADDR   0xe0000000  256MB
-+------------------+
-| Uncached KIO     |  XCHAL_KIO_BYPASS_VADDR   0xf0000000  256MB
-+------------------+
diff --git a/arch/xtensa/include/asm/initialize_mmu.h b/arch/xtensa/include/asm/initialize_mmu.h
index 323d05789159..3b054d2bede0 100644
--- a/arch/xtensa/include/asm/initialize_mmu.h
+++ b/arch/xtensa/include/asm/initialize_mmu.h
@@ -42,7 +42,7 @@
 #if XCHAL_HAVE_S32C1I && (XCHAL_HW_MIN_VERSION >= XTENSA_HWVERSION_RC_2009_0)
 /*
  * We Have Atomic Operation Control (ATOMCTL) Register; Initialize it.
- * For details see Documentation/xtensa/atomctl.txt
+ * For details see Documentation/xtensa/atomctl.rst
  */
 #if XCHAL_DCACHE_IS_COHERENT
 	movi	a3, 0x25	/* For SMP/MX -- internal for writeback,
-- 
2.21.0

[PATCH v2 29/29] docs: mmc: convert to ReST

[Mauro Carvalho Chehab]

Rename the mmc documentation files to ReST, add an
index for them and adjust in order to produce a nice html
output via the Sphinx build system.

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/mmc/index.rst                   | 13 +++++
 .../{mmc-async-req.txt => mmc-async-req.rst}  | 53 +++++++++++--------
 .../{mmc-dev-attrs.txt => mmc-dev-attrs.rst}  | 32 +++++++----
 .../{mmc-dev-parts.txt => mmc-dev-parts.rst}  | 13 ++---
 .../mmc/{mmc-tools.txt => mmc-tools.rst}      |  5 +-
 5 files changed, 79 insertions(+), 37 deletions(-)
 create mode 100644 Documentation/mmc/index.rst
 rename Documentation/mmc/{mmc-async-req.txt => mmc-async-req.rst} (75%)
 rename Documentation/mmc/{mmc-dev-attrs.txt => mmc-dev-attrs.rst} (73%)
 rename Documentation/mmc/{mmc-dev-parts.txt => mmc-dev-parts.rst} (83%)
 rename Documentation/mmc/{mmc-tools.txt => mmc-tools.rst} (92%)

diff --git a/Documentation/mmc/index.rst b/Documentation/mmc/index.rst
new file mode 100644
index 000000000000..3305478ddadb
--- /dev/null
+++ b/Documentation/mmc/index.rst
@@ -0,0 +1,13 @@
+:orphan:
+
+========================
+MMC/SD/SDIO card support
+========================
+
+.. toctree::
+   :maxdepth: 1
+
+   mmc-dev-attrs
+   mmc-dev-parts
+   mmc-async-req
+   mmc-tools
diff --git a/Documentation/mmc/mmc-async-req.txt b/Documentation/mmc/mmc-async-req.rst
similarity index 75%
rename from Documentation/mmc/mmc-async-req.txt
rename to Documentation/mmc/mmc-async-req.rst
index ae1907b10e4a..0f7197c9c3b5 100644
--- a/Documentation/mmc/mmc-async-req.txt
+++ b/Documentation/mmc/mmc-async-req.rst
@@ -1,13 +1,20 @@
+========================
+MMC Asynchronous Request
+========================
+
 Rationale
 =========
 
 How significant is the cache maintenance overhead?
+
 It depends. Fast eMMC and multiple cache levels with speculative cache
 pre-fetch makes the cache overhead relatively significant. If the DMA
 preparations for the next request are done in parallel with the current
 transfer, the DMA preparation overhead would not affect the MMC performance.
+
 The intention of non-blocking (asynchronous) MMC requests is to minimize the
 time between when an MMC request ends and another MMC request begins.
+
 Using mmc_wait_for_req(), the MMC controller is idle while dma_map_sg and
 dma_unmap_sg are processing. Using non-blocking MMC requests makes it
 possible to prepare the caches for next job in parallel with an active
@@ -17,6 +24,7 @@ MMC block driver
 ================
 
 The mmc_blk_issue_rw_rq() in the MMC block driver is made non-blocking.
+
 The increase in throughput is proportional to the time it takes to
 prepare (major part of preparations are dma_map_sg() and dma_unmap_sg())
 a request and how fast the memory is. The faster the MMC/SD is the
@@ -35,6 +43,7 @@ MMC core API extension
 ======================
 
 There is one new public function mmc_start_req().
+
 It starts a new MMC command request for a host. The function isn't
 truly non-blocking. If there is an ongoing async request it waits
 for completion of that request and starts the new one and returns. It
@@ -47,6 +56,7 @@ MMC host extensions
 There are two optional members in the mmc_host_ops -- pre_req() and
 post_req() -- that the host driver may implement in order to move work
 to before and after the actual mmc_host_ops.request() function is called.
+
 In the DMA case pre_req() may do dma_map_sg() and prepare the DMA
 descriptor, and post_req() runs the dma_unmap_sg().
 
@@ -55,33 +65,34 @@ Optimize for the first request
 
 The first request in a series of requests can't be prepared in parallel
 with the previous transfer, since there is no previous request.
+
 The argument is_first_req in pre_req() indicates that there is no previous
 request. The host driver may optimize for this scenario to minimize
 the performance loss. A way to optimize for this is to split the current
 request in two chunks, prepare the first chunk and start the request,
 and finally prepare the second chunk and start the transfer.
 
-Pseudocode to handle is_first_req scenario with minimal prepare overhead:
+Pseudocode to handle is_first_req scenario with minimal prepare overhead::
 
-if (is_first_req && req->size > threshold)
-   /* start MMC transfer for the complete transfer size */
-   mmc_start_command(MMC_CMD_TRANSFER_FULL_SIZE);
+  if (is_first_req && req->size > threshold)
+     /* start MMC transfer for the complete transfer size */
+     mmc_start_command(MMC_CMD_TRANSFER_FULL_SIZE);
 
-   /*
-    * Begin to prepare DMA while cmd is being processed by MMC.
-    * The first chunk of the request should take the same time
-    * to prepare as the "MMC process command time".
-    * If prepare time exceeds MMC cmd time
-    * the transfer is delayed, guesstimate max 4k as first chunk size.
-    */
-    prepare_1st_chunk_for_dma(req);
-    /* flush pending desc to the DMAC (dmaengine.h) */
-    dma_issue_pending(req->dma_desc);
+     /*
+      * Begin to prepare DMA while cmd is being processed by MMC.
+      * The first chunk of the request should take the same time
+      * to prepare as the "MMC process command time".
+      * If prepare time exceeds MMC cmd time
+      * the transfer is delayed, guesstimate max 4k as first chunk size.
+      */
+      prepare_1st_chunk_for_dma(req);
+      /* flush pending desc to the DMAC (dmaengine.h) */
+      dma_issue_pending(req->dma_desc);
 
-    prepare_2nd_chunk_for_dma(req);
-    /*
-     * The second issue_pending should be called before MMC runs out
-     * of the first chunk. If the MMC runs out of the first data chunk
-     * before this call, the transfer is delayed.
-     */
-    dma_issue_pending(req->dma_desc);
+      prepare_2nd_chunk_for_dma(req);
+      /*
+       * The second issue_pending should be called before MMC runs out
+       * of the first chunk. If the MMC runs out of the first data chunk
+       * before this call, the transfer is delayed.
+       */
+      dma_issue_pending(req->dma_desc);
diff --git a/Documentation/mmc/mmc-dev-attrs.txt b/Documentation/mmc/mmc-dev-attrs.rst
similarity index 73%
rename from Documentation/mmc/mmc-dev-attrs.txt
rename to Documentation/mmc/mmc-dev-attrs.rst
index 4ad0bb17f343..4f44b1b730d6 100644
--- a/Documentation/mmc/mmc-dev-attrs.txt
+++ b/Documentation/mmc/mmc-dev-attrs.rst
@@ -1,3 +1,4 @@
+==================================
 SD and MMC Block Device Attributes
 ==================================
 
@@ -6,23 +7,29 @@ SD or MMC device.
 
 The following attributes are read/write.
 
-	force_ro		Enforce read-only access even if write protect switch is off.
+	========		===============================================
+	force_ro		Enforce read-only access even if write protect 					switch is off.
+	========		===============================================
 
 SD and MMC Device Attributes
 ============================
 
 All attributes are read-only.
 
+	======================	===============================================
 	cid			Card Identification Register
 	csd			Card Specific Data Register
 	scr			SD Card Configuration Register (SD only)
 	date			Manufacturing Date (from CID Register)
-	fwrev			Firmware/Product Revision (from CID Register) (SD and MMCv1 only)
-	hwrev			Hardware/Product Revision (from CID Register) (SD and MMCv1 only)
+	fwrev			Firmware/Product Revision (from CID Register)
+				(SD and MMCv1 only)
+	hwrev			Hardware/Product Revision (from CID Register)
+				(SD and MMCv1 only)
 	manfid			Manufacturer ID (from CID Register)
 	name			Product Name (from CID Register)
 	oemid			OEM/Application ID (from CID Register)
-	prv			Product Revision (from CID Register) (SD and MMCv4 only)
+	prv			Product Revision (from CID Register)
+				(SD and MMCv4 only)
 	serial			Product Serial Number (from CID Register)
 	erase_size		Erase group size
 	preferred_erase_size	Preferred erase size
@@ -30,7 +37,10 @@ All attributes are read-only.
 	rel_sectors		Reliable write sector count
 	ocr 			Operation Conditions Register
 	dsr			Driver Stage Register
-	cmdq_en			Command Queue enabled: 1 => enabled, 0 => not enabled
+	cmdq_en			Command Queue enabled:
+
+					1 => enabled, 0 => not enabled
+	======================	===============================================
 
 Note on Erase Size and Preferred Erase Size:
 
@@ -44,14 +54,15 @@ Note on Erase Size and Preferred Erase Size:
 	SD/MMC cards can erase an arbitrarily large area up to and
 	including the whole card.  When erasing a large area it may
 	be desirable to do it in smaller chunks for three reasons:
-		1. A single erase command will make all other I/O on
+
+	     1. A single erase command will make all other I/O on
 		the card wait.  This is not a problem if the whole card
 		is being erased, but erasing one partition will make
 		I/O for another partition on the same card wait for the
 		duration of the erase - which could be a several
 		minutes.
-		2. To be able to inform the user of erase progress.
-		3. The erase timeout becomes too large to be very
+	     2. To be able to inform the user of erase progress.
+	     3. The erase timeout becomes too large to be very
 		useful.  Because the erase timeout contains a margin
 		which is multiplied by the size of the erase area,
 		the value can end up being several minutes for large
@@ -72,6 +83,9 @@ Note on Erase Size and Preferred Erase Size:
 	"preferred_erase_size" is in bytes.
 
 Note on raw_rpmb_size_mult:
+
 	"raw_rpmb_size_mult" is a multiple of 128kB block.
+
 	RPMB size in byte is calculated by using the following equation:
-	RPMB partition size = 128kB x raw_rpmb_size_mult
+
+		RPMB partition size = 128kB x raw_rpmb_size_mult
diff --git a/Documentation/mmc/mmc-dev-parts.txt b/Documentation/mmc/mmc-dev-parts.rst
similarity index 83%
rename from Documentation/mmc/mmc-dev-parts.txt
rename to Documentation/mmc/mmc-dev-parts.rst
index f08d078d43cf..995922f1f744 100644
--- a/Documentation/mmc/mmc-dev-parts.txt
+++ b/Documentation/mmc/mmc-dev-parts.rst
@@ -1,3 +1,4 @@
+============================
 SD and MMC Device Partitions
 ============================
 
@@ -18,18 +19,18 @@ platform, write access is disabled by default to reduce the chance of
 accidental bricking.
 
 To enable write access to /dev/mmcblkXbootY, disable the forced read-only
-access with:
+access with::
 
-echo 0 > /sys/block/mmcblkXbootY/force_ro
+	echo 0 > /sys/block/mmcblkXbootY/force_ro
 
-To re-enable read-only access:
+To re-enable read-only access::
 
-echo 1 > /sys/block/mmcblkXbootY/force_ro
+	echo 1 > /sys/block/mmcblkXbootY/force_ro
 
 The boot partitions can also be locked read only until the next power on,
-with:
+with::
 
-echo 1 > /sys/block/mmcblkXbootY/ro_lock_until_next_power_on
+	echo 1 > /sys/block/mmcblkXbootY/ro_lock_until_next_power_on
 
 This is a feature of the card and not of the kernel. If the card does
 not support boot partition locking, the file will not exist. If the
diff --git a/Documentation/mmc/mmc-tools.txt b/Documentation/mmc/mmc-tools.rst
similarity index 92%
rename from Documentation/mmc/mmc-tools.txt
rename to Documentation/mmc/mmc-tools.rst
index 735509c165d5..54406093768b 100644
--- a/Documentation/mmc/mmc-tools.txt
+++ b/Documentation/mmc/mmc-tools.rst
@@ -1,14 +1,17 @@
+======================
 MMC tools introduction
 ======================
 
 There is one MMC test tools called mmc-utils, which is maintained by Chris Ball,
 you can find it at the below public git repository:
-http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/
+
+	http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/
 
 Functions
 =========
 
 The mmc-utils tools can do the following:
+
  - Print and parse extcsd data.
  - Determine the eMMC writeprotect status.
  - Set the eMMC writeprotect status.
-- 
2.21.0

Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir

[Mauro Carvalho Chehab]

(c/c list cleaned)

Em Wed, 19 Jun 2019 13:43:56 +0200
Peter Zijlstra <peterz@infradead.org> escreveu:

> On Tue, Jun 18, 2019 at 05:53:17PM -0300, Mauro Carvalho Chehab wrote:
> 
> >  .../{ => driver-api}/atomic_bitops.rst        |  2 -  
> 
> That's a .txt file, big fat NAK for making it an rst.

Rst is a text file. This one is parsed properly by Sphinx without
any changes.

> 
> >  .../{ => driver-api}/futex-requeue-pi.rst     |  2 -  
> 
> >  .../{ => driver-api}/gcc-plugins.rst          |  2 -  
> 
> >  Documentation/{ => driver-api}/kprobes.rst    |  2 -
> >  .../{ => driver-api}/percpu-rw-semaphore.rst  |  2 -  
> 
> More NAK for rst conversion

Again, those don't need any conversion. Those files already parse 
as-is by Sphinx, with no need for any change.

The only change here is that, on patch 1/22, the files that
aren't listed on an index file got a :orphan: added in order
to make this explicit. This patch removes it.

> 
> >  Documentation/{ => driver-api}/pi-futex.rst   |  2 -
> >  .../{ => driver-api}/preempt-locking.rst      |  2 -  
> 
> >  Documentation/{ => driver-api}/rbtree.rst     |  2 -  
> 
> >  .../{ => driver-api}/robust-futex-ABI.rst     |  2 -
> >  .../{ => driver-api}/robust-futexes.rst       |  2 -  
> 
> >  .../{ => driver-api}/speculation.rst          |  8 +--
> >  .../{ => driver-api}/static-keys.rst          |  2 -  
> 
> >  .../{ => driver-api}/this_cpu_ops.rst         |  2 -  
> 
> >  Documentation/locking/rt-mutex.rst            |  2 +-  
> 
> NAK. None of the above have anything to do with driver-api.

Ok. Where do you think they should sit instead? core-api?

Thanks,
Mauro

Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir

[Peter Zijlstra]

On Wed, Jun 19, 2019 at 10:19:22AM -0300, Mauro Carvalho Chehab wrote:
> (c/c list cleaned)
> 
> Em Wed, 19 Jun 2019 13:43:56 +0200
> Peter Zijlstra <peterz@infradead.org> escreveu:
> 
> > On Tue, Jun 18, 2019 at 05:53:17PM -0300, Mauro Carvalho Chehab wrote:
> > 
> > >  .../{ => driver-api}/atomic_bitops.rst        |  2 -  
> > 
> > That's a .txt file, big fat NAK for making it an rst.
> 
> Rst is a text file. This one is parsed properly by Sphinx without
> any changes.

In my tree it is a .txt file, I've not seen patches changing it. And I
disagree, rst is just as much 'a text file' as .c is.

> > >  .../{ => driver-api}/futex-requeue-pi.rst     |  2 -  
> > 
> > >  .../{ => driver-api}/gcc-plugins.rst          |  2 -  
> > 
> > >  Documentation/{ => driver-api}/kprobes.rst    |  2 -
> > >  .../{ => driver-api}/percpu-rw-semaphore.rst  |  2 -  
> > 
> > More NAK for rst conversion
> 
> Again, those don't need any conversion. Those files already parse 
> as-is by Sphinx, with no need for any change.

And yet, they're a .txt file in my tree. And I've not seen a rename,
just this move.

> The only change here is that, on patch 1/22, the files that
> aren't listed on an index file got a :orphan: added in order
> to make this explicit. This patch removes it.

I've no idea what :orphan: is. Text file don't have markup.

> > >  Documentation/{ => driver-api}/pi-futex.rst   |  2 -
> > >  .../{ => driver-api}/preempt-locking.rst      |  2 -  
> > 
> > >  Documentation/{ => driver-api}/rbtree.rst     |  2 -  
> > 
> > >  .../{ => driver-api}/robust-futex-ABI.rst     |  2 -
> > >  .../{ => driver-api}/robust-futexes.rst       |  2 -  
> > 
> > >  .../{ => driver-api}/speculation.rst          |  8 +--
> > >  .../{ => driver-api}/static-keys.rst          |  2 -  
> > 
> > >  .../{ => driver-api}/this_cpu_ops.rst         |  2 -  
> > 
> > >  Documentation/locking/rt-mutex.rst            |  2 +-  
> > 
> > NAK. None of the above have anything to do with driver-api.
> 
> Ok. Where do you think they should sit instead? core-api?

Pretty much all of then are core-api I tihnk, with exception of the one
that are ABI, which have nothing to do with API. And i've no idea where
GCC plugins go, but it's definitely nothing to do with drivers.

Many of the futex ones are about the sys_futex user API, which
apparently we have Documentation/userspace-api/ for.

Why are you doing this if you've no clue what they're on about?

Just randomly moving files about isn't helpful.

Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir

[Mauro Carvalho Chehab]

Em Wed, 19 Jun 2019 23:27:53 +0200
Peter Zijlstra <peterz@infradead.org> escreveu:

> On Wed, Jun 19, 2019 at 10:19:22AM -0300, Mauro Carvalho Chehab wrote:
> > (c/c list cleaned)
> > 
> > Em Wed, 19 Jun 2019 13:43:56 +0200
> > Peter Zijlstra <peterz@infradead.org> escreveu:
> >   
> > > On Tue, Jun 18, 2019 at 05:53:17PM -0300, Mauro Carvalho Chehab wrote:
> > >   
> > > >  .../{ => driver-api}/atomic_bitops.rst        |  2 -    
> > > 
> > > That's a .txt file, big fat NAK for making it an rst.  
> > 
> > Rst is a text file. This one is parsed properly by Sphinx without
> > any changes.  
> 
> In my tree it is a .txt file, I've not seen patches changing it. And I
> disagree, rst is just as much 'a text file' as .c is.

ReStructured text is just text with a stricter style + some commands,
if the text author wants to enhance it.

Btw, I'm glad you mentioned c. 

This is c:

	int
	func( int a, int
			 b ) {
	 return a + b;
	}

This is also c:

	func(int a,int b) { goto foo;
	foo:
	   return(a+b) }

K&R style is also c, and this is also c:

	#define f(a,b) (a+b)

Despite none of the above matches my taste - and some have issues - they
all build with gcc.

Yet, none of the above follows the Kernel coding style.

The way we use ReST (with absolute minimal changes), it becomes just
a text style.

Btw, I agree with you: there are some odd things at its style - and we 
should work to try to reduce this to its minimal extent.

> 
> > > >  .../{ => driver-api}/futex-requeue-pi.rst     |  2 -    
> > >   
> > > >  .../{ => driver-api}/gcc-plugins.rst          |  2 -    
> > >   
> > > >  Documentation/{ => driver-api}/kprobes.rst    |  2 -
> > > >  .../{ => driver-api}/percpu-rw-semaphore.rst  |  2 -    
> > > 
> > > More NAK for rst conversion  
> > 
> > Again, those don't need any conversion. Those files already parse 
> > as-is by Sphinx, with no need for any change.  
> 
> And yet, they're a .txt file in my tree. And I've not seen a rename,
> just this move.

Rename is on patch 1/22.

No matter the extension, all the above files pass at the Sphinx style
validation without warnings or errors. Patch 1/22 doesn't make any
conversion.

Btw, the .rst extension is just a convenient way to help identifying what
was not validated. If I'm not mistaken, when the discussions about a
replacement for DocBook started at at linux-doc, someone proposed to
keep the .txt extension (changing it to accept .rst, .txt or both is
a single line change at conf.py).

> 
> > The only change here is that, on patch 1/22, the files that
> > aren't listed on an index file got a :orphan: added in order
> > to make this explicit. This patch removes it.  
> 
> I've no idea what :orphan: is. Text file don't have markup.
> 
> > > >  Documentation/{ => driver-api}/pi-futex.rst   |  2 -
> > > >  .../{ => driver-api}/preempt-locking.rst      |  2 -    
> > >   
> > > >  Documentation/{ => driver-api}/rbtree.rst     |  2 -    
> > >   
> > > >  .../{ => driver-api}/robust-futex-ABI.rst     |  2 -
> > > >  .../{ => driver-api}/robust-futexes.rst       |  2 -    
> > >   
> > > >  .../{ => driver-api}/speculation.rst          |  8 +--
> > > >  .../{ => driver-api}/static-keys.rst          |  2 -    
> > >   
> > > >  .../{ => driver-api}/this_cpu_ops.rst         |  2 -    
> > >   
> > > >  Documentation/locking/rt-mutex.rst            |  2 +-    
> > > 
> > > NAK. None of the above have anything to do with driver-api.  
> > 
> > Ok. Where do you think they should sit instead? core-api?  
> 
> Pretty much all of then are core-api I tihnk, with exception of the one
> that are ABI, which have nothing to do with API. 

OK.

> And i've no idea where
> GCC plugins go, but it's definitely nothing to do with drivers.

I suspect that Documentation/security would be a better place
for GCC plugins (as it has been discussed at kernel-hardening ML),
but I'm waiting a feedback from Kees.

> 
> Many of the futex ones are about the sys_futex user API, which
> apparently we have Documentation/userspace-api/ for.

Yeah, it makes sense to place sys_futex there.

Despite being an old dir, it is not too popular: there are
very few document there. I only discovered this one a few
days ago.

> 
> Why are you doing this if you've no clue what they're on about?

I don't pretend to know precisely where each document will fit.
If you read carefully the content of each orphaned document, you'll see
that many of them have uAPI, kAPI and admin-guide info inside.

To be frank, I actually tried to get rid of this document shift
part, but a Jon's feedback when I submitted a much simpler RFC
patchset challenged me to try to place each document on some place. The 
renaming part is by far a lot more complex than the conversion, 
because depending on how you interpret the file contents -
and the description of each documentation chapter - it may fit on a
different subdir.

-

My main goal is to have an organized body with the documentation. 

Try to read our docs as if it is a book, and you'll see what I'm talking
about: there are important missing parts, the document order isn't in
an order that would make easier for the headers, several documents are
placed on random places, etc.

Just like we have Makefiles, the index.rst files, plus the subdirectories
help to classify and organize the documentation on a coherent way.

- 

The main problem I want to address with this particular patch is that 
there are so many random documents from all sorts of subject at
Documentation/*.txt that it makes really hard to see the document
structure or to organize them.

Also, keeping txt files there at the root doc dir is a bad idea, as 
people keep flooding Documentation/ root with new unclassified documents
on almost every Kernel version.

After 5.1, there are two new documents added inside Documentation/*.txt
(I guess both added at linux-next for 5.3).

I proposed a few months ago to create a Documentation/staging, and do:

	mv Documentation/*.txt Documentation/*.rst Documentation/staging 

Jani proposed today something similar to it (Documentation/attic)

The name is not important. Having a place were we can temporarily
place documents while we organize the directory structure and the
documentation indexes seem to be the best way to reorganize the
docs on a coherent way.

Thanks,
Mauro

Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir

[Mauro Carvalho Chehab]

Em Wed, 19 Jun 2019 12:42:39 +0200
Peter Zijlstra <peterz@infradead.org> escreveu:

(reduced the C/C to just the relevant ML/people)

> On Wed, Jun 19, 2019 at 07:22:18AM -0300, Mauro Carvalho Chehab wrote:
> > Hi Daniel,
> > 
> > Em Wed, 19 Jun 2019 11:05:57 +0200
> > Daniel Vetter <daniel@ffwll.ch> escreveu:
> >   
> > > On Tue, Jun 18, 2019 at 10:55 PM Mauro Carvalho Chehab
> > > <mchehab+samsung@kernel.org> wrote:  
> > > > diff --git a/Documentation/gpu/drm-mm.rst b/Documentation/gpu/drm-mm.rst
> > > > index fa30dfcfc3c8..b0f948d8733b 100644
> > > > --- a/Documentation/gpu/drm-mm.rst
> > > > +++ b/Documentation/gpu/drm-mm.rst
> > > > @@ -320,7 +320,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.rst
> > > > +Documentation/driver-api/nommu-mmap.rst    
> > > 
> > > Random drive-by comment: Could we convert these into hyperlinks within
> > > sphinx somehow, without making them less useful as raw file references
> > > (with vim I can just type 'gf' and it works, emacs probably the same).
> > > -Daniel  
> > 
> > Short answer: I don't know how vim/emacs would recognize Sphinx tags.  
> 
> No, the other way around, Sphinx can recognize local files and treat
> them special. That way we keep the text readable.
> 
> Same with that :c:func:'foo' crap, that needs to die, and Sphinx needs
> to be taught about foo().

Just did a test today with Jon's extension with is meant to replace
:c:func:'foo' (with is currently on a separate 'automarkup' branch).
At least the version therestill needs some work, as it currently 
mangles with titles and tables. like on those warnings/errors:

	6.4 :c:func:`resync_start()`, :c:func:`resync_finish()`
	-----------------------------------
	/devel/v4l/docs/Documentation/driver-api/md/md-cluster.rst:323: WARNING: Title underline too short.


	/devel/v4l/docs/Documentation/driver-api/serial/tty.rst:74: WARNING: Malformed table.
	Text in column margin in table line 34.

	======================= =======================================================
	:c:func:`open()`                        Called when the line discipline is attached to

-

That's said, once it gets fixed to address those complex cases, a
regex like:

	\bDocumentation/([\w\d\-\_\/]+)\.rst\b

could be used to convert to :doc: tag. It should be smart enough to convert
the relative paths, as we refer to the files from the git root directory
(with makes a lot sense to me), while Sphinx :doc: use relative patches
from the location where the parsed file is.

Something like the enclosed patch. 

Thanks,
Mauro

[PATCH] automarkup.py: convert Documentation/* to hyperlinks

Auto-create hyperlinks when it finds a Documentation/.. occurrence.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index 39c8f4d5af82..9d6926b61241 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -9,6 +9,7 @@
 from __future__ import print_function
 import re
 import sphinx
+#import sys		# Just for debug
 
 #
 # Regex nastiness.  Of course.
@@ -31,10 +32,26 @@ RE_literal = re.compile(r'^(\s*)(.*::\s*|\.\.\s+code-block::.*)$')
 #
 RE_whitesp = re.compile(r'^(\s*)')
 
+#
+# Get a documentation reference
+#
+RE_doc_links = re.compile(r'\bDocumentation/([\w\d\-\_\/]+)\.rst\b')
+
+#
+# Doc link false-positives
+#
+RE_false_doc_links = re.compile(r':ref:`\s*Documentation/[\w\d\-\_\/]+\.rst')
+
 def MangleFile(app, docname, text):
     ret = [ ]
     previous = ''
     literal = False
+
+    rel_dir = ''
+
+    for depth in range(0, docname.count('/')):
+        rel_dir += "../"
+
     for line in text[0].split('\n'):
         #
         # See if we might be ending a literal block, as denoted by
@@ -63,7 +80,17 @@ def MangleFile(app, docname, text):
         # Normal line - perform substitutions.
         #
         else:
-            ret.append(RE_function.sub(r'\1:c:func:`\2`\3', line))
+            new_line = RE_function.sub(r'\1:c:func:`\2`\3', line)
+
+            if not RE_false_doc_links.search(new_line):
+                new_line = RE_doc_links.sub(r':doc:`' + rel_dir + r'\1`', new_line)
+
+ #           # Just for debug - should be removed on production
+ #           if new_line != line:
+ #               print ("===>" + new_line, file=sys.stderr)
+
+            ret.append(new_line)
+
         #
         # Might we be starting a literal block?  If so make note of
         # the fact.

Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir

[Mauro Carvalho Chehab]

Hi Jon,

Em Wed, 19 Jun 2019 08:13:53 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Wed, 19 Jun 2019 12:42:39 +0200
> Peter Zijlstra <peterz@infradead.org> wrote:
> 
> > No, the other way around, Sphinx can recognize local files and treat
> > them special. That way we keep the text readable.
> > 
> > Same with that :c:func:'foo' crap, that needs to die, and Sphinx needs
> > to be taught about foo().  
> 
> I did a patch to make that latter part happen, but haven't been able to
> find the time to address the comments and get it out there.  It definitely
> cleaned up the source files a lot and is worth doing.  Will try to get
> back to it soon.

See my comment. Yeah, the :c:func:'foo' (the version you merged at the automarkup
branch) has currently a bug, when there's something like:

	func()
	======

or when func() is inside a table.

Solving the table case would be a lot better if the plugin could run the
existing table parser and only then handle the cross-reference replacements,
but I've no idea how flexible the Sphinx plugins can be.

> 
> The local file links should be easy to do; we shouldn't need to add any
> markup for those.

Yeah, those are easy - except if someone adds a Documentation/* link 
inside a table or inside a topic header.

Running a modified version of your tool shows just two new warnings:

	Documentation/translations/ja_JP/howto.rst:176: WARNING: undefined label: :doc: (if the link has no caption the label must precede a section header)         
	Documentation/translations/zh_CN/process/submitting-drivers.rst:25: WARNING: unknown document: ../../../Documentation/translations/zh_CN/process/submitting-patches

The first one is because of this:

	:Ref:`Documentation/process/kernel-docs.rst <kernel_docs>`

(my parser didn't consider upper-case tags - a simple fix at a regex should
fix this)

The second one is because the URL is wrong. It is pointing to:

	Documentation/Documentation/translations/zh_CN/process/submitting-patches

at Chinese translation.

So, at least the way our documentation is, the plugin seems to be working
as expected.

As a reference, I'm enclosing the diff against your patch:

    commit 6231d7456e87bd3e11f892709945887bd55a8a20 (docs/automarkup)
    Author: Jonathan Corbet <corbet@lwn.net>
    Date:   Thu Apr 25 07:55:07 2019 -0600

        Docs: An initial automarkup extension for sphinx
    
        Rather than fill our text files with :c:func:`function()` syntax, just do
        the markup via a hook into the sphinx build process.  As is always the
        case, the real problem is detecting the situations where this markup should
        *not* be done.
    
        Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Thanks,
Mauro

-

diff --git a/Documentation/sphinx/automarkup.py b/Documentation/sphinx/automarkup.py
index 39c8f4d5af82..60dad596c790 100644
--- a/Documentation/sphinx/automarkup.py
+++ b/Documentation/sphinx/automarkup.py
@@ -9,6 +9,7 @@
 from __future__ import print_function
 import re
 import sphinx
+#import sys		# Just for debug
 
 #
 # Regex nastiness.  Of course.
@@ -31,10 +32,26 @@ RE_literal = re.compile(r'^(\s*)(.*::\s*|\.\.\s+code-block::.*)$')
 #
 RE_whitesp = re.compile(r'^(\s*)')
 
+#
+# Get a documentation reference
+#
+RE_doc_links = re.compile(r'\bDocumentation/([\w\d\-\_\/]+)\.rst\b')
+
+#
+# Doc link false-positives
+#
+RE_false_doc_links = re.compile(r':ref:`\s*Documentation/[\w\d\-\_\/]+\.rst')
+
 def MangleFile(app, docname, text):
     ret = [ ]
     previous = ''
     literal = False
+
+    rel_dir = ''
+
+    for depth in range(0, docname.count('/')):
+        rel_dir += "../"
+
     for line in text[0].split('\n'):
         #
         # See if we might be ending a literal block, as denoted by
@@ -63,7 +80,18 @@ def MangleFile(app, docname, text):
         # Normal line - perform substitutions.
         #
         else:
-            ret.append(RE_function.sub(r'\1:c:func:`\2`\3', line))
+#            new_line = RE_function.sub(r'\1:c:func:`\2`\3', line)
+            new_line = line
+
+            if not RE_false_doc_links.search(new_line):
+                new_line = RE_doc_links.sub(r':doc:`' + rel_dir + r'\1`', new_line)
+
+ #           # Just for debug - should be removed on production
+ #           if new_line != line:
+ #               print ("===>" + new_line, file=sys.stderr)
+
+            ret.append(new_line)
+
         #
         # Might we be starting a literal block?  If so make note of
         # the fact.

Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir

[David Howells]

Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> > > -Documentation/nommu-mmap.rst
> > > +Documentation/driver-api/nommu-mmap.rst  

Why is this moving to Documentation/driver-api?  It's less to do with drivers
than with the userspace mapping interface.  Documentation/vm/ would seem a
better home.

Or should we institute a Documentation/uapi/?  Though that might be seen to
overlap with man2.  Actually, should this be in man7?

David

Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir

[Mauro Carvalho Chehab]

Hi David,

Em Wed, 19 Jun 2019 14:39:10 +0100
David Howells <dhowells@redhat.com> escreveu:

> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> 
> > > > -Documentation/nommu-mmap.rst
> > > > +Documentation/driver-api/nommu-mmap.rst    
> 
> Why is this moving to Documentation/driver-api?  

Good point. I tried to do my best with those document renames, but
I'm pretty sure some of them ended by going to the wrong place - or
at least there are arguments in favor of moving it to different
places :-)

The driver-api ended to be where most of the stuff has been moved,
as this is the main kAPI dir (there is also a core-api dir for kAPI too).

I tend to place there stuff that has a mix of kAPI and uAPI at
driver-api, as usually such documents are written assuming that
the one that would be reading it is a Kernel developer.

> It's less to do with drivers
> than with the userspace mapping interface.  Documentation/vm/ would seem a
> better home.
> 
> Or should we institute a Documentation/uapi/?  Though that might be seen to
> overlap with man2.  Actually, should this be in man7?

Actually, there is an userspace-api dir too. While the logs show that
this was created back on 2017, I only noticed it very recently.

Re-checking the file, I see your point: there are lots of
userspace-relevant contents there. Yet, it also mentions kAPI internals,
like a reference for file and vm ops (at "Providing shareable character
device support" session):

	file->f_op->get_unmapped_area()
	file->f_op->mmap()
	vm_ops->close()

It is up to MM people and Jon to decide where to place it.

In any case, the best (long term) seems to split it on separate files, 
one with kAPI and another one with uAPI (just like may other subsystem
specific docs).

Thanks,
Mauro

Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir

[Jonathan Corbet]

[Trimming the CC list from hell made sense, but it might have been better
to leave me on it...]

On Wed, 19 Jun 2019 11:15:28 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> Em Wed, 19 Jun 2019 14:39:10 +0100
> David Howells <dhowells@redhat.com> escreveu:
> 
> > Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> >   
> > > > > -Documentation/nommu-mmap.rst
> > > > > +Documentation/driver-api/nommu-mmap.rst      
> > 
> > Why is this moving to Documentation/driver-api?    
> 
> Good point. I tried to do my best with those document renames, but
> I'm pretty sure some of them ended by going to the wrong place - or
> at least there are arguments in favor of moving it to different
> places :-)

I think that a lot of this might also be an argument for slowing down just
a little bit.  I really don't think that blasting through and reformatting
all of our text documents is the most urgent problem right now and, in
cases like this, it might create others.

Organization of the documentation tree is important; it has never really
gotten any attention so far, and we're trying to make it better.  But
moving documents will, by its nature, annoy people.  We can generally get
past that, but I'd really like to avoid moving things twice.  In general,
I would rather see a single document converted, read critically and
updated, and carefully integrated with the rest than a hundred of them
swept into different piles...

See what I'm getting at?

Thanks,

jon

Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir

[Jani Nikula]

On Wed, 19 Jun 2019, Jonathan Corbet <corbet@lwn.net> wrote:
> Organization of the documentation tree is important; it has never really
> gotten any attention so far, and we're trying to make it better.  But
> moving documents will, by its nature, annoy people.  We can generally get
> past that, but I'd really like to avoid moving things twice.  In general,
> I would rather see a single document converted, read critically and
> updated, and carefully integrated with the rest than a hundred of them
> swept into different piles...

FWIW, as a first step, my preference would actually be cleaning up the
top level Documentation/ directory. Move every file to an existing or a
new subdirectory, even if just as .txt, or just delete. I understand
this would lead to an extra rst conversion and extension change later,
which you'd like to avoid, but IMO would be helpful.

We could even add an attic directory, which would be a suitable place
for things like zorro.txt. Attic is where I'd look for my old Amiga
hardware, so feels natural.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH v1 12/22] docs: driver-api: add .rst files from the main dir

[Mauro Carvalho Chehab]

Em Wed, 19 Jun 2019 08:54:58 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> [Trimming the CC list from hell made sense, but it might have been better
> to leave me on it...]
> 
> On Wed, 19 Jun 2019 11:15:28 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> 
> > Em Wed, 19 Jun 2019 14:39:10 +0100
> > David Howells <dhowells@redhat.com> escreveu:
> >   
> > > Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> > >     
> > > > > > -Documentation/nommu-mmap.rst
> > > > > > +Documentation/driver-api/nommu-mmap.rst        
> > > 
> > > Why is this moving to Documentation/driver-api?      
> > 
> > Good point. I tried to do my best with those document renames, but
> > I'm pretty sure some of them ended by going to the wrong place - or
> > at least there are arguments in favor of moving it to different
> > places :-)  
> 
> I think that a lot of this might also be an argument for slowing down just
> a little bit.  I really don't think that blasting through and reformatting
> all of our text documents is the most urgent problem right now and, in
> cases like this, it might create others.
> 
> Organization of the documentation tree is important; it has never really
> gotten any attention so far, and we're trying to make it better.  But
> moving documents will, by its nature, annoy people.  We can generally get
> past that, but I'd really like to avoid moving things twice.  In general,
> I would rather see a single document converted, read critically and
> updated, and carefully integrated with the rest than a hundred of them
> swept into different piles...
> 
> See what I'm getting at?

I see what you mean, and I agree with this principle. That's basically 
why I split the patches into two groups. 

The first group (with comes first) does just the conversion
and renames from txt to rst, adding a :orphan: to the stuff that was
just converted.

On this series, those are patches 1 to 11. I was already expecting
some heat on patch 1.

The next group of patches do the renaming part. Those are the ones that
actually took me a lot more time, as I needed to quickly read several docs
in order to understand what's happening, before proposing a change.

That's also the group of patches were I expect more active comments,
as there are several cases where this is not obvious.

Yet, from what I saw, there are some documents that sounds easy to
move, like Documentation/laptops, with (except if I missed something)
clearly belongs to admin-guide.

Applying the second patch series and patches 2 to 11 from this third
series is, IMHO, a good thing to do.

-

IMO, patches 1 and 12 are important, as, after those patches, the
/Documentation dir becomes a lot cleaner:

	$ ls -F Documentation/
	ABI/              fb/              locking/        s390/
	accounting/       features/        logo.gif        scheduler/
	acpi/             filesystems/     logo.txt        scsi/
	admin-guide/      firmware_class/  m68k/           security/
	arm/              firmware-guide/  maintainer/     sh/
	arm64/            fpga/            Makefile        sound/
	auxdisplay/       gpio/            media/          sparc/
	block/            gpu/             mic/            sphinx/
	bpf/              hid/             mips/           sphinx-static/
	cdrom/            hwmon/           misc-devices/   spi/
	Changes@          i2c/             Module.symvers  SubmittingPatches
	CodingStyle       ia64/            netlabel/       target/
	conf.py           ide/             networking/     timers/
	core-api/         iio/             nios2/          trace/
	cpu-freq/         index.rst        openrisc/       translations/
	crypto/           infiniband/      output/         usb/
	devicetree/       input/           packing.txt     userspace-api/
	dev-tools/        ioctl/           parisc/         virtual/
	DocBook/          IPMB.txt         PCI/            vm/
	doc-guide/        isdn/            pcmcia/         w1/
	docutils.conf     kbuild/          power/          watchdog/
	dontdiff          Kconfig          powerpc/        wimax/
	driver-api/       kernel-hacking/  process/        x86/
	EDID/             leds/            RCU/            xtensa/
	fault-injection/  livepatch/       riscv/

Being easy to identify when someone tries to add a new text file there
without thinking on where it would fit[1], and to reorganize the
directory tree in a way that it will fit our needs.

[1] Btw, there are some two files at linux-next, incrementally
    increasing the Documentation/ mess:

	   IPMB.txt and packing.txt.

   Added on those commits:

	commit 51bd6f291583684f495ea498984dfc22049d7fd2
	Author: Asmaa Mnebhi <Asmaa@mellanox.com>
	Date:   Mon Jun 10 14:57:02 2019 -0400

	    Add support for IPMB driver

	commit 554aae35007e49f533d3d10e788295f7141725bc
	Author: Vladimir Oltean <olteanv@gmail.com>
	Date:   Thu May 2 23:23:29 2019 +0300

	    lib: Add support for generic packing operations

   We'll never finish organizing documents while people don't stop
   adding new files to Documentation/ directory.


Thanks,
Mauro