linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH v1 00/31] Convert files to ReST - part 2
@ 2019-06-12 18:38 Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 01/31] docs: connector: convert to ReST and rename to connector.rst Mauro Carvalho Chehab
                   ` (29 more replies)
  0 siblings, 30 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

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-20190612.

The first version of this series had 57 patches. Right now, there are ~80 
patches pending applying on this undergoing work. 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. That's the second part.

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.

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_v4.3

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/

Mauro Carvalho Chehab (31):
  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: fmc: convert to ReST
  docs: hid: 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 +-
 .../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/fmc/{API.txt => api.rst}        |  10 +-
 .../fmc/{carrier.txt => carrier.rst}          |  65 +--
 .../fmc/{FMC-and-SDB.txt => fmc-and-sdb.rst}  |  19 +-
 .../fmc/{fmc-chardev.txt => fmc-chardev.rst}  |   9 +-
 .../fmc/{fmc-fakedev.txt => fmc-fakedev.rst}  |  13 +-
 .../fmc/{fmc-trivial.txt => fmc-trivial.rst}  |  11 +-
 ...-write-eeprom.txt => fmc-write-eeprom.rst} |  36 +-
 .../fmc/{identifiers.txt => identifiers.rst}  |  20 +-
 Documentation/fmc/index.rst                   |  21 +
 .../fmc/{mezzanine.txt => mezzanine.rst}      |  34 +-
 .../fmc/{parameters.txt => parameters.rst}    |  11 +-
 .../hid/{hid-alps.txt => hid-alps.rst}        |  85 ++-
 .../hid/{hid-sensor.txt => hid-sensor.rst}    | 192 ++++---
 .../{hid-transport.txt => hid-transport.rst}  |  82 ++-
 Documentation/hid/{hiddev.txt => hiddev.rst}  | 154 ++++--
 Documentation/hid/{hidraw.txt => hidraw.rst}  |  53 +-
 Documentation/hid/index.rst                   |  18 +
 Documentation/hid/intel-ish-hid.rst           | 485 ++++++++++++++++
 Documentation/hid/intel-ish-hid.txt           | 454 ---------------
 Documentation/hid/{uhid.txt => uhid.rst}      |  46 +-
 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 +
 Documentation/input/input.rst                 |   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}  | 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                                   |  18 +-
 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 +-
 277 files changed, 8166 insertions(+), 6117 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/fmc/{API.txt => api.rst} (87%)
 rename Documentation/fmc/{carrier.txt => carrier.rst} (91%)
 rename Documentation/fmc/{FMC-and-SDB.txt => fmc-and-sdb.rst} (88%)
 rename Documentation/fmc/{fmc-chardev.txt => fmc-chardev.rst} (96%)
 rename Documentation/fmc/{fmc-fakedev.txt => fmc-fakedev.rst} (85%)
 rename Documentation/fmc/{fmc-trivial.txt => fmc-trivial.rst} (69%)
 rename Documentation/fmc/{fmc-write-eeprom.txt => fmc-write-eeprom.rst} (79%)
 rename Documentation/fmc/{identifiers.txt => identifiers.rst} (93%)
 create mode 100644 Documentation/fmc/index.rst
 rename Documentation/fmc/{mezzanine.txt => mezzanine.rst} (87%)
 rename Documentation/fmc/{parameters.txt => parameters.rst} (96%)
 rename Documentation/hid/{hid-alps.txt => hid-alps.rst} (64%)
 rename Documentation/hid/{hid-sensor.txt => hid-sensor.rst} (61%)
 rename Documentation/hid/{hid-transport.txt => hid-transport.rst} (93%)
 rename Documentation/hid/{hiddev.txt => hiddev.rst} (77%)
 rename Documentation/hid/{hidraw.txt => hidraw.rst} (89%)
 create mode 100644 Documentation/hid/index.rst
 create mode 100644 Documentation/hid/intel-ish-hid.rst
 delete mode 100644 Documentation/hid/intel-ish-hid.txt
 rename Documentation/hid/{uhid.txt => uhid.rst} (94%)
 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



^ permalink raw reply	[flat|nested] 38+ messages in thread

* [PATCH v1 01/31] docs: connector: convert to ReST and rename to connector.rst
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 02/31] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
                   ` (28 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Evgeniy Polyakov

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 02/31] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 01/31] docs: connector: convert to ReST and rename to connector.rst Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 03/31] docs: lp855x-driver.txt: convert to ReST and move to kernel-api Mauro Carvalho Chehab
                   ` (27 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

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 b0b674f5aaca..fa236f3f5979 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -11932,7 +11932,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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 03/31] docs: lp855x-driver.txt: convert to ReST and move to kernel-api
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 01/31] docs: connector: convert to ReST and rename to connector.rst Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 02/31] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 04/31] docs: m68k: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
                   ` (26 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Milo Kim

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 fa236f3f5979..28c3b926555e 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15828,7 +15828,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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 04/31] docs: m68k: convert docs to ReST and rename to *.rst
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (2 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 03/31] docs: lp855x-driver.txt: convert to ReST and move to kernel-api Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 05/31] docs: cma/debugfs.txt: " Mauro Carvalho Chehab
                   ` (25 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 05/31] docs: cma/debugfs.txt: convert docs to ReST and rename to *.rst
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (3 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 04/31] docs: m68k: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 06/31] docs: console.txt: " Mauro Carvalho Chehab
                   ` (24 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 06/31] docs: console.txt: convert docs to ReST and rename to *.rst
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (4 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 05/31] docs: cma/debugfs.txt: " Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 07/31] docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst Mauro Carvalho Chehab
                   ` (23 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Bartlomiej Zolnierkiewicz, Greg Kroah-Hartman,
	Jiri Slaby, dri-devel, linux-fbdev

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 07/31] docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (5 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 06/31] docs: console.txt: " Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 08/31] docs: early-userspace: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
                   ` (22 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 08/31] docs: early-userspace: convert docs to ReST and rename to *.rst
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (6 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 07/31] docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 09/31] docs: driver-model: " Mauro Carvalho Chehab
                   ` (21 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 09/31] docs: driver-model: convert docs to ReST and rename to *.rst
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (7 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 08/31] docs: early-userspace: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 20:21   ` Jeff Kirsher
  2019-06-12 18:38 ` [PATCH v1 11/31] docs: memory-devices: convert ti-emif.txt to ReST Mauro Carvalho Chehab
                   ` (20 subsequent siblings)
  29 siblings, 1 reply; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Linus Walleij, Bartosz Golaszewski,
	Jean Delvare, Guenter Roeck, Greg Kroah-Hartman,
	Rafael J. Wysocki, Jeff Kirsher, David S. Miller, Julia Lawall,
	Gilles Muller, Nicolas Palix, Michal Marek, linux-gpio,
	linux-hwmon, intel-wired-lan, netdev, cocci

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>
---
 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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 11/31] docs: memory-devices: convert ti-emif.txt to ReST
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (8 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 09/31] docs: driver-model: " Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 12/31] docs: xen-tpmfront.txt: convert it to .rst Mauro Carvalho Chehab
                   ` (19 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 12/31] docs: xen-tpmfront.txt: convert it to .rst
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (9 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 11/31] docs: memory-devices: convert ti-emif.txt to ReST Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 13/31] docs: bus-devices: ti-gpmc.rst: convert it to ReST Mauro Carvalho Chehab
                   ` (18 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 13/31] docs: bus-devices: ti-gpmc.rst: convert it to ReST
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (10 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 12/31] docs: xen-tpmfront.txt: convert it to .rst Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 14/31] docs: nvmem: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
                   ` (17 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 14/31] docs: nvmem: convert docs to ReST and rename to *.rst
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (11 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 13/31] docs: bus-devices: ti-gpmc.rst: convert it to ReST Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 15/31] docs: phy: convert samsung-usb2.txt to ReST format Mauro Carvalho Chehab
                   ` (16 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 15/31] docs: phy: convert samsung-usb2.txt to ReST format
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (12 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 14/31] docs: nvmem: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 16/31] docs: rbtree.txt: fix Sphinx build warnings Mauro Carvalho Chehab
                   ` (15 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Kamil Debski, Sylwester Nawrocki

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 62a6771e261f..8d39979e4091 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -13963,7 +13963,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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 16/31] docs: rbtree.txt: fix Sphinx build warnings
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (13 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 15/31] docs: phy: convert samsung-usb2.txt to ReST format Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 17/31] docs: DMA-API-HOWTO.txt: fix an unmarked code block Mauro Carvalho Chehab
                   ` (14 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 17/31] docs: DMA-API-HOWTO.txt: fix an unmarked code block
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (14 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 16/31] docs: rbtree.txt: fix Sphinx build warnings Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 18/31] docs: accounting: convert to ReST Mauro Carvalho Chehab
                   ` (13 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 18/31] docs: accounting: convert to ReST
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (15 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 17/31] docs: DMA-API-HOWTO.txt: fix an unmarked code block Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 19/31] docs: fmc: " Mauro Carvalho Chehab
                   ` (12 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Balbir Singh, Tejun Heo, Li Zefan,
	Johannes Weiner, cgroups

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 19/31] docs: fmc: convert to ReST
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (16 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 18/31] docs: accounting: convert to ReST Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 20/31] docs: hid: " Mauro Carvalho Chehab
                   ` (11 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

Rename the FMC 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 least some of this files seemed to be using some markup
language similar to ReST, but with a different markup for
cross-references. Adjust those to use the ReST syntax.

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/fmc/{API.txt => api.rst}        | 10 +--
 .../fmc/{carrier.txt => carrier.rst}          | 65 ++++++++++---------
 .../fmc/{FMC-and-SDB.txt => fmc-and-sdb.rst}  | 19 ++++--
 .../fmc/{fmc-chardev.txt => fmc-chardev.rst}  |  9 +--
 .../fmc/{fmc-fakedev.txt => fmc-fakedev.rst}  | 13 ++--
 .../fmc/{fmc-trivial.txt => fmc-trivial.rst}  | 11 ++--
 ...-write-eeprom.txt => fmc-write-eeprom.rst} | 36 +++++-----
 .../fmc/{identifiers.txt => identifiers.rst}  | 20 +++---
 Documentation/fmc/index.rst                   | 21 ++++++
 .../fmc/{mezzanine.txt => mezzanine.rst}      | 34 +++++-----
 .../fmc/{parameters.txt => parameters.rst}    | 11 ++--
 11 files changed, 147 insertions(+), 102 deletions(-)
 rename Documentation/fmc/{API.txt => api.rst} (87%)
 rename Documentation/fmc/{carrier.txt => carrier.rst} (91%)
 rename Documentation/fmc/{FMC-and-SDB.txt => fmc-and-sdb.rst} (88%)
 rename Documentation/fmc/{fmc-chardev.txt => fmc-chardev.rst} (96%)
 rename Documentation/fmc/{fmc-fakedev.txt => fmc-fakedev.rst} (85%)
 rename Documentation/fmc/{fmc-trivial.txt => fmc-trivial.rst} (69%)
 rename Documentation/fmc/{fmc-write-eeprom.txt => fmc-write-eeprom.rst} (79%)
 rename Documentation/fmc/{identifiers.txt => identifiers.rst} (93%)
 create mode 100644 Documentation/fmc/index.rst
 rename Documentation/fmc/{mezzanine.txt => mezzanine.rst} (87%)
 rename Documentation/fmc/{parameters.txt => parameters.rst} (96%)

diff --git a/Documentation/fmc/API.txt b/Documentation/fmc/api.rst
similarity index 87%
rename from Documentation/fmc/API.txt
rename to Documentation/fmc/api.rst
index 06b06b92c794..157a7343180c 100644
--- a/Documentation/fmc/API.txt
+++ b/Documentation/fmc/api.rst
@@ -2,7 +2,7 @@ Functions Exported by fmc.ko
 ****************************
 
 The FMC core exports the usual 4 functions that are needed for a bus to
-work, and a few more:
+work, and a few more::
 
         int fmc_driver_register(struct fmc_driver *drv);
         void fmc_driver_unregister(struct fmc_driver *drv);
@@ -20,9 +20,9 @@ work, and a few more:
         int fmc_reprogram(struct fmc_device *f, struct fmc_driver *d, char *gw,
                           int sdb_entry);
 
-The data structure that describe a device is detailed in *note FMC
-Device::, the one that describes a driver is detailed in *note FMC
-Driver::.  Please note that structures of type fmc_device must be
+The data structure that describe a device is detailed in :ref:`fmc_device`,
+the one that describes a driver is detailed in :ref:`fmc_driver`.
+Please note that structures of type fmc_device must be
 allocated by the caller, but must not be released after unregistering.
 The fmc-bus itself takes care of releasing the structure when their use
 count reaches zero - actually, the device model does that in lieu of us.
@@ -39,7 +39,7 @@ should register as a group only mezzanines that are driven by the same
 FPGA, for the reason outlined above.
 
 Finally, the fmc_reprogram function calls the reprogram method (see
-*note The API Offered by Carriers:: and also scans the memory area for
+:ref:`fmc_api_offered_by_carriers`) and also scans the memory area for
 an SDB tree. You can pass -1 as sdb_entry to disable such scan.
 Otherwise, the function fails if no tree is found at the specified
 entry point.  The function is meant to factorize common code, and by
diff --git a/Documentation/fmc/carrier.txt b/Documentation/fmc/carrier.rst
similarity index 91%
rename from Documentation/fmc/carrier.txt
rename to Documentation/fmc/carrier.rst
index 5e4f1dd3e98b..06ba443441e1 100644
--- a/Documentation/fmc/carrier.txt
+++ b/Documentation/fmc/carrier.rst
@@ -1,5 +1,8 @@
+.. _fmc_device:
+
+==========
 FMC Device
-**********
+==========
 
 Within the Linux bus framework, the FMC device is created and
 registered by the carrier driver. For example, the PCI driver for the
@@ -25,7 +28,7 @@ change for compatible changes (like a new flag) and the major number
 will increase when an incompatible change happens (for example, a
 change in layout of some fmc data structures).  Device writers should
 just set it to the value FMC_VERSION, and be ready to get back -EINVAL
-at registration time.
+at registration time::
 
      struct fmc_device {
              unsigned long version;
@@ -123,13 +126,15 @@ As I write this, she SPEC carrier is already completely functional in
 the fmc-bus environment, and is a good reference to look at.
 
 
+.. _fmc_api_offered_by_carriers:
+
 The API Offered by Carriers
 ===========================
 
 The carrier provides a number of methods by means of the
-`fmc_operations' structure, which currently is defined like this
+`fmc_operations` structure, which currently is defined like this
 (again, it is a moving target, please refer to the header rather than
-this document):
+this document)::
 
      struct fmc_operations {
              uint32_t (*readl)(struct fmc_device *fmc, int offset);
@@ -148,8 +153,7 @@ this document):
 
 The individual methods perform the following tasks:
 
-`readl'
-`writel'
+`readl`, `writel`
      These functions access FPGA registers by whatever means the
      carrier offers. They are not expected to fail, and most of the time
      they will just make a memory access to the host bus. If the
@@ -161,20 +165,20 @@ The individual methods perform the following tasks:
      or other non-local carriers, error-management is still to be
      defined.
 
-`validate'
+`validate`
      Module parameters are used to manage different applications for
      two or more boards of the same kind. Validation is based on the
      busid module parameter, if provided, and returns the matching
-     index in the associated array. See *note Module Parameters:: in in
-     doubt. If no match is found, `-ENOENT' is returned; if the user
-     didn't pass `busid=', all devices will pass validation.  The value
+     index in the associated array. See :ref:`fmc_module_parameters` in in
+     doubt. If no match is found, `-ENOENT` is returned; if the user
+     didn't pass `busid=`, all devices will pass validation.  The value
      returned by the validate method can be used as index into other
-     parameters (for example, some drivers use the `lm32=' parameter in
-     this way). Such "generic parameters" are documented in *note
-     Module Parameters::, below. The validate method is used by
-     `fmc-trivial.ko', described in *note fmc-trivial::.
+     parameters (for example, some drivers use the `lm32=` parameter in
+     this way). Such "generic parameters" are documented in
+     :ref:`fmc_module_parameters` below. The validate method is used by
+     `fmc-trivial.ko`, described in :ref:`fmc_trivial`.
 
-`reprogram'
+`reprogram`
      The carrier enumerates FMC devices by loading a standard (or
      golden) FPGA binary that allows EEPROM access. Each driver, then,
      will need to reprogram the FPGA by calling this function.  If the
@@ -182,31 +186,28 @@ The individual methods perform the following tasks:
      binary. If the gateware name has been overridden through module
      parameters (in a carrier-specific way) the file loaded will match
      the parameters. Per-device gateware names can be specified using
-     the `gateware=' parameter, see *note Module Parameters::.  Note:
+     the `gateware=` parameter, see :ref:`fmc_module_parameters`.  Note:
      Clients should call rhe new helper, fmc_reprogram, which both
      calls this method and parse the SDB tree of the FPGA.
 
-`irq_request'
-`irq_ack'
-`irq_free'
+`irq_request`, `irq_ack`, `irq_free`
      Interrupt management is carrier-specific, so it is abstracted as
      operations. The interrupt number is listed in the device
      structure, and for the mezzanine driver the number is only
      informative.  The handler will receive the fmc pointer as dev_id;
      the flags argument is passed to the Linux request_irq function,
      but fmc-specific flags may be added in the future. You'll most
-     likely want to pass the `IRQF_SHARED' flag.
+     likely want to pass the `IRQF_SHARED` flag.
 
-`gpio_config'
+`gpio_config`
      The method allows to configure a GPIO pin in the carrier, and read
-     its current value if it is configured as input. See *note The GPIO
-     Abstraction:: for details.
+     its current value if it is configured as input. See
+     :ref:`fmc_gpio_abstraction` for details.
 
-`read_ee'
-`write_ee'
+`read_ee`, `write_ee`
      Read or write the EEPROM. The functions are expected to be only
      called before reprogramming and the carrier should refuse them
-     with `ENODEV' after reprogramming.  The offset is expected to be
+     with `ENODEV` after reprogramming.  The offset is expected to be
      within 8kB (the current size), but addresses up to 1MB are
      reserved to fit bigger I2C devices in the future. Carriers may
      offer access to other internal flash memories using these same
@@ -214,9 +215,9 @@ The individual methods perform the following tasks:
      I2C memory is seen at offset 1M and the internal SPI flash is seen
      at offset 16M.  This multiplexing of several flash memories in the
      same address space is carrier-specific and should only be used
-     by a driver that has verified the `carrier_name' field.
-
+     by a driver that has verified the `carrier_name` field.
 
+.. _fmc_gpio_abstraction:
 
 The GPIO Abstraction
 ====================
@@ -230,7 +231,7 @@ some knowledge of the carrier itself.  For this reason, the specific
 driver can request to configure carrier-specific GPIO pins, numbered
 from 0 to at most 4095.  Configuration is performed by passing a
 pointer to an array of struct fmc_gpio items, as well as the length of
-the array. This is the data structure:
+the array. This is the data structure::
 
         struct fmc_gpio {
                 char *carrier_name;
@@ -254,7 +255,7 @@ pins, and expect one such configuration to succeed - if none succeeds
 it most likely means that the current carrier is a still-unknown one.
 
 If, however, your GPIO pin has a specific known role, you can pass a
-special number in the gpio field, using one of the following macros:
+special number in the gpio field, using one of the following macros::
 
         #define FMC_GPIO_RAW(x)         (x)             /* 4096 of them */
         #define FMC_GPIO_IRQ(x)         ((x) + 0x1000)  /*  256 of them */
@@ -293,9 +294,9 @@ carriers.
 
 The return value of gpio_config is defined as follows:
 
-   * If no pin in the array can be used by the carrier, `-ENODEV'.
+   * If no pin in the array can be used by the carrier, `-ENODEV`.
 
-   * If at least one virtual GPIO number cannot be mapped, `-ENOENT'.
+   * If at least one virtual GPIO number cannot be mapped, `-ENOENT`.
 
    * On success, 0 or positive. The value returned is the number of
      high input bits (if no input is configured, the value for success
diff --git a/Documentation/fmc/FMC-and-SDB.txt b/Documentation/fmc/fmc-and-sdb.rst
similarity index 88%
rename from Documentation/fmc/FMC-and-SDB.txt
rename to Documentation/fmc/fmc-and-sdb.rst
index fa14e0b24521..e64c6104a241 100644
--- a/Documentation/fmc/FMC-and-SDB.txt
+++ b/Documentation/fmc/fmc-and-sdb.rst
@@ -1,3 +1,6 @@
+============
+Introduction
+============
 
 FMC (FPGA Mezzanine Card) is the standard we use for our I/O devices,
 in the context of White Rabbit and related hardware.
@@ -18,12 +21,12 @@ submodule.
 The most up to date version of code and documentation is always
 available from the repository you can clone from:
 
-        git://ohwr.org/fmc-projects/fmc-bus.git (read-only)
-        git@ohwr.org:fmc-projects/fmc-bus.git (read-write for developers)
+        - git://ohwr.org/fmc-projects/fmc-bus.git (read-only)
+        - git@ohwr.org:fmc-projects/fmc-bus.git (read-write for developers)
 
 Selected versions of the documentation, as well as complete tar
 archives for selected revisions are placed to the Files section of the
-project: `http://www.ohwr.org/projects/fmc-bus/files'
+project: `http://www.ohwr.org/projects/fmc-bus/files`
 
 
 What is FMC
@@ -62,13 +65,15 @@ a filesystem inside the FMC EEPROM.
 SDB is not mandatory for use of this FMC kernel bus, but if you have SDB
 this package can make good use of it.  SDB itself is developed in the
 fpga-config-space OHWR project. The link to the repository is
-`git://ohwr.org/hdl-core-lib/fpga-config-space.git' and what is used in
+`git://ohwr.org/hdl-core-lib/fpga-config-space.git` and what is used in
 this project lives in the sdbfs subdirectory in there.
 
-SDB support for FMC is described in *note FMC Identification:: and
-*note SDB Support::
+SDB support for FMC is described in :ref:`fmc_identification` and
+:ref:`fmc_sdb_support`.
 
 
+.. _fmc_sdb_support:
+
 SDB Support
 ***********
 
@@ -79,7 +84,7 @@ memory image.
 The module exports the following functions, in the special header
 <linux/fmc-sdb.h>. The linux/ prefix in the name is there because we
 plan to submit it upstream in the future, and don't want to force
-changes on our drivers if that happens.
+changes on our drivers if that happens::
 
          int fmc_scan_sdb_tree(struct fmc_device *fmc, unsigned long address);
          void fmc_show_sdb_tree(struct fmc_device *fmc);
diff --git a/Documentation/fmc/fmc-chardev.txt b/Documentation/fmc/fmc-chardev.rst
similarity index 96%
rename from Documentation/fmc/fmc-chardev.txt
rename to Documentation/fmc/fmc-chardev.rst
index d9ccb278e597..5aa77511e4d1 100644
--- a/Documentation/fmc/fmc-chardev.txt
+++ b/Documentation/fmc/fmc-chardev.rst
@@ -1,5 +1,6 @@
-fmc-chardev
-===========
+================
+Character device
+================
 
 This is a simple generic driver, that allows user access by means of a
 character device (actually, one for each mezzanine it takes hold of).
@@ -27,7 +28,7 @@ arises.
 The example below shows raw access to a SPEC card programmed with its
 golden FPGA file, that features an SDB structure at offset 256 - i.e.
 64 words.  The mezzanine's EEPROM in this case is not programmed, so the
-default name is fmc-<bus><devfn>, and there are two cards in the system:
+default name is fmc-<bus><devfn>, and there are two cards in the system::
 
   spusa.root# insmod fmc-chardev.ko
   [ 1073.339332] spec 0000:02:00.0: Driver has no ID: matches all
@@ -52,7 +53,7 @@ repeated reading data is written to stdout; repeated writes read from
 stdin and the value argument is ignored.
 
 The following examples show reading the SDB magic number and the first
-SDB record from a SPEC device programmed with its golden image:
+SDB record from a SPEC device programmed with its golden image::
 
      spusa.root# ./fmc-mem /dev/fmc-0200 100
      5344422d
diff --git a/Documentation/fmc/fmc-fakedev.txt b/Documentation/fmc/fmc-fakedev.rst
similarity index 85%
rename from Documentation/fmc/fmc-fakedev.txt
rename to Documentation/fmc/fmc-fakedev.rst
index e85b74a4ae30..e9300e839eef 100644
--- a/Documentation/fmc/fmc-fakedev.txt
+++ b/Documentation/fmc/fmc-fakedev.rst
@@ -1,7 +1,10 @@
-fmc-fakedev
-===========
+.. _fmc_fakedev:
 
-This package includes a software-only device, called fmc-fakedev, which
+=========================
+Software-only Fake Device
+=========================
+
+This package includes a software-only device, called **fmc-fakedev**, which
 is able to register up to 4 mezzanines (by default it registers one).
 Unlike the SPEC driver, which creates an FMC device for each PCI cards
 it manages, this module creates a single instance of its set of
@@ -9,14 +12,14 @@ mezzanines.
 
 It is meant as the simplest possible example of how a driver should be
 written, and it includes a fake EEPROM image (built using the tools
-described in *note FMC Identification::),, which by default is
+described in :ref:`fmc_identification` which by default is
 replicated for each fake mezzanine.
 
 You can also use this device to verify the match algorithms, by asking
 it to test your own EEPROM image. You can provide the image by means of
 the eeprom= module parameter: the new EEPROM image is loaded, as usual,
 by means of the firmware loader.  This example shows the defaults and a
-custom EEPROM image:
+custom EEPROM image::
 
      spusa.root# insmod fmc-fakedev.ko
      [   99.971247]  fake-fmc-carrier: mezzanine 0
diff --git a/Documentation/fmc/fmc-trivial.txt b/Documentation/fmc/fmc-trivial.rst
similarity index 69%
rename from Documentation/fmc/fmc-trivial.txt
rename to Documentation/fmc/fmc-trivial.rst
index d1910bc67159..c98324f955ea 100644
--- a/Documentation/fmc/fmc-trivial.txt
+++ b/Documentation/fmc/fmc-trivial.rst
@@ -1,7 +1,9 @@
-fmc-trivial
-===========
+.. _fmc_trivial:
 
-The simple module fmc-trivial is just a simple client that registers an
+FMC trivial driver
+==================
+
+The simple module **fmc-trivial** is just a simple client that registers an
 interrupt handler. I used it to verify the basic mechanism of the FMC
 bus and how interrupts worked.
 
@@ -9,8 +11,7 @@ The module implements the generic FMC parameters, so it can program a
 different gateware file in each card. The whole list of parameters it
 accepts are:
 
-`busid='
-`gateware='
+`busid=`, `gateware=`
      Generic parameters. See mezzanine.txt
 
 
diff --git a/Documentation/fmc/fmc-write-eeprom.txt b/Documentation/fmc/fmc-write-eeprom.rst
similarity index 79%
rename from Documentation/fmc/fmc-write-eeprom.txt
rename to Documentation/fmc/fmc-write-eeprom.rst
index e0a9712156aa..45311bcc804a 100644
--- a/Documentation/fmc/fmc-write-eeprom.txt
+++ b/Documentation/fmc/fmc-write-eeprom.rst
@@ -1,9 +1,12 @@
-fmc-write-eeprom
+.. _fmc_write_eeprom:
+
+================
+FMC write eeprom
 ================
 
-This module is designed to load a binary file from /lib/firmware and to
-write it to the internal EEPROM of the mezzanine card. This driver uses
-the `busid' generic parameter.
+The module **fmc-write-eeprom** is designed to load a binary file from
+/lib/firmware and to write it to the internal EEPROM of the mezzanine card.
+This driver uses the `busid` generic parameter.
 
 Overwriting the EEPROM is not something you should do daily, and it is
 expected to only happen during manufacturing. For this reason, the
@@ -11,36 +14,36 @@ module makes it unlikely for the random user to change a working EEPROM.
 
 However, since the EEPROM may include application-specific information
 other than the identification, later versions of this packages added
-write-support through sysfs. See *note Accessing the EEPROM::.
+write-support through sysfs. See :ref:`fmc_accessing_eeprom`.
 
 To avoid damaging the EEPROM content, the module takes the following
 measures:
 
-   * It accepts a `file=' argument (within /lib/firmware) and if no
+   * It accepts a `file=` argument (within /lib/firmware) and if no
      such argument is received, it doesn't write anything to EEPROM
      (i.e. there is no default file name).
 
-   * If the file name ends with `.bin' it is written verbatim starting
+   * If the file name ends with `.bin` it is written verbatim starting
      at offset 0.
 
-   * If the file name ends with `.tlv' it is interpreted as
+   * If the file name ends with `.tlv` it is interpreted as
      type-length-value (i.e., it allows writev(2)-like operation).
 
    * If the file name doesn't match any of the patterns above, it is
      ignored and no write is performed.
 
-   * Only cards listed with `busid=' are written to. If no busid is
+   * Only cards listed with `busid=` are written to. If no busid is
      specified, no programming is done (and the probe function of the
      driver will fail).
 
 
 Each TLV tuple is formatted in this way: the header is 5 bytes,
-followed by data. The first byte is `w' for write, the next two bytes
+followed by data. The first byte is `w` for write, the next two bytes
 represent the address, in little-endian byte order, and the next two
 represent the data length, in little-endian order. The length does not
 include the header (it is the actual number of bytes to be written).
 
-This is a real example: that writes 5 bytes at position 0x110:
+This is a real example: that writes 5 bytes at position 0x110::
 
         spusa.root# od -t x1 -Ax /lib/firmware/try.tlv
         000000 77 10 01 05 00 30 31 32 33 34
@@ -55,13 +58,13 @@ Rabbit environment. For this reason the TLV format is not expected to
 be used much and is not expected to be developed further.
 
 If you want to try reflashing fake EEPROM devices, you can use the
-fmc-fakedev.ko module (see *note fmc-fakedev::).  Whenever you change
+fmc-fakedev.ko module (see :ref:`fmc_fakedev`).  Whenever you change
 the image starting at offset 0, it will deregister and register again
 after two seconds.  Please note, however, that if fmc-write-eeprom is
 still loaded, the system will associate it to the new device, which
 will be reprogrammed and thus will be unloaded after two seconds.  The
 following example removes the module after it reflashed fakedev the
-first time.
+first time::
 
      spusa.root# insmod fmc-fakedev.ko
         [   72.984733]  fake-fmc: Manufacturer: fake-vendor
@@ -74,12 +77,13 @@ first time.
         [  132.895794]  fake-fmc: Manufacturer: CERN
         [  132.899872]  fake-fmc: Product name: FmcDelay1ns4cha
 
+.. _fmc_accessing_eeprom:
 
 Accessing the EEPROM
-=====================
+====================
 
 The bus creates a sysfs binary file called eeprom for each mezzanine it
-knows about:
+knows about::
 
         spusa.root# cd /sys/bus/fmc/devices; ls -l */eeprom
         -r--r--r-- 1 root root 8192 Feb 21 12:30 FmcAdc100m14b4cha-0800/eeprom
@@ -94,5 +98,5 @@ the FPGA with a custom circuit, the carrier is unable to access the
 EEPROM and returns ENOTSUPP.
 
 An alternative way to write the EEPROM is the mezzanine driver
-fmc-write-eeprom (See *note fmc-write-eeprom::), but the procedure is
+fmc-write-eeprom (See :ref:`fmc_write_eeprom`), but the procedure is
 more complex.
diff --git a/Documentation/fmc/identifiers.txt b/Documentation/fmc/identifiers.rst
similarity index 93%
rename from Documentation/fmc/identifiers.txt
rename to Documentation/fmc/identifiers.rst
index 3bb577ff0d52..01e6dde0996f 100644
--- a/Documentation/fmc/identifiers.txt
+++ b/Documentation/fmc/identifiers.rst
@@ -1,3 +1,5 @@
+.. _fmc_identification:
+
 FMC Identification
 ******************
 
@@ -19,7 +21,7 @@ package and SDB (part of the fpga-config-space package).
 
 The first sections are only interesting for manufacturers who need to
 write the EEPROM. If you are just a software developer writing an FMC
-device or driver, you may jump straight to *note SDB Support::.
+device or driver, you may jump straight to :ref:`fmc_sdb_support`.
 
 
 Building the FRU Structure
@@ -27,7 +29,7 @@ Building the FRU Structure
 
 If you want to know the internals of the FRU structure and despair, you
 can retrieve the document from
-`http://download.intel.com/design/servers/ipmi/FRU1011.pdf' .  The
+`http://download.intel.com/design/servers/ipmi/FRU1011.pdf` .  The
 standard is awful and difficult without reason, so we only support the
 minimum mandatory subset - we create a simple structure and parse it
 back at run time, but we are not able to either generate or parse more
@@ -43,13 +45,15 @@ line takes precedence)
 To make a long story short, in order to build a standard-compliant
 binary file to be burned in your EEPROM, you need the following items:
 
+	===========    ===     =====================  ============
         Environment    Opt     Official Name          Default
----------------------------------------------------------------------
+	===========    ===     =====================  ============
         FRU_VENDOR     -v      "Board Manufacturer"   fmc-example
         FRU_NAME       -n      "Board Product Name"   mezzanine
-        FRU_SERIAL     -s      `Board Serial Number"  0001
+        FRU_SERIAL     -s      "Board Serial Number"  0001
         FRU_PART       -p      "Board Part Number"    sample-part
         FRU_OUTPUT     -o      not applicable         /dev/stdout
+	===========    ===     =====================  ============
 
 The "Official Name" above is what you find in the FRU official
 documentation, chapter 11, page 7 ("Board Info Area Format").  The
@@ -63,7 +67,7 @@ soon as I find some time for that.
 
 FIXME: consumption etc for FRU are here or in PTS?
 
-The following example creates a binary image for a specific board:
+The following example creates a binary image for a specific board::
 
         ./tools/fru-generator -v CERN -n FmcAdc100m14b4cha \
                -s HCCFFIA___-CR000003 -p EDA-02063-V5-0 > eeprom.bin
@@ -71,7 +75,7 @@ The following example creates a binary image for a specific board:
 The following example shows a script that builds several binary EEPROM
 images for a series of boards, changing the serial number for each of
 them. The script uses a mix of environment variables and command line
-options, and uses the same string patterns shown above.
+options, and uses the same string patterns shown above::
 
         #!/bin/sh
 
@@ -131,7 +135,7 @@ name. The IPMI-FRU name is not mandatory, but a strongly suggested
 choice; the name filename is mandatory, because this is the preferred
 short name used by the FMC core.  For example, a name of "fdelay" may
 supplement a Product Name like "FmcDelay1ns4cha" - exactly as
-demonstrated in `tools/sdbfs'.
+demonstrated in `tools/sdbfs`.
 
 Note: SDB access to flash memory is not yet supported, so the short
 name currently in use is just the "Product Name" FRU string.
@@ -139,7 +143,7 @@ name currently in use is just the "Product Name" FRU string.
 The example in tools/sdbfs includes an extra file, that is needed by
 the fine-delay driver, and must live at a known address of 0x1800.  By
 running gensdbfs on that directory you can output your binary EEPROM
-image (here below spusa$ is the shell prompt):
+image (here below spusa$ is the shell prompt)::
 
         spusa$ ../fru-generator -v CERN -n FmcDelay1ns4cha -s proto-0 \
                       -p EDA-02267-V3 > IPMI-FRU
diff --git a/Documentation/fmc/index.rst b/Documentation/fmc/index.rst
new file mode 100644
index 000000000000..a749cb04f39e
--- /dev/null
+++ b/Documentation/fmc/index.rst
@@ -0,0 +1,21 @@
+:orphan:
+
+=========================
+FMC (FPGA Mezzanine Card)
+=========================
+
+.. toctree::
+   :maxdepth: 1
+
+   fmc-and-sdb
+   carrier
+   identifiers
+   mezzanine
+   parameters
+
+   api
+
+   fmc-fakedev
+   fmc-trivial
+   fmc-write-eeprom
+   fmc-chardev
diff --git a/Documentation/fmc/mezzanine.txt b/Documentation/fmc/mezzanine.rst
similarity index 87%
rename from Documentation/fmc/mezzanine.txt
rename to Documentation/fmc/mezzanine.rst
index 87910dbfc91e..9a37147e8f14 100644
--- a/Documentation/fmc/mezzanine.txt
+++ b/Documentation/fmc/mezzanine.rst
@@ -1,5 +1,8 @@
+.. _fmc_driver:
+
+==========
 FMC Driver
-**********
+==========
 
 An FMC driver is concerned with the specific mezzanine and associated
 gateware. As such, it is expected to be independent of the carrier
@@ -12,23 +15,23 @@ configured in the FPGA; the latter technique is used when the FPGA is
 already programmed when the device is registered to the bus core.
 
 In some special cases it is possible for a driver to directly access
-FPGA registers, by means of the `fpga_base' field of the device
+FPGA registers, by means of the `fpga_base` field of the device
 structure. This may be needed for high-bandwidth peripherals like fast
 ADC cards. If the device module registered a remote device (for example
-by means of Etherbone), the `fpga_base' pointer will be NULL.
+by means of Etherbone), the `fpga_base` pointer will be NULL.
 Therefore, drivers must be ready to deal with NULL base pointers, and
 fail gracefully.  Most driver, however, are not expected to access the
 pointer directly but run fmc_readl and fmc_writel instead, which will
 work in any case.
 
 In even more special cases, the driver may access carrier-specific
-functionality: the `carrier_name' string allows the driver to check
-which is the current carrier and make use of the `carrier_data'
+functionality: the `carrier_name` string allows the driver to check
+which is the current carrier and make use of the `carrier_data`
 pointer.  We chose to use carrier names rather than numeric identifiers
 for greater flexibility, but also to avoid a central registry within
-the `fmc.h' file - we hope other users will exploit our framework with
+the `fmc.h` file - we hope other users will exploit our framework with
 their own carriers.  An example use of carrier names is in GPIO setup
-(see *note The GPIO Abstraction::), although the name match is not
+(see :ref:`fmc_gpio_abstraction`), although the name match is not
 expected to be performed by the driver.  If you depend on specific
 carriers, please check the carrier name and fail gracefully if your
 driver finds it is running in a yet-unknown-to-it environment.
@@ -44,7 +47,7 @@ their EEPROM or on the actual FPGA cores that can be enumerated.
 Therefore, we have two tables of identifiers.
 
 Matching of FRU information depends on two names, the manufacturer (or
-vendor) and the device (see *note FMC Identification::); for
+vendor) and the device (see :ref:`fmc_identification`); for
 flexibility during production (i.e. before writing to the EEPROM) the
 bus supports a catch-all driver that specifies NULL strings. For this
 reason, the table is specified as pointer-and-length, not a a
@@ -58,7 +61,7 @@ instantiated), and for consistency the list is passed as
 pointer-and-length.  Several similar devices can be driven by the same
 driver, and thus the driver specifies and array of such arrays.
 
-The complete set of involved data structures is thus the following:
+The complete set of involved data structures is thus the following::
 
         struct fmc_fru_id { char *manufacturer; char *product_name; };
         struct fmc_sdb_one_id { uint64_t vendor; uint32_t device; };
@@ -71,13 +74,14 @@ The complete set of involved data structures is thus the following:
 
 A better reference, with full explanation, is the <linux/fmc.h> header.
 
+.. _fmc_module_parameters:
 
 Module Parameters
 =================
 
 Most of the FMC drivers need the same set of kernel parameters. This
 package includes support to implement common parameters by means of
-fields in the `fmc_driver' structure and simple macro definitions.
+fields in the `fmc_driver` structure and simple macro definitions.
 
 The parameters are carrier-specific, in that they rely on the busid
 concept, that varies among carriers. For the SPEC, the identifier is a
@@ -88,20 +92,20 @@ and some code duplication is unavoidable.
 This is the list of parameters that are common to several modules to
 see how they are actually used, please look at spec-trivial.c.
 
-`busid='
+`busid=`
      This is an array of integers, listing carrier-specific
-     identification numbers. For PIC, for example, `0x0400' represents
+     identification numbers. For PIC, for example, `0x0400` represents
      bus 4, slot 0.  If any such ID is specified, the driver will only
      accept to drive cards that appear in the list (even if the FMC ID
      matches). This is accomplished by the validate carrier method.
 
-`gateware='
+`gateware=`
      The argument is an array of strings. If no busid= is specified,
      the first string of gateware= is used for all cards; otherwise the
      identifiers and gateware names are paired one by one, in the order
      specified.
 
-`show_sdb='
+`show_sdb=`
      For modules supporting it, this parameter asks to show the SDB
      internal structure by means of kernel messages. It is disabled by
      default because those lines tend to hide more important messages,
@@ -113,7 +117,7 @@ see how they are actually used, please look at spec-trivial.c.
 For example, if you are using the trivial driver to load two different
 gateware files to two different cards, you can use the following
 parameters to load different binaries to the cards, after looking up
-the PCI identifiers. This has been tested with a SPEC carrier.
+the PCI identifiers. This has been tested with a SPEC carrier::
 
         insmod fmc-trivial.ko \
                               busid=0x0200,0x0400 \
diff --git a/Documentation/fmc/parameters.txt b/Documentation/fmc/parameters.rst
similarity index 96%
rename from Documentation/fmc/parameters.txt
rename to Documentation/fmc/parameters.rst
index 59edf088e3a4..bf4566967e9c 100644
--- a/Documentation/fmc/parameters.txt
+++ b/Documentation/fmc/parameters.rst
@@ -1,16 +1,17 @@
+===========================
 Module Parameters in fmc.ko
-***************************
+===========================
 
 The core driver receives two module parameters, meant to help debugging
 client modules. Both parameters can be modified by writing to
 /sys/module/fmc/parameters/, because they are used when client drivers
 are devices are registered, not when fmc.ko is loaded.
 
-`dump_eeprom='
+`dump_eeprom=`
      If not zero, the parameter asks the bus controller to dump the
      EEPROM of any device that is registered, using printk.
 
-`dump_sdb='
+`dump_sdb=`
      If not zero, the parameter prints the SDB tree of every FPGA it is
      loaded by fmc_reprogram(). If greater than one, it asks to dump
      the binary content of SDB records.  This currently only dumps the
@@ -19,7 +20,7 @@ are devices are registered, not when fmc.ko is loaded.
 
 EEPROM dumping avoids repeating lines, since most of the contents is
 usually empty and all bits are one or zero. This is an example of the
-output:
+output::
 
         [ 6625.850480] spec 0000:02:00.0: FPGA programming successful
         [ 6626.139949] spec 0000:02:00.0: Manufacturer: CERN
@@ -40,7 +41,7 @@ output:
 
 The dump of SDB looks like the following; the example shows the simple
 golden gateware for the SPEC card, removing the leading timestamps to
-fit the page:
+fit the page::
 
         spec 0000:02:00.0: SDB: 00000651:e6a542c9 WB4-Crossbar-GSI
         spec 0000:02:00.0: SDB: 0000ce42:ff07fc47 WR-Periph-Syscon (00000000-000000ff)
-- 
2.21.0


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 20/31] docs: hid: convert to ReST
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (17 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 19/31] docs: fmc: " Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-13  8:08   ` Benjamin Tissoires
  2019-06-12 18:38 ` [PATCH v1 21/31] docs: ia64: " Mauro Carvalho Chehab
                   ` (10 subsequent siblings)
  29 siblings, 1 reply; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Jiri Kosina, Jonathan Cameron,
	Srinivas Pandruvada, Benjamin Tissoires, Dmitry Torokhov,
	linux-input, linux-iio, linux-usb

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

While here, fix the sysfs example from hid-sensor.txt, that
has a lot of "?" instead of the proper UTF-8 characters that
are produced by the tree command.

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>
---
 .../hid/{hid-alps.txt => hid-alps.rst}        |  85 ++-
 .../hid/{hid-sensor.txt => hid-sensor.rst}    | 192 +++----
 .../{hid-transport.txt => hid-transport.rst}  |  82 ++-
 Documentation/hid/{hiddev.txt => hiddev.rst}  | 154 ++++--
 Documentation/hid/{hidraw.txt => hidraw.rst}  |  53 +-
 Documentation/hid/index.rst                   |  18 +
 Documentation/hid/intel-ish-hid.rst           | 485 ++++++++++++++++++
 Documentation/hid/intel-ish-hid.txt           | 454 ----------------
 Documentation/hid/{uhid.txt => uhid.rst}      |  46 +-
 Documentation/input/input.rst                 |   2 +-
 MAINTAINERS                                   |   2 +-
 11 files changed, 897 insertions(+), 676 deletions(-)
 rename Documentation/hid/{hid-alps.txt => hid-alps.rst} (64%)
 rename Documentation/hid/{hid-sensor.txt => hid-sensor.rst} (61%)
 rename Documentation/hid/{hid-transport.txt => hid-transport.rst} (93%)
 rename Documentation/hid/{hiddev.txt => hiddev.rst} (77%)
 rename Documentation/hid/{hidraw.txt => hidraw.rst} (89%)
 create mode 100644 Documentation/hid/index.rst
 create mode 100644 Documentation/hid/intel-ish-hid.rst
 delete mode 100644 Documentation/hid/intel-ish-hid.txt
 rename Documentation/hid/{uhid.txt => uhid.rst} (94%)

diff --git a/Documentation/hid/hid-alps.txt b/Documentation/hid/hid-alps.rst
similarity index 64%
rename from Documentation/hid/hid-alps.txt
rename to Documentation/hid/hid-alps.rst
index 6b02a2447c77..e2f4c4c11e3f 100644
--- a/Documentation/hid/hid-alps.txt
+++ b/Documentation/hid/hid-alps.rst
@@ -1,19 +1,26 @@
+==========================
 ALPS HID Touchpad Protocol
-----------------------
+==========================
 
 Introduction
 ------------
 Currently ALPS HID driver supports U1 Touchpad device.
 
-U1 devuce basic information.
+U1 device basic information.
+
+==========	======
 Vender ID	0x044E
 Product ID	0x120B
 Version ID	0x0121
+==========	======
 
 
 HID Descriptor
-------------
+--------------
+
+=======	====================	=====	=======================================
 Byte	Field			Value	Notes
+=======	====================	=====	=======================================
 0	wHIDDescLength		001E	Length of HID Descriptor : 30 bytes
 2	bcdVersion		0100	Compliant with Version 1.00
 4	wReportDescLength	00B2	Report Descriptor is 178 Bytes (0x00B2)
@@ -28,32 +35,42 @@ Byte	Field			Value	Notes
 22	wProductID		120B	Product ID 0x120B
 24	wVersionID		0121	Version 01.21
 26	RESERVED		0000	RESERVED
+=======	====================	=====	=======================================
 
 
 Report ID
-------------
-ReportID-1	(Input Reports)	(HIDUsage-Mouse) for TP&SP
-ReportID-2	(Input Reports)	(HIDUsage-keyboard) for TP
-ReportID-3	(Input Reports)	(Vendor Usage: Max 10 finger data) for TP
-ReportID-4	(Input Reports)	(Vendor Usage: ON bit data) for GP
-ReportID-5	(Feature Reports)	Feature Reports
-ReportID-6	(Input Reports)	(Vendor Usage: StickPointer data) for SP
-ReportID-7	(Feature Reports)	Flash update (Bootloader)
+---------
+
+==========	=================  =========================================
+ReportID-1	(Input Reports)	   (HIDUsage-Mouse) for TP&SP
+ReportID-2	(Input Reports)	   (HIDUsage-keyboard) for TP
+ReportID-3	(Input Reports)	   (Vendor Usage: Max 10 finger data) for TP
+ReportID-4	(Input Reports)	   (Vendor Usage: ON bit data) for GP
+ReportID-5	(Feature Reports)  Feature Reports
+ReportID-6	(Input Reports)	   (Vendor Usage: StickPointer data) for SP
+ReportID-7	(Feature Reports)  Flash update (Bootloader)
+==========	=================  =========================================
 
 
 Data pattern
 ------------
+
+=====	==========	=====	=================
 Case1	ReportID_1	TP/SP	Relative/Relative
 Case2	ReportID_3	TP	Absolute
 	ReportID_6	SP	Absolute
+=====	==========	=====	=================
 
 
 Command Read/Write
 ------------------
 To read/write to RAM, need to send a commands to the device.
+
 The command format is as below.
 
 DataByte(SET_REPORT)
+
+=====	======================
 Byte1	Command Byte
 Byte2	Address - Byte 0 (LSB)
 Byte3	Address - Byte 1
@@ -61,13 +78,19 @@ Byte4	Address - Byte 2
 Byte5	Address - Byte 3 (MSB)
 Byte6	Value Byte
 Byte7	Checksum
+=====	======================
 
 Command Byte is read=0xD1/write=0xD2 .
+
 Address is read/write RAM address.
+
 Value Byte is writing data when you send the write commands.
+
 When you read RAM, there is no meaning.
 
 DataByte(GET_REPORT)
+
+=====	======================
 Byte1	Response Byte
 Byte2	Address - Byte 0 (LSB)
 Byte3	Address - Byte 1
@@ -75,6 +98,7 @@ Byte4	Address - Byte 2
 Byte5	Address - Byte 3 (MSB)
 Byte6	Value Byte
 Byte7	Checksum
+=====	======================
 
 Read value is stored in Value Byte.
 
@@ -82,7 +106,11 @@ Read value is stored in Value Byte.
 Packet Format
 Touchpad data byte
 ------------------
-	b7	b6	b5	b4	b3	b2	b1	b0
+
+
+======= ======= ======= ======= ======= ======= ======= ======= =====
+-	b7	b6	b5	b4	b3	b2	b1	b0
+======= ======= ======= ======= ======= ======= ======= ======= =====
 1	0	0	SW6	SW5	SW4	SW3	SW2	SW1
 2	0	0	0	Fcv	Fn3	Fn2	Fn1	Fn0
 3	Xa0_7	Xa0_6	Xa0_5	Xa0_4	Xa0_3	Xa0_2	Xa0_1	Xa0_0
@@ -114,17 +142,25 @@ Touchpad data byte
 25	Ya4_7	Ya4_6	Ya4_5	Ya4_4	Ya4_3	Ya4_2	Ya4_1	Ya4_0
 26	Ya4_15	Ya4_14	Ya4_13	Ya4_12	Ya4_11	Ya4_10	Ya4_9	Ya4_8
 27	LFB4	Zs4_6	Zs4_5	Zs4_4	Zs4_3	Zs4_2	Zs4_1	Zs4_0
+======= ======= ======= ======= ======= ======= ======= ======= =====
 
 
-SW1-SW6:	SW ON/OFF status
-Xan_15-0(16bit):X Absolute data of the "n"th finger
-Yan_15-0(16bit):Y Absolute data of the "n"th finger
-Zsn_6-0(7bit):	Operation area of the "n"th finger
+SW1-SW6:
+	SW ON/OFF status
+Xan_15-0(16bit):
+	X Absolute data of the "n"th finger
+Yan_15-0(16bit):
+	Y Absolute data of the "n"th finger
+Zsn_6-0(7bit):
+	Operation area of the "n"th finger
 
 
 StickPointer data byte
-------------------
-	b7	b6	b5	b4	b3	b2	b1	b0
+----------------------
+
+======= ======= ======= ======= ======= ======= ======= ======= =====
+-	b7	b6	b5	b4	b3	b2	b1	b0
+======= ======= ======= ======= ======= ======= ======= ======= =====
 Byte1	1	1	1	0	1	SW3	SW2	SW1
 Byte2	X7	X6	X5	X4	X3	X2	X1	X0
 Byte3	X15	X14	X13	X12	X11	X10	X9	X8
@@ -132,8 +168,13 @@ Byte4	Y7	Y6	Y5	Y4	Y3	Y2	Y1	Y0
 Byte5	Y15	Y14	Y13	Y12	Y11	Y10	Y9	Y8
 Byte6	Z7	Z6	Z5	Z4	Z3	Z2	Z1	Z0
 Byte7	T&P	Z14	Z13	Z12	Z11	Z10	Z9	Z8
+======= ======= ======= ======= ======= ======= ======= ======= =====
 
-SW1-SW3:	SW ON/OFF status
-Xn_15-0(16bit):X Absolute data
-Yn_15-0(16bit):Y Absolute data
-Zn_14-0(15bit):Z
+SW1-SW3:
+	SW ON/OFF status
+Xn_15-0(16bit):
+	X Absolute data
+Yn_15-0(16bit):
+	Y Absolute data
+Zn_14-0(15bit):
+	Z
diff --git a/Documentation/hid/hid-sensor.txt b/Documentation/hid/hid-sensor.rst
similarity index 61%
rename from Documentation/hid/hid-sensor.txt
rename to Documentation/hid/hid-sensor.rst
index b287752a31cd..758972e34971 100644
--- a/Documentation/hid/hid-sensor.txt
+++ b/Documentation/hid/hid-sensor.rst
@@ -1,6 +1,6 @@
-
+=====================
 HID Sensors Framework
-======================
+=====================
 HID sensor framework provides necessary interfaces to implement sensor drivers,
 which are connected to a sensor hub. The sensor hub is a HID device and it provides
 a report descriptor conforming to HID 1.12 sensor usage tables.
@@ -15,22 +15,22 @@ the drivers themselves."
 This specification describes many usage IDs, which describe the type of sensor
 and also the individual data fields. Each sensor can have variable number of
 data fields. The length and order is specified in the report descriptor. For
-example a part of report descriptor can look like:
+example a part of report descriptor can look like::
 
-   INPUT(1)[INPUT]
- ..
-    Field(2)
-      Physical(0020.0073)
-      Usage(1)
-        0020.045f
-      Logical Minimum(-32767)
-      Logical Maximum(32767)
-      Report Size(8)
-      Report Count(1)
-      Report Offset(16)
-      Flags(Variable Absolute)
-..
-..
+     INPUT(1)[INPUT]
+   ..
+      Field(2)
+        Physical(0020.0073)
+        Usage(1)
+          0020.045f
+        Logical Minimum(-32767)
+        Logical Maximum(32767)
+        Report Size(8)
+        Report Count(1)
+        Report Offset(16)
+        Flags(Variable Absolute)
+  ..
+  ..
 
 The report is indicating "sensor page (0x20)" contains an accelerometer-3D (0x73).
 This accelerometer-3D has some fields. Here for example field 2 is motion intensity
@@ -40,13 +40,14 @@ data will use this format.
 
 
 Implementation
-=================
+==============
 
 This specification defines many different types of sensors with different sets of
 data fields. It is difficult to have a common input event to user space applications,
 for different sensors. For example an accelerometer can send X,Y and Z data, whereas
 an ambient light sensor can send illumination data.
 So the implementation has two parts:
+
 - Core hid driver
 - Individual sensor processing part (sensor drivers)
 
@@ -55,8 +56,11 @@ Core driver
 The core driver registers (hid-sensor-hub) registers as a HID driver. It parses
 report descriptors and identifies all the sensors present. It adds an MFD device
 with name HID-SENSOR-xxxx (where xxxx is usage id from the specification).
-For example
+
+For example:
+
 HID-SENSOR-200073 is registered for an Accelerometer 3D driver.
+
 So if any driver with this name is inserted, then the probe routine for that
 function will be called. So an accelerometer processing driver can register
 with this name and will be probed if there is an accelerometer-3D detected.
@@ -66,7 +70,8 @@ drivers to register and get events for that usage id. Also it provides parsing
 functions, which get and set each input/feature/output report.
 
 Individual sensor processing part (sensor drivers)
------------
+--------------------------------------------------
+
 The processing driver will use an interface provided by the core driver to parse
 the report and get the indexes of the fields and also can get events. This driver
 can use IIO interface to use the standard ABI defined for a type of sensor.
@@ -75,31 +80,34 @@ can use IIO interface to use the standard ABI defined for a type of sensor.
 Core driver Interface
 =====================
 
-Callback structure:
-Each processing driver can use this structure to set some callbacks.
+Callback structure::
+
+  Each processing driver can use this structure to set some callbacks.
 	int (*suspend)(..): Callback when HID suspend is received
 	int (*resume)(..): Callback when HID resume is received
 	int (*capture_sample)(..): Capture a sample for one of its data fields
 	int (*send_event)(..): One complete event is received which can have
                                multiple data fields.
 
-Registration functions:
-int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
+Registration functions::
+
+  int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
 			u32 usage_id,
 			struct hid_sensor_hub_callbacks *usage_callback):
 
 Registers callbacks for an usage id. The callback functions are not allowed
-to sleep.
+to sleep::
 
 
-int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
+  int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
 			u32 usage_id):
 
 Removes callbacks for an usage id.
 
 
-Parsing function:
-int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
+Parsing function::
+
+  int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
 			u8 type,
 			u32 usage_id, u32 attr_usage_id,
 			struct hid_sensor_hub_attribute_info *info);
@@ -110,26 +118,27 @@ so that fields can be set or get individually.
 These indexes avoid searching every time and getting field index to get or set.
 
 
-Set Feature report
-int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
+Set Feature report::
+
+  int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
 			u32 field_index, s32 value);
 
 This interface is used to set a value for a field in feature report. For example
 if there is a field report_interval, which is parsed by a call to
-sensor_hub_input_get_attribute_info before, then it can directly set that individual
-field.
+sensor_hub_input_get_attribute_info before, then it can directly set that
+individual field::
 
 
-int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
+  int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
 			u32 field_index, s32 *value);
 
 This interface is used to get a value for a field in input report. For example
 if there is a field report_interval, which is parsed by a call to
-sensor_hub_input_get_attribute_info before, then it can directly get that individual
-field value.
+sensor_hub_input_get_attribute_info before, then it can directly get that
+individual field value::
 
 
-int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
+  int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
 			u32 usage_id,
 			u32 attr_usage_id, u32 report_id);
 
@@ -143,6 +152,8 @@ registered callback function to process the sample.
 ----------
 
 HID Custom and generic Sensors
+------------------------------
+
 
 HID Sensor specification defines two special sensor usage types. Since they
 don't represent a standard sensor, it is not possible to define using Linux IIO
@@ -158,66 +169,73 @@ keyboard attached/detached or lid open/close.
 To allow application to utilize these sensors, here they are exported uses sysfs
 attribute groups, attributes and misc device interface.
 
-An example of this representation on sysfs:
-/sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R
-.
-????????? enable_sensor
-????????? feature-0-200316
-??????? ????????? feature-0-200316-maximum
-??????? ????????? feature-0-200316-minimum
-??????? ????????? feature-0-200316-name
-??????? ????????? feature-0-200316-size
-??????? ????????? feature-0-200316-unit-expo
-??????? ????????? feature-0-200316-units
-??????? ????????? feature-0-200316-value
-????????? feature-1-200201
-??????? ????????? feature-1-200201-maximum
-??????? ????????? feature-1-200201-minimum
-??????? ????????? feature-1-200201-name
-??????? ????????? feature-1-200201-size
-??????? ????????? feature-1-200201-unit-expo
-??????? ????????? feature-1-200201-units
-??????? ????????? feature-1-200201-value
-????????? input-0-200201
-??????? ????????? input-0-200201-maximum
-??????? ????????? input-0-200201-minimum
-??????? ????????? input-0-200201-name
-??????? ????????? input-0-200201-size
-??????? ????????? input-0-200201-unit-expo
-??????? ????????? input-0-200201-units
-??????? ????????? input-0-200201-value
-????????? input-1-200202
-??????? ????????? input-1-200202-maximum
-??????? ????????? input-1-200202-minimum
-??????? ????????? input-1-200202-name
-??????? ????????? input-1-200202-size
-??????? ????????? input-1-200202-unit-expo
-??????? ????????? input-1-200202-units
-??????? ????????? input-1-200202-value
+An example of this representation on sysfs::
+
+  /sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R
+  .
+  │   ├──  enable_sensor
+  │   │   ├── feature-0-200316
+  │   │   │   ├── feature-0-200316-maximum
+  │   │   │   ├── feature-0-200316-minimum
+  │   │   │   ├── feature-0-200316-name
+  │   │   │   ├── feature-0-200316-size
+  │   │   │   ├── feature-0-200316-unit-expo
+  │   │   │   ├── feature-0-200316-units
+  │   │   │   ├── feature-0-200316-value
+  │   │   ├── feature-1-200201
+  │   │   │   ├── feature-1-200201-maximum
+  │   │   │   ├── feature-1-200201-minimum
+  │   │   │   ├── feature-1-200201-name
+  │   │   │   ├── feature-1-200201-size
+  │   │   │   ├── feature-1-200201-unit-expo
+  │   │   │   ├── feature-1-200201-units
+  │   │   │   ├── feature-1-200201-value
+  │   │   ├── input-0-200201
+  │   │   │   ├── input-0-200201-maximum
+  │   │   │   ├── input-0-200201-minimum
+  │   │   │   ├── input-0-200201-name
+  │   │   │   ├── input-0-200201-size
+  │   │   │   ├── input-0-200201-unit-expo
+  │   │   │   ├── input-0-200201-units
+  │   │   │   ├── input-0-200201-value
+  │   │   ├── input-1-200202
+  │   │   │   ├── input-1-200202-maximum
+  │   │   │   ├── input-1-200202-minimum
+  │   │   │   ├── input-1-200202-name
+  │   │   │   ├── input-1-200202-size
+  │   │   │   ├── input-1-200202-unit-expo
+  │   │   │   ├── input-1-200202-units
+  │   │   │   ├── input-1-200202-value
 
 Here there is a custom sensors with four fields, two feature and two inputs.
 Each field is represented by a set of attributes. All fields except the "value"
 are read only. The value field is a RW field.
-Example
-/sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
-feature-0-200316-maximum:6
-feature-0-200316-minimum:0
-feature-0-200316-name:property-reporting-state
-feature-0-200316-size:1
-feature-0-200316-unit-expo:0
-feature-0-200316-units:25
-feature-0-200316-value:1
+
+Example::
+
+  /sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
+  feature-0-200316-maximum:6
+  feature-0-200316-minimum:0
+  feature-0-200316-name:property-reporting-state
+  feature-0-200316-size:1
+  feature-0-200316-unit-expo:0
+  feature-0-200316-units:25
+  feature-0-200316-value:1
 
 How to enable such sensor?
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 By default sensor can be power gated. To enable sysfs attribute "enable" can be
-used.
-$ echo 1 > enable_sensor
+used::
+
+	$ echo 1 > enable_sensor
 
 Once enabled and powered on, sensor can report value using HID reports.
-These reports are pushed using misc device interface in a FIFO order.
-/dev$ tree | grep HID-SENSOR-2000e1.6.auto
-??????? ????????? 10:53 -> ../HID-SENSOR-2000e1.6.auto
-????????? HID-SENSOR-2000e1.6.auto
+These reports are pushed using misc device interface in a FIFO order::
+
+	/dev$ tree | grep HID-SENSOR-2000e1.6.auto
+	│   │   │   ├── 10:53 -> ../HID-SENSOR-2000e1.6.auto
+	│   ├──  HID-SENSOR-2000e1.6.auto
 
 Each reports can be of variable length preceded by a header. This header
 consist of a 32 bit usage id, 64 bit time stamp and 32 bit length field of raw
diff --git a/Documentation/hid/hid-transport.txt b/Documentation/hid/hid-transport.rst
similarity index 93%
rename from Documentation/hid/hid-transport.txt
rename to Documentation/hid/hid-transport.rst
index 3dcba9fd4a3a..6f3aaa86ce7b 100644
--- a/Documentation/hid/hid-transport.txt
+++ b/Documentation/hid/hid-transport.rst
@@ -1,5 +1,6 @@
-                          HID I/O Transport Drivers
-                         ===========================
+=========================
+HID I/O Transport Drivers
+=========================
 
 The HID subsystem is independent of the underlying transport driver. Initially,
 only USB was supported, but other specifications adopted the HID design and
@@ -16,6 +17,8 @@ transport and device setup/management. HID core is responsible of
 report-parsing, report interpretation and the user-space API. Device specifics
 and quirks are handled by all layers depending on the quirk.
 
+::
+
  +-----------+  +-----------+            +-----------+  +-----------+
  | Device #1 |  | Device #i |            | Device #j |  | Device #k |
  +-----------+  +-----------+            +-----------+  +-----------+
@@ -42,8 +45,9 @@ and quirks are handled by all layers depending on the quirk.
  +----------------+  +-----------+  +------------------+  +------------------+
 
 Example Drivers:
-  I/O: USB, I2C, Bluetooth-l2cap
-  Transport: USB-HID, I2C-HID, BT-HIDP
+
+  - I/O: USB, I2C, Bluetooth-l2cap
+  - Transport: USB-HID, I2C-HID, BT-HIDP
 
 Everything below "HID Core" is simplified in this graph as it is only of
 interest to HID device drivers. Transport drivers do not need to know the
@@ -183,7 +187,7 @@ Other ctrl-channel requests are supported by USB-HID but are not available
 -------------------
 
 Transport drivers normally use the following procedure to register a new device
-with HID core:
+with HID core::
 
 	struct hid_device *hid;
 	int ret;
@@ -215,7 +219,7 @@ Once hid_add_device() is entered, HID core might use the callbacks provided in
 "custom_ll_driver". Note that fields like "country" can be ignored by underlying
 transport-drivers if not supported.
 
-To unregister a device, use:
+To unregister a device, use::
 
 	hid_destroy_device(hid);
 
@@ -226,73 +230,110 @@ driver callbacks.
 -----------------------------
 
 The available HID callbacks are:
- - int (*start) (struct hid_device *hdev)
+
+   ::
+
+      int (*start) (struct hid_device *hdev)
+
    Called from HID device drivers once they want to use the device. Transport
    drivers can choose to setup their device in this callback. However, normally
    devices are already set up before transport drivers register them to HID core
    so this is mostly only used by USB-HID.
 
- - void (*stop) (struct hid_device *hdev)
+   ::
+
+      void (*stop) (struct hid_device *hdev)
+
    Called from HID device drivers once they are done with a device. Transport
    drivers can free any buffers and deinitialize the device. But note that
    ->start() might be called again if another HID device driver is loaded on the
    device.
+
    Transport drivers are free to ignore it and deinitialize devices after they
    destroyed them via hid_destroy_device().
 
- - int (*open) (struct hid_device *hdev)
+   ::
+
+      int (*open) (struct hid_device *hdev)
+
    Called from HID device drivers once they are interested in data reports.
    Usually, while user-space didn't open any input API/etc., device drivers are
    not interested in device data and transport drivers can put devices asleep.
    However, once ->open() is called, transport drivers must be ready for I/O.
    ->open() calls are nested for each client that opens the HID device.
 
- - void (*close) (struct hid_device *hdev)
+   ::
+
+      void (*close) (struct hid_device *hdev)
+
    Called from HID device drivers after ->open() was called but they are no
    longer interested in device reports. (Usually if user-space closed any input
    devices of the driver).
+
    Transport drivers can put devices asleep and terminate any I/O of all
    ->open() calls have been followed by a ->close() call. However, ->start() may
    be called again if the device driver is interested in input reports again.
 
- - int (*parse) (struct hid_device *hdev)
+   ::
+
+      int (*parse) (struct hid_device *hdev)
+
    Called once during device setup after ->start() has been called. Transport
    drivers must read the HID report-descriptor from the device and tell HID core
    about it via hid_parse_report().
 
- - int (*power) (struct hid_device *hdev, int level)
+   ::
+
+      int (*power) (struct hid_device *hdev, int level)
+
    Called by HID core to give PM hints to transport drivers. Usually this is
    analogical to the ->open() and ->close() hints and redundant.
 
- - void (*request) (struct hid_device *hdev, struct hid_report *report,
-                    int reqtype)
+   ::
+
+      void (*request) (struct hid_device *hdev, struct hid_report *report,
+		       int reqtype)
+
    Send an HID request on the ctrl channel. "report" contains the report that
    should be sent and "reqtype" the request type. Request-type can be
    HID_REQ_SET_REPORT or HID_REQ_GET_REPORT.
+
    This callback is optional. If not provided, HID core will assemble a raw
    report following the HID specs and send it via the ->raw_request() callback.
    The transport driver is free to implement this asynchronously.
 
- - int (*wait) (struct hid_device *hdev)
+   ::
+
+      int (*wait) (struct hid_device *hdev)
+
    Used by HID core before calling ->request() again. A transport driver can use
    it to wait for any pending requests to complete if only one request is
    allowed at a time.
 
- - int (*raw_request) (struct hid_device *hdev, unsigned char reportnum,
-                       __u8 *buf, size_t count, unsigned char rtype,
-                       int reqtype)
+   ::
+
+      int (*raw_request) (struct hid_device *hdev, unsigned char reportnum,
+                          __u8 *buf, size_t count, unsigned char rtype,
+                          int reqtype)
+
    Same as ->request() but provides the report as raw buffer. This request shall
    be synchronous. A transport driver must not use ->wait() to complete such
    requests. This request is mandatory and hid core will reject the device if
    it is missing.
 
- - int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len)
+   ::
+
+      int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len)
+
    Send raw output report via intr channel. Used by some HID device drivers
    which require high throughput for outgoing requests on the intr channel. This
    must not cause SET_REPORT calls! This must be implemented as asynchronous
    output report on the intr channel!
 
- - int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype)
+   ::
+
+      int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype)
+
    Perform SET/GET_IDLE request. Only used by USB-HID, do not implement!
 
 2.3) Data Path
@@ -314,4 +355,5 @@ transport driver and not passed to hid_input_report().
 Acknowledgements to SET_REPORT requests are not of interest to HID core.
 
 ----------------------------------------------------
+
 Written 2013, David Herrmann <dh.herrmann@gmail.com>
diff --git a/Documentation/hid/hiddev.txt b/Documentation/hid/hiddev.rst
similarity index 77%
rename from Documentation/hid/hiddev.txt
rename to Documentation/hid/hiddev.rst
index 638448707aa2..209e6ba4e019 100644
--- a/Documentation/hid/hiddev.txt
+++ b/Documentation/hid/hiddev.rst
@@ -1,6 +1,9 @@
+================================================
 Care and feeding of your Human Interface Devices
+================================================
 
-INTRODUCTION
+Introduction
+============
 
 In addition to the normal input type HID devices, USB also uses the
 human interface device protocols for things that are not really human
@@ -16,38 +19,40 @@ normalised event interface - see Documentation/input/input.rst
 * the hiddev interface, which provides fairly raw HID events
 
 The data flow for a HID event produced by a device is something like
-the following :
+the following::
 
  usb.c ---> hid-core.c  ----> hid-input.c ----> [keyboard/mouse/joystick/event]
                          |
                          |
-                          --> hiddev.c ----> POWER / MONITOR CONTROL 
+                          --> hiddev.c ----> POWER / MONITOR CONTROL
 
 In addition, other subsystems (apart from USB) can potentially feed
 events into the input subsystem, but these have no effect on the hid
 device interface.
 
-USING THE HID DEVICE INTERFACE
+Using the HID Device Interface
+==============================
 
 The hiddev interface is a char interface using the normal USB major,
 with the minor numbers starting at 96 and finishing at 111. Therefore,
-you need the following commands:
-mknod /dev/usb/hiddev0 c 180 96
-mknod /dev/usb/hiddev1 c 180 97
-mknod /dev/usb/hiddev2 c 180 98
-mknod /dev/usb/hiddev3 c 180 99
-mknod /dev/usb/hiddev4 c 180 100
-mknod /dev/usb/hiddev5 c 180 101
-mknod /dev/usb/hiddev6 c 180 102
-mknod /dev/usb/hiddev7 c 180 103
-mknod /dev/usb/hiddev8 c 180 104
-mknod /dev/usb/hiddev9 c 180 105
-mknod /dev/usb/hiddev10 c 180 106
-mknod /dev/usb/hiddev11 c 180 107
-mknod /dev/usb/hiddev12 c 180 108
-mknod /dev/usb/hiddev13 c 180 109
-mknod /dev/usb/hiddev14 c 180 110
-mknod /dev/usb/hiddev15 c 180 111
+you need the following commands::
+
+	mknod /dev/usb/hiddev0 c 180 96
+	mknod /dev/usb/hiddev1 c 180 97
+	mknod /dev/usb/hiddev2 c 180 98
+	mknod /dev/usb/hiddev3 c 180 99
+	mknod /dev/usb/hiddev4 c 180 100
+	mknod /dev/usb/hiddev5 c 180 101
+	mknod /dev/usb/hiddev6 c 180 102
+	mknod /dev/usb/hiddev7 c 180 103
+	mknod /dev/usb/hiddev8 c 180 104
+	mknod /dev/usb/hiddev9 c 180 105
+	mknod /dev/usb/hiddev10 c 180 106
+	mknod /dev/usb/hiddev11 c 180 107
+	mknod /dev/usb/hiddev12 c 180 108
+	mknod /dev/usb/hiddev13 c 180 109
+	mknod /dev/usb/hiddev14 c 180 110
+	mknod /dev/usb/hiddev15 c 180 111
 
 So you point your hiddev compliant user-space program at the correct
 interface for your device, and it all just works.
@@ -56,7 +61,9 @@ Assuming that you have a hiddev compliant user-space program, of
 course. If you need to write one, read on.
 
 
-THE HIDDEV API
+The HIDDEV API
+==============
+
 This description should be read in conjunction with the HID
 specification, freely available from http://www.usb.org, and
 conveniently linked of http://www.linux-usb.org.
@@ -69,12 +76,14 @@ each of which can have one or more "usages".  In the hid-core,
 each one of these usages has a single signed 32 bit value.
 
 read():
+-------
+
 This is the event interface.  When the HID device's state changes,
 it performs an interrupt transfer containing a report which contains
 the changed value.  The hid-core.c module parses the report, and
 returns to hiddev.c the individual usages that have changed within
 the report.  In its basic mode, the hiddev will make these individual
-usage changes available to the reader using a struct hiddev_event:
+usage changes available to the reader using a struct hiddev_event::
 
        struct hiddev_event {
            unsigned hid;
@@ -90,13 +99,19 @@ behavior of the read() function can be modified using the HIDIOCSFLAG
 ioctl() described below.
 
 
-ioctl(): 
-This is the control interface. There are a number of controls: 
+ioctl():
+--------
 
-HIDIOCGVERSION - int (read)
-Gets the version code out of the hiddev driver.
+This is the control interface. There are a number of controls:
+
+HIDIOCGVERSION
+  - int (read)
+
+ Gets the version code out of the hiddev driver.
+
+HIDIOCAPPLICATION
+  - (none)
 
-HIDIOCAPPLICATION - (none)
 This ioctl call returns the HID application usage associated with the
 hid device. The third argument to ioctl() specifies which application
 index to get. This is useful when the device has more than one
@@ -104,25 +119,33 @@ application collection. If the index is invalid (greater or equal to
 the number of application collections this device has) the ioctl
 returns -1. You can find out beforehand how many application
 collections the device has from the num_applications field from the
-hiddev_devinfo structure. 
+hiddev_devinfo structure.
+
+HIDIOCGCOLLECTIONINFO
+  - struct hiddev_collection_info (read/write)
 
-HIDIOCGCOLLECTIONINFO - struct hiddev_collection_info (read/write)
 This returns a superset of the information above, providing not only
 application collections, but all the collections the device has.  It
 also returns the level the collection lives in the hierarchy.
-The user passes in a hiddev_collection_info struct with the index 
-field set to the index that should be returned.  The ioctl fills in 
-the other fields.  If the index is larger than the last collection 
+The user passes in a hiddev_collection_info struct with the index
+field set to the index that should be returned.  The ioctl fills in
+the other fields.  If the index is larger than the last collection
 index, the ioctl returns -1 and sets errno to -EINVAL.
 
-HIDIOCGDEVINFO - struct hiddev_devinfo (read)
+HIDIOCGDEVINFO
+  - struct hiddev_devinfo (read)
+
 Gets a hiddev_devinfo structure which describes the device.
 
-HIDIOCGSTRING - struct hiddev_string_descriptor (read/write)
+HIDIOCGSTRING
+  - struct hiddev_string_descriptor (read/write)
+
 Gets a string descriptor from the device. The caller must fill in the
 "index" field to indicate which descriptor should be returned.
 
-HIDIOCINITREPORT - (none)
+HIDIOCINITREPORT
+  - (none)
+
 Instructs the kernel to retrieve all input and feature report values
 from the device. At this point, all the usage structures will contain
 current values for the device, and will maintain it as the device
@@ -130,21 +153,29 @@ changes.  Note that the use of this ioctl is unnecessary in general,
 since later kernels automatically initialize the reports from the
 device at attach time.
 
-HIDIOCGNAME - string (variable length)
+HIDIOCGNAME
+  - string (variable length)
+
 Gets the device name
 
-HIDIOCGREPORT - struct hiddev_report_info (write)
+HIDIOCGREPORT
+  - struct hiddev_report_info (write)
+
 Instructs the kernel to get a feature or input report from the device,
 in order to selectively update the usage structures (in contrast to
 INITREPORT).
 
-HIDIOCSREPORT - struct hiddev_report_info (write)
+HIDIOCSREPORT
+  - struct hiddev_report_info (write)
+
 Instructs the kernel to send a report to the device. This report can
 be filled in by the user through HIDIOCSUSAGE calls (below) to fill in
 individual usage values in the report before sending the report in full
-to the device. 
+to the device.
+
+HIDIOCGREPORTINFO
+  - struct hiddev_report_info (read/write)
 
-HIDIOCGREPORTINFO - struct hiddev_report_info (read/write)
 Fills in a hiddev_report_info structure for the user. The report is
 looked up by type (input, output or feature) and id, so these fields
 must be filled in by the user. The ID can be absolute -- the actual
@@ -154,52 +185,67 @@ report_id) for the next report after report_id. Without a-priori
 information about report ids, the right way to use this ioctl is to
 use the relative IDs above to enumerate the valid IDs. The ioctl
 returns non-zero when there is no more next ID. The real report ID is
-filled into the returned hiddev_report_info structure. 
+filled into the returned hiddev_report_info structure.
+
+HIDIOCGFIELDINFO
+  - struct hiddev_field_info (read/write)
 
-HIDIOCGFIELDINFO - struct hiddev_field_info (read/write)
 Returns the field information associated with a report in a
 hiddev_field_info structure. The user must fill in report_id and
 report_type in this structure, as above. The field_index should also
 be filled in, which should be a number from 0 and maxfield-1, as
-returned from a previous HIDIOCGREPORTINFO call. 
+returned from a previous HIDIOCGREPORTINFO call.
+
+HIDIOCGUCODE
+  - struct hiddev_usage_ref (read/write)
 
-HIDIOCGUCODE - struct hiddev_usage_ref (read/write)
 Returns the usage_code in a hiddev_usage_ref structure, given that
 given its report type, report id, field index, and index within the
 field have already been filled into the structure.
 
-HIDIOCGUSAGE - struct hiddev_usage_ref (read/write)
+HIDIOCGUSAGE
+  - struct hiddev_usage_ref (read/write)
+
 Returns the value of a usage in a hiddev_usage_ref structure. The
 usage to be retrieved can be specified as above, or the user can
 choose to fill in the report_type field and specify the report_id as
 HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be
 filled in with the report and field information associated with this
-usage if it is found. 
+usage if it is found.
+
+HIDIOCSUSAGE
+  - struct hiddev_usage_ref (write)
 
-HIDIOCSUSAGE - struct hiddev_usage_ref (write)
 Sets the value of a usage in an output report.  The user fills in
 the hiddev_usage_ref structure as above, but additionally fills in
 the value field.
 
-HIDIOGCOLLECTIONINDEX - struct hiddev_usage_ref (write)
+HIDIOGCOLLECTIONINDEX
+  - struct hiddev_usage_ref (write)
+
 Returns the collection index associated with this usage.  This
 indicates where in the collection hierarchy this usage sits.
 
-HIDIOCGFLAG - int (read)
-HIDIOCSFLAG - int (write)
+HIDIOCGFLAG
+  - int (read)
+HIDIOCSFLAG
+  - int (write)
+
 These operations respectively inspect and replace the mode flags
 that influence the read() call above.  The flags are as follows:
 
-    HIDDEV_FLAG_UREF - read() calls will now return 
+    HIDDEV_FLAG_UREF
+      - read() calls will now return
         struct hiddev_usage_ref instead of struct hiddev_event.
         This is a larger structure, but in situations where the
         device has more than one usage in its reports with the
         same usage code, this mode serves to resolve such
         ambiguity.
 
-    HIDDEV_FLAG_REPORT - This flag can only be used in conjunction
+    HIDDEV_FLAG_REPORT
+      - This flag can only be used in conjunction
         with HIDDEV_FLAG_UREF.  With this flag set, when the device
         sends a report, a struct hiddev_usage_ref will be returned
-        to read() filled in with the report_type and report_id, but 
+        to read() filled in with the report_type and report_id, but
         with field_index set to FIELD_INDEX_NONE.  This serves as
         additional notification when the device has sent a report.
diff --git a/Documentation/hid/hidraw.txt b/Documentation/hid/hidraw.rst
similarity index 89%
rename from Documentation/hid/hidraw.txt
rename to Documentation/hid/hidraw.rst
index c8436e354f44..4a4a0ba1f362 100644
--- a/Documentation/hid/hidraw.txt
+++ b/Documentation/hid/hidraw.rst
@@ -1,5 +1,6 @@
-      HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices
-     ==================================================================
+================================================================
+HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices
+================================================================
 
 The hidraw driver provides a raw interface to USB and Bluetooth Human
 Interface Devices (HIDs).  It differs from hiddev in that reports sent and
@@ -31,6 +32,7 @@ directly under /dev (eg: /dev/hidraw0).  As this location is distribution-
 and udev rule-dependent, applications should use libudev to locate hidraw
 devices attached to the system.  There is a tutorial on libudev with a
 working example at:
+
 	http://www.signal11.us/oss/udev/
 
 The HIDRAW API
@@ -51,7 +53,7 @@ byte.  For devices which do not use numbered reports, the report data
 will begin at the first byte.
 
 write()
---------
+-------
 The write() function will write a report to the device. For USB devices, if
 the device has an INTERRUPT OUT endpoint, the report will be sent on that
 endpoint. If it does not, the report will be sent over the control endpoint,
@@ -62,38 +64,52 @@ number.  If the device does not use numbered reports, the first byte should
 be set to 0. The report data itself should begin at the second byte.
 
 ioctl()
---------
+-------
 Hidraw supports the following ioctls:
 
-HIDIOCGRDESCSIZE: Get Report Descriptor Size
+HIDIOCGRDESCSIZE:
+	Get Report Descriptor Size
+
 This ioctl will get the size of the device's report descriptor.
 
-HIDIOCGRDESC: Get Report Descriptor
+HIDIOCGRDESC:
+	Get Report Descriptor
+
 This ioctl returns the device's report descriptor using a
 hidraw_report_descriptor struct.  Make sure to set the size field of the
 hidraw_report_descriptor struct to the size returned from HIDIOCGRDESCSIZE.
 
-HIDIOCGRAWINFO: Get Raw Info
+HIDIOCGRAWINFO:
+	Get Raw Info
+
 This ioctl will return a hidraw_devinfo struct containing the bus type, the
 vendor ID (VID), and product ID (PID) of the device. The bus type can be one
-of:
-	BUS_USB
-	BUS_HIL
-	BUS_BLUETOOTH
-	BUS_VIRTUAL
+of::
+
+	- BUS_USB
+	- BUS_HIL
+	- BUS_BLUETOOTH
+	- BUS_VIRTUAL
+
 which are defined in uapi/linux/input.h.
 
-HIDIOCGRAWNAME(len): Get Raw Name
+HIDIOCGRAWNAME(len):
+	Get Raw Name
+
 This ioctl returns a string containing the vendor and product strings of
 the device.  The returned string is Unicode, UTF-8 encoded.
 
-HIDIOCGRAWPHYS(len): Get Physical Address
+HIDIOCGRAWPHYS(len):
+	Get Physical Address
+
 This ioctl returns a string representing the physical address of the device.
 For USB devices, the string contains the physical path to the device (the
 USB controller, hubs, ports, etc).  For Bluetooth devices, the string
 contains the hardware (MAC) address of the device.
 
-HIDIOCSFEATURE(len): Send a Feature Report
+HIDIOCSFEATURE(len):
+	Send a Feature Report
+
 This ioctl will send a feature report to the device.  Per the HID
 specification, feature reports are always sent using the control endpoint.
 Set the first byte of the supplied buffer to the report number.  For devices
@@ -101,7 +117,9 @@ which do not use numbered reports, set the first byte to 0. The report data
 begins in the second byte. Make sure to set len accordingly, to one more
 than the length of the report (to account for the report number).
 
-HIDIOCGFEATURE(len): Get a Feature Report
+HIDIOCGFEATURE(len):
+	Get a Feature Report
+
 This ioctl will request a feature report from the device using the control
 endpoint.  The first byte of the supplied buffer should be set to the report
 number of the requested report.  For devices which do not use numbered
@@ -109,11 +127,12 @@ reports, set the first byte to 0.  The report will be returned starting at
 the first byte of the buffer (ie: the report number is not returned).
 
 Example
----------
+-------
 In samples/, find hid-example.c, which shows examples of read(), write(),
 and all the ioctls for hidraw.  The code may be used by anyone for any
 purpose, and can serve as a starting point for developing applications using
 hidraw.
 
 Document by:
+
 	Alan Ott <alan@signal11.us>, Signal 11 Software
diff --git a/Documentation/hid/index.rst b/Documentation/hid/index.rst
new file mode 100644
index 000000000000..af4324902622
--- /dev/null
+++ b/Documentation/hid/index.rst
@@ -0,0 +1,18 @@
+:orphan:
+
+=============================
+Human Interface Devices (HID)
+=============================
+
+.. toctree::
+   :maxdepth: 1
+
+   hiddev
+   hidraw
+   hid-sensor
+   hid-transport
+
+   uhid
+
+   hid-alps
+   intel-ish-hid
diff --git a/Documentation/hid/intel-ish-hid.rst b/Documentation/hid/intel-ish-hid.rst
new file mode 100644
index 000000000000..cccbf4be17d7
--- /dev/null
+++ b/Documentation/hid/intel-ish-hid.rst
@@ -0,0 +1,485 @@
+=================================
+Intel Integrated Sensor Hub (ISH)
+=================================
+
+A sensor hub enables the ability to offload sensor polling and algorithm
+processing to a dedicated low power co-processor. This allows the core
+processor to go into low power modes more often, resulting in the increased
+battery life.
+
+There are many vendors providing external sensor hubs confirming to HID
+Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops
+and embedded products. Linux had this support since Linux 3.9.
+
+Intel® introduced integrated sensor hubs as a part of the SoC starting from
+Cherry Trail and now supported on multiple generations of CPU packages. There
+are many commercial devices already shipped with Integrated Sensor Hubs (ISH).
+These ISH also comply to HID sensor specification, but the  difference is the
+transport protocol used for communication. The current external sensor hubs
+mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB.
+
+1. Overview
+===========
+
+Using a analogy with a usbhid implementation, the ISH follows a similar model
+for a very high speed communication::
+
+	-----------------		----------------------
+	|    USB HID	|	-->	|    ISH HID	     |
+	-----------------		----------------------
+	-----------------		----------------------
+	|  USB protocol	|	-->	|    ISH Transport   |
+	-----------------		----------------------
+	-----------------		----------------------
+	|  EHCI/XHCI	|	-->	|    ISH IPC	     |
+	-----------------		----------------------
+	      PCI				 PCI
+	-----------------		----------------------
+        |Host controller|	-->	|    ISH processor   |
+	-----------------		----------------------
+	     USB Link
+	-----------------		----------------------
+	| USB End points|	-->	|    ISH Clients     |
+	-----------------		----------------------
+
+Like USB protocol provides a method for device enumeration, link management
+and user data encapsulation, the ISH also provides similar services. But it is
+very light weight tailored to manage and communicate with ISH client
+applications implemented in the firmware.
+
+The ISH allows multiple sensor management applications executing in the
+firmware. Like USB endpoints the messaging can be to/from a client. As part of
+enumeration process, these clients are identified. These clients can be simple
+HID sensor applications, sensor calibration application or senor firmware
+update application.
+
+The implementation model is similar, like USB bus, ISH transport is also
+implemented as a bus. Each client application executing in the ISH processor
+is registered as a device on this bus. The driver, which binds each device
+(ISH HID driver) identifies the device type and registers with the hid core.
+
+2. ISH Implementation: Block Diagram
+====================================
+
+::
+
+	 ---------------------------
+	|  User Space Applications  |
+	 ---------------------------
+
+  ----------------IIO ABI----------------
+	 --------------------------
+	|  IIO Sensor Drivers	  |
+	 --------------------------
+	 --------------------------
+	|	 IIO core	  |
+	 --------------------------
+	 --------------------------
+	|   HID Sensor Hub MFD	  |
+	 --------------------------
+	 --------------------------
+	|       HID Core	  |
+	 --------------------------
+	 --------------------------
+	|   HID over ISH Client   |
+	 --------------------------
+	 --------------------------
+	|   ISH Transport (ISHTP) |
+	 --------------------------
+	 --------------------------
+	|      IPC Drivers	  |
+	 --------------------------
+  OS
+  ---------------- PCI -----------------
+  Hardware + Firmware
+	 ----------------------------
+	| ISH Hardware/Firmware(FW) |
+	 ----------------------------
+
+3. High level processing in above blocks
+========================================
+
+3.1 Hardware Interface
+----------------------
+
+The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI
+product and vendor IDs are changed from different generations of processors. So
+the source code which enumerate drivers needs to update from generation to
+generation.
+
+3.2 Inter Processor Communication (IPC) driver
+----------------------------------------------
+
+Location: drivers/hid/intel-ish-hid/ipc
+
+The IPC message used memory mapped I/O. The registers are defined in
+hw-ish-regs.h.
+
+3.2.1 IPC/FW message types
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are two types of messages, one for management of link and other messages
+are to and from transport layers.
+
+TX and RX of Transport messages
+...............................
+
+A set of memory mapped register offers support of multi byte messages TX and
+RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains
+internal queues to sequence messages and send them in order to the FW.
+Optionally the caller can register handler to get notification of completion.
+A door bell mechanism is used in messaging to trigger processing in host and
+client firmware side. When ISH interrupt handler is called, the ISH2HOST
+doorbell register is used by host drivers to determine that the interrupt
+is for ISH.
+
+Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell
+register has the following format:
+Bits 0..6: fragment length (7 bits are used)
+Bits 10..13: encapsulated protocol
+Bits 16..19: management command (for IPC management protocol)
+Bit 31: doorbell trigger (signal H/W interrupt to the other side)
+Other bits are reserved, should be 0.
+
+3.2.2 Transport layer interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To abstract HW level IPC communication, a set of callbacks are registered.
+The transport layer uses them to send and receive messages.
+Refer to  struct ishtp_hw_ops for callbacks.
+
+3.3 ISH Transport layer
+-----------------------
+
+Location: drivers/hid/intel-ish-hid/ishtp/
+
+3.3.1 A Generic Transport Layer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The transport layer is a bi-directional protocol, which defines:
+- Set of commands to start, stop, connect, disconnect and flow control
+(ishtp/hbm.h) for details
+- A flow control mechanism to avoid buffer overflows
+
+This protocol resembles bus messages described in the following document:
+http://www.intel.com/content/dam/www/public/us/en/documents/technical-\
+specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer"
+
+3.3.2 Connection and Flow Control Mechanism
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Each FW client and a protocol is identified by an UUID. In order to communicate
+to a FW client, a connection must be established using connect request and
+response bus messages. If successful, a pair (host_client_id and fw_client_id)
+will identify the connection.
+
+Once connection is established, peers send each other flow control bus messages
+independently. Every peer may send a message only if it has received a
+flow-control credit before. Once it sent a message, it may not send another one
+before receiving the next flow control credit.
+Either side can send disconnect request bus message to end communication. Also
+the link will be dropped if major FW reset occurs.
+
+3.3.3 Peer to Peer data transfer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Peer to Peer data transfer can happen with or without using DMA. Depending on
+the sensor bandwidth requirement DMA can be enabled by using module parameter
+ishtp_use_dma under intel_ishtp.
+
+Each side (host and FW) manages its DMA transfer memory independently. When an
+ISHTP client from either host or FW side wants to send something, it decides
+whether to send over IPC or over DMA; for each transfer the decision is
+independent. The sending side sends DMA_XFER message when the message is in
+the respective host buffer (TX when host client sends, RX when FW client
+sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating
+the sender that the memory region for that message may be reused.
+
+DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message
+(that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK.
+Additionally to DMA address communication, this sequence checks capabilities:
+if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't
+send DMA; if FW doesn't support DMA then it won't respond with
+DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers.
+Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER,
+it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means
+that it already did DMA and the message resides at host. Thus, DMA_XFER
+and DMA_XFER_ACK act as ownership indicators.
+
+At initial state all outgoing memory belongs to the sender (TX to host, RX to
+FW), DMA_XFER transfers ownership on the region that contains ISHTP message to
+the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender
+needs not wait for previous DMA_XFER to be ack'ed, and may send another message
+as long as remaining continuous memory in its ownership is enough.
+In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once
+(up to IPC MTU), thus allowing for interrupt throttling.
+Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC
+fragments and via IPC otherwise.
+
+3.3.4 Ring Buffers
+^^^^^^^^^^^^^^^^^^
+
+When a client initiate a connection, a ring or RX and TX buffers are allocated.
+The size of ring can be specified by the client. HID client set 16 and 32 for
+TX and RX buffers respectively. On send request from client, the data to be
+sent is copied to one of the send ring buffer and scheduled to be sent using
+bus message protocol. These buffers are required because the FW may have not
+have processed the last message and may not have enough flow control credits
+to send. Same thing holds true on receive side and flow control is required.
+
+3.3.5 Host Enumeration
+^^^^^^^^^^^^^^^^^^^^^^
+
+The host enumeration bus command allow discovery of clients present in the FW.
+There can be multiple sensor clients and clients for calibration function.
+
+To ease in implantation and allow independent driver handle each client
+this transport layer takes advantage of Linux Bus driver model. Each
+client is registered as device on the the transport bus (ishtp bus).
+
+Enumeration sequence of messages:
+
+- Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up.
+- FW responds with HOST_START_RES_CMD
+- Host sends HOST_ENUM_REQ_CMD (enumerate FW clients)
+- FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW
+  client IDs
+- For each FW ID found in that bitmap host sends
+  HOST_CLIENT_PROPERTIES_REQ_CMD
+- FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID,
+  max ISHTP message size, etc.
+- Once host received properties for that last discovered client, it considers
+  ISHTP device fully functional (and allocates DMA buffers)
+
+3.4 HID over ISH Client
+-----------------------
+
+Location: drivers/hid/intel-ish-hid
+
+The ISHTP client driver is responsible for:
+
+- enumerate HID devices under FW ISH client
+- Get Report descriptor
+- Register with HID core as a LL driver
+- Process Get/Set feature request
+- Get input reports
+
+3.5 HID Sensor Hub MFD and IIO sensor drivers
+---------------------------------------------
+
+The functionality in these drivers is the same as an external sensor hub.
+Refer to
+Documentation/hid/hid-sensor.rst for HID sensor
+Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space
+
+3.6 End to End HID transport Sequence Diagram
+---------------------------------------------
+
+::
+
+  HID-ISH-CLN                    ISHTP                    IPC                             HW
+          |                        |                       |                               |
+          |                        |                       |-----WAKE UP------------------>|
+          |                        |                       |                               |
+          |                        |                       |-----HOST READY--------------->|
+          |                        |                       |                               |
+          |                        |                       |<----MNG_RESET_NOTIFY_ACK----- |
+          |                        |                       |                               |
+          |                        |<----ISHTP_START------ |                               |
+          |                        |                       |                               |
+          |                        |<-----------------HOST_START_RES_CMD-------------------|
+          |                        |                       |                               |
+          |                        |------------------QUERY_SUBSCRIBER-------------------->|
+          |                        |                       |                               |
+          |                        |------------------HOST_ENUM_REQ_CMD------------------->|
+          |                        |                       |                               |
+          |                        |<-----------------HOST_ENUM_RES_CMD--------------------|
+          |                        |                       |                               |
+          |                        |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
+          |                        |                       |                               |
+          |                        |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
+          |       Create new device on in ishtp bus        |                               |
+          |                        |                       |                               |
+          |                        |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
+          |                        |                       |                               |
+          |                        |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
+          |       Create new device on in ishtp bus        |                               |
+          |                        |                       |                               |
+          |                        |--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--|
+          |                        |                       |                               |
+       probed()
+          |----ishtp_cl_connect--->|----------------- CLIENT_CONNECT_REQ_CMD-------------->|
+          |                        |                       |                               |
+          |                        |<----------------CLIENT_CONNECT_RES_CMD----------------|
+          |                        |                       |                               |
+          |register event callback |                       |                               |
+          |                        |                       |                               |
+          |ishtp_cl_send(
+          HOSTIF_DM_ENUM_DEVICES)  |----------fill ishtp_msg_hdr struct write to HW-----  >|
+          |                        |                       |                               |
+          |                        |                       |<-----IRQ(IPC_PROTOCOL_ISHTP---|
+          |                        |                       |                               |
+          |<--ENUM_DEVICE RSP------|                       |                               |
+          |                        |                       |                               |
+  for each enumerated device
+          |ishtp_cl_send(
+          HOSTIF_GET_HID_DESCRIPTOR|----------fill ishtp_msg_hdr struct write to HW-----  >|
+          |                        |                       |                               |
+          ...Response
+          |                        |                       |                               |
+  for each enumerated device
+          |ishtp_cl_send(
+       HOSTIF_GET_REPORT_DESCRIPTOR|--------------fill ishtp_msg_hdr struct write to HW-- >|
+          |                        |                       |                               |
+          |                        |                       |                               |
+   hid_allocate_device
+          |                        |                       |                               |
+   hid_add_device                  |                       |                               |
+          |                        |                       |                               |
+
+
+3.7 ISH Debugging
+-----------------
+
+To debug ISH, event tracing mechanism is used. To enable debug logs
+echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable
+cat sys/kernel/debug/tracing/trace
+
+3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260
+-----------------------------------------------------
+
+::
+
+  root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/
+  /sys/bus/iio/devices/
+  ├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0
+  │   ├── buffer
+  │   │   ├── enable
+  │   │   ├── length
+  │   │   └── watermark
+  ...
+  │   ├── in_accel_hysteresis
+  │   ├── in_accel_offset
+  │   ├── in_accel_sampling_frequency
+  │   ├── in_accel_scale
+  │   ├── in_accel_x_raw
+  │   ├── in_accel_y_raw
+  │   ├── in_accel_z_raw
+  │   ├── name
+  │   ├── scan_elements
+  │   │   ├── in_accel_x_en
+  │   │   ├── in_accel_x_index
+  │   │   ├── in_accel_x_type
+  │   │   ├── in_accel_y_en
+  │   │   ├── in_accel_y_index
+  │   │   ├── in_accel_y_type
+  │   │   ├── in_accel_z_en
+  │   │   ├── in_accel_z_index
+  │   │   └── in_accel_z_type
+  ...
+  │   │   ├── devices
+  │   │   │   │   ├── buffer
+  │   │   │   │   │   ├── enable
+  │   │   │   │   │   ├── length
+  │   │   │   │   │   └── watermark
+  │   │   │   │   ├── dev
+  │   │   │   │   ├── in_intensity_both_raw
+  │   │   │   │   ├── in_intensity_hysteresis
+  │   │   │   │   ├── in_intensity_offset
+  │   │   │   │   ├── in_intensity_sampling_frequency
+  │   │   │   │   ├── in_intensity_scale
+  │   │   │   │   ├── name
+  │   │   │   │   ├── scan_elements
+  │   │   │   │   │   ├── in_intensity_both_en
+  │   │   │   │   │   ├── in_intensity_both_index
+  │   │   │   │   │   └── in_intensity_both_type
+  │   │   │   │   ├── trigger
+  │   │   │   │   │   └── current_trigger
+  ...
+  │   │   │   │   ├── buffer
+  │   │   │   │   │   ├── enable
+  │   │   │   │   │   ├── length
+  │   │   │   │   │   └── watermark
+  │   │   │   │   ├── dev
+  │   │   │   │   ├── in_magn_hysteresis
+  │   │   │   │   ├── in_magn_offset
+  │   │   │   │   ├── in_magn_sampling_frequency
+  │   │   │   │   ├── in_magn_scale
+  │   │   │   │   ├── in_magn_x_raw
+  │   │   │   │   ├── in_magn_y_raw
+  │   │   │   │   ├── in_magn_z_raw
+  │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_raw
+  │   │   │   │   ├── in_rot_hysteresis
+  │   │   │   │   ├── in_rot_offset
+  │   │   │   │   ├── in_rot_sampling_frequency
+  │   │   │   │   ├── in_rot_scale
+  │   │   │   │   ├── name
+  ...
+  │   │   │   │   ├── scan_elements
+  │   │   │   │   │   ├── in_magn_x_en
+  │   │   │   │   │   ├── in_magn_x_index
+  │   │   │   │   │   ├── in_magn_x_type
+  │   │   │   │   │   ├── in_magn_y_en
+  │   │   │   │   │   ├── in_magn_y_index
+  │   │   │   │   │   ├── in_magn_y_type
+  │   │   │   │   │   ├── in_magn_z_en
+  │   │   │   │   │   ├── in_magn_z_index
+  │   │   │   │   │   ├── in_magn_z_type
+  │   │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_en
+  │   │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_index
+  │   │   │   │   │   └── in_rot_from_north_magnetic_tilt_comp_type
+  │   │   │   │   ├── trigger
+  │   │   │   │   │   └── current_trigger
+  ...
+  │   │   │   │   ├── buffer
+  │   │   │   │   │   ├── enable
+  │   │   │   │   │   ├── length
+  │   │   │   │   │   └── watermark
+  │   │   │   │   ├── dev
+  │   │   │   │   ├── in_anglvel_hysteresis
+  │   │   │   │   ├── in_anglvel_offset
+  │   │   │   │   ├── in_anglvel_sampling_frequency
+  │   │   │   │   ├── in_anglvel_scale
+  │   │   │   │   ├── in_anglvel_x_raw
+  │   │   │   │   ├── in_anglvel_y_raw
+  │   │   │   │   ├── in_anglvel_z_raw
+  │   │   │   │   ├── name
+  │   │   │   │   ├── scan_elements
+  │   │   │   │   │   ├── in_anglvel_x_en
+  │   │   │   │   │   ├── in_anglvel_x_index
+  │   │   │   │   │   ├── in_anglvel_x_type
+  │   │   │   │   │   ├── in_anglvel_y_en
+  │   │   │   │   │   ├── in_anglvel_y_index
+  │   │   │   │   │   ├── in_anglvel_y_type
+  │   │   │   │   │   ├── in_anglvel_z_en
+  │   │   │   │   │   ├── in_anglvel_z_index
+  │   │   │   │   │   └── in_anglvel_z_type
+  │   │   │   │   ├── trigger
+  │   │   │   │   │   └── current_trigger
+  ...
+  │   │   │   │   ├── buffer
+  │   │   │   │   │   ├── enable
+  │   │   │   │   │   ├── length
+  │   │   │   │   │   └── watermark
+  │   │   │   │   ├── dev
+  │   │   │   │   ├── in_anglvel_hysteresis
+  │   │   │   │   ├── in_anglvel_offset
+  │   │   │   │   ├── in_anglvel_sampling_frequency
+  │   │   │   │   ├── in_anglvel_scale
+  │   │   │   │   ├── in_anglvel_x_raw
+  │   │   │   │   ├── in_anglvel_y_raw
+  │   │   │   │   ├── in_anglvel_z_raw
+  │   │   │   │   ├── name
+  │   │   │   │   ├── scan_elements
+  │   │   │   │   │   ├── in_anglvel_x_en
+  │   │   │   │   │   ├── in_anglvel_x_index
+  │   │   │   │   │   ├── in_anglvel_x_type
+  │   │   │   │   │   ├── in_anglvel_y_en
+  │   │   │   │   │   ├── in_anglvel_y_index
+  │   │   │   │   │   ├── in_anglvel_y_type
+  │   │   │   │   │   ├── in_anglvel_z_en
+  │   │   │   │   │   ├── in_anglvel_z_index
+  │   │   │   │   │   └── in_anglvel_z_type
+  │   │   │   │   ├── trigger
+  │   │   │   │   │   └── current_trigger
+  ...
diff --git a/Documentation/hid/intel-ish-hid.txt b/Documentation/hid/intel-ish-hid.txt
deleted file mode 100644
index d48b21c71ddd..000000000000
--- a/Documentation/hid/intel-ish-hid.txt
+++ /dev/null
@@ -1,454 +0,0 @@
-Intel Integrated Sensor Hub (ISH)
-===============================
-
-A sensor hub enables the ability to offload sensor polling and algorithm
-processing to a dedicated low power co-processor. This allows the core
-processor to go into low power modes more often, resulting in the increased
-battery life.
-
-There are many vendors providing external sensor hubs confirming to HID
-Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops
-and embedded products. Linux had this support since Linux 3.9.
-
-Intel® introduced integrated sensor hubs as a part of the SoC starting from
-Cherry Trail and now supported on multiple generations of CPU packages. There
-are many commercial devices already shipped with Integrated Sensor Hubs (ISH).
-These ISH also comply to HID sensor specification, but the  difference is the
-transport protocol used for communication. The current external sensor hubs
-mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB.
-
-1. Overview
-
-Using a analogy with a usbhid implementation, the ISH follows a similar model
-for a very high speed communication:
-
-	-----------------		----------------------
-	|    USB HID	|	-->	|    ISH HID	     |
-	-----------------		----------------------
-	-----------------		----------------------
-	|  USB protocol	|	-->	|    ISH Transport   |
-	-----------------		----------------------
-	-----------------		----------------------
-	|  EHCI/XHCI	|	-->	|    ISH IPC	     |
-	-----------------		----------------------
-	      PCI				 PCI
-	-----------------		----------------------
-        |Host controller|	-->	|    ISH processor   |
-	-----------------		----------------------
-	     USB Link
-	-----------------		----------------------
-	| USB End points|	-->	|    ISH Clients     |
-	-----------------		----------------------
-
-Like USB protocol provides a method for device enumeration, link management
-and user data encapsulation, the ISH also provides similar services. But it is
-very light weight tailored to manage and communicate with ISH client
-applications implemented in the firmware.
-
-The ISH allows multiple sensor management applications executing in the
-firmware. Like USB endpoints the messaging can be to/from a client. As part of
-enumeration process, these clients are identified. These clients can be simple
-HID sensor applications, sensor calibration application or senor firmware
-update application.
-
-The implementation model is similar, like USB bus, ISH transport is also
-implemented as a bus. Each client application executing in the ISH processor
-is registered as a device on this bus. The driver, which binds each device
-(ISH HID driver) identifies the device type and registers with the hid core.
-
-2. ISH Implementation: Block Diagram
-
-	 ---------------------------
-	|  User Space Applications  |
-	 ---------------------------
-
-----------------IIO ABI----------------
-	 --------------------------
-	|  IIO Sensor Drivers	  |
-	 --------------------------
-	 --------------------------
-	|	 IIO core	  |
-	 --------------------------
-	 --------------------------
-	|   HID Sensor Hub MFD	  |
-	 --------------------------
-	 --------------------------
-	|       HID Core	  |
-	 --------------------------
-	 --------------------------
-	|   HID over ISH Client   |
-	 --------------------------
-	 --------------------------
-	|   ISH Transport (ISHTP) |
-	 --------------------------
-	 --------------------------
-	|      IPC Drivers	  |
-	 --------------------------
-OS
-----------------   PCI -----------------
-Hardware + Firmware
-	 ----------------------------
-	| ISH Hardware/Firmware(FW) |
-	 ----------------------------
-
-3. High level processing in above blocks
-
-3.1 Hardware Interface
-
-The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI
-product and vendor IDs are changed from different generations of processors. So
-the source code which enumerate drivers needs to update from generation to
-generation.
-
-3.2 Inter Processor Communication (IPC) driver
-Location: drivers/hid/intel-ish-hid/ipc
-
-The IPC message used memory mapped I/O. The registers are defined in
-hw-ish-regs.h.
-
-3.2.1 IPC/FW message types
-
-There are two types of messages, one for management of link and other messages
-are to and from transport layers.
-
-TX and RX of Transport messages
-
-A set of memory mapped register offers support of multi byte messages TX and
-RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains
-internal queues to sequence messages and send them in order to the FW.
-Optionally the caller can register handler to get notification of completion.
-A door bell mechanism is used in messaging to trigger processing in host and
-client firmware side. When ISH interrupt handler is called, the ISH2HOST
-doorbell register is used by host drivers to determine that the interrupt
-is for ISH.
-
-Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell
-register has the following format:
-Bits 0..6: fragment length (7 bits are used)
-Bits 10..13: encapsulated protocol
-Bits 16..19: management command (for IPC management protocol)
-Bit 31: doorbell trigger (signal H/W interrupt to the other side)
-Other bits are reserved, should be 0.
-
-3.2.2 Transport layer interface
-
-To abstract HW level IPC communication, a set of callbacks are registered.
-The transport layer uses them to send and receive messages.
-Refer to  struct ishtp_hw_ops for callbacks.
-
-3.3 ISH Transport layer
-Location: drivers/hid/intel-ish-hid/ishtp/
-
-3.3.1 A Generic Transport Layer
-
-The transport layer is a bi-directional protocol, which defines:
-- Set of commands to start, stop, connect, disconnect and flow control
-(ishtp/hbm.h) for details
-- A flow control mechanism to avoid buffer overflows
-
-This protocol resembles bus messages described in the following document:
-http://www.intel.com/content/dam/www/public/us/en/documents/technical-\
-specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer"
-
-3.3.2 Connection and Flow Control Mechanism
-
-Each FW client and a protocol is identified by an UUID. In order to communicate
-to a FW client, a connection must be established using connect request and
-response bus messages. If successful, a pair (host_client_id and fw_client_id)
-will identify the connection.
-
-Once connection is established, peers send each other flow control bus messages
-independently. Every peer may send a message only if it has received a
-flow-control credit before. Once it sent a message, it may not send another one
-before receiving the next flow control credit.
-Either side can send disconnect request bus message to end communication. Also
-the link will be dropped if major FW reset occurs.
-
-3.3.3 Peer to Peer data transfer
-
-Peer to Peer data transfer can happen with or without using DMA. Depending on
-the sensor bandwidth requirement DMA can be enabled by using module parameter
-ishtp_use_dma under intel_ishtp.
-
-Each side (host and FW) manages its DMA transfer memory independently. When an
-ISHTP client from either host or FW side wants to send something, it decides
-whether to send over IPC or over DMA; for each transfer the decision is
-independent. The sending side sends DMA_XFER message when the message is in
-the respective host buffer (TX when host client sends, RX when FW client
-sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating
-the sender that the memory region for that message may be reused.
-
-DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message
-(that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK.
-Additionally to DMA address communication, this sequence checks capabilities:
-if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't
-send DMA; if FW doesn't support DMA then it won't respond with
-DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers.
-Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER,
-it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means
-that it already did DMA and the message resides at host. Thus, DMA_XFER
-and DMA_XFER_ACK act as ownership indicators.
-
-At initial state all outgoing memory belongs to the sender (TX to host, RX to
-FW), DMA_XFER transfers ownership on the region that contains ISHTP message to
-the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender
-needs not wait for previous DMA_XFER to be ack'ed, and may send another message
-as long as remaining continuous memory in its ownership is enough.
-In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once
-(up to IPC MTU), thus allowing for interrupt throttling.
-Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC
-fragments and via IPC otherwise.
-
-3.3.4 Ring Buffers
-
-When a client initiate a connection, a ring or RX and TX buffers are allocated.
-The size of ring can be specified by the client. HID client set 16 and 32 for
-TX and RX buffers respectively. On send request from client, the data to be
-sent is copied to one of the send ring buffer and scheduled to be sent using
-bus message protocol. These buffers are required because the FW may have not
-have processed the last message and may not have enough flow control credits
-to send. Same thing holds true on receive side and flow control is required.
-
-3.3.5 Host Enumeration
-
-The host enumeration bus command allow discovery of clients present in the FW.
-There can be multiple sensor clients and clients for calibration function.
-
-To ease in implantation and allow independent driver handle each client
-this transport layer takes advantage of Linux Bus driver model. Each
-client is registered as device on the the transport bus (ishtp bus).
-
-Enumeration sequence of messages:
-- Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up.
-- FW responds with HOST_START_RES_CMD
-- Host sends HOST_ENUM_REQ_CMD (enumerate FW clients)
-- FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW
-client IDs
-- For each FW ID found in that bitmap host sends
-HOST_CLIENT_PROPERTIES_REQ_CMD
-- FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID,
-max ISHTP message size, etc.
-- Once host received properties for that last discovered client, it considers
-ISHTP device fully functional (and allocates DMA buffers)
-
-3.4 HID over ISH Client
-Location: drivers/hid/intel-ish-hid
-
-The ISHTP client driver is responsible for:
-- enumerate HID devices under FW ISH client
-- Get Report descriptor
-- Register with HID core as a LL driver
-- Process Get/Set feature request
-- Get input reports
-
-3.5 HID Sensor Hub MFD and IIO sensor drivers
-
-The functionality in these drivers is the same as an external sensor hub.
-Refer to
-Documentation/hid/hid-sensor.txt for HID sensor
-Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space
-
-3.6 End to End HID transport Sequence Diagram
-
-HID-ISH-CLN			ISHTP			IPC				HW
-	|			|			|				|
-	|			|			|-----WAKE UP------------------>|
-	|			|			|				|
-	|			|			|-----HOST READY--------------->|
-	|			|			|				|
-	|			|			|<----MNG_RESET_NOTIFY_ACK----- |
-	|			|			|				|
-	|			|<----ISHTP_START------ |				|
-	|			|			|				|
-	|			|<-----------------HOST_START_RES_CMD-------------------|
-	|			|			|				|
-	|			|------------------QUERY_SUBSCRIBER-------------------->|
-	|			|			|				|
-	|			|------------------HOST_ENUM_REQ_CMD------------------->|
-	|			|			|				|
-	|			|<-----------------HOST_ENUM_RES_CMD--------------------|
-	|			|			|				|
-	|			|------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
-	|			|			|				|
-	|			|<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
-	|	Create new device on in ishtp bus	|				|
-	|			|			|				|
-	|			|------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
-	|			|			|				|
-	|			|<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
-	|	Create new device on in ishtp bus	|				|
-	|			|			|				|
-	|			|--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--|
-	|			|			|				|
-     probed()
-	|----ishtp_cl_connect-->|----------------- CLIENT_CONNECT_REQ_CMD-------------->|
-	|			|			|				|
-	|			|<----------------CLIENT_CONNECT_RES_CMD----------------|
-	|			|			|				|
-	|register event callback|			|				|
-	|			|			|				|
-	|ishtp_cl_send(
-	HOSTIF_DM_ENUM_DEVICES) |----------fill ishtp_msg_hdr struct write to HW-----  >|
-	|			|			|				|
-	|			|			|<-----IRQ(IPC_PROTOCOL_ISHTP---|
-	|			|			|				|
-	|<--ENUM_DEVICE RSP-----|			|				|
-	|			|			|				|
-for each enumerated device
-	|ishtp_cl_send(
-	HOSTIF_GET_HID_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW---  >|
-	|			|			|				|
-	...Response
-	|			|			|				|
-for each enumerated device
-	|ishtp_cl_send(
-	HOSTIF_GET_REPORT_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW- >|
-	|			|			|				|
-	|			|			|				|
- hid_allocate_device
-	|			|			|				|
- hid_add_device			|			|				|
-	|			|			|				|
-
-
-3.7 ISH Debugging
-
-To debug ISH, event tracing mechanism is used. To enable debug logs
-echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable
-cat sys/kernel/debug/tracing/trace
-
-3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260
-
-root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/
-/sys/bus/iio/devices/
-├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0
-│   ├── buffer
-│   │   ├── enable
-│   │   ├── length
-│   │   └── watermark
-...
-│   ├── in_accel_hysteresis
-│   ├── in_accel_offset
-│   ├── in_accel_sampling_frequency
-│   ├── in_accel_scale
-│   ├── in_accel_x_raw
-│   ├── in_accel_y_raw
-│   ├── in_accel_z_raw
-│   ├── name
-│   ├── scan_elements
-│   │   ├── in_accel_x_en
-│   │   ├── in_accel_x_index
-│   │   ├── in_accel_x_type
-│   │   ├── in_accel_y_en
-│   │   ├── in_accel_y_index
-│   │   ├── in_accel_y_type
-│   │   ├── in_accel_z_en
-│   │   ├── in_accel_z_index
-│   │   └── in_accel_z_type
-...
-│   │   ├── devices
-│   │   │   │   ├── buffer
-│   │   │   │   │   ├── enable
-│   │   │   │   │   ├── length
-│   │   │   │   │   └── watermark
-│   │   │   │   ├── dev
-│   │   │   │   ├── in_intensity_both_raw
-│   │   │   │   ├── in_intensity_hysteresis
-│   │   │   │   ├── in_intensity_offset
-│   │   │   │   ├── in_intensity_sampling_frequency
-│   │   │   │   ├── in_intensity_scale
-│   │   │   │   ├── name
-│   │   │   │   ├── scan_elements
-│   │   │   │   │   ├── in_intensity_both_en
-│   │   │   │   │   ├── in_intensity_both_index
-│   │   │   │   │   └── in_intensity_both_type
-│   │   │   │   ├── trigger
-│   │   │   │   │   └── current_trigger
-...
-│   │   │   │   ├── buffer
-│   │   │   │   │   ├── enable
-│   │   │   │   │   ├── length
-│   │   │   │   │   └── watermark
-│   │   │   │   ├── dev
-│   │   │   │   ├── in_magn_hysteresis
-│   │   │   │   ├── in_magn_offset
-│   │   │   │   ├── in_magn_sampling_frequency
-│   │   │   │   ├── in_magn_scale
-│   │   │   │   ├── in_magn_x_raw
-│   │   │   │   ├── in_magn_y_raw
-│   │   │   │   ├── in_magn_z_raw
-│   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_raw
-│   │   │   │   ├── in_rot_hysteresis
-│   │   │   │   ├── in_rot_offset
-│   │   │   │   ├── in_rot_sampling_frequency
-│   │   │   │   ├── in_rot_scale
-│   │   │   │   ├── name
-...
-│   │   │   │   ├── scan_elements
-│   │   │   │   │   ├── in_magn_x_en
-│   │   │   │   │   ├── in_magn_x_index
-│   │   │   │   │   ├── in_magn_x_type
-│   │   │   │   │   ├── in_magn_y_en
-│   │   │   │   │   ├── in_magn_y_index
-│   │   │   │   │   ├── in_magn_y_type
-│   │   │   │   │   ├── in_magn_z_en
-│   │   │   │   │   ├── in_magn_z_index
-│   │   │   │   │   ├── in_magn_z_type
-│   │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_en
-│   │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_index
-│   │   │   │   │   └── in_rot_from_north_magnetic_tilt_comp_type
-│   │   │   │   ├── trigger
-│   │   │   │   │   └── current_trigger
-...
-│   │   │   │   ├── buffer
-│   │   │   │   │   ├── enable
-│   │   │   │   │   ├── length
-│   │   │   │   │   └── watermark
-│   │   │   │   ├── dev
-│   │   │   │   ├── in_anglvel_hysteresis
-│   │   │   │   ├── in_anglvel_offset
-│   │   │   │   ├── in_anglvel_sampling_frequency
-│   │   │   │   ├── in_anglvel_scale
-│   │   │   │   ├── in_anglvel_x_raw
-│   │   │   │   ├── in_anglvel_y_raw
-│   │   │   │   ├── in_anglvel_z_raw
-│   │   │   │   ├── name
-│   │   │   │   ├── scan_elements
-│   │   │   │   │   ├── in_anglvel_x_en
-│   │   │   │   │   ├── in_anglvel_x_index
-│   │   │   │   │   ├── in_anglvel_x_type
-│   │   │   │   │   ├── in_anglvel_y_en
-│   │   │   │   │   ├── in_anglvel_y_index
-│   │   │   │   │   ├── in_anglvel_y_type
-│   │   │   │   │   ├── in_anglvel_z_en
-│   │   │   │   │   ├── in_anglvel_z_index
-│   │   │   │   │   └── in_anglvel_z_type
-│   │   │   │   ├── trigger
-│   │   │   │   │   └── current_trigger
-...
-│   │   │   │   ├── buffer
-│   │   │   │   │   ├── enable
-│   │   │   │   │   ├── length
-│   │   │   │   │   └── watermark
-│   │   │   │   ├── dev
-│   │   │   │   ├── in_anglvel_hysteresis
-│   │   │   │   ├── in_anglvel_offset
-│   │   │   │   ├── in_anglvel_sampling_frequency
-│   │   │   │   ├── in_anglvel_scale
-│   │   │   │   ├── in_anglvel_x_raw
-│   │   │   │   ├── in_anglvel_y_raw
-│   │   │   │   ├── in_anglvel_z_raw
-│   │   │   │   ├── name
-│   │   │   │   ├── scan_elements
-│   │   │   │   │   ├── in_anglvel_x_en
-│   │   │   │   │   ├── in_anglvel_x_index
-│   │   │   │   │   ├── in_anglvel_x_type
-│   │   │   │   │   ├── in_anglvel_y_en
-│   │   │   │   │   ├── in_anglvel_y_index
-│   │   │   │   │   ├── in_anglvel_y_type
-│   │   │   │   │   ├── in_anglvel_z_en
-│   │   │   │   │   ├── in_anglvel_z_index
-│   │   │   │   │   └── in_anglvel_z_type
-│   │   │   │   ├── trigger
-│   │   │   │   │   └── current_trigger
-...
diff --git a/Documentation/hid/uhid.txt b/Documentation/hid/uhid.rst
similarity index 94%
rename from Documentation/hid/uhid.txt
rename to Documentation/hid/uhid.rst
index 958fff945304..b18cb96c885f 100644
--- a/Documentation/hid/uhid.txt
+++ b/Documentation/hid/uhid.rst
@@ -1,5 +1,6 @@
-      UHID - User-space I/O driver support for HID subsystem
-     ========================================================
+======================================================
+UHID - User-space I/O driver support for HID subsystem
+======================================================
 
 UHID allows user-space to implement HID transport drivers. Please see
 hid-transport.txt for an introduction into HID transport drivers. This document
@@ -22,9 +23,9 @@ If a new device is detected by your HID I/O Driver and you want to register this
 device with the HID subsystem, then you need to open /dev/uhid once for each
 device you want to register. All further communication is done by read()'ing or
 write()'ing "struct uhid_event" objects. Non-blocking operations are supported
-by setting O_NONBLOCK.
+by setting O_NONBLOCK::
 
-struct uhid_event {
+  struct uhid_event {
         __u32 type;
         union {
                 struct uhid_create2_req create2;
@@ -32,7 +33,7 @@ struct uhid_event {
                 struct uhid_input2_req input2;
                 ...
         } u;
-};
+  };
 
 The "type" field contains the ID of the event. Depending on the ID different
 payloads are sent. You must not split a single event across multiple read()'s or
@@ -86,31 +87,31 @@ the request was handled successfully. O_NONBLOCK does not affect write() as
 writes are always handled immediately in a non-blocking fashion. Future requests
 might make use of O_NONBLOCK, though.
 
-  UHID_CREATE2:
+UHID_CREATE2:
   This creates the internal HID device. No I/O is possible until you send this
   event to the kernel. The payload is of type struct uhid_create2_req and
   contains information about your device. You can start I/O now.
 
-  UHID_DESTROY:
+UHID_DESTROY:
   This destroys the internal HID device. No further I/O will be accepted. There
   may still be pending messages that you can receive with read() but no further
   UHID_INPUT events can be sent to the kernel.
   You can create a new device by sending UHID_CREATE2 again. There is no need to
   reopen the character device.
 
-  UHID_INPUT2:
+UHID_INPUT2:
   You must send UHID_CREATE2 before sending input to the kernel! This event
   contains a data-payload. This is the raw data that you read from your device
   on the interrupt channel. The kernel will parse the HID reports.
 
-  UHID_GET_REPORT_REPLY:
+UHID_GET_REPORT_REPLY:
   If you receive a UHID_GET_REPORT request you must answer with this request.
   You  must copy the "id" field from the request into the answer. Set the "err"
   field to 0 if no error occurred or to EIO if an I/O error occurred.
   If "err" is 0 then you should fill the buffer of the answer with the results
   of the GET_REPORT request and set "size" correspondingly.
 
-  UHID_SET_REPORT_REPLY:
+UHID_SET_REPORT_REPLY:
   This is the SET_REPORT equivalent of UHID_GET_REPORT_REPLY. Unlike GET_REPORT,
   SET_REPORT never returns a data buffer, therefore, it's sufficient to set the
   "id" and "err" fields correctly.
@@ -120,16 +121,18 @@ read()
 read() will return a queued output report. No reaction is required to any of
 them but you should handle them according to your needs.
 
-  UHID_START:
+UHID_START:
   This is sent when the HID device is started. Consider this as an answer to
   UHID_CREATE2. This is always the first event that is sent. Note that this
   event might not be available immediately after write(UHID_CREATE2) returns.
   Device drivers might required delayed setups.
   This event contains a payload of type uhid_start_req. The "dev_flags" field
   describes special behaviors of a device. The following flags are defined:
-      UHID_DEV_NUMBERED_FEATURE_REPORTS:
-      UHID_DEV_NUMBERED_OUTPUT_REPORTS:
-      UHID_DEV_NUMBERED_INPUT_REPORTS:
+
+      - UHID_DEV_NUMBERED_FEATURE_REPORTS
+      - UHID_DEV_NUMBERED_OUTPUT_REPORTS
+      - UHID_DEV_NUMBERED_INPUT_REPORTS
+
           Each of these flags defines whether a given report-type uses numbered
           reports. If numbered reports are used for a type, all messages from
           the kernel already have the report-number as prefix. Otherwise, no
@@ -137,33 +140,35 @@ them but you should handle them according to your needs.
           For messages sent by user-space to the kernel, you must adjust the
           prefixes according to these flags.
 
-  UHID_STOP:
+UHID_STOP:
   This is sent when the HID device is stopped. Consider this as an answer to
   UHID_DESTROY.
+
   If you didn't destroy your device via UHID_DESTROY, but the kernel sends an
   UHID_STOP event, this should usually be ignored. It means that the kernel
   reloaded/changed the device driver loaded on your HID device (or some other
   maintenance actions happened).
+
   You can usually ignored any UHID_STOP events safely.
 
-  UHID_OPEN:
+UHID_OPEN:
   This is sent when the HID device is opened. That is, the data that the HID
   device provides is read by some other process. You may ignore this event but
   it is useful for power-management. As long as you haven't received this event
   there is actually no other process that reads your data so there is no need to
   send UHID_INPUT2 events to the kernel.
 
-  UHID_CLOSE:
+UHID_CLOSE:
   This is sent when there are no more processes which read the HID data. It is
   the counterpart of UHID_OPEN and you may as well ignore this event.
 
-  UHID_OUTPUT:
+UHID_OUTPUT:
   This is sent if the HID device driver wants to send raw data to the I/O
   device on the interrupt channel. You should read the payload and forward it to
   the device. The payload is of type "struct uhid_output_req".
   This may be received even though you haven't received UHID_OPEN, yet.
 
-  UHID_GET_REPORT:
+UHID_GET_REPORT:
   This event is sent if the kernel driver wants to perform a GET_REPORT request
   on the control channeld as described in the HID specs. The report-type and
   report-number are available in the payload.
@@ -177,11 +182,12 @@ them but you should handle them according to your needs.
   timed out, the kernel will ignore the response silently. The "id" field is
   never re-used, so conflicts cannot happen.
 
-  UHID_SET_REPORT:
+UHID_SET_REPORT:
   This is the SET_REPORT equivalent of UHID_GET_REPORT. On receipt, you shall
   send a SET_REPORT request to your hid device. Once it replies, you must tell
   the kernel about it via UHID_SET_REPORT_REPLY.
   The same restrictions as for UHID_GET_REPORT apply.
 
 ----------------------------------------------------
+
 Written 2012, David Herrmann <dh.herrmann@gmail.com>
diff --git a/Documentation/input/input.rst b/Documentation/input/input.rst
index 47f86a4bf16c..0eb61e67a7b7 100644
--- a/Documentation/input/input.rst
+++ b/Documentation/input/input.rst
@@ -188,7 +188,7 @@ LCDs and many other purposes.
 
 The monitor and speaker controls should be easy to add to the hid/input
 interface, but for the UPSs and LCDs it doesn't make much sense. For this,
-the hiddev interface was designed. See Documentation/hid/hiddev.txt
+the hiddev interface was designed. See Documentation/hid/hiddev.rst
 for more information about it.
 
 The usage of the usbhid module is very simple, it takes no parameters,
diff --git a/MAINTAINERS b/MAINTAINERS
index 8d39979e4091..969225e6bfce 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -16383,7 +16383,7 @@ M:	Benjamin Tissoires <benjamin.tissoires@redhat.com>
 L:	linux-usb@vger.kernel.org
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/hid/hid.git
 S:	Maintained
-F:	Documentation/hid/hiddev.txt
+F:	Documentation/hid/hiddev.rst
 F:	drivers/hid/usbhid/
 
 USB INTEL XHCI ROLE MUX DRIVER
-- 
2.21.0


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 21/31] docs: ia64: convert to ReST
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (18 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 20/31] docs: hid: " Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 22/31] docs: leds: " Mauro Carvalho Chehab
                   ` (9 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Pat Gefre, Ard Biesheuvel, Tony Luck,
	Fenghua Yu, linux-ia64, linux-efi

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 969225e6bfce..f8f2394f9e84 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14263,7 +14263,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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 22/31] docs: leds: convert to ReST
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (19 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 21/31] docs: ia64: " Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 23/31] docs: laptops: " Mauro Carvalho Chehab
                   ` (8 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Vadim Pasternak, Jacek Anaszewski, Pavel Machek,
	Dan Murphy, Pablo Neira Ayuso, Jozsef Kadlecsik,
	Florian Westphal, David S. Miller, linux-leds, netfilter-devel,
	coreteam, netdev

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 f8f2394f9e84..73000e7d7f19 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -10172,7 +10172,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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 23/31] docs: laptops: convert to ReST
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (20 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 22/31] docs: leds: " Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 20:19   ` Andy Shevchenko
  2019-06-12 18:38 ` [PATCH v1 24/31] docs: iio: " Mauro Carvalho Chehab
                   ` (7 subsequent siblings)
  29 siblings, 1 reply; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Mattia Dongili, Arnd Bergmann,
	Greg Kroah-Hartman, Darren Hart, Andy Shevchenko,
	platform-driver-x86

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>
---
 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 73000e7d7f19..c63b1b9cbed4 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14753,7 +14753,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 5d5cc6111081..e53c915761e7 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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 24/31] docs: iio: convert to ReST
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (21 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 23/31] docs: laptops: " Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-16 13:47   ` Jonathan Cameron
  2019-06-12 18:38 ` [PATCH v1 25/31] docs: namespaces: " Mauro Carvalho Chehab
                   ` (6 subsequent siblings)
  29 siblings, 1 reply; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Jonathan Cameron, Hartmut Knaack,
	Lars-Peter Clausen, Peter Meerwald-Stadler, linux-iio

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>
---
 .../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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 25/31] docs: namespaces: convert to ReST
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (22 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 24/31] docs: iio: " Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 26/31] docs: nfc: " Mauro Carvalho Chehab
                   ` (5 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 26/31] docs: nfc: convert to ReST
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (23 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 25/31] docs: namespaces: " Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 27/31] docs: md: " Mauro Carvalho Chehab
                   ` (4 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 27/31] docs: md: convert to ReST
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (24 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 26/31] docs: nfc: " Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 28/31] docs: mtd: " Mauro Carvalho Chehab
                   ` (3 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 28/31] docs: mtd: convert to ReST
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (25 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 27/31] docs: md: " Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 29/31] docs: nvdimm: " Mauro Carvalho Chehab
                   ` (2 subsequent siblings)
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Miquel Raynal, Richard Weinberger,
	David Woodhouse, Brian Norris, Marek Vasut, Vignesh Raghavendra,
	linux-mtd

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 29/31] docs: nvdimm: convert to ReST
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (26 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 28/31] docs: mtd: " Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 19:04   ` Dan Williams
  2019-06-12 18:38 ` [PATCH v1 30/31] docs: xtensa: " Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 31/31] docs: mmc: " Mauro Carvalho Chehab
  29 siblings, 1 reply; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Dan Williams, Vishal Verma, Dave Jiang,
	Keith Busch, Ira Weiny, linux-nvdimm

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.

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 30/31] docs: xtensa: convert to ReST
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (27 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 29/31] docs: nvdimm: " Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  2019-06-12 18:38 ` [PATCH v1 31/31] docs: mmc: " Mauro Carvalho Chehab
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Chris Zankel, Max Filippov, linux-xtensa

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* [PATCH v1 31/31] docs: mmc: convert to ReST
  2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
                   ` (28 preceding siblings ...)
  2019-06-12 18:38 ` [PATCH v1 30/31] docs: xtensa: " Mauro Carvalho Chehab
@ 2019-06-12 18:38 ` Mauro Carvalho Chehab
  29 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 18:38 UTC (permalink / raw)
  To: Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet

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


^ permalink raw reply related	[flat|nested] 38+ messages in thread

* Re: [PATCH v1 29/31] docs: nvdimm: convert to ReST
  2019-06-12 18:38 ` [PATCH v1 29/31] docs: nvdimm: " Mauro Carvalho Chehab
@ 2019-06-12 19:04   ` Dan Williams
  2019-06-12 20:41     ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 38+ messages in thread
From: Dan Williams @ 2019-06-12 19:04 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
	Linux Kernel Mailing List, Jonathan Corbet, Vishal Verma,
	Dave Jiang, Keith Busch, Ira Weiny, linux-nvdimm

Hi Mauro,

On Wed, Jun 12, 2019 at 11:38 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> Rename the mtd documentation files to ReST, add an

s/mtd/nvdimm/

> 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.

Looks ok, but I was not able to apply this one in isolation to give it
a try. Am I missing some pre-reqs compared to v5.2-rc4?

^ permalink raw reply	[flat|nested] 38+ messages in thread

* Re: [PATCH v1 23/31] docs: laptops: convert to ReST
  2019-06-12 18:38 ` [PATCH v1 23/31] docs: laptops: " Mauro Carvalho Chehab
@ 2019-06-12 20:19   ` Andy Shevchenko
  0 siblings, 0 replies; 38+ messages in thread
From: Andy Shevchenko @ 2019-06-12 20:19 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
	Linux Kernel Mailing List, Jonathan Corbet, Mattia Dongili,
	Arnd Bergmann, Greg Kroah-Hartman, Darren Hart, Andy Shevchenko,
	Platform Driver

On Wed, Jun 12, 2019 at 9:38 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> 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.
>

Thanks!
Acked-by: Andy Shevchenko <andy.shevchenko@gmail.com>

> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> ---
>  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 73000e7d7f19..c63b1b9cbed4 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -14753,7 +14753,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 5d5cc6111081..e53c915761e7 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
>


-- 
With Best Regards,
Andy Shevchenko

^ permalink raw reply	[flat|nested] 38+ messages in thread

* Re: [PATCH v1 09/31] docs: driver-model: convert docs to ReST and rename to *.rst
  2019-06-12 18:38 ` [PATCH v1 09/31] docs: driver-model: " Mauro Carvalho Chehab
@ 2019-06-12 20:21   ` Jeff Kirsher
  0 siblings, 0 replies; 38+ messages in thread
From: Jeff Kirsher @ 2019-06-12 20:21 UTC (permalink / raw)
  To: Mauro Carvalho Chehab, Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
	Linus Walleij, Bartosz Golaszewski, Jean Delvare, Guenter Roeck,
	Greg Kroah-Hartman, Rafael J. Wysocki, David S. Miller,
	Julia Lawall, Gilles Muller, Nicolas Palix, Michal Marek,
	linux-gpio, linux-hwmon, intel-wired-lan, netdev, cocci

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

On Wed, 2019-06-12 at 15:38 -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>

For the ice driver comment change.

> ---
>  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%)


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

^ permalink raw reply	[flat|nested] 38+ messages in thread

* Re: [PATCH v1 29/31] docs: nvdimm: convert to ReST
  2019-06-12 19:04   ` Dan Williams
@ 2019-06-12 20:41     ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-12 20:41 UTC (permalink / raw)
  To: Dan Williams
  Cc: Linux Doc Mailing List, Mauro Carvalho Chehab,
	Linux Kernel Mailing List, Jonathan Corbet, Vishal Verma,
	Dave Jiang, Keith Busch, Ira Weiny, linux-nvdimm

Em Wed, 12 Jun 2019 12:04:12 -0700
Dan Williams <dan.j.williams@intel.com> escreveu:

> Hi Mauro,
> 
> On Wed, Jun 12, 2019 at 11:38 AM Mauro Carvalho Chehab
> <mchehab+samsung@kernel.org> wrote:
> >
> > Rename the mtd documentation files to ReST, add an  
> 
> s/mtd/nvdimm/

Sorry, cut and paste issue :-)

> 
> > 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.  
> 
> Looks ok, but I was not able to apply this one in isolation to give it
> a try. Am I missing some pre-reqs compared to v5.2-rc4?

I wrote the patch before v5.2-rc1, but, as this series touches a lot
of stuff, it was rebased against today's linux-next (next-20190612).

I didn't notice an conflict on this specific file during the rebases
though. 

There is a simple patch applied on linux-next after v5.2-rc4:

commit 3d9cf48b2ca257f1a249b347236098c3cf9d54f1
Author: Shiyang Ruan <ruansy.fnst@cn.fujitsu.com>
Date:   Thu May 9 15:40:49 2019 +0800

    Documentation: nvdimm: Fix typo
    
    Remove the extra 'we '.
    
    Signed-off-by: Shiyang Ruan <ruansy.fnst@cn.fujitsu.com>
    Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Could this be the cause of the issue you're noticing when
trying to apply it?

As this is signed-off by Jon, I suspect it went via docs-next.

Thanks,
Mauro

^ permalink raw reply	[flat|nested] 38+ messages in thread

* Re: [PATCH v1 20/31] docs: hid: convert to ReST
  2019-06-12 18:38 ` [PATCH v1 20/31] docs: hid: " Mauro Carvalho Chehab
@ 2019-06-13  8:08   ` Benjamin Tissoires
  2019-06-13  9:52     ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 38+ messages in thread
From: Benjamin Tissoires @ 2019-06-13  8:08 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, lkml,
	Jonathan Corbet, Jiri Kosina, Jonathan Cameron,
	Srinivas Pandruvada, Dmitry Torokhov, open list:HID CORE LAYER,
	linux-iio, Linux USB Mailing List

On Wed, Jun 12, 2019 at 8:39 PM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> Rename the HID documentation files to ReST, add an
> index for them and adjust in order to produce a nice html
> output via the Sphinx build system.
>
> While here, fix the sysfs example from hid-sensor.txt, that
> has a lot of "?" instead of the proper UTF-8 characters that
> are produced by the tree command.
>
> 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: Benjamin Tissoires <benjamin.tissoires@redhat.com>

Do you need to take this patch through the doc tree or should we carry
it in the HID one?

Cheers,
Benjamin

>  .../hid/{hid-alps.txt => hid-alps.rst}        |  85 ++-
>  .../hid/{hid-sensor.txt => hid-sensor.rst}    | 192 +++----
>  .../{hid-transport.txt => hid-transport.rst}  |  82 ++-
>  Documentation/hid/{hiddev.txt => hiddev.rst}  | 154 ++++--
>  Documentation/hid/{hidraw.txt => hidraw.rst}  |  53 +-
>  Documentation/hid/index.rst                   |  18 +
>  Documentation/hid/intel-ish-hid.rst           | 485 ++++++++++++++++++
>  Documentation/hid/intel-ish-hid.txt           | 454 ----------------
>  Documentation/hid/{uhid.txt => uhid.rst}      |  46 +-
>  Documentation/input/input.rst                 |   2 +-
>  MAINTAINERS                                   |   2 +-
>  11 files changed, 897 insertions(+), 676 deletions(-)
>  rename Documentation/hid/{hid-alps.txt => hid-alps.rst} (64%)
>  rename Documentation/hid/{hid-sensor.txt => hid-sensor.rst} (61%)
>  rename Documentation/hid/{hid-transport.txt => hid-transport.rst} (93%)
>  rename Documentation/hid/{hiddev.txt => hiddev.rst} (77%)
>  rename Documentation/hid/{hidraw.txt => hidraw.rst} (89%)
>  create mode 100644 Documentation/hid/index.rst
>  create mode 100644 Documentation/hid/intel-ish-hid.rst
>  delete mode 100644 Documentation/hid/intel-ish-hid.txt
>  rename Documentation/hid/{uhid.txt => uhid.rst} (94%)
>
> diff --git a/Documentation/hid/hid-alps.txt b/Documentation/hid/hid-alps.rst
> similarity index 64%
> rename from Documentation/hid/hid-alps.txt
> rename to Documentation/hid/hid-alps.rst
> index 6b02a2447c77..e2f4c4c11e3f 100644
> --- a/Documentation/hid/hid-alps.txt
> +++ b/Documentation/hid/hid-alps.rst
> @@ -1,19 +1,26 @@
> +==========================
>  ALPS HID Touchpad Protocol
> -----------------------
> +==========================
>
>  Introduction
>  ------------
>  Currently ALPS HID driver supports U1 Touchpad device.
>
> -U1 devuce basic information.
> +U1 device basic information.
> +
> +==========     ======
>  Vender ID      0x044E
>  Product ID     0x120B
>  Version ID     0x0121
> +==========     ======
>
>
>  HID Descriptor
> -------------
> +--------------
> +
> +=======        ====================    =====   =======================================
>  Byte   Field                   Value   Notes
> +=======        ====================    =====   =======================================
>  0      wHIDDescLength          001E    Length of HID Descriptor : 30 bytes
>  2      bcdVersion              0100    Compliant with Version 1.00
>  4      wReportDescLength       00B2    Report Descriptor is 178 Bytes (0x00B2)
> @@ -28,32 +35,42 @@ Byte        Field                   Value   Notes
>  22     wProductID              120B    Product ID 0x120B
>  24     wVersionID              0121    Version 01.21
>  26     RESERVED                0000    RESERVED
> +=======        ====================    =====   =======================================
>
>
>  Report ID
> -------------
> -ReportID-1     (Input Reports) (HIDUsage-Mouse) for TP&SP
> -ReportID-2     (Input Reports) (HIDUsage-keyboard) for TP
> -ReportID-3     (Input Reports) (Vendor Usage: Max 10 finger data) for TP
> -ReportID-4     (Input Reports) (Vendor Usage: ON bit data) for GP
> -ReportID-5     (Feature Reports)       Feature Reports
> -ReportID-6     (Input Reports) (Vendor Usage: StickPointer data) for SP
> -ReportID-7     (Feature Reports)       Flash update (Bootloader)
> +---------
> +
> +==========     =================  =========================================
> +ReportID-1     (Input Reports)    (HIDUsage-Mouse) for TP&SP
> +ReportID-2     (Input Reports)    (HIDUsage-keyboard) for TP
> +ReportID-3     (Input Reports)    (Vendor Usage: Max 10 finger data) for TP
> +ReportID-4     (Input Reports)    (Vendor Usage: ON bit data) for GP
> +ReportID-5     (Feature Reports)  Feature Reports
> +ReportID-6     (Input Reports)    (Vendor Usage: StickPointer data) for SP
> +ReportID-7     (Feature Reports)  Flash update (Bootloader)
> +==========     =================  =========================================
>
>
>  Data pattern
>  ------------
> +
> +=====  ==========      =====   =================
>  Case1  ReportID_1      TP/SP   Relative/Relative
>  Case2  ReportID_3      TP      Absolute
>         ReportID_6      SP      Absolute
> +=====  ==========      =====   =================
>
>
>  Command Read/Write
>  ------------------
>  To read/write to RAM, need to send a commands to the device.
> +
>  The command format is as below.
>
>  DataByte(SET_REPORT)
> +
> +=====  ======================
>  Byte1  Command Byte
>  Byte2  Address - Byte 0 (LSB)
>  Byte3  Address - Byte 1
> @@ -61,13 +78,19 @@ Byte4       Address - Byte 2
>  Byte5  Address - Byte 3 (MSB)
>  Byte6  Value Byte
>  Byte7  Checksum
> +=====  ======================
>
>  Command Byte is read=0xD1/write=0xD2 .
> +
>  Address is read/write RAM address.
> +
>  Value Byte is writing data when you send the write commands.
> +
>  When you read RAM, there is no meaning.
>
>  DataByte(GET_REPORT)
> +
> +=====  ======================
>  Byte1  Response Byte
>  Byte2  Address - Byte 0 (LSB)
>  Byte3  Address - Byte 1
> @@ -75,6 +98,7 @@ Byte4 Address - Byte 2
>  Byte5  Address - Byte 3 (MSB)
>  Byte6  Value Byte
>  Byte7  Checksum
> +=====  ======================
>
>  Read value is stored in Value Byte.
>
> @@ -82,7 +106,11 @@ Read value is stored in Value Byte.
>  Packet Format
>  Touchpad data byte
>  ------------------
> -       b7      b6      b5      b4      b3      b2      b1      b0
> +
> +
> +======= ======= ======= ======= ======= ======= ======= ======= =====
> +-      b7      b6      b5      b4      b3      b2      b1      b0
> +======= ======= ======= ======= ======= ======= ======= ======= =====
>  1      0       0       SW6     SW5     SW4     SW3     SW2     SW1
>  2      0       0       0       Fcv     Fn3     Fn2     Fn1     Fn0
>  3      Xa0_7   Xa0_6   Xa0_5   Xa0_4   Xa0_3   Xa0_2   Xa0_1   Xa0_0
> @@ -114,17 +142,25 @@ Touchpad data byte
>  25     Ya4_7   Ya4_6   Ya4_5   Ya4_4   Ya4_3   Ya4_2   Ya4_1   Ya4_0
>  26     Ya4_15  Ya4_14  Ya4_13  Ya4_12  Ya4_11  Ya4_10  Ya4_9   Ya4_8
>  27     LFB4    Zs4_6   Zs4_5   Zs4_4   Zs4_3   Zs4_2   Zs4_1   Zs4_0
> +======= ======= ======= ======= ======= ======= ======= ======= =====
>
>
> -SW1-SW6:       SW ON/OFF status
> -Xan_15-0(16bit):X Absolute data of the "n"th finger
> -Yan_15-0(16bit):Y Absolute data of the "n"th finger
> -Zsn_6-0(7bit): Operation area of the "n"th finger
> +SW1-SW6:
> +       SW ON/OFF status
> +Xan_15-0(16bit):
> +       X Absolute data of the "n"th finger
> +Yan_15-0(16bit):
> +       Y Absolute data of the "n"th finger
> +Zsn_6-0(7bit):
> +       Operation area of the "n"th finger
>
>
>  StickPointer data byte
> -------------------
> -       b7      b6      b5      b4      b3      b2      b1      b0
> +----------------------
> +
> +======= ======= ======= ======= ======= ======= ======= ======= =====
> +-      b7      b6      b5      b4      b3      b2      b1      b0
> +======= ======= ======= ======= ======= ======= ======= ======= =====
>  Byte1  1       1       1       0       1       SW3     SW2     SW1
>  Byte2  X7      X6      X5      X4      X3      X2      X1      X0
>  Byte3  X15     X14     X13     X12     X11     X10     X9      X8
> @@ -132,8 +168,13 @@ Byte4      Y7      Y6      Y5      Y4      Y3      Y2      Y1      Y0
>  Byte5  Y15     Y14     Y13     Y12     Y11     Y10     Y9      Y8
>  Byte6  Z7      Z6      Z5      Z4      Z3      Z2      Z1      Z0
>  Byte7  T&P     Z14     Z13     Z12     Z11     Z10     Z9      Z8
> +======= ======= ======= ======= ======= ======= ======= ======= =====
>
> -SW1-SW3:       SW ON/OFF status
> -Xn_15-0(16bit):X Absolute data
> -Yn_15-0(16bit):Y Absolute data
> -Zn_14-0(15bit):Z
> +SW1-SW3:
> +       SW ON/OFF status
> +Xn_15-0(16bit):
> +       X Absolute data
> +Yn_15-0(16bit):
> +       Y Absolute data
> +Zn_14-0(15bit):
> +       Z
> diff --git a/Documentation/hid/hid-sensor.txt b/Documentation/hid/hid-sensor.rst
> similarity index 61%
> rename from Documentation/hid/hid-sensor.txt
> rename to Documentation/hid/hid-sensor.rst
> index b287752a31cd..758972e34971 100644
> --- a/Documentation/hid/hid-sensor.txt
> +++ b/Documentation/hid/hid-sensor.rst
> @@ -1,6 +1,6 @@
> -
> +=====================
>  HID Sensors Framework
> -======================
> +=====================
>  HID sensor framework provides necessary interfaces to implement sensor drivers,
>  which are connected to a sensor hub. The sensor hub is a HID device and it provides
>  a report descriptor conforming to HID 1.12 sensor usage tables.
> @@ -15,22 +15,22 @@ the drivers themselves."
>  This specification describes many usage IDs, which describe the type of sensor
>  and also the individual data fields. Each sensor can have variable number of
>  data fields. The length and order is specified in the report descriptor. For
> -example a part of report descriptor can look like:
> +example a part of report descriptor can look like::
>
> -   INPUT(1)[INPUT]
> - ..
> -    Field(2)
> -      Physical(0020.0073)
> -      Usage(1)
> -        0020.045f
> -      Logical Minimum(-32767)
> -      Logical Maximum(32767)
> -      Report Size(8)
> -      Report Count(1)
> -      Report Offset(16)
> -      Flags(Variable Absolute)
> -..
> -..
> +     INPUT(1)[INPUT]
> +   ..
> +      Field(2)
> +        Physical(0020.0073)
> +        Usage(1)
> +          0020.045f
> +        Logical Minimum(-32767)
> +        Logical Maximum(32767)
> +        Report Size(8)
> +        Report Count(1)
> +        Report Offset(16)
> +        Flags(Variable Absolute)
> +  ..
> +  ..
>
>  The report is indicating "sensor page (0x20)" contains an accelerometer-3D (0x73).
>  This accelerometer-3D has some fields. Here for example field 2 is motion intensity
> @@ -40,13 +40,14 @@ data will use this format.
>
>
>  Implementation
> -=================
> +==============
>
>  This specification defines many different types of sensors with different sets of
>  data fields. It is difficult to have a common input event to user space applications,
>  for different sensors. For example an accelerometer can send X,Y and Z data, whereas
>  an ambient light sensor can send illumination data.
>  So the implementation has two parts:
> +
>  - Core hid driver
>  - Individual sensor processing part (sensor drivers)
>
> @@ -55,8 +56,11 @@ Core driver
>  The core driver registers (hid-sensor-hub) registers as a HID driver. It parses
>  report descriptors and identifies all the sensors present. It adds an MFD device
>  with name HID-SENSOR-xxxx (where xxxx is usage id from the specification).
> -For example
> +
> +For example:
> +
>  HID-SENSOR-200073 is registered for an Accelerometer 3D driver.
> +
>  So if any driver with this name is inserted, then the probe routine for that
>  function will be called. So an accelerometer processing driver can register
>  with this name and will be probed if there is an accelerometer-3D detected.
> @@ -66,7 +70,8 @@ drivers to register and get events for that usage id. Also it provides parsing
>  functions, which get and set each input/feature/output report.
>
>  Individual sensor processing part (sensor drivers)
> ------------
> +--------------------------------------------------
> +
>  The processing driver will use an interface provided by the core driver to parse
>  the report and get the indexes of the fields and also can get events. This driver
>  can use IIO interface to use the standard ABI defined for a type of sensor.
> @@ -75,31 +80,34 @@ can use IIO interface to use the standard ABI defined for a type of sensor.
>  Core driver Interface
>  =====================
>
> -Callback structure:
> -Each processing driver can use this structure to set some callbacks.
> +Callback structure::
> +
> +  Each processing driver can use this structure to set some callbacks.
>         int (*suspend)(..): Callback when HID suspend is received
>         int (*resume)(..): Callback when HID resume is received
>         int (*capture_sample)(..): Capture a sample for one of its data fields
>         int (*send_event)(..): One complete event is received which can have
>                                 multiple data fields.
>
> -Registration functions:
> -int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
> +Registration functions::
> +
> +  int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
>                         u32 usage_id,
>                         struct hid_sensor_hub_callbacks *usage_callback):
>
>  Registers callbacks for an usage id. The callback functions are not allowed
> -to sleep.
> +to sleep::
>
>
> -int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
> +  int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
>                         u32 usage_id):
>
>  Removes callbacks for an usage id.
>
>
> -Parsing function:
> -int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
> +Parsing function::
> +
> +  int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
>                         u8 type,
>                         u32 usage_id, u32 attr_usage_id,
>                         struct hid_sensor_hub_attribute_info *info);
> @@ -110,26 +118,27 @@ so that fields can be set or get individually.
>  These indexes avoid searching every time and getting field index to get or set.
>
>
> -Set Feature report
> -int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
> +Set Feature report::
> +
> +  int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
>                         u32 field_index, s32 value);
>
>  This interface is used to set a value for a field in feature report. For example
>  if there is a field report_interval, which is parsed by a call to
> -sensor_hub_input_get_attribute_info before, then it can directly set that individual
> -field.
> +sensor_hub_input_get_attribute_info before, then it can directly set that
> +individual field::
>
>
> -int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
> +  int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
>                         u32 field_index, s32 *value);
>
>  This interface is used to get a value for a field in input report. For example
>  if there is a field report_interval, which is parsed by a call to
> -sensor_hub_input_get_attribute_info before, then it can directly get that individual
> -field value.
> +sensor_hub_input_get_attribute_info before, then it can directly get that
> +individual field value::
>
>
> -int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
> +  int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
>                         u32 usage_id,
>                         u32 attr_usage_id, u32 report_id);
>
> @@ -143,6 +152,8 @@ registered callback function to process the sample.
>  ----------
>
>  HID Custom and generic Sensors
> +------------------------------
> +
>
>  HID Sensor specification defines two special sensor usage types. Since they
>  don't represent a standard sensor, it is not possible to define using Linux IIO
> @@ -158,66 +169,73 @@ keyboard attached/detached or lid open/close.
>  To allow application to utilize these sensors, here they are exported uses sysfs
>  attribute groups, attributes and misc device interface.
>
> -An example of this representation on sysfs:
> -/sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R
> -.
> -????????? enable_sensor
> -????????? feature-0-200316
> -??????? ????????? feature-0-200316-maximum
> -??????? ????????? feature-0-200316-minimum
> -??????? ????????? feature-0-200316-name
> -??????? ????????? feature-0-200316-size
> -??????? ????????? feature-0-200316-unit-expo
> -??????? ????????? feature-0-200316-units
> -??????? ????????? feature-0-200316-value
> -????????? feature-1-200201
> -??????? ????????? feature-1-200201-maximum
> -??????? ????????? feature-1-200201-minimum
> -??????? ????????? feature-1-200201-name
> -??????? ????????? feature-1-200201-size
> -??????? ????????? feature-1-200201-unit-expo
> -??????? ????????? feature-1-200201-units
> -??????? ????????? feature-1-200201-value
> -????????? input-0-200201
> -??????? ????????? input-0-200201-maximum
> -??????? ????????? input-0-200201-minimum
> -??????? ????????? input-0-200201-name
> -??????? ????????? input-0-200201-size
> -??????? ????????? input-0-200201-unit-expo
> -??????? ????????? input-0-200201-units
> -??????? ????????? input-0-200201-value
> -????????? input-1-200202
> -??????? ????????? input-1-200202-maximum
> -??????? ????????? input-1-200202-minimum
> -??????? ????????? input-1-200202-name
> -??????? ????????? input-1-200202-size
> -??????? ????????? input-1-200202-unit-expo
> -??????? ????????? input-1-200202-units
> -??????? ????????? input-1-200202-value
> +An example of this representation on sysfs::
> +
> +  /sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R
> +  .
> +  │   ├──  enable_sensor
> +  │   │   ├── feature-0-200316
> +  │   │   │   ├── feature-0-200316-maximum
> +  │   │   │   ├── feature-0-200316-minimum
> +  │   │   │   ├── feature-0-200316-name
> +  │   │   │   ├── feature-0-200316-size
> +  │   │   │   ├── feature-0-200316-unit-expo
> +  │   │   │   ├── feature-0-200316-units
> +  │   │   │   ├── feature-0-200316-value
> +  │   │   ├── feature-1-200201
> +  │   │   │   ├── feature-1-200201-maximum
> +  │   │   │   ├── feature-1-200201-minimum
> +  │   │   │   ├── feature-1-200201-name
> +  │   │   │   ├── feature-1-200201-size
> +  │   │   │   ├── feature-1-200201-unit-expo
> +  │   │   │   ├── feature-1-200201-units
> +  │   │   │   ├── feature-1-200201-value
> +  │   │   ├── input-0-200201
> +  │   │   │   ├── input-0-200201-maximum
> +  │   │   │   ├── input-0-200201-minimum
> +  │   │   │   ├── input-0-200201-name
> +  │   │   │   ├── input-0-200201-size
> +  │   │   │   ├── input-0-200201-unit-expo
> +  │   │   │   ├── input-0-200201-units
> +  │   │   │   ├── input-0-200201-value
> +  │   │   ├── input-1-200202
> +  │   │   │   ├── input-1-200202-maximum
> +  │   │   │   ├── input-1-200202-minimum
> +  │   │   │   ├── input-1-200202-name
> +  │   │   │   ├── input-1-200202-size
> +  │   │   │   ├── input-1-200202-unit-expo
> +  │   │   │   ├── input-1-200202-units
> +  │   │   │   ├── input-1-200202-value
>
>  Here there is a custom sensors with four fields, two feature and two inputs.
>  Each field is represented by a set of attributes. All fields except the "value"
>  are read only. The value field is a RW field.
> -Example
> -/sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
> -feature-0-200316-maximum:6
> -feature-0-200316-minimum:0
> -feature-0-200316-name:property-reporting-state
> -feature-0-200316-size:1
> -feature-0-200316-unit-expo:0
> -feature-0-200316-units:25
> -feature-0-200316-value:1
> +
> +Example::
> +
> +  /sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
> +  feature-0-200316-maximum:6
> +  feature-0-200316-minimum:0
> +  feature-0-200316-name:property-reporting-state
> +  feature-0-200316-size:1
> +  feature-0-200316-unit-expo:0
> +  feature-0-200316-units:25
> +  feature-0-200316-value:1
>
>  How to enable such sensor?
> +^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
>  By default sensor can be power gated. To enable sysfs attribute "enable" can be
> -used.
> -$ echo 1 > enable_sensor
> +used::
> +
> +       $ echo 1 > enable_sensor
>
>  Once enabled and powered on, sensor can report value using HID reports.
> -These reports are pushed using misc device interface in a FIFO order.
> -/dev$ tree | grep HID-SENSOR-2000e1.6.auto
> -??????? ????????? 10:53 -> ../HID-SENSOR-2000e1.6.auto
> -????????? HID-SENSOR-2000e1.6.auto
> +These reports are pushed using misc device interface in a FIFO order::
> +
> +       /dev$ tree | grep HID-SENSOR-2000e1.6.auto
> +       │   │   │   ├── 10:53 -> ../HID-SENSOR-2000e1.6.auto
> +       │   ├──  HID-SENSOR-2000e1.6.auto
>
>  Each reports can be of variable length preceded by a header. This header
>  consist of a 32 bit usage id, 64 bit time stamp and 32 bit length field of raw
> diff --git a/Documentation/hid/hid-transport.txt b/Documentation/hid/hid-transport.rst
> similarity index 93%
> rename from Documentation/hid/hid-transport.txt
> rename to Documentation/hid/hid-transport.rst
> index 3dcba9fd4a3a..6f3aaa86ce7b 100644
> --- a/Documentation/hid/hid-transport.txt
> +++ b/Documentation/hid/hid-transport.rst
> @@ -1,5 +1,6 @@
> -                          HID I/O Transport Drivers
> -                         ===========================
> +=========================
> +HID I/O Transport Drivers
> +=========================
>
>  The HID subsystem is independent of the underlying transport driver. Initially,
>  only USB was supported, but other specifications adopted the HID design and
> @@ -16,6 +17,8 @@ transport and device setup/management. HID core is responsible of
>  report-parsing, report interpretation and the user-space API. Device specifics
>  and quirks are handled by all layers depending on the quirk.
>
> +::
> +
>   +-----------+  +-----------+            +-----------+  +-----------+
>   | Device #1 |  | Device #i |            | Device #j |  | Device #k |
>   +-----------+  +-----------+            +-----------+  +-----------+
> @@ -42,8 +45,9 @@ and quirks are handled by all layers depending on the quirk.
>   +----------------+  +-----------+  +------------------+  +------------------+
>
>  Example Drivers:
> -  I/O: USB, I2C, Bluetooth-l2cap
> -  Transport: USB-HID, I2C-HID, BT-HIDP
> +
> +  - I/O: USB, I2C, Bluetooth-l2cap
> +  - Transport: USB-HID, I2C-HID, BT-HIDP
>
>  Everything below "HID Core" is simplified in this graph as it is only of
>  interest to HID device drivers. Transport drivers do not need to know the
> @@ -183,7 +187,7 @@ Other ctrl-channel requests are supported by USB-HID but are not available
>  -------------------
>
>  Transport drivers normally use the following procedure to register a new device
> -with HID core:
> +with HID core::
>
>         struct hid_device *hid;
>         int ret;
> @@ -215,7 +219,7 @@ Once hid_add_device() is entered, HID core might use the callbacks provided in
>  "custom_ll_driver". Note that fields like "country" can be ignored by underlying
>  transport-drivers if not supported.
>
> -To unregister a device, use:
> +To unregister a device, use::
>
>         hid_destroy_device(hid);
>
> @@ -226,73 +230,110 @@ driver callbacks.
>  -----------------------------
>
>  The available HID callbacks are:
> - - int (*start) (struct hid_device *hdev)
> +
> +   ::
> +
> +      int (*start) (struct hid_device *hdev)
> +
>     Called from HID device drivers once they want to use the device. Transport
>     drivers can choose to setup their device in this callback. However, normally
>     devices are already set up before transport drivers register them to HID core
>     so this is mostly only used by USB-HID.
>
> - - void (*stop) (struct hid_device *hdev)
> +   ::
> +
> +      void (*stop) (struct hid_device *hdev)
> +
>     Called from HID device drivers once they are done with a device. Transport
>     drivers can free any buffers and deinitialize the device. But note that
>     ->start() might be called again if another HID device driver is loaded on the
>     device.
> +
>     Transport drivers are free to ignore it and deinitialize devices after they
>     destroyed them via hid_destroy_device().
>
> - - int (*open) (struct hid_device *hdev)
> +   ::
> +
> +      int (*open) (struct hid_device *hdev)
> +
>     Called from HID device drivers once they are interested in data reports.
>     Usually, while user-space didn't open any input API/etc., device drivers are
>     not interested in device data and transport drivers can put devices asleep.
>     However, once ->open() is called, transport drivers must be ready for I/O.
>     ->open() calls are nested for each client that opens the HID device.
>
> - - void (*close) (struct hid_device *hdev)
> +   ::
> +
> +      void (*close) (struct hid_device *hdev)
> +
>     Called from HID device drivers after ->open() was called but they are no
>     longer interested in device reports. (Usually if user-space closed any input
>     devices of the driver).
> +
>     Transport drivers can put devices asleep and terminate any I/O of all
>     ->open() calls have been followed by a ->close() call. However, ->start() may
>     be called again if the device driver is interested in input reports again.
>
> - - int (*parse) (struct hid_device *hdev)
> +   ::
> +
> +      int (*parse) (struct hid_device *hdev)
> +
>     Called once during device setup after ->start() has been called. Transport
>     drivers must read the HID report-descriptor from the device and tell HID core
>     about it via hid_parse_report().
>
> - - int (*power) (struct hid_device *hdev, int level)
> +   ::
> +
> +      int (*power) (struct hid_device *hdev, int level)
> +
>     Called by HID core to give PM hints to transport drivers. Usually this is
>     analogical to the ->open() and ->close() hints and redundant.
>
> - - void (*request) (struct hid_device *hdev, struct hid_report *report,
> -                    int reqtype)
> +   ::
> +
> +      void (*request) (struct hid_device *hdev, struct hid_report *report,
> +                      int reqtype)
> +
>     Send an HID request on the ctrl channel. "report" contains the report that
>     should be sent and "reqtype" the request type. Request-type can be
>     HID_REQ_SET_REPORT or HID_REQ_GET_REPORT.
> +
>     This callback is optional. If not provided, HID core will assemble a raw
>     report following the HID specs and send it via the ->raw_request() callback.
>     The transport driver is free to implement this asynchronously.
>
> - - int (*wait) (struct hid_device *hdev)
> +   ::
> +
> +      int (*wait) (struct hid_device *hdev)
> +
>     Used by HID core before calling ->request() again. A transport driver can use
>     it to wait for any pending requests to complete if only one request is
>     allowed at a time.
>
> - - int (*raw_request) (struct hid_device *hdev, unsigned char reportnum,
> -                       __u8 *buf, size_t count, unsigned char rtype,
> -                       int reqtype)
> +   ::
> +
> +      int (*raw_request) (struct hid_device *hdev, unsigned char reportnum,
> +                          __u8 *buf, size_t count, unsigned char rtype,
> +                          int reqtype)
> +
>     Same as ->request() but provides the report as raw buffer. This request shall
>     be synchronous. A transport driver must not use ->wait() to complete such
>     requests. This request is mandatory and hid core will reject the device if
>     it is missing.
>
> - - int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len)
> +   ::
> +
> +      int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len)
> +
>     Send raw output report via intr channel. Used by some HID device drivers
>     which require high throughput for outgoing requests on the intr channel. This
>     must not cause SET_REPORT calls! This must be implemented as asynchronous
>     output report on the intr channel!
>
> - - int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype)
> +   ::
> +
> +      int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype)
> +
>     Perform SET/GET_IDLE request. Only used by USB-HID, do not implement!
>
>  2.3) Data Path
> @@ -314,4 +355,5 @@ transport driver and not passed to hid_input_report().
>  Acknowledgements to SET_REPORT requests are not of interest to HID core.
>
>  ----------------------------------------------------
> +
>  Written 2013, David Herrmann <dh.herrmann@gmail.com>
> diff --git a/Documentation/hid/hiddev.txt b/Documentation/hid/hiddev.rst
> similarity index 77%
> rename from Documentation/hid/hiddev.txt
> rename to Documentation/hid/hiddev.rst
> index 638448707aa2..209e6ba4e019 100644
> --- a/Documentation/hid/hiddev.txt
> +++ b/Documentation/hid/hiddev.rst
> @@ -1,6 +1,9 @@
> +================================================
>  Care and feeding of your Human Interface Devices
> +================================================
>
> -INTRODUCTION
> +Introduction
> +============
>
>  In addition to the normal input type HID devices, USB also uses the
>  human interface device protocols for things that are not really human
> @@ -16,38 +19,40 @@ normalised event interface - see Documentation/input/input.rst
>  * the hiddev interface, which provides fairly raw HID events
>
>  The data flow for a HID event produced by a device is something like
> -the following :
> +the following::
>
>   usb.c ---> hid-core.c  ----> hid-input.c ----> [keyboard/mouse/joystick/event]
>                           |
>                           |
> -                          --> hiddev.c ----> POWER / MONITOR CONTROL
> +                          --> hiddev.c ----> POWER / MONITOR CONTROL
>
>  In addition, other subsystems (apart from USB) can potentially feed
>  events into the input subsystem, but these have no effect on the hid
>  device interface.
>
> -USING THE HID DEVICE INTERFACE
> +Using the HID Device Interface
> +==============================
>
>  The hiddev interface is a char interface using the normal USB major,
>  with the minor numbers starting at 96 and finishing at 111. Therefore,
> -you need the following commands:
> -mknod /dev/usb/hiddev0 c 180 96
> -mknod /dev/usb/hiddev1 c 180 97
> -mknod /dev/usb/hiddev2 c 180 98
> -mknod /dev/usb/hiddev3 c 180 99
> -mknod /dev/usb/hiddev4 c 180 100
> -mknod /dev/usb/hiddev5 c 180 101
> -mknod /dev/usb/hiddev6 c 180 102
> -mknod /dev/usb/hiddev7 c 180 103
> -mknod /dev/usb/hiddev8 c 180 104
> -mknod /dev/usb/hiddev9 c 180 105
> -mknod /dev/usb/hiddev10 c 180 106
> -mknod /dev/usb/hiddev11 c 180 107
> -mknod /dev/usb/hiddev12 c 180 108
> -mknod /dev/usb/hiddev13 c 180 109
> -mknod /dev/usb/hiddev14 c 180 110
> -mknod /dev/usb/hiddev15 c 180 111
> +you need the following commands::
> +
> +       mknod /dev/usb/hiddev0 c 180 96
> +       mknod /dev/usb/hiddev1 c 180 97
> +       mknod /dev/usb/hiddev2 c 180 98
> +       mknod /dev/usb/hiddev3 c 180 99
> +       mknod /dev/usb/hiddev4 c 180 100
> +       mknod /dev/usb/hiddev5 c 180 101
> +       mknod /dev/usb/hiddev6 c 180 102
> +       mknod /dev/usb/hiddev7 c 180 103
> +       mknod /dev/usb/hiddev8 c 180 104
> +       mknod /dev/usb/hiddev9 c 180 105
> +       mknod /dev/usb/hiddev10 c 180 106
> +       mknod /dev/usb/hiddev11 c 180 107
> +       mknod /dev/usb/hiddev12 c 180 108
> +       mknod /dev/usb/hiddev13 c 180 109
> +       mknod /dev/usb/hiddev14 c 180 110
> +       mknod /dev/usb/hiddev15 c 180 111
>
>  So you point your hiddev compliant user-space program at the correct
>  interface for your device, and it all just works.
> @@ -56,7 +61,9 @@ Assuming that you have a hiddev compliant user-space program, of
>  course. If you need to write one, read on.
>
>
> -THE HIDDEV API
> +The HIDDEV API
> +==============
> +
>  This description should be read in conjunction with the HID
>  specification, freely available from http://www.usb.org, and
>  conveniently linked of http://www.linux-usb.org.
> @@ -69,12 +76,14 @@ each of which can have one or more "usages".  In the hid-core,
>  each one of these usages has a single signed 32 bit value.
>
>  read():
> +-------
> +
>  This is the event interface.  When the HID device's state changes,
>  it performs an interrupt transfer containing a report which contains
>  the changed value.  The hid-core.c module parses the report, and
>  returns to hiddev.c the individual usages that have changed within
>  the report.  In its basic mode, the hiddev will make these individual
> -usage changes available to the reader using a struct hiddev_event:
> +usage changes available to the reader using a struct hiddev_event::
>
>         struct hiddev_event {
>             unsigned hid;
> @@ -90,13 +99,19 @@ behavior of the read() function can be modified using the HIDIOCSFLAG
>  ioctl() described below.
>
>
> -ioctl():
> -This is the control interface. There are a number of controls:
> +ioctl():
> +--------
>
> -HIDIOCGVERSION - int (read)
> -Gets the version code out of the hiddev driver.
> +This is the control interface. There are a number of controls:
> +
> +HIDIOCGVERSION
> +  - int (read)
> +
> + Gets the version code out of the hiddev driver.
> +
> +HIDIOCAPPLICATION
> +  - (none)
>
> -HIDIOCAPPLICATION - (none)
>  This ioctl call returns the HID application usage associated with the
>  hid device. The third argument to ioctl() specifies which application
>  index to get. This is useful when the device has more than one
> @@ -104,25 +119,33 @@ application collection. If the index is invalid (greater or equal to
>  the number of application collections this device has) the ioctl
>  returns -1. You can find out beforehand how many application
>  collections the device has from the num_applications field from the
> -hiddev_devinfo structure.
> +hiddev_devinfo structure.
> +
> +HIDIOCGCOLLECTIONINFO
> +  - struct hiddev_collection_info (read/write)
>
> -HIDIOCGCOLLECTIONINFO - struct hiddev_collection_info (read/write)
>  This returns a superset of the information above, providing not only
>  application collections, but all the collections the device has.  It
>  also returns the level the collection lives in the hierarchy.
> -The user passes in a hiddev_collection_info struct with the index
> -field set to the index that should be returned.  The ioctl fills in
> -the other fields.  If the index is larger than the last collection
> +The user passes in a hiddev_collection_info struct with the index
> +field set to the index that should be returned.  The ioctl fills in
> +the other fields.  If the index is larger than the last collection
>  index, the ioctl returns -1 and sets errno to -EINVAL.
>
> -HIDIOCGDEVINFO - struct hiddev_devinfo (read)
> +HIDIOCGDEVINFO
> +  - struct hiddev_devinfo (read)
> +
>  Gets a hiddev_devinfo structure which describes the device.
>
> -HIDIOCGSTRING - struct hiddev_string_descriptor (read/write)
> +HIDIOCGSTRING
> +  - struct hiddev_string_descriptor (read/write)
> +
>  Gets a string descriptor from the device. The caller must fill in the
>  "index" field to indicate which descriptor should be returned.
>
> -HIDIOCINITREPORT - (none)
> +HIDIOCINITREPORT
> +  - (none)
> +
>  Instructs the kernel to retrieve all input and feature report values
>  from the device. At this point, all the usage structures will contain
>  current values for the device, and will maintain it as the device
> @@ -130,21 +153,29 @@ changes.  Note that the use of this ioctl is unnecessary in general,
>  since later kernels automatically initialize the reports from the
>  device at attach time.
>
> -HIDIOCGNAME - string (variable length)
> +HIDIOCGNAME
> +  - string (variable length)
> +
>  Gets the device name
>
> -HIDIOCGREPORT - struct hiddev_report_info (write)
> +HIDIOCGREPORT
> +  - struct hiddev_report_info (write)
> +
>  Instructs the kernel to get a feature or input report from the device,
>  in order to selectively update the usage structures (in contrast to
>  INITREPORT).
>
> -HIDIOCSREPORT - struct hiddev_report_info (write)
> +HIDIOCSREPORT
> +  - struct hiddev_report_info (write)
> +
>  Instructs the kernel to send a report to the device. This report can
>  be filled in by the user through HIDIOCSUSAGE calls (below) to fill in
>  individual usage values in the report before sending the report in full
> -to the device.
> +to the device.
> +
> +HIDIOCGREPORTINFO
> +  - struct hiddev_report_info (read/write)
>
> -HIDIOCGREPORTINFO - struct hiddev_report_info (read/write)
>  Fills in a hiddev_report_info structure for the user. The report is
>  looked up by type (input, output or feature) and id, so these fields
>  must be filled in by the user. The ID can be absolute -- the actual
> @@ -154,52 +185,67 @@ report_id) for the next report after report_id. Without a-priori
>  information about report ids, the right way to use this ioctl is to
>  use the relative IDs above to enumerate the valid IDs. The ioctl
>  returns non-zero when there is no more next ID. The real report ID is
> -filled into the returned hiddev_report_info structure.
> +filled into the returned hiddev_report_info structure.
> +
> +HIDIOCGFIELDINFO
> +  - struct hiddev_field_info (read/write)
>
> -HIDIOCGFIELDINFO - struct hiddev_field_info (read/write)
>  Returns the field information associated with a report in a
>  hiddev_field_info structure. The user must fill in report_id and
>  report_type in this structure, as above. The field_index should also
>  be filled in, which should be a number from 0 and maxfield-1, as
> -returned from a previous HIDIOCGREPORTINFO call.
> +returned from a previous HIDIOCGREPORTINFO call.
> +
> +HIDIOCGUCODE
> +  - struct hiddev_usage_ref (read/write)
>
> -HIDIOCGUCODE - struct hiddev_usage_ref (read/write)
>  Returns the usage_code in a hiddev_usage_ref structure, given that
>  given its report type, report id, field index, and index within the
>  field have already been filled into the structure.
>
> -HIDIOCGUSAGE - struct hiddev_usage_ref (read/write)
> +HIDIOCGUSAGE
> +  - struct hiddev_usage_ref (read/write)
> +
>  Returns the value of a usage in a hiddev_usage_ref structure. The
>  usage to be retrieved can be specified as above, or the user can
>  choose to fill in the report_type field and specify the report_id as
>  HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be
>  filled in with the report and field information associated with this
> -usage if it is found.
> +usage if it is found.
> +
> +HIDIOCSUSAGE
> +  - struct hiddev_usage_ref (write)
>
> -HIDIOCSUSAGE - struct hiddev_usage_ref (write)
>  Sets the value of a usage in an output report.  The user fills in
>  the hiddev_usage_ref structure as above, but additionally fills in
>  the value field.
>
> -HIDIOGCOLLECTIONINDEX - struct hiddev_usage_ref (write)
> +HIDIOGCOLLECTIONINDEX
> +  - struct hiddev_usage_ref (write)
> +
>  Returns the collection index associated with this usage.  This
>  indicates where in the collection hierarchy this usage sits.
>
> -HIDIOCGFLAG - int (read)
> -HIDIOCSFLAG - int (write)
> +HIDIOCGFLAG
> +  - int (read)
> +HIDIOCSFLAG
> +  - int (write)
> +
>  These operations respectively inspect and replace the mode flags
>  that influence the read() call above.  The flags are as follows:
>
> -    HIDDEV_FLAG_UREF - read() calls will now return
> +    HIDDEV_FLAG_UREF
> +      - read() calls will now return
>          struct hiddev_usage_ref instead of struct hiddev_event.
>          This is a larger structure, but in situations where the
>          device has more than one usage in its reports with the
>          same usage code, this mode serves to resolve such
>          ambiguity.
>
> -    HIDDEV_FLAG_REPORT - This flag can only be used in conjunction
> +    HIDDEV_FLAG_REPORT
> +      - This flag can only be used in conjunction
>          with HIDDEV_FLAG_UREF.  With this flag set, when the device
>          sends a report, a struct hiddev_usage_ref will be returned
> -        to read() filled in with the report_type and report_id, but
> +        to read() filled in with the report_type and report_id, but
>          with field_index set to FIELD_INDEX_NONE.  This serves as
>          additional notification when the device has sent a report.
> diff --git a/Documentation/hid/hidraw.txt b/Documentation/hid/hidraw.rst
> similarity index 89%
> rename from Documentation/hid/hidraw.txt
> rename to Documentation/hid/hidraw.rst
> index c8436e354f44..4a4a0ba1f362 100644
> --- a/Documentation/hid/hidraw.txt
> +++ b/Documentation/hid/hidraw.rst
> @@ -1,5 +1,6 @@
> -      HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices
> -     ==================================================================
> +================================================================
> +HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices
> +================================================================
>
>  The hidraw driver provides a raw interface to USB and Bluetooth Human
>  Interface Devices (HIDs).  It differs from hiddev in that reports sent and
> @@ -31,6 +32,7 @@ directly under /dev (eg: /dev/hidraw0).  As this location is distribution-
>  and udev rule-dependent, applications should use libudev to locate hidraw
>  devices attached to the system.  There is a tutorial on libudev with a
>  working example at:
> +
>         http://www.signal11.us/oss/udev/
>
>  The HIDRAW API
> @@ -51,7 +53,7 @@ byte.  For devices which do not use numbered reports, the report data
>  will begin at the first byte.
>
>  write()
> ---------
> +-------
>  The write() function will write a report to the device. For USB devices, if
>  the device has an INTERRUPT OUT endpoint, the report will be sent on that
>  endpoint. If it does not, the report will be sent over the control endpoint,
> @@ -62,38 +64,52 @@ number.  If the device does not use numbered reports, the first byte should
>  be set to 0. The report data itself should begin at the second byte.
>
>  ioctl()
> ---------
> +-------
>  Hidraw supports the following ioctls:
>
> -HIDIOCGRDESCSIZE: Get Report Descriptor Size
> +HIDIOCGRDESCSIZE:
> +       Get Report Descriptor Size
> +
>  This ioctl will get the size of the device's report descriptor.
>
> -HIDIOCGRDESC: Get Report Descriptor
> +HIDIOCGRDESC:
> +       Get Report Descriptor
> +
>  This ioctl returns the device's report descriptor using a
>  hidraw_report_descriptor struct.  Make sure to set the size field of the
>  hidraw_report_descriptor struct to the size returned from HIDIOCGRDESCSIZE.
>
> -HIDIOCGRAWINFO: Get Raw Info
> +HIDIOCGRAWINFO:
> +       Get Raw Info
> +
>  This ioctl will return a hidraw_devinfo struct containing the bus type, the
>  vendor ID (VID), and product ID (PID) of the device. The bus type can be one
> -of:
> -       BUS_USB
> -       BUS_HIL
> -       BUS_BLUETOOTH
> -       BUS_VIRTUAL
> +of::
> +
> +       - BUS_USB
> +       - BUS_HIL
> +       - BUS_BLUETOOTH
> +       - BUS_VIRTUAL
> +
>  which are defined in uapi/linux/input.h.
>
> -HIDIOCGRAWNAME(len): Get Raw Name
> +HIDIOCGRAWNAME(len):
> +       Get Raw Name
> +
>  This ioctl returns a string containing the vendor and product strings of
>  the device.  The returned string is Unicode, UTF-8 encoded.
>
> -HIDIOCGRAWPHYS(len): Get Physical Address
> +HIDIOCGRAWPHYS(len):
> +       Get Physical Address
> +
>  This ioctl returns a string representing the physical address of the device.
>  For USB devices, the string contains the physical path to the device (the
>  USB controller, hubs, ports, etc).  For Bluetooth devices, the string
>  contains the hardware (MAC) address of the device.
>
> -HIDIOCSFEATURE(len): Send a Feature Report
> +HIDIOCSFEATURE(len):
> +       Send a Feature Report
> +
>  This ioctl will send a feature report to the device.  Per the HID
>  specification, feature reports are always sent using the control endpoint.
>  Set the first byte of the supplied buffer to the report number.  For devices
> @@ -101,7 +117,9 @@ which do not use numbered reports, set the first byte to 0. The report data
>  begins in the second byte. Make sure to set len accordingly, to one more
>  than the length of the report (to account for the report number).
>
> -HIDIOCGFEATURE(len): Get a Feature Report
> +HIDIOCGFEATURE(len):
> +       Get a Feature Report
> +
>  This ioctl will request a feature report from the device using the control
>  endpoint.  The first byte of the supplied buffer should be set to the report
>  number of the requested report.  For devices which do not use numbered
> @@ -109,11 +127,12 @@ reports, set the first byte to 0.  The report will be returned starting at
>  the first byte of the buffer (ie: the report number is not returned).
>
>  Example
> ----------
> +-------
>  In samples/, find hid-example.c, which shows examples of read(), write(),
>  and all the ioctls for hidraw.  The code may be used by anyone for any
>  purpose, and can serve as a starting point for developing applications using
>  hidraw.
>
>  Document by:
> +
>         Alan Ott <alan@signal11.us>, Signal 11 Software
> diff --git a/Documentation/hid/index.rst b/Documentation/hid/index.rst
> new file mode 100644
> index 000000000000..af4324902622
> --- /dev/null
> +++ b/Documentation/hid/index.rst
> @@ -0,0 +1,18 @@
> +:orphan:
> +
> +=============================
> +Human Interface Devices (HID)
> +=============================
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   hiddev
> +   hidraw
> +   hid-sensor
> +   hid-transport
> +
> +   uhid
> +
> +   hid-alps
> +   intel-ish-hid
> diff --git a/Documentation/hid/intel-ish-hid.rst b/Documentation/hid/intel-ish-hid.rst
> new file mode 100644
> index 000000000000..cccbf4be17d7
> --- /dev/null
> +++ b/Documentation/hid/intel-ish-hid.rst
> @@ -0,0 +1,485 @@
> +=================================
> +Intel Integrated Sensor Hub (ISH)
> +=================================
> +
> +A sensor hub enables the ability to offload sensor polling and algorithm
> +processing to a dedicated low power co-processor. This allows the core
> +processor to go into low power modes more often, resulting in the increased
> +battery life.
> +
> +There are many vendors providing external sensor hubs confirming to HID
> +Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops
> +and embedded products. Linux had this support since Linux 3.9.
> +
> +Intel® introduced integrated sensor hubs as a part of the SoC starting from
> +Cherry Trail and now supported on multiple generations of CPU packages. There
> +are many commercial devices already shipped with Integrated Sensor Hubs (ISH).
> +These ISH also comply to HID sensor specification, but the  difference is the
> +transport protocol used for communication. The current external sensor hubs
> +mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB.
> +
> +1. Overview
> +===========
> +
> +Using a analogy with a usbhid implementation, the ISH follows a similar model
> +for a very high speed communication::
> +
> +       -----------------               ----------------------
> +       |    USB HID    |       -->     |    ISH HID         |
> +       -----------------               ----------------------
> +       -----------------               ----------------------
> +       |  USB protocol |       -->     |    ISH Transport   |
> +       -----------------               ----------------------
> +       -----------------               ----------------------
> +       |  EHCI/XHCI    |       -->     |    ISH IPC         |
> +       -----------------               ----------------------
> +             PCI                                PCI
> +       -----------------               ----------------------
> +        |Host controller|      -->     |    ISH processor   |
> +       -----------------               ----------------------
> +            USB Link
> +       -----------------               ----------------------
> +       | USB End points|       -->     |    ISH Clients     |
> +       -----------------               ----------------------
> +
> +Like USB protocol provides a method for device enumeration, link management
> +and user data encapsulation, the ISH also provides similar services. But it is
> +very light weight tailored to manage and communicate with ISH client
> +applications implemented in the firmware.
> +
> +The ISH allows multiple sensor management applications executing in the
> +firmware. Like USB endpoints the messaging can be to/from a client. As part of
> +enumeration process, these clients are identified. These clients can be simple
> +HID sensor applications, sensor calibration application or senor firmware
> +update application.
> +
> +The implementation model is similar, like USB bus, ISH transport is also
> +implemented as a bus. Each client application executing in the ISH processor
> +is registered as a device on this bus. The driver, which binds each device
> +(ISH HID driver) identifies the device type and registers with the hid core.
> +
> +2. ISH Implementation: Block Diagram
> +====================================
> +
> +::
> +
> +        ---------------------------
> +       |  User Space Applications  |
> +        ---------------------------
> +
> +  ----------------IIO ABI----------------
> +        --------------------------
> +       |  IIO Sensor Drivers     |
> +        --------------------------
> +        --------------------------
> +       |        IIO core         |
> +        --------------------------
> +        --------------------------
> +       |   HID Sensor Hub MFD    |
> +        --------------------------
> +        --------------------------
> +       |       HID Core          |
> +        --------------------------
> +        --------------------------
> +       |   HID over ISH Client   |
> +        --------------------------
> +        --------------------------
> +       |   ISH Transport (ISHTP) |
> +        --------------------------
> +        --------------------------
> +       |      IPC Drivers        |
> +        --------------------------
> +  OS
> +  ---------------- PCI -----------------
> +  Hardware + Firmware
> +        ----------------------------
> +       | ISH Hardware/Firmware(FW) |
> +        ----------------------------
> +
> +3. High level processing in above blocks
> +========================================
> +
> +3.1 Hardware Interface
> +----------------------
> +
> +The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI
> +product and vendor IDs are changed from different generations of processors. So
> +the source code which enumerate drivers needs to update from generation to
> +generation.
> +
> +3.2 Inter Processor Communication (IPC) driver
> +----------------------------------------------
> +
> +Location: drivers/hid/intel-ish-hid/ipc
> +
> +The IPC message used memory mapped I/O. The registers are defined in
> +hw-ish-regs.h.
> +
> +3.2.1 IPC/FW message types
> +^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +There are two types of messages, one for management of link and other messages
> +are to and from transport layers.
> +
> +TX and RX of Transport messages
> +...............................
> +
> +A set of memory mapped register offers support of multi byte messages TX and
> +RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains
> +internal queues to sequence messages and send them in order to the FW.
> +Optionally the caller can register handler to get notification of completion.
> +A door bell mechanism is used in messaging to trigger processing in host and
> +client firmware side. When ISH interrupt handler is called, the ISH2HOST
> +doorbell register is used by host drivers to determine that the interrupt
> +is for ISH.
> +
> +Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell
> +register has the following format:
> +Bits 0..6: fragment length (7 bits are used)
> +Bits 10..13: encapsulated protocol
> +Bits 16..19: management command (for IPC management protocol)
> +Bit 31: doorbell trigger (signal H/W interrupt to the other side)
> +Other bits are reserved, should be 0.
> +
> +3.2.2 Transport layer interface
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +To abstract HW level IPC communication, a set of callbacks are registered.
> +The transport layer uses them to send and receive messages.
> +Refer to  struct ishtp_hw_ops for callbacks.
> +
> +3.3 ISH Transport layer
> +-----------------------
> +
> +Location: drivers/hid/intel-ish-hid/ishtp/
> +
> +3.3.1 A Generic Transport Layer
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +The transport layer is a bi-directional protocol, which defines:
> +- Set of commands to start, stop, connect, disconnect and flow control
> +(ishtp/hbm.h) for details
> +- A flow control mechanism to avoid buffer overflows
> +
> +This protocol resembles bus messages described in the following document:
> +http://www.intel.com/content/dam/www/public/us/en/documents/technical-\
> +specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer"
> +
> +3.3.2 Connection and Flow Control Mechanism
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Each FW client and a protocol is identified by an UUID. In order to communicate
> +to a FW client, a connection must be established using connect request and
> +response bus messages. If successful, a pair (host_client_id and fw_client_id)
> +will identify the connection.
> +
> +Once connection is established, peers send each other flow control bus messages
> +independently. Every peer may send a message only if it has received a
> +flow-control credit before. Once it sent a message, it may not send another one
> +before receiving the next flow control credit.
> +Either side can send disconnect request bus message to end communication. Also
> +the link will be dropped if major FW reset occurs.
> +
> +3.3.3 Peer to Peer data transfer
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Peer to Peer data transfer can happen with or without using DMA. Depending on
> +the sensor bandwidth requirement DMA can be enabled by using module parameter
> +ishtp_use_dma under intel_ishtp.
> +
> +Each side (host and FW) manages its DMA transfer memory independently. When an
> +ISHTP client from either host or FW side wants to send something, it decides
> +whether to send over IPC or over DMA; for each transfer the decision is
> +independent. The sending side sends DMA_XFER message when the message is in
> +the respective host buffer (TX when host client sends, RX when FW client
> +sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating
> +the sender that the memory region for that message may be reused.
> +
> +DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message
> +(that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK.
> +Additionally to DMA address communication, this sequence checks capabilities:
> +if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't
> +send DMA; if FW doesn't support DMA then it won't respond with
> +DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers.
> +Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER,
> +it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means
> +that it already did DMA and the message resides at host. Thus, DMA_XFER
> +and DMA_XFER_ACK act as ownership indicators.
> +
> +At initial state all outgoing memory belongs to the sender (TX to host, RX to
> +FW), DMA_XFER transfers ownership on the region that contains ISHTP message to
> +the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender
> +needs not wait for previous DMA_XFER to be ack'ed, and may send another message
> +as long as remaining continuous memory in its ownership is enough.
> +In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once
> +(up to IPC MTU), thus allowing for interrupt throttling.
> +Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC
> +fragments and via IPC otherwise.
> +
> +3.3.4 Ring Buffers
> +^^^^^^^^^^^^^^^^^^
> +
> +When a client initiate a connection, a ring or RX and TX buffers are allocated.
> +The size of ring can be specified by the client. HID client set 16 and 32 for
> +TX and RX buffers respectively. On send request from client, the data to be
> +sent is copied to one of the send ring buffer and scheduled to be sent using
> +bus message protocol. These buffers are required because the FW may have not
> +have processed the last message and may not have enough flow control credits
> +to send. Same thing holds true on receive side and flow control is required.
> +
> +3.3.5 Host Enumeration
> +^^^^^^^^^^^^^^^^^^^^^^
> +
> +The host enumeration bus command allow discovery of clients present in the FW.
> +There can be multiple sensor clients and clients for calibration function.
> +
> +To ease in implantation and allow independent driver handle each client
> +this transport layer takes advantage of Linux Bus driver model. Each
> +client is registered as device on the the transport bus (ishtp bus).
> +
> +Enumeration sequence of messages:
> +
> +- Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up.
> +- FW responds with HOST_START_RES_CMD
> +- Host sends HOST_ENUM_REQ_CMD (enumerate FW clients)
> +- FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW
> +  client IDs
> +- For each FW ID found in that bitmap host sends
> +  HOST_CLIENT_PROPERTIES_REQ_CMD
> +- FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID,
> +  max ISHTP message size, etc.
> +- Once host received properties for that last discovered client, it considers
> +  ISHTP device fully functional (and allocates DMA buffers)
> +
> +3.4 HID over ISH Client
> +-----------------------
> +
> +Location: drivers/hid/intel-ish-hid
> +
> +The ISHTP client driver is responsible for:
> +
> +- enumerate HID devices under FW ISH client
> +- Get Report descriptor
> +- Register with HID core as a LL driver
> +- Process Get/Set feature request
> +- Get input reports
> +
> +3.5 HID Sensor Hub MFD and IIO sensor drivers
> +---------------------------------------------
> +
> +The functionality in these drivers is the same as an external sensor hub.
> +Refer to
> +Documentation/hid/hid-sensor.rst for HID sensor
> +Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space
> +
> +3.6 End to End HID transport Sequence Diagram
> +---------------------------------------------
> +
> +::
> +
> +  HID-ISH-CLN                    ISHTP                    IPC                             HW
> +          |                        |                       |                               |
> +          |                        |                       |-----WAKE UP------------------>|
> +          |                        |                       |                               |
> +          |                        |                       |-----HOST READY--------------->|
> +          |                        |                       |                               |
> +          |                        |                       |<----MNG_RESET_NOTIFY_ACK----- |
> +          |                        |                       |                               |
> +          |                        |<----ISHTP_START------ |                               |
> +          |                        |                       |                               |
> +          |                        |<-----------------HOST_START_RES_CMD-------------------|
> +          |                        |                       |                               |
> +          |                        |------------------QUERY_SUBSCRIBER-------------------->|
> +          |                        |                       |                               |
> +          |                        |------------------HOST_ENUM_REQ_CMD------------------->|
> +          |                        |                       |                               |
> +          |                        |<-----------------HOST_ENUM_RES_CMD--------------------|
> +          |                        |                       |                               |
> +          |                        |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
> +          |                        |                       |                               |
> +          |                        |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
> +          |       Create new device on in ishtp bus        |                               |
> +          |                        |                       |                               |
> +          |                        |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
> +          |                        |                       |                               |
> +          |                        |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
> +          |       Create new device on in ishtp bus        |                               |
> +          |                        |                       |                               |
> +          |                        |--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--|
> +          |                        |                       |                               |
> +       probed()
> +          |----ishtp_cl_connect--->|----------------- CLIENT_CONNECT_REQ_CMD-------------->|
> +          |                        |                       |                               |
> +          |                        |<----------------CLIENT_CONNECT_RES_CMD----------------|
> +          |                        |                       |                               |
> +          |register event callback |                       |                               |
> +          |                        |                       |                               |
> +          |ishtp_cl_send(
> +          HOSTIF_DM_ENUM_DEVICES)  |----------fill ishtp_msg_hdr struct write to HW-----  >|
> +          |                        |                       |                               |
> +          |                        |                       |<-----IRQ(IPC_PROTOCOL_ISHTP---|
> +          |                        |                       |                               |
> +          |<--ENUM_DEVICE RSP------|                       |                               |
> +          |                        |                       |                               |
> +  for each enumerated device
> +          |ishtp_cl_send(
> +          HOSTIF_GET_HID_DESCRIPTOR|----------fill ishtp_msg_hdr struct write to HW-----  >|
> +          |                        |                       |                               |
> +          ...Response
> +          |                        |                       |                               |
> +  for each enumerated device
> +          |ishtp_cl_send(
> +       HOSTIF_GET_REPORT_DESCRIPTOR|--------------fill ishtp_msg_hdr struct write to HW-- >|
> +          |                        |                       |                               |
> +          |                        |                       |                               |
> +   hid_allocate_device
> +          |                        |                       |                               |
> +   hid_add_device                  |                       |                               |
> +          |                        |                       |                               |
> +
> +
> +3.7 ISH Debugging
> +-----------------
> +
> +To debug ISH, event tracing mechanism is used. To enable debug logs
> +echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable
> +cat sys/kernel/debug/tracing/trace
> +
> +3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260
> +-----------------------------------------------------
> +
> +::
> +
> +  root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/
> +  /sys/bus/iio/devices/
> +  ├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0
> +  │   ├── buffer
> +  │   │   ├── enable
> +  │   │   ├── length
> +  │   │   └── watermark
> +  ...
> +  │   ├── in_accel_hysteresis
> +  │   ├── in_accel_offset
> +  │   ├── in_accel_sampling_frequency
> +  │   ├── in_accel_scale
> +  │   ├── in_accel_x_raw
> +  │   ├── in_accel_y_raw
> +  │   ├── in_accel_z_raw
> +  │   ├── name
> +  │   ├── scan_elements
> +  │   │   ├── in_accel_x_en
> +  │   │   ├── in_accel_x_index
> +  │   │   ├── in_accel_x_type
> +  │   │   ├── in_accel_y_en
> +  │   │   ├── in_accel_y_index
> +  │   │   ├── in_accel_y_type
> +  │   │   ├── in_accel_z_en
> +  │   │   ├── in_accel_z_index
> +  │   │   └── in_accel_z_type
> +  ...
> +  │   │   ├── devices
> +  │   │   │   │   ├── buffer
> +  │   │   │   │   │   ├── enable
> +  │   │   │   │   │   ├── length
> +  │   │   │   │   │   └── watermark
> +  │   │   │   │   ├── dev
> +  │   │   │   │   ├── in_intensity_both_raw
> +  │   │   │   │   ├── in_intensity_hysteresis
> +  │   │   │   │   ├── in_intensity_offset
> +  │   │   │   │   ├── in_intensity_sampling_frequency
> +  │   │   │   │   ├── in_intensity_scale
> +  │   │   │   │   ├── name
> +  │   │   │   │   ├── scan_elements
> +  │   │   │   │   │   ├── in_intensity_both_en
> +  │   │   │   │   │   ├── in_intensity_both_index
> +  │   │   │   │   │   └── in_intensity_both_type
> +  │   │   │   │   ├── trigger
> +  │   │   │   │   │   └── current_trigger
> +  ...
> +  │   │   │   │   ├── buffer
> +  │   │   │   │   │   ├── enable
> +  │   │   │   │   │   ├── length
> +  │   │   │   │   │   └── watermark
> +  │   │   │   │   ├── dev
> +  │   │   │   │   ├── in_magn_hysteresis
> +  │   │   │   │   ├── in_magn_offset
> +  │   │   │   │   ├── in_magn_sampling_frequency
> +  │   │   │   │   ├── in_magn_scale
> +  │   │   │   │   ├── in_magn_x_raw
> +  │   │   │   │   ├── in_magn_y_raw
> +  │   │   │   │   ├── in_magn_z_raw
> +  │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_raw
> +  │   │   │   │   ├── in_rot_hysteresis
> +  │   │   │   │   ├── in_rot_offset
> +  │   │   │   │   ├── in_rot_sampling_frequency
> +  │   │   │   │   ├── in_rot_scale
> +  │   │   │   │   ├── name
> +  ...
> +  │   │   │   │   ├── scan_elements
> +  │   │   │   │   │   ├── in_magn_x_en
> +  │   │   │   │   │   ├── in_magn_x_index
> +  │   │   │   │   │   ├── in_magn_x_type
> +  │   │   │   │   │   ├── in_magn_y_en
> +  │   │   │   │   │   ├── in_magn_y_index
> +  │   │   │   │   │   ├── in_magn_y_type
> +  │   │   │   │   │   ├── in_magn_z_en
> +  │   │   │   │   │   ├── in_magn_z_index
> +  │   │   │   │   │   ├── in_magn_z_type
> +  │   │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_en
> +  │   │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_index
> +  │   │   │   │   │   └── in_rot_from_north_magnetic_tilt_comp_type
> +  │   │   │   │   ├── trigger
> +  │   │   │   │   │   └── current_trigger
> +  ...
> +  │   │   │   │   ├── buffer
> +  │   │   │   │   │   ├── enable
> +  │   │   │   │   │   ├── length
> +  │   │   │   │   │   └── watermark
> +  │   │   │   │   ├── dev
> +  │   │   │   │   ├── in_anglvel_hysteresis
> +  │   │   │   │   ├── in_anglvel_offset
> +  │   │   │   │   ├── in_anglvel_sampling_frequency
> +  │   │   │   │   ├── in_anglvel_scale
> +  │   │   │   │   ├── in_anglvel_x_raw
> +  │   │   │   │   ├── in_anglvel_y_raw
> +  │   │   │   │   ├── in_anglvel_z_raw
> +  │   │   │   │   ├── name
> +  │   │   │   │   ├── scan_elements
> +  │   │   │   │   │   ├── in_anglvel_x_en
> +  │   │   │   │   │   ├── in_anglvel_x_index
> +  │   │   │   │   │   ├── in_anglvel_x_type
> +  │   │   │   │   │   ├── in_anglvel_y_en
> +  │   │   │   │   │   ├── in_anglvel_y_index
> +  │   │   │   │   │   ├── in_anglvel_y_type
> +  │   │   │   │   │   ├── in_anglvel_z_en
> +  │   │   │   │   │   ├── in_anglvel_z_index
> +  │   │   │   │   │   └── in_anglvel_z_type
> +  │   │   │   │   ├── trigger
> +  │   │   │   │   │   └── current_trigger
> +  ...
> +  │   │   │   │   ├── buffer
> +  │   │   │   │   │   ├── enable
> +  │   │   │   │   │   ├── length
> +  │   │   │   │   │   └── watermark
> +  │   │   │   │   ├── dev
> +  │   │   │   │   ├── in_anglvel_hysteresis
> +  │   │   │   │   ├── in_anglvel_offset
> +  │   │   │   │   ├── in_anglvel_sampling_frequency
> +  │   │   │   │   ├── in_anglvel_scale
> +  │   │   │   │   ├── in_anglvel_x_raw
> +  │   │   │   │   ├── in_anglvel_y_raw
> +  │   │   │   │   ├── in_anglvel_z_raw
> +  │   │   │   │   ├── name
> +  │   │   │   │   ├── scan_elements
> +  │   │   │   │   │   ├── in_anglvel_x_en
> +  │   │   │   │   │   ├── in_anglvel_x_index
> +  │   │   │   │   │   ├── in_anglvel_x_type
> +  │   │   │   │   │   ├── in_anglvel_y_en
> +  │   │   │   │   │   ├── in_anglvel_y_index
> +  │   │   │   │   │   ├── in_anglvel_y_type
> +  │   │   │   │   │   ├── in_anglvel_z_en
> +  │   │   │   │   │   ├── in_anglvel_z_index
> +  │   │   │   │   │   └── in_anglvel_z_type
> +  │   │   │   │   ├── trigger
> +  │   │   │   │   │   └── current_trigger
> +  ...
> diff --git a/Documentation/hid/intel-ish-hid.txt b/Documentation/hid/intel-ish-hid.txt
> deleted file mode 100644
> index d48b21c71ddd..000000000000
> --- a/Documentation/hid/intel-ish-hid.txt
> +++ /dev/null
> @@ -1,454 +0,0 @@
> -Intel Integrated Sensor Hub (ISH)
> -===============================
> -
> -A sensor hub enables the ability to offload sensor polling and algorithm
> -processing to a dedicated low power co-processor. This allows the core
> -processor to go into low power modes more often, resulting in the increased
> -battery life.
> -
> -There are many vendors providing external sensor hubs confirming to HID
> -Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops
> -and embedded products. Linux had this support since Linux 3.9.
> -
> -Intel® introduced integrated sensor hubs as a part of the SoC starting from
> -Cherry Trail and now supported on multiple generations of CPU packages. There
> -are many commercial devices already shipped with Integrated Sensor Hubs (ISH).
> -These ISH also comply to HID sensor specification, but the  difference is the
> -transport protocol used for communication. The current external sensor hubs
> -mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB.
> -
> -1. Overview
> -
> -Using a analogy with a usbhid implementation, the ISH follows a similar model
> -for a very high speed communication:
> -
> -       -----------------               ----------------------
> -       |    USB HID    |       -->     |    ISH HID         |
> -       -----------------               ----------------------
> -       -----------------               ----------------------
> -       |  USB protocol |       -->     |    ISH Transport   |
> -       -----------------               ----------------------
> -       -----------------               ----------------------
> -       |  EHCI/XHCI    |       -->     |    ISH IPC         |
> -       -----------------               ----------------------
> -             PCI                                PCI
> -       -----------------               ----------------------
> -        |Host controller|      -->     |    ISH processor   |
> -       -----------------               ----------------------
> -            USB Link
> -       -----------------               ----------------------
> -       | USB End points|       -->     |    ISH Clients     |
> -       -----------------               ----------------------
> -
> -Like USB protocol provides a method for device enumeration, link management
> -and user data encapsulation, the ISH also provides similar services. But it is
> -very light weight tailored to manage and communicate with ISH client
> -applications implemented in the firmware.
> -
> -The ISH allows multiple sensor management applications executing in the
> -firmware. Like USB endpoints the messaging can be to/from a client. As part of
> -enumeration process, these clients are identified. These clients can be simple
> -HID sensor applications, sensor calibration application or senor firmware
> -update application.
> -
> -The implementation model is similar, like USB bus, ISH transport is also
> -implemented as a bus. Each client application executing in the ISH processor
> -is registered as a device on this bus. The driver, which binds each device
> -(ISH HID driver) identifies the device type and registers with the hid core.
> -
> -2. ISH Implementation: Block Diagram
> -
> -        ---------------------------
> -       |  User Space Applications  |
> -        ---------------------------
> -
> -----------------IIO ABI----------------
> -        --------------------------
> -       |  IIO Sensor Drivers     |
> -        --------------------------
> -        --------------------------
> -       |        IIO core         |
> -        --------------------------
> -        --------------------------
> -       |   HID Sensor Hub MFD    |
> -        --------------------------
> -        --------------------------
> -       |       HID Core          |
> -        --------------------------
> -        --------------------------
> -       |   HID over ISH Client   |
> -        --------------------------
> -        --------------------------
> -       |   ISH Transport (ISHTP) |
> -        --------------------------
> -        --------------------------
> -       |      IPC Drivers        |
> -        --------------------------
> -OS
> -----------------   PCI -----------------
> -Hardware + Firmware
> -        ----------------------------
> -       | ISH Hardware/Firmware(FW) |
> -        ----------------------------
> -
> -3. High level processing in above blocks
> -
> -3.1 Hardware Interface
> -
> -The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI
> -product and vendor IDs are changed from different generations of processors. So
> -the source code which enumerate drivers needs to update from generation to
> -generation.
> -
> -3.2 Inter Processor Communication (IPC) driver
> -Location: drivers/hid/intel-ish-hid/ipc
> -
> -The IPC message used memory mapped I/O. The registers are defined in
> -hw-ish-regs.h.
> -
> -3.2.1 IPC/FW message types
> -
> -There are two types of messages, one for management of link and other messages
> -are to and from transport layers.
> -
> -TX and RX of Transport messages
> -
> -A set of memory mapped register offers support of multi byte messages TX and
> -RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains
> -internal queues to sequence messages and send them in order to the FW.
> -Optionally the caller can register handler to get notification of completion.
> -A door bell mechanism is used in messaging to trigger processing in host and
> -client firmware side. When ISH interrupt handler is called, the ISH2HOST
> -doorbell register is used by host drivers to determine that the interrupt
> -is for ISH.
> -
> -Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell
> -register has the following format:
> -Bits 0..6: fragment length (7 bits are used)
> -Bits 10..13: encapsulated protocol
> -Bits 16..19: management command (for IPC management protocol)
> -Bit 31: doorbell trigger (signal H/W interrupt to the other side)
> -Other bits are reserved, should be 0.
> -
> -3.2.2 Transport layer interface
> -
> -To abstract HW level IPC communication, a set of callbacks are registered.
> -The transport layer uses them to send and receive messages.
> -Refer to  struct ishtp_hw_ops for callbacks.
> -
> -3.3 ISH Transport layer
> -Location: drivers/hid/intel-ish-hid/ishtp/
> -
> -3.3.1 A Generic Transport Layer
> -
> -The transport layer is a bi-directional protocol, which defines:
> -- Set of commands to start, stop, connect, disconnect and flow control
> -(ishtp/hbm.h) for details
> -- A flow control mechanism to avoid buffer overflows
> -
> -This protocol resembles bus messages described in the following document:
> -http://www.intel.com/content/dam/www/public/us/en/documents/technical-\
> -specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer"
> -
> -3.3.2 Connection and Flow Control Mechanism
> -
> -Each FW client and a protocol is identified by an UUID. In order to communicate
> -to a FW client, a connection must be established using connect request and
> -response bus messages. If successful, a pair (host_client_id and fw_client_id)
> -will identify the connection.
> -
> -Once connection is established, peers send each other flow control bus messages
> -independently. Every peer may send a message only if it has received a
> -flow-control credit before. Once it sent a message, it may not send another one
> -before receiving the next flow control credit.
> -Either side can send disconnect request bus message to end communication. Also
> -the link will be dropped if major FW reset occurs.
> -
> -3.3.3 Peer to Peer data transfer
> -
> -Peer to Peer data transfer can happen with or without using DMA. Depending on
> -the sensor bandwidth requirement DMA can be enabled by using module parameter
> -ishtp_use_dma under intel_ishtp.
> -
> -Each side (host and FW) manages its DMA transfer memory independently. When an
> -ISHTP client from either host or FW side wants to send something, it decides
> -whether to send over IPC or over DMA; for each transfer the decision is
> -independent. The sending side sends DMA_XFER message when the message is in
> -the respective host buffer (TX when host client sends, RX when FW client
> -sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating
> -the sender that the memory region for that message may be reused.
> -
> -DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message
> -(that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK.
> -Additionally to DMA address communication, this sequence checks capabilities:
> -if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't
> -send DMA; if FW doesn't support DMA then it won't respond with
> -DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers.
> -Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER,
> -it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means
> -that it already did DMA and the message resides at host. Thus, DMA_XFER
> -and DMA_XFER_ACK act as ownership indicators.
> -
> -At initial state all outgoing memory belongs to the sender (TX to host, RX to
> -FW), DMA_XFER transfers ownership on the region that contains ISHTP message to
> -the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender
> -needs not wait for previous DMA_XFER to be ack'ed, and may send another message
> -as long as remaining continuous memory in its ownership is enough.
> -In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once
> -(up to IPC MTU), thus allowing for interrupt throttling.
> -Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC
> -fragments and via IPC otherwise.
> -
> -3.3.4 Ring Buffers
> -
> -When a client initiate a connection, a ring or RX and TX buffers are allocated.
> -The size of ring can be specified by the client. HID client set 16 and 32 for
> -TX and RX buffers respectively. On send request from client, the data to be
> -sent is copied to one of the send ring buffer and scheduled to be sent using
> -bus message protocol. These buffers are required because the FW may have not
> -have processed the last message and may not have enough flow control credits
> -to send. Same thing holds true on receive side and flow control is required.
> -
> -3.3.5 Host Enumeration
> -
> -The host enumeration bus command allow discovery of clients present in the FW.
> -There can be multiple sensor clients and clients for calibration function.
> -
> -To ease in implantation and allow independent driver handle each client
> -this transport layer takes advantage of Linux Bus driver model. Each
> -client is registered as device on the the transport bus (ishtp bus).
> -
> -Enumeration sequence of messages:
> -- Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up.
> -- FW responds with HOST_START_RES_CMD
> -- Host sends HOST_ENUM_REQ_CMD (enumerate FW clients)
> -- FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW
> -client IDs
> -- For each FW ID found in that bitmap host sends
> -HOST_CLIENT_PROPERTIES_REQ_CMD
> -- FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID,
> -max ISHTP message size, etc.
> -- Once host received properties for that last discovered client, it considers
> -ISHTP device fully functional (and allocates DMA buffers)
> -
> -3.4 HID over ISH Client
> -Location: drivers/hid/intel-ish-hid
> -
> -The ISHTP client driver is responsible for:
> -- enumerate HID devices under FW ISH client
> -- Get Report descriptor
> -- Register with HID core as a LL driver
> -- Process Get/Set feature request
> -- Get input reports
> -
> -3.5 HID Sensor Hub MFD and IIO sensor drivers
> -
> -The functionality in these drivers is the same as an external sensor hub.
> -Refer to
> -Documentation/hid/hid-sensor.txt for HID sensor
> -Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space
> -
> -3.6 End to End HID transport Sequence Diagram
> -
> -HID-ISH-CLN                    ISHTP                   IPC                             HW
> -       |                       |                       |                               |
> -       |                       |                       |-----WAKE UP------------------>|
> -       |                       |                       |                               |
> -       |                       |                       |-----HOST READY--------------->|
> -       |                       |                       |                               |
> -       |                       |                       |<----MNG_RESET_NOTIFY_ACK----- |
> -       |                       |                       |                               |
> -       |                       |<----ISHTP_START------ |                               |
> -       |                       |                       |                               |
> -       |                       |<-----------------HOST_START_RES_CMD-------------------|
> -       |                       |                       |                               |
> -       |                       |------------------QUERY_SUBSCRIBER-------------------->|
> -       |                       |                       |                               |
> -       |                       |------------------HOST_ENUM_REQ_CMD------------------->|
> -       |                       |                       |                               |
> -       |                       |<-----------------HOST_ENUM_RES_CMD--------------------|
> -       |                       |                       |                               |
> -       |                       |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
> -       |                       |                       |                               |
> -       |                       |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
> -       |       Create new device on in ishtp bus       |                               |
> -       |                       |                       |                               |
> -       |                       |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
> -       |                       |                       |                               |
> -       |                       |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
> -       |       Create new device on in ishtp bus       |                               |
> -       |                       |                       |                               |
> -       |                       |--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--|
> -       |                       |                       |                               |
> -     probed()
> -       |----ishtp_cl_connect-->|----------------- CLIENT_CONNECT_REQ_CMD-------------->|
> -       |                       |                       |                               |
> -       |                       |<----------------CLIENT_CONNECT_RES_CMD----------------|
> -       |                       |                       |                               |
> -       |register event callback|                       |                               |
> -       |                       |                       |                               |
> -       |ishtp_cl_send(
> -       HOSTIF_DM_ENUM_DEVICES) |----------fill ishtp_msg_hdr struct write to HW-----  >|
> -       |                       |                       |                               |
> -       |                       |                       |<-----IRQ(IPC_PROTOCOL_ISHTP---|
> -       |                       |                       |                               |
> -       |<--ENUM_DEVICE RSP-----|                       |                               |
> -       |                       |                       |                               |
> -for each enumerated device
> -       |ishtp_cl_send(
> -       HOSTIF_GET_HID_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW---  >|
> -       |                       |                       |                               |
> -       ...Response
> -       |                       |                       |                               |
> -for each enumerated device
> -       |ishtp_cl_send(
> -       HOSTIF_GET_REPORT_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW- >|
> -       |                       |                       |                               |
> -       |                       |                       |                               |
> - hid_allocate_device
> -       |                       |                       |                               |
> - hid_add_device                        |                       |                               |
> -       |                       |                       |                               |
> -
> -
> -3.7 ISH Debugging
> -
> -To debug ISH, event tracing mechanism is used. To enable debug logs
> -echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable
> -cat sys/kernel/debug/tracing/trace
> -
> -3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260
> -
> -root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/
> -/sys/bus/iio/devices/
> -├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0
> -│   ├── buffer
> -│   │   ├── enable
> -│   │   ├── length
> -│   │   └── watermark
> -...
> -│   ├── in_accel_hysteresis
> -│   ├── in_accel_offset
> -│   ├── in_accel_sampling_frequency
> -│   ├── in_accel_scale
> -│   ├── in_accel_x_raw
> -│   ├── in_accel_y_raw
> -│   ├── in_accel_z_raw
> -│   ├── name
> -│   ├── scan_elements
> -│   │   ├── in_accel_x_en
> -│   │   ├── in_accel_x_index
> -│   │   ├── in_accel_x_type
> -│   │   ├── in_accel_y_en
> -│   │   ├── in_accel_y_index
> -│   │   ├── in_accel_y_type
> -│   │   ├── in_accel_z_en
> -│   │   ├── in_accel_z_index
> -│   │   └── in_accel_z_type
> -...
> -│   │   ├── devices
> -│   │   │   │   ├── buffer
> -│   │   │   │   │   ├── enable
> -│   │   │   │   │   ├── length
> -│   │   │   │   │   └── watermark
> -│   │   │   │   ├── dev
> -│   │   │   │   ├── in_intensity_both_raw
> -│   │   │   │   ├── in_intensity_hysteresis
> -│   │   │   │   ├── in_intensity_offset
> -│   │   │   │   ├── in_intensity_sampling_frequency
> -│   │   │   │   ├── in_intensity_scale
> -│   │   │   │   ├── name
> -│   │   │   │   ├── scan_elements
> -│   │   │   │   │   ├── in_intensity_both_en
> -│   │   │   │   │   ├── in_intensity_both_index
> -│   │   │   │   │   └── in_intensity_both_type
> -│   │   │   │   ├── trigger
> -│   │   │   │   │   └── current_trigger
> -...
> -│   │   │   │   ├── buffer
> -│   │   │   │   │   ├── enable
> -│   │   │   │   │   ├── length
> -│   │   │   │   │   └── watermark
> -│   │   │   │   ├── dev
> -│   │   │   │   ├── in_magn_hysteresis
> -│   │   │   │   ├── in_magn_offset
> -│   │   │   │   ├── in_magn_sampling_frequency
> -│   │   │   │   ├── in_magn_scale
> -│   │   │   │   ├── in_magn_x_raw
> -│   │   │   │   ├── in_magn_y_raw
> -│   │   │   │   ├── in_magn_z_raw
> -│   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_raw
> -│   │   │   │   ├── in_rot_hysteresis
> -│   │   │   │   ├── in_rot_offset
> -│   │   │   │   ├── in_rot_sampling_frequency
> -│   │   │   │   ├── in_rot_scale
> -│   │   │   │   ├── name
> -...
> -│   │   │   │   ├── scan_elements
> -│   │   │   │   │   ├── in_magn_x_en
> -│   │   │   │   │   ├── in_magn_x_index
> -│   │   │   │   │   ├── in_magn_x_type
> -│   │   │   │   │   ├── in_magn_y_en
> -│   │   │   │   │   ├── in_magn_y_index
> -│   │   │   │   │   ├── in_magn_y_type
> -│   │   │   │   │   ├── in_magn_z_en
> -│   │   │   │   │   ├── in_magn_z_index
> -│   │   │   │   │   ├── in_magn_z_type
> -│   │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_en
> -│   │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_index
> -│   │   │   │   │   └── in_rot_from_north_magnetic_tilt_comp_type
> -│   │   │   │   ├── trigger
> -│   │   │   │   │   └── current_trigger
> -...
> -│   │   │   │   ├── buffer
> -│   │   │   │   │   ├── enable
> -│   │   │   │   │   ├── length
> -│   │   │   │   │   └── watermark
> -│   │   │   │   ├── dev
> -│   │   │   │   ├── in_anglvel_hysteresis
> -│   │   │   │   ├── in_anglvel_offset
> -│   │   │   │   ├── in_anglvel_sampling_frequency
> -│   │   │   │   ├── in_anglvel_scale
> -│   │   │   │   ├── in_anglvel_x_raw
> -│   │   │   │   ├── in_anglvel_y_raw
> -│   │   │   │   ├── in_anglvel_z_raw
> -│   │   │   │   ├── name
> -│   │   │   │   ├── scan_elements
> -│   │   │   │   │   ├── in_anglvel_x_en
> -│   │   │   │   │   ├── in_anglvel_x_index
> -│   │   │   │   │   ├── in_anglvel_x_type
> -│   │   │   │   │   ├── in_anglvel_y_en
> -│   │   │   │   │   ├── in_anglvel_y_index
> -│   │   │   │   │   ├── in_anglvel_y_type
> -│   │   │   │   │   ├── in_anglvel_z_en
> -│   │   │   │   │   ├── in_anglvel_z_index
> -│   │   │   │   │   └── in_anglvel_z_type
> -│   │   │   │   ├── trigger
> -│   │   │   │   │   └── current_trigger
> -...
> -│   │   │   │   ├── buffer
> -│   │   │   │   │   ├── enable
> -│   │   │   │   │   ├── length
> -│   │   │   │   │   └── watermark
> -│   │   │   │   ├── dev
> -│   │   │   │   ├── in_anglvel_hysteresis
> -│   │   │   │   ├── in_anglvel_offset
> -│   │   │   │   ├── in_anglvel_sampling_frequency
> -│   │   │   │   ├── in_anglvel_scale
> -│   │   │   │   ├── in_anglvel_x_raw
> -│   │   │   │   ├── in_anglvel_y_raw
> -│   │   │   │   ├── in_anglvel_z_raw
> -│   │   │   │   ├── name
> -│   │   │   │   ├── scan_elements
> -│   │   │   │   │   ├── in_anglvel_x_en
> -│   │   │   │   │   ├── in_anglvel_x_index
> -│   │   │   │   │   ├── in_anglvel_x_type
> -│   │   │   │   │   ├── in_anglvel_y_en
> -│   │   │   │   │   ├── in_anglvel_y_index
> -│   │   │   │   │   ├── in_anglvel_y_type
> -│   │   │   │   │   ├── in_anglvel_z_en
> -│   │   │   │   │   ├── in_anglvel_z_index
> -│   │   │   │   │   └── in_anglvel_z_type
> -│   │   │   │   ├── trigger
> -│   │   │   │   │   └── current_trigger
> -...
> diff --git a/Documentation/hid/uhid.txt b/Documentation/hid/uhid.rst
> similarity index 94%
> rename from Documentation/hid/uhid.txt
> rename to Documentation/hid/uhid.rst
> index 958fff945304..b18cb96c885f 100644
> --- a/Documentation/hid/uhid.txt
> +++ b/Documentation/hid/uhid.rst
> @@ -1,5 +1,6 @@
> -      UHID - User-space I/O driver support for HID subsystem
> -     ========================================================
> +======================================================
> +UHID - User-space I/O driver support for HID subsystem
> +======================================================
>
>  UHID allows user-space to implement HID transport drivers. Please see
>  hid-transport.txt for an introduction into HID transport drivers. This document
> @@ -22,9 +23,9 @@ If a new device is detected by your HID I/O Driver and you want to register this
>  device with the HID subsystem, then you need to open /dev/uhid once for each
>  device you want to register. All further communication is done by read()'ing or
>  write()'ing "struct uhid_event" objects. Non-blocking operations are supported
> -by setting O_NONBLOCK.
> +by setting O_NONBLOCK::
>
> -struct uhid_event {
> +  struct uhid_event {
>          __u32 type;
>          union {
>                  struct uhid_create2_req create2;
> @@ -32,7 +33,7 @@ struct uhid_event {
>                  struct uhid_input2_req input2;
>                  ...
>          } u;
> -};
> +  };
>
>  The "type" field contains the ID of the event. Depending on the ID different
>  payloads are sent. You must not split a single event across multiple read()'s or
> @@ -86,31 +87,31 @@ the request was handled successfully. O_NONBLOCK does not affect write() as
>  writes are always handled immediately in a non-blocking fashion. Future requests
>  might make use of O_NONBLOCK, though.
>
> -  UHID_CREATE2:
> +UHID_CREATE2:
>    This creates the internal HID device. No I/O is possible until you send this
>    event to the kernel. The payload is of type struct uhid_create2_req and
>    contains information about your device. You can start I/O now.
>
> -  UHID_DESTROY:
> +UHID_DESTROY:
>    This destroys the internal HID device. No further I/O will be accepted. There
>    may still be pending messages that you can receive with read() but no further
>    UHID_INPUT events can be sent to the kernel.
>    You can create a new device by sending UHID_CREATE2 again. There is no need to
>    reopen the character device.
>
> -  UHID_INPUT2:
> +UHID_INPUT2:
>    You must send UHID_CREATE2 before sending input to the kernel! This event
>    contains a data-payload. This is the raw data that you read from your device
>    on the interrupt channel. The kernel will parse the HID reports.
>
> -  UHID_GET_REPORT_REPLY:
> +UHID_GET_REPORT_REPLY:
>    If you receive a UHID_GET_REPORT request you must answer with this request.
>    You  must copy the "id" field from the request into the answer. Set the "err"
>    field to 0 if no error occurred or to EIO if an I/O error occurred.
>    If "err" is 0 then you should fill the buffer of the answer with the results
>    of the GET_REPORT request and set "size" correspondingly.
>
> -  UHID_SET_REPORT_REPLY:
> +UHID_SET_REPORT_REPLY:
>    This is the SET_REPORT equivalent of UHID_GET_REPORT_REPLY. Unlike GET_REPORT,
>    SET_REPORT never returns a data buffer, therefore, it's sufficient to set the
>    "id" and "err" fields correctly.
> @@ -120,16 +121,18 @@ read()
>  read() will return a queued output report. No reaction is required to any of
>  them but you should handle them according to your needs.
>
> -  UHID_START:
> +UHID_START:
>    This is sent when the HID device is started. Consider this as an answer to
>    UHID_CREATE2. This is always the first event that is sent. Note that this
>    event might not be available immediately after write(UHID_CREATE2) returns.
>    Device drivers might required delayed setups.
>    This event contains a payload of type uhid_start_req. The "dev_flags" field
>    describes special behaviors of a device. The following flags are defined:
> -      UHID_DEV_NUMBERED_FEATURE_REPORTS:
> -      UHID_DEV_NUMBERED_OUTPUT_REPORTS:
> -      UHID_DEV_NUMBERED_INPUT_REPORTS:
> +
> +      - UHID_DEV_NUMBERED_FEATURE_REPORTS
> +      - UHID_DEV_NUMBERED_OUTPUT_REPORTS
> +      - UHID_DEV_NUMBERED_INPUT_REPORTS
> +
>            Each of these flags defines whether a given report-type uses numbered
>            reports. If numbered reports are used for a type, all messages from
>            the kernel already have the report-number as prefix. Otherwise, no
> @@ -137,33 +140,35 @@ them but you should handle them according to your needs.
>            For messages sent by user-space to the kernel, you must adjust the
>            prefixes according to these flags.
>
> -  UHID_STOP:
> +UHID_STOP:
>    This is sent when the HID device is stopped. Consider this as an answer to
>    UHID_DESTROY.
> +
>    If you didn't destroy your device via UHID_DESTROY, but the kernel sends an
>    UHID_STOP event, this should usually be ignored. It means that the kernel
>    reloaded/changed the device driver loaded on your HID device (or some other
>    maintenance actions happened).
> +
>    You can usually ignored any UHID_STOP events safely.
>
> -  UHID_OPEN:
> +UHID_OPEN:
>    This is sent when the HID device is opened. That is, the data that the HID
>    device provides is read by some other process. You may ignore this event but
>    it is useful for power-management. As long as you haven't received this event
>    there is actually no other process that reads your data so there is no need to
>    send UHID_INPUT2 events to the kernel.
>
> -  UHID_CLOSE:
> +UHID_CLOSE:
>    This is sent when there are no more processes which read the HID data. It is
>    the counterpart of UHID_OPEN and you may as well ignore this event.
>
> -  UHID_OUTPUT:
> +UHID_OUTPUT:
>    This is sent if the HID device driver wants to send raw data to the I/O
>    device on the interrupt channel. You should read the payload and forward it to
>    the device. The payload is of type "struct uhid_output_req".
>    This may be received even though you haven't received UHID_OPEN, yet.
>
> -  UHID_GET_REPORT:
> +UHID_GET_REPORT:
>    This event is sent if the kernel driver wants to perform a GET_REPORT request
>    on the control channeld as described in the HID specs. The report-type and
>    report-number are available in the payload.
> @@ -177,11 +182,12 @@ them but you should handle them according to your needs.
>    timed out, the kernel will ignore the response silently. The "id" field is
>    never re-used, so conflicts cannot happen.
>
> -  UHID_SET_REPORT:
> +UHID_SET_REPORT:
>    This is the SET_REPORT equivalent of UHID_GET_REPORT. On receipt, you shall
>    send a SET_REPORT request to your hid device. Once it replies, you must tell
>    the kernel about it via UHID_SET_REPORT_REPLY.
>    The same restrictions as for UHID_GET_REPORT apply.
>
>  ----------------------------------------------------
> +
>  Written 2012, David Herrmann <dh.herrmann@gmail.com>
> diff --git a/Documentation/input/input.rst b/Documentation/input/input.rst
> index 47f86a4bf16c..0eb61e67a7b7 100644
> --- a/Documentation/input/input.rst
> +++ b/Documentation/input/input.rst
> @@ -188,7 +188,7 @@ LCDs and many other purposes.
>
>  The monitor and speaker controls should be easy to add to the hid/input
>  interface, but for the UPSs and LCDs it doesn't make much sense. For this,
> -the hiddev interface was designed. See Documentation/hid/hiddev.txt
> +the hiddev interface was designed. See Documentation/hid/hiddev.rst
>  for more information about it.
>
>  The usage of the usbhid module is very simple, it takes no parameters,
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 8d39979e4091..969225e6bfce 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -16383,7 +16383,7 @@ M:      Benjamin Tissoires <benjamin.tissoires@redhat.com>
>  L:     linux-usb@vger.kernel.org
>  T:     git git://git.kernel.org/pub/scm/linux/kernel/git/hid/hid.git
>  S:     Maintained
> -F:     Documentation/hid/hiddev.txt
> +F:     Documentation/hid/hiddev.rst
>  F:     drivers/hid/usbhid/
>
>  USB INTEL XHCI ROLE MUX DRIVER
> --
> 2.21.0
>

^ permalink raw reply	[flat|nested] 38+ messages in thread

* Re: [PATCH v1 20/31] docs: hid: convert to ReST
  2019-06-13  8:08   ` Benjamin Tissoires
@ 2019-06-13  9:52     ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 38+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-13  9:52 UTC (permalink / raw)
  To: Benjamin Tissoires
  Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, lkml,
	Jonathan Corbet, Jiri Kosina, Jonathan Cameron,
	Srinivas Pandruvada, Dmitry Torokhov, open list:HID CORE LAYER,
	linux-iio, Linux USB Mailing List

Em Thu, 13 Jun 2019 10:08:34 +0200
Benjamin Tissoires <benjamin.tissoires@redhat.com> escreveu:

> On Wed, Jun 12, 2019 at 8:39 PM Mauro Carvalho Chehab
> <mchehab+samsung@kernel.org> wrote:
> >
> > Rename the HID documentation files to ReST, add an
> > index for them and adjust in order to produce a nice html
> > output via the Sphinx build system.
> >
> > While here, fix the sysfs example from hid-sensor.txt, that
> > has a lot of "?" instead of the proper UTF-8 characters that
> > are produced by the tree command.
> >
> > 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: Benjamin Tissoires <benjamin.tissoires@redhat.com>
> 
> Do you need to take this patch through the doc tree or should we carry
> it in the HID one?

Each patch in this series is pretty much independent. So, feel
free to apply it via the HID tree. 

> 
> Cheers,
> Benjamin
> 
> >  .../hid/{hid-alps.txt => hid-alps.rst}        |  85 ++-
> >  .../hid/{hid-sensor.txt => hid-sensor.rst}    | 192 +++----
> >  .../{hid-transport.txt => hid-transport.rst}  |  82 ++-
> >  Documentation/hid/{hiddev.txt => hiddev.rst}  | 154 ++++--
> >  Documentation/hid/{hidraw.txt => hidraw.rst}  |  53 +-
> >  Documentation/hid/index.rst                   |  18 +
> >  Documentation/hid/intel-ish-hid.rst           | 485 ++++++++++++++++++
> >  Documentation/hid/intel-ish-hid.txt           | 454 ----------------
> >  Documentation/hid/{uhid.txt => uhid.rst}      |  46 +-
> >  Documentation/input/input.rst                 |   2 +-
> >  MAINTAINERS                                   |   2 +-
> >  11 files changed, 897 insertions(+), 676 deletions(-)
> >  rename Documentation/hid/{hid-alps.txt => hid-alps.rst} (64%)
> >  rename Documentation/hid/{hid-sensor.txt => hid-sensor.rst} (61%)
> >  rename Documentation/hid/{hid-transport.txt => hid-transport.rst} (93%)
> >  rename Documentation/hid/{hiddev.txt => hiddev.rst} (77%)
> >  rename Documentation/hid/{hidraw.txt => hidraw.rst} (89%)
> >  create mode 100644 Documentation/hid/index.rst
> >  create mode 100644 Documentation/hid/intel-ish-hid.rst
> >  delete mode 100644 Documentation/hid/intel-ish-hid.txt
> >  rename Documentation/hid/{uhid.txt => uhid.rst} (94%)
> >
> > diff --git a/Documentation/hid/hid-alps.txt b/Documentation/hid/hid-alps.rst
> > similarity index 64%
> > rename from Documentation/hid/hid-alps.txt
> > rename to Documentation/hid/hid-alps.rst
> > index 6b02a2447c77..e2f4c4c11e3f 100644
> > --- a/Documentation/hid/hid-alps.txt
> > +++ b/Documentation/hid/hid-alps.rst
> > @@ -1,19 +1,26 @@
> > +==========================
> >  ALPS HID Touchpad Protocol
> > -----------------------
> > +==========================
> >
> >  Introduction
> >  ------------
> >  Currently ALPS HID driver supports U1 Touchpad device.
> >
> > -U1 devuce basic information.
> > +U1 device basic information.
> > +
> > +==========     ======
> >  Vender ID      0x044E
> >  Product ID     0x120B
> >  Version ID     0x0121
> > +==========     ======
> >
> >
> >  HID Descriptor
> > -------------
> > +--------------
> > +
> > +=======        ====================    =====   =======================================
> >  Byte   Field                   Value   Notes
> > +=======        ====================    =====   =======================================
> >  0      wHIDDescLength          001E    Length of HID Descriptor : 30 bytes
> >  2      bcdVersion              0100    Compliant with Version 1.00
> >  4      wReportDescLength       00B2    Report Descriptor is 178 Bytes (0x00B2)
> > @@ -28,32 +35,42 @@ Byte        Field                   Value   Notes
> >  22     wProductID              120B    Product ID 0x120B
> >  24     wVersionID              0121    Version 01.21
> >  26     RESERVED                0000    RESERVED
> > +=======        ====================    =====   =======================================
> >
> >
> >  Report ID
> > -------------
> > -ReportID-1     (Input Reports) (HIDUsage-Mouse) for TP&SP
> > -ReportID-2     (Input Reports) (HIDUsage-keyboard) for TP
> > -ReportID-3     (Input Reports) (Vendor Usage: Max 10 finger data) for TP
> > -ReportID-4     (Input Reports) (Vendor Usage: ON bit data) for GP
> > -ReportID-5     (Feature Reports)       Feature Reports
> > -ReportID-6     (Input Reports) (Vendor Usage: StickPointer data) for SP
> > -ReportID-7     (Feature Reports)       Flash update (Bootloader)
> > +---------
> > +
> > +==========     =================  =========================================
> > +ReportID-1     (Input Reports)    (HIDUsage-Mouse) for TP&SP
> > +ReportID-2     (Input Reports)    (HIDUsage-keyboard) for TP
> > +ReportID-3     (Input Reports)    (Vendor Usage: Max 10 finger data) for TP
> > +ReportID-4     (Input Reports)    (Vendor Usage: ON bit data) for GP
> > +ReportID-5     (Feature Reports)  Feature Reports
> > +ReportID-6     (Input Reports)    (Vendor Usage: StickPointer data) for SP
> > +ReportID-7     (Feature Reports)  Flash update (Bootloader)
> > +==========     =================  =========================================
> >
> >
> >  Data pattern
> >  ------------
> > +
> > +=====  ==========      =====   =================
> >  Case1  ReportID_1      TP/SP   Relative/Relative
> >  Case2  ReportID_3      TP      Absolute
> >         ReportID_6      SP      Absolute
> > +=====  ==========      =====   =================
> >
> >
> >  Command Read/Write
> >  ------------------
> >  To read/write to RAM, need to send a commands to the device.
> > +
> >  The command format is as below.
> >
> >  DataByte(SET_REPORT)
> > +
> > +=====  ======================
> >  Byte1  Command Byte
> >  Byte2  Address - Byte 0 (LSB)
> >  Byte3  Address - Byte 1
> > @@ -61,13 +78,19 @@ Byte4       Address - Byte 2
> >  Byte5  Address - Byte 3 (MSB)
> >  Byte6  Value Byte
> >  Byte7  Checksum
> > +=====  ======================
> >
> >  Command Byte is read=0xD1/write=0xD2 .
> > +
> >  Address is read/write RAM address.
> > +
> >  Value Byte is writing data when you send the write commands.
> > +
> >  When you read RAM, there is no meaning.
> >
> >  DataByte(GET_REPORT)
> > +
> > +=====  ======================
> >  Byte1  Response Byte
> >  Byte2  Address - Byte 0 (LSB)
> >  Byte3  Address - Byte 1
> > @@ -75,6 +98,7 @@ Byte4 Address - Byte 2
> >  Byte5  Address - Byte 3 (MSB)
> >  Byte6  Value Byte
> >  Byte7  Checksum
> > +=====  ======================
> >
> >  Read value is stored in Value Byte.
> >
> > @@ -82,7 +106,11 @@ Read value is stored in Value Byte.
> >  Packet Format
> >  Touchpad data byte
> >  ------------------
> > -       b7      b6      b5      b4      b3      b2      b1      b0
> > +
> > +
> > +======= ======= ======= ======= ======= ======= ======= ======= =====
> > +-      b7      b6      b5      b4      b3      b2      b1      b0
> > +======= ======= ======= ======= ======= ======= ======= ======= =====
> >  1      0       0       SW6     SW5     SW4     SW3     SW2     SW1
> >  2      0       0       0       Fcv     Fn3     Fn2     Fn1     Fn0
> >  3      Xa0_7   Xa0_6   Xa0_5   Xa0_4   Xa0_3   Xa0_2   Xa0_1   Xa0_0
> > @@ -114,17 +142,25 @@ Touchpad data byte
> >  25     Ya4_7   Ya4_6   Ya4_5   Ya4_4   Ya4_3   Ya4_2   Ya4_1   Ya4_0
> >  26     Ya4_15  Ya4_14  Ya4_13  Ya4_12  Ya4_11  Ya4_10  Ya4_9   Ya4_8
> >  27     LFB4    Zs4_6   Zs4_5   Zs4_4   Zs4_3   Zs4_2   Zs4_1   Zs4_0
> > +======= ======= ======= ======= ======= ======= ======= ======= =====
> >
> >
> > -SW1-SW6:       SW ON/OFF status
> > -Xan_15-0(16bit):X Absolute data of the "n"th finger
> > -Yan_15-0(16bit):Y Absolute data of the "n"th finger
> > -Zsn_6-0(7bit): Operation area of the "n"th finger
> > +SW1-SW6:
> > +       SW ON/OFF status
> > +Xan_15-0(16bit):
> > +       X Absolute data of the "n"th finger
> > +Yan_15-0(16bit):
> > +       Y Absolute data of the "n"th finger
> > +Zsn_6-0(7bit):
> > +       Operation area of the "n"th finger
> >
> >
> >  StickPointer data byte
> > -------------------
> > -       b7      b6      b5      b4      b3      b2      b1      b0
> > +----------------------
> > +
> > +======= ======= ======= ======= ======= ======= ======= ======= =====
> > +-      b7      b6      b5      b4      b3      b2      b1      b0
> > +======= ======= ======= ======= ======= ======= ======= ======= =====
> >  Byte1  1       1       1       0       1       SW3     SW2     SW1
> >  Byte2  X7      X6      X5      X4      X3      X2      X1      X0
> >  Byte3  X15     X14     X13     X12     X11     X10     X9      X8
> > @@ -132,8 +168,13 @@ Byte4      Y7      Y6      Y5      Y4      Y3      Y2      Y1      Y0
> >  Byte5  Y15     Y14     Y13     Y12     Y11     Y10     Y9      Y8
> >  Byte6  Z7      Z6      Z5      Z4      Z3      Z2      Z1      Z0
> >  Byte7  T&P     Z14     Z13     Z12     Z11     Z10     Z9      Z8
> > +======= ======= ======= ======= ======= ======= ======= ======= =====
> >
> > -SW1-SW3:       SW ON/OFF status
> > -Xn_15-0(16bit):X Absolute data
> > -Yn_15-0(16bit):Y Absolute data
> > -Zn_14-0(15bit):Z
> > +SW1-SW3:
> > +       SW ON/OFF status
> > +Xn_15-0(16bit):
> > +       X Absolute data
> > +Yn_15-0(16bit):
> > +       Y Absolute data
> > +Zn_14-0(15bit):
> > +       Z
> > diff --git a/Documentation/hid/hid-sensor.txt b/Documentation/hid/hid-sensor.rst
> > similarity index 61%
> > rename from Documentation/hid/hid-sensor.txt
> > rename to Documentation/hid/hid-sensor.rst
> > index b287752a31cd..758972e34971 100644
> > --- a/Documentation/hid/hid-sensor.txt
> > +++ b/Documentation/hid/hid-sensor.rst
> > @@ -1,6 +1,6 @@
> > -
> > +=====================
> >  HID Sensors Framework
> > -======================
> > +=====================
> >  HID sensor framework provides necessary interfaces to implement sensor drivers,
> >  which are connected to a sensor hub. The sensor hub is a HID device and it provides
> >  a report descriptor conforming to HID 1.12 sensor usage tables.
> > @@ -15,22 +15,22 @@ the drivers themselves."
> >  This specification describes many usage IDs, which describe the type of sensor
> >  and also the individual data fields. Each sensor can have variable number of
> >  data fields. The length and order is specified in the report descriptor. For
> > -example a part of report descriptor can look like:
> > +example a part of report descriptor can look like::
> >
> > -   INPUT(1)[INPUT]
> > - ..
> > -    Field(2)
> > -      Physical(0020.0073)
> > -      Usage(1)
> > -        0020.045f
> > -      Logical Minimum(-32767)
> > -      Logical Maximum(32767)
> > -      Report Size(8)
> > -      Report Count(1)
> > -      Report Offset(16)
> > -      Flags(Variable Absolute)
> > -..
> > -..
> > +     INPUT(1)[INPUT]
> > +   ..
> > +      Field(2)
> > +        Physical(0020.0073)
> > +        Usage(1)
> > +          0020.045f
> > +        Logical Minimum(-32767)
> > +        Logical Maximum(32767)
> > +        Report Size(8)
> > +        Report Count(1)
> > +        Report Offset(16)
> > +        Flags(Variable Absolute)
> > +  ..
> > +  ..
> >
> >  The report is indicating "sensor page (0x20)" contains an accelerometer-3D (0x73).
> >  This accelerometer-3D has some fields. Here for example field 2 is motion intensity
> > @@ -40,13 +40,14 @@ data will use this format.
> >
> >
> >  Implementation
> > -=================
> > +==============
> >
> >  This specification defines many different types of sensors with different sets of
> >  data fields. It is difficult to have a common input event to user space applications,
> >  for different sensors. For example an accelerometer can send X,Y and Z data, whereas
> >  an ambient light sensor can send illumination data.
> >  So the implementation has two parts:
> > +
> >  - Core hid driver
> >  - Individual sensor processing part (sensor drivers)
> >
> > @@ -55,8 +56,11 @@ Core driver
> >  The core driver registers (hid-sensor-hub) registers as a HID driver. It parses
> >  report descriptors and identifies all the sensors present. It adds an MFD device
> >  with name HID-SENSOR-xxxx (where xxxx is usage id from the specification).
> > -For example
> > +
> > +For example:
> > +
> >  HID-SENSOR-200073 is registered for an Accelerometer 3D driver.
> > +
> >  So if any driver with this name is inserted, then the probe routine for that
> >  function will be called. So an accelerometer processing driver can register
> >  with this name and will be probed if there is an accelerometer-3D detected.
> > @@ -66,7 +70,8 @@ drivers to register and get events for that usage id. Also it provides parsing
> >  functions, which get and set each input/feature/output report.
> >
> >  Individual sensor processing part (sensor drivers)
> > ------------
> > +--------------------------------------------------
> > +
> >  The processing driver will use an interface provided by the core driver to parse
> >  the report and get the indexes of the fields and also can get events. This driver
> >  can use IIO interface to use the standard ABI defined for a type of sensor.
> > @@ -75,31 +80,34 @@ can use IIO interface to use the standard ABI defined for a type of sensor.
> >  Core driver Interface
> >  =====================
> >
> > -Callback structure:
> > -Each processing driver can use this structure to set some callbacks.
> > +Callback structure::
> > +
> > +  Each processing driver can use this structure to set some callbacks.
> >         int (*suspend)(..): Callback when HID suspend is received
> >         int (*resume)(..): Callback when HID resume is received
> >         int (*capture_sample)(..): Capture a sample for one of its data fields
> >         int (*send_event)(..): One complete event is received which can have
> >                                 multiple data fields.
> >
> > -Registration functions:
> > -int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
> > +Registration functions::
> > +
> > +  int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
> >                         u32 usage_id,
> >                         struct hid_sensor_hub_callbacks *usage_callback):
> >
> >  Registers callbacks for an usage id. The callback functions are not allowed
> > -to sleep.
> > +to sleep::
> >
> >
> > -int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
> > +  int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
> >                         u32 usage_id):
> >
> >  Removes callbacks for an usage id.
> >
> >
> > -Parsing function:
> > -int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
> > +Parsing function::
> > +
> > +  int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
> >                         u8 type,
> >                         u32 usage_id, u32 attr_usage_id,
> >                         struct hid_sensor_hub_attribute_info *info);
> > @@ -110,26 +118,27 @@ so that fields can be set or get individually.
> >  These indexes avoid searching every time and getting field index to get or set.
> >
> >
> > -Set Feature report
> > -int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
> > +Set Feature report::
> > +
> > +  int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
> >                         u32 field_index, s32 value);
> >
> >  This interface is used to set a value for a field in feature report. For example
> >  if there is a field report_interval, which is parsed by a call to
> > -sensor_hub_input_get_attribute_info before, then it can directly set that individual
> > -field.
> > +sensor_hub_input_get_attribute_info before, then it can directly set that
> > +individual field::
> >
> >
> > -int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
> > +  int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
> >                         u32 field_index, s32 *value);
> >
> >  This interface is used to get a value for a field in input report. For example
> >  if there is a field report_interval, which is parsed by a call to
> > -sensor_hub_input_get_attribute_info before, then it can directly get that individual
> > -field value.
> > +sensor_hub_input_get_attribute_info before, then it can directly get that
> > +individual field value::
> >
> >
> > -int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
> > +  int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
> >                         u32 usage_id,
> >                         u32 attr_usage_id, u32 report_id);
> >
> > @@ -143,6 +152,8 @@ registered callback function to process the sample.
> >  ----------
> >
> >  HID Custom and generic Sensors
> > +------------------------------
> > +
> >
> >  HID Sensor specification defines two special sensor usage types. Since they
> >  don't represent a standard sensor, it is not possible to define using Linux IIO
> > @@ -158,66 +169,73 @@ keyboard attached/detached or lid open/close.
> >  To allow application to utilize these sensors, here they are exported uses sysfs
> >  attribute groups, attributes and misc device interface.
> >
> > -An example of this representation on sysfs:
> > -/sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R
> > -.
> > -????????? enable_sensor
> > -????????? feature-0-200316
> > -??????? ????????? feature-0-200316-maximum
> > -??????? ????????? feature-0-200316-minimum
> > -??????? ????????? feature-0-200316-name
> > -??????? ????????? feature-0-200316-size
> > -??????? ????????? feature-0-200316-unit-expo
> > -??????? ????????? feature-0-200316-units
> > -??????? ????????? feature-0-200316-value
> > -????????? feature-1-200201
> > -??????? ????????? feature-1-200201-maximum
> > -??????? ????????? feature-1-200201-minimum
> > -??????? ????????? feature-1-200201-name
> > -??????? ????????? feature-1-200201-size
> > -??????? ????????? feature-1-200201-unit-expo
> > -??????? ????????? feature-1-200201-units
> > -??????? ????????? feature-1-200201-value
> > -????????? input-0-200201
> > -??????? ????????? input-0-200201-maximum
> > -??????? ????????? input-0-200201-minimum
> > -??????? ????????? input-0-200201-name
> > -??????? ????????? input-0-200201-size
> > -??????? ????????? input-0-200201-unit-expo
> > -??????? ????????? input-0-200201-units
> > -??????? ????????? input-0-200201-value
> > -????????? input-1-200202
> > -??????? ????????? input-1-200202-maximum
> > -??????? ????????? input-1-200202-minimum
> > -??????? ????????? input-1-200202-name
> > -??????? ????????? input-1-200202-size
> > -??????? ????????? input-1-200202-unit-expo
> > -??????? ????????? input-1-200202-units
> > -??????? ????????? input-1-200202-value
> > +An example of this representation on sysfs::
> > +
> > +  /sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R
> > +  .
> > +  │   ├──  enable_sensor
> > +  │   │   ├── feature-0-200316
> > +  │   │   │   ├── feature-0-200316-maximum
> > +  │   │   │   ├── feature-0-200316-minimum
> > +  │   │   │   ├── feature-0-200316-name
> > +  │   │   │   ├── feature-0-200316-size
> > +  │   │   │   ├── feature-0-200316-unit-expo
> > +  │   │   │   ├── feature-0-200316-units
> > +  │   │   │   ├── feature-0-200316-value
> > +  │   │   ├── feature-1-200201
> > +  │   │   │   ├── feature-1-200201-maximum
> > +  │   │   │   ├── feature-1-200201-minimum
> > +  │   │   │   ├── feature-1-200201-name
> > +  │   │   │   ├── feature-1-200201-size
> > +  │   │   │   ├── feature-1-200201-unit-expo
> > +  │   │   │   ├── feature-1-200201-units
> > +  │   │   │   ├── feature-1-200201-value
> > +  │   │   ├── input-0-200201
> > +  │   │   │   ├── input-0-200201-maximum
> > +  │   │   │   ├── input-0-200201-minimum
> > +  │   │   │   ├── input-0-200201-name
> > +  │   │   │   ├── input-0-200201-size
> > +  │   │   │   ├── input-0-200201-unit-expo
> > +  │   │   │   ├── input-0-200201-units
> > +  │   │   │   ├── input-0-200201-value
> > +  │   │   ├── input-1-200202
> > +  │   │   │   ├── input-1-200202-maximum
> > +  │   │   │   ├── input-1-200202-minimum
> > +  │   │   │   ├── input-1-200202-name
> > +  │   │   │   ├── input-1-200202-size
> > +  │   │   │   ├── input-1-200202-unit-expo
> > +  │   │   │   ├── input-1-200202-units
> > +  │   │   │   ├── input-1-200202-value
> >
> >  Here there is a custom sensors with four fields, two feature and two inputs.
> >  Each field is represented by a set of attributes. All fields except the "value"
> >  are read only. The value field is a RW field.
> > -Example
> > -/sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
> > -feature-0-200316-maximum:6
> > -feature-0-200316-minimum:0
> > -feature-0-200316-name:property-reporting-state
> > -feature-0-200316-size:1
> > -feature-0-200316-unit-expo:0
> > -feature-0-200316-units:25
> > -feature-0-200316-value:1
> > +
> > +Example::
> > +
> > +  /sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
> > +  feature-0-200316-maximum:6
> > +  feature-0-200316-minimum:0
> > +  feature-0-200316-name:property-reporting-state
> > +  feature-0-200316-size:1
> > +  feature-0-200316-unit-expo:0
> > +  feature-0-200316-units:25
> > +  feature-0-200316-value:1
> >
> >  How to enable such sensor?
> > +^^^^^^^^^^^^^^^^^^^^^^^^^^
> > +
> >  By default sensor can be power gated. To enable sysfs attribute "enable" can be
> > -used.
> > -$ echo 1 > enable_sensor
> > +used::
> > +
> > +       $ echo 1 > enable_sensor
> >
> >  Once enabled and powered on, sensor can report value using HID reports.
> > -These reports are pushed using misc device interface in a FIFO order.
> > -/dev$ tree | grep HID-SENSOR-2000e1.6.auto
> > -??????? ????????? 10:53 -> ../HID-SENSOR-2000e1.6.auto
> > -????????? HID-SENSOR-2000e1.6.auto
> > +These reports are pushed using misc device interface in a FIFO order::
> > +
> > +       /dev$ tree | grep HID-SENSOR-2000e1.6.auto
> > +       │   │   │   ├── 10:53 -> ../HID-SENSOR-2000e1.6.auto
> > +       │   ├──  HID-SENSOR-2000e1.6.auto
> >
> >  Each reports can be of variable length preceded by a header. This header
> >  consist of a 32 bit usage id, 64 bit time stamp and 32 bit length field of raw
> > diff --git a/Documentation/hid/hid-transport.txt b/Documentation/hid/hid-transport.rst
> > similarity index 93%
> > rename from Documentation/hid/hid-transport.txt
> > rename to Documentation/hid/hid-transport.rst
> > index 3dcba9fd4a3a..6f3aaa86ce7b 100644
> > --- a/Documentation/hid/hid-transport.txt
> > +++ b/Documentation/hid/hid-transport.rst
> > @@ -1,5 +1,6 @@
> > -                          HID I/O Transport Drivers
> > -                         ===========================
> > +=========================
> > +HID I/O Transport Drivers
> > +=========================
> >
> >  The HID subsystem is independent of the underlying transport driver. Initially,
> >  only USB was supported, but other specifications adopted the HID design and
> > @@ -16,6 +17,8 @@ transport and device setup/management. HID core is responsible of
> >  report-parsing, report interpretation and the user-space API. Device specifics
> >  and quirks are handled by all layers depending on the quirk.
> >
> > +::
> > +
> >   +-----------+  +-----------+            +-----------+  +-----------+
> >   | Device #1 |  | Device #i |            | Device #j |  | Device #k |
> >   +-----------+  +-----------+            +-----------+  +-----------+
> > @@ -42,8 +45,9 @@ and quirks are handled by all layers depending on the quirk.
> >   +----------------+  +-----------+  +------------------+  +------------------+
> >
> >  Example Drivers:
> > -  I/O: USB, I2C, Bluetooth-l2cap
> > -  Transport: USB-HID, I2C-HID, BT-HIDP
> > +
> > +  - I/O: USB, I2C, Bluetooth-l2cap
> > +  - Transport: USB-HID, I2C-HID, BT-HIDP
> >
> >  Everything below "HID Core" is simplified in this graph as it is only of
> >  interest to HID device drivers. Transport drivers do not need to know the
> > @@ -183,7 +187,7 @@ Other ctrl-channel requests are supported by USB-HID but are not available
> >  -------------------
> >
> >  Transport drivers normally use the following procedure to register a new device
> > -with HID core:
> > +with HID core::
> >
> >         struct hid_device *hid;
> >         int ret;
> > @@ -215,7 +219,7 @@ Once hid_add_device() is entered, HID core might use the callbacks provided in
> >  "custom_ll_driver". Note that fields like "country" can be ignored by underlying
> >  transport-drivers if not supported.
> >
> > -To unregister a device, use:
> > +To unregister a device, use::
> >
> >         hid_destroy_device(hid);
> >
> > @@ -226,73 +230,110 @@ driver callbacks.
> >  -----------------------------
> >
> >  The available HID callbacks are:
> > - - int (*start) (struct hid_device *hdev)
> > +
> > +   ::
> > +
> > +      int (*start) (struct hid_device *hdev)
> > +
> >     Called from HID device drivers once they want to use the device. Transport
> >     drivers can choose to setup their device in this callback. However, normally
> >     devices are already set up before transport drivers register them to HID core
> >     so this is mostly only used by USB-HID.
> >
> > - - void (*stop) (struct hid_device *hdev)
> > +   ::
> > +
> > +      void (*stop) (struct hid_device *hdev)
> > +
> >     Called from HID device drivers once they are done with a device. Transport
> >     drivers can free any buffers and deinitialize the device. But note that  
> >     ->start() might be called again if another HID device driver is loaded on the  
> >     device.
> > +
> >     Transport drivers are free to ignore it and deinitialize devices after they
> >     destroyed them via hid_destroy_device().
> >
> > - - int (*open) (struct hid_device *hdev)
> > +   ::
> > +
> > +      int (*open) (struct hid_device *hdev)
> > +
> >     Called from HID device drivers once they are interested in data reports.
> >     Usually, while user-space didn't open any input API/etc., device drivers are
> >     not interested in device data and transport drivers can put devices asleep.
> >     However, once ->open() is called, transport drivers must be ready for I/O.  
> >     ->open() calls are nested for each client that opens the HID device.  
> >
> > - - void (*close) (struct hid_device *hdev)
> > +   ::
> > +
> > +      void (*close) (struct hid_device *hdev)
> > +
> >     Called from HID device drivers after ->open() was called but they are no
> >     longer interested in device reports. (Usually if user-space closed any input
> >     devices of the driver).
> > +
> >     Transport drivers can put devices asleep and terminate any I/O of all  
> >     ->open() calls have been followed by a ->close() call. However, ->start() may  
> >     be called again if the device driver is interested in input reports again.
> >
> > - - int (*parse) (struct hid_device *hdev)
> > +   ::
> > +
> > +      int (*parse) (struct hid_device *hdev)
> > +
> >     Called once during device setup after ->start() has been called. Transport
> >     drivers must read the HID report-descriptor from the device and tell HID core
> >     about it via hid_parse_report().
> >
> > - - int (*power) (struct hid_device *hdev, int level)
> > +   ::
> > +
> > +      int (*power) (struct hid_device *hdev, int level)
> > +
> >     Called by HID core to give PM hints to transport drivers. Usually this is
> >     analogical to the ->open() and ->close() hints and redundant.
> >
> > - - void (*request) (struct hid_device *hdev, struct hid_report *report,
> > -                    int reqtype)
> > +   ::
> > +
> > +      void (*request) (struct hid_device *hdev, struct hid_report *report,
> > +                      int reqtype)
> > +
> >     Send an HID request on the ctrl channel. "report" contains the report that
> >     should be sent and "reqtype" the request type. Request-type can be
> >     HID_REQ_SET_REPORT or HID_REQ_GET_REPORT.
> > +
> >     This callback is optional. If not provided, HID core will assemble a raw
> >     report following the HID specs and send it via the ->raw_request() callback.
> >     The transport driver is free to implement this asynchronously.
> >
> > - - int (*wait) (struct hid_device *hdev)
> > +   ::
> > +
> > +      int (*wait) (struct hid_device *hdev)
> > +
> >     Used by HID core before calling ->request() again. A transport driver can use
> >     it to wait for any pending requests to complete if only one request is
> >     allowed at a time.
> >
> > - - int (*raw_request) (struct hid_device *hdev, unsigned char reportnum,
> > -                       __u8 *buf, size_t count, unsigned char rtype,
> > -                       int reqtype)
> > +   ::
> > +
> > +      int (*raw_request) (struct hid_device *hdev, unsigned char reportnum,
> > +                          __u8 *buf, size_t count, unsigned char rtype,
> > +                          int reqtype)
> > +
> >     Same as ->request() but provides the report as raw buffer. This request shall
> >     be synchronous. A transport driver must not use ->wait() to complete such
> >     requests. This request is mandatory and hid core will reject the device if
> >     it is missing.
> >
> > - - int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len)
> > +   ::
> > +
> > +      int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len)
> > +
> >     Send raw output report via intr channel. Used by some HID device drivers
> >     which require high throughput for outgoing requests on the intr channel. This
> >     must not cause SET_REPORT calls! This must be implemented as asynchronous
> >     output report on the intr channel!
> >
> > - - int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype)
> > +   ::
> > +
> > +      int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype)
> > +
> >     Perform SET/GET_IDLE request. Only used by USB-HID, do not implement!
> >
> >  2.3) Data Path
> > @@ -314,4 +355,5 @@ transport driver and not passed to hid_input_report().
> >  Acknowledgements to SET_REPORT requests are not of interest to HID core.
> >
> >  ----------------------------------------------------
> > +
> >  Written 2013, David Herrmann <dh.herrmann@gmail.com>
> > diff --git a/Documentation/hid/hiddev.txt b/Documentation/hid/hiddev.rst
> > similarity index 77%
> > rename from Documentation/hid/hiddev.txt
> > rename to Documentation/hid/hiddev.rst
> > index 638448707aa2..209e6ba4e019 100644
> > --- a/Documentation/hid/hiddev.txt
> > +++ b/Documentation/hid/hiddev.rst
> > @@ -1,6 +1,9 @@
> > +================================================
> >  Care and feeding of your Human Interface Devices
> > +================================================
> >
> > -INTRODUCTION
> > +Introduction
> > +============
> >
> >  In addition to the normal input type HID devices, USB also uses the
> >  human interface device protocols for things that are not really human
> > @@ -16,38 +19,40 @@ normalised event interface - see Documentation/input/input.rst
> >  * the hiddev interface, which provides fairly raw HID events
> >
> >  The data flow for a HID event produced by a device is something like
> > -the following :
> > +the following::
> >
> >   usb.c ---> hid-core.c  ----> hid-input.c ----> [keyboard/mouse/joystick/event]
> >                           |
> >                           |  
> > -                          --> hiddev.c ----> POWER / MONITOR CONTROL  
> > +                          --> hiddev.c ----> POWER / MONITOR CONTROL
> >
> >  In addition, other subsystems (apart from USB) can potentially feed
> >  events into the input subsystem, but these have no effect on the hid
> >  device interface.
> >
> > -USING THE HID DEVICE INTERFACE
> > +Using the HID Device Interface
> > +==============================
> >
> >  The hiddev interface is a char interface using the normal USB major,
> >  with the minor numbers starting at 96 and finishing at 111. Therefore,
> > -you need the following commands:
> > -mknod /dev/usb/hiddev0 c 180 96
> > -mknod /dev/usb/hiddev1 c 180 97
> > -mknod /dev/usb/hiddev2 c 180 98
> > -mknod /dev/usb/hiddev3 c 180 99
> > -mknod /dev/usb/hiddev4 c 180 100
> > -mknod /dev/usb/hiddev5 c 180 101
> > -mknod /dev/usb/hiddev6 c 180 102
> > -mknod /dev/usb/hiddev7 c 180 103
> > -mknod /dev/usb/hiddev8 c 180 104
> > -mknod /dev/usb/hiddev9 c 180 105
> > -mknod /dev/usb/hiddev10 c 180 106
> > -mknod /dev/usb/hiddev11 c 180 107
> > -mknod /dev/usb/hiddev12 c 180 108
> > -mknod /dev/usb/hiddev13 c 180 109
> > -mknod /dev/usb/hiddev14 c 180 110
> > -mknod /dev/usb/hiddev15 c 180 111
> > +you need the following commands::
> > +
> > +       mknod /dev/usb/hiddev0 c 180 96
> > +       mknod /dev/usb/hiddev1 c 180 97
> > +       mknod /dev/usb/hiddev2 c 180 98
> > +       mknod /dev/usb/hiddev3 c 180 99
> > +       mknod /dev/usb/hiddev4 c 180 100
> > +       mknod /dev/usb/hiddev5 c 180 101
> > +       mknod /dev/usb/hiddev6 c 180 102
> > +       mknod /dev/usb/hiddev7 c 180 103
> > +       mknod /dev/usb/hiddev8 c 180 104
> > +       mknod /dev/usb/hiddev9 c 180 105
> > +       mknod /dev/usb/hiddev10 c 180 106
> > +       mknod /dev/usb/hiddev11 c 180 107
> > +       mknod /dev/usb/hiddev12 c 180 108
> > +       mknod /dev/usb/hiddev13 c 180 109
> > +       mknod /dev/usb/hiddev14 c 180 110
> > +       mknod /dev/usb/hiddev15 c 180 111
> >
> >  So you point your hiddev compliant user-space program at the correct
> >  interface for your device, and it all just works.
> > @@ -56,7 +61,9 @@ Assuming that you have a hiddev compliant user-space program, of
> >  course. If you need to write one, read on.
> >
> >
> > -THE HIDDEV API
> > +The HIDDEV API
> > +==============
> > +
> >  This description should be read in conjunction with the HID
> >  specification, freely available from http://www.usb.org, and
> >  conveniently linked of http://www.linux-usb.org.
> > @@ -69,12 +76,14 @@ each of which can have one or more "usages".  In the hid-core,
> >  each one of these usages has a single signed 32 bit value.
> >
> >  read():
> > +-------
> > +
> >  This is the event interface.  When the HID device's state changes,
> >  it performs an interrupt transfer containing a report which contains
> >  the changed value.  The hid-core.c module parses the report, and
> >  returns to hiddev.c the individual usages that have changed within
> >  the report.  In its basic mode, the hiddev will make these individual
> > -usage changes available to the reader using a struct hiddev_event:
> > +usage changes available to the reader using a struct hiddev_event::
> >
> >         struct hiddev_event {
> >             unsigned hid;
> > @@ -90,13 +99,19 @@ behavior of the read() function can be modified using the HIDIOCSFLAG
> >  ioctl() described below.
> >
> >
> > -ioctl():
> > -This is the control interface. There are a number of controls:
> > +ioctl():
> > +--------
> >
> > -HIDIOCGVERSION - int (read)
> > -Gets the version code out of the hiddev driver.
> > +This is the control interface. There are a number of controls:
> > +
> > +HIDIOCGVERSION
> > +  - int (read)
> > +
> > + Gets the version code out of the hiddev driver.
> > +
> > +HIDIOCAPPLICATION
> > +  - (none)
> >
> > -HIDIOCAPPLICATION - (none)
> >  This ioctl call returns the HID application usage associated with the
> >  hid device. The third argument to ioctl() specifies which application
> >  index to get. This is useful when the device has more than one
> > @@ -104,25 +119,33 @@ application collection. If the index is invalid (greater or equal to
> >  the number of application collections this device has) the ioctl
> >  returns -1. You can find out beforehand how many application
> >  collections the device has from the num_applications field from the
> > -hiddev_devinfo structure.
> > +hiddev_devinfo structure.
> > +
> > +HIDIOCGCOLLECTIONINFO
> > +  - struct hiddev_collection_info (read/write)
> >
> > -HIDIOCGCOLLECTIONINFO - struct hiddev_collection_info (read/write)
> >  This returns a superset of the information above, providing not only
> >  application collections, but all the collections the device has.  It
> >  also returns the level the collection lives in the hierarchy.
> > -The user passes in a hiddev_collection_info struct with the index
> > -field set to the index that should be returned.  The ioctl fills in
> > -the other fields.  If the index is larger than the last collection
> > +The user passes in a hiddev_collection_info struct with the index
> > +field set to the index that should be returned.  The ioctl fills in
> > +the other fields.  If the index is larger than the last collection
> >  index, the ioctl returns -1 and sets errno to -EINVAL.
> >
> > -HIDIOCGDEVINFO - struct hiddev_devinfo (read)
> > +HIDIOCGDEVINFO
> > +  - struct hiddev_devinfo (read)
> > +
> >  Gets a hiddev_devinfo structure which describes the device.
> >
> > -HIDIOCGSTRING - struct hiddev_string_descriptor (read/write)
> > +HIDIOCGSTRING
> > +  - struct hiddev_string_descriptor (read/write)
> > +
> >  Gets a string descriptor from the device. The caller must fill in the
> >  "index" field to indicate which descriptor should be returned.
> >
> > -HIDIOCINITREPORT - (none)
> > +HIDIOCINITREPORT
> > +  - (none)
> > +
> >  Instructs the kernel to retrieve all input and feature report values
> >  from the device. At this point, all the usage structures will contain
> >  current values for the device, and will maintain it as the device
> > @@ -130,21 +153,29 @@ changes.  Note that the use of this ioctl is unnecessary in general,
> >  since later kernels automatically initialize the reports from the
> >  device at attach time.
> >
> > -HIDIOCGNAME - string (variable length)
> > +HIDIOCGNAME
> > +  - string (variable length)
> > +
> >  Gets the device name
> >
> > -HIDIOCGREPORT - struct hiddev_report_info (write)
> > +HIDIOCGREPORT
> > +  - struct hiddev_report_info (write)
> > +
> >  Instructs the kernel to get a feature or input report from the device,
> >  in order to selectively update the usage structures (in contrast to
> >  INITREPORT).
> >
> > -HIDIOCSREPORT - struct hiddev_report_info (write)
> > +HIDIOCSREPORT
> > +  - struct hiddev_report_info (write)
> > +
> >  Instructs the kernel to send a report to the device. This report can
> >  be filled in by the user through HIDIOCSUSAGE calls (below) to fill in
> >  individual usage values in the report before sending the report in full
> > -to the device.
> > +to the device.
> > +
> > +HIDIOCGREPORTINFO
> > +  - struct hiddev_report_info (read/write)
> >
> > -HIDIOCGREPORTINFO - struct hiddev_report_info (read/write)
> >  Fills in a hiddev_report_info structure for the user. The report is
> >  looked up by type (input, output or feature) and id, so these fields
> >  must be filled in by the user. The ID can be absolute -- the actual
> > @@ -154,52 +185,67 @@ report_id) for the next report after report_id. Without a-priori
> >  information about report ids, the right way to use this ioctl is to
> >  use the relative IDs above to enumerate the valid IDs. The ioctl
> >  returns non-zero when there is no more next ID. The real report ID is
> > -filled into the returned hiddev_report_info structure.
> > +filled into the returned hiddev_report_info structure.
> > +
> > +HIDIOCGFIELDINFO
> > +  - struct hiddev_field_info (read/write)
> >
> > -HIDIOCGFIELDINFO - struct hiddev_field_info (read/write)
> >  Returns the field information associated with a report in a
> >  hiddev_field_info structure. The user must fill in report_id and
> >  report_type in this structure, as above. The field_index should also
> >  be filled in, which should be a number from 0 and maxfield-1, as
> > -returned from a previous HIDIOCGREPORTINFO call.
> > +returned from a previous HIDIOCGREPORTINFO call.
> > +
> > +HIDIOCGUCODE
> > +  - struct hiddev_usage_ref (read/write)
> >
> > -HIDIOCGUCODE - struct hiddev_usage_ref (read/write)
> >  Returns the usage_code in a hiddev_usage_ref structure, given that
> >  given its report type, report id, field index, and index within the
> >  field have already been filled into the structure.
> >
> > -HIDIOCGUSAGE - struct hiddev_usage_ref (read/write)
> > +HIDIOCGUSAGE
> > +  - struct hiddev_usage_ref (read/write)
> > +
> >  Returns the value of a usage in a hiddev_usage_ref structure. The
> >  usage to be retrieved can be specified as above, or the user can
> >  choose to fill in the report_type field and specify the report_id as
> >  HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be
> >  filled in with the report and field information associated with this
> > -usage if it is found.
> > +usage if it is found.
> > +
> > +HIDIOCSUSAGE
> > +  - struct hiddev_usage_ref (write)
> >
> > -HIDIOCSUSAGE - struct hiddev_usage_ref (write)
> >  Sets the value of a usage in an output report.  The user fills in
> >  the hiddev_usage_ref structure as above, but additionally fills in
> >  the value field.
> >
> > -HIDIOGCOLLECTIONINDEX - struct hiddev_usage_ref (write)
> > +HIDIOGCOLLECTIONINDEX
> > +  - struct hiddev_usage_ref (write)
> > +
> >  Returns the collection index associated with this usage.  This
> >  indicates where in the collection hierarchy this usage sits.
> >
> > -HIDIOCGFLAG - int (read)
> > -HIDIOCSFLAG - int (write)
> > +HIDIOCGFLAG
> > +  - int (read)
> > +HIDIOCSFLAG
> > +  - int (write)
> > +
> >  These operations respectively inspect and replace the mode flags
> >  that influence the read() call above.  The flags are as follows:
> >
> > -    HIDDEV_FLAG_UREF - read() calls will now return
> > +    HIDDEV_FLAG_UREF
> > +      - read() calls will now return
> >          struct hiddev_usage_ref instead of struct hiddev_event.
> >          This is a larger structure, but in situations where the
> >          device has more than one usage in its reports with the
> >          same usage code, this mode serves to resolve such
> >          ambiguity.
> >
> > -    HIDDEV_FLAG_REPORT - This flag can only be used in conjunction
> > +    HIDDEV_FLAG_REPORT
> > +      - This flag can only be used in conjunction
> >          with HIDDEV_FLAG_UREF.  With this flag set, when the device
> >          sends a report, a struct hiddev_usage_ref will be returned
> > -        to read() filled in with the report_type and report_id, but
> > +        to read() filled in with the report_type and report_id, but
> >          with field_index set to FIELD_INDEX_NONE.  This serves as
> >          additional notification when the device has sent a report.
> > diff --git a/Documentation/hid/hidraw.txt b/Documentation/hid/hidraw.rst
> > similarity index 89%
> > rename from Documentation/hid/hidraw.txt
> > rename to Documentation/hid/hidraw.rst
> > index c8436e354f44..4a4a0ba1f362 100644
> > --- a/Documentation/hid/hidraw.txt
> > +++ b/Documentation/hid/hidraw.rst
> > @@ -1,5 +1,6 @@
> > -      HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices
> > -     ==================================================================
> > +================================================================
> > +HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices
> > +================================================================
> >
> >  The hidraw driver provides a raw interface to USB and Bluetooth Human
> >  Interface Devices (HIDs).  It differs from hiddev in that reports sent and
> > @@ -31,6 +32,7 @@ directly under /dev (eg: /dev/hidraw0).  As this location is distribution-
> >  and udev rule-dependent, applications should use libudev to locate hidraw
> >  devices attached to the system.  There is a tutorial on libudev with a
> >  working example at:
> > +
> >         http://www.signal11.us/oss/udev/
> >
> >  The HIDRAW API
> > @@ -51,7 +53,7 @@ byte.  For devices which do not use numbered reports, the report data
> >  will begin at the first byte.
> >
> >  write()
> > ---------
> > +-------
> >  The write() function will write a report to the device. For USB devices, if
> >  the device has an INTERRUPT OUT endpoint, the report will be sent on that
> >  endpoint. If it does not, the report will be sent over the control endpoint,
> > @@ -62,38 +64,52 @@ number.  If the device does not use numbered reports, the first byte should
> >  be set to 0. The report data itself should begin at the second byte.
> >
> >  ioctl()
> > ---------
> > +-------
> >  Hidraw supports the following ioctls:
> >
> > -HIDIOCGRDESCSIZE: Get Report Descriptor Size
> > +HIDIOCGRDESCSIZE:
> > +       Get Report Descriptor Size
> > +
> >  This ioctl will get the size of the device's report descriptor.
> >
> > -HIDIOCGRDESC: Get Report Descriptor
> > +HIDIOCGRDESC:
> > +       Get Report Descriptor
> > +
> >  This ioctl returns the device's report descriptor using a
> >  hidraw_report_descriptor struct.  Make sure to set the size field of the
> >  hidraw_report_descriptor struct to the size returned from HIDIOCGRDESCSIZE.
> >
> > -HIDIOCGRAWINFO: Get Raw Info
> > +HIDIOCGRAWINFO:
> > +       Get Raw Info
> > +
> >  This ioctl will return a hidraw_devinfo struct containing the bus type, the
> >  vendor ID (VID), and product ID (PID) of the device. The bus type can be one
> > -of:
> > -       BUS_USB
> > -       BUS_HIL
> > -       BUS_BLUETOOTH
> > -       BUS_VIRTUAL
> > +of::
> > +
> > +       - BUS_USB
> > +       - BUS_HIL
> > +       - BUS_BLUETOOTH
> > +       - BUS_VIRTUAL
> > +
> >  which are defined in uapi/linux/input.h.
> >
> > -HIDIOCGRAWNAME(len): Get Raw Name
> > +HIDIOCGRAWNAME(len):
> > +       Get Raw Name
> > +
> >  This ioctl returns a string containing the vendor and product strings of
> >  the device.  The returned string is Unicode, UTF-8 encoded.
> >
> > -HIDIOCGRAWPHYS(len): Get Physical Address
> > +HIDIOCGRAWPHYS(len):
> > +       Get Physical Address
> > +
> >  This ioctl returns a string representing the physical address of the device.
> >  For USB devices, the string contains the physical path to the device (the
> >  USB controller, hubs, ports, etc).  For Bluetooth devices, the string
> >  contains the hardware (MAC) address of the device.
> >
> > -HIDIOCSFEATURE(len): Send a Feature Report
> > +HIDIOCSFEATURE(len):
> > +       Send a Feature Report
> > +
> >  This ioctl will send a feature report to the device.  Per the HID
> >  specification, feature reports are always sent using the control endpoint.
> >  Set the first byte of the supplied buffer to the report number.  For devices
> > @@ -101,7 +117,9 @@ which do not use numbered reports, set the first byte to 0. The report data
> >  begins in the second byte. Make sure to set len accordingly, to one more
> >  than the length of the report (to account for the report number).
> >
> > -HIDIOCGFEATURE(len): Get a Feature Report
> > +HIDIOCGFEATURE(len):
> > +       Get a Feature Report
> > +
> >  This ioctl will request a feature report from the device using the control
> >  endpoint.  The first byte of the supplied buffer should be set to the report
> >  number of the requested report.  For devices which do not use numbered
> > @@ -109,11 +127,12 @@ reports, set the first byte to 0.  The report will be returned starting at
> >  the first byte of the buffer (ie: the report number is not returned).
> >
> >  Example
> > ----------
> > +-------
> >  In samples/, find hid-example.c, which shows examples of read(), write(),
> >  and all the ioctls for hidraw.  The code may be used by anyone for any
> >  purpose, and can serve as a starting point for developing applications using
> >  hidraw.
> >
> >  Document by:
> > +
> >         Alan Ott <alan@signal11.us>, Signal 11 Software
> > diff --git a/Documentation/hid/index.rst b/Documentation/hid/index.rst
> > new file mode 100644
> > index 000000000000..af4324902622
> > --- /dev/null
> > +++ b/Documentation/hid/index.rst
> > @@ -0,0 +1,18 @@
> > +:orphan:
> > +
> > +=============================
> > +Human Interface Devices (HID)
> > +=============================
> > +
> > +.. toctree::
> > +   :maxdepth: 1
> > +
> > +   hiddev
> > +   hidraw
> > +   hid-sensor
> > +   hid-transport
> > +
> > +   uhid
> > +
> > +   hid-alps
> > +   intel-ish-hid
> > diff --git a/Documentation/hid/intel-ish-hid.rst b/Documentation/hid/intel-ish-hid.rst
> > new file mode 100644
> > index 000000000000..cccbf4be17d7
> > --- /dev/null
> > +++ b/Documentation/hid/intel-ish-hid.rst
> > @@ -0,0 +1,485 @@
> > +=================================
> > +Intel Integrated Sensor Hub (ISH)
> > +=================================
> > +
> > +A sensor hub enables the ability to offload sensor polling and algorithm
> > +processing to a dedicated low power co-processor. This allows the core
> > +processor to go into low power modes more often, resulting in the increased
> > +battery life.
> > +
> > +There are many vendors providing external sensor hubs confirming to HID
> > +Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops
> > +and embedded products. Linux had this support since Linux 3.9.
> > +
> > +Intel® introduced integrated sensor hubs as a part of the SoC starting from
> > +Cherry Trail and now supported on multiple generations of CPU packages. There
> > +are many commercial devices already shipped with Integrated Sensor Hubs (ISH).
> > +These ISH also comply to HID sensor specification, but the  difference is the
> > +transport protocol used for communication. The current external sensor hubs
> > +mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB.
> > +
> > +1. Overview
> > +===========
> > +
> > +Using a analogy with a usbhid implementation, the ISH follows a similar model
> > +for a very high speed communication::
> > +
> > +       -----------------               ----------------------
> > +       |    USB HID    |       -->     |    ISH HID         |
> > +       -----------------               ----------------------
> > +       -----------------               ----------------------
> > +       |  USB protocol |       -->     |    ISH Transport   |
> > +       -----------------               ----------------------
> > +       -----------------               ----------------------
> > +       |  EHCI/XHCI    |       -->     |    ISH IPC         |
> > +       -----------------               ----------------------
> > +             PCI                                PCI
> > +       -----------------               ----------------------
> > +        |Host controller|      -->     |    ISH processor   |
> > +       -----------------               ----------------------
> > +            USB Link
> > +       -----------------               ----------------------
> > +       | USB End points|       -->     |    ISH Clients     |
> > +       -----------------               ----------------------
> > +
> > +Like USB protocol provides a method for device enumeration, link management
> > +and user data encapsulation, the ISH also provides similar services. But it is
> > +very light weight tailored to manage and communicate with ISH client
> > +applications implemented in the firmware.
> > +
> > +The ISH allows multiple sensor management applications executing in the
> > +firmware. Like USB endpoints the messaging can be to/from a client. As part of
> > +enumeration process, these clients are identified. These clients can be simple
> > +HID sensor applications, sensor calibration application or senor firmware
> > +update application.
> > +
> > +The implementation model is similar, like USB bus, ISH transport is also
> > +implemented as a bus. Each client application executing in the ISH processor
> > +is registered as a device on this bus. The driver, which binds each device
> > +(ISH HID driver) identifies the device type and registers with the hid core.
> > +
> > +2. ISH Implementation: Block Diagram
> > +====================================
> > +
> > +::
> > +
> > +        ---------------------------
> > +       |  User Space Applications  |
> > +        ---------------------------
> > +
> > +  ----------------IIO ABI----------------
> > +        --------------------------
> > +       |  IIO Sensor Drivers     |
> > +        --------------------------
> > +        --------------------------
> > +       |        IIO core         |
> > +        --------------------------
> > +        --------------------------
> > +       |   HID Sensor Hub MFD    |
> > +        --------------------------
> > +        --------------------------
> > +       |       HID Core          |
> > +        --------------------------
> > +        --------------------------
> > +       |   HID over ISH Client   |
> > +        --------------------------
> > +        --------------------------
> > +       |   ISH Transport (ISHTP) |
> > +        --------------------------
> > +        --------------------------
> > +       |      IPC Drivers        |
> > +        --------------------------
> > +  OS
> > +  ---------------- PCI -----------------
> > +  Hardware + Firmware
> > +        ----------------------------
> > +       | ISH Hardware/Firmware(FW) |
> > +        ----------------------------
> > +
> > +3. High level processing in above blocks
> > +========================================
> > +
> > +3.1 Hardware Interface
> > +----------------------
> > +
> > +The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI
> > +product and vendor IDs are changed from different generations of processors. So
> > +the source code which enumerate drivers needs to update from generation to
> > +generation.
> > +
> > +3.2 Inter Processor Communication (IPC) driver
> > +----------------------------------------------
> > +
> > +Location: drivers/hid/intel-ish-hid/ipc
> > +
> > +The IPC message used memory mapped I/O. The registers are defined in
> > +hw-ish-regs.h.
> > +
> > +3.2.1 IPC/FW message types
> > +^^^^^^^^^^^^^^^^^^^^^^^^^^
> > +
> > +There are two types of messages, one for management of link and other messages
> > +are to and from transport layers.
> > +
> > +TX and RX of Transport messages
> > +...............................
> > +
> > +A set of memory mapped register offers support of multi byte messages TX and
> > +RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains
> > +internal queues to sequence messages and send them in order to the FW.
> > +Optionally the caller can register handler to get notification of completion.
> > +A door bell mechanism is used in messaging to trigger processing in host and
> > +client firmware side. When ISH interrupt handler is called, the ISH2HOST
> > +doorbell register is used by host drivers to determine that the interrupt
> > +is for ISH.
> > +
> > +Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell
> > +register has the following format:
> > +Bits 0..6: fragment length (7 bits are used)
> > +Bits 10..13: encapsulated protocol
> > +Bits 16..19: management command (for IPC management protocol)
> > +Bit 31: doorbell trigger (signal H/W interrupt to the other side)
> > +Other bits are reserved, should be 0.
> > +
> > +3.2.2 Transport layer interface
> > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > +
> > +To abstract HW level IPC communication, a set of callbacks are registered.
> > +The transport layer uses them to send and receive messages.
> > +Refer to  struct ishtp_hw_ops for callbacks.
> > +
> > +3.3 ISH Transport layer
> > +-----------------------
> > +
> > +Location: drivers/hid/intel-ish-hid/ishtp/
> > +
> > +3.3.1 A Generic Transport Layer
> > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > +
> > +The transport layer is a bi-directional protocol, which defines:
> > +- Set of commands to start, stop, connect, disconnect and flow control
> > +(ishtp/hbm.h) for details
> > +- A flow control mechanism to avoid buffer overflows
> > +
> > +This protocol resembles bus messages described in the following document:
> > +http://www.intel.com/content/dam/www/public/us/en/documents/technical-\
> > +specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer"
> > +
> > +3.3.2 Connection and Flow Control Mechanism
> > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > +
> > +Each FW client and a protocol is identified by an UUID. In order to communicate
> > +to a FW client, a connection must be established using connect request and
> > +response bus messages. If successful, a pair (host_client_id and fw_client_id)
> > +will identify the connection.
> > +
> > +Once connection is established, peers send each other flow control bus messages
> > +independently. Every peer may send a message only if it has received a
> > +flow-control credit before. Once it sent a message, it may not send another one
> > +before receiving the next flow control credit.
> > +Either side can send disconnect request bus message to end communication. Also
> > +the link will be dropped if major FW reset occurs.
> > +
> > +3.3.3 Peer to Peer data transfer
> > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > +
> > +Peer to Peer data transfer can happen with or without using DMA. Depending on
> > +the sensor bandwidth requirement DMA can be enabled by using module parameter
> > +ishtp_use_dma under intel_ishtp.
> > +
> > +Each side (host and FW) manages its DMA transfer memory independently. When an
> > +ISHTP client from either host or FW side wants to send something, it decides
> > +whether to send over IPC or over DMA; for each transfer the decision is
> > +independent. The sending side sends DMA_XFER message when the message is in
> > +the respective host buffer (TX when host client sends, RX when FW client
> > +sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating
> > +the sender that the memory region for that message may be reused.
> > +
> > +DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message
> > +(that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK.
> > +Additionally to DMA address communication, this sequence checks capabilities:
> > +if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't
> > +send DMA; if FW doesn't support DMA then it won't respond with
> > +DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers.
> > +Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER,
> > +it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means
> > +that it already did DMA and the message resides at host. Thus, DMA_XFER
> > +and DMA_XFER_ACK act as ownership indicators.
> > +
> > +At initial state all outgoing memory belongs to the sender (TX to host, RX to
> > +FW), DMA_XFER transfers ownership on the region that contains ISHTP message to
> > +the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender
> > +needs not wait for previous DMA_XFER to be ack'ed, and may send another message
> > +as long as remaining continuous memory in its ownership is enough.
> > +In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once
> > +(up to IPC MTU), thus allowing for interrupt throttling.
> > +Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC
> > +fragments and via IPC otherwise.
> > +
> > +3.3.4 Ring Buffers
> > +^^^^^^^^^^^^^^^^^^
> > +
> > +When a client initiate a connection, a ring or RX and TX buffers are allocated.
> > +The size of ring can be specified by the client. HID client set 16 and 32 for
> > +TX and RX buffers respectively. On send request from client, the data to be
> > +sent is copied to one of the send ring buffer and scheduled to be sent using
> > +bus message protocol. These buffers are required because the FW may have not
> > +have processed the last message and may not have enough flow control credits
> > +to send. Same thing holds true on receive side and flow control is required.
> > +
> > +3.3.5 Host Enumeration
> > +^^^^^^^^^^^^^^^^^^^^^^
> > +
> > +The host enumeration bus command allow discovery of clients present in the FW.
> > +There can be multiple sensor clients and clients for calibration function.
> > +
> > +To ease in implantation and allow independent driver handle each client
> > +this transport layer takes advantage of Linux Bus driver model. Each
> > +client is registered as device on the the transport bus (ishtp bus).
> > +
> > +Enumeration sequence of messages:
> > +
> > +- Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up.
> > +- FW responds with HOST_START_RES_CMD
> > +- Host sends HOST_ENUM_REQ_CMD (enumerate FW clients)
> > +- FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW
> > +  client IDs
> > +- For each FW ID found in that bitmap host sends
> > +  HOST_CLIENT_PROPERTIES_REQ_CMD
> > +- FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID,
> > +  max ISHTP message size, etc.
> > +- Once host received properties for that last discovered client, it considers
> > +  ISHTP device fully functional (and allocates DMA buffers)
> > +
> > +3.4 HID over ISH Client
> > +-----------------------
> > +
> > +Location: drivers/hid/intel-ish-hid
> > +
> > +The ISHTP client driver is responsible for:
> > +
> > +- enumerate HID devices under FW ISH client
> > +- Get Report descriptor
> > +- Register with HID core as a LL driver
> > +- Process Get/Set feature request
> > +- Get input reports
> > +
> > +3.5 HID Sensor Hub MFD and IIO sensor drivers
> > +---------------------------------------------
> > +
> > +The functionality in these drivers is the same as an external sensor hub.
> > +Refer to
> > +Documentation/hid/hid-sensor.rst for HID sensor
> > +Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space
> > +
> > +3.6 End to End HID transport Sequence Diagram
> > +---------------------------------------------
> > +
> > +::
> > +
> > +  HID-ISH-CLN                    ISHTP                    IPC                             HW
> > +          |                        |                       |                               |
> > +          |                        |                       |-----WAKE UP------------------>|
> > +          |                        |                       |                               |
> > +          |                        |                       |-----HOST READY--------------->|
> > +          |                        |                       |                               |
> > +          |                        |                       |<----MNG_RESET_NOTIFY_ACK----- |
> > +          |                        |                       |                               |
> > +          |                        |<----ISHTP_START------ |                               |
> > +          |                        |                       |                               |
> > +          |                        |<-----------------HOST_START_RES_CMD-------------------|
> > +          |                        |                       |                               |
> > +          |                        |------------------QUERY_SUBSCRIBER-------------------->|
> > +          |                        |                       |                               |
> > +          |                        |------------------HOST_ENUM_REQ_CMD------------------->|
> > +          |                        |                       |                               |
> > +          |                        |<-----------------HOST_ENUM_RES_CMD--------------------|
> > +          |                        |                       |                               |
> > +          |                        |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
> > +          |                        |                       |                               |
> > +          |                        |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
> > +          |       Create new device on in ishtp bus        |                               |
> > +          |                        |                       |                               |
> > +          |                        |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
> > +          |                        |                       |                               |
> > +          |                        |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
> > +          |       Create new device on in ishtp bus        |                               |
> > +          |                        |                       |                               |
> > +          |                        |--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--|
> > +          |                        |                       |                               |
> > +       probed()
> > +          |----ishtp_cl_connect--->|----------------- CLIENT_CONNECT_REQ_CMD-------------->|
> > +          |                        |                       |                               |
> > +          |                        |<----------------CLIENT_CONNECT_RES_CMD----------------|
> > +          |                        |                       |                               |
> > +          |register event callback |                       |                               |
> > +          |                        |                       |                               |
> > +          |ishtp_cl_send(
> > +          HOSTIF_DM_ENUM_DEVICES)  |----------fill ishtp_msg_hdr struct write to HW-----  >|
> > +          |                        |                       |                               |
> > +          |                        |                       |<-----IRQ(IPC_PROTOCOL_ISHTP---|
> > +          |                        |                       |                               |
> > +          |<--ENUM_DEVICE RSP------|                       |                               |
> > +          |                        |                       |                               |
> > +  for each enumerated device
> > +          |ishtp_cl_send(
> > +          HOSTIF_GET_HID_DESCRIPTOR|----------fill ishtp_msg_hdr struct write to HW-----  >|
> > +          |                        |                       |                               |
> > +          ...Response
> > +          |                        |                       |                               |
> > +  for each enumerated device
> > +          |ishtp_cl_send(
> > +       HOSTIF_GET_REPORT_DESCRIPTOR|--------------fill ishtp_msg_hdr struct write to HW-- >|
> > +          |                        |                       |                               |
> > +          |                        |                       |                               |
> > +   hid_allocate_device
> > +          |                        |                       |                               |
> > +   hid_add_device                  |                       |                               |
> > +          |                        |                       |                               |
> > +
> > +
> > +3.7 ISH Debugging
> > +-----------------
> > +
> > +To debug ISH, event tracing mechanism is used. To enable debug logs
> > +echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable
> > +cat sys/kernel/debug/tracing/trace
> > +
> > +3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260
> > +-----------------------------------------------------
> > +
> > +::
> > +
> > +  root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/
> > +  /sys/bus/iio/devices/
> > +  ├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0
> > +  │   ├── buffer
> > +  │   │   ├── enable
> > +  │   │   ├── length
> > +  │   │   └── watermark
> > +  ...
> > +  │   ├── in_accel_hysteresis
> > +  │   ├── in_accel_offset
> > +  │   ├── in_accel_sampling_frequency
> > +  │   ├── in_accel_scale
> > +  │   ├── in_accel_x_raw
> > +  │   ├── in_accel_y_raw
> > +  │   ├── in_accel_z_raw
> > +  │   ├── name
> > +  │   ├── scan_elements
> > +  │   │   ├── in_accel_x_en
> > +  │   │   ├── in_accel_x_index
> > +  │   │   ├── in_accel_x_type
> > +  │   │   ├── in_accel_y_en
> > +  │   │   ├── in_accel_y_index
> > +  │   │   ├── in_accel_y_type
> > +  │   │   ├── in_accel_z_en
> > +  │   │   ├── in_accel_z_index
> > +  │   │   └── in_accel_z_type
> > +  ...
> > +  │   │   ├── devices
> > +  │   │   │   │   ├── buffer
> > +  │   │   │   │   │   ├── enable
> > +  │   │   │   │   │   ├── length
> > +  │   │   │   │   │   └── watermark
> > +  │   │   │   │   ├── dev
> > +  │   │   │   │   ├── in_intensity_both_raw
> > +  │   │   │   │   ├── in_intensity_hysteresis
> > +  │   │   │   │   ├── in_intensity_offset
> > +  │   │   │   │   ├── in_intensity_sampling_frequency
> > +  │   │   │   │   ├── in_intensity_scale
> > +  │   │   │   │   ├── name
> > +  │   │   │   │   ├── scan_elements
> > +  │   │   │   │   │   ├── in_intensity_both_en
> > +  │   │   │   │   │   ├── in_intensity_both_index
> > +  │   │   │   │   │   └── in_intensity_both_type
> > +  │   │   │   │   ├── trigger
> > +  │   │   │   │   │   └── current_trigger
> > +  ...
> > +  │   │   │   │   ├── buffer
> > +  │   │   │   │   │   ├── enable
> > +  │   │   │   │   │   ├── length
> > +  │   │   │   │   │   └── watermark
> > +  │   │   │   │   ├── dev
> > +  │   │   │   │   ├── in_magn_hysteresis
> > +  │   │   │   │   ├── in_magn_offset
> > +  │   │   │   │   ├── in_magn_sampling_frequency
> > +  │   │   │   │   ├── in_magn_scale
> > +  │   │   │   │   ├── in_magn_x_raw
> > +  │   │   │   │   ├── in_magn_y_raw
> > +  │   │   │   │   ├── in_magn_z_raw
> > +  │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_raw
> > +  │   │   │   │   ├── in_rot_hysteresis
> > +  │   │   │   │   ├── in_rot_offset
> > +  │   │   │   │   ├── in_rot_sampling_frequency
> > +  │   │   │   │   ├── in_rot_scale
> > +  │   │   │   │   ├── name
> > +  ...
> > +  │   │   │   │   ├── scan_elements
> > +  │   │   │   │   │   ├── in_magn_x_en
> > +  │   │   │   │   │   ├── in_magn_x_index
> > +  │   │   │   │   │   ├── in_magn_x_type
> > +  │   │   │   │   │   ├── in_magn_y_en
> > +  │   │   │   │   │   ├── in_magn_y_index
> > +  │   │   │   │   │   ├── in_magn_y_type
> > +  │   │   │   │   │   ├── in_magn_z_en
> > +  │   │   │   │   │   ├── in_magn_z_index
> > +  │   │   │   │   │   ├── in_magn_z_type
> > +  │   │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_en
> > +  │   │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_index
> > +  │   │   │   │   │   └── in_rot_from_north_magnetic_tilt_comp_type
> > +  │   │   │   │   ├── trigger
> > +  │   │   │   │   │   └── current_trigger
> > +  ...
> > +  │   │   │   │   ├── buffer
> > +  │   │   │   │   │   ├── enable
> > +  │   │   │   │   │   ├── length
> > +  │   │   │   │   │   └── watermark
> > +  │   │   │   │   ├── dev
> > +  │   │   │   │   ├── in_anglvel_hysteresis
> > +  │   │   │   │   ├── in_anglvel_offset
> > +  │   │   │   │   ├── in_anglvel_sampling_frequency
> > +  │   │   │   │   ├── in_anglvel_scale
> > +  │   │   │   │   ├── in_anglvel_x_raw
> > +  │   │   │   │   ├── in_anglvel_y_raw
> > +  │   │   │   │   ├── in_anglvel_z_raw
> > +  │   │   │   │   ├── name
> > +  │   │   │   │   ├── scan_elements
> > +  │   │   │   │   │   ├── in_anglvel_x_en
> > +  │   │   │   │   │   ├── in_anglvel_x_index
> > +  │   │   │   │   │   ├── in_anglvel_x_type
> > +  │   │   │   │   │   ├── in_anglvel_y_en
> > +  │   │   │   │   │   ├── in_anglvel_y_index
> > +  │   │   │   │   │   ├── in_anglvel_y_type
> > +  │   │   │   │   │   ├── in_anglvel_z_en
> > +  │   │   │   │   │   ├── in_anglvel_z_index
> > +  │   │   │   │   │   └── in_anglvel_z_type
> > +  │   │   │   │   ├── trigger
> > +  │   │   │   │   │   └── current_trigger
> > +  ...
> > +  │   │   │   │   ├── buffer
> > +  │   │   │   │   │   ├── enable
> > +  │   │   │   │   │   ├── length
> > +  │   │   │   │   │   └── watermark
> > +  │   │   │   │   ├── dev
> > +  │   │   │   │   ├── in_anglvel_hysteresis
> > +  │   │   │   │   ├── in_anglvel_offset
> > +  │   │   │   │   ├── in_anglvel_sampling_frequency
> > +  │   │   │   │   ├── in_anglvel_scale
> > +  │   │   │   │   ├── in_anglvel_x_raw
> > +  │   │   │   │   ├── in_anglvel_y_raw
> > +  │   │   │   │   ├── in_anglvel_z_raw
> > +  │   │   │   │   ├── name
> > +  │   │   │   │   ├── scan_elements
> > +  │   │   │   │   │   ├── in_anglvel_x_en
> > +  │   │   │   │   │   ├── in_anglvel_x_index
> > +  │   │   │   │   │   ├── in_anglvel_x_type
> > +  │   │   │   │   │   ├── in_anglvel_y_en
> > +  │   │   │   │   │   ├── in_anglvel_y_index
> > +  │   │   │   │   │   ├── in_anglvel_y_type
> > +  │   │   │   │   │   ├── in_anglvel_z_en
> > +  │   │   │   │   │   ├── in_anglvel_z_index
> > +  │   │   │   │   │   └── in_anglvel_z_type
> > +  │   │   │   │   ├── trigger
> > +  │   │   │   │   │   └── current_trigger
> > +  ...
> > diff --git a/Documentation/hid/intel-ish-hid.txt b/Documentation/hid/intel-ish-hid.txt
> > deleted file mode 100644
> > index d48b21c71ddd..000000000000
> > --- a/Documentation/hid/intel-ish-hid.txt
> > +++ /dev/null
> > @@ -1,454 +0,0 @@
> > -Intel Integrated Sensor Hub (ISH)
> > -===============================
> > -
> > -A sensor hub enables the ability to offload sensor polling and algorithm
> > -processing to a dedicated low power co-processor. This allows the core
> > -processor to go into low power modes more often, resulting in the increased
> > -battery life.
> > -
> > -There are many vendors providing external sensor hubs confirming to HID
> > -Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops
> > -and embedded products. Linux had this support since Linux 3.9.
> > -
> > -Intel® introduced integrated sensor hubs as a part of the SoC starting from
> > -Cherry Trail and now supported on multiple generations of CPU packages. There
> > -are many commercial devices already shipped with Integrated Sensor Hubs (ISH).
> > -These ISH also comply to HID sensor specification, but the  difference is the
> > -transport protocol used for communication. The current external sensor hubs
> > -mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB.
> > -
> > -1. Overview
> > -
> > -Using a analogy with a usbhid implementation, the ISH follows a similar model
> > -for a very high speed communication:
> > -
> > -       -----------------               ----------------------
> > -       |    USB HID    |       -->     |    ISH HID         |
> > -       -----------------               ----------------------
> > -       -----------------               ----------------------
> > -       |  USB protocol |       -->     |    ISH Transport   |
> > -       -----------------               ----------------------
> > -       -----------------               ----------------------
> > -       |  EHCI/XHCI    |       -->     |    ISH IPC         |
> > -       -----------------               ----------------------
> > -             PCI                                PCI
> > -       -----------------               ----------------------
> > -        |Host controller|      -->     |    ISH processor   |
> > -       -----------------               ----------------------
> > -            USB Link
> > -       -----------------               ----------------------
> > -       | USB End points|       -->     |    ISH Clients     |
> > -       -----------------               ----------------------
> > -
> > -Like USB protocol provides a method for device enumeration, link management
> > -and user data encapsulation, the ISH also provides similar services. But it is
> > -very light weight tailored to manage and communicate with ISH client
> > -applications implemented in the firmware.
> > -
> > -The ISH allows multiple sensor management applications executing in the
> > -firmware. Like USB endpoints the messaging can be to/from a client. As part of
> > -enumeration process, these clients are identified. These clients can be simple
> > -HID sensor applications, sensor calibration application or senor firmware
> > -update application.
> > -
> > -The implementation model is similar, like USB bus, ISH transport is also
> > -implemented as a bus. Each client application executing in the ISH processor
> > -is registered as a device on this bus. The driver, which binds each device
> > -(ISH HID driver) identifies the device type and registers with the hid core.
> > -
> > -2. ISH Implementation: Block Diagram
> > -
> > -        ---------------------------
> > -       |  User Space Applications  |
> > -        ---------------------------
> > -
> > -----------------IIO ABI----------------
> > -        --------------------------
> > -       |  IIO Sensor Drivers     |
> > -        --------------------------
> > -        --------------------------
> > -       |        IIO core         |
> > -        --------------------------
> > -        --------------------------
> > -       |   HID Sensor Hub MFD    |
> > -        --------------------------
> > -        --------------------------
> > -       |       HID Core          |
> > -        --------------------------
> > -        --------------------------
> > -       |   HID over ISH Client   |
> > -        --------------------------
> > -        --------------------------
> > -       |   ISH Transport (ISHTP) |
> > -        --------------------------
> > -        --------------------------
> > -       |      IPC Drivers        |
> > -        --------------------------
> > -OS
> > -----------------   PCI -----------------
> > -Hardware + Firmware
> > -        ----------------------------
> > -       | ISH Hardware/Firmware(FW) |
> > -        ----------------------------
> > -
> > -3. High level processing in above blocks
> > -
> > -3.1 Hardware Interface
> > -
> > -The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI
> > -product and vendor IDs are changed from different generations of processors. So
> > -the source code which enumerate drivers needs to update from generation to
> > -generation.
> > -
> > -3.2 Inter Processor Communication (IPC) driver
> > -Location: drivers/hid/intel-ish-hid/ipc
> > -
> > -The IPC message used memory mapped I/O. The registers are defined in
> > -hw-ish-regs.h.
> > -
> > -3.2.1 IPC/FW message types
> > -
> > -There are two types of messages, one for management of link and other messages
> > -are to and from transport layers.
> > -
> > -TX and RX of Transport messages
> > -
> > -A set of memory mapped register offers support of multi byte messages TX and
> > -RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains
> > -internal queues to sequence messages and send them in order to the FW.
> > -Optionally the caller can register handler to get notification of completion.
> > -A door bell mechanism is used in messaging to trigger processing in host and
> > -client firmware side. When ISH interrupt handler is called, the ISH2HOST
> > -doorbell register is used by host drivers to determine that the interrupt
> > -is for ISH.
> > -
> > -Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell
> > -register has the following format:
> > -Bits 0..6: fragment length (7 bits are used)
> > -Bits 10..13: encapsulated protocol
> > -Bits 16..19: management command (for IPC management protocol)
> > -Bit 31: doorbell trigger (signal H/W interrupt to the other side)
> > -Other bits are reserved, should be 0.
> > -
> > -3.2.2 Transport layer interface
> > -
> > -To abstract HW level IPC communication, a set of callbacks are registered.
> > -The transport layer uses them to send and receive messages.
> > -Refer to  struct ishtp_hw_ops for callbacks.
> > -
> > -3.3 ISH Transport layer
> > -Location: drivers/hid/intel-ish-hid/ishtp/
> > -
> > -3.3.1 A Generic Transport Layer
> > -
> > -The transport layer is a bi-directional protocol, which defines:
> > -- Set of commands to start, stop, connect, disconnect and flow control
> > -(ishtp/hbm.h) for details
> > -- A flow control mechanism to avoid buffer overflows
> > -
> > -This protocol resembles bus messages described in the following document:
> > -http://www.intel.com/content/dam/www/public/us/en/documents/technical-\
> > -specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer"
> > -
> > -3.3.2 Connection and Flow Control Mechanism
> > -
> > -Each FW client and a protocol is identified by an UUID. In order to communicate
> > -to a FW client, a connection must be established using connect request and
> > -response bus messages. If successful, a pair (host_client_id and fw_client_id)
> > -will identify the connection.
> > -
> > -Once connection is established, peers send each other flow control bus messages
> > -independently. Every peer may send a message only if it has received a
> > -flow-control credit before. Once it sent a message, it may not send another one
> > -before receiving the next flow control credit.
> > -Either side can send disconnect request bus message to end communication. Also
> > -the link will be dropped if major FW reset occurs.
> > -
> > -3.3.3 Peer to Peer data transfer
> > -
> > -Peer to Peer data transfer can happen with or without using DMA. Depending on
> > -the sensor bandwidth requirement DMA can be enabled by using module parameter
> > -ishtp_use_dma under intel_ishtp.
> > -
> > -Each side (host and FW) manages its DMA transfer memory independently. When an
> > -ISHTP client from either host or FW side wants to send something, it decides
> > -whether to send over IPC or over DMA; for each transfer the decision is
> > -independent. The sending side sends DMA_XFER message when the message is in
> > -the respective host buffer (TX when host client sends, RX when FW client
> > -sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating
> > -the sender that the memory region for that message may be reused.
> > -
> > -DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message
> > -(that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK.
> > -Additionally to DMA address communication, this sequence checks capabilities:
> > -if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't
> > -send DMA; if FW doesn't support DMA then it won't respond with
> > -DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers.
> > -Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER,
> > -it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means
> > -that it already did DMA and the message resides at host. Thus, DMA_XFER
> > -and DMA_XFER_ACK act as ownership indicators.
> > -
> > -At initial state all outgoing memory belongs to the sender (TX to host, RX to
> > -FW), DMA_XFER transfers ownership on the region that contains ISHTP message to
> > -the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender
> > -needs not wait for previous DMA_XFER to be ack'ed, and may send another message
> > -as long as remaining continuous memory in its ownership is enough.
> > -In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once
> > -(up to IPC MTU), thus allowing for interrupt throttling.
> > -Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC
> > -fragments and via IPC otherwise.
> > -
> > -3.3.4 Ring Buffers
> > -
> > -When a client initiate a connection, a ring or RX and TX buffers are allocated.
> > -The size of ring can be specified by the client. HID client set 16 and 32 for
> > -TX and RX buffers respectively. On send request from client, the data to be
> > -sent is copied to one of the send ring buffer and scheduled to be sent using
> > -bus message protocol. These buffers are required because the FW may have not
> > -have processed the last message and may not have enough flow control credits
> > -to send. Same thing holds true on receive side and flow control is required.
> > -
> > -3.3.5 Host Enumeration
> > -
> > -The host enumeration bus command allow discovery of clients present in the FW.
> > -There can be multiple sensor clients and clients for calibration function.
> > -
> > -To ease in implantation and allow independent driver handle each client
> > -this transport layer takes advantage of Linux Bus driver model. Each
> > -client is registered as device on the the transport bus (ishtp bus).
> > -
> > -Enumeration sequence of messages:
> > -- Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up.
> > -- FW responds with HOST_START_RES_CMD
> > -- Host sends HOST_ENUM_REQ_CMD (enumerate FW clients)
> > -- FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW
> > -client IDs
> > -- For each FW ID found in that bitmap host sends
> > -HOST_CLIENT_PROPERTIES_REQ_CMD
> > -- FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID,
> > -max ISHTP message size, etc.
> > -- Once host received properties for that last discovered client, it considers
> > -ISHTP device fully functional (and allocates DMA buffers)
> > -
> > -3.4 HID over ISH Client
> > -Location: drivers/hid/intel-ish-hid
> > -
> > -The ISHTP client driver is responsible for:
> > -- enumerate HID devices under FW ISH client
> > -- Get Report descriptor
> > -- Register with HID core as a LL driver
> > -- Process Get/Set feature request
> > -- Get input reports
> > -
> > -3.5 HID Sensor Hub MFD and IIO sensor drivers
> > -
> > -The functionality in these drivers is the same as an external sensor hub.
> > -Refer to
> > -Documentation/hid/hid-sensor.txt for HID sensor
> > -Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space
> > -
> > -3.6 End to End HID transport Sequence Diagram
> > -
> > -HID-ISH-CLN                    ISHTP                   IPC                             HW
> > -       |                       |                       |                               |
> > -       |                       |                       |-----WAKE UP------------------>|
> > -       |                       |                       |                               |
> > -       |                       |                       |-----HOST READY--------------->|
> > -       |                       |                       |                               |
> > -       |                       |                       |<----MNG_RESET_NOTIFY_ACK----- |
> > -       |                       |                       |                               |
> > -       |                       |<----ISHTP_START------ |                               |
> > -       |                       |                       |                               |
> > -       |                       |<-----------------HOST_START_RES_CMD-------------------|
> > -       |                       |                       |                               |
> > -       |                       |------------------QUERY_SUBSCRIBER-------------------->|
> > -       |                       |                       |                               |
> > -       |                       |------------------HOST_ENUM_REQ_CMD------------------->|
> > -       |                       |                       |                               |
> > -       |                       |<-----------------HOST_ENUM_RES_CMD--------------------|
> > -       |                       |                       |                               |
> > -       |                       |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
> > -       |                       |                       |                               |
> > -       |                       |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
> > -       |       Create new device on in ishtp bus       |                               |
> > -       |                       |                       |                               |
> > -       |                       |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
> > -       |                       |                       |                               |
> > -       |                       |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
> > -       |       Create new device on in ishtp bus       |                               |
> > -       |                       |                       |                               |
> > -       |                       |--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--|
> > -       |                       |                       |                               |
> > -     probed()
> > -       |----ishtp_cl_connect-->|----------------- CLIENT_CONNECT_REQ_CMD-------------->|
> > -       |                       |                       |                               |
> > -       |                       |<----------------CLIENT_CONNECT_RES_CMD----------------|
> > -       |                       |                       |                               |
> > -       |register event callback|                       |                               |
> > -       |                       |                       |                               |
> > -       |ishtp_cl_send(
> > -       HOSTIF_DM_ENUM_DEVICES) |----------fill ishtp_msg_hdr struct write to HW-----  >|
> > -       |                       |                       |                               |
> > -       |                       |                       |<-----IRQ(IPC_PROTOCOL_ISHTP---|
> > -       |                       |                       |                               |
> > -       |<--ENUM_DEVICE RSP-----|                       |                               |
> > -       |                       |                       |                               |
> > -for each enumerated device
> > -       |ishtp_cl_send(
> > -       HOSTIF_GET_HID_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW---  >|
> > -       |                       |                       |                               |
> > -       ...Response
> > -       |                       |                       |                               |
> > -for each enumerated device
> > -       |ishtp_cl_send(
> > -       HOSTIF_GET_REPORT_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW- >|
> > -       |                       |                       |                               |
> > -       |                       |                       |                               |
> > - hid_allocate_device
> > -       |                       |                       |                               |
> > - hid_add_device                        |                       |                               |
> > -       |                       |                       |                               |
> > -
> > -
> > -3.7 ISH Debugging
> > -
> > -To debug ISH, event tracing mechanism is used. To enable debug logs
> > -echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable
> > -cat sys/kernel/debug/tracing/trace
> > -
> > -3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260
> > -
> > -root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/
> > -/sys/bus/iio/devices/
> > -├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0
> > -│   ├── buffer
> > -│   │   ├── enable
> > -│   │   ├── length
> > -│   │   └── watermark
> > -...
> > -│   ├── in_accel_hysteresis
> > -│   ├── in_accel_offset
> > -│   ├── in_accel_sampling_frequency
> > -│   ├── in_accel_scale
> > -│   ├── in_accel_x_raw
> > -│   ├── in_accel_y_raw
> > -│   ├── in_accel_z_raw
> > -│   ├── name
> > -│   ├── scan_elements
> > -│   │   ├── in_accel_x_en
> > -│   │   ├── in_accel_x_index
> > -│   │   ├── in_accel_x_type
> > -│   │   ├── in_accel_y_en
> > -│   │   ├── in_accel_y_index
> > -│   │   ├── in_accel_y_type
> > -│   │   ├── in_accel_z_en
> > -│   │   ├── in_accel_z_index
> > -│   │   └── in_accel_z_type
> > -...
> > -│   │   ├── devices
> > -│   │   │   │   ├── buffer
> > -│   │   │   │   │   ├── enable
> > -│   │   │   │   │   ├── length
> > -│   │   │   │   │   └── watermark
> > -│   │   │   │   ├── dev
> > -│   │   │   │   ├── in_intensity_both_raw
> > -│   │   │   │   ├── in_intensity_hysteresis
> > -│   │   │   │   ├── in_intensity_offset
> > -│   │   │   │   ├── in_intensity_sampling_frequency
> > -│   │   │   │   ├── in_intensity_scale
> > -│   │   │   │   ├── name
> > -│   │   │   │   ├── scan_elements
> > -│   │   │   │   │   ├── in_intensity_both_en
> > -│   │   │   │   │   ├── in_intensity_both_index
> > -│   │   │   │   │   └── in_intensity_both_type
> > -│   │   │   │   ├── trigger
> > -│   │   │   │   │   └── current_trigger
> > -...
> > -│   │   │   │   ├── buffer
> > -│   │   │   │   │   ├── enable
> > -│   │   │   │   │   ├── length
> > -│   │   │   │   │   └── watermark
> > -│   │   │   │   ├── dev
> > -│   │   │   │   ├── in_magn_hysteresis
> > -│   │   │   │   ├── in_magn_offset
> > -│   │   │   │   ├── in_magn_sampling_frequency
> > -│   │   │   │   ├── in_magn_scale
> > -│   │   │   │   ├── in_magn_x_raw
> > -│   │   │   │   ├── in_magn_y_raw
> > -│   │   │   │   ├── in_magn_z_raw
> > -│   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_raw
> > -│   │   │   │   ├── in_rot_hysteresis
> > -│   │   │   │   ├── in_rot_offset
> > -│   │   │   │   ├── in_rot_sampling_frequency
> > -│   │   │   │   ├── in_rot_scale
> > -│   │   │   │   ├── name
> > -...
> > -│   │   │   │   ├── scan_elements
> > -│   │   │   │   │   ├── in_magn_x_en
> > -│   │   │   │   │   ├── in_magn_x_index
> > -│   │   │   │   │   ├── in_magn_x_type
> > -│   │   │   │   │   ├── in_magn_y_en
> > -│   │   │   │   │   ├── in_magn_y_index
> > -│   │   │   │   │   ├── in_magn_y_type
> > -│   │   │   │   │   ├── in_magn_z_en
> > -│   │   │   │   │   ├── in_magn_z_index
> > -│   │   │   │   │   ├── in_magn_z_type
> > -│   │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_en
> > -│   │   │   │   │   ├── in_rot_from_north_magnetic_tilt_comp_index
> > -│   │   │   │   │   └── in_rot_from_north_magnetic_tilt_comp_type
> > -│   │   │   │   ├── trigger
> > -│   │   │   │   │   └── current_trigger
> > -...
> > -│   │   │   │   ├── buffer
> > -│   │   │   │   │   ├── enable
> > -│   │   │   │   │   ├── length
> > -│   │   │   │   │   └── watermark
> > -│   │   │   │   ├── dev
> > -│   │   │   │   ├── in_anglvel_hysteresis
> > -│   │   │   │   ├── in_anglvel_offset
> > -│   │   │   │   ├── in_anglvel_sampling_frequency
> > -│   │   │   │   ├── in_anglvel_scale
> > -│   │   │   │   ├── in_anglvel_x_raw
> > -│   │   │   │   ├── in_anglvel_y_raw
> > -│   │   │   │   ├── in_anglvel_z_raw
> > -│   │   │   │   ├── name
> > -│   │   │   │   ├── scan_elements
> > -│   │   │   │   │   ├── in_anglvel_x_en
> > -│   │   │   │   │   ├── in_anglvel_x_index
> > -│   │   │   │   │   ├── in_anglvel_x_type
> > -│   │   │   │   │   ├── in_anglvel_y_en
> > -│   │   │   │   │   ├── in_anglvel_y_index
> > -│   │   │   │   │   ├── in_anglvel_y_type
> > -│   │   │   │   │   ├── in_anglvel_z_en
> > -│   │   │   │   │   ├── in_anglvel_z_index
> > -│   │   │   │   │   └── in_anglvel_z_type
> > -│   │   │   │   ├── trigger
> > -│   │   │   │   │   └── current_trigger
> > -...
> > -│   │   │   │   ├── buffer
> > -│   │   │   │   │   ├── enable
> > -│   │   │   │   │   ├── length
> > -│   │   │   │   │   └── watermark
> > -│   │   │   │   ├── dev
> > -│   │   │   │   ├── in_anglvel_hysteresis
> > -│   │   │   │   ├── in_anglvel_offset
> > -│   │   │   │   ├── in_anglvel_sampling_frequency
> > -│   │   │   │   ├── in_anglvel_scale
> > -│   │   │   │   ├── in_anglvel_x_raw
> > -│   │   │   │   ├── in_anglvel_y_raw
> > -│   │   │   │   ├── in_anglvel_z_raw
> > -│   │   │   │   ├── name
> > -│   │   │   │   ├── scan_elements
> > -│   │   │   │   │   ├── in_anglvel_x_en
> > -│   │   │   │   │   ├── in_anglvel_x_index
> > -│   │   │   │   │   ├── in_anglvel_x_type
> > -│   │   │   │   │   ├── in_anglvel_y_en
> > -│   │   │   │   │   ├── in_anglvel_y_index
> > -│   │   │   │   │   ├── in_anglvel_y_type
> > -│   │   │   │   │   ├── in_anglvel_z_en
> > -│   │   │   │   │   ├── in_anglvel_z_index
> > -│   │   │   │   │   └── in_anglvel_z_type
> > -│   │   │   │   ├── trigger
> > -│   │   │   │   │   └── current_trigger
> > -...
> > diff --git a/Documentation/hid/uhid.txt b/Documentation/hid/uhid.rst
> > similarity index 94%
> > rename from Documentation/hid/uhid.txt
> > rename to Documentation/hid/uhid.rst
> > index 958fff945304..b18cb96c885f 100644
> > --- a/Documentation/hid/uhid.txt
> > +++ b/Documentation/hid/uhid.rst
> > @@ -1,5 +1,6 @@
> > -      UHID - User-space I/O driver support for HID subsystem
> > -     ========================================================
> > +======================================================
> > +UHID - User-space I/O driver support for HID subsystem
> > +======================================================
> >
> >  UHID allows user-space to implement HID transport drivers. Please see
> >  hid-transport.txt for an introduction into HID transport drivers. This document
> > @@ -22,9 +23,9 @@ If a new device is detected by your HID I/O Driver and you want to register this
> >  device with the HID subsystem, then you need to open /dev/uhid once for each
> >  device you want to register. All further communication is done by read()'ing or
> >  write()'ing "struct uhid_event" objects. Non-blocking operations are supported
> > -by setting O_NONBLOCK.
> > +by setting O_NONBLOCK::
> >
> > -struct uhid_event {
> > +  struct uhid_event {
> >          __u32 type;
> >          union {
> >                  struct uhid_create2_req create2;
> > @@ -32,7 +33,7 @@ struct uhid_event {
> >                  struct uhid_input2_req input2;
> >                  ...
> >          } u;
> > -};
> > +  };
> >
> >  The "type" field contains the ID of the event. Depending on the ID different
> >  payloads are sent. You must not split a single event across multiple read()'s or
> > @@ -86,31 +87,31 @@ the request was handled successfully. O_NONBLOCK does not affect write() as
> >  writes are always handled immediately in a non-blocking fashion. Future requests
> >  might make use of O_NONBLOCK, though.
> >
> > -  UHID_CREATE2:
> > +UHID_CREATE2:
> >    This creates the internal HID device. No I/O is possible until you send this
> >    event to the kernel. The payload is of type struct uhid_create2_req and
> >    contains information about your device. You can start I/O now.
> >
> > -  UHID_DESTROY:
> > +UHID_DESTROY:
> >    This destroys the internal HID device. No further I/O will be accepted. There
> >    may still be pending messages that you can receive with read() but no further
> >    UHID_INPUT events can be sent to the kernel.
> >    You can create a new device by sending UHID_CREATE2 again. There is no need to
> >    reopen the character device.
> >
> > -  UHID_INPUT2:
> > +UHID_INPUT2:
> >    You must send UHID_CREATE2 before sending input to the kernel! This event
> >    contains a data-payload. This is the raw data that you read from your device
> >    on the interrupt channel. The kernel will parse the HID reports.
> >
> > -  UHID_GET_REPORT_REPLY:
> > +UHID_GET_REPORT_REPLY:
> >    If you receive a UHID_GET_REPORT request you must answer with this request.
> >    You  must copy the "id" field from the request into the answer. Set the "err"
> >    field to 0 if no error occurred or to EIO if an I/O error occurred.
> >    If "err" is 0 then you should fill the buffer of the answer with the results
> >    of the GET_REPORT request and set "size" correspondingly.
> >
> > -  UHID_SET_REPORT_REPLY:
> > +UHID_SET_REPORT_REPLY:
> >    This is the SET_REPORT equivalent of UHID_GET_REPORT_REPLY. Unlike GET_REPORT,
> >    SET_REPORT never returns a data buffer, therefore, it's sufficient to set the
> >    "id" and "err" fields correctly.
> > @@ -120,16 +121,18 @@ read()
> >  read() will return a queued output report. No reaction is required to any of
> >  them but you should handle them according to your needs.
> >
> > -  UHID_START:
> > +UHID_START:
> >    This is sent when the HID device is started. Consider this as an answer to
> >    UHID_CREATE2. This is always the first event that is sent. Note that this
> >    event might not be available immediately after write(UHID_CREATE2) returns.
> >    Device drivers might required delayed setups.
> >    This event contains a payload of type uhid_start_req. The "dev_flags" field
> >    describes special behaviors of a device. The following flags are defined:
> > -      UHID_DEV_NUMBERED_FEATURE_REPORTS:
> > -      UHID_DEV_NUMBERED_OUTPUT_REPORTS:
> > -      UHID_DEV_NUMBERED_INPUT_REPORTS:
> > +
> > +      - UHID_DEV_NUMBERED_FEATURE_REPORTS
> > +      - UHID_DEV_NUMBERED_OUTPUT_REPORTS
> > +      - UHID_DEV_NUMBERED_INPUT_REPORTS
> > +
> >            Each of these flags defines whether a given report-type uses numbered
> >            reports. If numbered reports are used for a type, all messages from
> >            the kernel already have the report-number as prefix. Otherwise, no
> > @@ -137,33 +140,35 @@ them but you should handle them according to your needs.
> >            For messages sent by user-space to the kernel, you must adjust the
> >            prefixes according to these flags.
> >
> > -  UHID_STOP:
> > +UHID_STOP:
> >    This is sent when the HID device is stopped. Consider this as an answer to
> >    UHID_DESTROY.
> > +
> >    If you didn't destroy your device via UHID_DESTROY, but the kernel sends an
> >    UHID_STOP event, this should usually be ignored. It means that the kernel
> >    reloaded/changed the device driver loaded on your HID device (or some other
> >    maintenance actions happened).
> > +
> >    You can usually ignored any UHID_STOP events safely.
> >
> > -  UHID_OPEN:
> > +UHID_OPEN:
> >    This is sent when the HID device is opened. That is, the data that the HID
> >    device provides is read by some other process. You may ignore this event but
> >    it is useful for power-management. As long as you haven't received this event
> >    there is actually no other process that reads your data so there is no need to
> >    send UHID_INPUT2 events to the kernel.
> >
> > -  UHID_CLOSE:
> > +UHID_CLOSE:
> >    This is sent when there are no more processes which read the HID data. It is
> >    the counterpart of UHID_OPEN and you may as well ignore this event.
> >
> > -  UHID_OUTPUT:
> > +UHID_OUTPUT:
> >    This is sent if the HID device driver wants to send raw data to the I/O
> >    device on the interrupt channel. You should read the payload and forward it to
> >    the device. The payload is of type "struct uhid_output_req".
> >    This may be received even though you haven't received UHID_OPEN, yet.
> >
> > -  UHID_GET_REPORT:
> > +UHID_GET_REPORT:
> >    This event is sent if the kernel driver wants to perform a GET_REPORT request
> >    on the control channeld as described in the HID specs. The report-type and
> >    report-number are available in the payload.
> > @@ -177,11 +182,12 @@ them but you should handle them according to your needs.
> >    timed out, the kernel will ignore the response silently. The "id" field is
> >    never re-used, so conflicts cannot happen.
> >
> > -  UHID_SET_REPORT:
> > +UHID_SET_REPORT:
> >    This is the SET_REPORT equivalent of UHID_GET_REPORT. On receipt, you shall
> >    send a SET_REPORT request to your hid device. Once it replies, you must tell
> >    the kernel about it via UHID_SET_REPORT_REPLY.
> >    The same restrictions as for UHID_GET_REPORT apply.
> >
> >  ----------------------------------------------------
> > +
> >  Written 2012, David Herrmann <dh.herrmann@gmail.com>
> > diff --git a/Documentation/input/input.rst b/Documentation/input/input.rst
> > index 47f86a4bf16c..0eb61e67a7b7 100644
> > --- a/Documentation/input/input.rst
> > +++ b/Documentation/input/input.rst
> > @@ -188,7 +188,7 @@ LCDs and many other purposes.
> >
> >  The monitor and speaker controls should be easy to add to the hid/input
> >  interface, but for the UPSs and LCDs it doesn't make much sense. For this,
> > -the hiddev interface was designed. See Documentation/hid/hiddev.txt
> > +the hiddev interface was designed. See Documentation/hid/hiddev.rst
> >  for more information about it.
> >
> >  The usage of the usbhid module is very simple, it takes no parameters,
> > diff --git a/MAINTAINERS b/MAINTAINERS
> > index 8d39979e4091..969225e6bfce 100644
> > --- a/MAINTAINERS
> > +++ b/MAINTAINERS
> > @@ -16383,7 +16383,7 @@ M:      Benjamin Tissoires <benjamin.tissoires@redhat.com>
> >  L:     linux-usb@vger.kernel.org
> >  T:     git git://git.kernel.org/pub/scm/linux/kernel/git/hid/hid.git
> >  S:     Maintained
> > -F:     Documentation/hid/hiddev.txt
> > +F:     Documentation/hid/hiddev.rst
> >  F:     drivers/hid/usbhid/
> >
> >  USB INTEL XHCI ROLE MUX DRIVER
> > --
> > 2.21.0
> >  



Thanks,
Mauro

^ permalink raw reply	[flat|nested] 38+ messages in thread

* Re: [PATCH v1 24/31] docs: iio: convert to ReST
  2019-06-12 18:38 ` [PATCH v1 24/31] docs: iio: " Mauro Carvalho Chehab
@ 2019-06-16 13:47   ` Jonathan Cameron
  0 siblings, 0 replies; 38+ messages in thread
From: Jonathan Cameron @ 2019-06-16 13:47 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Hartmut Knaack, Lars-Peter Clausen,
	Peter Meerwald-Stadler, linux-iio

On Wed, 12 Jun 2019 15:38:27 -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>
Thanks, looks good to me.   At some point we need to look at how
to tie together the various IIO docs as they are split between
here and the driver-api/iio/ directory.  That split isn't currently
along particularly logical lines.

Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>

Thanks for tidying this up!

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"


^ permalink raw reply	[flat|nested] 38+ messages in thread

end of thread, other threads:[~2019-06-16 13:47 UTC | newest]

Thread overview: 38+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-06-12 18:38 [PATCH v1 00/31] Convert files to ReST - part 2 Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 01/31] docs: connector: convert to ReST and rename to connector.rst Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 02/31] docs: lcd-panel-cgram.txt: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 03/31] docs: lp855x-driver.txt: convert to ReST and move to kernel-api Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 04/31] docs: m68k: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 05/31] docs: cma/debugfs.txt: " Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 06/31] docs: console.txt: " Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 07/31] docs: pti_intel_mid.txt: convert it to pti_intel_mid.rst Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 08/31] docs: early-userspace: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 09/31] docs: driver-model: " Mauro Carvalho Chehab
2019-06-12 20:21   ` Jeff Kirsher
2019-06-12 18:38 ` [PATCH v1 11/31] docs: memory-devices: convert ti-emif.txt to ReST Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 12/31] docs: xen-tpmfront.txt: convert it to .rst Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 13/31] docs: bus-devices: ti-gpmc.rst: convert it to ReST Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 14/31] docs: nvmem: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 15/31] docs: phy: convert samsung-usb2.txt to ReST format Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 16/31] docs: rbtree.txt: fix Sphinx build warnings Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 17/31] docs: DMA-API-HOWTO.txt: fix an unmarked code block Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 18/31] docs: accounting: convert to ReST Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 19/31] docs: fmc: " Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 20/31] docs: hid: " Mauro Carvalho Chehab
2019-06-13  8:08   ` Benjamin Tissoires
2019-06-13  9:52     ` Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 21/31] docs: ia64: " Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 22/31] docs: leds: " Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 23/31] docs: laptops: " Mauro Carvalho Chehab
2019-06-12 20:19   ` Andy Shevchenko
2019-06-12 18:38 ` [PATCH v1 24/31] docs: iio: " Mauro Carvalho Chehab
2019-06-16 13:47   ` Jonathan Cameron
2019-06-12 18:38 ` [PATCH v1 25/31] docs: namespaces: " Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 26/31] docs: nfc: " Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 27/31] docs: md: " Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 28/31] docs: mtd: " Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 29/31] docs: nvdimm: " Mauro Carvalho Chehab
2019-06-12 19:04   ` Dan Williams
2019-06-12 20:41     ` Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 30/31] docs: xtensa: " Mauro Carvalho Chehab
2019-06-12 18:38 ` [PATCH v1 31/31] docs: mmc: " Mauro Carvalho Chehab

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).