All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH v2 00/26] ReST conversion of text files without .txt extension
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: Mauro Carvalho Chehab, linux-doc, linux-kernel, linux-pm,
	linux-arm-kernel, linux-samsung-soc, linux-pci, linuxppc-dev,
	linux-scsi, devicetree, linux-i2c, linux-hwmon, linux-spi,
	linux-iio, linux-rtc, netdev, linux-parisc, openrisc, devel,
	linux-cifs, samba-technical, devel, dmaengine, alsa-devel,
	linux-mips, linux-wireless, rcu

This series converts the text files under Documentation with doesn't end
neither .txt or .rst and are not part of ABI or features.

This series is at:
	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3

And it is based on yesterday's upstream tree.

After this series, we have ~320 files left to be converted to ReST.

v2:
  - Added 3 files submitted for v5.3 that weren't merged yet;
  - markdown patch broken into two, per Rob's request;
  - rebased on the top of upstream master branch

Mauro Carvalho Chehab (26):
  docs: power: add it to to the main documentation index
  docs: thermal: add it to the driver API
  docs: powerpc: convert docs to ReST and rename to *.rst
  docs: ubifs-authentication.md: convert to ReST
  docs: writing-schema.md: convert from markdown to ReST
  docs: i2c: convert to ReST and add to driver-api bookset
  docs: w1: convert to ReST and add to the kAPI group of docs
  spi: docs: convert to ReST and add it to the kABI bookset
  docs: ipmb: place it at driver-api and convert to ReST
  docs: packing: move it to core-api book and adjust markups
  docs: admin-guide: add auxdisplay files to it after conversion to ReST
  docs: README.buddha: convert to ReST and add to m68k book
  docs: parisc: convert to ReST and add to documentation body
  docs: openrisc: convert to ReST and add to documentation body
  docs: isdn: convert to ReST and add to kAPI bookset
  docs: fs: cifs: convert to ReST and add to admin-guide book
  docs: fs: convert docs without extension to ReST
  docs: fs: convert porting to ReST
  docs: index.rst: don't use genindex for pdf output
  docs: wimax: convert to ReST and add to admin-guide
  docs: mips: add to the documentation body as ReST
  docs: hwmon: pxe1610: convert to ReST format and add to the index
  docs: nios2: add it to the main Documentation body
  docs: net: convert two README files to ReST format
  docs: rcu: convert some articles from html to ReST
  docs: ABI: remove extension from sysfs-class-mic.txt

 Documentation/ABI/stable/sysfs-bus-w1         |    2 +-
 .../ABI/stable/sysfs-driver-w1_ds28e04        |    4 +-
 .../ABI/stable/sysfs-driver-w1_ds28ea00       |    2 +-
 .../{sysfs-class-mic.txt => sysfs-class-mic}  |    0
 Documentation/PCI/pci-error-recovery.rst      |    2 +-
 .../Data-Structures/Data-Structures.html      | 1391 -------
 .../Data-Structures/Data-Structures.rst       | 1163 ++++++
 ...riods.html => Expedited-Grace-Periods.rst} |  949 ++---
 .../Memory-Ordering/Tree-RCU-Diagram.html     |    9 -
 ...ring.html => Tree-RCU-Memory-Ordering.rst} | 1181 +++---
 .../RCU/Design/Requirements/Requirements.html | 3330 -----------------
 .../RCU/Design/Requirements/Requirements.rst  | 2662 +++++++++++++
 Documentation/RCU/index.rst                   |    5 +
 Documentation/RCU/whatisRCU.txt               |    4 +-
 .../auxdisplay/cfag12864b.rst}                |  115 +-
 .../admin-guide/auxdisplay/index.rst          |   16 +
 .../auxdisplay/ks0108.rst}                    |   53 +-
 .../AUTHORS => admin-guide/cifs/authors.rst}  |   64 +-
 .../CHANGES => admin-guide/cifs/changes.rst}  |    4 +
 Documentation/admin-guide/cifs/index.rst      |   21 +
 .../cifs/introduction.rst}                    |    8 +
 .../cifs/TODO => admin-guide/cifs/todo.rst}   |   87 +-
 .../README => admin-guide/cifs/usage.rst}     |  560 +--
 .../cifs/winucase_convert.pl                  |    0
 Documentation/admin-guide/index.rst           |    3 +
 .../wimax/i2400m.rst}                         |  145 +-
 Documentation/admin-guide/wimax/index.rst     |   19 +
 .../wimax/wimax.rst}                          |   36 +-
 Documentation/core-api/index.rst              |    3 +-
 .../{packing.txt => core-api/packing.rst}     |   81 +-
 .../devicetree/bindings/i2c/i2c-mux-gpmux.txt |    2 +-
 .../{writing-schema.md => writing-schema.rst} |  137 +-
 Documentation/driver-api/dmaengine/index.rst  |    2 +-
 Documentation/driver-api/index.rst            |    2 +
 Documentation/driver-api/ipmb.rst             |    2 +-
 Documentation/driver-api/soundwire/index.rst  |    2 +-
 .../thermal/cpu-cooling-api.rst               |    0
 .../thermal/exynos_thermal.rst                |    0
 .../thermal/exynos_thermal_emulation.rst      |    0
 .../{ => driver-api}/thermal/index.rst        |    2 +-
 .../thermal/intel_powerclamp.rst              |    0
 .../thermal/nouveau_thermal.rst               |    0
 .../thermal/power_allocator.rst               |    0
 .../{ => driver-api}/thermal/sysfs-api.rst    |   12 +-
 .../thermal/x86_pkg_temperature_thermal.rst   |    2 +-
 ...irectory-locking => directory-locking.rst} |   40 +-
 Documentation/filesystems/index.rst           |    4 +
 .../filesystems/{Locking => locking.rst}      |  257 +-
 .../nfs/{Exporting => exporting.rst}          |   31 +-
 .../filesystems/{porting => porting.rst}      |  824 ++--
 ...entication.md => ubifs-authentication.rst} |   70 +-
 Documentation/filesystems/vfs.rst             |    2 +-
 Documentation/hwmon/adm1021.rst               |    2 +-
 Documentation/hwmon/adm1275.rst               |    2 +-
 Documentation/hwmon/hih6130.rst               |    2 +-
 Documentation/hwmon/ibm-cffps.rst             |    2 +-
 Documentation/hwmon/index.rst                 |    1 +
 Documentation/hwmon/lm25066.rst               |    2 +-
 Documentation/hwmon/max16064.rst              |    2 +-
 Documentation/hwmon/max16065.rst              |    2 +-
 Documentation/hwmon/max20751.rst              |    2 +-
 Documentation/hwmon/max34440.rst              |    2 +-
 Documentation/hwmon/max6650.rst               |    2 +-
 Documentation/hwmon/max8688.rst               |    2 +-
 Documentation/hwmon/menf21bmc.rst             |    2 +-
 Documentation/hwmon/pcf8591.rst               |    2 +-
 Documentation/hwmon/{pxe1610 => pxe1610.rst}  |   33 +-
 Documentation/hwmon/sht3x.rst                 |    2 +-
 Documentation/hwmon/shtc1.rst                 |    2 +-
 Documentation/hwmon/tmp103.rst                |    2 +-
 Documentation/hwmon/tps40422.rst              |    2 +-
 Documentation/hwmon/ucd9000.rst               |    2 +-
 Documentation/hwmon/ucd9200.rst               |    2 +-
 Documentation/hwmon/via686a.rst               |    2 +-
 Documentation/hwmon/zl6100.rst                |    2 +-
 .../busses/{i2c-ali1535 => i2c-ali1535.rst}   |   13 +-
 .../busses/{i2c-ali1563 => i2c-ali1563.rst}   |    3 +
 .../busses/{i2c-ali15x3 => i2c-ali15x3.rst}   |   64 +-
 .../busses/{i2c-amd-mp2 => i2c-amd-mp2.rst}   |   14 +-
 .../i2c/busses/{i2c-amd756 => i2c-amd756.rst} |    8 +-
 .../busses/{i2c-amd8111 => i2c-amd8111.rst}   |   14 +-
 .../{i2c-diolan-u2c => i2c-diolan-u2c.rst}    |    3 +
 .../i2c/busses/{i2c-i801 => i2c-i801.rst}     |   33 +-
 .../i2c/busses/{i2c-ismt => i2c-ismt.rst}     |   20 +-
 .../busses/{i2c-mlxcpld => i2c-mlxcpld.rst}   |    6 +
 .../busses/{i2c-nforce2 => i2c-nforce2.rst}   |   33 +-
 .../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst}    |    6 +-
 .../i2c/busses/{i2c-ocores => i2c-ocores.rst} |   22 +-
 ...2c-parport-light => i2c-parport-light.rst} |    8 +-
 .../busses/{i2c-parport => i2c-parport.rst}   |  164 +-
 .../busses/{i2c-pca-isa => i2c-pca-isa.rst}   |    9 +-
 .../i2c/busses/{i2c-piix4 => i2c-piix4.rst}   |   18 +-
 .../busses/{i2c-sis5595 => i2c-sis5595.rst}   |   19 +-
 .../i2c/busses/{i2c-sis630 => i2c-sis630.rst} |   39 +-
 .../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} |   31 +-
 .../busses/{i2c-taos-evm => i2c-taos-evm.rst} |    8 +-
 .../i2c/busses/{i2c-via => i2c-via.rst}       |   28 +-
 .../i2c/busses/{i2c-viapro => i2c-viapro.rst} |   12 +-
 Documentation/i2c/busses/index.rst            |   33 +
 .../i2c/busses/{scx200_acb => scx200_acb.rst} |    9 +-
 .../i2c/{dev-interface => dev-interface.rst}  |   94 +-
 ...-considerations => dma-considerations.rst} |    0
 .../i2c/{fault-codes => fault-codes.rst}      |    5 +-
 .../i2c/{functionality => functionality.rst}  |   22 +-
 ...ult-injection => gpio-fault-injection.rst} |   12 +-
 .../i2c/{i2c-protocol => i2c-protocol.rst}    |   28 +-
 Documentation/i2c/{i2c-stub => i2c-stub.rst}  |   20 +-
 .../i2c/{i2c-topology => i2c-topology.rst}    |   68 +-
 Documentation/i2c/index.rst                   |   37 +
 ...ting-devices => instantiating-devices.rst} |   45 +-
 .../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst}  |   26 +-
 ...e-parameters => old-module-parameters.rst} |   27 +-
 ...eprom-backend => slave-eeprom-backend.rst} |    4 +-
 .../{slave-interface => slave-interface.rst}  |   33 +-
 .../{smbus-protocol => smbus-protocol.rst}    |   86 +-
 Documentation/i2c/{summary => summary.rst}    |    6 +-
 ...en-bit-addresses => ten-bit-addresses.rst} |    5 +
 ...pgrading-clients => upgrading-clients.rst} |  204 +-
 .../{writing-clients => writing-clients.rst}  |   94 +-
 Documentation/index.rst                       |   10 +
 .../isdn/{README.avmb1 => avmb1.rst}          |  231 +-
 Documentation/isdn/{CREDITS => credits.rst}   |    7 +-
 .../isdn/{README.gigaset => gigaset.rst}      |  290 +-
 .../isdn/{README.hysdn => hysdn.rst}          |  125 +-
 Documentation/isdn/index.rst                  |   24 +
 .../{INTERFACE.CAPI => interface_capi.rst}    |  182 +-
 .../isdn/{README.mISDN => m_isdn.rst}         |    5 +-
 .../m68k/{README.buddha => buddha-driver.rst} |   95 +-
 Documentation/m68k/index.rst                  |    1 +
 .../{AU1xxx_IDE.README => au1xxx_ide.rst}     |   89 +-
 Documentation/mips/index.rst                  |   17 +
 .../networking/caif/{README => caif.rst}      |   88 +-
 .../networking/device_drivers/index.rst       |    2 +-
 Documentation/networking/index.rst            |    2 +-
 .../{README => mac80211_hwsim.rst}            |   28 +-
 Documentation/nios2/{README => nios2.rst}     |    1 +
 Documentation/openrisc/index.rst              |   18 +
 .../openrisc/{README => openrisc_port.rst}    |   25 +-
 Documentation/openrisc/{TODO => todo.rst}     |    9 +-
 .../parisc/{debugging => debugging.rst}       |    7 +
 Documentation/parisc/index.rst                |   18 +
 .../parisc/{registers => registers.rst}       |   59 +-
 Documentation/power/index.rst                 |    2 +-
 .../{bootwrapper.txt => bootwrapper.rst}      |   28 +-
 .../{cpu_families.txt => cpu_families.rst}    |   23 +-
 .../{cpu_features.txt => cpu_features.rst}    |    6 +-
 Documentation/powerpc/{cxl.txt => cxl.rst}    |   46 +-
 .../powerpc/{cxlflash.txt => cxlflash.rst}    |   10 +-
 .../{DAWR-POWER9.txt => dawr-power9.rst}      |   15 +-
 Documentation/powerpc/{dscr.txt => dscr.rst}  |   18 +-
 ...ecovery.txt => eeh-pci-error-recovery.rst} |  108 +-
 ...ed-dump.txt => firmware-assisted-dump.rst} |  117 +-
 Documentation/powerpc/{hvcs.txt => hvcs.rst}  |  108 +-
 Documentation/powerpc/index.rst               |   34 +
 Documentation/powerpc/isa-versions.rst        |   15 +-
 .../powerpc/{mpc52xx.txt => mpc52xx.rst}      |   12 +-
 ...nv.txt => pci_iov_resource_on_powernv.rst} |   15 +-
 .../powerpc/{pmu-ebb.txt => pmu-ebb.rst}      |    1 +
 .../powerpc/{ptrace.txt => ptrace.rst}        |  169 +-
 .../{qe_firmware.txt => qe_firmware.rst}      |   37 +-
 .../{syscall64-abi.txt => syscall64-abi.rst}  |   29 +-
 ...al_memory.txt => transactional_memory.rst} |   45 +-
 Documentation/sound/index.rst                 |    2 +-
 .../spi/{butterfly => butterfly.rst}          |   44 +-
 Documentation/spi/index.rst                   |   22 +
 Documentation/spi/{pxa2xx => pxa2xx.rst}      |   95 +-
 .../spi/{spi-lm70llp => spi-lm70llp.rst}      |   17 +-
 .../spi/{spi-sc18is602 => spi-sc18is602.rst}  |    5 +-
 .../spi/{spi-summary => spi-summary.rst}      |  105 +-
 Documentation/spi/{spidev => spidev.rst}      |   30 +-
 Documentation/w1/index.rst                    |   21 +
 .../w1/masters/{ds2482 => ds2482.rst}         |   16 +-
 .../w1/masters/{ds2490 => ds2490.rst}         |    6 +-
 Documentation/w1/masters/index.rst            |   14 +
 .../w1/masters/{mxc-w1 => mxc-w1.rst}         |   13 +-
 .../w1/masters/{omap-hdq => omap-hdq.rst}     |   12 +-
 .../w1/masters/{w1-gpio => w1-gpio.rst}       |   21 +-
 Documentation/w1/slaves/index.rst             |   16 +
 .../w1/slaves/{w1_ds2406 => w1_ds2406.rst}    |    4 +-
 .../w1/slaves/{w1_ds2413 => w1_ds2413.rst}    |    9 +
 .../w1/slaves/{w1_ds2423 => w1_ds2423.rst}    |   27 +-
 .../w1/slaves/{w1_ds2438 => w1_ds2438.rst}    |   10 +-
 .../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst}  |    5 +
 .../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst}  |   16 +-
 .../w1/slaves/{w1_therm => w1_therm.rst}      |   11 +-
 .../w1/{w1.generic => w1-generic.rst}         |   88 +-
 .../w1/{w1.netlink => w1-netlink.rst}         |   89 +-
 MAINTAINERS                                   |   68 +-
 arch/powerpc/kernel/exceptions-64s.S          |    2 +-
 drivers/auxdisplay/Kconfig                    |    2 +-
 drivers/hwmon/atxp1.c                         |    2 +-
 drivers/hwmon/smm665.c                        |    2 +-
 drivers/i2c/Kconfig                           |    4 +-
 drivers/i2c/busses/Kconfig                    |    2 +-
 drivers/i2c/busses/i2c-i801.c                 |    2 +-
 drivers/i2c/busses/i2c-taos-evm.c             |    2 +-
 drivers/i2c/i2c-core-base.c                   |    4 +-
 drivers/iio/dummy/iio_simple_dummy.c          |    4 +-
 drivers/rtc/rtc-ds1374.c                      |    2 +-
 drivers/soc/fsl/qe/qe.c                       |    2 +-
 drivers/spi/Kconfig                           |    2 +-
 drivers/spi/spi-butterfly.c                   |    2 +-
 drivers/spi/spi-lm70llp.c                     |    2 +-
 drivers/staging/isdn/hysdn/Kconfig            |    2 +-
 drivers/tty/hvc/hvcs.c                        |    2 +-
 fs/cifs/export.c                              |    2 +-
 fs/exportfs/expfs.c                           |    2 +-
 fs/isofs/export.c                             |    2 +-
 fs/orangefs/file.c                            |    2 +-
 fs/orangefs/orangefs-kernel.h                 |    2 +-
 include/linux/dcache.h                        |    2 +-
 include/linux/exportfs.h                      |    2 +-
 include/linux/i2c.h                           |    2 +-
 include/linux/platform_data/sc18is602.h       |    2 +-
 include/linux/thermal.h                       |    4 +-
 include/soc/fsl/qe/qe.h                       |    2 +-
 216 files changed, 9148 insertions(+), 8672 deletions(-)
 rename Documentation/ABI/testing/{sysfs-class-mic.txt => sysfs-class-mic} (100%)
 delete mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.html
 create mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.rst
 rename Documentation/RCU/Design/Expedited-Grace-Periods/{Expedited-Grace-Periods.html => Expedited-Grace-Periods.rst} (15%)
 delete mode 100644 Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Diagram.html
 rename Documentation/RCU/Design/Memory-Ordering/{Tree-RCU-Memory-Ordering.html => Tree-RCU-Memory-Ordering.rst} (10%)
 delete mode 100644 Documentation/RCU/Design/Requirements/Requirements.html
 create mode 100644 Documentation/RCU/Design/Requirements/Requirements.rst
 rename Documentation/{auxdisplay/cfag12864b => admin-guide/auxdisplay/cfag12864b.rst} (26%)
 create mode 100644 Documentation/admin-guide/auxdisplay/index.rst
 rename Documentation/{auxdisplay/ks0108 => admin-guide/auxdisplay/ks0108.rst} (32%)
 rename Documentation/{filesystems/cifs/AUTHORS => admin-guide/cifs/authors.rst} (60%)
 rename Documentation/{filesystems/cifs/CHANGES => admin-guide/cifs/changes.rst} (91%)
 create mode 100644 Documentation/admin-guide/cifs/index.rst
 rename Documentation/{filesystems/cifs/cifs.txt => admin-guide/cifs/introduction.rst} (98%)
 rename Documentation/{filesystems/cifs/TODO => admin-guide/cifs/todo.rst} (58%)
 rename Documentation/{filesystems/cifs/README => admin-guide/cifs/usage.rst} (72%)
 rename Documentation/{filesystems => admin-guide}/cifs/winucase_convert.pl (100%)
 rename Documentation/{wimax/README.i2400m => admin-guide/wimax/i2400m.rst} (69%)
 create mode 100644 Documentation/admin-guide/wimax/index.rst
 rename Documentation/{wimax/README.wimax => admin-guide/wimax/wimax.rst} (74%)
 rename Documentation/{packing.txt => core-api/packing.rst} (61%)
 rename Documentation/devicetree/{writing-schema.md => writing-schema.rst} (48%)
 rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%)
 rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%)
 rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%)
 rename Documentation/{ => driver-api}/thermal/index.rst (86%)
 rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%)
 rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%)
 rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%)
 rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%)
 rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%)
 rename Documentation/filesystems/{directory-locking => directory-locking.rst} (86%)
 rename Documentation/filesystems/{Locking => locking.rst} (79%)
 rename Documentation/filesystems/nfs/{Exporting => exporting.rst} (91%)
 rename Documentation/filesystems/{porting => porting.rst} (49%)
 rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
 rename Documentation/hwmon/{pxe1610 => pxe1610.rst} (82%)
 rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
 rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
 rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
 rename Documentation/i2c/busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} (42%)
 rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
 rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
 rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
 rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
 rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
 rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
 rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (58%)
 rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
 rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
 rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (91%)
 rename Documentation/i2c/busses/{i2c-parport => i2c-parport.rst} (49%)
 rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
 rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
 rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
 rename Documentation/i2c/busses/{i2c-sis630 => i2c-sis630.rst} (37%)
 rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (74%)
 rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
 rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (54%)
 rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
 create mode 100644 Documentation/i2c/busses/index.rst
 rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
 rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
 rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
 rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
 rename Documentation/i2c/{functionality => functionality.rst} (91%)
 rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
 rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
 rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
 rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
 create mode 100644 Documentation/i2c/index.rst
 rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
 rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
 rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
 rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
 rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
 rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (82%)
 rename Documentation/i2c/{summary => summary.rst} (96%)
 rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
 rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (54%)
 rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)
 rename Documentation/isdn/{README.avmb1 => avmb1.rst} (50%)
 rename Documentation/isdn/{CREDITS => credits.rst} (96%)
 rename Documentation/isdn/{README.gigaset => gigaset.rst} (74%)
 rename Documentation/isdn/{README.hysdn => hysdn.rst} (80%)
 create mode 100644 Documentation/isdn/index.rst
 rename Documentation/isdn/{INTERFACE.CAPI => interface_capi.rst} (75%)
 rename Documentation/isdn/{README.mISDN => m_isdn.rst} (89%)
 rename Documentation/m68k/{README.buddha => buddha-driver.rst} (73%)
 rename Documentation/mips/{AU1xxx_IDE.README => au1xxx_ide.rst} (67%)
 create mode 100644 Documentation/mips/index.rst
 rename Documentation/networking/caif/{README => caif.rst} (70%)
 rename Documentation/networking/mac80211_hwsim/{README => mac80211_hwsim.rst} (81%)
 rename Documentation/nios2/{README => nios2.rst} (96%)
 create mode 100644 Documentation/openrisc/index.rst
 rename Documentation/openrisc/{README => openrisc_port.rst} (80%)
 rename Documentation/openrisc/{TODO => todo.rst} (78%)
 rename Documentation/parisc/{debugging => debugging.rst} (94%)
 create mode 100644 Documentation/parisc/index.rst
 rename Documentation/parisc/{registers => registers.rst} (70%)
 rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
 rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
 rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
 rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
 rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
 rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
 rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
 rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
 rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
 rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
 create mode 100644 Documentation/powerpc/index.rst
 rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
 rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
 rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
 rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
 rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
 rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
 rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
 rename Documentation/spi/{butterfly => butterfly.rst} (71%)
 create mode 100644 Documentation/spi/index.rst
 rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
 rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
 rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (92%)
 rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
 rename Documentation/spi/{spidev => spidev.rst} (90%)
 create mode 100644 Documentation/w1/index.rst
 rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
 rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
 create mode 100644 Documentation/w1/masters/index.rst
 rename Documentation/w1/masters/{mxc-w1 => mxc-w1.rst} (33%)
 rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
 rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
 create mode 100644 Documentation/w1/slaves/index.rst
 rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (96%)
 rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
 rename Documentation/w1/slaves/{w1_ds2423 => w1_ds2423.rst} (48%)
 rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
 rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
 rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
 rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
 rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
 rename Documentation/w1/{w1.netlink => w1-netlink.rst} (77%)

-- 
2.21.0



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

* [PATCH v2 00/26] ReST conversion of text files without .txt extension
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: Mauro Carvalho Chehab, linux-doc, linux-kernel, linux-pm,
	linux-arm-kernel, linux-samsung-soc, linux-pci, linuxppc-dev,
	linux-scsi, devicetree, linux-i2c, linux-hwmon, linux-spi,
	linux-iio, linux-rtc, netdev, linux-parisc, openrisc, devel,
	linux-cifs, samba-technical, devel, dmaengine, alsa-devel,
	linux-mips, linux-wireless, rcu

This series converts the text files under Documentation with doesn't end
neither .txt or .rst and are not part of ABI or features.

This series is at:
	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3

And it is based on yesterday's upstream tree.

After this series, we have ~320 files left to be converted to ReST.

v2:
  - Added 3 files submitted for v5.3 that weren't merged yet;
  - markdown patch broken into two, per Rob's request;
  - rebased on the top of upstream master branch

Mauro Carvalho Chehab (26):
  docs: power: add it to to the main documentation index
  docs: thermal: add it to the driver API
  docs: powerpc: convert docs to ReST and rename to *.rst
  docs: ubifs-authentication.md: convert to ReST
  docs: writing-schema.md: convert from markdown to ReST
  docs: i2c: convert to ReST and add to driver-api bookset
  docs: w1: convert to ReST and add to the kAPI group of docs
  spi: docs: convert to ReST and add it to the kABI bookset
  docs: ipmb: place it at driver-api and convert to ReST
  docs: packing: move it to core-api book and adjust markups
  docs: admin-guide: add auxdisplay files to it after conversion to ReST
  docs: README.buddha: convert to ReST and add to m68k book
  docs: parisc: convert to ReST and add to documentation body
  docs: openrisc: convert to ReST and add to documentation body
  docs: isdn: convert to ReST and add to kAPI bookset
  docs: fs: cifs: convert to ReST and add to admin-guide book
  docs: fs: convert docs without extension to ReST
  docs: fs: convert porting to ReST
  docs: index.rst: don't use genindex for pdf output
  docs: wimax: convert to ReST and add to admin-guide
  docs: mips: add to the documentation body as ReST
  docs: hwmon: pxe1610: convert to ReST format and add to the index
  docs: nios2: add it to the main Documentation body
  docs: net: convert two README files to ReST format
  docs: rcu: convert some articles from html to ReST
  docs: ABI: remove extension from sysfs-class-mic.txt

 Documentation/ABI/stable/sysfs-bus-w1         |    2 +-
 .../ABI/stable/sysfs-driver-w1_ds28e04        |    4 +-
 .../ABI/stable/sysfs-driver-w1_ds28ea00       |    2 +-
 .../{sysfs-class-mic.txt => sysfs-class-mic}  |    0
 Documentation/PCI/pci-error-recovery.rst      |    2 +-
 .../Data-Structures/Data-Structures.html      | 1391 -------
 .../Data-Structures/Data-Structures.rst       | 1163 ++++++
 ...riods.html => Expedited-Grace-Periods.rst} |  949 ++---
 .../Memory-Ordering/Tree-RCU-Diagram.html     |    9 -
 ...ring.html => Tree-RCU-Memory-Ordering.rst} | 1181 +++---
 .../RCU/Design/Requirements/Requirements.html | 3330 -----------------
 .../RCU/Design/Requirements/Requirements.rst  | 2662 +++++++++++++
 Documentation/RCU/index.rst                   |    5 +
 Documentation/RCU/whatisRCU.txt               |    4 +-
 .../auxdisplay/cfag12864b.rst}                |  115 +-
 .../admin-guide/auxdisplay/index.rst          |   16 +
 .../auxdisplay/ks0108.rst}                    |   53 +-
 .../AUTHORS => admin-guide/cifs/authors.rst}  |   64 +-
 .../CHANGES => admin-guide/cifs/changes.rst}  |    4 +
 Documentation/admin-guide/cifs/index.rst      |   21 +
 .../cifs/introduction.rst}                    |    8 +
 .../cifs/TODO => admin-guide/cifs/todo.rst}   |   87 +-
 .../README => admin-guide/cifs/usage.rst}     |  560 +--
 .../cifs/winucase_convert.pl                  |    0
 Documentation/admin-guide/index.rst           |    3 +
 .../wimax/i2400m.rst}                         |  145 +-
 Documentation/admin-guide/wimax/index.rst     |   19 +
 .../wimax/wimax.rst}                          |   36 +-
 Documentation/core-api/index.rst              |    3 +-
 .../{packing.txt => core-api/packing.rst}     |   81 +-
 .../devicetree/bindings/i2c/i2c-mux-gpmux.txt |    2 +-
 .../{writing-schema.md => writing-schema.rst} |  137 +-
 Documentation/driver-api/dmaengine/index.rst  |    2 +-
 Documentation/driver-api/index.rst            |    2 +
 Documentation/driver-api/ipmb.rst             |    2 +-
 Documentation/driver-api/soundwire/index.rst  |    2 +-
 .../thermal/cpu-cooling-api.rst               |    0
 .../thermal/exynos_thermal.rst                |    0
 .../thermal/exynos_thermal_emulation.rst      |    0
 .../{ => driver-api}/thermal/index.rst        |    2 +-
 .../thermal/intel_powerclamp.rst              |    0
 .../thermal/nouveau_thermal.rst               |    0
 .../thermal/power_allocator.rst               |    0
 .../{ => driver-api}/thermal/sysfs-api.rst    |   12 +-
 .../thermal/x86_pkg_temperature_thermal.rst   |    2 +-
 ...irectory-locking => directory-locking.rst} |   40 +-
 Documentation/filesystems/index.rst           |    4 +
 .../filesystems/{Locking => locking.rst}      |  257 +-
 .../nfs/{Exporting => exporting.rst}          |   31 +-
 .../filesystems/{porting => porting.rst}      |  824 ++--
 ...entication.md => ubifs-authentication.rst} |   70 +-
 Documentation/filesystems/vfs.rst             |    2 +-
 Documentation/hwmon/adm1021.rst               |    2 +-
 Documentation/hwmon/adm1275.rst               |    2 +-
 Documentation/hwmon/hih6130.rst               |    2 +-
 Documentation/hwmon/ibm-cffps.rst             |    2 +-
 Documentation/hwmon/index.rst                 |    1 +
 Documentation/hwmon/lm25066.rst               |    2 +-
 Documentation/hwmon/max16064.rst              |    2 +-
 Documentation/hwmon/max16065.rst              |    2 +-
 Documentation/hwmon/max20751.rst              |    2 +-
 Documentation/hwmon/max34440.rst              |    2 +-
 Documentation/hwmon/max6650.rst               |    2 +-
 Documentation/hwmon/max8688.rst               |    2 +-
 Documentation/hwmon/menf21bmc.rst             |    2 +-
 Documentation/hwmon/pcf8591.rst               |    2 +-
 Documentation/hwmon/{pxe1610 => pxe1610.rst}  |   33 +-
 Documentation/hwmon/sht3x.rst                 |    2 +-
 Documentation/hwmon/shtc1.rst                 |    2 +-
 Documentation/hwmon/tmp103.rst                |    2 +-
 Documentation/hwmon/tps40422.rst              |    2 +-
 Documentation/hwmon/ucd9000.rst               |    2 +-
 Documentation/hwmon/ucd9200.rst               |    2 +-
 Documentation/hwmon/via686a.rst               |    2 +-
 Documentation/hwmon/zl6100.rst                |    2 +-
 .../busses/{i2c-ali1535 => i2c-ali1535.rst}   |   13 +-
 .../busses/{i2c-ali1563 => i2c-ali1563.rst}   |    3 +
 .../busses/{i2c-ali15x3 => i2c-ali15x3.rst}   |   64 +-
 .../busses/{i2c-amd-mp2 => i2c-amd-mp2.rst}   |   14 +-
 .../i2c/busses/{i2c-amd756 => i2c-amd756.rst} |    8 +-
 .../busses/{i2c-amd8111 => i2c-amd8111.rst}   |   14 +-
 .../{i2c-diolan-u2c => i2c-diolan-u2c.rst}    |    3 +
 .../i2c/busses/{i2c-i801 => i2c-i801.rst}     |   33 +-
 .../i2c/busses/{i2c-ismt => i2c-ismt.rst}     |   20 +-
 .../busses/{i2c-mlxcpld => i2c-mlxcpld.rst}   |    6 +
 .../busses/{i2c-nforce2 => i2c-nforce2.rst}   |   33 +-
 .../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst}    |    6 +-
 .../i2c/busses/{i2c-ocores => i2c-ocores.rst} |   22 +-
 ...2c-parport-light => i2c-parport-light.rst} |    8 +-
 .../busses/{i2c-parport => i2c-parport.rst}   |  164 +-
 .../busses/{i2c-pca-isa => i2c-pca-isa.rst}   |    9 +-
 .../i2c/busses/{i2c-piix4 => i2c-piix4.rst}   |   18 +-
 .../busses/{i2c-sis5595 => i2c-sis5595.rst}   |   19 +-
 .../i2c/busses/{i2c-sis630 => i2c-sis630.rst} |   39 +-
 .../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} |   31 +-
 .../busses/{i2c-taos-evm => i2c-taos-evm.rst} |    8 +-
 .../i2c/busses/{i2c-via => i2c-via.rst}       |   28 +-
 .../i2c/busses/{i2c-viapro => i2c-viapro.rst} |   12 +-
 Documentation/i2c/busses/index.rst            |   33 +
 .../i2c/busses/{scx200_acb => scx200_acb.rst} |    9 +-
 .../i2c/{dev-interface => dev-interface.rst}  |   94 +-
 ...-considerations => dma-considerations.rst} |    0
 .../i2c/{fault-codes => fault-codes.rst}      |    5 +-
 .../i2c/{functionality => functionality.rst}  |   22 +-
 ...ult-injection => gpio-fault-injection.rst} |   12 +-
 .../i2c/{i2c-protocol => i2c-protocol.rst}    |   28 +-
 Documentation/i2c/{i2c-stub => i2c-stub.rst}  |   20 +-
 .../i2c/{i2c-topology => i2c-topology.rst}    |   68 +-
 Documentation/i2c/index.rst                   |   37 +
 ...ting-devices => instantiating-devices.rst} |   45 +-
 .../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst}  |   26 +-
 ...e-parameters => old-module-parameters.rst} |   27 +-
 ...eprom-backend => slave-eeprom-backend.rst} |    4 +-
 .../{slave-interface => slave-interface.rst}  |   33 +-
 .../{smbus-protocol => smbus-protocol.rst}    |   86 +-
 Documentation/i2c/{summary => summary.rst}    |    6 +-
 ...en-bit-addresses => ten-bit-addresses.rst} |    5 +
 ...pgrading-clients => upgrading-clients.rst} |  204 +-
 .../{writing-clients => writing-clients.rst}  |   94 +-
 Documentation/index.rst                       |   10 +
 .../isdn/{README.avmb1 => avmb1.rst}          |  231 +-
 Documentation/isdn/{CREDITS => credits.rst}   |    7 +-
 .../isdn/{README.gigaset => gigaset.rst}      |  290 +-
 .../isdn/{README.hysdn => hysdn.rst}          |  125 +-
 Documentation/isdn/index.rst                  |   24 +
 .../{INTERFACE.CAPI => interface_capi.rst}    |  182 +-
 .../isdn/{README.mISDN => m_isdn.rst}         |    5 +-
 .../m68k/{README.buddha => buddha-driver.rst} |   95 +-
 Documentation/m68k/index.rst                  |    1 +
 .../{AU1xxx_IDE.README => au1xxx_ide.rst}     |   89 +-
 Documentation/mips/index.rst                  |   17 +
 .../networking/caif/{README => caif.rst}      |   88 +-
 .../networking/device_drivers/index.rst       |    2 +-
 Documentation/networking/index.rst            |    2 +-
 .../{README => mac80211_hwsim.rst}            |   28 +-
 Documentation/nios2/{README => nios2.rst}     |    1 +
 Documentation/openrisc/index.rst              |   18 +
 .../openrisc/{README => openrisc_port.rst}    |   25 +-
 Documentation/openrisc/{TODO => todo.rst}     |    9 +-
 .../parisc/{debugging => debugging.rst}       |    7 +
 Documentation/parisc/index.rst                |   18 +
 .../parisc/{registers => registers.rst}       |   59 +-
 Documentation/power/index.rst                 |    2 +-
 .../{bootwrapper.txt => bootwrapper.rst}      |   28 +-
 .../{cpu_families.txt => cpu_families.rst}    |   23 +-
 .../{cpu_features.txt => cpu_features.rst}    |    6 +-
 Documentation/powerpc/{cxl.txt => cxl.rst}    |   46 +-
 .../powerpc/{cxlflash.txt => cxlflash.rst}    |   10 +-
 .../{DAWR-POWER9.txt => dawr-power9.rst}      |   15 +-
 Documentation/powerpc/{dscr.txt => dscr.rst}  |   18 +-
 ...ecovery.txt => eeh-pci-error-recovery.rst} |  108 +-
 ...ed-dump.txt => firmware-assisted-dump.rst} |  117 +-
 Documentation/powerpc/{hvcs.txt => hvcs.rst}  |  108 +-
 Documentation/powerpc/index.rst               |   34 +
 Documentation/powerpc/isa-versions.rst        |   15 +-
 .../powerpc/{mpc52xx.txt => mpc52xx.rst}      |   12 +-
 ...nv.txt => pci_iov_resource_on_powernv.rst} |   15 +-
 .../powerpc/{pmu-ebb.txt => pmu-ebb.rst}      |    1 +
 .../powerpc/{ptrace.txt => ptrace.rst}        |  169 +-
 .../{qe_firmware.txt => qe_firmware.rst}      |   37 +-
 .../{syscall64-abi.txt => syscall64-abi.rst}  |   29 +-
 ...al_memory.txt => transactional_memory.rst} |   45 +-
 Documentation/sound/index.rst                 |    2 +-
 .../spi/{butterfly => butterfly.rst}          |   44 +-
 Documentation/spi/index.rst                   |   22 +
 Documentation/spi/{pxa2xx => pxa2xx.rst}      |   95 +-
 .../spi/{spi-lm70llp => spi-lm70llp.rst}      |   17 +-
 .../spi/{spi-sc18is602 => spi-sc18is602.rst}  |    5 +-
 .../spi/{spi-summary => spi-summary.rst}      |  105 +-
 Documentation/spi/{spidev => spidev.rst}      |   30 +-
 Documentation/w1/index.rst                    |   21 +
 .../w1/masters/{ds2482 => ds2482.rst}         |   16 +-
 .../w1/masters/{ds2490 => ds2490.rst}         |    6 +-
 Documentation/w1/masters/index.rst            |   14 +
 .../w1/masters/{mxc-w1 => mxc-w1.rst}         |   13 +-
 .../w1/masters/{omap-hdq => omap-hdq.rst}     |   12 +-
 .../w1/masters/{w1-gpio => w1-gpio.rst}       |   21 +-
 Documentation/w1/slaves/index.rst             |   16 +
 .../w1/slaves/{w1_ds2406 => w1_ds2406.rst}    |    4 +-
 .../w1/slaves/{w1_ds2413 => w1_ds2413.rst}    |    9 +
 .../w1/slaves/{w1_ds2423 => w1_ds2423.rst}    |   27 +-
 .../w1/slaves/{w1_ds2438 => w1_ds2438.rst}    |   10 +-
 .../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst}  |    5 +
 .../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst}  |   16 +-
 .../w1/slaves/{w1_therm => w1_therm.rst}      |   11 +-
 .../w1/{w1.generic => w1-generic.rst}         |   88 +-
 .../w1/{w1.netlink => w1-netlink.rst}         |   89 +-
 MAINTAINERS                                   |   68 +-
 arch/powerpc/kernel/exceptions-64s.S          |    2 +-
 drivers/auxdisplay/Kconfig                    |    2 +-
 drivers/hwmon/atxp1.c                         |    2 +-
 drivers/hwmon/smm665.c                        |    2 +-
 drivers/i2c/Kconfig                           |    4 +-
 drivers/i2c/busses/Kconfig                    |    2 +-
 drivers/i2c/busses/i2c-i801.c                 |    2 +-
 drivers/i2c/busses/i2c-taos-evm.c             |    2 +-
 drivers/i2c/i2c-core-base.c                   |    4 +-
 drivers/iio/dummy/iio_simple_dummy.c          |    4 +-
 drivers/rtc/rtc-ds1374.c                      |    2 +-
 drivers/soc/fsl/qe/qe.c                       |    2 +-
 drivers/spi/Kconfig                           |    2 +-
 drivers/spi/spi-butterfly.c                   |    2 +-
 drivers/spi/spi-lm70llp.c                     |    2 +-
 drivers/staging/isdn/hysdn/Kconfig            |    2 +-
 drivers/tty/hvc/hvcs.c                        |    2 +-
 fs/cifs/export.c                              |    2 +-
 fs/exportfs/expfs.c                           |    2 +-
 fs/isofs/export.c                             |    2 +-
 fs/orangefs/file.c                            |    2 +-
 fs/orangefs/orangefs-kernel.h                 |    2 +-
 include/linux/dcache.h                        |    2 +-
 include/linux/exportfs.h                      |    2 +-
 include/linux/i2c.h                           |    2 +-
 include/linux/platform_data/sc18is602.h       |    2 +-
 include/linux/thermal.h                       |    4 +-
 include/soc/fsl/qe/qe.h                       |    2 +-
 216 files changed, 9148 insertions(+), 8672 deletions(-)
 rename Documentation/ABI/testing/{sysfs-class-mic.txt => sysfs-class-mic} (100%)
 delete mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.html
 create mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.rst
 rename Documentation/RCU/Design/Expedited-Grace-Periods/{Expedited-Grace-Periods.html => Expedited-Grace-Periods.rst} (15%)
 delete mode 100644 Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Diagram.html
 rename Documentation/RCU/Design/Memory-Ordering/{Tree-RCU-Memory-Ordering.html => Tree-RCU-Memory-Ordering.rst} (10%)
 delete mode 100644 Documentation/RCU/Design/Requirements/Requirements.html
 create mode 100644 Documentation/RCU/Design/Requirements/Requirements.rst
 rename Documentation/{auxdisplay/cfag12864b => admin-guide/auxdisplay/cfag12864b.rst} (26%)
 create mode 100644 Documentation/admin-guide/auxdisplay/index.rst
 rename Documentation/{auxdisplay/ks0108 => admin-guide/auxdisplay/ks0108.rst} (32%)
 rename Documentation/{filesystems/cifs/AUTHORS => admin-guide/cifs/authors.rst} (60%)
 rename Documentation/{filesystems/cifs/CHANGES => admin-guide/cifs/changes.rst} (91%)
 create mode 100644 Documentation/admin-guide/cifs/index.rst
 rename Documentation/{filesystems/cifs/cifs.txt => admin-guide/cifs/introduction.rst} (98%)
 rename Documentation/{filesystems/cifs/TODO => admin-guide/cifs/todo.rst} (58%)
 rename Documentation/{filesystems/cifs/README => admin-guide/cifs/usage.rst} (72%)
 rename Documentation/{filesystems => admin-guide}/cifs/winucase_convert.pl (100%)
 rename Documentation/{wimax/README.i2400m => admin-guide/wimax/i2400m.rst} (69%)
 create mode 100644 Documentation/admin-guide/wimax/index.rst
 rename Documentation/{wimax/README.wimax => admin-guide/wimax/wimax.rst} (74%)
 rename Documentation/{packing.txt => core-api/packing.rst} (61%)
 rename Documentation/devicetree/{writing-schema.md => writing-schema.rst} (48%)
 rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%)
 rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%)
 rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%)
 rename Documentation/{ => driver-api}/thermal/index.rst (86%)
 rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%)
 rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%)
 rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%)
 rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%)
 rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%)
 rename Documentation/filesystems/{directory-locking => directory-locking.rst} (86%)
 rename Documentation/filesystems/{Locking => locking.rst} (79%)
 rename Documentation/filesystems/nfs/{Exporting => exporting.rst} (91%)
 rename Documentation/filesystems/{porting => porting.rst} (49%)
 rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
 rename Documentation/hwmon/{pxe1610 => pxe1610.rst} (82%)
 rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
 rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
 rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
 rename Documentation/i2c/busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} (42%)
 rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
 rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
 rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
 rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
 rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
 rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
 rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (58%)
 rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
 rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
 rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (91%)
 rename Documentation/i2c/busses/{i2c-parport => i2c-parport.rst} (49%)
 rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
 rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
 rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
 rename Documentation/i2c/busses/{i2c-sis630 => i2c-sis630.rst} (37%)
 rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (74%)
 rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
 rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (54%)
 rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
 create mode 100644 Documentation/i2c/busses/index.rst
 rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
 rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
 rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
 rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
 rename Documentation/i2c/{functionality => functionality.rst} (91%)
 rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
 rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
 rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
 rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
 create mode 100644 Documentation/i2c/index.rst
 rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
 rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
 rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
 rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
 rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
 rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (82%)
 rename Documentation/i2c/{summary => summary.rst} (96%)
 rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
 rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (54%)
 rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)
 rename Documentation/isdn/{README.avmb1 => avmb1.rst} (50%)
 rename Documentation/isdn/{CREDITS => credits.rst} (96%)
 rename Documentation/isdn/{README.gigaset => gigaset.rst} (74%)
 rename Documentation/isdn/{README.hysdn => hysdn.rst} (80%)
 create mode 100644 Documentation/isdn/index.rst
 rename Documentation/isdn/{INTERFACE.CAPI => interface_capi.rst} (75%)
 rename Documentation/isdn/{README.mISDN => m_isdn.rst} (89%)
 rename Documentation/m68k/{README.buddha => buddha-driver.rst} (73%)
 rename Documentation/mips/{AU1xxx_IDE.README => au1xxx_ide.rst} (67%)
 create mode 100644 Documentation/mips/index.rst
 rename Documentation/networking/caif/{README => caif.rst} (70%)
 rename Documentation/networking/mac80211_hwsim/{README => mac80211_hwsim.rst} (81%)
 rename Documentation/nios2/{README => nios2.rst} (96%)
 create mode 100644 Documentation/openrisc/index.rst
 rename Documentation/openrisc/{README => openrisc_port.rst} (80%)
 rename Documentation/openrisc/{TODO => todo.rst} (78%)
 rename Documentation/parisc/{debugging => debugging.rst} (94%)
 create mode 100644 Documentation/parisc/index.rst
 rename Documentation/parisc/{registers => registers.rst} (70%)
 rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
 rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
 rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
 rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
 rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
 rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
 rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
 rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
 rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
 rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
 create mode 100644 Documentation/powerpc/index.rst
 rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
 rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
 rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
 rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
 rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
 rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
 rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
 rename Documentation/spi/{butterfly => butterfly.rst} (71%)
 create mode 100644 Documentation/spi/index.rst
 rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
 rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
 rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (92%)
 rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
 rename Documentation/spi/{spidev => spidev.rst} (90%)
 create mode 100644 Documentation/w1/index.rst
 rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
 rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
 create mode 100644 Documentation/w1/masters/index.rst
 rename Documentation/w1/masters/{mxc-w1 => mxc-w1.rst} (33%)
 rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
 rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
 create mode 100644 Documentation/w1/slaves/index.rst
 rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (96%)
 rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
 rename Documentation/w1/slaves/{w1_ds2423 => w1_ds2423.rst} (48%)
 rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
 rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
 rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
 rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
 rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
 rename Documentation/w1/{w1.netlink => w1-netlink.rst} (77%)

-- 
2.21.0

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

* [PATCH v2 00/26] ReST conversion of text files without .txt extension
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: linux-wireless, alsa-devel, linux-doc, linux-iio, linux-pci,
	linux-mips, linux-i2c, Mauro Carvalho Chehab, devel, linux-cifs,
	linux-samsung-soc, linux-scsi, devel, devicetree, linux-pm, rcu,
	openrisc, linux-arm-kernel, linux-hwmon, linux-parisc, netdev,
	samba-technical, linux-kernel, linux-spi, dmaengine,
	linuxppc-dev, linux-rtc

This series converts the text files under Documentation with doesn't end
neither .txt or .rst and are not part of ABI or features.

This series is at:
	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3

And it is based on yesterday's upstream tree.

After this series, we have ~320 files left to be converted to ReST.

v2:
  - Added 3 files submitted for v5.3 that weren't merged yet;
  - markdown patch broken into two, per Rob's request;
  - rebased on the top of upstream master branch

Mauro Carvalho Chehab (26):
  docs: power: add it to to the main documentation index
  docs: thermal: add it to the driver API
  docs: powerpc: convert docs to ReST and rename to *.rst
  docs: ubifs-authentication.md: convert to ReST
  docs: writing-schema.md: convert from markdown to ReST
  docs: i2c: convert to ReST and add to driver-api bookset
  docs: w1: convert to ReST and add to the kAPI group of docs
  spi: docs: convert to ReST and add it to the kABI bookset
  docs: ipmb: place it at driver-api and convert to ReST
  docs: packing: move it to core-api book and adjust markups
  docs: admin-guide: add auxdisplay files to it after conversion to ReST
  docs: README.buddha: convert to ReST and add to m68k book
  docs: parisc: convert to ReST and add to documentation body
  docs: openrisc: convert to ReST and add to documentation body
  docs: isdn: convert to ReST and add to kAPI bookset
  docs: fs: cifs: convert to ReST and add to admin-guide book
  docs: fs: convert docs without extension to ReST
  docs: fs: convert porting to ReST
  docs: index.rst: don't use genindex for pdf output
  docs: wimax: convert to ReST and add to admin-guide
  docs: mips: add to the documentation body as ReST
  docs: hwmon: pxe1610: convert to ReST format and add to the index
  docs: nios2: add it to the main Documentation body
  docs: net: convert two README files to ReST format
  docs: rcu: convert some articles from html to ReST
  docs: ABI: remove extension from sysfs-class-mic.txt

 Documentation/ABI/stable/sysfs-bus-w1         |    2 +-
 .../ABI/stable/sysfs-driver-w1_ds28e04        |    4 +-
 .../ABI/stable/sysfs-driver-w1_ds28ea00       |    2 +-
 .../{sysfs-class-mic.txt => sysfs-class-mic}  |    0
 Documentation/PCI/pci-error-recovery.rst      |    2 +-
 .../Data-Structures/Data-Structures.html      | 1391 -------
 .../Data-Structures/Data-Structures.rst       | 1163 ++++++
 ...riods.html => Expedited-Grace-Periods.rst} |  949 ++---
 .../Memory-Ordering/Tree-RCU-Diagram.html     |    9 -
 ...ring.html => Tree-RCU-Memory-Ordering.rst} | 1181 +++---
 .../RCU/Design/Requirements/Requirements.html | 3330 -----------------
 .../RCU/Design/Requirements/Requirements.rst  | 2662 +++++++++++++
 Documentation/RCU/index.rst                   |    5 +
 Documentation/RCU/whatisRCU.txt               |    4 +-
 .../auxdisplay/cfag12864b.rst}                |  115 +-
 .../admin-guide/auxdisplay/index.rst          |   16 +
 .../auxdisplay/ks0108.rst}                    |   53 +-
 .../AUTHORS => admin-guide/cifs/authors.rst}  |   64 +-
 .../CHANGES => admin-guide/cifs/changes.rst}  |    4 +
 Documentation/admin-guide/cifs/index.rst      |   21 +
 .../cifs/introduction.rst}                    |    8 +
 .../cifs/TODO => admin-guide/cifs/todo.rst}   |   87 +-
 .../README => admin-guide/cifs/usage.rst}     |  560 +--
 .../cifs/winucase_convert.pl                  |    0
 Documentation/admin-guide/index.rst           |    3 +
 .../wimax/i2400m.rst}                         |  145 +-
 Documentation/admin-guide/wimax/index.rst     |   19 +
 .../wimax/wimax.rst}                          |   36 +-
 Documentation/core-api/index.rst              |    3 +-
 .../{packing.txt => core-api/packing.rst}     |   81 +-
 .../devicetree/bindings/i2c/i2c-mux-gpmux.txt |    2 +-
 .../{writing-schema.md => writing-schema.rst} |  137 +-
 Documentation/driver-api/dmaengine/index.rst  |    2 +-
 Documentation/driver-api/index.rst            |    2 +
 Documentation/driver-api/ipmb.rst             |    2 +-
 Documentation/driver-api/soundwire/index.rst  |    2 +-
 .../thermal/cpu-cooling-api.rst               |    0
 .../thermal/exynos_thermal.rst                |    0
 .../thermal/exynos_thermal_emulation.rst      |    0
 .../{ => driver-api}/thermal/index.rst        |    2 +-
 .../thermal/intel_powerclamp.rst              |    0
 .../thermal/nouveau_thermal.rst               |    0
 .../thermal/power_allocator.rst               |    0
 .../{ => driver-api}/thermal/sysfs-api.rst    |   12 +-
 .../thermal/x86_pkg_temperature_thermal.rst   |    2 +-
 ...irectory-locking => directory-locking.rst} |   40 +-
 Documentation/filesystems/index.rst           |    4 +
 .../filesystems/{Locking => locking.rst}      |  257 +-
 .../nfs/{Exporting => exporting.rst}          |   31 +-
 .../filesystems/{porting => porting.rst}      |  824 ++--
 ...entication.md => ubifs-authentication.rst} |   70 +-
 Documentation/filesystems/vfs.rst             |    2 +-
 Documentation/hwmon/adm1021.rst               |    2 +-
 Documentation/hwmon/adm1275.rst               |    2 +-
 Documentation/hwmon/hih6130.rst               |    2 +-
 Documentation/hwmon/ibm-cffps.rst             |    2 +-
 Documentation/hwmon/index.rst                 |    1 +
 Documentation/hwmon/lm25066.rst               |    2 +-
 Documentation/hwmon/max16064.rst              |    2 +-
 Documentation/hwmon/max16065.rst              |    2 +-
 Documentation/hwmon/max20751.rst              |    2 +-
 Documentation/hwmon/max34440.rst              |    2 +-
 Documentation/hwmon/max6650.rst               |    2 +-
 Documentation/hwmon/max8688.rst               |    2 +-
 Documentation/hwmon/menf21bmc.rst             |    2 +-
 Documentation/hwmon/pcf8591.rst               |    2 +-
 Documentation/hwmon/{pxe1610 => pxe1610.rst}  |   33 +-
 Documentation/hwmon/sht3x.rst                 |    2 +-
 Documentation/hwmon/shtc1.rst                 |    2 +-
 Documentation/hwmon/tmp103.rst                |    2 +-
 Documentation/hwmon/tps40422.rst              |    2 +-
 Documentation/hwmon/ucd9000.rst               |    2 +-
 Documentation/hwmon/ucd9200.rst               |    2 +-
 Documentation/hwmon/via686a.rst               |    2 +-
 Documentation/hwmon/zl6100.rst                |    2 +-
 .../busses/{i2c-ali1535 => i2c-ali1535.rst}   |   13 +-
 .../busses/{i2c-ali1563 => i2c-ali1563.rst}   |    3 +
 .../busses/{i2c-ali15x3 => i2c-ali15x3.rst}   |   64 +-
 .../busses/{i2c-amd-mp2 => i2c-amd-mp2.rst}   |   14 +-
 .../i2c/busses/{i2c-amd756 => i2c-amd756.rst} |    8 +-
 .../busses/{i2c-amd8111 => i2c-amd8111.rst}   |   14 +-
 .../{i2c-diolan-u2c => i2c-diolan-u2c.rst}    |    3 +
 .../i2c/busses/{i2c-i801 => i2c-i801.rst}     |   33 +-
 .../i2c/busses/{i2c-ismt => i2c-ismt.rst}     |   20 +-
 .../busses/{i2c-mlxcpld => i2c-mlxcpld.rst}   |    6 +
 .../busses/{i2c-nforce2 => i2c-nforce2.rst}   |   33 +-
 .../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst}    |    6 +-
 .../i2c/busses/{i2c-ocores => i2c-ocores.rst} |   22 +-
 ...2c-parport-light => i2c-parport-light.rst} |    8 +-
 .../busses/{i2c-parport => i2c-parport.rst}   |  164 +-
 .../busses/{i2c-pca-isa => i2c-pca-isa.rst}   |    9 +-
 .../i2c/busses/{i2c-piix4 => i2c-piix4.rst}   |   18 +-
 .../busses/{i2c-sis5595 => i2c-sis5595.rst}   |   19 +-
 .../i2c/busses/{i2c-sis630 => i2c-sis630.rst} |   39 +-
 .../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} |   31 +-
 .../busses/{i2c-taos-evm => i2c-taos-evm.rst} |    8 +-
 .../i2c/busses/{i2c-via => i2c-via.rst}       |   28 +-
 .../i2c/busses/{i2c-viapro => i2c-viapro.rst} |   12 +-
 Documentation/i2c/busses/index.rst            |   33 +
 .../i2c/busses/{scx200_acb => scx200_acb.rst} |    9 +-
 .../i2c/{dev-interface => dev-interface.rst}  |   94 +-
 ...-considerations => dma-considerations.rst} |    0
 .../i2c/{fault-codes => fault-codes.rst}      |    5 +-
 .../i2c/{functionality => functionality.rst}  |   22 +-
 ...ult-injection => gpio-fault-injection.rst} |   12 +-
 .../i2c/{i2c-protocol => i2c-protocol.rst}    |   28 +-
 Documentation/i2c/{i2c-stub => i2c-stub.rst}  |   20 +-
 .../i2c/{i2c-topology => i2c-topology.rst}    |   68 +-
 Documentation/i2c/index.rst                   |   37 +
 ...ting-devices => instantiating-devices.rst} |   45 +-
 .../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst}  |   26 +-
 ...e-parameters => old-module-parameters.rst} |   27 +-
 ...eprom-backend => slave-eeprom-backend.rst} |    4 +-
 .../{slave-interface => slave-interface.rst}  |   33 +-
 .../{smbus-protocol => smbus-protocol.rst}    |   86 +-
 Documentation/i2c/{summary => summary.rst}    |    6 +-
 ...en-bit-addresses => ten-bit-addresses.rst} |    5 +
 ...pgrading-clients => upgrading-clients.rst} |  204 +-
 .../{writing-clients => writing-clients.rst}  |   94 +-
 Documentation/index.rst                       |   10 +
 .../isdn/{README.avmb1 => avmb1.rst}          |  231 +-
 Documentation/isdn/{CREDITS => credits.rst}   |    7 +-
 .../isdn/{README.gigaset => gigaset.rst}      |  290 +-
 .../isdn/{README.hysdn => hysdn.rst}          |  125 +-
 Documentation/isdn/index.rst                  |   24 +
 .../{INTERFACE.CAPI => interface_capi.rst}    |  182 +-
 .../isdn/{README.mISDN => m_isdn.rst}         |    5 +-
 .../m68k/{README.buddha => buddha-driver.rst} |   95 +-
 Documentation/m68k/index.rst                  |    1 +
 .../{AU1xxx_IDE.README => au1xxx_ide.rst}     |   89 +-
 Documentation/mips/index.rst                  |   17 +
 .../networking/caif/{README => caif.rst}      |   88 +-
 .../networking/device_drivers/index.rst       |    2 +-
 Documentation/networking/index.rst            |    2 +-
 .../{README => mac80211_hwsim.rst}            |   28 +-
 Documentation/nios2/{README => nios2.rst}     |    1 +
 Documentation/openrisc/index.rst              |   18 +
 .../openrisc/{README => openrisc_port.rst}    |   25 +-
 Documentation/openrisc/{TODO => todo.rst}     |    9 +-
 .../parisc/{debugging => debugging.rst}       |    7 +
 Documentation/parisc/index.rst                |   18 +
 .../parisc/{registers => registers.rst}       |   59 +-
 Documentation/power/index.rst                 |    2 +-
 .../{bootwrapper.txt => bootwrapper.rst}      |   28 +-
 .../{cpu_families.txt => cpu_families.rst}    |   23 +-
 .../{cpu_features.txt => cpu_features.rst}    |    6 +-
 Documentation/powerpc/{cxl.txt => cxl.rst}    |   46 +-
 .../powerpc/{cxlflash.txt => cxlflash.rst}    |   10 +-
 .../{DAWR-POWER9.txt => dawr-power9.rst}      |   15 +-
 Documentation/powerpc/{dscr.txt => dscr.rst}  |   18 +-
 ...ecovery.txt => eeh-pci-error-recovery.rst} |  108 +-
 ...ed-dump.txt => firmware-assisted-dump.rst} |  117 +-
 Documentation/powerpc/{hvcs.txt => hvcs.rst}  |  108 +-
 Documentation/powerpc/index.rst               |   34 +
 Documentation/powerpc/isa-versions.rst        |   15 +-
 .../powerpc/{mpc52xx.txt => mpc52xx.rst}      |   12 +-
 ...nv.txt => pci_iov_resource_on_powernv.rst} |   15 +-
 .../powerpc/{pmu-ebb.txt => pmu-ebb.rst}      |    1 +
 .../powerpc/{ptrace.txt => ptrace.rst}        |  169 +-
 .../{qe_firmware.txt => qe_firmware.rst}      |   37 +-
 .../{syscall64-abi.txt => syscall64-abi.rst}  |   29 +-
 ...al_memory.txt => transactional_memory.rst} |   45 +-
 Documentation/sound/index.rst                 |    2 +-
 .../spi/{butterfly => butterfly.rst}          |   44 +-
 Documentation/spi/index.rst                   |   22 +
 Documentation/spi/{pxa2xx => pxa2xx.rst}      |   95 +-
 .../spi/{spi-lm70llp => spi-lm70llp.rst}      |   17 +-
 .../spi/{spi-sc18is602 => spi-sc18is602.rst}  |    5 +-
 .../spi/{spi-summary => spi-summary.rst}      |  105 +-
 Documentation/spi/{spidev => spidev.rst}      |   30 +-
 Documentation/w1/index.rst                    |   21 +
 .../w1/masters/{ds2482 => ds2482.rst}         |   16 +-
 .../w1/masters/{ds2490 => ds2490.rst}         |    6 +-
 Documentation/w1/masters/index.rst            |   14 +
 .../w1/masters/{mxc-w1 => mxc-w1.rst}         |   13 +-
 .../w1/masters/{omap-hdq => omap-hdq.rst}     |   12 +-
 .../w1/masters/{w1-gpio => w1-gpio.rst}       |   21 +-
 Documentation/w1/slaves/index.rst             |   16 +
 .../w1/slaves/{w1_ds2406 => w1_ds2406.rst}    |    4 +-
 .../w1/slaves/{w1_ds2413 => w1_ds2413.rst}    |    9 +
 .../w1/slaves/{w1_ds2423 => w1_ds2423.rst}    |   27 +-
 .../w1/slaves/{w1_ds2438 => w1_ds2438.rst}    |   10 +-
 .../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst}  |    5 +
 .../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst}  |   16 +-
 .../w1/slaves/{w1_therm => w1_therm.rst}      |   11 +-
 .../w1/{w1.generic => w1-generic.rst}         |   88 +-
 .../w1/{w1.netlink => w1-netlink.rst}         |   89 +-
 MAINTAINERS                                   |   68 +-
 arch/powerpc/kernel/exceptions-64s.S          |    2 +-
 drivers/auxdisplay/Kconfig                    |    2 +-
 drivers/hwmon/atxp1.c                         |    2 +-
 drivers/hwmon/smm665.c                        |    2 +-
 drivers/i2c/Kconfig                           |    4 +-
 drivers/i2c/busses/Kconfig                    |    2 +-
 drivers/i2c/busses/i2c-i801.c                 |    2 +-
 drivers/i2c/busses/i2c-taos-evm.c             |    2 +-
 drivers/i2c/i2c-core-base.c                   |    4 +-
 drivers/iio/dummy/iio_simple_dummy.c          |    4 +-
 drivers/rtc/rtc-ds1374.c                      |    2 +-
 drivers/soc/fsl/qe/qe.c                       |    2 +-
 drivers/spi/Kconfig                           |    2 +-
 drivers/spi/spi-butterfly.c                   |    2 +-
 drivers/spi/spi-lm70llp.c                     |    2 +-
 drivers/staging/isdn/hysdn/Kconfig            |    2 +-
 drivers/tty/hvc/hvcs.c                        |    2 +-
 fs/cifs/export.c                              |    2 +-
 fs/exportfs/expfs.c                           |    2 +-
 fs/isofs/export.c                             |    2 +-
 fs/orangefs/file.c                            |    2 +-
 fs/orangefs/orangefs-kernel.h                 |    2 +-
 include/linux/dcache.h                        |    2 +-
 include/linux/exportfs.h                      |    2 +-
 include/linux/i2c.h                           |    2 +-
 include/linux/platform_data/sc18is602.h       |    2 +-
 include/linux/thermal.h                       |    4 +-
 include/soc/fsl/qe/qe.h                       |    2 +-
 216 files changed, 9148 insertions(+), 8672 deletions(-)
 rename Documentation/ABI/testing/{sysfs-class-mic.txt => sysfs-class-mic} (100%)
 delete mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.html
 create mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.rst
 rename Documentation/RCU/Design/Expedited-Grace-Periods/{Expedited-Grace-Periods.html => Expedited-Grace-Periods.rst} (15%)
 delete mode 100644 Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Diagram.html
 rename Documentation/RCU/Design/Memory-Ordering/{Tree-RCU-Memory-Ordering.html => Tree-RCU-Memory-Ordering.rst} (10%)
 delete mode 100644 Documentation/RCU/Design/Requirements/Requirements.html
 create mode 100644 Documentation/RCU/Design/Requirements/Requirements.rst
 rename Documentation/{auxdisplay/cfag12864b => admin-guide/auxdisplay/cfag12864b.rst} (26%)
 create mode 100644 Documentation/admin-guide/auxdisplay/index.rst
 rename Documentation/{auxdisplay/ks0108 => admin-guide/auxdisplay/ks0108.rst} (32%)
 rename Documentation/{filesystems/cifs/AUTHORS => admin-guide/cifs/authors.rst} (60%)
 rename Documentation/{filesystems/cifs/CHANGES => admin-guide/cifs/changes.rst} (91%)
 create mode 100644 Documentation/admin-guide/cifs/index.rst
 rename Documentation/{filesystems/cifs/cifs.txt => admin-guide/cifs/introduction.rst} (98%)
 rename Documentation/{filesystems/cifs/TODO => admin-guide/cifs/todo.rst} (58%)
 rename Documentation/{filesystems/cifs/README => admin-guide/cifs/usage.rst} (72%)
 rename Documentation/{filesystems => admin-guide}/cifs/winucase_convert.pl (100%)
 rename Documentation/{wimax/README.i2400m => admin-guide/wimax/i2400m.rst} (69%)
 create mode 100644 Documentation/admin-guide/wimax/index.rst
 rename Documentation/{wimax/README.wimax => admin-guide/wimax/wimax.rst} (74%)
 rename Documentation/{packing.txt => core-api/packing.rst} (61%)
 rename Documentation/devicetree/{writing-schema.md => writing-schema.rst} (48%)
 rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%)
 rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%)
 rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%)
 rename Documentation/{ => driver-api}/thermal/index.rst (86%)
 rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%)
 rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%)
 rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%)
 rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%)
 rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%)
 rename Documentation/filesystems/{directory-locking => directory-locking.rst} (86%)
 rename Documentation/filesystems/{Locking => locking.rst} (79%)
 rename Documentation/filesystems/nfs/{Exporting => exporting.rst} (91%)
 rename Documentation/filesystems/{porting => porting.rst} (49%)
 rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
 rename Documentation/hwmon/{pxe1610 => pxe1610.rst} (82%)
 rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
 rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
 rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
 rename Documentation/i2c/busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} (42%)
 rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
 rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
 rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
 rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
 rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
 rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
 rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (58%)
 rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
 rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
 rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (91%)
 rename Documentation/i2c/busses/{i2c-parport => i2c-parport.rst} (49%)
 rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
 rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
 rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
 rename Documentation/i2c/busses/{i2c-sis630 => i2c-sis630.rst} (37%)
 rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (74%)
 rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
 rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (54%)
 rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
 create mode 100644 Documentation/i2c/busses/index.rst
 rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
 rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
 rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
 rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
 rename Documentation/i2c/{functionality => functionality.rst} (91%)
 rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
 rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
 rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
 rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
 create mode 100644 Documentation/i2c/index.rst
 rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
 rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
 rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
 rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
 rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
 rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (82%)
 rename Documentation/i2c/{summary => summary.rst} (96%)
 rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
 rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (54%)
 rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)
 rename Documentation/isdn/{README.avmb1 => avmb1.rst} (50%)
 rename Documentation/isdn/{CREDITS => credits.rst} (96%)
 rename Documentation/isdn/{README.gigaset => gigaset.rst} (74%)
 rename Documentation/isdn/{README.hysdn => hysdn.rst} (80%)
 create mode 100644 Documentation/isdn/index.rst
 rename Documentation/isdn/{INTERFACE.CAPI => interface_capi.rst} (75%)
 rename Documentation/isdn/{README.mISDN => m_isdn.rst} (89%)
 rename Documentation/m68k/{README.buddha => buddha-driver.rst} (73%)
 rename Documentation/mips/{AU1xxx_IDE.README => au1xxx_ide.rst} (67%)
 create mode 100644 Documentation/mips/index.rst
 rename Documentation/networking/caif/{README => caif.rst} (70%)
 rename Documentation/networking/mac80211_hwsim/{README => mac80211_hwsim.rst} (81%)
 rename Documentation/nios2/{README => nios2.rst} (96%)
 create mode 100644 Documentation/openrisc/index.rst
 rename Documentation/openrisc/{README => openrisc_port.rst} (80%)
 rename Documentation/openrisc/{TODO => todo.rst} (78%)
 rename Documentation/parisc/{debugging => debugging.rst} (94%)
 create mode 100644 Documentation/parisc/index.rst
 rename Documentation/parisc/{registers => registers.rst} (70%)
 rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
 rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
 rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
 rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
 rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
 rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
 rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
 rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
 rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
 rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
 create mode 100644 Documentation/powerpc/index.rst
 rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
 rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
 rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
 rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
 rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
 rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
 rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
 rename Documentation/spi/{butterfly => butterfly.rst} (71%)
 create mode 100644 Documentation/spi/index.rst
 rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
 rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
 rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (92%)
 rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
 rename Documentation/spi/{spidev => spidev.rst} (90%)
 create mode 100644 Documentation/w1/index.rst
 rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
 rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
 create mode 100644 Documentation/w1/masters/index.rst
 rename Documentation/w1/masters/{mxc-w1 => mxc-w1.rst} (33%)
 rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
 rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
 create mode 100644 Documentation/w1/slaves/index.rst
 rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (96%)
 rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
 rename Documentation/w1/slaves/{w1_ds2423 => w1_ds2423.rst} (48%)
 rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
 rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
 rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
 rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
 rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
 rename Documentation/w1/{w1.netlink => w1-netlink.rst} (77%)

-- 
2.21.0



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

* [PATCH v2 00/26] ReST conversion of text files without .txt extension
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: linux-wireless, alsa-devel, linux-doc, linux-iio, linux-pci,
	linux-mips, linux-i2c, Mauro Carvalho Chehab, devel, linux-cifs,
	linux-samsung-soc, linux-scsi, devel, devicetree, linux-pm, rcu,
	openrisc, linux-arm-kernel, linux-hwmon, linux-parisc, netdev,
	samba-technical, linux-kernel, linux-spi, dmaengine,
	linuxppc-dev, linux-rtc

This series converts the text files under Documentation with doesn't end
neither .txt or .rst and are not part of ABI or features.

This series is at:
	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3

And it is based on yesterday's upstream tree.

After this series, we have ~320 files left to be converted to ReST.

v2:
  - Added 3 files submitted for v5.3 that weren't merged yet;
  - markdown patch broken into two, per Rob's request;
  - rebased on the top of upstream master branch

Mauro Carvalho Chehab (26):
  docs: power: add it to to the main documentation index
  docs: thermal: add it to the driver API
  docs: powerpc: convert docs to ReST and rename to *.rst
  docs: ubifs-authentication.md: convert to ReST
  docs: writing-schema.md: convert from markdown to ReST
  docs: i2c: convert to ReST and add to driver-api bookset
  docs: w1: convert to ReST and add to the kAPI group of docs
  spi: docs: convert to ReST and add it to the kABI bookset
  docs: ipmb: place it at driver-api and convert to ReST
  docs: packing: move it to core-api book and adjust markups
  docs: admin-guide: add auxdisplay files to it after conversion to ReST
  docs: README.buddha: convert to ReST and add to m68k book
  docs: parisc: convert to ReST and add to documentation body
  docs: openrisc: convert to ReST and add to documentation body
  docs: isdn: convert to ReST and add to kAPI bookset
  docs: fs: cifs: convert to ReST and add to admin-guide book
  docs: fs: convert docs without extension to ReST
  docs: fs: convert porting to ReST
  docs: index.rst: don't use genindex for pdf output
  docs: wimax: convert to ReST and add to admin-guide
  docs: mips: add to the documentation body as ReST
  docs: hwmon: pxe1610: convert to ReST format and add to the index
  docs: nios2: add it to the main Documentation body
  docs: net: convert two README files to ReST format
  docs: rcu: convert some articles from html to ReST
  docs: ABI: remove extension from sysfs-class-mic.txt

 Documentation/ABI/stable/sysfs-bus-w1         |    2 +-
 .../ABI/stable/sysfs-driver-w1_ds28e04        |    4 +-
 .../ABI/stable/sysfs-driver-w1_ds28ea00       |    2 +-
 .../{sysfs-class-mic.txt => sysfs-class-mic}  |    0
 Documentation/PCI/pci-error-recovery.rst      |    2 +-
 .../Data-Structures/Data-Structures.html      | 1391 -------
 .../Data-Structures/Data-Structures.rst       | 1163 ++++++
 ...riods.html => Expedited-Grace-Periods.rst} |  949 ++---
 .../Memory-Ordering/Tree-RCU-Diagram.html     |    9 -
 ...ring.html => Tree-RCU-Memory-Ordering.rst} | 1181 +++---
 .../RCU/Design/Requirements/Requirements.html | 3330 -----------------
 .../RCU/Design/Requirements/Requirements.rst  | 2662 +++++++++++++
 Documentation/RCU/index.rst                   |    5 +
 Documentation/RCU/whatisRCU.txt               |    4 +-
 .../auxdisplay/cfag12864b.rst}                |  115 +-
 .../admin-guide/auxdisplay/index.rst          |   16 +
 .../auxdisplay/ks0108.rst}                    |   53 +-
 .../AUTHORS => admin-guide/cifs/authors.rst}  |   64 +-
 .../CHANGES => admin-guide/cifs/changes.rst}  |    4 +
 Documentation/admin-guide/cifs/index.rst      |   21 +
 .../cifs/introduction.rst}                    |    8 +
 .../cifs/TODO => admin-guide/cifs/todo.rst}   |   87 +-
 .../README => admin-guide/cifs/usage.rst}     |  560 +--
 .../cifs/winucase_convert.pl                  |    0
 Documentation/admin-guide/index.rst           |    3 +
 .../wimax/i2400m.rst}                         |  145 +-
 Documentation/admin-guide/wimax/index.rst     |   19 +
 .../wimax/wimax.rst}                          |   36 +-
 Documentation/core-api/index.rst              |    3 +-
 .../{packing.txt => core-api/packing.rst}     |   81 +-
 .../devicetree/bindings/i2c/i2c-mux-gpmux.txt |    2 +-
 .../{writing-schema.md => writing-schema.rst} |  137 +-
 Documentation/driver-api/dmaengine/index.rst  |    2 +-
 Documentation/driver-api/index.rst            |    2 +
 Documentation/driver-api/ipmb.rst             |    2 +-
 Documentation/driver-api/soundwire/index.rst  |    2 +-
 .../thermal/cpu-cooling-api.rst               |    0
 .../thermal/exynos_thermal.rst                |    0
 .../thermal/exynos_thermal_emulation.rst      |    0
 .../{ => driver-api}/thermal/index.rst        |    2 +-
 .../thermal/intel_powerclamp.rst              |    0
 .../thermal/nouveau_thermal.rst               |    0
 .../thermal/power_allocator.rst               |    0
 .../{ => driver-api}/thermal/sysfs-api.rst    |   12 +-
 .../thermal/x86_pkg_temperature_thermal.rst   |    2 +-
 ...irectory-locking => directory-locking.rst} |   40 +-
 Documentation/filesystems/index.rst           |    4 +
 .../filesystems/{Locking => locking.rst}      |  257 +-
 .../nfs/{Exporting => exporting.rst}          |   31 +-
 .../filesystems/{porting => porting.rst}      |  824 ++--
 ...entication.md => ubifs-authentication.rst} |   70 +-
 Documentation/filesystems/vfs.rst             |    2 +-
 Documentation/hwmon/adm1021.rst               |    2 +-
 Documentation/hwmon/adm1275.rst               |    2 +-
 Documentation/hwmon/hih6130.rst               |    2 +-
 Documentation/hwmon/ibm-cffps.rst             |    2 +-
 Documentation/hwmon/index.rst                 |    1 +
 Documentation/hwmon/lm25066.rst               |    2 +-
 Documentation/hwmon/max16064.rst              |    2 +-
 Documentation/hwmon/max16065.rst              |    2 +-
 Documentation/hwmon/max20751.rst              |    2 +-
 Documentation/hwmon/max34440.rst              |    2 +-
 Documentation/hwmon/max6650.rst               |    2 +-
 Documentation/hwmon/max8688.rst               |    2 +-
 Documentation/hwmon/menf21bmc.rst             |    2 +-
 Documentation/hwmon/pcf8591.rst               |    2 +-
 Documentation/hwmon/{pxe1610 => pxe1610.rst}  |   33 +-
 Documentation/hwmon/sht3x.rst                 |    2 +-
 Documentation/hwmon/shtc1.rst                 |    2 +-
 Documentation/hwmon/tmp103.rst                |    2 +-
 Documentation/hwmon/tps40422.rst              |    2 +-
 Documentation/hwmon/ucd9000.rst               |    2 +-
 Documentation/hwmon/ucd9200.rst               |    2 +-
 Documentation/hwmon/via686a.rst               |    2 +-
 Documentation/hwmon/zl6100.rst                |    2 +-
 .../busses/{i2c-ali1535 => i2c-ali1535.rst}   |   13 +-
 .../busses/{i2c-ali1563 => i2c-ali1563.rst}   |    3 +
 .../busses/{i2c-ali15x3 => i2c-ali15x3.rst}   |   64 +-
 .../busses/{i2c-amd-mp2 => i2c-amd-mp2.rst}   |   14 +-
 .../i2c/busses/{i2c-amd756 => i2c-amd756.rst} |    8 +-
 .../busses/{i2c-amd8111 => i2c-amd8111.rst}   |   14 +-
 .../{i2c-diolan-u2c => i2c-diolan-u2c.rst}    |    3 +
 .../i2c/busses/{i2c-i801 => i2c-i801.rst}     |   33 +-
 .../i2c/busses/{i2c-ismt => i2c-ismt.rst}     |   20 +-
 .../busses/{i2c-mlxcpld => i2c-mlxcpld.rst}   |    6 +
 .../busses/{i2c-nforce2 => i2c-nforce2.rst}   |   33 +-
 .../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst}    |    6 +-
 .../i2c/busses/{i2c-ocores => i2c-ocores.rst} |   22 +-
 ...2c-parport-light => i2c-parport-light.rst} |    8 +-
 .../busses/{i2c-parport => i2c-parport.rst}   |  164 +-
 .../busses/{i2c-pca-isa => i2c-pca-isa.rst}   |    9 +-
 .../i2c/busses/{i2c-piix4 => i2c-piix4.rst}   |   18 +-
 .../busses/{i2c-sis5595 => i2c-sis5595.rst}   |   19 +-
 .../i2c/busses/{i2c-sis630 => i2c-sis630.rst} |   39 +-
 .../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} |   31 +-
 .../busses/{i2c-taos-evm => i2c-taos-evm.rst} |    8 +-
 .../i2c/busses/{i2c-via => i2c-via.rst}       |   28 +-
 .../i2c/busses/{i2c-viapro => i2c-viapro.rst} |   12 +-
 Documentation/i2c/busses/index.rst            |   33 +
 .../i2c/busses/{scx200_acb => scx200_acb.rst} |    9 +-
 .../i2c/{dev-interface => dev-interface.rst}  |   94 +-
 ...-considerations => dma-considerations.rst} |    0
 .../i2c/{fault-codes => fault-codes.rst}      |    5 +-
 .../i2c/{functionality => functionality.rst}  |   22 +-
 ...ult-injection => gpio-fault-injection.rst} |   12 +-
 .../i2c/{i2c-protocol => i2c-protocol.rst}    |   28 +-
 Documentation/i2c/{i2c-stub => i2c-stub.rst}  |   20 +-
 .../i2c/{i2c-topology => i2c-topology.rst}    |   68 +-
 Documentation/i2c/index.rst                   |   37 +
 ...ting-devices => instantiating-devices.rst} |   45 +-
 .../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst}  |   26 +-
 ...e-parameters => old-module-parameters.rst} |   27 +-
 ...eprom-backend => slave-eeprom-backend.rst} |    4 +-
 .../{slave-interface => slave-interface.rst}  |   33 +-
 .../{smbus-protocol => smbus-protocol.rst}    |   86 +-
 Documentation/i2c/{summary => summary.rst}    |    6 +-
 ...en-bit-addresses => ten-bit-addresses.rst} |    5 +
 ...pgrading-clients => upgrading-clients.rst} |  204 +-
 .../{writing-clients => writing-clients.rst}  |   94 +-
 Documentation/index.rst                       |   10 +
 .../isdn/{README.avmb1 => avmb1.rst}          |  231 +-
 Documentation/isdn/{CREDITS => credits.rst}   |    7 +-
 .../isdn/{README.gigaset => gigaset.rst}      |  290 +-
 .../isdn/{README.hysdn => hysdn.rst}          |  125 +-
 Documentation/isdn/index.rst                  |   24 +
 .../{INTERFACE.CAPI => interface_capi.rst}    |  182 +-
 .../isdn/{README.mISDN => m_isdn.rst}         |    5 +-
 .../m68k/{README.buddha => buddha-driver.rst} |   95 +-
 Documentation/m68k/index.rst                  |    1 +
 .../{AU1xxx_IDE.README => au1xxx_ide.rst}     |   89 +-
 Documentation/mips/index.rst                  |   17 +
 .../networking/caif/{README => caif.rst}      |   88 +-
 .../networking/device_drivers/index.rst       |    2 +-
 Documentation/networking/index.rst            |    2 +-
 .../{README => mac80211_hwsim.rst}            |   28 +-
 Documentation/nios2/{README => nios2.rst}     |    1 +
 Documentation/openrisc/index.rst              |   18 +
 .../openrisc/{README => openrisc_port.rst}    |   25 +-
 Documentation/openrisc/{TODO => todo.rst}     |    9 +-
 .../parisc/{debugging => debugging.rst}       |    7 +
 Documentation/parisc/index.rst                |   18 +
 .../parisc/{registers => registers.rst}       |   59 +-
 Documentation/power/index.rst                 |    2 +-
 .../{bootwrapper.txt => bootwrapper.rst}      |   28 +-
 .../{cpu_families.txt => cpu_families.rst}    |   23 +-
 .../{cpu_features.txt => cpu_features.rst}    |    6 +-
 Documentation/powerpc/{cxl.txt => cxl.rst}    |   46 +-
 .../powerpc/{cxlflash.txt => cxlflash.rst}    |   10 +-
 .../{DAWR-POWER9.txt => dawr-power9.rst}      |   15 +-
 Documentation/powerpc/{dscr.txt => dscr.rst}  |   18 +-
 ...ecovery.txt => eeh-pci-error-recovery.rst} |  108 +-
 ...ed-dump.txt => firmware-assisted-dump.rst} |  117 +-
 Documentation/powerpc/{hvcs.txt => hvcs.rst}  |  108 +-
 Documentation/powerpc/index.rst               |   34 +
 Documentation/powerpc/isa-versions.rst        |   15 +-
 .../powerpc/{mpc52xx.txt => mpc52xx.rst}      |   12 +-
 ...nv.txt => pci_iov_resource_on_powernv.rst} |   15 +-
 .../powerpc/{pmu-ebb.txt => pmu-ebb.rst}      |    1 +
 .../powerpc/{ptrace.txt => ptrace.rst}        |  169 +-
 .../{qe_firmware.txt => qe_firmware.rst}      |   37 +-
 .../{syscall64-abi.txt => syscall64-abi.rst}  |   29 +-
 ...al_memory.txt => transactional_memory.rst} |   45 +-
 Documentation/sound/index.rst                 |    2 +-
 .../spi/{butterfly => butterfly.rst}          |   44 +-
 Documentation/spi/index.rst                   |   22 +
 Documentation/spi/{pxa2xx => pxa2xx.rst}      |   95 +-
 .../spi/{spi-lm70llp => spi-lm70llp.rst}      |   17 +-
 .../spi/{spi-sc18is602 => spi-sc18is602.rst}  |    5 +-
 .../spi/{spi-summary => spi-summary.rst}      |  105 +-
 Documentation/spi/{spidev => spidev.rst}      |   30 +-
 Documentation/w1/index.rst                    |   21 +
 .../w1/masters/{ds2482 => ds2482.rst}         |   16 +-
 .../w1/masters/{ds2490 => ds2490.rst}         |    6 +-
 Documentation/w1/masters/index.rst            |   14 +
 .../w1/masters/{mxc-w1 => mxc-w1.rst}         |   13 +-
 .../w1/masters/{omap-hdq => omap-hdq.rst}     |   12 +-
 .../w1/masters/{w1-gpio => w1-gpio.rst}       |   21 +-
 Documentation/w1/slaves/index.rst             |   16 +
 .../w1/slaves/{w1_ds2406 => w1_ds2406.rst}    |    4 +-
 .../w1/slaves/{w1_ds2413 => w1_ds2413.rst}    |    9 +
 .../w1/slaves/{w1_ds2423 => w1_ds2423.rst}    |   27 +-
 .../w1/slaves/{w1_ds2438 => w1_ds2438.rst}    |   10 +-
 .../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst}  |    5 +
 .../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst}  |   16 +-
 .../w1/slaves/{w1_therm => w1_therm.rst}      |   11 +-
 .../w1/{w1.generic => w1-generic.rst}         |   88 +-
 .../w1/{w1.netlink => w1-netlink.rst}         |   89 +-
 MAINTAINERS                                   |   68 +-
 arch/powerpc/kernel/exceptions-64s.S          |    2 +-
 drivers/auxdisplay/Kconfig                    |    2 +-
 drivers/hwmon/atxp1.c                         |    2 +-
 drivers/hwmon/smm665.c                        |    2 +-
 drivers/i2c/Kconfig                           |    4 +-
 drivers/i2c/busses/Kconfig                    |    2 +-
 drivers/i2c/busses/i2c-i801.c                 |    2 +-
 drivers/i2c/busses/i2c-taos-evm.c             |    2 +-
 drivers/i2c/i2c-core-base.c                   |    4 +-
 drivers/iio/dummy/iio_simple_dummy.c          |    4 +-
 drivers/rtc/rtc-ds1374.c                      |    2 +-
 drivers/soc/fsl/qe/qe.c                       |    2 +-
 drivers/spi/Kconfig                           |    2 +-
 drivers/spi/spi-butterfly.c                   |    2 +-
 drivers/spi/spi-lm70llp.c                     |    2 +-
 drivers/staging/isdn/hysdn/Kconfig            |    2 +-
 drivers/tty/hvc/hvcs.c                        |    2 +-
 fs/cifs/export.c                              |    2 +-
 fs/exportfs/expfs.c                           |    2 +-
 fs/isofs/export.c                             |    2 +-
 fs/orangefs/file.c                            |    2 +-
 fs/orangefs/orangefs-kernel.h                 |    2 +-
 include/linux/dcache.h                        |    2 +-
 include/linux/exportfs.h                      |    2 +-
 include/linux/i2c.h                           |    2 +-
 include/linux/platform_data/sc18is602.h       |    2 +-
 include/linux/thermal.h                       |    4 +-
 include/soc/fsl/qe/qe.h                       |    2 +-
 216 files changed, 9148 insertions(+), 8672 deletions(-)
 rename Documentation/ABI/testing/{sysfs-class-mic.txt => sysfs-class-mic} (100%)
 delete mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.html
 create mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.rst
 rename Documentation/RCU/Design/Expedited-Grace-Periods/{Expedited-Grace-Periods.html => Expedited-Grace-Periods.rst} (15%)
 delete mode 100644 Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Diagram.html
 rename Documentation/RCU/Design/Memory-Ordering/{Tree-RCU-Memory-Ordering.html => Tree-RCU-Memory-Ordering.rst} (10%)
 delete mode 100644 Documentation/RCU/Design/Requirements/Requirements.html
 create mode 100644 Documentation/RCU/Design/Requirements/Requirements.rst
 rename Documentation/{auxdisplay/cfag12864b => admin-guide/auxdisplay/cfag12864b.rst} (26%)
 create mode 100644 Documentation/admin-guide/auxdisplay/index.rst
 rename Documentation/{auxdisplay/ks0108 => admin-guide/auxdisplay/ks0108.rst} (32%)
 rename Documentation/{filesystems/cifs/AUTHORS => admin-guide/cifs/authors.rst} (60%)
 rename Documentation/{filesystems/cifs/CHANGES => admin-guide/cifs/changes.rst} (91%)
 create mode 100644 Documentation/admin-guide/cifs/index.rst
 rename Documentation/{filesystems/cifs/cifs.txt => admin-guide/cifs/introduction.rst} (98%)
 rename Documentation/{filesystems/cifs/TODO => admin-guide/cifs/todo.rst} (58%)
 rename Documentation/{filesystems/cifs/README => admin-guide/cifs/usage.rst} (72%)
 rename Documentation/{filesystems => admin-guide}/cifs/winucase_convert.pl (100%)
 rename Documentation/{wimax/README.i2400m => admin-guide/wimax/i2400m.rst} (69%)
 create mode 100644 Documentation/admin-guide/wimax/index.rst
 rename Documentation/{wimax/README.wimax => admin-guide/wimax/wimax.rst} (74%)
 rename Documentation/{packing.txt => core-api/packing.rst} (61%)
 rename Documentation/devicetree/{writing-schema.md => writing-schema.rst} (48%)
 rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%)
 rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%)
 rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%)
 rename Documentation/{ => driver-api}/thermal/index.rst (86%)
 rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%)
 rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%)
 rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%)
 rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%)
 rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%)
 rename Documentation/filesystems/{directory-locking => directory-locking.rst} (86%)
 rename Documentation/filesystems/{Locking => locking.rst} (79%)
 rename Documentation/filesystems/nfs/{Exporting => exporting.rst} (91%)
 rename Documentation/filesystems/{porting => porting.rst} (49%)
 rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
 rename Documentation/hwmon/{pxe1610 => pxe1610.rst} (82%)
 rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
 rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
 rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
 rename Documentation/i2c/busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} (42%)
 rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
 rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
 rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
 rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
 rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
 rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
 rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (58%)
 rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
 rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
 rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (91%)
 rename Documentation/i2c/busses/{i2c-parport => i2c-parport.rst} (49%)
 rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
 rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
 rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
 rename Documentation/i2c/busses/{i2c-sis630 => i2c-sis630.rst} (37%)
 rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (74%)
 rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
 rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (54%)
 rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
 create mode 100644 Documentation/i2c/busses/index.rst
 rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
 rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
 rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
 rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
 rename Documentation/i2c/{functionality => functionality.rst} (91%)
 rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
 rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
 rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
 rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
 create mode 100644 Documentation/i2c/index.rst
 rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
 rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
 rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
 rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
 rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
 rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (82%)
 rename Documentation/i2c/{summary => summary.rst} (96%)
 rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
 rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (54%)
 rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)
 rename Documentation/isdn/{README.avmb1 => avmb1.rst} (50%)
 rename Documentation/isdn/{CREDITS => credits.rst} (96%)
 rename Documentation/isdn/{README.gigaset => gigaset.rst} (74%)
 rename Documentation/isdn/{README.hysdn => hysdn.rst} (80%)
 create mode 100644 Documentation/isdn/index.rst
 rename Documentation/isdn/{INTERFACE.CAPI => interface_capi.rst} (75%)
 rename Documentation/isdn/{README.mISDN => m_isdn.rst} (89%)
 rename Documentation/m68k/{README.buddha => buddha-driver.rst} (73%)
 rename Documentation/mips/{AU1xxx_IDE.README => au1xxx_ide.rst} (67%)
 create mode 100644 Documentation/mips/index.rst
 rename Documentation/networking/caif/{README => caif.rst} (70%)
 rename Documentation/networking/mac80211_hwsim/{README => mac80211_hwsim.rst} (81%)
 rename Documentation/nios2/{README => nios2.rst} (96%)
 create mode 100644 Documentation/openrisc/index.rst
 rename Documentation/openrisc/{README => openrisc_port.rst} (80%)
 rename Documentation/openrisc/{TODO => todo.rst} (78%)
 rename Documentation/parisc/{debugging => debugging.rst} (94%)
 create mode 100644 Documentation/parisc/index.rst
 rename Documentation/parisc/{registers => registers.rst} (70%)
 rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
 rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
 rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
 rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
 rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
 rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
 rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
 rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
 rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
 rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
 create mode 100644 Documentation/powerpc/index.rst
 rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
 rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
 rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
 rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
 rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
 rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
 rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
 rename Documentation/spi/{butterfly => butterfly.rst} (71%)
 create mode 100644 Documentation/spi/index.rst
 rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
 rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
 rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (92%)
 rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
 rename Documentation/spi/{spidev => spidev.rst} (90%)
 create mode 100644 Documentation/w1/index.rst
 rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
 rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
 create mode 100644 Documentation/w1/masters/index.rst
 rename Documentation/w1/masters/{mxc-w1 => mxc-w1.rst} (33%)
 rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
 rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
 create mode 100644 Documentation/w1/slaves/index.rst
 rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (96%)
 rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
 rename Documentation/w1/slaves/{w1_ds2423 => w1_ds2423.rst} (48%)
 rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
 rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
 rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
 rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
 rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
 rename Documentation/w1/{w1.netlink => w1-netlink.rst} (77%)

-- 
2.21.0



_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

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

* [OpenRISC] [PATCH v2 00/26] ReST conversion of text files without .txt extension
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  To: openrisc

This series converts the text files under Documentation with doesn't end
neither .txt or .rst and are not part of ABI or features.

This series is at:
	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3

And it is based on yesterday's upstream tree.

After this series, we have ~320 files left to be converted to ReST.

v2:
  - Added 3 files submitted for v5.3 that weren't merged yet;
  - markdown patch broken into two, per Rob's request;
  - rebased on the top of upstream master branch

Mauro Carvalho Chehab (26):
  docs: power: add it to to the main documentation index
  docs: thermal: add it to the driver API
  docs: powerpc: convert docs to ReST and rename to *.rst
  docs: ubifs-authentication.md: convert to ReST
  docs: writing-schema.md: convert from markdown to ReST
  docs: i2c: convert to ReST and add to driver-api bookset
  docs: w1: convert to ReST and add to the kAPI group of docs
  spi: docs: convert to ReST and add it to the kABI bookset
  docs: ipmb: place it at driver-api and convert to ReST
  docs: packing: move it to core-api book and adjust markups
  docs: admin-guide: add auxdisplay files to it after conversion to ReST
  docs: README.buddha: convert to ReST and add to m68k book
  docs: parisc: convert to ReST and add to documentation body
  docs: openrisc: convert to ReST and add to documentation body
  docs: isdn: convert to ReST and add to kAPI bookset
  docs: fs: cifs: convert to ReST and add to admin-guide book
  docs: fs: convert docs without extension to ReST
  docs: fs: convert porting to ReST
  docs: index.rst: don't use genindex for pdf output
  docs: wimax: convert to ReST and add to admin-guide
  docs: mips: add to the documentation body as ReST
  docs: hwmon: pxe1610: convert to ReST format and add to the index
  docs: nios2: add it to the main Documentation body
  docs: net: convert two README files to ReST format
  docs: rcu: convert some articles from html to ReST
  docs: ABI: remove extension from sysfs-class-mic.txt

 Documentation/ABI/stable/sysfs-bus-w1         |    2 +-
 .../ABI/stable/sysfs-driver-w1_ds28e04        |    4 +-
 .../ABI/stable/sysfs-driver-w1_ds28ea00       |    2 +-
 .../{sysfs-class-mic.txt => sysfs-class-mic}  |    0
 Documentation/PCI/pci-error-recovery.rst      |    2 +-
 .../Data-Structures/Data-Structures.html      | 1391 -------
 .../Data-Structures/Data-Structures.rst       | 1163 ++++++
 ...riods.html => Expedited-Grace-Periods.rst} |  949 ++---
 .../Memory-Ordering/Tree-RCU-Diagram.html     |    9 -
 ...ring.html => Tree-RCU-Memory-Ordering.rst} | 1181 +++---
 .../RCU/Design/Requirements/Requirements.html | 3330 -----------------
 .../RCU/Design/Requirements/Requirements.rst  | 2662 +++++++++++++
 Documentation/RCU/index.rst                   |    5 +
 Documentation/RCU/whatisRCU.txt               |    4 +-
 .../auxdisplay/cfag12864b.rst}                |  115 +-
 .../admin-guide/auxdisplay/index.rst          |   16 +
 .../auxdisplay/ks0108.rst}                    |   53 +-
 .../AUTHORS => admin-guide/cifs/authors.rst}  |   64 +-
 .../CHANGES => admin-guide/cifs/changes.rst}  |    4 +
 Documentation/admin-guide/cifs/index.rst      |   21 +
 .../cifs/introduction.rst}                    |    8 +
 .../cifs/TODO => admin-guide/cifs/todo.rst}   |   87 +-
 .../README => admin-guide/cifs/usage.rst}     |  560 +--
 .../cifs/winucase_convert.pl                  |    0
 Documentation/admin-guide/index.rst           |    3 +
 .../wimax/i2400m.rst}                         |  145 +-
 Documentation/admin-guide/wimax/index.rst     |   19 +
 .../wimax/wimax.rst}                          |   36 +-
 Documentation/core-api/index.rst              |    3 +-
 .../{packing.txt => core-api/packing.rst}     |   81 +-
 .../devicetree/bindings/i2c/i2c-mux-gpmux.txt |    2 +-
 .../{writing-schema.md => writing-schema.rst} |  137 +-
 Documentation/driver-api/dmaengine/index.rst  |    2 +-
 Documentation/driver-api/index.rst            |    2 +
 Documentation/driver-api/ipmb.rst             |    2 +-
 Documentation/driver-api/soundwire/index.rst  |    2 +-
 .../thermal/cpu-cooling-api.rst               |    0
 .../thermal/exynos_thermal.rst                |    0
 .../thermal/exynos_thermal_emulation.rst      |    0
 .../{ => driver-api}/thermal/index.rst        |    2 +-
 .../thermal/intel_powerclamp.rst              |    0
 .../thermal/nouveau_thermal.rst               |    0
 .../thermal/power_allocator.rst               |    0
 .../{ => driver-api}/thermal/sysfs-api.rst    |   12 +-
 .../thermal/x86_pkg_temperature_thermal.rst   |    2 +-
 ...irectory-locking => directory-locking.rst} |   40 +-
 Documentation/filesystems/index.rst           |    4 +
 .../filesystems/{Locking => locking.rst}      |  257 +-
 .../nfs/{Exporting => exporting.rst}          |   31 +-
 .../filesystems/{porting => porting.rst}      |  824 ++--
 ...entication.md => ubifs-authentication.rst} |   70 +-
 Documentation/filesystems/vfs.rst             |    2 +-
 Documentation/hwmon/adm1021.rst               |    2 +-
 Documentation/hwmon/adm1275.rst               |    2 +-
 Documentation/hwmon/hih6130.rst               |    2 +-
 Documentation/hwmon/ibm-cffps.rst             |    2 +-
 Documentation/hwmon/index.rst                 |    1 +
 Documentation/hwmon/lm25066.rst               |    2 +-
 Documentation/hwmon/max16064.rst              |    2 +-
 Documentation/hwmon/max16065.rst              |    2 +-
 Documentation/hwmon/max20751.rst              |    2 +-
 Documentation/hwmon/max34440.rst              |    2 +-
 Documentation/hwmon/max6650.rst               |    2 +-
 Documentation/hwmon/max8688.rst               |    2 +-
 Documentation/hwmon/menf21bmc.rst             |    2 +-
 Documentation/hwmon/pcf8591.rst               |    2 +-
 Documentation/hwmon/{pxe1610 => pxe1610.rst}  |   33 +-
 Documentation/hwmon/sht3x.rst                 |    2 +-
 Documentation/hwmon/shtc1.rst                 |    2 +-
 Documentation/hwmon/tmp103.rst                |    2 +-
 Documentation/hwmon/tps40422.rst              |    2 +-
 Documentation/hwmon/ucd9000.rst               |    2 +-
 Documentation/hwmon/ucd9200.rst               |    2 +-
 Documentation/hwmon/via686a.rst               |    2 +-
 Documentation/hwmon/zl6100.rst                |    2 +-
 .../busses/{i2c-ali1535 => i2c-ali1535.rst}   |   13 +-
 .../busses/{i2c-ali1563 => i2c-ali1563.rst}   |    3 +
 .../busses/{i2c-ali15x3 => i2c-ali15x3.rst}   |   64 +-
 .../busses/{i2c-amd-mp2 => i2c-amd-mp2.rst}   |   14 +-
 .../i2c/busses/{i2c-amd756 => i2c-amd756.rst} |    8 +-
 .../busses/{i2c-amd8111 => i2c-amd8111.rst}   |   14 +-
 .../{i2c-diolan-u2c => i2c-diolan-u2c.rst}    |    3 +
 .../i2c/busses/{i2c-i801 => i2c-i801.rst}     |   33 +-
 .../i2c/busses/{i2c-ismt => i2c-ismt.rst}     |   20 +-
 .../busses/{i2c-mlxcpld => i2c-mlxcpld.rst}   |    6 +
 .../busses/{i2c-nforce2 => i2c-nforce2.rst}   |   33 +-
 .../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst}    |    6 +-
 .../i2c/busses/{i2c-ocores => i2c-ocores.rst} |   22 +-
 ...2c-parport-light => i2c-parport-light.rst} |    8 +-
 .../busses/{i2c-parport => i2c-parport.rst}   |  164 +-
 .../busses/{i2c-pca-isa => i2c-pca-isa.rst}   |    9 +-
 .../i2c/busses/{i2c-piix4 => i2c-piix4.rst}   |   18 +-
 .../busses/{i2c-sis5595 => i2c-sis5595.rst}   |   19 +-
 .../i2c/busses/{i2c-sis630 => i2c-sis630.rst} |   39 +-
 .../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} |   31 +-
 .../busses/{i2c-taos-evm => i2c-taos-evm.rst} |    8 +-
 .../i2c/busses/{i2c-via => i2c-via.rst}       |   28 +-
 .../i2c/busses/{i2c-viapro => i2c-viapro.rst} |   12 +-
 Documentation/i2c/busses/index.rst            |   33 +
 .../i2c/busses/{scx200_acb => scx200_acb.rst} |    9 +-
 .../i2c/{dev-interface => dev-interface.rst}  |   94 +-
 ...-considerations => dma-considerations.rst} |    0
 .../i2c/{fault-codes => fault-codes.rst}      |    5 +-
 .../i2c/{functionality => functionality.rst}  |   22 +-
 ...ult-injection => gpio-fault-injection.rst} |   12 +-
 .../i2c/{i2c-protocol => i2c-protocol.rst}    |   28 +-
 Documentation/i2c/{i2c-stub => i2c-stub.rst}  |   20 +-
 .../i2c/{i2c-topology => i2c-topology.rst}    |   68 +-
 Documentation/i2c/index.rst                   |   37 +
 ...ting-devices => instantiating-devices.rst} |   45 +-
 .../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst}  |   26 +-
 ...e-parameters => old-module-parameters.rst} |   27 +-
 ...eprom-backend => slave-eeprom-backend.rst} |    4 +-
 .../{slave-interface => slave-interface.rst}  |   33 +-
 .../{smbus-protocol => smbus-protocol.rst}    |   86 +-
 Documentation/i2c/{summary => summary.rst}    |    6 +-
 ...en-bit-addresses => ten-bit-addresses.rst} |    5 +
 ...pgrading-clients => upgrading-clients.rst} |  204 +-
 .../{writing-clients => writing-clients.rst}  |   94 +-
 Documentation/index.rst                       |   10 +
 .../isdn/{README.avmb1 => avmb1.rst}          |  231 +-
 Documentation/isdn/{CREDITS => credits.rst}   |    7 +-
 .../isdn/{README.gigaset => gigaset.rst}      |  290 +-
 .../isdn/{README.hysdn => hysdn.rst}          |  125 +-
 Documentation/isdn/index.rst                  |   24 +
 .../{INTERFACE.CAPI => interface_capi.rst}    |  182 +-
 .../isdn/{README.mISDN => m_isdn.rst}         |    5 +-
 .../m68k/{README.buddha => buddha-driver.rst} |   95 +-
 Documentation/m68k/index.rst                  |    1 +
 .../{AU1xxx_IDE.README => au1xxx_ide.rst}     |   89 +-
 Documentation/mips/index.rst                  |   17 +
 .../networking/caif/{README => caif.rst}      |   88 +-
 .../networking/device_drivers/index.rst       |    2 +-
 Documentation/networking/index.rst            |    2 +-
 .../{README => mac80211_hwsim.rst}            |   28 +-
 Documentation/nios2/{README => nios2.rst}     |    1 +
 Documentation/openrisc/index.rst              |   18 +
 .../openrisc/{README => openrisc_port.rst}    |   25 +-
 Documentation/openrisc/{TODO => todo.rst}     |    9 +-
 .../parisc/{debugging => debugging.rst}       |    7 +
 Documentation/parisc/index.rst                |   18 +
 .../parisc/{registers => registers.rst}       |   59 +-
 Documentation/power/index.rst                 |    2 +-
 .../{bootwrapper.txt => bootwrapper.rst}      |   28 +-
 .../{cpu_families.txt => cpu_families.rst}    |   23 +-
 .../{cpu_features.txt => cpu_features.rst}    |    6 +-
 Documentation/powerpc/{cxl.txt => cxl.rst}    |   46 +-
 .../powerpc/{cxlflash.txt => cxlflash.rst}    |   10 +-
 .../{DAWR-POWER9.txt => dawr-power9.rst}      |   15 +-
 Documentation/powerpc/{dscr.txt => dscr.rst}  |   18 +-
 ...ecovery.txt => eeh-pci-error-recovery.rst} |  108 +-
 ...ed-dump.txt => firmware-assisted-dump.rst} |  117 +-
 Documentation/powerpc/{hvcs.txt => hvcs.rst}  |  108 +-
 Documentation/powerpc/index.rst               |   34 +
 Documentation/powerpc/isa-versions.rst        |   15 +-
 .../powerpc/{mpc52xx.txt => mpc52xx.rst}      |   12 +-
 ...nv.txt => pci_iov_resource_on_powernv.rst} |   15 +-
 .../powerpc/{pmu-ebb.txt => pmu-ebb.rst}      |    1 +
 .../powerpc/{ptrace.txt => ptrace.rst}        |  169 +-
 .../{qe_firmware.txt => qe_firmware.rst}      |   37 +-
 .../{syscall64-abi.txt => syscall64-abi.rst}  |   29 +-
 ...al_memory.txt => transactional_memory.rst} |   45 +-
 Documentation/sound/index.rst                 |    2 +-
 .../spi/{butterfly => butterfly.rst}          |   44 +-
 Documentation/spi/index.rst                   |   22 +
 Documentation/spi/{pxa2xx => pxa2xx.rst}      |   95 +-
 .../spi/{spi-lm70llp => spi-lm70llp.rst}      |   17 +-
 .../spi/{spi-sc18is602 => spi-sc18is602.rst}  |    5 +-
 .../spi/{spi-summary => spi-summary.rst}      |  105 +-
 Documentation/spi/{spidev => spidev.rst}      |   30 +-
 Documentation/w1/index.rst                    |   21 +
 .../w1/masters/{ds2482 => ds2482.rst}         |   16 +-
 .../w1/masters/{ds2490 => ds2490.rst}         |    6 +-
 Documentation/w1/masters/index.rst            |   14 +
 .../w1/masters/{mxc-w1 => mxc-w1.rst}         |   13 +-
 .../w1/masters/{omap-hdq => omap-hdq.rst}     |   12 +-
 .../w1/masters/{w1-gpio => w1-gpio.rst}       |   21 +-
 Documentation/w1/slaves/index.rst             |   16 +
 .../w1/slaves/{w1_ds2406 => w1_ds2406.rst}    |    4 +-
 .../w1/slaves/{w1_ds2413 => w1_ds2413.rst}    |    9 +
 .../w1/slaves/{w1_ds2423 => w1_ds2423.rst}    |   27 +-
 .../w1/slaves/{w1_ds2438 => w1_ds2438.rst}    |   10 +-
 .../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst}  |    5 +
 .../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst}  |   16 +-
 .../w1/slaves/{w1_therm => w1_therm.rst}      |   11 +-
 .../w1/{w1.generic => w1-generic.rst}         |   88 +-
 .../w1/{w1.netlink => w1-netlink.rst}         |   89 +-
 MAINTAINERS                                   |   68 +-
 arch/powerpc/kernel/exceptions-64s.S          |    2 +-
 drivers/auxdisplay/Kconfig                    |    2 +-
 drivers/hwmon/atxp1.c                         |    2 +-
 drivers/hwmon/smm665.c                        |    2 +-
 drivers/i2c/Kconfig                           |    4 +-
 drivers/i2c/busses/Kconfig                    |    2 +-
 drivers/i2c/busses/i2c-i801.c                 |    2 +-
 drivers/i2c/busses/i2c-taos-evm.c             |    2 +-
 drivers/i2c/i2c-core-base.c                   |    4 +-
 drivers/iio/dummy/iio_simple_dummy.c          |    4 +-
 drivers/rtc/rtc-ds1374.c                      |    2 +-
 drivers/soc/fsl/qe/qe.c                       |    2 +-
 drivers/spi/Kconfig                           |    2 +-
 drivers/spi/spi-butterfly.c                   |    2 +-
 drivers/spi/spi-lm70llp.c                     |    2 +-
 drivers/staging/isdn/hysdn/Kconfig            |    2 +-
 drivers/tty/hvc/hvcs.c                        |    2 +-
 fs/cifs/export.c                              |    2 +-
 fs/exportfs/expfs.c                           |    2 +-
 fs/isofs/export.c                             |    2 +-
 fs/orangefs/file.c                            |    2 +-
 fs/orangefs/orangefs-kernel.h                 |    2 +-
 include/linux/dcache.h                        |    2 +-
 include/linux/exportfs.h                      |    2 +-
 include/linux/i2c.h                           |    2 +-
 include/linux/platform_data/sc18is602.h       |    2 +-
 include/linux/thermal.h                       |    4 +-
 include/soc/fsl/qe/qe.h                       |    2 +-
 216 files changed, 9148 insertions(+), 8672 deletions(-)
 rename Documentation/ABI/testing/{sysfs-class-mic.txt => sysfs-class-mic} (100%)
 delete mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.html
 create mode 100644 Documentation/RCU/Design/Data-Structures/Data-Structures.rst
 rename Documentation/RCU/Design/Expedited-Grace-Periods/{Expedited-Grace-Periods.html => Expedited-Grace-Periods.rst} (15%)
 delete mode 100644 Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Diagram.html
 rename Documentation/RCU/Design/Memory-Ordering/{Tree-RCU-Memory-Ordering.html => Tree-RCU-Memory-Ordering.rst} (10%)
 delete mode 100644 Documentation/RCU/Design/Requirements/Requirements.html
 create mode 100644 Documentation/RCU/Design/Requirements/Requirements.rst
 rename Documentation/{auxdisplay/cfag12864b => admin-guide/auxdisplay/cfag12864b.rst} (26%)
 create mode 100644 Documentation/admin-guide/auxdisplay/index.rst
 rename Documentation/{auxdisplay/ks0108 => admin-guide/auxdisplay/ks0108.rst} (32%)
 rename Documentation/{filesystems/cifs/AUTHORS => admin-guide/cifs/authors.rst} (60%)
 rename Documentation/{filesystems/cifs/CHANGES => admin-guide/cifs/changes.rst} (91%)
 create mode 100644 Documentation/admin-guide/cifs/index.rst
 rename Documentation/{filesystems/cifs/cifs.txt => admin-guide/cifs/introduction.rst} (98%)
 rename Documentation/{filesystems/cifs/TODO => admin-guide/cifs/todo.rst} (58%)
 rename Documentation/{filesystems/cifs/README => admin-guide/cifs/usage.rst} (72%)
 rename Documentation/{filesystems => admin-guide}/cifs/winucase_convert.pl (100%)
 rename Documentation/{wimax/README.i2400m => admin-guide/wimax/i2400m.rst} (69%)
 create mode 100644 Documentation/admin-guide/wimax/index.rst
 rename Documentation/{wimax/README.wimax => admin-guide/wimax/wimax.rst} (74%)
 rename Documentation/{packing.txt => core-api/packing.rst} (61%)
 rename Documentation/devicetree/{writing-schema.md => writing-schema.rst} (48%)
 rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%)
 rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%)
 rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%)
 rename Documentation/{ => driver-api}/thermal/index.rst (86%)
 rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%)
 rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%)
 rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%)
 rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%)
 rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%)
 rename Documentation/filesystems/{directory-locking => directory-locking.rst} (86%)
 rename Documentation/filesystems/{Locking => locking.rst} (79%)
 rename Documentation/filesystems/nfs/{Exporting => exporting.rst} (91%)
 rename Documentation/filesystems/{porting => porting.rst} (49%)
 rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)
 rename Documentation/hwmon/{pxe1610 => pxe1610.rst} (82%)
 rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
 rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
 rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
 rename Documentation/i2c/busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} (42%)
 rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
 rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
 rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
 rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
 rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
 rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
 rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (58%)
 rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
 rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
 rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (91%)
 rename Documentation/i2c/busses/{i2c-parport => i2c-parport.rst} (49%)
 rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
 rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
 rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
 rename Documentation/i2c/busses/{i2c-sis630 => i2c-sis630.rst} (37%)
 rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (74%)
 rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
 rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (54%)
 rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
 create mode 100644 Documentation/i2c/busses/index.rst
 rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
 rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
 rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
 rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
 rename Documentation/i2c/{functionality => functionality.rst} (91%)
 rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
 rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
 rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
 rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
 create mode 100644 Documentation/i2c/index.rst
 rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
 rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
 rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
 rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
 rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
 rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (82%)
 rename Documentation/i2c/{summary => summary.rst} (96%)
 rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
 rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (54%)
 rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)
 rename Documentation/isdn/{README.avmb1 => avmb1.rst} (50%)
 rename Documentation/isdn/{CREDITS => credits.rst} (96%)
 rename Documentation/isdn/{README.gigaset => gigaset.rst} (74%)
 rename Documentation/isdn/{README.hysdn => hysdn.rst} (80%)
 create mode 100644 Documentation/isdn/index.rst
 rename Documentation/isdn/{INTERFACE.CAPI => interface_capi.rst} (75%)
 rename Documentation/isdn/{README.mISDN => m_isdn.rst} (89%)
 rename Documentation/m68k/{README.buddha => buddha-driver.rst} (73%)
 rename Documentation/mips/{AU1xxx_IDE.README => au1xxx_ide.rst} (67%)
 create mode 100644 Documentation/mips/index.rst
 rename Documentation/networking/caif/{README => caif.rst} (70%)
 rename Documentation/networking/mac80211_hwsim/{README => mac80211_hwsim.rst} (81%)
 rename Documentation/nios2/{README => nios2.rst} (96%)
 create mode 100644 Documentation/openrisc/index.rst
 rename Documentation/openrisc/{README => openrisc_port.rst} (80%)
 rename Documentation/openrisc/{TODO => todo.rst} (78%)
 rename Documentation/parisc/{debugging => debugging.rst} (94%)
 create mode 100644 Documentation/parisc/index.rst
 rename Documentation/parisc/{registers => registers.rst} (70%)
 rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
 rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
 rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
 rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
 rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
 rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
 rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
 rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
 rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
 rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
 create mode 100644 Documentation/powerpc/index.rst
 rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
 rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
 rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
 rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
 rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
 rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
 rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)
 rename Documentation/spi/{butterfly => butterfly.rst} (71%)
 create mode 100644 Documentation/spi/index.rst
 rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
 rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
 rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (92%)
 rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
 rename Documentation/spi/{spidev => spidev.rst} (90%)
 create mode 100644 Documentation/w1/index.rst
 rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
 rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
 create mode 100644 Documentation/w1/masters/index.rst
 rename Documentation/w1/masters/{mxc-w1 => mxc-w1.rst} (33%)
 rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
 rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
 create mode 100644 Documentation/w1/slaves/index.rst
 rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (96%)
 rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
 rename Documentation/w1/slaves/{w1_ds2423 => w1_ds2423.rst} (48%)
 rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
 rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
 rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
 rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
 rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
 rename Documentation/w1/{w1.netlink => w1-netlink.rst} (77%)

-- 
2.21.0



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

* [PATCH v2 01/26] docs: power: add it to to the main documentation index
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (3 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  2019-07-31 19:03   ` Jonathan Corbet
  -1 siblings, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Rafael J. Wysocki,
	Len Brown, Pavel Machek, linux-doc, linux-pm

The power docs are orphaned at the documentation body.

While it could likely be moved to be inside some guide, I'm opting to just
adding it to the main index.rst, removing the :orphan: and adding the SPDX
header.

The reason is similar to what it was done for other driver-specific
subsystems: the docs there contain a mix of Kernelspace, uAPI and
admin-guide. So, better to keep them on its own directory,
while the docs there are not properly classified.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/index.rst       | 1 +
 Documentation/power/index.rst | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 70ae148ec980..230e550e9741 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -111,6 +111,7 @@ needed).
    netlabel/index
    networking/index
    pcmcia/index
+   power/index
    target/index
    timers/index
    watchdog/index
diff --git a/Documentation/power/index.rst b/Documentation/power/index.rst
index 20415f21e48a..002e42745263 100644
--- a/Documentation/power/index.rst
+++ b/Documentation/power/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 ================
 Power Management
-- 
2.21.0


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

* [PATCH v2 02/26] docs: thermal: add it to the driver API
  2019-07-26 12:51 ` Mauro Carvalho Chehab
  (?)
@ 2019-07-26 12:51   ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Amit Daniel Kachhap,
	Viresh Kumar, Javi Merino, Kukjin Kim, Krzysztof Kozlowski,
	Zhang Rui, Eduardo Valentin, Daniel Lezcano, linux-doc, linux-pm,
	linux-arm-kernel, linux-samsung-soc

The file contents mostly describes driver internals.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/driver-api/index.rst                   |  1 +
 .../{ => driver-api}/thermal/cpu-cooling-api.rst     |  0
 .../{ => driver-api}/thermal/exynos_thermal.rst      |  0
 .../thermal/exynos_thermal_emulation.rst             |  0
 Documentation/{ => driver-api}/thermal/index.rst     |  2 +-
 .../{ => driver-api}/thermal/intel_powerclamp.rst    |  0
 .../{ => driver-api}/thermal/nouveau_thermal.rst     |  0
 .../{ => driver-api}/thermal/power_allocator.rst     |  0
 Documentation/{ => driver-api}/thermal/sysfs-api.rst | 12 ++++++------
 .../thermal/x86_pkg_temperature_thermal.rst          |  2 +-
 MAINTAINERS                                          |  2 +-
 include/linux/thermal.h                              |  4 ++--
 12 files changed, 12 insertions(+), 11 deletions(-)
 rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%)
 rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%)
 rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%)
 rename Documentation/{ => driver-api}/thermal/index.rst (86%)
 rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%)
 rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%)
 rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%)
 rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%)
 rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%)

diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index d12a80f386a6..37ac052ded85 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -65,6 +65,7 @@ available subsections can be seen below.
    dmaengine/index
    slimbus
    soundwire/index
+   thermal/index
    fpga/index
    acpi/index
    backlight/lp855x-driver.rst
diff --git a/Documentation/thermal/cpu-cooling-api.rst b/Documentation/driver-api/thermal/cpu-cooling-api.rst
similarity index 100%
rename from Documentation/thermal/cpu-cooling-api.rst
rename to Documentation/driver-api/thermal/cpu-cooling-api.rst
diff --git a/Documentation/thermal/exynos_thermal.rst b/Documentation/driver-api/thermal/exynos_thermal.rst
similarity index 100%
rename from Documentation/thermal/exynos_thermal.rst
rename to Documentation/driver-api/thermal/exynos_thermal.rst
diff --git a/Documentation/thermal/exynos_thermal_emulation.rst b/Documentation/driver-api/thermal/exynos_thermal_emulation.rst
similarity index 100%
rename from Documentation/thermal/exynos_thermal_emulation.rst
rename to Documentation/driver-api/thermal/exynos_thermal_emulation.rst
diff --git a/Documentation/thermal/index.rst b/Documentation/driver-api/thermal/index.rst
similarity index 86%
rename from Documentation/thermal/index.rst
rename to Documentation/driver-api/thermal/index.rst
index 8c1c00146cad..5ba61d19c6ae 100644
--- a/Documentation/thermal/index.rst
+++ b/Documentation/driver-api/thermal/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 =======
 Thermal
diff --git a/Documentation/thermal/intel_powerclamp.rst b/Documentation/driver-api/thermal/intel_powerclamp.rst
similarity index 100%
rename from Documentation/thermal/intel_powerclamp.rst
rename to Documentation/driver-api/thermal/intel_powerclamp.rst
diff --git a/Documentation/thermal/nouveau_thermal.rst b/Documentation/driver-api/thermal/nouveau_thermal.rst
similarity index 100%
rename from Documentation/thermal/nouveau_thermal.rst
rename to Documentation/driver-api/thermal/nouveau_thermal.rst
diff --git a/Documentation/thermal/power_allocator.rst b/Documentation/driver-api/thermal/power_allocator.rst
similarity index 100%
rename from Documentation/thermal/power_allocator.rst
rename to Documentation/driver-api/thermal/power_allocator.rst
diff --git a/Documentation/thermal/sysfs-api.rst b/Documentation/driver-api/thermal/sysfs-api.rst
similarity index 98%
rename from Documentation/thermal/sysfs-api.rst
rename to Documentation/driver-api/thermal/sysfs-api.rst
index e4930761d3e5..fab2c9b36d08 100644
--- a/Documentation/thermal/sysfs-api.rst
+++ b/Documentation/driver-api/thermal/sysfs-api.rst
@@ -552,7 +552,7 @@ emul_temp
 sustainable_power
 	An estimate of the sustained power that can be dissipated by
 	the thermal zone. Used by the power allocator governor. For
-	more information see Documentation/thermal/power_allocator.rst
+	more information see Documentation/driver-api/thermal/power_allocator.rst
 
 	Unit: milliwatts
 
@@ -563,7 +563,7 @@ k_po
 	controller during temperature overshoot. Temperature overshoot
 	is when the current temperature is above the "desired
 	temperature" trip point. For more information see
-	Documentation/thermal/power_allocator.rst
+	Documentation/driver-api/thermal/power_allocator.rst
 
 	RW, Optional
 
@@ -572,7 +572,7 @@ k_pu
 	controller during temperature undershoot. Temperature undershoot
 	is when the current temperature is below the "desired
 	temperature" trip point. For more information see
-	Documentation/thermal/power_allocator.rst
+	Documentation/driver-api/thermal/power_allocator.rst
 
 	RW, Optional
 
@@ -580,14 +580,14 @@ k_i
 	The integral term of the power allocator governor's PID
 	controller. This term allows the PID controller to compensate
 	for long term drift. For more information see
-	Documentation/thermal/power_allocator.rst
+	Documentation/driver-api/thermal/power_allocator.rst
 
 	RW, Optional
 
 k_d
 	The derivative term of the power allocator governor's PID
 	controller. For more information see
-	Documentation/thermal/power_allocator.rst
+	Documentation/driver-api/thermal/power_allocator.rst
 
 	RW, Optional
 
@@ -598,7 +598,7 @@ integral_cutoff
 	example, if integral_cutoff is 0, then the integral term only
 	accumulates error when temperature is above the desired
 	temperature trip point. For more information see
-	Documentation/thermal/power_allocator.rst
+	Documentation/driver-api/thermal/power_allocator.rst
 
 	Unit: millidegree Celsius
 
diff --git a/Documentation/thermal/x86_pkg_temperature_thermal.rst b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
similarity index 94%
rename from Documentation/thermal/x86_pkg_temperature_thermal.rst
rename to Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
index f134dbd3f5a9..2ac42ccd236f 100644
--- a/Documentation/thermal/x86_pkg_temperature_thermal.rst
+++ b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
@@ -40,7 +40,7 @@ This contains two trip points:
 - trip_point_1_temp
 
 User can set any temperature between 0 to TJ-Max temperature. Temperature units
-are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.rst" for
+are in milli-degree Celsius. Refer to "Documentation/driver-api/thermal/sysfs-api.rst" for
 thermal sys-fs details.
 
 Any value other than 0 in these trip points, can trigger thermal notifications.
diff --git a/MAINTAINERS b/MAINTAINERS
index 4e2a525e22c0..3d6cd6efb264 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15907,7 +15907,7 @@ M:	Viresh Kumar <viresh.kumar@linaro.org>
 M:	Javi Merino <javi.merino@kernel.org>
 L:	linux-pm@vger.kernel.org
 S:	Supported
-F:	Documentation/thermal/cpu-cooling-api.rst
+F:	Documentation/driver-api/thermal/cpu-cooling-api.rst
 F:	drivers/thermal/cpu_cooling.c
 F:	include/linux/cpu_cooling.h
 
diff --git a/include/linux/thermal.h b/include/linux/thermal.h
index 681047f8cc05..e45659c75920 100644
--- a/include/linux/thermal.h
+++ b/include/linux/thermal.h
@@ -251,7 +251,7 @@ struct thermal_bind_params {
 	 * platform characterization. This value is relative to the
 	 * rest of the weights so a cooling device whose weight is
 	 * double that of another cooling device is twice as
-	 * effective. See Documentation/thermal/sysfs-api.rst for more
+	 * effective. See Documentation/driver-api/thermal/sysfs-api.rst for more
 	 * information.
 	 */
 	int weight;
@@ -259,7 +259,7 @@ struct thermal_bind_params {
 	/*
 	 * This is a bit mask that gives the binding relation between this
 	 * thermal zone and cdev, for a particular trip point.
-	 * See Documentation/thermal/sysfs-api.rst for more information.
+	 * See Documentation/driver-api/thermal/sysfs-api.rst for more information.
 	 */
 	int trip_mask;
 
-- 
2.21.0


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

* [PATCH v2 02/26] docs: thermal: add it to the driver API
@ 2019-07-26 12:51   ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: linux-samsung-soc, Jonathan Corbet, Viresh Kumar,
	Amit Daniel Kachhap, Daniel Lezcano, linux-doc,
	Krzysztof Kozlowski, Eduardo Valentin, Kukjin Kim, linux-pm,
	Mauro Carvalho Chehab, Zhang Rui, Javi Merino, linux-arm-kernel

The file contents mostly describes driver internals.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/driver-api/index.rst                   |  1 +
 .../{ => driver-api}/thermal/cpu-cooling-api.rst     |  0
 .../{ => driver-api}/thermal/exynos_thermal.rst      |  0
 .../thermal/exynos_thermal_emulation.rst             |  0
 Documentation/{ => driver-api}/thermal/index.rst     |  2 +-
 .../{ => driver-api}/thermal/intel_powerclamp.rst    |  0
 .../{ => driver-api}/thermal/nouveau_thermal.rst     |  0
 .../{ => driver-api}/thermal/power_allocator.rst     |  0
 Documentation/{ => driver-api}/thermal/sysfs-api.rst | 12 ++++++------
 .../thermal/x86_pkg_temperature_thermal.rst          |  2 +-
 MAINTAINERS                                          |  2 +-
 include/linux/thermal.h                              |  4 ++--
 12 files changed, 12 insertions(+), 11 deletions(-)
 rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%)
 rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%)
 rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%)
 rename Documentation/{ => driver-api}/thermal/index.rst (86%)
 rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%)
 rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%)
 rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%)
 rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%)
 rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%)

diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index d12a80f386a6..37ac052ded85 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -65,6 +65,7 @@ available subsections can be seen below.
    dmaengine/index
    slimbus
    soundwire/index
+   thermal/index
    fpga/index
    acpi/index
    backlight/lp855x-driver.rst
diff --git a/Documentation/thermal/cpu-cooling-api.rst b/Documentation/driver-api/thermal/cpu-cooling-api.rst
similarity index 100%
rename from Documentation/thermal/cpu-cooling-api.rst
rename to Documentation/driver-api/thermal/cpu-cooling-api.rst
diff --git a/Documentation/thermal/exynos_thermal.rst b/Documentation/driver-api/thermal/exynos_thermal.rst
similarity index 100%
rename from Documentation/thermal/exynos_thermal.rst
rename to Documentation/driver-api/thermal/exynos_thermal.rst
diff --git a/Documentation/thermal/exynos_thermal_emulation.rst b/Documentation/driver-api/thermal/exynos_thermal_emulation.rst
similarity index 100%
rename from Documentation/thermal/exynos_thermal_emulation.rst
rename to Documentation/driver-api/thermal/exynos_thermal_emulation.rst
diff --git a/Documentation/thermal/index.rst b/Documentation/driver-api/thermal/index.rst
similarity index 86%
rename from Documentation/thermal/index.rst
rename to Documentation/driver-api/thermal/index.rst
index 8c1c00146cad..5ba61d19c6ae 100644
--- a/Documentation/thermal/index.rst
+++ b/Documentation/driver-api/thermal/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 =======
 Thermal
diff --git a/Documentation/thermal/intel_powerclamp.rst b/Documentation/driver-api/thermal/intel_powerclamp.rst
similarity index 100%
rename from Documentation/thermal/intel_powerclamp.rst
rename to Documentation/driver-api/thermal/intel_powerclamp.rst
diff --git a/Documentation/thermal/nouveau_thermal.rst b/Documentation/driver-api/thermal/nouveau_thermal.rst
similarity index 100%
rename from Documentation/thermal/nouveau_thermal.rst
rename to Documentation/driver-api/thermal/nouveau_thermal.rst
diff --git a/Documentation/thermal/power_allocator.rst b/Documentation/driver-api/thermal/power_allocator.rst
similarity index 100%
rename from Documentation/thermal/power_allocator.rst
rename to Documentation/driver-api/thermal/power_allocator.rst
diff --git a/Documentation/thermal/sysfs-api.rst b/Documentation/driver-api/thermal/sysfs-api.rst
similarity index 98%
rename from Documentation/thermal/sysfs-api.rst
rename to Documentation/driver-api/thermal/sysfs-api.rst
index e4930761d3e5..fab2c9b36d08 100644
--- a/Documentation/thermal/sysfs-api.rst
+++ b/Documentation/driver-api/thermal/sysfs-api.rst
@@ -552,7 +552,7 @@ emul_temp
 sustainable_power
 	An estimate of the sustained power that can be dissipated by
 	the thermal zone. Used by the power allocator governor. For
-	more information see Documentation/thermal/power_allocator.rst
+	more information see Documentation/driver-api/thermal/power_allocator.rst
 
 	Unit: milliwatts
 
@@ -563,7 +563,7 @@ k_po
 	controller during temperature overshoot. Temperature overshoot
 	is when the current temperature is above the "desired
 	temperature" trip point. For more information see
-	Documentation/thermal/power_allocator.rst
+	Documentation/driver-api/thermal/power_allocator.rst
 
 	RW, Optional
 
@@ -572,7 +572,7 @@ k_pu
 	controller during temperature undershoot. Temperature undershoot
 	is when the current temperature is below the "desired
 	temperature" trip point. For more information see
-	Documentation/thermal/power_allocator.rst
+	Documentation/driver-api/thermal/power_allocator.rst
 
 	RW, Optional
 
@@ -580,14 +580,14 @@ k_i
 	The integral term of the power allocator governor's PID
 	controller. This term allows the PID controller to compensate
 	for long term drift. For more information see
-	Documentation/thermal/power_allocator.rst
+	Documentation/driver-api/thermal/power_allocator.rst
 
 	RW, Optional
 
 k_d
 	The derivative term of the power allocator governor's PID
 	controller. For more information see
-	Documentation/thermal/power_allocator.rst
+	Documentation/driver-api/thermal/power_allocator.rst
 
 	RW, Optional
 
@@ -598,7 +598,7 @@ integral_cutoff
 	example, if integral_cutoff is 0, then the integral term only
 	accumulates error when temperature is above the desired
 	temperature trip point. For more information see
-	Documentation/thermal/power_allocator.rst
+	Documentation/driver-api/thermal/power_allocator.rst
 
 	Unit: millidegree Celsius
 
diff --git a/Documentation/thermal/x86_pkg_temperature_thermal.rst b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
similarity index 94%
rename from Documentation/thermal/x86_pkg_temperature_thermal.rst
rename to Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
index f134dbd3f5a9..2ac42ccd236f 100644
--- a/Documentation/thermal/x86_pkg_temperature_thermal.rst
+++ b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
@@ -40,7 +40,7 @@ This contains two trip points:
 - trip_point_1_temp
 
 User can set any temperature between 0 to TJ-Max temperature. Temperature units
-are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.rst" for
+are in milli-degree Celsius. Refer to "Documentation/driver-api/thermal/sysfs-api.rst" for
 thermal sys-fs details.
 
 Any value other than 0 in these trip points, can trigger thermal notifications.
diff --git a/MAINTAINERS b/MAINTAINERS
index 4e2a525e22c0..3d6cd6efb264 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15907,7 +15907,7 @@ M:	Viresh Kumar <viresh.kumar@linaro.org>
 M:	Javi Merino <javi.merino@kernel.org>
 L:	linux-pm@vger.kernel.org
 S:	Supported
-F:	Documentation/thermal/cpu-cooling-api.rst
+F:	Documentation/driver-api/thermal/cpu-cooling-api.rst
 F:	drivers/thermal/cpu_cooling.c
 F:	include/linux/cpu_cooling.h
 
diff --git a/include/linux/thermal.h b/include/linux/thermal.h
index 681047f8cc05..e45659c75920 100644
--- a/include/linux/thermal.h
+++ b/include/linux/thermal.h
@@ -251,7 +251,7 @@ struct thermal_bind_params {
 	 * platform characterization. This value is relative to the
 	 * rest of the weights so a cooling device whose weight is
 	 * double that of another cooling device is twice as
-	 * effective. See Documentation/thermal/sysfs-api.rst for more
+	 * effective. See Documentation/driver-api/thermal/sysfs-api.rst for more
 	 * information.
 	 */
 	int weight;
@@ -259,7 +259,7 @@ struct thermal_bind_params {
 	/*
 	 * This is a bit mask that gives the binding relation between this
 	 * thermal zone and cdev, for a particular trip point.
-	 * See Documentation/thermal/sysfs-api.rst for more information.
+	 * See Documentation/driver-api/thermal/sysfs-api.rst for more information.
 	 */
 	int trip_mask;
 
-- 
2.21.0

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

* [PATCH v2 02/26] docs: thermal: add it to the driver API
@ 2019-07-26 12:51   ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: linux-samsung-soc, Jonathan Corbet, Viresh Kumar,
	Amit Daniel Kachhap, Daniel Lezcano, linux-doc,
	Krzysztof Kozlowski, Eduardo Valentin, Kukjin Kim, linux-pm,
	Mauro Carvalho Chehab, Zhang Rui, Javi Merino, linux-arm-kernel

The file contents mostly describes driver internals.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/driver-api/index.rst                   |  1 +
 .../{ => driver-api}/thermal/cpu-cooling-api.rst     |  0
 .../{ => driver-api}/thermal/exynos_thermal.rst      |  0
 .../thermal/exynos_thermal_emulation.rst             |  0
 Documentation/{ => driver-api}/thermal/index.rst     |  2 +-
 .../{ => driver-api}/thermal/intel_powerclamp.rst    |  0
 .../{ => driver-api}/thermal/nouveau_thermal.rst     |  0
 .../{ => driver-api}/thermal/power_allocator.rst     |  0
 Documentation/{ => driver-api}/thermal/sysfs-api.rst | 12 ++++++------
 .../thermal/x86_pkg_temperature_thermal.rst          |  2 +-
 MAINTAINERS                                          |  2 +-
 include/linux/thermal.h                              |  4 ++--
 12 files changed, 12 insertions(+), 11 deletions(-)
 rename Documentation/{ => driver-api}/thermal/cpu-cooling-api.rst (100%)
 rename Documentation/{ => driver-api}/thermal/exynos_thermal.rst (100%)
 rename Documentation/{ => driver-api}/thermal/exynos_thermal_emulation.rst (100%)
 rename Documentation/{ => driver-api}/thermal/index.rst (86%)
 rename Documentation/{ => driver-api}/thermal/intel_powerclamp.rst (100%)
 rename Documentation/{ => driver-api}/thermal/nouveau_thermal.rst (100%)
 rename Documentation/{ => driver-api}/thermal/power_allocator.rst (100%)
 rename Documentation/{ => driver-api}/thermal/sysfs-api.rst (98%)
 rename Documentation/{ => driver-api}/thermal/x86_pkg_temperature_thermal.rst (94%)

diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index d12a80f386a6..37ac052ded85 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -65,6 +65,7 @@ available subsections can be seen below.
    dmaengine/index
    slimbus
    soundwire/index
+   thermal/index
    fpga/index
    acpi/index
    backlight/lp855x-driver.rst
diff --git a/Documentation/thermal/cpu-cooling-api.rst b/Documentation/driver-api/thermal/cpu-cooling-api.rst
similarity index 100%
rename from Documentation/thermal/cpu-cooling-api.rst
rename to Documentation/driver-api/thermal/cpu-cooling-api.rst
diff --git a/Documentation/thermal/exynos_thermal.rst b/Documentation/driver-api/thermal/exynos_thermal.rst
similarity index 100%
rename from Documentation/thermal/exynos_thermal.rst
rename to Documentation/driver-api/thermal/exynos_thermal.rst
diff --git a/Documentation/thermal/exynos_thermal_emulation.rst b/Documentation/driver-api/thermal/exynos_thermal_emulation.rst
similarity index 100%
rename from Documentation/thermal/exynos_thermal_emulation.rst
rename to Documentation/driver-api/thermal/exynos_thermal_emulation.rst
diff --git a/Documentation/thermal/index.rst b/Documentation/driver-api/thermal/index.rst
similarity index 86%
rename from Documentation/thermal/index.rst
rename to Documentation/driver-api/thermal/index.rst
index 8c1c00146cad..5ba61d19c6ae 100644
--- a/Documentation/thermal/index.rst
+++ b/Documentation/driver-api/thermal/index.rst
@@ -1,4 +1,4 @@
-:orphan:
+.. SPDX-License-Identifier: GPL-2.0
 
 =======
 Thermal
diff --git a/Documentation/thermal/intel_powerclamp.rst b/Documentation/driver-api/thermal/intel_powerclamp.rst
similarity index 100%
rename from Documentation/thermal/intel_powerclamp.rst
rename to Documentation/driver-api/thermal/intel_powerclamp.rst
diff --git a/Documentation/thermal/nouveau_thermal.rst b/Documentation/driver-api/thermal/nouveau_thermal.rst
similarity index 100%
rename from Documentation/thermal/nouveau_thermal.rst
rename to Documentation/driver-api/thermal/nouveau_thermal.rst
diff --git a/Documentation/thermal/power_allocator.rst b/Documentation/driver-api/thermal/power_allocator.rst
similarity index 100%
rename from Documentation/thermal/power_allocator.rst
rename to Documentation/driver-api/thermal/power_allocator.rst
diff --git a/Documentation/thermal/sysfs-api.rst b/Documentation/driver-api/thermal/sysfs-api.rst
similarity index 98%
rename from Documentation/thermal/sysfs-api.rst
rename to Documentation/driver-api/thermal/sysfs-api.rst
index e4930761d3e5..fab2c9b36d08 100644
--- a/Documentation/thermal/sysfs-api.rst
+++ b/Documentation/driver-api/thermal/sysfs-api.rst
@@ -552,7 +552,7 @@ emul_temp
 sustainable_power
 	An estimate of the sustained power that can be dissipated by
 	the thermal zone. Used by the power allocator governor. For
-	more information see Documentation/thermal/power_allocator.rst
+	more information see Documentation/driver-api/thermal/power_allocator.rst
 
 	Unit: milliwatts
 
@@ -563,7 +563,7 @@ k_po
 	controller during temperature overshoot. Temperature overshoot
 	is when the current temperature is above the "desired
 	temperature" trip point. For more information see
-	Documentation/thermal/power_allocator.rst
+	Documentation/driver-api/thermal/power_allocator.rst
 
 	RW, Optional
 
@@ -572,7 +572,7 @@ k_pu
 	controller during temperature undershoot. Temperature undershoot
 	is when the current temperature is below the "desired
 	temperature" trip point. For more information see
-	Documentation/thermal/power_allocator.rst
+	Documentation/driver-api/thermal/power_allocator.rst
 
 	RW, Optional
 
@@ -580,14 +580,14 @@ k_i
 	The integral term of the power allocator governor's PID
 	controller. This term allows the PID controller to compensate
 	for long term drift. For more information see
-	Documentation/thermal/power_allocator.rst
+	Documentation/driver-api/thermal/power_allocator.rst
 
 	RW, Optional
 
 k_d
 	The derivative term of the power allocator governor's PID
 	controller. For more information see
-	Documentation/thermal/power_allocator.rst
+	Documentation/driver-api/thermal/power_allocator.rst
 
 	RW, Optional
 
@@ -598,7 +598,7 @@ integral_cutoff
 	example, if integral_cutoff is 0, then the integral term only
 	accumulates error when temperature is above the desired
 	temperature trip point. For more information see
-	Documentation/thermal/power_allocator.rst
+	Documentation/driver-api/thermal/power_allocator.rst
 
 	Unit: millidegree Celsius
 
diff --git a/Documentation/thermal/x86_pkg_temperature_thermal.rst b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
similarity index 94%
rename from Documentation/thermal/x86_pkg_temperature_thermal.rst
rename to Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
index f134dbd3f5a9..2ac42ccd236f 100644
--- a/Documentation/thermal/x86_pkg_temperature_thermal.rst
+++ b/Documentation/driver-api/thermal/x86_pkg_temperature_thermal.rst
@@ -40,7 +40,7 @@ This contains two trip points:
 - trip_point_1_temp
 
 User can set any temperature between 0 to TJ-Max temperature. Temperature units
-are in milli-degree Celsius. Refer to "Documentation/thermal/sysfs-api.rst" for
+are in milli-degree Celsius. Refer to "Documentation/driver-api/thermal/sysfs-api.rst" for
 thermal sys-fs details.
 
 Any value other than 0 in these trip points, can trigger thermal notifications.
diff --git a/MAINTAINERS b/MAINTAINERS
index 4e2a525e22c0..3d6cd6efb264 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15907,7 +15907,7 @@ M:	Viresh Kumar <viresh.kumar@linaro.org>
 M:	Javi Merino <javi.merino@kernel.org>
 L:	linux-pm@vger.kernel.org
 S:	Supported
-F:	Documentation/thermal/cpu-cooling-api.rst
+F:	Documentation/driver-api/thermal/cpu-cooling-api.rst
 F:	drivers/thermal/cpu_cooling.c
 F:	include/linux/cpu_cooling.h
 
diff --git a/include/linux/thermal.h b/include/linux/thermal.h
index 681047f8cc05..e45659c75920 100644
--- a/include/linux/thermal.h
+++ b/include/linux/thermal.h
@@ -251,7 +251,7 @@ struct thermal_bind_params {
 	 * platform characterization. This value is relative to the
 	 * rest of the weights so a cooling device whose weight is
 	 * double that of another cooling device is twice as
-	 * effective. See Documentation/thermal/sysfs-api.rst for more
+	 * effective. See Documentation/driver-api/thermal/sysfs-api.rst for more
 	 * information.
 	 */
 	int weight;
@@ -259,7 +259,7 @@ struct thermal_bind_params {
 	/*
 	 * This is a bit mask that gives the binding relation between this
 	 * thermal zone and cdev, for a particular trip point.
-	 * See Documentation/thermal/sysfs-api.rst for more information.
+	 * See Documentation/driver-api/thermal/sysfs-api.rst for more information.
 	 */
 	int trip_mask;
 
-- 
2.21.0


_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

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

* [PATCH v2 03/26] docs: powerpc: convert docs to ReST and rename to *.rst
  2019-07-26 12:51 ` Mauro Carvalho Chehab
  (?)
  (?)
@ 2019-07-26 12:51   ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Linas Vepstas, Russell Currey,
	Sam Bobroff, Oliver O'Halloran, Bjorn Helgaas,
	Jonathan Corbet, Benjamin Herrenschmidt, Paul Mackerras,
	Michael Ellerman, Frederic Barrat, Andrew Donnellan,
	Manoj N. Kumar, Matthew R. Ochs, Uma Krishnan, Qiang Zhao,
	Li Yang, Greg Kroah-Hartman, Jiri Slaby, linux-pci, linuxppc-dev,
	linux-doc, linux-scsi, linux-arm-kernel, Andrew Donnellan

Convert docs to ReST and add them to the arch-specific
book.

The conversion here was trivial, as almost every file there
was already using an elegant format close to ReST standard.

The changes were mostly to mark literal blocks and add a few
missing section title identifiers.

One note with regards to "--": on Sphinx, this can't be used
to identify a list, as it will format it badly. This can be
used, however, to identify a long hyphen - and "---" is an
even longer one.

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: Andrew Donnellan <andrew.donnellan@au1.ibm.com> # cxl
---
 Documentation/PCI/pci-error-recovery.rst      |   2 +-
 Documentation/index.rst                       |   1 +
 .../{bootwrapper.txt => bootwrapper.rst}      |  28 ++-
 .../{cpu_families.txt => cpu_families.rst}    |  23 +--
 .../{cpu_features.txt => cpu_features.rst}    |   6 +-
 Documentation/powerpc/{cxl.txt => cxl.rst}    |  46 +++--
 .../powerpc/{cxlflash.txt => cxlflash.rst}    |  10 +-
 .../{DAWR-POWER9.txt => dawr-power9.rst}      |  15 +-
 Documentation/powerpc/{dscr.txt => dscr.rst}  |  18 +-
 ...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +++++------
 ...ed-dump.txt => firmware-assisted-dump.rst} | 117 ++++++------
 Documentation/powerpc/{hvcs.txt => hvcs.rst}  | 108 ++++++-----
 Documentation/powerpc/index.rst               |  34 ++++
 Documentation/powerpc/isa-versions.rst        |  15 +-
 .../powerpc/{mpc52xx.txt => mpc52xx.rst}      |  12 +-
 ...nv.txt => pci_iov_resource_on_powernv.rst} |  15 +-
 .../powerpc/{pmu-ebb.txt => pmu-ebb.rst}      |   1 +
 .../powerpc/{ptrace.txt => ptrace.rst}        | 169 +++++++++---------
 .../{qe_firmware.txt => qe_firmware.rst}      |  37 ++--
 .../{syscall64-abi.txt => syscall64-abi.rst}  |  29 +--
 ...al_memory.txt => transactional_memory.rst} |  45 ++---
 MAINTAINERS                                   |   6 +-
 arch/powerpc/kernel/exceptions-64s.S          |   2 +-
 drivers/soc/fsl/qe/qe.c                       |   2 +-
 drivers/tty/hvc/hvcs.c                        |   2 +-
 include/soc/fsl/qe/qe.h                       |   2 +-
 26 files changed, 495 insertions(+), 358 deletions(-)
 rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
 rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
 rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
 rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
 rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
 rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
 rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
 rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
 rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
 rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
 create mode 100644 Documentation/powerpc/index.rst
 rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
 rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
 rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
 rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
 rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
 rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
 rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)

diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
index 83db42092935..69800a9d1b0d 100644
--- a/Documentation/PCI/pci-error-recovery.rst
+++ b/Documentation/PCI/pci-error-recovery.rst
@@ -403,7 +403,7 @@ That is, the recovery API only requires that:
 .. note::
 
    Implementation details for the powerpc platform are discussed in
-   the file Documentation/powerpc/eeh-pci-error-recovery.txt
+   the file Documentation/powerpc/eeh-pci-error-recovery.rst
 
    As of this writing, there is a growing list of device drivers with
    patches implementing error recovery. Not all of these patches are in
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 230e550e9741..68ae2a4d689d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -144,6 +144,7 @@ implementation.
    arm64/index
    ia64/index
    m68k/index
+   powerpc/index
    riscv/index
    s390/index
    sh/index
diff --git a/Documentation/powerpc/bootwrapper.txt b/Documentation/powerpc/bootwrapper.rst
similarity index 93%
rename from Documentation/powerpc/bootwrapper.txt
rename to Documentation/powerpc/bootwrapper.rst
index d60fced5e1cc..a6292afba573 100644
--- a/Documentation/powerpc/bootwrapper.txt
+++ b/Documentation/powerpc/bootwrapper.rst
@@ -1,5 +1,7 @@
+========================
 The PowerPC boot wrapper
-------------------------
+========================
+
 Copyright (C) Secret Lab Technologies Ltd.
 
 PowerPC image targets compresses and wraps the kernel image (vmlinux) with
@@ -21,6 +23,7 @@ it uses the wrapper script (arch/powerpc/boot/wrapper) to generate target
 image.  The details of the build system is discussed in the next section.
 Currently, the following image format targets exist:
 
+   ==================== ========================================================
    cuImage.%:		Backwards compatible uImage for older version of
 			U-Boot (for versions that don't understand the device
 			tree).  This image embeds a device tree blob inside
@@ -29,31 +32,36 @@ Currently, the following image format targets exist:
 			with boot wrapper code that extracts data from the old
 			bd_info structure and loads the data into the device
 			tree before jumping into the kernel.
-			  Because of the series of #ifdefs found in the
+
+			Because of the series of #ifdefs found in the
 			bd_info structure used in the old U-Boot interfaces,
 			cuImages are platform specific.  Each specific
 			U-Boot platform has a different platform init file
 			which populates the embedded device tree with data
 			from the platform specific bd_info file.  The platform
 			specific cuImage platform init code can be found in
-			arch/powerpc/boot/cuboot.*.c.  Selection of the correct
+			`arch/powerpc/boot/cuboot.*.c`. Selection of the correct
 			cuImage init code for a specific board can be found in
 			the wrapper structure.
+
    dtbImage.%:		Similar to zImage, except device tree blob is embedded
 			inside the image instead of provided by firmware.  The
 			output image file can be either an elf file or a flat
 			binary depending on the platform.
-			  dtbImages are used on systems which do not have an
+
+			dtbImages are used on systems which do not have an
 			interface for passing a device tree directly.
 			dtbImages are similar to simpleImages except that
 			dtbImages have platform specific code for extracting
 			data from the board firmware, but simpleImages do not
 			talk to the firmware at all.
-			  PlayStation 3 support uses dtbImage.  So do Embedded
+
+			PlayStation 3 support uses dtbImage.  So do Embedded
 			Planet boards using the PlanetCore firmware.  Board
 			specific initialization code is typically found in a
 			file named arch/powerpc/boot/<platform>.c; but this
 			can be overridden by the wrapper script.
+
    simpleImage.%:	Firmware independent compressed image that does not
 			depend on any particular firmware interface and embeds
 			a device tree blob.  This image is a flat binary that
@@ -61,14 +69,16 @@ Currently, the following image format targets exist:
 			Firmware cannot pass any configuration data to the
 			kernel with this image type and it depends entirely on
 			the embedded device tree for all information.
-			  The simpleImage is useful for booting systems with
+
+			The simpleImage is useful for booting systems with
 			an unknown firmware interface or for booting from
 			a debugger when no firmware is present (such as on
 			the Xilinx Virtex platform).  The only assumption that
 			simpleImage makes is that RAM is correctly initialized
 			and that the MMU is either off or has RAM mapped to
 			base address 0.
-			  simpleImage also supports inserting special platform
+
+			simpleImage also supports inserting special platform
 			specific initialization code to the start of the bootup
 			sequence.  The virtex405 platform uses this feature to
 			ensure that the cache is invalidated before caching
@@ -81,9 +91,11 @@ Currently, the following image format targets exist:
 			named (virtex405-<board>.dts).  Search the wrapper
 			script for 'virtex405' and see the file
 			arch/powerpc/boot/virtex405-head.S for details.
+
    treeImage.%;		Image format for used with OpenBIOS firmware found
 			on some ppc4xx hardware.  This image embeds a device
 			tree blob inside the image.
+
    uImage:		Native image format used by U-Boot.  The uImage target
 			does not add any boot code.  It just wraps a compressed
 			vmlinux in the uImage data structure.  This image
@@ -91,12 +103,14 @@ Currently, the following image format targets exist:
 			a device tree to the kernel at boot.  If using an older
 			version of U-Boot, then you need to use a cuImage
 			instead.
+
    zImage.%:		Image format which does not embed a device tree.
 			Used by OpenFirmware and other firmware interfaces
 			which are able to supply a device tree.  This image
 			expects firmware to provide the device tree at boot.
 			Typically, if you have general purpose PowerPC
 			hardware then you want this image format.
+   ==================== ========================================================
 
 Image types which embed a device tree blob (simpleImage, dtbImage, treeImage,
 and cuImage) all generate the device tree blob from a file in the
diff --git a/Documentation/powerpc/cpu_families.txt b/Documentation/powerpc/cpu_families.rst
similarity index 95%
rename from Documentation/powerpc/cpu_families.txt
rename to Documentation/powerpc/cpu_families.rst
index fc08e22feb1a..1e063c5440c3 100644
--- a/Documentation/powerpc/cpu_families.txt
+++ b/Documentation/powerpc/cpu_families.rst
@@ -1,3 +1,4 @@
+============
 CPU Families
 ============
 
@@ -8,8 +9,8 @@ and are supported by arch/powerpc.
 Book3S (aka sPAPR)
 ------------------
 
- - Hash MMU
- - Mix of 32 & 64 bit
+- Hash MMU
+- Mix of 32 & 64 bit::
 
    +--------------+                 +----------------+
    |  Old POWER   | --------------> | RS64 (threads) |
@@ -108,8 +109,8 @@ Book3S (aka sPAPR)
 IBM BookE
 ---------
 
- - Software loaded TLB.
- - All 32 bit
+- Software loaded TLB.
+- All 32 bit::
 
    +--------------+
    |     401      |
@@ -155,8 +156,8 @@ IBM BookE
 Motorola/Freescale 8xx
 ----------------------
 
- - Software loaded with hardware assist.
- - All 32 bit
+- Software loaded with hardware assist.
+- All 32 bit::
 
    +-------------+
    | MPC8xx Core |
@@ -166,9 +167,9 @@ Motorola/Freescale 8xx
 Freescale BookE
 ---------------
 
- - Software loaded TLB.
- - e6500 adds HW loaded indirect TLB entries.
- - Mix of 32 & 64 bit
+- Software loaded TLB.
+- e6500 adds HW loaded indirect TLB entries.
+- Mix of 32 & 64 bit::
 
    +--------------+
    |     e200     |
@@ -207,8 +208,8 @@ Freescale BookE
 IBM A2 core
 -----------
 
- - Book3E, software loaded TLB + HW loaded indirect TLB entries.
- - 64 bit
+- Book3E, software loaded TLB + HW loaded indirect TLB entries.
+- 64 bit::
 
    +--------------+     +----------------+
    |   A2 core    | --> |      WSP       |
diff --git a/Documentation/powerpc/cpu_features.txt b/Documentation/powerpc/cpu_features.rst
similarity index 97%
rename from Documentation/powerpc/cpu_features.txt
rename to Documentation/powerpc/cpu_features.rst
index ae09df8722c8..b7bcdd2f41bb 100644
--- a/Documentation/powerpc/cpu_features.txt
+++ b/Documentation/powerpc/cpu_features.rst
@@ -1,3 +1,7 @@
+============
+CPU Features
+============
+
 Hollis Blanchard <hollis@austin.ibm.com>
 5 Jun 2002
 
@@ -32,7 +36,7 @@ anyways).
 After detecting the processor type, the kernel patches out sections of code
 that shouldn't be used by writing nop's over it. Using cpufeatures requires
 just 2 macros (found in arch/powerpc/include/asm/cputable.h), as seen in head.S
-transfer_to_handler:
+transfer_to_handler::
 
 	#ifdef CONFIG_ALTIVEC
 	BEGIN_FTR_SECTION
diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.rst
similarity index 95%
rename from Documentation/powerpc/cxl.txt
rename to Documentation/powerpc/cxl.rst
index c5e8d5098ed3..920546d81326 100644
--- a/Documentation/powerpc/cxl.txt
+++ b/Documentation/powerpc/cxl.rst
@@ -1,3 +1,4 @@
+====================================
 Coherent Accelerator Interface (CXL)
 ====================================
 
@@ -21,6 +22,8 @@ Introduction
 Hardware overview
 =================
 
+    ::
+
          POWER8/9             FPGA
        +----------+        +---------+
        |          |        |         |
@@ -59,14 +62,16 @@ Hardware overview
     the fault. The context to which this fault is serviced is based on
     who owns that acceleration function.
 
-    POWER8 <-----> PSL Version 8 is compliant to the CAIA Version 1.0.
-    POWER9 <-----> PSL Version 9 is compliant to the CAIA Version 2.0.
+    - POWER8 and PSL Version 8 are compliant to the CAIA Version 1.0.
+    - POWER9 and PSL Version 9 are compliant to the CAIA Version 2.0.
+
     This PSL Version 9 provides new features such as:
+
     * Interaction with the nest MMU on the P9 chip.
     * Native DMA support.
     * Supports sending ASB_Notify messages for host thread wakeup.
     * Supports Atomic operations.
-    * ....
+    * etc.
 
     Cards with a PSL9 won't work on a POWER8 system and cards with a
     PSL8 won't work on a POWER9 system.
@@ -147,7 +152,9 @@ User API
     master devices.
 
     A userspace library libcxl is available here:
+
 	https://github.com/ibm-capi/libcxl
+
     This provides a C interface to this kernel API.
 
 open
@@ -165,7 +172,8 @@ open
     When all available contexts are allocated the open call will fail
     and return -ENOSPC.
 
-    Note: IRQs need to be allocated for each context, which may limit
+    Note:
+	  IRQs need to be allocated for each context, which may limit
           the number of contexts that can be created, and therefore
           how many times the device can be opened. The POWER8 CAPP
           supports 2040 IRQs and 3 are used by the kernel, so 2037 are
@@ -186,7 +194,9 @@ ioctl
         updated as userspace allocates and frees memory. This ioctl
         returns once the AFU context is started.
 
-        Takes a pointer to a struct cxl_ioctl_start_work:
+        Takes a pointer to a struct cxl_ioctl_start_work
+
+            ::
 
                 struct cxl_ioctl_start_work {
                         __u64 flags;
@@ -269,7 +279,7 @@ read
     The buffer passed to read() must be at least 4K bytes.
 
     The result of the read will be a buffer of one or more events,
-    each event is of type struct cxl_event, of varying size.
+    each event is of type struct cxl_event, of varying size::
 
             struct cxl_event {
                     struct cxl_event_header header;
@@ -280,7 +290,9 @@ read
                     };
             };
 
-    The struct cxl_event_header is defined as:
+    The struct cxl_event_header is defined as
+
+        ::
 
             struct cxl_event_header {
                     __u16 type;
@@ -307,7 +319,9 @@ read
             For future extensions and padding.
 
     If the event type is CXL_EVENT_AFU_INTERRUPT then the event
-    structure is defined as:
+    structure is defined as
+
+        ::
 
             struct cxl_event_afu_interrupt {
                     __u16 flags;
@@ -326,7 +340,9 @@ read
             For future extensions and padding.
 
     If the event type is CXL_EVENT_DATA_STORAGE then the event
-    structure is defined as:
+    structure is defined as
+
+        ::
 
             struct cxl_event_data_storage {
                     __u16 flags;
@@ -356,7 +372,9 @@ read
             For future extensions
 
     If the event type is CXL_EVENT_AFU_ERROR then the event structure
-    is defined as:
+    is defined as
+
+        ::
 
             struct cxl_event_afu_error {
                     __u16 flags;
@@ -393,15 +411,15 @@ open
 ioctl
 -----
 
-CXL_IOCTL_DOWNLOAD_IMAGE:
-CXL_IOCTL_VALIDATE_IMAGE:
+CXL_IOCTL_DOWNLOAD_IMAGE / CXL_IOCTL_VALIDATE_IMAGE:
     Starts and controls flashing a new FPGA image. Partial
     reconfiguration is not supported (yet), so the image must contain
     a copy of the PSL and AFU(s). Since an image can be quite large,
     the caller may have to iterate, splitting the image in smaller
     chunks.
 
-    Takes a pointer to a struct cxl_adapter_image:
+    Takes a pointer to a struct cxl_adapter_image::
+
         struct cxl_adapter_image {
             __u64 flags;
             __u64 data;
@@ -442,7 +460,7 @@ Udev rules
     The following udev rules could be used to create a symlink to the
     most logical chardev to use in any programming mode (afuX.Yd for
     dedicated, afuX.Ys for afu directed), since the API is virtually
-    identical for each:
+    identical for each::
 
 	SUBSYSTEM=="cxl", ATTRS{mode}=="dedicated_process", SYMLINK="cxl/%b"
 	SUBSYSTEM=="cxl", ATTRS{mode}=="afu_directed", \
diff --git a/Documentation/powerpc/cxlflash.txt b/Documentation/powerpc/cxlflash.rst
similarity index 98%
rename from Documentation/powerpc/cxlflash.txt
rename to Documentation/powerpc/cxlflash.rst
index a64bdaa0a1cf..cea67931b3b9 100644
--- a/Documentation/powerpc/cxlflash.txt
+++ b/Documentation/powerpc/cxlflash.rst
@@ -1,3 +1,7 @@
+================================
+Coherent Accelerator (CXL) Flash
+================================
+
 Introduction
 ============
 
@@ -28,7 +32,7 @@ Introduction
     responsible for the initialization of the adapter, setting up the
     special path for user space access, and performing error recovery. It
     communicates directly the Flash Accelerator Functional Unit (AFU)
-    as described in Documentation/powerpc/cxl.txt.
+    as described in Documentation/powerpc/cxl.rst.
 
     The cxlflash driver supports two, mutually exclusive, modes of
     operation at the device (LUN) level:
@@ -58,7 +62,7 @@ Overview
 
     The CXL Flash Adapter Driver establishes a master context with the
     AFU. It uses memory mapped I/O (MMIO) for this control and setup. The
-    Adapter Problem Space Memory Map looks like this:
+    Adapter Problem Space Memory Map looks like this::
 
                      +-------------------------------+
                      |    512 * 64 KB User MMIO      |
@@ -375,7 +379,7 @@ CXL Flash Driver Host IOCTLs
     Each host adapter instance that is supported by the cxlflash driver
     has a special character device associated with it to enable a set of
     host management function. These character devices are hosted in a
-    class dedicated for cxlflash and can be accessed via /dev/cxlflash/*.
+    class dedicated for cxlflash and can be accessed via `/dev/cxlflash/*`.
 
     Applications can be written to perform various functions using the
     host ioctl APIs below.
diff --git a/Documentation/powerpc/DAWR-POWER9.txt b/Documentation/powerpc/dawr-power9.rst
similarity index 95%
rename from Documentation/powerpc/DAWR-POWER9.txt
rename to Documentation/powerpc/dawr-power9.rst
index ecdbb076438c..c96ab6befd9c 100644
--- a/Documentation/powerpc/DAWR-POWER9.txt
+++ b/Documentation/powerpc/dawr-power9.rst
@@ -1,10 +1,11 @@
+=====================
 DAWR issues on POWER9
-============================
+=====================
 
 On POWER9 the Data Address Watchpoint Register (DAWR) can cause a checkstop
 if it points to cache inhibited (CI) memory. Currently Linux has no way to
 disinguish CI memory when configuring the DAWR, so (for now) the DAWR is
-disabled by this commit:
+disabled by this commit::
 
     commit 9654153158d3e0684a1bdb76dbababdb7111d5a0
     Author: Michael Neuling <mikey@neuling.org>
@@ -12,7 +13,7 @@ disabled by this commit:
     powerpc: Disable DAWR in the base POWER9 CPU features
 
 Technical Details:
-============================
+==================
 
 DAWR has 6 different ways of being set.
 1) ptrace
@@ -37,7 +38,7 @@ DAWR on the migration.
 For xmon, the 'bd' command will return an error on P9.
 
 Consequences for users
-============================
+======================
 
 For GDB watchpoints (ie 'watch' command) on POWER9 bare metal , GDB
 will accept the command. Unfortunately since there is no hardware
@@ -57,8 +58,8 @@ trapped in GDB. The watchpoint is remembered, so if the guest is
 migrated back to the POWER8 host, it will start working again.
 
 Force enabling the DAWR
-=============================
-Kernels (since ~v5.2) have an option to force enable the DAWR via:
+=======================
+Kernels (since ~v5.2) have an option to force enable the DAWR via::
 
   echo Y > /sys/kernel/debug/powerpc/dawr_enable_dangerous
 
@@ -86,5 +87,7 @@ dawr_enable_dangerous file will fail if the hypervisor doesn't support
 writing the DAWR.
 
 To double check the DAWR is working, run this kernel selftest:
+
   tools/testing/selftests/powerpc/ptrace/ptrace-hwbreak.c
+
 Any errors/failures/skips mean something is wrong.
diff --git a/Documentation/powerpc/dscr.txt b/Documentation/powerpc/dscr.rst
similarity index 91%
rename from Documentation/powerpc/dscr.txt
rename to Documentation/powerpc/dscr.rst
index ece300c64f76..2ab99006014c 100644
--- a/Documentation/powerpc/dscr.txt
+++ b/Documentation/powerpc/dscr.rst
@@ -1,5 +1,6 @@
-			DSCR (Data Stream Control Register)
-		================================================
+===================================
+DSCR (Data Stream Control Register)
+===================================
 
 DSCR register in powerpc allows user to have some control of prefetch of data
 stream in the processor. Please refer to the ISA documents or related manual
@@ -10,14 +11,17 @@ user interface.
 
 (A) Data Structures:
 
-	(1) thread_struct:
+	(1) thread_struct::
+
 		dscr		/* Thread DSCR value */
 		dscr_inherit	/* Thread has changed default DSCR */
 
-	(2) PACA:
+	(2) PACA::
+
 		dscr_default	/* per-CPU DSCR default value */
 
-	(3) sysfs.c:
+	(3) sysfs.c::
+
 		dscr_default	/* System DSCR default value */
 
 (B) Scheduler Changes:
@@ -35,8 +39,8 @@ user interface.
 
 (C) SYSFS Interface:
 
-	Global DSCR default:		/sys/devices/system/cpu/dscr_default
-	CPU specific DSCR default:	/sys/devices/system/cpu/cpuN/dscr
+	- Global DSCR default:		/sys/devices/system/cpu/dscr_default
+	- CPU specific DSCR default:	/sys/devices/system/cpu/cpuN/dscr
 
 	Changing the global DSCR default in the sysfs will change all the CPU
 	specific DSCR defaults immediately in their PACA structures. Again if
diff --git a/Documentation/powerpc/eeh-pci-error-recovery.txt b/Documentation/powerpc/eeh-pci-error-recovery.rst
similarity index 82%
rename from Documentation/powerpc/eeh-pci-error-recovery.txt
rename to Documentation/powerpc/eeh-pci-error-recovery.rst
index 678189280bb4..438a87ebc095 100644
--- a/Documentation/powerpc/eeh-pci-error-recovery.txt
+++ b/Documentation/powerpc/eeh-pci-error-recovery.rst
@@ -1,10 +1,10 @@
+==========================
+PCI Bus EEH Error Recovery
+==========================
 
+Linas Vepstas <linas@austin.ibm.com>
 
-                      PCI Bus EEH Error Recovery
-                      --------------------------
-                           Linas Vepstas
-                       <linas@austin.ibm.com>
-                          12 January 2005
+12 January 2005
 
 
 Overview:
@@ -143,17 +143,17 @@ seen in /proc/ppc64/eeh (subject to change).  Normally, almost
 all of these occur during boot, when the PCI bus is scanned, where
 a large number of 0xff reads are part of the bus scan procedure.
 
-If a frozen slot is detected, code in 
-arch/powerpc/platforms/pseries/eeh.c will print a stack trace to 
-syslog (/var/log/messages).  This stack trace has proven to be very 
-useful to device-driver authors for finding out at what point the EEH 
-error was detected, as the error itself usually occurs slightly 
+If a frozen slot is detected, code in
+arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
+syslog (/var/log/messages).  This stack trace has proven to be very
+useful to device-driver authors for finding out at what point the EEH
+error was detected, as the error itself usually occurs slightly
 beforehand.
 
 Next, it uses the Linux kernel notifier chain/work queue mechanism to
 allow any interested parties to find out about the failure.  Device
 drivers, or other parts of the kernel, can use
-eeh_register_notifier(struct notifier_block *) to find out about EEH
+`eeh_register_notifier(struct notifier_block *)` to find out about EEH
 events.  The event will include a pointer to the pci device, the
 device node and some state info.  Receivers of the event can "do as
 they wish"; the default handler will be described further in this
@@ -162,10 +162,13 @@ section.
 To assist in the recovery of the device, eeh.c exports the
 following functions:
 
-rtas_set_slot_reset() -- assert the  PCI #RST line for 1/8th of a second
-rtas_configure_bridge() -- ask firmware to configure any PCI bridges
+rtas_set_slot_reset()
+   assert the  PCI #RST line for 1/8th of a second
+rtas_configure_bridge()
+   ask firmware to configure any PCI bridges
    located topologically under the pci slot.
-eeh_save_bars() and eeh_restore_bars(): save and restore the PCI
+eeh_save_bars() and eeh_restore_bars():
+   save and restore the PCI
    config-space info for a device and any devices under it.
 
 
@@ -191,7 +194,7 @@ events get delivered to user-space scripts.
 
 Following is an example sequence of events that cause a device driver
 close function to be called during the first phase of an EEH reset.
-The following sequence is an example of the pcnet32 device driver.
+The following sequence is an example of the pcnet32 device driver::
 
     rpa_php_unconfig_pci_adapter (struct slot *)  // in rpaphp_pci.c
     {
@@ -241,53 +244,54 @@ The following sequence is an example of the pcnet32 device driver.
      }}}}}}
 
 
-    in drivers/pci/pci_driver.c,
-    struct device_driver->remove() is just pci_device_remove()
-    which calls struct pci_driver->remove() which is pcnet32_remove_one()
-    which calls unregister_netdev()  (in net/core/dev.c)
-    which calls dev_close()  (in net/core/dev.c)
-    which calls dev->stop() which is pcnet32_close()
-    which then does the appropriate shutdown.
+in drivers/pci/pci_driver.c,
+struct device_driver->remove() is just pci_device_remove()
+which calls struct pci_driver->remove() which is pcnet32_remove_one()
+which calls unregister_netdev()  (in net/core/dev.c)
+which calls dev_close()  (in net/core/dev.c)
+which calls dev->stop() which is pcnet32_close()
+which then does the appropriate shutdown.
 
 ---
+
 Following is the analogous stack trace for events sent to user-space
-when the pci device is unconfigured.
+when the pci device is unconfigured::
 
-rpa_php_unconfig_pci_adapter() {             // in rpaphp_pci.c
-  calls
-  pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
+  rpa_php_unconfig_pci_adapter() {             // in rpaphp_pci.c
     calls
-    pci_destroy_dev (struct pci_dev *) {
+    pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
       calls
-      device_unregister (&dev->dev) {        // in /drivers/base/core.c
+      pci_destroy_dev (struct pci_dev *) {
         calls
-        device_del(struct device * dev) {    // in /drivers/base/core.c
+        device_unregister (&dev->dev) {        // in /drivers/base/core.c
           calls
-          kobject_del() {                    //in /libs/kobject.c
+          device_del(struct device * dev) {    // in /drivers/base/core.c
             calls
-            kobject_uevent() {               // in /libs/kobject.c
+            kobject_del() {                    //in /libs/kobject.c
               calls
-              kset_uevent() {                // in /lib/kobject.c
+              kobject_uevent() {               // in /libs/kobject.c
                 calls
-                kset->uevent_ops->uevent()   // which is really just
-                a call to
-                dev_uevent() {               // in /drivers/base/core.c
+                kset_uevent() {                // in /lib/kobject.c
                   calls
-                  dev->bus->uevent() which is really just a call to
-                  pci_uevent () {            // in drivers/pci/hotplug.c
-                    which prints device name, etc....
+                  kset->uevent_ops->uevent()   // which is really just
+                  a call to
+                  dev_uevent() {               // in /drivers/base/core.c
+                    calls
+                    dev->bus->uevent() which is really just a call to
+                    pci_uevent () {            // in drivers/pci/hotplug.c
+                      which prints device name, etc....
+                   }
                  }
-               }
-               then kobject_uevent() sends a netlink uevent to userspace
-               --> userspace uevent
-               (during early boot, nobody listens to netlink events and
-               kobject_uevent() executes uevent_helper[], which runs the
-               event process /sbin/hotplug)
+                 then kobject_uevent() sends a netlink uevent to userspace
+                 --> userspace uevent
+                 (during early boot, nobody listens to netlink events and
+                 kobject_uevent() executes uevent_helper[], which runs the
+                 event process /sbin/hotplug)
+             }
            }
-         }
-         kobject_del() then calls sysfs_remove_dir(), which would
-         trigger any user-space daemon that was watching /sysfs,
-         and notice the delete event.
+           kobject_del() then calls sysfs_remove_dir(), which would
+           trigger any user-space daemon that was watching /sysfs,
+           and notice the delete event.
 
 
 Pro's and Con's of the Current Design
@@ -299,12 +303,12 @@ individual device drivers, so that the current design throws a wide net.
 The biggest negative of the design is that it potentially disturbs
 network daemons and file systems that didn't need to be disturbed.
 
--- A minor complaint is that resetting the network card causes
+-  A minor complaint is that resetting the network card causes
    user-space back-to-back ifdown/ifup burps that potentially disturb
    network daemons, that didn't need to even know that the pci
    card was being rebooted.
 
--- A more serious concern is that the same reset, for SCSI devices,
+-  A more serious concern is that the same reset, for SCSI devices,
    causes havoc to mounted file systems.  Scripts cannot post-facto
    unmount a file system without flushing pending buffers, but this
    is impossible, because I/O has already been stopped.  Thus,
@@ -322,7 +326,7 @@ network daemons and file systems that didn't need to be disturbed.
    from the block layer.  It would be very natural to add an EEH
    reset into this chain of events.
 
--- If a SCSI error occurs for the root device, all is lost unless
+-  If a SCSI error occurs for the root device, all is lost unless
    the sysadmin had the foresight to run /bin, /sbin, /etc, /var
    and so on, out of ramdisk/tmpfs.
 
@@ -330,5 +334,3 @@ network daemons and file systems that didn't need to be disturbed.
 Conclusions
 -----------
 There's forward progress ...
-
-
diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.rst
similarity index 80%
rename from Documentation/powerpc/firmware-assisted-dump.txt
rename to Documentation/powerpc/firmware-assisted-dump.rst
index 10e7f4d16c14..9ca12830a48e 100644
--- a/Documentation/powerpc/firmware-assisted-dump.txt
+++ b/Documentation/powerpc/firmware-assisted-dump.rst
@@ -1,7 +1,8 @@
+======================
+Firmware-Assisted Dump
+======================
 
-                   Firmware-Assisted Dump
-                   ------------------------
-                       July 2011
+July 2011
 
 The goal of firmware-assisted dump is to enable the dump of
 a crashed system, and to do so from a fully-reset system, and
@@ -27,11 +28,11 @@ in production use.
 Comparing with kdump or other strategies, firmware-assisted
 dump offers several strong, practical advantages:
 
--- Unlike kdump, the system has been reset, and loaded
+-  Unlike kdump, the system has been reset, and loaded
    with a fresh copy of the kernel.  In particular,
    PCI and I/O devices have been reinitialized and are
    in a clean, consistent state.
--- Once the dump is copied out, the memory that held the dump
+-  Once the dump is copied out, the memory that held the dump
    is immediately available to the running kernel. And therefore,
    unlike kdump, fadump doesn't need a 2nd reboot to get back
    the system to the production configuration.
@@ -40,17 +41,18 @@ The above can only be accomplished by coordination with,
 and assistance from the Power firmware. The procedure is
 as follows:
 
--- The first kernel registers the sections of memory with the
+-  The first kernel registers the sections of memory with the
    Power firmware for dump preservation during OS initialization.
    These registered sections of memory are reserved by the first
    kernel during early boot.
 
--- When a system crashes, the Power firmware will save
+-  When a system crashes, the Power firmware will save
    the low memory (boot memory of size larger of 5% of system RAM
    or 256MB) of RAM to the previous registered region. It will
    also save system registers, and hardware PTE's.
 
-   NOTE: The term 'boot memory' means size of the low memory chunk
+   NOTE:
+         The term 'boot memory' means size of the low memory chunk
          that is required for a kernel to boot successfully when
          booted with restricted memory. By default, the boot memory
          size will be the larger of 5% of system RAM or 256MB.
@@ -64,12 +66,12 @@ as follows:
          as fadump uses a predefined offset to reserve memory
          for boot memory dump preservation in case of a crash.
 
--- After the low memory (boot memory) area has been saved, the
+-  After the low memory (boot memory) area has been saved, the
    firmware will reset PCI and other hardware state.  It will
    *not* clear the RAM. It will then launch the bootloader, as
    normal.
 
--- The freshly booted kernel will notice that there is a new
+-  The freshly booted kernel will notice that there is a new
    node (ibm,dump-kernel) in the device tree, indicating that
    there is crash data available from a previous boot. During
    the early boot OS will reserve rest of the memory above
@@ -77,17 +79,18 @@ as follows:
    size. This will make sure that the second kernel will not
    touch any of the dump memory area.
 
--- User-space tools will read /proc/vmcore to obtain the contents
+-  User-space tools will read /proc/vmcore to obtain the contents
    of memory, which holds the previous crashed kernel dump in ELF
    format. The userspace tools may copy this info to disk, or
    network, nas, san, iscsi, etc. as desired.
 
--- Once the userspace tool is done saving dump, it will echo
+-  Once the userspace tool is done saving dump, it will echo
    '1' to /sys/kernel/fadump_release_mem to release the reserved
    memory back to general use, except the memory required for
    next firmware-assisted dump registration.
 
-   e.g.
+   e.g.::
+
      # echo 1 > /sys/kernel/fadump_release_mem
 
 Please note that the firmware-assisted dump feature
@@ -95,7 +98,7 @@ is only available on Power6 and above systems with recent
 firmware versions.
 
 Implementation details:
-----------------------
+-----------------------
 
 During boot, a check is made to see if firmware supports
 this feature on that particular machine. If it does, then
@@ -121,7 +124,7 @@ Allocator (CMA) for memory reservation if CMA is configured for kernel.
 With CMA reservation this memory will be available for applications to
 use it, while kernel is prevented from using it. With this fadump will
 still be able to capture all of the kernel memory and most of the user
-space memory except the user pages that were present in CMA region.
+space memory except the user pages that were present in CMA region::
 
   o Memory Reservation during first kernel
 
@@ -166,7 +169,7 @@ The tools to examine the dump will be same as the ones
 used for kdump.
 
 How to enable firmware-assisted dump (fadump):
--------------------------------------
+----------------------------------------------
 
 1. Set config option CONFIG_FA_DUMP=y and build kernel.
 2. Boot into linux kernel with 'fadump=on' kernel cmdline option.
@@ -177,19 +180,20 @@ How to enable firmware-assisted dump (fadump):
    to specify size of the memory to reserve for boot memory dump
    preservation.
 
-NOTE: 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
-         use 'crashkernel=' to specify size of the memory to reserve
-         for boot memory dump preservation.
-      2. If firmware-assisted dump fails to reserve memory then it
-         will fallback to existing kdump mechanism if 'crashkernel='
-         option is set at kernel cmdline.
-      3. if user wants to capture all of user space memory and ok with
-         reserved memory not available to production system, then
-         'fadump=nocma' kernel parameter can be used to fallback to
-         old behaviour.
+NOTE:
+     1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
+        use 'crashkernel=' to specify size of the memory to reserve
+        for boot memory dump preservation.
+     2. If firmware-assisted dump fails to reserve memory then it
+        will fallback to existing kdump mechanism if 'crashkernel='
+        option is set at kernel cmdline.
+     3. if user wants to capture all of user space memory and ok with
+        reserved memory not available to production system, then
+        'fadump=nocma' kernel parameter can be used to fallback to
+        old behaviour.
 
 Sysfs/debugfs files:
-------------
+--------------------
 
 Firmware-assisted dump feature uses sysfs file system to hold
 the control files and debugfs file to display memory reserved region.
@@ -197,20 +201,20 @@ the control files and debugfs file to display memory reserved region.
 Here is the list of files under kernel sysfs:
 
  /sys/kernel/fadump_enabled
-
     This is used to display the fadump status.
-    0 = fadump is disabled
-    1 = fadump is enabled
+
+    - 0 = fadump is disabled
+    - 1 = fadump is enabled
 
     This interface can be used by kdump init scripts to identify if
     fadump is enabled in the kernel and act accordingly.
 
  /sys/kernel/fadump_registered
-
     This is used to display the fadump registration status as well
     as to control (start/stop) the fadump registration.
-    0 = fadump is not registered.
-    1 = fadump is registered and ready to handle system crash.
+
+    - 0 = fadump is not registered.
+    - 1 = fadump is registered and ready to handle system crash.
 
     To register fadump echo 1 > /sys/kernel/fadump_registered and
     echo 0 > /sys/kernel/fadump_registered for un-register and stop the
@@ -219,13 +223,12 @@ Here is the list of files under kernel sysfs:
     easily integrated with kdump service start/stop.
 
  /sys/kernel/fadump_release_mem
-
     This file is available only when fadump is active during
     second kernel. This is used to release the reserved memory
     region that are held for saving crash dump. To release the
-    reserved memory echo 1 to it:
+    reserved memory echo 1 to it::
 
-    echo 1  > /sys/kernel/fadump_release_mem
+	echo 1  > /sys/kernel/fadump_release_mem
 
     After echo 1, the content of the /sys/kernel/debug/powerpc/fadump_region
     file will change to reflect the new memory reservations.
@@ -238,38 +241,39 @@ Here is the list of files under powerpc debugfs:
 (Assuming debugfs is mounted on /sys/kernel/debug directory.)
 
  /sys/kernel/debug/powerpc/fadump_region
-
     This file shows the reserved memory regions if fadump is
     enabled otherwise this file is empty. The output format
-    is:
-    <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
+    is::
+
+      <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
 
     e.g.
-    Contents when fadump is registered during first kernel
+    Contents when fadump is registered during first kernel::
 
-    # cat /sys/kernel/debug/powerpc/fadump_region
-    CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
-    HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
-    DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
+      # cat /sys/kernel/debug/powerpc/fadump_region
+      CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
+      HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
+      DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
 
-    Contents when fadump is active during second kernel
+    Contents when fadump is active during second kernel::
 
-    # cat /sys/kernel/debug/powerpc/fadump_region
-    CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
-    HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
-    DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
-        : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
+      # cat /sys/kernel/debug/powerpc/fadump_region
+      CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
+      HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
+      DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
+          : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
 
-NOTE: Please refer to Documentation/filesystems/debugfs.txt on
+NOTE:
+      Please refer to Documentation/filesystems/debugfs.txt on
       how to mount the debugfs filesystem.
 
 
 TODO:
 -----
- o Need to come up with the better approach to find out more
+ - Need to come up with the better approach to find out more
    accurate boot memory size that is required for a kernel to
    boot successfully when booted with restricted memory.
- o The fadump implementation introduces a fadump crash info structure
+ - The fadump implementation introduces a fadump crash info structure
    in the scratch area before the ELF core header. The idea of introducing
    this structure is to pass some important crash info data to the second
    kernel which will help second kernel to populate ELF core header with
@@ -277,7 +281,9 @@ TODO:
    design implementation does not address a possibility of introducing
    additional fields (in future) to this structure without affecting
    compatibility. Need to come up with the better approach to address this.
+
    The possible approaches are:
+
 	1. Introduce version field for version tracking, bump up the version
 	whenever a new field is added to the structure in future. The version
 	field can be used to find out what fields are valid for the current
@@ -285,8 +291,11 @@ TODO:
 	2. Reserve the area of predefined size (say PAGE_SIZE) for this
 	structure and have unused area as reserved (initialized to zero)
 	for future field additions.
+
    The advantage of approach 1 over 2 is we don't need to reserve extra space.
----
+
 Author: Mahesh Salgaonkar <mahesh@linux.vnet.ibm.com>
+
 This document is based on the original documentation written for phyp
+
 assisted dump by Linas Vepstas and Manish Ahuja.
diff --git a/Documentation/powerpc/hvcs.txt b/Documentation/powerpc/hvcs.rst
similarity index 91%
rename from Documentation/powerpc/hvcs.txt
rename to Documentation/powerpc/hvcs.rst
index a730ca5a07f8..6808acde672f 100644
--- a/Documentation/powerpc/hvcs.txt
+++ b/Documentation/powerpc/hvcs.rst
@@ -1,19 +1,22 @@
-===========================================================================
-				   HVCS
-	IBM "Hypervisor Virtual Console Server" Installation Guide
-			  for Linux Kernel 2.6.4+
-		    Copyright (C) 2004 IBM Corporation
+===============================================================
+HVCS IBM "Hypervisor Virtual Console Server" Installation Guide
+===============================================================
 
-===========================================================================
-NOTE:Eight space tabs are the optimum editor setting for reading this file.
-===========================================================================
+for Linux Kernel 2.6.4+
 
-	       Author(s) :  Ryan S. Arnold <rsa@us.ibm.com>
-		       Date Created: March, 02, 2004
-		       Last Changed: August, 24, 2004
+Copyright (C) 2004 IBM Corporation
 
----------------------------------------------------------------------------
-Table of contents:
+.. ===========================================================================
+.. NOTE:Eight space tabs are the optimum editor setting for reading this file.
+.. ===========================================================================
+
+
+Author(s): Ryan S. Arnold <rsa@us.ibm.com>
+
+Date Created: March, 02, 2004
+Last Changed: August, 24, 2004
+
+.. Table of contents:
 
 	1.  Driver Introduction:
 	2.  System Requirements
@@ -27,8 +30,8 @@ Table of contents:
 	8.  Questions & Answers:
 	9.  Reporting Bugs:
 
----------------------------------------------------------------------------
 1. Driver Introduction:
+=======================
 
 This is the device driver for the IBM Hypervisor Virtual Console Server,
 "hvcs".  The IBM hvcs provides a tty driver interface to allow Linux user
@@ -38,8 +41,8 @@ ppc64 system.  Physical hardware consoles per partition are not practical
 on this hardware so system consoles are accessed by this driver using
 firmware interfaces to virtual terminal devices.
 
----------------------------------------------------------------------------
 2. System Requirements:
+=======================
 
 This device driver was written using 2.6.4 Linux kernel APIs and will only
 build and run on kernels of this version or later.
@@ -52,8 +55,8 @@ Sysfs must be mounted on the system so that the user can determine which
 major and minor numbers are associated with each vty-server.  Directions
 for sysfs mounting are outside the scope of this document.
 
----------------------------------------------------------------------------
 3. Build Options:
+=================
 
 The hvcs driver registers itself as a tty driver.  The tty layer
 dynamically allocates a block of major and minor numbers in a quantity
@@ -65,11 +68,11 @@ If the default number of device entries is adequate then this driver can be
 built into the kernel.  If not, the default can be over-ridden by inserting
 the driver as a module with insmod parameters.
 
----------------------------------------------------------------------------
 3.1 Built-in:
+-------------
 
 The following menuconfig example demonstrates selecting to build this
-driver into the kernel.
+driver into the kernel::
 
 	Device Drivers  --->
 		Character devices  --->
@@ -77,11 +80,11 @@ driver into the kernel.
 
 Begin the kernel make process.
 
----------------------------------------------------------------------------
 3.2 Module:
+-----------
 
 The following menuconfig example demonstrates selecting to build this
-driver as a kernel module.
+driver as a kernel module::
 
 	Device Drivers  --->
 		Character devices  --->
@@ -89,11 +92,11 @@ driver as a kernel module.
 
 The make process will build the following kernel modules:
 
-	hvcs.ko
-	hvcserver.ko
+	- hvcs.ko
+	- hvcserver.ko
 
 To insert the module with the default allocation execute the following
-commands in the order they appear:
+commands in the order they appear::
 
 	insmod hvcserver.ko
 	insmod hvcs.ko
@@ -103,7 +106,7 @@ be inserted first, otherwise the hvcs module will not find some of the
 symbols it expects.
 
 To override the default use an insmod parameter as follows (requesting 4
-tty devices as an example):
+tty devices as an example)::
 
 	insmod hvcs.ko hvcs_parm_num_devs=4
 
@@ -115,31 +118,31 @@ source file before building.
 NOTE: The length of time it takes to insmod the driver seems to be related
 to the number of tty interfaces the registering driver requests.
 
-In order to remove the driver module execute the following command:
+In order to remove the driver module execute the following command::
 
 	rmmod hvcs.ko
 
 The recommended method for installing hvcs as a module is to use depmod to
 build a current modules.dep file in /lib/modules/`uname -r` and then
-execute:
+execute::
 
-modprobe hvcs hvcs_parm_num_devs=4
+	modprobe hvcs hvcs_parm_num_devs=4
 
 The modules.dep file indicates that hvcserver.ko needs to be inserted
 before hvcs.ko and modprobe uses this file to smartly insert the modules in
 the proper order.
 
 The following modprobe command is used to remove hvcs and hvcserver in the
-proper order:
+proper order::
 
-modprobe -r hvcs
+	modprobe -r hvcs
 
----------------------------------------------------------------------------
 4. Installation:
+================
 
 The tty layer creates sysfs entries which contain the major and minor
 numbers allocated for the hvcs driver.  The following snippet of "tree"
-output of the sysfs directory shows where these numbers are presented:
+output of the sysfs directory shows where these numbers are presented::
 
 	sys/
 	|-- *other sysfs base dirs*
@@ -164,7 +167,7 @@ output of the sysfs directory shows where these numbers are presented:
 	|-- *other sysfs base dirs*
 
 For the above examples the following output is a result of cat'ing the
-"dev" entry in the hvcs directory:
+"dev" entry in the hvcs directory::
 
 	Pow5:/sys/class/tty/hvcs0/ # cat dev
 	254:0
@@ -184,7 +187,7 @@ systems running hvcs will already have the device entries created or udev
 will do it automatically.
 
 Given the example output above, to manually create a /dev/hvcs* node entry
-mknod can be used as follows:
+mknod can be used as follows::
 
 	mknod /dev/hvcs0 c 254 0
 	mknod /dev/hvcs1 c 254 1
@@ -195,15 +198,15 @@ Using mknod to manually create the device entries makes these device nodes
 persistent.  Once created they will exist prior to the driver insmod.
 
 Attempting to connect an application to /dev/hvcs* prior to insertion of
-the hvcs module will result in an error message similar to the following:
+the hvcs module will result in an error message similar to the following::
 
 	"/dev/hvcs*: No such device".
 
 NOTE: Just because there is a device node present doesn't mean that there
 is a vty-server device configured for that node.
 
----------------------------------------------------------------------------
 5. Connection
+=============
 
 Since this driver controls devices that provide a tty interface a user can
 interact with the device node entries using any standard tty-interactive
@@ -249,7 +252,7 @@ vty-server adapter is associated with which /dev/hvcs* node a special sysfs
 attribute has been added to each vty-server sysfs entry.  This entry is
 called "index" and showing it reveals an integer that refers to the
 /dev/hvcs* entry to use to connect to that device.  For instance cating the
-index attribute of vty-server adapter 30000004 shows the following.
+index attribute of vty-server adapter 30000004 shows the following::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
 	2
@@ -262,8 +265,8 @@ system the /dev/hvcs* entry that interacts with a particular vty-server
 adapter is not guaranteed to remain the same across system reboots.  Look
 in the Q & A section for more on this issue.
 
----------------------------------------------------------------------------
 6. Disconnection
+================
 
 As a security feature to prevent the delivery of stale data to an
 unintended target the Power5 system firmware disables the fetching of data
@@ -305,7 +308,7 @@ connection between the vty-server and target vty ONLY if the vterm_state
 previously read '1'.  The write directive is ignored if the vterm_state
 read '0' or if any value other than '0' was written to the vterm_state
 attribute.  The following example will show the method used for verifying
-the vty-server connection status and disconnecting a vty-server connection.
+the vty-server connection status and disconnecting a vty-server connection::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
 	1
@@ -318,12 +321,12 @@ the vty-server connection status and disconnecting a vty-server connection.
 All vty-server connections are automatically terminated when the device is
 hotplug removed and when the module is removed.
 
----------------------------------------------------------------------------
 7. Configuration
+================
 
 Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
 is symlinked in several other sysfs tree directories, notably under the
-hvcs driver entry, which looks like the following example:
+hvcs driver entry, which looks like the following example::
 
 	Pow5:/sys/bus/vio/drivers/hvcs # ls
 	.  ..  30000003  30000004  rescan
@@ -344,7 +347,7 @@ completed or was never executed.
 
 Vty-server entries in this directory are a 32 bit partition unique unit
 address that is created by firmware.  An example vty-server sysfs entry
-looks like the following:
+looks like the following::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
 	.   current_vty   devspec       name          partner_vtys
@@ -352,21 +355,21 @@ looks like the following:
 
 Each entry is provided, by default with a "name" attribute.  Reading the
 "name" attribute will reveal the device type as shown in the following
-example:
+example::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
 	vty-server
 
 Each entry is also provided, by default, with a "devspec" attribute which
 reveals the full device specification when read, as shown in the following
-example:
+example::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
 	/vdevice/vty-server@30000004
 
 Each vty-server sysfs dir is provided with two read-only attributes that
 provide lists of easily parsed partner vty data: "partner_vtys" and
-"partner_clcs".
+"partner_clcs"::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
 	30000000
@@ -396,7 +399,7 @@ A vty-server can only be connected to a single vty at a time.  The entry,
 read.
 
 The current_vty can be changed by writing a valid partner clc to the entry
-as in the following example:
+as in the following example::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
 	8A-V4-C0 > current_vty
@@ -408,9 +411,9 @@ currently open connection is freed.
 Information on the "vterm_state" attribute was covered earlier on the
 chapter entitled "disconnection".
 
----------------------------------------------------------------------------
 8. Questions & Answers:
-===========================================================================
+=======================
+
 Q: What are the security concerns involving hvcs?
 
 A: There are three main security concerns:
@@ -429,6 +432,7 @@ A: There are three main security concerns:
 	partition) will experience the previously logged in session.
 
 ---------------------------------------------------------------------------
+
 Q: How do I multiplex a console that I grab through hvcs so that other
 people can see it:
 
@@ -440,6 +444,7 @@ term type "screen" to others.  This means that curses based programs may
 not display properly in screen sessions.
 
 ---------------------------------------------------------------------------
+
 Q: Why are the colors all messed up?
 Q: Why are the control characters acting strange or not working?
 Q: Why is the console output all strange and unintelligible?
@@ -455,6 +460,7 @@ disconnect from the console.  This will ensure that the next user gets
 their own TERM type set when they login.
 
 ---------------------------------------------------------------------------
+
 Q: When I try to CONNECT kermit to an hvcs device I get:
 "Sorry, can't open connection: /dev/hvcs*"What is happening?
 
@@ -490,6 +496,7 @@ A: There is not a corresponding vty-server device that maps to an existing
 /dev/hvcs* entry.
 
 ---------------------------------------------------------------------------
+
 Q: When I try to CONNECT kermit to an hvcs device I get:
 "Sorry, write access to UUCP lockfile directory denied."
 
@@ -497,6 +504,7 @@ A: The /dev/hvcs* entry you have specified doesn't exist where you said it
 does?  Maybe you haven't inserted the module (on systems with udev).
 
 ---------------------------------------------------------------------------
+
 Q: If I already have one Linux partition installed can I use hvcs on said
 partition to provide the console for the install of a second Linux
 partition?
@@ -505,6 +513,7 @@ A: Yes granted that your are connected to the /dev/hvcs* device using
 kermit or cu or some other program that doesn't provide terminal emulation.
 
 ---------------------------------------------------------------------------
+
 Q: Can I connect to more than one partition's console at a time using this
 driver?
 
@@ -512,6 +521,7 @@ A: Yes.  Of course this means that there must be more than one vty-server
 configured for this partition and each must point to a disconnected vty.
 
 ---------------------------------------------------------------------------
+
 Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
 
 A: Yes, if you have dlpar and hotplug enabled for your system and it has
@@ -519,6 +529,7 @@ been built into the kernel the hvcs drivers is configured to dynamically
 handle additions of new devices and removals of unused devices.
 
 ---------------------------------------------------------------------------
+
 Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
 after a reboot.  What happened?
 
@@ -533,6 +544,7 @@ on how to determine which vty-server goes with which /dev/hvcs* node.
 Hint; look at the sysfs "index" attribute for the vty-server.
 
 ---------------------------------------------------------------------------
+
 Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
 device on that partition as the other end of the pipe?
 
@@ -554,7 +566,9 @@ read or write to /dev/hvcs*.  Now you have a tty conduit between two
 partitions.
 
 ---------------------------------------------------------------------------
+
 9. Reporting Bugs:
+==================
 
 The proper channel for reporting bugs is either through the Linux OS
 distribution company that provided your OS or by posting issues to the
diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst
new file mode 100644
index 000000000000..549b1cdd77ae
--- /dev/null
+++ b/Documentation/powerpc/index.rst
@@ -0,0 +1,34 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======
+powerpc
+=======
+
+.. toctree::
+    :maxdepth: 1
+
+    bootwrapper
+    cpu_families
+    cpu_features
+    cxl
+    cxlflash
+    dawr-power9
+    dscr
+    eeh-pci-error-recovery
+    firmware-assisted-dump
+    hvcs
+    isa-versions
+    mpc52xx
+    pci_iov_resource_on_powernv
+    pmu-ebb
+    ptrace
+    qe_firmware
+    syscall64-abi
+    transactional_memory
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/powerpc/isa-versions.rst
index 66c24140ebf1..a363d8c1603c 100644
--- a/Documentation/powerpc/isa-versions.rst
+++ b/Documentation/powerpc/isa-versions.rst
@@ -1,13 +1,12 @@
-:orphan:
-
+==========================
 CPU to ISA Version Mapping
 ==========================
 
 Mapping of some CPU versions to relevant ISA versions.
 
-========= ====================
+========= ====================================================================
 CPU       Architecture version
-========= ====================
+========= ====================================================================
 Power9    Power ISA v3.0B
 Power8    Power ISA v2.07
 Power7    Power ISA v2.06
@@ -24,7 +23,7 @@ PPC970    - PowerPC User Instruction Set Architecture Book I v2.01
           - PowerPC Virtual Environment Architecture Book II v2.01
           - PowerPC Operating Environment Architecture Book III v2.01
           - Plus Altivec/VMX ~= 2.03
-========= ====================
+========= ====================================================================
 
 
 Key Features
@@ -60,9 +59,9 @@ Power5     No
 PPC970     No
 ========== ====
 
-========== ====================
+========== ====================================
 CPU        Transactional Memory
-========== ====================
+========== ====================================
 Power9     Yes (* see transactional_memory.txt)
 Power8     Yes
 Power7     No
@@ -73,4 +72,4 @@ Power5++   No
 Power5+    No
 Power5     No
 PPC970     No
-========== ====================
+========== ====================================
diff --git a/Documentation/powerpc/mpc52xx.txt b/Documentation/powerpc/mpc52xx.rst
similarity index 91%
rename from Documentation/powerpc/mpc52xx.txt
rename to Documentation/powerpc/mpc52xx.rst
index 0d540a31ea1a..8676ac63e077 100644
--- a/Documentation/powerpc/mpc52xx.txt
+++ b/Documentation/powerpc/mpc52xx.rst
@@ -1,11 +1,13 @@
+=============================
 Linux 2.6.x on MPC52xx family
------------------------------
+=============================
 
 For the latest info, go to http://www.246tNt.com/mpc52xx/
 
 To compile/use :
 
-  - U-Boot:
+  - U-Boot::
+
      # <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
         if you wish to ).
      # make lite5200_defconfig
@@ -16,7 +18,8 @@ To compile/use :
      => tftpboot 400000 pRamdisk
      => bootm 200000 400000
 
-  - DBug:
+  - DBug::
+
      # <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
         if you wish to ).
      # make lite5200_defconfig
@@ -28,7 +31,8 @@ To compile/use :
      DBug> dn -i zImage.initrd.lite5200
 
 
-Some remarks :
+Some remarks:
+
  - The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100
    is not supported, and I'm not sure anyone is interesting in working on it
    so. I didn't took 5xxx because there's apparently a lot of 5xxx that have
diff --git a/Documentation/powerpc/pci_iov_resource_on_powernv.txt b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
similarity index 97%
rename from Documentation/powerpc/pci_iov_resource_on_powernv.txt
rename to Documentation/powerpc/pci_iov_resource_on_powernv.rst
index b55c5cd83f8d..f5a5793e1613 100644
--- a/Documentation/powerpc/pci_iov_resource_on_powernv.txt
+++ b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
@@ -1,6 +1,13 @@
+===================================================
+PCI Express I/O Virtualization Resource on Powerenv
+===================================================
+
 Wei Yang <weiyang@linux.vnet.ibm.com>
+
 Benjamin Herrenschmidt <benh@au1.ibm.com>
+
 Bjorn Helgaas <bhelgaas@google.com>
+
 26 Aug 2014
 
 This document describes the requirement from hardware for PCI MMIO resource
@@ -10,6 +17,7 @@ Endpoints and the implementation on P8 (IODA2). The next two sections talks
 about considerations on enabling SRIOV on IODA2.
 
 1. Introduction to Partitionable Endpoints
+==========================================
 
 A Partitionable Endpoint (PE) is a way to group the various resources
 associated with a device or a set of devices to provide isolation between
@@ -35,6 +43,7 @@ is a completely separate HW entity that replicates the entire logic, so has
 its own set of PEs, etc.
 
 2. Implementation of Partitionable Endpoints on P8 (IODA2)
+==========================================================
 
 P8 supports up to 256 Partitionable Endpoints per PHB.
 
@@ -149,6 +158,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
     sense, but we haven't done it yet.
 
 3. Considerations for SR-IOV on PowerKVM
+========================================
 
   * SR-IOV Background
 
@@ -224,7 +234,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
   IODA supports 256 PEs, so segmented windows contain 256 segments, so if
   total_VFs is less than 256, we have the situation in Figure 1.0, where
   segments [total_VFs, 255] of the M64 window may map to some MMIO range on
-  other devices:
+  other devices::
 
      0      1                     total_VFs - 1
      +------+------+-     -+------+------+
@@ -243,7 +253,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
 		Figure 1.0 Direct map VF(n) BAR space
 
   Our current solution is to allocate 256 segments even if the VF(n) BAR
-  space doesn't need that much, as shown in Figure 1.1:
+  space doesn't need that much, as shown in Figure 1.1::
 
      0      1                     total_VFs - 1                255
      +------+------+-     -+------+------+-      -+------+------+
@@ -269,6 +279,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
   responds to segments [total_VFs, 255].
 
 4. Implications for the Generic PCI Code
+========================================
 
 The PCIe SR-IOV spec requires that the base of the VF(n) BAR space be
 aligned to the size of an individual VF BAR.
diff --git a/Documentation/powerpc/pmu-ebb.txt b/Documentation/powerpc/pmu-ebb.rst
similarity index 99%
rename from Documentation/powerpc/pmu-ebb.txt
rename to Documentation/powerpc/pmu-ebb.rst
index 73cd163dbfb8..4f474758eb55 100644
--- a/Documentation/powerpc/pmu-ebb.txt
+++ b/Documentation/powerpc/pmu-ebb.rst
@@ -1,3 +1,4 @@
+========================
 PMU Event Based Branches
 ========================
 
diff --git a/Documentation/powerpc/ptrace.txt b/Documentation/powerpc/ptrace.rst
similarity index 48%
rename from Documentation/powerpc/ptrace.txt
rename to Documentation/powerpc/ptrace.rst
index 99c5ce88d0fe..864d4b6dddd1 100644
--- a/Documentation/powerpc/ptrace.txt
+++ b/Documentation/powerpc/ptrace.rst
@@ -1,3 +1,7 @@
+======
+Ptrace
+======
+
 GDB intends to support the following hardware debug features of BookE
 processors:
 
@@ -12,6 +16,7 @@ that GDB doesn't need to special-case each of them. We added the
 following 3 new ptrace requests.
 
 1. PTRACE_PPC_GETHWDEBUGINFO
+============================
 
 Query for GDB to discover the hardware debug features. The main info to
 be returned here is the minimum alignment for the hardware watchpoints.
@@ -22,9 +27,9 @@ adding special cases to GDB based on what it sees in AUXV.
 Since we're at it, we added other useful info that the kernel can return to
 GDB: this query will return the number of hardware breakpoints, hardware
 watchpoints and whether it supports a range of addresses and a condition.
-The query will fill the following structure provided by the requesting process:
+The query will fill the following structure provided by the requesting process::
 
-struct ppc_debug_info {
+  struct ppc_debug_info {
        unit32_t version;
        unit32_t num_instruction_bps;
        unit32_t num_data_bps;
@@ -32,46 +37,46 @@ struct ppc_debug_info {
        unit32_t data_bp_alignment;
        unit32_t sizeof_condition; /* size of the DVC register */
        uint64_t features; /* bitmask of the individual flags */
-};
+  };
 
-features will have bits indicating whether there is support for:
+features will have bits indicating whether there is support for::
 
-#define PPC_DEBUG_FEATURE_INSN_BP_RANGE		0x1
-#define PPC_DEBUG_FEATURE_INSN_BP_MASK		0x2
-#define PPC_DEBUG_FEATURE_DATA_BP_RANGE		0x4
-#define PPC_DEBUG_FEATURE_DATA_BP_MASK		0x8
-#define PPC_DEBUG_FEATURE_DATA_BP_DAWR		0x10
+  #define PPC_DEBUG_FEATURE_INSN_BP_RANGE		0x1
+  #define PPC_DEBUG_FEATURE_INSN_BP_MASK		0x2
+  #define PPC_DEBUG_FEATURE_DATA_BP_RANGE		0x4
+  #define PPC_DEBUG_FEATURE_DATA_BP_MASK		0x8
+  #define PPC_DEBUG_FEATURE_DATA_BP_DAWR		0x10
 
 2. PTRACE_SETHWDEBUG
 
-Sets a hardware breakpoint or watchpoint, according to the provided structure:
+Sets a hardware breakpoint or watchpoint, according to the provided structure::
 
-struct ppc_hw_breakpoint {
+  struct ppc_hw_breakpoint {
         uint32_t version;
-#define PPC_BREAKPOINT_TRIGGER_EXECUTE  0x1
-#define PPC_BREAKPOINT_TRIGGER_READ     0x2
-#define PPC_BREAKPOINT_TRIGGER_WRITE    0x4
+  #define PPC_BREAKPOINT_TRIGGER_EXECUTE  0x1
+  #define PPC_BREAKPOINT_TRIGGER_READ     0x2
+ #define PPC_BREAKPOINT_TRIGGER_WRITE    0x4
         uint32_t trigger_type;       /* only some combinations allowed */
-#define PPC_BREAKPOINT_MODE_EXACT               0x0
-#define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE     0x1
-#define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE     0x2
-#define PPC_BREAKPOINT_MODE_MASK                0x3
+  #define PPC_BREAKPOINT_MODE_EXACT               0x0
+  #define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE     0x1
+  #define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE     0x2
+  #define PPC_BREAKPOINT_MODE_MASK                0x3
         uint32_t addr_mode;          /* address match mode */
 
-#define PPC_BREAKPOINT_CONDITION_MODE   0x3
-#define PPC_BREAKPOINT_CONDITION_NONE   0x0
-#define PPC_BREAKPOINT_CONDITION_AND    0x1
-#define PPC_BREAKPOINT_CONDITION_EXACT  0x1	/* different name for the same thing as above */
-#define PPC_BREAKPOINT_CONDITION_OR     0x2
-#define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
-#define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000	/* byte enable bits */
-#define PPC_BREAKPOINT_CONDITION_BE(n)  (1<<((n)+16))
+  #define PPC_BREAKPOINT_CONDITION_MODE   0x3
+  #define PPC_BREAKPOINT_CONDITION_NONE   0x0
+  #define PPC_BREAKPOINT_CONDITION_AND    0x1
+  #define PPC_BREAKPOINT_CONDITION_EXACT  0x1	/* different name for the same thing as above */
+  #define PPC_BREAKPOINT_CONDITION_OR     0x2
+  #define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
+  #define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000	/* byte enable bits */
+  #define PPC_BREAKPOINT_CONDITION_BE(n)  (1<<((n)+16))
         uint32_t condition_mode;     /* break/watchpoint condition flags */
 
         uint64_t addr;
         uint64_t addr2;
         uint64_t condition_value;
-};
+  };
 
 A request specifies one event, not necessarily just one register to be set.
 For instance, if the request is for a watchpoint with a condition, both the
@@ -88,61 +93,61 @@ can't be allocated on the registers.
 
 Some examples of using the structure to:
 
-- set a breakpoint in the first breakpoint register
-
-  p.version         = PPC_DEBUG_CURRENT_VERSION;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_EXECUTE;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
-  p.addr            = (uint64_t) address;
-  p.addr2           = 0;
-  p.condition_value = 0;
-
-- set a watchpoint which triggers on reads in the second watchpoint register
-
-  p.version         = PPC_DEBUG_CURRENT_VERSION;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_READ;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
-  p.addr            = (uint64_t) address;
-  p.addr2           = 0;
-  p.condition_value = 0;
-
-- set a watchpoint which triggers only with a specific value
-
-  p.version         = PPC_DEBUG_CURRENT_VERSION;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_READ;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
-  p.addr            = (uint64_t) address;
-  p.addr2           = 0;
-  p.condition_value = (uint64_t) condition;
-
-- set a ranged hardware breakpoint
-
-  p.version         = PPC_DEBUG_CURRENT_VERSION;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_EXECUTE;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
-  p.addr            = (uint64_t) begin_range;
-  p.addr2           = (uint64_t) end_range;
-  p.condition_value = 0;
-
-- set a watchpoint in server processors (BookS)
-
-  p.version         = 1;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_RW;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
-  or
-  p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
-
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
-  p.addr            = (uint64_t) begin_range;
-  /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
-   * addr2 - addr <= 8 Bytes.
-   */
-  p.addr2           = (uint64_t) end_range;
-  p.condition_value = 0;
+- set a breakpoint in the first breakpoint register::
+
+    p.version         = PPC_DEBUG_CURRENT_VERSION;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
+    p.addr            = (uint64_t) address;
+    p.addr2           = 0;
+    p.condition_value = 0;
+
+- set a watchpoint which triggers on reads in the second watchpoint register::
+
+    p.version         = PPC_DEBUG_CURRENT_VERSION;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_READ;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
+    p.addr            = (uint64_t) address;
+    p.addr2           = 0;
+    p.condition_value = 0;
+
+- set a watchpoint which triggers only with a specific value::
+
+    p.version         = PPC_DEBUG_CURRENT_VERSION;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_READ;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
+    p.addr            = (uint64_t) address;
+    p.addr2           = 0;
+    p.condition_value = (uint64_t) condition;
+
+- set a ranged hardware breakpoint::
+
+    p.version         = PPC_DEBUG_CURRENT_VERSION;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
+    p.addr            = (uint64_t) begin_range;
+    p.addr2           = (uint64_t) end_range;
+    p.condition_value = 0;
+
+- set a watchpoint in server processors (BookS)::
+
+    p.version         = 1;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_RW;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+    or
+    p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
+
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
+    p.addr            = (uint64_t) begin_range;
+    /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
+     * addr2 - addr <= 8 Bytes.
+     */
+    p.addr2           = (uint64_t) end_range;
+    p.condition_value = 0;
 
 3. PTRACE_DELHWDEBUG
 
diff --git a/Documentation/powerpc/qe_firmware.txt b/Documentation/powerpc/qe_firmware.rst
similarity index 95%
rename from Documentation/powerpc/qe_firmware.txt
rename to Documentation/powerpc/qe_firmware.rst
index e7ac24aec4ff..42f5103140c9 100644
--- a/Documentation/powerpc/qe_firmware.txt
+++ b/Documentation/powerpc/qe_firmware.rst
@@ -1,23 +1,23 @@
-	   Freescale QUICC Engine Firmware Uploading
-	   -----------------------------------------
+=========================================
+Freescale QUICC Engine Firmware Uploading
+=========================================
 
 (c) 2007 Timur Tabi <timur at freescale.com>,
     Freescale Semiconductor
 
-Table of Contents
-=================
+.. Table of Contents
 
-  I - Software License for Firmware
+   I - Software License for Firmware
 
-  II - Microcode Availability
+   II - Microcode Availability
 
-  III - Description and Terminology
+   III - Description and Terminology
 
-  IV - Microcode Programming Details
+   IV - Microcode Programming Details
 
-  V - Firmware Structure Layout
+   V - Firmware Structure Layout
 
-  VI - Sample Code for Creating Firmware Files
+   VI - Sample Code for Creating Firmware Files
 
 Revision Information
 ====================
@@ -39,7 +39,7 @@ http://opensource.freescale.com.  For other firmware files, please contact
 your Freescale representative or your operating system vendor.
 
 III - Description and Terminology
-================================
+=================================
 
 In this document, the term 'microcode' refers to the sequence of 32-bit
 integers that compose the actual QE microcode.
@@ -89,7 +89,7 @@ being fixed in the RAM package utilizing they should be activated.  This data
 structure signals the microcode which of these virtual traps is active.
 
 This structure contains 6 words that the application should copy to some
-specific been defined.  This table describes the structure.
+specific been defined.  This table describes the structure::
 
 	---------------------------------------------------------------
 	| Offset in |                  | Destination Offset | Size of |
@@ -119,7 +119,7 @@ Extended Modes
 This is a double word bit array (64 bits) that defines special functionality
 which has an impact on the software drivers.  Each bit has its own impact
 and has special instructions for the s/w associated with it.  This structure is
-described in this table:
+described in this table::
 
 	-----------------------------------------------------------------------
 	| Bit #  |     Name     |   Description                               |
@@ -220,7 +220,8 @@ The 'model' field is a 16-bit number that matches the actual SOC. The
 'major' and 'minor' fields are the major and minor revision numbers,
 respectively, of the SOC.
 
-For example, to match the 8323, revision 1.0:
+For example, to match the 8323, revision 1.0::
+
      soc.model = 8323
      soc.major = 1
      soc.minor = 0
@@ -273,10 +274,10 @@ library and available to any driver that calles qe_get_firmware_info().
 	'reserved'.
 
 After the last microcode is a 32-bit CRC.  It can be calculated using
-this algorithm:
+this algorithm::
 
-u32 crc32(const u8 *p, unsigned int len)
-{
+  u32 crc32(const u8 *p, unsigned int len)
+  {
 	unsigned int i;
 	u32 crc = 0;
 
@@ -286,7 +287,7 @@ u32 crc32(const u8 *p, unsigned int len)
 		   crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
 	}
 	return crc;
-}
+  }
 
 VI - Sample Code for Creating Firmware Files
 ============================================
diff --git a/Documentation/powerpc/syscall64-abi.txt b/Documentation/powerpc/syscall64-abi.rst
similarity index 82%
rename from Documentation/powerpc/syscall64-abi.txt
rename to Documentation/powerpc/syscall64-abi.rst
index fa716a0d88bd..e49f69f941b9 100644
--- a/Documentation/powerpc/syscall64-abi.txt
+++ b/Documentation/powerpc/syscall64-abi.rst
@@ -5,12 +5,12 @@ Power Architecture 64-bit Linux system call ABI
 syscall
 =======
 
-syscall calling sequence[*] matches the Power Architecture 64-bit ELF ABI
+syscall calling sequence\ [1]_ matches the Power Architecture 64-bit ELF ABI
 specification C function calling sequence, including register preservation
 rules, with the following differences.
 
-[*] Some syscalls (typically low-level management functions) may have
-    different calling sequences (e.g., rt_sigreturn).
+.. [1] Some syscalls (typically low-level management functions) may have
+       different calling sequences (e.g., rt_sigreturn).
 
 Parameters and return value
 ---------------------------
@@ -33,12 +33,14 @@ Register preservation rules
 Register preservation rules match the ELF ABI calling sequence with the
 following differences:
 
-r0:         Volatile.   (System call number.)
-r3:         Volatile.   (Parameter 1, and return value.)
-r4-r8:      Volatile.   (Parameters 2-6.)
-cr0:        Volatile    (cr0.SO is the return error condition)
-cr1, cr5-7: Nonvolatile.
-lr:         Nonvolatile.
+=========== ============= ========================================
+r0          Volatile      (System call number.)
+r3          Volatile      (Parameter 1, and return value.)
+r4-r8       Volatile      (Parameters 2-6.)
+cr0         Volatile      (cr0.SO is the return error condition)
+cr1, cr5-7  Nonvolatile
+lr          Nonvolatile
+=========== ============= ========================================
 
 All floating point and vector data registers as well as control and status
 registers are nonvolatile.
@@ -90,9 +92,12 @@ The vsyscall may or may not use the caller's stack frame save areas.
 
 Register preservation rules
 ---------------------------
-r0: Volatile.
-cr1, cr5-7: Volatile.
-lr: Volatile.
+
+=========== ========
+r0          Volatile
+cr1, cr5-7  Volatile
+lr          Volatile
+=========== ========
 
 Invocation
 ----------
diff --git a/Documentation/powerpc/transactional_memory.txt b/Documentation/powerpc/transactional_memory.rst
similarity index 93%
rename from Documentation/powerpc/transactional_memory.txt
rename to Documentation/powerpc/transactional_memory.rst
index 52c023e14f26..09955103acb4 100644
--- a/Documentation/powerpc/transactional_memory.txt
+++ b/Documentation/powerpc/transactional_memory.rst
@@ -1,3 +1,4 @@
+============================
 Transactional Memory support
 ============================
 
@@ -17,29 +18,29 @@ instructions are presented to delimit transactions; transactions are
 guaranteed to either complete atomically or roll back and undo any partial
 changes.
 
-A simple transaction looks like this:
+A simple transaction looks like this::
 
-begin_move_money:
-  tbegin
-  beq   abort_handler
+  begin_move_money:
+    tbegin
+    beq   abort_handler
 
-  ld    r4, SAVINGS_ACCT(r3)
-  ld    r5, CURRENT_ACCT(r3)
-  subi  r5, r5, 1
-  addi  r4, r4, 1
-  std   r4, SAVINGS_ACCT(r3)
-  std   r5, CURRENT_ACCT(r3)
+    ld    r4, SAVINGS_ACCT(r3)
+    ld    r5, CURRENT_ACCT(r3)
+    subi  r5, r5, 1
+    addi  r4, r4, 1
+    std   r4, SAVINGS_ACCT(r3)
+    std   r5, CURRENT_ACCT(r3)
 
-  tend
+    tend
 
-  b     continue
+    b     continue
 
-abort_handler:
-  ... test for odd failures ...
+  abort_handler:
+    ... test for odd failures ...
 
-  /* Retry the transaction if it failed because it conflicted with
-   * someone else: */
-  b     begin_move_money
+    /* Retry the transaction if it failed because it conflicted with
+     * someone else: */
+    b     begin_move_money
 
 
 The 'tbegin' instruction denotes the start point, and 'tend' the end point.
@@ -123,7 +124,7 @@ Transaction-aware signal handlers can read the transactional register state
 from the second ucontext.  This will be necessary for crash handlers to
 determine, for example, the address of the instruction causing the SIGSEGV.
 
-Example signal handler:
+Example signal handler::
 
     void crash_handler(int sig, siginfo_t *si, void *uc)
     {
@@ -133,9 +134,9 @@ Example signal handler:
       if (ucp_link) {
         u64 msr = ucp->uc_mcontext.regs->msr;
         /* May have transactional ucontext! */
-#ifndef __powerpc64__
+  #ifndef __powerpc64__
         msr |= ((u64)transactional_ucp->uc_mcontext.regs->msr) << 32;
-#endif
+  #endif
         if (MSR_TM_ACTIVE(msr)) {
            /* Yes, we crashed during a transaction.  Oops. */
    fprintf(stderr, "Transaction to be restarted at 0x%llx, but "
@@ -176,6 +177,7 @@ Failure cause codes used by kernel
 These are defined in <asm/reg.h>, and distinguish different reasons why the
 kernel aborted a transaction:
 
+ ====================== ================================
  TM_CAUSE_RESCHED       Thread was rescheduled.
  TM_CAUSE_TLBI          Software TLB invalid.
  TM_CAUSE_FAC_UNAV      FP/VEC/VSX unavailable trap.
@@ -184,6 +186,7 @@ kernel aborted a transaction:
  TM_CAUSE_MISC          Currently unused.
  TM_CAUSE_ALIGNMENT     Alignment fault.
  TM_CAUSE_EMULATE       Emulation that touched memory.
+ ====================== ================================
 
 These can be checked by the user program's abort handler as TEXASR[0:7].  If
 bit 7 is set, it indicates that the error is consider persistent.  For example
@@ -203,7 +206,7 @@ POWER9
 ======
 
 TM on POWER9 has issues with storing the complete register state. This
-is described in this commit:
+is described in this commit::
 
     commit 4bb3c7a0208fc13ca70598efd109901a7cd45ae7
     Author: Paul Mackerras <paulus@ozlabs.org>
diff --git a/MAINTAINERS b/MAINTAINERS
index 3d6cd6efb264..15b58d5947a3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4469,7 +4469,7 @@ F:	arch/powerpc/platforms/powernv/pci-cxl.c
 F:	drivers/misc/cxl/
 F:	include/misc/cxl*
 F:	include/uapi/misc/cxl.h
-F:	Documentation/powerpc/cxl.txt
+F:	Documentation/powerpc/cxl.rst
 F:	Documentation/ABI/testing/sysfs-class-cxl
 
 CXLFLASH (IBM Coherent Accelerator Processor Interface CAPI Flash) SCSI DRIVER
@@ -4480,7 +4480,7 @@ L:	linux-scsi@vger.kernel.org
 S:	Supported
 F:	drivers/scsi/cxlflash/
 F:	include/uapi/scsi/cxlflash_ioctl.h
-F:	Documentation/powerpc/cxlflash.txt
+F:	Documentation/powerpc/cxlflash.rst
 
 CYBERPRO FB DRIVER
 M:	Russell King <linux@armlinux.org.uk>
@@ -12394,7 +12394,7 @@ F:	Documentation/PCI/pci-error-recovery.rst
 F:	drivers/pci/pcie/aer.c
 F:	drivers/pci/pcie/dpc.c
 F:	drivers/pci/pcie/err.c
-F:	Documentation/powerpc/eeh-pci-error-recovery.txt
+F:	Documentation/powerpc/eeh-pci-error-recovery.rst
 F:	arch/powerpc/kernel/eeh*.c
 F:	arch/powerpc/platforms/*/eeh*.c
 F:	arch/powerpc/include/*/eeh*.h
diff --git a/arch/powerpc/kernel/exceptions-64s.S b/arch/powerpc/kernel/exceptions-64s.S
index eee5bef736c8..6ba3cc2ef8ab 100644
--- a/arch/powerpc/kernel/exceptions-64s.S
+++ b/arch/powerpc/kernel/exceptions-64s.S
@@ -1531,7 +1531,7 @@ EXC_COMMON(trap_0b_common, 0xb00, unknown_exception)
  *
  * Call convention:
  *
- * syscall register convention is in Documentation/powerpc/syscall64-abi.txt
+ * syscall register convention is in Documentation/powerpc/syscall64-abi.rst
  *
  * For hypercalls, the register convention is as follows:
  * r0 volatile
diff --git a/drivers/soc/fsl/qe/qe.c b/drivers/soc/fsl/qe/qe.c
index 62c6ba17991a..c9519e62308c 100644
--- a/drivers/soc/fsl/qe/qe.c
+++ b/drivers/soc/fsl/qe/qe.c
@@ -419,7 +419,7 @@ static void qe_upload_microcode(const void *base,
 /*
  * Upload a microcode to the I-RAM at a specific address.
  *
- * See Documentation/powerpc/qe_firmware.txt for information on QE microcode
+ * See Documentation/powerpc/qe_firmware.rst for information on QE microcode
  * uploading.
  *
  * Currently, only version 1 is supported, so the 'version' field must be
diff --git a/drivers/tty/hvc/hvcs.c b/drivers/tty/hvc/hvcs.c
index cb4db1b3ca3c..5fb214e67d73 100644
--- a/drivers/tty/hvc/hvcs.c
+++ b/drivers/tty/hvc/hvcs.c
@@ -47,7 +47,7 @@
  * using the 2.6 Linux kernel kref construct.
  *
  * For direction on installation and usage of this driver please reference
- * Documentation/powerpc/hvcs.txt.
+ * Documentation/powerpc/hvcs.rst.
  */
 
 #include <linux/device.h>
diff --git a/include/soc/fsl/qe/qe.h b/include/soc/fsl/qe/qe.h
index 3f9d6b6a5691..c1036d16ed03 100644
--- a/include/soc/fsl/qe/qe.h
+++ b/include/soc/fsl/qe/qe.h
@@ -259,7 +259,7 @@ static inline int qe_alive_during_sleep(void)
 
 /* Structure that defines QE firmware binary files.
  *
- * See Documentation/powerpc/qe_firmware.txt for a description of these
+ * See Documentation/powerpc/qe_firmware.rst for a description of these
  * fields.
  */
 struct qe_firmware {
-- 
2.21.0


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

* [PATCH v2 03/26] docs: powerpc: convert docs to ReST and rename to *.rst
@ 2019-07-26 12:51   ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: linux-doc, Benjamin Herrenschmidt, linux-pci,
	Oliver O'Halloran, Russell Currey, Mauro Carvalho Chehab,
	Qiang Zhao, linux-scsi, Jonathan Corbet, Michael Ellerman,
	Jiri Slaby, Linas Vepstas, Andrew Donnellan, Manoj N. Kumar,
	Bjorn Helgaas, linux-arm-kernel, Matthew R. Ochs, Uma Krishnan,
	Sam Bobroff, Greg Kroah-Hartman, Li Yang, Andrew Donnellan,
	Frederic Barrat, Paul

Convert docs to ReST and add them to the arch-specific
book.

The conversion here was trivial, as almost every file there
was already using an elegant format close to ReST standard.

The changes were mostly to mark literal blocks and add a few
missing section title identifiers.

One note with regards to "--": on Sphinx, this can't be used
to identify a list, as it will format it badly. This can be
used, however, to identify a long hyphen - and "---" is an
even longer one.

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: Andrew Donnellan <andrew.donnellan@au1.ibm.com> # cxl
---
 Documentation/PCI/pci-error-recovery.rst      |   2 +-
 Documentation/index.rst                       |   1 +
 .../{bootwrapper.txt => bootwrapper.rst}      |  28 ++-
 .../{cpu_families.txt => cpu_families.rst}    |  23 +--
 .../{cpu_features.txt => cpu_features.rst}    |   6 +-
 Documentation/powerpc/{cxl.txt => cxl.rst}    |  46 +++--
 .../powerpc/{cxlflash.txt => cxlflash.rst}    |  10 +-
 .../{DAWR-POWER9.txt => dawr-power9.rst}      |  15 +-
 Documentation/powerpc/{dscr.txt => dscr.rst}  |  18 +-
 ...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +++++------
 ...ed-dump.txt => firmware-assisted-dump.rst} | 117 ++++++------
 Documentation/powerpc/{hvcs.txt => hvcs.rst}  | 108 ++++++-----
 Documentation/powerpc/index.rst               |  34 ++++
 Documentation/powerpc/isa-versions.rst        |  15 +-
 .../powerpc/{mpc52xx.txt => mpc52xx.rst}      |  12 +-
 ...nv.txt => pci_iov_resource_on_powernv.rst} |  15 +-
 .../powerpc/{pmu-ebb.txt => pmu-ebb.rst}      |   1 +
 .../powerpc/{ptrace.txt => ptrace.rst}        | 169 +++++++++---------
 .../{qe_firmware.txt => qe_firmware.rst}      |  37 ++--
 .../{syscall64-abi.txt => syscall64-abi.rst}  |  29 +--
 ...al_memory.txt => transactional_memory.rst} |  45 ++---
 MAINTAINERS                                   |   6 +-
 arch/powerpc/kernel/exceptions-64s.S          |   2 +-
 drivers/soc/fsl/qe/qe.c                       |   2 +-
 drivers/tty/hvc/hvcs.c                        |   2 +-
 include/soc/fsl/qe/qe.h                       |   2 +-
 26 files changed, 495 insertions(+), 358 deletions(-)
 rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
 rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
 rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
 rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
 rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
 rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
 rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
 rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
 rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
 rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
 create mode 100644 Documentation/powerpc/index.rst
 rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
 rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
 rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
 rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
 rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
 rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
 rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)

diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
index 83db42092935..69800a9d1b0d 100644
--- a/Documentation/PCI/pci-error-recovery.rst
+++ b/Documentation/PCI/pci-error-recovery.rst
@@ -403,7 +403,7 @@ That is, the recovery API only requires that:
 .. note::
 
    Implementation details for the powerpc platform are discussed in
-   the file Documentation/powerpc/eeh-pci-error-recovery.txt
+   the file Documentation/powerpc/eeh-pci-error-recovery.rst
 
    As of this writing, there is a growing list of device drivers with
    patches implementing error recovery. Not all of these patches are in
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 230e550e9741..68ae2a4d689d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -144,6 +144,7 @@ implementation.
    arm64/index
    ia64/index
    m68k/index
+   powerpc/index
    riscv/index
    s390/index
    sh/index
diff --git a/Documentation/powerpc/bootwrapper.txt b/Documentation/powerpc/bootwrapper.rst
similarity index 93%
rename from Documentation/powerpc/bootwrapper.txt
rename to Documentation/powerpc/bootwrapper.rst
index d60fced5e1cc..a6292afba573 100644
--- a/Documentation/powerpc/bootwrapper.txt
+++ b/Documentation/powerpc/bootwrapper.rst
@@ -1,5 +1,7 @@
+========================
 The PowerPC boot wrapper
-------------------------
+========================
+
 Copyright (C) Secret Lab Technologies Ltd.
 
 PowerPC image targets compresses and wraps the kernel image (vmlinux) with
@@ -21,6 +23,7 @@ it uses the wrapper script (arch/powerpc/boot/wrapper) to generate target
 image.  The details of the build system is discussed in the next section.
 Currently, the following image format targets exist:
 
+   ==================== ========================================================
    cuImage.%:		Backwards compatible uImage for older version of
 			U-Boot (for versions that don't understand the device
 			tree).  This image embeds a device tree blob inside
@@ -29,31 +32,36 @@ Currently, the following image format targets exist:
 			with boot wrapper code that extracts data from the old
 			bd_info structure and loads the data into the device
 			tree before jumping into the kernel.
-			  Because of the series of #ifdefs found in the
+
+			Because of the series of #ifdefs found in the
 			bd_info structure used in the old U-Boot interfaces,
 			cuImages are platform specific.  Each specific
 			U-Boot platform has a different platform init file
 			which populates the embedded device tree with data
 			from the platform specific bd_info file.  The platform
 			specific cuImage platform init code can be found in
-			arch/powerpc/boot/cuboot.*.c.  Selection of the correct
+			`arch/powerpc/boot/cuboot.*.c`. Selection of the correct
 			cuImage init code for a specific board can be found in
 			the wrapper structure.
+
    dtbImage.%:		Similar to zImage, except device tree blob is embedded
 			inside the image instead of provided by firmware.  The
 			output image file can be either an elf file or a flat
 			binary depending on the platform.
-			  dtbImages are used on systems which do not have an
+
+			dtbImages are used on systems which do not have an
 			interface for passing a device tree directly.
 			dtbImages are similar to simpleImages except that
 			dtbImages have platform specific code for extracting
 			data from the board firmware, but simpleImages do not
 			talk to the firmware at all.
-			  PlayStation 3 support uses dtbImage.  So do Embedded
+
+			PlayStation 3 support uses dtbImage.  So do Embedded
 			Planet boards using the PlanetCore firmware.  Board
 			specific initialization code is typically found in a
 			file named arch/powerpc/boot/<platform>.c; but this
 			can be overridden by the wrapper script.
+
    simpleImage.%:	Firmware independent compressed image that does not
 			depend on any particular firmware interface and embeds
 			a device tree blob.  This image is a flat binary that
@@ -61,14 +69,16 @@ Currently, the following image format targets exist:
 			Firmware cannot pass any configuration data to the
 			kernel with this image type and it depends entirely on
 			the embedded device tree for all information.
-			  The simpleImage is useful for booting systems with
+
+			The simpleImage is useful for booting systems with
 			an unknown firmware interface or for booting from
 			a debugger when no firmware is present (such as on
 			the Xilinx Virtex platform).  The only assumption that
 			simpleImage makes is that RAM is correctly initialized
 			and that the MMU is either off or has RAM mapped to
 			base address 0.
-			  simpleImage also supports inserting special platform
+
+			simpleImage also supports inserting special platform
 			specific initialization code to the start of the bootup
 			sequence.  The virtex405 platform uses this feature to
 			ensure that the cache is invalidated before caching
@@ -81,9 +91,11 @@ Currently, the following image format targets exist:
 			named (virtex405-<board>.dts).  Search the wrapper
 			script for 'virtex405' and see the file
 			arch/powerpc/boot/virtex405-head.S for details.
+
    treeImage.%;		Image format for used with OpenBIOS firmware found
 			on some ppc4xx hardware.  This image embeds a device
 			tree blob inside the image.
+
    uImage:		Native image format used by U-Boot.  The uImage target
 			does not add any boot code.  It just wraps a compressed
 			vmlinux in the uImage data structure.  This image
@@ -91,12 +103,14 @@ Currently, the following image format targets exist:
 			a device tree to the kernel at boot.  If using an older
 			version of U-Boot, then you need to use a cuImage
 			instead.
+
    zImage.%:		Image format which does not embed a device tree.
 			Used by OpenFirmware and other firmware interfaces
 			which are able to supply a device tree.  This image
 			expects firmware to provide the device tree at boot.
 			Typically, if you have general purpose PowerPC
 			hardware then you want this image format.
+   ==================== ========================================================
 
 Image types which embed a device tree blob (simpleImage, dtbImage, treeImage,
 and cuImage) all generate the device tree blob from a file in the
diff --git a/Documentation/powerpc/cpu_families.txt b/Documentation/powerpc/cpu_families.rst
similarity index 95%
rename from Documentation/powerpc/cpu_families.txt
rename to Documentation/powerpc/cpu_families.rst
index fc08e22feb1a..1e063c5440c3 100644
--- a/Documentation/powerpc/cpu_families.txt
+++ b/Documentation/powerpc/cpu_families.rst
@@ -1,3 +1,4 @@
+============
 CPU Families
 ============
 
@@ -8,8 +9,8 @@ and are supported by arch/powerpc.
 Book3S (aka sPAPR)
 ------------------
 
- - Hash MMU
- - Mix of 32 & 64 bit
+- Hash MMU
+- Mix of 32 & 64 bit::
 
    +--------------+                 +----------------+
    |  Old POWER   | --------------> | RS64 (threads) |
@@ -108,8 +109,8 @@ Book3S (aka sPAPR)
 IBM BookE
 ---------
 
- - Software loaded TLB.
- - All 32 bit
+- Software loaded TLB.
+- All 32 bit::
 
    +--------------+
    |     401      |
@@ -155,8 +156,8 @@ IBM BookE
 Motorola/Freescale 8xx
 ----------------------
 
- - Software loaded with hardware assist.
- - All 32 bit
+- Software loaded with hardware assist.
+- All 32 bit::
 
    +-------------+
    | MPC8xx Core |
@@ -166,9 +167,9 @@ Motorola/Freescale 8xx
 Freescale BookE
 ---------------
 
- - Software loaded TLB.
- - e6500 adds HW loaded indirect TLB entries.
- - Mix of 32 & 64 bit
+- Software loaded TLB.
+- e6500 adds HW loaded indirect TLB entries.
+- Mix of 32 & 64 bit::
 
    +--------------+
    |     e200     |
@@ -207,8 +208,8 @@ Freescale BookE
 IBM A2 core
 -----------
 
- - Book3E, software loaded TLB + HW loaded indirect TLB entries.
- - 64 bit
+- Book3E, software loaded TLB + HW loaded indirect TLB entries.
+- 64 bit::
 
    +--------------+     +----------------+
    |   A2 core    | --> |      WSP       |
diff --git a/Documentation/powerpc/cpu_features.txt b/Documentation/powerpc/cpu_features.rst
similarity index 97%
rename from Documentation/powerpc/cpu_features.txt
rename to Documentation/powerpc/cpu_features.rst
index ae09df8722c8..b7bcdd2f41bb 100644
--- a/Documentation/powerpc/cpu_features.txt
+++ b/Documentation/powerpc/cpu_features.rst
@@ -1,3 +1,7 @@
+============
+CPU Features
+============
+
 Hollis Blanchard <hollis@austin.ibm.com>
 5 Jun 2002
 
@@ -32,7 +36,7 @@ anyways).
 After detecting the processor type, the kernel patches out sections of code
 that shouldn't be used by writing nop's over it. Using cpufeatures requires
 just 2 macros (found in arch/powerpc/include/asm/cputable.h), as seen in head.S
-transfer_to_handler:
+transfer_to_handler::
 
 	#ifdef CONFIG_ALTIVEC
 	BEGIN_FTR_SECTION
diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.rst
similarity index 95%
rename from Documentation/powerpc/cxl.txt
rename to Documentation/powerpc/cxl.rst
index c5e8d5098ed3..920546d81326 100644
--- a/Documentation/powerpc/cxl.txt
+++ b/Documentation/powerpc/cxl.rst
@@ -1,3 +1,4 @@
+====================================
 Coherent Accelerator Interface (CXL)
 ====================================
 
@@ -21,6 +22,8 @@ Introduction
 Hardware overview
 =================
 
+    ::
+
          POWER8/9             FPGA
        +----------+        +---------+
        |          |        |         |
@@ -59,14 +62,16 @@ Hardware overview
     the fault. The context to which this fault is serviced is based on
     who owns that acceleration function.
 
-    POWER8 <-----> PSL Version 8 is compliant to the CAIA Version 1.0.
-    POWER9 <-----> PSL Version 9 is compliant to the CAIA Version 2.0.
+    - POWER8 and PSL Version 8 are compliant to the CAIA Version 1.0.
+    - POWER9 and PSL Version 9 are compliant to the CAIA Version 2.0.
+
     This PSL Version 9 provides new features such as:
+
     * Interaction with the nest MMU on the P9 chip.
     * Native DMA support.
     * Supports sending ASB_Notify messages for host thread wakeup.
     * Supports Atomic operations.
-    * ....
+    * etc.
 
     Cards with a PSL9 won't work on a POWER8 system and cards with a
     PSL8 won't work on a POWER9 system.
@@ -147,7 +152,9 @@ User API
     master devices.
 
     A userspace library libcxl is available here:
+
 	https://github.com/ibm-capi/libcxl
+
     This provides a C interface to this kernel API.
 
 open
@@ -165,7 +172,8 @@ open
     When all available contexts are allocated the open call will fail
     and return -ENOSPC.
 
-    Note: IRQs need to be allocated for each context, which may limit
+    Note:
+	  IRQs need to be allocated for each context, which may limit
           the number of contexts that can be created, and therefore
           how many times the device can be opened. The POWER8 CAPP
           supports 2040 IRQs and 3 are used by the kernel, so 2037 are
@@ -186,7 +194,9 @@ ioctl
         updated as userspace allocates and frees memory. This ioctl
         returns once the AFU context is started.
 
-        Takes a pointer to a struct cxl_ioctl_start_work:
+        Takes a pointer to a struct cxl_ioctl_start_work
+
+            ::
 
                 struct cxl_ioctl_start_work {
                         __u64 flags;
@@ -269,7 +279,7 @@ read
     The buffer passed to read() must be at least 4K bytes.
 
     The result of the read will be a buffer of one or more events,
-    each event is of type struct cxl_event, of varying size.
+    each event is of type struct cxl_event, of varying size::
 
             struct cxl_event {
                     struct cxl_event_header header;
@@ -280,7 +290,9 @@ read
                     };
             };
 
-    The struct cxl_event_header is defined as:
+    The struct cxl_event_header is defined as
+
+        ::
 
             struct cxl_event_header {
                     __u16 type;
@@ -307,7 +319,9 @@ read
             For future extensions and padding.
 
     If the event type is CXL_EVENT_AFU_INTERRUPT then the event
-    structure is defined as:
+    structure is defined as
+
+        ::
 
             struct cxl_event_afu_interrupt {
                     __u16 flags;
@@ -326,7 +340,9 @@ read
             For future extensions and padding.
 
     If the event type is CXL_EVENT_DATA_STORAGE then the event
-    structure is defined as:
+    structure is defined as
+
+        ::
 
             struct cxl_event_data_storage {
                     __u16 flags;
@@ -356,7 +372,9 @@ read
             For future extensions
 
     If the event type is CXL_EVENT_AFU_ERROR then the event structure
-    is defined as:
+    is defined as
+
+        ::
 
             struct cxl_event_afu_error {
                     __u16 flags;
@@ -393,15 +411,15 @@ open
 ioctl
 -----
 
-CXL_IOCTL_DOWNLOAD_IMAGE:
-CXL_IOCTL_VALIDATE_IMAGE:
+CXL_IOCTL_DOWNLOAD_IMAGE / CXL_IOCTL_VALIDATE_IMAGE:
     Starts and controls flashing a new FPGA image. Partial
     reconfiguration is not supported (yet), so the image must contain
     a copy of the PSL and AFU(s). Since an image can be quite large,
     the caller may have to iterate, splitting the image in smaller
     chunks.
 
-    Takes a pointer to a struct cxl_adapter_image:
+    Takes a pointer to a struct cxl_adapter_image::
+
         struct cxl_adapter_image {
             __u64 flags;
             __u64 data;
@@ -442,7 +460,7 @@ Udev rules
     The following udev rules could be used to create a symlink to the
     most logical chardev to use in any programming mode (afuX.Yd for
     dedicated, afuX.Ys for afu directed), since the API is virtually
-    identical for each:
+    identical for each::
 
 	SUBSYSTEM=="cxl", ATTRS{mode}=="dedicated_process", SYMLINK="cxl/%b"
 	SUBSYSTEM=="cxl", ATTRS{mode}=="afu_directed", \
diff --git a/Documentation/powerpc/cxlflash.txt b/Documentation/powerpc/cxlflash.rst
similarity index 98%
rename from Documentation/powerpc/cxlflash.txt
rename to Documentation/powerpc/cxlflash.rst
index a64bdaa0a1cf..cea67931b3b9 100644
--- a/Documentation/powerpc/cxlflash.txt
+++ b/Documentation/powerpc/cxlflash.rst
@@ -1,3 +1,7 @@
+================================
+Coherent Accelerator (CXL) Flash
+================================
+
 Introduction
 ============
 
@@ -28,7 +32,7 @@ Introduction
     responsible for the initialization of the adapter, setting up the
     special path for user space access, and performing error recovery. It
     communicates directly the Flash Accelerator Functional Unit (AFU)
-    as described in Documentation/powerpc/cxl.txt.
+    as described in Documentation/powerpc/cxl.rst.
 
     The cxlflash driver supports two, mutually exclusive, modes of
     operation at the device (LUN) level:
@@ -58,7 +62,7 @@ Overview
 
     The CXL Flash Adapter Driver establishes a master context with the
     AFU. It uses memory mapped I/O (MMIO) for this control and setup. The
-    Adapter Problem Space Memory Map looks like this:
+    Adapter Problem Space Memory Map looks like this::
 
                      +-------------------------------+
                      |    512 * 64 KB User MMIO      |
@@ -375,7 +379,7 @@ CXL Flash Driver Host IOCTLs
     Each host adapter instance that is supported by the cxlflash driver
     has a special character device associated with it to enable a set of
     host management function. These character devices are hosted in a
-    class dedicated for cxlflash and can be accessed via /dev/cxlflash/*.
+    class dedicated for cxlflash and can be accessed via `/dev/cxlflash/*`.
 
     Applications can be written to perform various functions using the
     host ioctl APIs below.
diff --git a/Documentation/powerpc/DAWR-POWER9.txt b/Documentation/powerpc/dawr-power9.rst
similarity index 95%
rename from Documentation/powerpc/DAWR-POWER9.txt
rename to Documentation/powerpc/dawr-power9.rst
index ecdbb076438c..c96ab6befd9c 100644
--- a/Documentation/powerpc/DAWR-POWER9.txt
+++ b/Documentation/powerpc/dawr-power9.rst
@@ -1,10 +1,11 @@
+=====================
 DAWR issues on POWER9
-============================
+=====================
 
 On POWER9 the Data Address Watchpoint Register (DAWR) can cause a checkstop
 if it points to cache inhibited (CI) memory. Currently Linux has no way to
 disinguish CI memory when configuring the DAWR, so (for now) the DAWR is
-disabled by this commit:
+disabled by this commit::
 
     commit 9654153158d3e0684a1bdb76dbababdb7111d5a0
     Author: Michael Neuling <mikey@neuling.org>
@@ -12,7 +13,7 @@ disabled by this commit:
     powerpc: Disable DAWR in the base POWER9 CPU features
 
 Technical Details:
-============================
+==================
 
 DAWR has 6 different ways of being set.
 1) ptrace
@@ -37,7 +38,7 @@ DAWR on the migration.
 For xmon, the 'bd' command will return an error on P9.
 
 Consequences for users
-============================
+======================
 
 For GDB watchpoints (ie 'watch' command) on POWER9 bare metal , GDB
 will accept the command. Unfortunately since there is no hardware
@@ -57,8 +58,8 @@ trapped in GDB. The watchpoint is remembered, so if the guest is
 migrated back to the POWER8 host, it will start working again.
 
 Force enabling the DAWR
-=============================
-Kernels (since ~v5.2) have an option to force enable the DAWR via:
+=======================
+Kernels (since ~v5.2) have an option to force enable the DAWR via::
 
   echo Y > /sys/kernel/debug/powerpc/dawr_enable_dangerous
 
@@ -86,5 +87,7 @@ dawr_enable_dangerous file will fail if the hypervisor doesn't support
 writing the DAWR.
 
 To double check the DAWR is working, run this kernel selftest:
+
   tools/testing/selftests/powerpc/ptrace/ptrace-hwbreak.c
+
 Any errors/failures/skips mean something is wrong.
diff --git a/Documentation/powerpc/dscr.txt b/Documentation/powerpc/dscr.rst
similarity index 91%
rename from Documentation/powerpc/dscr.txt
rename to Documentation/powerpc/dscr.rst
index ece300c64f76..2ab99006014c 100644
--- a/Documentation/powerpc/dscr.txt
+++ b/Documentation/powerpc/dscr.rst
@@ -1,5 +1,6 @@
-			DSCR (Data Stream Control Register)
-		================================================
+===================================
+DSCR (Data Stream Control Register)
+===================================
 
 DSCR register in powerpc allows user to have some control of prefetch of data
 stream in the processor. Please refer to the ISA documents or related manual
@@ -10,14 +11,17 @@ user interface.
 
 (A) Data Structures:
 
-	(1) thread_struct:
+	(1) thread_struct::
+
 		dscr		/* Thread DSCR value */
 		dscr_inherit	/* Thread has changed default DSCR */
 
-	(2) PACA:
+	(2) PACA::
+
 		dscr_default	/* per-CPU DSCR default value */
 
-	(3) sysfs.c:
+	(3) sysfs.c::
+
 		dscr_default	/* System DSCR default value */
 
 (B) Scheduler Changes:
@@ -35,8 +39,8 @@ user interface.
 
 (C) SYSFS Interface:
 
-	Global DSCR default:		/sys/devices/system/cpu/dscr_default
-	CPU specific DSCR default:	/sys/devices/system/cpu/cpuN/dscr
+	- Global DSCR default:		/sys/devices/system/cpu/dscr_default
+	- CPU specific DSCR default:	/sys/devices/system/cpu/cpuN/dscr
 
 	Changing the global DSCR default in the sysfs will change all the CPU
 	specific DSCR defaults immediately in their PACA structures. Again if
diff --git a/Documentation/powerpc/eeh-pci-error-recovery.txt b/Documentation/powerpc/eeh-pci-error-recovery.rst
similarity index 82%
rename from Documentation/powerpc/eeh-pci-error-recovery.txt
rename to Documentation/powerpc/eeh-pci-error-recovery.rst
index 678189280bb4..438a87ebc095 100644
--- a/Documentation/powerpc/eeh-pci-error-recovery.txt
+++ b/Documentation/powerpc/eeh-pci-error-recovery.rst
@@ -1,10 +1,10 @@
+==========================
+PCI Bus EEH Error Recovery
+==========================
 
+Linas Vepstas <linas@austin.ibm.com>
 
-                      PCI Bus EEH Error Recovery
-                      --------------------------
-                           Linas Vepstas
-                       <linas@austin.ibm.com>
-                          12 January 2005
+12 January 2005
 
 
 Overview:
@@ -143,17 +143,17 @@ seen in /proc/ppc64/eeh (subject to change).  Normally, almost
 all of these occur during boot, when the PCI bus is scanned, where
 a large number of 0xff reads are part of the bus scan procedure.
 
-If a frozen slot is detected, code in 
-arch/powerpc/platforms/pseries/eeh.c will print a stack trace to 
-syslog (/var/log/messages).  This stack trace has proven to be very 
-useful to device-driver authors for finding out at what point the EEH 
-error was detected, as the error itself usually occurs slightly 
+If a frozen slot is detected, code in
+arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
+syslog (/var/log/messages).  This stack trace has proven to be very
+useful to device-driver authors for finding out at what point the EEH
+error was detected, as the error itself usually occurs slightly
 beforehand.
 
 Next, it uses the Linux kernel notifier chain/work queue mechanism to
 allow any interested parties to find out about the failure.  Device
 drivers, or other parts of the kernel, can use
-eeh_register_notifier(struct notifier_block *) to find out about EEH
+`eeh_register_notifier(struct notifier_block *)` to find out about EEH
 events.  The event will include a pointer to the pci device, the
 device node and some state info.  Receivers of the event can "do as
 they wish"; the default handler will be described further in this
@@ -162,10 +162,13 @@ section.
 To assist in the recovery of the device, eeh.c exports the
 following functions:
 
-rtas_set_slot_reset() -- assert the  PCI #RST line for 1/8th of a second
-rtas_configure_bridge() -- ask firmware to configure any PCI bridges
+rtas_set_slot_reset()
+   assert the  PCI #RST line for 1/8th of a second
+rtas_configure_bridge()
+   ask firmware to configure any PCI bridges
    located topologically under the pci slot.
-eeh_save_bars() and eeh_restore_bars(): save and restore the PCI
+eeh_save_bars() and eeh_restore_bars():
+   save and restore the PCI
    config-space info for a device and any devices under it.
 
 
@@ -191,7 +194,7 @@ events get delivered to user-space scripts.
 
 Following is an example sequence of events that cause a device driver
 close function to be called during the first phase of an EEH reset.
-The following sequence is an example of the pcnet32 device driver.
+The following sequence is an example of the pcnet32 device driver::
 
     rpa_php_unconfig_pci_adapter (struct slot *)  // in rpaphp_pci.c
     {
@@ -241,53 +244,54 @@ The following sequence is an example of the pcnet32 device driver.
      }}}}}}
 
 
-    in drivers/pci/pci_driver.c,
-    struct device_driver->remove() is just pci_device_remove()
-    which calls struct pci_driver->remove() which is pcnet32_remove_one()
-    which calls unregister_netdev()  (in net/core/dev.c)
-    which calls dev_close()  (in net/core/dev.c)
-    which calls dev->stop() which is pcnet32_close()
-    which then does the appropriate shutdown.
+in drivers/pci/pci_driver.c,
+struct device_driver->remove() is just pci_device_remove()
+which calls struct pci_driver->remove() which is pcnet32_remove_one()
+which calls unregister_netdev()  (in net/core/dev.c)
+which calls dev_close()  (in net/core/dev.c)
+which calls dev->stop() which is pcnet32_close()
+which then does the appropriate shutdown.
 
 ---
+
 Following is the analogous stack trace for events sent to user-space
-when the pci device is unconfigured.
+when the pci device is unconfigured::
 
-rpa_php_unconfig_pci_adapter() {             // in rpaphp_pci.c
-  calls
-  pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
+  rpa_php_unconfig_pci_adapter() {             // in rpaphp_pci.c
     calls
-    pci_destroy_dev (struct pci_dev *) {
+    pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
       calls
-      device_unregister (&dev->dev) {        // in /drivers/base/core.c
+      pci_destroy_dev (struct pci_dev *) {
         calls
-        device_del(struct device * dev) {    // in /drivers/base/core.c
+        device_unregister (&dev->dev) {        // in /drivers/base/core.c
           calls
-          kobject_del() {                    //in /libs/kobject.c
+          device_del(struct device * dev) {    // in /drivers/base/core.c
             calls
-            kobject_uevent() {               // in /libs/kobject.c
+            kobject_del() {                    //in /libs/kobject.c
               calls
-              kset_uevent() {                // in /lib/kobject.c
+              kobject_uevent() {               // in /libs/kobject.c
                 calls
-                kset->uevent_ops->uevent()   // which is really just
-                a call to
-                dev_uevent() {               // in /drivers/base/core.c
+                kset_uevent() {                // in /lib/kobject.c
                   calls
-                  dev->bus->uevent() which is really just a call to
-                  pci_uevent () {            // in drivers/pci/hotplug.c
-                    which prints device name, etc....
+                  kset->uevent_ops->uevent()   // which is really just
+                  a call to
+                  dev_uevent() {               // in /drivers/base/core.c
+                    calls
+                    dev->bus->uevent() which is really just a call to
+                    pci_uevent () {            // in drivers/pci/hotplug.c
+                      which prints device name, etc....
+                   }
                  }
-               }
-               then kobject_uevent() sends a netlink uevent to userspace
-               --> userspace uevent
-               (during early boot, nobody listens to netlink events and
-               kobject_uevent() executes uevent_helper[], which runs the
-               event process /sbin/hotplug)
+                 then kobject_uevent() sends a netlink uevent to userspace
+                 --> userspace uevent
+                 (during early boot, nobody listens to netlink events and
+                 kobject_uevent() executes uevent_helper[], which runs the
+                 event process /sbin/hotplug)
+             }
            }
-         }
-         kobject_del() then calls sysfs_remove_dir(), which would
-         trigger any user-space daemon that was watching /sysfs,
-         and notice the delete event.
+           kobject_del() then calls sysfs_remove_dir(), which would
+           trigger any user-space daemon that was watching /sysfs,
+           and notice the delete event.
 
 
 Pro's and Con's of the Current Design
@@ -299,12 +303,12 @@ individual device drivers, so that the current design throws a wide net.
 The biggest negative of the design is that it potentially disturbs
 network daemons and file systems that didn't need to be disturbed.
 
--- A minor complaint is that resetting the network card causes
+-  A minor complaint is that resetting the network card causes
    user-space back-to-back ifdown/ifup burps that potentially disturb
    network daemons, that didn't need to even know that the pci
    card was being rebooted.
 
--- A more serious concern is that the same reset, for SCSI devices,
+-  A more serious concern is that the same reset, for SCSI devices,
    causes havoc to mounted file systems.  Scripts cannot post-facto
    unmount a file system without flushing pending buffers, but this
    is impossible, because I/O has already been stopped.  Thus,
@@ -322,7 +326,7 @@ network daemons and file systems that didn't need to be disturbed.
    from the block layer.  It would be very natural to add an EEH
    reset into this chain of events.
 
--- If a SCSI error occurs for the root device, all is lost unless
+-  If a SCSI error occurs for the root device, all is lost unless
    the sysadmin had the foresight to run /bin, /sbin, /etc, /var
    and so on, out of ramdisk/tmpfs.
 
@@ -330,5 +334,3 @@ network daemons and file systems that didn't need to be disturbed.
 Conclusions
 -----------
 There's forward progress ...
-
-
diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.rst
similarity index 80%
rename from Documentation/powerpc/firmware-assisted-dump.txt
rename to Documentation/powerpc/firmware-assisted-dump.rst
index 10e7f4d16c14..9ca12830a48e 100644
--- a/Documentation/powerpc/firmware-assisted-dump.txt
+++ b/Documentation/powerpc/firmware-assisted-dump.rst
@@ -1,7 +1,8 @@
+======================
+Firmware-Assisted Dump
+======================
 
-                   Firmware-Assisted Dump
-                   ------------------------
-                       July 2011
+July 2011
 
 The goal of firmware-assisted dump is to enable the dump of
 a crashed system, and to do so from a fully-reset system, and
@@ -27,11 +28,11 @@ in production use.
 Comparing with kdump or other strategies, firmware-assisted
 dump offers several strong, practical advantages:
 
--- Unlike kdump, the system has been reset, and loaded
+-  Unlike kdump, the system has been reset, and loaded
    with a fresh copy of the kernel.  In particular,
    PCI and I/O devices have been reinitialized and are
    in a clean, consistent state.
--- Once the dump is copied out, the memory that held the dump
+-  Once the dump is copied out, the memory that held the dump
    is immediately available to the running kernel. And therefore,
    unlike kdump, fadump doesn't need a 2nd reboot to get back
    the system to the production configuration.
@@ -40,17 +41,18 @@ The above can only be accomplished by coordination with,
 and assistance from the Power firmware. The procedure is
 as follows:
 
--- The first kernel registers the sections of memory with the
+-  The first kernel registers the sections of memory with the
    Power firmware for dump preservation during OS initialization.
    These registered sections of memory are reserved by the first
    kernel during early boot.
 
--- When a system crashes, the Power firmware will save
+-  When a system crashes, the Power firmware will save
    the low memory (boot memory of size larger of 5% of system RAM
    or 256MB) of RAM to the previous registered region. It will
    also save system registers, and hardware PTE's.
 
-   NOTE: The term 'boot memory' means size of the low memory chunk
+   NOTE:
+         The term 'boot memory' means size of the low memory chunk
          that is required for a kernel to boot successfully when
          booted with restricted memory. By default, the boot memory
          size will be the larger of 5% of system RAM or 256MB.
@@ -64,12 +66,12 @@ as follows:
          as fadump uses a predefined offset to reserve memory
          for boot memory dump preservation in case of a crash.
 
--- After the low memory (boot memory) area has been saved, the
+-  After the low memory (boot memory) area has been saved, the
    firmware will reset PCI and other hardware state.  It will
    *not* clear the RAM. It will then launch the bootloader, as
    normal.
 
--- The freshly booted kernel will notice that there is a new
+-  The freshly booted kernel will notice that there is a new
    node (ibm,dump-kernel) in the device tree, indicating that
    there is crash data available from a previous boot. During
    the early boot OS will reserve rest of the memory above
@@ -77,17 +79,18 @@ as follows:
    size. This will make sure that the second kernel will not
    touch any of the dump memory area.
 
--- User-space tools will read /proc/vmcore to obtain the contents
+-  User-space tools will read /proc/vmcore to obtain the contents
    of memory, which holds the previous crashed kernel dump in ELF
    format. The userspace tools may copy this info to disk, or
    network, nas, san, iscsi, etc. as desired.
 
--- Once the userspace tool is done saving dump, it will echo
+-  Once the userspace tool is done saving dump, it will echo
    '1' to /sys/kernel/fadump_release_mem to release the reserved
    memory back to general use, except the memory required for
    next firmware-assisted dump registration.
 
-   e.g.
+   e.g.::
+
      # echo 1 > /sys/kernel/fadump_release_mem
 
 Please note that the firmware-assisted dump feature
@@ -95,7 +98,7 @@ is only available on Power6 and above systems with recent
 firmware versions.
 
 Implementation details:
-----------------------
+-----------------------
 
 During boot, a check is made to see if firmware supports
 this feature on that particular machine. If it does, then
@@ -121,7 +124,7 @@ Allocator (CMA) for memory reservation if CMA is configured for kernel.
 With CMA reservation this memory will be available for applications to
 use it, while kernel is prevented from using it. With this fadump will
 still be able to capture all of the kernel memory and most of the user
-space memory except the user pages that were present in CMA region.
+space memory except the user pages that were present in CMA region::
 
   o Memory Reservation during first kernel
 
@@ -166,7 +169,7 @@ The tools to examine the dump will be same as the ones
 used for kdump.
 
 How to enable firmware-assisted dump (fadump):
--------------------------------------
+----------------------------------------------
 
 1. Set config option CONFIG_FA_DUMP=y and build kernel.
 2. Boot into linux kernel with 'fadump=on' kernel cmdline option.
@@ -177,19 +180,20 @@ How to enable firmware-assisted dump (fadump):
    to specify size of the memory to reserve for boot memory dump
    preservation.
 
-NOTE: 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
-         use 'crashkernel=' to specify size of the memory to reserve
-         for boot memory dump preservation.
-      2. If firmware-assisted dump fails to reserve memory then it
-         will fallback to existing kdump mechanism if 'crashkernel='
-         option is set at kernel cmdline.
-      3. if user wants to capture all of user space memory and ok with
-         reserved memory not available to production system, then
-         'fadump=nocma' kernel parameter can be used to fallback to
-         old behaviour.
+NOTE:
+     1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
+        use 'crashkernel=' to specify size of the memory to reserve
+        for boot memory dump preservation.
+     2. If firmware-assisted dump fails to reserve memory then it
+        will fallback to existing kdump mechanism if 'crashkernel='
+        option is set at kernel cmdline.
+     3. if user wants to capture all of user space memory and ok with
+        reserved memory not available to production system, then
+        'fadump=nocma' kernel parameter can be used to fallback to
+        old behaviour.
 
 Sysfs/debugfs files:
-------------
+--------------------
 
 Firmware-assisted dump feature uses sysfs file system to hold
 the control files and debugfs file to display memory reserved region.
@@ -197,20 +201,20 @@ the control files and debugfs file to display memory reserved region.
 Here is the list of files under kernel sysfs:
 
  /sys/kernel/fadump_enabled
-
     This is used to display the fadump status.
-    0 = fadump is disabled
-    1 = fadump is enabled
+
+    - 0 = fadump is disabled
+    - 1 = fadump is enabled
 
     This interface can be used by kdump init scripts to identify if
     fadump is enabled in the kernel and act accordingly.
 
  /sys/kernel/fadump_registered
-
     This is used to display the fadump registration status as well
     as to control (start/stop) the fadump registration.
-    0 = fadump is not registered.
-    1 = fadump is registered and ready to handle system crash.
+
+    - 0 = fadump is not registered.
+    - 1 = fadump is registered and ready to handle system crash.
 
     To register fadump echo 1 > /sys/kernel/fadump_registered and
     echo 0 > /sys/kernel/fadump_registered for un-register and stop the
@@ -219,13 +223,12 @@ Here is the list of files under kernel sysfs:
     easily integrated with kdump service start/stop.
 
  /sys/kernel/fadump_release_mem
-
     This file is available only when fadump is active during
     second kernel. This is used to release the reserved memory
     region that are held for saving crash dump. To release the
-    reserved memory echo 1 to it:
+    reserved memory echo 1 to it::
 
-    echo 1  > /sys/kernel/fadump_release_mem
+	echo 1  > /sys/kernel/fadump_release_mem
 
     After echo 1, the content of the /sys/kernel/debug/powerpc/fadump_region
     file will change to reflect the new memory reservations.
@@ -238,38 +241,39 @@ Here is the list of files under powerpc debugfs:
 (Assuming debugfs is mounted on /sys/kernel/debug directory.)
 
  /sys/kernel/debug/powerpc/fadump_region
-
     This file shows the reserved memory regions if fadump is
     enabled otherwise this file is empty. The output format
-    is:
-    <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
+    is::
+
+      <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
 
     e.g.
-    Contents when fadump is registered during first kernel
+    Contents when fadump is registered during first kernel::
 
-    # cat /sys/kernel/debug/powerpc/fadump_region
-    CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
-    HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
-    DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
+      # cat /sys/kernel/debug/powerpc/fadump_region
+      CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
+      HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
+      DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
 
-    Contents when fadump is active during second kernel
+    Contents when fadump is active during second kernel::
 
-    # cat /sys/kernel/debug/powerpc/fadump_region
-    CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
-    HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
-    DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
-        : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
+      # cat /sys/kernel/debug/powerpc/fadump_region
+      CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
+      HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
+      DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
+          : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
 
-NOTE: Please refer to Documentation/filesystems/debugfs.txt on
+NOTE:
+      Please refer to Documentation/filesystems/debugfs.txt on
       how to mount the debugfs filesystem.
 
 
 TODO:
 -----
- o Need to come up with the better approach to find out more
+ - Need to come up with the better approach to find out more
    accurate boot memory size that is required for a kernel to
    boot successfully when booted with restricted memory.
- o The fadump implementation introduces a fadump crash info structure
+ - The fadump implementation introduces a fadump crash info structure
    in the scratch area before the ELF core header. The idea of introducing
    this structure is to pass some important crash info data to the second
    kernel which will help second kernel to populate ELF core header with
@@ -277,7 +281,9 @@ TODO:
    design implementation does not address a possibility of introducing
    additional fields (in future) to this structure without affecting
    compatibility. Need to come up with the better approach to address this.
+
    The possible approaches are:
+
 	1. Introduce version field for version tracking, bump up the version
 	whenever a new field is added to the structure in future. The version
 	field can be used to find out what fields are valid for the current
@@ -285,8 +291,11 @@ TODO:
 	2. Reserve the area of predefined size (say PAGE_SIZE) for this
 	structure and have unused area as reserved (initialized to zero)
 	for future field additions.
+
    The advantage of approach 1 over 2 is we don't need to reserve extra space.
----
+
 Author: Mahesh Salgaonkar <mahesh@linux.vnet.ibm.com>
+
 This document is based on the original documentation written for phyp
+
 assisted dump by Linas Vepstas and Manish Ahuja.
diff --git a/Documentation/powerpc/hvcs.txt b/Documentation/powerpc/hvcs.rst
similarity index 91%
rename from Documentation/powerpc/hvcs.txt
rename to Documentation/powerpc/hvcs.rst
index a730ca5a07f8..6808acde672f 100644
--- a/Documentation/powerpc/hvcs.txt
+++ b/Documentation/powerpc/hvcs.rst
@@ -1,19 +1,22 @@
-===========================================================================
-				   HVCS
-	IBM "Hypervisor Virtual Console Server" Installation Guide
-			  for Linux Kernel 2.6.4+
-		    Copyright (C) 2004 IBM Corporation
+===============================================================
+HVCS IBM "Hypervisor Virtual Console Server" Installation Guide
+===============================================================
 
-===========================================================================
-NOTE:Eight space tabs are the optimum editor setting for reading this file.
-===========================================================================
+for Linux Kernel 2.6.4+
 
-	       Author(s) :  Ryan S. Arnold <rsa@us.ibm.com>
-		       Date Created: March, 02, 2004
-		       Last Changed: August, 24, 2004
+Copyright (C) 2004 IBM Corporation
 
----------------------------------------------------------------------------
-Table of contents:
+.. ===========================================================================
+.. NOTE:Eight space tabs are the optimum editor setting for reading this file.
+.. ===========================================================================
+
+
+Author(s): Ryan S. Arnold <rsa@us.ibm.com>
+
+Date Created: March, 02, 2004
+Last Changed: August, 24, 2004
+
+.. Table of contents:
 
 	1.  Driver Introduction:
 	2.  System Requirements
@@ -27,8 +30,8 @@ Table of contents:
 	8.  Questions & Answers:
 	9.  Reporting Bugs:
 
----------------------------------------------------------------------------
 1. Driver Introduction:
+=======================
 
 This is the device driver for the IBM Hypervisor Virtual Console Server,
 "hvcs".  The IBM hvcs provides a tty driver interface to allow Linux user
@@ -38,8 +41,8 @@ ppc64 system.  Physical hardware consoles per partition are not practical
 on this hardware so system consoles are accessed by this driver using
 firmware interfaces to virtual terminal devices.
 
----------------------------------------------------------------------------
 2. System Requirements:
+=======================
 
 This device driver was written using 2.6.4 Linux kernel APIs and will only
 build and run on kernels of this version or later.
@@ -52,8 +55,8 @@ Sysfs must be mounted on the system so that the user can determine which
 major and minor numbers are associated with each vty-server.  Directions
 for sysfs mounting are outside the scope of this document.
 
----------------------------------------------------------------------------
 3. Build Options:
+=================
 
 The hvcs driver registers itself as a tty driver.  The tty layer
 dynamically allocates a block of major and minor numbers in a quantity
@@ -65,11 +68,11 @@ If the default number of device entries is adequate then this driver can be
 built into the kernel.  If not, the default can be over-ridden by inserting
 the driver as a module with insmod parameters.
 
----------------------------------------------------------------------------
 3.1 Built-in:
+-------------
 
 The following menuconfig example demonstrates selecting to build this
-driver into the kernel.
+driver into the kernel::
 
 	Device Drivers  --->
 		Character devices  --->
@@ -77,11 +80,11 @@ driver into the kernel.
 
 Begin the kernel make process.
 
----------------------------------------------------------------------------
 3.2 Module:
+-----------
 
 The following menuconfig example demonstrates selecting to build this
-driver as a kernel module.
+driver as a kernel module::
 
 	Device Drivers  --->
 		Character devices  --->
@@ -89,11 +92,11 @@ driver as a kernel module.
 
 The make process will build the following kernel modules:
 
-	hvcs.ko
-	hvcserver.ko
+	- hvcs.ko
+	- hvcserver.ko
 
 To insert the module with the default allocation execute the following
-commands in the order they appear:
+commands in the order they appear::
 
 	insmod hvcserver.ko
 	insmod hvcs.ko
@@ -103,7 +106,7 @@ be inserted first, otherwise the hvcs module will not find some of the
 symbols it expects.
 
 To override the default use an insmod parameter as follows (requesting 4
-tty devices as an example):
+tty devices as an example)::
 
 	insmod hvcs.ko hvcs_parm_num_devs=4
 
@@ -115,31 +118,31 @@ source file before building.
 NOTE: The length of time it takes to insmod the driver seems to be related
 to the number of tty interfaces the registering driver requests.
 
-In order to remove the driver module execute the following command:
+In order to remove the driver module execute the following command::
 
 	rmmod hvcs.ko
 
 The recommended method for installing hvcs as a module is to use depmod to
 build a current modules.dep file in /lib/modules/`uname -r` and then
-execute:
+execute::
 
-modprobe hvcs hvcs_parm_num_devs=4
+	modprobe hvcs hvcs_parm_num_devs=4
 
 The modules.dep file indicates that hvcserver.ko needs to be inserted
 before hvcs.ko and modprobe uses this file to smartly insert the modules in
 the proper order.
 
 The following modprobe command is used to remove hvcs and hvcserver in the
-proper order:
+proper order::
 
-modprobe -r hvcs
+	modprobe -r hvcs
 
----------------------------------------------------------------------------
 4. Installation:
+================
 
 The tty layer creates sysfs entries which contain the major and minor
 numbers allocated for the hvcs driver.  The following snippet of "tree"
-output of the sysfs directory shows where these numbers are presented:
+output of the sysfs directory shows where these numbers are presented::
 
 	sys/
 	|-- *other sysfs base dirs*
@@ -164,7 +167,7 @@ output of the sysfs directory shows where these numbers are presented:
 	|-- *other sysfs base dirs*
 
 For the above examples the following output is a result of cat'ing the
-"dev" entry in the hvcs directory:
+"dev" entry in the hvcs directory::
 
 	Pow5:/sys/class/tty/hvcs0/ # cat dev
 	254:0
@@ -184,7 +187,7 @@ systems running hvcs will already have the device entries created or udev
 will do it automatically.
 
 Given the example output above, to manually create a /dev/hvcs* node entry
-mknod can be used as follows:
+mknod can be used as follows::
 
 	mknod /dev/hvcs0 c 254 0
 	mknod /dev/hvcs1 c 254 1
@@ -195,15 +198,15 @@ Using mknod to manually create the device entries makes these device nodes
 persistent.  Once created they will exist prior to the driver insmod.
 
 Attempting to connect an application to /dev/hvcs* prior to insertion of
-the hvcs module will result in an error message similar to the following:
+the hvcs module will result in an error message similar to the following::
 
 	"/dev/hvcs*: No such device".
 
 NOTE: Just because there is a device node present doesn't mean that there
 is a vty-server device configured for that node.
 
----------------------------------------------------------------------------
 5. Connection
+=============
 
 Since this driver controls devices that provide a tty interface a user can
 interact with the device node entries using any standard tty-interactive
@@ -249,7 +252,7 @@ vty-server adapter is associated with which /dev/hvcs* node a special sysfs
 attribute has been added to each vty-server sysfs entry.  This entry is
 called "index" and showing it reveals an integer that refers to the
 /dev/hvcs* entry to use to connect to that device.  For instance cating the
-index attribute of vty-server adapter 30000004 shows the following.
+index attribute of vty-server adapter 30000004 shows the following::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
 	2
@@ -262,8 +265,8 @@ system the /dev/hvcs* entry that interacts with a particular vty-server
 adapter is not guaranteed to remain the same across system reboots.  Look
 in the Q & A section for more on this issue.
 
----------------------------------------------------------------------------
 6. Disconnection
+================
 
 As a security feature to prevent the delivery of stale data to an
 unintended target the Power5 system firmware disables the fetching of data
@@ -305,7 +308,7 @@ connection between the vty-server and target vty ONLY if the vterm_state
 previously read '1'.  The write directive is ignored if the vterm_state
 read '0' or if any value other than '0' was written to the vterm_state
 attribute.  The following example will show the method used for verifying
-the vty-server connection status and disconnecting a vty-server connection.
+the vty-server connection status and disconnecting a vty-server connection::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
 	1
@@ -318,12 +321,12 @@ the vty-server connection status and disconnecting a vty-server connection.
 All vty-server connections are automatically terminated when the device is
 hotplug removed and when the module is removed.
 
----------------------------------------------------------------------------
 7. Configuration
+================
 
 Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
 is symlinked in several other sysfs tree directories, notably under the
-hvcs driver entry, which looks like the following example:
+hvcs driver entry, which looks like the following example::
 
 	Pow5:/sys/bus/vio/drivers/hvcs # ls
 	.  ..  30000003  30000004  rescan
@@ -344,7 +347,7 @@ completed or was never executed.
 
 Vty-server entries in this directory are a 32 bit partition unique unit
 address that is created by firmware.  An example vty-server sysfs entry
-looks like the following:
+looks like the following::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
 	.   current_vty   devspec       name          partner_vtys
@@ -352,21 +355,21 @@ looks like the following:
 
 Each entry is provided, by default with a "name" attribute.  Reading the
 "name" attribute will reveal the device type as shown in the following
-example:
+example::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
 	vty-server
 
 Each entry is also provided, by default, with a "devspec" attribute which
 reveals the full device specification when read, as shown in the following
-example:
+example::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
 	/vdevice/vty-server@30000004
 
 Each vty-server sysfs dir is provided with two read-only attributes that
 provide lists of easily parsed partner vty data: "partner_vtys" and
-"partner_clcs".
+"partner_clcs"::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
 	30000000
@@ -396,7 +399,7 @@ A vty-server can only be connected to a single vty at a time.  The entry,
 read.
 
 The current_vty can be changed by writing a valid partner clc to the entry
-as in the following example:
+as in the following example::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
 	8A-V4-C0 > current_vty
@@ -408,9 +411,9 @@ currently open connection is freed.
 Information on the "vterm_state" attribute was covered earlier on the
 chapter entitled "disconnection".
 
----------------------------------------------------------------------------
 8. Questions & Answers:
-===========================================================================
+=======================
+
 Q: What are the security concerns involving hvcs?
 
 A: There are three main security concerns:
@@ -429,6 +432,7 @@ A: There are three main security concerns:
 	partition) will experience the previously logged in session.
 
 ---------------------------------------------------------------------------
+
 Q: How do I multiplex a console that I grab through hvcs so that other
 people can see it:
 
@@ -440,6 +444,7 @@ term type "screen" to others.  This means that curses based programs may
 not display properly in screen sessions.
 
 ---------------------------------------------------------------------------
+
 Q: Why are the colors all messed up?
 Q: Why are the control characters acting strange or not working?
 Q: Why is the console output all strange and unintelligible?
@@ -455,6 +460,7 @@ disconnect from the console.  This will ensure that the next user gets
 their own TERM type set when they login.
 
 ---------------------------------------------------------------------------
+
 Q: When I try to CONNECT kermit to an hvcs device I get:
 "Sorry, can't open connection: /dev/hvcs*"What is happening?
 
@@ -490,6 +496,7 @@ A: There is not a corresponding vty-server device that maps to an existing
 /dev/hvcs* entry.
 
 ---------------------------------------------------------------------------
+
 Q: When I try to CONNECT kermit to an hvcs device I get:
 "Sorry, write access to UUCP lockfile directory denied."
 
@@ -497,6 +504,7 @@ A: The /dev/hvcs* entry you have specified doesn't exist where you said it
 does?  Maybe you haven't inserted the module (on systems with udev).
 
 ---------------------------------------------------------------------------
+
 Q: If I already have one Linux partition installed can I use hvcs on said
 partition to provide the console for the install of a second Linux
 partition?
@@ -505,6 +513,7 @@ A: Yes granted that your are connected to the /dev/hvcs* device using
 kermit or cu or some other program that doesn't provide terminal emulation.
 
 ---------------------------------------------------------------------------
+
 Q: Can I connect to more than one partition's console at a time using this
 driver?
 
@@ -512,6 +521,7 @@ A: Yes.  Of course this means that there must be more than one vty-server
 configured for this partition and each must point to a disconnected vty.
 
 ---------------------------------------------------------------------------
+
 Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
 
 A: Yes, if you have dlpar and hotplug enabled for your system and it has
@@ -519,6 +529,7 @@ been built into the kernel the hvcs drivers is configured to dynamically
 handle additions of new devices and removals of unused devices.
 
 ---------------------------------------------------------------------------
+
 Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
 after a reboot.  What happened?
 
@@ -533,6 +544,7 @@ on how to determine which vty-server goes with which /dev/hvcs* node.
 Hint; look at the sysfs "index" attribute for the vty-server.
 
 ---------------------------------------------------------------------------
+
 Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
 device on that partition as the other end of the pipe?
 
@@ -554,7 +566,9 @@ read or write to /dev/hvcs*.  Now you have a tty conduit between two
 partitions.
 
 ---------------------------------------------------------------------------
+
 9. Reporting Bugs:
+==================
 
 The proper channel for reporting bugs is either through the Linux OS
 distribution company that provided your OS or by posting issues to the
diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst
new file mode 100644
index 000000000000..549b1cdd77ae
--- /dev/null
+++ b/Documentation/powerpc/index.rst
@@ -0,0 +1,34 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======
+powerpc
+=======
+
+.. toctree::
+    :maxdepth: 1
+
+    bootwrapper
+    cpu_families
+    cpu_features
+    cxl
+    cxlflash
+    dawr-power9
+    dscr
+    eeh-pci-error-recovery
+    firmware-assisted-dump
+    hvcs
+    isa-versions
+    mpc52xx
+    pci_iov_resource_on_powernv
+    pmu-ebb
+    ptrace
+    qe_firmware
+    syscall64-abi
+    transactional_memory
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/powerpc/isa-versions.rst
index 66c24140ebf1..a363d8c1603c 100644
--- a/Documentation/powerpc/isa-versions.rst
+++ b/Documentation/powerpc/isa-versions.rst
@@ -1,13 +1,12 @@
-:orphan:
-
+==========================
 CPU to ISA Version Mapping
 ==========================
 
 Mapping of some CPU versions to relevant ISA versions.
 
-========= ====================
+========= ====================================================================
 CPU       Architecture version
-========= ====================
+========= ====================================================================
 Power9    Power ISA v3.0B
 Power8    Power ISA v2.07
 Power7    Power ISA v2.06
@@ -24,7 +23,7 @@ PPC970    - PowerPC User Instruction Set Architecture Book I v2.01
           - PowerPC Virtual Environment Architecture Book II v2.01
           - PowerPC Operating Environment Architecture Book III v2.01
           - Plus Altivec/VMX ~= 2.03
-========= ====================
+========= ====================================================================
 
 
 Key Features
@@ -60,9 +59,9 @@ Power5     No
 PPC970     No
 ========== ====
 
-========== ====================
+========== ====================================
 CPU        Transactional Memory
-========== ====================
+========== ====================================
 Power9     Yes (* see transactional_memory.txt)
 Power8     Yes
 Power7     No
@@ -73,4 +72,4 @@ Power5++   No
 Power5+    No
 Power5     No
 PPC970     No
-========== ====================
+========== ====================================
diff --git a/Documentation/powerpc/mpc52xx.txt b/Documentation/powerpc/mpc52xx.rst
similarity index 91%
rename from Documentation/powerpc/mpc52xx.txt
rename to Documentation/powerpc/mpc52xx.rst
index 0d540a31ea1a..8676ac63e077 100644
--- a/Documentation/powerpc/mpc52xx.txt
+++ b/Documentation/powerpc/mpc52xx.rst
@@ -1,11 +1,13 @@
+=============================
 Linux 2.6.x on MPC52xx family
------------------------------
+=============================
 
 For the latest info, go to http://www.246tNt.com/mpc52xx/
 
 To compile/use :
 
-  - U-Boot:
+  - U-Boot::
+
      # <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
         if you wish to ).
      # make lite5200_defconfig
@@ -16,7 +18,8 @@ To compile/use :
      => tftpboot 400000 pRamdisk
      => bootm 200000 400000
 
-  - DBug:
+  - DBug::
+
      # <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
         if you wish to ).
      # make lite5200_defconfig
@@ -28,7 +31,8 @@ To compile/use :
      DBug> dn -i zImage.initrd.lite5200
 
 
-Some remarks :
+Some remarks:
+
  - The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100
    is not supported, and I'm not sure anyone is interesting in working on it
    so. I didn't took 5xxx because there's apparently a lot of 5xxx that have
diff --git a/Documentation/powerpc/pci_iov_resource_on_powernv.txt b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
similarity index 97%
rename from Documentation/powerpc/pci_iov_resource_on_powernv.txt
rename to Documentation/powerpc/pci_iov_resource_on_powernv.rst
index b55c5cd83f8d..f5a5793e1613 100644
--- a/Documentation/powerpc/pci_iov_resource_on_powernv.txt
+++ b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
@@ -1,6 +1,13 @@
+===================================================
+PCI Express I/O Virtualization Resource on Powerenv
+===================================================
+
 Wei Yang <weiyang@linux.vnet.ibm.com>
+
 Benjamin Herrenschmidt <benh@au1.ibm.com>
+
 Bjorn Helgaas <bhelgaas@google.com>
+
 26 Aug 2014
 
 This document describes the requirement from hardware for PCI MMIO resource
@@ -10,6 +17,7 @@ Endpoints and the implementation on P8 (IODA2). The next two sections talks
 about considerations on enabling SRIOV on IODA2.
 
 1. Introduction to Partitionable Endpoints
+==========================================
 
 A Partitionable Endpoint (PE) is a way to group the various resources
 associated with a device or a set of devices to provide isolation between
@@ -35,6 +43,7 @@ is a completely separate HW entity that replicates the entire logic, so has
 its own set of PEs, etc.
 
 2. Implementation of Partitionable Endpoints on P8 (IODA2)
+==========================================================
 
 P8 supports up to 256 Partitionable Endpoints per PHB.
 
@@ -149,6 +158,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
     sense, but we haven't done it yet.
 
 3. Considerations for SR-IOV on PowerKVM
+========================================
 
   * SR-IOV Background
 
@@ -224,7 +234,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
   IODA supports 256 PEs, so segmented windows contain 256 segments, so if
   total_VFs is less than 256, we have the situation in Figure 1.0, where
   segments [total_VFs, 255] of the M64 window may map to some MMIO range on
-  other devices:
+  other devices::
 
      0      1                     total_VFs - 1
      +------+------+-     -+------+------+
@@ -243,7 +253,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
 		Figure 1.0 Direct map VF(n) BAR space
 
   Our current solution is to allocate 256 segments even if the VF(n) BAR
-  space doesn't need that much, as shown in Figure 1.1:
+  space doesn't need that much, as shown in Figure 1.1::
 
      0      1                     total_VFs - 1                255
      +------+------+-     -+------+------+-      -+------+------+
@@ -269,6 +279,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
   responds to segments [total_VFs, 255].
 
 4. Implications for the Generic PCI Code
+========================================
 
 The PCIe SR-IOV spec requires that the base of the VF(n) BAR space be
 aligned to the size of an individual VF BAR.
diff --git a/Documentation/powerpc/pmu-ebb.txt b/Documentation/powerpc/pmu-ebb.rst
similarity index 99%
rename from Documentation/powerpc/pmu-ebb.txt
rename to Documentation/powerpc/pmu-ebb.rst
index 73cd163dbfb8..4f474758eb55 100644
--- a/Documentation/powerpc/pmu-ebb.txt
+++ b/Documentation/powerpc/pmu-ebb.rst
@@ -1,3 +1,4 @@
+========================
 PMU Event Based Branches
 ========================
 
diff --git a/Documentation/powerpc/ptrace.txt b/Documentation/powerpc/ptrace.rst
similarity index 48%
rename from Documentation/powerpc/ptrace.txt
rename to Documentation/powerpc/ptrace.rst
index 99c5ce88d0fe..864d4b6dddd1 100644
--- a/Documentation/powerpc/ptrace.txt
+++ b/Documentation/powerpc/ptrace.rst
@@ -1,3 +1,7 @@
+======
+Ptrace
+======
+
 GDB intends to support the following hardware debug features of BookE
 processors:
 
@@ -12,6 +16,7 @@ that GDB doesn't need to special-case each of them. We added the
 following 3 new ptrace requests.
 
 1. PTRACE_PPC_GETHWDEBUGINFO
+============================
 
 Query for GDB to discover the hardware debug features. The main info to
 be returned here is the minimum alignment for the hardware watchpoints.
@@ -22,9 +27,9 @@ adding special cases to GDB based on what it sees in AUXV.
 Since we're at it, we added other useful info that the kernel can return to
 GDB: this query will return the number of hardware breakpoints, hardware
 watchpoints and whether it supports a range of addresses and a condition.
-The query will fill the following structure provided by the requesting process:
+The query will fill the following structure provided by the requesting process::
 
-struct ppc_debug_info {
+  struct ppc_debug_info {
        unit32_t version;
        unit32_t num_instruction_bps;
        unit32_t num_data_bps;
@@ -32,46 +37,46 @@ struct ppc_debug_info {
        unit32_t data_bp_alignment;
        unit32_t sizeof_condition; /* size of the DVC register */
        uint64_t features; /* bitmask of the individual flags */
-};
+  };
 
-features will have bits indicating whether there is support for:
+features will have bits indicating whether there is support for::
 
-#define PPC_DEBUG_FEATURE_INSN_BP_RANGE		0x1
-#define PPC_DEBUG_FEATURE_INSN_BP_MASK		0x2
-#define PPC_DEBUG_FEATURE_DATA_BP_RANGE		0x4
-#define PPC_DEBUG_FEATURE_DATA_BP_MASK		0x8
-#define PPC_DEBUG_FEATURE_DATA_BP_DAWR		0x10
+  #define PPC_DEBUG_FEATURE_INSN_BP_RANGE		0x1
+  #define PPC_DEBUG_FEATURE_INSN_BP_MASK		0x2
+  #define PPC_DEBUG_FEATURE_DATA_BP_RANGE		0x4
+  #define PPC_DEBUG_FEATURE_DATA_BP_MASK		0x8
+  #define PPC_DEBUG_FEATURE_DATA_BP_DAWR		0x10
 
 2. PTRACE_SETHWDEBUG
 
-Sets a hardware breakpoint or watchpoint, according to the provided structure:
+Sets a hardware breakpoint or watchpoint, according to the provided structure::
 
-struct ppc_hw_breakpoint {
+  struct ppc_hw_breakpoint {
         uint32_t version;
-#define PPC_BREAKPOINT_TRIGGER_EXECUTE  0x1
-#define PPC_BREAKPOINT_TRIGGER_READ     0x2
-#define PPC_BREAKPOINT_TRIGGER_WRITE    0x4
+  #define PPC_BREAKPOINT_TRIGGER_EXECUTE  0x1
+  #define PPC_BREAKPOINT_TRIGGER_READ     0x2
+ #define PPC_BREAKPOINT_TRIGGER_WRITE    0x4
         uint32_t trigger_type;       /* only some combinations allowed */
-#define PPC_BREAKPOINT_MODE_EXACT               0x0
-#define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE     0x1
-#define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE     0x2
-#define PPC_BREAKPOINT_MODE_MASK                0x3
+  #define PPC_BREAKPOINT_MODE_EXACT               0x0
+  #define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE     0x1
+  #define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE     0x2
+  #define PPC_BREAKPOINT_MODE_MASK                0x3
         uint32_t addr_mode;          /* address match mode */
 
-#define PPC_BREAKPOINT_CONDITION_MODE   0x3
-#define PPC_BREAKPOINT_CONDITION_NONE   0x0
-#define PPC_BREAKPOINT_CONDITION_AND    0x1
-#define PPC_BREAKPOINT_CONDITION_EXACT  0x1	/* different name for the same thing as above */
-#define PPC_BREAKPOINT_CONDITION_OR     0x2
-#define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
-#define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000	/* byte enable bits */
-#define PPC_BREAKPOINT_CONDITION_BE(n)  (1<<((n)+16))
+  #define PPC_BREAKPOINT_CONDITION_MODE   0x3
+  #define PPC_BREAKPOINT_CONDITION_NONE   0x0
+  #define PPC_BREAKPOINT_CONDITION_AND    0x1
+  #define PPC_BREAKPOINT_CONDITION_EXACT  0x1	/* different name for the same thing as above */
+  #define PPC_BREAKPOINT_CONDITION_OR     0x2
+  #define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
+  #define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000	/* byte enable bits */
+  #define PPC_BREAKPOINT_CONDITION_BE(n)  (1<<((n)+16))
         uint32_t condition_mode;     /* break/watchpoint condition flags */
 
         uint64_t addr;
         uint64_t addr2;
         uint64_t condition_value;
-};
+  };
 
 A request specifies one event, not necessarily just one register to be set.
 For instance, if the request is for a watchpoint with a condition, both the
@@ -88,61 +93,61 @@ can't be allocated on the registers.
 
 Some examples of using the structure to:
 
-- set a breakpoint in the first breakpoint register
-
-  p.version         = PPC_DEBUG_CURRENT_VERSION;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_EXECUTE;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
-  p.addr            = (uint64_t) address;
-  p.addr2           = 0;
-  p.condition_value = 0;
-
-- set a watchpoint which triggers on reads in the second watchpoint register
-
-  p.version         = PPC_DEBUG_CURRENT_VERSION;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_READ;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
-  p.addr            = (uint64_t) address;
-  p.addr2           = 0;
-  p.condition_value = 0;
-
-- set a watchpoint which triggers only with a specific value
-
-  p.version         = PPC_DEBUG_CURRENT_VERSION;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_READ;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
-  p.addr            = (uint64_t) address;
-  p.addr2           = 0;
-  p.condition_value = (uint64_t) condition;
-
-- set a ranged hardware breakpoint
-
-  p.version         = PPC_DEBUG_CURRENT_VERSION;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_EXECUTE;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
-  p.addr            = (uint64_t) begin_range;
-  p.addr2           = (uint64_t) end_range;
-  p.condition_value = 0;
-
-- set a watchpoint in server processors (BookS)
-
-  p.version         = 1;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_RW;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
-  or
-  p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
-
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
-  p.addr            = (uint64_t) begin_range;
-  /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
-   * addr2 - addr <= 8 Bytes.
-   */
-  p.addr2           = (uint64_t) end_range;
-  p.condition_value = 0;
+- set a breakpoint in the first breakpoint register::
+
+    p.version         = PPC_DEBUG_CURRENT_VERSION;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
+    p.addr            = (uint64_t) address;
+    p.addr2           = 0;
+    p.condition_value = 0;
+
+- set a watchpoint which triggers on reads in the second watchpoint register::
+
+    p.version         = PPC_DEBUG_CURRENT_VERSION;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_READ;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
+    p.addr            = (uint64_t) address;
+    p.addr2           = 0;
+    p.condition_value = 0;
+
+- set a watchpoint which triggers only with a specific value::
+
+    p.version         = PPC_DEBUG_CURRENT_VERSION;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_READ;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
+    p.addr            = (uint64_t) address;
+    p.addr2           = 0;
+    p.condition_value = (uint64_t) condition;
+
+- set a ranged hardware breakpoint::
+
+    p.version         = PPC_DEBUG_CURRENT_VERSION;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
+    p.addr            = (uint64_t) begin_range;
+    p.addr2           = (uint64_t) end_range;
+    p.condition_value = 0;
+
+- set a watchpoint in server processors (BookS)::
+
+    p.version         = 1;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_RW;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+    or
+    p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
+
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
+    p.addr            = (uint64_t) begin_range;
+    /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
+     * addr2 - addr <= 8 Bytes.
+     */
+    p.addr2           = (uint64_t) end_range;
+    p.condition_value = 0;
 
 3. PTRACE_DELHWDEBUG
 
diff --git a/Documentation/powerpc/qe_firmware.txt b/Documentation/powerpc/qe_firmware.rst
similarity index 95%
rename from Documentation/powerpc/qe_firmware.txt
rename to Documentation/powerpc/qe_firmware.rst
index e7ac24aec4ff..42f5103140c9 100644
--- a/Documentation/powerpc/qe_firmware.txt
+++ b/Documentation/powerpc/qe_firmware.rst
@@ -1,23 +1,23 @@
-	   Freescale QUICC Engine Firmware Uploading
-	   -----------------------------------------
+=========================================
+Freescale QUICC Engine Firmware Uploading
+=========================================
 
 (c) 2007 Timur Tabi <timur at freescale.com>,
     Freescale Semiconductor
 
-Table of Contents
-=================
+.. Table of Contents
 
-  I - Software License for Firmware
+   I - Software License for Firmware
 
-  II - Microcode Availability
+   II - Microcode Availability
 
-  III - Description and Terminology
+   III - Description and Terminology
 
-  IV - Microcode Programming Details
+   IV - Microcode Programming Details
 
-  V - Firmware Structure Layout
+   V - Firmware Structure Layout
 
-  VI - Sample Code for Creating Firmware Files
+   VI - Sample Code for Creating Firmware Files
 
 Revision Information
 ====================
@@ -39,7 +39,7 @@ http://opensource.freescale.com.  For other firmware files, please contact
 your Freescale representative or your operating system vendor.
 
 III - Description and Terminology
-================================
+=================================
 
 In this document, the term 'microcode' refers to the sequence of 32-bit
 integers that compose the actual QE microcode.
@@ -89,7 +89,7 @@ being fixed in the RAM package utilizing they should be activated.  This data
 structure signals the microcode which of these virtual traps is active.
 
 This structure contains 6 words that the application should copy to some
-specific been defined.  This table describes the structure.
+specific been defined.  This table describes the structure::
 
 	---------------------------------------------------------------
 	| Offset in |                  | Destination Offset | Size of |
@@ -119,7 +119,7 @@ Extended Modes
 This is a double word bit array (64 bits) that defines special functionality
 which has an impact on the software drivers.  Each bit has its own impact
 and has special instructions for the s/w associated with it.  This structure is
-described in this table:
+described in this table::
 
 	-----------------------------------------------------------------------
 	| Bit #  |     Name     |   Description                               |
@@ -220,7 +220,8 @@ The 'model' field is a 16-bit number that matches the actual SOC. The
 'major' and 'minor' fields are the major and minor revision numbers,
 respectively, of the SOC.
 
-For example, to match the 8323, revision 1.0:
+For example, to match the 8323, revision 1.0::
+
      soc.model = 8323
      soc.major = 1
      soc.minor = 0
@@ -273,10 +274,10 @@ library and available to any driver that calles qe_get_firmware_info().
 	'reserved'.
 
 After the last microcode is a 32-bit CRC.  It can be calculated using
-this algorithm:
+this algorithm::
 
-u32 crc32(const u8 *p, unsigned int len)
-{
+  u32 crc32(const u8 *p, unsigned int len)
+  {
 	unsigned int i;
 	u32 crc = 0;
 
@@ -286,7 +287,7 @@ u32 crc32(const u8 *p, unsigned int len)
 		   crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
 	}
 	return crc;
-}
+  }
 
 VI - Sample Code for Creating Firmware Files
 ============================================
diff --git a/Documentation/powerpc/syscall64-abi.txt b/Documentation/powerpc/syscall64-abi.rst
similarity index 82%
rename from Documentation/powerpc/syscall64-abi.txt
rename to Documentation/powerpc/syscall64-abi.rst
index fa716a0d88bd..e49f69f941b9 100644
--- a/Documentation/powerpc/syscall64-abi.txt
+++ b/Documentation/powerpc/syscall64-abi.rst
@@ -5,12 +5,12 @@ Power Architecture 64-bit Linux system call ABI
 syscall
 =======
 
-syscall calling sequence[*] matches the Power Architecture 64-bit ELF ABI
+syscall calling sequence\ [1]_ matches the Power Architecture 64-bit ELF ABI
 specification C function calling sequence, including register preservation
 rules, with the following differences.
 
-[*] Some syscalls (typically low-level management functions) may have
-    different calling sequences (e.g., rt_sigreturn).
+.. [1] Some syscalls (typically low-level management functions) may have
+       different calling sequences (e.g., rt_sigreturn).
 
 Parameters and return value
 ---------------------------
@@ -33,12 +33,14 @@ Register preservation rules
 Register preservation rules match the ELF ABI calling sequence with the
 following differences:
 
-r0:         Volatile.   (System call number.)
-r3:         Volatile.   (Parameter 1, and return value.)
-r4-r8:      Volatile.   (Parameters 2-6.)
-cr0:        Volatile    (cr0.SO is the return error condition)
-cr1, cr5-7: Nonvolatile.
-lr:         Nonvolatile.
+=========== ============= ========================================
+r0          Volatile      (System call number.)
+r3          Volatile      (Parameter 1, and return value.)
+r4-r8       Volatile      (Parameters 2-6.)
+cr0         Volatile      (cr0.SO is the return error condition)
+cr1, cr5-7  Nonvolatile
+lr          Nonvolatile
+=========== ============= ========================================
 
 All floating point and vector data registers as well as control and status
 registers are nonvolatile.
@@ -90,9 +92,12 @@ The vsyscall may or may not use the caller's stack frame save areas.
 
 Register preservation rules
 ---------------------------
-r0: Volatile.
-cr1, cr5-7: Volatile.
-lr: Volatile.
+
+=========== ========
+r0          Volatile
+cr1, cr5-7  Volatile
+lr          Volatile
+=========== ========
 
 Invocation
 ----------
diff --git a/Documentation/powerpc/transactional_memory.txt b/Documentation/powerpc/transactional_memory.rst
similarity index 93%
rename from Documentation/powerpc/transactional_memory.txt
rename to Documentation/powerpc/transactional_memory.rst
index 52c023e14f26..09955103acb4 100644
--- a/Documentation/powerpc/transactional_memory.txt
+++ b/Documentation/powerpc/transactional_memory.rst
@@ -1,3 +1,4 @@
+============================
 Transactional Memory support
 ============================
 
@@ -17,29 +18,29 @@ instructions are presented to delimit transactions; transactions are
 guaranteed to either complete atomically or roll back and undo any partial
 changes.
 
-A simple transaction looks like this:
+A simple transaction looks like this::
 
-begin_move_money:
-  tbegin
-  beq   abort_handler
+  begin_move_money:
+    tbegin
+    beq   abort_handler
 
-  ld    r4, SAVINGS_ACCT(r3)
-  ld    r5, CURRENT_ACCT(r3)
-  subi  r5, r5, 1
-  addi  r4, r4, 1
-  std   r4, SAVINGS_ACCT(r3)
-  std   r5, CURRENT_ACCT(r3)
+    ld    r4, SAVINGS_ACCT(r3)
+    ld    r5, CURRENT_ACCT(r3)
+    subi  r5, r5, 1
+    addi  r4, r4, 1
+    std   r4, SAVINGS_ACCT(r3)
+    std   r5, CURRENT_ACCT(r3)
 
-  tend
+    tend
 
-  b     continue
+    b     continue
 
-abort_handler:
-  ... test for odd failures ...
+  abort_handler:
+    ... test for odd failures ...
 
-  /* Retry the transaction if it failed because it conflicted with
-   * someone else: */
-  b     begin_move_money
+    /* Retry the transaction if it failed because it conflicted with
+     * someone else: */
+    b     begin_move_money
 
 
 The 'tbegin' instruction denotes the start point, and 'tend' the end point.
@@ -123,7 +124,7 @@ Transaction-aware signal handlers can read the transactional register state
 from the second ucontext.  This will be necessary for crash handlers to
 determine, for example, the address of the instruction causing the SIGSEGV.
 
-Example signal handler:
+Example signal handler::
 
     void crash_handler(int sig, siginfo_t *si, void *uc)
     {
@@ -133,9 +134,9 @@ Example signal handler:
       if (ucp_link) {
         u64 msr = ucp->uc_mcontext.regs->msr;
         /* May have transactional ucontext! */
-#ifndef __powerpc64__
+  #ifndef __powerpc64__
         msr |= ((u64)transactional_ucp->uc_mcontext.regs->msr) << 32;
-#endif
+  #endif
         if (MSR_TM_ACTIVE(msr)) {
            /* Yes, we crashed during a transaction.  Oops. */
    fprintf(stderr, "Transaction to be restarted at 0x%llx, but "
@@ -176,6 +177,7 @@ Failure cause codes used by kernel
 These are defined in <asm/reg.h>, and distinguish different reasons why the
 kernel aborted a transaction:
 
+ ====================== ================================
  TM_CAUSE_RESCHED       Thread was rescheduled.
  TM_CAUSE_TLBI          Software TLB invalid.
  TM_CAUSE_FAC_UNAV      FP/VEC/VSX unavailable trap.
@@ -184,6 +186,7 @@ kernel aborted a transaction:
  TM_CAUSE_MISC          Currently unused.
  TM_CAUSE_ALIGNMENT     Alignment fault.
  TM_CAUSE_EMULATE       Emulation that touched memory.
+ ====================== ================================
 
 These can be checked by the user program's abort handler as TEXASR[0:7].  If
 bit 7 is set, it indicates that the error is consider persistent.  For example
@@ -203,7 +206,7 @@ POWER9
 ======
 
 TM on POWER9 has issues with storing the complete register state. This
-is described in this commit:
+is described in this commit::
 
     commit 4bb3c7a0208fc13ca70598efd109901a7cd45ae7
     Author: Paul Mackerras <paulus@ozlabs.org>
diff --git a/MAINTAINERS b/MAINTAINERS
index 3d6cd6efb264..15b58d5947a3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4469,7 +4469,7 @@ F:	arch/powerpc/platforms/powernv/pci-cxl.c
 F:	drivers/misc/cxl/
 F:	include/misc/cxl*
 F:	include/uapi/misc/cxl.h
-F:	Documentation/powerpc/cxl.txt
+F:	Documentation/powerpc/cxl.rst
 F:	Documentation/ABI/testing/sysfs-class-cxl
 
 CXLFLASH (IBM Coherent Accelerator Processor Interface CAPI Flash) SCSI DRIVER
@@ -4480,7 +4480,7 @@ L:	linux-scsi@vger.kernel.org
 S:	Supported
 F:	drivers/scsi/cxlflash/
 F:	include/uapi/scsi/cxlflash_ioctl.h
-F:	Documentation/powerpc/cxlflash.txt
+F:	Documentation/powerpc/cxlflash.rst
 
 CYBERPRO FB DRIVER
 M:	Russell King <linux@armlinux.org.uk>
@@ -12394,7 +12394,7 @@ F:	Documentation/PCI/pci-error-recovery.rst
 F:	drivers/pci/pcie/aer.c
 F:	drivers/pci/pcie/dpc.c
 F:	drivers/pci/pcie/err.c
-F:	Documentation/powerpc/eeh-pci-error-recovery.txt
+F:	Documentation/powerpc/eeh-pci-error-recovery.rst
 F:	arch/powerpc/kernel/eeh*.c
 F:	arch/powerpc/platforms/*/eeh*.c
 F:	arch/powerpc/include/*/eeh*.h
diff --git a/arch/powerpc/kernel/exceptions-64s.S b/arch/powerpc/kernel/exceptions-64s.S
index eee5bef736c8..6ba3cc2ef8ab 100644
--- a/arch/powerpc/kernel/exceptions-64s.S
+++ b/arch/powerpc/kernel/exceptions-64s.S
@@ -1531,7 +1531,7 @@ EXC_COMMON(trap_0b_common, 0xb00, unknown_exception)
  *
  * Call convention:
  *
- * syscall register convention is in Documentation/powerpc/syscall64-abi.txt
+ * syscall register convention is in Documentation/powerpc/syscall64-abi.rst
  *
  * For hypercalls, the register convention is as follows:
  * r0 volatile
diff --git a/drivers/soc/fsl/qe/qe.c b/drivers/soc/fsl/qe/qe.c
index 62c6ba17991a..c9519e62308c 100644
--- a/drivers/soc/fsl/qe/qe.c
+++ b/drivers/soc/fsl/qe/qe.c
@@ -419,7 +419,7 @@ static void qe_upload_microcode(const void *base,
 /*
  * Upload a microcode to the I-RAM at a specific address.
  *
- * See Documentation/powerpc/qe_firmware.txt for information on QE microcode
+ * See Documentation/powerpc/qe_firmware.rst for information on QE microcode
  * uploading.
  *
  * Currently, only version 1 is supported, so the 'version' field must be
diff --git a/drivers/tty/hvc/hvcs.c b/drivers/tty/hvc/hvcs.c
index cb4db1b3ca3c..5fb214e67d73 100644
--- a/drivers/tty/hvc/hvcs.c
+++ b/drivers/tty/hvc/hvcs.c
@@ -47,7 +47,7 @@
  * using the 2.6 Linux kernel kref construct.
  *
  * For direction on installation and usage of this driver please reference
- * Documentation/powerpc/hvcs.txt.
+ * Documentation/powerpc/hvcs.rst.
  */
 
 #include <linux/device.h>
diff --git a/include/soc/fsl/qe/qe.h b/include/soc/fsl/qe/qe.h
index 3f9d6b6a5691..c1036d16ed03 100644
--- a/include/soc/fsl/qe/qe.h
+++ b/include/soc/fsl/qe/qe.h
@@ -259,7 +259,7 @@ static inline int qe_alive_during_sleep(void)
 
 /* Structure that defines QE firmware binary files.
  *
- * See Documentation/powerpc/qe_firmware.txt for a description of these
+ * See Documentation/powerpc/qe_firmware.rst for a description of these
  * fields.
  */
 struct qe_firmware {
-- 
2.21.0

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

* [PATCH v2 03/26] docs: powerpc: convert docs to ReST and rename to *.rst
@ 2019-07-26 12:51   ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: linux-doc, linux-pci, Oliver O'Halloran,
	Mauro Carvalho Chehab, Qiang Zhao, linux-scsi, Jonathan Corbet,
	Jiri Slaby, Linas Vepstas, Andrew Donnellan, Manoj N. Kumar,
	Bjorn Helgaas, linux-arm-kernel, Matthew R. Ochs, Uma Krishnan,
	Sam Bobroff, Greg Kroah-Hartman, Li Yang, Andrew Donnellan,
	Frederic Barrat, Paul Mackerras, linuxppc-dev

Convert docs to ReST and add them to the arch-specific
book.

The conversion here was trivial, as almost every file there
was already using an elegant format close to ReST standard.

The changes were mostly to mark literal blocks and add a few
missing section title identifiers.

One note with regards to "--": on Sphinx, this can't be used
to identify a list, as it will format it badly. This can be
used, however, to identify a long hyphen - and "---" is an
even longer one.

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: Andrew Donnellan <andrew.donnellan@au1.ibm.com> # cxl
---
 Documentation/PCI/pci-error-recovery.rst      |   2 +-
 Documentation/index.rst                       |   1 +
 .../{bootwrapper.txt => bootwrapper.rst}      |  28 ++-
 .../{cpu_families.txt => cpu_families.rst}    |  23 +--
 .../{cpu_features.txt => cpu_features.rst}    |   6 +-
 Documentation/powerpc/{cxl.txt => cxl.rst}    |  46 +++--
 .../powerpc/{cxlflash.txt => cxlflash.rst}    |  10 +-
 .../{DAWR-POWER9.txt => dawr-power9.rst}      |  15 +-
 Documentation/powerpc/{dscr.txt => dscr.rst}  |  18 +-
 ...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +++++------
 ...ed-dump.txt => firmware-assisted-dump.rst} | 117 ++++++------
 Documentation/powerpc/{hvcs.txt => hvcs.rst}  | 108 ++++++-----
 Documentation/powerpc/index.rst               |  34 ++++
 Documentation/powerpc/isa-versions.rst        |  15 +-
 .../powerpc/{mpc52xx.txt => mpc52xx.rst}      |  12 +-
 ...nv.txt => pci_iov_resource_on_powernv.rst} |  15 +-
 .../powerpc/{pmu-ebb.txt => pmu-ebb.rst}      |   1 +
 .../powerpc/{ptrace.txt => ptrace.rst}        | 169 +++++++++---------
 .../{qe_firmware.txt => qe_firmware.rst}      |  37 ++--
 .../{syscall64-abi.txt => syscall64-abi.rst}  |  29 +--
 ...al_memory.txt => transactional_memory.rst} |  45 ++---
 MAINTAINERS                                   |   6 +-
 arch/powerpc/kernel/exceptions-64s.S          |   2 +-
 drivers/soc/fsl/qe/qe.c                       |   2 +-
 drivers/tty/hvc/hvcs.c                        |   2 +-
 include/soc/fsl/qe/qe.h                       |   2 +-
 26 files changed, 495 insertions(+), 358 deletions(-)
 rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
 rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
 rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
 rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
 rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
 rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
 rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
 rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
 rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
 rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
 create mode 100644 Documentation/powerpc/index.rst
 rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
 rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
 rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
 rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
 rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
 rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
 rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)

diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
index 83db42092935..69800a9d1b0d 100644
--- a/Documentation/PCI/pci-error-recovery.rst
+++ b/Documentation/PCI/pci-error-recovery.rst
@@ -403,7 +403,7 @@ That is, the recovery API only requires that:
 .. note::
 
    Implementation details for the powerpc platform are discussed in
-   the file Documentation/powerpc/eeh-pci-error-recovery.txt
+   the file Documentation/powerpc/eeh-pci-error-recovery.rst
 
    As of this writing, there is a growing list of device drivers with
    patches implementing error recovery. Not all of these patches are in
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 230e550e9741..68ae2a4d689d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -144,6 +144,7 @@ implementation.
    arm64/index
    ia64/index
    m68k/index
+   powerpc/index
    riscv/index
    s390/index
    sh/index
diff --git a/Documentation/powerpc/bootwrapper.txt b/Documentation/powerpc/bootwrapper.rst
similarity index 93%
rename from Documentation/powerpc/bootwrapper.txt
rename to Documentation/powerpc/bootwrapper.rst
index d60fced5e1cc..a6292afba573 100644
--- a/Documentation/powerpc/bootwrapper.txt
+++ b/Documentation/powerpc/bootwrapper.rst
@@ -1,5 +1,7 @@
+========================
 The PowerPC boot wrapper
-------------------------
+========================
+
 Copyright (C) Secret Lab Technologies Ltd.
 
 PowerPC image targets compresses and wraps the kernel image (vmlinux) with
@@ -21,6 +23,7 @@ it uses the wrapper script (arch/powerpc/boot/wrapper) to generate target
 image.  The details of the build system is discussed in the next section.
 Currently, the following image format targets exist:
 
+   ==================== ========================================================
    cuImage.%:		Backwards compatible uImage for older version of
 			U-Boot (for versions that don't understand the device
 			tree).  This image embeds a device tree blob inside
@@ -29,31 +32,36 @@ Currently, the following image format targets exist:
 			with boot wrapper code that extracts data from the old
 			bd_info structure and loads the data into the device
 			tree before jumping into the kernel.
-			  Because of the series of #ifdefs found in the
+
+			Because of the series of #ifdefs found in the
 			bd_info structure used in the old U-Boot interfaces,
 			cuImages are platform specific.  Each specific
 			U-Boot platform has a different platform init file
 			which populates the embedded device tree with data
 			from the platform specific bd_info file.  The platform
 			specific cuImage platform init code can be found in
-			arch/powerpc/boot/cuboot.*.c.  Selection of the correct
+			`arch/powerpc/boot/cuboot.*.c`. Selection of the correct
 			cuImage init code for a specific board can be found in
 			the wrapper structure.
+
    dtbImage.%:		Similar to zImage, except device tree blob is embedded
 			inside the image instead of provided by firmware.  The
 			output image file can be either an elf file or a flat
 			binary depending on the platform.
-			  dtbImages are used on systems which do not have an
+
+			dtbImages are used on systems which do not have an
 			interface for passing a device tree directly.
 			dtbImages are similar to simpleImages except that
 			dtbImages have platform specific code for extracting
 			data from the board firmware, but simpleImages do not
 			talk to the firmware at all.
-			  PlayStation 3 support uses dtbImage.  So do Embedded
+
+			PlayStation 3 support uses dtbImage.  So do Embedded
 			Planet boards using the PlanetCore firmware.  Board
 			specific initialization code is typically found in a
 			file named arch/powerpc/boot/<platform>.c; but this
 			can be overridden by the wrapper script.
+
    simpleImage.%:	Firmware independent compressed image that does not
 			depend on any particular firmware interface and embeds
 			a device tree blob.  This image is a flat binary that
@@ -61,14 +69,16 @@ Currently, the following image format targets exist:
 			Firmware cannot pass any configuration data to the
 			kernel with this image type and it depends entirely on
 			the embedded device tree for all information.
-			  The simpleImage is useful for booting systems with
+
+			The simpleImage is useful for booting systems with
 			an unknown firmware interface or for booting from
 			a debugger when no firmware is present (such as on
 			the Xilinx Virtex platform).  The only assumption that
 			simpleImage makes is that RAM is correctly initialized
 			and that the MMU is either off or has RAM mapped to
 			base address 0.
-			  simpleImage also supports inserting special platform
+
+			simpleImage also supports inserting special platform
 			specific initialization code to the start of the bootup
 			sequence.  The virtex405 platform uses this feature to
 			ensure that the cache is invalidated before caching
@@ -81,9 +91,11 @@ Currently, the following image format targets exist:
 			named (virtex405-<board>.dts).  Search the wrapper
 			script for 'virtex405' and see the file
 			arch/powerpc/boot/virtex405-head.S for details.
+
    treeImage.%;		Image format for used with OpenBIOS firmware found
 			on some ppc4xx hardware.  This image embeds a device
 			tree blob inside the image.
+
    uImage:		Native image format used by U-Boot.  The uImage target
 			does not add any boot code.  It just wraps a compressed
 			vmlinux in the uImage data structure.  This image
@@ -91,12 +103,14 @@ Currently, the following image format targets exist:
 			a device tree to the kernel at boot.  If using an older
 			version of U-Boot, then you need to use a cuImage
 			instead.
+
    zImage.%:		Image format which does not embed a device tree.
 			Used by OpenFirmware and other firmware interfaces
 			which are able to supply a device tree.  This image
 			expects firmware to provide the device tree at boot.
 			Typically, if you have general purpose PowerPC
 			hardware then you want this image format.
+   ==================== ========================================================
 
 Image types which embed a device tree blob (simpleImage, dtbImage, treeImage,
 and cuImage) all generate the device tree blob from a file in the
diff --git a/Documentation/powerpc/cpu_families.txt b/Documentation/powerpc/cpu_families.rst
similarity index 95%
rename from Documentation/powerpc/cpu_families.txt
rename to Documentation/powerpc/cpu_families.rst
index fc08e22feb1a..1e063c5440c3 100644
--- a/Documentation/powerpc/cpu_families.txt
+++ b/Documentation/powerpc/cpu_families.rst
@@ -1,3 +1,4 @@
+============
 CPU Families
 ============
 
@@ -8,8 +9,8 @@ and are supported by arch/powerpc.
 Book3S (aka sPAPR)
 ------------------
 
- - Hash MMU
- - Mix of 32 & 64 bit
+- Hash MMU
+- Mix of 32 & 64 bit::
 
    +--------------+                 +----------------+
    |  Old POWER   | --------------> | RS64 (threads) |
@@ -108,8 +109,8 @@ Book3S (aka sPAPR)
 IBM BookE
 ---------
 
- - Software loaded TLB.
- - All 32 bit
+- Software loaded TLB.
+- All 32 bit::
 
    +--------------+
    |     401      |
@@ -155,8 +156,8 @@ IBM BookE
 Motorola/Freescale 8xx
 ----------------------
 
- - Software loaded with hardware assist.
- - All 32 bit
+- Software loaded with hardware assist.
+- All 32 bit::
 
    +-------------+
    | MPC8xx Core |
@@ -166,9 +167,9 @@ Motorola/Freescale 8xx
 Freescale BookE
 ---------------
 
- - Software loaded TLB.
- - e6500 adds HW loaded indirect TLB entries.
- - Mix of 32 & 64 bit
+- Software loaded TLB.
+- e6500 adds HW loaded indirect TLB entries.
+- Mix of 32 & 64 bit::
 
    +--------------+
    |     e200     |
@@ -207,8 +208,8 @@ Freescale BookE
 IBM A2 core
 -----------
 
- - Book3E, software loaded TLB + HW loaded indirect TLB entries.
- - 64 bit
+- Book3E, software loaded TLB + HW loaded indirect TLB entries.
+- 64 bit::
 
    +--------------+     +----------------+
    |   A2 core    | --> |      WSP       |
diff --git a/Documentation/powerpc/cpu_features.txt b/Documentation/powerpc/cpu_features.rst
similarity index 97%
rename from Documentation/powerpc/cpu_features.txt
rename to Documentation/powerpc/cpu_features.rst
index ae09df8722c8..b7bcdd2f41bb 100644
--- a/Documentation/powerpc/cpu_features.txt
+++ b/Documentation/powerpc/cpu_features.rst
@@ -1,3 +1,7 @@
+============
+CPU Features
+============
+
 Hollis Blanchard <hollis@austin.ibm.com>
 5 Jun 2002
 
@@ -32,7 +36,7 @@ anyways).
 After detecting the processor type, the kernel patches out sections of code
 that shouldn't be used by writing nop's over it. Using cpufeatures requires
 just 2 macros (found in arch/powerpc/include/asm/cputable.h), as seen in head.S
-transfer_to_handler:
+transfer_to_handler::
 
 	#ifdef CONFIG_ALTIVEC
 	BEGIN_FTR_SECTION
diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.rst
similarity index 95%
rename from Documentation/powerpc/cxl.txt
rename to Documentation/powerpc/cxl.rst
index c5e8d5098ed3..920546d81326 100644
--- a/Documentation/powerpc/cxl.txt
+++ b/Documentation/powerpc/cxl.rst
@@ -1,3 +1,4 @@
+====================================
 Coherent Accelerator Interface (CXL)
 ====================================
 
@@ -21,6 +22,8 @@ Introduction
 Hardware overview
 =================
 
+    ::
+
          POWER8/9             FPGA
        +----------+        +---------+
        |          |        |         |
@@ -59,14 +62,16 @@ Hardware overview
     the fault. The context to which this fault is serviced is based on
     who owns that acceleration function.
 
-    POWER8 <-----> PSL Version 8 is compliant to the CAIA Version 1.0.
-    POWER9 <-----> PSL Version 9 is compliant to the CAIA Version 2.0.
+    - POWER8 and PSL Version 8 are compliant to the CAIA Version 1.0.
+    - POWER9 and PSL Version 9 are compliant to the CAIA Version 2.0.
+
     This PSL Version 9 provides new features such as:
+
     * Interaction with the nest MMU on the P9 chip.
     * Native DMA support.
     * Supports sending ASB_Notify messages for host thread wakeup.
     * Supports Atomic operations.
-    * ....
+    * etc.
 
     Cards with a PSL9 won't work on a POWER8 system and cards with a
     PSL8 won't work on a POWER9 system.
@@ -147,7 +152,9 @@ User API
     master devices.
 
     A userspace library libcxl is available here:
+
 	https://github.com/ibm-capi/libcxl
+
     This provides a C interface to this kernel API.
 
 open
@@ -165,7 +172,8 @@ open
     When all available contexts are allocated the open call will fail
     and return -ENOSPC.
 
-    Note: IRQs need to be allocated for each context, which may limit
+    Note:
+	  IRQs need to be allocated for each context, which may limit
           the number of contexts that can be created, and therefore
           how many times the device can be opened. The POWER8 CAPP
           supports 2040 IRQs and 3 are used by the kernel, so 2037 are
@@ -186,7 +194,9 @@ ioctl
         updated as userspace allocates and frees memory. This ioctl
         returns once the AFU context is started.
 
-        Takes a pointer to a struct cxl_ioctl_start_work:
+        Takes a pointer to a struct cxl_ioctl_start_work
+
+            ::
 
                 struct cxl_ioctl_start_work {
                         __u64 flags;
@@ -269,7 +279,7 @@ read
     The buffer passed to read() must be at least 4K bytes.
 
     The result of the read will be a buffer of one or more events,
-    each event is of type struct cxl_event, of varying size.
+    each event is of type struct cxl_event, of varying size::
 
             struct cxl_event {
                     struct cxl_event_header header;
@@ -280,7 +290,9 @@ read
                     };
             };
 
-    The struct cxl_event_header is defined as:
+    The struct cxl_event_header is defined as
+
+        ::
 
             struct cxl_event_header {
                     __u16 type;
@@ -307,7 +319,9 @@ read
             For future extensions and padding.
 
     If the event type is CXL_EVENT_AFU_INTERRUPT then the event
-    structure is defined as:
+    structure is defined as
+
+        ::
 
             struct cxl_event_afu_interrupt {
                     __u16 flags;
@@ -326,7 +340,9 @@ read
             For future extensions and padding.
 
     If the event type is CXL_EVENT_DATA_STORAGE then the event
-    structure is defined as:
+    structure is defined as
+
+        ::
 
             struct cxl_event_data_storage {
                     __u16 flags;
@@ -356,7 +372,9 @@ read
             For future extensions
 
     If the event type is CXL_EVENT_AFU_ERROR then the event structure
-    is defined as:
+    is defined as
+
+        ::
 
             struct cxl_event_afu_error {
                     __u16 flags;
@@ -393,15 +411,15 @@ open
 ioctl
 -----
 
-CXL_IOCTL_DOWNLOAD_IMAGE:
-CXL_IOCTL_VALIDATE_IMAGE:
+CXL_IOCTL_DOWNLOAD_IMAGE / CXL_IOCTL_VALIDATE_IMAGE:
     Starts and controls flashing a new FPGA image. Partial
     reconfiguration is not supported (yet), so the image must contain
     a copy of the PSL and AFU(s). Since an image can be quite large,
     the caller may have to iterate, splitting the image in smaller
     chunks.
 
-    Takes a pointer to a struct cxl_adapter_image:
+    Takes a pointer to a struct cxl_adapter_image::
+
         struct cxl_adapter_image {
             __u64 flags;
             __u64 data;
@@ -442,7 +460,7 @@ Udev rules
     The following udev rules could be used to create a symlink to the
     most logical chardev to use in any programming mode (afuX.Yd for
     dedicated, afuX.Ys for afu directed), since the API is virtually
-    identical for each:
+    identical for each::
 
 	SUBSYSTEM=="cxl", ATTRS{mode}=="dedicated_process", SYMLINK="cxl/%b"
 	SUBSYSTEM=="cxl", ATTRS{mode}=="afu_directed", \
diff --git a/Documentation/powerpc/cxlflash.txt b/Documentation/powerpc/cxlflash.rst
similarity index 98%
rename from Documentation/powerpc/cxlflash.txt
rename to Documentation/powerpc/cxlflash.rst
index a64bdaa0a1cf..cea67931b3b9 100644
--- a/Documentation/powerpc/cxlflash.txt
+++ b/Documentation/powerpc/cxlflash.rst
@@ -1,3 +1,7 @@
+================================
+Coherent Accelerator (CXL) Flash
+================================
+
 Introduction
 ============
 
@@ -28,7 +32,7 @@ Introduction
     responsible for the initialization of the adapter, setting up the
     special path for user space access, and performing error recovery. It
     communicates directly the Flash Accelerator Functional Unit (AFU)
-    as described in Documentation/powerpc/cxl.txt.
+    as described in Documentation/powerpc/cxl.rst.
 
     The cxlflash driver supports two, mutually exclusive, modes of
     operation at the device (LUN) level:
@@ -58,7 +62,7 @@ Overview
 
     The CXL Flash Adapter Driver establishes a master context with the
     AFU. It uses memory mapped I/O (MMIO) for this control and setup. The
-    Adapter Problem Space Memory Map looks like this:
+    Adapter Problem Space Memory Map looks like this::
 
                      +-------------------------------+
                      |    512 * 64 KB User MMIO      |
@@ -375,7 +379,7 @@ CXL Flash Driver Host IOCTLs
     Each host adapter instance that is supported by the cxlflash driver
     has a special character device associated with it to enable a set of
     host management function. These character devices are hosted in a
-    class dedicated for cxlflash and can be accessed via /dev/cxlflash/*.
+    class dedicated for cxlflash and can be accessed via `/dev/cxlflash/*`.
 
     Applications can be written to perform various functions using the
     host ioctl APIs below.
diff --git a/Documentation/powerpc/DAWR-POWER9.txt b/Documentation/powerpc/dawr-power9.rst
similarity index 95%
rename from Documentation/powerpc/DAWR-POWER9.txt
rename to Documentation/powerpc/dawr-power9.rst
index ecdbb076438c..c96ab6befd9c 100644
--- a/Documentation/powerpc/DAWR-POWER9.txt
+++ b/Documentation/powerpc/dawr-power9.rst
@@ -1,10 +1,11 @@
+=====================
 DAWR issues on POWER9
-============================
+=====================
 
 On POWER9 the Data Address Watchpoint Register (DAWR) can cause a checkstop
 if it points to cache inhibited (CI) memory. Currently Linux has no way to
 disinguish CI memory when configuring the DAWR, so (for now) the DAWR is
-disabled by this commit:
+disabled by this commit::
 
     commit 9654153158d3e0684a1bdb76dbababdb7111d5a0
     Author: Michael Neuling <mikey@neuling.org>
@@ -12,7 +13,7 @@ disabled by this commit:
     powerpc: Disable DAWR in the base POWER9 CPU features
 
 Technical Details:
-============================
+==================
 
 DAWR has 6 different ways of being set.
 1) ptrace
@@ -37,7 +38,7 @@ DAWR on the migration.
 For xmon, the 'bd' command will return an error on P9.
 
 Consequences for users
-============================
+======================
 
 For GDB watchpoints (ie 'watch' command) on POWER9 bare metal , GDB
 will accept the command. Unfortunately since there is no hardware
@@ -57,8 +58,8 @@ trapped in GDB. The watchpoint is remembered, so if the guest is
 migrated back to the POWER8 host, it will start working again.
 
 Force enabling the DAWR
-=============================
-Kernels (since ~v5.2) have an option to force enable the DAWR via:
+=======================
+Kernels (since ~v5.2) have an option to force enable the DAWR via::
 
   echo Y > /sys/kernel/debug/powerpc/dawr_enable_dangerous
 
@@ -86,5 +87,7 @@ dawr_enable_dangerous file will fail if the hypervisor doesn't support
 writing the DAWR.
 
 To double check the DAWR is working, run this kernel selftest:
+
   tools/testing/selftests/powerpc/ptrace/ptrace-hwbreak.c
+
 Any errors/failures/skips mean something is wrong.
diff --git a/Documentation/powerpc/dscr.txt b/Documentation/powerpc/dscr.rst
similarity index 91%
rename from Documentation/powerpc/dscr.txt
rename to Documentation/powerpc/dscr.rst
index ece300c64f76..2ab99006014c 100644
--- a/Documentation/powerpc/dscr.txt
+++ b/Documentation/powerpc/dscr.rst
@@ -1,5 +1,6 @@
-			DSCR (Data Stream Control Register)
-		================================================
+===================================
+DSCR (Data Stream Control Register)
+===================================
 
 DSCR register in powerpc allows user to have some control of prefetch of data
 stream in the processor. Please refer to the ISA documents or related manual
@@ -10,14 +11,17 @@ user interface.
 
 (A) Data Structures:
 
-	(1) thread_struct:
+	(1) thread_struct::
+
 		dscr		/* Thread DSCR value */
 		dscr_inherit	/* Thread has changed default DSCR */
 
-	(2) PACA:
+	(2) PACA::
+
 		dscr_default	/* per-CPU DSCR default value */
 
-	(3) sysfs.c:
+	(3) sysfs.c::
+
 		dscr_default	/* System DSCR default value */
 
 (B) Scheduler Changes:
@@ -35,8 +39,8 @@ user interface.
 
 (C) SYSFS Interface:
 
-	Global DSCR default:		/sys/devices/system/cpu/dscr_default
-	CPU specific DSCR default:	/sys/devices/system/cpu/cpuN/dscr
+	- Global DSCR default:		/sys/devices/system/cpu/dscr_default
+	- CPU specific DSCR default:	/sys/devices/system/cpu/cpuN/dscr
 
 	Changing the global DSCR default in the sysfs will change all the CPU
 	specific DSCR defaults immediately in their PACA structures. Again if
diff --git a/Documentation/powerpc/eeh-pci-error-recovery.txt b/Documentation/powerpc/eeh-pci-error-recovery.rst
similarity index 82%
rename from Documentation/powerpc/eeh-pci-error-recovery.txt
rename to Documentation/powerpc/eeh-pci-error-recovery.rst
index 678189280bb4..438a87ebc095 100644
--- a/Documentation/powerpc/eeh-pci-error-recovery.txt
+++ b/Documentation/powerpc/eeh-pci-error-recovery.rst
@@ -1,10 +1,10 @@
+==========================
+PCI Bus EEH Error Recovery
+==========================
 
+Linas Vepstas <linas@austin.ibm.com>
 
-                      PCI Bus EEH Error Recovery
-                      --------------------------
-                           Linas Vepstas
-                       <linas@austin.ibm.com>
-                          12 January 2005
+12 January 2005
 
 
 Overview:
@@ -143,17 +143,17 @@ seen in /proc/ppc64/eeh (subject to change).  Normally, almost
 all of these occur during boot, when the PCI bus is scanned, where
 a large number of 0xff reads are part of the bus scan procedure.
 
-If a frozen slot is detected, code in 
-arch/powerpc/platforms/pseries/eeh.c will print a stack trace to 
-syslog (/var/log/messages).  This stack trace has proven to be very 
-useful to device-driver authors for finding out at what point the EEH 
-error was detected, as the error itself usually occurs slightly 
+If a frozen slot is detected, code in
+arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
+syslog (/var/log/messages).  This stack trace has proven to be very
+useful to device-driver authors for finding out at what point the EEH
+error was detected, as the error itself usually occurs slightly
 beforehand.
 
 Next, it uses the Linux kernel notifier chain/work queue mechanism to
 allow any interested parties to find out about the failure.  Device
 drivers, or other parts of the kernel, can use
-eeh_register_notifier(struct notifier_block *) to find out about EEH
+`eeh_register_notifier(struct notifier_block *)` to find out about EEH
 events.  The event will include a pointer to the pci device, the
 device node and some state info.  Receivers of the event can "do as
 they wish"; the default handler will be described further in this
@@ -162,10 +162,13 @@ section.
 To assist in the recovery of the device, eeh.c exports the
 following functions:
 
-rtas_set_slot_reset() -- assert the  PCI #RST line for 1/8th of a second
-rtas_configure_bridge() -- ask firmware to configure any PCI bridges
+rtas_set_slot_reset()
+   assert the  PCI #RST line for 1/8th of a second
+rtas_configure_bridge()
+   ask firmware to configure any PCI bridges
    located topologically under the pci slot.
-eeh_save_bars() and eeh_restore_bars(): save and restore the PCI
+eeh_save_bars() and eeh_restore_bars():
+   save and restore the PCI
    config-space info for a device and any devices under it.
 
 
@@ -191,7 +194,7 @@ events get delivered to user-space scripts.
 
 Following is an example sequence of events that cause a device driver
 close function to be called during the first phase of an EEH reset.
-The following sequence is an example of the pcnet32 device driver.
+The following sequence is an example of the pcnet32 device driver::
 
     rpa_php_unconfig_pci_adapter (struct slot *)  // in rpaphp_pci.c
     {
@@ -241,53 +244,54 @@ The following sequence is an example of the pcnet32 device driver.
      }}}}}}
 
 
-    in drivers/pci/pci_driver.c,
-    struct device_driver->remove() is just pci_device_remove()
-    which calls struct pci_driver->remove() which is pcnet32_remove_one()
-    which calls unregister_netdev()  (in net/core/dev.c)
-    which calls dev_close()  (in net/core/dev.c)
-    which calls dev->stop() which is pcnet32_close()
-    which then does the appropriate shutdown.
+in drivers/pci/pci_driver.c,
+struct device_driver->remove() is just pci_device_remove()
+which calls struct pci_driver->remove() which is pcnet32_remove_one()
+which calls unregister_netdev()  (in net/core/dev.c)
+which calls dev_close()  (in net/core/dev.c)
+which calls dev->stop() which is pcnet32_close()
+which then does the appropriate shutdown.
 
 ---
+
 Following is the analogous stack trace for events sent to user-space
-when the pci device is unconfigured.
+when the pci device is unconfigured::
 
-rpa_php_unconfig_pci_adapter() {             // in rpaphp_pci.c
-  calls
-  pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
+  rpa_php_unconfig_pci_adapter() {             // in rpaphp_pci.c
     calls
-    pci_destroy_dev (struct pci_dev *) {
+    pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
       calls
-      device_unregister (&dev->dev) {        // in /drivers/base/core.c
+      pci_destroy_dev (struct pci_dev *) {
         calls
-        device_del(struct device * dev) {    // in /drivers/base/core.c
+        device_unregister (&dev->dev) {        // in /drivers/base/core.c
           calls
-          kobject_del() {                    //in /libs/kobject.c
+          device_del(struct device * dev) {    // in /drivers/base/core.c
             calls
-            kobject_uevent() {               // in /libs/kobject.c
+            kobject_del() {                    //in /libs/kobject.c
               calls
-              kset_uevent() {                // in /lib/kobject.c
+              kobject_uevent() {               // in /libs/kobject.c
                 calls
-                kset->uevent_ops->uevent()   // which is really just
-                a call to
-                dev_uevent() {               // in /drivers/base/core.c
+                kset_uevent() {                // in /lib/kobject.c
                   calls
-                  dev->bus->uevent() which is really just a call to
-                  pci_uevent () {            // in drivers/pci/hotplug.c
-                    which prints device name, etc....
+                  kset->uevent_ops->uevent()   // which is really just
+                  a call to
+                  dev_uevent() {               // in /drivers/base/core.c
+                    calls
+                    dev->bus->uevent() which is really just a call to
+                    pci_uevent () {            // in drivers/pci/hotplug.c
+                      which prints device name, etc....
+                   }
                  }
-               }
-               then kobject_uevent() sends a netlink uevent to userspace
-               --> userspace uevent
-               (during early boot, nobody listens to netlink events and
-               kobject_uevent() executes uevent_helper[], which runs the
-               event process /sbin/hotplug)
+                 then kobject_uevent() sends a netlink uevent to userspace
+                 --> userspace uevent
+                 (during early boot, nobody listens to netlink events and
+                 kobject_uevent() executes uevent_helper[], which runs the
+                 event process /sbin/hotplug)
+             }
            }
-         }
-         kobject_del() then calls sysfs_remove_dir(), which would
-         trigger any user-space daemon that was watching /sysfs,
-         and notice the delete event.
+           kobject_del() then calls sysfs_remove_dir(), which would
+           trigger any user-space daemon that was watching /sysfs,
+           and notice the delete event.
 
 
 Pro's and Con's of the Current Design
@@ -299,12 +303,12 @@ individual device drivers, so that the current design throws a wide net.
 The biggest negative of the design is that it potentially disturbs
 network daemons and file systems that didn't need to be disturbed.
 
--- A minor complaint is that resetting the network card causes
+-  A minor complaint is that resetting the network card causes
    user-space back-to-back ifdown/ifup burps that potentially disturb
    network daemons, that didn't need to even know that the pci
    card was being rebooted.
 
--- A more serious concern is that the same reset, for SCSI devices,
+-  A more serious concern is that the same reset, for SCSI devices,
    causes havoc to mounted file systems.  Scripts cannot post-facto
    unmount a file system without flushing pending buffers, but this
    is impossible, because I/O has already been stopped.  Thus,
@@ -322,7 +326,7 @@ network daemons and file systems that didn't need to be disturbed.
    from the block layer.  It would be very natural to add an EEH
    reset into this chain of events.
 
--- If a SCSI error occurs for the root device, all is lost unless
+-  If a SCSI error occurs for the root device, all is lost unless
    the sysadmin had the foresight to run /bin, /sbin, /etc, /var
    and so on, out of ramdisk/tmpfs.
 
@@ -330,5 +334,3 @@ network daemons and file systems that didn't need to be disturbed.
 Conclusions
 -----------
 There's forward progress ...
-
-
diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.rst
similarity index 80%
rename from Documentation/powerpc/firmware-assisted-dump.txt
rename to Documentation/powerpc/firmware-assisted-dump.rst
index 10e7f4d16c14..9ca12830a48e 100644
--- a/Documentation/powerpc/firmware-assisted-dump.txt
+++ b/Documentation/powerpc/firmware-assisted-dump.rst
@@ -1,7 +1,8 @@
+======================
+Firmware-Assisted Dump
+======================
 
-                   Firmware-Assisted Dump
-                   ------------------------
-                       July 2011
+July 2011
 
 The goal of firmware-assisted dump is to enable the dump of
 a crashed system, and to do so from a fully-reset system, and
@@ -27,11 +28,11 @@ in production use.
 Comparing with kdump or other strategies, firmware-assisted
 dump offers several strong, practical advantages:
 
--- Unlike kdump, the system has been reset, and loaded
+-  Unlike kdump, the system has been reset, and loaded
    with a fresh copy of the kernel.  In particular,
    PCI and I/O devices have been reinitialized and are
    in a clean, consistent state.
--- Once the dump is copied out, the memory that held the dump
+-  Once the dump is copied out, the memory that held the dump
    is immediately available to the running kernel. And therefore,
    unlike kdump, fadump doesn't need a 2nd reboot to get back
    the system to the production configuration.
@@ -40,17 +41,18 @@ The above can only be accomplished by coordination with,
 and assistance from the Power firmware. The procedure is
 as follows:
 
--- The first kernel registers the sections of memory with the
+-  The first kernel registers the sections of memory with the
    Power firmware for dump preservation during OS initialization.
    These registered sections of memory are reserved by the first
    kernel during early boot.
 
--- When a system crashes, the Power firmware will save
+-  When a system crashes, the Power firmware will save
    the low memory (boot memory of size larger of 5% of system RAM
    or 256MB) of RAM to the previous registered region. It will
    also save system registers, and hardware PTE's.
 
-   NOTE: The term 'boot memory' means size of the low memory chunk
+   NOTE:
+         The term 'boot memory' means size of the low memory chunk
          that is required for a kernel to boot successfully when
          booted with restricted memory. By default, the boot memory
          size will be the larger of 5% of system RAM or 256MB.
@@ -64,12 +66,12 @@ as follows:
          as fadump uses a predefined offset to reserve memory
          for boot memory dump preservation in case of a crash.
 
--- After the low memory (boot memory) area has been saved, the
+-  After the low memory (boot memory) area has been saved, the
    firmware will reset PCI and other hardware state.  It will
    *not* clear the RAM. It will then launch the bootloader, as
    normal.
 
--- The freshly booted kernel will notice that there is a new
+-  The freshly booted kernel will notice that there is a new
    node (ibm,dump-kernel) in the device tree, indicating that
    there is crash data available from a previous boot. During
    the early boot OS will reserve rest of the memory above
@@ -77,17 +79,18 @@ as follows:
    size. This will make sure that the second kernel will not
    touch any of the dump memory area.
 
--- User-space tools will read /proc/vmcore to obtain the contents
+-  User-space tools will read /proc/vmcore to obtain the contents
    of memory, which holds the previous crashed kernel dump in ELF
    format. The userspace tools may copy this info to disk, or
    network, nas, san, iscsi, etc. as desired.
 
--- Once the userspace tool is done saving dump, it will echo
+-  Once the userspace tool is done saving dump, it will echo
    '1' to /sys/kernel/fadump_release_mem to release the reserved
    memory back to general use, except the memory required for
    next firmware-assisted dump registration.
 
-   e.g.
+   e.g.::
+
      # echo 1 > /sys/kernel/fadump_release_mem
 
 Please note that the firmware-assisted dump feature
@@ -95,7 +98,7 @@ is only available on Power6 and above systems with recent
 firmware versions.
 
 Implementation details:
-----------------------
+-----------------------
 
 During boot, a check is made to see if firmware supports
 this feature on that particular machine. If it does, then
@@ -121,7 +124,7 @@ Allocator (CMA) for memory reservation if CMA is configured for kernel.
 With CMA reservation this memory will be available for applications to
 use it, while kernel is prevented from using it. With this fadump will
 still be able to capture all of the kernel memory and most of the user
-space memory except the user pages that were present in CMA region.
+space memory except the user pages that were present in CMA region::
 
   o Memory Reservation during first kernel
 
@@ -166,7 +169,7 @@ The tools to examine the dump will be same as the ones
 used for kdump.
 
 How to enable firmware-assisted dump (fadump):
--------------------------------------
+----------------------------------------------
 
 1. Set config option CONFIG_FA_DUMP=y and build kernel.
 2. Boot into linux kernel with 'fadump=on' kernel cmdline option.
@@ -177,19 +180,20 @@ How to enable firmware-assisted dump (fadump):
    to specify size of the memory to reserve for boot memory dump
    preservation.
 
-NOTE: 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
-         use 'crashkernel=' to specify size of the memory to reserve
-         for boot memory dump preservation.
-      2. If firmware-assisted dump fails to reserve memory then it
-         will fallback to existing kdump mechanism if 'crashkernel='
-         option is set at kernel cmdline.
-      3. if user wants to capture all of user space memory and ok with
-         reserved memory not available to production system, then
-         'fadump=nocma' kernel parameter can be used to fallback to
-         old behaviour.
+NOTE:
+     1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
+        use 'crashkernel=' to specify size of the memory to reserve
+        for boot memory dump preservation.
+     2. If firmware-assisted dump fails to reserve memory then it
+        will fallback to existing kdump mechanism if 'crashkernel='
+        option is set at kernel cmdline.
+     3. if user wants to capture all of user space memory and ok with
+        reserved memory not available to production system, then
+        'fadump=nocma' kernel parameter can be used to fallback to
+        old behaviour.
 
 Sysfs/debugfs files:
-------------
+--------------------
 
 Firmware-assisted dump feature uses sysfs file system to hold
 the control files and debugfs file to display memory reserved region.
@@ -197,20 +201,20 @@ the control files and debugfs file to display memory reserved region.
 Here is the list of files under kernel sysfs:
 
  /sys/kernel/fadump_enabled
-
     This is used to display the fadump status.
-    0 = fadump is disabled
-    1 = fadump is enabled
+
+    - 0 = fadump is disabled
+    - 1 = fadump is enabled
 
     This interface can be used by kdump init scripts to identify if
     fadump is enabled in the kernel and act accordingly.
 
  /sys/kernel/fadump_registered
-
     This is used to display the fadump registration status as well
     as to control (start/stop) the fadump registration.
-    0 = fadump is not registered.
-    1 = fadump is registered and ready to handle system crash.
+
+    - 0 = fadump is not registered.
+    - 1 = fadump is registered and ready to handle system crash.
 
     To register fadump echo 1 > /sys/kernel/fadump_registered and
     echo 0 > /sys/kernel/fadump_registered for un-register and stop the
@@ -219,13 +223,12 @@ Here is the list of files under kernel sysfs:
     easily integrated with kdump service start/stop.
 
  /sys/kernel/fadump_release_mem
-
     This file is available only when fadump is active during
     second kernel. This is used to release the reserved memory
     region that are held for saving crash dump. To release the
-    reserved memory echo 1 to it:
+    reserved memory echo 1 to it::
 
-    echo 1  > /sys/kernel/fadump_release_mem
+	echo 1  > /sys/kernel/fadump_release_mem
 
     After echo 1, the content of the /sys/kernel/debug/powerpc/fadump_region
     file will change to reflect the new memory reservations.
@@ -238,38 +241,39 @@ Here is the list of files under powerpc debugfs:
 (Assuming debugfs is mounted on /sys/kernel/debug directory.)
 
  /sys/kernel/debug/powerpc/fadump_region
-
     This file shows the reserved memory regions if fadump is
     enabled otherwise this file is empty. The output format
-    is:
-    <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
+    is::
+
+      <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
 
     e.g.
-    Contents when fadump is registered during first kernel
+    Contents when fadump is registered during first kernel::
 
-    # cat /sys/kernel/debug/powerpc/fadump_region
-    CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
-    HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
-    DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
+      # cat /sys/kernel/debug/powerpc/fadump_region
+      CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
+      HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
+      DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
 
-    Contents when fadump is active during second kernel
+    Contents when fadump is active during second kernel::
 
-    # cat /sys/kernel/debug/powerpc/fadump_region
-    CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
-    HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
-    DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
-        : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
+      # cat /sys/kernel/debug/powerpc/fadump_region
+      CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
+      HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
+      DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
+          : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
 
-NOTE: Please refer to Documentation/filesystems/debugfs.txt on
+NOTE:
+      Please refer to Documentation/filesystems/debugfs.txt on
       how to mount the debugfs filesystem.
 
 
 TODO:
 -----
- o Need to come up with the better approach to find out more
+ - Need to come up with the better approach to find out more
    accurate boot memory size that is required for a kernel to
    boot successfully when booted with restricted memory.
- o The fadump implementation introduces a fadump crash info structure
+ - The fadump implementation introduces a fadump crash info structure
    in the scratch area before the ELF core header. The idea of introducing
    this structure is to pass some important crash info data to the second
    kernel which will help second kernel to populate ELF core header with
@@ -277,7 +281,9 @@ TODO:
    design implementation does not address a possibility of introducing
    additional fields (in future) to this structure without affecting
    compatibility. Need to come up with the better approach to address this.
+
    The possible approaches are:
+
 	1. Introduce version field for version tracking, bump up the version
 	whenever a new field is added to the structure in future. The version
 	field can be used to find out what fields are valid for the current
@@ -285,8 +291,11 @@ TODO:
 	2. Reserve the area of predefined size (say PAGE_SIZE) for this
 	structure and have unused area as reserved (initialized to zero)
 	for future field additions.
+
    The advantage of approach 1 over 2 is we don't need to reserve extra space.
----
+
 Author: Mahesh Salgaonkar <mahesh@linux.vnet.ibm.com>
+
 This document is based on the original documentation written for phyp
+
 assisted dump by Linas Vepstas and Manish Ahuja.
diff --git a/Documentation/powerpc/hvcs.txt b/Documentation/powerpc/hvcs.rst
similarity index 91%
rename from Documentation/powerpc/hvcs.txt
rename to Documentation/powerpc/hvcs.rst
index a730ca5a07f8..6808acde672f 100644
--- a/Documentation/powerpc/hvcs.txt
+++ b/Documentation/powerpc/hvcs.rst
@@ -1,19 +1,22 @@
-===========================================================================
-				   HVCS
-	IBM "Hypervisor Virtual Console Server" Installation Guide
-			  for Linux Kernel 2.6.4+
-		    Copyright (C) 2004 IBM Corporation
+===============================================================
+HVCS IBM "Hypervisor Virtual Console Server" Installation Guide
+===============================================================
 
-===========================================================================
-NOTE:Eight space tabs are the optimum editor setting for reading this file.
-===========================================================================
+for Linux Kernel 2.6.4+
 
-	       Author(s) :  Ryan S. Arnold <rsa@us.ibm.com>
-		       Date Created: March, 02, 2004
-		       Last Changed: August, 24, 2004
+Copyright (C) 2004 IBM Corporation
 
----------------------------------------------------------------------------
-Table of contents:
+.. ===========================================================================
+.. NOTE:Eight space tabs are the optimum editor setting for reading this file.
+.. ===========================================================================
+
+
+Author(s): Ryan S. Arnold <rsa@us.ibm.com>
+
+Date Created: March, 02, 2004
+Last Changed: August, 24, 2004
+
+.. Table of contents:
 
 	1.  Driver Introduction:
 	2.  System Requirements
@@ -27,8 +30,8 @@ Table of contents:
 	8.  Questions & Answers:
 	9.  Reporting Bugs:
 
----------------------------------------------------------------------------
 1. Driver Introduction:
+=======================
 
 This is the device driver for the IBM Hypervisor Virtual Console Server,
 "hvcs".  The IBM hvcs provides a tty driver interface to allow Linux user
@@ -38,8 +41,8 @@ ppc64 system.  Physical hardware consoles per partition are not practical
 on this hardware so system consoles are accessed by this driver using
 firmware interfaces to virtual terminal devices.
 
----------------------------------------------------------------------------
 2. System Requirements:
+=======================
 
 This device driver was written using 2.6.4 Linux kernel APIs and will only
 build and run on kernels of this version or later.
@@ -52,8 +55,8 @@ Sysfs must be mounted on the system so that the user can determine which
 major and minor numbers are associated with each vty-server.  Directions
 for sysfs mounting are outside the scope of this document.
 
----------------------------------------------------------------------------
 3. Build Options:
+=================
 
 The hvcs driver registers itself as a tty driver.  The tty layer
 dynamically allocates a block of major and minor numbers in a quantity
@@ -65,11 +68,11 @@ If the default number of device entries is adequate then this driver can be
 built into the kernel.  If not, the default can be over-ridden by inserting
 the driver as a module with insmod parameters.
 
----------------------------------------------------------------------------
 3.1 Built-in:
+-------------
 
 The following menuconfig example demonstrates selecting to build this
-driver into the kernel.
+driver into the kernel::
 
 	Device Drivers  --->
 		Character devices  --->
@@ -77,11 +80,11 @@ driver into the kernel.
 
 Begin the kernel make process.
 
----------------------------------------------------------------------------
 3.2 Module:
+-----------
 
 The following menuconfig example demonstrates selecting to build this
-driver as a kernel module.
+driver as a kernel module::
 
 	Device Drivers  --->
 		Character devices  --->
@@ -89,11 +92,11 @@ driver as a kernel module.
 
 The make process will build the following kernel modules:
 
-	hvcs.ko
-	hvcserver.ko
+	- hvcs.ko
+	- hvcserver.ko
 
 To insert the module with the default allocation execute the following
-commands in the order they appear:
+commands in the order they appear::
 
 	insmod hvcserver.ko
 	insmod hvcs.ko
@@ -103,7 +106,7 @@ be inserted first, otherwise the hvcs module will not find some of the
 symbols it expects.
 
 To override the default use an insmod parameter as follows (requesting 4
-tty devices as an example):
+tty devices as an example)::
 
 	insmod hvcs.ko hvcs_parm_num_devs=4
 
@@ -115,31 +118,31 @@ source file before building.
 NOTE: The length of time it takes to insmod the driver seems to be related
 to the number of tty interfaces the registering driver requests.
 
-In order to remove the driver module execute the following command:
+In order to remove the driver module execute the following command::
 
 	rmmod hvcs.ko
 
 The recommended method for installing hvcs as a module is to use depmod to
 build a current modules.dep file in /lib/modules/`uname -r` and then
-execute:
+execute::
 
-modprobe hvcs hvcs_parm_num_devs=4
+	modprobe hvcs hvcs_parm_num_devs=4
 
 The modules.dep file indicates that hvcserver.ko needs to be inserted
 before hvcs.ko and modprobe uses this file to smartly insert the modules in
 the proper order.
 
 The following modprobe command is used to remove hvcs and hvcserver in the
-proper order:
+proper order::
 
-modprobe -r hvcs
+	modprobe -r hvcs
 
----------------------------------------------------------------------------
 4. Installation:
+================
 
 The tty layer creates sysfs entries which contain the major and minor
 numbers allocated for the hvcs driver.  The following snippet of "tree"
-output of the sysfs directory shows where these numbers are presented:
+output of the sysfs directory shows where these numbers are presented::
 
 	sys/
 	|-- *other sysfs base dirs*
@@ -164,7 +167,7 @@ output of the sysfs directory shows where these numbers are presented:
 	|-- *other sysfs base dirs*
 
 For the above examples the following output is a result of cat'ing the
-"dev" entry in the hvcs directory:
+"dev" entry in the hvcs directory::
 
 	Pow5:/sys/class/tty/hvcs0/ # cat dev
 	254:0
@@ -184,7 +187,7 @@ systems running hvcs will already have the device entries created or udev
 will do it automatically.
 
 Given the example output above, to manually create a /dev/hvcs* node entry
-mknod can be used as follows:
+mknod can be used as follows::
 
 	mknod /dev/hvcs0 c 254 0
 	mknod /dev/hvcs1 c 254 1
@@ -195,15 +198,15 @@ Using mknod to manually create the device entries makes these device nodes
 persistent.  Once created they will exist prior to the driver insmod.
 
 Attempting to connect an application to /dev/hvcs* prior to insertion of
-the hvcs module will result in an error message similar to the following:
+the hvcs module will result in an error message similar to the following::
 
 	"/dev/hvcs*: No such device".
 
 NOTE: Just because there is a device node present doesn't mean that there
 is a vty-server device configured for that node.
 
----------------------------------------------------------------------------
 5. Connection
+=============
 
 Since this driver controls devices that provide a tty interface a user can
 interact with the device node entries using any standard tty-interactive
@@ -249,7 +252,7 @@ vty-server adapter is associated with which /dev/hvcs* node a special sysfs
 attribute has been added to each vty-server sysfs entry.  This entry is
 called "index" and showing it reveals an integer that refers to the
 /dev/hvcs* entry to use to connect to that device.  For instance cating the
-index attribute of vty-server adapter 30000004 shows the following.
+index attribute of vty-server adapter 30000004 shows the following::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
 	2
@@ -262,8 +265,8 @@ system the /dev/hvcs* entry that interacts with a particular vty-server
 adapter is not guaranteed to remain the same across system reboots.  Look
 in the Q & A section for more on this issue.
 
----------------------------------------------------------------------------
 6. Disconnection
+================
 
 As a security feature to prevent the delivery of stale data to an
 unintended target the Power5 system firmware disables the fetching of data
@@ -305,7 +308,7 @@ connection between the vty-server and target vty ONLY if the vterm_state
 previously read '1'.  The write directive is ignored if the vterm_state
 read '0' or if any value other than '0' was written to the vterm_state
 attribute.  The following example will show the method used for verifying
-the vty-server connection status and disconnecting a vty-server connection.
+the vty-server connection status and disconnecting a vty-server connection::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
 	1
@@ -318,12 +321,12 @@ the vty-server connection status and disconnecting a vty-server connection.
 All vty-server connections are automatically terminated when the device is
 hotplug removed and when the module is removed.
 
----------------------------------------------------------------------------
 7. Configuration
+================
 
 Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
 is symlinked in several other sysfs tree directories, notably under the
-hvcs driver entry, which looks like the following example:
+hvcs driver entry, which looks like the following example::
 
 	Pow5:/sys/bus/vio/drivers/hvcs # ls
 	.  ..  30000003  30000004  rescan
@@ -344,7 +347,7 @@ completed or was never executed.
 
 Vty-server entries in this directory are a 32 bit partition unique unit
 address that is created by firmware.  An example vty-server sysfs entry
-looks like the following:
+looks like the following::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
 	.   current_vty   devspec       name          partner_vtys
@@ -352,21 +355,21 @@ looks like the following:
 
 Each entry is provided, by default with a "name" attribute.  Reading the
 "name" attribute will reveal the device type as shown in the following
-example:
+example::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
 	vty-server
 
 Each entry is also provided, by default, with a "devspec" attribute which
 reveals the full device specification when read, as shown in the following
-example:
+example::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
 	/vdevice/vty-server@30000004
 
 Each vty-server sysfs dir is provided with two read-only attributes that
 provide lists of easily parsed partner vty data: "partner_vtys" and
-"partner_clcs".
+"partner_clcs"::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
 	30000000
@@ -396,7 +399,7 @@ A vty-server can only be connected to a single vty at a time.  The entry,
 read.
 
 The current_vty can be changed by writing a valid partner clc to the entry
-as in the following example:
+as in the following example::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
 	8A-V4-C0 > current_vty
@@ -408,9 +411,9 @@ currently open connection is freed.
 Information on the "vterm_state" attribute was covered earlier on the
 chapter entitled "disconnection".
 
----------------------------------------------------------------------------
 8. Questions & Answers:
-===========================================================================
+=======================
+
 Q: What are the security concerns involving hvcs?
 
 A: There are three main security concerns:
@@ -429,6 +432,7 @@ A: There are three main security concerns:
 	partition) will experience the previously logged in session.
 
 ---------------------------------------------------------------------------
+
 Q: How do I multiplex a console that I grab through hvcs so that other
 people can see it:
 
@@ -440,6 +444,7 @@ term type "screen" to others.  This means that curses based programs may
 not display properly in screen sessions.
 
 ---------------------------------------------------------------------------
+
 Q: Why are the colors all messed up?
 Q: Why are the control characters acting strange or not working?
 Q: Why is the console output all strange and unintelligible?
@@ -455,6 +460,7 @@ disconnect from the console.  This will ensure that the next user gets
 their own TERM type set when they login.
 
 ---------------------------------------------------------------------------
+
 Q: When I try to CONNECT kermit to an hvcs device I get:
 "Sorry, can't open connection: /dev/hvcs*"What is happening?
 
@@ -490,6 +496,7 @@ A: There is not a corresponding vty-server device that maps to an existing
 /dev/hvcs* entry.
 
 ---------------------------------------------------------------------------
+
 Q: When I try to CONNECT kermit to an hvcs device I get:
 "Sorry, write access to UUCP lockfile directory denied."
 
@@ -497,6 +504,7 @@ A: The /dev/hvcs* entry you have specified doesn't exist where you said it
 does?  Maybe you haven't inserted the module (on systems with udev).
 
 ---------------------------------------------------------------------------
+
 Q: If I already have one Linux partition installed can I use hvcs on said
 partition to provide the console for the install of a second Linux
 partition?
@@ -505,6 +513,7 @@ A: Yes granted that your are connected to the /dev/hvcs* device using
 kermit or cu or some other program that doesn't provide terminal emulation.
 
 ---------------------------------------------------------------------------
+
 Q: Can I connect to more than one partition's console at a time using this
 driver?
 
@@ -512,6 +521,7 @@ A: Yes.  Of course this means that there must be more than one vty-server
 configured for this partition and each must point to a disconnected vty.
 
 ---------------------------------------------------------------------------
+
 Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
 
 A: Yes, if you have dlpar and hotplug enabled for your system and it has
@@ -519,6 +529,7 @@ been built into the kernel the hvcs drivers is configured to dynamically
 handle additions of new devices and removals of unused devices.
 
 ---------------------------------------------------------------------------
+
 Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
 after a reboot.  What happened?
 
@@ -533,6 +544,7 @@ on how to determine which vty-server goes with which /dev/hvcs* node.
 Hint; look at the sysfs "index" attribute for the vty-server.
 
 ---------------------------------------------------------------------------
+
 Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
 device on that partition as the other end of the pipe?
 
@@ -554,7 +566,9 @@ read or write to /dev/hvcs*.  Now you have a tty conduit between two
 partitions.
 
 ---------------------------------------------------------------------------
+
 9. Reporting Bugs:
+==================
 
 The proper channel for reporting bugs is either through the Linux OS
 distribution company that provided your OS or by posting issues to the
diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst
new file mode 100644
index 000000000000..549b1cdd77ae
--- /dev/null
+++ b/Documentation/powerpc/index.rst
@@ -0,0 +1,34 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======
+powerpc
+=======
+
+.. toctree::
+    :maxdepth: 1
+
+    bootwrapper
+    cpu_families
+    cpu_features
+    cxl
+    cxlflash
+    dawr-power9
+    dscr
+    eeh-pci-error-recovery
+    firmware-assisted-dump
+    hvcs
+    isa-versions
+    mpc52xx
+    pci_iov_resource_on_powernv
+    pmu-ebb
+    ptrace
+    qe_firmware
+    syscall64-abi
+    transactional_memory
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/powerpc/isa-versions.rst
index 66c24140ebf1..a363d8c1603c 100644
--- a/Documentation/powerpc/isa-versions.rst
+++ b/Documentation/powerpc/isa-versions.rst
@@ -1,13 +1,12 @@
-:orphan:
-
+==========================
 CPU to ISA Version Mapping
 ==========================
 
 Mapping of some CPU versions to relevant ISA versions.
 
-========= ====================
+========= ====================================================================
 CPU       Architecture version
-========= ====================
+========= ====================================================================
 Power9    Power ISA v3.0B
 Power8    Power ISA v2.07
 Power7    Power ISA v2.06
@@ -24,7 +23,7 @@ PPC970    - PowerPC User Instruction Set Architecture Book I v2.01
           - PowerPC Virtual Environment Architecture Book II v2.01
           - PowerPC Operating Environment Architecture Book III v2.01
           - Plus Altivec/VMX ~= 2.03
-========= ====================
+========= ====================================================================
 
 
 Key Features
@@ -60,9 +59,9 @@ Power5     No
 PPC970     No
 ========== ====
 
-========== ====================
+========== ====================================
 CPU        Transactional Memory
-========== ====================
+========== ====================================
 Power9     Yes (* see transactional_memory.txt)
 Power8     Yes
 Power7     No
@@ -73,4 +72,4 @@ Power5++   No
 Power5+    No
 Power5     No
 PPC970     No
-========== ====================
+========== ====================================
diff --git a/Documentation/powerpc/mpc52xx.txt b/Documentation/powerpc/mpc52xx.rst
similarity index 91%
rename from Documentation/powerpc/mpc52xx.txt
rename to Documentation/powerpc/mpc52xx.rst
index 0d540a31ea1a..8676ac63e077 100644
--- a/Documentation/powerpc/mpc52xx.txt
+++ b/Documentation/powerpc/mpc52xx.rst
@@ -1,11 +1,13 @@
+=============================
 Linux 2.6.x on MPC52xx family
------------------------------
+=============================
 
 For the latest info, go to http://www.246tNt.com/mpc52xx/
 
 To compile/use :
 
-  - U-Boot:
+  - U-Boot::
+
      # <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
         if you wish to ).
      # make lite5200_defconfig
@@ -16,7 +18,8 @@ To compile/use :
      => tftpboot 400000 pRamdisk
      => bootm 200000 400000
 
-  - DBug:
+  - DBug::
+
      # <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
         if you wish to ).
      # make lite5200_defconfig
@@ -28,7 +31,8 @@ To compile/use :
      DBug> dn -i zImage.initrd.lite5200
 
 
-Some remarks :
+Some remarks:
+
  - The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100
    is not supported, and I'm not sure anyone is interesting in working on it
    so. I didn't took 5xxx because there's apparently a lot of 5xxx that have
diff --git a/Documentation/powerpc/pci_iov_resource_on_powernv.txt b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
similarity index 97%
rename from Documentation/powerpc/pci_iov_resource_on_powernv.txt
rename to Documentation/powerpc/pci_iov_resource_on_powernv.rst
index b55c5cd83f8d..f5a5793e1613 100644
--- a/Documentation/powerpc/pci_iov_resource_on_powernv.txt
+++ b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
@@ -1,6 +1,13 @@
+===================================================
+PCI Express I/O Virtualization Resource on Powerenv
+===================================================
+
 Wei Yang <weiyang@linux.vnet.ibm.com>
+
 Benjamin Herrenschmidt <benh@au1.ibm.com>
+
 Bjorn Helgaas <bhelgaas@google.com>
+
 26 Aug 2014
 
 This document describes the requirement from hardware for PCI MMIO resource
@@ -10,6 +17,7 @@ Endpoints and the implementation on P8 (IODA2). The next two sections talks
 about considerations on enabling SRIOV on IODA2.
 
 1. Introduction to Partitionable Endpoints
+==========================================
 
 A Partitionable Endpoint (PE) is a way to group the various resources
 associated with a device or a set of devices to provide isolation between
@@ -35,6 +43,7 @@ is a completely separate HW entity that replicates the entire logic, so has
 its own set of PEs, etc.
 
 2. Implementation of Partitionable Endpoints on P8 (IODA2)
+==========================================================
 
 P8 supports up to 256 Partitionable Endpoints per PHB.
 
@@ -149,6 +158,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
     sense, but we haven't done it yet.
 
 3. Considerations for SR-IOV on PowerKVM
+========================================
 
   * SR-IOV Background
 
@@ -224,7 +234,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
   IODA supports 256 PEs, so segmented windows contain 256 segments, so if
   total_VFs is less than 256, we have the situation in Figure 1.0, where
   segments [total_VFs, 255] of the M64 window may map to some MMIO range on
-  other devices:
+  other devices::
 
      0      1                     total_VFs - 1
      +------+------+-     -+------+------+
@@ -243,7 +253,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
 		Figure 1.0 Direct map VF(n) BAR space
 
   Our current solution is to allocate 256 segments even if the VF(n) BAR
-  space doesn't need that much, as shown in Figure 1.1:
+  space doesn't need that much, as shown in Figure 1.1::
 
      0      1                     total_VFs - 1                255
      +------+------+-     -+------+------+-      -+------+------+
@@ -269,6 +279,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
   responds to segments [total_VFs, 255].
 
 4. Implications for the Generic PCI Code
+========================================
 
 The PCIe SR-IOV spec requires that the base of the VF(n) BAR space be
 aligned to the size of an individual VF BAR.
diff --git a/Documentation/powerpc/pmu-ebb.txt b/Documentation/powerpc/pmu-ebb.rst
similarity index 99%
rename from Documentation/powerpc/pmu-ebb.txt
rename to Documentation/powerpc/pmu-ebb.rst
index 73cd163dbfb8..4f474758eb55 100644
--- a/Documentation/powerpc/pmu-ebb.txt
+++ b/Documentation/powerpc/pmu-ebb.rst
@@ -1,3 +1,4 @@
+========================
 PMU Event Based Branches
 ========================
 
diff --git a/Documentation/powerpc/ptrace.txt b/Documentation/powerpc/ptrace.rst
similarity index 48%
rename from Documentation/powerpc/ptrace.txt
rename to Documentation/powerpc/ptrace.rst
index 99c5ce88d0fe..864d4b6dddd1 100644
--- a/Documentation/powerpc/ptrace.txt
+++ b/Documentation/powerpc/ptrace.rst
@@ -1,3 +1,7 @@
+======
+Ptrace
+======
+
 GDB intends to support the following hardware debug features of BookE
 processors:
 
@@ -12,6 +16,7 @@ that GDB doesn't need to special-case each of them. We added the
 following 3 new ptrace requests.
 
 1. PTRACE_PPC_GETHWDEBUGINFO
+============================
 
 Query for GDB to discover the hardware debug features. The main info to
 be returned here is the minimum alignment for the hardware watchpoints.
@@ -22,9 +27,9 @@ adding special cases to GDB based on what it sees in AUXV.
 Since we're at it, we added other useful info that the kernel can return to
 GDB: this query will return the number of hardware breakpoints, hardware
 watchpoints and whether it supports a range of addresses and a condition.
-The query will fill the following structure provided by the requesting process:
+The query will fill the following structure provided by the requesting process::
 
-struct ppc_debug_info {
+  struct ppc_debug_info {
        unit32_t version;
        unit32_t num_instruction_bps;
        unit32_t num_data_bps;
@@ -32,46 +37,46 @@ struct ppc_debug_info {
        unit32_t data_bp_alignment;
        unit32_t sizeof_condition; /* size of the DVC register */
        uint64_t features; /* bitmask of the individual flags */
-};
+  };
 
-features will have bits indicating whether there is support for:
+features will have bits indicating whether there is support for::
 
-#define PPC_DEBUG_FEATURE_INSN_BP_RANGE		0x1
-#define PPC_DEBUG_FEATURE_INSN_BP_MASK		0x2
-#define PPC_DEBUG_FEATURE_DATA_BP_RANGE		0x4
-#define PPC_DEBUG_FEATURE_DATA_BP_MASK		0x8
-#define PPC_DEBUG_FEATURE_DATA_BP_DAWR		0x10
+  #define PPC_DEBUG_FEATURE_INSN_BP_RANGE		0x1
+  #define PPC_DEBUG_FEATURE_INSN_BP_MASK		0x2
+  #define PPC_DEBUG_FEATURE_DATA_BP_RANGE		0x4
+  #define PPC_DEBUG_FEATURE_DATA_BP_MASK		0x8
+  #define PPC_DEBUG_FEATURE_DATA_BP_DAWR		0x10
 
 2. PTRACE_SETHWDEBUG
 
-Sets a hardware breakpoint or watchpoint, according to the provided structure:
+Sets a hardware breakpoint or watchpoint, according to the provided structure::
 
-struct ppc_hw_breakpoint {
+  struct ppc_hw_breakpoint {
         uint32_t version;
-#define PPC_BREAKPOINT_TRIGGER_EXECUTE  0x1
-#define PPC_BREAKPOINT_TRIGGER_READ     0x2
-#define PPC_BREAKPOINT_TRIGGER_WRITE    0x4
+  #define PPC_BREAKPOINT_TRIGGER_EXECUTE  0x1
+  #define PPC_BREAKPOINT_TRIGGER_READ     0x2
+ #define PPC_BREAKPOINT_TRIGGER_WRITE    0x4
         uint32_t trigger_type;       /* only some combinations allowed */
-#define PPC_BREAKPOINT_MODE_EXACT               0x0
-#define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE     0x1
-#define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE     0x2
-#define PPC_BREAKPOINT_MODE_MASK                0x3
+  #define PPC_BREAKPOINT_MODE_EXACT               0x0
+  #define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE     0x1
+  #define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE     0x2
+  #define PPC_BREAKPOINT_MODE_MASK                0x3
         uint32_t addr_mode;          /* address match mode */
 
-#define PPC_BREAKPOINT_CONDITION_MODE   0x3
-#define PPC_BREAKPOINT_CONDITION_NONE   0x0
-#define PPC_BREAKPOINT_CONDITION_AND    0x1
-#define PPC_BREAKPOINT_CONDITION_EXACT  0x1	/* different name for the same thing as above */
-#define PPC_BREAKPOINT_CONDITION_OR     0x2
-#define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
-#define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000	/* byte enable bits */
-#define PPC_BREAKPOINT_CONDITION_BE(n)  (1<<((n)+16))
+  #define PPC_BREAKPOINT_CONDITION_MODE   0x3
+  #define PPC_BREAKPOINT_CONDITION_NONE   0x0
+  #define PPC_BREAKPOINT_CONDITION_AND    0x1
+  #define PPC_BREAKPOINT_CONDITION_EXACT  0x1	/* different name for the same thing as above */
+  #define PPC_BREAKPOINT_CONDITION_OR     0x2
+  #define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
+  #define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000	/* byte enable bits */
+  #define PPC_BREAKPOINT_CONDITION_BE(n)  (1<<((n)+16))
         uint32_t condition_mode;     /* break/watchpoint condition flags */
 
         uint64_t addr;
         uint64_t addr2;
         uint64_t condition_value;
-};
+  };
 
 A request specifies one event, not necessarily just one register to be set.
 For instance, if the request is for a watchpoint with a condition, both the
@@ -88,61 +93,61 @@ can't be allocated on the registers.
 
 Some examples of using the structure to:
 
-- set a breakpoint in the first breakpoint register
-
-  p.version         = PPC_DEBUG_CURRENT_VERSION;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_EXECUTE;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
-  p.addr            = (uint64_t) address;
-  p.addr2           = 0;
-  p.condition_value = 0;
-
-- set a watchpoint which triggers on reads in the second watchpoint register
-
-  p.version         = PPC_DEBUG_CURRENT_VERSION;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_READ;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
-  p.addr            = (uint64_t) address;
-  p.addr2           = 0;
-  p.condition_value = 0;
-
-- set a watchpoint which triggers only with a specific value
-
-  p.version         = PPC_DEBUG_CURRENT_VERSION;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_READ;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
-  p.addr            = (uint64_t) address;
-  p.addr2           = 0;
-  p.condition_value = (uint64_t) condition;
-
-- set a ranged hardware breakpoint
-
-  p.version         = PPC_DEBUG_CURRENT_VERSION;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_EXECUTE;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
-  p.addr            = (uint64_t) begin_range;
-  p.addr2           = (uint64_t) end_range;
-  p.condition_value = 0;
-
-- set a watchpoint in server processors (BookS)
-
-  p.version         = 1;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_RW;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
-  or
-  p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
-
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
-  p.addr            = (uint64_t) begin_range;
-  /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
-   * addr2 - addr <= 8 Bytes.
-   */
-  p.addr2           = (uint64_t) end_range;
-  p.condition_value = 0;
+- set a breakpoint in the first breakpoint register::
+
+    p.version         = PPC_DEBUG_CURRENT_VERSION;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
+    p.addr            = (uint64_t) address;
+    p.addr2           = 0;
+    p.condition_value = 0;
+
+- set a watchpoint which triggers on reads in the second watchpoint register::
+
+    p.version         = PPC_DEBUG_CURRENT_VERSION;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_READ;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
+    p.addr            = (uint64_t) address;
+    p.addr2           = 0;
+    p.condition_value = 0;
+
+- set a watchpoint which triggers only with a specific value::
+
+    p.version         = PPC_DEBUG_CURRENT_VERSION;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_READ;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
+    p.addr            = (uint64_t) address;
+    p.addr2           = 0;
+    p.condition_value = (uint64_t) condition;
+
+- set a ranged hardware breakpoint::
+
+    p.version         = PPC_DEBUG_CURRENT_VERSION;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
+    p.addr            = (uint64_t) begin_range;
+    p.addr2           = (uint64_t) end_range;
+    p.condition_value = 0;
+
+- set a watchpoint in server processors (BookS)::
+
+    p.version         = 1;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_RW;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+    or
+    p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
+
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
+    p.addr            = (uint64_t) begin_range;
+    /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
+     * addr2 - addr <= 8 Bytes.
+     */
+    p.addr2           = (uint64_t) end_range;
+    p.condition_value = 0;
 
 3. PTRACE_DELHWDEBUG
 
diff --git a/Documentation/powerpc/qe_firmware.txt b/Documentation/powerpc/qe_firmware.rst
similarity index 95%
rename from Documentation/powerpc/qe_firmware.txt
rename to Documentation/powerpc/qe_firmware.rst
index e7ac24aec4ff..42f5103140c9 100644
--- a/Documentation/powerpc/qe_firmware.txt
+++ b/Documentation/powerpc/qe_firmware.rst
@@ -1,23 +1,23 @@
-	   Freescale QUICC Engine Firmware Uploading
-	   -----------------------------------------
+=========================================
+Freescale QUICC Engine Firmware Uploading
+=========================================
 
 (c) 2007 Timur Tabi <timur at freescale.com>,
     Freescale Semiconductor
 
-Table of Contents
-=================
+.. Table of Contents
 
-  I - Software License for Firmware
+   I - Software License for Firmware
 
-  II - Microcode Availability
+   II - Microcode Availability
 
-  III - Description and Terminology
+   III - Description and Terminology
 
-  IV - Microcode Programming Details
+   IV - Microcode Programming Details
 
-  V - Firmware Structure Layout
+   V - Firmware Structure Layout
 
-  VI - Sample Code for Creating Firmware Files
+   VI - Sample Code for Creating Firmware Files
 
 Revision Information
 ====================
@@ -39,7 +39,7 @@ http://opensource.freescale.com.  For other firmware files, please contact
 your Freescale representative or your operating system vendor.
 
 III - Description and Terminology
-================================
+=================================
 
 In this document, the term 'microcode' refers to the sequence of 32-bit
 integers that compose the actual QE microcode.
@@ -89,7 +89,7 @@ being fixed in the RAM package utilizing they should be activated.  This data
 structure signals the microcode which of these virtual traps is active.
 
 This structure contains 6 words that the application should copy to some
-specific been defined.  This table describes the structure.
+specific been defined.  This table describes the structure::
 
 	---------------------------------------------------------------
 	| Offset in |                  | Destination Offset | Size of |
@@ -119,7 +119,7 @@ Extended Modes
 This is a double word bit array (64 bits) that defines special functionality
 which has an impact on the software drivers.  Each bit has its own impact
 and has special instructions for the s/w associated with it.  This structure is
-described in this table:
+described in this table::
 
 	-----------------------------------------------------------------------
 	| Bit #  |     Name     |   Description                               |
@@ -220,7 +220,8 @@ The 'model' field is a 16-bit number that matches the actual SOC. The
 'major' and 'minor' fields are the major and minor revision numbers,
 respectively, of the SOC.
 
-For example, to match the 8323, revision 1.0:
+For example, to match the 8323, revision 1.0::
+
      soc.model = 8323
      soc.major = 1
      soc.minor = 0
@@ -273,10 +274,10 @@ library and available to any driver that calles qe_get_firmware_info().
 	'reserved'.
 
 After the last microcode is a 32-bit CRC.  It can be calculated using
-this algorithm:
+this algorithm::
 
-u32 crc32(const u8 *p, unsigned int len)
-{
+  u32 crc32(const u8 *p, unsigned int len)
+  {
 	unsigned int i;
 	u32 crc = 0;
 
@@ -286,7 +287,7 @@ u32 crc32(const u8 *p, unsigned int len)
 		   crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
 	}
 	return crc;
-}
+  }
 
 VI - Sample Code for Creating Firmware Files
 ============================================
diff --git a/Documentation/powerpc/syscall64-abi.txt b/Documentation/powerpc/syscall64-abi.rst
similarity index 82%
rename from Documentation/powerpc/syscall64-abi.txt
rename to Documentation/powerpc/syscall64-abi.rst
index fa716a0d88bd..e49f69f941b9 100644
--- a/Documentation/powerpc/syscall64-abi.txt
+++ b/Documentation/powerpc/syscall64-abi.rst
@@ -5,12 +5,12 @@ Power Architecture 64-bit Linux system call ABI
 syscall
 =======
 
-syscall calling sequence[*] matches the Power Architecture 64-bit ELF ABI
+syscall calling sequence\ [1]_ matches the Power Architecture 64-bit ELF ABI
 specification C function calling sequence, including register preservation
 rules, with the following differences.
 
-[*] Some syscalls (typically low-level management functions) may have
-    different calling sequences (e.g., rt_sigreturn).
+.. [1] Some syscalls (typically low-level management functions) may have
+       different calling sequences (e.g., rt_sigreturn).
 
 Parameters and return value
 ---------------------------
@@ -33,12 +33,14 @@ Register preservation rules
 Register preservation rules match the ELF ABI calling sequence with the
 following differences:
 
-r0:         Volatile.   (System call number.)
-r3:         Volatile.   (Parameter 1, and return value.)
-r4-r8:      Volatile.   (Parameters 2-6.)
-cr0:        Volatile    (cr0.SO is the return error condition)
-cr1, cr5-7: Nonvolatile.
-lr:         Nonvolatile.
+=========== ============= ========================================
+r0          Volatile      (System call number.)
+r3          Volatile      (Parameter 1, and return value.)
+r4-r8       Volatile      (Parameters 2-6.)
+cr0         Volatile      (cr0.SO is the return error condition)
+cr1, cr5-7  Nonvolatile
+lr          Nonvolatile
+=========== ============= ========================================
 
 All floating point and vector data registers as well as control and status
 registers are nonvolatile.
@@ -90,9 +92,12 @@ The vsyscall may or may not use the caller's stack frame save areas.
 
 Register preservation rules
 ---------------------------
-r0: Volatile.
-cr1, cr5-7: Volatile.
-lr: Volatile.
+
+=========== ========
+r0          Volatile
+cr1, cr5-7  Volatile
+lr          Volatile
+=========== ========
 
 Invocation
 ----------
diff --git a/Documentation/powerpc/transactional_memory.txt b/Documentation/powerpc/transactional_memory.rst
similarity index 93%
rename from Documentation/powerpc/transactional_memory.txt
rename to Documentation/powerpc/transactional_memory.rst
index 52c023e14f26..09955103acb4 100644
--- a/Documentation/powerpc/transactional_memory.txt
+++ b/Documentation/powerpc/transactional_memory.rst
@@ -1,3 +1,4 @@
+============================
 Transactional Memory support
 ============================
 
@@ -17,29 +18,29 @@ instructions are presented to delimit transactions; transactions are
 guaranteed to either complete atomically or roll back and undo any partial
 changes.
 
-A simple transaction looks like this:
+A simple transaction looks like this::
 
-begin_move_money:
-  tbegin
-  beq   abort_handler
+  begin_move_money:
+    tbegin
+    beq   abort_handler
 
-  ld    r4, SAVINGS_ACCT(r3)
-  ld    r5, CURRENT_ACCT(r3)
-  subi  r5, r5, 1
-  addi  r4, r4, 1
-  std   r4, SAVINGS_ACCT(r3)
-  std   r5, CURRENT_ACCT(r3)
+    ld    r4, SAVINGS_ACCT(r3)
+    ld    r5, CURRENT_ACCT(r3)
+    subi  r5, r5, 1
+    addi  r4, r4, 1
+    std   r4, SAVINGS_ACCT(r3)
+    std   r5, CURRENT_ACCT(r3)
 
-  tend
+    tend
 
-  b     continue
+    b     continue
 
-abort_handler:
-  ... test for odd failures ...
+  abort_handler:
+    ... test for odd failures ...
 
-  /* Retry the transaction if it failed because it conflicted with
-   * someone else: */
-  b     begin_move_money
+    /* Retry the transaction if it failed because it conflicted with
+     * someone else: */
+    b     begin_move_money
 
 
 The 'tbegin' instruction denotes the start point, and 'tend' the end point.
@@ -123,7 +124,7 @@ Transaction-aware signal handlers can read the transactional register state
 from the second ucontext.  This will be necessary for crash handlers to
 determine, for example, the address of the instruction causing the SIGSEGV.
 
-Example signal handler:
+Example signal handler::
 
     void crash_handler(int sig, siginfo_t *si, void *uc)
     {
@@ -133,9 +134,9 @@ Example signal handler:
       if (ucp_link) {
         u64 msr = ucp->uc_mcontext.regs->msr;
         /* May have transactional ucontext! */
-#ifndef __powerpc64__
+  #ifndef __powerpc64__
         msr |= ((u64)transactional_ucp->uc_mcontext.regs->msr) << 32;
-#endif
+  #endif
         if (MSR_TM_ACTIVE(msr)) {
            /* Yes, we crashed during a transaction.  Oops. */
    fprintf(stderr, "Transaction to be restarted at 0x%llx, but "
@@ -176,6 +177,7 @@ Failure cause codes used by kernel
 These are defined in <asm/reg.h>, and distinguish different reasons why the
 kernel aborted a transaction:
 
+ ====================== ================================
  TM_CAUSE_RESCHED       Thread was rescheduled.
  TM_CAUSE_TLBI          Software TLB invalid.
  TM_CAUSE_FAC_UNAV      FP/VEC/VSX unavailable trap.
@@ -184,6 +186,7 @@ kernel aborted a transaction:
  TM_CAUSE_MISC          Currently unused.
  TM_CAUSE_ALIGNMENT     Alignment fault.
  TM_CAUSE_EMULATE       Emulation that touched memory.
+ ====================== ================================
 
 These can be checked by the user program's abort handler as TEXASR[0:7].  If
 bit 7 is set, it indicates that the error is consider persistent.  For example
@@ -203,7 +206,7 @@ POWER9
 ======
 
 TM on POWER9 has issues with storing the complete register state. This
-is described in this commit:
+is described in this commit::
 
     commit 4bb3c7a0208fc13ca70598efd109901a7cd45ae7
     Author: Paul Mackerras <paulus@ozlabs.org>
diff --git a/MAINTAINERS b/MAINTAINERS
index 3d6cd6efb264..15b58d5947a3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4469,7 +4469,7 @@ F:	arch/powerpc/platforms/powernv/pci-cxl.c
 F:	drivers/misc/cxl/
 F:	include/misc/cxl*
 F:	include/uapi/misc/cxl.h
-F:	Documentation/powerpc/cxl.txt
+F:	Documentation/powerpc/cxl.rst
 F:	Documentation/ABI/testing/sysfs-class-cxl
 
 CXLFLASH (IBM Coherent Accelerator Processor Interface CAPI Flash) SCSI DRIVER
@@ -4480,7 +4480,7 @@ L:	linux-scsi@vger.kernel.org
 S:	Supported
 F:	drivers/scsi/cxlflash/
 F:	include/uapi/scsi/cxlflash_ioctl.h
-F:	Documentation/powerpc/cxlflash.txt
+F:	Documentation/powerpc/cxlflash.rst
 
 CYBERPRO FB DRIVER
 M:	Russell King <linux@armlinux.org.uk>
@@ -12394,7 +12394,7 @@ F:	Documentation/PCI/pci-error-recovery.rst
 F:	drivers/pci/pcie/aer.c
 F:	drivers/pci/pcie/dpc.c
 F:	drivers/pci/pcie/err.c
-F:	Documentation/powerpc/eeh-pci-error-recovery.txt
+F:	Documentation/powerpc/eeh-pci-error-recovery.rst
 F:	arch/powerpc/kernel/eeh*.c
 F:	arch/powerpc/platforms/*/eeh*.c
 F:	arch/powerpc/include/*/eeh*.h
diff --git a/arch/powerpc/kernel/exceptions-64s.S b/arch/powerpc/kernel/exceptions-64s.S
index eee5bef736c8..6ba3cc2ef8ab 100644
--- a/arch/powerpc/kernel/exceptions-64s.S
+++ b/arch/powerpc/kernel/exceptions-64s.S
@@ -1531,7 +1531,7 @@ EXC_COMMON(trap_0b_common, 0xb00, unknown_exception)
  *
  * Call convention:
  *
- * syscall register convention is in Documentation/powerpc/syscall64-abi.txt
+ * syscall register convention is in Documentation/powerpc/syscall64-abi.rst
  *
  * For hypercalls, the register convention is as follows:
  * r0 volatile
diff --git a/drivers/soc/fsl/qe/qe.c b/drivers/soc/fsl/qe/qe.c
index 62c6ba17991a..c9519e62308c 100644
--- a/drivers/soc/fsl/qe/qe.c
+++ b/drivers/soc/fsl/qe/qe.c
@@ -419,7 +419,7 @@ static void qe_upload_microcode(const void *base,
 /*
  * Upload a microcode to the I-RAM at a specific address.
  *
- * See Documentation/powerpc/qe_firmware.txt for information on QE microcode
+ * See Documentation/powerpc/qe_firmware.rst for information on QE microcode
  * uploading.
  *
  * Currently, only version 1 is supported, so the 'version' field must be
diff --git a/drivers/tty/hvc/hvcs.c b/drivers/tty/hvc/hvcs.c
index cb4db1b3ca3c..5fb214e67d73 100644
--- a/drivers/tty/hvc/hvcs.c
+++ b/drivers/tty/hvc/hvcs.c
@@ -47,7 +47,7 @@
  * using the 2.6 Linux kernel kref construct.
  *
  * For direction on installation and usage of this driver please reference
- * Documentation/powerpc/hvcs.txt.
+ * Documentation/powerpc/hvcs.rst.
  */
 
 #include <linux/device.h>
diff --git a/include/soc/fsl/qe/qe.h b/include/soc/fsl/qe/qe.h
index 3f9d6b6a5691..c1036d16ed03 100644
--- a/include/soc/fsl/qe/qe.h
+++ b/include/soc/fsl/qe/qe.h
@@ -259,7 +259,7 @@ static inline int qe_alive_during_sleep(void)
 
 /* Structure that defines QE firmware binary files.
  *
- * See Documentation/powerpc/qe_firmware.txt for a description of these
+ * See Documentation/powerpc/qe_firmware.rst for a description of these
  * fields.
  */
 struct qe_firmware {
-- 
2.21.0


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

* [PATCH v2 03/26] docs: powerpc: convert docs to ReST and rename to *.rst
@ 2019-07-26 12:51   ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: linux-doc, Benjamin Herrenschmidt, linux-pci,
	Oliver O'Halloran, Russell Currey, Mauro Carvalho Chehab,
	Qiang Zhao, linux-scsi, Jonathan Corbet, Michael Ellerman,
	Jiri Slaby, Linas Vepstas, Andrew Donnellan, Manoj N. Kumar,
	Bjorn Helgaas, linux-arm-kernel, Matthew R. Ochs, Uma Krishnan,
	Sam Bobroff, Greg Kroah-Hartman, Li Yang, Andrew Donnellan,
	Frederic Barrat, Paul Mackerras, linuxppc-dev

Convert docs to ReST and add them to the arch-specific
book.

The conversion here was trivial, as almost every file there
was already using an elegant format close to ReST standard.

The changes were mostly to mark literal blocks and add a few
missing section title identifiers.

One note with regards to "--": on Sphinx, this can't be used
to identify a list, as it will format it badly. This can be
used, however, to identify a long hyphen - and "---" is an
even longer one.

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: Andrew Donnellan <andrew.donnellan@au1.ibm.com> # cxl
---
 Documentation/PCI/pci-error-recovery.rst      |   2 +-
 Documentation/index.rst                       |   1 +
 .../{bootwrapper.txt => bootwrapper.rst}      |  28 ++-
 .../{cpu_families.txt => cpu_families.rst}    |  23 +--
 .../{cpu_features.txt => cpu_features.rst}    |   6 +-
 Documentation/powerpc/{cxl.txt => cxl.rst}    |  46 +++--
 .../powerpc/{cxlflash.txt => cxlflash.rst}    |  10 +-
 .../{DAWR-POWER9.txt => dawr-power9.rst}      |  15 +-
 Documentation/powerpc/{dscr.txt => dscr.rst}  |  18 +-
 ...ecovery.txt => eeh-pci-error-recovery.rst} | 108 +++++------
 ...ed-dump.txt => firmware-assisted-dump.rst} | 117 ++++++------
 Documentation/powerpc/{hvcs.txt => hvcs.rst}  | 108 ++++++-----
 Documentation/powerpc/index.rst               |  34 ++++
 Documentation/powerpc/isa-versions.rst        |  15 +-
 .../powerpc/{mpc52xx.txt => mpc52xx.rst}      |  12 +-
 ...nv.txt => pci_iov_resource_on_powernv.rst} |  15 +-
 .../powerpc/{pmu-ebb.txt => pmu-ebb.rst}      |   1 +
 .../powerpc/{ptrace.txt => ptrace.rst}        | 169 +++++++++---------
 .../{qe_firmware.txt => qe_firmware.rst}      |  37 ++--
 .../{syscall64-abi.txt => syscall64-abi.rst}  |  29 +--
 ...al_memory.txt => transactional_memory.rst} |  45 ++---
 MAINTAINERS                                   |   6 +-
 arch/powerpc/kernel/exceptions-64s.S          |   2 +-
 drivers/soc/fsl/qe/qe.c                       |   2 +-
 drivers/tty/hvc/hvcs.c                        |   2 +-
 include/soc/fsl/qe/qe.h                       |   2 +-
 26 files changed, 495 insertions(+), 358 deletions(-)
 rename Documentation/powerpc/{bootwrapper.txt => bootwrapper.rst} (93%)
 rename Documentation/powerpc/{cpu_families.txt => cpu_families.rst} (95%)
 rename Documentation/powerpc/{cpu_features.txt => cpu_features.rst} (97%)
 rename Documentation/powerpc/{cxl.txt => cxl.rst} (95%)
 rename Documentation/powerpc/{cxlflash.txt => cxlflash.rst} (98%)
 rename Documentation/powerpc/{DAWR-POWER9.txt => dawr-power9.rst} (95%)
 rename Documentation/powerpc/{dscr.txt => dscr.rst} (91%)
 rename Documentation/powerpc/{eeh-pci-error-recovery.txt => eeh-pci-error-recovery.rst} (82%)
 rename Documentation/powerpc/{firmware-assisted-dump.txt => firmware-assisted-dump.rst} (80%)
 rename Documentation/powerpc/{hvcs.txt => hvcs.rst} (91%)
 create mode 100644 Documentation/powerpc/index.rst
 rename Documentation/powerpc/{mpc52xx.txt => mpc52xx.rst} (91%)
 rename Documentation/powerpc/{pci_iov_resource_on_powernv.txt => pci_iov_resource_on_powernv.rst} (97%)
 rename Documentation/powerpc/{pmu-ebb.txt => pmu-ebb.rst} (99%)
 rename Documentation/powerpc/{ptrace.txt => ptrace.rst} (48%)
 rename Documentation/powerpc/{qe_firmware.txt => qe_firmware.rst} (95%)
 rename Documentation/powerpc/{syscall64-abi.txt => syscall64-abi.rst} (82%)
 rename Documentation/powerpc/{transactional_memory.txt => transactional_memory.rst} (93%)

diff --git a/Documentation/PCI/pci-error-recovery.rst b/Documentation/PCI/pci-error-recovery.rst
index 83db42092935..69800a9d1b0d 100644
--- a/Documentation/PCI/pci-error-recovery.rst
+++ b/Documentation/PCI/pci-error-recovery.rst
@@ -403,7 +403,7 @@ That is, the recovery API only requires that:
 .. note::
 
    Implementation details for the powerpc platform are discussed in
-   the file Documentation/powerpc/eeh-pci-error-recovery.txt
+   the file Documentation/powerpc/eeh-pci-error-recovery.rst
 
    As of this writing, there is a growing list of device drivers with
    patches implementing error recovery. Not all of these patches are in
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 230e550e9741..68ae2a4d689d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -144,6 +144,7 @@ implementation.
    arm64/index
    ia64/index
    m68k/index
+   powerpc/index
    riscv/index
    s390/index
    sh/index
diff --git a/Documentation/powerpc/bootwrapper.txt b/Documentation/powerpc/bootwrapper.rst
similarity index 93%
rename from Documentation/powerpc/bootwrapper.txt
rename to Documentation/powerpc/bootwrapper.rst
index d60fced5e1cc..a6292afba573 100644
--- a/Documentation/powerpc/bootwrapper.txt
+++ b/Documentation/powerpc/bootwrapper.rst
@@ -1,5 +1,7 @@
+========================
 The PowerPC boot wrapper
-------------------------
+========================
+
 Copyright (C) Secret Lab Technologies Ltd.
 
 PowerPC image targets compresses and wraps the kernel image (vmlinux) with
@@ -21,6 +23,7 @@ it uses the wrapper script (arch/powerpc/boot/wrapper) to generate target
 image.  The details of the build system is discussed in the next section.
 Currently, the following image format targets exist:
 
+   ==================== ========================================================
    cuImage.%:		Backwards compatible uImage for older version of
 			U-Boot (for versions that don't understand the device
 			tree).  This image embeds a device tree blob inside
@@ -29,31 +32,36 @@ Currently, the following image format targets exist:
 			with boot wrapper code that extracts data from the old
 			bd_info structure and loads the data into the device
 			tree before jumping into the kernel.
-			  Because of the series of #ifdefs found in the
+
+			Because of the series of #ifdefs found in the
 			bd_info structure used in the old U-Boot interfaces,
 			cuImages are platform specific.  Each specific
 			U-Boot platform has a different platform init file
 			which populates the embedded device tree with data
 			from the platform specific bd_info file.  The platform
 			specific cuImage platform init code can be found in
-			arch/powerpc/boot/cuboot.*.c.  Selection of the correct
+			`arch/powerpc/boot/cuboot.*.c`. Selection of the correct
 			cuImage init code for a specific board can be found in
 			the wrapper structure.
+
    dtbImage.%:		Similar to zImage, except device tree blob is embedded
 			inside the image instead of provided by firmware.  The
 			output image file can be either an elf file or a flat
 			binary depending on the platform.
-			  dtbImages are used on systems which do not have an
+
+			dtbImages are used on systems which do not have an
 			interface for passing a device tree directly.
 			dtbImages are similar to simpleImages except that
 			dtbImages have platform specific code for extracting
 			data from the board firmware, but simpleImages do not
 			talk to the firmware at all.
-			  PlayStation 3 support uses dtbImage.  So do Embedded
+
+			PlayStation 3 support uses dtbImage.  So do Embedded
 			Planet boards using the PlanetCore firmware.  Board
 			specific initialization code is typically found in a
 			file named arch/powerpc/boot/<platform>.c; but this
 			can be overridden by the wrapper script.
+
    simpleImage.%:	Firmware independent compressed image that does not
 			depend on any particular firmware interface and embeds
 			a device tree blob.  This image is a flat binary that
@@ -61,14 +69,16 @@ Currently, the following image format targets exist:
 			Firmware cannot pass any configuration data to the
 			kernel with this image type and it depends entirely on
 			the embedded device tree for all information.
-			  The simpleImage is useful for booting systems with
+
+			The simpleImage is useful for booting systems with
 			an unknown firmware interface or for booting from
 			a debugger when no firmware is present (such as on
 			the Xilinx Virtex platform).  The only assumption that
 			simpleImage makes is that RAM is correctly initialized
 			and that the MMU is either off or has RAM mapped to
 			base address 0.
-			  simpleImage also supports inserting special platform
+
+			simpleImage also supports inserting special platform
 			specific initialization code to the start of the bootup
 			sequence.  The virtex405 platform uses this feature to
 			ensure that the cache is invalidated before caching
@@ -81,9 +91,11 @@ Currently, the following image format targets exist:
 			named (virtex405-<board>.dts).  Search the wrapper
 			script for 'virtex405' and see the file
 			arch/powerpc/boot/virtex405-head.S for details.
+
    treeImage.%;		Image format for used with OpenBIOS firmware found
 			on some ppc4xx hardware.  This image embeds a device
 			tree blob inside the image.
+
    uImage:		Native image format used by U-Boot.  The uImage target
 			does not add any boot code.  It just wraps a compressed
 			vmlinux in the uImage data structure.  This image
@@ -91,12 +103,14 @@ Currently, the following image format targets exist:
 			a device tree to the kernel at boot.  If using an older
 			version of U-Boot, then you need to use a cuImage
 			instead.
+
    zImage.%:		Image format which does not embed a device tree.
 			Used by OpenFirmware and other firmware interfaces
 			which are able to supply a device tree.  This image
 			expects firmware to provide the device tree at boot.
 			Typically, if you have general purpose PowerPC
 			hardware then you want this image format.
+   ==================== ========================================================
 
 Image types which embed a device tree blob (simpleImage, dtbImage, treeImage,
 and cuImage) all generate the device tree blob from a file in the
diff --git a/Documentation/powerpc/cpu_families.txt b/Documentation/powerpc/cpu_families.rst
similarity index 95%
rename from Documentation/powerpc/cpu_families.txt
rename to Documentation/powerpc/cpu_families.rst
index fc08e22feb1a..1e063c5440c3 100644
--- a/Documentation/powerpc/cpu_families.txt
+++ b/Documentation/powerpc/cpu_families.rst
@@ -1,3 +1,4 @@
+============
 CPU Families
 ============
 
@@ -8,8 +9,8 @@ and are supported by arch/powerpc.
 Book3S (aka sPAPR)
 ------------------
 
- - Hash MMU
- - Mix of 32 & 64 bit
+- Hash MMU
+- Mix of 32 & 64 bit::
 
    +--------------+                 +----------------+
    |  Old POWER   | --------------> | RS64 (threads) |
@@ -108,8 +109,8 @@ Book3S (aka sPAPR)
 IBM BookE
 ---------
 
- - Software loaded TLB.
- - All 32 bit
+- Software loaded TLB.
+- All 32 bit::
 
    +--------------+
    |     401      |
@@ -155,8 +156,8 @@ IBM BookE
 Motorola/Freescale 8xx
 ----------------------
 
- - Software loaded with hardware assist.
- - All 32 bit
+- Software loaded with hardware assist.
+- All 32 bit::
 
    +-------------+
    | MPC8xx Core |
@@ -166,9 +167,9 @@ Motorola/Freescale 8xx
 Freescale BookE
 ---------------
 
- - Software loaded TLB.
- - e6500 adds HW loaded indirect TLB entries.
- - Mix of 32 & 64 bit
+- Software loaded TLB.
+- e6500 adds HW loaded indirect TLB entries.
+- Mix of 32 & 64 bit::
 
    +--------------+
    |     e200     |
@@ -207,8 +208,8 @@ Freescale BookE
 IBM A2 core
 -----------
 
- - Book3E, software loaded TLB + HW loaded indirect TLB entries.
- - 64 bit
+- Book3E, software loaded TLB + HW loaded indirect TLB entries.
+- 64 bit::
 
    +--------------+     +----------------+
    |   A2 core    | --> |      WSP       |
diff --git a/Documentation/powerpc/cpu_features.txt b/Documentation/powerpc/cpu_features.rst
similarity index 97%
rename from Documentation/powerpc/cpu_features.txt
rename to Documentation/powerpc/cpu_features.rst
index ae09df8722c8..b7bcdd2f41bb 100644
--- a/Documentation/powerpc/cpu_features.txt
+++ b/Documentation/powerpc/cpu_features.rst
@@ -1,3 +1,7 @@
+============
+CPU Features
+============
+
 Hollis Blanchard <hollis@austin.ibm.com>
 5 Jun 2002
 
@@ -32,7 +36,7 @@ anyways).
 After detecting the processor type, the kernel patches out sections of code
 that shouldn't be used by writing nop's over it. Using cpufeatures requires
 just 2 macros (found in arch/powerpc/include/asm/cputable.h), as seen in head.S
-transfer_to_handler:
+transfer_to_handler::
 
 	#ifdef CONFIG_ALTIVEC
 	BEGIN_FTR_SECTION
diff --git a/Documentation/powerpc/cxl.txt b/Documentation/powerpc/cxl.rst
similarity index 95%
rename from Documentation/powerpc/cxl.txt
rename to Documentation/powerpc/cxl.rst
index c5e8d5098ed3..920546d81326 100644
--- a/Documentation/powerpc/cxl.txt
+++ b/Documentation/powerpc/cxl.rst
@@ -1,3 +1,4 @@
+====================================
 Coherent Accelerator Interface (CXL)
 ====================================
 
@@ -21,6 +22,8 @@ Introduction
 Hardware overview
 =================
 
+    ::
+
          POWER8/9             FPGA
        +----------+        +---------+
        |          |        |         |
@@ -59,14 +62,16 @@ Hardware overview
     the fault. The context to which this fault is serviced is based on
     who owns that acceleration function.
 
-    POWER8 <-----> PSL Version 8 is compliant to the CAIA Version 1.0.
-    POWER9 <-----> PSL Version 9 is compliant to the CAIA Version 2.0.
+    - POWER8 and PSL Version 8 are compliant to the CAIA Version 1.0.
+    - POWER9 and PSL Version 9 are compliant to the CAIA Version 2.0.
+
     This PSL Version 9 provides new features such as:
+
     * Interaction with the nest MMU on the P9 chip.
     * Native DMA support.
     * Supports sending ASB_Notify messages for host thread wakeup.
     * Supports Atomic operations.
-    * ....
+    * etc.
 
     Cards with a PSL9 won't work on a POWER8 system and cards with a
     PSL8 won't work on a POWER9 system.
@@ -147,7 +152,9 @@ User API
     master devices.
 
     A userspace library libcxl is available here:
+
 	https://github.com/ibm-capi/libcxl
+
     This provides a C interface to this kernel API.
 
 open
@@ -165,7 +172,8 @@ open
     When all available contexts are allocated the open call will fail
     and return -ENOSPC.
 
-    Note: IRQs need to be allocated for each context, which may limit
+    Note:
+	  IRQs need to be allocated for each context, which may limit
           the number of contexts that can be created, and therefore
           how many times the device can be opened. The POWER8 CAPP
           supports 2040 IRQs and 3 are used by the kernel, so 2037 are
@@ -186,7 +194,9 @@ ioctl
         updated as userspace allocates and frees memory. This ioctl
         returns once the AFU context is started.
 
-        Takes a pointer to a struct cxl_ioctl_start_work:
+        Takes a pointer to a struct cxl_ioctl_start_work
+
+            ::
 
                 struct cxl_ioctl_start_work {
                         __u64 flags;
@@ -269,7 +279,7 @@ read
     The buffer passed to read() must be at least 4K bytes.
 
     The result of the read will be a buffer of one or more events,
-    each event is of type struct cxl_event, of varying size.
+    each event is of type struct cxl_event, of varying size::
 
             struct cxl_event {
                     struct cxl_event_header header;
@@ -280,7 +290,9 @@ read
                     };
             };
 
-    The struct cxl_event_header is defined as:
+    The struct cxl_event_header is defined as
+
+        ::
 
             struct cxl_event_header {
                     __u16 type;
@@ -307,7 +319,9 @@ read
             For future extensions and padding.
 
     If the event type is CXL_EVENT_AFU_INTERRUPT then the event
-    structure is defined as:
+    structure is defined as
+
+        ::
 
             struct cxl_event_afu_interrupt {
                     __u16 flags;
@@ -326,7 +340,9 @@ read
             For future extensions and padding.
 
     If the event type is CXL_EVENT_DATA_STORAGE then the event
-    structure is defined as:
+    structure is defined as
+
+        ::
 
             struct cxl_event_data_storage {
                     __u16 flags;
@@ -356,7 +372,9 @@ read
             For future extensions
 
     If the event type is CXL_EVENT_AFU_ERROR then the event structure
-    is defined as:
+    is defined as
+
+        ::
 
             struct cxl_event_afu_error {
                     __u16 flags;
@@ -393,15 +411,15 @@ open
 ioctl
 -----
 
-CXL_IOCTL_DOWNLOAD_IMAGE:
-CXL_IOCTL_VALIDATE_IMAGE:
+CXL_IOCTL_DOWNLOAD_IMAGE / CXL_IOCTL_VALIDATE_IMAGE:
     Starts and controls flashing a new FPGA image. Partial
     reconfiguration is not supported (yet), so the image must contain
     a copy of the PSL and AFU(s). Since an image can be quite large,
     the caller may have to iterate, splitting the image in smaller
     chunks.
 
-    Takes a pointer to a struct cxl_adapter_image:
+    Takes a pointer to a struct cxl_adapter_image::
+
         struct cxl_adapter_image {
             __u64 flags;
             __u64 data;
@@ -442,7 +460,7 @@ Udev rules
     The following udev rules could be used to create a symlink to the
     most logical chardev to use in any programming mode (afuX.Yd for
     dedicated, afuX.Ys for afu directed), since the API is virtually
-    identical for each:
+    identical for each::
 
 	SUBSYSTEM=="cxl", ATTRS{mode}=="dedicated_process", SYMLINK="cxl/%b"
 	SUBSYSTEM=="cxl", ATTRS{mode}=="afu_directed", \
diff --git a/Documentation/powerpc/cxlflash.txt b/Documentation/powerpc/cxlflash.rst
similarity index 98%
rename from Documentation/powerpc/cxlflash.txt
rename to Documentation/powerpc/cxlflash.rst
index a64bdaa0a1cf..cea67931b3b9 100644
--- a/Documentation/powerpc/cxlflash.txt
+++ b/Documentation/powerpc/cxlflash.rst
@@ -1,3 +1,7 @@
+================================
+Coherent Accelerator (CXL) Flash
+================================
+
 Introduction
 ============
 
@@ -28,7 +32,7 @@ Introduction
     responsible for the initialization of the adapter, setting up the
     special path for user space access, and performing error recovery. It
     communicates directly the Flash Accelerator Functional Unit (AFU)
-    as described in Documentation/powerpc/cxl.txt.
+    as described in Documentation/powerpc/cxl.rst.
 
     The cxlflash driver supports two, mutually exclusive, modes of
     operation at the device (LUN) level:
@@ -58,7 +62,7 @@ Overview
 
     The CXL Flash Adapter Driver establishes a master context with the
     AFU. It uses memory mapped I/O (MMIO) for this control and setup. The
-    Adapter Problem Space Memory Map looks like this:
+    Adapter Problem Space Memory Map looks like this::
 
                      +-------------------------------+
                      |    512 * 64 KB User MMIO      |
@@ -375,7 +379,7 @@ CXL Flash Driver Host IOCTLs
     Each host adapter instance that is supported by the cxlflash driver
     has a special character device associated with it to enable a set of
     host management function. These character devices are hosted in a
-    class dedicated for cxlflash and can be accessed via /dev/cxlflash/*.
+    class dedicated for cxlflash and can be accessed via `/dev/cxlflash/*`.
 
     Applications can be written to perform various functions using the
     host ioctl APIs below.
diff --git a/Documentation/powerpc/DAWR-POWER9.txt b/Documentation/powerpc/dawr-power9.rst
similarity index 95%
rename from Documentation/powerpc/DAWR-POWER9.txt
rename to Documentation/powerpc/dawr-power9.rst
index ecdbb076438c..c96ab6befd9c 100644
--- a/Documentation/powerpc/DAWR-POWER9.txt
+++ b/Documentation/powerpc/dawr-power9.rst
@@ -1,10 +1,11 @@
+=====================
 DAWR issues on POWER9
-============================
+=====================
 
 On POWER9 the Data Address Watchpoint Register (DAWR) can cause a checkstop
 if it points to cache inhibited (CI) memory. Currently Linux has no way to
 disinguish CI memory when configuring the DAWR, so (for now) the DAWR is
-disabled by this commit:
+disabled by this commit::
 
     commit 9654153158d3e0684a1bdb76dbababdb7111d5a0
     Author: Michael Neuling <mikey@neuling.org>
@@ -12,7 +13,7 @@ disabled by this commit:
     powerpc: Disable DAWR in the base POWER9 CPU features
 
 Technical Details:
-============================
+==================
 
 DAWR has 6 different ways of being set.
 1) ptrace
@@ -37,7 +38,7 @@ DAWR on the migration.
 For xmon, the 'bd' command will return an error on P9.
 
 Consequences for users
-============================
+======================
 
 For GDB watchpoints (ie 'watch' command) on POWER9 bare metal , GDB
 will accept the command. Unfortunately since there is no hardware
@@ -57,8 +58,8 @@ trapped in GDB. The watchpoint is remembered, so if the guest is
 migrated back to the POWER8 host, it will start working again.
 
 Force enabling the DAWR
-=============================
-Kernels (since ~v5.2) have an option to force enable the DAWR via:
+=======================
+Kernels (since ~v5.2) have an option to force enable the DAWR via::
 
   echo Y > /sys/kernel/debug/powerpc/dawr_enable_dangerous
 
@@ -86,5 +87,7 @@ dawr_enable_dangerous file will fail if the hypervisor doesn't support
 writing the DAWR.
 
 To double check the DAWR is working, run this kernel selftest:
+
   tools/testing/selftests/powerpc/ptrace/ptrace-hwbreak.c
+
 Any errors/failures/skips mean something is wrong.
diff --git a/Documentation/powerpc/dscr.txt b/Documentation/powerpc/dscr.rst
similarity index 91%
rename from Documentation/powerpc/dscr.txt
rename to Documentation/powerpc/dscr.rst
index ece300c64f76..2ab99006014c 100644
--- a/Documentation/powerpc/dscr.txt
+++ b/Documentation/powerpc/dscr.rst
@@ -1,5 +1,6 @@
-			DSCR (Data Stream Control Register)
-		================================================
+===================================
+DSCR (Data Stream Control Register)
+===================================
 
 DSCR register in powerpc allows user to have some control of prefetch of data
 stream in the processor. Please refer to the ISA documents or related manual
@@ -10,14 +11,17 @@ user interface.
 
 (A) Data Structures:
 
-	(1) thread_struct:
+	(1) thread_struct::
+
 		dscr		/* Thread DSCR value */
 		dscr_inherit	/* Thread has changed default DSCR */
 
-	(2) PACA:
+	(2) PACA::
+
 		dscr_default	/* per-CPU DSCR default value */
 
-	(3) sysfs.c:
+	(3) sysfs.c::
+
 		dscr_default	/* System DSCR default value */
 
 (B) Scheduler Changes:
@@ -35,8 +39,8 @@ user interface.
 
 (C) SYSFS Interface:
 
-	Global DSCR default:		/sys/devices/system/cpu/dscr_default
-	CPU specific DSCR default:	/sys/devices/system/cpu/cpuN/dscr
+	- Global DSCR default:		/sys/devices/system/cpu/dscr_default
+	- CPU specific DSCR default:	/sys/devices/system/cpu/cpuN/dscr
 
 	Changing the global DSCR default in the sysfs will change all the CPU
 	specific DSCR defaults immediately in their PACA structures. Again if
diff --git a/Documentation/powerpc/eeh-pci-error-recovery.txt b/Documentation/powerpc/eeh-pci-error-recovery.rst
similarity index 82%
rename from Documentation/powerpc/eeh-pci-error-recovery.txt
rename to Documentation/powerpc/eeh-pci-error-recovery.rst
index 678189280bb4..438a87ebc095 100644
--- a/Documentation/powerpc/eeh-pci-error-recovery.txt
+++ b/Documentation/powerpc/eeh-pci-error-recovery.rst
@@ -1,10 +1,10 @@
+==========================
+PCI Bus EEH Error Recovery
+==========================
 
+Linas Vepstas <linas@austin.ibm.com>
 
-                      PCI Bus EEH Error Recovery
-                      --------------------------
-                           Linas Vepstas
-                       <linas@austin.ibm.com>
-                          12 January 2005
+12 January 2005
 
 
 Overview:
@@ -143,17 +143,17 @@ seen in /proc/ppc64/eeh (subject to change).  Normally, almost
 all of these occur during boot, when the PCI bus is scanned, where
 a large number of 0xff reads are part of the bus scan procedure.
 
-If a frozen slot is detected, code in 
-arch/powerpc/platforms/pseries/eeh.c will print a stack trace to 
-syslog (/var/log/messages).  This stack trace has proven to be very 
-useful to device-driver authors for finding out at what point the EEH 
-error was detected, as the error itself usually occurs slightly 
+If a frozen slot is detected, code in
+arch/powerpc/platforms/pseries/eeh.c will print a stack trace to
+syslog (/var/log/messages).  This stack trace has proven to be very
+useful to device-driver authors for finding out at what point the EEH
+error was detected, as the error itself usually occurs slightly
 beforehand.
 
 Next, it uses the Linux kernel notifier chain/work queue mechanism to
 allow any interested parties to find out about the failure.  Device
 drivers, or other parts of the kernel, can use
-eeh_register_notifier(struct notifier_block *) to find out about EEH
+`eeh_register_notifier(struct notifier_block *)` to find out about EEH
 events.  The event will include a pointer to the pci device, the
 device node and some state info.  Receivers of the event can "do as
 they wish"; the default handler will be described further in this
@@ -162,10 +162,13 @@ section.
 To assist in the recovery of the device, eeh.c exports the
 following functions:
 
-rtas_set_slot_reset() -- assert the  PCI #RST line for 1/8th of a second
-rtas_configure_bridge() -- ask firmware to configure any PCI bridges
+rtas_set_slot_reset()
+   assert the  PCI #RST line for 1/8th of a second
+rtas_configure_bridge()
+   ask firmware to configure any PCI bridges
    located topologically under the pci slot.
-eeh_save_bars() and eeh_restore_bars(): save and restore the PCI
+eeh_save_bars() and eeh_restore_bars():
+   save and restore the PCI
    config-space info for a device and any devices under it.
 
 
@@ -191,7 +194,7 @@ events get delivered to user-space scripts.
 
 Following is an example sequence of events that cause a device driver
 close function to be called during the first phase of an EEH reset.
-The following sequence is an example of the pcnet32 device driver.
+The following sequence is an example of the pcnet32 device driver::
 
     rpa_php_unconfig_pci_adapter (struct slot *)  // in rpaphp_pci.c
     {
@@ -241,53 +244,54 @@ The following sequence is an example of the pcnet32 device driver.
      }}}}}}
 
 
-    in drivers/pci/pci_driver.c,
-    struct device_driver->remove() is just pci_device_remove()
-    which calls struct pci_driver->remove() which is pcnet32_remove_one()
-    which calls unregister_netdev()  (in net/core/dev.c)
-    which calls dev_close()  (in net/core/dev.c)
-    which calls dev->stop() which is pcnet32_close()
-    which then does the appropriate shutdown.
+in drivers/pci/pci_driver.c,
+struct device_driver->remove() is just pci_device_remove()
+which calls struct pci_driver->remove() which is pcnet32_remove_one()
+which calls unregister_netdev()  (in net/core/dev.c)
+which calls dev_close()  (in net/core/dev.c)
+which calls dev->stop() which is pcnet32_close()
+which then does the appropriate shutdown.
 
 ---
+
 Following is the analogous stack trace for events sent to user-space
-when the pci device is unconfigured.
+when the pci device is unconfigured::
 
-rpa_php_unconfig_pci_adapter() {             // in rpaphp_pci.c
-  calls
-  pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
+  rpa_php_unconfig_pci_adapter() {             // in rpaphp_pci.c
     calls
-    pci_destroy_dev (struct pci_dev *) {
+    pci_remove_bus_device (struct pci_dev *) { // in /drivers/pci/remove.c
       calls
-      device_unregister (&dev->dev) {        // in /drivers/base/core.c
+      pci_destroy_dev (struct pci_dev *) {
         calls
-        device_del(struct device * dev) {    // in /drivers/base/core.c
+        device_unregister (&dev->dev) {        // in /drivers/base/core.c
           calls
-          kobject_del() {                    //in /libs/kobject.c
+          device_del(struct device * dev) {    // in /drivers/base/core.c
             calls
-            kobject_uevent() {               // in /libs/kobject.c
+            kobject_del() {                    //in /libs/kobject.c
               calls
-              kset_uevent() {                // in /lib/kobject.c
+              kobject_uevent() {               // in /libs/kobject.c
                 calls
-                kset->uevent_ops->uevent()   // which is really just
-                a call to
-                dev_uevent() {               // in /drivers/base/core.c
+                kset_uevent() {                // in /lib/kobject.c
                   calls
-                  dev->bus->uevent() which is really just a call to
-                  pci_uevent () {            // in drivers/pci/hotplug.c
-                    which prints device name, etc....
+                  kset->uevent_ops->uevent()   // which is really just
+                  a call to
+                  dev_uevent() {               // in /drivers/base/core.c
+                    calls
+                    dev->bus->uevent() which is really just a call to
+                    pci_uevent () {            // in drivers/pci/hotplug.c
+                      which prints device name, etc....
+                   }
                  }
-               }
-               then kobject_uevent() sends a netlink uevent to userspace
-               --> userspace uevent
-               (during early boot, nobody listens to netlink events and
-               kobject_uevent() executes uevent_helper[], which runs the
-               event process /sbin/hotplug)
+                 then kobject_uevent() sends a netlink uevent to userspace
+                 --> userspace uevent
+                 (during early boot, nobody listens to netlink events and
+                 kobject_uevent() executes uevent_helper[], which runs the
+                 event process /sbin/hotplug)
+             }
            }
-         }
-         kobject_del() then calls sysfs_remove_dir(), which would
-         trigger any user-space daemon that was watching /sysfs,
-         and notice the delete event.
+           kobject_del() then calls sysfs_remove_dir(), which would
+           trigger any user-space daemon that was watching /sysfs,
+           and notice the delete event.
 
 
 Pro's and Con's of the Current Design
@@ -299,12 +303,12 @@ individual device drivers, so that the current design throws a wide net.
 The biggest negative of the design is that it potentially disturbs
 network daemons and file systems that didn't need to be disturbed.
 
--- A minor complaint is that resetting the network card causes
+-  A minor complaint is that resetting the network card causes
    user-space back-to-back ifdown/ifup burps that potentially disturb
    network daemons, that didn't need to even know that the pci
    card was being rebooted.
 
--- A more serious concern is that the same reset, for SCSI devices,
+-  A more serious concern is that the same reset, for SCSI devices,
    causes havoc to mounted file systems.  Scripts cannot post-facto
    unmount a file system without flushing pending buffers, but this
    is impossible, because I/O has already been stopped.  Thus,
@@ -322,7 +326,7 @@ network daemons and file systems that didn't need to be disturbed.
    from the block layer.  It would be very natural to add an EEH
    reset into this chain of events.
 
--- If a SCSI error occurs for the root device, all is lost unless
+-  If a SCSI error occurs for the root device, all is lost unless
    the sysadmin had the foresight to run /bin, /sbin, /etc, /var
    and so on, out of ramdisk/tmpfs.
 
@@ -330,5 +334,3 @@ network daemons and file systems that didn't need to be disturbed.
 Conclusions
 -----------
 There's forward progress ...
-
-
diff --git a/Documentation/powerpc/firmware-assisted-dump.txt b/Documentation/powerpc/firmware-assisted-dump.rst
similarity index 80%
rename from Documentation/powerpc/firmware-assisted-dump.txt
rename to Documentation/powerpc/firmware-assisted-dump.rst
index 10e7f4d16c14..9ca12830a48e 100644
--- a/Documentation/powerpc/firmware-assisted-dump.txt
+++ b/Documentation/powerpc/firmware-assisted-dump.rst
@@ -1,7 +1,8 @@
+======================
+Firmware-Assisted Dump
+======================
 
-                   Firmware-Assisted Dump
-                   ------------------------
-                       July 2011
+July 2011
 
 The goal of firmware-assisted dump is to enable the dump of
 a crashed system, and to do so from a fully-reset system, and
@@ -27,11 +28,11 @@ in production use.
 Comparing with kdump or other strategies, firmware-assisted
 dump offers several strong, practical advantages:
 
--- Unlike kdump, the system has been reset, and loaded
+-  Unlike kdump, the system has been reset, and loaded
    with a fresh copy of the kernel.  In particular,
    PCI and I/O devices have been reinitialized and are
    in a clean, consistent state.
--- Once the dump is copied out, the memory that held the dump
+-  Once the dump is copied out, the memory that held the dump
    is immediately available to the running kernel. And therefore,
    unlike kdump, fadump doesn't need a 2nd reboot to get back
    the system to the production configuration.
@@ -40,17 +41,18 @@ The above can only be accomplished by coordination with,
 and assistance from the Power firmware. The procedure is
 as follows:
 
--- The first kernel registers the sections of memory with the
+-  The first kernel registers the sections of memory with the
    Power firmware for dump preservation during OS initialization.
    These registered sections of memory are reserved by the first
    kernel during early boot.
 
--- When a system crashes, the Power firmware will save
+-  When a system crashes, the Power firmware will save
    the low memory (boot memory of size larger of 5% of system RAM
    or 256MB) of RAM to the previous registered region. It will
    also save system registers, and hardware PTE's.
 
-   NOTE: The term 'boot memory' means size of the low memory chunk
+   NOTE:
+         The term 'boot memory' means size of the low memory chunk
          that is required for a kernel to boot successfully when
          booted with restricted memory. By default, the boot memory
          size will be the larger of 5% of system RAM or 256MB.
@@ -64,12 +66,12 @@ as follows:
          as fadump uses a predefined offset to reserve memory
          for boot memory dump preservation in case of a crash.
 
--- After the low memory (boot memory) area has been saved, the
+-  After the low memory (boot memory) area has been saved, the
    firmware will reset PCI and other hardware state.  It will
    *not* clear the RAM. It will then launch the bootloader, as
    normal.
 
--- The freshly booted kernel will notice that there is a new
+-  The freshly booted kernel will notice that there is a new
    node (ibm,dump-kernel) in the device tree, indicating that
    there is crash data available from a previous boot. During
    the early boot OS will reserve rest of the memory above
@@ -77,17 +79,18 @@ as follows:
    size. This will make sure that the second kernel will not
    touch any of the dump memory area.
 
--- User-space tools will read /proc/vmcore to obtain the contents
+-  User-space tools will read /proc/vmcore to obtain the contents
    of memory, which holds the previous crashed kernel dump in ELF
    format. The userspace tools may copy this info to disk, or
    network, nas, san, iscsi, etc. as desired.
 
--- Once the userspace tool is done saving dump, it will echo
+-  Once the userspace tool is done saving dump, it will echo
    '1' to /sys/kernel/fadump_release_mem to release the reserved
    memory back to general use, except the memory required for
    next firmware-assisted dump registration.
 
-   e.g.
+   e.g.::
+
      # echo 1 > /sys/kernel/fadump_release_mem
 
 Please note that the firmware-assisted dump feature
@@ -95,7 +98,7 @@ is only available on Power6 and above systems with recent
 firmware versions.
 
 Implementation details:
-----------------------
+-----------------------
 
 During boot, a check is made to see if firmware supports
 this feature on that particular machine. If it does, then
@@ -121,7 +124,7 @@ Allocator (CMA) for memory reservation if CMA is configured for kernel.
 With CMA reservation this memory will be available for applications to
 use it, while kernel is prevented from using it. With this fadump will
 still be able to capture all of the kernel memory and most of the user
-space memory except the user pages that were present in CMA region.
+space memory except the user pages that were present in CMA region::
 
   o Memory Reservation during first kernel
 
@@ -166,7 +169,7 @@ The tools to examine the dump will be same as the ones
 used for kdump.
 
 How to enable firmware-assisted dump (fadump):
--------------------------------------
+----------------------------------------------
 
 1. Set config option CONFIG_FA_DUMP=y and build kernel.
 2. Boot into linux kernel with 'fadump=on' kernel cmdline option.
@@ -177,19 +180,20 @@ How to enable firmware-assisted dump (fadump):
    to specify size of the memory to reserve for boot memory dump
    preservation.
 
-NOTE: 1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
-         use 'crashkernel=' to specify size of the memory to reserve
-         for boot memory dump preservation.
-      2. If firmware-assisted dump fails to reserve memory then it
-         will fallback to existing kdump mechanism if 'crashkernel='
-         option is set at kernel cmdline.
-      3. if user wants to capture all of user space memory and ok with
-         reserved memory not available to production system, then
-         'fadump=nocma' kernel parameter can be used to fallback to
-         old behaviour.
+NOTE:
+     1. 'fadump_reserve_mem=' parameter has been deprecated. Instead
+        use 'crashkernel=' to specify size of the memory to reserve
+        for boot memory dump preservation.
+     2. If firmware-assisted dump fails to reserve memory then it
+        will fallback to existing kdump mechanism if 'crashkernel='
+        option is set at kernel cmdline.
+     3. if user wants to capture all of user space memory and ok with
+        reserved memory not available to production system, then
+        'fadump=nocma' kernel parameter can be used to fallback to
+        old behaviour.
 
 Sysfs/debugfs files:
-------------
+--------------------
 
 Firmware-assisted dump feature uses sysfs file system to hold
 the control files and debugfs file to display memory reserved region.
@@ -197,20 +201,20 @@ the control files and debugfs file to display memory reserved region.
 Here is the list of files under kernel sysfs:
 
  /sys/kernel/fadump_enabled
-
     This is used to display the fadump status.
-    0 = fadump is disabled
-    1 = fadump is enabled
+
+    - 0 = fadump is disabled
+    - 1 = fadump is enabled
 
     This interface can be used by kdump init scripts to identify if
     fadump is enabled in the kernel and act accordingly.
 
  /sys/kernel/fadump_registered
-
     This is used to display the fadump registration status as well
     as to control (start/stop) the fadump registration.
-    0 = fadump is not registered.
-    1 = fadump is registered and ready to handle system crash.
+
+    - 0 = fadump is not registered.
+    - 1 = fadump is registered and ready to handle system crash.
 
     To register fadump echo 1 > /sys/kernel/fadump_registered and
     echo 0 > /sys/kernel/fadump_registered for un-register and stop the
@@ -219,13 +223,12 @@ Here is the list of files under kernel sysfs:
     easily integrated with kdump service start/stop.
 
  /sys/kernel/fadump_release_mem
-
     This file is available only when fadump is active during
     second kernel. This is used to release the reserved memory
     region that are held for saving crash dump. To release the
-    reserved memory echo 1 to it:
+    reserved memory echo 1 to it::
 
-    echo 1  > /sys/kernel/fadump_release_mem
+	echo 1  > /sys/kernel/fadump_release_mem
 
     After echo 1, the content of the /sys/kernel/debug/powerpc/fadump_region
     file will change to reflect the new memory reservations.
@@ -238,38 +241,39 @@ Here is the list of files under powerpc debugfs:
 (Assuming debugfs is mounted on /sys/kernel/debug directory.)
 
  /sys/kernel/debug/powerpc/fadump_region
-
     This file shows the reserved memory regions if fadump is
     enabled otherwise this file is empty. The output format
-    is:
-    <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
+    is::
+
+      <region>: [<start>-<end>] <reserved-size> bytes, Dumped: <dump-size>
 
     e.g.
-    Contents when fadump is registered during first kernel
+    Contents when fadump is registered during first kernel::
 
-    # cat /sys/kernel/debug/powerpc/fadump_region
-    CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
-    HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
-    DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
+      # cat /sys/kernel/debug/powerpc/fadump_region
+      CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x0
+      HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x0
+      DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x0
 
-    Contents when fadump is active during second kernel
+    Contents when fadump is active during second kernel::
 
-    # cat /sys/kernel/debug/powerpc/fadump_region
-    CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
-    HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
-    DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
-        : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
+      # cat /sys/kernel/debug/powerpc/fadump_region
+      CPU : [0x0000006ffb0000-0x0000006fff001f] 0x40020 bytes, Dumped: 0x40020
+      HPTE: [0x0000006fff0020-0x0000006fff101f] 0x1000 bytes, Dumped: 0x1000
+      DUMP: [0x0000006fff1020-0x0000007fff101f] 0x10000000 bytes, Dumped: 0x10000000
+          : [0x00000010000000-0x0000006ffaffff] 0x5ffb0000 bytes, Dumped: 0x5ffb0000
 
-NOTE: Please refer to Documentation/filesystems/debugfs.txt on
+NOTE:
+      Please refer to Documentation/filesystems/debugfs.txt on
       how to mount the debugfs filesystem.
 
 
 TODO:
 -----
- o Need to come up with the better approach to find out more
+ - Need to come up with the better approach to find out more
    accurate boot memory size that is required for a kernel to
    boot successfully when booted with restricted memory.
- o The fadump implementation introduces a fadump crash info structure
+ - The fadump implementation introduces a fadump crash info structure
    in the scratch area before the ELF core header. The idea of introducing
    this structure is to pass some important crash info data to the second
    kernel which will help second kernel to populate ELF core header with
@@ -277,7 +281,9 @@ TODO:
    design implementation does not address a possibility of introducing
    additional fields (in future) to this structure without affecting
    compatibility. Need to come up with the better approach to address this.
+
    The possible approaches are:
+
 	1. Introduce version field for version tracking, bump up the version
 	whenever a new field is added to the structure in future. The version
 	field can be used to find out what fields are valid for the current
@@ -285,8 +291,11 @@ TODO:
 	2. Reserve the area of predefined size (say PAGE_SIZE) for this
 	structure and have unused area as reserved (initialized to zero)
 	for future field additions.
+
    The advantage of approach 1 over 2 is we don't need to reserve extra space.
----
+
 Author: Mahesh Salgaonkar <mahesh@linux.vnet.ibm.com>
+
 This document is based on the original documentation written for phyp
+
 assisted dump by Linas Vepstas and Manish Ahuja.
diff --git a/Documentation/powerpc/hvcs.txt b/Documentation/powerpc/hvcs.rst
similarity index 91%
rename from Documentation/powerpc/hvcs.txt
rename to Documentation/powerpc/hvcs.rst
index a730ca5a07f8..6808acde672f 100644
--- a/Documentation/powerpc/hvcs.txt
+++ b/Documentation/powerpc/hvcs.rst
@@ -1,19 +1,22 @@
-===========================================================================
-				   HVCS
-	IBM "Hypervisor Virtual Console Server" Installation Guide
-			  for Linux Kernel 2.6.4+
-		    Copyright (C) 2004 IBM Corporation
+===============================================================
+HVCS IBM "Hypervisor Virtual Console Server" Installation Guide
+===============================================================
 
-===========================================================================
-NOTE:Eight space tabs are the optimum editor setting for reading this file.
-===========================================================================
+for Linux Kernel 2.6.4+
 
-	       Author(s) :  Ryan S. Arnold <rsa@us.ibm.com>
-		       Date Created: March, 02, 2004
-		       Last Changed: August, 24, 2004
+Copyright (C) 2004 IBM Corporation
 
----------------------------------------------------------------------------
-Table of contents:
+.. ===========================================================================
+.. NOTE:Eight space tabs are the optimum editor setting for reading this file.
+.. ===========================================================================
+
+
+Author(s): Ryan S. Arnold <rsa@us.ibm.com>
+
+Date Created: March, 02, 2004
+Last Changed: August, 24, 2004
+
+.. Table of contents:
 
 	1.  Driver Introduction:
 	2.  System Requirements
@@ -27,8 +30,8 @@ Table of contents:
 	8.  Questions & Answers:
 	9.  Reporting Bugs:
 
----------------------------------------------------------------------------
 1. Driver Introduction:
+=======================
 
 This is the device driver for the IBM Hypervisor Virtual Console Server,
 "hvcs".  The IBM hvcs provides a tty driver interface to allow Linux user
@@ -38,8 +41,8 @@ ppc64 system.  Physical hardware consoles per partition are not practical
 on this hardware so system consoles are accessed by this driver using
 firmware interfaces to virtual terminal devices.
 
----------------------------------------------------------------------------
 2. System Requirements:
+=======================
 
 This device driver was written using 2.6.4 Linux kernel APIs and will only
 build and run on kernels of this version or later.
@@ -52,8 +55,8 @@ Sysfs must be mounted on the system so that the user can determine which
 major and minor numbers are associated with each vty-server.  Directions
 for sysfs mounting are outside the scope of this document.
 
----------------------------------------------------------------------------
 3. Build Options:
+=================
 
 The hvcs driver registers itself as a tty driver.  The tty layer
 dynamically allocates a block of major and minor numbers in a quantity
@@ -65,11 +68,11 @@ If the default number of device entries is adequate then this driver can be
 built into the kernel.  If not, the default can be over-ridden by inserting
 the driver as a module with insmod parameters.
 
----------------------------------------------------------------------------
 3.1 Built-in:
+-------------
 
 The following menuconfig example demonstrates selecting to build this
-driver into the kernel.
+driver into the kernel::
 
 	Device Drivers  --->
 		Character devices  --->
@@ -77,11 +80,11 @@ driver into the kernel.
 
 Begin the kernel make process.
 
----------------------------------------------------------------------------
 3.2 Module:
+-----------
 
 The following menuconfig example demonstrates selecting to build this
-driver as a kernel module.
+driver as a kernel module::
 
 	Device Drivers  --->
 		Character devices  --->
@@ -89,11 +92,11 @@ driver as a kernel module.
 
 The make process will build the following kernel modules:
 
-	hvcs.ko
-	hvcserver.ko
+	- hvcs.ko
+	- hvcserver.ko
 
 To insert the module with the default allocation execute the following
-commands in the order they appear:
+commands in the order they appear::
 
 	insmod hvcserver.ko
 	insmod hvcs.ko
@@ -103,7 +106,7 @@ be inserted first, otherwise the hvcs module will not find some of the
 symbols it expects.
 
 To override the default use an insmod parameter as follows (requesting 4
-tty devices as an example):
+tty devices as an example)::
 
 	insmod hvcs.ko hvcs_parm_num_devs=4
 
@@ -115,31 +118,31 @@ source file before building.
 NOTE: The length of time it takes to insmod the driver seems to be related
 to the number of tty interfaces the registering driver requests.
 
-In order to remove the driver module execute the following command:
+In order to remove the driver module execute the following command::
 
 	rmmod hvcs.ko
 
 The recommended method for installing hvcs as a module is to use depmod to
 build a current modules.dep file in /lib/modules/`uname -r` and then
-execute:
+execute::
 
-modprobe hvcs hvcs_parm_num_devs=4
+	modprobe hvcs hvcs_parm_num_devs=4
 
 The modules.dep file indicates that hvcserver.ko needs to be inserted
 before hvcs.ko and modprobe uses this file to smartly insert the modules in
 the proper order.
 
 The following modprobe command is used to remove hvcs and hvcserver in the
-proper order:
+proper order::
 
-modprobe -r hvcs
+	modprobe -r hvcs
 
----------------------------------------------------------------------------
 4. Installation:
+================
 
 The tty layer creates sysfs entries which contain the major and minor
 numbers allocated for the hvcs driver.  The following snippet of "tree"
-output of the sysfs directory shows where these numbers are presented:
+output of the sysfs directory shows where these numbers are presented::
 
 	sys/
 	|-- *other sysfs base dirs*
@@ -164,7 +167,7 @@ output of the sysfs directory shows where these numbers are presented:
 	|-- *other sysfs base dirs*
 
 For the above examples the following output is a result of cat'ing the
-"dev" entry in the hvcs directory:
+"dev" entry in the hvcs directory::
 
 	Pow5:/sys/class/tty/hvcs0/ # cat dev
 	254:0
@@ -184,7 +187,7 @@ systems running hvcs will already have the device entries created or udev
 will do it automatically.
 
 Given the example output above, to manually create a /dev/hvcs* node entry
-mknod can be used as follows:
+mknod can be used as follows::
 
 	mknod /dev/hvcs0 c 254 0
 	mknod /dev/hvcs1 c 254 1
@@ -195,15 +198,15 @@ Using mknod to manually create the device entries makes these device nodes
 persistent.  Once created they will exist prior to the driver insmod.
 
 Attempting to connect an application to /dev/hvcs* prior to insertion of
-the hvcs module will result in an error message similar to the following:
+the hvcs module will result in an error message similar to the following::
 
 	"/dev/hvcs*: No such device".
 
 NOTE: Just because there is a device node present doesn't mean that there
 is a vty-server device configured for that node.
 
----------------------------------------------------------------------------
 5. Connection
+=============
 
 Since this driver controls devices that provide a tty interface a user can
 interact with the device node entries using any standard tty-interactive
@@ -249,7 +252,7 @@ vty-server adapter is associated with which /dev/hvcs* node a special sysfs
 attribute has been added to each vty-server sysfs entry.  This entry is
 called "index" and showing it reveals an integer that refers to the
 /dev/hvcs* entry to use to connect to that device.  For instance cating the
-index attribute of vty-server adapter 30000004 shows the following.
+index attribute of vty-server adapter 30000004 shows the following::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
 	2
@@ -262,8 +265,8 @@ system the /dev/hvcs* entry that interacts with a particular vty-server
 adapter is not guaranteed to remain the same across system reboots.  Look
 in the Q & A section for more on this issue.
 
----------------------------------------------------------------------------
 6. Disconnection
+================
 
 As a security feature to prevent the delivery of stale data to an
 unintended target the Power5 system firmware disables the fetching of data
@@ -305,7 +308,7 @@ connection between the vty-server and target vty ONLY if the vterm_state
 previously read '1'.  The write directive is ignored if the vterm_state
 read '0' or if any value other than '0' was written to the vterm_state
 attribute.  The following example will show the method used for verifying
-the vty-server connection status and disconnecting a vty-server connection.
+the vty-server connection status and disconnecting a vty-server connection::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
 	1
@@ -318,12 +321,12 @@ the vty-server connection status and disconnecting a vty-server connection.
 All vty-server connections are automatically terminated when the device is
 hotplug removed and when the module is removed.
 
----------------------------------------------------------------------------
 7. Configuration
+================
 
 Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
 is symlinked in several other sysfs tree directories, notably under the
-hvcs driver entry, which looks like the following example:
+hvcs driver entry, which looks like the following example::
 
 	Pow5:/sys/bus/vio/drivers/hvcs # ls
 	.  ..  30000003  30000004  rescan
@@ -344,7 +347,7 @@ completed or was never executed.
 
 Vty-server entries in this directory are a 32 bit partition unique unit
 address that is created by firmware.  An example vty-server sysfs entry
-looks like the following:
+looks like the following::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
 	.   current_vty   devspec       name          partner_vtys
@@ -352,21 +355,21 @@ looks like the following:
 
 Each entry is provided, by default with a "name" attribute.  Reading the
 "name" attribute will reveal the device type as shown in the following
-example:
+example::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
 	vty-server
 
 Each entry is also provided, by default, with a "devspec" attribute which
 reveals the full device specification when read, as shown in the following
-example:
+example::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
 	/vdevice/vty-server@30000004
 
 Each vty-server sysfs dir is provided with two read-only attributes that
 provide lists of easily parsed partner vty data: "partner_vtys" and
-"partner_clcs".
+"partner_clcs"::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
 	30000000
@@ -396,7 +399,7 @@ A vty-server can only be connected to a single vty at a time.  The entry,
 read.
 
 The current_vty can be changed by writing a valid partner clc to the entry
-as in the following example:
+as in the following example::
 
 	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
 	8A-V4-C0 > current_vty
@@ -408,9 +411,9 @@ currently open connection is freed.
 Information on the "vterm_state" attribute was covered earlier on the
 chapter entitled "disconnection".
 
----------------------------------------------------------------------------
 8. Questions & Answers:
-===========================================================================
+=======================
+
 Q: What are the security concerns involving hvcs?
 
 A: There are three main security concerns:
@@ -429,6 +432,7 @@ A: There are three main security concerns:
 	partition) will experience the previously logged in session.
 
 ---------------------------------------------------------------------------
+
 Q: How do I multiplex a console that I grab through hvcs so that other
 people can see it:
 
@@ -440,6 +444,7 @@ term type "screen" to others.  This means that curses based programs may
 not display properly in screen sessions.
 
 ---------------------------------------------------------------------------
+
 Q: Why are the colors all messed up?
 Q: Why are the control characters acting strange or not working?
 Q: Why is the console output all strange and unintelligible?
@@ -455,6 +460,7 @@ disconnect from the console.  This will ensure that the next user gets
 their own TERM type set when they login.
 
 ---------------------------------------------------------------------------
+
 Q: When I try to CONNECT kermit to an hvcs device I get:
 "Sorry, can't open connection: /dev/hvcs*"What is happening?
 
@@ -490,6 +496,7 @@ A: There is not a corresponding vty-server device that maps to an existing
 /dev/hvcs* entry.
 
 ---------------------------------------------------------------------------
+
 Q: When I try to CONNECT kermit to an hvcs device I get:
 "Sorry, write access to UUCP lockfile directory denied."
 
@@ -497,6 +504,7 @@ A: The /dev/hvcs* entry you have specified doesn't exist where you said it
 does?  Maybe you haven't inserted the module (on systems with udev).
 
 ---------------------------------------------------------------------------
+
 Q: If I already have one Linux partition installed can I use hvcs on said
 partition to provide the console for the install of a second Linux
 partition?
@@ -505,6 +513,7 @@ A: Yes granted that your are connected to the /dev/hvcs* device using
 kermit or cu or some other program that doesn't provide terminal emulation.
 
 ---------------------------------------------------------------------------
+
 Q: Can I connect to more than one partition's console at a time using this
 driver?
 
@@ -512,6 +521,7 @@ A: Yes.  Of course this means that there must be more than one vty-server
 configured for this partition and each must point to a disconnected vty.
 
 ---------------------------------------------------------------------------
+
 Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
 
 A: Yes, if you have dlpar and hotplug enabled for your system and it has
@@ -519,6 +529,7 @@ been built into the kernel the hvcs drivers is configured to dynamically
 handle additions of new devices and removals of unused devices.
 
 ---------------------------------------------------------------------------
+
 Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
 after a reboot.  What happened?
 
@@ -533,6 +544,7 @@ on how to determine which vty-server goes with which /dev/hvcs* node.
 Hint; look at the sysfs "index" attribute for the vty-server.
 
 ---------------------------------------------------------------------------
+
 Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
 device on that partition as the other end of the pipe?
 
@@ -554,7 +566,9 @@ read or write to /dev/hvcs*.  Now you have a tty conduit between two
 partitions.
 
 ---------------------------------------------------------------------------
+
 9. Reporting Bugs:
+==================
 
 The proper channel for reporting bugs is either through the Linux OS
 distribution company that provided your OS or by posting issues to the
diff --git a/Documentation/powerpc/index.rst b/Documentation/powerpc/index.rst
new file mode 100644
index 000000000000..549b1cdd77ae
--- /dev/null
+++ b/Documentation/powerpc/index.rst
@@ -0,0 +1,34 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======
+powerpc
+=======
+
+.. toctree::
+    :maxdepth: 1
+
+    bootwrapper
+    cpu_families
+    cpu_features
+    cxl
+    cxlflash
+    dawr-power9
+    dscr
+    eeh-pci-error-recovery
+    firmware-assisted-dump
+    hvcs
+    isa-versions
+    mpc52xx
+    pci_iov_resource_on_powernv
+    pmu-ebb
+    ptrace
+    qe_firmware
+    syscall64-abi
+    transactional_memory
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/powerpc/isa-versions.rst b/Documentation/powerpc/isa-versions.rst
index 66c24140ebf1..a363d8c1603c 100644
--- a/Documentation/powerpc/isa-versions.rst
+++ b/Documentation/powerpc/isa-versions.rst
@@ -1,13 +1,12 @@
-:orphan:
-
+==========================
 CPU to ISA Version Mapping
 ==========================
 
 Mapping of some CPU versions to relevant ISA versions.
 
-========= ====================
+========= ====================================================================
 CPU       Architecture version
-========= ====================
+========= ====================================================================
 Power9    Power ISA v3.0B
 Power8    Power ISA v2.07
 Power7    Power ISA v2.06
@@ -24,7 +23,7 @@ PPC970    - PowerPC User Instruction Set Architecture Book I v2.01
           - PowerPC Virtual Environment Architecture Book II v2.01
           - PowerPC Operating Environment Architecture Book III v2.01
           - Plus Altivec/VMX ~= 2.03
-========= ====================
+========= ====================================================================
 
 
 Key Features
@@ -60,9 +59,9 @@ Power5     No
 PPC970     No
 ========== ====
 
-========== ====================
+========== ====================================
 CPU        Transactional Memory
-========== ====================
+========== ====================================
 Power9     Yes (* see transactional_memory.txt)
 Power8     Yes
 Power7     No
@@ -73,4 +72,4 @@ Power5++   No
 Power5+    No
 Power5     No
 PPC970     No
-========== ====================
+========== ====================================
diff --git a/Documentation/powerpc/mpc52xx.txt b/Documentation/powerpc/mpc52xx.rst
similarity index 91%
rename from Documentation/powerpc/mpc52xx.txt
rename to Documentation/powerpc/mpc52xx.rst
index 0d540a31ea1a..8676ac63e077 100644
--- a/Documentation/powerpc/mpc52xx.txt
+++ b/Documentation/powerpc/mpc52xx.rst
@@ -1,11 +1,13 @@
+=============================
 Linux 2.6.x on MPC52xx family
------------------------------
+=============================
 
 For the latest info, go to http://www.246tNt.com/mpc52xx/
 
 To compile/use :
 
-  - U-Boot:
+  - U-Boot::
+
      # <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
         if you wish to ).
      # make lite5200_defconfig
@@ -16,7 +18,8 @@ To compile/use :
      => tftpboot 400000 pRamdisk
      => bootm 200000 400000
 
-  - DBug:
+  - DBug::
+
      # <edit Makefile to set ARCH=ppc & CROSS_COMPILE=... ( also EXTRAVERSION
         if you wish to ).
      # make lite5200_defconfig
@@ -28,7 +31,8 @@ To compile/use :
      DBug> dn -i zImage.initrd.lite5200
 
 
-Some remarks :
+Some remarks:
+
  - The port is named mpc52xxx, and config options are PPC_MPC52xx. The MGT5100
    is not supported, and I'm not sure anyone is interesting in working on it
    so. I didn't took 5xxx because there's apparently a lot of 5xxx that have
diff --git a/Documentation/powerpc/pci_iov_resource_on_powernv.txt b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
similarity index 97%
rename from Documentation/powerpc/pci_iov_resource_on_powernv.txt
rename to Documentation/powerpc/pci_iov_resource_on_powernv.rst
index b55c5cd83f8d..f5a5793e1613 100644
--- a/Documentation/powerpc/pci_iov_resource_on_powernv.txt
+++ b/Documentation/powerpc/pci_iov_resource_on_powernv.rst
@@ -1,6 +1,13 @@
+===================================================
+PCI Express I/O Virtualization Resource on Powerenv
+===================================================
+
 Wei Yang <weiyang@linux.vnet.ibm.com>
+
 Benjamin Herrenschmidt <benh@au1.ibm.com>
+
 Bjorn Helgaas <bhelgaas@google.com>
+
 26 Aug 2014
 
 This document describes the requirement from hardware for PCI MMIO resource
@@ -10,6 +17,7 @@ Endpoints and the implementation on P8 (IODA2). The next two sections talks
 about considerations on enabling SRIOV on IODA2.
 
 1. Introduction to Partitionable Endpoints
+==========================================
 
 A Partitionable Endpoint (PE) is a way to group the various resources
 associated with a device or a set of devices to provide isolation between
@@ -35,6 +43,7 @@ is a completely separate HW entity that replicates the entire logic, so has
 its own set of PEs, etc.
 
 2. Implementation of Partitionable Endpoints on P8 (IODA2)
+==========================================================
 
 P8 supports up to 256 Partitionable Endpoints per PHB.
 
@@ -149,6 +158,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
     sense, but we haven't done it yet.
 
 3. Considerations for SR-IOV on PowerKVM
+========================================
 
   * SR-IOV Background
 
@@ -224,7 +234,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
   IODA supports 256 PEs, so segmented windows contain 256 segments, so if
   total_VFs is less than 256, we have the situation in Figure 1.0, where
   segments [total_VFs, 255] of the M64 window may map to some MMIO range on
-  other devices:
+  other devices::
 
      0      1                     total_VFs - 1
      +------+------+-     -+------+------+
@@ -243,7 +253,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
 		Figure 1.0 Direct map VF(n) BAR space
 
   Our current solution is to allocate 256 segments even if the VF(n) BAR
-  space doesn't need that much, as shown in Figure 1.1:
+  space doesn't need that much, as shown in Figure 1.1::
 
      0      1                     total_VFs - 1                255
      +------+------+-     -+------+------+-      -+------+------+
@@ -269,6 +279,7 @@ P8 supports up to 256 Partitionable Endpoints per PHB.
   responds to segments [total_VFs, 255].
 
 4. Implications for the Generic PCI Code
+========================================
 
 The PCIe SR-IOV spec requires that the base of the VF(n) BAR space be
 aligned to the size of an individual VF BAR.
diff --git a/Documentation/powerpc/pmu-ebb.txt b/Documentation/powerpc/pmu-ebb.rst
similarity index 99%
rename from Documentation/powerpc/pmu-ebb.txt
rename to Documentation/powerpc/pmu-ebb.rst
index 73cd163dbfb8..4f474758eb55 100644
--- a/Documentation/powerpc/pmu-ebb.txt
+++ b/Documentation/powerpc/pmu-ebb.rst
@@ -1,3 +1,4 @@
+========================
 PMU Event Based Branches
 ========================
 
diff --git a/Documentation/powerpc/ptrace.txt b/Documentation/powerpc/ptrace.rst
similarity index 48%
rename from Documentation/powerpc/ptrace.txt
rename to Documentation/powerpc/ptrace.rst
index 99c5ce88d0fe..864d4b6dddd1 100644
--- a/Documentation/powerpc/ptrace.txt
+++ b/Documentation/powerpc/ptrace.rst
@@ -1,3 +1,7 @@
+======
+Ptrace
+======
+
 GDB intends to support the following hardware debug features of BookE
 processors:
 
@@ -12,6 +16,7 @@ that GDB doesn't need to special-case each of them. We added the
 following 3 new ptrace requests.
 
 1. PTRACE_PPC_GETHWDEBUGINFO
+============================
 
 Query for GDB to discover the hardware debug features. The main info to
 be returned here is the minimum alignment for the hardware watchpoints.
@@ -22,9 +27,9 @@ adding special cases to GDB based on what it sees in AUXV.
 Since we're at it, we added other useful info that the kernel can return to
 GDB: this query will return the number of hardware breakpoints, hardware
 watchpoints and whether it supports a range of addresses and a condition.
-The query will fill the following structure provided by the requesting process:
+The query will fill the following structure provided by the requesting process::
 
-struct ppc_debug_info {
+  struct ppc_debug_info {
        unit32_t version;
        unit32_t num_instruction_bps;
        unit32_t num_data_bps;
@@ -32,46 +37,46 @@ struct ppc_debug_info {
        unit32_t data_bp_alignment;
        unit32_t sizeof_condition; /* size of the DVC register */
        uint64_t features; /* bitmask of the individual flags */
-};
+  };
 
-features will have bits indicating whether there is support for:
+features will have bits indicating whether there is support for::
 
-#define PPC_DEBUG_FEATURE_INSN_BP_RANGE		0x1
-#define PPC_DEBUG_FEATURE_INSN_BP_MASK		0x2
-#define PPC_DEBUG_FEATURE_DATA_BP_RANGE		0x4
-#define PPC_DEBUG_FEATURE_DATA_BP_MASK		0x8
-#define PPC_DEBUG_FEATURE_DATA_BP_DAWR		0x10
+  #define PPC_DEBUG_FEATURE_INSN_BP_RANGE		0x1
+  #define PPC_DEBUG_FEATURE_INSN_BP_MASK		0x2
+  #define PPC_DEBUG_FEATURE_DATA_BP_RANGE		0x4
+  #define PPC_DEBUG_FEATURE_DATA_BP_MASK		0x8
+  #define PPC_DEBUG_FEATURE_DATA_BP_DAWR		0x10
 
 2. PTRACE_SETHWDEBUG
 
-Sets a hardware breakpoint or watchpoint, according to the provided structure:
+Sets a hardware breakpoint or watchpoint, according to the provided structure::
 
-struct ppc_hw_breakpoint {
+  struct ppc_hw_breakpoint {
         uint32_t version;
-#define PPC_BREAKPOINT_TRIGGER_EXECUTE  0x1
-#define PPC_BREAKPOINT_TRIGGER_READ     0x2
-#define PPC_BREAKPOINT_TRIGGER_WRITE    0x4
+  #define PPC_BREAKPOINT_TRIGGER_EXECUTE  0x1
+  #define PPC_BREAKPOINT_TRIGGER_READ     0x2
+ #define PPC_BREAKPOINT_TRIGGER_WRITE    0x4
         uint32_t trigger_type;       /* only some combinations allowed */
-#define PPC_BREAKPOINT_MODE_EXACT               0x0
-#define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE     0x1
-#define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE     0x2
-#define PPC_BREAKPOINT_MODE_MASK                0x3
+  #define PPC_BREAKPOINT_MODE_EXACT               0x0
+  #define PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE     0x1
+  #define PPC_BREAKPOINT_MODE_RANGE_EXCLUSIVE     0x2
+  #define PPC_BREAKPOINT_MODE_MASK                0x3
         uint32_t addr_mode;          /* address match mode */
 
-#define PPC_BREAKPOINT_CONDITION_MODE   0x3
-#define PPC_BREAKPOINT_CONDITION_NONE   0x0
-#define PPC_BREAKPOINT_CONDITION_AND    0x1
-#define PPC_BREAKPOINT_CONDITION_EXACT  0x1	/* different name for the same thing as above */
-#define PPC_BREAKPOINT_CONDITION_OR     0x2
-#define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
-#define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000	/* byte enable bits */
-#define PPC_BREAKPOINT_CONDITION_BE(n)  (1<<((n)+16))
+  #define PPC_BREAKPOINT_CONDITION_MODE   0x3
+  #define PPC_BREAKPOINT_CONDITION_NONE   0x0
+  #define PPC_BREAKPOINT_CONDITION_AND    0x1
+  #define PPC_BREAKPOINT_CONDITION_EXACT  0x1	/* different name for the same thing as above */
+  #define PPC_BREAKPOINT_CONDITION_OR     0x2
+  #define PPC_BREAKPOINT_CONDITION_AND_OR 0x3
+  #define PPC_BREAKPOINT_CONDITION_BE_ALL 0x00ff0000	/* byte enable bits */
+  #define PPC_BREAKPOINT_CONDITION_BE(n)  (1<<((n)+16))
         uint32_t condition_mode;     /* break/watchpoint condition flags */
 
         uint64_t addr;
         uint64_t addr2;
         uint64_t condition_value;
-};
+  };
 
 A request specifies one event, not necessarily just one register to be set.
 For instance, if the request is for a watchpoint with a condition, both the
@@ -88,61 +93,61 @@ can't be allocated on the registers.
 
 Some examples of using the structure to:
 
-- set a breakpoint in the first breakpoint register
-
-  p.version         = PPC_DEBUG_CURRENT_VERSION;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_EXECUTE;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
-  p.addr            = (uint64_t) address;
-  p.addr2           = 0;
-  p.condition_value = 0;
-
-- set a watchpoint which triggers on reads in the second watchpoint register
-
-  p.version         = PPC_DEBUG_CURRENT_VERSION;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_READ;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
-  p.addr            = (uint64_t) address;
-  p.addr2           = 0;
-  p.condition_value = 0;
-
-- set a watchpoint which triggers only with a specific value
-
-  p.version         = PPC_DEBUG_CURRENT_VERSION;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_READ;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
-  p.addr            = (uint64_t) address;
-  p.addr2           = 0;
-  p.condition_value = (uint64_t) condition;
-
-- set a ranged hardware breakpoint
-
-  p.version         = PPC_DEBUG_CURRENT_VERSION;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_EXECUTE;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
-  p.addr            = (uint64_t) begin_range;
-  p.addr2           = (uint64_t) end_range;
-  p.condition_value = 0;
-
-- set a watchpoint in server processors (BookS)
-
-  p.version         = 1;
-  p.trigger_type    = PPC_BREAKPOINT_TRIGGER_RW;
-  p.addr_mode       = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
-  or
-  p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
-
-  p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
-  p.addr            = (uint64_t) begin_range;
-  /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
-   * addr2 - addr <= 8 Bytes.
-   */
-  p.addr2           = (uint64_t) end_range;
-  p.condition_value = 0;
+- set a breakpoint in the first breakpoint register::
+
+    p.version         = PPC_DEBUG_CURRENT_VERSION;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
+    p.addr            = (uint64_t) address;
+    p.addr2           = 0;
+    p.condition_value = 0;
+
+- set a watchpoint which triggers on reads in the second watchpoint register::
+
+    p.version         = PPC_DEBUG_CURRENT_VERSION;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_READ;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
+    p.addr            = (uint64_t) address;
+    p.addr2           = 0;
+    p.condition_value = 0;
+
+- set a watchpoint which triggers only with a specific value::
+
+    p.version         = PPC_DEBUG_CURRENT_VERSION;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_READ;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_AND | PPC_BREAKPOINT_CONDITION_BE_ALL;
+    p.addr            = (uint64_t) address;
+    p.addr2           = 0;
+    p.condition_value = (uint64_t) condition;
+
+- set a ranged hardware breakpoint::
+
+    p.version         = PPC_DEBUG_CURRENT_VERSION;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_EXECUTE;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
+    p.addr            = (uint64_t) begin_range;
+    p.addr2           = (uint64_t) end_range;
+    p.condition_value = 0;
+
+- set a watchpoint in server processors (BookS)::
+
+    p.version         = 1;
+    p.trigger_type    = PPC_BREAKPOINT_TRIGGER_RW;
+    p.addr_mode       = PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE;
+    or
+    p.addr_mode       = PPC_BREAKPOINT_MODE_EXACT;
+
+    p.condition_mode  = PPC_BREAKPOINT_CONDITION_NONE;
+    p.addr            = (uint64_t) begin_range;
+    /* For PPC_BREAKPOINT_MODE_RANGE_INCLUSIVE addr2 needs to be specified, where
+     * addr2 - addr <= 8 Bytes.
+     */
+    p.addr2           = (uint64_t) end_range;
+    p.condition_value = 0;
 
 3. PTRACE_DELHWDEBUG
 
diff --git a/Documentation/powerpc/qe_firmware.txt b/Documentation/powerpc/qe_firmware.rst
similarity index 95%
rename from Documentation/powerpc/qe_firmware.txt
rename to Documentation/powerpc/qe_firmware.rst
index e7ac24aec4ff..42f5103140c9 100644
--- a/Documentation/powerpc/qe_firmware.txt
+++ b/Documentation/powerpc/qe_firmware.rst
@@ -1,23 +1,23 @@
-	   Freescale QUICC Engine Firmware Uploading
-	   -----------------------------------------
+=========================================
+Freescale QUICC Engine Firmware Uploading
+=========================================
 
 (c) 2007 Timur Tabi <timur at freescale.com>,
     Freescale Semiconductor
 
-Table of Contents
-=================
+.. Table of Contents
 
-  I - Software License for Firmware
+   I - Software License for Firmware
 
-  II - Microcode Availability
+   II - Microcode Availability
 
-  III - Description and Terminology
+   III - Description and Terminology
 
-  IV - Microcode Programming Details
+   IV - Microcode Programming Details
 
-  V - Firmware Structure Layout
+   V - Firmware Structure Layout
 
-  VI - Sample Code for Creating Firmware Files
+   VI - Sample Code for Creating Firmware Files
 
 Revision Information
 ====================
@@ -39,7 +39,7 @@ http://opensource.freescale.com.  For other firmware files, please contact
 your Freescale representative or your operating system vendor.
 
 III - Description and Terminology
-================================
+=================================
 
 In this document, the term 'microcode' refers to the sequence of 32-bit
 integers that compose the actual QE microcode.
@@ -89,7 +89,7 @@ being fixed in the RAM package utilizing they should be activated.  This data
 structure signals the microcode which of these virtual traps is active.
 
 This structure contains 6 words that the application should copy to some
-specific been defined.  This table describes the structure.
+specific been defined.  This table describes the structure::
 
 	---------------------------------------------------------------
 	| Offset in |                  | Destination Offset | Size of |
@@ -119,7 +119,7 @@ Extended Modes
 This is a double word bit array (64 bits) that defines special functionality
 which has an impact on the software drivers.  Each bit has its own impact
 and has special instructions for the s/w associated with it.  This structure is
-described in this table:
+described in this table::
 
 	-----------------------------------------------------------------------
 	| Bit #  |     Name     |   Description                               |
@@ -220,7 +220,8 @@ The 'model' field is a 16-bit number that matches the actual SOC. The
 'major' and 'minor' fields are the major and minor revision numbers,
 respectively, of the SOC.
 
-For example, to match the 8323, revision 1.0:
+For example, to match the 8323, revision 1.0::
+
      soc.model = 8323
      soc.major = 1
      soc.minor = 0
@@ -273,10 +274,10 @@ library and available to any driver that calles qe_get_firmware_info().
 	'reserved'.
 
 After the last microcode is a 32-bit CRC.  It can be calculated using
-this algorithm:
+this algorithm::
 
-u32 crc32(const u8 *p, unsigned int len)
-{
+  u32 crc32(const u8 *p, unsigned int len)
+  {
 	unsigned int i;
 	u32 crc = 0;
 
@@ -286,7 +287,7 @@ u32 crc32(const u8 *p, unsigned int len)
 		   crc = (crc >> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
 	}
 	return crc;
-}
+  }
 
 VI - Sample Code for Creating Firmware Files
 ============================================
diff --git a/Documentation/powerpc/syscall64-abi.txt b/Documentation/powerpc/syscall64-abi.rst
similarity index 82%
rename from Documentation/powerpc/syscall64-abi.txt
rename to Documentation/powerpc/syscall64-abi.rst
index fa716a0d88bd..e49f69f941b9 100644
--- a/Documentation/powerpc/syscall64-abi.txt
+++ b/Documentation/powerpc/syscall64-abi.rst
@@ -5,12 +5,12 @@ Power Architecture 64-bit Linux system call ABI
 syscall
 =======
 
-syscall calling sequence[*] matches the Power Architecture 64-bit ELF ABI
+syscall calling sequence\ [1]_ matches the Power Architecture 64-bit ELF ABI
 specification C function calling sequence, including register preservation
 rules, with the following differences.
 
-[*] Some syscalls (typically low-level management functions) may have
-    different calling sequences (e.g., rt_sigreturn).
+.. [1] Some syscalls (typically low-level management functions) may have
+       different calling sequences (e.g., rt_sigreturn).
 
 Parameters and return value
 ---------------------------
@@ -33,12 +33,14 @@ Register preservation rules
 Register preservation rules match the ELF ABI calling sequence with the
 following differences:
 
-r0:         Volatile.   (System call number.)
-r3:         Volatile.   (Parameter 1, and return value.)
-r4-r8:      Volatile.   (Parameters 2-6.)
-cr0:        Volatile    (cr0.SO is the return error condition)
-cr1, cr5-7: Nonvolatile.
-lr:         Nonvolatile.
+=========== ============= ========================================
+r0          Volatile      (System call number.)
+r3          Volatile      (Parameter 1, and return value.)
+r4-r8       Volatile      (Parameters 2-6.)
+cr0         Volatile      (cr0.SO is the return error condition)
+cr1, cr5-7  Nonvolatile
+lr          Nonvolatile
+=========== ============= ========================================
 
 All floating point and vector data registers as well as control and status
 registers are nonvolatile.
@@ -90,9 +92,12 @@ The vsyscall may or may not use the caller's stack frame save areas.
 
 Register preservation rules
 ---------------------------
-r0: Volatile.
-cr1, cr5-7: Volatile.
-lr: Volatile.
+
+=========== ========
+r0          Volatile
+cr1, cr5-7  Volatile
+lr          Volatile
+=========== ========
 
 Invocation
 ----------
diff --git a/Documentation/powerpc/transactional_memory.txt b/Documentation/powerpc/transactional_memory.rst
similarity index 93%
rename from Documentation/powerpc/transactional_memory.txt
rename to Documentation/powerpc/transactional_memory.rst
index 52c023e14f26..09955103acb4 100644
--- a/Documentation/powerpc/transactional_memory.txt
+++ b/Documentation/powerpc/transactional_memory.rst
@@ -1,3 +1,4 @@
+============================
 Transactional Memory support
 ============================
 
@@ -17,29 +18,29 @@ instructions are presented to delimit transactions; transactions are
 guaranteed to either complete atomically or roll back and undo any partial
 changes.
 
-A simple transaction looks like this:
+A simple transaction looks like this::
 
-begin_move_money:
-  tbegin
-  beq   abort_handler
+  begin_move_money:
+    tbegin
+    beq   abort_handler
 
-  ld    r4, SAVINGS_ACCT(r3)
-  ld    r5, CURRENT_ACCT(r3)
-  subi  r5, r5, 1
-  addi  r4, r4, 1
-  std   r4, SAVINGS_ACCT(r3)
-  std   r5, CURRENT_ACCT(r3)
+    ld    r4, SAVINGS_ACCT(r3)
+    ld    r5, CURRENT_ACCT(r3)
+    subi  r5, r5, 1
+    addi  r4, r4, 1
+    std   r4, SAVINGS_ACCT(r3)
+    std   r5, CURRENT_ACCT(r3)
 
-  tend
+    tend
 
-  b     continue
+    b     continue
 
-abort_handler:
-  ... test for odd failures ...
+  abort_handler:
+    ... test for odd failures ...
 
-  /* Retry the transaction if it failed because it conflicted with
-   * someone else: */
-  b     begin_move_money
+    /* Retry the transaction if it failed because it conflicted with
+     * someone else: */
+    b     begin_move_money
 
 
 The 'tbegin' instruction denotes the start point, and 'tend' the end point.
@@ -123,7 +124,7 @@ Transaction-aware signal handlers can read the transactional register state
 from the second ucontext.  This will be necessary for crash handlers to
 determine, for example, the address of the instruction causing the SIGSEGV.
 
-Example signal handler:
+Example signal handler::
 
     void crash_handler(int sig, siginfo_t *si, void *uc)
     {
@@ -133,9 +134,9 @@ Example signal handler:
       if (ucp_link) {
         u64 msr = ucp->uc_mcontext.regs->msr;
         /* May have transactional ucontext! */
-#ifndef __powerpc64__
+  #ifndef __powerpc64__
         msr |= ((u64)transactional_ucp->uc_mcontext.regs->msr) << 32;
-#endif
+  #endif
         if (MSR_TM_ACTIVE(msr)) {
            /* Yes, we crashed during a transaction.  Oops. */
    fprintf(stderr, "Transaction to be restarted at 0x%llx, but "
@@ -176,6 +177,7 @@ Failure cause codes used by kernel
 These are defined in <asm/reg.h>, and distinguish different reasons why the
 kernel aborted a transaction:
 
+ ====================== ================================
  TM_CAUSE_RESCHED       Thread was rescheduled.
  TM_CAUSE_TLBI          Software TLB invalid.
  TM_CAUSE_FAC_UNAV      FP/VEC/VSX unavailable trap.
@@ -184,6 +186,7 @@ kernel aborted a transaction:
  TM_CAUSE_MISC          Currently unused.
  TM_CAUSE_ALIGNMENT     Alignment fault.
  TM_CAUSE_EMULATE       Emulation that touched memory.
+ ====================== ================================
 
 These can be checked by the user program's abort handler as TEXASR[0:7].  If
 bit 7 is set, it indicates that the error is consider persistent.  For example
@@ -203,7 +206,7 @@ POWER9
 ======
 
 TM on POWER9 has issues with storing the complete register state. This
-is described in this commit:
+is described in this commit::
 
     commit 4bb3c7a0208fc13ca70598efd109901a7cd45ae7
     Author: Paul Mackerras <paulus@ozlabs.org>
diff --git a/MAINTAINERS b/MAINTAINERS
index 3d6cd6efb264..15b58d5947a3 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4469,7 +4469,7 @@ F:	arch/powerpc/platforms/powernv/pci-cxl.c
 F:	drivers/misc/cxl/
 F:	include/misc/cxl*
 F:	include/uapi/misc/cxl.h
-F:	Documentation/powerpc/cxl.txt
+F:	Documentation/powerpc/cxl.rst
 F:	Documentation/ABI/testing/sysfs-class-cxl
 
 CXLFLASH (IBM Coherent Accelerator Processor Interface CAPI Flash) SCSI DRIVER
@@ -4480,7 +4480,7 @@ L:	linux-scsi@vger.kernel.org
 S:	Supported
 F:	drivers/scsi/cxlflash/
 F:	include/uapi/scsi/cxlflash_ioctl.h
-F:	Documentation/powerpc/cxlflash.txt
+F:	Documentation/powerpc/cxlflash.rst
 
 CYBERPRO FB DRIVER
 M:	Russell King <linux@armlinux.org.uk>
@@ -12394,7 +12394,7 @@ F:	Documentation/PCI/pci-error-recovery.rst
 F:	drivers/pci/pcie/aer.c
 F:	drivers/pci/pcie/dpc.c
 F:	drivers/pci/pcie/err.c
-F:	Documentation/powerpc/eeh-pci-error-recovery.txt
+F:	Documentation/powerpc/eeh-pci-error-recovery.rst
 F:	arch/powerpc/kernel/eeh*.c
 F:	arch/powerpc/platforms/*/eeh*.c
 F:	arch/powerpc/include/*/eeh*.h
diff --git a/arch/powerpc/kernel/exceptions-64s.S b/arch/powerpc/kernel/exceptions-64s.S
index eee5bef736c8..6ba3cc2ef8ab 100644
--- a/arch/powerpc/kernel/exceptions-64s.S
+++ b/arch/powerpc/kernel/exceptions-64s.S
@@ -1531,7 +1531,7 @@ EXC_COMMON(trap_0b_common, 0xb00, unknown_exception)
  *
  * Call convention:
  *
- * syscall register convention is in Documentation/powerpc/syscall64-abi.txt
+ * syscall register convention is in Documentation/powerpc/syscall64-abi.rst
  *
  * For hypercalls, the register convention is as follows:
  * r0 volatile
diff --git a/drivers/soc/fsl/qe/qe.c b/drivers/soc/fsl/qe/qe.c
index 62c6ba17991a..c9519e62308c 100644
--- a/drivers/soc/fsl/qe/qe.c
+++ b/drivers/soc/fsl/qe/qe.c
@@ -419,7 +419,7 @@ static void qe_upload_microcode(const void *base,
 /*
  * Upload a microcode to the I-RAM at a specific address.
  *
- * See Documentation/powerpc/qe_firmware.txt for information on QE microcode
+ * See Documentation/powerpc/qe_firmware.rst for information on QE microcode
  * uploading.
  *
  * Currently, only version 1 is supported, so the 'version' field must be
diff --git a/drivers/tty/hvc/hvcs.c b/drivers/tty/hvc/hvcs.c
index cb4db1b3ca3c..5fb214e67d73 100644
--- a/drivers/tty/hvc/hvcs.c
+++ b/drivers/tty/hvc/hvcs.c
@@ -47,7 +47,7 @@
  * using the 2.6 Linux kernel kref construct.
  *
  * For direction on installation and usage of this driver please reference
- * Documentation/powerpc/hvcs.txt.
+ * Documentation/powerpc/hvcs.rst.
  */
 
 #include <linux/device.h>
diff --git a/include/soc/fsl/qe/qe.h b/include/soc/fsl/qe/qe.h
index 3f9d6b6a5691..c1036d16ed03 100644
--- a/include/soc/fsl/qe/qe.h
+++ b/include/soc/fsl/qe/qe.h
@@ -259,7 +259,7 @@ static inline int qe_alive_during_sleep(void)
 
 /* Structure that defines QE firmware binary files.
  *
- * See Documentation/powerpc/qe_firmware.txt for a description of these
+ * See Documentation/powerpc/qe_firmware.rst for a description of these
  * fields.
  */
 struct qe_firmware {
-- 
2.21.0


_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

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

* [PATCH v2 04/26] docs: ubifs-authentication.md: convert to ReST
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (6 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-doc, Rob Herring

The documentation standard is ReST and not markdown.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Rob Herring <robh@kernel.org>
---
 ...entication.md => ubifs-authentication.rst} | 70 ++++++++++++-------
 1 file changed, 44 insertions(+), 26 deletions(-)
 rename Documentation/filesystems/{ubifs-authentication.md => ubifs-authentication.rst} (95%)

diff --git a/Documentation/filesystems/ubifs-authentication.md b/Documentation/filesystems/ubifs-authentication.rst
similarity index 95%
rename from Documentation/filesystems/ubifs-authentication.md
rename to Documentation/filesystems/ubifs-authentication.rst
index 23e698167141..6a9584f6ff46 100644
--- a/Documentation/filesystems/ubifs-authentication.md
+++ b/Documentation/filesystems/ubifs-authentication.rst
@@ -1,8 +1,11 @@
-% UBIFS Authentication
-% sigma star gmbh
-% 2018
+:orphan:
 
-# Introduction
+.. UBIFS Authentication
+.. sigma star gmbh
+.. 2018
+
+Introduction
+============
 
 UBIFS utilizes the fscrypt framework to provide confidentiality for file
 contents and file names. This prevents attacks where an attacker is able to
@@ -33,7 +36,8 @@ existing features like key derivation can be utilized. It should however also
 be possible to use UBIFS authentication without using encryption.
 
 
-## MTD, UBI & UBIFS
+MTD, UBI & UBIFS
+----------------
 
 On Linux, the MTD (Memory Technology Devices) subsystem provides a uniform
 interface to access raw flash devices. One of the more prominent subsystems that
@@ -47,7 +51,7 @@ UBIFS is a filesystem for raw flash which operates on top of UBI. Thus, wear
 leveling and some flash specifics are left to UBI, while UBIFS focuses on
 scalability, performance and recoverability.
 
-
+::
 
 	+------------+ +*******+ +-----------+ +-----+
 	|            | * UBIFS * | UBI-BLOCK | | ... |
@@ -84,7 +88,8 @@ persisted onto the flash directly. More details on UBIFS can also be found in
 [UBIFS-WP].
 
 
-### UBIFS Index & Tree Node Cache
+UBIFS Index & Tree Node Cache
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Basic on-flash UBIFS entities are called *nodes*. UBIFS knows different types
 of nodes. Eg. data nodes (`struct ubifs_data_node`) which store chunks of file
@@ -118,17 +123,18 @@ on-flash filesystem structures like the index. On every commit, the TNC nodes
 marked as dirty are written to the flash to update the persisted index.
 
 
-### Journal
+Journal
+~~~~~~~
 
 To avoid wearing out the flash, the index is only persisted (*commited*) when
-certain conditions are met (eg. `fsync(2)`). The journal is used to record
+certain conditions are met (eg. ``fsync(2)``). The journal is used to record
 any changes (in form of inode nodes, data nodes etc.) between commits
 of the index. During mount, the journal is read from the flash and replayed
 onto the TNC (which will be created on-demand from the on-flash index).
 
 UBIFS reserves a bunch of LEBs just for the journal called *log area*. The
 amount of log area LEBs is configured on filesystem creation (using
-`mkfs.ubifs`) and stored in the superblock node. The log area contains only
+``mkfs.ubifs``) and stored in the superblock node. The log area contains only
 two types of nodes: *reference nodes* and *commit start nodes*. A commit start
 node is written whenever an index commit is performed. Reference nodes are
 written on every journal update. Each reference node points to the position of
@@ -152,6 +158,7 @@ done for the last referenced LEB of the journal. Only this can become corrupt
 because of a power cut. If the recovery fails, UBIFS will not mount. An error
 for every other LEB will directly cause UBIFS to fail the mount operation.
 
+::
 
        | ----    LOG AREA     ---- | ----------    MAIN AREA    ------------ |
 
@@ -172,10 +179,11 @@ for every other LEB will directly cause UBIFS to fail the mount operation.
                           containing their buds
 
 
-### LEB Property Tree/Table
+LEB Property Tree/Table
+~~~~~~~~~~~~~~~~~~~~~~~
 
 The LEB property tree is used to store per-LEB information. This includes the
-LEB type and amount of free and *dirty* (old, obsolete content) space [1] on
+LEB type and amount of free and *dirty* (old, obsolete content) space [1]_ on
 the LEB. The type is important, because UBIFS never mixes index nodes with data
 nodes on a single LEB and thus each LEB has a specific purpose. This again is
 useful for free space calculations. See [UBIFS-WP] for more details.
@@ -185,19 +193,21 @@ index. Due to its smaller size it is always written as one chunk on every
 commit. Thus, saving the LPT is an atomic operation.
 
 
-[1] Since LEBs can only be appended and never overwritten, there is a
-difference between free space ie. the remaining space left on the LEB to be
-written to without erasing it and previously written content that is obsolete
-but can't be overwritten without erasing the full LEB.
+.. [1] Since LEBs can only be appended and never overwritten, there is a
+   difference between free space ie. the remaining space left on the LEB to be
+   written to without erasing it and previously written content that is obsolete
+   but can't be overwritten without erasing the full LEB.
 
 
-# UBIFS Authentication
+UBIFS Authentication
+====================
 
 This chapter introduces UBIFS authentication which enables UBIFS to verify
 the authenticity and integrity of metadata and file contents stored on flash.
 
 
-## Threat Model
+Threat Model
+------------
 
 UBIFS authentication enables detection of offline data modification. While it
 does not prevent it, it enables (trusted) code to check the integrity and
@@ -224,7 +234,8 @@ Additional measures like secure boot and trusted boot have to be taken to
 ensure that only trusted code is executed on a device.
 
 
-## Authentication
+Authentication
+--------------
 
 To be able to fully trust data read from flash, all UBIFS data structures
 stored on flash are authenticated. That is:
@@ -236,7 +247,8 @@ stored on flash are authenticated. That is:
 - The LPT which stores UBI LEB metadata which UBIFS uses for free space accounting
 
 
-### Index Authentication
+Index Authentication
+~~~~~~~~~~~~~~~~~~~~
 
 Through UBIFS' concept of a wandering tree, it already takes care of only
 updating and persisting changed parts from leaf node up to the root node
@@ -260,6 +272,7 @@ include a hash. All other types of nodes will remain unchanged. This reduces
 the storage overhead which is precious for users of UBIFS (ie. embedded
 devices).
 
+::
 
                              +---------------+
                              |  Master Node  |
@@ -303,7 +316,8 @@ hashes to index nodes does not change this since each hash will be persisted
 atomically together with its respective node.
 
 
-### Journal Authentication
+Journal Authentication
+~~~~~~~~~~~~~~~~~~~~~~
 
 The journal is authenticated too. Since the journal is continuously written
 it is necessary to also add authentication information frequently to the
@@ -316,7 +330,7 @@ of the hash chain. That way a journal can be authenticated up to the last
 authentication node. The tail of the journal which may not have a authentication
 node cannot be authenticated and is skipped during journal replay.
 
-We get this picture for journal authentication:
+We get this picture for journal authentication::
 
     ,,,,,,,,
     ,......,...........................................
@@ -352,7 +366,8 @@ the superblock struct. The superblock node is stored in LEB 0 and is only
 modified on feature flag or similar changes, but never on file changes.
 
 
-### LPT Authentication
+LPT Authentication
+~~~~~~~~~~~~~~~~~~
 
 The location of the LPT root node on the flash is stored in the UBIFS master
 node. Since the LPT is written and read atomically on every commit, there is
@@ -363,7 +378,8 @@ be verified by verifying the authenticity of the master node and comparing the
 LTP hash stored there with the hash computed from the read on-flash LPT.
 
 
-## Key Management
+Key Management
+--------------
 
 For simplicity, UBIFS authentication uses a single key to compute the HMACs
 of superblock, master, commit start and reference nodes. This key has to be
@@ -399,7 +415,8 @@ approach is similar to the approach proposed for fscrypt encryption policy v2
 [FSCRYPT-POLICY2].
 
 
-# Future Extensions
+Future Extensions
+=================
 
 In certain cases where a vendor wants to provide an authenticated filesystem
 image to customers, it should be possible to do so without sharing the secret
@@ -411,7 +428,8 @@ to the way the IMA/EVM subsystem deals with such situations. The HMAC key
 will then have to be provided beforehand in the normal way.
 
 
-# References
+References
+==========
 
 [CRYPTSETUP2]        http://www.saout.de/pipermail/dm-crypt/2017-November/005745.html
 
-- 
2.21.0


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

* [PATCH v2 05/26] docs: writing-schema.md: convert from markdown to ReST
  2019-07-26 12:51 ` Mauro Carvalho Chehab
@ 2019-07-26 12:51   ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Rob Herring, Mark Rutland, devicetree,
	Rob Herring

The documentation standard is ReST and not markdown.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Rob Herring <robh@kernel.org>
---
 .../{writing-schema.md => writing-schema.rst} | 137 ++++++++++--------
 1 file changed, 80 insertions(+), 57 deletions(-)
 rename Documentation/devicetree/{writing-schema.md => writing-schema.rst} (48%)

diff --git a/Documentation/devicetree/writing-schema.md b/Documentation/devicetree/writing-schema.rst
similarity index 48%
rename from Documentation/devicetree/writing-schema.md
rename to Documentation/devicetree/writing-schema.rst
index dc032db36262..8f71d1e2ac52 100644
--- a/Documentation/devicetree/writing-schema.md
+++ b/Documentation/devicetree/writing-schema.rst
@@ -1,65 +1,81 @@
-# Writing DeviceTree Bindings in json-schema
+:orphan:
+
+Writing DeviceTree Bindings in json-schema
+==========================================
 
 Devicetree bindings are written using json-schema vocabulary. Schema files are
 written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
 considered more human readable and has some advantages such as allowing
 comments (Prefixed with '#').
 
-## Schema Contents
+Schema Contents
+---------------
 
 Each schema doc is a structured json-schema which is defined by a set of
 top-level properties. Generally, there is one binding defined per file. The
 top-level json-schema properties used are:
 
-- __$id__ - A json-schema unique identifier string. The string must be a valid
-URI typically containing the binding's filename and path. For DT schema, it must
-begin with "http://devicetree.org/schemas/". The URL is used in constructing
-references to other files specified in schema "$ref" properties. A $ref values
-with a leading '/' will have the hostname prepended. A $ref value a relative
-path or filename only will be prepended with the hostname and path components
-of the current schema file's '$id' value. A URL is used even for local files,
-but there may not actually be files present at those locations.
-
-- __$schema__ - Indicates the meta-schema the schema file adheres to.
-
-- __title__ - A one line description on the contents of the binding schema.
-
-- __maintainers__ - A DT specific property. Contains a list of email address(es)
-for maintainers of this binding.
-
-- __description__ - Optional. A multi-line text block containing any detailed
-information about this binding. It should contain things such as what the block
-or device does, standards the device conforms to, and links to datasheets for
-more information.
-
-- __select__ - Optional. A json-schema used to match nodes for applying the
-schema. By default without 'select', nodes are matched against their possible
-compatible string values or node name. Most bindings should not need select.
-
-- __allOf__ - Optional. A list of other schemas to include. This is used to
-include other schemas the binding conforms to. This may be schemas for a
-particular class of devices such as I2C or SPI controllers.
-
-- __properties__ - A set of sub-schema defining all the DT properties for the
-binding. The exact schema syntax depends on whether properties are known,
-common properties (e.g. 'interrupts') or are binding/vendor specific properties.
-
-  A property can also define a child DT node with child properties defined
+$id
+  A json-schema unique identifier string. The string must be a valid
+  URI typically containing the binding's filename and path. For DT schema, it must
+  begin with "http://devicetree.org/schemas/". The URL is used in constructing
+  references to other files specified in schema "$ref" properties. A $ref values
+  with a leading '/' will have the hostname prepended. A $ref value a relative
+  path or filename only will be prepended with the hostname and path components
+  of the current schema file's '$id' value. A URL is used even for local files,
+  but there may not actually be files present at those locations.
+
+$schema
+  Indicates the meta-schema the schema file adheres to.
+
+title
+  A one line description on the contents of the binding schema.
+
+maintainers
+  A DT specific property. Contains a list of email address(es)
+  for maintainers of this binding.
+
+description
+  Optional. A multi-line text block containing any detailed
+  information about this binding. It should contain things such as what the block
+  or device does, standards the device conforms to, and links to datasheets for
+  more information.
+
+select
+  Optional. A json-schema used to match nodes for applying the
+  schema. By default without 'select', nodes are matched against their possible
+  compatible string values or node name. Most bindings should not need select.
+
+ allOf
+  Optional. A list of other schemas to include. This is used to
+  include other schemas the binding conforms to. This may be schemas for a
+  particular class of devices such as I2C or SPI controllers.
+
+ properties
+  A set of sub-schema defining all the DT properties for the
+  binding. The exact schema syntax depends on whether properties are known,
+  common properties (e.g. 'interrupts') or are binding/vendor specific properties.
+
+A property can also define a child DT node with child properties defined
 under it.
 
-  For more details on properties sections, see 'Property Schema' section.
+For more details on properties sections, see 'Property Schema' section.
 
-- __patternProperties__ - Optional. Similar to 'properties', but names are regex.
+patternProperties
+  Optional. Similar to 'properties', but names are regex.
 
-- __required__ - A list of DT properties from the 'properties' section that
-must always be present.
+required
+  A list of DT properties from the 'properties' section that
+  must always be present.
 
-- __examples__ - Optional. A list of one or more DTS hunks implementing the
-binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
+examples
+  Optional. A list of one or more DTS hunks implementing the
+  binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
 
 Unless noted otherwise, all properties are required.
 
-## Property Schema
+Property Schema
+---------------
 
 The 'properties' section of the schema contains all the DT properties for a
 binding. Each property contains a set of constraints using json-schema
@@ -89,42 +105,49 @@ The YAML Devicetree format also makes all string values an array and scalar
 values a matrix (in order to define groupings) even when only a single value
 is present. Single entries in schemas are fixed up to match this encoding.
 
-## Testing
+Testing
+-------
 
-### Dependencies
+Dependencies
+~~~~~~~~~~~~
 
 The DT schema project must be installed in order to validate the DT schema
 binding documents and validate DTS files using the DT schema. The DT schema
-project can be installed with pip:
+project can be installed with pip::
 
-`pip3 install git+https://github.com/devicetree-org/dt-schema.git@master`
+    pip3 install git+https://github.com/devicetree-org/dt-schema.git@master
 
 dtc must also be built with YAML output support enabled. This requires that
 libyaml and its headers be installed on the host system.
 
-### Running checks
+Running checks
+~~~~~~~~~~~~~~
 
 The DT schema binding documents must be validated using the meta-schema (the
 schema for the schema) to ensure they are both valid json-schema and valid
 binding schema. All of the DT binding documents can be validated using the
-`dt_binding_check` target:
+``dt_binding_check`` target::
 
-`make dt_binding_check`
+    make dt_binding_check
 
-In order to perform validation of DT source files, use the `dtbs_check` target:
+In order to perform validation of DT source files, use the `dtbs_check` target::
 
-`make dtbs_check`
+    make dtbs_check
 
 This will first run the `dt_binding_check` which generates the processed schema.
 
 It is also possible to run checks with a single schema file by setting the
-'DT_SCHEMA_FILES' variable to a specific schema file.
+``DT_SCHEMA_FILES`` variable to a specific schema file.
 
-`make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml`
+::
 
+    make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml
 
-## json-schema Resources
 
-[JSON-Schema Specifications](http://json-schema.org/)
+json-schema Resources
+---------------------
 
-[Using JSON Schema Book](http://usingjsonschema.com/)
+
+`JSON-Schema Specifications <http://json-schema.org/>`_
+
+`Using JSON Schema Book <http://usingjsonschema.com/>`_
-- 
2.21.0

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

* [PATCH v2 05/26] docs: writing-schema.md: convert from markdown to ReST
@ 2019-07-26 12:51   ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Rob Herring, Mark Rutland, devicetree,
	Rob Herring

The documentation standard is ReST and not markdown.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Rob Herring <robh@kernel.org>
---
 .../{writing-schema.md => writing-schema.rst} | 137 ++++++++++--------
 1 file changed, 80 insertions(+), 57 deletions(-)
 rename Documentation/devicetree/{writing-schema.md => writing-schema.rst} (48%)

diff --git a/Documentation/devicetree/writing-schema.md b/Documentation/devicetree/writing-schema.rst
similarity index 48%
rename from Documentation/devicetree/writing-schema.md
rename to Documentation/devicetree/writing-schema.rst
index dc032db36262..8f71d1e2ac52 100644
--- a/Documentation/devicetree/writing-schema.md
+++ b/Documentation/devicetree/writing-schema.rst
@@ -1,65 +1,81 @@
-# Writing DeviceTree Bindings in json-schema
+:orphan:
+
+Writing DeviceTree Bindings in json-schema
+==========================================
 
 Devicetree bindings are written using json-schema vocabulary. Schema files are
 written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
 considered more human readable and has some advantages such as allowing
 comments (Prefixed with '#').
 
-## Schema Contents
+Schema Contents
+---------------
 
 Each schema doc is a structured json-schema which is defined by a set of
 top-level properties. Generally, there is one binding defined per file. The
 top-level json-schema properties used are:
 
-- __$id__ - A json-schema unique identifier string. The string must be a valid
-URI typically containing the binding's filename and path. For DT schema, it must
-begin with "http://devicetree.org/schemas/". The URL is used in constructing
-references to other files specified in schema "$ref" properties. A $ref values
-with a leading '/' will have the hostname prepended. A $ref value a relative
-path or filename only will be prepended with the hostname and path components
-of the current schema file's '$id' value. A URL is used even for local files,
-but there may not actually be files present at those locations.
-
-- __$schema__ - Indicates the meta-schema the schema file adheres to.
-
-- __title__ - A one line description on the contents of the binding schema.
-
-- __maintainers__ - A DT specific property. Contains a list of email address(es)
-for maintainers of this binding.
-
-- __description__ - Optional. A multi-line text block containing any detailed
-information about this binding. It should contain things such as what the block
-or device does, standards the device conforms to, and links to datasheets for
-more information.
-
-- __select__ - Optional. A json-schema used to match nodes for applying the
-schema. By default without 'select', nodes are matched against their possible
-compatible string values or node name. Most bindings should not need select.
-
-- __allOf__ - Optional. A list of other schemas to include. This is used to
-include other schemas the binding conforms to. This may be schemas for a
-particular class of devices such as I2C or SPI controllers.
-
-- __properties__ - A set of sub-schema defining all the DT properties for the
-binding. The exact schema syntax depends on whether properties are known,
-common properties (e.g. 'interrupts') or are binding/vendor specific properties.
-
-  A property can also define a child DT node with child properties defined
+$id
+  A json-schema unique identifier string. The string must be a valid
+  URI typically containing the binding's filename and path. For DT schema, it must
+  begin with "http://devicetree.org/schemas/". The URL is used in constructing
+  references to other files specified in schema "$ref" properties. A $ref values
+  with a leading '/' will have the hostname prepended. A $ref value a relative
+  path or filename only will be prepended with the hostname and path components
+  of the current schema file's '$id' value. A URL is used even for local files,
+  but there may not actually be files present at those locations.
+
+$schema
+  Indicates the meta-schema the schema file adheres to.
+
+title
+  A one line description on the contents of the binding schema.
+
+maintainers
+  A DT specific property. Contains a list of email address(es)
+  for maintainers of this binding.
+
+description
+  Optional. A multi-line text block containing any detailed
+  information about this binding. It should contain things such as what the block
+  or device does, standards the device conforms to, and links to datasheets for
+  more information.
+
+select
+  Optional. A json-schema used to match nodes for applying the
+  schema. By default without 'select', nodes are matched against their possible
+  compatible string values or node name. Most bindings should not need select.
+
+ allOf
+  Optional. A list of other schemas to include. This is used to
+  include other schemas the binding conforms to. This may be schemas for a
+  particular class of devices such as I2C or SPI controllers.
+
+ properties
+  A set of sub-schema defining all the DT properties for the
+  binding. The exact schema syntax depends on whether properties are known,
+  common properties (e.g. 'interrupts') or are binding/vendor specific properties.
+
+A property can also define a child DT node with child properties defined
 under it.
 
-  For more details on properties sections, see 'Property Schema' section.
+For more details on properties sections, see 'Property Schema' section.
 
-- __patternProperties__ - Optional. Similar to 'properties', but names are regex.
+patternProperties
+  Optional. Similar to 'properties', but names are regex.
 
-- __required__ - A list of DT properties from the 'properties' section that
-must always be present.
+required
+  A list of DT properties from the 'properties' section that
+  must always be present.
 
-- __examples__ - Optional. A list of one or more DTS hunks implementing the
-binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
+examples
+  Optional. A list of one or more DTS hunks implementing the
+  binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
 
 Unless noted otherwise, all properties are required.
 
-## Property Schema
+Property Schema
+---------------
 
 The 'properties' section of the schema contains all the DT properties for a
 binding. Each property contains a set of constraints using json-schema
@@ -89,42 +105,49 @@ The YAML Devicetree format also makes all string values an array and scalar
 values a matrix (in order to define groupings) even when only a single value
 is present. Single entries in schemas are fixed up to match this encoding.
 
-## Testing
+Testing
+-------
 
-### Dependencies
+Dependencies
+~~~~~~~~~~~~
 
 The DT schema project must be installed in order to validate the DT schema
 binding documents and validate DTS files using the DT schema. The DT schema
-project can be installed with pip:
+project can be installed with pip::
 
-`pip3 install git+https://github.com/devicetree-org/dt-schema.git@master`
+    pip3 install git+https://github.com/devicetree-org/dt-schema.git@master
 
 dtc must also be built with YAML output support enabled. This requires that
 libyaml and its headers be installed on the host system.
 
-### Running checks
+Running checks
+~~~~~~~~~~~~~~
 
 The DT schema binding documents must be validated using the meta-schema (the
 schema for the schema) to ensure they are both valid json-schema and valid
 binding schema. All of the DT binding documents can be validated using the
-`dt_binding_check` target:
+``dt_binding_check`` target::
 
-`make dt_binding_check`
+    make dt_binding_check
 
-In order to perform validation of DT source files, use the `dtbs_check` target:
+In order to perform validation of DT source files, use the `dtbs_check` target::
 
-`make dtbs_check`
+    make dtbs_check
 
 This will first run the `dt_binding_check` which generates the processed schema.
 
 It is also possible to run checks with a single schema file by setting the
-'DT_SCHEMA_FILES' variable to a specific schema file.
+``DT_SCHEMA_FILES`` variable to a specific schema file.
 
-`make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml`
+::
 
+    make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml
 
-## json-schema Resources
 
-[JSON-Schema Specifications](http://json-schema.org/)
+json-schema Resources
+---------------------
 
-[Using JSON Schema Book](http://usingjsonschema.com/)
+
+`JSON-Schema Specifications <http://json-schema.org/>`_
+
+`Using JSON Schema Book <http://usingjsonschema.com/>`_
-- 
2.21.0


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

* [PATCH v2 06/26] docs: i2c: convert to ReST and add to driver-api bookset
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (8 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Peter Rosin, Rob Herring, Mark Rutland,
	Jonathan Corbet, Jean Delvare, Guenter Roeck, Andreas Werner,
	Wolfram Sang, Rudolf Marek, Seth Heasley, Neil Horman,
	Vadim Pasternak, Michael Shych, Ajay Gupta, Peter Korsgaard,
	Andrew Lunn, Jim Cromie, Mark Brown, Jonathan Cameron,
	Hartmut Knaack, Lars-Peter Clausen, Peter Meerwald-Stadler,
	Alessandro Zummo, Alexandre Belloni, linux-i2c, devicetree,
	linux-doc, linux-hwmon, linux-spi, linux-iio, linux-rtc,
	Jonathan Cameron

Convert each file at I2C subsystem, renaming them to .rst and
adding to the driver-api book.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Wolfram Sang <wsa@the-dreams.de>
Acked-by: Alexandre Belloni <alexandre.belloni@bootlin.com>
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com>
---
 .../devicetree/bindings/i2c/i2c-mux-gpmux.txt |   2 +-
 Documentation/driver-api/ipmb.rst             |   2 +-
 Documentation/hwmon/adm1021.rst               |   2 +-
 Documentation/hwmon/adm1275.rst               |   2 +-
 Documentation/hwmon/hih6130.rst               |   2 +-
 Documentation/hwmon/ibm-cffps.rst             |   2 +-
 Documentation/hwmon/lm25066.rst               |   2 +-
 Documentation/hwmon/max16064.rst              |   2 +-
 Documentation/hwmon/max16065.rst              |   2 +-
 Documentation/hwmon/max20751.rst              |   2 +-
 Documentation/hwmon/max34440.rst              |   2 +-
 Documentation/hwmon/max6650.rst               |   2 +-
 Documentation/hwmon/max8688.rst               |   2 +-
 Documentation/hwmon/menf21bmc.rst             |   2 +-
 Documentation/hwmon/pcf8591.rst               |   2 +-
 Documentation/hwmon/sht3x.rst                 |   2 +-
 Documentation/hwmon/shtc1.rst                 |   2 +-
 Documentation/hwmon/tmp103.rst                |   2 +-
 Documentation/hwmon/tps40422.rst              |   2 +-
 Documentation/hwmon/ucd9000.rst               |   2 +-
 Documentation/hwmon/ucd9200.rst               |   2 +-
 Documentation/hwmon/via686a.rst               |   2 +-
 Documentation/hwmon/zl6100.rst                |   2 +-
 .../busses/{i2c-ali1535 => i2c-ali1535.rst}   |  13 +-
 .../busses/{i2c-ali1563 => i2c-ali1563.rst}   |   3 +
 .../busses/{i2c-ali15x3 => i2c-ali15x3.rst}   |  64 +++---
 .../busses/{i2c-amd-mp2 => i2c-amd-mp2.rst}   |  14 +-
 .../i2c/busses/{i2c-amd756 => i2c-amd756.rst} |   8 +-
 .../busses/{i2c-amd8111 => i2c-amd8111.rst}   |  14 +-
 .../{i2c-diolan-u2c => i2c-diolan-u2c.rst}    |   3 +
 .../i2c/busses/{i2c-i801 => i2c-i801.rst}     |  33 +--
 .../i2c/busses/{i2c-ismt => i2c-ismt.rst}     |  20 +-
 .../busses/{i2c-mlxcpld => i2c-mlxcpld.rst}   |   6 +
 .../busses/{i2c-nforce2 => i2c-nforce2.rst}   |  33 +--
 .../{i2c-nvidia-gpu => i2c-nvidia-gpu.rst}    |   6 +-
 .../i2c/busses/{i2c-ocores => i2c-ocores.rst} |  22 +-
 ...2c-parport-light => i2c-parport-light.rst} |   8 +-
 .../busses/{i2c-parport => i2c-parport.rst}   | 164 +++++++-------
 .../busses/{i2c-pca-isa => i2c-pca-isa.rst}   |   9 +-
 .../i2c/busses/{i2c-piix4 => i2c-piix4.rst}   |  18 +-
 .../busses/{i2c-sis5595 => i2c-sis5595.rst}   |  19 +-
 .../i2c/busses/{i2c-sis630 => i2c-sis630.rst} |  39 ++--
 .../i2c/busses/{i2c-sis96x => i2c-sis96x.rst} |  31 ++-
 .../busses/{i2c-taos-evm => i2c-taos-evm.rst} |   8 +-
 .../i2c/busses/{i2c-via => i2c-via.rst}       |  28 ++-
 .../i2c/busses/{i2c-viapro => i2c-viapro.rst} |  12 +-
 Documentation/i2c/busses/index.rst            |  33 +++
 .../i2c/busses/{scx200_acb => scx200_acb.rst} |   9 +-
 .../i2c/{dev-interface => dev-interface.rst}  |  94 ++++----
 ...-considerations => dma-considerations.rst} |   0
 .../i2c/{fault-codes => fault-codes.rst}      |   5 +-
 .../i2c/{functionality => functionality.rst}  |  22 +-
 ...ult-injection => gpio-fault-injection.rst} |  12 +-
 .../i2c/{i2c-protocol => i2c-protocol.rst}    |  28 ++-
 Documentation/i2c/{i2c-stub => i2c-stub.rst}  |  20 +-
 .../i2c/{i2c-topology => i2c-topology.rst}    |  68 +++---
 Documentation/i2c/index.rst                   |  37 ++++
 ...ting-devices => instantiating-devices.rst} |  45 ++--
 .../muxes/{i2c-mux-gpio => i2c-mux-gpio.rst}  |  26 +--
 ...e-parameters => old-module-parameters.rst} |  27 ++-
 ...eprom-backend => slave-eeprom-backend.rst} |   4 +-
 .../{slave-interface => slave-interface.rst}  |  33 +--
 .../{smbus-protocol => smbus-protocol.rst}    |  86 +++++---
 Documentation/i2c/{summary => summary.rst}    |   6 +-
 ...en-bit-addresses => ten-bit-addresses.rst} |   5 +
 ...pgrading-clients => upgrading-clients.rst} | 204 +++++++++---------
 .../{writing-clients => writing-clients.rst}  |  94 ++++----
 Documentation/index.rst                       |   1 +
 Documentation/spi/spi-sc18is602               |   2 +-
 MAINTAINERS                                   |  48 ++---
 drivers/hwmon/atxp1.c                         |   2 +-
 drivers/hwmon/smm665.c                        |   2 +-
 drivers/i2c/Kconfig                           |   4 +-
 drivers/i2c/busses/Kconfig                    |   2 +-
 drivers/i2c/busses/i2c-i801.c                 |   2 +-
 drivers/i2c/busses/i2c-taos-evm.c             |   2 +-
 drivers/i2c/i2c-core-base.c                   |   4 +-
 drivers/iio/dummy/iio_simple_dummy.c          |   2 +-
 drivers/rtc/rtc-ds1374.c                      |   2 +-
 include/linux/i2c.h                           |   2 +-
 80 files changed, 930 insertions(+), 624 deletions(-)
 rename Documentation/i2c/busses/{i2c-ali1535 => i2c-ali1535.rst} (82%)
 rename Documentation/i2c/busses/{i2c-ali1563 => i2c-ali1563.rst} (93%)
 rename Documentation/i2c/busses/{i2c-ali15x3 => i2c-ali15x3.rst} (72%)
 rename Documentation/i2c/busses/{i2c-amd-mp2 => i2c-amd-mp2.rst} (42%)
 rename Documentation/i2c/busses/{i2c-amd756 => i2c-amd756.rst} (79%)
 rename Documentation/i2c/busses/{i2c-amd8111 => i2c-amd8111.rst} (66%)
 rename Documentation/i2c/busses/{i2c-diolan-u2c => i2c-diolan-u2c.rst} (91%)
 rename Documentation/i2c/busses/{i2c-i801 => i2c-i801.rst} (89%)
 rename Documentation/i2c/busses/{i2c-ismt => i2c-ismt.rst} (81%)
 rename Documentation/i2c/busses/{i2c-mlxcpld => i2c-mlxcpld.rst} (88%)
 rename Documentation/i2c/busses/{i2c-nforce2 => i2c-nforce2.rst} (58%)
 rename Documentation/i2c/busses/{i2c-nvidia-gpu => i2c-nvidia-gpu.rst} (63%)
 rename Documentation/i2c/busses/{i2c-ocores => i2c-ocores.rst} (82%)
 rename Documentation/i2c/busses/{i2c-parport-light => i2c-parport-light.rst} (91%)
 rename Documentation/i2c/busses/{i2c-parport => i2c-parport.rst} (49%)
 rename Documentation/i2c/busses/{i2c-pca-isa => i2c-pca-isa.rst} (72%)
 rename Documentation/i2c/busses/{i2c-piix4 => i2c-piix4.rst} (92%)
 rename Documentation/i2c/busses/{i2c-sis5595 => i2c-sis5595.rst} (74%)
 rename Documentation/i2c/busses/{i2c-sis630 => i2c-sis630.rst} (37%)
 rename Documentation/i2c/busses/{i2c-sis96x => i2c-sis96x.rst} (74%)
 rename Documentation/i2c/busses/{i2c-taos-evm => i2c-taos-evm.rst} (91%)
 rename Documentation/i2c/busses/{i2c-via => i2c-via.rst} (54%)
 rename Documentation/i2c/busses/{i2c-viapro => i2c-viapro.rst} (87%)
 create mode 100644 Documentation/i2c/busses/index.rst
 rename Documentation/i2c/busses/{scx200_acb => scx200_acb.rst} (86%)
 rename Documentation/i2c/{dev-interface => dev-interface.rst} (71%)
 rename Documentation/i2c/{DMA-considerations => dma-considerations.rst} (100%)
 rename Documentation/i2c/{fault-codes => fault-codes.rst} (98%)
 rename Documentation/i2c/{functionality => functionality.rst} (91%)
 rename Documentation/i2c/{gpio-fault-injection => gpio-fault-injection.rst} (97%)
 rename Documentation/i2c/{i2c-protocol => i2c-protocol.rst} (83%)
 rename Documentation/i2c/{i2c-stub => i2c-stub.rst} (93%)
 rename Documentation/i2c/{i2c-topology => i2c-topology.rst} (89%)
 create mode 100644 Documentation/i2c/index.rst
 rename Documentation/i2c/{instantiating-devices => instantiating-devices.rst} (93%)
 rename Documentation/i2c/muxes/{i2c-mux-gpio => i2c-mux-gpio.rst} (85%)
 rename Documentation/i2c/{old-module-parameters => old-module-parameters.rst} (75%)
 rename Documentation/i2c/{slave-eeprom-backend => slave-eeprom-backend.rst} (90%)
 rename Documentation/i2c/{slave-interface => slave-interface.rst} (94%)
 rename Documentation/i2c/{smbus-protocol => smbus-protocol.rst} (82%)
 rename Documentation/i2c/{summary => summary.rst} (96%)
 rename Documentation/i2c/{ten-bit-addresses => ten-bit-addresses.rst} (95%)
 rename Documentation/i2c/{upgrading-clients => upgrading-clients.rst} (54%)
 rename Documentation/i2c/{writing-clients => writing-clients.rst} (91%)

diff --git a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
index 2907dab56298..8b444b94e92f 100644
--- a/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
+++ b/Documentation/devicetree/bindings/i2c/i2c-mux-gpmux.txt
@@ -42,7 +42,7 @@ Optional properties:
   This means that no unrelated I2C transactions are allowed on the parent I2C
   adapter for the complete multiplexed I2C transaction.
   The properties of mux-locked and parent-locked multiplexers are discussed
-  in more detail in Documentation/i2c/i2c-topology.
+  in more detail in Documentation/i2c/i2c-topology.rst.
 
 For each i2c child node, an I2C child bus will be created. They will
 be numbered based on their order in the device tree.
diff --git a/Documentation/driver-api/ipmb.rst b/Documentation/driver-api/ipmb.rst
index 7e2265144157..3ec3baed84c4 100644
--- a/Documentation/driver-api/ipmb.rst
+++ b/Documentation/driver-api/ipmb.rst
@@ -83,7 +83,7 @@ Instantiate the device
 ----------------------
 
 After loading the driver, you can instantiate the device as
-described in 'Documentation/i2c/instantiating-devices'.
+described in 'Documentation/i2c/instantiating-devices.rst'.
 If you have multiple BMCs, each connected to your Satellite MC via
 a different I2C bus, you can instantiate a device for each of
 those BMCs.
diff --git a/Documentation/hwmon/adm1021.rst b/Documentation/hwmon/adm1021.rst
index 6cbb0f75fe00..116fb2019956 100644
--- a/Documentation/hwmon/adm1021.rst
+++ b/Documentation/hwmon/adm1021.rst
@@ -142,7 +142,7 @@ loading the adm1021 module, then things are good.
 If nothing happens when loading the adm1021 module, and you are certain
 that your specific Xeon processor model includes compatible sensors, you
 will have to explicitly instantiate the sensor chips from user-space. See
-method 4 in Documentation/i2c/instantiating-devices. Possible slave
+method 4 in Documentation/i2c/instantiating-devices.rst. Possible slave
 addresses are 0x18, 0x1a, 0x29, 0x2b, 0x4c, or 0x4e. It is likely that
 only temp2 will be correct and temp1 will have to be ignored.
 
diff --git a/Documentation/hwmon/adm1275.rst b/Documentation/hwmon/adm1275.rst
index 9a1913e5b4d9..49966ed70ec6 100644
--- a/Documentation/hwmon/adm1275.rst
+++ b/Documentation/hwmon/adm1275.rst
@@ -75,7 +75,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 The ADM1075, unlike many other PMBus devices, does not support internal voltage
diff --git a/Documentation/hwmon/hih6130.rst b/Documentation/hwmon/hih6130.rst
index 649bd4be4fc2..e95d373eb693 100644
--- a/Documentation/hwmon/hih6130.rst
+++ b/Documentation/hwmon/hih6130.rst
@@ -27,7 +27,7 @@ The devices communicate with the I2C protocol. All sensors are set to the same
 I2C address 0x27 by default, so an entry with I2C_BOARD_INFO("hih6130", 0x27)
 can be used in the board setup code.
 
-Please see Documentation/i2c/instantiating-devices for details on how to
+Please see Documentation/i2c/instantiating-devices.rst for details on how to
 instantiate I2C devices.
 
 sysfs-Interface
diff --git a/Documentation/hwmon/ibm-cffps.rst b/Documentation/hwmon/ibm-cffps.rst
index 52e74e39463a..ef8f3f806968 100644
--- a/Documentation/hwmon/ibm-cffps.rst
+++ b/Documentation/hwmon/ibm-cffps.rst
@@ -17,7 +17,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 Sysfs entries
diff --git a/Documentation/hwmon/lm25066.rst b/Documentation/hwmon/lm25066.rst
index da15e3094c8c..30e6e77fb3c8 100644
--- a/Documentation/hwmon/lm25066.rst
+++ b/Documentation/hwmon/lm25066.rst
@@ -76,7 +76,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 
diff --git a/Documentation/hwmon/max16064.rst b/Documentation/hwmon/max16064.rst
index 6d5e9538991f..c06249292557 100644
--- a/Documentation/hwmon/max16064.rst
+++ b/Documentation/hwmon/max16064.rst
@@ -28,7 +28,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 
diff --git a/Documentation/hwmon/max16065.rst b/Documentation/hwmon/max16065.rst
index fa5c852a178c..45f69f334f25 100644
--- a/Documentation/hwmon/max16065.rst
+++ b/Documentation/hwmon/max16065.rst
@@ -79,7 +79,7 @@ Usage Notes
 
 This driver does not probe for devices, since there is no register which
 can be safely used to identify the chip. You will have to instantiate
-the devices explicitly. Please see Documentation/i2c/instantiating-devices for
+the devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 WARNING: Do not access chip registers using the i2cdump command, and do not use
diff --git a/Documentation/hwmon/max20751.rst b/Documentation/hwmon/max20751.rst
index aa4469be6674..fe701e07eaf5 100644
--- a/Documentation/hwmon/max20751.rst
+++ b/Documentation/hwmon/max20751.rst
@@ -30,7 +30,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 
diff --git a/Documentation/hwmon/max34440.rst b/Documentation/hwmon/max34440.rst
index 939138e12b02..5744df100a5d 100644
--- a/Documentation/hwmon/max34440.rst
+++ b/Documentation/hwmon/max34440.rst
@@ -83,7 +83,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 For MAX34446, the value of the currX_crit attribute determines if current or
diff --git a/Documentation/hwmon/max6650.rst b/Documentation/hwmon/max6650.rst
index 253482add082..7952b6ecaa2d 100644
--- a/Documentation/hwmon/max6650.rst
+++ b/Documentation/hwmon/max6650.rst
@@ -55,7 +55,7 @@ Usage notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 Module parameters
diff --git a/Documentation/hwmon/max8688.rst b/Documentation/hwmon/max8688.rst
index 009487759c61..71e7f2cbe2e2 100644
--- a/Documentation/hwmon/max8688.rst
+++ b/Documentation/hwmon/max8688.rst
@@ -28,7 +28,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 
diff --git a/Documentation/hwmon/menf21bmc.rst b/Documentation/hwmon/menf21bmc.rst
index 1f0c6b2235ab..978691d5956d 100644
--- a/Documentation/hwmon/menf21bmc.rst
+++ b/Documentation/hwmon/menf21bmc.rst
@@ -28,7 +28,7 @@ Usage Notes
 This driver is part of the MFD driver named "menf21bmc" and does
 not auto-detect devices.
 You will have to instantiate the MFD driver explicitly.
-Please see Documentation/i2c/instantiating-devices for
+Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 Sysfs entries
diff --git a/Documentation/hwmon/pcf8591.rst b/Documentation/hwmon/pcf8591.rst
index e98bd542a441..5c4e85f53177 100644
--- a/Documentation/hwmon/pcf8591.rst
+++ b/Documentation/hwmon/pcf8591.rst
@@ -68,7 +68,7 @@ Accessing PCF8591 via /sys interface
 The PCF8591 is plainly impossible to detect! Thus the driver won't even
 try. You have to explicitly instantiate the device at the relevant
 address (in the interval [0x48..0x4f]) either through platform data, or
-using the sysfs interface. See Documentation/i2c/instantiating-devices
+using the sysfs interface. See Documentation/i2c/instantiating-devices.rst
 for details.
 
 Directories are being created for each instantiated PCF8591:
diff --git a/Documentation/hwmon/sht3x.rst b/Documentation/hwmon/sht3x.rst
index 978a7117e4b2..95a850d5b2c1 100644
--- a/Documentation/hwmon/sht3x.rst
+++ b/Documentation/hwmon/sht3x.rst
@@ -26,7 +26,7 @@ scaled by 1000, i.e. the value for 31.5 degrees celsius is 31500.
 
 The device communicates with the I2C protocol. Sensors can have the I2C
 addresses 0x44 or 0x45, depending on the wiring. See
-Documentation/i2c/instantiating-devices for methods to instantiate the device.
+Documentation/i2c/instantiating-devices.rst for methods to instantiate the device.
 
 There are two options configurable by means of sht3x_platform_data:
 
diff --git a/Documentation/hwmon/shtc1.rst b/Documentation/hwmon/shtc1.rst
index aa116332ba26..70c1192bbd8c 100644
--- a/Documentation/hwmon/shtc1.rst
+++ b/Documentation/hwmon/shtc1.rst
@@ -36,7 +36,7 @@ humidity is expressed as a percentage. Driver can be used as well for SHTW1
 chip, which has the same electrical interface.
 
 The device communicates with the I2C protocol. All sensors are set to I2C
-address 0x70. See Documentation/i2c/instantiating-devices for methods to
+address 0x70. See Documentation/i2c/instantiating-devices.rst for methods to
 instantiate the device.
 
 There are two options configurable by means of shtc1_platform_data:
diff --git a/Documentation/hwmon/tmp103.rst b/Documentation/hwmon/tmp103.rst
index 15d25806d585..205de6148fcb 100644
--- a/Documentation/hwmon/tmp103.rst
+++ b/Documentation/hwmon/tmp103.rst
@@ -30,4 +30,4 @@ The driver provides the common sysfs-interface for temperatures (see
 Documentation/hwmon/sysfs-interface.rst under Temperatures).
 
 Please refer how to instantiate this driver:
-Documentation/i2c/instantiating-devices
+Documentation/i2c/instantiating-devices.rst
diff --git a/Documentation/hwmon/tps40422.rst b/Documentation/hwmon/tps40422.rst
index b691e30479dd..8fe3e1c3572e 100644
--- a/Documentation/hwmon/tps40422.rst
+++ b/Documentation/hwmon/tps40422.rst
@@ -28,7 +28,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 
diff --git a/Documentation/hwmon/ucd9000.rst b/Documentation/hwmon/ucd9000.rst
index ebc4f2b3bfea..746f21fcb48c 100644
--- a/Documentation/hwmon/ucd9000.rst
+++ b/Documentation/hwmon/ucd9000.rst
@@ -64,7 +64,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 
diff --git a/Documentation/hwmon/ucd9200.rst b/Documentation/hwmon/ucd9200.rst
index b819dfd75f71..4f0e7c3ca6f4 100644
--- a/Documentation/hwmon/ucd9200.rst
+++ b/Documentation/hwmon/ucd9200.rst
@@ -40,7 +40,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 
diff --git a/Documentation/hwmon/via686a.rst b/Documentation/hwmon/via686a.rst
index a343c35df740..7ab9ddebcf79 100644
--- a/Documentation/hwmon/via686a.rst
+++ b/Documentation/hwmon/via686a.rst
@@ -40,7 +40,7 @@ all as a 686A.
 
 The Via 686a southbridge has integrated hardware monitor functionality.
 It also has an I2C bus, but this driver only supports the hardware monitor.
-For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro>
+For the I2C bus driver, see <file:Documentation/i2c/busses/i2c-viapro.rst>
 
 The Via 686a implements three temperature sensors, two fan rotation speed
 sensors, five voltage sensors and alarms.
diff --git a/Documentation/hwmon/zl6100.rst b/Documentation/hwmon/zl6100.rst
index 41513bb7fe51..968aff10ce0a 100644
--- a/Documentation/hwmon/zl6100.rst
+++ b/Documentation/hwmon/zl6100.rst
@@ -121,7 +121,7 @@ Usage Notes
 -----------
 
 This driver does not auto-detect devices. You will have to instantiate the
-devices explicitly. Please see Documentation/i2c/instantiating-devices for
+devices explicitly. Please see Documentation/i2c/instantiating-devices.rst for
 details.
 
 .. warning::
diff --git a/Documentation/i2c/busses/i2c-ali1535 b/Documentation/i2c/busses/i2c-ali1535.rst
similarity index 82%
rename from Documentation/i2c/busses/i2c-ali1535
rename to Documentation/i2c/busses/i2c-ali1535.rst
index 5d46342e486a..6941064730dc 100644
--- a/Documentation/i2c/busses/i2c-ali1535
+++ b/Documentation/i2c/busses/i2c-ali1535.rst
@@ -1,16 +1,19 @@
+=========================
 Kernel driver i2c-ali1535
+=========================
 
 Supported adapters:
   * Acer Labs, Inc. ALI 1535 (south bridge)
+
     Datasheet: Now under NDA
 	http://www.ali.com.tw/
 
 Authors:
-	Frodo Looijaard <frodol@dds.nl>,
-	Philip Edelbrock <phil@netroedge.com>,
-	Mark D. Studebaker <mdsxyz123@yahoo.com>,
-	Dan Eaton <dan.eaton@rocketlogix.com>,
-	Stephen Rousset<stephen.rousset@rocketlogix.com>
+	- Frodo Looijaard <frodol@dds.nl>,
+	- Philip Edelbrock <phil@netroedge.com>,
+	- Mark D. Studebaker <mdsxyz123@yahoo.com>,
+	- Dan Eaton <dan.eaton@rocketlogix.com>,
+	- Stephen Rousset<stephen.rousset@rocketlogix.com>
 
 Description
 -----------
diff --git a/Documentation/i2c/busses/i2c-ali1563 b/Documentation/i2c/busses/i2c-ali1563.rst
similarity index 93%
rename from Documentation/i2c/busses/i2c-ali1563
rename to Documentation/i2c/busses/i2c-ali1563.rst
index 41b1a077e4c7..eec32c3ba92a 100644
--- a/Documentation/i2c/busses/i2c-ali1563
+++ b/Documentation/i2c/busses/i2c-ali1563.rst
@@ -1,7 +1,10 @@
+=========================
 Kernel driver i2c-ali1563
+=========================
 
 Supported adapters:
   * Acer Labs, Inc. ALI 1563 (south bridge)
+
     Datasheet: Now under NDA
 	http://www.ali.com.tw/
 
diff --git a/Documentation/i2c/busses/i2c-ali15x3 b/Documentation/i2c/busses/i2c-ali15x3.rst
similarity index 72%
rename from Documentation/i2c/busses/i2c-ali15x3
rename to Documentation/i2c/busses/i2c-ali15x3.rst
index 42888d8ac124..d4c1a2a419cb 100644
--- a/Documentation/i2c/busses/i2c-ali15x3
+++ b/Documentation/i2c/busses/i2c-ali15x3.rst
@@ -1,20 +1,23 @@
+=========================
 Kernel driver i2c-ali15x3
+=========================
 
 Supported adapters:
   * Acer Labs, Inc. ALI 1533 and 1543C (south bridge)
+
     Datasheet: Now under NDA
 	http://www.ali.com.tw/
 
 Authors:
-	Frodo Looijaard <frodol@dds.nl>,
-	Philip Edelbrock <phil@netroedge.com>,
-	Mark D. Studebaker <mdsxyz123@yahoo.com>
+	- Frodo Looijaard <frodol@dds.nl>,
+	- Philip Edelbrock <phil@netroedge.com>,
+	- Mark D. Studebaker <mdsxyz123@yahoo.com>
 
 Module Parameters
 -----------------
 
 * force_addr: int
-  Initialize the base address of the i2c controller
+    Initialize the base address of the i2c controller
 
 
 Notes
@@ -25,7 +28,9 @@ the BIOS. Does not do a PCI force; the device must still be present in
 lspci. Don't use this unless the driver complains that the base address is
 not set.
 
-Example: 'modprobe i2c-ali15x3 force_addr=0xe800'
+Example::
+
+    modprobe i2c-ali15x3 force_addr=0xe800
 
 SMBus periodically hangs on ASUS P5A motherboards and can only be cleared
 by a power cycle. Cause unknown (see Issues below).
@@ -38,47 +43,53 @@ This is the driver for the SMB Host controller on Acer Labs Inc. (ALI)
 M1541 and M1543C South Bridges.
 
 The M1543C is a South bridge for desktop systems.
+
 The M1541 is a South bridge for portable systems.
+
 They are part of the following ALI chipsets:
 
  * "Aladdin Pro 2" includes the M1621 Slot 1 North bridge with AGP and
- 		100MHz CPU Front Side bus
+   100MHz CPU Front Side bus
  * "Aladdin V" includes the M1541 Socket 7 North bridge with AGP and 100MHz
- 		CPU Front Side bus
+   CPU Front Side bus
+
    Some Aladdin V motherboards:
-	Asus P5A
-	Atrend ATC-5220
-	BCM/GVC VP1541
-	Biostar M5ALA
-	Gigabyte GA-5AX (** Generally doesn't work because the BIOS doesn't
-                            enable the 7101 device! **)
-	Iwill XA100 Plus
-	Micronics C200
-	Microstar (MSI) MS-5169
+	- Asus P5A
+	- Atrend ATC-5220
+	- BCM/GVC VP1541
+	- Biostar M5ALA
+	- Gigabyte GA-5AX (Generally doesn't work because the BIOS doesn't
+	  enable the 7101 device!)
+	- Iwill XA100 Plus
+	- Micronics C200
+	- Microstar (MSI) MS-5169
 
   * "Aladdin IV" includes the M1541 Socket 7 North bridge
-   		with host bus up to 83.3 MHz.
+    with host bus up to 83.3 MHz.
 
 For an overview of these chips see http://www.acerlabs.com. At this time the
 full data sheets on the web site are password protected, however if you
 contact the ALI office in San Jose they may give you the password.
 
 The M1533/M1543C devices appear as FOUR separate devices on the PCI bus. An
-output of lspci will show something similar to the following:
+output of lspci will show something similar to the following::
 
   00:02.0 USB Controller: Acer Laboratories Inc. M5237 (rev 03)
   00:03.0 Bridge: Acer Laboratories Inc. M7101      <= THIS IS THE ONE WE NEED
   00:07.0 ISA bridge: Acer Laboratories Inc. M1533 (rev c3)
   00:0f.0 IDE interface: Acer Laboratories Inc. M5229 (rev c1)
 
-** IMPORTANT **
-** If you have a M1533 or M1543C on the board and you get
-** "ali15x3: Error: Can't detect ali15x3!"
-** then run lspci.
-** If you see the 1533 and 5229 devices but NOT the 7101 device,
-** then you must enable ACPI, the PMU, SMB, or something similar
-** in the BIOS.
-** The driver won't work if it can't find the M7101 device.
+.. important::
+
+   If you have a M1533 or M1543C on the board and you get
+   "ali15x3: Error: Can't detect ali15x3!"
+   then run lspci.
+
+   If you see the 1533 and 5229 devices but NOT the 7101 device,
+   then you must enable ACPI, the PMU, SMB, or something similar
+   in the BIOS.
+
+   The driver won't work if it can't find the M7101 device.
 
 The SMB controller is part of the M7101 device, which is an ACPI-compliant
 Power Management Unit (PMU).
@@ -109,4 +120,3 @@ There may be electrical problems on this board.
 On the P5A, the W83781D sensor chip is on both the ISA and
 SMBus. Therefore the SMBus hangs can generally be avoided
 by accessing the W83781D on the ISA bus only.
-
diff --git a/Documentation/i2c/busses/i2c-amd-mp2 b/Documentation/i2c/busses/i2c-amd-mp2.rst
similarity index 42%
rename from Documentation/i2c/busses/i2c-amd-mp2
rename to Documentation/i2c/busses/i2c-amd-mp2.rst
index 6571487171f4..ebc2fa899325 100644
--- a/Documentation/i2c/busses/i2c-amd-mp2
+++ b/Documentation/i2c/busses/i2c-amd-mp2.rst
@@ -1,4 +1,6 @@
+=========================
 Kernel driver i2c-amd-mp2
+=========================
 
 Supported adapters:
   * AMD MP2 PCIe interface
@@ -6,9 +8,9 @@ Supported adapters:
 Datasheet: not publicly available.
 
 Authors:
-	Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
-	Nehal Shah <nehal-bakulchandra.shah@amd.com>
-	Elie Morisse <syniurge@gmail.com>
+	- Shyam Sundar S K <Shyam-sundar.S-k@amd.com>
+	- Nehal Shah <nehal-bakulchandra.shah@amd.com>
+	- Elie Morisse <syniurge@gmail.com>
 
 Description
 -----------
@@ -16,8 +18,8 @@ Description
 The MP2 is an ARM processor programmed as an I2C controller and communicating
 with the x86 host through PCI.
 
-If you see something like this:
+If you see something like this::
 
-03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6
+  03:00.7 MP2 I2C controller: Advanced Micro Devices, Inc. [AMD] Device 15e6
 
-in your 'lspci -v', then this driver is for your device.
+in your ``lspci -v``, then this driver is for your device.
diff --git a/Documentation/i2c/busses/i2c-amd756 b/Documentation/i2c/busses/i2c-amd756.rst
similarity index 79%
rename from Documentation/i2c/busses/i2c-amd756
rename to Documentation/i2c/busses/i2c-amd756.rst
index 67f30874d0bf..bc93f392a4fc 100644
--- a/Documentation/i2c/busses/i2c-amd756
+++ b/Documentation/i2c/busses/i2c-amd756.rst
@@ -1,18 +1,22 @@
+========================
 Kernel driver i2c-amd756
+========================
 
 Supported adapters:
   * AMD 756
   * AMD 766
   * AMD 768
   * AMD 8111
+
     Datasheets: Publicly available on AMD website
 
   * nVidia nForce
+
     Datasheet: Unavailable
 
 Authors:
-	Frodo Looijaard <frodol@dds.nl>,
-	Philip Edelbrock <phil@netroedge.com> 
+	- Frodo Looijaard <frodol@dds.nl>,
+	- Philip Edelbrock <phil@netroedge.com>
 
 Description
 -----------
diff --git a/Documentation/i2c/busses/i2c-amd8111 b/Documentation/i2c/busses/i2c-amd8111.rst
similarity index 66%
rename from Documentation/i2c/busses/i2c-amd8111
rename to Documentation/i2c/busses/i2c-amd8111.rst
index 460dd6635fd2..d08bf0a7f0ac 100644
--- a/Documentation/i2c/busses/i2c-amd8111
+++ b/Documentation/i2c/busses/i2c-amd8111.rst
@@ -1,4 +1,6 @@
+=========================
 Kernel driver i2c-adm8111
+=========================
 
 Supported adapters:
     * AMD-8111 SMBus 2.0 PCI interface
@@ -13,14 +15,14 @@ Author: Vojtech Pavlik <vojtech@suse.cz>
 Description
 -----------
 
-If you see something like this:
+If you see something like this::
 
-00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
-        Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
-        Flags: medium devsel, IRQ 19
-        I/O ports at d400 [size=32]
+  00:07.2 SMBus: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0 (rev 02)
+          Subsystem: Advanced Micro Devices [AMD] AMD-8111 SMBus 2.0
+          Flags: medium devsel, IRQ 19
+          I/O ports at d400 [size=32]
 
-in your 'lspci -v', then this driver is for your chipset.
+in your ``lspci -v``, then this driver is for your chipset.
 
 Process Call Support
 --------------------
diff --git a/Documentation/i2c/busses/i2c-diolan-u2c b/Documentation/i2c/busses/i2c-diolan-u2c.rst
similarity index 91%
rename from Documentation/i2c/busses/i2c-diolan-u2c
rename to Documentation/i2c/busses/i2c-diolan-u2c.rst
index 0d6018c316c7..c18cbdcdf73c 100644
--- a/Documentation/i2c/busses/i2c-diolan-u2c
+++ b/Documentation/i2c/busses/i2c-diolan-u2c.rst
@@ -1,7 +1,10 @@
+============================
 Kernel driver i2c-diolan-u2c
+============================
 
 Supported adapters:
   * Diolan U2C-12 I2C-USB adapter
+
     Documentation:
 	http://www.diolan.com/i2c/u2c12.html
 
diff --git a/Documentation/i2c/busses/i2c-i801 b/Documentation/i2c/busses/i2c-i801.rst
similarity index 89%
rename from Documentation/i2c/busses/i2c-i801
rename to Documentation/i2c/busses/i2c-i801.rst
index f426c13c63a9..2a570c214880 100644
--- a/Documentation/i2c/busses/i2c-i801
+++ b/Documentation/i2c/busses/i2c-i801.rst
@@ -1,4 +1,7 @@
+======================
 Kernel driver i2c-i801
+======================
+
 
 Supported adapters:
   * Intel 82801AA and 82801AB (ICH and ICH0 - part of the
@@ -39,28 +42,33 @@ Supported adapters:
   * Intel Comet Lake (PCH)
   * Intel Elkhart Lake (PCH)
   * Intel Tiger Lake (PCH)
+
    Datasheets: Publicly available at the Intel website
 
 On Intel Patsburg and later chipsets, both the normal host SMBus controller
 and the additional 'Integrated Device Function' controllers are supported.
 
-Authors: 
-	Mark Studebaker <mdsxyz123@yahoo.com>
-	Jean Delvare <jdelvare@suse.de>
+Authors:
+	- Mark Studebaker <mdsxyz123@yahoo.com>
+	- Jean Delvare <jdelvare@suse.de>
 
 
 Module Parameters
 -----------------
 
 * disable_features (bit vector)
+
 Disable selected features normally supported by the device. This makes it
 possible to work around possible driver or hardware bugs if the feature in
 question doesn't work as intended for whatever reason. Bit values:
+
+ ====  =========================================
  0x01  disable SMBus PEC
  0x02  disable the block buffer
  0x08  disable the I2C block read functionality
  0x10  don't use interrupts
  0x20  disable SMBus Host Notify
+ ====  =========================================
 
 
 Description
@@ -73,7 +81,7 @@ Pentium-based PCs, '815E' chipset, and others.
 
 The ICH chips contain at least SEVEN separate PCI functions in TWO logical
 PCI devices. An output of lspci will show something similar to the
-following:
+following::
 
   00:1e.0 PCI bridge: Intel Corporation: Unknown device 2418 (rev 01)
   00:1f.0 ISA bridge: Intel Corporation: Unknown device 2410 (rev 01)
@@ -139,14 +147,14 @@ and you think there's something interesting on the SMBus (e.g. a
 hardware monitoring chip), you need to add your board to the list.
 
 The motherboard is identified using the subvendor and subdevice IDs of the
-host bridge PCI device. Get yours with "lspci -n -v -s 00:00.0":
+host bridge PCI device. Get yours with ``lspci -n -v -s 00:00.0``::
 
-00:00.0 Class 0600: 8086:2570 (rev 02)
-        Subsystem: 1043:80f2
-        Flags: bus master, fast devsel, latency 0
-        Memory at fc000000 (32-bit, prefetchable) [size=32M]
-        Capabilities: [e4] #09 [2106]
-        Capabilities: [a0] AGP version 3.0
+  00:00.0 Class 0600: 8086:2570 (rev 02)
+          Subsystem: 1043:80f2
+          Flags: bus master, fast devsel, latency 0
+          Memory at fc000000 (32-bit, prefetchable) [size=32M]
+          Capabilities: [e4] #09 [2106]
+          Capabilities: [a0] AGP version 3.0
 
 Here the host bridge ID is 2570 (82865G/PE/P), the subvendor ID is 1043
 (Asus) and the subdevice ID is 80f2 (P4P800-X). You can find the symbolic
@@ -165,7 +173,8 @@ kernel. It's very convenient if you just want to check if there's
 anything interesting on your hidden ICH SMBus.
 
 
-**********************
+----------------------------------------------------------------------------
+
 The lm_sensors project gratefully acknowledges the support of Texas
 Instruments in the initial development of this driver.
 
diff --git a/Documentation/i2c/busses/i2c-ismt b/Documentation/i2c/busses/i2c-ismt.rst
similarity index 81%
rename from Documentation/i2c/busses/i2c-ismt
rename to Documentation/i2c/busses/i2c-ismt.rst
index 737355822c0b..8e74919a3fdf 100644
--- a/Documentation/i2c/busses/i2c-ismt
+++ b/Documentation/i2c/busses/i2c-ismt.rst
@@ -1,4 +1,7 @@
+======================
 Kernel driver i2c-ismt
+======================
+
 
 Supported adapters:
   * Intel S12xx series SOCs
@@ -11,16 +14,21 @@ Module Parameters
 -----------------
 
 * bus_speed (unsigned int)
+
 Allows changing of the bus speed.  Normally, the bus speed is set by the BIOS
 and never needs to be changed.  However, some SMBus analyzers are too slow for
 monitoring the bus during debug, thus the need for this module parameter.
 Specify the bus speed in kHz.
+
 Available bus frequency settings:
-  0  no change
-  80 kHz
-  100 kHz
-  400 kHz
-  1000 kHz
+
+  ====   =========
+  0      no change
+  80     kHz
+  100    kHz
+  400    kHz
+  1000   kHz
+  ====   =========
 
 
 Description
@@ -30,7 +38,7 @@ The S12xx series of SOCs have a pair of integrated SMBus 2.0 controllers
 targeted primarily at the microserver and storage markets.
 
 The S12xx series contain a pair of PCI functions.  An output of lspci will show
-something similar to the following:
+something similar to the following::
 
   00:13.0 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 0
   00:13.1 System peripheral: Intel Corporation Centerton SMBus 2.0 Controller 1
diff --git a/Documentation/i2c/busses/i2c-mlxcpld b/Documentation/i2c/busses/i2c-mlxcpld.rst
similarity index 88%
rename from Documentation/i2c/busses/i2c-mlxcpld
rename to Documentation/i2c/busses/i2c-mlxcpld.rst
index 925904aa9b57..9a0b2916aa71 100644
--- a/Documentation/i2c/busses/i2c-mlxcpld
+++ b/Documentation/i2c/busses/i2c-mlxcpld.rst
@@ -1,9 +1,12 @@
+==================
 Driver i2c-mlxcpld
+==================
 
 Author: Michael Shych <michaelsh@mellanox.com>
 
 This is the Mellanox I2C controller logic, implemented in Lattice CPLD
 device.
+
 Device supports:
  - Master mode.
  - One physical bus.
@@ -20,6 +23,8 @@ The next transaction types are supported:
  - Write Byte/Block.
 
 Registers:
+
+=============== === =======================================================================
 CPBLTY		0x0 - capability reg.
 			Bits [6:5] - transaction length. b01 - 72B is supported,
 			36B in other case.
@@ -49,3 +54,4 @@ DATAx		0xa - 0x54  - 68 bytes data buffer regs.
 			For read transactions address is sent in a separate transaction and
 			specified in the four first bytes (DATA0 - DATA3). Data is read
 			starting from DATA0.
+=============== === =======================================================================
diff --git a/Documentation/i2c/busses/i2c-nforce2 b/Documentation/i2c/busses/i2c-nforce2.rst
similarity index 58%
rename from Documentation/i2c/busses/i2c-nforce2
rename to Documentation/i2c/busses/i2c-nforce2.rst
index 9698c396b830..83181445268f 100644
--- a/Documentation/i2c/busses/i2c-nforce2
+++ b/Documentation/i2c/busses/i2c-nforce2.rst
@@ -1,10 +1,12 @@
+=========================
 Kernel driver i2c-nforce2
+=========================
 
 Supported adapters:
-  * nForce2 MCP                10de:0064 
-  * nForce2 Ultra 400 MCP      10de:0084 
-  * nForce3 Pro150 MCP         10de:00D4 
-  * nForce3 250Gb MCP          10de:00E4 
+  * nForce2 MCP                10de:0064
+  * nForce2 Ultra 400 MCP      10de:0084
+  * nForce3 Pro150 MCP         10de:00D4
+  * nForce3 250Gb MCP          10de:00E4
   * nForce4 MCP                10de:0052
   * nForce4 MCP-04             10de:0034
   * nForce MCP51               10de:0264
@@ -16,26 +18,27 @@ Supported adapters:
   * nForce MCP78S              10de:0752
   * nForce MCP79               10de:0AA2
 
-Datasheet: not publicly available, but seems to be similar to the
+Datasheet:
+           not publicly available, but seems to be similar to the
            AMD-8111 SMBus 2.0 adapter.
 
 Authors:
-	Hans-Frieder Vogt <hfvogt@gmx.net>,
-	Thomas Leibold <thomas@plx.com>, 
-        Patrick Dreker <patrick@dreker.de>
-	
+	- Hans-Frieder Vogt <hfvogt@gmx.net>,
+	- Thomas Leibold <thomas@plx.com>,
+        - Patrick Dreker <patrick@dreker.de>
+
 Description
 -----------
 
 i2c-nforce2 is a driver for the SMBuses included in the nVidia nForce2 MCP.
 
-If your 'lspci -v' listing shows something like the following,
+If your ``lspci -v`` listing shows something like the following::
 
-00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
-        Subsystem: Asustek Computer, Inc.: Unknown device 0c11
-        Flags: 66Mhz, fast devsel, IRQ 5
-        I/O ports at c000 [size=32]
-        Capabilities: <available only to root>
+  00:01.1 SMBus: nVidia Corporation: Unknown device 0064 (rev a2)
+          Subsystem: Asustek Computer, Inc.: Unknown device 0c11
+          Flags: 66Mhz, fast devsel, IRQ 5
+          I/O ports at c000 [size=32]
+          Capabilities: <available only to root>
 
 then this driver should support the SMBuses of your motherboard.
 
diff --git a/Documentation/i2c/busses/i2c-nvidia-gpu b/Documentation/i2c/busses/i2c-nvidia-gpu.rst
similarity index 63%
rename from Documentation/i2c/busses/i2c-nvidia-gpu
rename to Documentation/i2c/busses/i2c-nvidia-gpu.rst
index 31884d2b2eb5..38fb8a4c8756 100644
--- a/Documentation/i2c/busses/i2c-nvidia-gpu
+++ b/Documentation/i2c/busses/i2c-nvidia-gpu.rst
@@ -1,4 +1,6 @@
+============================
 Kernel driver i2c-nvidia-gpu
+============================
 
 Datasheet: not publicly available.
 
@@ -11,8 +13,8 @@ Description
 i2c-nvidia-gpu is a driver for I2C controller included in NVIDIA Turing
 and later GPUs and it is used to communicate with Type-C controller on GPUs.
 
-If your 'lspci -v' listing shows something like the following,
+If your ``lspci -v`` listing shows something like the following::
 
-01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)
+  01:00.3 Serial bus controller [0c80]: NVIDIA Corporation Device 1ad9 (rev a1)
 
 then this driver should support the I2C controller of your GPU.
diff --git a/Documentation/i2c/busses/i2c-ocores b/Documentation/i2c/busses/i2c-ocores.rst
similarity index 82%
rename from Documentation/i2c/busses/i2c-ocores
rename to Documentation/i2c/busses/i2c-ocores.rst
index 9caaf7df1b2f..f5e175f2a2a6 100644
--- a/Documentation/i2c/busses/i2c-ocores
+++ b/Documentation/i2c/busses/i2c-ocores.rst
@@ -1,4 +1,6 @@
+========================
 Kernel driver i2c-ocores
+========================
 
 Supported adapters:
   * OpenCores.org I2C controller by Richard Herveille (see datasheet link)
@@ -23,9 +25,9 @@ distance between registers and the input clock speed.
 There is also a possibility to attach a list of i2c_board_info which
 the i2c-ocores driver will add to the bus upon creation.
 
-E.G. something like:
+E.G. something like::
 
-static struct resource ocores_resources[] = {
+  static struct resource ocores_resources[] = {
 	[0] = {
 		.start	= MYI2C_BASEADDR,
 		.end	= MYI2C_BASEADDR + 8,
@@ -36,10 +38,10 @@ static struct resource ocores_resources[] = {
 		.end	= MYI2C_IRQ,
 		.flags	= IORESOURCE_IRQ,
 	},
-};
+  };
 
-/* optional board info */
-struct i2c_board_info ocores_i2c_board_info[] = {
+  /* optional board info */
+  struct i2c_board_info ocores_i2c_board_info[] = {
 	{
 		I2C_BOARD_INFO("tsc2003", 0x48),
 		.platform_data = &tsc2003_platform_data,
@@ -49,20 +51,20 @@ struct i2c_board_info ocores_i2c_board_info[] = {
 		I2C_BOARD_INFO("adv7180", 0x42 >> 1),
 		.irq = ADV_IRQ
 	}
-};
+  };
 
-static struct ocores_i2c_platform_data myi2c_data = {
+  static struct ocores_i2c_platform_data myi2c_data = {
 	.regstep	= 2,		/* two bytes between registers */
 	.clock_khz	= 50000,	/* input clock of 50MHz */
 	.devices	= ocores_i2c_board_info, /* optional table of devices */
 	.num_devices	= ARRAY_SIZE(ocores_i2c_board_info), /* table size */
-};
+  };
 
-static struct platform_device myi2c = {
+  static struct platform_device myi2c = {
 	.name			= "ocores-i2c",
 	.dev = {
 		.platform_data	= &myi2c_data,
 	},
 	.num_resources		= ARRAY_SIZE(ocores_resources),
 	.resource		= ocores_resources,
-};
+  };
diff --git a/Documentation/i2c/busses/i2c-parport-light b/Documentation/i2c/busses/i2c-parport-light.rst
similarity index 91%
rename from Documentation/i2c/busses/i2c-parport-light
rename to Documentation/i2c/busses/i2c-parport-light.rst
index 7071b8ba0af4..e73af975d2c8 100644
--- a/Documentation/i2c/busses/i2c-parport-light
+++ b/Documentation/i2c/busses/i2c-parport-light.rst
@@ -1,13 +1,15 @@
+===============================
 Kernel driver i2c-parport-light
+===============================
 
 Author: Jean Delvare <jdelvare@suse.de>
 
-This driver is a light version of i2c-parport. It doesn't depend        
+This driver is a light version of i2c-parport. It doesn't depend
 on the parport driver, and uses direct I/O access instead. This might be
 preferred on embedded systems where wasting memory for the clean but heavy
 parport handling is not an option. The drawback is a reduced portability
-and the impossibility to daisy-chain other parallel port devices.                 
-  
+and the impossibility to daisy-chain other parallel port devices.
+
 Please see i2c-parport for documentation.
 
 Module parameters:
diff --git a/Documentation/i2c/busses/i2c-parport b/Documentation/i2c/busses/i2c-parport.rst
similarity index 49%
rename from Documentation/i2c/busses/i2c-parport
rename to Documentation/i2c/busses/i2c-parport.rst
index c3dbb3bfd814..a9b4e8133700 100644
--- a/Documentation/i2c/busses/i2c-parport
+++ b/Documentation/i2c/busses/i2c-parport.rst
@@ -1,17 +1,21 @@
+=========================
 Kernel driver i2c-parport
+=========================
 
 Author: Jean Delvare <jdelvare@suse.de>
 
 This is a unified driver for several i2c-over-parallel-port adapters,
 such as the ones made by Philips, Velleman or ELV. This driver is
 meant as a replacement for the older, individual drivers:
+
  * i2c-philips-par
  * i2c-elv
  * i2c-velleman
- * video/i2c-parport (NOT the same as this one, dedicated to home brew
-                      teletext adapters)
+ * video/i2c-parport
+   (NOT the same as this one, dedicated to home brew teletext adapters)
 
 It currently supports the following devices:
+
  * (type=0) Philips adapter
  * (type=1) home brew teletext adapter
  * (type=2) Velleman K8000 adapter
@@ -38,44 +42,48 @@ Building your own adapter
 -------------------------
 
 If you want to build you own i2c-over-parallel-port adapter, here is
-a sample electronics schema (credits go to Sylvain Munaut):
+a sample electronics schema (credits go to Sylvain Munaut)::
+
+  Device                                                      PC
+  Side          ___________________Vdd (+)                    Side
+                 |    |         |
+                ---  ---       ---
+                | |  | |       | |
+                |R|  |R|       |R|
+                | |  | |       | |
+                ---  ---       ---
+                 |    |         |
+                 |    |    /|   |
+  SCL  ----------x--------o |-----------x-------------------  pin 2
+                      |    \|   |       |
+                      |         |       |
+                      |   |\    |       |
+  SDA  ----------x----x---| o---x---------------------------  pin 13
+                 |        |/            |
+                 |                      |
+                 |         /|           |
+                 ---------o |----------------x--------------  pin 3
+                           \|           |    |
+                                        |    |
+                                       ---  ---
+                                       | |  | |
+                                       |R|  |R|
+                                       | |  | |
+                                       ---  ---
+                                        |    |
+                                       ###  ###
+                                       GND  GND
 
-Device                                                      PC
-Side          ___________________Vdd (+)                    Side
-               |    |         |
-              ---  ---       ---
-              | |  | |       | |
-              |R|  |R|       |R|
-              | |  | |       | |
-              ---  ---       ---
-               |    |         |
-               |    |    /|   |
-SCL  ----------x--------o |-----------x-------------------  pin 2
-                    |    \|   |       |
-                    |         |       |
-                    |   |\    |       |
-SDA  ----------x----x---| o---x---------------------------  pin 13
-               |        |/            |
-               |                      |
-               |         /|           |
-               ---------o |----------------x--------------  pin 3
-                         \|           |    |
-                                      |    |
-                                     ---  ---
-                                     | |  | |
-                                     |R|  |R|
-                                     | |  | |
-                                     ---  ---
-                                      |    | 
-                                     ###  ###
-                                     GND  GND
-        
 Remarks:
  - This is the exact pinout and electronics used on the Analog Devices
    evaluation boards.
+ - All inverters::
+
                    /|
- - All inverters -o |- must be 74HC05, they must be open collector output.
+                 -o |-
                    \|
+
+   must be 74HC05, they must be open collector output.
  - All resitors are 10k.
  - Pins 18-25 of the parallel port connected to GND.
  - Pins 4-9 (D2-D7) could be used as VDD is the driver drives them high.
@@ -84,47 +92,47 @@ Remarks:
    all connected lines MUST BE driven at the same state, else you'll short
    circuit the output buffers! So plugging the I2C adapter after loading
    the i2c-parport module might be a good safety since data line state
-   prior to init may be unknown. 
+   prior to init may be unknown.
  - This is 5V!
  - Obviously you cannot read SCL (so it's not really standard-compliant).
    Pretty easy to add, just copy the SDA part and use another input pin.
-   That would give (ELV compatible pinout):
+   That would give (ELV compatible pinout)::
 
 
-Device                                                      PC
-Side          ______________________________Vdd (+)         Side
-               |    |            |    |
-              ---  ---          ---  ---
-              | |  | |          | |  | |
-              |R|  |R|          |R|  |R|
-              | |  | |          | |  | |
-              ---  ---          ---  ---
-               |    |            |    |
-               |    |      |\    |    |
-SCL  ----------x--------x--| o---x------------------------  pin 15
-                    |   |  |/         | 
-                    |   |             |
-                    |   |   /|        |
-                    |   ---o |-------------x--------------  pin 2
-                    |       \|        |    |
-                    |                 |    |
-                    |                 |    |
-                    |      |\         |    |
-SDA  ---------------x---x--| o--------x-------------------  pin 10
-                        |  |/              |
-                        |                  |
-                        |   /|             |
-                        ---o |------------------x---------  pin 3
-                            \|             |    |
-                                           |    |
-                                          ---  ---
-                                          | |  | |
-                                          |R|  |R|
-                                          | |  | |
-                                          ---  ---
-                                           |    | 
-                                          ###  ###
-                                          GND  GND
+      Device                                                      PC
+      Side          ______________________________Vdd (+)         Side
+                     |    |            |    |
+                    ---  ---          ---  ---
+                    | |  | |          | |  | |
+                    |R|  |R|          |R|  |R|
+                    | |  | |          | |  | |
+                    ---  ---          ---  ---
+                     |    |            |    |
+                     |    |      |\    |    |
+      SCL  ----------x--------x--| o---x------------------------  pin 15
+                          |   |  |/         |
+                          |   |             |
+                          |   |   /|        |
+                          |   ---o |-------------x--------------  pin 2
+                          |       \|        |    |
+                          |                 |    |
+                          |                 |    |
+                          |      |\         |    |
+      SDA  ---------------x---x--| o--------x-------------------  pin 10
+                              |  |/              |
+                              |                  |
+                              |   /|             |
+                              ---o |------------------x---------  pin 3
+                                  \|             |    |
+                                                 |    |
+                                                ---  ---
+                                                | |  | |
+                                                |R|  |R|
+                                                | |  | |
+                                                ---  ---
+                                                 |    |
+                                                ###  ###
+                                                GND  GND
 
 
 If possible, you should use the same pinout configuration as existing
@@ -149,19 +157,23 @@ Legacy documentation for Velleman adapter
 -----------------------------------------
 
 Useful links:
-Velleman                http://www.velleman.be/
-Velleman K8000 Howto    http://howto.htlw16.ac.at/k8000-howto.html
+
+- Velleman                http://www.velleman.be/
+- Velleman K8000 Howto    http://howto.htlw16.ac.at/k8000-howto.html
 
 The project has lead to new libs for the Velleman K8000 and K8005:
+
   LIBK8000 v1.99.1 and LIBK8005 v0.21
+
 With these libs, you can control the K8000 interface card and the K8005
 stepper motor card with the simple commands which are in the original
 Velleman software, like SetIOchannel, ReadADchannel, SendStepCCWFull and
 many more, using /dev/velleman.
-  http://home.wanadoo.nl/hihihi/libk8000.htm
-  http://home.wanadoo.nl/hihihi/libk8005.htm
-  http://struyve.mine.nu:8080/index.php?block=k8000
-  http://sourceforge.net/projects/libk8005/
+
+  - http://home.wanadoo.nl/hihihi/libk8000.htm
+  - http://home.wanadoo.nl/hihihi/libk8005.htm
+  - http://struyve.mine.nu:8080/index.php?block=k8000
+  - http://sourceforge.net/projects/libk8005/
 
 
 One For All JP1 parallel port adapter
diff --git a/Documentation/i2c/busses/i2c-pca-isa b/Documentation/i2c/busses/i2c-pca-isa.rst
similarity index 72%
rename from Documentation/i2c/busses/i2c-pca-isa
rename to Documentation/i2c/busses/i2c-pca-isa.rst
index b044e5265488..a254010c8055 100644
--- a/Documentation/i2c/busses/i2c-pca-isa
+++ b/Documentation/i2c/busses/i2c-pca-isa.rst
@@ -1,6 +1,9 @@
+=========================
 Kernel driver i2c-pca-isa
+=========================
 
 Supported adapters:
+
 This driver supports ISA boards using the Philips PCA 9564
 Parallel bus to I2C bus controller
 
@@ -10,11 +13,11 @@ Module Parameters
 -----------------
 
 * base int
- I/O base address
+    I/O base address
 * irq int
- IRQ interrupt
+    IRQ interrupt
 * clock int
- Clock rate as described in table 1 of PCA9564 datasheet
+    Clock rate as described in table 1 of PCA9564 datasheet
 
 Description
 -----------
diff --git a/Documentation/i2c/busses/i2c-piix4 b/Documentation/i2c/busses/i2c-piix4.rst
similarity index 92%
rename from Documentation/i2c/busses/i2c-piix4
rename to Documentation/i2c/busses/i2c-piix4.rst
index 2703bc3acad0..cc9000259223 100644
--- a/Documentation/i2c/busses/i2c-piix4
+++ b/Documentation/i2c/busses/i2c-piix4.rst
@@ -1,4 +1,6 @@
+=======================
 Kernel driver i2c-piix4
+=======================
 
 Supported adapters:
   * Intel 82371AB PIIX4 and PIIX4E
@@ -20,9 +22,9 @@ Supported adapters:
   * Standard Microsystems (SMSC) SLC90E66 (Victory66) southbridge
     Datasheet: Publicly available at the SMSC website http://www.smsc.com
 
-Authors: 
-	Frodo Looijaard <frodol@dds.nl>
-	Philip Edelbrock <phil@netroedge.com>
+Authors:
+	- Frodo Looijaard <frodol@dds.nl>
+	- Philip Edelbrock <phil@netroedge.com>
 
 
 Module Parameters
@@ -39,16 +41,16 @@ Description
 
 The PIIX4 (properly known as the 82371AB) is an Intel chip with a lot of
 functionality. Among other things, it implements the PCI bus. One of its
-minor functions is implementing a System Management Bus. This is a true 
+minor functions is implementing a System Management Bus. This is a true
 SMBus - you can not access it on I2C levels. The good news is that it
 natively understands SMBus commands and you do not have to worry about
 timing problems. The bad news is that non-SMBus devices connected to it can
 confuse it mightily. Yes, this is known to happen...
 
-Do 'lspci -v' and see whether it contains an entry like this:
+Do ``lspci -v`` and see whether it contains an entry like this::
 
-0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
-	     Flags: medium devsel, IRQ 9
+  0000:00:02.3 Bridge: Intel Corp. 82371AB/EB/MB PIIX4 ACPI (rev 02)
+	       Flags: medium devsel, IRQ 9
 
 Bus and device numbers may differ, but the function number must be
 identical (like many PCI devices, the PIIX4 incorporates a number of
@@ -91,7 +93,7 @@ the SMI mode.
    device is located at 00:0f.0.
 2) Now you just need to change the value in 0xD2 register. Get it first with
    command: lspci -xxx -s 00:0f.0
-   If the value is 0x3 then you need to change it to 0x1
+   If the value is 0x3 then you need to change it to 0x1:
    setpci  -s 00:0f.0 d2.b=1
 
 Please note that you don't need to do that in all cases, just when the SMBus is
diff --git a/Documentation/i2c/busses/i2c-sis5595 b/Documentation/i2c/busses/i2c-sis5595.rst
similarity index 74%
rename from Documentation/i2c/busses/i2c-sis5595
rename to Documentation/i2c/busses/i2c-sis5595.rst
index ecd21fb49a8f..b85630c84a96 100644
--- a/Documentation/i2c/busses/i2c-sis5595
+++ b/Documentation/i2c/busses/i2c-sis5595.rst
@@ -1,9 +1,11 @@
+=========================
 Kernel driver i2c-sis5595
+=========================
 
 Authors:
-	Frodo Looijaard <frodol@dds.nl>,
-        Mark D. Studebaker <mdsxyz123@yahoo.com>,
-	Philip Edelbrock <phil@netroedge.com>
+	- Frodo Looijaard <frodol@dds.nl>,
+        - Mark D. Studebaker <mdsxyz123@yahoo.com>,
+	- Philip Edelbrock <phil@netroedge.com>
 
 Supported adapters:
   * Silicon Integrated Systems Corp. SiS5595 Southbridge
@@ -11,14 +13,19 @@ Supported adapters:
 
 Note: all have mfr. ID 0x1039.
 
+   =========            ======
    SUPPORTED            PCI ID
+   =========            ======
         5595            0008
+   =========            ======
 
    Note: these chips contain a 0008 device which is incompatible with the
          5595. We recognize these by the presence of the listed
          "blacklist" PCI ID and refuse to load.
 
+   =============        ======          ================
    NOT SUPPORTED        PCI ID          BLACKLIST PCI ID
+   =============        ======          ================
          540            0008            0540
          550            0008            0550
         5513            0008            5511
@@ -36,15 +43,18 @@ Note: all have mfr. ID 0x1039.
          735            0008            0735
          745            0008            0745
          746            0008            0746
+   =============        ======          ================
 
 Module Parameters
 -----------------
 
-* force_addr=0xaddr	Set the I/O base address. Useful for boards
+==================	=====================================================
+force_addr=0xaddr	Set the I/O base address. Useful for boards
 			that don't set the address in the BIOS. Does not do a
 			PCI force; the device must still be present in lspci.
 			Don't use this unless the driver complains that the
 			base address is not set.
+==================	=====================================================
 
 Description
 -----------
@@ -56,4 +66,3 @@ WARNING: If you are trying to access the integrated sensors on the SiS5595
 chip, you want the sis5595 driver for those, not this driver. This driver
 is a BUS driver, not a CHIP driver. A BUS driver is used by other CHIP
 drivers to access chips on the bus.
-
diff --git a/Documentation/i2c/busses/i2c-sis630 b/Documentation/i2c/busses/i2c-sis630.rst
similarity index 37%
rename from Documentation/i2c/busses/i2c-sis630
rename to Documentation/i2c/busses/i2c-sis630.rst
index ee7943631074..9fcd74b18781 100644
--- a/Documentation/i2c/busses/i2c-sis630
+++ b/Documentation/i2c/busses/i2c-sis630.rst
@@ -1,4 +1,6 @@
+========================
 Kernel driver i2c-sis630
+========================
 
 Supported adapters:
   * Silicon Integrated Systems Corp (SiS)
@@ -7,20 +9,24 @@ Supported adapters:
 	964 chipset
   * Possible other SiS chipsets ?
 
-Author: Alexander Malysh <amalysh@web.de>
-	Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support
+Author:
+        - Alexander Malysh <amalysh@web.de>
+	- Amaury Decrême <amaury.decreme@gmail.com> - SiS964 support
 
 Module Parameters
 -----------------
 
-* force = [1|0] Forcibly enable the SIS630. DANGEROUS!
-		This can be interesting for chipsets not named
-		above to check if it works for you chipset, but DANGEROUS!
+==================      =====================================================
+force = [1|0]           Forcibly enable the SIS630. DANGEROUS!
+                        This can be interesting for chipsets not named
+                        above to check if it works for you chipset,
+                        but DANGEROUS!
 
-* high_clock = [1|0] Forcibly set Host Master Clock to 56KHz (default,
+high_clock = [1|0]      Forcibly set Host Master Clock to 56KHz (default,
 			what your BIOS use). DANGEROUS! This should be a bit
 			faster, but freeze some systems (i.e. my Laptop).
 			SIS630/730 chip only.
+==================      =====================================================
 
 
 Description
@@ -29,23 +35,23 @@ Description
 This SMBus only driver is known to work on motherboards with the above
 named chipsets.
 
-If you see something like this:
+If you see something like this::
 
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31)
-00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+  00:00.0 Host bridge: Silicon Integrated Systems [SiS] 630 Host (rev 31)
+  00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
 
-or like this:
+or like this::
 
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02)
-00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+  00:00.0 Host bridge: Silicon Integrated Systems [SiS] 730 Host (rev 02)
+  00:01.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
 
-or like this:
+or like this::
 
-00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02)
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO]
+  00:00.0 Host bridge: Silicon Integrated Systems [SiS] 760/M760 Host (rev 02)
+  00:02.0 ISA bridge: Silicon Integrated Systems [SiS] SiS964 [MuTIOL Media IO]
 							LPC Controller (rev 36)
 
-in your 'lspci' output , then this driver is for your chipset.
+in your ``lspci`` output , then this driver is for your chipset.
 
 Thank You
 ---------
@@ -55,4 +61,3 @@ Mark M. Hoffman <mhoffman@lightlink.com>
 - bug fixes
 
 To anyone else which I forgot here ;), thanks!
-
diff --git a/Documentation/i2c/busses/i2c-sis96x b/Documentation/i2c/busses/i2c-sis96x.rst
similarity index 74%
rename from Documentation/i2c/busses/i2c-sis96x
rename to Documentation/i2c/busses/i2c-sis96x.rst
index 0b979f3252a4..437cc1d89588 100644
--- a/Documentation/i2c/busses/i2c-sis96x
+++ b/Documentation/i2c/busses/i2c-sis96x.rst
@@ -1,13 +1,18 @@
+========================
 Kernel driver i2c-sis96x
+========================
 
 Replaces 2.4.x i2c-sis645
 
 Supported adapters:
+
   * Silicon Integrated Systems Corp (SiS)
+
     Any combination of these host bridges:
 	645, 645DX (aka 646), 648, 650, 651, 655, 735, 745, 746
+
     and these south bridges:
-    	961, 962, 963(L)
+	961, 962, 963(L)
 
 Author: Mark M. Hoffman <mhoffman@lightlink.com>
 
@@ -21,17 +26,17 @@ those of the SiS630, although they are located in a completely different
 place. Thanks to Alexander Malysh <amalysh@web.de> for providing the
 SiS630 datasheet (and  driver).
 
-The command "lspci" as root should produce something like these lines:
+The command ``lspci`` as root should produce something like these lines::
 
-00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
-00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
+  00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
+  00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
+  00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
 
-or perhaps this...
+or perhaps this::
 
-00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
-00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
-00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
+  00:00.0 Host bridge: Silicon Integrated Systems [SiS]: Unknown device 0645
+  00:02.0 ISA bridge: Silicon Integrated Systems [SiS]: Unknown device 0961
+  00:02.1 SMBus: Silicon Integrated Systems [SiS]: Unknown device 0016
 
 (kernel versions later than 2.4.18 may fill in the "Unknown"s)
 
@@ -50,7 +55,7 @@ TO DOs
 ------
 
 * The driver does not support SMBus block reads/writes; I may add them if a
-scenario is found where they're needed.
+  scenario is found where they're needed.
 
 
 Thank You
@@ -58,16 +63,20 @@ Thank You
 
 Mark D. Studebaker <mdsxyz123@yahoo.com>
  - design hints and bug fixes
+
 Alexander Maylsh <amalysh@web.de>
  - ditto, plus an important datasheet... almost the one I really wanted
+
 Hans-Günter Lütke Uphues <hg_lu@t-online.de>
  - patch for SiS735
+
 Robert Zwerus <arzie@dds.nl>
  - testing for SiS645DX
+
 Kianusch Sayah Karadji <kianusch@sk-tech.net>
  - patch for SiS645DX/962
+
 Ken Healy
  - patch for SiS655
 
 To anyone else who has written w/ feedback, thanks!
-
diff --git a/Documentation/i2c/busses/i2c-taos-evm b/Documentation/i2c/busses/i2c-taos-evm.rst
similarity index 91%
rename from Documentation/i2c/busses/i2c-taos-evm
rename to Documentation/i2c/busses/i2c-taos-evm.rst
index 60299555dcf0..f342e313ee3d 100644
--- a/Documentation/i2c/busses/i2c-taos-evm
+++ b/Documentation/i2c/busses/i2c-taos-evm.rst
@@ -1,4 +1,6 @@
+==========================
 Kernel driver i2c-taos-evm
+==========================
 
 Author: Jean Delvare <jdelvare@suse.de>
 
@@ -23,10 +25,10 @@ Using this driver
 In order to use this driver, you'll need the serport driver, and the
 inputattach tool, which is part of the input-utils package. The following
 commands will tell the kernel that you have a TAOS EVM on the first
-serial port:
+serial port::
 
-# modprobe serport
-# inputattach --taos-evm /dev/ttyS0
+  # modprobe serport
+  # inputattach --taos-evm /dev/ttyS0
 
 
 Technical details
diff --git a/Documentation/i2c/busses/i2c-via b/Documentation/i2c/busses/i2c-via.rst
similarity index 54%
rename from Documentation/i2c/busses/i2c-via
rename to Documentation/i2c/busses/i2c-via.rst
index 343870661ac3..846aa17d80a2 100644
--- a/Documentation/i2c/busses/i2c-via
+++ b/Documentation/i2c/busses/i2c-via.rst
@@ -1,4 +1,6 @@
+=====================
 Kernel driver i2c-via
+=====================
 
 Supported adapters:
   * VIA Technologies, InC. VT82C586B
@@ -12,23 +14,27 @@ Description
 i2c-via is an i2c bus driver for motherboards with VIA chipset.
 
 The following VIA pci chipsets are supported:
- - MVP3, VP3, VP2/97, VPX/97 
+ - MVP3, VP3, VP2/97, VPX/97
  - others with South bridge VT82C586B
 
-Your lspci listing must show this :
+Your ``lspci`` listing must show this ::
 
  Bridge: VIA Technologies, Inc. VT82C586B ACPI (rev 10)
 
-    Problems?
- 
- Q: You have VT82C586B on the motherboard, but not in the listing. 
- 
- A: Go to your BIOS setup, section PCI devices or similar.
-    Turn USB support on, and try again. 
+Problems?
+---------
 
- Q: No error messages, but still i2c doesn't seem to work.
+ Q:
+    You have VT82C586B on the motherboard, but not in the listing.
 
- A: This can happen. This driver uses the pins VIA recommends in their
+ A:
+    Go to your BIOS setup, section PCI devices or similar.
+    Turn USB support on, and try again.
+
+ Q:
+    No error messages, but still i2c doesn't seem to work.
+
+ A:
+    This can happen. This driver uses the pins VIA recommends in their
     datasheets, but there are several ways the motherboard manufacturer
     can actually wire the lines.
-
diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro.rst
similarity index 87%
rename from Documentation/i2c/busses/i2c-viapro
rename to Documentation/i2c/busses/i2c-viapro.rst
index ab64ce21c254..1762f0cf93d0 100644
--- a/Documentation/i2c/busses/i2c-viapro
+++ b/Documentation/i2c/busses/i2c-viapro.rst
@@ -1,4 +1,6 @@
+========================
 Kernel driver i2c-viapro
+========================
 
 Supported adapters:
   * VIA Technologies, Inc. VT82C596A/B
@@ -26,9 +28,9 @@ Supported adapters:
     Datasheet: available on http://linux.via.com.tw
 
 Authors:
-	Kyösti Mälkki <kmalkki@cc.hut.fi>,
-	Mark D. Studebaker <mdsxyz123@yahoo.com>,
-	Jean Delvare <jdelvare@suse.de>
+	- Kyösti Mälkki <kmalkki@cc.hut.fi>,
+	- Mark D. Studebaker <mdsxyz123@yahoo.com>,
+	- Jean Delvare <jdelvare@suse.de>
 
 Module Parameters
 -----------------
@@ -44,8 +46,9 @@ Description
 i2c-viapro is a true SMBus host driver for motherboards with one of the
 supported VIA south bridges.
 
-Your lspci -n listing must show one of these :
+Your ``lspci -n`` listing must show one of these :
 
+ ================   ======================
  device 1106:3050   (VT82C596A function 3)
  device 1106:3051   (VT82C596B function 3)
  device 1106:3057   (VT82C686 function 4)
@@ -61,6 +64,7 @@ Your lspci -n listing must show one of these :
  device 1106:8353   (VX800/VX820)
  device 1106:8409   (VX855/VX875)
  device 1106:8410   (VX900)
+ ================   ======================
 
 If none of these show up, you should look in the BIOS for settings like
 enable ACPI / SMBus or even USB.
diff --git a/Documentation/i2c/busses/index.rst b/Documentation/i2c/busses/index.rst
new file mode 100644
index 000000000000..97ca4d510816
--- /dev/null
+++ b/Documentation/i2c/busses/index.rst
@@ -0,0 +1,33 @@
+. SPDX-License-Identifier: GPL-2.0
+
+===============
+I2C Bus Drivers
+===============
+
+.. toctree::
+   :maxdepth: 1
+
+   i2c-ali1535
+   i2c-ali1563
+   i2c-ali15x3
+   i2c-amd756
+   i2c-amd8111
+   i2c-amd-mp2
+   i2c-diolan-u2c
+   i2c-i801
+   i2c-ismt
+   i2c-mlxcpld
+   i2c-nforce2
+   i2c-nvidia-gpu
+   i2c-ocores
+   i2c-parport-light
+   i2c-parport
+   i2c-pca-isa
+   i2c-piix4
+   i2c-sis5595
+   i2c-sis630
+   i2c-sis96x
+   i2c-taos-evm
+   i2c-viapro
+   i2c-via
+   scx200_acb
diff --git a/Documentation/i2c/busses/scx200_acb b/Documentation/i2c/busses/scx200_acb.rst
similarity index 86%
rename from Documentation/i2c/busses/scx200_acb
rename to Documentation/i2c/busses/scx200_acb.rst
index ce83c871fe95..8dc7c352508c 100644
--- a/Documentation/i2c/busses/scx200_acb
+++ b/Documentation/i2c/busses/scx200_acb.rst
@@ -1,4 +1,6 @@
+========================
 Kernel driver scx200_acb
+========================
 
 Author: Christer Weinigel <wingel@nano-system.com>
 
@@ -25,8 +27,11 @@ Device-specific notes
 
 The SC1100 WRAP boards are known to use base addresses 0x810 and 0x820.
 If the scx200_acb driver is built into the kernel, add the following
-parameter to your boot command line:
+parameter to your boot command line::
+
   scx200_acb.base=0x810,0x820
+
 If the scx200_acb driver is built as a module, add the following line to
-a configuration file in /etc/modprobe.d/ instead:
+a configuration file in /etc/modprobe.d/ instead::
+
   options scx200_acb base=0x810,0x820
diff --git a/Documentation/i2c/dev-interface b/Documentation/i2c/dev-interface.rst
similarity index 71%
rename from Documentation/i2c/dev-interface
rename to Documentation/i2c/dev-interface.rst
index fbed645ccd75..69c23a3c2b1b 100644
--- a/Documentation/i2c/dev-interface
+++ b/Documentation/i2c/dev-interface.rst
@@ -1,3 +1,7 @@
+====================
+I2C Device Interface
+====================
+
 Usually, i2c devices are controlled by a kernel driver. But it is also
 possible to access all devices on an adapter from userspace, through
 the /dev interface. You need to load module i2c-dev for this.
@@ -18,7 +22,7 @@ C example
 =========
 
 So let's say you want to access an i2c adapter from a C program.
-First, you need to include these two headers:
+First, you need to include these two headers::
 
   #include <linux/i2c-dev.h>
   #include <i2c/smbus.h>
@@ -28,7 +32,7 @@ inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this.
 Adapter numbers are assigned somewhat dynamically, so you can not
 assume much about them. They can even change from one boot to the next.
 
-Next thing, open the device file, as follows:
+Next thing, open the device file, as follows::
 
   int file;
   int adapter_nr = 2; /* probably dynamically determined */
@@ -42,7 +46,7 @@ Next thing, open the device file, as follows:
   }
 
 When you have opened the device, you must specify with what device
-address you want to communicate:
+address you want to communicate::
 
   int addr = 0x40; /* The I2C address */
 
@@ -53,7 +57,7 @@ address you want to communicate:
 
 Well, you are all set up now. You can now use SMBus commands or plain
 I2C to communicate with your device. SMBus commands are preferred if
-the device supports them. Both are illustrated below.
+the device supports them. Both are illustrated below::
 
   __u8 reg = 0x10; /* Device register to access */
   __s32 res;
@@ -100,35 +104,35 @@ Full interface description
 
 The following IOCTLs are defined:
 
-ioctl(file, I2C_SLAVE, long addr)
+``ioctl(file, I2C_SLAVE, long addr)``
   Change slave address. The address is passed in the 7 lower bits of the
   argument (except for 10 bit addresses, passed in the 10 lower bits in this
   case).
 
-ioctl(file, I2C_TENBIT, long select)
+``ioctl(file, I2C_TENBIT, long select)``
   Selects ten bit addresses if select not equals 0, selects normal 7 bit
   addresses if select equals 0. Default 0.  This request is only valid
   if the adapter has I2C_FUNC_10BIT_ADDR.
 
-ioctl(file, I2C_PEC, long select)
+``ioctl(file, I2C_PEC, long select)``
   Selects SMBus PEC (packet error checking) generation and verification
   if select not equals 0, disables if select equals 0. Default 0.
   Used only for SMBus transactions.  This request only has an effect if the
   the adapter has I2C_FUNC_SMBUS_PEC; it is still safe if not, it just
   doesn't have any effect.
 
-ioctl(file, I2C_FUNCS, unsigned long *funcs)
-  Gets the adapter functionality and puts it in *funcs.
+``ioctl(file, I2C_FUNCS, unsigned long *funcs)``
+  Gets the adapter functionality and puts it in ``*funcs``.
 
-ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
+``ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)``
   Do combined read/write transaction without stop in between.
   Only valid if the adapter has I2C_FUNC_I2C.  The argument is
-  a pointer to a
+  a pointer to a::
 
-  struct i2c_rdwr_ioctl_data {
+    struct i2c_rdwr_ioctl_data {
       struct i2c_msg *msgs;  /* ptr to array of simple messages */
       int nmsgs;             /* number of messages to exchange */
-  }
+    }
 
   The msgs[] themselves contain further pointers into data buffers.
   The function will write or read data to or from that buffers depending
@@ -136,8 +140,8 @@ ioctl(file, I2C_RDWR, struct i2c_rdwr_ioctl_data *msgset)
   The slave address and whether to use ten bit address mode has to be
   set in each message, overriding the values set with the above ioctl's.
 
-ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)
-  If possible, use the provided i2c_smbus_* methods described below instead
+``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)``
+  If possible, use the provided ``i2c_smbus_*`` methods described below instead
   of issuing direct ioctls.
 
 You can do plain i2c transactions by using read(2) and write(2) calls.
@@ -145,7 +149,8 @@ You do not need to pass the address byte; instead, set it through
 ioctl I2C_SLAVE before you try to access the device.
 
 You can do SMBus level transactions (see documentation file smbus-protocol
-for details) through the following functions:
+for details) through the following functions::
+
   __s32 i2c_smbus_write_quick(int file, __u8 value);
   __s32 i2c_smbus_read_byte(int file);
   __s32 i2c_smbus_write_byte(int file, __u8 value);
@@ -157,6 +162,7 @@ for details) through the following functions:
   __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
   __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
                                    __u8 *values);
+
 All these transactions return -1 on failure; you can read errno to see
 what happened. The 'write' transactions return 0 on success; the
 'read' transactions return the read value, except for read_block, which
@@ -174,39 +180,39 @@ Implementation details
 For the interested, here's the code flow which happens inside the kernel
 when you use the /dev interface to I2C:
 
-1* Your program opens /dev/i2c-N and calls ioctl() on it, as described in
-section "C example" above.
+1) Your program opens /dev/i2c-N and calls ioctl() on it, as described in
+   section "C example" above.
 
-2* These open() and ioctl() calls are handled by the i2c-dev kernel
-driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
-respectively. You can think of i2c-dev as a generic I2C chip driver
-that can be programmed from user-space.
+2) These open() and ioctl() calls are handled by the i2c-dev kernel
+   driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
+   respectively. You can think of i2c-dev as a generic I2C chip driver
+   that can be programmed from user-space.
 
-3* Some ioctl() calls are for administrative tasks and are handled by
-i2c-dev directly. Examples include I2C_SLAVE (set the address of the
-device you want to access) and I2C_PEC (enable or disable SMBus error
-checking on future transactions.)
+3) Some ioctl() calls are for administrative tasks and are handled by
+   i2c-dev directly. Examples include I2C_SLAVE (set the address of the
+   device you want to access) and I2C_PEC (enable or disable SMBus error
+   checking on future transactions.)
 
-4* Other ioctl() calls are converted to in-kernel function calls by
-i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
-functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
-performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().
+4) Other ioctl() calls are converted to in-kernel function calls by
+   i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
+   functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
+   performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().
 
-The i2c-dev driver is responsible for checking all the parameters that
-come from user-space for validity. After this point, there is no
-difference between these calls that came from user-space through i2c-dev
-and calls that would have been performed by kernel I2C chip drivers
-directly. This means that I2C bus drivers don't need to implement
-anything special to support access from user-space.
+   The i2c-dev driver is responsible for checking all the parameters that
+   come from user-space for validity. After this point, there is no
+   difference between these calls that came from user-space through i2c-dev
+   and calls that would have been performed by kernel I2C chip drivers
+   directly. This means that I2C bus drivers don't need to implement
+   anything special to support access from user-space.
 
-5* These i2c.h functions are wrappers to the actual implementation of
-your I2C bus driver. Each adapter must declare callback functions
-implementing these standard calls. i2c.h:i2c_get_functionality() calls
-i2c_adapter.algo->functionality(), while
-i2c-core-smbus.c:i2c_smbus_xfer() calls either
-adapter.algo->smbus_xfer() if it is implemented, or if not,
-i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls
-i2c_adapter.algo->master_xfer().
+5) These i2c.h functions are wrappers to the actual implementation of
+   your I2C bus driver. Each adapter must declare callback functions
+   implementing these standard calls. i2c.h:i2c_get_functionality() calls
+   i2c_adapter.algo->functionality(), while
+   i2c-core-smbus.c:i2c_smbus_xfer() calls either
+   adapter.algo->smbus_xfer() if it is implemented, or if not,
+   i2c-core-smbus.c:i2c_smbus_xfer_emulated() which in turn calls
+   i2c_adapter.algo->master_xfer().
 
 After your I2C bus driver has processed these requests, execution runs
 up the call chain, with almost no processing done, except by i2c-dev to
diff --git a/Documentation/i2c/DMA-considerations b/Documentation/i2c/dma-considerations.rst
similarity index 100%
rename from Documentation/i2c/DMA-considerations
rename to Documentation/i2c/dma-considerations.rst
diff --git a/Documentation/i2c/fault-codes b/Documentation/i2c/fault-codes.rst
similarity index 98%
rename from Documentation/i2c/fault-codes
rename to Documentation/i2c/fault-codes.rst
index 0cee0fc545b4..80b14e718b52 100644
--- a/Documentation/i2c/fault-codes
+++ b/Documentation/i2c/fault-codes.rst
@@ -1,3 +1,7 @@
+=====================
+I2C/SMBUS Fault Codes
+=====================
+
 This is a summary of the most important conventions for use of fault
 codes in the I2C/SMBus stack.
 
@@ -125,4 +129,3 @@ ETIMEDOUT
 	when a slave stretches clocks too far.  I2C has no such
 	timeouts, but it's normal for I2C adapters to impose some
 	arbitrary limits (much longer than SMBus!) too.
-
diff --git a/Documentation/i2c/functionality b/Documentation/i2c/functionality.rst
similarity index 91%
rename from Documentation/i2c/functionality
rename to Documentation/i2c/functionality.rst
index 4aae8ed15873..377507c56162 100644
--- a/Documentation/i2c/functionality
+++ b/Documentation/i2c/functionality.rst
@@ -1,11 +1,15 @@
+=======================
+I2C/SMBus Functionality
+=======================
+
 INTRODUCTION
 ------------
 
-Because not every I2C or SMBus adapter implements everything in the 
+Because not every I2C or SMBus adapter implements everything in the
 I2C specifications, a client can not trust that everything it needs
 is implemented when it is given the option to attach to an adapter:
 the client needs some way to check whether an adapter has the needed
-functionality. 
+functionality.
 
 
 FUNCTIONALITY CONSTANTS
@@ -14,6 +18,7 @@ FUNCTIONALITY CONSTANTS
 For the most up-to-date list of functionality constants, please check
 <uapi/linux/i2c.h>!
 
+  =============================== ==============================================
   I2C_FUNC_I2C                    Plain i2c-level commands (Pure SMBus
                                   adapters typically can not do these)
   I2C_FUNC_10BIT_ADDR             Handles the 10-bit address extensions
@@ -33,9 +38,11 @@ For the most up-to-date list of functionality constants, please check
   I2C_FUNC_SMBUS_WRITE_BLOCK_DATA Handles the SMBus write_block_data command
   I2C_FUNC_SMBUS_READ_I2C_BLOCK   Handles the SMBus read_i2c_block_data command
   I2C_FUNC_SMBUS_WRITE_I2C_BLOCK  Handles the SMBus write_i2c_block_data command
+  =============================== ==============================================
 
 A few combinations of the above flags are also defined for your convenience:
 
+  =========================       ======================================
   I2C_FUNC_SMBUS_BYTE             Handles the SMBus read_byte
                                   and write_byte commands
   I2C_FUNC_SMBUS_BYTE_DATA        Handles the SMBus read_byte_data
@@ -49,6 +56,7 @@ A few combinations of the above flags are also defined for your convenience:
   I2C_FUNC_SMBUS_EMUL             Handles all SMBus commands that can be
                                   emulated by a real I2C adapter (using
                                   the transparent emulation layer)
+  =========================       ======================================
 
 In kernel versions prior to 3.5 I2C_FUNC_NOSTART was implemented as
 part of I2C_FUNC_PROTOCOL_MANGLING.
@@ -58,11 +66,11 @@ ADAPTER IMPLEMENTATION
 ----------------------
 
 When you write a new adapter driver, you will have to implement a
-function callback `functionality'. Typical implementations are given
+function callback ``functionality``. Typical implementations are given
 below.
 
 A typical SMBus-only adapter would list all the SMBus transactions it
-supports. This example comes from the i2c-piix4 driver:
+supports. This example comes from the i2c-piix4 driver::
 
   static u32 piix4_func(struct i2c_adapter *adapter)
   {
@@ -72,7 +80,7 @@ supports. This example comes from the i2c-piix4 driver:
   }
 
 A typical full-I2C adapter would use the following (from the i2c-pxa
-driver):
+driver)::
 
   static u32 i2c_pxa_functionality(struct i2c_adapter *adap)
   {
@@ -94,7 +102,7 @@ CLIENT CHECKING
 Before a client tries to attach to an adapter, or even do tests to check
 whether one of the devices it supports is present on an adapter, it should
 check whether the needed functionality is present. The typical way to do
-this is (from the lm75 driver):
+this is (from the lm75 driver)::
 
   static int lm75_detect(...)
   {
@@ -129,7 +137,7 @@ If you try to access an adapter from a userspace program, you will have
 to use the /dev interface. You will still have to check whether the
 functionality you need is supported, of course. This is done using
 the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is
-below:
+below::
 
   int file;
   if (file = open("/dev/i2c-0", O_RDWR) < 0) {
diff --git a/Documentation/i2c/gpio-fault-injection b/Documentation/i2c/gpio-fault-injection.rst
similarity index 97%
rename from Documentation/i2c/gpio-fault-injection
rename to Documentation/i2c/gpio-fault-injection.rst
index c87f416d53dd..9dca6ec7d266 100644
--- a/Documentation/i2c/gpio-fault-injection
+++ b/Documentation/i2c/gpio-fault-injection.rst
@@ -104,10 +104,10 @@ There doesn't need to be a device at this address because arbitration lost
 should be detected beforehand. Also note, that SCL going down is monitored
 using interrupts, so the interrupt latency might cause the first bits to be not
 corrupted. A good starting point for using this fault injector on an otherwise
-idle bus is:
+idle bus is::
 
-# echo 200 > lose_arbitration &
-# i2cget -y <bus_to_test> 0x3f
+  # echo 200 > lose_arbitration &
+  # i2cget -y <bus_to_test> 0x3f
 
 Panic during transfer
 =====================
@@ -127,10 +127,10 @@ The calling process will then sleep and wait for the next bus clock. The
 process is interruptible, though.
 
 Start of a transfer is detected by waiting for SCL going down by the master
-under test.  A good starting point for using this fault injector is:
+under test.  A good starting point for using this fault injector is::
 
-# echo 0 > inject_panic &
-# i2cget -y <bus_to_test> <some_address>
+  # echo 0 > inject_panic &
+  # i2cget -y <bus_to_test> <some_address>
 
 Note that there doesn't need to be a device listening to the address you are
 using. Results may vary depending on that, though.
diff --git a/Documentation/i2c/i2c-protocol b/Documentation/i2c/i2c-protocol.rst
similarity index 83%
rename from Documentation/i2c/i2c-protocol
rename to Documentation/i2c/i2c-protocol.rst
index ff6d6cee6c7e..2f8fcf671b2e 100644
--- a/Documentation/i2c/i2c-protocol
+++ b/Documentation/i2c/i2c-protocol.rst
@@ -1,8 +1,13 @@
+============
+I2C Protocol
+============
+
 This document describes the i2c protocol. Or will, when it is finished :-)
 
 Key to symbols
 ==============
 
+=============== =============================================================
 S     (1 bit) : Start bit
 P     (1 bit) : Stop bit
 Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
@@ -15,33 +20,35 @@ Data  (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
                 for 16 bit data.
 Count (8 bits): A data byte containing the length of a block operation.
 
-[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
+[..]:           Data sent by I2C device, as opposed to data sent by the
+                host adapter.
+=============== =============================================================
 
 
 Simple send transaction
-======================
+=======================
 
-This corresponds to i2c_master_send.
+This corresponds to i2c_master_send::
 
   S Addr Wr [A] Data [A] Data [A] ... [A] Data [A] P
 
 
 Simple receive transaction
-===========================
+==========================
 
-This corresponds to i2c_master_recv
+This corresponds to i2c_master_recv::
 
   S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
 
 
 Combined transactions
-====================
+=====================
 
 This corresponds to i2c_transfer
 
 They are just like the above transactions, but instead of a stop bit P
 a start bit S is sent and the transaction continues. An example of
-a byte read, followed by a byte write:
+a byte read, followed by a byte write::
 
   S Addr Rd [A] [Data] NA S Addr Wr [A] Data [A] P
 
@@ -65,8 +72,10 @@ I2C_M_NO_RD_ACK:
 I2C_M_NOSTART:
     In a combined transaction, no 'S Addr Wr/Rd [A]' is generated at some
     point. For example, setting I2C_M_NOSTART on the second partial message
-    generates something like:
+    generates something like::
+
       S Addr Rd [A] [Data] NA Data [A] P
+
     If you set the I2C_M_NOSTART variable for the first partial message,
     we do not generate Addr, but we do generate the startbit S. This will
     probably confuse all other clients on your bus, so don't try this.
@@ -79,7 +88,8 @@ I2C_M_NOSTART:
 I2C_M_REV_DIR_ADDR:
     This toggles the Rd/Wr flag. That is, if you want to do a write, but
     need to emit an Rd instead of a Wr, or vice versa, you set this
-    flag. For example:
+    flag. For example::
+
       S Addr Rd [A] Data [A] Data [A] ... [A] Data [A] P
 
 I2C_M_STOP:
diff --git a/Documentation/i2c/i2c-stub b/Documentation/i2c/i2c-stub.rst
similarity index 93%
rename from Documentation/i2c/i2c-stub
rename to Documentation/i2c/i2c-stub.rst
index a16924fbd289..a6fc6916d6bc 100644
--- a/Documentation/i2c/i2c-stub
+++ b/Documentation/i2c/i2c-stub.rst
@@ -1,6 +1,9 @@
-MODULE: i2c-stub
+========
+i2c-stub
+========
 
-DESCRIPTION:
+Description
+===========
 
 This module is a very simple fake I2C/SMBus driver.  It implements six
 types of SMBus commands: write quick, (r/w) byte, (r/w) byte data, (r/w)
@@ -28,6 +31,7 @@ SMBus block operations. Writes can be partial. Block read commands always
 return the number of bytes selected with the largest write so far.
 
 The typical use-case is like this:
+
 	1. load this module
 	2. use i2cset (from the i2c-tools project) to pre-load some data
 	3. load the target chip driver module
@@ -36,7 +40,8 @@ The typical use-case is like this:
 There's a script named i2c-stub-from-dump in the i2c-tools package which
 can load register values automatically from a chip dump.
 
-PARAMETERS:
+Parameters
+==========
 
 int chip_addr[10]:
 	The SMBus addresses to emulate chips at.
@@ -47,18 +52,15 @@ unsigned long functionality:
 	value 0x1f0000 would only enable the quick, byte and byte data
 	commands.
 
-u8 bank_reg[10]
-u8 bank_mask[10]
-u8 bank_start[10]
-u8 bank_end[10]:
+u8 bank_reg[10], u8 bank_mask[10], u8 bank_start[10], u8 bank_end[10]:
 	Optional bank settings. They tell which bits in which register
 	select the active bank, as well as the range of banked registers.
 
-CAVEATS:
+Caveats
+=======
 
 If your target driver polls some byte or word waiting for it to change, the
 stub could lock it up.  Use i2cset to unlock it.
 
 If you spam it hard enough, printk can be lossy.  This module really wants
 something like relayfs.
-
diff --git a/Documentation/i2c/i2c-topology b/Documentation/i2c/i2c-topology.rst
similarity index 89%
rename from Documentation/i2c/i2c-topology
rename to Documentation/i2c/i2c-topology.rst
index f74d78b53d4d..0c1ae95f6a97 100644
--- a/Documentation/i2c/i2c-topology
+++ b/Documentation/i2c/i2c-topology.rst
@@ -1,3 +1,4 @@
+============
 I2C topology
 ============
 
@@ -14,6 +15,7 @@ than a straight-forward i2c bus with one adapter and one or more devices.
    that has to be operated before the device can be accessed.
 
 Etc
+===
 
 These constructs are represented as i2c adapter trees by Linux, where
 each adapter has a parent adapter (except the root adapter) and zero or
@@ -37,7 +39,9 @@ mux-locked or parent-locked muxes. As is evident from below, it can be
 useful to know if a mux is mux-locked or if it is parent-locked. The
 following list was correct at the time of writing:
 
-In drivers/i2c/muxes/
+In drivers/i2c/muxes/:
+
+======================    =============================================
 i2c-arb-gpio-challenge    Parent-locked
 i2c-mux-gpio              Normally parent-locked, mux-locked iff
                           all involved gpio pins are controlled by the
@@ -52,18 +56,25 @@ i2c-mux-pinctrl           Normally parent-locked, mux-locked iff
                           all involved pinctrl devices are controlled
                           by the same i2c root adapter that they mux.
 i2c-mux-reg               Parent-locked
+======================    =============================================
 
-In drivers/iio/
+In drivers/iio/:
+
+======================    =============================================
 gyro/mpu3050              Mux-locked
 imu/inv_mpu6050/          Mux-locked
+======================    =============================================
 
-In drivers/media/
+In drivers/media/:
+
+=======================   =============================================
 dvb-frontends/lgdt3306a   Mux-locked
 dvb-frontends/m88ds3103   Parent-locked
 dvb-frontends/rtl2830     Parent-locked
 dvb-frontends/rtl2832     Mux-locked
 dvb-frontends/si2168      Mux-locked
 usb/cx231xx/              Parent-locked
+=======================   =============================================
 
 
 Mux-locked muxes
@@ -78,6 +89,7 @@ full transaction, unrelated i2c transfers may interleave the different
 stages of the transaction. This has the benefit that the mux driver
 may be easier and cleaner to implement, but it has some caveats.
 
+==== =====================================================================
 ML1. If you build a topology with a mux-locked mux being the parent
      of a parent-locked mux, this might break the expectation from the
      parent-locked mux that the root adapter is locked during the
@@ -105,11 +117,15 @@ ML4. If any non-i2c operation in the mux driver changes the i2c mux state,
      Otherwise garbage may appear on the bus as seen from devices
      behind the mux, when an unrelated i2c transfer is in flight during
      the non-i2c mux-changing operation.
+==== =====================================================================
 
 
 Mux-locked Example
 ------------------
 
+
+::
+
                    .----------.     .--------.
     .--------.     |   mux-   |-----| dev D1 |
     |  root  |--+--|  locked  |     '--------'
@@ -148,6 +164,7 @@ adapter during the transaction are unlocked i2c transfers (using e.g.
 __i2c_transfer), or a deadlock will follow. There are a couple of
 caveats.
 
+==== ====================================================================
 PL1. If you build a topology with a parent-locked mux being the child
      of another mux, this might break a possible assumption from the
      child mux that the root adapter is unused between its select op
@@ -161,11 +178,14 @@ PL2. If select/deselect calls out to other subsystems such as gpio,
      caused by these subsystems are unlocked. This can be convoluted to
      accomplish, maybe even impossible if an acceptably clean solution
      is sought.
+==== ====================================================================
 
 
 Parent-locked Example
 ---------------------
 
+::
+
                    .----------.     .--------.
     .--------.     |  parent- |-----| dev D1 |
     |  root  |--+--|  locked  |     '--------'
@@ -177,20 +197,20 @@ Parent-locked Example
 
 When there is an access to D1, this happens:
 
- 1. Someone issues an i2c-transfer to D1.
- 2. M1 locks muxes on its parent (the root adapter in this case).
- 3. M1 locks its parent adapter.
- 4. M1 calls ->select to ready the mux.
- 5. If M1 does any i2c-transfers (on this root adapter) as part of
-    its select, those transfers must be unlocked i2c-transfers so
-    that they do not deadlock the root adapter.
- 6. M1 feeds the i2c-transfer from step 1 to the root adapter as an
-    unlocked i2c-transfer, so that it does not deadlock the parent
-    adapter.
- 7. M1 calls ->deselect, if it has one.
- 8. Same rules as in step 5, but for ->deselect.
- 9. M1 unlocks its parent adapter.
-10. M1 unlocks muxes on its parent.
+ 1.  Someone issues an i2c-transfer to D1.
+ 2.  M1 locks muxes on its parent (the root adapter in this case).
+ 3.  M1 locks its parent adapter.
+ 4.  M1 calls ->select to ready the mux.
+ 5.  If M1 does any i2c-transfers (on this root adapter) as part of
+     its select, those transfers must be unlocked i2c-transfers so
+     that they do not deadlock the root adapter.
+ 6.  M1 feeds the i2c-transfer from step 1 to the root adapter as an
+     unlocked i2c-transfer, so that it does not deadlock the parent
+     adapter.
+ 7.  M1 calls ->deselect, if it has one.
+ 8.  Same rules as in step 5, but for ->deselect.
+ 9.  M1 unlocks its parent adapter.
+ 10. M1 unlocks muxes on its parent.
 
 
 This means that accesses to both D2 and D3 are locked out for the full
@@ -203,7 +223,7 @@ Complex Examples
 Parent-locked mux as parent of parent-locked mux
 ------------------------------------------------
 
-This is a useful topology, but it can be bad.
+This is a useful topology, but it can be bad::
 
                    .----------.     .----------.     .--------.
     .--------.     |  parent- |-----|  parent- |-----| dev D1 |
@@ -227,7 +247,7 @@ through and be seen by the M2 adapter, thus closing M2 prematurely.
 Mux-locked mux as parent of mux-locked mux
 ------------------------------------------
 
-This is a good topology.
+This is a good topology::
 
                    .----------.     .----------.     .--------.
     .--------.     |   mux-   |-----|   mux-   |-----| dev D1 |
@@ -248,7 +268,7 @@ are still possibly interleaved.
 Mux-locked mux as parent of parent-locked mux
 ---------------------------------------------
 
-This is probably a bad topology.
+This is probably a bad topology::
 
                    .----------.     .----------.     .--------.
     .--------.     |   mux-   |-----|  parent- |-----| dev D1 |
@@ -282,7 +302,7 @@ auto-closing, the topology is fine.
 Parent-locked mux as parent of mux-locked mux
 ---------------------------------------------
 
-This is a good topology.
+This is a good topology::
 
                    .----------.     .----------.     .--------.
     .--------.     |  parent- |-----|   mux-   |-----| dev D1 |
@@ -306,7 +326,7 @@ adapter is locked directly.
 Two mux-locked sibling muxes
 ----------------------------
 
-This is a good topology.
+This is a good topology::
 
                                     .--------.
                    .----------.  .--| dev D1 |
@@ -330,7 +350,7 @@ accesses to D5 may be interleaved at any time.
 Two parent-locked sibling muxes
 -------------------------------
 
-This is a good topology.
+This is a good topology::
 
                                     .--------.
                    .----------.  .--| dev D1 |
@@ -354,7 +374,7 @@ out.
 Mux-locked and parent-locked sibling muxes
 ------------------------------------------
 
-This is a good topology.
+This is a good topology::
 
                                     .--------.
                    .----------.  .--| dev D1 |
diff --git a/Documentation/i2c/index.rst b/Documentation/i2c/index.rst
new file mode 100644
index 000000000000..cd8d020f7ac5
--- /dev/null
+++ b/Documentation/i2c/index.rst
@@ -0,0 +1,37 @@
+. SPDX-License-Identifier: GPL-2.0
+
+===================
+I2C/SMBus Subsystem
+===================
+
+.. toctree::
+   :maxdepth: 1
+
+   dev-interface
+   dma-considerations
+   fault-codes
+   functionality
+   gpio-fault-injection
+   i2c-protocol
+   i2c-stub
+   i2c-topology
+   instantiating-devices
+   old-module-parameters
+   slave-eeprom-backend
+   slave-interface
+   smbus-protocol
+   summary
+   ten-bit-addresses
+   upgrading-clients
+   writing-clients
+
+   muxes/i2c-mux-gpio
+
+   busses/index
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/i2c/instantiating-devices b/Documentation/i2c/instantiating-devices.rst
similarity index 93%
rename from Documentation/i2c/instantiating-devices
rename to Documentation/i2c/instantiating-devices.rst
index 345e9ea8281a..1238f1fa3382 100644
--- a/Documentation/i2c/instantiating-devices
+++ b/Documentation/i2c/instantiating-devices.rst
@@ -1,3 +1,4 @@
+==============================
 How to instantiate I2C devices
 ==============================
 
@@ -17,9 +18,9 @@ which is known in advance. It is thus possible to pre-declare the I2C
 devices which live on this bus. This is done with an array of struct
 i2c_board_info which is registered by calling i2c_register_board_info().
 
-Example (from omap2 h4):
+Example (from omap2 h4)::
 
-static struct i2c_board_info h4_i2c_board_info[] __initdata = {
+  static struct i2c_board_info h4_i2c_board_info[] __initdata = {
 	{
 		I2C_BOARD_INFO("isp1301_omap", 0x2d),
 		.irq		= OMAP_GPIO_IRQ(125),
@@ -32,15 +33,15 @@ static struct i2c_board_info h4_i2c_board_info[] __initdata = {
 		I2C_BOARD_INFO("24c01", 0x57),
 		.platform_data	= &m24c01,
 	},
-};
+  };
 
-static void __init omap_h4_init(void)
-{
+  static void __init omap_h4_init(void)
+  {
 	(...)
 	i2c_register_board_info(1, h4_i2c_board_info,
 			ARRAY_SIZE(h4_i2c_board_info));
 	(...)
-}
+  }
 
 The above code declares 3 devices on I2C bus 1, including their respective
 addresses and custom data needed by their drivers. When the I2C bus in
@@ -57,7 +58,7 @@ Method 1b: Declare the I2C devices via devicetree
 This method has the same implications as method 1a. The declaration of I2C
 devices is here done via devicetree as subnodes of the master controller.
 
-Example:
+Example::
 
 	i2c1: i2c@400a0000 {
 		/* ... master properties skipped ... */
@@ -99,20 +100,20 @@ bus in advance, so the method 1 described above can't be used. Instead,
 you can instantiate your I2C devices explicitly. This is done by filling
 a struct i2c_board_info and calling i2c_new_device().
 
-Example (from the sfe4001 network driver):
+Example (from the sfe4001 network driver)::
 
-static struct i2c_board_info sfe4001_hwmon_info = {
+  static struct i2c_board_info sfe4001_hwmon_info = {
 	I2C_BOARD_INFO("max6647", 0x4e),
-};
+  };
 
-int sfe4001_init(struct efx_nic *efx)
-{
+  int sfe4001_init(struct efx_nic *efx)
+  {
 	(...)
 	efx->board_info.hwmon_client =
 		i2c_new_device(&efx->i2c_adap, &sfe4001_hwmon_info);
 
 	(...)
-}
+  }
 
 The above code instantiates 1 I2C device on the I2C bus which is on the
 network adapter in question.
@@ -124,12 +125,12 @@ it may have different addresses from one board to the next (manufacturer
 changing its design without notice). In this case, you can call
 i2c_new_probed_device() instead of i2c_new_device().
 
-Example (from the nxp OHCI driver):
+Example (from the nxp OHCI driver)::
 
-static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
+  static const unsigned short normal_i2c[] = { 0x2c, 0x2d, I2C_CLIENT_END };
 
-static int usb_hcd_nxp_probe(struct platform_device *pdev)
-{
+  static int usb_hcd_nxp_probe(struct platform_device *pdev)
+  {
 	(...)
 	struct i2c_adapter *i2c_adap;
 	struct i2c_board_info i2c_info;
@@ -142,7 +143,7 @@ static int usb_hcd_nxp_probe(struct platform_device *pdev)
 						   normal_i2c, NULL);
 	i2c_put_adapter(i2c_adap);
 	(...)
-}
+  }
 
 The above code instantiates up to 1 I2C device on the I2C bus which is on
 the OHCI adapter in question. It first tries at address 0x2c, if nothing
@@ -172,6 +173,7 @@ explicitly. Instead, i2c-core will probe for such devices as soon as their
 drivers are loaded, and if any is found, an I2C device will be
 instantiated automatically. In order to prevent any misbehavior of this
 mechanism, the following restrictions apply:
+
 * The I2C device driver must implement the detect() method, which
   identifies a supported device by reading from arbitrary registers.
 * Only buses which are likely to have a supported device and agree to be
@@ -189,6 +191,7 @@ first.
 Those of you familiar with the i2c subsystem of 2.4 kernels and early 2.6
 kernels will find out that this method 3 is essentially similar to what
 was done there. Two significant differences are:
+
 * Probing is only one way to instantiate I2C devices now, while it was the
   only way back then. Where possible, methods 1 and 2 should be preferred.
   Method 3 should only be used when there is no other way, as it can have
@@ -224,11 +227,13 @@ device. As no two devices can live at the same address on a given I2C
 segment, the address is sufficient to uniquely identify the device to be
 deleted.
 
-Example:
-# echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
+Example::
+
+  # echo eeprom 0x50 > /sys/bus/i2c/devices/i2c-3/new_device
 
 While this interface should only be used when in-kernel device declaration
 can't be done, there is a variety of cases where it can be helpful:
+
 * The I2C driver usually detects devices (method 3 above) but the bus
   segment your device lives on doesn't have the proper class bit set and
   thus detection doesn't trigger.
diff --git a/Documentation/i2c/muxes/i2c-mux-gpio b/Documentation/i2c/muxes/i2c-mux-gpio.rst
similarity index 85%
rename from Documentation/i2c/muxes/i2c-mux-gpio
rename to Documentation/i2c/muxes/i2c-mux-gpio.rst
index 893ecdfe6e43..7d27444035c3 100644
--- a/Documentation/i2c/muxes/i2c-mux-gpio
+++ b/Documentation/i2c/muxes/i2c-mux-gpio.rst
@@ -1,4 +1,6 @@
+==========================
 Kernel driver i2c-mux-gpio
+==========================
 
 Author: Peter Korsgaard <peter.korsgaard@barco.com>
 
@@ -8,7 +10,7 @@ Description
 i2c-mux-gpio is an i2c mux driver providing access to I2C bus segments
 from a master I2C bus and a hardware MUX controlled through GPIO pins.
 
-E.G.:
+E.G.::
 
   ----------              ----------  Bus segment 1   - - - - -
  |          | SCL/SDA    |          |-------------- |           |
@@ -33,20 +35,20 @@ bus, the number of bus segments to create and the GPIO pins used
 to control it. See include/linux/platform_data/i2c-mux-gpio.h for details.
 
 E.G. something like this for a MUX providing 4 bus segments
-controlled through 3 GPIO pins:
+controlled through 3 GPIO pins::
 
-#include <linux/platform_data/i2c-mux-gpio.h>
-#include <linux/platform_device.h>
+  #include <linux/platform_data/i2c-mux-gpio.h>
+  #include <linux/platform_device.h>
 
-static const unsigned myboard_gpiomux_gpios[] = {
+  static const unsigned myboard_gpiomux_gpios[] = {
 	AT91_PIN_PC26, AT91_PIN_PC25, AT91_PIN_PC24
-};
+  };
 
-static const unsigned myboard_gpiomux_values[] = {
+  static const unsigned myboard_gpiomux_values[] = {
 	0, 1, 2, 3
-};
+  };
 
-static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
+  static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
 	.parent		= 1,
 	.base_nr	= 2, /* optional */
 	.values		= myboard_gpiomux_values,
@@ -54,15 +56,15 @@ static struct i2c_mux_gpio_platform_data myboard_i2cmux_data = {
 	.gpios		= myboard_gpiomux_gpios,
 	.n_gpios	= ARRAY_SIZE(myboard_gpiomux_gpios),
 	.idle		= 4, /* optional */
-};
+  };
 
-static struct platform_device myboard_i2cmux = {
+  static struct platform_device myboard_i2cmux = {
 	.name		= "i2c-mux-gpio",
 	.id		= 0,
 	.dev		= {
 		.platform_data	= &myboard_i2cmux_data,
 	},
-};
+  };
 
 If you don't know the absolute GPIO pin numbers at registration time,
 you can instead provide a chip name (.chip_name) and relative GPIO pin
diff --git a/Documentation/i2c/old-module-parameters b/Documentation/i2c/old-module-parameters.rst
similarity index 75%
rename from Documentation/i2c/old-module-parameters
rename to Documentation/i2c/old-module-parameters.rst
index 8e2b629d533c..a1939512ad66 100644
--- a/Documentation/i2c/old-module-parameters
+++ b/Documentation/i2c/old-module-parameters.rst
@@ -1,3 +1,4 @@
+=================================================
 I2C device driver binding control from user-space
 =================================================
 
@@ -19,23 +20,27 @@ Below is a mapping from the old module parameters to the new interface.
 Attaching a driver to an I2C device
 -----------------------------------
 
-Old method (module parameters):
-# modprobe <driver> probe=1,0x2d
-# modprobe <driver> force=1,0x2d
-# modprobe <driver> force_<device>=1,0x2d
+Old method (module parameters)::
 
-New method (sysfs interface):
-# echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device
+  # modprobe <driver> probe=1,0x2d
+  # modprobe <driver> force=1,0x2d
+  # modprobe <driver> force_<device>=1,0x2d
+
+New method (sysfs interface)::
+
+  # echo <device> 0x2d > /sys/bus/i2c/devices/i2c-1/new_device
 
 Preventing a driver from attaching to an I2C device
 ---------------------------------------------------
 
-Old method (module parameters):
-# modprobe <driver> ignore=1,0x2f
+Old method (module parameters)::
 
-New method (sysfs interface):
-# echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device
-# modprobe <driver>
+  # modprobe <driver> ignore=1,0x2f
+
+New method (sysfs interface)::
+
+  # echo dummy 0x2f > /sys/bus/i2c/devices/i2c-1/new_device
+  # modprobe <driver>
 
 Of course, it is important to instantiate the "dummy" device before loading
 the driver. The dummy device will be handled by i2c-core itself, preventing
diff --git a/Documentation/i2c/slave-eeprom-backend b/Documentation/i2c/slave-eeprom-backend.rst
similarity index 90%
rename from Documentation/i2c/slave-eeprom-backend
rename to Documentation/i2c/slave-eeprom-backend.rst
index 04f8d8a9b817..0b8cd83698e0 100644
--- a/Documentation/i2c/slave-eeprom-backend
+++ b/Documentation/i2c/slave-eeprom-backend.rst
@@ -1,3 +1,4 @@
+==============================
 Linux I2C slave eeprom backend
 ==============================
 
@@ -5,10 +6,9 @@ by Wolfram Sang <wsa@sang-engineering.com> in 2014-15
 
 This is a proof-of-concept backend which acts like an EEPROM on the connected
 I2C bus. The memory contents can be modified from userspace via this file
-located in sysfs:
+located in sysfs::
 
 	/sys/bus/i2c/devices/<device-directory>/slave-eeprom
 
 As of 2015, Linux doesn't support poll on binary sysfs files, so there is no
 notification when another master changed the content.
-
diff --git a/Documentation/i2c/slave-interface b/Documentation/i2c/slave-interface.rst
similarity index 94%
rename from Documentation/i2c/slave-interface
rename to Documentation/i2c/slave-interface.rst
index 7e2a228f21bc..c769bd6a15bf 100644
--- a/Documentation/i2c/slave-interface
+++ b/Documentation/i2c/slave-interface.rst
@@ -1,3 +1,4 @@
+=====================================
 Linux I2C slave interface description
 =====================================
 
@@ -12,7 +13,7 @@ EEPROM, the Linux I2C slave can access the content via sysfs and handle data as
 needed. The backend driver and the I2C bus driver communicate via events. Here
 is a small graph visualizing the data flow and the means by which data is
 transported. The dotted line marks only one example. The backend could also
-use a character device, be in-kernel only, or something completely different:
+use a character device, be in-kernel only, or something completely different::
 
 
               e.g. sysfs        I2C slave events        I/O registers
@@ -35,7 +36,7 @@ them as described in the document 'instantiating-devices'. The only difference
 is that i2c slave backends have their own address space. So, you have to add
 0x1000 to the address you would originally request. An example for
 instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64
-on bus 1:
+on bus 1::
 
   # echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device
 
@@ -54,7 +55,7 @@ drivers and writing backends will be given.
 I2C slave events
 ----------------
 
-The bus driver sends an event to the backend using the following function:
+The bus driver sends an event to the backend using the following function::
 
 	ret = i2c_slave_event(client, event, &val)
 
@@ -69,8 +70,9 @@ Event types:
 
 * I2C_SLAVE_WRITE_REQUESTED (mandatory)
 
-'val': unused
-'ret': always 0
+  'val': unused
+
+  'ret': always 0
 
 Another I2C master wants to write data to us. This event should be sent once
 our own address and the write bit was detected. The data did not arrive yet, so
@@ -79,8 +81,9 @@ to be done, though.
 
 * I2C_SLAVE_READ_REQUESTED (mandatory)
 
-'val': backend returns first byte to be sent
-'ret': always 0
+  'val': backend returns first byte to be sent
+
+  'ret': always 0
 
 Another I2C master wants to read data from us. This event should be sent once
 our own address and the read bit was detected. After returning, the bus driver
@@ -88,8 +91,9 @@ should transmit the first byte.
 
 * I2C_SLAVE_WRITE_RECEIVED (mandatory)
 
-'val': bus driver delivers received byte
-'ret': 0 if the byte should be acked, some errno if the byte should be nacked
+  'val': bus driver delivers received byte
+
+  'ret': 0 if the byte should be acked, some errno if the byte should be nacked
 
 Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret'
 is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte
@@ -97,8 +101,9 @@ should be nacked.
 
 * I2C_SLAVE_READ_PROCESSED (mandatory)
 
-'val': backend returns next byte to be sent
-'ret': always 0
+  'val': backend returns next byte to be sent
+
+  'ret': always 0
 
 The bus driver requests the next byte to be sent to another I2C master in
 'val'. Important: This does not mean that the previous byte has been acked, it
@@ -111,8 +116,9 @@ your backend, though.
 
 * I2C_SLAVE_STOP (mandatory)
 
-'val': unused
-'ret': always 0
+  'val': unused
+
+  'ret': always 0
 
 A stop condition was received. This can happen anytime and the backend should
 reset its state machine for I2C transfers to be able to receive new requests.
@@ -190,4 +196,3 @@ this time of writing. Some points to keep in mind when using buffers:
 * A master can send STOP at any time. For partially transferred buffers, this
   means additional code to handle this exception. Such code tends to be
   error-prone.
-
diff --git a/Documentation/i2c/smbus-protocol b/Documentation/i2c/smbus-protocol.rst
similarity index 82%
rename from Documentation/i2c/smbus-protocol
rename to Documentation/i2c/smbus-protocol.rst
index 092d474f5843..e30eb1d274c6 100644
--- a/Documentation/i2c/smbus-protocol
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -1,3 +1,4 @@
+======================
 SMBus Protocol Summary
 ======================
 
@@ -27,17 +28,18 @@ Each transaction type corresponds to a functionality flag. Before calling a
 transaction function, a device driver should always check (just once) for
 the corresponding functionality flag to ensure that the underlying I2C
 adapter supports the transaction in question. See
-<file:Documentation/i2c/functionality> for the details.
+<file:Documentation/i2c/functionality.rst> for the details.
 
 
 Key to symbols
 ==============
 
+=============== =============================================================
 S     (1 bit) : Start bit
 P     (1 bit) : Stop bit
 Rd/Wr (1 bit) : Read/Write bit. Rd equals 1, Wr equals 0.
-A, NA (1 bit) : Accept and reverse accept bit. 
-Addr  (7 bits): I2C 7 bit address. Note that this can be expanded as usual to 
+A, NA (1 bit) : Accept and reverse accept bit.
+Addr  (7 bits): I2C 7 bit address. Note that this can be expanded as usual to
                 get a 10 bit I2C address.
 Comm  (8 bits): Command byte, a data byte which often selects a register on
                 the device.
@@ -45,15 +47,17 @@ Data  (8 bits): A plain data byte. Sometimes, I write DataLow, DataHigh
                 for 16 bit data.
 Count (8 bits): A data byte containing the length of a block operation.
 
-[..]: Data sent by I2C device, as opposed to data sent by the host adapter.
+[..]:           Data sent by I2C device, as opposed to data sent by the host
+                adapter.
+=============== =============================================================
 
 
 SMBus Quick Command
 ===================
 
-This sends a single bit to the device, at the place of the Rd/Wr bit.
+This sends a single bit to the device, at the place of the Rd/Wr bit::
 
-A Addr Rd/Wr [A] P
+  A Addr Rd/Wr [A] P
 
 Functionality flag: I2C_FUNC_SMBUS_QUICK
 
@@ -64,9 +68,9 @@ SMBus Receive Byte:  i2c_smbus_read_byte()
 This reads a single byte from a device, without specifying a device
 register. Some devices are so simple that this interface is enough; for
 others, it is a shorthand if you want to read the same register as in
-the previous SMBus command.
+the previous SMBus command::
 
-S Addr Rd [A] [Data] NA P
+  S Addr Rd [A] [Data] NA P
 
 Functionality flag: I2C_FUNC_SMBUS_READ_BYTE
 
@@ -77,7 +81,9 @@ SMBus Send Byte:  i2c_smbus_write_byte()
 This operation is the reverse of Receive Byte: it sends a single byte
 to a device.  See Receive Byte for more information.
 
-S Addr Wr [A] Data [A] P
+::
+
+  S Addr Wr [A] Data [A] P
 
 Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE
 
@@ -86,9 +92,9 @@ SMBus Read Byte:  i2c_smbus_read_byte_data()
 ============================================
 
 This reads a single byte from a device, from a designated register.
-The register is specified through the Comm byte.
+The register is specified through the Comm byte::
 
-S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
+  S Addr Wr [A] Comm [A] S Addr Rd [A] [Data] NA P
 
 Functionality flag: I2C_FUNC_SMBUS_READ_BYTE_DATA
 
@@ -98,9 +104,9 @@ SMBus Read Word:  i2c_smbus_read_word_data()
 
 This operation is very like Read Byte; again, data is read from a
 device, from a designated register that is specified through the Comm
-byte. But this time, the data is a complete word (16 bits).
+byte. But this time, the data is a complete word (16 bits)::
 
-S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
+  S Addr Wr [A] Comm [A] S Addr Rd [A] [DataLow] A [DataHigh] NA P
 
 Functionality flag: I2C_FUNC_SMBUS_READ_WORD_DATA
 
@@ -116,7 +122,9 @@ This writes a single byte to a device, to a designated register. The
 register is specified through the Comm byte. This is the opposite of
 the Read Byte operation.
 
-S Addr Wr [A] Comm [A] Data [A] P
+::
+
+  S Addr Wr [A] Comm [A] Data [A] P
 
 Functionality flag: I2C_FUNC_SMBUS_WRITE_BYTE_DATA
 
@@ -126,9 +134,9 @@ SMBus Write Word:  i2c_smbus_write_word_data()
 
 This is the opposite of the Read Word operation. 16 bits
 of data is written to a device, to the designated register that is
-specified through the Comm byte. 
+specified through the Comm byte.::
 
-S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
+  S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] P
 
 Functionality flag: I2C_FUNC_SMBUS_WRITE_WORD_DATA
 
@@ -141,10 +149,10 @@ SMBus Process Call:
 ===================
 
 This command selects a device register (through the Comm byte), sends
-16 bits of data to it, and reads 16 bits of data in return.
+16 bits of data to it, and reads 16 bits of data in return::
 
-S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A] 
-                             S Addr Rd [A] [DataLow] A [DataHigh] NA P
+  S Addr Wr [A] Comm [A] DataLow [A] DataHigh [A]
+                               S Addr Rd [A] [DataLow] A [DataHigh] NA P
 
 Functionality flag: I2C_FUNC_SMBUS_PROC_CALL
 
@@ -152,12 +160,14 @@ Functionality flag: I2C_FUNC_SMBUS_PROC_CALL
 SMBus Block Read:  i2c_smbus_read_block_data()
 ==============================================
 
-This command reads a block of up to 32 bytes from a device, from a 
+This command reads a block of up to 32 bytes from a device, from a
 designated register that is specified through the Comm byte. The amount
 of data is specified by the device in the Count byte.
 
-S Addr Wr [A] Comm [A] 
-           S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
+::
+
+  S Addr Wr [A] Comm [A]
+             S Addr Rd [A] [Count] A [Data] A [Data] A ... A [Data] NA P
 
 Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA
 
@@ -165,11 +175,13 @@ Functionality flag: I2C_FUNC_SMBUS_READ_BLOCK_DATA
 SMBus Block Write:  i2c_smbus_write_block_data()
 ================================================
 
-The opposite of the Block Read command, this writes up to 32 bytes to 
+The opposite of the Block Read command, this writes up to 32 bytes to
 a device, to a designated register that is specified through the
 Comm byte. The amount of data is specified in the Count byte.
 
-S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
+::
+
+  S Addr Wr [A] Comm [A] Count [A] Data [A] Data [A] ... [A] Data [A] P
 
 Functionality flag: I2C_FUNC_SMBUS_WRITE_BLOCK_DATA
 
@@ -181,10 +193,10 @@ SMBus Block Write - Block Read Process Call was introduced in
 Revision 2.0 of the specification.
 
 This command selects a device register (through the Comm byte), sends
-1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return.
+1 to 31 bytes of data to it, and reads 1 to 31 bytes of data in return::
 
-S Addr Wr [A] Comm [A] Count [A] Data [A] ...
-                             S Addr Rd [A] [Count] A [Data] ... A P
+  S Addr Wr [A] Comm [A] Count [A] Data [A] ...
+                               S Addr Rd [A] [Count] A [Data] ... A P
 
 Functionality flag: I2C_FUNC_SMBUS_BLOCK_PROC_CALL
 
@@ -197,9 +209,12 @@ SMBus host acting as a slave.
 It is the same form as Write Word, with the command code replaced by the
 alerting device's address.
 
-[S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
+::
+
+  [S] [HostAddr] [Wr] A [DevAddr] A [DataLow] A [DataHigh] A [P]
 
 This is implemented in the following way in the Linux kernel:
+
 * I2C bus drivers which support SMBus Host Notify should report
   I2C_FUNC_SMBUS_HOST_NOTIFY.
 * I2C bus drivers trigger SMBus Host Notify by a call to
@@ -241,6 +256,7 @@ single interrupt pin on the SMBus master, while still allowing the master
 to know which slave triggered the interrupt.
 
 This is implemented the following way in the Linux kernel:
+
 * I2C bus drivers which support SMBus alert should call
   i2c_setup_smbus_alert() to setup SMBus alert support.
 * I2C drivers for devices which can trigger SMBus alerts should implement
@@ -261,11 +277,11 @@ but the SMBus layer places a limit of 32 bytes.
 I2C Block Read:  i2c_smbus_read_i2c_block_data()
 ================================================
 
-This command reads a block of bytes from a device, from a 
-designated register that is specified through the Comm byte.
+This command reads a block of bytes from a device, from a
+designated register that is specified through the Comm byte::
 
-S Addr Wr [A] Comm [A] 
-           S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
+  S Addr Wr [A] Comm [A]
+             S Addr Rd [A] [Data] A [Data] A ... A [Data] NA P
 
 Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK
 
@@ -273,11 +289,13 @@ Functionality flag: I2C_FUNC_SMBUS_READ_I2C_BLOCK
 I2C Block Write:  i2c_smbus_write_i2c_block_data()
 ==================================================
 
-The opposite of the Block Read command, this writes bytes to 
+The opposite of the Block Read command, this writes bytes to
 a device, to a designated register that is specified through the
 Comm byte. Note that command lengths of 0, 2, or more bytes are
 supported as they are indistinguishable from data.
 
-S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
+::
+
+  S Addr Wr [A] Comm [A] Data [A] Data [A] ... [A] Data [A] P
 
 Functionality flag: I2C_FUNC_SMBUS_WRITE_I2C_BLOCK
diff --git a/Documentation/i2c/summary b/Documentation/i2c/summary.rst
similarity index 96%
rename from Documentation/i2c/summary
rename to Documentation/i2c/summary.rst
index 809541ab352f..3a24eac17375 100644
--- a/Documentation/i2c/summary
+++ b/Documentation/i2c/summary.rst
@@ -1,7 +1,8 @@
+=============
 I2C and SMBus
 =============
 
-I2C (pronounce: I squared C) is a protocol developed by Philips. It is a 
+I2C (pronounce: I squared C) is a protocol developed by Philips. It is a
 slow two-wire protocol (variable speed, up to 400 kHz), with a high speed
 extension (3.4 MHz).  It provides an inexpensive bus for connecting many
 types of devices with infrequent or low bandwidth communications needs.
@@ -24,7 +25,8 @@ implement all the common SMBus protocol semantics or messages.
 Terminology
 ===========
 
-When we talk about I2C, we use the following terms:
+When we talk about I2C, we use the following terms::
+
   Bus    -> Algorithm
             Adapter
   Device -> Driver
diff --git a/Documentation/i2c/ten-bit-addresses b/Documentation/i2c/ten-bit-addresses.rst
similarity index 95%
rename from Documentation/i2c/ten-bit-addresses
rename to Documentation/i2c/ten-bit-addresses.rst
index 7b2d11e53a49..5c765aff16d5 100644
--- a/Documentation/i2c/ten-bit-addresses
+++ b/Documentation/i2c/ten-bit-addresses.rst
@@ -1,3 +1,7 @@
+=====================
+I2C Ten-bit Addresses
+=====================
+
 The I2C protocol knows about two kinds of device addresses: normal 7 bit
 addresses, and an extended set of 10 bit addresses. The sets of addresses
 do not intersect: the 7 bit address 0x10 is not the same as the 10 bit
@@ -12,6 +16,7 @@ See the I2C specification for the details.
 
 The current 10 bit address support is minimal. It should work, however
 you can expect some problems along the way:
+
 * Not all bus drivers support 10-bit addresses. Some don't because the
   hardware doesn't support them (SMBus doesn't require 10-bit address
   support for example), some don't because nobody bothered adding the
diff --git a/Documentation/i2c/upgrading-clients b/Documentation/i2c/upgrading-clients.rst
similarity index 54%
rename from Documentation/i2c/upgrading-clients
rename to Documentation/i2c/upgrading-clients.rst
index 96392cc5b5c7..27d29032c138 100644
--- a/Documentation/i2c/upgrading-clients
+++ b/Documentation/i2c/upgrading-clients.rst
@@ -1,3 +1,4 @@
+=================================================
 Upgrading I2C Drivers to the new 2.6 Driver Model
 =================================================
 
@@ -13,21 +14,22 @@ the old to the new new binding methods.
 Example old-style driver
 ------------------------
 
+::
 
-struct example_state {
+  struct example_state {
 	struct i2c_client	client;
 	....
-};
+  };
 
-static struct i2c_driver example_driver;
+  static struct i2c_driver example_driver;
 
-static unsigned short ignore[] = { I2C_CLIENT_END };
-static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
+  static unsigned short ignore[] = { I2C_CLIENT_END };
+  static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
 
-I2C_CLIENT_INSMOD;
+  I2C_CLIENT_INSMOD;
 
-static int example_attach(struct i2c_adapter *adap, int addr, int kind)
-{
+  static int example_attach(struct i2c_adapter *adap, int addr, int kind)
+  {
 	struct example_state *state;
 	struct device *dev = &adap->dev;  /* to use for dev_ reports */
 	int ret;
@@ -59,31 +61,31 @@ static int example_attach(struct i2c_adapter *adap, int addr, int kind)
 	dev_info(dev, "example client created\n");
 
 	return 0;
-}
+  }
 
-static int example_detach(struct i2c_client *client)
-{
+  static int example_detach(struct i2c_client *client)
+  {
 	struct example_state *state = i2c_get_clientdata(client);
 
 	i2c_detach_client(client);
 	kfree(state);
 	return 0;
-}
+  }
 
-static int example_attach_adapter(struct i2c_adapter *adap)
-{
+  static int example_attach_adapter(struct i2c_adapter *adap)
+  {
 	return i2c_probe(adap, &addr_data, example_attach);
-}
+  }
 
-static struct i2c_driver example_driver = {
- 	.driver		= {
+  static struct i2c_driver example_driver = {
+	.driver		= {
 		.owner		= THIS_MODULE,
 		.name		= "example",
 		.pm		= &example_pm_ops,
 	},
 	.attach_adapter = example_attach_adapter,
 	.detach_client	= example_detach,
-};
+  };
 
 
 Updating the client
@@ -93,38 +95,38 @@ The new style binding model will check against a list of supported
 devices and their associated address supplied by the code registering
 the busses. This means that the driver .attach_adapter and
 .detach_client methods can be removed, along with the addr_data,
-as follows:
+as follows::
 
-- static struct i2c_driver example_driver;
+  - static struct i2c_driver example_driver;
 
-- static unsigned short ignore[] = { I2C_CLIENT_END };
-- static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
+  - static unsigned short ignore[] = { I2C_CLIENT_END };
+  - static unsigned short normal_addr[] = { OUR_ADDR, I2C_CLIENT_END };
 
-- I2C_CLIENT_INSMOD;
+  - I2C_CLIENT_INSMOD;
 
-- static int example_attach_adapter(struct i2c_adapter *adap)
-- {
-- 	return i2c_probe(adap, &addr_data, example_attach);
-- }
+  - static int example_attach_adapter(struct i2c_adapter *adap)
+  - {
+  - 	return i2c_probe(adap, &addr_data, example_attach);
+  - }
 
- static struct i2c_driver example_driver = {
--	.attach_adapter = example_attach_adapter,
--	.detach_client	= example_detach,
- }
+    static struct i2c_driver example_driver = {
+  -	.attach_adapter = example_attach_adapter,
+  -	.detach_client	= example_detach,
+    }
 
-Add the probe and remove methods to the i2c_driver, as so:
+Add the probe and remove methods to the i2c_driver, as so::
 
- static struct i2c_driver example_driver = {
-+	.probe		= example_probe,
-+	.remove		= example_remove,
- }
+   static struct i2c_driver example_driver = {
+  +	.probe		= example_probe,
+  +	.remove		= example_remove,
+   }
 
 Change the example_attach method to accept the new parameters
-which include the i2c_client that it will be working with:
+which include the i2c_client that it will be working with::
 
-- static int example_attach(struct i2c_adapter *adap, int addr, int kind)
-+ static int example_probe(struct i2c_client *client,
-+			   const struct i2c_device_id *id)
+  - static int example_attach(struct i2c_adapter *adap, int addr, int kind)
+  + static int example_probe(struct i2c_client *client,
+  +			   const struct i2c_device_id *id)
 
 Change the name of example_attach to example_probe to align it with the
 i2c_driver entry names. The rest of the probe routine will now need to be
@@ -132,57 +134,59 @@ changed as the i2c_client has already been setup for use.
 
 The necessary client fields have already been setup before
 the probe function is called, so the following client setup
-can be removed:
+can be removed::
 
--	example->client.addr    = addr;
--	example->client.flags   = 0;
--	example->client.adapter = adap;
--
--	strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
+  -	example->client.addr    = addr;
+  -	example->client.flags   = 0;
+  -	example->client.adapter = adap;
+  -
+  -	strscpy(client->i2c_client.name, "example", sizeof(client->i2c_client.name));
 
-The i2c_set_clientdata is now:
+The i2c_set_clientdata is now::
 
--	i2c_set_clientdata(&state->client, state);
-+	i2c_set_clientdata(client, state);
+  -	i2c_set_clientdata(&state->client, state);
+  +	i2c_set_clientdata(client, state);
 
 The call to i2c_attach_client is no longer needed, if the probe
 routine exits successfully, then the driver will be automatically
-attached by the core. Change the probe routine as so:
+attached by the core. Change the probe routine as so::
 
--	ret = i2c_attach_client(&state->i2c_client);
--	if (ret < 0) {
--		dev_err(dev, "failed to attach client\n");
--		kfree(state);
--		return ret;
--	}
+  -	ret = i2c_attach_client(&state->i2c_client);
+  -	if (ret < 0) {
+  -		dev_err(dev, "failed to attach client\n");
+  -		kfree(state);
+  -		return ret;
+  -	}
 
 
 Remove the storage of 'struct i2c_client' from the 'struct example_state'
 as we are provided with the i2c_client in our example_probe. Instead we
 store a pointer to it for when it is needed.
 
-struct example_state {
--	struct i2c_client	client;
-+	struct i2c_client	*client;
+::
 
-the new i2c client as so:
+  struct example_state {
+  -	struct i2c_client	client;
+  +	struct i2c_client	*client;
 
--	struct device *dev = &adap->dev;  /* to use for dev_ reports */
-+ 	struct device *dev = &i2c_client->dev;  /* to use for dev_ reports */
+the new i2c client as so::
+
+  -	struct device *dev = &adap->dev;  /* to use for dev_ reports */
+  + 	struct device *dev = &i2c_client->dev;  /* to use for dev_ reports */
 
 And remove the change after our client is attached, as the driver no
-longer needs to register a new client structure with the core:
+longer needs to register a new client structure with the core::
 
--	dev = &state->i2c_client.dev;
+  -	dev = &state->i2c_client.dev;
 
 In the probe routine, ensure that the new state has the client stored
-in it:
+in it::
 
-static int example_probe(struct i2c_client *i2c_client,
+  static int example_probe(struct i2c_client *i2c_client,
 			 const struct i2c_device_id *id)
-{
+  {
 	struct example_state *state;
- 	struct device *dev = &i2c_client->dev;
+	struct device *dev = &i2c_client->dev;
 	int ret;
 
 	state = kzalloc(sizeof(struct example_state), GFP_KERNEL);
@@ -191,48 +195,50 @@ static int example_probe(struct i2c_client *i2c_client,
 		return -ENOMEM;
 	}
 
-+	state->client = i2c_client;
+  +	state->client = i2c_client;
 
 Update the detach method, by changing the name to _remove and
 to delete the i2c_detach_client call. It is possible that you
 can also remove the ret variable as it is not needed for any
 of the core functions.
 
-- static int example_detach(struct i2c_client *client)
-+ static int example_remove(struct i2c_client *client)
-{
+::
+
+  - static int example_detach(struct i2c_client *client)
+  + static int example_remove(struct i2c_client *client)
+  {
 	struct example_state *state = i2c_get_clientdata(client);
 
--	i2c_detach_client(client);
+  -	i2c_detach_client(client);
 
 And finally ensure that we have the correct ID table for the i2c-core
-and other utilities:
+and other utilities::
 
-+ struct i2c_device_id example_idtable[] = {
-+       { "example", 0 },
-+       { }
-+};
-+
-+MODULE_DEVICE_TABLE(i2c, example_idtable);
+  + struct i2c_device_id example_idtable[] = {
+  +       { "example", 0 },
+  +       { }
+  +};
+  +
+  +MODULE_DEVICE_TABLE(i2c, example_idtable);
 
-static struct i2c_driver example_driver = {
- 	.driver		= {
+  static struct i2c_driver example_driver = {
+	.driver		= {
 		.owner		= THIS_MODULE,
 		.name		= "example",
 	},
-+	.id_table	= example_ids,
+  +	.id_table	= example_ids,
 
 
-Our driver should now look like this:
+Our driver should now look like this::
 
-struct example_state {
+  struct example_state {
 	struct i2c_client	*client;
 	....
-};
+  };
 
-static int example_probe(struct i2c_client *client,
-		     	 const struct i2c_device_id *id)
-{
+  static int example_probe(struct i2c_client *client,
+			 const struct i2c_device_id *id)
+  {
 	struct example_state *state;
 	struct device *dev = &client->dev;
 
@@ -250,25 +256,25 @@ static int example_probe(struct i2c_client *client,
 	dev_info(dev, "example client created\n");
 
 	return 0;
-}
+  }
 
-static int example_remove(struct i2c_client *client)
-{
+  static int example_remove(struct i2c_client *client)
+  {
 	struct example_state *state = i2c_get_clientdata(client);
 
 	kfree(state);
 	return 0;
-}
+  }
 
-static struct i2c_device_id example_idtable[] = {
+  static struct i2c_device_id example_idtable[] = {
 	{ "example", 0 },
 	{ }
-};
+  };
 
-MODULE_DEVICE_TABLE(i2c, example_idtable);
+  MODULE_DEVICE_TABLE(i2c, example_idtable);
 
-static struct i2c_driver example_driver = {
- 	.driver		= {
+  static struct i2c_driver example_driver = {
+	.driver		= {
 		.owner		= THIS_MODULE,
 		.name		= "example",
 		.pm		= &example_pm_ops,
@@ -276,4 +282,4 @@ static struct i2c_driver example_driver = {
 	.id_table	= example_idtable,
 	.probe		= example_probe,
 	.remove		= example_remove,
-};
+  };
diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients.rst
similarity index 91%
rename from Documentation/i2c/writing-clients
rename to Documentation/i2c/writing-clients.rst
index a755b141fa4a..dddf0a14ab7c 100644
--- a/Documentation/i2c/writing-clients
+++ b/Documentation/i2c/writing-clients.rst
@@ -1,3 +1,7 @@
+===================
+Writing I2C Clients
+===================
+
 This is a small guide for those who want to write kernel drivers for I2C
 or SMBus devices, using Linux as the protocol host/master (not slave).
 
@@ -12,7 +16,7 @@ General remarks
 Try to keep the kernel namespace as clean as possible. The best way to
 do this is to use a unique prefix for all global symbols. This is
 especially important for exported symbols, but it is a good idea to do
-it for non-exported symbols too. We will use the prefix `foo_' in this
+it for non-exported symbols too. We will use the prefix ``foo_`` in this
 tutorial.
 
 
@@ -25,15 +29,17 @@ routines, and should be zero-initialized except for fields with data you
 provide.  A client structure holds device-specific information like the
 driver model device node, and its I2C address.
 
-static struct i2c_device_id foo_idtable[] = {
+::
+
+  static struct i2c_device_id foo_idtable[] = {
 	{ "foo", my_id_for_foo },
 	{ "bar", my_id_for_bar },
 	{ }
-};
+  };
 
-MODULE_DEVICE_TABLE(i2c, foo_idtable);
+  MODULE_DEVICE_TABLE(i2c, foo_idtable);
 
-static struct i2c_driver foo_driver = {
+  static struct i2c_driver foo_driver = {
 	.driver = {
 		.name	= "foo",
 		.pm	= &foo_pm_ops,	/* optional */
@@ -49,7 +55,7 @@ static struct i2c_driver foo_driver = {
 
 	.shutdown	= foo_shutdown,	/* optional */
 	.command	= foo_command,	/* optional, deprecated */
-}
+  }
 
 The name field is the driver name, and must not contain spaces.  It
 should match the module name (if the driver can be compiled as a module),
@@ -64,16 +70,18 @@ below.
 Extra client data
 =================
 
-Each client structure has a special `data' field that can point to any
+Each client structure has a special ``data`` field that can point to any
 structure at all.  You should use this to keep device-specific data.
 
+::
+
 	/* store the value */
 	void i2c_set_clientdata(struct i2c_client *client, void *data);
 
 	/* retrieve the value */
 	void *i2c_get_clientdata(const struct i2c_client *client);
 
-Note that starting with kernel 2.6.34, you don't have to set the `data' field
+Note that starting with kernel 2.6.34, you don't have to set the ``data`` field
 to NULL in remove() or if probe() failed anymore. The i2c-core does this
 automatically on these occasions. Those are also the only times the core will
 touch this field.
@@ -92,25 +100,25 @@ but many chips have some kind of register-value idea that can easily
 be encapsulated.
 
 The below functions are simple examples, and should not be copied
-literally.
+literally::
 
-int foo_read_value(struct i2c_client *client, u8 reg)
-{
+  int foo_read_value(struct i2c_client *client, u8 reg)
+  {
 	if (reg < 0x10)	/* byte-sized register */
 		return i2c_smbus_read_byte_data(client, reg);
 	else		/* word-sized register */
 		return i2c_smbus_read_word_data(client, reg);
-}
+  }
 
-int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
-{
+  int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
+  {
 	if (reg == 0x10)	/* Impossible to write - driver error! */
 		return -EINVAL;
 	else if (reg < 0x10)	/* byte-sized register */
 		return i2c_smbus_write_byte_data(client, reg, value);
 	else			/* word-sized register */
 		return i2c_smbus_write_word_data(client, reg, value);
-}
+  }
 
 
 Probing and attaching
@@ -145,6 +153,8 @@ I2C device drivers using this binding model work just like any other
 kind of driver in Linux:  they provide a probe() method to bind to
 those devices, and a remove() method to unbind.
 
+::
+
 	static int foo_probe(struct i2c_client *client,
 			     const struct i2c_device_id *id);
 	static int foo_remove(struct i2c_client *client);
@@ -240,37 +250,41 @@ When the kernel is booted, or when your foo driver module is inserted,
 you have to do some initializing. Fortunately, just registering the
 driver module is usually enough.
 
-static int __init foo_init(void)
-{
+::
+
+  static int __init foo_init(void)
+  {
 	return i2c_add_driver(&foo_driver);
-}
-module_init(foo_init);
+  }
+  module_init(foo_init);
 
-static void __exit foo_cleanup(void)
-{
+  static void __exit foo_cleanup(void)
+  {
 	i2c_del_driver(&foo_driver);
-}
-module_exit(foo_cleanup);
+  }
+  module_exit(foo_cleanup);
 
-The module_i2c_driver() macro can be used to reduce above code.
+  The module_i2c_driver() macro can be used to reduce above code.
 
-module_i2c_driver(foo_driver);
+  module_i2c_driver(foo_driver);
 
-Note that some functions are marked by `__init'.  These functions can
+Note that some functions are marked by ``__init``.  These functions can
 be removed after kernel booting (or module loading) is completed.
-Likewise, functions marked by `__exit' are dropped by the compiler when
+Likewise, functions marked by ``__exit`` are dropped by the compiler when
 the code is built into the kernel, as they would never be called.
 
 
 Driver Information
 ==================
 
-/* Substitute your own name and email address */
-MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
-MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
+::
 
-/* a few non-GPL license types are also allowed */
-MODULE_LICENSE("GPL");
+  /* Substitute your own name and email address */
+  MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
+  MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
+
+  /* a few non-GPL license types are also allowed */
+  MODULE_LICENSE("GPL");
 
 
 Power Management
@@ -323,6 +337,8 @@ commands, but only some of them understand plain I2C!
 Plain I2C communication
 -----------------------
 
+::
+
 	int i2c_master_send(struct i2c_client *client, const char *buf,
 			    int count);
 	int i2c_master_recv(struct i2c_client *client, char *buf, int count);
@@ -334,6 +350,8 @@ to read/write (must be less than the length of the buffer, also should be
 less than 64k since msg.len is u16.) Returned is the actual number of bytes
 read/written.
 
+::
+
 	int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg,
 			 int num);
 
@@ -343,13 +361,15 @@ stop bit is sent between transaction. The i2c_msg structure contains
 for each message the client address, the number of bytes of the message
 and the message data itself.
 
-You can read the file `i2c-protocol' for more information about the
+You can read the file ``i2c-protocol`` for more information about the
 actual I2C protocol.
 
 
 SMBus communication
 -------------------
 
+::
+
 	s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
 			   unsigned short flags, char read_write, u8 command,
 			   int size, union i2c_smbus_data *data);
@@ -357,6 +377,8 @@ SMBus communication
 This is the generic SMBus function. All functions below are implemented
 in terms of it. Never use this function directly!
 
+::
+
 	s32 i2c_smbus_read_byte(struct i2c_client *client);
 	s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value);
 	s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command);
@@ -376,7 +398,7 @@ in terms of it. Never use this function directly!
 					   const u8 *values);
 
 These ones were removed from i2c-core because they had no users, but could
-be added back later if needed:
+be added back later if needed::
 
 	s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value);
 	s32 i2c_smbus_process_call(struct i2c_client *client,
@@ -389,7 +411,7 @@ transactions return 0 on success; the 'read' transactions return the read
 value, except for block transactions, which return the number of values
 read. The block buffers need not be longer than 32 bytes.
 
-You can read the file `smbus-protocol' for more information about the
+You can read the file ``smbus-protocol`` for more information about the
 actual SMBus protocol.
 
 
@@ -397,7 +419,7 @@ General purpose routines
 ========================
 
 Below all general purpose routines are listed, that were not mentioned
-before.
+before::
 
 	/* Return the adapter number for a specific adapter */
 	int i2c_adapter_id(struct i2c_adapter *adap);
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 68ae2a4d689d..f6ee5333587d 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -104,6 +104,7 @@ needed).
    fb/index
    fpga/index
    hid/index
+   i2c/index
    iio/index
    infiniband/index
    leds/index
diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602
index a45702865a38..0feffd5af411 100644
--- a/Documentation/spi/spi-sc18is602
+++ b/Documentation/spi/spi-sc18is602
@@ -17,7 +17,7 @@ kernel's SPI core subsystem.
 
 The driver does not probe for supported chips, since the SI18IS602/603 does not
 support Chip ID registers. You will have to instantiate the devices explicitly.
-Please see Documentation/i2c/instantiating-devices for details.
+Please see Documentation/i2c/instantiating-devices.rst for details.
 
 
 Usage Notes
diff --git a/MAINTAINERS b/MAINTAINERS
index 15b58d5947a3..8fcb0c65ab91 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -666,7 +666,7 @@ ALI1563 I2C DRIVER
 M:	Rudolf Marek <r.marek@assembler.cz>
 L:	linux-i2c@vger.kernel.org
 S:	Maintained
-F:	Documentation/i2c/busses/i2c-ali1563
+F:	Documentation/i2c/busses/i2c-ali1563.rst
 F:	drivers/i2c/busses/i2c-ali1563.c
 
 ALLEGRO DVT VIDEO IP CORE DRIVER
@@ -6731,7 +6731,7 @@ L:	linux-i2c@vger.kernel.org
 S:	Supported
 F:	drivers/i2c/muxes/i2c-mux-gpio.c
 F:	include/linux/platform_data/i2c-mux-gpio.h
-F:	Documentation/i2c/muxes/i2c-mux-gpio
+F:	Documentation/i2c/muxes/i2c-mux-gpio.rst
 
 GENERIC HDLC (WAN) DRIVERS
 M:	Krzysztof Halasa <khc@pm.waw.pl>
@@ -7487,14 +7487,14 @@ I2C CONTROLLER DRIVER FOR NVIDIA GPU
 M:	Ajay Gupta <ajayg@nvidia.com>
 L:	linux-i2c@vger.kernel.org
 S:	Maintained
-F:	Documentation/i2c/busses/i2c-nvidia-gpu
+F:	Documentation/i2c/busses/i2c-nvidia-gpu.rst
 F:	drivers/i2c/busses/i2c-nvidia-gpu.c
 
 I2C MUXES
 M:	Peter Rosin <peda@axentia.se>
 L:	linux-i2c@vger.kernel.org
 S:	Maintained
-F:	Documentation/i2c/i2c-topology
+F:	Documentation/i2c/i2c-topology.rst
 F:	Documentation/i2c/muxes/
 F:	Documentation/devicetree/bindings/i2c/i2c-mux*
 F:	Documentation/devicetree/bindings/i2c/i2c-arb*
@@ -7514,8 +7514,8 @@ I2C OVER PARALLEL PORT
 M:	Jean Delvare <jdelvare@suse.com>
 L:	linux-i2c@vger.kernel.org
 S:	Maintained
-F:	Documentation/i2c/busses/i2c-parport
-F:	Documentation/i2c/busses/i2c-parport-light
+F:	Documentation/i2c/busses/i2c-parport.rst
+F:	Documentation/i2c/busses/i2c-parport-light.rst
 F:	drivers/i2c/busses/i2c-parport.c
 F:	drivers/i2c/busses/i2c-parport-light.c
 
@@ -7549,7 +7549,7 @@ I2C-TAOS-EVM DRIVER
 M:	Jean Delvare <jdelvare@suse.com>
 L:	linux-i2c@vger.kernel.org
 S:	Maintained
-F:	Documentation/i2c/busses/i2c-taos-evm
+F:	Documentation/i2c/busses/i2c-taos-evm.rst
 F:	drivers/i2c/busses/i2c-taos-evm.c
 
 I2C-TINY-USB DRIVER
@@ -7563,19 +7563,19 @@ I2C/SMBUS CONTROLLER DRIVERS FOR PC
 M:	Jean Delvare <jdelvare@suse.com>
 L:	linux-i2c@vger.kernel.org
 S:	Maintained
-F:	Documentation/i2c/busses/i2c-ali1535
-F:	Documentation/i2c/busses/i2c-ali1563
-F:	Documentation/i2c/busses/i2c-ali15x3
-F:	Documentation/i2c/busses/i2c-amd756
-F:	Documentation/i2c/busses/i2c-amd8111
-F:	Documentation/i2c/busses/i2c-i801
-F:	Documentation/i2c/busses/i2c-nforce2
-F:	Documentation/i2c/busses/i2c-piix4
-F:	Documentation/i2c/busses/i2c-sis5595
-F:	Documentation/i2c/busses/i2c-sis630
-F:	Documentation/i2c/busses/i2c-sis96x
-F:	Documentation/i2c/busses/i2c-via
-F:	Documentation/i2c/busses/i2c-viapro
+F:	Documentation/i2c/busses/i2c-ali1535.rst
+F:	Documentation/i2c/busses/i2c-ali1563.rst
+F:	Documentation/i2c/busses/i2c-ali15x3.rst
+F:	Documentation/i2c/busses/i2c-amd756.rst
+F:	Documentation/i2c/busses/i2c-amd8111.rst
+F:	Documentation/i2c/busses/i2c-i801.rst
+F:	Documentation/i2c/busses/i2c-nforce2.rst
+F:	Documentation/i2c/busses/i2c-piix4.rst
+F:	Documentation/i2c/busses/i2c-sis5595.rst
+F:	Documentation/i2c/busses/i2c-sis630.rst
+F:	Documentation/i2c/busses/i2c-sis96x.rst
+F:	Documentation/i2c/busses/i2c-via.rst
+F:	Documentation/i2c/busses/i2c-viapro.rst
 F:	drivers/i2c/busses/i2c-ali1535.c
 F:	drivers/i2c/busses/i2c-ali1563.c
 F:	drivers/i2c/busses/i2c-ali15x3.c
@@ -7604,7 +7604,7 @@ M:	Seth Heasley <seth.heasley@intel.com>
 M:	Neil Horman <nhorman@tuxdriver.com>
 L:	linux-i2c@vger.kernel.org
 F:	drivers/i2c/busses/i2c-ismt.c
-F:	Documentation/i2c/busses/i2c-ismt
+F:	Documentation/i2c/busses/i2c-ismt.rst
 
 I2C/SMBUS STUB DRIVER
 M:	Jean Delvare <jdelvare@suse.com>
@@ -10345,7 +10345,7 @@ L:	linux-i2c@vger.kernel.org
 S:	Supported
 F:	drivers/i2c/busses/i2c-mlxcpld.c
 F:	drivers/i2c/muxes/i2c-mux-mlxcpld.c
-F:	Documentation/i2c/busses/i2c-mlxcpld
+F:	Documentation/i2c/busses/i2c-mlxcpld.rst
 
 MELLANOX MLXCPLD LED DRIVER
 M:	Vadim Pasternak <vadimp@mellanox.com>
@@ -11966,7 +11966,7 @@ M:	Andrew Lunn <andrew@lunn.ch>
 L:	linux-i2c@vger.kernel.org
 S:	Maintained
 F:	Documentation/devicetree/bindings/i2c/i2c-ocores.txt
-F:	Documentation/i2c/busses/i2c-ocores
+F:	Documentation/i2c/busses/i2c-ocores.rst
 F:	drivers/i2c/busses/i2c-ocores.c
 F:	include/linux/platform_data/i2c-ocores.h
 
@@ -14271,7 +14271,7 @@ F:	net/sctp/
 SCx200 CPU SUPPORT
 M:	Jim Cromie <jim.cromie@gmail.com>
 S:	Odd Fixes
-F:	Documentation/i2c/busses/scx200_acb
+F:	Documentation/i2c/busses/scx200_acb.rst
 F:	arch/x86/platform/scx200/
 F:	drivers/watchdog/scx200_wdt.c
 F:	drivers/i2c/busses/scx200*
diff --git a/drivers/hwmon/atxp1.c b/drivers/hwmon/atxp1.c
index e232fa948833..79b8df258371 100644
--- a/drivers/hwmon/atxp1.c
+++ b/drivers/hwmon/atxp1.c
@@ -5,7 +5,7 @@
  *
  * The ATXP1 can reside on I2C addresses 0x37 or 0x4e. The chip is
  * not auto-detected by the driver and must be instantiated explicitly.
- * See Documentation/i2c/instantiating-devices for more information.
+ * See Documentation/i2c/instantiating-devices.rst for more information.
  */
 
 #include <linux/kernel.h>
diff --git a/drivers/hwmon/smm665.c b/drivers/hwmon/smm665.c
index d8c91c2cb8cf..9ae0dc28b9cf 100644
--- a/drivers/hwmon/smm665.c
+++ b/drivers/hwmon/smm665.c
@@ -197,7 +197,7 @@ static int smm665_read_adc(struct smm665_data *data, int adc)
 	if (rv != -ENXIO) {
 		/*
 		 * We expect ENXIO to reflect NACK
-		 * (per Documentation/i2c/fault-codes).
+		 * (per Documentation/i2c/fault-codes.rst).
 		 * Everything else is an error.
 		 */
 		dev_dbg(&client->dev,
diff --git a/drivers/i2c/Kconfig b/drivers/i2c/Kconfig
index abedd55a1264..1474e57ecafc 100644
--- a/drivers/i2c/Kconfig
+++ b/drivers/i2c/Kconfig
@@ -54,7 +54,7 @@ config I2C_CHARDEV
 	  Say Y here to use i2c-* device files, usually found in the /dev
 	  directory on your system.  They make it possible to have user-space
 	  programs use the I2C bus.  Information on how to do this is
-	  contained in the file <file:Documentation/i2c/dev-interface>.
+	  contained in the file <file:Documentation/i2c/dev-interface.rst>.
 
 	  This support is also available as a module.  If so, the module 
 	  will be called i2c-dev.
@@ -107,7 +107,7 @@ config I2C_STUB
 	  especially for certain kinds of sensor chips.
 
 	  If you do build this module, be sure to read the notes and warnings
-	  in <file:Documentation/i2c/i2c-stub>.
+	  in <file:Documentation/i2c/i2c-stub.rst>.
 
 	  If you don't know what to do here, definitely say N.
 
diff --git a/drivers/i2c/busses/Kconfig b/drivers/i2c/busses/Kconfig
index 09367fc014c3..22fcf554257b 100644
--- a/drivers/i2c/busses/Kconfig
+++ b/drivers/i2c/busses/Kconfig
@@ -1206,7 +1206,7 @@ config I2C_PARPORT
 	  and makes it easier to add support for new devices.
 
 	  An adapter type parameter is now mandatory.  Please read the file
-	  Documentation/i2c/busses/i2c-parport for details.
+	  Documentation/i2c/busses/i2c-parport.rst for details.
 
 	  Another driver exists, named i2c-parport-light, which doesn't depend
 	  on the parport driver.  This is meant for embedded systems. Don't say
diff --git a/drivers/i2c/busses/i2c-i801.c b/drivers/i2c/busses/i2c-i801.c
index f2956936c3f2..c2f087d20420 100644
--- a/drivers/i2c/busses/i2c-i801.c
+++ b/drivers/i2c/busses/i2c-i801.c
@@ -77,7 +77,7 @@
  * SMBus Host Notify			yes
  * Interrupt processing			yes
  *
- * See the file Documentation/i2c/busses/i2c-i801 for details.
+ * See the file Documentation/i2c/busses/i2c-i801.rst for details.
  */
 
 #include <linux/interrupt.h>
diff --git a/drivers/i2c/busses/i2c-taos-evm.c b/drivers/i2c/busses/i2c-taos-evm.c
index c82e78f57386..37347c93e8e0 100644
--- a/drivers/i2c/busses/i2c-taos-evm.c
+++ b/drivers/i2c/busses/i2c-taos-evm.c
@@ -125,7 +125,7 @@ static int taos_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
 			/*
 			 * Voluntarily dropping error code of kstrtou8 since all
 			 * error code that it could return are invalid according
-			 * to Documentation/i2c/fault-codes.
+			 * to Documentation/i2c/fault-codes.rst.
 			 */
 			if (kstrtou8(p + 1, 16, &data->byte))
 				return -EPROTO;
diff --git a/drivers/i2c/i2c-core-base.c b/drivers/i2c/i2c-core-base.c
index f26ed495d384..2e6dcf8ecbc9 100644
--- a/drivers/i2c/i2c-core-base.c
+++ b/drivers/i2c/i2c-core-base.c
@@ -2206,7 +2206,7 @@ static int i2c_detect_address(struct i2c_client *temp_client,
 			dev_warn(&adapter->dev,
 				"This adapter will soon drop class based instantiation of devices. "
 				"Please make sure client 0x%02x gets instantiated by other means. "
-				"Check 'Documentation/i2c/instantiating-devices' for details.\n",
+				"Check 'Documentation/i2c/instantiating-devices.rst' for details.\n",
 				info.addr);
 
 		dev_dbg(&adapter->dev, "Creating %s at 0x%02x\n",
@@ -2236,7 +2236,7 @@ static int i2c_detect(struct i2c_adapter *adapter, struct i2c_driver *driver)
 	if (adapter->class == I2C_CLASS_DEPRECATED) {
 		dev_dbg(&adapter->dev,
 			"This adapter dropped support for I2C classes and won't auto-detect %s devices anymore. "
-			"If you need it, check 'Documentation/i2c/instantiating-devices' for alternatives.\n",
+			"If you need it, check 'Documentation/i2c/instantiating-devices.rst' for alternatives.\n",
 			driver->driver.name);
 		return 0;
 	}
diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c
index 8f99c005458a..d28974ad9e0e 100644
--- a/drivers/iio/dummy/iio_simple_dummy.c
+++ b/drivers/iio/dummy/iio_simple_dummy.c
@@ -693,7 +693,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
  * Varies depending on bus type of the device. As there is no device
  * here, call probe directly. For information on device registration
  * i2c:
- * Documentation/i2c/writing-clients
+ * Documentation/i2c/writing-clients.rst
  * spi:
  * Documentation/spi/spi-summary
  */
diff --git a/drivers/rtc/rtc-ds1374.c b/drivers/rtc/rtc-ds1374.c
index 225a8df1d4e9..367497914c10 100644
--- a/drivers/rtc/rtc-ds1374.c
+++ b/drivers/rtc/rtc-ds1374.c
@@ -14,7 +14,7 @@
  */
 /*
  * It would be more efficient to use i2c msgs/i2c_transfer directly but, as
- * recommened in .../Documentation/i2c/writing-clients section
+ * recommended in .../Documentation/i2c/writing-clients.rst section
  * "Sending and receiving", using SMBus level communication is preferred.
  */
 
diff --git a/include/linux/i2c.h b/include/linux/i2c.h
index fa5552c2307b..c0a78c069117 100644
--- a/include/linux/i2c.h
+++ b/include/linux/i2c.h
@@ -521,7 +521,7 @@ i2c_register_board_info(int busnum, struct i2c_board_info const *info,
  *
  * The return codes from the @master_xfer{_atomic} fields should indicate the
  * type of error code that occurred during the transfer, as documented in the
- * Kernel Documentation file Documentation/i2c/fault-codes.
+ * Kernel Documentation file Documentation/i2c/fault-codes.rst.
  */
 struct i2c_algorithm {
 	/*
-- 
2.21.0

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

* [PATCH v2 07/26] docs: w1: convert to ReST and add to the kAPI group of docs
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (9 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Evgeniy Polyakov, linux-doc

The 1wire documentation was written with w1 developers in
mind, so, it makes sense to add it together with the driver-api
set.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/ABI/stable/sysfs-bus-w1         |  2 +-
 .../ABI/stable/sysfs-driver-w1_ds28e04        |  4 +-
 .../ABI/stable/sysfs-driver-w1_ds28ea00       |  2 +-
 Documentation/index.rst                       |  1 +
 Documentation/w1/index.rst                    | 21 +++++
 .../w1/masters/{ds2482 => ds2482.rst}         | 16 +++-
 .../w1/masters/{ds2490 => ds2490.rst}         |  6 +-
 Documentation/w1/masters/index.rst            | 14 +++
 .../w1/masters/{mxc-w1 => mxc-w1.rst}         | 13 ++-
 .../w1/masters/{omap-hdq => omap-hdq.rst}     | 12 +--
 .../w1/masters/{w1-gpio => w1-gpio.rst}       | 21 +++--
 Documentation/w1/slaves/index.rst             | 16 ++++
 .../w1/slaves/{w1_ds2406 => w1_ds2406.rst}    |  4 +-
 .../w1/slaves/{w1_ds2413 => w1_ds2413.rst}    |  9 ++
 .../w1/slaves/{w1_ds2423 => w1_ds2423.rst}    | 27 +++---
 .../w1/slaves/{w1_ds2438 => w1_ds2438.rst}    | 10 ++-
 .../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst}  |  5 ++
 .../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst}  | 16 ++--
 .../w1/slaves/{w1_therm => w1_therm.rst}      | 11 ++-
 .../w1/{w1.generic => w1-generic.rst}         | 88 ++++++++++--------
 .../w1/{w1.netlink => w1-netlink.rst}         | 89 +++++++++++--------
 21 files changed, 263 insertions(+), 124 deletions(-)
 create mode 100644 Documentation/w1/index.rst
 rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
 rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
 create mode 100644 Documentation/w1/masters/index.rst
 rename Documentation/w1/masters/{mxc-w1 => mxc-w1.rst} (33%)
 rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
 rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
 create mode 100644 Documentation/w1/slaves/index.rst
 rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (96%)
 rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
 rename Documentation/w1/slaves/{w1_ds2423 => w1_ds2423.rst} (48%)
 rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
 rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
 rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
 rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
 rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
 rename Documentation/w1/{w1.netlink => w1-netlink.rst} (77%)

diff --git a/Documentation/ABI/stable/sysfs-bus-w1 b/Documentation/ABI/stable/sysfs-bus-w1
index 140d85b4ae92..992dfb183ed0 100644
--- a/Documentation/ABI/stable/sysfs-bus-w1
+++ b/Documentation/ABI/stable/sysfs-bus-w1
@@ -6,6 +6,6 @@ Description:	Bus scanning interval, microseconds component.
 		control systems are attached/generate presence for as short as
 		100 ms - hence the tens-to-hundreds milliseconds scan intervals
 		are required.
-		see Documentation/w1/w1.generic for detailed information.
+		see Documentation/w1/w1-generic.rst for detailed information.
 Users:		any user space application which wants to know bus scanning
 		interval
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
index 26579ee868c9..3e1c1fa8d54d 100644
--- a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04
@@ -2,7 +2,7 @@ What:		/sys/bus/w1/devices/.../pio
 Date:		May 2012
 Contact:	Markus Franke <franm@hrz.tu-chemnitz.de>
 Description:	read/write the contents of the two PIO's of the DS28E04-100
-		see Documentation/w1/slaves/w1_ds28e04 for detailed information
+		see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
 Users:		any user space application which wants to communicate with DS28E04-100
 
 
@@ -11,5 +11,5 @@ What:		/sys/bus/w1/devices/.../eeprom
 Date:		May 2012
 Contact:	Markus Franke <franm@hrz.tu-chemnitz.de>
 Description:	read/write the contents of the EEPROM memory of the DS28E04-100
-		see Documentation/w1/slaves/w1_ds28e04 for detailed information
+		see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
 Users:		any user space application which wants to communicate with DS28E04-100
diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
index e928def14f28..534e63731a49 100644
--- a/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
+++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28ea00
@@ -2,5 +2,5 @@ What:		/sys/bus/w1/devices/.../w1_seq
 Date:		Apr 2015
 Contact:	Matt Campbell <mattrcampbell@gmail.com>
 Description:	Support for the DS28EA00 chain sequence function
-		see Documentation/w1/slaves/w1_therm for detailed information
+		see Documentation/w1/slaves/w1_therm.rst for detailed information
 Users:		any user space application which wants to communicate with DS28EA00
diff --git a/Documentation/index.rst b/Documentation/index.rst
index f6ee5333587d..e53c379dcb78 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -115,6 +115,7 @@ needed).
    power/index
    target/index
    timers/index
+   w1/index
    watchdog/index
    input/index
    hwmon/index
diff --git a/Documentation/w1/index.rst b/Documentation/w1/index.rst
new file mode 100644
index 000000000000..57cba81865e2
--- /dev/null
+++ b/Documentation/w1/index.rst
@@ -0,0 +1,21 @@
+. SPDX-License-Identifier: GPL-2.0
+
+================
+1-Wire Subsystem
+================
+
+.. toctree::
+   :maxdepth: 1
+
+
+   w1-generic.rst
+   w1-netlink.rst
+   masters/index
+   slaves/index
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/w1/masters/ds2482 b/Documentation/w1/masters/ds2482.rst
similarity index 71%
rename from Documentation/w1/masters/ds2482
rename to Documentation/w1/masters/ds2482.rst
index 56f8edace6ac..17ebe8f660cd 100644
--- a/Documentation/w1/masters/ds2482
+++ b/Documentation/w1/masters/ds2482.rst
@@ -1,13 +1,19 @@
+====================
 Kernel driver ds2482
 ====================
 
 Supported chips:
+
   * Maxim DS2482-100, Maxim DS2482-800
+
     Prefix: 'ds2482'
+
     Addresses scanned: None
+
     Datasheets:
-        http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
-        http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
+
+        - http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
+        - http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
 
 Author: Ben Gardner <bgardner@wabtec.com>
 
@@ -23,9 +29,11 @@ General Remarks
 ---------------
 
 Valid addresses are 0x18, 0x19, 0x1a, and 0x1b.
+
 However, the device cannot be detected without writing to the i2c bus, so no
 detection is done. You should instantiate the device explicitly.
 
-$ modprobe ds2482
-$ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
+::
 
+  $ modprobe ds2482
+  $ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
diff --git a/Documentation/w1/masters/ds2490 b/Documentation/w1/masters/ds2490.rst
similarity index 98%
rename from Documentation/w1/masters/ds2490
rename to Documentation/w1/masters/ds2490.rst
index 3e091151dd80..7e5b50f9c0f5 100644
--- a/Documentation/w1/masters/ds2490
+++ b/Documentation/w1/masters/ds2490.rst
@@ -1,7 +1,9 @@
+====================
 Kernel driver ds2490
 ====================
 
 Supported chips:
+
   * Maxim DS2490 based
 
 Author: Evgeniy Polyakov <johnpol@2ka.mipt.ru>
@@ -18,6 +20,7 @@ which has 0x81 family ID integrated chip and DS2490
 low-level operational chip.
 
 Notes and limitations.
+
 - The weak pullup current is a minimum of 0.9mA and maximum of 6.0mA.
 - The 5V strong pullup is supported with a minimum of 5.9mA and a
   maximum of 30.4 mA.  (From DS2490.pdf)
@@ -65,4 +68,5 @@ Notes and limitations.
   reattaching would clear the problem.  usbmon output in the guest and
   host did not explain the problem.  My guess is a bug in either qemu
   or the host OS and more likely the host OS.
--- 03-06-2008 David Fries <David@Fries.net>
+
+03-06-2008 David Fries <David@Fries.net>
diff --git a/Documentation/w1/masters/index.rst b/Documentation/w1/masters/index.rst
new file mode 100644
index 000000000000..4442a98850ad
--- /dev/null
+++ b/Documentation/w1/masters/index.rst
@@ -0,0 +1,14 @@
+. SPDX-License-Identifier: GPL-2.0
+
+=====================
+1-wire Master Drivers
+=====================
+
+.. toctree::
+   :maxdepth: 1
+
+   ds2482
+   ds2490
+   mxc-w1
+   omap-hdq
+   w1-gpio
diff --git a/Documentation/w1/masters/mxc-w1 b/Documentation/w1/masters/mxc-w1.rst
similarity index 33%
rename from Documentation/w1/masters/mxc-w1
rename to Documentation/w1/masters/mxc-w1.rst
index 38be1ad65532..334f9893103f 100644
--- a/Documentation/w1/masters/mxc-w1
+++ b/Documentation/w1/masters/mxc-w1.rst
@@ -1,12 +1,17 @@
+====================
 Kernel driver mxc_w1
 ====================
 
 Supported chips:
+
   * Freescale MX27, MX31 and probably other i.MX SoCs
+
     Datasheets:
-        http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
-	http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=
-	Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
 
-Author: Originally based on Freescale code, prepared for mainline by
+        - http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
+	- http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
+
+Author:
+
+	Originally based on Freescale code, prepared for mainline by
 	Sascha Hauer <s.hauer@pengutronix.de>
diff --git a/Documentation/w1/masters/omap-hdq b/Documentation/w1/masters/omap-hdq.rst
similarity index 90%
rename from Documentation/w1/masters/omap-hdq
rename to Documentation/w1/masters/omap-hdq.rst
index 234522709a5f..345298a59e50 100644
--- a/Documentation/w1/masters/omap-hdq
+++ b/Documentation/w1/masters/omap-hdq.rst
@@ -1,9 +1,10 @@
-Kernel driver for omap HDQ/1-wire module.
+========================================
+Kernel driver for omap HDQ/1-wire module
 ========================================
 
 Supported chips:
 ================
-	HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
+HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
 
 A useful link about HDQ basics:
 ===============================
@@ -40,9 +41,10 @@ driver(drivers/w1/slaves/w1_bq27000.c) sets the ID to 1.
 Please note to load both the modules with a different ID if required, but note
 that the ID used should be same for both master and slave driver loading.
 
-e.g:
-insmod omap_hdq.ko W1_ID=2
-inamod w1_bq27000.ko F_ID=2
+e.g::
+
+  insmod omap_hdq.ko W1_ID=2
+  inamod w1_bq27000.ko F_ID=2
 
 The driver also supports 1-wire mode. In this mode, there is no need to
 pass slave ID as parameter. The driver will auto-detect slaves connected
diff --git a/Documentation/w1/masters/w1-gpio b/Documentation/w1/masters/w1-gpio.rst
similarity index 75%
rename from Documentation/w1/masters/w1-gpio
rename to Documentation/w1/masters/w1-gpio.rst
index 623961d9e83f..18fdb7366372 100644
--- a/Documentation/w1/masters/w1-gpio
+++ b/Documentation/w1/masters/w1-gpio.rst
@@ -1,3 +1,4 @@
+=====================
 Kernel driver w1-gpio
 =====================
 
@@ -16,28 +17,30 @@ Documentation/devicetree/bindings/w1/w1-gpio.txt
 Example (mach-at91)
 -------------------
 
-#include <linux/gpio/machine.h>
-#include <linux/w1-gpio.h>
+::
 
-static struct gpiod_lookup_table foo_w1_gpiod_table = {
+  #include <linux/gpio/machine.h>
+  #include <linux/w1-gpio.h>
+
+  static struct gpiod_lookup_table foo_w1_gpiod_table = {
 	.dev_id = "w1-gpio",
 	.table = {
 		GPIO_LOOKUP_IDX("at91-gpio", AT91_PIN_PB20, NULL, 0,
 			GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN),
 	},
-};
+  };
 
-static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
+  static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
 	.ext_pullup_enable_pin	= -EINVAL,
-};
+  };
 
-static struct platform_device foo_w1_device = {
+  static struct platform_device foo_w1_device = {
 	.name			= "w1-gpio",
 	.id			= -1,
 	.dev.platform_data	= &foo_w1_gpio_pdata,
-};
+  };
 
-...
+  ...
 	at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1);
 	at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1);
 	gpiod_add_lookup_table(&foo_w1_gpiod_table);
diff --git a/Documentation/w1/slaves/index.rst b/Documentation/w1/slaves/index.rst
new file mode 100644
index 000000000000..d0697b202f09
--- /dev/null
+++ b/Documentation/w1/slaves/index.rst
@@ -0,0 +1,16 @@
+. SPDX-License-Identifier: GPL-2.0
+
+====================
+1-wire Slave Drivers
+====================
+
+.. toctree::
+   :maxdepth: 1
+
+   w1_ds2406
+   w1_ds2413
+   w1_ds2423
+   w1_ds2438
+   w1_ds28e04
+   w1_ds28e17
+   w1_therm
diff --git a/Documentation/w1/slaves/w1_ds2406 b/Documentation/w1/slaves/w1_ds2406.rst
similarity index 96%
rename from Documentation/w1/slaves/w1_ds2406
rename to Documentation/w1/slaves/w1_ds2406.rst
index 8137fe6f6c3d..d3e68266084f 100644
--- a/Documentation/w1/slaves/w1_ds2406
+++ b/Documentation/w1/slaves/w1_ds2406.rst
@@ -1,7 +1,9 @@
+=======================
 w1_ds2406 kernel driver
 =======================
 
 Supported chips:
+
   * Maxim DS2406 (and other family 0x12) addressable switches
 
 Author: Scott Alfter <scott@alfter.us>
@@ -9,7 +11,7 @@ Author: Scott Alfter <scott@alfter.us>
 Description
 -----------
 
-The w1_ds2406 driver allows connected devices to be switched on and off. 
+The w1_ds2406 driver allows connected devices to be switched on and off.
 These chips also provide 128 bytes of OTP EPROM, but reading/writing it is
 not supported.  In TSOC-6 form, the DS2406 provides two switch outputs and
 can be provided with power on a dedicated input.  In TO-92 form, it provides
diff --git a/Documentation/w1/slaves/w1_ds2413 b/Documentation/w1/slaves/w1_ds2413.rst
similarity index 81%
rename from Documentation/w1/slaves/w1_ds2413
rename to Documentation/w1/slaves/w1_ds2413.rst
index 936263a8ccb4..c15bb5b919b7 100644
--- a/Documentation/w1/slaves/w1_ds2413
+++ b/Documentation/w1/slaves/w1_ds2413.rst
@@ -1,11 +1,16 @@
+=======================
 Kernel driver w1_ds2413
 =======================
 
 Supported chips:
+
   * Maxim DS2413 1-Wire Dual Channel Addressable Switch
 
 supported family codes:
+
+        ================        ====
         W1_FAMILY_DS2413        0x3A
+        ================        ====
 
 Author: Mariusz Bialonczyk <manio@skyboo.net>
 
@@ -20,11 +25,13 @@ Reading state
 The "state" file provides one-byte value which is in the same format as for
 the chip PIO_ACCESS_READ command (refer the datasheet for details):
 
+======== =============================================================
 Bit 0:   PIOA Pin State
 Bit 1:   PIOA Output Latch State
 Bit 2:   PIOB Pin State
 Bit 3:   PIOB Output Latch State
 Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module)
+======== =============================================================
 
 This file is readonly.
 
@@ -34,9 +41,11 @@ You can set the PIO pins using the "output" file.
 It is writable, you can write one-byte value to this sysfs file.
 Similarly the byte format is the same as for the PIO_ACCESS_WRITE command:
 
+======== ======================================
 Bit 0:   PIOA
 Bit 1:   PIOB
 Bit 2-7: No matter (driver will set it to "1"s)
+======== ======================================
 
 
 The chip has some kind of basic protection against transmission errors.
diff --git a/Documentation/w1/slaves/w1_ds2423 b/Documentation/w1/slaves/w1_ds2423.rst
similarity index 48%
rename from Documentation/w1/slaves/w1_ds2423
rename to Documentation/w1/slaves/w1_ds2423.rst
index 3f98b505a0ee..755d659ad997 100644
--- a/Documentation/w1/slaves/w1_ds2423
+++ b/Documentation/w1/slaves/w1_ds2423.rst
@@ -2,10 +2,14 @@ Kernel driver w1_ds2423
 =======================
 
 Supported chips:
+
   * Maxim DS2423 based counter devices.
 
 supported family codes:
+
+        ===============	====
 	W1_THERM_DS2423	0x1D
+        ===============	====
 
 Author: Mika Laitio <lamikr@pilppa.org>
 
@@ -26,6 +30,7 @@ If the operation was successful, there is also in the end of each line
 a counter value expressed as an integer after c=
 
 Meaning of 42 bytes represented is following:
+
  - 1 byte from ram page
  - 4 bytes for the counter value
  - 4 zero bytes
@@ -34,14 +39,16 @@ Meaning of 42 bytes represented is following:
  - crc=YES/NO indicating whether read was ok and crc matched
  - c=<int> current counter value
 
-example from the successful read:
-00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
-00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
+example from the successful read::
 
-example from the read with crc errors:
-00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
-00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
-00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
-00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO
+  00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+  00 02 00 00 00 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+  00 29 c6 5d 18 00 00 00 00 04 37 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=408798761
+  00 05 00 00 00 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=YES c=5
+
+example from the read with crc errors::
+
+  00 02 00 00 00 00 00 00 00 6d 38 00 ff ff 00 00 fe ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=YES c=2
+  00 02 00 00 22 00 00 00 00 e0 1f 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+  00 e1 61 5d 19 00 00 00 00 df 0b 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff 00 00 ff ff crc=NO
+  00 05 00 00 20 00 00 00 00 8d 39 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff crc=NO
diff --git a/Documentation/w1/slaves/w1_ds2438 b/Documentation/w1/slaves/w1_ds2438.rst
similarity index 93%
rename from Documentation/w1/slaves/w1_ds2438
rename to Documentation/w1/slaves/w1_ds2438.rst
index e64f65a09387..a29309a3f8e5 100644
--- a/Documentation/w1/slaves/w1_ds2438
+++ b/Documentation/w1/slaves/w1_ds2438.rst
@@ -2,10 +2,13 @@ Kernel driver w1_ds2438
 =======================
 
 Supported chips:
+
   * Maxim DS2438 Smart Battery Monitor
 
 supported family codes:
+        ================        ====
         W1_FAMILY_DS2438        0x26
+        ================        ====
 
 Author: Mariusz Bialonczyk <manio@skyboo.net>
 
@@ -56,8 +59,11 @@ Opening and reading this file initiates the CONVERT_V (voltage conversion)
 command of the chip.
 
 Depending on a sysfs filename a different input for the A/D will be selected:
-vad: general purpose A/D input (VAD)
-vdd: battery input (VDD)
+
+vad:
+    general purpose A/D input (VAD)
+vdd:
+    battery input (VDD)
 
 After the voltage conversion the value is returned as decimal ASCII.
 Note: To get a volts the value has to be divided by 100.
diff --git a/Documentation/w1/slaves/w1_ds28e04 b/Documentation/w1/slaves/w1_ds28e04.rst
similarity index 93%
rename from Documentation/w1/slaves/w1_ds28e04
rename to Documentation/w1/slaves/w1_ds28e04.rst
index 7819b65cfa48..b12b118890d3 100644
--- a/Documentation/w1/slaves/w1_ds28e04
+++ b/Documentation/w1/slaves/w1_ds28e04.rst
@@ -1,11 +1,16 @@
+========================
 Kernel driver w1_ds28e04
 ========================
 
 Supported chips:
+
   * Maxim DS28E04-100 4096-Bit Addressable 1-Wire EEPROM with PIO
 
 supported family codes:
+
+        =================	====
 	W1_FAMILY_DS28E04	0x1C
+        =================	====
 
 Author: Markus Franke, <franke.m@sebakmt.com> <franm@hrz.tu-chemnitz.de>
 
diff --git a/Documentation/w1/slaves/w1_ds28e17 b/Documentation/w1/slaves/w1_ds28e17.rst
similarity index 88%
rename from Documentation/w1/slaves/w1_ds28e17
rename to Documentation/w1/slaves/w1_ds28e17.rst
index 7fcfad5b4a37..e2d9f96d8f2c 100644
--- a/Documentation/w1/slaves/w1_ds28e17
+++ b/Documentation/w1/slaves/w1_ds28e17.rst
@@ -1,11 +1,16 @@
+========================
 Kernel driver w1_ds28e17
 ========================
 
 Supported chips:
+
   * Maxim DS28E17 1-Wire-to-I2C Master Bridge
 
 supported family codes:
+
+        =================  ====
 	W1_FAMILY_DS28E17  0x19
+        =================  ====
 
 Author: Jan Kandziora <jjj@gmx.de>
 
@@ -20,11 +25,11 @@ a DS28E17 can be accessed by the kernel or userspace tools as if they were
 connected to a "native" I2C bus master.
 
 
-An udev rule like the following
--------------------------------------------------------------------------------
-SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
-        SYMLINK+="i2c-$attr{name}"
--------------------------------------------------------------------------------
+An udev rule like the following::
+
+  SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
+          SYMLINK+="i2c-$attr{name}"
+
 may be used to create stable /dev/i2c- entries based on the unique id of the
 DS28E17 chip.
 
@@ -65,4 +70,3 @@ structure is created.
 
 
 See https://github.com/ianka/w1_ds28e17 for even more information.
-
diff --git a/Documentation/w1/slaves/w1_therm b/Documentation/w1/slaves/w1_therm.rst
similarity index 95%
rename from Documentation/w1/slaves/w1_therm
rename to Documentation/w1/slaves/w1_therm.rst
index d1f93af36f38..90531c340a07 100644
--- a/Documentation/w1/slaves/w1_therm
+++ b/Documentation/w1/slaves/w1_therm.rst
@@ -1,7 +1,9 @@
+======================
 Kernel driver w1_therm
-====================
+======================
 
 Supported chips:
+
   * Maxim ds18*20 based temperature sensors.
   * Maxim ds1825 based temperature sensors.
 
@@ -13,12 +15,16 @@ Description
 
 w1_therm provides basic temperature conversion for ds18*20 devices, and the
 ds28ea00 device.
-supported family codes:
+
+Supported family codes:
+
+====================	====
 W1_THERM_DS18S20	0x10
 W1_THERM_DS1822		0x22
 W1_THERM_DS18B20	0x28
 W1_THERM_DS1825		0x3B
 W1_THERM_DS28EA00	0x42
+====================	====
 
 Support is provided through the sysfs w1_slave file.  Each open and
 read sequence will initiate a temperature conversion then provide two
@@ -51,6 +57,7 @@ If so, it will activate the master's strong pullup.
 In case the detection of parasite devices using this command fails
 (seems to be the case with some DS18S20) the strong pullup can
 be force-enabled.
+
 If the strong pullup is enabled, the master's strong pullup will be
 driven when the conversion is taking place, provided the master driver
 does support the strong pullup (or it falls back to a pullup
diff --git a/Documentation/w1/w1.generic b/Documentation/w1/w1-generic.rst
similarity index 59%
rename from Documentation/w1/w1.generic
rename to Documentation/w1/w1-generic.rst
index c51b1ab012d0..da4e8b4e9b01 100644
--- a/Documentation/w1/w1.generic
+++ b/Documentation/w1/w1-generic.rst
@@ -1,5 +1,7 @@
-The 1-wire (w1) subsystem
-------------------------------------------------------------------
+=========================================
+Introduction to the 1-wire (w1) subsystem
+=========================================
+
 The 1-wire bus is a simple master-slave bus that communicates via a single
 signal wire (plus ground, so two wires).
 
@@ -12,14 +14,16 @@ communication with slaves.
 All w1 slave devices must be connected to a w1 bus master device.
 
 Example w1 master devices:
-    DS9490 usb device
-    W1-over-GPIO
-    DS2482 (i2c to w1 bridge)
-    Emulated devices, such as a RS232 converter, parallel port adapter, etc
+
+    - DS9490 usb device
+    - W1-over-GPIO
+    - DS2482 (i2c to w1 bridge)
+    - Emulated devices, such as a RS232 converter, parallel port adapter, etc
 
 
 What does the w1 subsystem do?
-------------------------------------------------------------------
+------------------------------
+
 When a w1 master driver registers with the w1 subsystem, the following occurs:
 
  - sysfs entries for that w1 master are created
@@ -43,24 +47,28 @@ be read, since no device was selected.
 
 
 W1 device families
-------------------------------------------------------------------
+------------------
+
 Slave devices are handled by a driver written for a family of w1 devices.
 
 A family driver populates a struct w1_family_ops (see w1_family.h) and
 registers with the w1 subsystem.
 
 Current family drivers:
-w1_therm - (ds18?20 thermal sensor family driver)
+
+w1_therm
+  - (ds18?20 thermal sensor family driver)
     provides temperature reading function which is bound to ->rbin() method
     of the above w1_family_ops structure.
 
-w1_smem - driver for simple 64bit memory cell provides ID reading method.
+w1_smem
+  - driver for simple 64bit memory cell provides ID reading method.
 
 You can call above methods by reading appropriate sysfs files.
 
 
 What does a w1 master driver need to implement?
-------------------------------------------------------------------
+-----------------------------------------------
 
 The driver for w1 bus master must provide at minimum two functions.
 
@@ -75,25 +83,26 @@ See struct w1_bus_master definition in w1.h for details.
 
 
 w1 master sysfs interface
-------------------------------------------------------------------
-<xx-xxxxxxxxxxxx>  - A directory for a found device. The format is family-serial
-bus                - (standard) symlink to the w1 bus
-driver             - (standard) symlink to the w1 driver
-w1_master_add      - (rw) manually register a slave device
-w1_master_attempts - (ro) the number of times a search was attempted
-w1_master_max_slave_count
-                   - (rw) maximum number of slaves to search for at a time
-w1_master_name     - (ro) the name of the device (w1_bus_masterX)
-w1_master_pullup   - (rw) 5V strong pullup 0 enabled, 1 disabled
-w1_master_remove   - (rw) manually remove a slave device
-w1_master_search   - (rw) the number of searches left to do,
-		     -1=continual (default)
-w1_master_slave_count
-                   - (ro) the number of slaves found
-w1_master_slaves   - (ro) the names of the slaves, one per line
-w1_master_timeout  - (ro) the delay in seconds between searches
-w1_master_timeout_us
-                   - (ro) the delay in microseconds beetwen searches
+-------------------------
+
+========================= =====================================================
+<xx-xxxxxxxxxxxx>         A directory for a found device. The format is
+                          family-serial
+bus                       (standard) symlink to the w1 bus
+driver                    (standard) symlink to the w1 driver
+w1_master_add             (rw) manually register a slave device
+w1_master_attempts        (ro) the number of times a search was attempted
+w1_master_max_slave_count (rw) maximum number of slaves to search for at a time
+w1_master_name            (ro) the name of the device (w1_bus_masterX)
+w1_master_pullup          (rw) 5V strong pullup 0 enabled, 1 disabled
+w1_master_remove          (rw) manually remove a slave device
+w1_master_search          (rw) the number of searches left to do,
+                          -1=continual (default)
+w1_master_slave_count     (ro) the number of slaves found
+w1_master_slaves          (ro) the names of the slaves, one per line
+w1_master_timeout         (ro) the delay in seconds between searches
+w1_master_timeout_us      (ro) the delay in microseconds beetwen searches
+========================= =====================================================
 
 If you have a w1 bus that never changes (you don't add or remove devices),
 you can set the module parameter search_count to a small positive number
@@ -111,11 +120,14 @@ decrements w1_master_search by 1 (down to 0) and increments
 w1_master_attempts by 1.
 
 w1 slave sysfs interface
-------------------------------------------------------------------
-bus                - (standard) symlink to the w1 bus
-driver             - (standard) symlink to the w1 driver
-name               - the device name, usually the same as the directory name
-w1_slave           - (optional) a binary file whose meaning depends on the
-                     family driver
-rw		   - (optional) created for slave devices which do not have
-		     appropriate family driver. Allows to read/write binary data.
+------------------------
+
+=================== ============================================================
+bus                 (standard) symlink to the w1 bus
+driver              (standard) symlink to the w1 driver
+name                the device name, usually the same as the directory name
+w1_slave            (optional) a binary file whose meaning depends on the
+                    family driver
+rw		    (optional) created for slave devices which do not have
+		    appropriate family driver. Allows to read/write binary data.
+=================== ============================================================
diff --git a/Documentation/w1/w1.netlink b/Documentation/w1/w1-netlink.rst
similarity index 77%
rename from Documentation/w1/w1.netlink
rename to Documentation/w1/w1-netlink.rst
index 94ad4c420828..aaa13243a5e4 100644
--- a/Documentation/w1/w1.netlink
+++ b/Documentation/w1/w1-netlink.rst
@@ -1,22 +1,26 @@
-Userspace communication protocol over connector [1].
+===============================================
+Userspace communication protocol over connector
+===============================================
 
-
-Message types.
+Message types
 =============
 
 There are three types of messages between w1 core and userspace:
+
 1. Events. They are generated each time a new master or slave device
-	is found either due to automatic or requested search.
+   is found either due to automatic or requested search.
 2. Userspace commands.
 3. Replies to userspace commands.
 
 
-Protocol.
+Protocol
 ========
 
-[struct cn_msg] - connector header.
+::
+
+  [struct cn_msg] - connector header.
 	Its length field is equal to size of the attached data
-[struct w1_netlink_msg] - w1 netlink header.
+  [struct w1_netlink_msg] - w1 netlink header.
 	__u8 type 	- message type.
 			W1_LIST_MASTERS
 				list current bus masters
@@ -40,7 +44,7 @@ Protocol.
 		} mst;
 	} id;
 
-[struct w1_netlink_cmd] - command for given master or slave device.
+  [struct w1_netlink_cmd] - command for given master or slave device.
 	__u8 cmd	- command opcode.
 			W1_CMD_READ 	- read command
 			W1_CMD_WRITE	- write command
@@ -71,18 +75,18 @@ when it is added to w1 core.
 Currently replies to userspace commands are only generated for read
 command request. One reply is generated exactly for one w1_netlink_cmd
 read request. Replies are not combined when sent - i.e. typical reply
-messages looks like the following:
+messages looks like the following::
 
-[cn_msg][w1_netlink_msg][w1_netlink_cmd]
-cn_msg.len = sizeof(struct w1_netlink_msg) +
+  [cn_msg][w1_netlink_msg][w1_netlink_cmd]
+  cn_msg.len = sizeof(struct w1_netlink_msg) +
 	     sizeof(struct w1_netlink_cmd) +
 	     cmd->len;
-w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
-w1_netlink_cmd.len = cmd->len;
+  w1_netlink_msg.len = sizeof(struct w1_netlink_cmd) + cmd->len;
+  w1_netlink_cmd.len = cmd->len;
 
 Replies to W1_LIST_MASTERS should send a message back to the userspace
 which will contain list of all registered master ids in the following
-format:
+format::
 
 	cn_msg (CN_W1_IDX.CN_W1_VAL as id, len is equal to sizeof(struct
 	w1_netlink_msg) plus number of masters multiplied by 4)
@@ -90,39 +94,47 @@ format:
 		number of masters multiplied by 4 (u32 size))
 	id0 ... idN
 
-	Each message is at most 4k in size, so if number of master devices
-	exceeds this, it will be split into several messages.
+Each message is at most 4k in size, so if number of master devices
+exceeds this, it will be split into several messages.
 
 W1 search and alarm search commands.
-request:
-[cn_msg]
-  [w1_netlink_msg type = W1_MASTER_CMD
-  	id is equal to the bus master id to use for searching]
-  [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
 
-reply:
+request::
+
+  [cn_msg]
+    [w1_netlink_msg type = W1_MASTER_CMD
+	id is equal to the bus master id to use for searching]
+    [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH]
+
+reply::
+
   [cn_msg, ack = 1 and increasing, 0 means the last message,
-  	seq is equal to the request seq]
+	seq is equal to the request seq]
   [w1_netlink_msg type = W1_MASTER_CMD]
   [w1_netlink_cmd cmd = W1_CMD_SEARCH or W1_CMD_ALARM_SEARCH
 	len is equal to number of IDs multiplied by 8]
   [64bit-id0 ... 64bit-idN]
+
 Length in each header corresponds to the size of the data behind it, so
 w1_netlink_cmd->len = N * 8; where N is number of IDs in this message.
-	Can be zero.
-w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
-cn_msg->len = sizeof(struct w1_netlink_msg) +
+Can be zero.
+
+::
+
+  w1_netlink_msg->len = sizeof(struct w1_netlink_cmd) + N * 8;
+  cn_msg->len = sizeof(struct w1_netlink_msg) +
 	      sizeof(struct w1_netlink_cmd) +
 	      N*8;
 
-W1 reset command.
-[cn_msg]
-  [w1_netlink_msg type = W1_MASTER_CMD
-  	id is equal to the bus master id to use for searching]
-  [w1_netlink_cmd cmd = W1_CMD_RESET]
+W1 reset command::
 
+  [cn_msg]
+    [w1_netlink_msg type = W1_MASTER_CMD
+	id is equal to the bus master id to use for searching]
+    [w1_netlink_cmd cmd = W1_CMD_RESET]
 
-Command status replies.
+
+Command status replies
 ======================
 
 Each command (either root, master or slave with or without w1_netlink_cmd
@@ -150,7 +162,7 @@ All w1_netlink_cmd command structures are handled in every w1_netlink_msg,
 even if there were errors, only length mismatch interrupts message processing.
 
 
-Operation steps in w1 core when new command is received.
+Operation steps in w1 core when new command is received
 =======================================================
 
 When new message (w1_netlink_msg) is received w1 core detects if it is
@@ -167,7 +179,7 @@ When all commands (w1_netlink_cmd) are processed master device is unlocked
 and next w1_netlink_msg header processing started.
 
 
-Connector [1] specific documentation.
+Connector [1] specific documentation
 ====================================
 
 Each connector message includes two u32 fields as "address".
@@ -180,10 +192,11 @@ Sequence number for reply is the same as was in request, and
 acknowledge number is set to seq+1.
 
 
-Additional documantion, source code examples.
-============================================
+Additional documentation, source code examples
+==============================================
 
 1. Documentation/driver-api/connector.rst
 2. http://www.ioremap.net/archive/w1
-This archive includes userspace application w1d.c which uses
-read/write/search commands for all master/slave devices found on the bus.
+
+   This archive includes userspace application w1d.c which uses
+   read/write/search commands for all master/slave devices found on the bus.
-- 
2.21.0


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

* [PATCH v2 08/26] spi: docs: convert to ReST and add it to the kABI bookset
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (10 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Mark Brown,
	Jonathan Cameron, Hartmut Knaack, Lars-Peter Clausen,
	Peter Meerwald-Stadler, linux-doc, linux-spi, linux-iio,
	Jonathan Cameron

While there's one file there with briefily describes the uAPI,
the documentation was written just like most subsystems: focused
on kernel developers. So, add it together with driver-api books.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> # for iio
---
 Documentation/index.rst                       |   1 +
 .../spi/{butterfly => butterfly.rst}          |  44 ++++----
 Documentation/spi/index.rst                   |  22 ++++
 Documentation/spi/{pxa2xx => pxa2xx.rst}      |  95 ++++++++--------
 .../spi/{spi-lm70llp => spi-lm70llp.rst}      |  17 ++-
 .../spi/{spi-sc18is602 => spi-sc18is602.rst}  |   3 +
 .../spi/{spi-summary => spi-summary.rst}      | 105 ++++++++++--------
 Documentation/spi/{spidev => spidev.rst}      |  30 +++--
 drivers/iio/dummy/iio_simple_dummy.c          |   2 +-
 drivers/spi/Kconfig                           |   2 +-
 drivers/spi/spi-butterfly.c                   |   2 +-
 drivers/spi/spi-lm70llp.c                     |   2 +-
 include/linux/platform_data/sc18is602.h       |   2 +-
 13 files changed, 198 insertions(+), 129 deletions(-)
 rename Documentation/spi/{butterfly => butterfly.rst} (71%)
 create mode 100644 Documentation/spi/index.rst
 rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
 rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
 rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (97%)
 rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
 rename Documentation/spi/{spidev => spidev.rst} (90%)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index e53c379dcb78..d9e607d8a9b9 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -115,6 +115,7 @@ needed).
    power/index
    target/index
    timers/index
+   spi/index
    w1/index
    watchdog/index
    input/index
diff --git a/Documentation/spi/butterfly b/Documentation/spi/butterfly.rst
similarity index 71%
rename from Documentation/spi/butterfly
rename to Documentation/spi/butterfly.rst
index 9927af7a629c..e614a589547c 100644
--- a/Documentation/spi/butterfly
+++ b/Documentation/spi/butterfly.rst
@@ -1,3 +1,4 @@
+===================================================
 spi_butterfly - parport-to-butterfly adapter driver
 ===================================================
 
@@ -27,25 +28,29 @@ need to reflash the firmware, and the pins are the standard Atmel "ISP"
 connector pins (used also on non-Butterfly AVR boards).  On the parport
 side this is like "sp12" programming cables.
 
+	======	  =============	  ===================
 	Signal	  Butterfly	  Parport (DB-25)
-	------	  ---------	  ---------------
-	SCK	= J403.PB1/SCK	= pin 2/D0
-	RESET	= J403.nRST	= pin 3/D1
-	VCC	= J403.VCC_EXT	= pin 8/D6
-	MOSI	= J403.PB2/MOSI	= pin 9/D7
-	MISO	= J403.PB3/MISO	= pin 11/S7,nBUSY
-	GND	= J403.GND	= pin 23/GND
+	======	  =============	  ===================
+	SCK	  J403.PB1/SCK	  pin 2/D0
+	RESET	  J403.nRST	  pin 3/D1
+	VCC	  J403.VCC_EXT	  pin 8/D6
+	MOSI	  J403.PB2/MOSI	  pin 9/D7
+	MISO	  J403.PB3/MISO	  pin 11/S7,nBUSY
+	GND	  J403.GND	  pin 23/GND
+	======	  =============	  ===================
 
 Then to let Linux master that bus to talk to the DataFlash chip, you must
 (a) flash new firmware that disables SPI (set PRR.2, and disable pullups
 by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and
 (c) cable in the chipselect.
 
+	======	  ============	  ===================
 	Signal	  Butterfly	  Parport (DB-25)
-	------	  ---------	  ---------------
-	VCC	= J400.VCC_EXT	= pin 7/D5
-	SELECT	= J400.PB0/nSS	= pin 17/C3,nSELECT
-	GND	= J400.GND	= pin 24/GND
+	======	  ============	  ===================
+	VCC	  J400.VCC_EXT	  pin 7/D5
+	SELECT	  J400.PB0/nSS	  pin 17/C3,nSELECT
+	GND	  J400.GND	  pin 24/GND
+	======	  ============	  ===================
 
 Or you could flash firmware making the AVR into an SPI slave (keeping the
 DataFlash in reset) and tweak the spi_butterfly driver to make it bind to
@@ -56,13 +61,14 @@ That would let you talk to the AVR using custom SPI-with-USI firmware,
 while letting either Linux or the AVR use the DataFlash.  There are plenty
 of spare parport pins to wire this one up, such as:
 
+	======	  =============	  ===================
 	Signal	  Butterfly	  Parport (DB-25)
-	------	  ---------	  ---------------
-	SCK	= J403.PE4/USCK	= pin 5/D3
-	MOSI	= J403.PE5/DI	= pin 6/D4
-	MISO	= J403.PE6/DO	= pin 12/S5,nPAPEROUT
-	GND	= J403.GND	= pin 22/GND
-
-	IRQ	= J402.PF4	= pin 10/S6,ACK
-	GND	= J402.GND(P2)	= pin 25/GND
+	======	  =============	  ===================
+	SCK	  J403.PE4/USCK	  pin 5/D3
+	MOSI	  J403.PE5/DI	  pin 6/D4
+	MISO	  J403.PE6/DO	  pin 12/S5,nPAPEROUT
+	GND	  J403.GND	  pin 22/GND
 
+	IRQ	  J402.PF4	  pin 10/S6,ACK
+	GND	  J402.GND(P2)	  pin 25/GND
+	======	  =============	  ===================
diff --git a/Documentation/spi/index.rst b/Documentation/spi/index.rst
new file mode 100644
index 000000000000..06c34ea11bcf
--- /dev/null
+++ b/Documentation/spi/index.rst
@@ -0,0 +1,22 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+Serial Peripheral Interface (SPI)
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   spi-summary
+   spidev
+   butterfly
+   pxa2xx
+   spi-lm70llp
+   spi-sc18is602
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/spi/pxa2xx b/Documentation/spi/pxa2xx.rst
similarity index 83%
rename from Documentation/spi/pxa2xx
rename to Documentation/spi/pxa2xx.rst
index 551325b66b23..882d3cc72cc2 100644
--- a/Documentation/spi/pxa2xx
+++ b/Documentation/spi/pxa2xx.rst
@@ -1,8 +1,10 @@
+==============================
 PXA2xx SPI on SSP driver HOWTO
-===================================================
+==============================
+
 This a mini howto on the pxa2xx_spi driver.  The driver turns a PXA2xx
 synchronous serial port into a SPI master controller
-(see Documentation/spi/spi-summary). The driver has the following features
+(see Documentation/spi/spi-summary.rst). The driver has the following features
 
 - Support for any PXA2xx SSP
 - SSP PIO and SSP DMA data transfers.
@@ -19,12 +21,12 @@ Declaring PXA2xx Master Controllers
 -----------------------------------
 Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a
 "platform device".  The master configuration is passed to the driver via a table
-found in include/linux/spi/pxa2xx_spi.h:
+found in include/linux/spi/pxa2xx_spi.h::
 
-struct pxa2xx_spi_controller {
+  struct pxa2xx_spi_controller {
 	u16 num_chipselect;
 	u8 enable_dma;
-};
+  };
 
 The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of
 slave device (chips) attached to this SPI master.
@@ -36,9 +38,9 @@ See the "PXA2xx Developer Manual" section "DMA Controller".
 
 NSSP MASTER SAMPLE
 ------------------
-Below is a sample configuration using the PXA255 NSSP.
+Below is a sample configuration using the PXA255 NSSP::
 
-static struct resource pxa_spi_nssp_resources[] = {
+  static struct resource pxa_spi_nssp_resources[] = {
 	[0] = {
 		.start	= __PREG(SSCR0_P(2)), /* Start address of NSSP */
 		.end	= __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */
@@ -49,14 +51,14 @@ static struct resource pxa_spi_nssp_resources[] = {
 		.end	= IRQ_NSSP,
 		.flags	= IORESOURCE_IRQ,
 	},
-};
+  };
 
-static struct pxa2xx_spi_controller pxa_nssp_master_info = {
+  static struct pxa2xx_spi_controller pxa_nssp_master_info = {
 	.num_chipselect = 1, /* Matches the number of chips attached to NSSP */
 	.enable_dma = 1, /* Enables NSSP DMA */
-};
+  };
 
-static struct platform_device pxa_spi_nssp = {
+  static struct platform_device pxa_spi_nssp = {
 	.name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */
 	.id = 2, /* Bus number, MUST MATCH SSP number 1..n */
 	.resource = pxa_spi_nssp_resources,
@@ -64,22 +66,22 @@ static struct platform_device pxa_spi_nssp = {
 	.dev = {
 		.platform_data = &pxa_nssp_master_info, /* Passed to driver */
 	},
-};
+  };
 
-static struct platform_device *devices[] __initdata = {
+  static struct platform_device *devices[] __initdata = {
 	&pxa_spi_nssp,
-};
+  };
 
-static void __init board_init(void)
-{
+  static void __init board_init(void)
+  {
 	(void)platform_add_device(devices, ARRAY_SIZE(devices));
-}
+  }
 
 Declaring Slave Devices
 -----------------------
 Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c
 using the "spi_board_info" structure found in "linux/spi/spi.h". See
-"Documentation/spi/spi-summary" for additional information.
+"Documentation/spi/spi-summary.rst" for additional information.
 
 Each slave device attached to the PXA must provide slave specific configuration
 information via the structure "pxa2xx_spi_chip" found in
@@ -87,19 +89,21 @@ information via the structure "pxa2xx_spi_chip" found in
 will uses the configuration whenever the driver communicates with the slave
 device. All fields are optional.
 
-struct pxa2xx_spi_chip {
+::
+
+  struct pxa2xx_spi_chip {
 	u8 tx_threshold;
 	u8 rx_threshold;
 	u8 dma_burst_size;
 	u32 timeout;
 	u8 enable_loopback;
 	void (*cs_control)(u32 command);
-};
+  };
 
 The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are
 used to configure the SSP hardware fifo.  These fields are critical to the
 performance of pxa2xx_spi driver and misconfiguration will result in rx
-fifo overruns (especially in PIO mode transfers). Good default values are
+fifo overruns (especially in PIO mode transfers). Good default values are::
 
 	.tx_threshold = 8,
 	.rx_threshold = 8,
@@ -141,41 +145,43 @@ The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the
 "spi_board_info.controller_data" field. Below is a sample configuration using
 the PXA255 NSSP.
 
-/* Chip Select control for the CS8415A SPI slave device */
-static void cs8415a_cs_control(u32 command)
-{
+::
+
+  /* Chip Select control for the CS8415A SPI slave device */
+  static void cs8415a_cs_control(u32 command)
+  {
 	if (command & PXA2XX_CS_ASSERT)
 		GPCR(2) = GPIO_bit(2);
 	else
 		GPSR(2) = GPIO_bit(2);
-}
+  }
 
-/* Chip Select control for the CS8405A SPI slave device */
-static void cs8405a_cs_control(u32 command)
-{
+  /* Chip Select control for the CS8405A SPI slave device */
+  static void cs8405a_cs_control(u32 command)
+  {
 	if (command & PXA2XX_CS_ASSERT)
 		GPCR(3) = GPIO_bit(3);
 	else
 		GPSR(3) = GPIO_bit(3);
-}
+  }
 
-static struct pxa2xx_spi_chip cs8415a_chip_info = {
+  static struct pxa2xx_spi_chip cs8415a_chip_info = {
 	.tx_threshold = 8, /* SSP hardward FIFO threshold */
 	.rx_threshold = 8, /* SSP hardward FIFO threshold */
 	.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
 	.timeout = 235, /* See Intel documentation */
 	.cs_control = cs8415a_cs_control, /* Use external chip select */
-};
+  };
 
-static struct pxa2xx_spi_chip cs8405a_chip_info = {
+  static struct pxa2xx_spi_chip cs8405a_chip_info = {
 	.tx_threshold = 8, /* SSP hardward FIFO threshold */
 	.rx_threshold = 8, /* SSP hardward FIFO threshold */
 	.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
 	.timeout = 235, /* See Intel documentation */
 	.cs_control = cs8405a_cs_control, /* Use external chip select */
-};
+  };
 
-static struct spi_board_info streetracer_spi_board_info[] __initdata = {
+  static struct spi_board_info streetracer_spi_board_info[] __initdata = {
 	{
 		.modalias = "cs8415a", /* Name of spi_driver for this device */
 		.max_speed_hz = 3686400, /* Run SSP as fast a possbile */
@@ -193,13 +199,13 @@ static struct spi_board_info streetracer_spi_board_info[] __initdata = {
 		.controller_data = &cs8405a_chip_info, /* Master chip config */
 		.irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */
 	},
-};
+  };
 
-static void __init streetracer_init(void)
-{
+  static void __init streetracer_init(void)
+  {
 	spi_register_board_info(streetracer_spi_board_info,
 				ARRAY_SIZE(streetracer_spi_board_info));
-}
+  }
 
 
 DMA and PIO I/O Support
@@ -210,26 +216,25 @@ by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure.  The
 mode supports both coherent and stream based DMA mappings.
 
 The following logic is used to determine the type of I/O to be used on
-a per "spi_transfer" basis:
+a per "spi_transfer" basis::
 
-if !enable_dma then
+  if !enable_dma then
 	always use PIO transfers
 
-if spi_message.len > 8191 then
+  if spi_message.len > 8191 then
 	print "rate limited" warning
 	use PIO transfers
 
-if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
+  if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
 	use coherent DMA mode
 
-if rx_buf and tx_buf are aligned on 8 byte boundary then
+  if rx_buf and tx_buf are aligned on 8 byte boundary then
 	use streaming DMA mode
 
-otherwise
+  otherwise
 	use PIO transfer
 
 THANKS TO
 ---------
 
 David Brownell and others for mentoring the development of this driver.
-
diff --git a/Documentation/spi/spi-lm70llp b/Documentation/spi/spi-lm70llp.rst
similarity index 88%
rename from Documentation/spi/spi-lm70llp
rename to Documentation/spi/spi-lm70llp.rst
index 463f6d01fa15..07631aef4343 100644
--- a/Documentation/spi/spi-lm70llp
+++ b/Documentation/spi/spi-lm70llp.rst
@@ -1,8 +1,11 @@
+==============================================
 spi_lm70llp :  LM70-LLP parport-to-SPI adapter
 ==============================================
 
 Supported board/chip:
+
   * National Semiconductor LM70 LLP evaluation board
+
     Datasheet: http://www.national.com/pf/LM/LM70.html
 
 Author:
@@ -29,9 +32,10 @@ available (on page 4) here:
 
 The hardware interfacing on the LM70 LLP eval board is as follows:
 
+   ======== == =========   ==========
    Parallel                 LM70 LLP
-     Port      Direction   JP2 Header
-   ----------- --------- ----------------
+     Port   .  Direction   JP2 Header
+   ======== == =========   ==========
       D0     2      -         -
       D1     3     -->      V+   5
       D2     4     -->      V+   5
@@ -42,7 +46,7 @@ The hardware interfacing on the LM70 LLP eval board is as follows:
       D7     9     -->      SI/O 5
      GND    25      -       GND  7
     Select  13     <--      SI/O 1
-   ----------- --------- ----------------
+   ======== == =========   ==========
 
 Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin
 is connected to both pin D7 (as Master Out) and Select (as Master In)
@@ -74,6 +78,7 @@ inverting the value read at pin 13.
 
 Thanks to
 ---------
-o David Brownell for mentoring the SPI-side driver development.
-o Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
-o Nadir Billimoria for help interpreting the circuit schematic.
+
+- David Brownell for mentoring the SPI-side driver development.
+- Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
+- Nadir Billimoria for help interpreting the circuit schematic.
diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602.rst
similarity index 97%
rename from Documentation/spi/spi-sc18is602
rename to Documentation/spi/spi-sc18is602.rst
index 0feffd5af411..2a31dc722321 100644
--- a/Documentation/spi/spi-sc18is602
+++ b/Documentation/spi/spi-sc18is602.rst
@@ -1,8 +1,11 @@
+===========================
 Kernel driver spi-sc18is602
 ===========================
 
 Supported chips:
+
   * NXP SI18IS602/602B/603
+
     Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf
 
 Author:
diff --git a/Documentation/spi/spi-summary b/Documentation/spi/spi-summary.rst
similarity index 93%
rename from Documentation/spi/spi-summary
rename to Documentation/spi/spi-summary.rst
index 1a63194b74d7..f1daffe10d78 100644
--- a/Documentation/spi/spi-summary
+++ b/Documentation/spi/spi-summary.rst
@@ -1,3 +1,4 @@
+====================================
 Overview of Linux kernel SPI support
 ====================================
 
@@ -139,12 +140,14 @@ a command and then reading its response.
 
 There are two types of SPI driver, here called:
 
-  Controller drivers ... controllers may be built into System-On-Chip
+  Controller drivers ...
+        controllers may be built into System-On-Chip
 	processors, and often support both Master and Slave roles.
 	These drivers touch hardware registers and may use DMA.
 	Or they can be PIO bitbangers, needing just GPIO pins.
 
-  Protocol drivers ... these pass messages through the controller
+  Protocol drivers ...
+        these pass messages through the controller
 	driver to communicate with a Slave or Master device on the
 	other side of an SPI link.
 
@@ -160,7 +163,7 @@ those two types of drivers.
 There is a minimal core of SPI programming interfaces, focussing on
 using the driver model to connect controller and protocol drivers using
 device tables provided by board specific initialization code.  SPI
-shows up in sysfs in several locations:
+shows up in sysfs in several locations::
 
    /sys/devices/.../CTLR ... physical node for a given SPI controller
 
@@ -168,7 +171,7 @@ shows up in sysfs in several locations:
 	chipselect C, accessed through CTLR.
 
    /sys/bus/spi/devices/spiB.C ... symlink to that physical
-   	.../CTLR/spiB.C device
+	.../CTLR/spiB.C device
 
    /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver
 	that should be used with this device (for hotplug/coldplug)
@@ -206,7 +209,8 @@ Linux needs several kinds of information to properly configure SPI devices.
 That information is normally provided by board-specific code, even for
 chips that do support some of automated discovery/enumeration.
 
-DECLARE CONTROLLERS
+Declare Controllers
+^^^^^^^^^^^^^^^^^^^
 
 The first kind of information is a list of what SPI controllers exist.
 For System-on-Chip (SOC) based boards, these will usually be platform
@@ -221,7 +225,7 @@ same basic controller setup code.  This is because most SOCs have several
 SPI-capable controllers, and only the ones actually usable on a given
 board should normally be set up and registered.
 
-So for example arch/.../mach-*/board-*.c files might have code like:
+So for example arch/.../mach-*/board-*.c files might have code like::
 
 	#include <mach/spi.h>	/* for mysoc_spi_data */
 
@@ -238,7 +242,7 @@ So for example arch/.../mach-*/board-*.c files might have code like:
 		...
 	}
 
-And SOC-specific utility code might look something like:
+And SOC-specific utility code might look something like::
 
 	#include <mach/spi.h>
 
@@ -269,8 +273,8 @@ same SOC controller is used.  For example, on one board SPI might use
 an external clock, where another derives the SPI clock from current
 settings of some master clock.
 
-
-DECLARE SLAVE DEVICES
+Declare Slave Devices
+^^^^^^^^^^^^^^^^^^^^^
 
 The second kind of information is a list of what SPI slave devices exist
 on the target board, often with some board-specific data needed for the
@@ -278,7 +282,7 @@ driver to work correctly.
 
 Normally your arch/.../mach-*/board-*.c files would provide a small table
 listing the SPI devices on each board.  (This would typically be only a
-small handful.)  That might look like:
+small handful.)  That might look like::
 
 	static struct ads7846_platform_data ads_info = {
 		.vref_delay_usecs	= 100,
@@ -316,7 +320,7 @@ not possible until the infrastructure knows how to deselect it.
 
 Then your board initialization code would register that table with the SPI
 infrastructure, so that it's available later when the SPI master controller
-driver is registered:
+driver is registered::
 
 	spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
 
@@ -324,12 +328,13 @@ Like with other static board-specific setup, you won't unregister those.
 
 The widely used "card" style computers bundle memory, cpu, and little else
 onto a card that's maybe just thirty square centimeters.  On such systems,
-your arch/.../mach-.../board-*.c file would primarily provide information
+your ``arch/.../mach-.../board-*.c`` file would primarily provide information
 about the devices on the mainboard into which such a card is plugged.  That
 certainly includes SPI devices hooked up through the card connectors!
 
 
-NON-STATIC CONFIGURATIONS
+Non-static Configurations
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Developer boards often play by different rules than product boards, and one
 example is the potential need to hotplug SPI devices and/or controllers.
@@ -349,7 +354,7 @@ How do I write an "SPI Protocol Driver"?
 Most SPI drivers are currently kernel drivers, but there's also support
 for userspace drivers.  Here we talk only about kernel drivers.
 
-SPI protocol drivers somewhat resemble platform device drivers:
+SPI protocol drivers somewhat resemble platform device drivers::
 
 	static struct spi_driver CHIP_driver = {
 		.driver = {
@@ -367,6 +372,8 @@ device whose board_info gave a modalias of "CHIP".  Your probe() code
 might look like this unless you're creating a device which is managing
 a bus (appearing under /sys/class/spi_master).
 
+::
+
 	static int CHIP_probe(struct spi_device *spi)
 	{
 		struct CHIP			*chip;
@@ -479,6 +486,8 @@ The main task of this type of driver is to provide an "spi_master".
 Use spi_alloc_master() to allocate the master, and spi_master_get_devdata()
 to get the driver-private data allocated for that device.
 
+::
+
 	struct spi_master	*master;
 	struct CONTROLLER	*c;
 
@@ -503,7 +512,8 @@ If you need to remove your SPI controller driver, spi_unregister_master()
 will reverse the effect of spi_register_master().
 
 
-BUS NUMBERING
+Bus Numbering
+^^^^^^^^^^^^^
 
 Bus numbering is important, since that's how Linux identifies a given
 SPI bus (shared SCK, MOSI, MISO).  Valid bus numbers start at zero.  On
@@ -517,9 +527,10 @@ then be replaced by a dynamically assigned number. You'd then need to treat
 this as a non-static configuration (see above).
 
 
-SPI MASTER METHODS
+SPI Master Methods
+^^^^^^^^^^^^^^^^^^
 
-    master->setup(struct spi_device *spi)
+``master->setup(struct spi_device *spi)``
 	This sets up the device clock rate, SPI mode, and word sizes.
 	Drivers may change the defaults provided by board_info, and then
 	call spi_setup(spi) to invoke this routine.  It may sleep.
@@ -528,37 +539,37 @@ SPI MASTER METHODS
 	change them right away ... otherwise drivers could corrupt I/O
 	that's in progress for other SPI devices.
 
-		** BUG ALERT:  for some reason the first version of
-		** many spi_master drivers seems to get this wrong.
-		** When you code setup(), ASSUME that the controller
-		** is actively processing transfers for another device.
+	.. note::
 
-    master->cleanup(struct spi_device *spi)
+		BUG ALERT:  for some reason the first version of
+		many spi_master drivers seems to get this wrong.
+		When you code setup(), ASSUME that the controller
+		is actively processing transfers for another device.
+
+``master->cleanup(struct spi_device *spi)``
 	Your controller driver may use spi_device.controller_state to hold
 	state it dynamically associates with that device.  If you do that,
 	be sure to provide the cleanup() method to free that state.
 
-    master->prepare_transfer_hardware(struct spi_master *master)
+``master->prepare_transfer_hardware(struct spi_master *master)``
 	This will be called by the queue mechanism to signal to the driver
 	that a message is coming in soon, so the subsystem requests the
 	driver to prepare the transfer hardware by issuing this call.
 	This may sleep.
 
-    master->unprepare_transfer_hardware(struct spi_master *master)
+``master->unprepare_transfer_hardware(struct spi_master *master)``
 	This will be called by the queue mechanism to signal to the driver
 	that there are no more messages pending in the queue and it may
 	relax the hardware (e.g. by power management calls). This may sleep.
 
-    master->transfer_one_message(struct spi_master *master,
-				 struct spi_message *mesg)
+``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
 	The subsystem calls the driver to transfer a single message while
 	queuing transfers that arrive in the meantime. When the driver is
 	finished with this message, it must call
 	spi_finalize_current_message() so the subsystem can issue the next
 	message. This may sleep.
 
-    master->transfer_one(struct spi_master *master, struct spi_device *spi,
-			 struct spi_transfer *transfer)
+``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)``
 	The subsystem calls the driver to transfer a single transfer while
 	queuing transfers that arrive in the meantime. When the driver is
 	finished with this transfer, it must call
@@ -568,19 +579,20 @@ SPI MASTER METHODS
 	not call your transfer_one callback.
 
 	Return values:
-	negative errno: error
-	0: transfer is finished
-	1: transfer is still in progress
 
-    master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles,
-			      u8 hold_clk_cycles, u8 inactive_clk_cycles)
+	* negative errno: error
+	* 0: transfer is finished
+	* 1: transfer is still in progress
+
+``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
 	This method allows SPI client drivers to request SPI master controller
 	for configuring device specific CS setup, hold and inactive timing
 	requirements.
 
-    DEPRECATED METHODS
+Deprecated Methods
+^^^^^^^^^^^^^^^^^^
 
-    master->transfer(struct spi_device *spi, struct spi_message *message)
+``master->transfer(struct spi_device *spi, struct spi_message *message)``
 	This must not sleep. Its responsibility is to arrange that the
 	transfer happens and its complete() callback is issued. The two
 	will normally happen later, after other transfers complete, and
@@ -590,7 +602,8 @@ SPI MASTER METHODS
 	implemented.
 
 
-SPI MESSAGE QUEUE
+SPI Message Queue
+^^^^^^^^^^^^^^^^^
 
 If you are happy with the standard queueing mechanism provided by the
 SPI subsystem, just implement the queued methods specified above. Using
@@ -619,13 +632,13 @@ THANKS TO
 Contributors to Linux-SPI discussions include (in alphabetical order,
 by last name):
 
-Mark Brown
-David Brownell
-Russell King
-Grant Likely
-Dmitry Pervushin
-Stephen Street
-Mark Underwood
-Andrew Victor
-Linus Walleij
-Vitaly Wool
+- Mark Brown
+- David Brownell
+- Russell King
+- Grant Likely
+- Dmitry Pervushin
+- Stephen Street
+- Mark Underwood
+- Andrew Victor
+- Linus Walleij
+- Vitaly Wool
diff --git a/Documentation/spi/spidev b/Documentation/spi/spidev.rst
similarity index 90%
rename from Documentation/spi/spidev
rename to Documentation/spi/spidev.rst
index 3d14035b1766..f05dbc5ccdbc 100644
--- a/Documentation/spi/spidev
+++ b/Documentation/spi/spidev.rst
@@ -1,7 +1,13 @@
+=================
+SPI userspace API
+=================
+
 SPI devices have a limited userspace API, supporting basic half-duplex
 read() and write() access to SPI slave devices.  Using ioctl() requests,
 full duplex transfers and device I/O configuration are also available.
 
+::
+
 	#include <fcntl.h>
 	#include <unistd.h>
 	#include <sys/ioctl.h>
@@ -39,14 +45,17 @@ device node with a "dev" attribute that will be understood by udev or mdev.
 busybox; it's less featureful, but often enough.)  For a SPI device with
 chipselect C on bus B, you should see:
 
-    /dev/spidevB.C ... character special device, major number 153 with
+    /dev/spidevB.C ...
+	character special device, major number 153 with
 	a dynamically chosen minor device number.  This is the node
 	that userspace programs will open, created by "udev" or "mdev".
 
-    /sys/devices/.../spiB.C ... as usual, the SPI device node will
+    /sys/devices/.../spiB.C ...
+	as usual, the SPI device node will
 	be a child of its SPI master controller.
 
-    /sys/class/spidev/spidevB.C ... created when the "spidev" driver
+    /sys/class/spidev/spidevB.C ...
+	created when the "spidev" driver
 	binds to that device.  (Directory or symlink, based on whether
 	or not you enabled the "deprecated sysfs files" Kconfig option.)
 
@@ -80,7 +89,8 @@ the SPI_IOC_MESSAGE(N) request.
 Several ioctl() requests let your driver read or override the device's current
 settings for data transfer parameters:
 
-    SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will
+    SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ...
+	pass a pointer to a byte which will
 	return (RD) or assign (WR) the SPI transfer mode.  Use the constants
 	SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL
 	(clock polarity, idle high iff this is set) or SPI_CPHA (clock phase,
@@ -88,22 +98,26 @@ settings for data transfer parameters:
 	Note that this request is limited to SPI mode flags that fit in a
 	single byte.
 
-    SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... pass a pointer to a uin32_t
+    SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ...
+	pass a pointer to a uin32_t
 	which will return (RD) or assign (WR) the full SPI transfer mode,
 	not limited to the bits that fit in one byte.
 
-    SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte
+    SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ...
+	pass a pointer to a byte
 	which will return (RD) or assign (WR) the bit justification used to
 	transfer SPI words.  Zero indicates MSB-first; other values indicate
 	the less common LSB-first encoding.  In both cases the specified value
 	is right-justified in each word, so that unused (TX) or undefined (RX)
 	bits are in the MSBs.
 
-    SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to
+    SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ...
+	pass a pointer to
 	a byte which will return (RD) or assign (WR) the number of bits in
 	each SPI transfer word.  The value zero signifies eight bits.
 
-    SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a
+    SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ...
+	pass a pointer to a
 	u32 which will return (RD) or assign (WR) the maximum SPI transfer
 	speed, in Hz.  The controller can't necessarily assign that specific
 	clock speed.
diff --git a/drivers/iio/dummy/iio_simple_dummy.c b/drivers/iio/dummy/iio_simple_dummy.c
index d28974ad9e0e..6cb02299a215 100644
--- a/drivers/iio/dummy/iio_simple_dummy.c
+++ b/drivers/iio/dummy/iio_simple_dummy.c
@@ -695,7 +695,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
  * i2c:
  * Documentation/i2c/writing-clients.rst
  * spi:
- * Documentation/spi/spi-summary
+ * Documentation/spi/spi-summary.rst
  */
 static const struct iio_sw_device_ops iio_dummy_device_ops = {
 	.probe = iio_dummy_probe,
diff --git a/drivers/spi/Kconfig b/drivers/spi/Kconfig
index 3a1d8f1170de..d5a24fe983e7 100644
--- a/drivers/spi/Kconfig
+++ b/drivers/spi/Kconfig
@@ -543,7 +543,7 @@ config SPI_PXA2XX
 	help
 	  This enables using a PXA2xx or Sodaville SSP port as a SPI master
 	  controller. The driver can be configured to use any SSP port and
-	  additional documentation can be found a Documentation/spi/pxa2xx.
+	  additional documentation can be found a Documentation/spi/pxa2xx.rst.
 
 config SPI_PXA2XX_PCI
 	def_tristate SPI_PXA2XX && PCI && COMMON_CLK
diff --git a/drivers/spi/spi-butterfly.c b/drivers/spi/spi-butterfly.c
index 8c77d1114ad3..7e71a351f3b7 100644
--- a/drivers/spi/spi-butterfly.c
+++ b/drivers/spi/spi-butterfly.c
@@ -23,7 +23,7 @@
  * with a battery powered AVR microcontroller and lots of goodies.  You
  * can use GCC to develop firmware for this.
  *
- * See Documentation/spi/butterfly for information about how to build
+ * See Documentation/spi/butterfly.rst for information about how to build
  * and use this custom parallel port cable.
  */
 
diff --git a/drivers/spi/spi-lm70llp.c b/drivers/spi/spi-lm70llp.c
index f18f912c9dea..174dba29b1dd 100644
--- a/drivers/spi/spi-lm70llp.c
+++ b/drivers/spi/spi-lm70llp.c
@@ -34,7 +34,7 @@
  * available (on page 4) here:
  *  http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf
  *
- * Also see Documentation/spi/spi-lm70llp.  The SPI<->parport code here is
+ * Also see Documentation/spi/spi-lm70llp.rst.  The SPI<->parport code here is
  * (heavily) based on spi-butterfly by David Brownell.
  *
  * The LM70 LLP connects to the PC parallel port in the following manner:
diff --git a/include/linux/platform_data/sc18is602.h b/include/linux/platform_data/sc18is602.h
index e066d3b0d6d8..0e91489edfe6 100644
--- a/include/linux/platform_data/sc18is602.h
+++ b/include/linux/platform_data/sc18is602.h
@@ -4,7 +4,7 @@
  *
  * Copyright (C) 2012 Guenter Roeck <linux@roeck-us.net>
  *
- * For further information, see the Documentation/spi/spi-sc18is602 file.
+ * For further information, see the Documentation/spi/spi-sc18is602.rst file.
  */
 
 /**
-- 
2.21.0


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

* [PATCH v2 09/26] docs: ipmb: place it at driver-api and convert to ReST
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (11 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-doc

No new doc should be added at the main Documentation/ directory.

Instead, new docs should be added as ReST files, within the
Kernel documentation body.

Fixes: 51bd6f291583 ("Add support for IPMB driver")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/driver-api/index.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index 37ac052ded85..38e638abe3eb 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -76,6 +76,7 @@ available subsections can be seen below.
    dell_rbu
    edid
    eisa
+   ipmb
    isa
    isapnp
    generic-counter
-- 
2.21.0


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

* [PATCH v2 10/26] docs: packing: move it to core-api book and adjust markups
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (12 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Vladimir Oltean,
	linux-doc, netdev, Mike Rapoport

The packing.txt file was misplaced, as docs should be part of
a documentation book, and not at the root dir.

So, move it to the core-api directory and add to its index.

Also, ensure that the file will be properly parsed and the bitmap
ascii artwork will use a monotonic font.

Fixes: 554aae35007e ("lib: Add support for generic packing operations")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Reviewed-by: Vladimir Oltean <olteanv@gmail.com>
Tested-by: Vladimir Oltean <olteanv@gmail.com>
Reviewed-by: Mike Rapoport <rppt@linux.ibm.com>
---
 Documentation/core-api/index.rst              |  1 +
 .../{packing.txt => core-api/packing.rst}     | 81 +++++++++++--------
 MAINTAINERS                                   |  2 +-
 3 files changed, 51 insertions(+), 33 deletions(-)
 rename Documentation/{packing.txt => core-api/packing.rst} (61%)

diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index da0ed972d224..dfd8fad1e1ec 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -25,6 +25,7 @@ Core utilities
    librs
    genalloc
    errseq
+   packing
    printk-formats
    circular-buffers
    generic-radix-tree
diff --git a/Documentation/packing.txt b/Documentation/core-api/packing.rst
similarity index 61%
rename from Documentation/packing.txt
rename to Documentation/core-api/packing.rst
index f830c98645f1..d8c341fe383e 100644
--- a/Documentation/packing.txt
+++ b/Documentation/core-api/packing.rst
@@ -30,6 +30,7 @@ The solution
 ------------
 
 This API deals with 2 basic operations:
+
   - Packing a CPU-usable number into a memory buffer (with hardware
     constraints/quirks)
   - Unpacking a memory buffer (which has hardware constraints/quirks)
@@ -49,10 +50,12 @@ What the examples show is where the logical bytes and bits sit.
 
 1. Normally (no quirks), we would do it like this:
 
-63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
-7                       6                       5                        4
-31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
-3                       2                       1                        0
+::
+
+  63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
+  7                       6                       5                        4
+  31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
+  3                       2                       1                        0
 
 That is, the MSByte (7) of the CPU-usable u64 sits at memory offset 0, and the
 LSByte (0) of the u64 sits at memory offset 7.
@@ -63,10 +66,12 @@ comments as "logical" notation.
 
 2. If QUIRK_MSB_ON_THE_RIGHT is set, we do it like this:
 
-56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
-7                       6                        5                       4
-24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23  8  9 10 11 12 13 14 15  0  1  2  3  4  5  6  7
-3                       2                        1                       0
+::
+
+  56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
+  7                       6                        5                       4
+  24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23  8  9 10 11 12 13 14 15  0  1  2  3  4  5  6  7
+  3                       2                        1                       0
 
 That is, QUIRK_MSB_ON_THE_RIGHT does not affect byte positioning, but
 inverts bit offsets inside a byte.
@@ -74,10 +79,12 @@ inverts bit offsets inside a byte.
 
 3. If QUIRK_LITTLE_ENDIAN is set, we do it like this:
 
-39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
-4                       5                       6                       7
-7  6  5  4  3  2  1  0  15 14 13 12 11 10  9  8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
-0                       1                       2                       3
+::
+
+  39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
+  4                       5                       6                       7
+  7  6  5  4  3  2  1  0  15 14 13 12 11 10  9  8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
+  0                       1                       2                       3
 
 Therefore, QUIRK_LITTLE_ENDIAN means that inside the memory region, every
 byte from each 4-byte word is placed at its mirrored position compared to
@@ -86,18 +93,22 @@ the boundary of that word.
 4. If QUIRK_MSB_ON_THE_RIGHT and QUIRK_LITTLE_ENDIAN are both set, we do it
    like this:
 
-32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
-4                       5                       6                       7
-0  1  2  3  4  5  6  7  8   9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
-0                       1                       2                       3
+::
+
+  32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
+  4                       5                       6                       7
+  0  1  2  3  4  5  6  7  8   9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+  0                       1                       2                       3
 
 
 5. If just QUIRK_LSW32_IS_FIRST is set, we do it like this:
 
-31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
-3                       2                       1                        0
-63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
-7                       6                       5                        4
+::
+
+  31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
+  3                       2                       1                        0
+  63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48 47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
+  7                       6                       5                        4
 
 In this case the 8 byte memory region is interpreted as follows: first
 4 bytes correspond to the least significant 4-byte word, next 4 bytes to
@@ -107,28 +118,34 @@ the more significant 4-byte word.
 6. If QUIRK_LSW32_IS_FIRST and QUIRK_MSB_ON_THE_RIGHT are set, we do it like
    this:
 
-24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23  8  9 10 11 12 13 14 15  0  1  2  3  4  5  6  7
-3                       2                        1                       0
-56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
-7                       6                        5                       4
+::
+
+  24 25 26 27 28 29 30 31 16 17 18 19 20 21 22 23  8  9 10 11 12 13 14 15  0  1  2  3  4  5  6  7
+  3                       2                        1                       0
+  56 57 58 59 60 61 62 63 48 49 50 51 52 53 54 55 40 41 42 43 44 45 46 47 32 33 34 35 36 37 38 39
+  7                       6                        5                       4
 
 
 7. If QUIRK_LSW32_IS_FIRST and QUIRK_LITTLE_ENDIAN are set, it looks like
    this:
 
-7  6  5  4  3  2  1  0  15 14 13 12 11 10  9  8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
-0                       1                       2                       3
-39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
-4                       5                       6                       7
+::
+
+  7  6  5  4  3  2  1  0  15 14 13 12 11 10  9  8 23 22 21 20 19 18 17 16 31 30 29 28 27 26 25 24
+  0                       1                       2                       3
+  39 38 37 36 35 34 33 32 47 46 45 44 43 42 41 40 55 54 53 52 51 50 49 48 63 62 61 60 59 58 57 56
+  4                       5                       6                       7
 
 
 8. If QUIRK_LSW32_IS_FIRST, QUIRK_LITTLE_ENDIAN and QUIRK_MSB_ON_THE_RIGHT
    are set, it looks like this:
 
-0  1  2  3  4  5  6  7  8   9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
-0                       1                       2                       3
-32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
-4                       5                       6                       7
+::
+
+  0  1  2  3  4  5  6  7  8   9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
+  0                       1                       2                       3
+  32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
+  4                       5                       6                       7
 
 
 We always think of our offsets as if there were no quirk, and we translate
diff --git a/MAINTAINERS b/MAINTAINERS
index 8fcb0c65ab91..e5593c66f904 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -12089,7 +12089,7 @@ L:	netdev@vger.kernel.org
 S:	Supported
 F:	lib/packing.c
 F:	include/linux/packing.h
-F:	Documentation/packing.txt
+F:	Documentation/core-api/packing.rst
 
 PADATA PARALLEL EXECUTION MECHANISM
 M:	Steffen Klassert <steffen.klassert@secunet.com>
-- 
2.21.0


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

* [PATCH v2 11/26] docs: admin-guide: add auxdisplay files to it after conversion to ReST
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (13 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Miguel Ojeda Sandonis, linux-doc

Those two files describe userspace-faced information. While part of
it might fit on uAPI, it sounds to me that the admin guide is the
best place for them.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>
---
 .../auxdisplay/cfag12864b.rst}                | 115 ++++++++----------
 .../admin-guide/auxdisplay/index.rst          |  16 +++
 .../auxdisplay/ks0108.rst}                    |  53 ++++----
 Documentation/admin-guide/index.rst           |   1 +
 MAINTAINERS                                   |   2 +-
 drivers/auxdisplay/Kconfig                    |   2 +-
 6 files changed, 97 insertions(+), 92 deletions(-)
 rename Documentation/{auxdisplay/cfag12864b => admin-guide/auxdisplay/cfag12864b.rst} (26%)
 create mode 100644 Documentation/admin-guide/auxdisplay/index.rst
 rename Documentation/{auxdisplay/ks0108 => admin-guide/auxdisplay/ks0108.rst} (32%)

diff --git a/Documentation/auxdisplay/cfag12864b b/Documentation/admin-guide/auxdisplay/cfag12864b.rst
similarity index 26%
rename from Documentation/auxdisplay/cfag12864b
rename to Documentation/admin-guide/auxdisplay/cfag12864b.rst
index 12fd51b8de75..18c2865bd322 100644
--- a/Documentation/auxdisplay/cfag12864b
+++ b/Documentation/admin-guide/auxdisplay/cfag12864b.rst
@@ -1,92 +1,85 @@
-	===================================
-	cfag12864b LCD Driver Documentation
-	===================================
+===================================
+cfag12864b LCD Driver Documentation
+===================================
 
-License:		GPLv2
-Author & Maintainer:	Miguel Ojeda Sandonis
-Date:			2006-10-27
+:License:		GPLv2
+:Author & Maintainer:	Miguel Ojeda Sandonis
+:Date:			2006-10-27
 
 
 
---------
-0. INDEX
---------
+.. INDEX
 
 	1. DRIVER INFORMATION
 	2. DEVICE INFORMATION
 	3. WIRING
 	4. USERSPACE PROGRAMMING
 
-
----------------------
-1. DRIVER INFORMATION
+1. Driver Information
 ---------------------
 
 This driver supports a cfag12864b LCD.
 
 
----------------------
-2. DEVICE INFORMATION
+2. Device Information
 ---------------------
 
-Manufacturer:	Crystalfontz
-Device Name:	Crystalfontz 12864b LCD Series
-Device Code:	cfag12864b
-Webpage:	http://www.crystalfontz.com
-Device Webpage:	http://www.crystalfontz.com/products/12864b/
-Type:		LCD (Liquid Crystal Display)
-Width:		128
-Height:		64
-Colors:		2 (B/N)
-Controller:	ks0108
-Controllers:	2
-Pages:		8 each controller
-Addresses:	64 each page
-Data size:	1 byte each address
-Memory size:	2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte
+:Manufacturer:	Crystalfontz
+:Device Name:	Crystalfontz 12864b LCD Series
+:Device Code:	cfag12864b
+:Webpage:	http://www.crystalfontz.com
+:Device Webpage: http://www.crystalfontz.com/products/12864b/
+:Type:		LCD (Liquid Crystal Display)
+:Width:		128
+:Height:	64
+:Colors:	2 (B/N)
+:Controller:	ks0108
+:Controllers:	2
+:Pages:		8 each controller
+:Addresses:	64 each page
+:Data size:	1 byte each address
+:Memory size:	2 * 8 * 64 * 1 = 1024 bytes = 1 Kbyte
 
 
----------
-3. WIRING
+3. Wiring
 ---------
 
 The cfag12864b LCD Series don't have official wiring.
 
-The common wiring is done to the parallel port as shown:
+The common wiring is done to the parallel port as shown::
 
-Parallel Port                          cfag12864b
+  Parallel Port                          cfag12864b
 
-  Name Pin#                            Pin# Name
+    Name Pin#                            Pin# Name
 
-Strobe ( 1)------------------------------(17) Enable
-Data 0 ( 2)------------------------------( 4) Data 0
-Data 1 ( 3)------------------------------( 5) Data 1
-Data 2 ( 4)------------------------------( 6) Data 2
-Data 3 ( 5)------------------------------( 7) Data 3
-Data 4 ( 6)------------------------------( 8) Data 4
-Data 5 ( 7)------------------------------( 9) Data 5
-Data 6 ( 8)------------------------------(10) Data 6
-Data 7 ( 9)------------------------------(11) Data 7
-       (10)                      [+5v]---( 1) Vdd
-       (11)                      [GND]---( 2) Ground
-       (12)                      [+5v]---(14) Reset
-       (13)                      [GND]---(15) Read / Write
-  Line (14)------------------------------(13) Controller Select 1
-       (15)
-  Init (16)------------------------------(12) Controller Select 2
-Select (17)------------------------------(16) Data / Instruction
-Ground (18)---[GND]              [+5v]---(19) LED +
-Ground (19)---[GND]
-Ground (20)---[GND]              E    A             Values:
-Ground (21)---[GND]       [GND]---[P1]---(18) Vee    - R = Resistor = 22 ohm
-Ground (22)---[GND]                |                 - P1 = Preset = 10 Kohm
-Ground (23)---[GND]       ----   S ------( 3) V0     - P2 = Preset = 1 Kohm
-Ground (24)---[GND]       |  |
-Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED -
+  Strobe ( 1)------------------------------(17) Enable
+  Data 0 ( 2)------------------------------( 4) Data 0
+  Data 1 ( 3)------------------------------( 5) Data 1
+  Data 2 ( 4)------------------------------( 6) Data 2
+  Data 3 ( 5)------------------------------( 7) Data 3
+  Data 4 ( 6)------------------------------( 8) Data 4
+  Data 5 ( 7)------------------------------( 9) Data 5
+  Data 6 ( 8)------------------------------(10) Data 6
+  Data 7 ( 9)------------------------------(11) Data 7
+         (10)                      [+5v]---( 1) Vdd
+         (11)                      [GND]---( 2) Ground
+         (12)                      [+5v]---(14) Reset
+         (13)                      [GND]---(15) Read / Write
+    Line (14)------------------------------(13) Controller Select 1
+         (15)
+    Init (16)------------------------------(12) Controller Select 2
+  Select (17)------------------------------(16) Data / Instruction
+  Ground (18)---[GND]              [+5v]---(19) LED +
+  Ground (19)---[GND]
+  Ground (20)---[GND]              E    A             Values:
+  Ground (21)---[GND]       [GND]---[P1]---(18) Vee    - R = Resistor = 22 ohm
+  Ground (22)---[GND]                |                 - P1 = Preset = 10 Kohm
+  Ground (23)---[GND]       ----   S ------( 3) V0     - P2 = Preset = 1 Kohm
+  Ground (24)---[GND]       |  |
+  Ground (25)---[GND] [GND]---[P2]---[R]---(20) LED -
 
 
-------------------------
-4. USERSPACE PROGRAMMING
+4. Userspace Programming
 ------------------------
 
 The cfag12864bfb describes a framebuffer device (/dev/fbX).
diff --git a/Documentation/admin-guide/auxdisplay/index.rst b/Documentation/admin-guide/auxdisplay/index.rst
new file mode 100644
index 000000000000..e466f0595248
--- /dev/null
+++ b/Documentation/admin-guide/auxdisplay/index.rst
@@ -0,0 +1,16 @@
+=========================
+Auxiliary Display Support
+=========================
+
+.. toctree::
+    :maxdepth: 1
+
+    ks0108.rst
+    cfag12864b.rst
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/auxdisplay/ks0108 b/Documentation/admin-guide/auxdisplay/ks0108.rst
similarity index 32%
rename from Documentation/auxdisplay/ks0108
rename to Documentation/admin-guide/auxdisplay/ks0108.rst
index 8ddda0c8ceef..c0b7faf73136 100644
--- a/Documentation/auxdisplay/ks0108
+++ b/Documentation/admin-guide/auxdisplay/ks0108.rst
@@ -1,50 +1,45 @@
-	==========================================
-	ks0108 LCD Controller Driver Documentation
-	==========================================
+==========================================
+ks0108 LCD Controller Driver Documentation
+==========================================
 
-License:		GPLv2
-Author & Maintainer:	Miguel Ojeda Sandonis
-Date:			2006-10-27
+:License:		GPLv2
+:Author & Maintainer:	Miguel Ojeda Sandonis
+:Date:			2006-10-27
 
 
 
---------
-0. INDEX
---------
+.. INDEX
 
 	1. DRIVER INFORMATION
 	2. DEVICE INFORMATION
 	3. WIRING
 
 
----------------------
-1. DRIVER INFORMATION
+1. Driver Information
 ---------------------
 
 This driver supports the ks0108 LCD controller.
 
 
----------------------
-2. DEVICE INFORMATION
+2. Device Information
 ---------------------
 
-Manufacturer:	Samsung
-Device Name:	KS0108 LCD Controller
-Device Code:	ks0108
-Webpage:	-
-Device Webpage:	-
-Type:		LCD Controller (Liquid Crystal Display Controller)
-Width:		64
-Height:		64
-Colors:		2 (B/N)
-Pages:		8
-Addresses:	64 each page
-Data size:	1 byte each address
-Memory size:	8 * 64 * 1 = 512 bytes
+:Manufacturer:	Samsung
+:Device Name:	KS0108 LCD Controller
+:Device Code:	ks0108
+:Webpage:	-
+:Device Webpage: -
+:Type:		LCD Controller (Liquid Crystal Display Controller)
+:Width:		64
+:Height:	64
+:Colors:	2 (B/N)
+:Pages:		8
+:Addresses:	64 each page
+:Data size:	1 byte each address
+:Memory size:	8 * 64 * 1 = 512 bytes
 
 
----------
-3. WIRING
+3. Wiring
 ---------
 
 The driver supports data parallel port wiring.
@@ -52,4 +47,4 @@ The driver supports data parallel port wiring.
 If you aren't building LCD related hardware, you should check
 your LCD specific wiring information in the same folder.
 
-For example, check Documentation/auxdisplay/cfag12864b.
+For example, check Documentation/admin-guide/auxdisplay/cfag12864b.rst
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 33feab2f4084..99d84f5f80db 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -98,6 +98,7 @@ configure specific aspects of kernel behavior to your liking.
    iostats
    kernel-per-CPU-kthreads
    laptops/index
+   auxdisplay/index
    lcd-panel-cgram
    ldm
    lockup-watchdogs
diff --git a/MAINTAINERS b/MAINTAINERS
index e5593c66f904..2055887f07ef 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8991,7 +8991,7 @@ F:	kernel/kprobes.c
 KS0108 LCD CONTROLLER DRIVER
 M:	Miguel Ojeda Sandonis <miguel.ojeda.sandonis@gmail.com>
 S:	Maintained
-F:	Documentation/auxdisplay/ks0108
+F:	Documentation/admin-guide/auxdisplay/ks0108.rst
 F:	drivers/auxdisplay/ks0108.c
 F:	include/linux/ks0108.h
 
diff --git a/drivers/auxdisplay/Kconfig b/drivers/auxdisplay/Kconfig
index dd61fdd400f0..6b476e663e80 100644
--- a/drivers/auxdisplay/Kconfig
+++ b/drivers/auxdisplay/Kconfig
@@ -97,7 +97,7 @@ config CFAG12864B
 	  say Y. You also need the ks0108 LCD Controller driver.
 
 	  For help about how to wire your LCD to the parallel port,
-	  check Documentation/auxdisplay/cfag12864b
+	  check Documentation/admin-guide/auxdisplay/cfag12864b.rst
 
 	  Depends on the x86 arch and the framebuffer support.
 
-- 
2.21.0


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

* [PATCH v2 12/26] docs: README.buddha: convert to ReST and add to m68k book
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (14 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-doc

Adjust the file for it to be properly parsed by Sphinx, adding
it to the index of the book it belongs.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 .../m68k/{README.buddha => buddha-driver.rst} | 95 +++++++++----------
 Documentation/m68k/index.rst                  |  1 +
 2 files changed, 48 insertions(+), 48 deletions(-)
 rename Documentation/m68k/{README.buddha => buddha-driver.rst} (73%)

diff --git a/Documentation/m68k/README.buddha b/Documentation/m68k/buddha-driver.rst
similarity index 73%
rename from Documentation/m68k/README.buddha
rename to Documentation/m68k/buddha-driver.rst
index 3ea9827ba3c7..20e401413991 100644
--- a/Documentation/m68k/README.buddha
+++ b/Documentation/m68k/buddha-driver.rst
@@ -1,3 +1,6 @@
+=====================================
+Amiga Buddha and Catweasel IDE Driver
+=====================================
 
 The Amiga Buddha and Catweasel IDE Driver (part of ide.c) was written by
 Geert Uytterhoeven based on the following specifications:
@@ -12,12 +15,12 @@ described  in  their  manuals, no tricks have been used (for
 example leaving some address lines out of the equations...).
 If you want to configure the board yourself (for example let
 a  Linux  kernel  configure the card), look at the Commodore
-Docs.  Reading the nibbles should give this information:
+Docs.  Reading the nibbles should give this information::
 
-Vendor number: 4626 ($1212)
-product number: 0 (42 for Catweasel Z-II)
-Serial number: 0
-Rom-vector: $1000
+  Vendor number: 4626 ($1212)
+  product number: 0 (42 for Catweasel Z-II)
+  Serial number: 0
+  Rom-vector: $1000
 
 The  card  should be a Z-II board, size 64K, not for freemem
 list, Rom-Vektor is valid, no second Autoconfig-board on the
@@ -34,6 +37,7 @@ otherwise your chance is only 1:16 to find the board :-).
 
 The local memory-map is even active when mapped to $e8:
 
+==============  ===========================================
 $0-$7e		Autokonfig-space, see Z-II docs.
 
 $80-$7fd	reserved
@@ -50,50 +54,51 @@ $a00-$aff	IDE-Select 2 (Port 1, Register set 0)
 $b00-$bff	IDE-Select 3 (Port 1, Register set 1)
 
 $c00-$cff	IDE-Select 4 (Port 2, Register set 0,
-                          Catweasel only!)
+                Catweasel only!)
 
 $d00-$dff	IDE-Select 5 (Port 3, Register set 1,
-			      Catweasel only!)
+		Catweasel only!)
 
-$e00-$eff	local expansion port, on Catweasel Z-II the 
+$e00-$eff	local expansion port, on Catweasel Z-II the
 		Catweasel registers are also mapped here.
 		Never touch, use multidisk.device!
-		
-$f00		read only, Byte-access: Bit 7 shows the 
-		level of the IRQ-line of IDE port 0. 
+
+$f00		read only, Byte-access: Bit 7 shows the
+		level of the IRQ-line of IDE port 0.
 
 $f01-$f3f	mirror of $f00
 
-$f40		read only, Byte-access: Bit 7 shows the 
-		level of the IRQ-line of IDE port 1. 
+$f40		read only, Byte-access: Bit 7 shows the
+		level of the IRQ-line of IDE port 1.
 
 $f41-$f7f	mirror of $f40
 
-$f80		read only, Byte-access: Bit 7 shows the 
-		level of the IRQ-line of IDE port 2. 
+$f80		read only, Byte-access: Bit 7 shows the
+		level of the IRQ-line of IDE port 2.
 		(Catweasel only!)
 
 $f81-$fbf	mirror of $f80
 
 $fc0		write-only: Writing any value to this
-		register enables IRQs to be passed from the 
-		IDE ports to the Zorro bus. This mechanism 
-		has been implemented to be compatible with 
+		register enables IRQs to be passed from the
+		IDE ports to the Zorro bus. This mechanism
+		has been implemented to be compatible with
 		harddisks that are either defective or have
-		a buggy firmware and pull the IRQ line up 
-		while starting up. If interrupts would 
-		always be passed to the bus, the computer 
-		might not start up. Once enabled, this flag 
-		can not be disabled again. The level of the 
-		flag can not be determined by software 
+		a buggy firmware and pull the IRQ line up
+		while starting up. If interrupts would
+		always be passed to the bus, the computer
+		might not start up. Once enabled, this flag
+		can not be disabled again. The level of the
+		flag can not be determined by software
 		(what for? Write to me if it's necessary!).
 
 $fc1-$fff	mirror of $fc0
 
 $1000-$ffff	Buddha-Rom with offset $1000 in the rom
-		chip. The addresses $0 to $fff of the rom 
+		chip. The addresses $0 to $fff of the rom
 		chip cannot be read. Rom is Byte-wide and
 		mapped to even addresses.
+==============  ===========================================
 
 The  IDE ports issue an INT2.  You can read the level of the
 IRQ-lines  of  the  IDE-ports by reading from the three (two
@@ -128,7 +133,8 @@ must  always  be set to 1 to be compatible with later Buddha
 versions  (if  I'll  ever  update this one).  I presume that
 I'll  never use the lower four bits, but they have to be set
 to 1 by definition.
-  The  values in this table have to be shifted 5 bits to the
+
+The  values in this table have to be shifted 5 bits to the
 left and or'd with $1f (this sets the lower 5 bits).
 
 All  the timings have in common:  Select and IOR/IOW rise at
@@ -138,44 +144,36 @@ values  are no multiple of 71.  One clock-cycle is 71ns long
 (exactly 70,5 at 14,18 Mhz on PAL systems).
 
 value 0 (Default after reset)
-
-497ns Select (7 clock cycles) , IOR/IOW after 172ns (2 clock cycles)
-(same timing as the Amiga 1200 does on it's IDE port without
-accelerator card)
+  497ns Select (7 clock cycles) , IOR/IOW after 172ns (2 clock cycles)
+  (same timing as the Amiga 1200 does on it's IDE port without
+  accelerator card)
 
 value 1
-
-639ns Select (9 clock cycles), IOR/IOW after 243ns (3 clock cycles)
+  639ns Select (9 clock cycles), IOR/IOW after 243ns (3 clock cycles)
 
 value 2
-
-781ns Select (11 clock cycles), IOR/IOW after 314ns (4 clock cycles)
+  781ns Select (11 clock cycles), IOR/IOW after 314ns (4 clock cycles)
 
 value 3
-
-355ns Select (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
+  355ns Select (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
 
 value 4
-
-355ns Select (5 clock cycles), IOR/IOW after 172ns (2 clock cycles)
+  355ns Select (5 clock cycles), IOR/IOW after 172ns (2 clock cycles)
 
 value 5
-
-355ns Select (5 clock cycles), IOR/IOW after 243ns (3 clock cycles)
+  355ns Select (5 clock cycles), IOR/IOW after 243ns (3 clock cycles)
 
 value 6
-
-1065ns Select (15 clock cycles), IOR/IOW after 314ns (4 clock cycles)
+  1065ns Select (15 clock cycles), IOR/IOW after 314ns (4 clock cycles)
 
 value 7
-
-355ns Select, (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
+  355ns Select, (5 clock cycles), IOR/IOW after 101ns (1 clock cycle)
 
 When accessing IDE registers with A6=1 (for example $84x),
 the timing will always be mode 0 8-bit compatible, no matter
 what you have selected in the speed register:
 
-781ns select, IOR/IOW after 4 clock cycles (=314ns) aktive. 
+781ns select, IOR/IOW after 4 clock cycles (=314ns) aktive.
 
 All  the  timings with a very short select-signal (the 355ns
 fast  accesses)  depend  on the accelerator card used in the
@@ -204,7 +202,8 @@ always  shows a "no IRQ here" on the Buddha, and accesses to
 the  third  IDE  port  are  going into data's Nirwana on the
 Buddha.
 
-			    Jens Schönfeld february 19th, 1997
-					updated may 27th, 1997
-			     eMail: sysop@nostlgic.tng.oche.de
+Jens Schönfeld february 19th, 1997
 
+updated may 27th, 1997
+
+eMail: sysop@nostlgic.tng.oche.de
diff --git a/Documentation/m68k/index.rst b/Documentation/m68k/index.rst
index 3a5ba7fe1703..b89cb6a86d9b 100644
--- a/Documentation/m68k/index.rst
+++ b/Documentation/m68k/index.rst
@@ -8,6 +8,7 @@ m68k Architecture
    :maxdepth: 2
 
    kernel-options
+   buddha-driver
 
 .. only::  subproject and html
 
-- 
2.21.0


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

* [PATCH v2 13/26] docs: parisc: convert to ReST and add to documentation body
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (15 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, James E.J. Bottomley,
	Helge Deller, linux-doc, linux-parisc

Manually convert the two PA-RISC documents to ReST, adding them
to the Linux documentation body.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/index.rst                       |  1 +
 .../parisc/{debugging => debugging.rst}       |  7 +++
 Documentation/parisc/index.rst                | 18 ++++++
 .../parisc/{registers => registers.rst}       | 59 +++++++++++++------
 4 files changed, 68 insertions(+), 17 deletions(-)
 rename Documentation/parisc/{debugging => debugging.rst} (94%)
 create mode 100644 Documentation/parisc/index.rst
 rename Documentation/parisc/{registers => registers.rst} (70%)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index d9e607d8a9b9..25e080664050 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -148,6 +148,7 @@ implementation.
    ia64/index
    m68k/index
    powerpc/index
+   parisc/index
    riscv/index
    s390/index
    sh/index
diff --git a/Documentation/parisc/debugging b/Documentation/parisc/debugging.rst
similarity index 94%
rename from Documentation/parisc/debugging
rename to Documentation/parisc/debugging.rst
index 7d75223fa18d..de1b60402c5b 100644
--- a/Documentation/parisc/debugging
+++ b/Documentation/parisc/debugging.rst
@@ -1,8 +1,13 @@
+=================
+PA-RISC Debugging
+=================
+
 okay, here are some hints for debugging the lower-level parts of
 linux/parisc.
 
 
 1. Absolute addresses
+=====================
 
 A lot of the assembly code currently runs in real mode, which means
 absolute addresses are used instead of virtual addresses as in the
@@ -12,6 +17,7 @@ currently).
 
 
 2. HPMCs
+========
 
 When real-mode code tries to access non-existent memory, you'll get
 an HPMC instead of a kernel oops.  To debug an HPMC, try to find
@@ -27,6 +33,7 @@ access it.
 
 
 3. Q bit fun
+============
 
 Certain, very critical code has to clear the Q bit in the PSW.  What
 happens when the Q bit is cleared is the CPU does not update the
diff --git a/Documentation/parisc/index.rst b/Documentation/parisc/index.rst
new file mode 100644
index 000000000000..aa3ee0470425
--- /dev/null
+++ b/Documentation/parisc/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+PA-RISC Architecture
+====================
+
+.. toctree::
+   :maxdepth: 2
+
+   debugging
+   registers
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/parisc/registers b/Documentation/parisc/registers.rst
similarity index 70%
rename from Documentation/parisc/registers
rename to Documentation/parisc/registers.rst
index 10c7d1730f5d..59c8ecf3e856 100644
--- a/Documentation/parisc/registers
+++ b/Documentation/parisc/registers.rst
@@ -1,11 +1,16 @@
+================================
 Register Usage for Linux/PA-RISC
+================================
 
 [ an asterisk is used for planned usage which is currently unimplemented ]
 
-	General Registers as specified by ABI
+General Registers as specified by ABI
+=====================================
 
-	Control Registers
+Control Registers
+-----------------
 
+===============================	===============================================
 CR 0 (Recovery Counter)		used for ptrace
 CR 1-CR 7(undefined)		unused
 CR 8 (Protection ID)		per-process value*
@@ -29,26 +34,35 @@ CR28 (TR 4)			not used
 CR29 (TR 5)			not used
 CR30 (TR 6)			current / 0
 CR31 (TR 7)			Temporary register, used in various places
+===============================	===============================================
 
-	Space Registers (kernel mode)
+Space Registers (kernel mode)
+-----------------------------
 
+===============================	===============================================
 SR0				temporary space register
 SR4-SR7 			set to 0
 SR1				temporary space register
 SR2				kernel should not clobber this
 SR3				used for userspace accesses (current process)
+===============================	===============================================
 
-	Space Registers (user mode)
+Space Registers (user mode)
+---------------------------
 
+===============================	===============================================
 SR0				temporary space register
 SR1                             temporary space register
 SR2                             holds space of linux gateway page
 SR3                             holds user address space value while in kernel
 SR4-SR7                         Defines short address space for user/kernel
+===============================	===============================================
 
 
-	Processor Status Word
+Processor Status Word
+---------------------
 
+===============================	===============================================
 W (64-bit addresses)		0
 E (Little-endian)		0
 S (Secure Interval Timer)	0
@@ -69,15 +83,19 @@ Q (collect interruption state)	1 (0 in code directly preceding an rfi)
 P (Protection Identifiers)	1*
 D (Data address translation)	1, 0 while executing real-mode code
 I (external interrupt mask)	used by cli()/sti() macros
+===============================	===============================================
 
-	"Invisible" Registers
+"Invisible" Registers
+---------------------
 
+===============================	===============================================
 PSW default W value		0
 PSW default E value		0
 Shadow Registers		used by interruption handler code
 TOC enable bit			1
+===============================	===============================================
 
-=========================================================================
+-------------------------------------------------------------------------
 
 The PA-RISC architecture defines 7 registers as "shadow registers".
 Those are used in RETURN FROM INTERRUPTION AND RESTORE instruction to reduce
@@ -85,7 +103,8 @@ the state save and restore time by eliminating the need for general register
 (GR) saves and restores in interruption handlers.
 Shadow registers are the GRs 1, 8, 9, 16, 17, 24, and 25.
 
-=========================================================================
+-------------------------------------------------------------------------
+
 Register usage notes, originally from John Marvin, with some additional
 notes from Randolph Chung.
 
@@ -96,10 +115,12 @@ course, you need to save them if you care about them, before calling
 another procedure. Some of the above registers do have special meanings
 that you should be aware of:
 
-    r1: The addil instruction is hardwired to place its result in r1,
+    r1:
+	The addil instruction is hardwired to place its result in r1,
 	so if you use that instruction be aware of that.
 
-    r2: This is the return pointer. In general you don't want to
+    r2:
+	This is the return pointer. In general you don't want to
 	use this, since you need the pointer to get back to your
 	caller. However, it is grouped with this set of registers
 	since the caller can't rely on the value being the same
@@ -107,23 +128,27 @@ that you should be aware of:
 	and return through that register after trashing r2, and
 	that should not cause a problem for the calling routine.
 
-    r19-r22: these are generally regarded as temporary registers.
+    r19-r22:
+	these are generally regarded as temporary registers.
 	Note that in 64 bit they are arg7-arg4.
 
-    r23-r26: these are arg3-arg0, i.e. you can use them if you
+    r23-r26:
+	these are arg3-arg0, i.e. you can use them if you
 	don't care about the values that were passed in anymore.
 
-    r28,r29: are ret0 and ret1. They are what you pass return values
+    r28,r29:
+	are ret0 and ret1. They are what you pass return values
 	in. r28 is the primary return. When returning small structures
 	r29 may also be used to pass data back to the caller.
 
-    r30: stack pointer
+    r30:
+	stack pointer
 
-    r31: the ble instruction puts the return pointer in here.
+    r31:
+	the ble instruction puts the return pointer in here.
 
 
-r3-r18,r27,r30 need to be saved and restored. r3-r18 are just
+    r3-r18,r27,r30 need to be saved and restored. r3-r18 are just
     general purpose registers. r27 is the data pointer, and is
     used to make references to global variables easier. r30 is
     the stack pointer.
-
-- 
2.21.0


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

* [PATCH v2 14/26] docs: openrisc: convert to ReST and add to documentation body
  2019-07-26 12:51 ` Mauro Carvalho Chehab
@ 2019-07-26 12:51   ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Jonas Bonn,
	Stefan Kristiansson, Stafford Horne, linux-doc, openrisc

Manually convert the two openRisc documents to ReST, adding them
to the Linux documentation body.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Stafford Horne <shorne@gmail.com>
---
 Documentation/index.rst                       |  1 +
 Documentation/openrisc/index.rst              | 18 +++++++++++++
 .../openrisc/{README => openrisc_port.rst}    | 25 +++++++++++++------
 Documentation/openrisc/{TODO => todo.rst}     |  9 ++++---
 4 files changed, 43 insertions(+), 10 deletions(-)
 create mode 100644 Documentation/openrisc/index.rst
 rename Documentation/openrisc/{README => openrisc_port.rst} (80%)
 rename Documentation/openrisc/{TODO => todo.rst} (78%)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 25e080664050..6402f62ac90f 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -148,6 +148,7 @@ implementation.
    ia64/index
    m68k/index
    powerpc/index
+   openrisc/index
    parisc/index
    riscv/index
    s390/index
diff --git a/Documentation/openrisc/index.rst b/Documentation/openrisc/index.rst
new file mode 100644
index 000000000000..748b3eea1707
--- /dev/null
+++ b/Documentation/openrisc/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
+OpenRISC Architecture
+=====================
+
+.. toctree::
+   :maxdepth: 2
+
+   openrisc_port
+   todo
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/openrisc/README b/Documentation/openrisc/openrisc_port.rst
similarity index 80%
rename from Documentation/openrisc/README
rename to Documentation/openrisc/openrisc_port.rst
index 777a893d533d..a18747a8d191 100644
--- a/Documentation/openrisc/README
+++ b/Documentation/openrisc/openrisc_port.rst
@@ -1,3 +1,4 @@
+==============
 OpenRISC Linux
 ==============
 
@@ -6,8 +7,10 @@ target architecture, specifically, is the 32-bit OpenRISC 1000 family (or1k).
 
 For information about OpenRISC processors and ongoing development:
 
+	=======		=============================
 	website		http://openrisc.io
 	email		openrisc@lists.librecores.org
+	=======		=============================
 
 ---------------------------------------------------------------------
 
@@ -24,13 +27,15 @@ Toolchain binaries can be obtained from openrisc.io or our github releases page.
 Instructions for building the different toolchains can be found on openrisc.io
 or Stafford's toolchain build and release scripts.
 
+	==========	=================================================
 	binaries	https://github.com/openrisc/or1k-gcc/releases
 	toolchains	https://openrisc.io/software
 	building	https://github.com/stffrdhrn/or1k-toolchain-build
+	==========	=================================================
 
 2) Building
 
-Build the Linux kernel as usual
+Build the Linux kernel as usual::
 
 	make ARCH=openrisc defconfig
 	make ARCH=openrisc
@@ -43,6 +48,8 @@ development board with the OpenRISC SoC.  During the build FPGA RTL is code
 downloaded from the FuseSoC IP cores repository and built using the FPGA vendor
 tools.  Binaries are loaded onto the board with openocd.
 
+::
+
 	git clone https://github.com/olofk/fusesoc
 	cd fusesoc
 	sudo pip install -e .
@@ -65,7 +72,9 @@ platform.  Please follow the OpenRISC instructions on the QEMU website to get
 Linux running on QEMU.  You can build QEMU yourself, but your Linux distribution
 likely provides binary packages to support OpenRISC.
 
+	=============	======================================================
 	qemu openrisc	https://wiki.qemu.org/Documentation/Platforms/OpenRISC
+	=============	======================================================
 
 ---------------------------------------------------------------------
 
@@ -75,36 +84,38 @@ Terminology
 In the code, the following particles are used on symbols to limit the scope
 to more or less specific processor implementations:
 
+========= =======================================
 openrisc: the OpenRISC class of processors
 or1k:     the OpenRISC 1000 family of processors
 or1200:   the OpenRISC 1200 processor
+========= =======================================
 
 ---------------------------------------------------------------------
 
 History
 ========
 
-18. 11. 2003	Matjaz Breskvar (phoenix@bsemi.com)
+18-11-2003	Matjaz Breskvar (phoenix@bsemi.com)
 	initial port of linux to OpenRISC/or32 architecture.
         all the core stuff is implemented and seams usable.
 
-08. 12. 2003	Matjaz Breskvar (phoenix@bsemi.com)
+08-12-2003	Matjaz Breskvar (phoenix@bsemi.com)
 	complete change of TLB miss handling.
 	rewrite of exceptions handling.
 	fully functional sash-3.6 in default initrd.
 	a much improved version with changes all around.
 
-10. 04. 2004	Matjaz Breskvar (phoenix@bsemi.com)
+10-04-2004	Matjaz Breskvar (phoenix@bsemi.com)
 	alot of bugfixes all over.
 	ethernet support, functional http and telnet servers.
 	running many standard linux apps.
 
-26. 06. 2004	Matjaz Breskvar (phoenix@bsemi.com)
+26-06-2004	Matjaz Breskvar (phoenix@bsemi.com)
 	port to 2.6.x
 
-30. 11. 2004	Matjaz Breskvar (phoenix@bsemi.com)
+30-11-2004	Matjaz Breskvar (phoenix@bsemi.com)
 	lots of bugfixes and enhancments.
 	added opencores framebuffer driver.
 
-09. 10. 2010    Jonas Bonn (jonas@southpole.se)
+09-10-2010    Jonas Bonn (jonas@southpole.se)
 	major rewrite to bring up to par with upstream Linux 2.6.36
diff --git a/Documentation/openrisc/TODO b/Documentation/openrisc/todo.rst
similarity index 78%
rename from Documentation/openrisc/TODO
rename to Documentation/openrisc/todo.rst
index c43d4e1d14eb..420b18b87eda 100644
--- a/Documentation/openrisc/TODO
+++ b/Documentation/openrisc/todo.rst
@@ -1,12 +1,15 @@
+====
+TODO
+====
+
 The OpenRISC Linux port is fully functional and has been tracking upstream
 since 2.6.35.  There are, however, remaining items to be completed within
 the coming months.  Here's a list of known-to-be-less-than-stellar items
 that are due for investigation shortly, i.e. our TODO list:
 
--- Implement the rest of the DMA API... dma_map_sg, etc.
+-  Implement the rest of the DMA API... dma_map_sg, etc.
 
--- Finish the renaming cleanup... there are references to or32 in the code
+-  Finish the renaming cleanup... there are references to or32 in the code
    which was an older name for the architecture.  The name we've settled on is
    or1k and this change is slowly trickling through the stack.  For the time
    being, or32 is equivalent to or1k.
-
-- 
2.21.0


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

* [OpenRISC] [PATCH v2 14/26] docs: openrisc: convert to ReST and add to documentation body
@ 2019-07-26 12:51   ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  To: openrisc

Manually convert the two openRisc documents to ReST, adding them
to the Linux documentation body.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Stafford Horne <shorne@gmail.com>
---
 Documentation/index.rst                       |  1 +
 Documentation/openrisc/index.rst              | 18 +++++++++++++
 .../openrisc/{README => openrisc_port.rst}    | 25 +++++++++++++------
 Documentation/openrisc/{TODO => todo.rst}     |  9 ++++---
 4 files changed, 43 insertions(+), 10 deletions(-)
 create mode 100644 Documentation/openrisc/index.rst
 rename Documentation/openrisc/{README => openrisc_port.rst} (80%)
 rename Documentation/openrisc/{TODO => todo.rst} (78%)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 25e080664050..6402f62ac90f 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -148,6 +148,7 @@ implementation.
    ia64/index
    m68k/index
    powerpc/index
+   openrisc/index
    parisc/index
    riscv/index
    s390/index
diff --git a/Documentation/openrisc/index.rst b/Documentation/openrisc/index.rst
new file mode 100644
index 000000000000..748b3eea1707
--- /dev/null
+++ b/Documentation/openrisc/index.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
+OpenRISC Architecture
+=====================
+
+.. toctree::
+   :maxdepth: 2
+
+   openrisc_port
+   todo
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/openrisc/README b/Documentation/openrisc/openrisc_port.rst
similarity index 80%
rename from Documentation/openrisc/README
rename to Documentation/openrisc/openrisc_port.rst
index 777a893d533d..a18747a8d191 100644
--- a/Documentation/openrisc/README
+++ b/Documentation/openrisc/openrisc_port.rst
@@ -1,3 +1,4 @@
+==============
 OpenRISC Linux
 ==============
 
@@ -6,8 +7,10 @@ target architecture, specifically, is the 32-bit OpenRISC 1000 family (or1k).
 
 For information about OpenRISC processors and ongoing development:
 
+	=======		=============================
 	website		http://openrisc.io
 	email		openrisc at lists.librecores.org
+	=======		=============================
 
 ---------------------------------------------------------------------
 
@@ -24,13 +27,15 @@ Toolchain binaries can be obtained from openrisc.io or our github releases page.
 Instructions for building the different toolchains can be found on openrisc.io
 or Stafford's toolchain build and release scripts.
 
+	==========	=================================================
 	binaries	https://github.com/openrisc/or1k-gcc/releases
 	toolchains	https://openrisc.io/software
 	building	https://github.com/stffrdhrn/or1k-toolchain-build
+	==========	=================================================
 
 2) Building
 
-Build the Linux kernel as usual
+Build the Linux kernel as usual::
 
 	make ARCH=openrisc defconfig
 	make ARCH=openrisc
@@ -43,6 +48,8 @@ development board with the OpenRISC SoC.  During the build FPGA RTL is code
 downloaded from the FuseSoC IP cores repository and built using the FPGA vendor
 tools.  Binaries are loaded onto the board with openocd.
 
+::
+
 	git clone https://github.com/olofk/fusesoc
 	cd fusesoc
 	sudo pip install -e .
@@ -65,7 +72,9 @@ platform.  Please follow the OpenRISC instructions on the QEMU website to get
 Linux running on QEMU.  You can build QEMU yourself, but your Linux distribution
 likely provides binary packages to support OpenRISC.
 
+	=============	======================================================
 	qemu openrisc	https://wiki.qemu.org/Documentation/Platforms/OpenRISC
+	=============	======================================================
 
 ---------------------------------------------------------------------
 
@@ -75,36 +84,38 @@ Terminology
 In the code, the following particles are used on symbols to limit the scope
 to more or less specific processor implementations:
 
+========= =======================================
 openrisc: the OpenRISC class of processors
 or1k:     the OpenRISC 1000 family of processors
 or1200:   the OpenRISC 1200 processor
+========= =======================================
 
 ---------------------------------------------------------------------
 
 History
 ========
 
-18. 11. 2003	Matjaz Breskvar (phoenix at bsemi.com)
+18-11-2003	Matjaz Breskvar (phoenix at bsemi.com)
 	initial port of linux to OpenRISC/or32 architecture.
         all the core stuff is implemented and seams usable.
 
-08. 12. 2003	Matjaz Breskvar (phoenix at bsemi.com)
+08-12-2003	Matjaz Breskvar (phoenix at bsemi.com)
 	complete change of TLB miss handling.
 	rewrite of exceptions handling.
 	fully functional sash-3.6 in default initrd.
 	a much improved version with changes all around.
 
-10. 04. 2004	Matjaz Breskvar (phoenix at bsemi.com)
+10-04-2004	Matjaz Breskvar (phoenix at bsemi.com)
 	alot of bugfixes all over.
 	ethernet support, functional http and telnet servers.
 	running many standard linux apps.
 
-26. 06. 2004	Matjaz Breskvar (phoenix at bsemi.com)
+26-06-2004	Matjaz Breskvar (phoenix at bsemi.com)
 	port to 2.6.x
 
-30. 11. 2004	Matjaz Breskvar (phoenix at bsemi.com)
+30-11-2004	Matjaz Breskvar (phoenix at bsemi.com)
 	lots of bugfixes and enhancments.
 	added opencores framebuffer driver.
 
-09. 10. 2010    Jonas Bonn (jonas at southpole.se)
+09-10-2010    Jonas Bonn (jonas at southpole.se)
 	major rewrite to bring up to par with upstream Linux 2.6.36
diff --git a/Documentation/openrisc/TODO b/Documentation/openrisc/todo.rst
similarity index 78%
rename from Documentation/openrisc/TODO
rename to Documentation/openrisc/todo.rst
index c43d4e1d14eb..420b18b87eda 100644
--- a/Documentation/openrisc/TODO
+++ b/Documentation/openrisc/todo.rst
@@ -1,12 +1,15 @@
+====
+TODO
+====
+
 The OpenRISC Linux port is fully functional and has been tracking upstream
 since 2.6.35.  There are, however, remaining items to be completed within
 the coming months.  Here's a list of known-to-be-less-than-stellar items
 that are due for investigation shortly, i.e. our TODO list:
 
--- Implement the rest of the DMA API... dma_map_sg, etc.
+-  Implement the rest of the DMA API... dma_map_sg, etc.
 
--- Finish the renaming cleanup... there are references to or32 in the code
+-  Finish the renaming cleanup... there are references to or32 in the code
    which was an older name for the architecture.  The name we've settled on is
    or1k and this change is slowly trickling through the stack.  For the time
    being, or32 is equivalent to or1k.
-
-- 
2.21.0


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

* [PATCH v2 15/26] docs: isdn: convert to ReST and add to kAPI bookset
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (17 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Karsten Keil,
	Greg Kroah-Hartman, linux-doc, netdev, devel

The ISDN documentation is a mix of admin guide, uAPI and kAPI.

Ideally, it should be split. Yet, not sure if it would worth
the troble. Anyway, we have the same kind of mix on several
drivers specific documentation. So, just like the others, keep
the directory at the root Documentation/ tree, just adding a
pointer to it at the kAPI section, as the documentation was
written with the Kernel developers in mind.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/index.rst                       |   1 +
 .../isdn/{README.avmb1 => avmb1.rst}          | 231 ++++++++------
 Documentation/isdn/{CREDITS => credits.rst}   |   7 +-
 .../isdn/{README.gigaset => gigaset.rst}      | 290 +++++++++++-------
 .../isdn/{README.hysdn => hysdn.rst}          | 125 ++++----
 Documentation/isdn/index.rst                  |  24 ++
 .../{INTERFACE.CAPI => interface_capi.rst}    | 182 +++++++----
 .../isdn/{README.mISDN => m_isdn.rst}         |   5 +-
 drivers/staging/isdn/hysdn/Kconfig            |   2 +-
 9 files changed, 536 insertions(+), 331 deletions(-)
 rename Documentation/isdn/{README.avmb1 => avmb1.rst} (50%)
 rename Documentation/isdn/{CREDITS => credits.rst} (96%)
 rename Documentation/isdn/{README.gigaset => gigaset.rst} (74%)
 rename Documentation/isdn/{README.hysdn => hysdn.rst} (80%)
 create mode 100644 Documentation/isdn/index.rst
 rename Documentation/isdn/{INTERFACE.CAPI => interface_capi.rst} (75%)
 rename Documentation/isdn/{README.mISDN => m_isdn.rst} (89%)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 6402f62ac90f..de7be1c31450 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -106,6 +106,7 @@ needed).
    hid/index
    i2c/index
    iio/index
+   isdn/index
    infiniband/index
    leds/index
    media/index
diff --git a/Documentation/isdn/README.avmb1 b/Documentation/isdn/avmb1.rst
similarity index 50%
rename from Documentation/isdn/README.avmb1
rename to Documentation/isdn/avmb1.rst
index 9e075484ef1e..de3961e67553 100644
--- a/Documentation/isdn/README.avmb1
+++ b/Documentation/isdn/avmb1.rst
@@ -1,4 +1,6 @@
-Driver for active AVM Controller.
+================================
+Driver for active AVM Controller
+================================
 
 The driver provides a kernel capi2.0 Interface (kernelcapi) and
 on top of this a User-Level-CAPI2.0-interface (capi)
@@ -11,25 +13,28 @@ The command avmcapictrl is part of the isdn4k-utils.
 t4-files can be found at ftp://ftp.avm.de/cardware/b1/linux/firmware
 
 Currently supported cards:
-	B1 ISA (all versions)
-	B1 PCI
-	T1/T1B (HEMA card)
-	M1
-	M2
-	B1 PCMCIA
+
+	- B1 ISA (all versions)
+	- B1 PCI
+	- T1/T1B (HEMA card)
+	- M1
+	- M2
+	- B1 PCMCIA
 
 Installing
 ----------
 
 You need at least /dev/capi20 to load the firmware.
 
-mknod /dev/capi20 c 68 0
-mknod /dev/capi20.00 c 68 1
-mknod /dev/capi20.01 c 68 2
-.
-.
-.
-mknod /dev/capi20.19 c 68 20
+::
+
+    mknod /dev/capi20 c 68 0
+    mknod /dev/capi20.00 c 68 1
+    mknod /dev/capi20.01 c 68 2
+    .
+    .
+    .
+    mknod /dev/capi20.19 c 68 20
 
 Running
 -------
@@ -38,45 +43,58 @@ To use the card you need the t4-files to download the firmware.
 AVM GmbH provides several t4-files for the different D-channel
 protocols (b1.t4 for Euro-ISDN). Install these file in /lib/isdn.
 
-if you configure as modules load the modules this way:
-
-insmod /lib/modules/current/misc/capiutil.o
-insmod /lib/modules/current/misc/b1.o
-insmod /lib/modules/current/misc/kernelcapi.o
-insmod /lib/modules/current/misc/capidrv.o
-insmod /lib/modules/current/misc/capi.o
-
-if you have an B1-PCI card load the module b1pci.o
-insmod /lib/modules/current/misc/b1pci.o
-and load the firmware with
-avmcapictrl load /lib/isdn/b1.t4 1
+if you configure as modules load the modules this way::
+
+    insmod /lib/modules/current/misc/capiutil.o
+    insmod /lib/modules/current/misc/b1.o
+    insmod /lib/modules/current/misc/kernelcapi.o
+    insmod /lib/modules/current/misc/capidrv.o
+    insmod /lib/modules/current/misc/capi.o
+
+if you have an B1-PCI card load the module b1pci.o::
+
+    insmod /lib/modules/current/misc/b1pci.o
+
+and load the firmware with::
+
+    avmcapictrl load /lib/isdn/b1.t4 1
 
 if you have an B1-ISA card load the module b1isa.o
-and add the card by calling
-avmcapictrl add 0x150 15
-and load the firmware by calling
-avmcapictrl load /lib/isdn/b1.t4 1
+and add the card by calling::
+
+    avmcapictrl add 0x150 15
+
+and load the firmware by calling::
+
+    avmcapictrl load /lib/isdn/b1.t4 1
 
 if you have an T1-ISA card load the module t1isa.o
-and add the card by calling
-avmcapictrl add 0x450 15 T1 0
-and load the firmware by calling
-avmcapictrl load /lib/isdn/t1.t4 1
+and add the card by calling::
+
+    avmcapictrl add 0x450 15 T1 0
+
+and load the firmware by calling::
+
+    avmcapictrl load /lib/isdn/t1.t4 1
 
 if you have an PCMCIA card (B1/M1/M2) load the module b1pcmcia.o
 before you insert the card.
 
 Leased Lines with B1
 --------------------
+
 Init card and load firmware.
+
 For an D64S use "FV: 1" as phone number
+
 For an D64S2 use "FV: 1" and "FV: 2" for multilink
 or "FV: 1,2" to use CAPI channel bundling.
 
 /proc-Interface
 -----------------
 
-/proc/capi:
+/proc/capi::
+
   dr-xr-xr-x   2 root     root            0 Jul  1 14:03 .
   dr-xr-xr-x  82 root     root            0 Jun 30 19:08 ..
   -r--r--r--   1 root     root            0 Jul  1 14:03 applications
@@ -91,84 +109,124 @@ or "FV: 1,2" to use CAPI channel bundling.
 
 /proc/capi/applications:
    applid level3cnt datablkcnt datablklen ncci-cnt recvqueuelen
-	level3cnt: capi_register parameter
-	datablkcnt: capi_register parameter
-	ncci-cnt: current number of nccis (connections)
-	recvqueuelen: number of messages on receive queue
-   for example:
-1 -2 16 2048 1 0
-2 2 7 2048 1 0
+	level3cnt:
+	    capi_register parameter
+	datablkcnt:
+	    capi_register parameter
+	ncci-cnt:
+	    current number of nccis (connections)
+	recvqueuelen:
+	    number of messages on receive queue
+
+   for example::
+
+	1 -2 16 2048 1 0
+	2 2 7 2048 1 0
 
 /proc/capi/applstats:
    applid recvctlmsg nrecvdatamsg nsentctlmsg nsentdatamsg
-	recvctlmsg: capi messages received without DATA_B3_IND
-	recvdatamsg: capi DATA_B3_IND received
-	sentctlmsg: capi messages sent without DATA_B3_REQ
-	sentdatamsg: capi DATA_B3_REQ sent
-   for example:
-1 2057 1699 1721 1699
+	recvctlmsg:
+	    capi messages received without DATA_B3_IND
+	recvdatamsg:
+	    capi DATA_B3_IND received
+	sentctlmsg:
+	    capi messages sent without DATA_B3_REQ
+	sentdatamsg:
+	    capi DATA_B3_REQ sent
+
+   for example::
+
+	1 2057 1699 1721 1699
 
 /proc/capi/capi20: statistics of capi.o (/dev/capi20)
     minor nopen nrecvdropmsg nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
-	minor: minor device number of capi device
-	nopen: number of calls to devices open
-	nrecvdropmsg: capi messages dropped (messages in recvqueue in close)
-	nrecvctlmsg: capi messages received without DATA_B3_IND
-	nrecvdatamsg: capi DATA_B3_IND received
-	nsentctlmsg: capi messages sent without DATA_B3_REQ
-	nsentdatamsg: capi DATA_B3_REQ sent
+	minor:
+	    minor device number of capi device
+	nopen:
+	    number of calls to devices open
+	nrecvdropmsg:
+	    capi messages dropped (messages in recvqueue in close)
+	nrecvctlmsg:
+	    capi messages received without DATA_B3_IND
+	nrecvdatamsg:
+	    capi DATA_B3_IND received
+	nsentctlmsg:
+	    capi messages sent without DATA_B3_REQ
+	nsentdatamsg:
+	    capi DATA_B3_REQ sent
 
-   for example:
-1 2 18 0 16 2
+   for example::
+
+	1 2 18 0 16 2
 
 /proc/capi/capidrv: statistics of capidrv.o (capi messages)
     nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
-	nrecvctlmsg: capi messages received without DATA_B3_IND
-	nrecvdatamsg: capi DATA_B3_IND received
-	nsentctlmsg: capi messages sent without DATA_B3_REQ
-	nsentdatamsg: capi DATA_B3_REQ sent
+	nrecvctlmsg:
+	    capi messages received without DATA_B3_IND
+	nrecvdatamsg:
+	    capi DATA_B3_IND received
+	nsentctlmsg:
+	    capi messages sent without DATA_B3_REQ
+	nsentdatamsg:
+	    capi DATA_B3_REQ sent
+
    for example:
-2780 2226 2256 2226
+	2780 2226 2256 2226
 
 /proc/capi/controller:
    controller drivername state cardname   controllerinfo
-   for example:
-1 b1pci      running  b1pci-e000       B1 3.07-01 0xe000 19
-2 t1isa      running  t1isa-450        B1 3.07-01 0x450 11 0
-3 b1pcmcia   running  m2-150           B1 3.07-01 0x150 5
+
+   for example::
+
+	1 b1pci      running  b1pci-e000       B1 3.07-01 0xe000 19
+	2 t1isa      running  t1isa-450        B1 3.07-01 0x450 11 0
+	3 b1pcmcia   running  m2-150           B1 3.07-01 0x150 5
 
 /proc/capi/contrstats:
     controller nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
-	nrecvctlmsg: capi messages received without DATA_B3_IND
-	nrecvdatamsg: capi DATA_B3_IND received
-	nsentctlmsg: capi messages sent without DATA_B3_REQ
-	nsentdatamsg: capi DATA_B3_REQ sent
-   for example:
-1 2845 2272 2310 2274
-2 2 0 2 0
-3 2 0 2 0
+	nrecvctlmsg:
+	    capi messages received without DATA_B3_IND
+	nrecvdatamsg:
+	    capi DATA_B3_IND received
+	nsentctlmsg:
+	    capi messages sent without DATA_B3_REQ
+	nsentdatamsg:
+	    capi DATA_B3_REQ sent
+
+   for example::
+
+	1 2845 2272 2310 2274
+	2 2 0 2 0
+	3 2 0 2 0
 
 /proc/capi/driver:
    drivername ncontroller
-   for example:
-b1pci                            1
-t1isa                            1
-b1pcmcia                         1
-b1isa                            0
+
+   for example::
+
+	b1pci                            1
+	t1isa                            1
+	b1pcmcia                         1
+	b1isa                            0
 
 /proc/capi/ncci:
    apllid ncci winsize sendwindow
-   for example:
-1 0x10101 8 0
+
+   for example::
+
+	1 0x10101 8 0
 
 /proc/capi/users: kernelmodules that use the kernelcapi.
    name
-   for example:
-capidrv
-capi20
+
+   for example::
+
+	capidrv
+	capi20
 
 Questions
 ---------
+
 Check out the FAQ (ftp.isdn4linux.de) or subscribe to the
 linux-avmb1@calle.in-berlin.de mailing list by sending
 a mail to majordomo@calle.in-berlin.de with
@@ -178,9 +236,10 @@ in the body.
 German documentation and several scripts can be found at
 ftp://ftp.avm.de/cardware/b1/linux/
 
-Bugs 
+Bugs
 ----
-If you find any please let me know. 
+
+If you find any please let me know.
 
 Enjoy,
 
diff --git a/Documentation/isdn/CREDITS b/Documentation/isdn/credits.rst
similarity index 96%
rename from Documentation/isdn/CREDITS
rename to Documentation/isdn/credits.rst
index c1679e913fca..319323f2091f 100644
--- a/Documentation/isdn/CREDITS
+++ b/Documentation/isdn/credits.rst
@@ -1,3 +1,7 @@
+=======
+Credits
+=======
+
 
 I want to thank all who contributed to this project and especially to:
 (in alphabetical order)
@@ -19,7 +23,7 @@ Matthias Hessler (hessler@isdn4linux.de)
   For creating and maintaining the FAQ.
 
 Bernhard Hailer (Bernhard.Hailer@lrz.uni-muenchen.de)
-  For creating the FAQ, and the leafsite HOWTO. 
+  For creating the FAQ, and the leafsite HOWTO.
 
 Michael 'Ghandi' Herold (michael@abadonna.franken.de)
   For contribution of the vbox answering machine.
@@ -67,4 +71,3 @@ Gerhard 'Fido' Schneider (fido@wuff.mayn.de)
 Thomas Uhl (uhl@think.de)
   For distributing the cards.
   For pushing me to work ;-)
-
diff --git a/Documentation/isdn/README.gigaset b/Documentation/isdn/gigaset.rst
similarity index 74%
rename from Documentation/isdn/README.gigaset
rename to Documentation/isdn/gigaset.rst
index f6184b637182..98b4ec521c51 100644
--- a/Documentation/isdn/README.gigaset
+++ b/Documentation/isdn/gigaset.rst
@@ -1,33 +1,36 @@
+==========================
 GigaSet 307x Device Driver
 ==========================
 
 1.   Requirements
-     ------------
+=================
+
 1.1. Hardware
-     --------
+-------------
+
      This driver supports the connection of the Gigaset 307x/417x family of
      ISDN DECT bases via Gigaset M101 Data, Gigaset M105 Data or direct USB
      connection. The following devices are reported to be compatible:
 
      Bases:
-        Siemens Gigaset 3070/3075 isdn
-        Siemens Gigaset 4170/4175 isdn
-        Siemens Gigaset SX205/255
-        Siemens Gigaset SX353
-        T-Com Sinus 45 [AB] isdn
-        T-Com Sinus 721X[A] [SE]
-        Vox Chicago 390 ISDN (KPN Telecom)
+       - Siemens Gigaset 3070/3075 isdn
+       - Siemens Gigaset 4170/4175 isdn
+       - Siemens Gigaset SX205/255
+       - Siemens Gigaset SX353
+       - T-Com Sinus 45 [AB] isdn
+       - T-Com Sinus 721X[A] [SE]
+       - Vox Chicago 390 ISDN (KPN Telecom)
 
      RS232 data boxes:
-        Siemens Gigaset M101 Data
-        T-Com Sinus 45 Data 1
+       - Siemens Gigaset M101 Data
+       - T-Com Sinus 45 Data 1
 
      USB data boxes:
-        Siemens Gigaset M105 Data
-        Siemens Gigaset USB Adapter DECT
-        T-Com Sinus 45 Data 2
-        T-Com Sinus 721 data
-        Chicago 390 USB (KPN)
+       - Siemens Gigaset M105 Data
+       - Siemens Gigaset USB Adapter DECT
+       - T-Com Sinus 45 Data 2
+       - T-Com Sinus 721 data
+       - Chicago 390 USB (KPN)
 
      See also http://www.erbze.info/sinus_gigaset.htm
        (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) and
@@ -37,17 +40,21 @@ GigaSet 307x Device Driver
      with SX 100 and CX 100 ISDN bases (only in unimodem mode, see section 2.5.)
      If you have another device that works with our driver, please let us know.
 
-     Chances of getting an USB device to work are good if the output of
-        lsusb
-     at the command line contains one of the following:
-        ID 0681:0001
-        ID 0681:0002
-        ID 0681:0009
-        ID 0681:0021
-        ID 0681:0022
+     Chances of getting an USB device to work are good if the output of::
+
+	lsusb
+
+     at the command line contains one of the following::
+
+	ID 0681:0001
+	ID 0681:0002
+	ID 0681:0009
+	ID 0681:0021
+	ID 0681:0022
 
 1.2. Software
-     --------
+-------------
+
      The driver works with the Kernel CAPI subsystem and can be used with any
      software which is able to use CAPI 2.0 for ISDN connections (voice or data).
 
@@ -58,9 +65,11 @@ GigaSet 307x Device Driver
 
 
 2.   How to use the driver
-     ---------------------
+==========================
+
 2.1. Modules
-     -------
+------------
+
      For the devices to work, the proper kernel modules have to be loaded.
      This normally happens automatically when the system detects the USB
      device (base, M105) or when the line discipline is attached (M101). It
@@ -71,13 +80,17 @@ GigaSet 307x Device Driver
      which uses the regular serial port driver to access the device, and must
      therefore be attached to the serial device to which the M101 is connected.
      The ldattach(8) command (included in util-linux-ng release 2.14 or later)
-     can be used for that purpose, for example:
+     can be used for that purpose, for example::
+
 	ldattach GIGASET_M101 /dev/ttyS1
+
      This will open the device file, attach the line discipline to it, and
      then sleep in the background, keeping the device open so that the line
      discipline remains active. To deactivate it, kill the daemon, for example
-     with
+     with::
+
 	killall ldattach
+
      before disconnecting the device. To have this happen automatically at
      system startup/shutdown on an LSB compatible system, create and activate
      an appropriate LSB startup script /etc/init.d/gigaset. (The init name
@@ -86,9 +99,10 @@ GigaSet 307x Device Driver
 
      The modules accept the following parameters:
 
-	Module	 	Parameter  Meaning
+	=============== ========== ==========================================
+	Module		Parameter  Meaning
 
-	gigaset	 	debug	   debug level (see section 3.2.)
+	gigaset		debug	   debug level (see section 3.2.)
 
 			startmode  initial operation mode (see section 2.5.):
 	bas_gigaset )		   1=CAPI (default), 0=Unimodem
@@ -96,11 +110,14 @@ GigaSet 307x Device Driver
 	usb_gigaset )	cidmode    initial Call-ID mode setting (see section
 				   2.5.): 1=on (default), 0=off
 
+	=============== ========== ==========================================
+
      Depending on your distribution you may want to create a separate module
      configuration file like /etc/modprobe.d/gigaset.conf for these.
 
 2.2. Device nodes for user space programs
-     ------------------------------------
+-----------------------------------------
+
      The device can be accessed from user space (eg. by the user space tools
      mentioned in 1.2.) through the device nodes:
 
@@ -113,46 +130,56 @@ GigaSet 307x Device Driver
 
      You can also set a "default device" for the user space tools to use when
      no device node is given as parameter, by creating a symlink /dev/ttyG to
-     one of them, eg.:
+     one of them, eg.::
 
 	ln -s /dev/ttyGB0 /dev/ttyG
 
      The devices accept the following device specific ioctl calls
      (defined in gigaset_dev.h):
 
-     ioctl(int fd, GIGASET_REDIR, int *cmd);
+     ``ioctl(int fd, GIGASET_REDIR, int *cmd);``
+
      If cmd==1, the device is set to be controlled exclusively through the
      character device node; access from the ISDN subsystem is blocked.
+
      If cmd==0, the device is set to be used from the ISDN subsystem and does
      not communicate through the character device node.
 
-     ioctl(int fd, GIGASET_CONFIG, int *cmd);
+     ``ioctl(int fd, GIGASET_CONFIG, int *cmd);``
+
      (ser_gigaset and usb_gigaset only)
+
      If cmd==1, the device is set to adapter configuration mode where commands
      are interpreted by the M10x DECT adapter itself instead of being
      forwarded to the base station. In this mode, the device accepts the
      commands described in Siemens document "AT-Kommando Alignment M10x Data"
      for setting the operation mode, associating with a base station and
      querying parameters like field strengh and signal quality.
+
      Note that there is no ioctl command for leaving adapter configuration
      mode and returning to regular operation. In order to leave adapter
      configuration mode, write the command ATO to the device.
 
-     ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);
+     ``ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);``
+
      (usb_gigaset only)
+
      Set the break characters on an M105's internal serial adapter to the six
      bytes stored in brkchars[]. Unused bytes should be set to zero.
 
      ioctl(int fd, GIGASET_VERSION, unsigned version[4]);
      Retrieve version information from the driver. version[0] must be set to
      one of:
+
      - GIGVER_DRIVER: retrieve driver version
      - GIGVER_COMPAT: retrieve interface compatibility version
      - GIGVER_FWBASE: retrieve the firmware version of the base
+
      Upon return, version[] is filled with the requested version information.
 
 2.3. CAPI
-     ----
+---------
+
      The devices will show up as CAPI controllers as soon as the
      corresponding driver module is loaded, and can then be used with
      CAPI 2.0 kernel and user space applications. For user space access,
@@ -165,21 +192,22 @@ GigaSet 307x Device Driver
      driver.
 
 2.5. Unimodem mode
-     -------------
+------------------
+
      In this mode the device works like a modem connected to a serial port
-     (the /dev/ttyGU0, ... mentioned above) which understands the commands
+     (the /dev/ttyGU0, ... mentioned above) which understands the commands::
 
-         ATZ                 init, reset
-             => OK or ERROR
-         ATD
-         ATDT                dial
-             => OK, CONNECT,
-                BUSY,
-                NO DIAL TONE,
-                NO CARRIER,
-                NO ANSWER
-         <pause>+++<pause>   change to command mode when connected
-         ATH                 hangup
+	 ATZ                 init, reset
+	     => OK or ERROR
+	 ATD
+	 ATDT                dial
+	     => OK, CONNECT,
+		BUSY,
+		NO DIAL TONE,
+		NO CARRIER,
+		NO ANSWER
+	 <pause>+++<pause>   change to command mode when connected
+	 ATH                 hangup
 
      You can use some configuration tool of your distribution to configure this
      "modem" or configure pppd/wvdial manually. There are some example ppp
@@ -189,40 +217,52 @@ GigaSet 307x Device Driver
      control lines. This means you must use "Stupid Mode" if you are using
      wvdial or you should use the nocrtscts option of pppd.
      You must also assure that the ppp_async module is loaded with the parameter
-     flag_time=0. You can do this e.g. by adding a line like
+     flag_time=0. You can do this e.g. by adding a line like::
 
-        options ppp_async flag_time=0
+	options ppp_async flag_time=0
 
-     to an appropriate module configuration file, like
-     /etc/modprobe.d/gigaset.conf.
+     to an appropriate module configuration file, like::
+
+	/etc/modprobe.d/gigaset.conf.
 
      Unimodem mode is needed for making some devices [e.g. SX100] work which
      do not support the regular Gigaset command set. If debug output (see
-     section 3.2.) shows something like this when dialing:
-         CMD Received: ERROR
-         Available Params: 0
-         Connection State: 0, Response: -1
-         gigaset_process_response: resp_code -1 in ConState 0 !
-         Timeout occurred
+     section 3.2.) shows something like this when dialing::
+
+	 CMD Received: ERROR
+	 Available Params: 0
+	 Connection State: 0, Response: -1
+	 gigaset_process_response: resp_code -1 in ConState 0 !
+	 Timeout occurred
+
      then switching to unimodem mode may help.
 
      If you have installed the command line tool gigacontr, you can enter
-     unimodem mode using
-         gigacontr --mode unimodem
-     You can switch back using
-         gigacontr --mode isdn
+     unimodem mode using::
+
+	 gigacontr --mode unimodem
+
+     You can switch back using::
+
+	 gigacontr --mode isdn
 
      You can also put the driver directly into Unimodem mode when it's loaded,
      by passing the module parameter startmode=0 to the hardware specific
-     module, e.g.
+     module, e.g.::
+
 	modprobe usb_gigaset startmode=0
-     or by adding a line like
+
+     or by adding a line like::
+
 	options usb_gigaset startmode=0
-     to an appropriate module configuration file, like
-     /etc/modprobe.d/gigaset.conf
+
+     to an appropriate module configuration file, like::
+
+	/etc/modprobe.d/gigaset.conf
 
 2.6. Call-ID (CID) mode
-     ------------------
+-----------------------
+
      Call-IDs are numbers used to tag commands to, and responses from, the
      Gigaset base in order to support the simultaneous handling of multiple
      ISDN calls. Their use can be enabled ("CID mode") or disabled ("Unimodem
@@ -238,6 +278,7 @@ GigaSet 307x Device Driver
      During active operation, the driver switches to the necessary mode
      automatically. However, for the reasons above, the mode chosen when
      the device is not in use (idle) can be selected by the user.
+
      - If you want to receive incoming calls, you can use the default
        settings (CID mode).
      - If you have several DECT data devices (M10x) which you want to use
@@ -247,25 +288,27 @@ GigaSet 307x Device Driver
      If you want both of these at once, you are out of luck.
 
      You can also use the tty class parameter "cidmode" of the device to
-     change its CID mode while the driver is loaded, eg.
-        echo 0 > /sys/class/tty/ttyGU0/cidmode
+     change its CID mode while the driver is loaded, eg.::
+
+	echo 0 > /sys/class/tty/ttyGU0/cidmode
 
 2.7. Dialing Numbers
-     ---------------
-     The called party number provided by an application for dialing out must
+--------------------
+provided by an application for dialing out must
      be a public network number according to the local dialing plan, without
      any dial prefix for getting an outside line.
 
      Internal calls can be made by providing an internal extension number
-     prefixed with "**" (two asterisks) as the called party number. So to dial
-     eg. the first registered DECT handset, give "**11" as the called party
-     number. Dialing "***" (three asterisks) calls all extensions
+     prefixed with ``**`` (two asterisks) as the called party number. So to dial
+     eg. the first registered DECT handset, give ``**11`` as the called party
+     number. Dialing ``***`` (three asterisks) calls all extensions
      simultaneously (global call).
 
      Unimodem mode does not support internal calls.
 
 2.8. Unregistered Wireless Devices (M101/M105)
-     -----------------------------------------
+----------------------------------------------
+
      The main purpose of the ser_gigaset and usb_gigaset drivers is to allow
      the M101 and M105 wireless devices to be used as ISDN devices for ISDN
      connections through a Gigaset base. Therefore they assume that the device
@@ -279,73 +322,91 @@ GigaSet 307x Device Driver
      modes. See the gigacontr(8) manpage for details.
 
 3.   Troubleshooting
-     ---------------
+====================
+
 3.1. Solutions to frequently reported problems
-     -----------------------------------------
+----------------------------------------------
+
      Problem:
-        You have a slow provider and isdn4linux gives up dialing too early.
+	You have a slow provider and isdn4linux gives up dialing too early.
      Solution:
-        Load the isdn module using the dialtimeout option. You can do this e.g.
-        by adding a line like
+	Load the isdn module using the dialtimeout option. You can do this e.g.
+	by adding a line like::
 
-           options isdn dialtimeout=15
+	   options isdn dialtimeout=15
 
-        to /etc/modprobe.d/gigaset.conf or a similar file.
+	to /etc/modprobe.d/gigaset.conf or a similar file.
 
      Problem:
-        The isdnlog program emits error messages or just doesn't work.
+	The isdnlog program emits error messages or just doesn't work.
      Solution:
-        Isdnlog supports only the HiSax driver. Do not attempt to use it with
+	Isdnlog supports only the HiSax driver. Do not attempt to use it with
 	other drivers such as Gigaset.
 
      Problem:
-        You have two or more DECT data adapters (M101/M105) and only the
-        first one you turn on works.
+	You have two or more DECT data adapters (M101/M105) and only the
+	first one you turn on works.
      Solution:
-        Select Unimodem mode for all DECT data adapters. (see section 2.5.)
+	Select Unimodem mode for all DECT data adapters. (see section 2.5.)
 
      Problem:
-	Messages like this:
+	Messages like this::
+
 	    usb_gigaset 3-2:1.0: Could not initialize the device.
+
 	appear in your syslog.
      Solution:
 	Check whether your M10x wireless device is correctly registered to the
 	Gigaset base. (see section 2.7.)
 
 3.2. Telling the driver to provide more information
-     ----------------------------------------------
+---------------------------------------------------
      Building the driver with the "Gigaset debugging" kernel configuration
      option (CONFIG_GIGASET_DEBUG) gives it the ability to produce additional
      information useful for debugging.
 
      You can control the amount of debugging information the driver produces by
-     writing an appropriate value to /sys/module/gigaset/parameters/debug, e.g.
-        echo 0 > /sys/module/gigaset/parameters/debug
+     writing an appropriate value to /sys/module/gigaset/parameters/debug,
+     e.g.::
+
+	echo 0 > /sys/module/gigaset/parameters/debug
+
      switches off debugging output completely,
-        echo 0x302020 > /sys/module/gigaset/parameters/debug
+
+     ::
+
+	echo 0x302020 > /sys/module/gigaset/parameters/debug
+
      enables a reasonable set of debugging output messages. These values are
      bit patterns where every bit controls a certain type of debugging output.
      See the constants DEBUG_* in the source file gigaset.h for details.
 
      The initial value can be set using the debug parameter when loading the
-     module "gigaset", e.g. by adding a line
-        options gigaset debug=0
+     module "gigaset", e.g. by adding a line::
+
+	options gigaset debug=0
+
      to your module configuration file, eg. /etc/modprobe.d/gigaset.conf
 
      Generated debugging information can be found
-     - as output of the command
-         dmesg
+     - as output of the command::
+
+	 dmesg
+
      - in system log files written by your syslog daemon, usually
        in /var/log/, e.g. /var/log/messages.
 
 3.3. Reporting problems and bugs
-     ---------------------------
+--------------------------------
      If you can't solve problems with the driver on your own, feel free to
      use one of the forums, bug trackers, or mailing lists on
-         https://sourceforge.net/projects/gigaset307x
+
+	 https://sourceforge.net/projects/gigaset307x
+
      or write an electronic mail to the maintainers.
 
      Try to provide as much information as possible, such as
+
      - distribution
      - kernel version (uname -r)
      - gcc version (gcc --version)
@@ -362,7 +423,7 @@ GigaSet 307x Device Driver
      appropriate forums and newsgroups.
 
 3.4. Reporting problem solutions
-     ---------------------------
+--------------------------------
      If you solved a problem with our drivers, wrote startup scripts for your
      distribution, ... feel free to contact us (using one of the places
      mentioned in 3.3.). We'd like to add scripts, hints, documentation
@@ -370,34 +431,35 @@ GigaSet 307x Device Driver
 
 
 4.   Links, other software
-     ---------------------
+==========================
+
      - Sourceforge project developing this driver and associated tools
-         https://sourceforge.net/projects/gigaset307x
+	 https://sourceforge.net/projects/gigaset307x
      - Yahoo! Group on the Siemens Gigaset family of devices
-         https://de.groups.yahoo.com/group/Siemens-Gigaset
+	 https://de.groups.yahoo.com/group/Siemens-Gigaset
      - Siemens Gigaset/T-Sinus compatibility table
-         http://www.erbze.info/sinus_gigaset.htm
+	 http://www.erbze.info/sinus_gigaset.htm
 	    (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm )
 
 
 5.   Credits
-     -------
+============
+
      Thanks to
 
      Karsten Keil
-        for his help with isdn4linux
+	for his help with isdn4linux
      Deti Fliegl
-        for his base driver code
+	for his base driver code
      Dennis Dietrich
-        for his kernel 2.6 patches
+	for his kernel 2.6 patches
      Andreas Rummel
-        for his work and logs to get unimodem mode working
+	for his work and logs to get unimodem mode working
      Andreas Degert
-        for his logs and patches to get cx 100 working
+	for his logs and patches to get cx 100 working
      Dietrich Feist
-        for his generous donation of one M105 and two M101 cordless adapters
+	for his generous donation of one M105 and two M101 cordless adapters
      Christoph Schweers
-        for his generous donation of a M34 device
+	for his generous donation of a M34 device
 
      and all the other people who sent logs and other information.
-
diff --git a/Documentation/isdn/README.hysdn b/Documentation/isdn/hysdn.rst
similarity index 80%
rename from Documentation/isdn/README.hysdn
rename to Documentation/isdn/hysdn.rst
index eeca11f00ccd..0a168d1cbffc 100644
--- a/Documentation/isdn/README.hysdn
+++ b/Documentation/isdn/hysdn.rst
@@ -1,4 +1,7 @@
-$Id: README.hysdn,v 1.3.6.1 2001/02/10 14:41:19 kai Exp $
+============
+Hysdn Driver
+============
+
 The hysdn driver has been written by
 Werner Cornelius (werner@isdn4linux.de or werner@titro.de)
 for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver
@@ -22,28 +25,28 @@ for Hypercope GmbH Aachen, Germany.
     along with this program; if not, write to the Free Software
     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 
-Table of contents
-=================
+.. Table of contents
 
-1. About the driver
+    1. About the driver
 
-2. Loading/Unloading the driver
+    2. Loading/Unloading the driver
 
-3. Entries in the /proc filesystem
+    3. Entries in the /proc filesystem
 
-4. The /proc/net/hysdn/cardconfX file
+    4. The /proc/net/hysdn/cardconfX file
 
-5. The /proc/net/hysdn/cardlogX file
+    5. The /proc/net/hysdn/cardlogX file
 
-6. Where to get additional info and help
+    6. Where to get additional info and help
 
 
 1. About the driver
+===================
 
-   The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active 
+   The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active
    PCI isdn cards Champ, Ergo and Metro. To enable support for this cards
    enable ISDN support in the kernel config and support for HYSDN cards in
-   the active cards submenu. The driver may only be compiled and used if 
+   the active cards submenu. The driver may only be compiled and used if
    support for loadable modules and the process filesystem have been enabled.
 
    These cards provide two different interfaces to the kernel. Without the
@@ -52,22 +55,23 @@ Table of contents
    handlers for various protocols like ppp and others as well as config info
    and firmware may be fetched from Hypercopes WWW-Site www.hypercope.de.
 
-   With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0 
-   compliant devices with either CAPI 2.0 applications 
+   With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0
+   compliant devices with either CAPI 2.0 applications
    (check isdn4k-utils) or -using the capidrv module- as a regular
-   isdn4linux device. This is done via the same mechanism as with the 
+   isdn4linux device. This is done via the same mechanism as with the
    active AVM cards and in fact uses the same module.
-   
+
 
 2. Loading/Unloading the driver
+===============================
 
    The module has no command line parameters and auto detects up to 10 cards
    in the id-range 0-9.
    If a loaded driver shall be unloaded all open files in the /proc/net/hysdn
-   subdir need to be closed and all ethernet interfaces allocated by this 
+   subdir need to be closed and all ethernet interfaces allocated by this
    driver must be shut down. Otherwise the module counter will avoid a module
    unload.
-   
+
    If you are using the CAPI 2.0-interface, make sure to load/modprobe the
    kernelcapi-module first.
 
@@ -76,52 +80,57 @@ Table of contents
    any avm-specific modules).
 
 3. Entries in the /proc filesystem
+==================================
 
-   When the module has been loaded it adds the directory hysdn in the 
-   /proc/net tree. This directory contains exactly 2 file entries for each 
+   When the module has been loaded it adds the directory hysdn in the
+   /proc/net tree. This directory contains exactly 2 file entries for each
    card. One is called cardconfX and the other cardlogX, where X is the
-   card id number from 0 to 9. 
+   card id number from 0 to 9.
    The cards are numbered in the order found in the PCI config data.
 
 4. The /proc/net/hysdn/cardconfX file
+=====================================
 
-   This file may be read to get by everyone to get info about the cards type, 
+   This file may be read to get by everyone to get info about the cards type,
    actual state, available features and used resources.
    The first 3 entries (id, bus and slot) are PCI info fields, the following
    type field gives the information about the cards type:
 
-   4 -> Ergo card (server card with 2 b-chans)
-   5 -> Metro card (server card with 4 or 8 b-chans)
-   6 -> Champ card (client card with 2 b-chans)   
+   - 4 -> Ergo card (server card with 2 b-chans)
+   - 5 -> Metro card (server card with 4 or 8 b-chans)
+   - 6 -> Champ card (client card with 2 b-chans)
 
    The following 3 fields show the hardware assignments for irq, iobase and the
    dual ported memory (dp-mem).
+
    The fields b-chans and fax-chans announce the available card resources of
    this types for the user.
+
    The state variable indicates the actual drivers state for this card with the
    following assignments.
 
-   0 -> card has not been booted since driver load
-   1 -> card booting is actually in progess
-   2 -> card is in an error state due to a previous boot failure
-   3 -> card is booted and active
+   - 0 -> card has not been booted since driver load
+   - 1 -> card booting is actually in progess
+   - 2 -> card is in an error state due to a previous boot failure
+   - 3 -> card is booted and active
 
    And the last field (device) shows the name of the ethernet device assigned
    to this card. Up to the first successful boot this field only shows a -
    to tell that no net device has been allocated up to now. Once a net device
    has been allocated it remains assigned to this card, even if a card is
-   rebooted and an boot error occurs. 
+   rebooted and an boot error occurs.
 
-   Writing to the cardconfX file boots the card or transfers config lines to 
-   the cards firmware. The type of data is automatically detected when the 
+   Writing to the cardconfX file boots the card or transfers config lines to
+   the cards firmware. The type of data is automatically detected when the
    first data is written. Only root has write access to this file.
    The firmware boot files are normally called hyclient.pof for client cards
    and hyserver.pof for server cards.
    After successfully writing the boot file, complete config files or single
    config lines may be copied to this file.
-   If an error occurs the return value given to the writing process has the 
+   If an error occurs the return value given to the writing process has the
    following additional codes (decimal):
 
+   ==== ============================================
    1000 Another process is currently bootng the card
    1001 Invalid firmware header
    1002 Boards dual-port RAM test failed
@@ -131,34 +140,39 @@ Table of contents
    1006 Second boot stage failure
    1007 Timeout waiting for card ready during boot
    1008 Operation only allowed in booted state
-   1009 Config line too long 
-   1010 Invalid channel number 
+   1009 Config line too long
+   1010 Invalid channel number
    1011 Timeout sending config data
+   ==== ============================================
 
-   Additional info about error reasons may be fetched from the log output. 
+   Additional info about error reasons may be fetched from the log output.
 
 5. The /proc/net/hysdn/cardlogX file
-   	  
-   The cardlogX file entry may be opened multiple for reading by everyone to 
+====================================
+
+   The cardlogX file entry may be opened multiple for reading by everyone to
    get the cards and drivers log data. Card messages always start with the
-   keyword LOG. All other lines are output from the driver. 
-   The driver log data may be redirected to the syslog by selecting the 
+   keyword LOG. All other lines are output from the driver.
+   The driver log data may be redirected to the syslog by selecting the
    appropriate bitmask. The cards log messages will always be send to this
    interface but never to the syslog.
 
    A root user may write a decimal or hex (with 0x) value t this file to select
-   desired output options. As mentioned above the cards log dat is always 
+   desired output options. As mentioned above the cards log dat is always
    written to the cardlog file independent of the following options only used
    to check and debug the driver itself:
 
-   For example: 
-   echo "0x34560078" > /proc/net/hysdn/cardlog0
+   For example::
+
+	echo "0x34560078" > /proc/net/hysdn/cardlog0
+
    to output the hex log mask 34560078 for card 0.
- 
-   The written value is regarded as an unsigned 32-Bit value, bit ored for 
+
+   The written value is regarded as an unsigned 32-Bit value, bit ored for
    desired output. The following bits are already assigned:
 
-   0x80000000   All driver log data is alternatively via syslog 
+   ==========   ============================================================
+   0x80000000   All driver log data is alternatively via syslog
    0x00000001   Log memory allocation errors
    0x00000010   Firmware load start and close are logged
    0x00000020   Log firmware record parser
@@ -171,25 +185,12 @@ Table of contents
    0x00100000   Log all open and close actions to /proc/net/hysdn/card files
    0x00200000   Log all actions from /proc file entries
    0x00010000   Log network interface init and deinit
-   
+   ==========   ============================================================
+
 6. Where to get additional info and help
+========================================
 
-   If you have any problems concerning the driver or configuration contact 
+   If you have any problems concerning the driver or configuration contact
    the Hypercope support team (support@hypercope.de) and or the authors
    Werner Cornelius (werner@isdn4linux or cornelius@titro.de) or
    Ulrich Albrecht (ualbrecht@hypercope.de).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/Documentation/isdn/index.rst b/Documentation/isdn/index.rst
new file mode 100644
index 000000000000..407e74b78372
--- /dev/null
+++ b/Documentation/isdn/index.rst
@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+ISDN
+====
+
+.. toctree::
+   :maxdepth: 2
+
+   interface_capi
+
+   avmb1
+   gigaset
+   hysdn
+   m_isdn
+
+   credits
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/interface_capi.rst
similarity index 75%
rename from Documentation/isdn/INTERFACE.CAPI
rename to Documentation/isdn/interface_capi.rst
index 021aa9cf139d..01a4b5ade9a4 100644
--- a/Documentation/isdn/INTERFACE.CAPI
+++ b/Documentation/isdn/interface_capi.rst
@@ -1,7 +1,9 @@
+=========================================
 Kernel CAPI Interface to Hardware Drivers
------------------------------------------
+=========================================
 
 1. Overview
+===========
 
 From the CAPI 2.0 specification:
 COMMON-ISDN-API (CAPI) is an application programming interface standard used
@@ -22,6 +24,7 @@ This standard is freely available from https://www.capi.org.
 
 
 2. Driver and Device Registration
+=================================
 
 CAPI drivers optionally register themselves with Kernel CAPI by calling the
 Kernel CAPI function register_capi_driver() with a pointer to a struct
@@ -50,6 +53,7 @@ callback functions by Kernel CAPI.
 
 
 3. Application Registration and Communication
+=============================================
 
 Kernel CAPI forwards registration requests from applications (calls to CAPI
 operation CAPI_REGISTER) to an appropriate hardware driver by calling its
@@ -71,23 +75,26 @@ messages for that application may be passed to or from the device anymore.
 
 
 4. Data Structures
+==================
 
 4.1 struct capi_driver
+----------------------
 
 This structure describes a Kernel CAPI driver itself. It is used in the
 register_capi_driver() and unregister_capi_driver() functions, and contains
 the following non-private fields, all to be set by the driver before calling
 register_capi_driver():
 
-char name[32]
+``char name[32]``
 	the name of the driver, as a zero-terminated ASCII string
-char revision[32]
+``char revision[32]``
 	the revision number of the driver, as a zero-terminated ASCII string
-int (*add_card)(struct capi_driver *driver, capicardparams *data)
+``int (*add_card)(struct capi_driver *driver, capicardparams *data)``
 	a callback function pointer (may be NULL)
 
 
 4.2 struct capi_ctr
+-------------------
 
 This structure describes an ISDN device (controller) handled by a Kernel CAPI
 driver. After registration via the attach_capi_ctr() function it is passed to
@@ -96,88 +103,109 @@ identify the controller to operate on.
 
 It contains the following non-private fields:
 
-- to be set by the driver before calling attach_capi_ctr():
+to be set by the driver before calling attach_capi_ctr():
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-struct module *owner
+``struct module *owner``
 	pointer to the driver module owning the device
 
-void *driverdata
+``void *driverdata``
 	an opaque pointer to driver specific data, not touched by Kernel CAPI
 
-char name[32]
+``char name[32]``
 	the name of the controller, as a zero-terminated ASCII string
 
-char *driver_name
+``char *driver_name``
 	the name of the driver, as a zero-terminated ASCII string
 
-int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)
+``int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)``
 	(optional) pointer to a callback function for sending firmware and
 	configuration data to the device
+
 	The function may return before the operation has completed.
+
 	Completion must be signalled by a call to capi_ctr_ready().
+
 	Return value: 0 on success, error code on error
 	Called in process context.
 
-void (*reset_ctr)(struct capi_ctr *ctrlr)
+``void (*reset_ctr)(struct capi_ctr *ctrlr)``
 	(optional) pointer to a callback function for stopping the device,
 	releasing all registered applications
+
 	The function may return before the operation has completed.
+
 	Completion must be signalled by a call to capi_ctr_down().
+
 	Called in process context.
 
-void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
-			capi_register_params *rparam)
-void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
-	pointers to callback functions for registration and deregistration of
+``void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, capi_register_params *rparam)``
+	pointers to callback function for registration of
 	applications with the device
+
+	Calls to these functions are serialized by Kernel CAPI so that only
+	one call to any of them is active at any time.
+
+``void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)``
+	pointers to callback functions deregistration of
+	applications with the device
+
 	Calls to these functions are serialized by Kernel CAPI so that only
 	one call to any of them is active at any time.
 
-u16  (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)
+``u16  (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)``
 	pointer to a callback function for sending a CAPI message to the
 	device
+
 	Return value: CAPI error code
+
 	If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
 	of the skb and the caller may no longer access it. If it returns a
 	non-zero (error) value then ownership of the skb returns to the caller
 	who may reuse or free it.
+
 	The return value should only be used to signal problems with respect
 	to accepting or queueing the message. Errors occurring during the
 	actual processing of the message should be signaled with an
 	appropriate reply message.
+
 	May be called in process or interrupt context.
+
 	Calls to this function are not serialized by Kernel CAPI, ie. it must
 	be prepared to be re-entered.
 
-char *(*procinfo)(struct capi_ctr *ctrlr)
+``char *(*procinfo)(struct capi_ctr *ctrlr)``
 	pointer to a callback function returning the entry for the device in
 	the CAPI controller info table, /proc/capi/controller
 
-const struct file_operations *proc_fops
+``const struct file_operations *proc_fops``
 	pointers to callback functions for the device's proc file
 	system entry, /proc/capi/controllers/<n>; pointer to the device's
 	capi_ctr structure is available from struct proc_dir_entry::data
 	which is available from struct inode.
 
-Note: Callback functions except send_message() are never called in interrupt
-context.
+Note:
+  Callback functions except send_message() are never called in interrupt
+  context.
 
-- to be filled in before calling capi_ctr_ready():
+to be filled in before calling capi_ctr_ready():
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-u8 manu[CAPI_MANUFACTURER_LEN]
+``u8 manu[CAPI_MANUFACTURER_LEN]``
 	value to return for CAPI_GET_MANUFACTURER
 
-capi_version version
+``capi_version version``
 	value to return for CAPI_GET_VERSION
 
-capi_profile profile
+``capi_profile profile``
 	value to return for CAPI_GET_PROFILE
 
-u8 serial[CAPI_SERIAL_LEN]
+``u8 serial[CAPI_SERIAL_LEN]``
 	value to return for CAPI_GET_SERIAL
 
 
 4.3 SKBs
+--------
 
 CAPI messages are passed between Kernel CAPI and the driver via send_message()
 and capi_ctr_handle_message(), stored in the data portion of a socket buffer
@@ -192,6 +220,7 @@ instead of 30.
 
 
 4.4 The _cmsg Structure
+-----------------------
 
 (declared in <linux/isdn/capiutil.h>)
 
@@ -216,6 +245,7 @@ Members are named after the CAPI 2.0 standard names of the parameters they
 represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
 types are:
 
+=========== =================================================================
 u8          for CAPI parameters of type 'byte'
 
 u16         for CAPI parameters of type 'word'
@@ -235,6 +265,7 @@ _cmstruct   alternative representation for CAPI parameters of type 'struct'
 	    CAPI_COMPOSE: The parameter is present.
 	    Subparameter values are stored individually in the corresponding
 	    _cmsg structure members.
+=========== =================================================================
 
 Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
 messages between their transport encoding described in the CAPI 2.0 standard
@@ -244,51 +275,71 @@ sure it is big enough to accommodate the resulting CAPI message.
 
 
 5. Lower Layer Interface Functions
+==================================
 
 (declared in <linux/isdn/capilli.h>)
 
-void register_capi_driver(struct capi_driver *drvr)
-void unregister_capi_driver(struct capi_driver *drvr)
-	register/unregister a driver with Kernel CAPI
-
-int attach_capi_ctr(struct capi_ctr *ctrlr)
-int detach_capi_ctr(struct capi_ctr *ctrlr)
-	register/unregister a device (controller) with Kernel CAPI
-
-void capi_ctr_ready(struct capi_ctr *ctrlr)
-void capi_ctr_down(struct capi_ctr *ctrlr)
-	signal controller ready/not ready
-
-void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
-void capi_ctr_resume_output(struct capi_ctr *ctrlr)
-	signal suspend/resume
-
-void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
-				struct sk_buff *skb)
-	pass a received CAPI message to Kernel CAPI
-	for forwarding to the specified application
+::
+
+  void register_capi_driver(struct capi_driver *drvr)
+  void unregister_capi_driver(struct capi_driver *drvr)
+
+register/unregister a driver with Kernel CAPI
+
+::
+
+  int attach_capi_ctr(struct capi_ctr *ctrlr)
+  int detach_capi_ctr(struct capi_ctr *ctrlr)
+
+register/unregister a device (controller) with Kernel CAPI
+
+::
+
+  void capi_ctr_ready(struct capi_ctr *ctrlr)
+  void capi_ctr_down(struct capi_ctr *ctrlr)
+
+signal controller ready/not ready
+
+::
+
+  void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
+  void capi_ctr_resume_output(struct capi_ctr *ctrlr)
+
+signal suspend/resume
+
+::
+
+  void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
+			       struct sk_buff *skb)
+
+pass a received CAPI message to Kernel CAPI
+for forwarding to the specified application
 
 
 6. Helper Functions and Macros
+==============================
 
 Library functions (from <linux/isdn/capilli.h>):
 
-void capilib_new_ncci(struct list_head *head, u16 applid,
+::
+
+  void capilib_new_ncci(struct list_head *head, u16 applid,
 			u32 ncci, u32 winsize)
-void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
-void capilib_release_appl(struct list_head *head, u16 applid)
-void capilib_release(struct list_head *head)
-void capilib_data_b3_conf(struct list_head *head, u16 applid,
+  void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
+  void capilib_release_appl(struct list_head *head, u16 applid)
+  void capilib_release(struct list_head *head)
+  void capilib_data_b3_conf(struct list_head *head, u16 applid,
 			u32 ncci, u16 msgid)
-u16  capilib_data_b3_req(struct list_head *head, u16 applid,
+  u16  capilib_data_b3_req(struct list_head *head, u16 applid,
 			u32 ncci, u16 msgid)
 
 
 Macros to extract/set element values from/in a CAPI message header
 (from <linux/isdn/capiutil.h>):
 
+======================  =============================   ====================
 Get Macro		Set Macro			Element (Type)
-
+======================  =============================   ====================
 CAPIMSG_LEN(m)		CAPIMSG_SETLEN(m, len)		Total Length (u16)
 CAPIMSG_APPID(m)	CAPIMSG_SETAPPID(m, applid)	ApplID (u16)
 CAPIMSG_COMMAND(m)	CAPIMSG_SETCOMMAND(m,cmd)	Command (u8)
@@ -300,31 +351,31 @@ CAPIMSG_MSGID(m)	CAPIMSG_SETMSGID(m, msgid)	Message Number (u16)
 CAPIMSG_CONTROL(m)	CAPIMSG_SETCONTROL(m, contr)	Controller/PLCI/NCCI
 							(u32)
 CAPIMSG_DATALEN(m)	CAPIMSG_SETDATALEN(m, len)	Data Length (u16)
+======================  =============================   ====================
 
 
 Library functions for working with _cmsg structures
 (from <linux/isdn/capiutil.h>):
 
-unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)
-	Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the
-	result in *msg.
+``unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)``
+	Assembles a CAPI 2.0 message from the parameters in ``*cmsg``,
+	storing the result in ``*msg``.
 
-unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
-	Disassembles the CAPI 2.0 message in *msg, storing the parameters in
-	*cmsg.
+``unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)``
+	Disassembles the CAPI 2.0 message in ``*msg``, storing the parameters
+	in ``*cmsg``.
 
-unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand,
-			  u16 Messagenumber, u32 Controller)
-	Fills the header part and address field of the _cmsg structure *cmsg
+``unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, u16 Messagenumber, u32 Controller)``
+	Fills the header part and address field of the _cmsg structure ``*cmsg``
 	with the given values, zeroing the remainder of the structure so only
 	parameters with non-default values need to be changed before sending
 	the message.
 
-void capi_cmsg_answer(_cmsg *cmsg)
-	Sets the low bit of the Subcommand field in *cmsg, thereby converting
-	_REQ to _CONF and _IND to _RESP.
+``void capi_cmsg_answer(_cmsg *cmsg)``
+	Sets the low bit of the Subcommand field in ``*cmsg``, thereby
+	converting ``_REQ`` to ``_CONF`` and ``_IND`` to ``_RESP``.
 
-char *capi_cmd2str(u8 Command, u8 Subcommand)
+``char *capi_cmd2str(u8 Command, u8 Subcommand)``
 	Returns the CAPI 2.0 message name corresponding to the given command
 	and subcommand values, as a static ASCII string. The return value may
 	be NULL if the command/subcommand is not one of those defined in the
@@ -332,6 +383,7 @@ char *capi_cmd2str(u8 Command, u8 Subcommand)
 
 
 7. Debugging
+============
 
 The module kernelcapi has a module parameter showcapimsgs controlling some
 debugging output produced by the module. It can only be set when the module is
diff --git a/Documentation/isdn/README.mISDN b/Documentation/isdn/m_isdn.rst
similarity index 89%
rename from Documentation/isdn/README.mISDN
rename to Documentation/isdn/m_isdn.rst
index cd8bf920e77b..9957de349e69 100644
--- a/Documentation/isdn/README.mISDN
+++ b/Documentation/isdn/m_isdn.rst
@@ -1,6 +1,9 @@
+============
+mISDN Driver
+============
+
 mISDN is a new modular ISDN driver, in the long term it should replace
 the old I4L driver architecture for passiv ISDN cards.
 It was designed to allow a broad range of applications and interfaces
 but only have the basic function in kernel, the interface to the user
 space is based on sockets with a own address family AF_ISDN.
-
diff --git a/drivers/staging/isdn/hysdn/Kconfig b/drivers/staging/isdn/hysdn/Kconfig
index 1971ef850c9a..4c8a9283b9dd 100644
--- a/drivers/staging/isdn/hysdn/Kconfig
+++ b/drivers/staging/isdn/hysdn/Kconfig
@@ -5,7 +5,7 @@ config HYSDN
 	help
 	  Say Y here if you have one of Hypercope's active PCI ISDN cards
 	  Champ, Ergo and Metro. You will then get a module called hysdn.
-	  Please read the file <file:Documentation/isdn/README.hysdn> for more
+	  Please read the file <file:Documentation/isdn/hysdn.rst> for more
 	  information.
 
 config HYSDN_CAPI
-- 
2.21.0


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

* [PATCH v2 15/26] docs: isdn: convert to ReST and add to kAPI bookset
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (18 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: devel, Karsten Keil, linux-doc, Greg Kroah-Hartman,
	Jonathan Corbet, netdev, Mauro Carvalho Chehab

The ISDN documentation is a mix of admin guide, uAPI and kAPI.

Ideally, it should be split. Yet, not sure if it would worth
the troble. Anyway, we have the same kind of mix on several
drivers specific documentation. So, just like the others, keep
the directory at the root Documentation/ tree, just adding a
pointer to it at the kAPI section, as the documentation was
written with the Kernel developers in mind.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/index.rst                       |   1 +
 .../isdn/{README.avmb1 => avmb1.rst}          | 231 ++++++++------
 Documentation/isdn/{CREDITS => credits.rst}   |   7 +-
 .../isdn/{README.gigaset => gigaset.rst}      | 290 +++++++++++-------
 .../isdn/{README.hysdn => hysdn.rst}          | 125 ++++----
 Documentation/isdn/index.rst                  |  24 ++
 .../{INTERFACE.CAPI => interface_capi.rst}    | 182 +++++++----
 .../isdn/{README.mISDN => m_isdn.rst}         |   5 +-
 drivers/staging/isdn/hysdn/Kconfig            |   2 +-
 9 files changed, 536 insertions(+), 331 deletions(-)
 rename Documentation/isdn/{README.avmb1 => avmb1.rst} (50%)
 rename Documentation/isdn/{CREDITS => credits.rst} (96%)
 rename Documentation/isdn/{README.gigaset => gigaset.rst} (74%)
 rename Documentation/isdn/{README.hysdn => hysdn.rst} (80%)
 create mode 100644 Documentation/isdn/index.rst
 rename Documentation/isdn/{INTERFACE.CAPI => interface_capi.rst} (75%)
 rename Documentation/isdn/{README.mISDN => m_isdn.rst} (89%)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 6402f62ac90f..de7be1c31450 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -106,6 +106,7 @@ needed).
    hid/index
    i2c/index
    iio/index
+   isdn/index
    infiniband/index
    leds/index
    media/index
diff --git a/Documentation/isdn/README.avmb1 b/Documentation/isdn/avmb1.rst
similarity index 50%
rename from Documentation/isdn/README.avmb1
rename to Documentation/isdn/avmb1.rst
index 9e075484ef1e..de3961e67553 100644
--- a/Documentation/isdn/README.avmb1
+++ b/Documentation/isdn/avmb1.rst
@@ -1,4 +1,6 @@
-Driver for active AVM Controller.
+================================
+Driver for active AVM Controller
+================================
 
 The driver provides a kernel capi2.0 Interface (kernelcapi) and
 on top of this a User-Level-CAPI2.0-interface (capi)
@@ -11,25 +13,28 @@ The command avmcapictrl is part of the isdn4k-utils.
 t4-files can be found at ftp://ftp.avm.de/cardware/b1/linux/firmware
 
 Currently supported cards:
-	B1 ISA (all versions)
-	B1 PCI
-	T1/T1B (HEMA card)
-	M1
-	M2
-	B1 PCMCIA
+
+	- B1 ISA (all versions)
+	- B1 PCI
+	- T1/T1B (HEMA card)
+	- M1
+	- M2
+	- B1 PCMCIA
 
 Installing
 ----------
 
 You need at least /dev/capi20 to load the firmware.
 
-mknod /dev/capi20 c 68 0
-mknod /dev/capi20.00 c 68 1
-mknod /dev/capi20.01 c 68 2
-.
-.
-.
-mknod /dev/capi20.19 c 68 20
+::
+
+    mknod /dev/capi20 c 68 0
+    mknod /dev/capi20.00 c 68 1
+    mknod /dev/capi20.01 c 68 2
+    .
+    .
+    .
+    mknod /dev/capi20.19 c 68 20
 
 Running
 -------
@@ -38,45 +43,58 @@ To use the card you need the t4-files to download the firmware.
 AVM GmbH provides several t4-files for the different D-channel
 protocols (b1.t4 for Euro-ISDN). Install these file in /lib/isdn.
 
-if you configure as modules load the modules this way:
-
-insmod /lib/modules/current/misc/capiutil.o
-insmod /lib/modules/current/misc/b1.o
-insmod /lib/modules/current/misc/kernelcapi.o
-insmod /lib/modules/current/misc/capidrv.o
-insmod /lib/modules/current/misc/capi.o
-
-if you have an B1-PCI card load the module b1pci.o
-insmod /lib/modules/current/misc/b1pci.o
-and load the firmware with
-avmcapictrl load /lib/isdn/b1.t4 1
+if you configure as modules load the modules this way::
+
+    insmod /lib/modules/current/misc/capiutil.o
+    insmod /lib/modules/current/misc/b1.o
+    insmod /lib/modules/current/misc/kernelcapi.o
+    insmod /lib/modules/current/misc/capidrv.o
+    insmod /lib/modules/current/misc/capi.o
+
+if you have an B1-PCI card load the module b1pci.o::
+
+    insmod /lib/modules/current/misc/b1pci.o
+
+and load the firmware with::
+
+    avmcapictrl load /lib/isdn/b1.t4 1
 
 if you have an B1-ISA card load the module b1isa.o
-and add the card by calling
-avmcapictrl add 0x150 15
-and load the firmware by calling
-avmcapictrl load /lib/isdn/b1.t4 1
+and add the card by calling::
+
+    avmcapictrl add 0x150 15
+
+and load the firmware by calling::
+
+    avmcapictrl load /lib/isdn/b1.t4 1
 
 if you have an T1-ISA card load the module t1isa.o
-and add the card by calling
-avmcapictrl add 0x450 15 T1 0
-and load the firmware by calling
-avmcapictrl load /lib/isdn/t1.t4 1
+and add the card by calling::
+
+    avmcapictrl add 0x450 15 T1 0
+
+and load the firmware by calling::
+
+    avmcapictrl load /lib/isdn/t1.t4 1
 
 if you have an PCMCIA card (B1/M1/M2) load the module b1pcmcia.o
 before you insert the card.
 
 Leased Lines with B1
 --------------------
+
 Init card and load firmware.
+
 For an D64S use "FV: 1" as phone number
+
 For an D64S2 use "FV: 1" and "FV: 2" for multilink
 or "FV: 1,2" to use CAPI channel bundling.
 
 /proc-Interface
 -----------------
 
-/proc/capi:
+/proc/capi::
+
   dr-xr-xr-x   2 root     root            0 Jul  1 14:03 .
   dr-xr-xr-x  82 root     root            0 Jun 30 19:08 ..
   -r--r--r--   1 root     root            0 Jul  1 14:03 applications
@@ -91,84 +109,124 @@ or "FV: 1,2" to use CAPI channel bundling.
 
 /proc/capi/applications:
    applid level3cnt datablkcnt datablklen ncci-cnt recvqueuelen
-	level3cnt: capi_register parameter
-	datablkcnt: capi_register parameter
-	ncci-cnt: current number of nccis (connections)
-	recvqueuelen: number of messages on receive queue
-   for example:
-1 -2 16 2048 1 0
-2 2 7 2048 1 0
+	level3cnt:
+	    capi_register parameter
+	datablkcnt:
+	    capi_register parameter
+	ncci-cnt:
+	    current number of nccis (connections)
+	recvqueuelen:
+	    number of messages on receive queue
+
+   for example::
+
+	1 -2 16 2048 1 0
+	2 2 7 2048 1 0
 
 /proc/capi/applstats:
    applid recvctlmsg nrecvdatamsg nsentctlmsg nsentdatamsg
-	recvctlmsg: capi messages received without DATA_B3_IND
-	recvdatamsg: capi DATA_B3_IND received
-	sentctlmsg: capi messages sent without DATA_B3_REQ
-	sentdatamsg: capi DATA_B3_REQ sent
-   for example:
-1 2057 1699 1721 1699
+	recvctlmsg:
+	    capi messages received without DATA_B3_IND
+	recvdatamsg:
+	    capi DATA_B3_IND received
+	sentctlmsg:
+	    capi messages sent without DATA_B3_REQ
+	sentdatamsg:
+	    capi DATA_B3_REQ sent
+
+   for example::
+
+	1 2057 1699 1721 1699
 
 /proc/capi/capi20: statistics of capi.o (/dev/capi20)
     minor nopen nrecvdropmsg nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
-	minor: minor device number of capi device
-	nopen: number of calls to devices open
-	nrecvdropmsg: capi messages dropped (messages in recvqueue in close)
-	nrecvctlmsg: capi messages received without DATA_B3_IND
-	nrecvdatamsg: capi DATA_B3_IND received
-	nsentctlmsg: capi messages sent without DATA_B3_REQ
-	nsentdatamsg: capi DATA_B3_REQ sent
+	minor:
+	    minor device number of capi device
+	nopen:
+	    number of calls to devices open
+	nrecvdropmsg:
+	    capi messages dropped (messages in recvqueue in close)
+	nrecvctlmsg:
+	    capi messages received without DATA_B3_IND
+	nrecvdatamsg:
+	    capi DATA_B3_IND received
+	nsentctlmsg:
+	    capi messages sent without DATA_B3_REQ
+	nsentdatamsg:
+	    capi DATA_B3_REQ sent
 
-   for example:
-1 2 18 0 16 2
+   for example::
+
+	1 2 18 0 16 2
 
 /proc/capi/capidrv: statistics of capidrv.o (capi messages)
     nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
-	nrecvctlmsg: capi messages received without DATA_B3_IND
-	nrecvdatamsg: capi DATA_B3_IND received
-	nsentctlmsg: capi messages sent without DATA_B3_REQ
-	nsentdatamsg: capi DATA_B3_REQ sent
+	nrecvctlmsg:
+	    capi messages received without DATA_B3_IND
+	nrecvdatamsg:
+	    capi DATA_B3_IND received
+	nsentctlmsg:
+	    capi messages sent without DATA_B3_REQ
+	nsentdatamsg:
+	    capi DATA_B3_REQ sent
+
    for example:
-2780 2226 2256 2226
+	2780 2226 2256 2226
 
 /proc/capi/controller:
    controller drivername state cardname   controllerinfo
-   for example:
-1 b1pci      running  b1pci-e000       B1 3.07-01 0xe000 19
-2 t1isa      running  t1isa-450        B1 3.07-01 0x450 11 0
-3 b1pcmcia   running  m2-150           B1 3.07-01 0x150 5
+
+   for example::
+
+	1 b1pci      running  b1pci-e000       B1 3.07-01 0xe000 19
+	2 t1isa      running  t1isa-450        B1 3.07-01 0x450 11 0
+	3 b1pcmcia   running  m2-150           B1 3.07-01 0x150 5
 
 /proc/capi/contrstats:
     controller nrecvctlmsg nrecvdatamsg sentctlmsg sentdatamsg
-	nrecvctlmsg: capi messages received without DATA_B3_IND
-	nrecvdatamsg: capi DATA_B3_IND received
-	nsentctlmsg: capi messages sent without DATA_B3_REQ
-	nsentdatamsg: capi DATA_B3_REQ sent
-   for example:
-1 2845 2272 2310 2274
-2 2 0 2 0
-3 2 0 2 0
+	nrecvctlmsg:
+	    capi messages received without DATA_B3_IND
+	nrecvdatamsg:
+	    capi DATA_B3_IND received
+	nsentctlmsg:
+	    capi messages sent without DATA_B3_REQ
+	nsentdatamsg:
+	    capi DATA_B3_REQ sent
+
+   for example::
+
+	1 2845 2272 2310 2274
+	2 2 0 2 0
+	3 2 0 2 0
 
 /proc/capi/driver:
    drivername ncontroller
-   for example:
-b1pci                            1
-t1isa                            1
-b1pcmcia                         1
-b1isa                            0
+
+   for example::
+
+	b1pci                            1
+	t1isa                            1
+	b1pcmcia                         1
+	b1isa                            0
 
 /proc/capi/ncci:
    apllid ncci winsize sendwindow
-   for example:
-1 0x10101 8 0
+
+   for example::
+
+	1 0x10101 8 0
 
 /proc/capi/users: kernelmodules that use the kernelcapi.
    name
-   for example:
-capidrv
-capi20
+
+   for example::
+
+	capidrv
+	capi20
 
 Questions
 ---------
+
 Check out the FAQ (ftp.isdn4linux.de) or subscribe to the
 linux-avmb1@calle.in-berlin.de mailing list by sending
 a mail to majordomo@calle.in-berlin.de with
@@ -178,9 +236,10 @@ in the body.
 German documentation and several scripts can be found at
 ftp://ftp.avm.de/cardware/b1/linux/
 
-Bugs 
+Bugs
 ----
-If you find any please let me know. 
+
+If you find any please let me know.
 
 Enjoy,
 
diff --git a/Documentation/isdn/CREDITS b/Documentation/isdn/credits.rst
similarity index 96%
rename from Documentation/isdn/CREDITS
rename to Documentation/isdn/credits.rst
index c1679e913fca..319323f2091f 100644
--- a/Documentation/isdn/CREDITS
+++ b/Documentation/isdn/credits.rst
@@ -1,3 +1,7 @@
+=======
+Credits
+=======
+
 
 I want to thank all who contributed to this project and especially to:
 (in alphabetical order)
@@ -19,7 +23,7 @@ Matthias Hessler (hessler@isdn4linux.de)
   For creating and maintaining the FAQ.
 
 Bernhard Hailer (Bernhard.Hailer@lrz.uni-muenchen.de)
-  For creating the FAQ, and the leafsite HOWTO. 
+  For creating the FAQ, and the leafsite HOWTO.
 
 Michael 'Ghandi' Herold (michael@abadonna.franken.de)
   For contribution of the vbox answering machine.
@@ -67,4 +71,3 @@ Gerhard 'Fido' Schneider (fido@wuff.mayn.de)
 Thomas Uhl (uhl@think.de)
   For distributing the cards.
   For pushing me to work ;-)
-
diff --git a/Documentation/isdn/README.gigaset b/Documentation/isdn/gigaset.rst
similarity index 74%
rename from Documentation/isdn/README.gigaset
rename to Documentation/isdn/gigaset.rst
index f6184b637182..98b4ec521c51 100644
--- a/Documentation/isdn/README.gigaset
+++ b/Documentation/isdn/gigaset.rst
@@ -1,33 +1,36 @@
+==========================
 GigaSet 307x Device Driver
 ==========================
 
 1.   Requirements
-     ------------
+=================
+
 1.1. Hardware
-     --------
+-------------
+
      This driver supports the connection of the Gigaset 307x/417x family of
      ISDN DECT bases via Gigaset M101 Data, Gigaset M105 Data or direct USB
      connection. The following devices are reported to be compatible:
 
      Bases:
-        Siemens Gigaset 3070/3075 isdn
-        Siemens Gigaset 4170/4175 isdn
-        Siemens Gigaset SX205/255
-        Siemens Gigaset SX353
-        T-Com Sinus 45 [AB] isdn
-        T-Com Sinus 721X[A] [SE]
-        Vox Chicago 390 ISDN (KPN Telecom)
+       - Siemens Gigaset 3070/3075 isdn
+       - Siemens Gigaset 4170/4175 isdn
+       - Siemens Gigaset SX205/255
+       - Siemens Gigaset SX353
+       - T-Com Sinus 45 [AB] isdn
+       - T-Com Sinus 721X[A] [SE]
+       - Vox Chicago 390 ISDN (KPN Telecom)
 
      RS232 data boxes:
-        Siemens Gigaset M101 Data
-        T-Com Sinus 45 Data 1
+       - Siemens Gigaset M101 Data
+       - T-Com Sinus 45 Data 1
 
      USB data boxes:
-        Siemens Gigaset M105 Data
-        Siemens Gigaset USB Adapter DECT
-        T-Com Sinus 45 Data 2
-        T-Com Sinus 721 data
-        Chicago 390 USB (KPN)
+       - Siemens Gigaset M105 Data
+       - Siemens Gigaset USB Adapter DECT
+       - T-Com Sinus 45 Data 2
+       - T-Com Sinus 721 data
+       - Chicago 390 USB (KPN)
 
      See also http://www.erbze.info/sinus_gigaset.htm
        (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm ) and
@@ -37,17 +40,21 @@ GigaSet 307x Device Driver
      with SX 100 and CX 100 ISDN bases (only in unimodem mode, see section 2.5.)
      If you have another device that works with our driver, please let us know.
 
-     Chances of getting an USB device to work are good if the output of
-        lsusb
-     at the command line contains one of the following:
-        ID 0681:0001
-        ID 0681:0002
-        ID 0681:0009
-        ID 0681:0021
-        ID 0681:0022
+     Chances of getting an USB device to work are good if the output of::
+
+	lsusb
+
+     at the command line contains one of the following::
+
+	ID 0681:0001
+	ID 0681:0002
+	ID 0681:0009
+	ID 0681:0021
+	ID 0681:0022
 
 1.2. Software
-     --------
+-------------
+
      The driver works with the Kernel CAPI subsystem and can be used with any
      software which is able to use CAPI 2.0 for ISDN connections (voice or data).
 
@@ -58,9 +65,11 @@ GigaSet 307x Device Driver
 
 
 2.   How to use the driver
-     ---------------------
+==========================
+
 2.1. Modules
-     -------
+------------
+
      For the devices to work, the proper kernel modules have to be loaded.
      This normally happens automatically when the system detects the USB
      device (base, M105) or when the line discipline is attached (M101). It
@@ -71,13 +80,17 @@ GigaSet 307x Device Driver
      which uses the regular serial port driver to access the device, and must
      therefore be attached to the serial device to which the M101 is connected.
      The ldattach(8) command (included in util-linux-ng release 2.14 or later)
-     can be used for that purpose, for example:
+     can be used for that purpose, for example::
+
 	ldattach GIGASET_M101 /dev/ttyS1
+
      This will open the device file, attach the line discipline to it, and
      then sleep in the background, keeping the device open so that the line
      discipline remains active. To deactivate it, kill the daemon, for example
-     with
+     with::
+
 	killall ldattach
+
      before disconnecting the device. To have this happen automatically at
      system startup/shutdown on an LSB compatible system, create and activate
      an appropriate LSB startup script /etc/init.d/gigaset. (The init name
@@ -86,9 +99,10 @@ GigaSet 307x Device Driver
 
      The modules accept the following parameters:
 
-	Module	 	Parameter  Meaning
+	=============== ========== ==========================================
+	Module		Parameter  Meaning
 
-	gigaset	 	debug	   debug level (see section 3.2.)
+	gigaset		debug	   debug level (see section 3.2.)
 
 			startmode  initial operation mode (see section 2.5.):
 	bas_gigaset )		   1=CAPI (default), 0=Unimodem
@@ -96,11 +110,14 @@ GigaSet 307x Device Driver
 	usb_gigaset )	cidmode    initial Call-ID mode setting (see section
 				   2.5.): 1=on (default), 0=off
 
+	=============== ========== ==========================================
+
      Depending on your distribution you may want to create a separate module
      configuration file like /etc/modprobe.d/gigaset.conf for these.
 
 2.2. Device nodes for user space programs
-     ------------------------------------
+-----------------------------------------
+
      The device can be accessed from user space (eg. by the user space tools
      mentioned in 1.2.) through the device nodes:
 
@@ -113,46 +130,56 @@ GigaSet 307x Device Driver
 
      You can also set a "default device" for the user space tools to use when
      no device node is given as parameter, by creating a symlink /dev/ttyG to
-     one of them, eg.:
+     one of them, eg.::
 
 	ln -s /dev/ttyGB0 /dev/ttyG
 
      The devices accept the following device specific ioctl calls
      (defined in gigaset_dev.h):
 
-     ioctl(int fd, GIGASET_REDIR, int *cmd);
+     ``ioctl(int fd, GIGASET_REDIR, int *cmd);``
+
      If cmd==1, the device is set to be controlled exclusively through the
      character device node; access from the ISDN subsystem is blocked.
+
      If cmd==0, the device is set to be used from the ISDN subsystem and does
      not communicate through the character device node.
 
-     ioctl(int fd, GIGASET_CONFIG, int *cmd);
+     ``ioctl(int fd, GIGASET_CONFIG, int *cmd);``
+
      (ser_gigaset and usb_gigaset only)
+
      If cmd==1, the device is set to adapter configuration mode where commands
      are interpreted by the M10x DECT adapter itself instead of being
      forwarded to the base station. In this mode, the device accepts the
      commands described in Siemens document "AT-Kommando Alignment M10x Data"
      for setting the operation mode, associating with a base station and
      querying parameters like field strengh and signal quality.
+
      Note that there is no ioctl command for leaving adapter configuration
      mode and returning to regular operation. In order to leave adapter
      configuration mode, write the command ATO to the device.
 
-     ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);
+     ``ioctl(int fd, GIGASET_BRKCHARS, unsigned char brkchars[6]);``
+
      (usb_gigaset only)
+
      Set the break characters on an M105's internal serial adapter to the six
      bytes stored in brkchars[]. Unused bytes should be set to zero.
 
      ioctl(int fd, GIGASET_VERSION, unsigned version[4]);
      Retrieve version information from the driver. version[0] must be set to
      one of:
+
      - GIGVER_DRIVER: retrieve driver version
      - GIGVER_COMPAT: retrieve interface compatibility version
      - GIGVER_FWBASE: retrieve the firmware version of the base
+
      Upon return, version[] is filled with the requested version information.
 
 2.3. CAPI
-     ----
+---------
+
      The devices will show up as CAPI controllers as soon as the
      corresponding driver module is loaded, and can then be used with
      CAPI 2.0 kernel and user space applications. For user space access,
@@ -165,21 +192,22 @@ GigaSet 307x Device Driver
      driver.
 
 2.5. Unimodem mode
-     -------------
+------------------
+
      In this mode the device works like a modem connected to a serial port
-     (the /dev/ttyGU0, ... mentioned above) which understands the commands
+     (the /dev/ttyGU0, ... mentioned above) which understands the commands::
 
-         ATZ                 init, reset
-             => OK or ERROR
-         ATD
-         ATDT                dial
-             => OK, CONNECT,
-                BUSY,
-                NO DIAL TONE,
-                NO CARRIER,
-                NO ANSWER
-         <pause>+++<pause>   change to command mode when connected
-         ATH                 hangup
+	 ATZ                 init, reset
+	     => OK or ERROR
+	 ATD
+	 ATDT                dial
+	     => OK, CONNECT,
+		BUSY,
+		NO DIAL TONE,
+		NO CARRIER,
+		NO ANSWER
+	 <pause>+++<pause>   change to command mode when connected
+	 ATH                 hangup
 
      You can use some configuration tool of your distribution to configure this
      "modem" or configure pppd/wvdial manually. There are some example ppp
@@ -189,40 +217,52 @@ GigaSet 307x Device Driver
      control lines. This means you must use "Stupid Mode" if you are using
      wvdial or you should use the nocrtscts option of pppd.
      You must also assure that the ppp_async module is loaded with the parameter
-     flag_time=0. You can do this e.g. by adding a line like
+     flag_time=0. You can do this e.g. by adding a line like::
 
-        options ppp_async flag_time=0
+	options ppp_async flag_time=0
 
-     to an appropriate module configuration file, like
-     /etc/modprobe.d/gigaset.conf.
+     to an appropriate module configuration file, like::
+
+	/etc/modprobe.d/gigaset.conf.
 
      Unimodem mode is needed for making some devices [e.g. SX100] work which
      do not support the regular Gigaset command set. If debug output (see
-     section 3.2.) shows something like this when dialing:
-         CMD Received: ERROR
-         Available Params: 0
-         Connection State: 0, Response: -1
-         gigaset_process_response: resp_code -1 in ConState 0 !
-         Timeout occurred
+     section 3.2.) shows something like this when dialing::
+
+	 CMD Received: ERROR
+	 Available Params: 0
+	 Connection State: 0, Response: -1
+	 gigaset_process_response: resp_code -1 in ConState 0 !
+	 Timeout occurred
+
      then switching to unimodem mode may help.
 
      If you have installed the command line tool gigacontr, you can enter
-     unimodem mode using
-         gigacontr --mode unimodem
-     You can switch back using
-         gigacontr --mode isdn
+     unimodem mode using::
+
+	 gigacontr --mode unimodem
+
+     You can switch back using::
+
+	 gigacontr --mode isdn
 
      You can also put the driver directly into Unimodem mode when it's loaded,
      by passing the module parameter startmode=0 to the hardware specific
-     module, e.g.
+     module, e.g.::
+
 	modprobe usb_gigaset startmode=0
-     or by adding a line like
+
+     or by adding a line like::
+
 	options usb_gigaset startmode=0
-     to an appropriate module configuration file, like
-     /etc/modprobe.d/gigaset.conf
+
+     to an appropriate module configuration file, like::
+
+	/etc/modprobe.d/gigaset.conf
 
 2.6. Call-ID (CID) mode
-     ------------------
+-----------------------
+
      Call-IDs are numbers used to tag commands to, and responses from, the
      Gigaset base in order to support the simultaneous handling of multiple
      ISDN calls. Their use can be enabled ("CID mode") or disabled ("Unimodem
@@ -238,6 +278,7 @@ GigaSet 307x Device Driver
      During active operation, the driver switches to the necessary mode
      automatically. However, for the reasons above, the mode chosen when
      the device is not in use (idle) can be selected by the user.
+
      - If you want to receive incoming calls, you can use the default
        settings (CID mode).
      - If you have several DECT data devices (M10x) which you want to use
@@ -247,25 +288,27 @@ GigaSet 307x Device Driver
      If you want both of these at once, you are out of luck.
 
      You can also use the tty class parameter "cidmode" of the device to
-     change its CID mode while the driver is loaded, eg.
-        echo 0 > /sys/class/tty/ttyGU0/cidmode
+     change its CID mode while the driver is loaded, eg.::
+
+	echo 0 > /sys/class/tty/ttyGU0/cidmode
 
 2.7. Dialing Numbers
-     ---------------
-     The called party number provided by an application for dialing out must
+--------------------
+provided by an application for dialing out must
      be a public network number according to the local dialing plan, without
      any dial prefix for getting an outside line.
 
      Internal calls can be made by providing an internal extension number
-     prefixed with "**" (two asterisks) as the called party number. So to dial
-     eg. the first registered DECT handset, give "**11" as the called party
-     number. Dialing "***" (three asterisks) calls all extensions
+     prefixed with ``**`` (two asterisks) as the called party number. So to dial
+     eg. the first registered DECT handset, give ``**11`` as the called party
+     number. Dialing ``***`` (three asterisks) calls all extensions
      simultaneously (global call).
 
      Unimodem mode does not support internal calls.
 
 2.8. Unregistered Wireless Devices (M101/M105)
-     -----------------------------------------
+----------------------------------------------
+
      The main purpose of the ser_gigaset and usb_gigaset drivers is to allow
      the M101 and M105 wireless devices to be used as ISDN devices for ISDN
      connections through a Gigaset base. Therefore they assume that the device
@@ -279,73 +322,91 @@ GigaSet 307x Device Driver
      modes. See the gigacontr(8) manpage for details.
 
 3.   Troubleshooting
-     ---------------
+====================
+
 3.1. Solutions to frequently reported problems
-     -----------------------------------------
+----------------------------------------------
+
      Problem:
-        You have a slow provider and isdn4linux gives up dialing too early.
+	You have a slow provider and isdn4linux gives up dialing too early.
      Solution:
-        Load the isdn module using the dialtimeout option. You can do this e.g.
-        by adding a line like
+	Load the isdn module using the dialtimeout option. You can do this e.g.
+	by adding a line like::
 
-           options isdn dialtimeout=15
+	   options isdn dialtimeout=15
 
-        to /etc/modprobe.d/gigaset.conf or a similar file.
+	to /etc/modprobe.d/gigaset.conf or a similar file.
 
      Problem:
-        The isdnlog program emits error messages or just doesn't work.
+	The isdnlog program emits error messages or just doesn't work.
      Solution:
-        Isdnlog supports only the HiSax driver. Do not attempt to use it with
+	Isdnlog supports only the HiSax driver. Do not attempt to use it with
 	other drivers such as Gigaset.
 
      Problem:
-        You have two or more DECT data adapters (M101/M105) and only the
-        first one you turn on works.
+	You have two or more DECT data adapters (M101/M105) and only the
+	first one you turn on works.
      Solution:
-        Select Unimodem mode for all DECT data adapters. (see section 2.5.)
+	Select Unimodem mode for all DECT data adapters. (see section 2.5.)
 
      Problem:
-	Messages like this:
+	Messages like this::
+
 	    usb_gigaset 3-2:1.0: Could not initialize the device.
+
 	appear in your syslog.
      Solution:
 	Check whether your M10x wireless device is correctly registered to the
 	Gigaset base. (see section 2.7.)
 
 3.2. Telling the driver to provide more information
-     ----------------------------------------------
+---------------------------------------------------
      Building the driver with the "Gigaset debugging" kernel configuration
      option (CONFIG_GIGASET_DEBUG) gives it the ability to produce additional
      information useful for debugging.
 
      You can control the amount of debugging information the driver produces by
-     writing an appropriate value to /sys/module/gigaset/parameters/debug, e.g.
-        echo 0 > /sys/module/gigaset/parameters/debug
+     writing an appropriate value to /sys/module/gigaset/parameters/debug,
+     e.g.::
+
+	echo 0 > /sys/module/gigaset/parameters/debug
+
      switches off debugging output completely,
-        echo 0x302020 > /sys/module/gigaset/parameters/debug
+
+     ::
+
+	echo 0x302020 > /sys/module/gigaset/parameters/debug
+
      enables a reasonable set of debugging output messages. These values are
      bit patterns where every bit controls a certain type of debugging output.
      See the constants DEBUG_* in the source file gigaset.h for details.
 
      The initial value can be set using the debug parameter when loading the
-     module "gigaset", e.g. by adding a line
-        options gigaset debug=0
+     module "gigaset", e.g. by adding a line::
+
+	options gigaset debug=0
+
      to your module configuration file, eg. /etc/modprobe.d/gigaset.conf
 
      Generated debugging information can be found
-     - as output of the command
-         dmesg
+     - as output of the command::
+
+	 dmesg
+
      - in system log files written by your syslog daemon, usually
        in /var/log/, e.g. /var/log/messages.
 
 3.3. Reporting problems and bugs
-     ---------------------------
+--------------------------------
      If you can't solve problems with the driver on your own, feel free to
      use one of the forums, bug trackers, or mailing lists on
-         https://sourceforge.net/projects/gigaset307x
+
+	 https://sourceforge.net/projects/gigaset307x
+
      or write an electronic mail to the maintainers.
 
      Try to provide as much information as possible, such as
+
      - distribution
      - kernel version (uname -r)
      - gcc version (gcc --version)
@@ -362,7 +423,7 @@ GigaSet 307x Device Driver
      appropriate forums and newsgroups.
 
 3.4. Reporting problem solutions
-     ---------------------------
+--------------------------------
      If you solved a problem with our drivers, wrote startup scripts for your
      distribution, ... feel free to contact us (using one of the places
      mentioned in 3.3.). We'd like to add scripts, hints, documentation
@@ -370,34 +431,35 @@ GigaSet 307x Device Driver
 
 
 4.   Links, other software
-     ---------------------
+==========================
+
      - Sourceforge project developing this driver and associated tools
-         https://sourceforge.net/projects/gigaset307x
+	 https://sourceforge.net/projects/gigaset307x
      - Yahoo! Group on the Siemens Gigaset family of devices
-         https://de.groups.yahoo.com/group/Siemens-Gigaset
+	 https://de.groups.yahoo.com/group/Siemens-Gigaset
      - Siemens Gigaset/T-Sinus compatibility table
-         http://www.erbze.info/sinus_gigaset.htm
+	 http://www.erbze.info/sinus_gigaset.htm
 	    (archived at https://web.archive.org/web/20100717020421/http://www.erbze.info:80/sinus_gigaset.htm )
 
 
 5.   Credits
-     -------
+============
+
      Thanks to
 
      Karsten Keil
-        for his help with isdn4linux
+	for his help with isdn4linux
      Deti Fliegl
-        for his base driver code
+	for his base driver code
      Dennis Dietrich
-        for his kernel 2.6 patches
+	for his kernel 2.6 patches
      Andreas Rummel
-        for his work and logs to get unimodem mode working
+	for his work and logs to get unimodem mode working
      Andreas Degert
-        for his logs and patches to get cx 100 working
+	for his logs and patches to get cx 100 working
      Dietrich Feist
-        for his generous donation of one M105 and two M101 cordless adapters
+	for his generous donation of one M105 and two M101 cordless adapters
      Christoph Schweers
-        for his generous donation of a M34 device
+	for his generous donation of a M34 device
 
      and all the other people who sent logs and other information.
-
diff --git a/Documentation/isdn/README.hysdn b/Documentation/isdn/hysdn.rst
similarity index 80%
rename from Documentation/isdn/README.hysdn
rename to Documentation/isdn/hysdn.rst
index eeca11f00ccd..0a168d1cbffc 100644
--- a/Documentation/isdn/README.hysdn
+++ b/Documentation/isdn/hysdn.rst
@@ -1,4 +1,7 @@
-$Id: README.hysdn,v 1.3.6.1 2001/02/10 14:41:19 kai Exp $
+============
+Hysdn Driver
+============
+
 The hysdn driver has been written by
 Werner Cornelius (werner@isdn4linux.de or werner@titro.de)
 for Hypercope GmbH Aachen Germany. Hypercope agreed to publish this driver
@@ -22,28 +25,28 @@ for Hypercope GmbH Aachen, Germany.
     along with this program; if not, write to the Free Software
     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 
-Table of contents
-=================
+.. Table of contents
 
-1. About the driver
+    1. About the driver
 
-2. Loading/Unloading the driver
+    2. Loading/Unloading the driver
 
-3. Entries in the /proc filesystem
+    3. Entries in the /proc filesystem
 
-4. The /proc/net/hysdn/cardconfX file
+    4. The /proc/net/hysdn/cardconfX file
 
-5. The /proc/net/hysdn/cardlogX file
+    5. The /proc/net/hysdn/cardlogX file
 
-6. Where to get additional info and help
+    6. Where to get additional info and help
 
 
 1. About the driver
+===================
 
-   The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active 
+   The drivers/isdn/hysdn subdir contains a driver for HYPERCOPEs active
    PCI isdn cards Champ, Ergo and Metro. To enable support for this cards
    enable ISDN support in the kernel config and support for HYSDN cards in
-   the active cards submenu. The driver may only be compiled and used if 
+   the active cards submenu. The driver may only be compiled and used if
    support for loadable modules and the process filesystem have been enabled.
 
    These cards provide two different interfaces to the kernel. Without the
@@ -52,22 +55,23 @@ Table of contents
    handlers for various protocols like ppp and others as well as config info
    and firmware may be fetched from Hypercopes WWW-Site www.hypercope.de.
 
-   With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0 
-   compliant devices with either CAPI 2.0 applications 
+   With CAPI 2.0 support enabled, the card can also be used as a CAPI 2.0
+   compliant devices with either CAPI 2.0 applications
    (check isdn4k-utils) or -using the capidrv module- as a regular
-   isdn4linux device. This is done via the same mechanism as with the 
+   isdn4linux device. This is done via the same mechanism as with the
    active AVM cards and in fact uses the same module.
-   
+
 
 2. Loading/Unloading the driver
+===============================
 
    The module has no command line parameters and auto detects up to 10 cards
    in the id-range 0-9.
    If a loaded driver shall be unloaded all open files in the /proc/net/hysdn
-   subdir need to be closed and all ethernet interfaces allocated by this 
+   subdir need to be closed and all ethernet interfaces allocated by this
    driver must be shut down. Otherwise the module counter will avoid a module
    unload.
-   
+
    If you are using the CAPI 2.0-interface, make sure to load/modprobe the
    kernelcapi-module first.
 
@@ -76,52 +80,57 @@ Table of contents
    any avm-specific modules).
 
 3. Entries in the /proc filesystem
+==================================
 
-   When the module has been loaded it adds the directory hysdn in the 
-   /proc/net tree. This directory contains exactly 2 file entries for each 
+   When the module has been loaded it adds the directory hysdn in the
+   /proc/net tree. This directory contains exactly 2 file entries for each
    card. One is called cardconfX and the other cardlogX, where X is the
-   card id number from 0 to 9. 
+   card id number from 0 to 9.
    The cards are numbered in the order found in the PCI config data.
 
 4. The /proc/net/hysdn/cardconfX file
+=====================================
 
-   This file may be read to get by everyone to get info about the cards type, 
+   This file may be read to get by everyone to get info about the cards type,
    actual state, available features and used resources.
    The first 3 entries (id, bus and slot) are PCI info fields, the following
    type field gives the information about the cards type:
 
-   4 -> Ergo card (server card with 2 b-chans)
-   5 -> Metro card (server card with 4 or 8 b-chans)
-   6 -> Champ card (client card with 2 b-chans)   
+   - 4 -> Ergo card (server card with 2 b-chans)
+   - 5 -> Metro card (server card with 4 or 8 b-chans)
+   - 6 -> Champ card (client card with 2 b-chans)
 
    The following 3 fields show the hardware assignments for irq, iobase and the
    dual ported memory (dp-mem).
+
    The fields b-chans and fax-chans announce the available card resources of
    this types for the user.
+
    The state variable indicates the actual drivers state for this card with the
    following assignments.
 
-   0 -> card has not been booted since driver load
-   1 -> card booting is actually in progess
-   2 -> card is in an error state due to a previous boot failure
-   3 -> card is booted and active
+   - 0 -> card has not been booted since driver load
+   - 1 -> card booting is actually in progess
+   - 2 -> card is in an error state due to a previous boot failure
+   - 3 -> card is booted and active
 
    And the last field (device) shows the name of the ethernet device assigned
    to this card. Up to the first successful boot this field only shows a -
    to tell that no net device has been allocated up to now. Once a net device
    has been allocated it remains assigned to this card, even if a card is
-   rebooted and an boot error occurs. 
+   rebooted and an boot error occurs.
 
-   Writing to the cardconfX file boots the card or transfers config lines to 
-   the cards firmware. The type of data is automatically detected when the 
+   Writing to the cardconfX file boots the card or transfers config lines to
+   the cards firmware. The type of data is automatically detected when the
    first data is written. Only root has write access to this file.
    The firmware boot files are normally called hyclient.pof for client cards
    and hyserver.pof for server cards.
    After successfully writing the boot file, complete config files or single
    config lines may be copied to this file.
-   If an error occurs the return value given to the writing process has the 
+   If an error occurs the return value given to the writing process has the
    following additional codes (decimal):
 
+   ==== ============================================
    1000 Another process is currently bootng the card
    1001 Invalid firmware header
    1002 Boards dual-port RAM test failed
@@ -131,34 +140,39 @@ Table of contents
    1006 Second boot stage failure
    1007 Timeout waiting for card ready during boot
    1008 Operation only allowed in booted state
-   1009 Config line too long 
-   1010 Invalid channel number 
+   1009 Config line too long
+   1010 Invalid channel number
    1011 Timeout sending config data
+   ==== ============================================
 
-   Additional info about error reasons may be fetched from the log output. 
+   Additional info about error reasons may be fetched from the log output.
 
 5. The /proc/net/hysdn/cardlogX file
-   	  
-   The cardlogX file entry may be opened multiple for reading by everyone to 
+====================================
+
+   The cardlogX file entry may be opened multiple for reading by everyone to
    get the cards and drivers log data. Card messages always start with the
-   keyword LOG. All other lines are output from the driver. 
-   The driver log data may be redirected to the syslog by selecting the 
+   keyword LOG. All other lines are output from the driver.
+   The driver log data may be redirected to the syslog by selecting the
    appropriate bitmask. The cards log messages will always be send to this
    interface but never to the syslog.
 
    A root user may write a decimal or hex (with 0x) value t this file to select
-   desired output options. As mentioned above the cards log dat is always 
+   desired output options. As mentioned above the cards log dat is always
    written to the cardlog file independent of the following options only used
    to check and debug the driver itself:
 
-   For example: 
-   echo "0x34560078" > /proc/net/hysdn/cardlog0
+   For example::
+
+	echo "0x34560078" > /proc/net/hysdn/cardlog0
+
    to output the hex log mask 34560078 for card 0.
- 
-   The written value is regarded as an unsigned 32-Bit value, bit ored for 
+
+   The written value is regarded as an unsigned 32-Bit value, bit ored for
    desired output. The following bits are already assigned:
 
-   0x80000000   All driver log data is alternatively via syslog 
+   ==========   ============================================================
+   0x80000000   All driver log data is alternatively via syslog
    0x00000001   Log memory allocation errors
    0x00000010   Firmware load start and close are logged
    0x00000020   Log firmware record parser
@@ -171,25 +185,12 @@ Table of contents
    0x00100000   Log all open and close actions to /proc/net/hysdn/card files
    0x00200000   Log all actions from /proc file entries
    0x00010000   Log network interface init and deinit
-   
+   ==========   ============================================================
+
 6. Where to get additional info and help
+========================================
 
-   If you have any problems concerning the driver or configuration contact 
+   If you have any problems concerning the driver or configuration contact
    the Hypercope support team (support@hypercope.de) and or the authors
    Werner Cornelius (werner@isdn4linux or cornelius@titro.de) or
    Ulrich Albrecht (ualbrecht@hypercope.de).
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/Documentation/isdn/index.rst b/Documentation/isdn/index.rst
new file mode 100644
index 000000000000..407e74b78372
--- /dev/null
+++ b/Documentation/isdn/index.rst
@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+ISDN
+====
+
+.. toctree::
+   :maxdepth: 2
+
+   interface_capi
+
+   avmb1
+   gigaset
+   hysdn
+   m_isdn
+
+   credits
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/isdn/INTERFACE.CAPI b/Documentation/isdn/interface_capi.rst
similarity index 75%
rename from Documentation/isdn/INTERFACE.CAPI
rename to Documentation/isdn/interface_capi.rst
index 021aa9cf139d..01a4b5ade9a4 100644
--- a/Documentation/isdn/INTERFACE.CAPI
+++ b/Documentation/isdn/interface_capi.rst
@@ -1,7 +1,9 @@
+=========================================
 Kernel CAPI Interface to Hardware Drivers
------------------------------------------
+=========================================
 
 1. Overview
+===========
 
 From the CAPI 2.0 specification:
 COMMON-ISDN-API (CAPI) is an application programming interface standard used
@@ -22,6 +24,7 @@ This standard is freely available from https://www.capi.org.
 
 
 2. Driver and Device Registration
+=================================
 
 CAPI drivers optionally register themselves with Kernel CAPI by calling the
 Kernel CAPI function register_capi_driver() with a pointer to a struct
@@ -50,6 +53,7 @@ callback functions by Kernel CAPI.
 
 
 3. Application Registration and Communication
+=============================================
 
 Kernel CAPI forwards registration requests from applications (calls to CAPI
 operation CAPI_REGISTER) to an appropriate hardware driver by calling its
@@ -71,23 +75,26 @@ messages for that application may be passed to or from the device anymore.
 
 
 4. Data Structures
+==================
 
 4.1 struct capi_driver
+----------------------
 
 This structure describes a Kernel CAPI driver itself. It is used in the
 register_capi_driver() and unregister_capi_driver() functions, and contains
 the following non-private fields, all to be set by the driver before calling
 register_capi_driver():
 
-char name[32]
+``char name[32]``
 	the name of the driver, as a zero-terminated ASCII string
-char revision[32]
+``char revision[32]``
 	the revision number of the driver, as a zero-terminated ASCII string
-int (*add_card)(struct capi_driver *driver, capicardparams *data)
+``int (*add_card)(struct capi_driver *driver, capicardparams *data)``
 	a callback function pointer (may be NULL)
 
 
 4.2 struct capi_ctr
+-------------------
 
 This structure describes an ISDN device (controller) handled by a Kernel CAPI
 driver. After registration via the attach_capi_ctr() function it is passed to
@@ -96,88 +103,109 @@ identify the controller to operate on.
 
 It contains the following non-private fields:
 
-- to be set by the driver before calling attach_capi_ctr():
+to be set by the driver before calling attach_capi_ctr():
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-struct module *owner
+``struct module *owner``
 	pointer to the driver module owning the device
 
-void *driverdata
+``void *driverdata``
 	an opaque pointer to driver specific data, not touched by Kernel CAPI
 
-char name[32]
+``char name[32]``
 	the name of the controller, as a zero-terminated ASCII string
 
-char *driver_name
+``char *driver_name``
 	the name of the driver, as a zero-terminated ASCII string
 
-int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)
+``int (*load_firmware)(struct capi_ctr *ctrlr, capiloaddata *ldata)``
 	(optional) pointer to a callback function for sending firmware and
 	configuration data to the device
+
 	The function may return before the operation has completed.
+
 	Completion must be signalled by a call to capi_ctr_ready().
+
 	Return value: 0 on success, error code on error
 	Called in process context.
 
-void (*reset_ctr)(struct capi_ctr *ctrlr)
+``void (*reset_ctr)(struct capi_ctr *ctrlr)``
 	(optional) pointer to a callback function for stopping the device,
 	releasing all registered applications
+
 	The function may return before the operation has completed.
+
 	Completion must be signalled by a call to capi_ctr_down().
+
 	Called in process context.
 
-void (*register_appl)(struct capi_ctr *ctrlr, u16 applid,
-			capi_register_params *rparam)
-void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)
-	pointers to callback functions for registration and deregistration of
+``void (*register_appl)(struct capi_ctr *ctrlr, u16 applid, capi_register_params *rparam)``
+	pointers to callback function for registration of
 	applications with the device
+
+	Calls to these functions are serialized by Kernel CAPI so that only
+	one call to any of them is active at any time.
+
+``void (*release_appl)(struct capi_ctr *ctrlr, u16 applid)``
+	pointers to callback functions deregistration of
+	applications with the device
+
 	Calls to these functions are serialized by Kernel CAPI so that only
 	one call to any of them is active at any time.
 
-u16  (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)
+``u16  (*send_message)(struct capi_ctr *ctrlr, struct sk_buff *skb)``
 	pointer to a callback function for sending a CAPI message to the
 	device
+
 	Return value: CAPI error code
+
 	If the method returns 0 (CAPI_NOERROR) the driver has taken ownership
 	of the skb and the caller may no longer access it. If it returns a
 	non-zero (error) value then ownership of the skb returns to the caller
 	who may reuse or free it.
+
 	The return value should only be used to signal problems with respect
 	to accepting or queueing the message. Errors occurring during the
 	actual processing of the message should be signaled with an
 	appropriate reply message.
+
 	May be called in process or interrupt context.
+
 	Calls to this function are not serialized by Kernel CAPI, ie. it must
 	be prepared to be re-entered.
 
-char *(*procinfo)(struct capi_ctr *ctrlr)
+``char *(*procinfo)(struct capi_ctr *ctrlr)``
 	pointer to a callback function returning the entry for the device in
 	the CAPI controller info table, /proc/capi/controller
 
-const struct file_operations *proc_fops
+``const struct file_operations *proc_fops``
 	pointers to callback functions for the device's proc file
 	system entry, /proc/capi/controllers/<n>; pointer to the device's
 	capi_ctr structure is available from struct proc_dir_entry::data
 	which is available from struct inode.
 
-Note: Callback functions except send_message() are never called in interrupt
-context.
+Note:
+  Callback functions except send_message() are never called in interrupt
+  context.
 
-- to be filled in before calling capi_ctr_ready():
+to be filled in before calling capi_ctr_ready():
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-u8 manu[CAPI_MANUFACTURER_LEN]
+``u8 manu[CAPI_MANUFACTURER_LEN]``
 	value to return for CAPI_GET_MANUFACTURER
 
-capi_version version
+``capi_version version``
 	value to return for CAPI_GET_VERSION
 
-capi_profile profile
+``capi_profile profile``
 	value to return for CAPI_GET_PROFILE
 
-u8 serial[CAPI_SERIAL_LEN]
+``u8 serial[CAPI_SERIAL_LEN]``
 	value to return for CAPI_GET_SERIAL
 
 
 4.3 SKBs
+--------
 
 CAPI messages are passed between Kernel CAPI and the driver via send_message()
 and capi_ctr_handle_message(), stored in the data portion of a socket buffer
@@ -192,6 +220,7 @@ instead of 30.
 
 
 4.4 The _cmsg Structure
+-----------------------
 
 (declared in <linux/isdn/capiutil.h>)
 
@@ -216,6 +245,7 @@ Members are named after the CAPI 2.0 standard names of the parameters they
 represent. See <linux/isdn/capiutil.h> for the exact spelling. Member data
 types are:
 
+=========== =================================================================
 u8          for CAPI parameters of type 'byte'
 
 u16         for CAPI parameters of type 'word'
@@ -235,6 +265,7 @@ _cmstruct   alternative representation for CAPI parameters of type 'struct'
 	    CAPI_COMPOSE: The parameter is present.
 	    Subparameter values are stored individually in the corresponding
 	    _cmsg structure members.
+=========== =================================================================
 
 Functions capi_cmsg2message() and capi_message2cmsg() are provided to convert
 messages between their transport encoding described in the CAPI 2.0 standard
@@ -244,51 +275,71 @@ sure it is big enough to accommodate the resulting CAPI message.
 
 
 5. Lower Layer Interface Functions
+==================================
 
 (declared in <linux/isdn/capilli.h>)
 
-void register_capi_driver(struct capi_driver *drvr)
-void unregister_capi_driver(struct capi_driver *drvr)
-	register/unregister a driver with Kernel CAPI
-
-int attach_capi_ctr(struct capi_ctr *ctrlr)
-int detach_capi_ctr(struct capi_ctr *ctrlr)
-	register/unregister a device (controller) with Kernel CAPI
-
-void capi_ctr_ready(struct capi_ctr *ctrlr)
-void capi_ctr_down(struct capi_ctr *ctrlr)
-	signal controller ready/not ready
-
-void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
-void capi_ctr_resume_output(struct capi_ctr *ctrlr)
-	signal suspend/resume
-
-void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
-				struct sk_buff *skb)
-	pass a received CAPI message to Kernel CAPI
-	for forwarding to the specified application
+::
+
+  void register_capi_driver(struct capi_driver *drvr)
+  void unregister_capi_driver(struct capi_driver *drvr)
+
+register/unregister a driver with Kernel CAPI
+
+::
+
+  int attach_capi_ctr(struct capi_ctr *ctrlr)
+  int detach_capi_ctr(struct capi_ctr *ctrlr)
+
+register/unregister a device (controller) with Kernel CAPI
+
+::
+
+  void capi_ctr_ready(struct capi_ctr *ctrlr)
+  void capi_ctr_down(struct capi_ctr *ctrlr)
+
+signal controller ready/not ready
+
+::
+
+  void capi_ctr_suspend_output(struct capi_ctr *ctrlr)
+  void capi_ctr_resume_output(struct capi_ctr *ctrlr)
+
+signal suspend/resume
+
+::
+
+  void capi_ctr_handle_message(struct capi_ctr * ctrlr, u16 applid,
+			       struct sk_buff *skb)
+
+pass a received CAPI message to Kernel CAPI
+for forwarding to the specified application
 
 
 6. Helper Functions and Macros
+==============================
 
 Library functions (from <linux/isdn/capilli.h>):
 
-void capilib_new_ncci(struct list_head *head, u16 applid,
+::
+
+  void capilib_new_ncci(struct list_head *head, u16 applid,
 			u32 ncci, u32 winsize)
-void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
-void capilib_release_appl(struct list_head *head, u16 applid)
-void capilib_release(struct list_head *head)
-void capilib_data_b3_conf(struct list_head *head, u16 applid,
+  void capilib_free_ncci(struct list_head *head, u16 applid, u32 ncci)
+  void capilib_release_appl(struct list_head *head, u16 applid)
+  void capilib_release(struct list_head *head)
+  void capilib_data_b3_conf(struct list_head *head, u16 applid,
 			u32 ncci, u16 msgid)
-u16  capilib_data_b3_req(struct list_head *head, u16 applid,
+  u16  capilib_data_b3_req(struct list_head *head, u16 applid,
 			u32 ncci, u16 msgid)
 
 
 Macros to extract/set element values from/in a CAPI message header
 (from <linux/isdn/capiutil.h>):
 
+======================  =============================   ====================
 Get Macro		Set Macro			Element (Type)
-
+======================  =============================   ====================
 CAPIMSG_LEN(m)		CAPIMSG_SETLEN(m, len)		Total Length (u16)
 CAPIMSG_APPID(m)	CAPIMSG_SETAPPID(m, applid)	ApplID (u16)
 CAPIMSG_COMMAND(m)	CAPIMSG_SETCOMMAND(m,cmd)	Command (u8)
@@ -300,31 +351,31 @@ CAPIMSG_MSGID(m)	CAPIMSG_SETMSGID(m, msgid)	Message Number (u16)
 CAPIMSG_CONTROL(m)	CAPIMSG_SETCONTROL(m, contr)	Controller/PLCI/NCCI
 							(u32)
 CAPIMSG_DATALEN(m)	CAPIMSG_SETDATALEN(m, len)	Data Length (u16)
+======================  =============================   ====================
 
 
 Library functions for working with _cmsg structures
 (from <linux/isdn/capiutil.h>):
 
-unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)
-	Assembles a CAPI 2.0 message from the parameters in *cmsg, storing the
-	result in *msg.
+``unsigned capi_cmsg2message(_cmsg *cmsg, u8 *msg)``
+	Assembles a CAPI 2.0 message from the parameters in ``*cmsg``,
+	storing the result in ``*msg``.
 
-unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)
-	Disassembles the CAPI 2.0 message in *msg, storing the parameters in
-	*cmsg.
+``unsigned capi_message2cmsg(_cmsg *cmsg, u8 *msg)``
+	Disassembles the CAPI 2.0 message in ``*msg``, storing the parameters
+	in ``*cmsg``.
 
-unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand,
-			  u16 Messagenumber, u32 Controller)
-	Fills the header part and address field of the _cmsg structure *cmsg
+``unsigned capi_cmsg_header(_cmsg *cmsg, u16 ApplId, u8 Command, u8 Subcommand, u16 Messagenumber, u32 Controller)``
+	Fills the header part and address field of the _cmsg structure ``*cmsg``
 	with the given values, zeroing the remainder of the structure so only
 	parameters with non-default values need to be changed before sending
 	the message.
 
-void capi_cmsg_answer(_cmsg *cmsg)
-	Sets the low bit of the Subcommand field in *cmsg, thereby converting
-	_REQ to _CONF and _IND to _RESP.
+``void capi_cmsg_answer(_cmsg *cmsg)``
+	Sets the low bit of the Subcommand field in ``*cmsg``, thereby
+	converting ``_REQ`` to ``_CONF`` and ``_IND`` to ``_RESP``.
 
-char *capi_cmd2str(u8 Command, u8 Subcommand)
+``char *capi_cmd2str(u8 Command, u8 Subcommand)``
 	Returns the CAPI 2.0 message name corresponding to the given command
 	and subcommand values, as a static ASCII string. The return value may
 	be NULL if the command/subcommand is not one of those defined in the
@@ -332,6 +383,7 @@ char *capi_cmd2str(u8 Command, u8 Subcommand)
 
 
 7. Debugging
+============
 
 The module kernelcapi has a module parameter showcapimsgs controlling some
 debugging output produced by the module. It can only be set when the module is
diff --git a/Documentation/isdn/README.mISDN b/Documentation/isdn/m_isdn.rst
similarity index 89%
rename from Documentation/isdn/README.mISDN
rename to Documentation/isdn/m_isdn.rst
index cd8bf920e77b..9957de349e69 100644
--- a/Documentation/isdn/README.mISDN
+++ b/Documentation/isdn/m_isdn.rst
@@ -1,6 +1,9 @@
+============
+mISDN Driver
+============
+
 mISDN is a new modular ISDN driver, in the long term it should replace
 the old I4L driver architecture for passiv ISDN cards.
 It was designed to allow a broad range of applications and interfaces
 but only have the basic function in kernel, the interface to the user
 space is based on sockets with a own address family AF_ISDN.
-
diff --git a/drivers/staging/isdn/hysdn/Kconfig b/drivers/staging/isdn/hysdn/Kconfig
index 1971ef850c9a..4c8a9283b9dd 100644
--- a/drivers/staging/isdn/hysdn/Kconfig
+++ b/drivers/staging/isdn/hysdn/Kconfig
@@ -5,7 +5,7 @@ config HYSDN
 	help
 	  Say Y here if you have one of Hypercope's active PCI ISDN cards
 	  Champ, Ergo and Metro. You will then get a module called hysdn.
-	  Please read the file <file:Documentation/isdn/README.hysdn> for more
+	  Please read the file <file:Documentation/isdn/hysdn.rst> for more
 	  information.
 
 config HYSDN_CAPI
-- 
2.21.0

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

* [PATCH v2 16/26] docs: fs: cifs: convert to ReST and add to admin-guide book
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (19 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Steve French, Jonathan Corbet, linux-cifs,
	samba-technical, linux-doc

The filenames for cifs documentation is not using the same
convention as almost all Kernel documents is using. So,
rename them to a more appropriate name. Then, manually convert
the documentation files for CIFS to ReST.

By doing a manual conversion, we can preserve the original
author's style, while making it to look more like the other
Kernel documents.

Most of the conversion here is trivial. The most complex one was
the README file (which was renamed to usage.rst).

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 .../AUTHORS => admin-guide/cifs/authors.rst}  |  64 +-
 .../CHANGES => admin-guide/cifs/changes.rst}  |   4 +
 Documentation/admin-guide/cifs/index.rst      |  21 +
 .../cifs/introduction.rst}                    |   8 +
 .../cifs/TODO => admin-guide/cifs/todo.rst}   |  87 +--
 .../README => admin-guide/cifs/usage.rst}     | 560 +++++++++++-------
 .../cifs/winucase_convert.pl                  |   0
 Documentation/admin-guide/index.rst           |   1 +
 MAINTAINERS                                   |   2 +-
 9 files changed, 460 insertions(+), 287 deletions(-)
 rename Documentation/{filesystems/cifs/AUTHORS => admin-guide/cifs/authors.rst} (60%)
 rename Documentation/{filesystems/cifs/CHANGES => admin-guide/cifs/changes.rst} (91%)
 create mode 100644 Documentation/admin-guide/cifs/index.rst
 rename Documentation/{filesystems/cifs/cifs.txt => admin-guide/cifs/introduction.rst} (98%)
 rename Documentation/{filesystems/cifs/TODO => admin-guide/cifs/todo.rst} (58%)
 rename Documentation/{filesystems/cifs/README => admin-guide/cifs/usage.rst} (72%)
 rename Documentation/{filesystems => admin-guide}/cifs/winucase_convert.pl (100%)

diff --git a/Documentation/filesystems/cifs/AUTHORS b/Documentation/admin-guide/cifs/authors.rst
similarity index 60%
rename from Documentation/filesystems/cifs/AUTHORS
rename to Documentation/admin-guide/cifs/authors.rst
index 75865da2ce14..b02d6dd6c070 100644
--- a/Documentation/filesystems/cifs/AUTHORS
+++ b/Documentation/admin-guide/cifs/authors.rst
@@ -1,5 +1,10 @@
+=======
+Authors
+=======
+
 Original Author
-===============
+---------------
+
 Steve French (sfrench@samba.org)
 
 The author wishes to express his appreciation and thanks to:
@@ -12,7 +17,7 @@ side of the original CIFS Unix extensions and reviewing and implementing
 portions of the newer CIFS POSIX extensions into the Samba 3 file server. Thank
 Dave Boutcher of IBM Rochester (author of the OS/400 smb/cifs filesystem client)
 for proving years ago that very good smb/cifs clients could be done on Unix-like
-operating systems.  Volker Lendecke, Andrew Tridgell, Urban Widmark, John 
+operating systems.  Volker Lendecke, Andrew Tridgell, Urban Widmark, John
 Newbigin and others for their work on the Linux smbfs module.  Thanks to
 the other members of the Storage Network Industry Association CIFS Technical
 Workgroup for their work specifying this highly complex protocol and finally
@@ -20,33 +25,34 @@ thanks to the Samba team for their technical advice and encouragement.
 
 Patch Contributors
 ------------------
-Zwane Mwaikambo
-Andi Kleen
-Amrut Joshi
-Shobhit Dayal
-Sergey Vlasov
-Richard Hughes
-Yury Umanets
-Mark Hamzy (for some of the early cifs IPv6 work)
-Domen Puncer
-Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
-Vince Negri and Dave Stahl (for finding an important caching bug)
-Adrian Bunk (kcalloc cleanups)
-Miklos Szeredi 
-Kazeon team for various fixes especially for 2.4 version.
-Asser Ferno (Change Notify support)
-Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
-Gunter Kukkukk (testing and suggestions for support of old servers)
-Igor Mammedov (DFS support)
-Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
-Scott Lovenberg
-Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
-Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
-Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
-Shirish Pargaonkar (for many ACL patches over the years)
-Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
-Paulo Alcantara
-Long Li (some great work on RDMA, SMB Direct)
+
+- Zwane Mwaikambo
+- Andi Kleen
+- Amrut Joshi
+- Shobhit Dayal
+- Sergey Vlasov
+- Richard Hughes
+- Yury Umanets
+- Mark Hamzy (for some of the early cifs IPv6 work)
+- Domen Puncer
+- Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
+- Vince Negri and Dave Stahl (for finding an important caching bug)
+- Adrian Bunk (kcalloc cleanups)
+- Miklos Szeredi
+- Kazeon team for various fixes especially for 2.4 version.
+- Asser Ferno (Change Notify support)
+- Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
+- Gunter Kukkukk (testing and suggestions for support of old servers)
+- Igor Mammedov (DFS support)
+- Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
+- Scott Lovenberg
+- Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
+- Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
+- Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
+- Shirish Pargaonkar (for many ACL patches over the years)
+- Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
+- Paulo Alcantara
+- Long Li (some great work on RDMA, SMB Direct)
 
 
 Test case and Bug Report contributors
diff --git a/Documentation/filesystems/cifs/CHANGES b/Documentation/admin-guide/cifs/changes.rst
similarity index 91%
rename from Documentation/filesystems/cifs/CHANGES
rename to Documentation/admin-guide/cifs/changes.rst
index 1df7f4910eb2..71f2ecb62299 100644
--- a/Documentation/filesystems/cifs/CHANGES
+++ b/Documentation/admin-guide/cifs/changes.rst
@@ -1,3 +1,7 @@
+=======
+Changes
+=======
+
 See https://wiki.samba.org/index.php/LinuxCIFSKernel for summary
 information (that may be easier to read than parsing the output of
 "git log fs/cifs") about fixes/improvements to CIFS/SMB2/SMB3 support (changes
diff --git a/Documentation/admin-guide/cifs/index.rst b/Documentation/admin-guide/cifs/index.rst
new file mode 100644
index 000000000000..fad5268635f5
--- /dev/null
+++ b/Documentation/admin-guide/cifs/index.rst
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+CIFS
+====
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   usage
+   todo
+   changes
+   authors
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/filesystems/cifs/cifs.txt b/Documentation/admin-guide/cifs/introduction.rst
similarity index 98%
rename from Documentation/filesystems/cifs/cifs.txt
rename to Documentation/admin-guide/cifs/introduction.rst
index 1be3d21c286e..0b98f672d36f 100644
--- a/Documentation/filesystems/cifs/cifs.txt
+++ b/Documentation/admin-guide/cifs/introduction.rst
@@ -1,3 +1,7 @@
+============
+Introduction
+============
+
   This is the client VFS module for the SMB3 NAS protocol as well
   as for older dialects such as the Common Internet File System (CIFS)
   protocol which was the successor to the Server Message Block
@@ -33,7 +37,9 @@
   tools (including smbinfo and setcifsacl) that can be obtained from
 
       https://git.samba.org/?p=cifs-utils.git
+
   or
+
       git://git.samba.org/cifs-utils.git
 
   mount.cifs should be installed in the directory with the other mount helpers.
@@ -41,5 +47,7 @@
   For more information on the module see the project wiki page at
 
       https://wiki.samba.org/index.php/LinuxCIFS
+
   and
+
       https://wiki.samba.org/index.php/LinuxCIFS_utils
diff --git a/Documentation/filesystems/cifs/TODO b/Documentation/admin-guide/cifs/todo.rst
similarity index 58%
rename from Documentation/filesystems/cifs/TODO
rename to Documentation/admin-guide/cifs/todo.rst
index 9267f3fb131f..95f18e8c9b8a 100644
--- a/Documentation/filesystems/cifs/TODO
+++ b/Documentation/admin-guide/cifs/todo.rst
@@ -1,3 +1,7 @@
+====
+TODO
+====
+
 Version 2.14 December 21, 2018
 
 A Partial List of Missing Features
@@ -8,6 +12,7 @@ for visible, important contributions to this module.  Here
 is a partial list of the known problems and missing features:
 
 a) SMB3 (and SMB3.1.1) missing optional features:
+
    - multichannel (started), integration with RDMA
    - directory leases (improved metadata caching), started (root dir only)
    - T10 copy offload ie "ODX" (copy chunk, and "Duplicate Extents" ioctl
@@ -16,45 +21,46 @@ a) SMB3 (and SMB3.1.1) missing optional features:
 b) improved sparse file support
 
 c) Directory entry caching relies on a 1 second timer, rather than
-using Directory Leases, currently only the root file handle is cached longer
+   using Directory Leases, currently only the root file handle is cached longer
 
 d) quota support (needs minor kernel change since quota calls
-to make it to network filesystems or deviceless filesystems)
+   to make it to network filesystems or deviceless filesystems)
 
 e) Additional use cases where we use "compoounding" (e.g. open/query/close
-and open/setinfo/close) to reduce the number of roundtrips, and also
-open to reduce redundant opens (using deferred close and reference counts more).
+   and open/setinfo/close) to reduce the number of roundtrips, and also
+   open to reduce redundant opens (using deferred close and reference counts
+   more).
 
 f) Finish inotify support so kde and gnome file list windows
-will autorefresh (partially complete by Asser). Needs minor kernel
-vfs change to support removing D_NOTIFY on a file.   
+   will autorefresh (partially complete by Asser). Needs minor kernel
+   vfs change to support removing D_NOTIFY on a file.
 
 g) Add GUI tool to configure /proc/fs/cifs settings and for display of
-the CIFS statistics (started)
+   the CIFS statistics (started)
 
 h) implement support for security and trusted categories of xattrs
-(requires minor protocol extension) to enable better support for SELINUX
+   (requires minor protocol extension) to enable better support for SELINUX
 
 i) Add support for tree connect contexts (see MS-SMB2) a new SMB3.1.1 protocol
    feature (may be especially useful for virtualization).
 
 j) Create UID mapping facility so server UIDs can be mapped on a per
-mount or a per server basis to client UIDs or nobody if no mapping
-exists. Also better integration with winbind for resolving SID owners
+   mount or a per server basis to client UIDs or nobody if no mapping
+   exists. Also better integration with winbind for resolving SID owners
 
 k) Add tools to take advantage of more smb3 specific ioctls and features
-(passthrough ioctl/fsctl for sending various SMB3 fsctls to the server
-is in progress, and a passthrough query_info call is already implemented
-in cifs.ko to allow smb3 info levels queries to be sent from userspace)
+   (passthrough ioctl/fsctl for sending various SMB3 fsctls to the server
+   is in progress, and a passthrough query_info call is already implemented
+   in cifs.ko to allow smb3 info levels queries to be sent from userspace)
 
 l) encrypted file support
 
 m) improved stats gathering tools (perhaps integration with nfsometer?)
-to extend and make easier to use what is currently in /proc/fs/cifs/Stats
+   to extend and make easier to use what is currently in /proc/fs/cifs/Stats
 
-n) allow setting more NTFS/SMB3 file attributes remotely (currently limited to compressed
-file attribute via chflags) and improve user space tools for managing and
-viewing them.
+n) allow setting more NTFS/SMB3 file attributes remotely (currently limited to
+   compressed file attribute via chflags) and improve user space tools for
+   managing and viewing them.
 
 o) mount helper GUI (to simplify the various configuration options on mount)
 
@@ -65,55 +71,56 @@ p) Add support for witness protocol (perhaps ioctl to cifs.ko from user space
    different servers, and the server we are connected to has gone down.
 
 q) Allow mount.cifs to be more verbose in reporting errors with dialect
-or unsupported feature errors.
+   or unsupported feature errors.
 
 r) updating cifs documentation, and user guide.
 
 s) Addressing bugs found by running a broader set of xfstests in standard
-file system xfstest suite.
+   file system xfstest suite.
 
 t) split cifs and smb3 support into separate modules so legacy (and less
-secure) CIFS dialect can be disabled in environments that don't need it
-and simplify the code.
+   secure) CIFS dialect can be disabled in environments that don't need it
+   and simplify the code.
 
 v) POSIX Extensions for SMB3.1.1 (started, create and mkdir support added
-so far).
+   so far).
 
 w) Add support for additional strong encryption types, and additional spnego
-authentication mechanisms (see MS-SMB2)
+   authentication mechanisms (see MS-SMB2)
+
+Known Bugs
+==========
 
-KNOWN BUGS
-====================================
 See http://bugzilla.samba.org - search on product "CifsVFS" for
 current bug list.  Also check http://bugzilla.kernel.org (Product = File System, Component = CIFS)
 
 1) existing symbolic links (Windows reparse points) are recognized but
-can not be created remotely. They are implemented for Samba and those that
-support the CIFS Unix extensions, although earlier versions of Samba
-overly restrict the pathnames.
+   can not be created remotely. They are implemented for Samba and those that
+   support the CIFS Unix extensions, although earlier versions of Samba
+   overly restrict the pathnames.
 2) follow_link and readdir code does not follow dfs junctions
-but recognizes them
+   but recognizes them
 
 Misc testing to do
 ==================
 1) check out max path names and max path name components against various server
-types. Try nested symlinks (8 deep). Return max path name in stat -f information
+   types. Try nested symlinks (8 deep). Return max path name in stat -f information
 
 2) Improve xfstest's cifs/smb3 enablement and adapt xfstests where needed to test
-cifs/smb3 better
+   cifs/smb3 better
 
-3) Additional performance testing and optimization using iozone and similar - 
-there are some easy changes that can be done to parallelize sequential writes,
-and when signing is disabled to request larger read sizes (larger than 
-negotiated size) and send larger write sizes to modern servers.
+3) Additional performance testing and optimization using iozone and similar -
+   there are some easy changes that can be done to parallelize sequential writes,
+   and when signing is disabled to request larger read sizes (larger than
+   negotiated size) and send larger write sizes to modern servers.
 
 4) More exhaustively test against less common servers
 
 5) Continue to extend the smb3 "buildbot" which does automated xfstesting
-against Windows, Samba and Azure currently - to add additional tests and
-to allow the buildbot to execute the tests faster. The URL for the
-buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com
+   against Windows, Samba and Azure currently - to add additional tests and
+   to allow the buildbot to execute the tests faster. The URL for the
+   buildbot is: http://smb3-test-rhel-75.southcentralus.cloudapp.azure.com
 
 6) Address various coverity warnings (most are not bugs per-se, but
-the more warnings are addressed, the easier it is to spot real
-problems that static analyzers will point out in the future).
+   the more warnings are addressed, the easier it is to spot real
+   problems that static analyzers will point out in the future).
diff --git a/Documentation/filesystems/cifs/README b/Documentation/admin-guide/cifs/usage.rst
similarity index 72%
rename from Documentation/filesystems/cifs/README
rename to Documentation/admin-guide/cifs/usage.rst
index 4a804619cff2..d3fb67b8a976 100644
--- a/Documentation/filesystems/cifs/README
+++ b/Documentation/admin-guide/cifs/usage.rst
@@ -1,53 +1,61 @@
+=====
+Usage
+=====
+
 This module supports the SMB3 family of advanced network protocols (as well
 as older dialects, originally called "CIFS" or SMB1).
 
 The CIFS VFS module for Linux supports many advanced network filesystem
 features such as hierarchical DFS like namespace, hardlinks, locking and more.
-It was designed to comply with the SNIA CIFS Technical Reference (which 
-supersedes the 1992 X/Open SMB Standard) as well as to perform best practice 
-practical interoperability with Windows 2000, Windows XP, Samba and equivalent 
+It was designed to comply with the SNIA CIFS Technical Reference (which
+supersedes the 1992 X/Open SMB Standard) as well as to perform best practice
+practical interoperability with Windows 2000, Windows XP, Samba and equivalent
 servers.  This code was developed in participation with the Protocol Freedom
 Information Foundation.  CIFS and now SMB3 has now become a defacto
 standard for interoperating between Macs and Windows and major NAS appliances.
 
 Please see
-  MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification)
-  http://protocolfreedom.org/ and
-  http://samba.org/samba/PFIF/
+MS-SMB2 (for detailed SMB2/SMB3/SMB3.1.1 protocol specification)
+http://protocolfreedom.org/ and
+http://samba.org/samba/PFIF/
 for more details.
 
 
 For questions or bug reports please contact:
+
     smfrench@gmail.com
 
 See the project page at: https://wiki.samba.org/index.php/LinuxCIFS_utils
 
-Build instructions:
+Build instructions
 ==================
+
 For Linux:
+
 1) Download the kernel (e.g. from http://www.kernel.org)
-and change directory into the top of the kernel directory tree
-(e.g. /usr/src/linux-2.5.73)
+   and change directory into the top of the kernel directory tree
+   (e.g. /usr/src/linux-2.5.73)
 2) make menuconfig (or make xconfig)
 3) select cifs from within the network filesystem choices
 4) save and exit
 5) make
 
 
-Installation instructions:
+Installation instructions
 =========================
+
 If you have built the CIFS vfs as module (successfully) simply
-type "make modules_install" (or if you prefer, manually copy the file to
+type ``make modules_install`` (or if you prefer, manually copy the file to
 the modules directory e.g. /lib/modules/2.4.10-4GB/kernel/fs/cifs/cifs.ko).
 
 If you have built the CIFS vfs into the kernel itself, follow the instructions
 for your distribution on how to install a new kernel (usually you
-would simply type "make install").
+would simply type ``make install``).
 
 If you do not have the utility mount.cifs (in the Samba 4.x source tree and on
 the CIFS VFS web site) copy it to the same directory in which mount helpers
 reside (usually /sbin).  Although the helper software is not
-required, mount.cifs is recommended.  Most distros include a "cifs-utils"
+required, mount.cifs is recommended.  Most distros include a ``cifs-utils``
 package that includes this utility so it is recommended to install this.
 
 Note that running the Winbind pam/nss module (logon service) on all of your
@@ -57,13 +65,16 @@ found at cifs-utils.git on git.samba.org
 
 If cifs is built as a module, then the size and number of network buffers
 and maximum number of simultaneous requests to one server can be configured.
-Changing these from their defaults is not recommended. By executing modinfo
+Changing these from their defaults is not recommended. By executing modinfo::
+
 	modinfo kernel/fs/cifs/cifs.ko
+
 on kernel/fs/cifs/cifs.ko the list of configuration changes that can be made
 at module initialization time (by running insmod cifs.ko) can be seen.
 
 Recommendations
 ===============
+
 To improve security the SMB2.1 dialect or later (usually will get SMB3) is now
 the new default. To use old dialects (e.g. to mount Windows XP) use "vers=1.0"
 on mount (or vers=2.0 for Windows Vista).  Note that the CIFS (vers=1.0) is
@@ -72,156 +83,168 @@ many advanced security features such as downgrade attack detection
 and encrypted shares and stronger signing and authentication algorithms.
 There are additional mount options that may be helpful for SMB3 to get
 improved POSIX behavior (NB: can use vers=3.0 to force only SMB3, never 2.1):
-     "mfsymlinks" and "cifsacl" and "idsfromsid"
+
+     ``mfsymlinks`` and ``cifsacl`` and ``idsfromsid``
 
 Allowing User Mounts
 ====================
+
 To permit users to mount and unmount over directories they own is possible
 with the cifs vfs.  A way to enable such mounting is to mark the mount.cifs
-utility as suid (e.g. "chmod +s /sbin/mount.cifs). To enable users to 
+utility as suid (e.g. ``chmod +s /sbin/mount.cifs``). To enable users to
 umount shares they mount requires
+
 1) mount.cifs version 1.4 or later
 2) an entry for the share in /etc/fstab indicating that a user may
-unmount it e.g.
-//server/usersharename  /mnt/username cifs user 0 0
+   unmount it e.g.::
 
-Note that when the mount.cifs utility is run suid (allowing user mounts), 
-in order to reduce risks, the "nosuid" mount flag is passed in on mount to
+     //server/usersharename  /mnt/username cifs user 0 0
+
+Note that when the mount.cifs utility is run suid (allowing user mounts),
+in order to reduce risks, the ``nosuid`` mount flag is passed in on mount to
 disallow execution of an suid program mounted on the remote target.
 When mount is executed as root, nosuid is not passed in by default,
 and execution of suid programs on the remote target would be enabled
-by default. This can be changed, as with nfs and other filesystems, 
-by simply specifying "nosuid" among the mount options. For user mounts 
-though to be able to pass the suid flag to mount requires rebuilding 
+by default. This can be changed, as with nfs and other filesystems,
+by simply specifying ``nosuid`` among the mount options. For user mounts
+though to be able to pass the suid flag to mount requires rebuilding
 mount.cifs with the following flag: CIFS_ALLOW_USR_SUID
 
 There is a corresponding manual page for cifs mounting in the Samba 3.0 and
-later source tree in docs/manpages/mount.cifs.8 
+later source tree in docs/manpages/mount.cifs.8
 
 Allowing User Unmounts
 ======================
+
 To permit users to ummount directories that they have user mounted (see above),
-the utility umount.cifs may be used.  It may be invoked directly, or if 
+the utility umount.cifs may be used.  It may be invoked directly, or if
 umount.cifs is placed in /sbin, umount can invoke the cifs umount helper
 (at least for most versions of the umount utility) for umount of cifs
 mounts, unless umount is invoked with -i (which will avoid invoking a umount
 helper). As with mount.cifs, to enable user unmounts umount.cifs must be marked
-as suid (e.g. "chmod +s /sbin/umount.cifs") or equivalent (some distributions
+as suid (e.g. ``chmod +s /sbin/umount.cifs``) or equivalent (some distributions
 allow adding entries to a file to the /etc/permissions file to achieve the
 equivalent suid effect).  For this utility to succeed the target path
 must be a cifs mount, and the uid of the current user must match the uid
 of the user who mounted the resource.
 
-Also note that the customary way of allowing user mounts and unmounts is 
+Also note that the customary way of allowing user mounts and unmounts is
 (instead of using mount.cifs and unmount.cifs as suid) to add a line
 to the file /etc/fstab for each //server/share you wish to mount, but
 this can become unwieldy when potential mount targets include many
 or  unpredictable UNC names.
 
-Samba Considerations 
+Samba Considerations
 ====================
+
 Most current servers support SMB2.1 and SMB3 which are more secure,
 but there are useful protocol extensions for the older less secure CIFS
 dialect, so to get the maximum benefit if mounting using the older dialect
 (CIFS/SMB1), we recommend using a server that supports the SNIA CIFS
 Unix Extensions standard (e.g. almost any  version of Samba ie version
 2.2.5 or later) but the CIFS vfs works fine with a wide variety of CIFS servers.
-Note that uid, gid and file permissions will display default values if you do 
-not have a server that supports the Unix extensions for CIFS (such as Samba 
-2.2.5 or later).  To enable the Unix CIFS Extensions in the Samba server, add 
-the line: 
+Note that uid, gid and file permissions will display default values if you do
+not have a server that supports the Unix extensions for CIFS (such as Samba
+2.2.5 or later).  To enable the Unix CIFS Extensions in the Samba server, add
+the line::
 
 	unix extensions = yes
-	
-to your smb.conf file on the server.  Note that the following smb.conf settings 
-are also useful (on the Samba server) when the majority of clients are Unix or 
-Linux: 
+
+to your smb.conf file on the server.  Note that the following smb.conf settings
+are also useful (on the Samba server) when the majority of clients are Unix or
+Linux::
 
 	case sensitive = yes
-	delete readonly = yes 
+	delete readonly = yes
 	ea support = yes
 
 Note that server ea support is required for supporting xattrs from the Linux
-cifs client, and that EA support is present in later versions of Samba (e.g. 
+cifs client, and that EA support is present in later versions of Samba (e.g.
 3.0.6 and later (also EA support works in all versions of Windows, at least to
 shares on NTFS filesystems).  Extended Attribute (xattr) support is an optional
 feature of most Linux filesystems which may require enabling via
 make menuconfig. Client support for extended attributes (user xattr) can be
-disabled on a per-mount basis by specifying "nouser_xattr" on mount.
+disabled on a per-mount basis by specifying ``nouser_xattr`` on mount.
 
 The CIFS client can get and set POSIX ACLs (getfacl, setfacl) to Samba servers
-version 3.10 and later.  Setting POSIX ACLs requires enabling both XATTR and 
+version 3.10 and later.  Setting POSIX ACLs requires enabling both XATTR and
 then POSIX support in the CIFS configuration options when building the cifs
 module.  POSIX ACL support can be disabled on a per mount basic by specifying
-"noacl" on mount.
- 
-Some administrators may want to change Samba's smb.conf "map archive" and 
-"create mask" parameters from the default.  Unless the create mask is changed
+``noacl`` on mount.
+
+Some administrators may want to change Samba's smb.conf ``map archive`` and
+``create mask`` parameters from the default.  Unless the create mask is changed
 newly created files can end up with an unnecessarily restrictive default mode,
 which may not be what you want, although if the CIFS Unix extensions are
 enabled on the server and client, subsequent setattr calls (e.g. chmod) can
-fix the mode.  Note that creating special devices (mknod) remotely 
-may require specifying a mkdev function to Samba if you are not using 
+fix the mode.  Note that creating special devices (mknod) remotely
+may require specifying a mkdev function to Samba if you are not using
 Samba 3.0.6 or later.  For more information on these see the manual pages
-("man smb.conf") on the Samba server system.  Note that the cifs vfs,
-unlike the smbfs vfs, does not read the smb.conf on the client system 
-(the few optional settings are passed in on mount via -o parameters instead).  
+(``man smb.conf``) on the Samba server system.  Note that the cifs vfs,
+unlike the smbfs vfs, does not read the smb.conf on the client system
+(the few optional settings are passed in on mount via -o parameters instead).
 Note that Samba 2.2.7 or later includes a fix that allows the CIFS VFS to delete
-open files (required for strict POSIX compliance).  Windows Servers already 
+open files (required for strict POSIX compliance).  Windows Servers already
 supported this feature. Samba server does not allow symlinks that refer to files
 outside of the share, so in Samba versions prior to 3.0.6, most symlinks to
-files with absolute paths (ie beginning with slash) such as:
+files with absolute paths (ie beginning with slash) such as::
+
 	 ln -s /mnt/foo bar
-would be forbidden. Samba 3.0.6 server or later includes the ability to create 
-such symlinks safely by converting unsafe symlinks (ie symlinks to server 
+
+would be forbidden. Samba 3.0.6 server or later includes the ability to create
+such symlinks safely by converting unsafe symlinks (ie symlinks to server
 files that are outside of the share) to a samba specific format on the server
 that is ignored by local server applications and non-cifs clients and that will
 not be traversed by the Samba server).  This is opaque to the Linux client
 application using the cifs vfs. Absolute symlinks will work to Samba 3.0.5 or
 later, but only for remote clients using the CIFS Unix extensions, and will
 be invisbile to Windows clients and typically will not affect local
-applications running on the same server as Samba.  
+applications running on the same server as Samba.
 
-Use instructions:
+Use instructions
 ================
-Once the CIFS VFS support is built into the kernel or installed as a module 
+
+Once the CIFS VFS support is built into the kernel or installed as a module
 (cifs.ko), you can use mount syntax like the following to access Samba or
-Mac or Windows servers:
+Mac or Windows servers::
 
   mount -t cifs //9.53.216.11/e$ /mnt -o username=myname,password=mypassword
 
 Before -o the option -v may be specified to make the mount.cifs
-mount helper display the mount steps more verbosely.  
+mount helper display the mount steps more verbosely.
 After -o the following commonly used cifs vfs specific options
-are supported:
+are supported::
 
   username=<username>
   password=<password>
   domain=<domain name>
-  
+
 Other cifs mount options are described below.  Use of TCP names (in addition to
 ip addresses) is available if the mount helper (mount.cifs) is installed. If
 you do not trust the server to which are mounted, or if you do not have
 cifs signing enabled (and the physical network is insecure), consider use
-of the standard mount options "noexec" and "nosuid" to reduce the risk of 
+of the standard mount options ``noexec`` and ``nosuid`` to reduce the risk of
 running an altered binary on your local system (downloaded from a hostile server
 or altered by a hostile router).
 
 Although mounting using format corresponding to the CIFS URL specification is
 not possible in mount.cifs yet, it is possible to use an alternate format
 for the server and sharename (which is somewhat similar to NFS style mount
-syntax) instead of the more widely used UNC format (i.e. \\server\share):
+syntax) instead of the more widely used UNC format (i.e. \\server\share)::
+
   mount -t cifs tcp_name_of_server:share_name /mnt -o user=myname,pass=mypasswd
 
 When using the mount helper mount.cifs, passwords may be specified via alternate
-mechanisms, instead of specifying it after -o using the normal "pass=" syntax
+mechanisms, instead of specifying it after -o using the normal ``pass=`` syntax
 on the command line:
 1) By including it in a credential file. Specify credentials=filename as one
-of the mount options. Credential files contain two lines
-        username=someuser
-        password=your_password
+of the mount options. Credential files contain two lines::
+
+	username=someuser
+	password=your_password
+
 2) By specifying the password in the PASSWD environment variable (similarly
-the user name can be taken from the USER environment variable).
+   the user name can be taken from the USER environment variable).
 3) By specifying the password in a file by name via PASSWD_FILE
 4) By specifying the password in a file by file descriptor via PASSWD_FD
 
@@ -229,39 +252,47 @@ If no password is provided, mount.cifs will prompt for password entry
 
 Restrictions
 ============
-Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC 
-1001/1002 support for "Netbios-Over-TCP/IP." This is not likely to be a 
+
+Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC
+1001/1002 support for "Netbios-Over-TCP/IP." This is not likely to be a
 problem as most servers support this.
 
 Valid filenames differ between Windows and Linux.  Windows typically restricts
-filenames which contain certain reserved characters (e.g.the character : 
+filenames which contain certain reserved characters (e.g.the character :
 which is used to delimit the beginning of a stream name by Windows), while
 Linux allows a slightly wider set of valid characters in filenames. Windows
 servers can remap such characters when an explicit mapping is specified in
-the Server's registry.  Samba starting with version 3.10 will allow such 
+the Server's registry.  Samba starting with version 3.10 will allow such
 filenames (ie those which contain valid Linux characters, which normally
 would be forbidden for Windows/CIFS semantics) as long as the server is
 configured for Unix Extensions (and the client has not disabled
 /proc/fs/cifs/LinuxExtensionsEnabled). In addition the mount option
-"mapposix" can be used on CIFS (vers=1.0) to force the mapping of
+``mapposix`` can be used on CIFS (vers=1.0) to force the mapping of
 illegal Windows/NTFS/SMB characters to a remap range (this mount parm
-is the default for SMB3). This remap ("mapposix") range is also
+is the default for SMB3). This remap (``mapposix``) range is also
 compatible with Mac (and "Services for Mac" on some older Windows).
 
 CIFS VFS Mount Options
 ======================
 A partial list of the supported mount options follows:
-  username	The user name to use when trying to establish
+
+  username
+		The user name to use when trying to establish
 		the CIFS session.
-  password	The user password.  If the mount helper is
+  password
+		The user password.  If the mount helper is
 		installed, the user will be prompted for password
 		if not supplied.
-  ip		The ip address of the target server
-  unc		The target server Universal Network Name (export) to 
-		mount.	
-  domain	Set the SMB/CIFS workgroup name prepended to the
+  ip
+		The ip address of the target server
+  unc
+		The target server Universal Network Name (export) to
+		mount.
+  domain
+		Set the SMB/CIFS workgroup name prepended to the
 		username during CIFS session establishment
-  forceuid	Set the default uid for inodes to the uid
+  forceuid
+		Set the default uid for inodes to the uid
 		passed in on mount. For mounts to servers
 		which do support the CIFS Unix extensions, such as a
 		properly configured Samba server, the server provides
@@ -276,32 +307,39 @@ A partial list of the supported mount options follows:
 		extensions, the default uid (and gid) returned on lookup
 		of existing files will be the uid (gid) of the person
 		who executed the mount (root, except when mount.cifs
-		is configured setuid for user mounts) unless the "uid=" 
+		is configured setuid for user mounts) unless the ``uid=``
 		(gid) mount option is specified. Also note that permission
 		checks (authorization checks) on accesses to a file occur
 		at the server, but there are cases in which an administrator
 		may want to restrict at the client as well.  For those
 		servers which do not report a uid/gid owner
 		(such as Windows), permissions can also be checked at the
-		client, and a crude form of client side permission checking 
-		can be enabled by specifying file_mode and dir_mode on 
+		client, and a crude form of client side permission checking
+		can be enabled by specifying file_mode and dir_mode on
 		the client.  (default)
-  forcegid	(similar to above but for the groupid instead of uid) (default)
-  noforceuid	Fill in file owner information (uid) by requesting it from
+  forcegid
+		(similar to above but for the groupid instead of uid) (default)
+  noforceuid
+		Fill in file owner information (uid) by requesting it from
 		the server if possible. With this option, the value given in
 		the uid= option (on mount) will only be used if the server
 		can not support returning uids on inodes.
-  noforcegid	(similar to above but for the group owner, gid, instead of uid)
-  uid		Set the default uid for inodes, and indicate to the
+  noforcegid
+		(similar to above but for the group owner, gid, instead of uid)
+  uid
+		Set the default uid for inodes, and indicate to the
 		cifs kernel driver which local user mounted. If the server
 		supports the unix extensions the default uid is
 		not used to fill in the owner fields of inodes (files)
-		unless the "forceuid" parameter is specified.
-  gid		Set the default gid for inodes (similar to above).
-  file_mode     If CIFS Unix extensions are not supported by the server
+		unless the ``forceuid`` parameter is specified.
+  gid
+		Set the default gid for inodes (similar to above).
+  file_mode
+		If CIFS Unix extensions are not supported by the server
 		this overrides the default mode for file inodes.
-  fsc		Enable local disk caching using FS-Cache (off by default). This
-  		option could be useful to improve performance on a slow link,
+  fsc
+		Enable local disk caching using FS-Cache (off by default). This
+		option could be useful to improve performance on a slow link,
 		heavily loaded server and/or network where reading from the
 		disk is faster than reading from the server (over the network).
 		This could also impact scalability positively as the
@@ -310,18 +348,22 @@ A partial list of the supported mount options follows:
 		type workloads. So, you need to consider carefully your
 		workload/scenario before using this option. Currently, local
 		disk caching is functional for CIFS files opened as read-only.
-  dir_mode      If CIFS Unix extensions are not supported by the server 
+  dir_mode
+		If CIFS Unix extensions are not supported by the server
 		this overrides the default mode for directory inodes.
-  port		attempt to contact the server on this tcp port, before
+  port
+		attempt to contact the server on this tcp port, before
 		trying the usual ports (port 445, then 139).
-  iocharset     Codepage used to convert local path names to and from
+  iocharset
+		Codepage used to convert local path names to and from
 		Unicode. Unicode is used by default for network path
 		names if the server supports it.  If iocharset is
 		not specified then the nls_default specified
 		during the local client kernel build will be used.
 		If server does not support Unicode, this parameter is
 		unused.
-  rsize		default read size (usually 16K). The client currently
+  rsize
+		default read size (usually 16K). The client currently
 		can not use rsize larger than CIFSMaxBufSize. CIFSMaxBufSize
 		defaults to 16K and may be changed (from 8K to the maximum
 		kmalloc size allowed by your kernel) at module install time
@@ -333,10 +375,12 @@ A partial list of the supported mount options follows:
 		newer servers (e.g. Samba 3.0.26 or later) do. rsize can be
 		set from a minimum of 2048 to a maximum of 130048 (127K or
 		CIFSMaxBufSize, whichever is smaller)
-  wsize		default write size (default 57344)
+  wsize
+		default write size (default 57344)
 		maximum wsize currently allowed by CIFS is 57344 (fourteen
 		4096 byte pages)
-  actimeo=n	attribute cache timeout in seconds (default 1 second).
+  actimeo=n
+		attribute cache timeout in seconds (default 1 second).
 		After this timeout, the cifs client requests fresh attribute
 		information from the server. This option allows to tune the
 		attribute cache timeout to suit the workload needs. Shorter
@@ -345,49 +389,67 @@ A partial list of the supported mount options follows:
 		of calls to the server at the expense of less stricter cache
 		coherency checks (i.e. incorrect attribute cache for a short
 		period of time).
-  rw		mount the network share read-write (note that the
+  rw
+		mount the network share read-write (note that the
 		server may still consider the share read-only)
-  ro		mount network share read-only
-  version	used to distinguish different versions of the
+  ro
+		mount network share read-only
+  version
+		used to distinguish different versions of the
 		mount helper utility (not typically needed)
-  sep		if first mount option (after the -o), overrides
+  sep
+		if first mount option (after the -o), overrides
 		the comma as the separator between the mount
-		parms. e.g.
+		parms. e.g.::
+
 			-o user=myname,password=mypassword,domain=mydom
-		could be passed instead with period as the separator by
+
+		could be passed instead with period as the separator by::
+
 			-o sep=.user=myname.password=mypassword.domain=mydom
+
 		this might be useful when comma is contained within username
 		or password or domain. This option is less important
 		when the cifs mount helper cifs.mount (version 1.1 or later)
 		is used.
-  nosuid        Do not allow remote executables with the suid bit 
+  nosuid
+		Do not allow remote executables with the suid bit
 		program to be executed.  This is only meaningful for mounts
 		to servers such as Samba which support the CIFS Unix Extensions.
 		If you do not trust the servers in your network (your mount
 		targets) it is recommended that you specify this option for
 		greater security.
-  exec		Permit execution of binaries on the mount.
-  noexec	Do not permit execution of binaries on the mount.
-  dev		Recognize block devices on the remote mount.
-  nodev		Do not recognize devices on the remote mount.
-  suid          Allow remote files on this mountpoint with suid enabled to 
+  exec
+		Permit execution of binaries on the mount.
+  noexec
+		Do not permit execution of binaries on the mount.
+  dev
+		Recognize block devices on the remote mount.
+  nodev
+		Do not recognize devices on the remote mount.
+  suid
+		Allow remote files on this mountpoint with suid enabled to
 		be executed (default for mounts when executed as root,
 		nosuid is default for user mounts).
-  credentials   Although ignored by the cifs kernel component, it is used by 
+  credentials
+		Although ignored by the cifs kernel component, it is used by
 		the mount helper, mount.cifs. When mount.cifs is installed it
-		opens and reads the credential file specified in order  
+		opens and reads the credential file specified in order
 		to obtain the userid and password arguments which are passed to
 		the cifs vfs.
-  guest         Although ignored by the kernel component, the mount.cifs
+  guest
+		Although ignored by the kernel component, the mount.cifs
 		mount helper will not prompt the user for a password
 		if guest is specified on the mount options.  If no
 		password is specified a null password will be used.
-  perm          Client does permission checks (vfs_permission check of uid
+  perm
+		Client does permission checks (vfs_permission check of uid
 		and gid of the file against the mode and desired operation),
 		Note that this is in addition to the normal ACL check on the
-		target machine done by the server software. 
+		target machine done by the server software.
 		Client permission checking is enabled by default.
-  noperm        Client does not do permission checks.  This can expose
+  noperm
+		Client does not do permission checks.  This can expose
 		files on this mount to access by other users on the local
 		client system. It is typically only needed when the server
 		supports the CIFS Unix Extensions but the UIDs/GIDs on the
@@ -399,7 +461,8 @@ A partial list of the supported mount options follows:
 		Note that this does not affect the normal ACL check on the
 		target machine done by the server software (of the server
 		ACL against the user name provided at mount time).
-  serverino	Use server's inode numbers instead of generating automatically
+  serverino
+		Use server's inode numbers instead of generating automatically
 		incrementing inode numbers on the client.  Although this will
 		make it easier to spot hardlinked files (as they will have
 		the same inode numbers) and inode numbers may be persistent,
@@ -412,14 +475,16 @@ A partial list of the supported mount options follows:
 		or the CIFS Unix Extensions equivalent and for those
 		this mount option will have no effect.  Exporting cifs mounts
 		under nfsd requires this mount option on the cifs mount.
-		This is now the default if server supports the 
+		This is now the default if server supports the
 		required network operation.
-  noserverino   Client generates inode numbers (rather than using the actual one
+  noserverino
+		Client generates inode numbers (rather than using the actual one
 		from the server). These inode numbers will vary after
 		unmount or reboot which can confuse some applications,
 		but not all server filesystems support unique inode
 		numbers.
-  setuids       If the CIFS Unix extensions are negotiated with the server
+  setuids
+		If the CIFS Unix extensions are negotiated with the server
 		the client will attempt to set the effective uid and gid of
 		the local process on newly created files, directories, and
 		devices (create, mkdir, mknod).  If the CIFS Unix Extensions
@@ -427,9 +492,10 @@ A partial list of the supported mount options follows:
 		instead of using the default uid and gid specified on
 		the mount, cache the new file's uid and gid locally which means
 		that the uid for the file can change when the inode is
-	        reloaded (or the user remounts the share).
-  nosetuids     The client will not attempt to set the uid and gid on
-		on newly created files, directories, and devices (create, 
+		reloaded (or the user remounts the share).
+  nosetuids
+		The client will not attempt to set the uid and gid on
+		on newly created files, directories, and devices (create,
 		mkdir, mknod) which will result in the server setting the
 		uid and gid to the default (usually the server uid of the
 		user who mounted the share).  Letting the server (rather than
@@ -437,38 +503,49 @@ A partial list of the supported mount options follows:
 		Unix Extensions are not negotiated then the uid and gid for
 		new files will appear to be the uid (gid) of the mounter or the
 		uid (gid) parameter specified on the mount.
-  netbiosname   When mounting to servers via port 139, specifies the RFC1001
-		source name to use to represent the client netbios machine 
+  netbiosname
+		When mounting to servers via port 139, specifies the RFC1001
+		source name to use to represent the client netbios machine
 		name when doing the RFC1001 netbios session initialize.
-  direct        Do not do inode data caching on files opened on this mount.
+  direct
+		Do not do inode data caching on files opened on this mount.
 		This precludes mmapping files on this mount. In some cases
 		with fast networks and little or no caching benefits on the
 		client (e.g. when the application is doing large sequential
-		reads bigger than page size without rereading the same data) 
+		reads bigger than page size without rereading the same data)
 		this can provide better performance than the default
-		behavior which caches reads (readahead) and writes 
-		(writebehind) through the local Linux client pagecache 
+		behavior which caches reads (readahead) and writes
+		(writebehind) through the local Linux client pagecache
 		if oplock (caching token) is granted and held. Note that
 		direct allows write operations larger than page size
 		to be sent to the server.
-  strictcache   Use for switching on strict cache mode. In this mode the
+  strictcache
+		Use for switching on strict cache mode. In this mode the
 		client read from the cache all the time it has Oplock Level II,
 		otherwise - read from the server. All written data are stored
 		in the cache, but if the client doesn't have Exclusive Oplock,
 		it writes the data to the server.
-  rwpidforward  Forward pid of a process who opened a file to any read or write
+  rwpidforward
+		Forward pid of a process who opened a file to any read or write
 		operation on that file. This prevent applications like WINE
 		from failing on read and write if we use mandatory brlock style.
-  acl   	Allow setfacl and getfacl to manage posix ACLs if server
+  acl
+		Allow setfacl and getfacl to manage posix ACLs if server
 		supports them.  (default)
-  noacl 	Do not allow setfacl and getfacl calls on this mount
-  user_xattr    Allow getting and setting user xattrs (those attributes whose
-		name begins with "user." or "os2.") as OS/2 EAs (extended
+  noacl
+		Do not allow setfacl and getfacl calls on this mount
+  user_xattr
+		Allow getting and setting user xattrs (those attributes whose
+		name begins with ``user.`` or ``os2.``) as OS/2 EAs (extended
 		attributes) to the server.  This allows support of the
 		setfattr and getfattr utilities. (default)
-  nouser_xattr  Do not allow getfattr/setfattr to get/set/list xattrs 
-  mapchars      Translate six of the seven reserved characters (not backslash)
+  nouser_xattr
+		Do not allow getfattr/setfattr to get/set/list xattrs
+  mapchars
+		Translate six of the seven reserved characters (not backslash)::
+
 			*?<>|:
+
 		to the remap range (above 0xF000), which also
 		allows the CIFS client to recognize files created with
 		such characters by Windows's POSIX emulation. This can
@@ -477,39 +554,47 @@ A partial list of the supported mount options follows:
 		whose names contain any of these seven characters).
 		This has no effect if the server does not support
 		Unicode on the wire.
- nomapchars     Do not translate any of these seven characters (default).
- nocase         Request case insensitive path name matching (case
+  nomapchars
+		Do not translate any of these seven characters (default).
+  nocase
+		Request case insensitive path name matching (case
 		sensitive is the default if the server supports it).
-		(mount option "ignorecase" is identical to "nocase")
- posixpaths     If CIFS Unix extensions are supported, attempt to
+		(mount option ``ignorecase`` is identical to ``nocase``)
+  posixpaths
+		If CIFS Unix extensions are supported, attempt to
 		negotiate posix path name support which allows certain
 		characters forbidden in typical CIFS filenames, without
 		requiring remapping. (default)
- noposixpaths   If CIFS Unix extensions are supported, do not request
+  noposixpaths
+		If CIFS Unix extensions are supported, do not request
 		posix path name support (this may cause servers to
 		reject creatingfile with certain reserved characters).
- nounix         Disable the CIFS Unix Extensions for this mount (tree
+  nounix
+		Disable the CIFS Unix Extensions for this mount (tree
 		connection). This is rarely needed, but it may be useful
 		in order to turn off multiple settings all at once (ie
 		posix acls, posix locks, posix paths, symlink support
 		and retrieving uids/gids/mode from the server) or to
 		work around a bug in server which implement the Unix
 		Extensions.
- nobrl          Do not send byte range lock requests to the server.
+  nobrl
+		Do not send byte range lock requests to the server.
 		This is necessary for certain applications that break
 		with cifs style mandatory byte range locks (and most
 		cifs servers do not yet support requesting advisory
 		byte range locks).
- forcemandatorylock Even if the server supports posix (advisory) byte range
+  forcemandatorylock
+		Even if the server supports posix (advisory) byte range
 		locking, send only mandatory lock requests.  For some
 		(presumably rare) applications, originally coded for
 		DOS/Windows, which require Windows style mandatory byte range
 		locking, they may be able to take advantage of this option,
 		forcing the cifs client to only send mandatory locks
 		even if the cifs server would support posix advisory locks.
-		"forcemand" is accepted as a shorter form of this mount
+		``forcemand`` is accepted as a shorter form of this mount
 		option.
- nostrictsync   If this mount option is set, when an application does an
+  nostrictsync
+		If this mount option is set, when an application does an
 		fsync call then the cifs client does not send an SMB Flush
 		to the server (to force the server to write all dirty data
 		for this file immediately to disk), although cifs still sends
@@ -522,41 +607,50 @@ A partial list of the supported mount options follows:
 		crash.  If this mount option is not set, by default cifs will
 		send an SMB flush request (and wait for a response) on every
 		fsync call.
- nodfs          Disable DFS (global name space support) even if the
+  nodfs
+		Disable DFS (global name space support) even if the
 		server claims to support it.  This can help work around
 		a problem with parsing of DFS paths with Samba server
 		versions 3.0.24 and 3.0.25.
- remount        remount the share (often used to change from ro to rw mounts
-	        or vice versa)
- cifsacl        Report mode bits (e.g. on stat) based on the Windows ACL for
-	        the file. (EXPERIMENTAL)
- servern        Specify the server 's netbios name (RFC1001 name) to use
-		when attempting to setup a session to the server. 
+  remount
+		remount the share (often used to change from ro to rw mounts
+		or vice versa)
+  cifsacl
+		Report mode bits (e.g. on stat) based on the Windows ACL for
+		the file. (EXPERIMENTAL)
+  servern
+		Specify the server 's netbios name (RFC1001 name) to use
+		when attempting to setup a session to the server.
 		This is needed for mounting to some older servers (such
 		as OS/2 or Windows 98 and Windows ME) since they do not
 		support a default server name.  A server name can be up
 		to 15 characters long and is usually uppercased.
- sfu            When the CIFS Unix Extensions are not negotiated, attempt to
+  sfu
+		When the CIFS Unix Extensions are not negotiated, attempt to
 		create device files and fifos in a format compatible with
 		Services for Unix (SFU).  In addition retrieve bits 10-12
 		of the mode via the SETFILEBITS extended attribute (as
 		SFU does).  In the future the bottom 9 bits of the
 		mode also will be emulated using queries of the security
 		descriptor (ACL).
- mfsymlinks     Enable support for Minshall+French symlinks
+  mfsymlinks
+		Enable support for Minshall+French symlinks
 		(see http://wiki.samba.org/index.php/UNIX_Extensions#Minshall.2BFrench_symlinks)
 		This option is ignored when specified together with the
 		'sfu' option. Minshall+French symlinks are used even if
 		the server supports the CIFS Unix Extensions.
- sign           Must use packet signing (helps avoid unwanted data modification
+  sign
+		Must use packet signing (helps avoid unwanted data modification
 		by intermediate systems in the route).  Note that signing
 		does not work with lanman or plaintext authentication.
- seal           Must seal (encrypt) all data on this mounted share before
+  seal
+		Must seal (encrypt) all data on this mounted share before
 		sending on the network.  Requires support for Unix Extensions.
 		Note that this differs from the sign mount option in that it
 		causes encryption of data sent over this mounted share but other
 		shares mounted to the same server are unaffected.
- locallease     This option is rarely needed. Fcntl F_SETLEASE is
+  locallease
+		This option is rarely needed. Fcntl F_SETLEASE is
 		used by some applications such as Samba and NFSv4 server to
 		check to see whether a file is cacheable.  CIFS has no way
 		to explicitly request a lease, but can check whether a file
@@ -569,51 +663,73 @@ A partial list of the supported mount options follows:
 		will allow the cifs client to check for leases (only) locally
 		for files which are not oplocked instead of denying leases
 		in that case. (EXPERIMENTAL)
- sec            Security mode.  Allowed values are:
-			none	attempt to connection as a null user (no name)
-			krb5    Use Kerberos version 5 authentication
-			krb5i   Use Kerberos authentication and packet signing
-			ntlm    Use NTLM password hashing (default)
-			ntlmi   Use NTLM password hashing with signing (if
+  sec
+		Security mode.  Allowed values are:
+
+			none
+				attempt to connection as a null user (no name)
+			krb5
+				Use Kerberos version 5 authentication
+			krb5i
+				Use Kerberos authentication and packet signing
+			ntlm
+				Use NTLM password hashing (default)
+			ntlmi
+				Use NTLM password hashing with signing (if
 				/proc/fs/cifs/PacketSigningEnabled on or if
-				server requires signing also can be the default) 
-			ntlmv2  Use NTLMv2 password hashing      
-			ntlmv2i Use NTLMv2 password hashing with packet signing
-			lanman  (if configured in kernel config) use older
+				server requires signing also can be the default)
+			ntlmv2
+				Use NTLMv2 password hashing
+			ntlmv2i
+				Use NTLMv2 password hashing with packet signing
+			lanman
+				(if configured in kernel config) use older
 				lanman hash
-hard		Retry file operations if server is not responding
-soft		Limit retries to unresponsive servers (usually only
+  hard
+		Retry file operations if server is not responding
+  soft
+		Limit retries to unresponsive servers (usually only
 		one retry) before returning an error.  (default)
 
 The mount.cifs mount helper also accepts a few mount options before -o
 including:
 
+=============== ===============================================================
 	-S      take password from stdin (equivalent to setting the environment
-		variable "PASSWD_FD=0"
+		variable ``PASSWD_FD=0``
 	-V      print mount.cifs version
 	-?      display simple usage information
+=============== ===============================================================
 
 With most 2.6 kernel versions of modutils, the version of the cifs kernel
 module can be displayed via modinfo.
 
 Misc /proc/fs/cifs Flags and Debug Info
 =======================================
+
 Informational pseudo-files:
+
+======================= =======================================================
 DebugData		Displays information about active CIFS sessions and
 			shares, features enabled as well as the cifs.ko
 			version.
 Stats			Lists summary resource usage information as well as per
 			share statistics.
+======================= =======================================================
 
 Configuration pseudo-files:
+
+======================= =======================================================
 SecurityFlags		Flags which control security negotiation and
 			also packet signing. Authentication (may/must)
 			flags (e.g. for NTLM and/or NTLMv2) may be combined with
 			the signing flags.  Specifying two different password
-			hashing mechanisms (as "must use") on the other hand 
-			does not make much sense. Default flags are 
-				0x07007 
-			(NTLM, NTLMv2 and packet signing allowed).  The maximum 
+			hashing mechanisms (as "must use") on the other hand
+			does not make much sense. Default flags are::
+
+				0x07007
+
+			(NTLM, NTLMv2 and packet signing allowed).  The maximum
 			allowable flags if you want to allow mounts to servers
 			using weaker password hashes is 0x37037 (lanman,
 			plaintext, ntlm, ntlmv2, signing allowed).  Some
@@ -626,21 +742,21 @@ SecurityFlags		Flags which control security negotiation and
 			laintext passwords using the older lanman dialect
 			form of the session setup SMB.  (e.g. for authentication
 			using plain text passwords, set the SecurityFlags
-			to 0x30030):
- 
-			may use packet signing 				0x00001
-			must use packet signing				0x01001
-			may use NTLM (most common password hash)	0x00002
-			must use NTLM					0x02002
-			may use NTLMv2					0x00004
-			must use NTLMv2					0x04004
-			may use Kerberos security			0x00008
-			must use Kerberos				0x08008
-			may use lanman (weak) password hash  		0x00010
-			must use lanman password hash			0x10010
-			may use plaintext passwords    			0x00020
-			must use plaintext passwords			0x20020
-			(reserved for future packet encryption)		0x00040
+			to 0x30030)::
+
+			  may use packet signing			0x00001
+			  must use packet signing			0x01001
+			  may use NTLM (most common password hash)	0x00002
+			  must use NTLM					0x02002
+			  may use NTLMv2				0x00004
+			  must use NTLMv2				0x04004
+			  may use Kerberos security			0x00008
+			  must use Kerberos				0x08008
+			  may use lanman (weak) password hash		0x00010
+			  must use lanman password hash			0x10010
+			  may use plaintext passwords			0x00020
+			  must use plaintext passwords			0x20020
+			  (reserved for future packet encryption)	0x00040
 
 cifsFYI			If set to non-zero value, additional debug information
 			will be logged to the system error log.  This field
@@ -650,14 +766,19 @@ cifsFYI			If set to non-zero value, additional debug information
 			Some debugging statements are not compiled into the
 			cifs kernel unless CONFIG_CIFS_DEBUG2 is enabled in the
 			kernel configuration. cifsFYI may be set to one or
-			nore of the following flags (7 sets them all):
+			nore of the following flags (7 sets them all)::
+
+			  +-----------------------------------------------+------+
+			  | log cifs informational messages		  | 0x01 |
+			  +-----------------------------------------------+------+
+			  | log return codes from cifs entry points	  | 0x02 |
+			  +-----------------------------------------------+------+
+			  | log slow responses				  | 0x04 |
+			  | (ie which take longer than 1 second)	  |      |
+			  |                                               |      |
+			  | CONFIG_CIFS_STATS2 must be enabled in .config |      |
+			  +-----------------------------------------------+------+
 
-			log cifs informational messages			0x01
-			log return codes from cifs entry points		0x02
-			log slow responses (ie which take longer than 1 second)
-			  CONFIG_CIFS_STATS2 must be enabled in .config	0x04
-				
-				
 traceSMB		If set to one, debug information is logged to the
 			system error log with the start of smb requests
 			and responses (default 0)
@@ -671,24 +792,25 @@ LinuxExtensionsEnabled	If set to one then the client will attempt to
 			as support symbolic links. If you use servers
 			such as Samba that support the CIFS Unix
 			extensions but do not want to use symbolic link
-			support and want to map the uid and gid fields 
-			to values supplied at mount (rather than the 
+			support and want to map the uid and gid fields
+			to values supplied at mount (rather than the
 			actual values, then set this to zero. (default 1)
+======================= =======================================================
 
-These experimental features and tracing can be enabled by changing flags in 
-/proc/fs/cifs (after the cifs module has been installed or built into the 
-kernel, e.g.  insmod cifs).  To enable a feature set it to 1 e.g.  to enable 
-tracing to the kernel message log type: 
+These experimental features and tracing can be enabled by changing flags in
+/proc/fs/cifs (after the cifs module has been installed or built into the
+kernel, e.g.  insmod cifs).  To enable a feature set it to 1 e.g.  to enable
+tracing to the kernel message log type::
 
 	echo 7 > /proc/fs/cifs/cifsFYI
-	
+
 cifsFYI functions as a bit mask. Setting it to 1 enables additional kernel
 logging of various informational messages.  2 enables logging of non-zero
 SMB return codes while 4 enables logging of requests that take longer
-than one second to complete (except for byte range lock requests). 
+than one second to complete (except for byte range lock requests).
 Setting it to 4 requires CONFIG_CIFS_STATS2 to be set in kernel configuration
 (.config). Setting it to seven enables all three.  Finally, tracing
-the start of smb requests and responses can be enabled via:
+the start of smb requests and responses can be enabled via::
 
 	echo 1 > /proc/fs/cifs/traceSMB
 
@@ -700,10 +822,10 @@ server) SMB3 (or cifs) requests grouped by request type (read, write, close etc.
 Also recorded is the total bytes read and bytes written to the server for
 that share.  Note that due to client caching effects this can be less than the
 number of bytes read and written by the application running on the client.
-Statistics can be reset to zero by "echo 0 > /proc/fs/cifs/Stats" which may be
+Statistics can be reset to zero by ``echo 0 > /proc/fs/cifs/Stats`` which may be
 useful if comparing performance of two different scenarios.
-	
-Also note that "cat /proc/fs/cifs/DebugData" will display information about
+
+Also note that ``cat /proc/fs/cifs/DebugData`` will display information about
 the active sessions and the shares that are mounted.
 
 Enabling Kerberos (extended security) works but requires version 1.2 or later
@@ -725,19 +847,23 @@ space to ease network configuration and improve reliability.
 
 To use cifs Kerberos and DFS support, the Linux keyutils package should be
 installed and something like the following lines should be added to the
-/etc/request-key.conf file:
+/etc/request-key.conf file::
 
-create cifs.spnego * * /usr/local/sbin/cifs.upcall %k
-create dns_resolver * * /usr/local/sbin/cifs.upcall %k
+  create cifs.spnego * * /usr/local/sbin/cifs.upcall %k
+  create dns_resolver * * /usr/local/sbin/cifs.upcall %k
 
 CIFS kernel module parameters
 =============================
 These module parameters can be specified or modified either during the time of
-module loading or during the runtime by using the interface
+module loading or during the runtime by using the interface::
+
 	/proc/module/cifs/parameters/<param>
 
-i.e. echo "value" > /sys/module/cifs/parameters/<param>
+i.e.::
 
-1. enable_oplocks - Enable or disable oplocks. Oplocks are enabled by default.
-		    [Y/y/1]. To disable use any of [N/n/0].
+    echo "value" > /sys/module/cifs/parameters/<param>
 
+================= ==========================================================
+1. enable_oplocks Enable or disable oplocks. Oplocks are enabled by default.
+		  [Y/y/1]. To disable use any of [N/n/0].
+================= ==========================================================
diff --git a/Documentation/filesystems/cifs/winucase_convert.pl b/Documentation/admin-guide/cifs/winucase_convert.pl
similarity index 100%
rename from Documentation/filesystems/cifs/winucase_convert.pl
rename to Documentation/admin-guide/cifs/winucase_convert.pl
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 99d84f5f80db..6e6c23b6193a 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -77,6 +77,7 @@ configure specific aspects of kernel behavior to your liking.
    blockdev/index
    ext4
    binderfs
+   cifs/index
    xfs
    pm/index
    thunderbolt
diff --git a/MAINTAINERS b/MAINTAINERS
index 2055887f07ef..b6b9d8c67987 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -4099,7 +4099,7 @@ L:	samba-technical@lists.samba.org (moderated for non-subscribers)
 W:	http://linux-cifs.samba.org/
 T:	git git://git.samba.org/sfrench/cifs-2.6.git
 S:	Supported
-F:	Documentation/filesystems/cifs/
+F:	Documentation/admin-guide/cifs/
 F:	fs/cifs/
 
 COMPACTPCI HOTPLUG CORE
-- 
2.21.0


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

* [PATCH v2 17/26] docs: fs: convert docs without extension to ReST
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (20 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Steve French,
	Mike Marshall, Martin Brandenburg, linux-doc, linux-cifs,
	samba-technical, devel

There are 3 remaining files without an extension inside the fs docs
dir.

Manually convert them to ReST.

In the case of the nfs/exporting.rst file, as the nfs docs
aren't ported yet, I opted to convert and add a :orphan: there,
with should be removed when it gets added into a nfs-specific
part of the fs documentation.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 ...irectory-locking => directory-locking.rst} |  40 ++-
 Documentation/filesystems/index.rst           |   2 +
 .../filesystems/{Locking => locking.rst}      | 257 ++++++++++++------
 .../nfs/{Exporting => exporting.rst}          |  31 ++-
 Documentation/filesystems/vfs.rst             |   2 +-
 fs/cifs/export.c                              |   2 +-
 fs/exportfs/expfs.c                           |   2 +-
 fs/isofs/export.c                             |   2 +-
 fs/orangefs/file.c                            |   2 +-
 include/linux/dcache.h                        |   2 +-
 include/linux/exportfs.h                      |   2 +-
 11 files changed, 225 insertions(+), 119 deletions(-)
 rename Documentation/filesystems/{directory-locking => directory-locking.rst} (86%)
 rename Documentation/filesystems/{Locking => locking.rst} (79%)
 rename Documentation/filesystems/nfs/{Exporting => exporting.rst} (91%)

diff --git a/Documentation/filesystems/directory-locking b/Documentation/filesystems/directory-locking.rst
similarity index 86%
rename from Documentation/filesystems/directory-locking
rename to Documentation/filesystems/directory-locking.rst
index 4e32cb961e5b..de12016ee419 100644
--- a/Documentation/filesystems/directory-locking
+++ b/Documentation/filesystems/directory-locking.rst
@@ -1,12 +1,17 @@
-	Locking scheme used for directory operations is based on two
+=================
+Directory Locking
+=================
+
+
+Locking scheme used for directory operations is based on two
 kinds of locks - per-inode (->i_rwsem) and per-filesystem
 (->s_vfs_rename_mutex).
 
-	When taking the i_rwsem on multiple non-directory objects, we
+When taking the i_rwsem on multiple non-directory objects, we
 always acquire the locks in order by increasing address.  We'll call
 that "inode pointer" order in the following.
 
-	For our purposes all operations fall in 5 classes:
+For our purposes all operations fall in 5 classes:
 
 1) read access.  Locking rules: caller locks directory we are accessing.
 The lock is taken shared.
@@ -27,25 +32,29 @@ NB: we might get away with locking the the source (and target in exchange
 case) shared.
 
 5) link creation.  Locking rules:
+
 	* lock parent
 	* check that source is not a directory
 	* lock source
 	* call the method.
+
 All locks are exclusive.
 
 6) cross-directory rename.  The trickiest in the whole bunch.  Locking
 rules:
+
 	* lock the filesystem
 	* lock parents in "ancestors first" order.
 	* find source and target.
 	* if old parent is equal to or is a descendent of target
-		fail with -ENOTEMPTY
+	  fail with -ENOTEMPTY
 	* if new parent is equal to or is a descendent of source
-		fail with -ELOOP
+	  fail with -ELOOP
 	* If it's an exchange, lock both the source and the target.
 	* If the target exists, lock it.  If the source is a non-directory,
 	  lock it.  If we need to lock both, do so in inode pointer order.
 	* call the method.
+
 All ->i_rwsem are taken exclusive.  Again, we might get away with locking
 the the source (and target in exchange case) shared.
 
@@ -54,10 +63,11 @@ read, modified or removed by method will be locked by caller.
 
 
 If no directory is its own ancestor, the scheme above is deadlock-free.
+
 Proof:
 
 	First of all, at any moment we have a partial ordering of the
-objects - A < B iff A is an ancestor of B.
+	objects - A < B iff A is an ancestor of B.
 
 	That ordering can change.  However, the following is true:
 
@@ -77,32 +87,32 @@ objects - A < B iff A is an ancestor of B.
     non-directory object, except renames, which take locks on source and
     target in inode pointer order in the case they are not directories.)
 
-	Now consider the minimal deadlock.  Each process is blocked on
+Now consider the minimal deadlock.  Each process is blocked on
 attempt to acquire some lock and already holds at least one lock.  Let's
 consider the set of contended locks.  First of all, filesystem lock is
 not contended, since any process blocked on it is not holding any locks.
 Thus all processes are blocked on ->i_rwsem.
 
-	By (3), any process holding a non-directory lock can only be
+By (3), any process holding a non-directory lock can only be
 waiting on another non-directory lock with a larger address.  Therefore
 the process holding the "largest" such lock can always make progress, and
 non-directory objects are not included in the set of contended locks.
 
-	Thus link creation can't be a part of deadlock - it can't be
+Thus link creation can't be a part of deadlock - it can't be
 blocked on source and it means that it doesn't hold any locks.
 
-	Any contended object is either held by cross-directory rename or
+Any contended object is either held by cross-directory rename or
 has a child that is also contended.  Indeed, suppose that it is held by
 operation other than cross-directory rename.  Then the lock this operation
 is blocked on belongs to child of that object due to (1).
 
-	It means that one of the operations is cross-directory rename.
+It means that one of the operations is cross-directory rename.
 Otherwise the set of contended objects would be infinite - each of them
 would have a contended child and we had assumed that no object is its
 own descendent.  Moreover, there is exactly one cross-directory rename
 (see above).
 
-	Consider the object blocking the cross-directory rename.  One
+Consider the object blocking the cross-directory rename.  One
 of its descendents is locked by cross-directory rename (otherwise we
 would again have an infinite set of contended objects).  But that
 means that cross-directory rename is taking locks out of order.  Due
@@ -112,7 +122,7 @@ try to acquire lock on descendent before the lock on ancestor.
 Contradiction.  I.e.  deadlock is impossible.  Q.E.D.
 
 
-	These operations are guaranteed to avoid loop creation.  Indeed,
+These operations are guaranteed to avoid loop creation.  Indeed,
 the only operation that could introduce loops is cross-directory rename.
 Since the only new (parent, child) pair added by rename() is (new parent,
 source), such loop would have to contain these objects and the rest of it
@@ -123,13 +133,13 @@ new parent had been equal to or a descendent of source since the moment when
 we had acquired filesystem lock and rename() would fail with -ELOOP in that
 case.
 
-	While this locking scheme works for arbitrary DAGs, it relies on
+While this locking scheme works for arbitrary DAGs, it relies on
 ability to check that directory is a descendent of another object.  Current
 implementation assumes that directory graph is a tree.  This assumption is
 also preserved by all operations (cross-directory rename on a tree that would
 not introduce a cycle will leave it a tree and link() fails for directories).
 
-	Notice that "directory" in the above == "anything that might have
+Notice that "directory" in the above == "anything that might have
 children", so if we are going to introduce hybrid objects we will need
 either to make sure that link(2) doesn't work for them or to make changes
 in is_subdir() that would make it work even in presence of such beasts.
diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 2de2fe2ab078..08320c35d03b 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -20,6 +20,8 @@ algorithms work.
    path-lookup
    api-summary
    splice
+   locking
+   directory-locking
 
 Filesystem support layers
 =========================
diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/locking.rst
similarity index 79%
rename from Documentation/filesystems/Locking
rename to Documentation/filesystems/locking.rst
index 204dd3ea36bb..fc3a0704553c 100644
--- a/Documentation/filesystems/Locking
+++ b/Documentation/filesystems/locking.rst
@@ -1,14 +1,22 @@
-	The text below describes the locking rules for VFS-related methods.
+=======
+Locking
+=======
+
+The text below describes the locking rules for VFS-related methods.
 It is (believed to be) up-to-date. *Please*, if you change anything in
 prototypes or locking protocols - update this file. And update the relevant
 instances in the tree, don't leave that to maintainers of filesystems/devices/
 etc. At the very least, put the list of dubious cases in the end of this file.
 Don't turn it into log - maintainers of out-of-the-tree code are supposed to
 be able to use diff(1).
-	Thing currently missing here: socket operations. Alexey?
 
---------------------------- dentry_operations --------------------------
-prototypes:
+Thing currently missing here: socket operations. Alexey?
+
+dentry_operations
+=================
+
+prototypes::
+
 	int (*d_revalidate)(struct dentry *, unsigned int);
 	int (*d_weak_revalidate)(struct dentry *, unsigned int);
 	int (*d_hash)(const struct dentry *, struct qstr *);
@@ -24,23 +32,30 @@ prototypes:
 	struct dentry *(*d_real)(struct dentry *, const struct inode *);
 
 locking rules:
-		rename_lock	->d_lock	may block	rcu-walk
-d_revalidate:	no		no		yes (ref-walk)	maybe
-d_weak_revalidate:no		no		yes	 	no
-d_hash		no		no		no		maybe
-d_compare:	yes		no		no		maybe
-d_delete:	no		yes		no		no
-d_init:	no		no		yes		no
-d_release:	no		no		yes		no
-d_prune:        no              yes             no              no
-d_iput:		no		no		yes		no
-d_dname:	no		no		no		no
-d_automount:	no		no		yes		no
-d_manage:	no		no		yes (ref-walk)	maybe
-d_real		no		no		yes 		no
 
---------------------------- inode_operations --------------------------- 
-prototypes:
+================== ===========	========	==============	========
+ops		   rename_lock	->d_lock	may block	rcu-walk
+================== ===========	========	==============	========
+d_revalidate:	   no		no		yes (ref-walk)	maybe
+d_weak_revalidate: no		no		yes	 	no
+d_hash		   no		no		no		maybe
+d_compare:	   yes		no		no		maybe
+d_delete:	   no		yes		no		no
+d_init:		   no		no		yes		no
+d_release:	   no		no		yes		no
+d_prune:           no		yes		no		no
+d_iput:		   no		no		yes		no
+d_dname:	   no		no		no		no
+d_automount:	   no		no		yes		no
+d_manage:	   no		no		yes (ref-walk)	maybe
+d_real		   no		no		yes 		no
+================== ===========	========	==============	========
+
+inode_operations
+================
+
+prototypes::
+
 	int (*create) (struct inode *,struct dentry *,umode_t, bool);
 	struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int);
 	int (*link) (struct dentry *,struct inode *,struct dentry *);
@@ -68,7 +83,10 @@ prototypes:
 
 locking rules:
 	all may block
-		i_rwsem(inode)
+
+============	=============================================
+ops		i_rwsem(inode)
+============	=============================================
 lookup:		shared
 create:		exclusive
 link:		exclusive (both)
@@ -89,17 +107,21 @@ fiemap:		no
 update_time:	no
 atomic_open:	exclusive
 tmpfile:	no
+============	=============================================
 
 
 	Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem
 	exclusive on victim.
 	cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem.
 
-See Documentation/filesystems/directory-locking for more detailed discussion
+See Documentation/filesystems/directory-locking.rst for more detailed discussion
 of the locking scheme for directory operations.
 
------------------------ xattr_handler operations -----------------------
-prototypes:
+xattr_handler operations
+========================
+
+prototypes::
+
 	bool (*list)(struct dentry *dentry);
 	int (*get)(const struct xattr_handler *handler, struct dentry *dentry,
 		   struct inode *inode, const char *name, void *buffer,
@@ -110,13 +132,20 @@ prototypes:
 
 locking rules:
 	all may block
-		i_rwsem(inode)
+
+=====		==============
+ops		i_rwsem(inode)
+=====		==============
 list:		no
 get:		no
 set:		exclusive
+=====		==============
+
+super_operations
+================
+
+prototypes::
 
---------------------------- super_operations ---------------------------
-prototypes:
 	struct inode *(*alloc_inode)(struct super_block *sb);
 	void (*free_inode)(struct inode *);
 	void (*destroy_inode)(struct inode *);
@@ -138,7 +167,10 @@ prototypes:
 
 locking rules:
 	All may block [not true, see below]
-			s_umount
+
+======================	============	========================
+ops			s_umount	note
+======================	============	========================
 alloc_inode:
 free_inode:				called from RCU callback
 destroy_inode:
@@ -157,6 +189,7 @@ show_options:		no		(namespace_sem)
 quota_read:		no		(see below)
 quota_write:		no		(see below)
 bdev_try_to_free_page:	no		(see below)
+======================	============	========================
 
 ->statfs() has s_umount (shared) when called by ustat(2) (native or
 compat), but that's an accident of bad API; s_umount is used to pin
@@ -164,31 +197,44 @@ the superblock down when we only have dev_t given us by userland to
 identify the superblock.  Everything else (statfs(), fstatfs(), etc.)
 doesn't hold it when calling ->statfs() - superblock is pinned down
 by resolving the pathname passed to syscall.
+
 ->quota_read() and ->quota_write() functions are both guaranteed to
 be the only ones operating on the quota file by the quota code (via
 dqio_sem) (unless an admin really wants to screw up something and
 writes to quota files with quotas on). For other details about locking
 see also dquot_operations section.
+
 ->bdev_try_to_free_page is called from the ->releasepage handler of
 the block device inode.  See there for more details.
 
---------------------------- file_system_type ---------------------------
-prototypes:
+file_system_type
+================
+
+prototypes::
+
 	struct dentry *(*mount) (struct file_system_type *, int,
 		       const char *, void *);
 	void (*kill_sb) (struct super_block *);
+
 locking rules:
-		may block
+
+=======		=========
+ops		may block
+=======		=========
 mount		yes
 kill_sb		yes
+=======		=========
 
 ->mount() returns ERR_PTR or the root dentry; its superblock should be locked
 on return.
+
 ->kill_sb() takes a write-locked superblock, does all shutdown work on it,
 unlocks and drops the reference.
 
---------------------------- address_space_operations --------------------------
-prototypes:
+address_space_operations
+========================
+prototypes::
+
 	int (*writepage)(struct page *page, struct writeback_control *wbc);
 	int (*readpage)(struct file *, struct page *);
 	int (*writepages)(struct address_space *, struct writeback_control *);
@@ -218,14 +264,16 @@ prototypes:
 locking rules:
 	All except set_page_dirty and freepage may block
 
-			PageLocked(page)	i_rwsem
+======================	======================== =========
+ops			PageLocked(page)	 i_rwsem
+======================	======================== =========
 writepage:		yes, unlocks (see below)
 readpage:		yes, unlocks
 writepages:
 set_page_dirty		no
 readpages:
-write_begin:		locks the page		exclusive
-write_end:		yes, unlocks		exclusive
+write_begin:		locks the page		 exclusive
+write_end:		yes, unlocks		 exclusive
 bmap:
 invalidatepage:		yes
 releasepage:		yes
@@ -239,17 +287,18 @@ is_partially_uptodate:	yes
 error_remove_page:	yes
 swap_activate:		no
 swap_deactivate:	no
+======================	======================== =========
 
-	->write_begin(), ->write_end() and ->readpage() may be called from
+->write_begin(), ->write_end() and ->readpage() may be called from
 the request handler (/dev/loop).
 
-	->readpage() unlocks the page, either synchronously or via I/O
+->readpage() unlocks the page, either synchronously or via I/O
 completion.
 
-	->readpages() populates the pagecache with the passed pages and starts
+->readpages() populates the pagecache with the passed pages and starts
 I/O against them.  They come unlocked upon I/O completion.
 
-	->writepage() is used for two purposes: for "memory cleansing" and for
+->writepage() is used for two purposes: for "memory cleansing" and for
 "sync".  These are quite different operations and the behaviour may differ
 depending upon the mode.
 
@@ -297,70 +346,81 @@ will leave the page itself marked clean but it will be tagged as dirty in the
 radix tree.  This incoherency can lead to all sorts of hard-to-debug problems
 in the filesystem like having dirty inodes at umount and losing written data.
 
-	->writepages() is used for periodic writeback and for syscall-initiated
+->writepages() is used for periodic writeback and for syscall-initiated
 sync operations.  The address_space should start I/O against at least
-*nr_to_write pages.  *nr_to_write must be decremented for each page which is
-written.  The address_space implementation may write more (or less) pages
-than *nr_to_write asks for, but it should try to be reasonably close.  If
-nr_to_write is NULL, all dirty pages must be written.
+``*nr_to_write`` pages.  ``*nr_to_write`` must be decremented for each page
+which is written.  The address_space implementation may write more (or less)
+pages than ``*nr_to_write`` asks for, but it should try to be reasonably close.
+If nr_to_write is NULL, all dirty pages must be written.
 
 writepages should _only_ write pages which are present on
 mapping->io_pages.
 
-	->set_page_dirty() is called from various places in the kernel
+->set_page_dirty() is called from various places in the kernel
 when the target page is marked as needing writeback.  It may be called
 under spinlock (it cannot block) and is sometimes called with the page
 not locked.
 
-	->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
+->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
 filesystems and by the swapper. The latter will eventually go away.  Please,
 keep it that way and don't breed new callers.
 
-	->invalidatepage() is called when the filesystem must attempt to drop
+->invalidatepage() is called when the filesystem must attempt to drop
 some or all of the buffers from the page when it is being truncated. It
 returns zero on success. If ->invalidatepage is zero, the kernel uses
 block_invalidatepage() instead.
 
-	->releasepage() is called when the kernel is about to try to drop the
+->releasepage() is called when the kernel is about to try to drop the
 buffers from the page in preparation for freeing it.  It returns zero to
 indicate that the buffers are (or may be) freeable.  If ->releasepage is zero,
 the kernel assumes that the fs has no private interest in the buffers.
 
-	->freepage() is called when the kernel is done dropping the page
+->freepage() is called when the kernel is done dropping the page
 from the page cache.
 
-	->launder_page() may be called prior to releasing a page if
+->launder_page() may be called prior to releasing a page if
 it is still found to be dirty. It returns zero if the page was successfully
 cleaned, or an error value if not. Note that in order to prevent the page
 getting mapped back in and redirtied, it needs to be kept locked
 across the entire operation.
 
-	->swap_activate will be called with a non-zero argument on
+->swap_activate will be called with a non-zero argument on
 files backing (non block device backed) swapfiles. A return value
 of zero indicates success, in which case this file can be used for
 backing swapspace. The swapspace operations will be proxied to the
 address space operations.
 
-	->swap_deactivate() will be called in the sys_swapoff()
+->swap_deactivate() will be called in the sys_swapoff()
 path after ->swap_activate() returned success.
 
------------------------ file_lock_operations ------------------------------
-prototypes:
+file_lock_operations
+====================
+
+prototypes::
+
 	void (*fl_copy_lock)(struct file_lock *, struct file_lock *);
 	void (*fl_release_private)(struct file_lock *);
 
 
 locking rules:
-			inode->i_lock	may block
+
+===================	=============	=========
+ops			inode->i_lock	may block
+===================	=============	=========
 fl_copy_lock:		yes		no
-fl_release_private:	maybe		maybe[1]
+fl_release_private:	maybe		maybe[1]_
+===================	=============	=========
 
-[1]:	->fl_release_private for flock or POSIX locks is currently allowed
-to block. Leases however can still be freed while the i_lock is held and
-so fl_release_private called on a lease should not block.
+.. [1]:
+   ->fl_release_private for flock or POSIX locks is currently allowed
+   to block. Leases however can still be freed while the i_lock is held and
+   so fl_release_private called on a lease should not block.
+
+lock_manager_operations
+=======================
+
+prototypes::
 
------------------------ lock_manager_operations ---------------------------
-prototypes:
 	void (*lm_notify)(struct file_lock *);  /* unblock callback */
 	int (*lm_grant)(struct file_lock *, struct file_lock *, int);
 	void (*lm_break)(struct file_lock *); /* break_lease callback */
@@ -368,24 +428,33 @@ prototypes:
 
 locking rules:
 
-			inode->i_lock	blocked_lock_lock	may block
+==========		=============	=================	=========
+ops			inode->i_lock	blocked_lock_lock	may block
+==========		=============	=================	=========
 lm_notify:		yes		yes			no
 lm_grant:		no		no			no
 lm_break:		yes		no			no
 lm_change		yes		no			no
+==========		=============	=================	=========
+
+buffer_head
+===========
+
+prototypes::
 
---------------------------- buffer_head -----------------------------------
-prototypes:
 	void (*b_end_io)(struct buffer_head *bh, int uptodate);
 
 locking rules:
-	called from interrupts. In other words, extreme care is needed here.
+
+called from interrupts. In other words, extreme care is needed here.
 bh is locked, but that's all warranties we have here. Currently only RAID1,
 highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices
 call this method upon the IO completion.
 
---------------------------- block_device_operations -----------------------
-prototypes:
+block_device_operations
+=======================
+prototypes::
+
 	int (*open) (struct block_device *, fmode_t);
 	int (*release) (struct gendisk *, fmode_t);
 	int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
@@ -399,7 +468,10 @@ prototypes:
 	void (*swap_slot_free_notify) (struct block_device *, unsigned long);
 
 locking rules:
-			bd_mutex
+
+======================= ===================
+ops			bd_mutex
+======================= ===================
 open:			yes
 release:		yes
 ioctl:			no
@@ -410,6 +482,7 @@ unlock_native_capacity:	no
 revalidate_disk:	no
 getgeo:			no
 swap_slot_free_notify:	no	(see below)
+======================= ===================
 
 media_changed, unlock_native_capacity and revalidate_disk are called only from
 check_disk_change().
@@ -418,8 +491,11 @@ swap_slot_free_notify is called with swap_lock and sometimes the page lock
 held.
 
 
---------------------------- file_operations -------------------------------
-prototypes:
+file_operations
+===============
+
+prototypes::
+
 	loff_t (*llseek) (struct file *, loff_t, int);
 	ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
 	ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
@@ -455,7 +531,6 @@ prototypes:
 			size_t, unsigned int);
 	int (*setlease)(struct file *, long, struct file_lock **, void **);
 	long (*fallocate)(struct file *, int, loff_t, loff_t);
-};
 
 locking rules:
 	All may block.
@@ -490,8 +565,11 @@ in sys_read() and friends.
 the lease within the individual filesystem to record the result of the
 operation
 
---------------------------- dquot_operations -------------------------------
-prototypes:
+dquot_operations
+================
+
+prototypes::
+
 	int (*write_dquot) (struct dquot *);
 	int (*acquire_dquot) (struct dquot *);
 	int (*release_dquot) (struct dquot *);
@@ -503,20 +581,26 @@ a proper locking wrt the filesystem and call the generic quota operations.
 
 What filesystem should expect from the generic quota functions:
 
-		FS recursion	Held locks when called
+==============	============	=========================
+ops		FS recursion	Held locks when called
+==============	============	=========================
 write_dquot:	yes		dqonoff_sem or dqptr_sem
 acquire_dquot:	yes		dqonoff_sem or dqptr_sem
 release_dquot:	yes		dqonoff_sem or dqptr_sem
 mark_dirty:	no		-
 write_info:	yes		dqonoff_sem
+==============	============	=========================
 
 FS recursion means calling ->quota_read() and ->quota_write() from superblock
 operations.
 
 More details about quota locking can be found in fs/dquot.c.
 
---------------------------- vm_operations_struct -----------------------------
-prototypes:
+vm_operations_struct
+====================
+
+prototypes::
+
 	void (*open)(struct vm_area_struct*);
 	void (*close)(struct vm_area_struct*);
 	vm_fault_t (*fault)(struct vm_area_struct*, struct vm_fault *);
@@ -525,7 +609,10 @@ prototypes:
 	int (*access)(struct vm_area_struct *, unsigned long, void*, int, int);
 
 locking rules:
-		mmap_sem	PageLocked(page)
+
+=============	========	===========================
+ops		mmap_sem	PageLocked(page)
+=============	========	===========================
 open:		yes
 close:		yes
 fault:		yes		can return with page locked
@@ -533,8 +620,9 @@ map_pages:	yes
 page_mkwrite:	yes		can return with page locked
 pfn_mkwrite:	yes
 access:		yes
+=============	========	===========================
 
-	->fault() is called when a previously not present pte is about
+->fault() is called when a previously not present pte is about
 to be faulted in. The filesystem must find and return the page associated
 with the passed in "pgoff" in the vm_fault structure. If it is possible that
 the page may be truncated and/or invalidated, then the filesystem must lock
@@ -542,7 +630,7 @@ the page, then ensure it is not already truncated (the page lock will block
 subsequent truncate), and then return with VM_FAULT_LOCKED, and the page
 locked. The VM will unlock the page.
 
-	->map_pages() is called when VM asks to map easy accessible pages.
+->map_pages() is called when VM asks to map easy accessible pages.
 Filesystem should find and map pages associated with offsets from "start_pgoff"
 till "end_pgoff". ->map_pages() is called with page table locked and must
 not block.  If it's not possible to reach a page without blocking,
@@ -551,25 +639,26 @@ page table entry. Pointer to entry associated with the page is passed in
 "pte" field in vm_fault structure. Pointers to entries for other offsets
 should be calculated relative to "pte".
 
-	->page_mkwrite() is called when a previously read-only pte is
+->page_mkwrite() is called when a previously read-only pte is
 about to become writeable. The filesystem again must ensure that there are
 no truncate/invalidate races, and then return with the page locked. If
 the page has been truncated, the filesystem should not look up a new page
 like the ->fault() handler, but simply return with VM_FAULT_NOPAGE, which
 will cause the VM to retry the fault.
 
-	->pfn_mkwrite() is the same as page_mkwrite but when the pte is
+->pfn_mkwrite() is the same as page_mkwrite but when the pte is
 VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is
 VM_FAULT_NOPAGE. Or one of the VM_FAULT_ERROR types. The default behavior
 after this call is to make the pte read-write, unless pfn_mkwrite returns
 an error.
 
-	->access() is called when get_user_pages() fails in
+->access() is called when get_user_pages() fails in
 access_process_vm(), typically used to debug a process through
 /proc/pid/mem or ptrace.  This function is needed only for
 VM_IO | VM_PFNMAP VMAs.
 
-================================================================================
+--------------------------------------------------------------------------------
+
 			Dubious stuff
 
 (if you break something or notice that it is broken and do not fix it yourself
diff --git a/Documentation/filesystems/nfs/Exporting b/Documentation/filesystems/nfs/exporting.rst
similarity index 91%
rename from Documentation/filesystems/nfs/Exporting
rename to Documentation/filesystems/nfs/exporting.rst
index 63889149f532..33d588a01ace 100644
--- a/Documentation/filesystems/nfs/Exporting
+++ b/Documentation/filesystems/nfs/exporting.rst
@@ -1,3 +1,4 @@
+:orphan:
 
 Making Filesystems Exportable
 =============================
@@ -42,9 +43,9 @@ filehandle fragment, there is no automatic creation of a path prefix
 for the object.  This leads to two related but distinct features of
 the dcache that are not needed for normal filesystem access.
 
-1/ The dcache must sometimes contain objects that are not part of the
+1. The dcache must sometimes contain objects that are not part of the
    proper prefix. i.e that are not connected to the root.
-2/ The dcache must be prepared for a newly found (via ->lookup) directory
+2. The dcache must be prepared for a newly found (via ->lookup) directory
    to already have a (non-connected) dentry, and must be able to move
    that dentry into place (based on the parent and name in the
    ->lookup).   This is particularly needed for directories as
@@ -52,7 +53,7 @@ the dcache that are not needed for normal filesystem access.
 
 To implement these features, the dcache has:
 
-a/ A dentry flag DCACHE_DISCONNECTED which is set on
+a. A dentry flag DCACHE_DISCONNECTED which is set on
    any dentry that might not be part of the proper prefix.
    This is set when anonymous dentries are created, and cleared when a
    dentry is noticed to be a child of a dentry which is in the proper
@@ -71,48 +72,52 @@ a/ A dentry flag DCACHE_DISCONNECTED which is set on
    dentries.  That guarantees that we won't need to hunt them down upon
    umount.
 
-b/ A primitive for creation of secondary roots - d_obtain_root(inode).
+b. A primitive for creation of secondary roots - d_obtain_root(inode).
    Those do _not_ bear DCACHE_DISCONNECTED.  They are placed on the
    per-superblock list (->s_roots), so they can be located at umount
    time for eviction purposes.
 
-c/ Helper routines to allocate anonymous dentries, and to help attach
+c. Helper routines to allocate anonymous dentries, and to help attach
    loose directory dentries at lookup time. They are:
+
     d_obtain_alias(inode) will return a dentry for the given inode.
       If the inode already has a dentry, one of those is returned.
+
       If it doesn't, a new anonymous (IS_ROOT and
-        DCACHE_DISCONNECTED) dentry is allocated and attached.
+      DCACHE_DISCONNECTED) dentry is allocated and attached.
+
       In the case of a directory, care is taken that only one dentry
       can ever be attached.
+
     d_splice_alias(inode, dentry) will introduce a new dentry into the tree;
       either the passed-in dentry or a preexisting alias for the given inode
       (such as an anonymous one created by d_obtain_alias), if appropriate.
       It returns NULL when the passed-in dentry is used, following the calling
       convention of ->lookup.
- 
+
 Filesystem Issues
 -----------------
 
 For a filesystem to be exportable it must:
- 
-   1/ provide the filehandle fragment routines described below.
-   2/ make sure that d_splice_alias is used rather than d_add
+
+   1. provide the filehandle fragment routines described below.
+   2. make sure that d_splice_alias is used rather than d_add
       when ->lookup finds an inode for a given parent and name.
 
-      If inode is NULL, d_splice_alias(inode, dentry) is equivalent to
+      If inode is NULL, d_splice_alias(inode, dentry) is equivalent to::
 
 		d_add(dentry, inode), NULL
 
       Similarly, d_splice_alias(ERR_PTR(err), dentry) = ERR_PTR(err)
 
-      Typically the ->lookup routine will simply end with a:
+      Typically the ->lookup routine will simply end with a::
 
 		return d_splice_alias(inode, dentry);
 	}
 
 
 
-  A file system implementation declares that instances of the filesystem
+A file system implementation declares that instances of the filesystem
 are exportable by setting the s_export_op field in the struct
 super_block.  This field must point to a "struct export_operations"
 struct which has the following members:
diff --git a/Documentation/filesystems/vfs.rst b/Documentation/filesystems/vfs.rst
index 0f85ab21c2ca..7d4d09dd5e6d 100644
--- a/Documentation/filesystems/vfs.rst
+++ b/Documentation/filesystems/vfs.rst
@@ -20,7 +20,7 @@ kernel which allows different filesystem implementations to coexist.
 
 VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so on
 are called from a process context.  Filesystem locking is described in
-the document Documentation/filesystems/Locking.
+the document Documentation/filesystems/locking.rst.
 
 
 Directory Entry Cache (dcache)
diff --git a/fs/cifs/export.c b/fs/cifs/export.c
index ce8b7f677c58..eb0bb8ca8e63 100644
--- a/fs/cifs/export.c
+++ b/fs/cifs/export.c
@@ -24,7 +24,7 @@
  */
 
  /*
-  * See Documentation/filesystems/nfs/Exporting
+  * See Documentation/filesystems/nfs/exporting.rst
   * and examples in fs/exportfs
   *
   * Since cifs is a network file system, an "fsid" must be included for
diff --git a/fs/exportfs/expfs.c b/fs/exportfs/expfs.c
index f0e549783caf..09bc68708d28 100644
--- a/fs/exportfs/expfs.c
+++ b/fs/exportfs/expfs.c
@@ -7,7 +7,7 @@
  * and for mapping back from file handles to dentries.
  *
  * For details on why we do all the strange and hairy things in here
- * take a look at Documentation/filesystems/nfs/Exporting.
+ * take a look at Documentation/filesystems/nfs/exporting.rst.
  */
 #include <linux/exportfs.h>
 #include <linux/fs.h>
diff --git a/fs/isofs/export.c b/fs/isofs/export.c
index 85a9093769a9..35768a63fb1d 100644
--- a/fs/isofs/export.c
+++ b/fs/isofs/export.c
@@ -10,7 +10,7 @@
  *
  * The following files are helpful:
  *
- *     Documentation/filesystems/nfs/Exporting
+ *     Documentation/filesystems/nfs/exporting.rst
  *     fs/exportfs/expfs.c.
  */
 
diff --git a/fs/orangefs/file.c b/fs/orangefs/file.c
index 960f9a3c012d..a5612abc0936 100644
--- a/fs/orangefs/file.c
+++ b/fs/orangefs/file.c
@@ -555,7 +555,7 @@ static int orangefs_fsync(struct file *file,
  * Change the file pointer position for an instance of an open file.
  *
  * \note If .llseek is overriden, we must acquire lock as described in
- *       Documentation/filesystems/Locking.
+ *       Documentation/filesystems/locking.rst.
  *
  * Future upgrade could support SEEK_DATA and SEEK_HOLE but would
  * require much changes to the FS
diff --git a/include/linux/dcache.h b/include/linux/dcache.h
index 9451011ac014..10090f11ab95 100644
--- a/include/linux/dcache.h
+++ b/include/linux/dcache.h
@@ -151,7 +151,7 @@ struct dentry_operations {
 
 /*
  * Locking rules for dentry_operations callbacks are to be found in
- * Documentation/filesystems/Locking. Keep it updated!
+ * Documentation/filesystems/locking.rst. Keep it updated!
  *
  * FUrther descriptions are found in Documentation/filesystems/vfs.rst.
  * Keep it updated too!
diff --git a/include/linux/exportfs.h b/include/linux/exportfs.h
index 0d3037419bc7..cf6571fc9c01 100644
--- a/include/linux/exportfs.h
+++ b/include/linux/exportfs.h
@@ -139,7 +139,7 @@ struct fid {
  * @get_parent:     find the parent of a given directory
  * @commit_metadata: commit metadata changes to stable storage
  *
- * See Documentation/filesystems/nfs/Exporting for details on how to use
+ * See Documentation/filesystems/nfs/exporting.rst for details on how to use
  * this interface correctly.
  *
  * encode_fh:
-- 
2.21.0


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

* [PATCH v2 18/26] docs: fs: convert porting to ReST
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (21 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Mike Marshall,
	Martin Brandenburg, linux-doc, devel

This file has its own proper style, except that, after a while,
the coding style gets violated and whitespaces are placed on
different ways.

As Sphinx and ReST are very sentitive to whitespace differences,
I had to opt if each entry after required/mandatory/... fields
should start with zero spaces or with a tab. I opted to start them
all from the zero position, in order to avoid needing to break lines
with more than 80 columns, with would make harder for review.

Most of the other changes at porting.rst were made to use an unified
notation with works nice as a text file while also produce a good html
output after being parsed.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/filesystems/index.rst           |   2 +
 .../filesystems/{porting => porting.rst}      | 824 +++++++++++-------
 fs/orangefs/orangefs-kernel.h                 |   2 +-
 3 files changed, 498 insertions(+), 330 deletions(-)
 rename Documentation/filesystems/{porting => porting.rst} (49%)

diff --git a/Documentation/filesystems/index.rst b/Documentation/filesystems/index.rst
index 08320c35d03b..96653ebefd7e 100644
--- a/Documentation/filesystems/index.rst
+++ b/Documentation/filesystems/index.rst
@@ -23,6 +23,8 @@ algorithms work.
    locking
    directory-locking
 
+   porting
+
 Filesystem support layers
 =========================
 
diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting.rst
similarity index 49%
rename from Documentation/filesystems/porting
rename to Documentation/filesystems/porting.rst
index 6b7a41cfcaed..66aa521e6376 100644
--- a/Documentation/filesystems/porting
+++ b/Documentation/filesystems/porting.rst
@@ -1,22 +1,28 @@
+====================
 Changes since 2.5.0:
+====================
 
 ---
-[recommended]
+
+**recommended**
 
 New helpers: sb_bread(), sb_getblk(), sb_find_get_block(), set_bh(),
-	sb_set_blocksize() and sb_min_blocksize().
+sb_set_blocksize() and sb_min_blocksize().
 
 Use them.
 
 (sb_find_get_block() replaces 2.4's get_hash_table())
 
 ---
-[recommended]
+
+**recommended**
 
 New methods: ->alloc_inode() and ->destroy_inode().
 
 Remove inode->u.foo_inode_i
-Declare
+
+Declare::
+
 	struct foo_inode_info {
 		/* fs-private stuff */
 		struct inode vfs_inode;
@@ -40,7 +46,8 @@ typically between calling iget_locked() and unlocking the inode.
 At some point that will become mandatory.
 
 ---
-[mandatory]
+
+**mandatory**
 
 Change of file_system_type method (->read_super to ->get_sb)
 
@@ -48,14 +55,14 @@ Change of file_system_type method (->read_super to ->get_sb)
 
 Turn your foo_read_super() into a function that would return 0 in case of
 success and negative number in case of error (-EINVAL unless you have more
-informative error value to report).  Call it foo_fill_super().  Now declare
+informative error value to report).  Call it foo_fill_super().  Now declare::
 
-int foo_get_sb(struct file_system_type *fs_type,
+  int foo_get_sb(struct file_system_type *fs_type,
 	int flags, const char *dev_name, void *data, struct vfsmount *mnt)
-{
+  {
 	return get_sb_bdev(fs_type, flags, dev_name, data, foo_fill_super,
 			   mnt);
-}
+  }
 
 (or similar with s/bdev/nodev/ or s/bdev/single/, depending on the kind of
 filesystem).
@@ -64,7 +71,8 @@ Replace DECLARE_FSTYPE... with explicit initializer and have ->get_sb set as
 foo_get_sb.
 
 ---
-[mandatory]
+
+**mandatory**
 
 Locking change: ->s_vfs_rename_sem is taken only by cross-directory renames.
 Most likely there is no need to change anything, but if you relied on
@@ -73,7 +81,8 @@ change your internal locking.  Otherwise exclusion warranties remain the
 same (i.e. parents and victim are locked, etc.).
 
 ---
-[informational]
+
+**informational**
 
 Now we have the exclusion between ->lookup() and directory removal (by
 ->rmdir() and ->rename()).  If you used to need that exclusion and do
@@ -81,7 +90,8 @@ it by internal locking (most of filesystems couldn't care less) - you
 can relax your locking.
 
 ---
-[mandatory]
+
+**mandatory**
 
 ->lookup(), ->truncate(), ->create(), ->unlink(), ->mknod(), ->mkdir(),
 ->rmdir(), ->link(), ->lseek(), ->symlink(), ->rename()
@@ -92,51 +102,60 @@ unlock_kernel() so that they would protect exactly what needs to be
 protected.
 
 ---
-[mandatory]
+
+**mandatory**
 
 BKL is also moved from around sb operations. BKL should have been shifted into
 individual fs sb_op functions.  If you don't need it, remove it.
 
 ---
-[informational]
+
+**informational**
 
 check for ->link() target not being a directory is done by callers.  Feel
 free to drop it...
 
 ---
-[informational]
+
+**informational**
 
 ->link() callers hold ->i_mutex on the object we are linking to.  Some of your
 problems might be over...
 
 ---
-[mandatory]
+
+**mandatory**
 
 new file_system_type method - kill_sb(superblock).  If you are converting
-an existing filesystem, set it according to ->fs_flags:
+an existing filesystem, set it according to ->fs_flags::
+
 	FS_REQUIRES_DEV		-	kill_block_super
 	FS_LITTER		-	kill_litter_super
 	neither			-	kill_anon_super
+
 FS_LITTER is gone - just remove it from fs_flags.
 
 ---
-[mandatory]
 
-	FS_SINGLE is gone (actually, that had happened back when ->get_sb()
+**mandatory**
+
+FS_SINGLE is gone (actually, that had happened back when ->get_sb()
 went in - and hadn't been documented ;-/).  Just remove it from fs_flags
 (and see ->get_sb() entry for other actions).
 
 ---
-[mandatory]
+
+**mandatory**
 
 ->setattr() is called without BKL now.  Caller _always_ holds ->i_mutex, so
 watch for ->i_mutex-grabbing code that might be used by your ->setattr().
 Callers of notify_change() need ->i_mutex now.
 
 ---
-[recommended]
 
-New super_block field "struct export_operations *s_export_op" for
+**recommended**
+
+New super_block field ``struct export_operations *s_export_op`` for
 explicit support for exporting, e.g. via NFS.  The structure is fully
 documented at its declaration in include/linux/fs.h, and in
 Documentation/filesystems/nfs/Exporting.
@@ -149,17 +168,18 @@ support for this helper, particularly get_parent.
 It is planned that this will be required for exporting once the code
 settles down a bit.
 
-[mandatory]
+**mandatory**
 
 s_export_op is now required for exporting a filesystem.
 isofs, ext2, ext3, resierfs, fat
 can be used as examples of very different filesystems.
 
 ---
-[mandatory]
+
+**mandatory**
 
 iget4() and the read_inode2 callback have been superseded by iget5_locked()
-which has the following prototype,
+which has the following prototype::
 
     struct inode *iget5_locked(struct super_block *sb, unsigned long ino,
 				int (*test)(struct inode *, void *),
@@ -182,7 +202,8 @@ when appropriate. There is also a simpler iget_locked function that
 just takes the superblock and inode number as arguments and does the
 test and set for you.
 
-e.g.
+e.g.::
+
 	inode = iget_locked(sb, ino);
 	if (inode->i_state & I_NEW) {
 		err = read_inode_from_disk(inode);
@@ -198,27 +219,32 @@ should be called on the inode to render it dead, and an appropriate error
 should be passed back to the caller.
 
 ---
-[recommended]
+
+**recommended**
 
 ->getattr() finally getting used.  See instances in nfs, minix, etc.
 
 ---
-[mandatory]
+
+**mandatory**
 
 ->revalidate() is gone.  If your filesystem had it - provide ->getattr()
 and let it call whatever you had as ->revlidate() + (for symlinks that
 had ->revalidate()) add calls in ->follow_link()/->readlink().
 
 ---
-[mandatory]
+
+**mandatory**
 
 ->d_parent changes are not protected by BKL anymore.  Read access is safe
 if at least one of the following is true:
+
 	* filesystem has no cross-directory rename()
 	* we know that parent had been locked (e.g. we are looking at
-->d_parent of ->lookup() argument).
+	  ->d_parent of ->lookup() argument).
 	* we are called from ->rename().
 	* the child's ->d_lock is held
+
 Audit your code and add locking if needed.  Notice that any place that is
 not protected by the conditions above is risky even in the old tree - you
 had been relying on BKL and that's prone to screwups.  Old tree had quite
@@ -226,20 +252,23 @@ a few holes of that kind - unprotected access to ->d_parent leading to
 anything from oops to silent memory corruption.
 
 ---
-[mandatory]
 
-	FS_NOMOUNT is gone.  If you use it - just set SB_NOUSER in flags
+**mandatory**
+
+FS_NOMOUNT is gone.  If you use it - just set SB_NOUSER in flags
 (see rootfs for one kind of solution and bdev/socket/pipe for another).
 
 ---
-[recommended]
 
-	Use bdev_read_only(bdev) instead of is_read_only(kdev).  The latter
+**recommended**
+
+Use bdev_read_only(bdev) instead of is_read_only(kdev).  The latter
 is still alive, but only because of the mess in drivers/s390/block/dasd.c.
 As soon as it gets fixed is_read_only() will die.
 
 ---
-[mandatory]
+
+**mandatory**
 
 ->permission() is called without BKL now. Grab it on entry, drop upon
 return - that will guarantee the same locking you used to have.  If
@@ -248,40 +277,44 @@ shift lock_kernel() and unlock_kernel() so that they would protect
 exactly what needs to be protected.
 
 ---
-[mandatory]
+
+**mandatory**
 
 ->statfs() is now called without BKL held.  BKL should have been
 shifted into individual fs sb_op functions where it's not clear that
 it's safe to remove it.  If you don't need it, remove it.
 
 ---
-[mandatory]
 
-	is_read_only() is gone; use bdev_read_only() instead.
+**mandatory**
+
+is_read_only() is gone; use bdev_read_only() instead.
 
 ---
-[mandatory]
 
-	destroy_buffers() is gone; use invalidate_bdev().
+**mandatory**
+
+destroy_buffers() is gone; use invalidate_bdev().
 
 ---
-[mandatory]
 
-	fsync_dev() is gone; use fsync_bdev().  NOTE: lvm breakage is
+**mandatory**
+
+fsync_dev() is gone; use fsync_bdev().  NOTE: lvm breakage is
 deliberate; as soon as struct block_device * is propagated in a reasonable
 way by that code fixing will become trivial; until then nothing can be
 done.
 
-[mandatory]
+**mandatory**
 
-	block truncatation on error exit from ->write_begin, and ->direct_IO
+block truncatation on error exit from ->write_begin, and ->direct_IO
 moved from generic methods (block_write_begin, cont_write_begin,
 nobh_write_begin, blockdev_direct_IO*) to callers.  Take a look at
 ext2_write_failed and callers for an example.
 
-[mandatory]
+**mandatory**
 
-	->truncate is gone.  The whole truncate sequence needs to be
+->truncate is gone.  The whole truncate sequence needs to be
 implemented in ->setattr, which is now mandatory for filesystems
 implementing on-disk size changes.  Start with a copy of the old inode_setattr
 and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to
@@ -290,78 +323,86 @@ size update and on finally on-disk truncation which should not fail.
 setattr_prepare (which used to be inode_change_ok) now includes the size checks
 for ATTR_SIZE and must be called in the beginning of ->setattr unconditionally.
 
-[mandatory]
+**mandatory**
 
-	->clear_inode() and ->delete_inode() are gone; ->evict_inode() should
+->clear_inode() and ->delete_inode() are gone; ->evict_inode() should
 be used instead.  It gets called whenever the inode is evicted, whether it has
 remaining links or not.  Caller does *not* evict the pagecache or inode-associated
 metadata buffers; the method has to use truncate_inode_pages_final() to get rid
 of those. Caller makes sure async writeback cannot be running for the inode while
 (or after) ->evict_inode() is called.
 
-	->drop_inode() returns int now; it's called on final iput() with
+->drop_inode() returns int now; it's called on final iput() with
 inode->i_lock held and it returns true if filesystems wants the inode to be
 dropped.  As before, generic_drop_inode() is still the default and it's been
 updated appropriately.  generic_delete_inode() is also alive and it consists
 simply of return 1.  Note that all actual eviction work is done by caller after
 ->drop_inode() returns.
 
-	As before, clear_inode() must be called exactly once on each call of
+As before, clear_inode() must be called exactly once on each call of
 ->evict_inode() (as it used to be for each call of ->delete_inode()).  Unlike
 before, if you are using inode-associated metadata buffers (i.e.
 mark_buffer_dirty_inode()), it's your responsibility to call
 invalidate_inode_buffers() before clear_inode().
 
-	NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out
+NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out
 if it's zero is not *and* *never* *had* *been* enough.  Final unlink() and iput()
 may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly
 free the on-disk inode, you may end up doing that while ->write_inode() is writing
 to it.
 
 ---
-[mandatory]
 
-	.d_delete() now only advises the dcache as to whether or not to cache
+**mandatory**
+
+.d_delete() now only advises the dcache as to whether or not to cache
 unreferenced dentries, and is now only called when the dentry refcount goes to
 0. Even on 0 refcount transition, it must be able to tolerate being called 0,
 1, or more times (eg. constant, idempotent).
 
 ---
-[mandatory]
 
-	.d_compare() calling convention and locking rules are significantly
+**mandatory**
+
+.d_compare() calling convention and locking rules are significantly
 changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
 look at examples of other filesystems) for guidance.
 
 ---
-[mandatory]
 
-	.d_hash() calling convention and locking rules are significantly
+**mandatory**
+
+.d_hash() calling convention and locking rules are significantly
 changed. Read updated documentation in Documentation/filesystems/vfs.rst (and
 look at examples of other filesystems) for guidance.
 
 ---
-[mandatory]
-	dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c
+
+**mandatory**
+
+dcache_lock is gone, replaced by fine grained locks. See fs/dcache.c
 for details of what locks to replace dcache_lock with in order to protect
 particular things. Most of the time, a filesystem only needs ->d_lock, which
 protects *all* the dcache state of a given dentry.
 
---
-[mandatory]
+---
 
-	Filesystems must RCU-free their inodes, if they can have been accessed
+**mandatory**
+
+Filesystems must RCU-free their inodes, if they can have been accessed
 via rcu-walk path walk (basically, if the file can have had a path name in the
 vfs namespace).
 
-	Even though i_dentry and i_rcu share storage in a union, we will
+Even though i_dentry and i_rcu share storage in a union, we will
 initialize the former in inode_init_always(), so just leave it alone in
 the callback.  It used to be necessary to clean it there, but not anymore
 (starting at 3.2).
 
---
-[recommended]
-	vfs now tries to do path walking in "rcu-walk mode", which avoids
+---
+
+**recommended**
+
+vfs now tries to do path walking in "rcu-walk mode", which avoids
 atomic operations and scalability hazards on dentries and inodes (see
 Documentation/filesystems/path-lookup.txt). d_hash and d_compare changes
 (above) are examples of the changes required to support this. For more complex
@@ -371,46 +412,58 @@ the benefits of rcu-walk mode. We will begin to add filesystem callbacks that
 are rcu-walk aware, shown below. Filesystems should take advantage of this
 where possible.
 
---
-[mandatory]
-	d_revalidate is a callback that is made on every path element (if
+---
+
+**mandatory**
+
+d_revalidate is a callback that is made on every path element (if
 the filesystem provides it), which requires dropping out of rcu-walk mode. This
 may now be called in rcu-walk mode (nd->flags & LOOKUP_RCU). -ECHILD should be
 returned if the filesystem cannot handle rcu-walk. See
 Documentation/filesystems/vfs.rst for more details.
 
-	permission is an inode permission check that is called on many or all
+permission is an inode permission check that is called on many or all
 directory inodes on the way down a path walk (to check for exec permission). It
 must now be rcu-walk aware (mask & MAY_NOT_BLOCK).  See
 Documentation/filesystems/vfs.rst for more details.
- 
---
-[mandatory]
-	In ->fallocate() you must check the mode option passed in.  If your
+
+---
+
+**mandatory**
+
+In ->fallocate() you must check the mode option passed in.  If your
 filesystem does not support hole punching (deallocating space in the middle of a
 file) you must return -EOPNOTSUPP if FALLOC_FL_PUNCH_HOLE is set in mode.
 Currently you can only have FALLOC_FL_PUNCH_HOLE with FALLOC_FL_KEEP_SIZE set,
 so the i_size should not change when hole punching, even when puching the end of
 a file off.
 
---
-[mandatory]
-	->get_sb() is gone.  Switch to use of ->mount().  Typically it's just
-a matter of switching from calling get_sb_... to mount_... and changing the
-function type.  If you were doing it manually, just switch from setting ->mnt_root
-to some pointer to returning that pointer.  On errors return ERR_PTR(...).
-
---
-[mandatory]
-	->permission() and generic_permission()have lost flags
+---
+
+**mandatory**
+
+->get_sb() is gone.  Switch to use of ->mount().  Typically it's just
+a matter of switching from calling ``get_sb_``... to ``mount_``... and changing
+the function type.  If you were doing it manually, just switch from setting
+->mnt_root to some pointer to returning that pointer.  On errors return
+ERR_PTR(...).
+
+---
+
+**mandatory**
+
+->permission() and generic_permission()have lost flags
 argument; instead of passing IPERM_FLAG_RCU we add MAY_NOT_BLOCK into mask.
-	generic_permission() has also lost the check_acl argument; ACL checking
+
+generic_permission() has also lost the check_acl argument; ACL checking
 has been taken to VFS and filesystems need to provide a non-NULL ->i_op->get_acl
 to read an ACL from disk.
 
---
-[mandatory]
-	If you implement your own ->llseek() you must handle SEEK_HOLE and
+---
+
+**mandatory**
+
+If you implement your own ->llseek() you must handle SEEK_HOLE and
 SEEK_DATA.  You can hanle this by returning -EINVAL, but it would be nicer to
 support it in some way.  The generic handler assumes that the entire file is
 data and there is a virtual hole at the end of the file.  So if the provided
@@ -418,22 +471,25 @@ offset is less than i_size and SEEK_DATA is specified, return the same offset.
 If the above is true for the offset and you are given SEEK_HOLE, return the end
 of the file.  If the offset is i_size or greater return -ENXIO in either case.
 
-[mandatory]
-	If you have your own ->fsync() you must make sure to call
+**mandatory**
+
+If you have your own ->fsync() you must make sure to call
 filemap_write_and_wait_range() so that all dirty pages are synced out properly.
 You must also keep in mind that ->fsync() is not called with i_mutex held
 anymore, so if you require i_mutex locking you must make sure to take it and
 release it yourself.
 
---
-[mandatory]
-	d_alloc_root() is gone, along with a lot of bugs caused by code
+---
+
+**mandatory**
+
+d_alloc_root() is gone, along with a lot of bugs caused by code
 misusing it.  Replacement: d_make_root(inode).  On success d_make_root(inode)
 allocates and returns a new dentry instantiated with the passed in inode.
 On failure NULL is returned and the passed in inode is dropped so the reference
 to inode is consumed in all cases and failure handling need not do any cleanup
 for the inode.  If d_make_root(inode) is passed a NULL inode it returns NULL
-and also requires no further error handling. Typical usage is:
+and also requires no further error handling. Typical usage is::
 
 	inode = foofs_new_inode(....);
 	s->s_root = d_make_root(inode);
@@ -442,245 +498,355 @@ and also requires no further error handling. Typical usage is:
 		return -ENOMEM;
 	...
 
---
-[mandatory]
-	The witch is dead!  Well, 2/3 of it, anyway.  ->d_revalidate() and
+---
+
+**mandatory**
+
+The witch is dead!  Well, 2/3 of it, anyway.  ->d_revalidate() and
 ->lookup() do *not* take struct nameidata anymore; just the flags.
---
-[mandatory]
-	->create() doesn't take struct nameidata *; unlike the previous
+
+---
+
+**mandatory**
+
+->create() doesn't take ``struct nameidata *``; unlike the previous
 two, it gets "is it an O_EXCL or equivalent?" boolean argument.  Note that
 local filesystems can ignore tha argument - they are guaranteed that the
 object doesn't exist.  It's remote/distributed ones that might care...
---
-[mandatory]
-	FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate()
+
+---
+
+**mandatory**
+
+FS_REVAL_DOT is gone; if you used to have it, add ->d_weak_revalidate()
 in your dentry operations instead.
---
-[mandatory]
-	vfs_readdir() is gone; switch to iterate_dir() instead
---
-[mandatory]
-	->readdir() is gone now; switch to ->iterate()
-[mandatory]
-	vfs_follow_link has been removed.  Filesystems must use nd_set_link
-	from ->follow_link for normal symlinks, or nd_jump_link for magic
-	/proc/<pid> style links.
---
-[mandatory]
-	iget5_locked()/ilookup5()/ilookup5_nowait() test() callback used to be
-	called with both ->i_lock and inode_hash_lock held; the former is *not*
-	taken anymore, so verify that your callbacks do not rely on it (none
-	of the in-tree instances did).  inode_hash_lock is still held,
-	of course, so they are still serialized wrt removal from inode hash,
-	as well as wrt set() callback of iget5_locked().
---
-[mandatory]
-	d_materialise_unique() is gone; d_splice_alias() does everything you
-	need now.  Remember that they have opposite orders of arguments ;-/
---
-[mandatory]
-	f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid
-	it entirely.
---
-[mandatory]
-	never call ->read() and ->write() directly; use __vfs_{read,write} or
-	wrappers; instead of checking for ->write or ->read being NULL, look for
-	FMODE_CAN_{WRITE,READ} in file->f_mode.
---
-[mandatory]
-	do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL
-	instead.
---
-[mandatory]
+
+---
+
+**mandatory**
+
+vfs_readdir() is gone; switch to iterate_dir() instead
+
+---
+
+**mandatory**
+
+->readdir() is gone now; switch to ->iterate()
+
+**mandatory**
+
+vfs_follow_link has been removed.  Filesystems must use nd_set_link
+from ->follow_link for normal symlinks, or nd_jump_link for magic
+/proc/<pid> style links.
+
+---
+
+**mandatory**
+
+iget5_locked()/ilookup5()/ilookup5_nowait() test() callback used to be
+called with both ->i_lock and inode_hash_lock held; the former is *not*
+taken anymore, so verify that your callbacks do not rely on it (none
+of the in-tree instances did).  inode_hash_lock is still held,
+of course, so they are still serialized wrt removal from inode hash,
+as well as wrt set() callback of iget5_locked().
+
+---
+
+**mandatory**
+
+d_materialise_unique() is gone; d_splice_alias() does everything you
+need now.  Remember that they have opposite orders of arguments ;-/
+
+---
+
+**mandatory**
+
+f_dentry is gone; use f_path.dentry, or, better yet, see if you can avoid
+it entirely.
+
+---
+
+**mandatory**
+
+never call ->read() and ->write() directly; use __vfs_{read,write} or
+wrappers; instead of checking for ->write or ->read being NULL, look for
+FMODE_CAN_{WRITE,READ} in file->f_mode.
+
+---
+
+**mandatory**
+
+do _not_ use new_sync_{read,write} for ->read/->write; leave it NULL
+instead.
+
+---
+
+**mandatory**
 	->aio_read/->aio_write are gone.  Use ->read_iter/->write_iter.
+
+---
+
+**recommended**
+
+for embedded ("fast") symlinks just set inode->i_link to wherever the
+symlink body is and use simple_follow_link() as ->follow_link().
+
+---
+
+**mandatory**
+
+calling conventions for ->follow_link() have changed.  Instead of returning
+cookie and using nd_set_link() to store the body to traverse, we return
+the body to traverse and store the cookie using explicit void ** argument.
+nameidata isn't passed at all - nd_jump_link() doesn't need it and
+nd_[gs]et_link() is gone.
+
+---
+
+**mandatory**
+
+calling conventions for ->put_link() have changed.  It gets inode instead of
+dentry,  it does not get nameidata at all and it gets called only when cookie
+is non-NULL.  Note that link body isn't available anymore, so if you need it,
+store it as cookie.
+
+---
+
+**mandatory**
+
+any symlink that might use page_follow_link_light/page_put_link() must
+have inode_nohighmem(inode) called before anything might start playing with
+its pagecache.  No highmem pages should end up in the pagecache of such
+symlinks.  That includes any preseeding that might be done during symlink
+creation.  __page_symlink() will honour the mapping gfp flags, so once
+you've done inode_nohighmem() it's safe to use, but if you allocate and
+insert the page manually, make sure to use the right gfp flags.
+
+---
+
+**mandatory**
+
+->follow_link() is replaced with ->get_link(); same API, except that
+
+	* ->get_link() gets inode as a separate argument
+	* ->get_link() may be called in RCU mode - in that case NULL
+	  dentry is passed
+
+---
+
+**mandatory**
+
+->get_link() gets struct delayed_call ``*done`` now, and should do
+set_delayed_call() where it used to set ``*cookie``.
+
+->put_link() is gone - just give the destructor to set_delayed_call()
+in ->get_link().
+
+---
+
+**mandatory**
+
+->getxattr() and xattr_handler.get() get dentry and inode passed separately.
+dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
+in the instances.  Rationale: !@#!@# security_d_instantiate() needs to be
+called before we attach dentry to inode.
+
+---
+
+**mandatory**
+
+symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/
+i_pipe/i_link union zeroed out at inode eviction.  As the result, you can't
+assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that
+it's a symlink.  Checking ->i_mode is really needed now.  In-tree we had
+to fix shmem_destroy_callback() that used to take that kind of shortcut;
+watch out, since that shortcut is no longer valid.
+
+---
+
+**mandatory**
+
+->i_mutex is replaced with ->i_rwsem now.  inode_lock() et.al. work as
+they used to - they just take it exclusive.  However, ->lookup() may be
+called with parent locked shared.  Its instances must not
+
+	* use d_instantiate) and d_rehash() separately - use d_add() or
+	  d_splice_alias() instead.
+	* use d_rehash() alone - call d_add(new_dentry, NULL) instead.
+	* in the unlikely case when (read-only) access to filesystem
+	  data structures needs exclusion for some reason, arrange it
+	  yourself.  None of the in-tree filesystems needed that.
+	* rely on ->d_parent and ->d_name not changing after dentry has
+	  been fed to d_add() or d_splice_alias().  Again, none of the
+	  in-tree instances relied upon that.
+
+We are guaranteed that lookups of the same name in the same directory
+will not happen in parallel ("same" in the sense of your ->d_compare()).
+Lookups on different names in the same directory can and do happen in
+parallel now.
+
 ---
-[recommended]
-	for embedded ("fast") symlinks just set inode->i_link to wherever the
-	symlink body is and use simple_follow_link() as ->follow_link().
---
-[mandatory]
-	calling conventions for ->follow_link() have changed.  Instead of returning
-	cookie and using nd_set_link() to store the body to traverse, we return
-	the body to traverse and store the cookie using explicit void ** argument.
-	nameidata isn't passed at all - nd_jump_link() doesn't need it and
-	nd_[gs]et_link() is gone.
---
-[mandatory]
-	calling conventions for ->put_link() have changed.  It gets inode instead of
-	dentry,  it does not get nameidata at all and it gets called only when cookie
-	is non-NULL.  Note that link body isn't available anymore, so if you need it,
-	store it as cookie.
---
-[mandatory]
-	any symlink that might use page_follow_link_light/page_put_link() must
-	have inode_nohighmem(inode) called before anything might start playing with
-	its pagecache.  No highmem pages should end up in the pagecache of such
-	symlinks.  That includes any preseeding that might be done during symlink
-	creation.  __page_symlink() will honour the mapping gfp flags, so once
-	you've done inode_nohighmem() it's safe to use, but if you allocate and
-	insert the page manually, make sure to use the right gfp flags.
---
-[mandatory]
-	->follow_link() is replaced with ->get_link(); same API, except that
-		* ->get_link() gets inode as a separate argument
-		* ->get_link() may be called in RCU mode - in that case NULL
-		  dentry is passed
---
-[mandatory]
-	->get_link() gets struct delayed_call *done now, and should do
-	set_delayed_call() where it used to set *cookie.
-	->put_link() is gone - just give the destructor to set_delayed_call()
-	in ->get_link().
---
-[mandatory]
-	->getxattr() and xattr_handler.get() get dentry and inode passed separately.
-	dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
-	in the instances.  Rationale: !@#!@# security_d_instantiate() needs to be
-	called before we attach dentry to inode.
---
-[mandatory]
-	symlinks are no longer the only inodes that do *not* have i_bdev/i_cdev/
-	i_pipe/i_link union zeroed out at inode eviction.  As the result, you can't
-	assume that non-NULL value in ->i_nlink at ->destroy_inode() implies that
-	it's a symlink.  Checking ->i_mode is really needed now.  In-tree we had
-	to fix shmem_destroy_callback() that used to take that kind of shortcut;
-	watch out, since that shortcut is no longer valid.
---
-[mandatory]
-	->i_mutex is replaced with ->i_rwsem now.  inode_lock() et.al. work as
-	they used to - they just take it exclusive.  However, ->lookup() may be
-	called with parent locked shared.  Its instances must not
-		* use d_instantiate) and d_rehash() separately - use d_add() or
-		  d_splice_alias() instead.
-		* use d_rehash() alone - call d_add(new_dentry, NULL) instead.
-		* in the unlikely case when (read-only) access to filesystem
-		  data structures needs exclusion for some reason, arrange it
-		  yourself.  None of the in-tree filesystems needed that.
-		* rely on ->d_parent and ->d_name not changing after dentry has
-		  been fed to d_add() or d_splice_alias().  Again, none of the
-		  in-tree instances relied upon that.
-	We are guaranteed that lookups of the same name in the same directory
-	will not happen in parallel ("same" in the sense of your ->d_compare()).
-	Lookups on different names in the same directory can and do happen in
-	parallel now.
---
-[recommended]
-	->iterate_shared() is added; it's a parallel variant of ->iterate().
-	Exclusion on struct file level is still provided (as well as that
-	between it and lseek on the same struct file), but if your directory
-	has been opened several times, you can get these called in parallel.
-	Exclusion between that method and all directory-modifying ones is
-	still provided, of course.
-
-	Often enough ->iterate() can serve as ->iterate_shared() without any
-	changes - it is a read-only operation, after all.  If you have any
-	per-inode or per-dentry in-core data structures modified by ->iterate(),
-	you might need something to serialize the access to them.  If you
-	do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for
-	that; look for in-tree examples.
-
-	Old method is only used if the new one is absent; eventually it will
-	be removed.  Switch while you still can; the old one won't stay.
---
-[mandatory]
-	->atomic_open() calls without O_CREAT may happen in parallel.
---
-[mandatory]
-	->setxattr() and xattr_handler.set() get dentry and inode passed separately.
-	dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
-	in the instances.  Rationale: !@#!@# security_d_instantiate() needs to be
-	called before we attach dentry to inode and !@#!@##!@$!$#!@#$!@$!@$ smack
-	->d_instantiate() uses not just ->getxattr() but ->setxattr() as well.
---
-[mandatory]
-	->d_compare() doesn't get parent as a separate argument anymore.  If you
-	used it for finding the struct super_block involved, dentry->d_sb will
-	work just as well; if it's something more complicated, use dentry->d_parent.
-	Just be careful not to assume that fetching it more than once will yield
-	the same value - in RCU mode it could change under you.
---
-[mandatory]
-	->rename() has an added flags argument.  Any flags not handled by the
-        filesystem should result in EINVAL being returned.
---
-[recommended]
-	->readlink is optional for symlinks.  Don't set, unless filesystem needs
-	to fake something for readlink(2).
---
-[mandatory]
-	->getattr() is now passed a struct path rather than a vfsmount and
-	dentry separately, and it now has request_mask and query_flags arguments
-	to specify the fields and sync type requested by statx.  Filesystems not
-	supporting any statx-specific features may ignore the new arguments.
---
-[mandatory]
-	->atomic_open() calling conventions have changed.  Gone is int *opened,
-	along with FILE_OPENED/FILE_CREATED.  In place of those we have
-	FMODE_OPENED/FMODE_CREATED, set in file->f_mode.  Additionally, return
-	value for 'called finish_no_open(), open it yourself' case has become
-	0, not 1.  Since finish_no_open() itself is returning 0 now, that part
-	does not need any changes in ->atomic_open() instances.
---
-[mandatory]
-	alloc_file() has become static now; two wrappers are to be used instead.
-	alloc_file_pseudo(inode, vfsmount, name, flags, ops) is for the cases
-	when dentry needs to be created; that's the majority of old alloc_file()
-	users.  Calling conventions: on success a reference to new struct file
-	is returned and callers reference to inode is subsumed by that.  On
-	failure, ERR_PTR() is returned and no caller's references are affected,
-	so the caller needs to drop the inode reference it held.
-	alloc_file_clone(file, flags, ops) does not affect any caller's references.
-	On success you get a new struct file sharing the mount/dentry with the
-	original, on failure - ERR_PTR().
---
-[mandatory]
-	->clone_file_range() and ->dedupe_file_range have been replaced with
-	->remap_file_range().  See Documentation/filesystems/vfs.rst for more
-	information.
---
-[recommended]
-	->lookup() instances doing an equivalent of
-		if (IS_ERR(inode))
-			return ERR_CAST(inode);
-		return d_splice_alias(inode, dentry);
-	don't need to bother with the check - d_splice_alias() will do the
-	right thing when given ERR_PTR(...) as inode.  Moreover, passing NULL
-	inode to d_splice_alias() will also do the right thing (equivalent of
-	d_add(dentry, NULL); return NULL;), so that kind of special cases
-	also doesn't need a separate treatment.
---
-[strongly recommended]
-	take the RCU-delayed parts of ->destroy_inode() into a new method -
-	->free_inode().  If ->destroy_inode() becomes empty - all the better,
-	just get rid of it.  Synchronous work (e.g. the stuff that can't
-	be done from an RCU callback, or any WARN_ON() where we want the
-	stack trace) *might* be movable to ->evict_inode(); however,
-	that goes only for the things that are not needed to balance something
-	done by ->alloc_inode().  IOW, if it's cleaning up the stuff that
-	might have accumulated over the life of in-core inode, ->evict_inode()
-	might be a fit.
-
-	Rules for inode destruction:
-		* if ->destroy_inode() is non-NULL, it gets called
-		* if ->free_inode() is non-NULL, it gets scheduled by call_rcu()
-		* combination of NULL ->destroy_inode and NULL ->free_inode is
-		  treated as NULL/free_inode_nonrcu, to preserve the compatibility.
-
-	Note that the callback (be it via ->free_inode() or explicit call_rcu()
-	in ->destroy_inode()) is *NOT* ordered wrt superblock destruction;
-	as the matter of fact, the superblock and all associated structures
-	might be already gone.  The filesystem driver is guaranteed to be still
-	there, but that's it.  Freeing memory in the callback is fine; doing
-	more than that is possible, but requires a lot of care and is best
-	avoided.
---
-[mandatory]
-	DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the
-	default.  DCACHE_NORCU opts out, and only d_alloc_pseudo() has any
-	business doing so.
---
-[mandatory]
-	d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are
-	very suspect (and won't work in modules).  Such uses are very likely to
-	be misspelled d_alloc_anon().
+
+**recommended**
+
+->iterate_shared() is added; it's a parallel variant of ->iterate().
+Exclusion on struct file level is still provided (as well as that
+between it and lseek on the same struct file), but if your directory
+has been opened several times, you can get these called in parallel.
+Exclusion between that method and all directory-modifying ones is
+still provided, of course.
+
+Often enough ->iterate() can serve as ->iterate_shared() without any
+changes - it is a read-only operation, after all.  If you have any
+per-inode or per-dentry in-core data structures modified by ->iterate(),
+you might need something to serialize the access to them.  If you
+do dcache pre-seeding, you'll need to switch to d_alloc_parallel() for
+that; look for in-tree examples.
+
+Old method is only used if the new one is absent; eventually it will
+be removed.  Switch while you still can; the old one won't stay.
+
+---
+
+**mandatory**
+
+->atomic_open() calls without O_CREAT may happen in parallel.
+
+---
+
+**mandatory**
+
+->setxattr() and xattr_handler.set() get dentry and inode passed separately.
+dentry might be yet to be attached to inode, so do _not_ use its ->d_inode
+in the instances.  Rationale: !@#!@# security_d_instantiate() needs to be
+called before we attach dentry to inode and !@#!@##!@$!$#!@#$!@$!@$ smack
+->d_instantiate() uses not just ->getxattr() but ->setxattr() as well.
+
+---
+
+**mandatory**
+
+->d_compare() doesn't get parent as a separate argument anymore.  If you
+used it for finding the struct super_block involved, dentry->d_sb will
+work just as well; if it's something more complicated, use dentry->d_parent.
+Just be careful not to assume that fetching it more than once will yield
+the same value - in RCU mode it could change under you.
+
+---
+
+**mandatory**
+
+->rename() has an added flags argument.  Any flags not handled by the
+filesystem should result in EINVAL being returned.
+
+---
+
+
+**recommended**
+
+->readlink is optional for symlinks.  Don't set, unless filesystem needs
+to fake something for readlink(2).
+
+---
+
+**mandatory**
+
+->getattr() is now passed a struct path rather than a vfsmount and
+dentry separately, and it now has request_mask and query_flags arguments
+to specify the fields and sync type requested by statx.  Filesystems not
+supporting any statx-specific features may ignore the new arguments.
+
+---
+
+**mandatory**
+
+->atomic_open() calling conventions have changed.  Gone is ``int *opened``,
+along with FILE_OPENED/FILE_CREATED.  In place of those we have
+FMODE_OPENED/FMODE_CREATED, set in file->f_mode.  Additionally, return
+value for 'called finish_no_open(), open it yourself' case has become
+0, not 1.  Since finish_no_open() itself is returning 0 now, that part
+does not need any changes in ->atomic_open() instances.
+
+---
+
+**mandatory**
+
+alloc_file() has become static now; two wrappers are to be used instead.
+alloc_file_pseudo(inode, vfsmount, name, flags, ops) is for the cases
+when dentry needs to be created; that's the majority of old alloc_file()
+users.  Calling conventions: on success a reference to new struct file
+is returned and callers reference to inode is subsumed by that.  On
+failure, ERR_PTR() is returned and no caller's references are affected,
+so the caller needs to drop the inode reference it held.
+alloc_file_clone(file, flags, ops) does not affect any caller's references.
+On success you get a new struct file sharing the mount/dentry with the
+original, on failure - ERR_PTR().
+
+---
+
+**mandatory**
+
+->clone_file_range() and ->dedupe_file_range have been replaced with
+->remap_file_range().  See Documentation/filesystems/vfs.rst for more
+information.
+
+---
+
+**recommended**
+
+->lookup() instances doing an equivalent of::
+
+	if (IS_ERR(inode))
+		return ERR_CAST(inode);
+	return d_splice_alias(inode, dentry);
+
+don't need to bother with the check - d_splice_alias() will do the
+right thing when given ERR_PTR(...) as inode.  Moreover, passing NULL
+inode to d_splice_alias() will also do the right thing (equivalent of
+d_add(dentry, NULL); return NULL;), so that kind of special cases
+also doesn't need a separate treatment.
+
+---
+
+**strongly recommended**
+
+take the RCU-delayed parts of ->destroy_inode() into a new method -
+->free_inode().  If ->destroy_inode() becomes empty - all the better,
+just get rid of it.  Synchronous work (e.g. the stuff that can't
+be done from an RCU callback, or any WARN_ON() where we want the
+stack trace) *might* be movable to ->evict_inode(); however,
+that goes only for the things that are not needed to balance something
+done by ->alloc_inode().  IOW, if it's cleaning up the stuff that
+might have accumulated over the life of in-core inode, ->evict_inode()
+might be a fit.
+
+Rules for inode destruction:
+
+	* if ->destroy_inode() is non-NULL, it gets called
+	* if ->free_inode() is non-NULL, it gets scheduled by call_rcu()
+	* combination of NULL ->destroy_inode and NULL ->free_inode is
+	  treated as NULL/free_inode_nonrcu, to preserve the compatibility.
+
+Note that the callback (be it via ->free_inode() or explicit call_rcu()
+in ->destroy_inode()) is *NOT* ordered wrt superblock destruction;
+as the matter of fact, the superblock and all associated structures
+might be already gone.  The filesystem driver is guaranteed to be still
+there, but that's it.  Freeing memory in the callback is fine; doing
+more than that is possible, but requires a lot of care and is best
+avoided.
+
+---
+
+**mandatory**
+
+DCACHE_RCUACCESS is gone; having an RCU delay on dentry freeing is the
+default.  DCACHE_NORCU opts out, and only d_alloc_pseudo() has any
+business doing so.
+
+---
+
+**mandatory**
+
+d_alloc_pseudo() is internal-only; uses outside of alloc_file_pseudo() are
+very suspect (and won't work in modules).  Such uses are very likely to
+be misspelled d_alloc_anon().
diff --git a/fs/orangefs/orangefs-kernel.h b/fs/orangefs/orangefs-kernel.h
index 572dd29fbd54..34a6c99fa29b 100644
--- a/fs/orangefs/orangefs-kernel.h
+++ b/fs/orangefs/orangefs-kernel.h
@@ -246,7 +246,7 @@ struct orangefs_read_options {
 extern struct orangefs_stats orangefs_stats;
 
 /*
- * NOTE: See Documentation/filesystems/porting for information
+ * NOTE: See Documentation/filesystems/porting.rst for information
  * on implementing FOO_I and properly accessing fs private data
  */
 static inline struct orangefs_inode_s *ORANGEFS_I(struct inode *inode)
-- 
2.21.0


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

* [PATCH v2 19/26] docs: index.rst: don't use genindex for pdf output
  2019-07-26 12:51 ` Mauro Carvalho Chehab
@ 2019-07-26 12:51   ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Vinod Koul, Sanyog Kale,
	Pierre-Louis Bossart, David S. Miller, Jaroslav Kysela,
	Takashi Iwai, linux-doc, dmaengine, alsa-devel, netdev

The genindex logic is meant to be used only for html output, as
pdf build has its own way to generate indexes.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Vinod Koul <vkoul@kernel.org> # dmaengine and soundwire
---
 Documentation/core-api/index.rst                  | 2 +-
 Documentation/driver-api/dmaengine/index.rst      | 2 +-
 Documentation/driver-api/soundwire/index.rst      | 2 +-
 Documentation/networking/device_drivers/index.rst | 2 +-
 Documentation/networking/index.rst                | 2 +-
 Documentation/sound/index.rst                     | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index dfd8fad1e1ec..fa16a0538dcb 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -49,7 +49,7 @@ Interfaces for kernel debugging
    debug-objects
    tracepoint
 
-.. only::  subproject
+.. only:: subproject and html
 
    Indices
    =======
diff --git a/Documentation/driver-api/dmaengine/index.rst b/Documentation/driver-api/dmaengine/index.rst
index 3026fa975937..b9df904d0a79 100644
--- a/Documentation/driver-api/dmaengine/index.rst
+++ b/Documentation/driver-api/dmaengine/index.rst
@@ -47,7 +47,7 @@ This book adds some notes about PXA DMA
 
    pxa_dma
 
-.. only::  subproject
+.. only::  subproject and html
 
    Indices
    =======
diff --git a/Documentation/driver-api/soundwire/index.rst b/Documentation/driver-api/soundwire/index.rst
index 6db026028f27..234911a0db99 100644
--- a/Documentation/driver-api/soundwire/index.rst
+++ b/Documentation/driver-api/soundwire/index.rst
@@ -10,7 +10,7 @@ SoundWire Documentation
    error_handling
    locking
 
-.. only::  subproject
+.. only::  subproject and html
 
    Indices
    =======
diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst
index 2b7fefe72351..f724b7c69b9e 100644
--- a/Documentation/networking/device_drivers/index.rst
+++ b/Documentation/networking/device_drivers/index.rst
@@ -24,7 +24,7 @@ Contents:
    google/gve
    mellanox/mlx5
 
-.. only::  subproject
+.. only::  subproject and html
 
    Indices
    =======
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index a46fca264bee..6739066acadb 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -31,7 +31,7 @@ Contents:
    tls
    tls-offload
 
-.. only::  subproject
+.. only::  subproject and html
 
    Indices
    =======
diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst
index 47b89f014e69..4d7d42acf6df 100644
--- a/Documentation/sound/index.rst
+++ b/Documentation/sound/index.rst
@@ -12,7 +12,7 @@ Linux Sound Subsystem Documentation
    hd-audio/index
    cards/index
 
-.. only::  subproject
+.. only::  subproject and html
 
    Indices
    =======
-- 
2.21.0


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

* [PATCH v2 19/26] docs: index.rst: don't use genindex for pdf output
@ 2019-07-26 12:51   ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Vinod Koul, Sanyog Kale,
	Pierre-Louis Bossart, David S. Miller, Jaroslav Kysela,
	Takashi Iwai, linux-doc, dmaengine, alsa-devel, netdev

The genindex logic is meant to be used only for html output, as
pdf build has its own way to generate indexes.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Vinod Koul <vkoul@kernel.org> # dmaengine and soundwire
---
 Documentation/core-api/index.rst                  | 2 +-
 Documentation/driver-api/dmaengine/index.rst      | 2 +-
 Documentation/driver-api/soundwire/index.rst      | 2 +-
 Documentation/networking/device_drivers/index.rst | 2 +-
 Documentation/networking/index.rst                | 2 +-
 Documentation/sound/index.rst                     | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index dfd8fad1e1ec..fa16a0538dcb 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -49,7 +49,7 @@ Interfaces for kernel debugging
    debug-objects
    tracepoint
 
-.. only::  subproject
+.. only:: subproject and html
 
    Indices
    =======
diff --git a/Documentation/driver-api/dmaengine/index.rst b/Documentation/driver-api/dmaengine/index.rst
index 3026fa975937..b9df904d0a79 100644
--- a/Documentation/driver-api/dmaengine/index.rst
+++ b/Documentation/driver-api/dmaengine/index.rst
@@ -47,7 +47,7 @@ This book adds some notes about PXA DMA
 
    pxa_dma
 
-.. only::  subproject
+.. only::  subproject and html
 
    Indices
    =======
diff --git a/Documentation/driver-api/soundwire/index.rst b/Documentation/driver-api/soundwire/index.rst
index 6db026028f27..234911a0db99 100644
--- a/Documentation/driver-api/soundwire/index.rst
+++ b/Documentation/driver-api/soundwire/index.rst
@@ -10,7 +10,7 @@ SoundWire Documentation
    error_handling
    locking
 
-.. only::  subproject
+.. only::  subproject and html
 
    Indices
    =======
diff --git a/Documentation/networking/device_drivers/index.rst b/Documentation/networking/device_drivers/index.rst
index 2b7fefe72351..f724b7c69b9e 100644
--- a/Documentation/networking/device_drivers/index.rst
+++ b/Documentation/networking/device_drivers/index.rst
@@ -24,7 +24,7 @@ Contents:
    google/gve
    mellanox/mlx5
 
-.. only::  subproject
+.. only::  subproject and html
 
    Indices
    =======
diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst
index a46fca264bee..6739066acadb 100644
--- a/Documentation/networking/index.rst
+++ b/Documentation/networking/index.rst
@@ -31,7 +31,7 @@ Contents:
    tls
    tls-offload
 
-.. only::  subproject
+.. only::  subproject and html
 
    Indices
    =======
diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst
index 47b89f014e69..4d7d42acf6df 100644
--- a/Documentation/sound/index.rst
+++ b/Documentation/sound/index.rst
@@ -12,7 +12,7 @@ Linux Sound Subsystem Documentation
    hd-audio/index
    cards/index
 
-.. only::  subproject
+.. only::  subproject and html
 
    Indices
    =======
-- 
2.21.0

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

* [PATCH v2 20/26] docs: wimax: convert to ReST and add to admin-guide
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (23 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Inaky Perez-Gonzalez,
	linux-wimax, linux-doc

Manually convert wimax documentation to ReST and add theit
to the Kernel doc body, inside the admin-guide.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/admin-guide/index.rst           |   1 +
 .../wimax/i2400m.rst}                         | 145 ++++++++++--------
 Documentation/admin-guide/wimax/index.rst     |  19 +++
 .../wimax/wimax.rst}                          |  36 +++--
 MAINTAINERS                                   |   4 +-
 5 files changed, 128 insertions(+), 77 deletions(-)
 rename Documentation/{wimax/README.i2400m => admin-guide/wimax/i2400m.rst} (69%)
 create mode 100644 Documentation/admin-guide/wimax/index.rst
 rename Documentation/{wimax/README.wimax => admin-guide/wimax/wimax.rst} (74%)

diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 6e6c23b6193a..083b7cc80ee4 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -107,6 +107,7 @@ configure specific aspects of kernel behavior to your liking.
    pnp
    rtc
    svga
+   wimax/index
    video-output
 
 .. only::  subproject and html
diff --git a/Documentation/wimax/README.i2400m b/Documentation/admin-guide/wimax/i2400m.rst
similarity index 69%
rename from Documentation/wimax/README.i2400m
rename to Documentation/admin-guide/wimax/i2400m.rst
index 7dffd8919cb0..194388c0c351 100644
--- a/Documentation/wimax/README.i2400m
+++ b/Documentation/admin-guide/wimax/i2400m.rst
@@ -1,18 +1,23 @@
+.. include:: <isonum.txt>
 
-   Driver for the Intel Wireless Wimax Connection 2400m
+====================================================
+Driver for the Intel Wireless Wimax Connection 2400m
+====================================================
 
-   (C) 2008 Intel Corporation < linux-wimax@intel.com >
+:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com >
 
    This provides a driver for the Intel Wireless WiMAX Connection 2400m
    and a basic Linux kernel WiMAX stack.
 
 1. Requirements
+===============
 
      * Linux installation with Linux kernel 2.6.22 or newer (if building
        from a separate tree)
      * Intel i2400m Echo Peak or Baxter Peak; this includes the Intel
        Wireless WiMAX/WiFi Link 5x50 series.
      * build tools:
+
           + Linux kernel development package for the target kernel; to
             build against your currently running kernel, you need to have
             the kernel development package corresponding to the running
@@ -22,8 +27,10 @@
           + GNU C Compiler, make
 
 2. Compilation and installation
+===============================
 
 2.1. Compilation of the drivers included in the kernel
+------------------------------------------------------
 
    Configure the kernel; to enable the WiMAX drivers select Drivers >
    Networking Drivers > WiMAX device support. Enable all of them as
@@ -36,37 +43,39 @@
    Compile and install your kernel as usual.
 
 2.2. Compilation of the drivers distributed as an standalone module
+-------------------------------------------------------------------
 
-   To compile
+   To compile::
 
-$ cd source/directory
-$ make
+	$ cd source/directory
+	$ make
 
    Once built you can load and unload using the provided load.sh script;
    load.sh will load the modules, load.sh u will unload them.
 
    To install in the default kernel directories (and enable auto loading
-   when the device is plugged):
+   when the device is plugged)::
 
-$ make install
-$ depmod -a
+	$ make install
+	$ depmod -a
 
    If your kernel development files are located in a non standard
    directory or if you want to build for a kernel that is not the
-   currently running one, set KDIR to the right location:
+   currently running one, set KDIR to the right location::
 
-$ make KDIR=/path/to/kernel/dev/tree
+	$ make KDIR=/path/to/kernel/dev/tree
 
    For more information, please contact linux-wimax@intel.com.
 
 3. Installing the firmware
+--------------------------
 
    The firmware can be obtained from http://linuxwimax.org or might have
    been supplied with your hardware.
 
-   It has to be installed in the target system:
-     *
-$ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
+   It has to be installed in the target system::
+
+	$ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
 
      * NOTE: if your firmware came in an .rpm or .deb file, just install
        it as normal, with the rpm (rpm -i FIRMWARE.rpm) or dpkg
@@ -76,6 +85,7 @@ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
        with other types.
 
 4. Design
+=========
 
    This package contains two major parts: a WiMAX kernel stack and a
    driver for the Intel i2400m.
@@ -102,16 +112,17 @@ $ cp FIRMWAREFILE.sbcf /lib/firmware/i2400m-fw-BUSTYPE-1.3.sbcf
    API calls should be replaced with the target OS's.
 
 5. Usage
+========
 
    To load the driver, follow the instructions in the install section;
    once the driver is loaded, plug in the device (unless it is permanently
    plugged in). The driver will enumerate the device, upload the firmware
    and output messages in the kernel log (dmesg, /var/log/messages or
-   /var/log/kern.log) such as:
+   /var/log/kern.log) such as::
 
-...
-i2400m_usb 5-4:1.0: firmware interface version 8.0.0
-i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
+	...
+	i2400m_usb 5-4:1.0: firmware interface version 8.0.0
+	i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
 
    At this point the device is ready to work.
 
@@ -120,38 +131,42 @@ i2400m_usb 5-4:1.0: WiMAX interface wmx0 (00:1d:e1:01:94:2c) ready
    on how to scan, connect and disconnect.
 
 5.1. Module parameters
+----------------------
 
    Module parameters can be set at kernel or module load time or by
-   echoing values:
+   echoing values::
 
-$ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME
+	$ echo VALUE > /sys/module/MODULENAME/parameters/PARAMETERNAME
 
    To make changes permanent, for example, for the i2400m module, you can
-   also create a file named /etc/modprobe.d/i2400m containing:
+   also create a file named /etc/modprobe.d/i2400m containing::
 
-options i2400m idle_mode_disabled=1
+	options i2400m idle_mode_disabled=1
 
-   To find which parameters are supported by a module, run:
+   To find which parameters are supported by a module, run::
 
-$ modinfo path/to/module.ko
+	$ modinfo path/to/module.ko
 
    During kernel bootup (if the driver is linked in the kernel), specify
-   the following to the kernel command line:
+   the following to the kernel command line::
 
-i2400m.PARAMETER=VALUE
+	i2400m.PARAMETER=VALUE
 
 5.1.1. i2400m: idle_mode_disabled
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
    The i2400m module supports a parameter to disable idle mode. This
    parameter, once set, will take effect only when the device is
    reinitialized by the driver (eg: following a reset or a reconnect).
 
 5.2. Debug operations: debugfs entries
+--------------------------------------
 
    The driver will register debugfs entries that allow the user to tweak
    debug settings. There are three main container directories where
    entries are placed, which correspond to the three blocks a i2400m WiMAX
    driver has:
+
      * /sys/kernel/debug/wimax:DEVNAME/ for the generic WiMAX stack
        controls
      * /sys/kernel/debug/wimax:DEVNAME/i2400m for the i2400m generic
@@ -163,52 +178,55 @@ i2400m.PARAMETER=VALUE
    /sys/kernel/debug, those paths will change.
 
 5.2.1. Increasing debug output
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
    The files named *dl_* indicate knobs for controlling the debug output
-   of different submodules:
-     *
-# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw
-/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_rx
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_fw
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_driver
-/sys/kernel/debug/wimax:wmx0/i2400m/dl_control
-/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
-/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
-/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
+   of different submodules::
+
+	# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
+	/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_tx
+	/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_rx
+	/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_notif
+	/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_fw
+	/sys/kernel/debug/wimax:wmx0/i2400m-usb/dl_usb
+	/sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
+	/sys/kernel/debug/wimax:wmx0/i2400m/dl_rx
+	/sys/kernel/debug/wimax:wmx0/i2400m/dl_rfkill
+	/sys/kernel/debug/wimax:wmx0/i2400m/dl_netdev
+	/sys/kernel/debug/wimax:wmx0/i2400m/dl_fw
+	/sys/kernel/debug/wimax:wmx0/i2400m/dl_debugfs
+	/sys/kernel/debug/wimax:wmx0/i2400m/dl_driver
+	/sys/kernel/debug/wimax:wmx0/i2400m/dl_control
+	/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
+	/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
+	/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
+	/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
+	/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
+	/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
 
    By reading the file you can obtain the current value of said debug
    level; by writing to it, you can set it.
 
    To increase the debug level of, for example, the i2400m's generic TX
-   engine, just write:
+   engine, just write::
 
-$ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
+	$ echo 3 > /sys/kernel/debug/wimax:wmx0/i2400m/dl_tx
 
    Increasing numbers yield increasing debug information; for details of
    what is printed and the available levels, check the source. The code
    uses 0 for disabled and increasing values until 8.
 
 5.2.2. RX and TX statistics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
    The i2400m/rx_stats and i2400m/tx_stats provide statistics about the
-   data reception/delivery from the device:
+   data reception/delivery from the device::
 
-$ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
-45 1 3 34 3104 48 480
+	$ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
+	45 1 3 34 3104 48 480
+
+   The numbers reported are:
 
-   The numbers reported are
      * packets/RX-buffer: total, min, max
      * RX-buffers: total RX buffers received, accumulated RX buffer size
        in bytes, min size received, max size received
@@ -216,9 +234,9 @@ $ cat /sys/kernel/debug/wimax:wmx0/i2400m/rx_stats
    Thus, to find the average buffer size received, divide accumulated
    RX-buffer / total RX-buffers.
 
-   To clear the statistics back to 0, write anything to the rx_stats file:
+   To clear the statistics back to 0, write anything to the rx_stats file::
 
-$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
+	$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
 
    Likewise for TX.
 
@@ -227,14 +245,16 @@ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m_rx_stats
    to the host. See drivers/net/wimax/i2400m/tx.c.
 
 5.2.3. Tracing messages received from user space
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
    To echo messages received from user space into the trace pipe that the
    i2400m driver creates, set the debug file i2400m/trace_msg_from_user to
-   1:
-     *
-$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
+   1::
+
+	$ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
 
 5.2.4. Performing a device reset
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
    By writing a 0, a 1 or a 2 to the file
    /sys/kernel/debug/wimax:wmx0/reset, the driver performs a warm (without
@@ -242,18 +262,21 @@ $ echo 1 > /sys/kernel/debug/wimax:wmx0/i2400m/trace_msg_from_user
    (bus specific) reset on the device.
 
 5.2.5. Asking the device to enter power saving mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
    By writing any value to the /sys/kernel/debug/wimax:wmx0 file, the
    device will attempt to enter power saving mode.
 
 6. Troubleshooting
+==================
 
-6.1. Driver complains about 'i2400m-fw-usb-1.2.sbcf: request failed'
+6.1. Driver complains about ``i2400m-fw-usb-1.2.sbcf: request failed``
+----------------------------------------------------------------------
 
    If upon connecting the device, the following is output in the kernel
-   log:
+   log::
 
-i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2
+	i2400m_usb 5-4:1.0: fw i2400m-fw-usb-1.3.sbcf: request failed: -2
 
    This means that the driver cannot locate the firmware file named
    /lib/firmware/i2400m-fw-usb-1.2.sbcf. Check that the file is present in
diff --git a/Documentation/admin-guide/wimax/index.rst b/Documentation/admin-guide/wimax/index.rst
new file mode 100644
index 000000000000..fdf7c1f99ff5
--- /dev/null
+++ b/Documentation/admin-guide/wimax/index.rst
@@ -0,0 +1,19 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============
+WiMAX subsystem
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   wimax
+
+   i2400m
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/wimax/README.wimax b/Documentation/admin-guide/wimax/wimax.rst
similarity index 74%
rename from Documentation/wimax/README.wimax
rename to Documentation/admin-guide/wimax/wimax.rst
index b78c4378084e..817ee8ba2732 100644
--- a/Documentation/wimax/README.wimax
+++ b/Documentation/admin-guide/wimax/wimax.rst
@@ -1,12 +1,16 @@
+.. include:: <isonum.txt>
 
-   Linux kernel WiMAX stack
+========================
+Linux kernel WiMAX stack
+========================
 
-   (C) 2008 Intel Corporation < linux-wimax@intel.com >
+:Copyright: |copy| 2008 Intel Corporation < linux-wimax@intel.com >
 
    This provides a basic Linux kernel WiMAX stack to provide a common
    control API for WiMAX devices, usable from kernel and user space.
 
 1. Design
+=========
 
    The WiMAX stack is designed to provide for common WiMAX control
    services to current and future WiMAX devices from any vendor.
@@ -31,6 +35,7 @@
    include/linux/wimax.h.
 
 2. Usage
+========
 
    For usage in a driver (registration, API, etc) please refer to the
    instructions in the header file include/linux/wimax.h.
@@ -40,6 +45,7 @@
    control.
 
 2.1. Obtaining debug information: debugfs entries
+-------------------------------------------------
 
    The WiMAX stack is compiled, by default, with debug messages that can
    be used to diagnose issues. By default, said messages are disabled.
@@ -52,20 +58,22 @@
    create more subentries below it.
 
 2.1.1. Increasing debug output
+------------------------------
 
    The files named *dl_* indicate knobs for controlling the debug output
-   of different submodules of the WiMAX stack:
-     *
-# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
-/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
-/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
-/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
-/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
-/sys/kernel/debug/wimax:wmx0/.... # other driver specific files
+   of different submodules of the WiMAX stack::
 
-       NOTE: Of course, if debugfs is mounted in a directory other than
+	# find /sys/kernel/debug/wimax\:wmx0 -name \*dl_\*
+	/sys/kernel/debug/wimax:wmx0/wimax_dl_stack
+	/sys/kernel/debug/wimax:wmx0/wimax_dl_op_rfkill
+	/sys/kernel/debug/wimax:wmx0/wimax_dl_op_reset
+	/sys/kernel/debug/wimax:wmx0/wimax_dl_op_msg
+	/sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
+	/sys/kernel/debug/wimax:wmx0/wimax_dl_debugfs
+	/sys/kernel/debug/wimax:wmx0/.... # other driver specific files
+
+   NOTE:
+       Of course, if debugfs is mounted in a directory other than
        /sys/kernel/debug, those paths will change.
 
    By reading the file you can obtain the current value of said debug
@@ -74,7 +82,7 @@
    To increase the debug level of, for example, the id-table submodule,
    just write:
 
-$ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
+	$ echo 3 > /sys/kernel/debug/wimax:wmx0/wimax_dl_id_table
 
    Increasing numbers yield increasing debug information; for details of
    what is printed and the available levels, check the source. The code
diff --git a/MAINTAINERS b/MAINTAINERS
index b6b9d8c67987..c7656edee696 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8346,7 +8346,7 @@ M:	linux-wimax@intel.com
 L:	wimax@linuxwimax.org (subscribers-only)
 S:	Supported
 W:	http://linuxwimax.org
-F:	Documentation/wimax/README.i2400m
+F:	Documentation/admin-guide/wimax/i2400m.rst
 F:	drivers/net/wimax/i2400m/
 F:	include/uapi/linux/wimax/i2400m.h
 
@@ -17349,7 +17349,7 @@ M:	linux-wimax@intel.com
 L:	wimax@linuxwimax.org (subscribers-only)
 S:	Supported
 W:	http://linuxwimax.org
-F:	Documentation/wimax/README.wimax
+F:	Documentation/admin-guide/wimax/wimax.rst
 F:	include/linux/wimax/debug.h
 F:	include/net/wimax.h
 F:	include/uapi/linux/wimax.h
-- 
2.21.0


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

* [PATCH v2 21/26] docs: mips: add to the documentation body as ReST
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (24 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, Ralf Baechle,
	Paul Burton, James Hogan, linux-doc, linux-mips

Manually convert the AU1xxx_IDE.README file to ReST and add
to a MIPS book as part of the main documentation body.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Paul Burton <paul.burton@mips.com>
---
 Documentation/index.rst                       |  1 +
 .../{AU1xxx_IDE.README => au1xxx_ide.rst}     | 89 +++++++++++--------
 Documentation/mips/index.rst                  | 17 ++++
 3 files changed, 70 insertions(+), 37 deletions(-)
 rename Documentation/mips/{AU1xxx_IDE.README => au1xxx_ide.rst} (67%)
 create mode 100644 Documentation/mips/index.rst

diff --git a/Documentation/index.rst b/Documentation/index.rst
index de7be1c31450..1ff03833276a 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -149,6 +149,7 @@ implementation.
    ia64/index
    m68k/index
    powerpc/index
+   mips/index
    openrisc/index
    parisc/index
    riscv/index
diff --git a/Documentation/mips/AU1xxx_IDE.README b/Documentation/mips/au1xxx_ide.rst
similarity index 67%
rename from Documentation/mips/AU1xxx_IDE.README
rename to Documentation/mips/au1xxx_ide.rst
index ff675a1b1422..2f9c2cff6738 100644
--- a/Documentation/mips/AU1xxx_IDE.README
+++ b/Documentation/mips/au1xxx_ide.rst
@@ -1,7 +1,14 @@
-README for MIPS AU1XXX IDE driver - Released 2005-07-15
+.. include:: <isonum.txt>
+
+======================
+MIPS AU1XXX IDE driver
+======================
+
+Released 2005-07-15
+
+About
+=====
 
-ABOUT
------
 This file describes the 'drivers/ide/au1xxx-ide.c', related files and the
 services they provide.
 
@@ -10,17 +17,17 @@ the white or black list, go to the 'ADD NEW HARD DISC TO WHITE OR BLACK LIST'
 section.
 
 
-LICENSE
--------
+License
+=======
 
-Copyright (c) 2003-2005 AMD, Personal Connectivity Solutions
+:Copyright: |copy| 2003-2005 AMD, Personal Connectivity Solutions
 
 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 SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+THIS SOFTWARE IS PROVIDED ``AS IS`` AND ANY EXPRESS OR IMPLIED WARRANTIES,
 INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR
 BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
@@ -35,31 +42,35 @@ 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.
 
-Note: for more information, please refer "AMD Alchemy Au1200/Au1550 IDE
+Note:
+      for more information, please refer "AMD Alchemy Au1200/Au1550 IDE
       Interface and Linux Device Driver" Application Note.
 
 
-FILES, CONFIGS AND COMPATIBILITY
---------------------------------
+Files, Configs and Compatibility
+================================
 
 Two files are introduced:
 
   a) 'arch/mips/include/asm/mach-au1x00/au1xxx_ide.h'
      contains : struct _auide_hwif
-                 timing parameters for PIO mode 0/1/2/3/4
-                 timing parameters for MWDMA 0/1/2
+
+                - timing parameters for PIO mode 0/1/2/3/4
+                - timing parameters for MWDMA 0/1/2
 
   b) 'drivers/ide/mips/au1xxx-ide.c'
      contains the functionality of the AU1XXX IDE driver
 
 Following extra configs variables are introduced:
 
-  CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA    - enable the PIO+DBDMA mode
-  CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA  - enable the MWDMA mode
+  CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA
+	- enable the PIO+DBDMA mode
+  CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA
+	- enable the MWDMA mode
 
 
-SUPPORTED IDE MODES
--------------------
+Supported IDE Modes
+===================
 
 The AU1XXX IDE driver supported all PIO modes - PIO mode 0/1/2/3/4 - and all
 MWDMA modes - MWDMA 0/1/2 -. There is no support for SWDMA and UDMA mode.
@@ -69,20 +80,21 @@ To change the PIO mode use the program hdparm with option -p, e.g.
 -X, e.g. 'hdparm -X32 [device]' for MWDMA mode 0.
 
 
-PERFORMANCE CONFIGURATIONS
---------------------------
+Performance Configurations
+==========================
 
-If the used system doesn't need USB support enable the following kernel configs:
+If the used system doesn't need USB support enable the following kernel
+configs::
 
-CONFIG_IDE=y
-CONFIG_BLK_DEV_IDE=y
-CONFIG_IDE_GENERIC=y
-CONFIG_BLK_DEV_IDEPCI=y
-CONFIG_BLK_DEV_GENERIC=y
-CONFIG_BLK_DEV_IDEDMA_PCI=y
-CONFIG_BLK_DEV_IDE_AU1XXX=y
-CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
-CONFIG_BLK_DEV_IDEDMA=y
+    CONFIG_IDE=y
+    CONFIG_BLK_DEV_IDE=y
+    CONFIG_IDE_GENERIC=y
+    CONFIG_BLK_DEV_IDEPCI=y
+    CONFIG_BLK_DEV_GENERIC=y
+    CONFIG_BLK_DEV_IDEDMA_PCI=y
+    CONFIG_BLK_DEV_IDE_AU1XXX=y
+    CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
+    CONFIG_BLK_DEV_IDEDMA=y
 
 Also define 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to enable
 the burst support on DBDMA controller.
@@ -90,20 +102,22 @@ the burst support on DBDMA controller.
 If the used system need the USB support enable the following kernel configs for
 high IDE to USB throughput.
 
-CONFIG_IDE_GENERIC=y
-CONFIG_BLK_DEV_IDEPCI=y
-CONFIG_BLK_DEV_GENERIC=y
-CONFIG_BLK_DEV_IDEDMA_PCI=y
-CONFIG_BLK_DEV_IDE_AU1XXX=y
-CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
-CONFIG_BLK_DEV_IDEDMA=y
+::
+
+    CONFIG_IDE_GENERIC=y
+    CONFIG_BLK_DEV_IDEPCI=y
+    CONFIG_BLK_DEV_GENERIC=y
+    CONFIG_BLK_DEV_IDEDMA_PCI=y
+    CONFIG_BLK_DEV_IDE_AU1XXX=y
+    CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y
+    CONFIG_BLK_DEV_IDEDMA=y
 
 Also undefine 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to
 disable the burst support on DBDMA controller.
 
 
-ACKNOWLEDGMENTS
----------------
+Acknowledgments
+===============
 
 These drivers wouldn't have been done without the base of kernel 2.4.x AU1XXX
 IDE driver from AMD.
@@ -112,4 +126,5 @@ Additional input also from:
 Matthias Lenk <matthias.lenk@amd.com>
 
 Happy hacking!
+
 Enrico Walther <enrico.walther@amd.com>
diff --git a/Documentation/mips/index.rst b/Documentation/mips/index.rst
new file mode 100644
index 000000000000..fd9023c8a89f
--- /dev/null
+++ b/Documentation/mips/index.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================
+MIPS architecture
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   au1xxx_ide
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
-- 
2.21.0


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

* [PATCH v2 22/26] docs: hwmon: pxe1610: convert to ReST format and add to the index
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (25 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jean Delvare, Guenter Roeck,
	Jonathan Corbet, linux-hwmon, linux-doc

This document was recently introduced. Convert it to ReST
just like the other hwmon documents, adding it to the hwmon index.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/hwmon/index.rst                |  1 +
 Documentation/hwmon/{pxe1610 => pxe1610.rst} | 33 +++++++++++++++-----
 2 files changed, 26 insertions(+), 8 deletions(-)
 rename Documentation/hwmon/{pxe1610 => pxe1610.rst} (82%)

diff --git a/Documentation/hwmon/index.rst b/Documentation/hwmon/index.rst
index ee090e51653a..4d5f5fec43a3 100644
--- a/Documentation/hwmon/index.rst
+++ b/Documentation/hwmon/index.rst
@@ -130,6 +130,7 @@ Hardware Monitoring Kernel Drivers
    pcf8591
    pmbus
    powr1220
+   pxe1610
    pwm-fan
    raspberrypi-hwmon
    sch5627
diff --git a/Documentation/hwmon/pxe1610 b/Documentation/hwmon/pxe1610.rst
similarity index 82%
rename from Documentation/hwmon/pxe1610
rename to Documentation/hwmon/pxe1610.rst
index 211cedeefb44..4f2388840d06 100644
--- a/Documentation/hwmon/pxe1610
+++ b/Documentation/hwmon/pxe1610.rst
@@ -2,19 +2,29 @@ Kernel driver pxe1610
 =====================
 
 Supported chips:
+
   * Infineon PXE1610
+
     Prefix: 'pxe1610'
+
     Addresses scanned: -
+
     Datasheet: Datasheet is not publicly available.
 
   * Infineon PXE1110
+
     Prefix: 'pxe1110'
+
     Addresses scanned: -
+
     Datasheet: Datasheet is not publicly available.
 
   * Infineon PXM1310
+
     Prefix: 'pxm1310'
+
     Addresses scanned: -
+
     Datasheet: Datasheet is not publicly available.
 
 Author: Vijay Khemka <vijaykhemka@fb.com>
@@ -25,14 +35,19 @@ Description
 
 PXE1610/PXE1110 are Multi-rail/Multiphase Digital Controllers
 and compliant to
-	-- Intel VR13 DC-DC converter specifications.
-	-- Intel SVID protocol.
+
+	- Intel VR13 DC-DC converter specifications.
+	- Intel SVID protocol.
+
 Used for Vcore power regulation for Intel VR13 based microprocessors
-	-- Servers, Workstations, and High-end desktops
+
+	- Servers, Workstations, and High-end desktops
 
 PXM1310 is a Multi-rail Controller and it is compliant to
-	-- Intel VR13 DC-DC converter specifications.
-	-- Intel SVID protocol.
+
+	- Intel VR13 DC-DC converter specifications.
+	- Intel SVID protocol.
+
 Used for DDR3/DDR4 Memory power regulation for Intel VR13 and
 IMVP8 based systems
 
@@ -44,10 +59,10 @@ This driver does not probe for PMBus devices. You will have
 to instantiate devices explicitly.
 
 Example: the following commands will load the driver for an PXE1610
-at address 0x70 on I2C bus #4:
+at address 0x70 on I2C bus #4::
 
-# modprobe pxe1610
-# echo pxe1610 0x70 > /sys/bus/i2c/devices/i2c-4/new_device
+    # modprobe pxe1610
+    # echo pxe1610 0x70 > /sys/bus/i2c/devices/i2c-4/new_device
 
 It can also be instantiated by declaring in device tree
 
@@ -55,6 +70,7 @@ It can also be instantiated by declaring in device tree
 Sysfs attributes
 ----------------
 
+======================  ====================================
 curr1_label		"iin"
 curr1_input		Measured input current
 curr1_alarm		Current high alarm
@@ -88,3 +104,4 @@ temp[1-3]_crit		Critical high temperature
 temp[1-3]_crit_alarm	Chip temperature critical high alarm
 temp[1-3]_max		Maximum temperature
 temp[1-3]_max_alarm	Chip temperature high alarm
+======================  ====================================
-- 
2.21.0


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

* [PATCH v2 23/26] docs: nios2: add it to the main Documentation body
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (26 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, Jonathan Corbet, linux-doc

Rename and add the nios2 documentation to the documentation
body.

The nios2 document is already on an ReST compatible format.
All it needs is that the title of the document to be promoted
one level.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/index.rst                   | 1 +
 Documentation/nios2/{README => nios2.rst} | 1 +
 2 files changed, 2 insertions(+)
 rename Documentation/nios2/{README => nios2.rst} (96%)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 1ff03833276a..d963db84fc42 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -150,6 +150,7 @@ implementation.
    m68k/index
    powerpc/index
    mips/index
+   nios2/nios2
    openrisc/index
    parisc/index
    riscv/index
diff --git a/Documentation/nios2/README b/Documentation/nios2/nios2.rst
similarity index 96%
rename from Documentation/nios2/README
rename to Documentation/nios2/nios2.rst
index 054a67d55563..43da3f7cee76 100644
--- a/Documentation/nios2/README
+++ b/Documentation/nios2/nios2.rst
@@ -1,3 +1,4 @@
+=================================
 Linux on the Nios II architecture
 =================================
 
-- 
2.21.0


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

* [PATCH v2 24/26] docs: net: convert two README files to ReST format
  2019-07-26 12:51 ` Mauro Carvalho Chehab
                   ` (27 preceding siblings ...)
  (?)
@ 2019-07-26 12:51 ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 12:51 UTC (permalink / raw)
  Cc: Mauro Carvalho Chehab, David S. Miller, Jonathan Corbet,
	Johannes Berg, netdev, linux-doc, linux-wireless

There are two README files there with doesn't have a .txt
extension nor are at ReST format.

In order to help with the docs conversion to ReST, rename those
and manually convert them to ReST format.

As there are lot more to be done for networking to be part of
the documentation body, for now mark those two files with
:orphan:, in order to supress a build warning.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 .../networking/caif/{README => caif.rst}      | 88 +++++++++++++------
 .../{README => mac80211_hwsim.rst}            | 28 ++++--
 MAINTAINERS                                   |  2 +-
 3 files changed, 81 insertions(+), 37 deletions(-)
 rename Documentation/networking/caif/{README => caif.rst} (70%)
 rename Documentation/networking/mac80211_hwsim/{README => mac80211_hwsim.rst} (81%)

diff --git a/Documentation/networking/caif/README b/Documentation/networking/caif/caif.rst
similarity index 70%
rename from Documentation/networking/caif/README
rename to Documentation/networking/caif/caif.rst
index 757ccfaa1385..07afc8063d4d 100644
--- a/Documentation/networking/caif/README
+++ b/Documentation/networking/caif/caif.rst
@@ -1,18 +1,31 @@
-Copyright (C) ST-Ericsson AB 2010
-Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
-License terms: GNU General Public License (GPL) version 2
----------------------------------------------------------
+:orphan:
 
-=== Start ===
-If you have compiled CAIF for modules do:
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
 
-$modprobe crc_ccitt
-$modprobe caif
-$modprobe caif_socket
-$modprobe chnl_net
 
+================
+Using Linux CAIF
+================
 
-=== Preparing the setup with a STE modem ===
+
+:Copyright: |copy| ST-Ericsson AB 2010
+
+:Author: Sjur Brendeland/ sjur.brandeland@stericsson.com
+
+Start
+=====
+
+If you have compiled CAIF for modules do::
+
+    $modprobe crc_ccitt
+    $modprobe caif
+    $modprobe caif_socket
+    $modprobe chnl_net
+
+
+Preparing the setup with a STE modem
+====================================
 
 If you are working on integration of CAIF you should make sure
 that the kernel is built with module support.
@@ -32,24 +45,30 @@ module parameter "ser_use_stx".
 Normally Frame Checksum is always used on UART, but this is also provided as a
 module parameter "ser_use_fcs".
 
-$ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
-$ ifconfig caif_ttyS0 up
+::
 
-PLEASE NOTE: 	There is a limitation in Android shell.
+    $ modprobe caif_serial ser_ttyname=/dev/ttyS0 ser_use_stx=yes
+    $ ifconfig caif_ttyS0 up
+
+PLEASE NOTE:
+		There is a limitation in Android shell.
 		It only accepts one argument to insmod/modprobe!
 
-=== Trouble shooting ===
+Trouble shooting
+================
 
 There are debugfs parameters provided for serial communication.
 /sys/kernel/debug/caif_serial/<tty-name>/
 
 * ser_state:   Prints the bit-mask status where
+
   - 0x02 means SENDING, this is a transient state.
   - 0x10 means FLOW_OFF_SENT, i.e. the previous frame has not been sent
-	and is blocking further send operation. Flow OFF has been propagated
-	to all CAIF Channels using this TTY.
+    and is blocking further send operation. Flow OFF has been propagated
+    to all CAIF Channels using this TTY.
 
 * tty_status: Prints the bit-mask tty status information
+
   - 0x01 - tty->warned is on.
   - 0x02 - tty->low_latency is on.
   - 0x04 - tty->packed is on.
@@ -58,13 +77,17 @@ There are debugfs parameters provided for serial communication.
   - 0x20 - tty->stopped is on.
 
 * last_tx_msg: Binary blob Prints the last transmitted frame.
-	This can be printed with
+
+  This can be printed with::
+
 	$od --format=x1 /sys/kernel/debug/caif_serial/<tty>/last_rx_msg.
-	The first two tx messages sent look like this. Note: The initial
-	byte 02 is start of frame extension (STX) used for re-syncing
-	upon errors.
 
-  - Enumeration:
+  The first two tx messages sent look like this. Note: The initial
+  byte 02 is start of frame extension (STX) used for re-syncing
+  upon errors.
+
+  - Enumeration::
+
         0000000  02 05 00 00 03 01 d2 02
                  |  |     |  |  |  |
                  STX(1)   |  |  |  |
@@ -73,7 +96,9 @@ There are debugfs parameters provided for serial communication.
                              Command:Enumeration(1)
                                 Link-ID(1)
                                     Checksum(2)
-  - Channel Setup:
+
+  - Channel Setup::
+
         0000000  02 07 00 00 00 21 a1 00 48 df
                  |  |     |  |  |  |  |  |
                  STX(1)   |  |  |  |  |  |
@@ -86,13 +111,18 @@ There are debugfs parameters provided for serial communication.
 					  Checksum(2)
 
 * last_rx_msg: Prints the last transmitted frame.
-	The RX messages for LinkSetup look almost identical but they have the
-	bit 0x20 set in the command bit, and Channel Setup has added one byte
-	before Checksum containing Channel ID.
-	NOTE: Several CAIF Messages might be concatenated. The maximum debug
+
+  The RX messages for LinkSetup look almost identical but they have the
+  bit 0x20 set in the command bit, and Channel Setup has added one byte
+  before Checksum containing Channel ID.
+
+  NOTE:
+	Several CAIF Messages might be concatenated. The maximum debug
 	buffer size is 128 bytes.
 
-== Error Scenarios:
+Error Scenarios
+===============
+
 - last_tx_msg contains channel setup message and last_rx_msg is empty ->
   The host seems to be able to send over the UART, at least the CAIF ldisc get
   notified that sending is completed.
@@ -103,7 +133,9 @@ There are debugfs parameters provided for serial communication.
 
 - if /sys/kernel/debug/caif_serial/<tty>/tty_status is non-zero there
   might be problems transmitting over UART.
+
   E.g. host and modem wiring is not correct you will typically see
   tty_status = 0x10 (hw_stopped) and ser_state = 0x10 (FLOW_OFF_SENT).
+
   You will probably see the enumeration message in last_tx_message
   and empty last_rx_message.
diff --git a/Documentation/networking/mac80211_hwsim/README b/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
similarity index 81%
rename from Documentation/networking/mac80211_hwsim/README
rename to Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
index 3566a725d19c..d2266ce5534e 100644
--- a/Documentation/networking/mac80211_hwsim/README
+++ b/Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
@@ -1,5 +1,13 @@
+:orphan:
+
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===================================================================
 mac80211_hwsim - software simulator of 802.11 radio(s) for mac80211
-Copyright (c) 2008, Jouni Malinen <j@w1.fi>
+===================================================================
+
+:Copyright: |copy| 2008, Jouni Malinen <j@w1.fi>
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License version 2 as
@@ -7,6 +15,7 @@ published by the Free Software Foundation.
 
 
 Introduction
+============
 
 mac80211_hwsim is a Linux kernel module that can be used to simulate
 arbitrary number of IEEE 802.11 radios for mac80211. It can be used to
@@ -43,6 +52,7 @@ regardless of channel.
 
 
 Simple example
+==============
 
 This example shows how to use mac80211_hwsim to simulate two radios:
 one to act as an access point and the other as a station that
@@ -50,17 +60,19 @@ associates with the AP. hostapd and wpa_supplicant are used to take
 care of WPA2-PSK authentication. In addition, hostapd is also
 processing access point side of association.
 
+::
 
-# Build mac80211_hwsim as part of kernel configuration
 
-# Load the module
-modprobe mac80211_hwsim
+    # Build mac80211_hwsim as part of kernel configuration
 
-# Run hostapd (AP) for wlan0
-hostapd hostapd.conf
+    # Load the module
+    modprobe mac80211_hwsim
 
-# Run wpa_supplicant (station) for wlan1
-wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf
+    # Run hostapd (AP) for wlan0
+    hostapd hostapd.conf
+
+    # Run wpa_supplicant (station) for wlan1
+    wpa_supplicant -Dnl80211 -iwlan1 -c wpa_supplicant.conf
 
 
 More test cases are available in hostap.git:
diff --git a/MAINTAINERS b/MAINTAINERS
index c7656edee696..4de2f288d1ec 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -9568,7 +9568,7 @@ F:	Documentation/networking/mac80211-injection.txt
 F:	include/net/mac80211.h
 F:	net/mac80211/
 F:	drivers/net/wireless/mac80211_hwsim.[ch]
-F:	Documentation/networking/mac80211_hwsim/README
+F:	Documentation/networking/mac80211_hwsim/mac80211_hwsim.rst
 
 MAILBOX API
 M:	Jassi Brar <jassisinghbrar@gmail.com>
-- 
2.21.0


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

* Re: [PATCH v2 00/26] ReST conversion of text files without .txt extension
  2019-07-26 12:51 ` Mauro Carvalho Chehab
  (?)
  (?)
@ 2019-07-26 13:05   ` Mauro Carvalho Chehab
  -1 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 13:05 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: linux-doc, linux-kernel, linux-pm, linux-arm-kernel,
	linux-samsung-soc, linux-pci, linuxppc-dev, linux-scsi,
	devicetree, linux-i2c, linux-hwmon, linux-spi, linux-iio,
	linux-rtc, netdev, linux-parisc, openrisc, devel, linux-cifs,
	samba-technical, devel, dmaengine, alsa-devel, linux-mips,
	linux-wireless, rcu

Em Fri, 26 Jul 2019 09:51:10 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:

> This series converts the text files under Documentation with doesn't end
> neither .txt or .rst and are not part of ABI or features.
> 
> This series is at:
> 	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3
> 
> And it is based on yesterday's upstream tree.
> 
> After this series, we have ~320 files left to be converted to ReST.
> 
> v2:
>   - Added 3 files submitted for v5.3 that weren't merged yet;
>   - markdown patch broken into two, per Rob's request;
>   - rebased on the top of upstream master branch
> 
> Mauro Carvalho Chehab (26):

>   docs: ABI: remove extension from sysfs-class-mic.txt

    ^ In time: this one was already merged.

Thanks,
Mauro

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

* Re: [PATCH v2 00/26] ReST conversion of text files without .txt extension
@ 2019-07-26 13:05   ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 13:05 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: linux-wireless, alsa-devel, linux-doc, linux-iio, linux-pci,
	linux-mips, linux-i2c, devel, linux-cifs, linux-samsung-soc,
	linux-scsi, devel, devicetree, linux-pm, rcu, openrisc,
	linux-arm-kernel, linux-hwmon, linux-parisc, netdev,
	samba-technical, linux-kernel, linux-spi, dmaengine,
	linuxppc-dev, linux-rtc

Em Fri, 26 Jul 2019 09:51:10 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:

> This series converts the text files under Documentation with doesn't end
> neither .txt or .rst and are not part of ABI or features.
> 
> This series is at:
> 	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3
> 
> And it is based on yesterday's upstream tree.
> 
> After this series, we have ~320 files left to be converted to ReST.
> 
> v2:
>   - Added 3 files submitted for v5.3 that weren't merged yet;
>   - markdown patch broken into two, per Rob's request;
>   - rebased on the top of upstream master branch
> 
> Mauro Carvalho Chehab (26):

>   docs: ABI: remove extension from sysfs-class-mic.txt

    ^ In time: this one was already merged.

Thanks,
Mauro

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

* Re: [PATCH v2 00/26] ReST conversion of text files without .txt extension
@ 2019-07-26 13:05   ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 13:05 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: linux-wireless, alsa-devel, linux-doc, linux-iio, linux-pci,
	linux-mips, linux-i2c, devel, linux-cifs, linux-samsung-soc,
	linux-scsi, devel, devicetree, linux-pm, rcu, openrisc,
	linux-arm-kernel, linux-hwmon, linux-parisc, netdev,
	samba-technical, linux-kernel, linux-spi, dmaengine,
	linuxppc-dev, linux-rtc

Em Fri, 26 Jul 2019 09:51:10 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:

> This series converts the text files under Documentation with doesn't end
> neither .txt or .rst and are not part of ABI or features.
> 
> This series is at:
> 	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3
> 
> And it is based on yesterday's upstream tree.
> 
> After this series, we have ~320 files left to be converted to ReST.
> 
> v2:
>   - Added 3 files submitted for v5.3 that weren't merged yet;
>   - markdown patch broken into two, per Rob's request;
>   - rebased on the top of upstream master branch
> 
> Mauro Carvalho Chehab (26):

>   docs: ABI: remove extension from sysfs-class-mic.txt

    ^ In time: this one was already merged.

Thanks,
Mauro

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

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

* [OpenRISC] [PATCH v2 00/26] ReST conversion of text files without .txt extension
@ 2019-07-26 13:05   ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 13:05 UTC (permalink / raw)
  To: openrisc

Em Fri, 26 Jul 2019 09:51:10 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> escreveu:

> This series converts the text files under Documentation with doesn't end
> neither .txt or .rst and are not part of ABI or features.
> 
> This series is at:
> 	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rst_for_5_4_v3
> 
> And it is based on yesterday's upstream tree.
> 
> After this series, we have ~320 files left to be converted to ReST.
> 
> v2:
>   - Added 3 files submitted for v5.3 that weren't merged yet;
>   - markdown patch broken into two, per Rob's request;
>   - rebased on the top of upstream master branch
> 
> Mauro Carvalho Chehab (26):

>   docs: ABI: remove extension from sysfs-class-mic.txt

    ^ In time: this one was already merged.

Thanks,
Mauro

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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
       [not found]     ` <20190726140028.38abb5fa@coco.lan>
@ 2019-07-26 17:55       ` Joel Fernandes
  2019-07-26 18:45         ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 75+ messages in thread
From: Joel Fernandes @ 2019-07-26 17:55 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
	Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
	linux-doc

On Fri, Jul 26, 2019 at 02:00:28PM -0300, Mauro Carvalho Chehab wrote:
> Hi Joel,
> 
> Em Fri, 26 Jul 2019 12:20:02 -0400
> Joel Fernandes <joel@joelfernandes.org> escreveu:
> 
> > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > > There are 4 RCU articles that are written on html format.
> > > 
> > > The way they are, they can't be part of the Linux Kernel
> > > documentation body nor share the styles and pdf output.
> > > 
> > > So, convert them to ReST format.
> > > 
> > > This way, make htmldocs and make pdfdocs will produce a
> > > documentation output that will be like the original ones, but
> > > will be part of the Linux Kernel documentation body.
> > > 
> > > Part of the conversion was done with the help of pandoc, but
> > > the result had some broken things that had to be manually
> > > fixed.  
> > 
> > This looks Ok to me, but I also nervous something could have been done
> > incorrectly during the conversion.
> > 
> > Could you list what were the "some broken things" that you had to manually
> > fix to make reviewing easier?
> 
> There are a couple of things.
> 
> At least the pandoc's version I used here has a bug: its conversion 
> from html to ReST on those files only start after a <body> tag - or 
> when the first quiz table starts. I only discovered that adding a
> <body> at the beginning of the file solve this book at the last
> conversions.
> 
> So, for most html->ReST conversions, I manually converted the first
> part of the document, basically stripping html paragraph tags and
> by replacing highlights by the ReST syntax.
> 
> Also, all the quiz tables seem to assume some javascript macro or
> css style that would be hiding the answer part until the mouse moves
> to it. Such macro/css was not there at the kernel tree. So, the quiz
> answers have the same color as the background, making them invisible.
> Even if we had such macro/css, this is not portable for pdf/LaTeX output
> (and I'm not sure if this would work with ePub).
> 
> So, I ended by manually doing the table conversion.
> 
> Finally, I double-checked if the conversions ended ok, addressing any
> issues that might have heppened.
> 
> So, after both automatic conversion and manual fixes, I opened both the 
> html files produced by Sphinx and the original ones and compared them
> line per line (except for the indexes, as Sphinx produces them 
> automatically), in order to see if all information from the original 
> files will be there on a format close to what we have on other ReST
> files, fixing any pending issues if any.

Thanks, I am in the process of going through these docs today and will let
you know anything I find. It would be nice to include the above challenges in
the changelog as well.

Some reason 'make htmldocs' needed me to install a whole bunch of
dependencies this time around.

By the way, that tools/memory-model/Documentation/explanation.txt is a useful
little document. Well not really little with over 1000 lines ;-). But it
would certainly benefit from ReST's / htmldocs ability to jump to labels and
search, etc since it is so long..

thanks,

 - Joel







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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
       [not found] ` <8444797277eea7be474f40625bb190775a9cee33.1564145354.git.mchehab+samsung@kernel.org>
       [not found]   ` <20190726162002.GA146401@google.com>
@ 2019-07-26 18:02   ` Joel Fernandes
  2019-07-26 19:01     ` [PATCH] tools: memory-model: add it to the Documentation body Mauro Carvalho Chehab
  2019-07-26 19:14     ` [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST Mauro Carvalho Chehab
  2019-07-30 21:22   ` Paul E. McKenney
  2 siblings, 2 replies; 75+ messages in thread
From: Joel Fernandes @ 2019-07-26 18:02 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
	Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
	linux-doc

On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
[snip]
> +| until the assignment to ``gp``, by which time both fields are fully   |
> +| initialized. So reordering the assignments to ``p->a`` and ``p->b``   |
> +| cannot possibly cause any problems.                                   |
> ++-----------------------------------------------------------------------+
> +
> +It is tempting to assume that the reader need not do anything special to
> +control its accesses to the RCU-protected data, as shown in
> +``do_something_gp_buggy()`` below:
> +
> +   ::
> +
> +       1 bool do_something_gp_buggy(void)
> +       2 {
> +       3   rcu_read_lock();
> +       4   p = gp;  /* OPTIMIZATIONS GALORE!!! */
> +       5   if (p) {
> +       6     do_something(p->a, p->b);
> +       7     rcu_read_unlock();
> +       8     return true;
> +       9   }
> +      10   rcu_read_unlock();
> +      11   return false;
> +      12 }
> +
> +However, this temptation must be resisted because there are a
> +surprisingly large number of ways that the compiler (to say nothing of
> +`DEC Alpha CPUs <https://h71000.www7.hp.com/wizard/wiz_2637.html>`__)
> +can trip this code up. For but one example, if the compiler were short
> +of registers, it might choose to refetch from ``gp`` rather than keeping
> +a separate copy in ``p`` as follows:
> +
> +   ::
> +
> +       1 bool do_something_gp_buggy_optimized(void)
> +       2 {
> +       3   rcu_read_lock();
> +       4   if (gp) { /* OPTIMIZATIONS GALORE!!! */
> +       5     do_something(gp->a, gp->b);
> +       6     rcu_read_unlock();
> +       7     return true;
> +       8   }
> +       9   rcu_read_unlock();
> +      10   return false;
> +      11 }
> +
> +If this function ran concurrently with a series of updates that replaced
> +the current structure with a new one, the fetches of ``gp->a`` and
> +``gp->b`` might well come from two different structures, which could
> +cause serious confusion. To prevent this (and much else besides),
> +``do_something_gp()`` uses ``rcu_dereference()`` to fetch from ``gp``:
> +
> +   ::
> +
> +       1 bool do_something_gp(void)
> +       2 {
> +       3   rcu_read_lock();
> +       4   p = rcu_dereference(gp);
> +       5   if (p) {
> +       6     do_something(p->a, p->b);
> +       7     rcu_read_unlock();
> +       8     return true;
> +       9   }
> +      10   rcu_read_unlock();
> +      11   return false;
> +      12 }
> +
> +The ``rcu_dereference()`` uses volatile casts and (for DEC Alpha) memory
> +barriers in the Linux kernel. Should a `high-quality implementation of
> +C11 ``memory_order_consume``
> +[PDF] <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__
> +ever appear, then ``rcu_dereference()`` could be implemented as a
> +``memory_order_consume`` load. Regardless of the exact implementation, a
> +pointer fetched by ``rcu_dereference()`` may not be used outside of the
> +outermost RCU read-side critical section containing that
> +``rcu_dereference()``, unless protection of the corresponding data
> +element has been passed from RCU to some other synchronization
> +mechanism, most commonly locking or `reference
> +counting <https://www.kernel.org/doc/Documentation/RCU/rcuref.txt>`__.

From the make htmldocs output, this appears very poorly for me, I get
something like this in the browser:

The rcu_dereference() uses volatile casts and (for DEC Alpha) memory barriers
in the Linux kernel. Should a high-quality implementation of C11
``memory_order_consume` [PDF]
<http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__ ever
appear, then rcu_dereference() could be implemented as a memory_order_consume
load.

Is there a syntax issue here?

One more feedback,
the image under "RCU read-side critical section that started before the current
grace period:" should probably be blown up a bit.

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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
  2019-07-26 17:55       ` [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST Joel Fernandes
@ 2019-07-26 18:45         ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 18:45 UTC (permalink / raw)
  To: Joel Fernandes
  Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
	Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
	linux-doc

Em Fri, 26 Jul 2019 13:55:27 -0400
Joel Fernandes <joel@joelfernandes.org> escreveu:

> On Fri, Jul 26, 2019 at 02:00:28PM -0300, Mauro Carvalho Chehab wrote:
> > Hi Joel,
> > 
> > Em Fri, 26 Jul 2019 12:20:02 -0400
> > Joel Fernandes <joel@joelfernandes.org> escreveu:
> >   
> > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:  
> > > > There are 4 RCU articles that are written on html format.
> > > > 

> > > Could you list what were the "some broken things" that you had to manually
> > > fix to make reviewing easier?  
> > 
> > There are a couple of things.
> > 
> > At least the pandoc's version I used here has a bug: its conversion 
> > from html to ReST on those files only start after a <body> tag - or 
> > when the first quiz table starts. I only discovered that adding a
> > <body> at the beginning of the file solve this book at the last
> > conversions.
> > 
> > So, for most html->ReST conversions, I manually converted the first
> > part of the document, basically stripping html paragraph tags and
> > by replacing highlights by the ReST syntax.
> > 
> > Also, all the quiz tables seem to assume some javascript macro or
> > css style that would be hiding the answer part until the mouse moves
> > to it. Such macro/css was not there at the kernel tree. So, the quiz
> > answers have the same color as the background, making them invisible.
> > Even if we had such macro/css, this is not portable for pdf/LaTeX output
> > (and I'm not sure if this would work with ePub).
> > 
> > So, I ended by manually doing the table conversion.
> > 
> > Finally, I double-checked if the conversions ended ok, addressing any
> > issues that might have heppened.
> > 
> > So, after both automatic conversion and manual fixes, I opened both the 
> > html files produced by Sphinx and the original ones and compared them
> > line per line (except for the indexes, as Sphinx produces them 
> > automatically), in order to see if all information from the original 
> > files will be there on a format close to what we have on other ReST
> > files, fixing any pending issues if any.  
> 
> Thanks, I am in the process of going through these docs today and will let
> you know anything I find. It would be nice to include the above challenges in
> the changelog as well.

Ok, will add on a next spin - or if you prefer to pick via your tree - feel
free to add them.

> Some reason 'make htmldocs' needed me to install a whole bunch of
> dependencies this time around.

Yes, you need Sphinx, plus some LaTeX stuff - not only for PDF but
also due to some math expressions found on some books.

Just installing Sphinx + its dependencies is enough for this specific
book.

> By the way, that tools/memory-model/Documentation/explanation.txt is a useful
> little document. Well not really little with over 1000 lines ;-). But it
> would certainly benefit from ReST's / htmldocs ability to jump to labels and
> search, etc since it is so long..

tools/*/Documentation is currently out of the current docs build system.

Maybe if you pass SPHINXDIRS=../tools/memory-model/Documentation/ it
could allow you to build something out there.

Btw, did a quick hack here, just for testing:

	$ ln -sf ../tools/memory-model/Documentation/ Documentation/tools
	$ cp tools/memory-model/Documentation/explanation.txt tools/memory-model/Documentation/explanation.rst

Sphinx tried to build explanation.txt:

/devel/v4l/docs_temp/Documentation/tools/explanation.rst:116: WARNING: Unexpected indentation.
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:118: WARNING: Block quote ends without a blank line; unexpected unindent.
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:122: WARNING: Unexpected indentation.
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:127: WARNING: Unexpected indentation.
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:128: WARNING: Block quote ends without a blank line; unexpected unindent.
/devel/v4l/docs_temp/Documentation/tools/explanation.rst:228: WARNING: Unexpected indentation.
...

So, it shouldn't be too hard to add it, but some adjustments will
be needed, specially at the code blocks.

Btw, if you want to play with it, the enclosing patch should give you
a good start.

As there aren't many files there, I suspect that converting them to
ReST should not be hard.

Thanks,
Mauro


[PATCH RFC] tools/memory-model: add it to the Documentation body

Add the cheatsheet file to the Documentation body.

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

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 0a564f3c336e..03ff920ac1cb 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -36,6 +36,7 @@ trying to get it to work optimally on a given system.
 
    admin-guide/index
    kbuild/index
+   tools/index
 
 Firmware-related documentation
 ------------------------------
diff --git a/Documentation/tools/memory-model b/Documentation/tools/memory-model
new file mode 120000
index 000000000000..020ed38ce302
--- /dev/null
+++ b/Documentation/tools/memory-model
@@ -0,0 +1 @@
+../../tools/memory-model/Documentation/
\ No newline at end of file
diff --git a/tools/memory-model/Documentation/cheatsheet.rst b/tools/memory-model/Documentation/cheatsheet.rst
new file mode 100644
index 000000000000..35f8749b8a53
--- /dev/null
+++ b/tools/memory-model/Documentation/cheatsheet.rst
@@ -0,0 +1,36 @@
+===========
+Cheat Sheet
+===========
+
+::
+
+				    Prior Operation     Subsequent Operation
+				    ---------------  ---------------------------
+				 C  Self  R  W  RMW  Self  R  W  DR  DW  RMW  SV
+				--  ----  -  -  ---  ----  -  -  --  --  ---  --
+
+  Store, e.g., WRITE_ONCE()            Y                                       Y
+  Load, e.g., READ_ONCE()              Y                          Y   Y        Y
+  Unsuccessful RMW operation           Y                          Y   Y        Y
+  rcu_dereference()                    Y                          Y   Y        Y
+  Successful *_acquire()               R                   Y  Y   Y   Y    Y   Y
+  Successful *_release()         C        Y  Y    Y     W                      Y
+  smp_rmb()                               Y       R        Y      Y        R
+  smp_wmb()                                  Y    W           Y       Y    W
+  smp_mb() & synchronize_rcu()  CP        Y  Y    Y        Y  Y   Y   Y    Y
+  Successful full non-void RMW  CP     Y  Y  Y    Y     Y  Y  Y   Y   Y    Y   Y
+  smp_mb__before_atomic()       CP        Y  Y    Y        a  a   a   a    Y
+  smp_mb__after_atomic()        CP        a  a    Y        Y  Y   Y   Y    Y
+
+
+  Key:    C:      Ordering is cumulative
+	  P:      Ordering propagates
+	  R:      Read, for example, READ_ONCE(), or read portion of RMW
+	  W:      Write, for example, WRITE_ONCE(), or write portion of RMW
+	  Y:      Provides ordering
+	  a:      Provides ordering given intervening RMW atomic operation
+	  DR:     Dependent read (address dependency)
+	  DW:     Dependent write (address, data, or control dependency)
+	  RMW:    Atomic read-modify-write operation
+	  SELF:   Orders self, as opposed to accesses before and/or after
+	  SV:     Orders later accesses to the same variable
diff --git a/tools/memory-model/Documentation/cheatsheet.txt b/tools/memory-model/Documentation/cheatsheet.txt
deleted file mode 100644
index 33ba98d72b16..000000000000
--- a/tools/memory-model/Documentation/cheatsheet.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-                                  Prior Operation     Subsequent Operation
-                                  ---------------  ---------------------------
-                               C  Self  R  W  RMW  Self  R  W  DR  DW  RMW  SV
-                              --  ----  -  -  ---  ----  -  -  --  --  ---  --
-
-Store, e.g., WRITE_ONCE()            Y                                       Y
-Load, e.g., READ_ONCE()              Y                          Y   Y        Y
-Unsuccessful RMW operation           Y                          Y   Y        Y
-rcu_dereference()                    Y                          Y   Y        Y
-Successful *_acquire()               R                   Y  Y   Y   Y    Y   Y
-Successful *_release()         C        Y  Y    Y     W                      Y
-smp_rmb()                               Y       R        Y      Y        R
-smp_wmb()                                  Y    W           Y       Y    W
-smp_mb() & synchronize_rcu()  CP        Y  Y    Y        Y  Y   Y   Y    Y
-Successful full non-void RMW  CP     Y  Y  Y    Y     Y  Y  Y   Y   Y    Y   Y
-smp_mb__before_atomic()       CP        Y  Y    Y        a  a   a   a    Y
-smp_mb__after_atomic()        CP        a  a    Y        Y  Y   Y   Y    Y
-
-
-Key:	C:	Ordering is cumulative
-	P:	Ordering propagates
-	R:	Read, for example, READ_ONCE(), or read portion of RMW
-	W:	Write, for example, WRITE_ONCE(), or write portion of RMW
-	Y:	Provides ordering
-	a:	Provides ordering given intervening RMW atomic operation
-	DR:	Dependent read (address dependency)
-	DW:	Dependent write (address, data, or control dependency)
-	RMW:	Atomic read-modify-write operation
-	SELF:	Orders self, as opposed to accesses before and/or after
-	SV:	Orders later accesses to the same variable
diff --git a/tools/memory-model/Documentation/index.rst b/tools/memory-model/Documentation/index.rst
new file mode 100644
index 000000000000..23caee7a96cc
--- /dev/null
+++ b/tools/memory-model/Documentation/index.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========
+Linux Tools
+===========
+
+.. toctree::
+   :maxdepth: 1
+
+   cheatsheet
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`


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

* [PATCH] tools: memory-model: add it to the Documentation body
  2019-07-26 18:02   ` Joel Fernandes
@ 2019-07-26 19:01     ` Mauro Carvalho Chehab
  2019-07-27 14:14       ` Joel Fernandes
  2019-07-26 19:14     ` [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST Mauro Carvalho Chehab
  1 sibling, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 19:01 UTC (permalink / raw)
  To: Joel Fernandes, Linux Doc Mailing List
  Cc: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Alan Stern, Andrea Parri, Will Deacon,
	Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
	Jade Alglave, Luc Maranget, Paul E. McKenney, Akira Yokosawa,
	Daniel Lustig, Ingo Molnar, Jason Gunthorpe, SeongJae Park,
	linux-arch

The books at tools/memory-model/Documentation are very well
formatted. Congrats to the ones that wrote them!

The manual conversion to ReST is really trivial:

	- Add document titles;
	- change the bullets on some lists;
	- mark code blocks.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/core-api/refcount-vs-atomic.rst |   2 +-
 Documentation/index.rst                       |   1 +
 Documentation/tools/memory-model              |   1 +
 .../memory-model/Documentation/cheatsheet.rst |  36 +++++
 .../memory-model/Documentation/cheatsheet.txt |  30 ----
 .../{explanation.txt => explanation.rst}      | 151 ++++++++++--------
 tools/memory-model/Documentation/index.rst    |  20 +++
 .../{recipes.txt => recipes.rst}              |  41 ++---
 .../{references.txt => references.rst}        |  46 +++---
 tools/memory-model/README                     |  10 +-
 10 files changed, 192 insertions(+), 146 deletions(-)
 create mode 120000 Documentation/tools/memory-model
 create mode 100644 tools/memory-model/Documentation/cheatsheet.rst
 delete mode 100644 tools/memory-model/Documentation/cheatsheet.txt
 rename tools/memory-model/Documentation/{explanation.txt => explanation.rst} (97%)
 create mode 100644 tools/memory-model/Documentation/index.rst
 rename tools/memory-model/Documentation/{recipes.txt => recipes.rst} (96%)
 rename tools/memory-model/Documentation/{references.txt => references.rst} (71%)

diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst
index 976e85adffe8..7e6500a6fa76 100644
--- a/Documentation/core-api/refcount-vs-atomic.rst
+++ b/Documentation/core-api/refcount-vs-atomic.rst
@@ -17,7 +17,7 @@ in order to help maintainers validate their code against the change in
 these memory ordering guarantees.
 
 The terms used through this document try to follow the formal LKMM defined in
-tools/memory-model/Documentation/explanation.txt.
+tools/memory-model/Documentation/explanation.rst.
 
 memory-barriers.txt and atomic_t.txt provide more background to the
 memory ordering in general and for atomic operations specifically.
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 0a564f3c336e..03ff920ac1cb 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -36,6 +36,7 @@ trying to get it to work optimally on a given system.
 
    admin-guide/index
    kbuild/index
+   tools/index
 
 Firmware-related documentation
 ------------------------------
diff --git a/Documentation/tools/memory-model b/Documentation/tools/memory-model
new file mode 120000
index 000000000000..020ed38ce302
--- /dev/null
+++ b/Documentation/tools/memory-model
@@ -0,0 +1 @@
+../../tools/memory-model/Documentation/
\ No newline at end of file
diff --git a/tools/memory-model/Documentation/cheatsheet.rst b/tools/memory-model/Documentation/cheatsheet.rst
new file mode 100644
index 000000000000..35f8749b8a53
--- /dev/null
+++ b/tools/memory-model/Documentation/cheatsheet.rst
@@ -0,0 +1,36 @@
+===========
+Cheat Sheet
+===========
+
+::
+
+				    Prior Operation     Subsequent Operation
+				    ---------------  ---------------------------
+				 C  Self  R  W  RMW  Self  R  W  DR  DW  RMW  SV
+				--  ----  -  -  ---  ----  -  -  --  --  ---  --
+
+  Store, e.g., WRITE_ONCE()            Y                                       Y
+  Load, e.g., READ_ONCE()              Y                          Y   Y        Y
+  Unsuccessful RMW operation           Y                          Y   Y        Y
+  rcu_dereference()                    Y                          Y   Y        Y
+  Successful *_acquire()               R                   Y  Y   Y   Y    Y   Y
+  Successful *_release()         C        Y  Y    Y     W                      Y
+  smp_rmb()                               Y       R        Y      Y        R
+  smp_wmb()                                  Y    W           Y       Y    W
+  smp_mb() & synchronize_rcu()  CP        Y  Y    Y        Y  Y   Y   Y    Y
+  Successful full non-void RMW  CP     Y  Y  Y    Y     Y  Y  Y   Y   Y    Y   Y
+  smp_mb__before_atomic()       CP        Y  Y    Y        a  a   a   a    Y
+  smp_mb__after_atomic()        CP        a  a    Y        Y  Y   Y   Y    Y
+
+
+  Key:    C:      Ordering is cumulative
+	  P:      Ordering propagates
+	  R:      Read, for example, READ_ONCE(), or read portion of RMW
+	  W:      Write, for example, WRITE_ONCE(), or write portion of RMW
+	  Y:      Provides ordering
+	  a:      Provides ordering given intervening RMW atomic operation
+	  DR:     Dependent read (address dependency)
+	  DW:     Dependent write (address, data, or control dependency)
+	  RMW:    Atomic read-modify-write operation
+	  SELF:   Orders self, as opposed to accesses before and/or after
+	  SV:     Orders later accesses to the same variable
diff --git a/tools/memory-model/Documentation/cheatsheet.txt b/tools/memory-model/Documentation/cheatsheet.txt
deleted file mode 100644
index 33ba98d72b16..000000000000
--- a/tools/memory-model/Documentation/cheatsheet.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-                                  Prior Operation     Subsequent Operation
-                                  ---------------  ---------------------------
-                               C  Self  R  W  RMW  Self  R  W  DR  DW  RMW  SV
-                              --  ----  -  -  ---  ----  -  -  --  --  ---  --
-
-Store, e.g., WRITE_ONCE()            Y                                       Y
-Load, e.g., READ_ONCE()              Y                          Y   Y        Y
-Unsuccessful RMW operation           Y                          Y   Y        Y
-rcu_dereference()                    Y                          Y   Y        Y
-Successful *_acquire()               R                   Y  Y   Y   Y    Y   Y
-Successful *_release()         C        Y  Y    Y     W                      Y
-smp_rmb()                               Y       R        Y      Y        R
-smp_wmb()                                  Y    W           Y       Y    W
-smp_mb() & synchronize_rcu()  CP        Y  Y    Y        Y  Y   Y   Y    Y
-Successful full non-void RMW  CP     Y  Y  Y    Y     Y  Y  Y   Y   Y    Y   Y
-smp_mb__before_atomic()       CP        Y  Y    Y        a  a   a   a    Y
-smp_mb__after_atomic()        CP        a  a    Y        Y  Y   Y   Y    Y
-
-
-Key:	C:	Ordering is cumulative
-	P:	Ordering propagates
-	R:	Read, for example, READ_ONCE(), or read portion of RMW
-	W:	Write, for example, WRITE_ONCE(), or write portion of RMW
-	Y:	Provides ordering
-	a:	Provides ordering given intervening RMW atomic operation
-	DR:	Dependent read (address dependency)
-	DW:	Dependent write (address, data, or control dependency)
-	RMW:	Atomic read-modify-write operation
-	SELF:	Orders self, as opposed to accesses before and/or after
-	SV:	Orders later accesses to the same variable
diff --git a/tools/memory-model/Documentation/explanation.txt b/tools/memory-model/Documentation/explanation.rst
similarity index 97%
rename from tools/memory-model/Documentation/explanation.txt
rename to tools/memory-model/Documentation/explanation.rst
index 68caa9a976d0..227ec75f8dc4 100644
--- a/tools/memory-model/Documentation/explanation.txt
+++ b/tools/memory-model/Documentation/explanation.rst
@@ -1,5 +1,6 @@
+========================================================
 Explanation of the Linux-Kernel Memory Consistency Model
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+========================================================
 
 :Author: Alan Stern <stern@rowland.harvard.edu>
 :Created: October 2017
@@ -107,7 +108,7 @@ and the flag are memory locations shared between the two CPUs.
 
 We can abstract out the important pieces of the driver code as follows
 (the reason for using WRITE_ONCE() and READ_ONCE() instead of simple
-assignment statements is discussed later):
+assignment statements is discussed later)::
 
 	int buf = 0, flag = 0;
 
@@ -219,7 +220,7 @@ Ordering).  This model predicts that the undesired outcome for the MP
 pattern cannot occur, but in other respects it differs from Sequential
 Consistency.  One example is the Store Buffer (SB) pattern, in which
 each CPU stores to its own shared location and then loads from the
-other CPU's location:
+other CPU's location::
 
 	int x = 0, y = 0;
 
@@ -264,7 +265,7 @@ The counterpart to ordering is a cycle.  Ordering rules out cycles:
 It's not possible to have X ordered before Y, Y ordered before Z, and
 Z ordered before X, because this would mean that X is ordered before
 itself.  The analysis of the MP example under Sequential Consistency
-involved just such an impossible cycle:
+involved just such an impossible cycle::
 
 	W: P0 stores 1 to flag   executes before
 	X: P1 loads 1 from flag  executes before
@@ -388,7 +389,7 @@ The protections provided by READ_ONCE(), WRITE_ONCE(), and others are
 not perfect; and under some circumstances it is possible for the
 compiler to undermine the memory model.  Here is an example.  Suppose
 both branches of an "if" statement store the same value to the same
-location:
+location::
 
 	r1 = READ_ONCE(x);
 	if (r1) {
@@ -402,7 +403,7 @@ location:
 For this code, the LKMM predicts that the load from x will always be
 executed before either of the stores to y.  However, a compiler could
 lift the stores out of the conditional, transforming the code into
-something resembling:
+something resembling::
 
 	r1 = READ_ONCE(x);
 	WRITE_ONCE(y, 2);
@@ -418,7 +419,7 @@ model's original prediction could be invalidated by the compiler.
 
 Another issue arises from the fact that in C, arguments to many
 operators and function calls can be evaluated in any order.  For
-example:
+example::
 
 	r1 = f(5) + g(6);
 
@@ -440,7 +441,7 @@ control (ctrl).
 
 A read and a write event are linked by a data dependency if the value
 obtained by the read affects the value stored by the write.  As a very
-simple example:
+simple example::
 
 	int x, y;
 
@@ -455,7 +456,7 @@ values of multiple reads.
 A read event and another memory access event are linked by an address
 dependency if the value obtained by the read affects the location
 accessed by the other event.  The second event can be either a read or
-a write.  Here's another simple example:
+a write.  Here's another simple example::
 
 	int a[20];
 	int i;
@@ -471,7 +472,7 @@ pointer.
 
 Finally, a read event and another memory access event are linked by a
 control dependency if the value obtained by the read affects whether
-the second event is executed at all.  Simple example:
+the second event is executed at all.  Simple example::
 
 	int x, y;
 
@@ -510,7 +511,7 @@ Usage of the rf relation implicitly assumes that loads will always
 read from a single store.  It doesn't apply properly in the presence
 of load-tearing, where a load obtains some of its bits from one store
 and some of them from another store.  Fortunately, use of READ_ONCE()
-and WRITE_ONCE() will prevent load-tearing; it's not possible to have:
+and WRITE_ONCE() will prevent load-tearing; it's not possible to have::
 
 	int x = 0;
 
@@ -530,7 +531,7 @@ and end up with r1 = 0x1200 (partly from x's initial value and partly
 from the value stored by P0).
 
 On the other hand, load-tearing is unavoidable when mixed-size
-accesses are used.  Consider this example:
+accesses are used.  Consider this example::
 
 	union {
 		u32	w;
@@ -612,7 +613,7 @@ requirement that every store eventually becomes visible to every CPU.)
 Any reasonable memory model will include cache coherence.  Indeed, our
 expectation of cache coherence is so deeply ingrained that violations
 of its requirements look more like hardware bugs than programming
-errors:
+errors::
 
 	int x;
 
@@ -628,6 +629,8 @@ write-write coherence rule: Since the store of 23 comes later in
 program order, it must also come later in x's coherence order and
 thus must overwrite the store of 17.
 
+::
+
 	int x = 0;
 
 	P0()
@@ -644,6 +647,8 @@ program order, so it must not read from that store but rather from one
 coming earlier in the coherence order (in this case, x's initial
 value).
 
+::
+
 	int x = 0;
 
 	P0()
@@ -694,7 +699,7 @@ value that R reads is overwritten (directly or indirectly) by W, or
 equivalently, when R reads from a store which comes earlier than W in
 the coherence order.
 
-For example:
+For example::
 
 	int x = 0;
 
@@ -721,6 +726,8 @@ relations; it is not independent.  Given a read event R and a write
 event W for the same location, we will have R ->fr W if and only if
 the write which R reads from is co-before W.  In symbols,
 
+::
+
 	(R ->fr W) := (there exists W' with W' ->rf R and W' ->co W).
 
 
@@ -907,7 +914,7 @@ whenever we have X ->rf Y or X ->co Y or X ->fr Y or X ->po-loc Y, the
 X event comes before the Y event in the global ordering.  The LKMM's
 "coherence" axiom expresses this by requiring the union of these
 relations not to have any cycles.  This means it must not be possible
-to find events
+to find events::
 
 	X0 -> X1 -> X2 -> ... -> Xn -> X0,
 
@@ -929,7 +936,7 @@ this case) does not get altered between the read and the write events
 making up the atomic operation.  In particular, if two CPUs perform
 atomic_inc(&x) concurrently, it must be guaranteed that the final
 value of x will be the initial value plus two.  We should never have
-the following sequence of events:
+the following sequence of events::
 
 	CPU 0 loads x obtaining 13;
 					CPU 1 loads x obtaining 13;
@@ -951,6 +958,8 @@ atomic read-modify-write and W' is the write event which R reads from,
 there must not be any stores coming between W' and W in the coherence
 order.  Equivalently,
 
+::
+
 	(R ->rmw W) implies (there is no X with R ->fr X and X ->co W),
 
 where the rmw relation links the read and write events making up each
@@ -1021,7 +1030,7 @@ includes address dependencies to loads in the ppo relation.
 
 On the other hand, dependencies can indirectly affect the ordering of
 two loads.  This happens when there is a dependency from a load to a
-store and a second, po-later load reads from that store:
+store and a second, po-later load reads from that store::
 
 	R ->dep W ->rfi R',
 
@@ -1036,7 +1045,7 @@ R; if the speculation turns out to be wrong then the CPU merely has to
 restart or abandon R'.
 
 (In theory, a CPU might forward a store to a load when it runs across
-an address dependency like this:
+an address dependency like this::
 
 	r1 = READ_ONCE(ptr);
 	WRITE_ONCE(*r1, 17);
@@ -1048,7 +1057,7 @@ However, none of the architectures supported by the Linux kernel do
 this.)
 
 Two memory accesses of the same location must always be executed in
-program order if the second access is a store.  Thus, if we have
+program order if the second access is a store.  Thus, if we have::
 
 	R ->po-loc W
 
@@ -1056,7 +1065,7 @@ program order if the second access is a store.  Thus, if we have
 access the same location), the CPU is obliged to execute W after R.
 If it executed W first then the memory subsystem would respond to R's
 read request with the value stored by W (or an even later store), in
-violation of the read-write coherence rule.  Similarly, if we had
+violation of the read-write coherence rule.  Similarly, if we had::
 
 	W ->po-loc W'
 
@@ -1074,7 +1083,7 @@ AND THEN THERE WAS ALPHA
 
 As mentioned above, the Alpha architecture is unique in that it does
 not appear to respect address dependencies to loads.  This means that
-code such as the following:
+code such as the following::
 
 	int x = 0;
 	int y = -1;
@@ -1128,7 +1137,7 @@ nothing at all on non-Alpha builds) after every READ_ONCE() and atomic
 load.  The effect of the fence is to cause the CPU not to execute any
 po-later instructions until after the local cache has finished
 processing all the stores it has already received.  Thus, if the code
-was changed to:
+was changed to::
 
 	P1()
 	{
@@ -1199,7 +1208,7 @@ the first event in the coherence order and propagates to C before the
 second event executes.
 
 This is best explained with some examples.  The simplest case looks
-like this:
+like this::
 
 	int x;
 
@@ -1225,7 +1234,7 @@ event, because P1's store came after P0's store in x's coherence
 order, and P1's store propagated to P0 before P0's load executed.
 
 An equally simple case involves two loads of the same location that
-read from different stores:
+read from different stores::
 
 	int x = 0;
 
@@ -1252,7 +1261,7 @@ P1's store propagated to P0 before P0's second load executed.
 
 Less trivial examples of prop all involve fences.  Unlike the simple
 examples above, they can require that some instructions are executed
-out of program order.  This next one should look familiar:
+out of program order.  This next one should look familiar::
 
 	int buf = 0, flag = 0;
 
@@ -1303,7 +1312,7 @@ rfe link.  You can concoct more exotic examples, containing more than
 one fence, although this quickly leads to diminishing returns in terms
 of complexity.  For instance, here's an example containing a coe link
 followed by two fences and an rfe link, utilizing the fact that
-release fences are A-cumulative:
+release fences are A-cumulative::
 
 	int x, y, z;
 
@@ -1363,7 +1372,7 @@ links.  Let's see how this definition works out.
 
 Consider first the case where E is a store (implying that the sequence
 of links begins with coe).  Then there are events W, X, Y, and Z such
-that:
+that::
 
 	E ->coe W ->cumul-fence* X ->rfe? Y ->strong-fence Z ->hb* F,
 
@@ -1390,7 +1399,7 @@ request with the value stored by W or an even later store,
 contradicting the fact that E ->fre W.
 
 A good example illustrating how pb works is the SB pattern with strong
-fences:
+fences::
 
 	int x = 0, y = 0;
 
@@ -1449,18 +1458,18 @@ span a full grace period.  In more detail, the Guarantee says:
 	For any critical section C and any grace period G, at least
 	one of the following statements must hold:
 
-(1)	C ends before G does, and in addition, every store that
-	propagates to C's CPU before the end of C must propagate to
-	every CPU before G ends.
+	(1)	C ends before G does, and in addition, every store that
+		propagates to C's CPU before the end of C must propagate to
+		every CPU before G ends.
 
-(2)	G starts before C does, and in addition, every store that
-	propagates to G's CPU before the start of G must propagate
-	to every CPU before C starts.
+	(2)	G starts before C does, and in addition, every store that
+		propagates to G's CPU before the start of G must propagate
+		to every CPU before C starts.
 
 In particular, it is not possible for a critical section to both start
 before and end after a grace period.
 
-Here is a simple example of RCU in action:
+Here is a simple example of RCU in action::
 
 	int x, y;
 
@@ -1544,13 +1553,13 @@ the end of a critical section which starts before Z begins.
 The LKMM goes on to define the rcu-fence relation as a sequence of
 rcu-gp and rcu-rscsi links separated by rcu-link links, in which the
 number of rcu-gp links is >= the number of rcu-rscsi links.  For
-example:
+example::
 
 	X ->rcu-gp Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
 
 would imply that X ->rcu-fence V, because this sequence contains two
 rcu-gp links and one rcu-rscsi link.  (It also implies that
-X ->rcu-fence T and Z ->rcu-fence V.)  On the other hand:
+X ->rcu-fence T and Z ->rcu-fence V.)  On the other hand::
 
 	X ->rcu-rscsi Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
 
@@ -1566,7 +1575,7 @@ E must execute before F; in fact, each synchronize_rcu() fence event
 is linked to itself by rcu-fence as a degenerate case.)
 
 To prove this in full generality requires some intellectual effort.
-We'll consider just a very simple case:
+We'll consider just a very simple case::
 
 	G ->rcu-gp W ->rcu-link Z ->rcu-rscsi F.
 
@@ -1621,7 +1630,7 @@ question, and let S be the synchronize_rcu() fence event for the grace
 period.  Saying that the critical section starts before S means there
 are events Q and R where Q is po-after L (which marks the start of the
 critical section), Q is "before" R in the sense used by the rcu-link
-relation, and R is po-before the grace period S.  Thus we have:
+relation, and R is po-before the grace period S.  Thus we have::
 
 	L ->rcu-link S.
 
@@ -1629,20 +1638,20 @@ Let W be the store mentioned above, let Y come before the end of the
 critical section and witness that W propagates to the critical
 section's CPU by reading from W, and let Z on some arbitrary CPU be a
 witness that W has not propagated to that CPU, where Z happens after
-some event X which is po-after S.  Symbolically, this amounts to:
+some event X which is po-after S.  Symbolically, this amounts to::
 
 	S ->po X ->hb* Z ->fr W ->rf Y ->po U.
 
 The fr link from Z to W indicates that W has not propagated to Z's CPU
 at the time that Z executes.  From this, it can be shown (see the
 discussion of the rcu-link relation earlier) that S and U are related
-by rcu-link:
+by rcu-link::
 
 	S ->rcu-link U.
 
 Since S is a grace period we have S ->rcu-gp S, and since L and U are
 the start and end of the critical section C we have U ->rcu-rscsi L.
-From this we obtain:
+From this we obtain::
 
 	S ->rcu-gp S ->rcu-link U ->rcu-rscsi L ->rcu-link S,
 
@@ -1651,7 +1660,7 @@ the Grace Period Guarantee.
 
 For something a little more down-to-earth, let's see how the axiom
 works out in practice.  Consider the RCU code example from above, this
-time with statement labels added:
+time with statement labels added::
 
 	int x, y;
 
@@ -1687,7 +1696,7 @@ Then U ->rcu-rscsi L ->rcu-link S ->rcu-gp S ->rcu-link U is a
 forbidden cycle, violating the "rcu" axiom.  Hence the outcome is not
 allowed by the LKMM, as we would expect.
 
-For contrast, let's see what can happen in a more complicated example:
+For contrast, let's see what can happen in a more complicated example::
 
 	int x, y, z;
 
@@ -1726,22 +1735,22 @@ L2 ->rcu-link U0.  However this cycle is not forbidden, because the
 sequence of relations contains fewer instances of rcu-gp (one) than of
 rcu-rscsi (two).  Consequently the outcome is allowed by the LKMM.
 The following instruction timing diagram shows how it might actually
-occur:
+occur::
 
-P0			P1			P2
---------------------	--------------------	--------------------
-rcu_read_lock()
-WRITE_ONCE(y, 1)
-			r1 = READ_ONCE(y)
-			synchronize_rcu() starts
-			.			rcu_read_lock()
-			.			WRITE_ONCE(x, 1)
-r0 = READ_ONCE(x)	.
-rcu_read_unlock()	.
-			synchronize_rcu() ends
-			WRITE_ONCE(z, 1)
-						r2 = READ_ONCE(z)
-						rcu_read_unlock()
+	P0			P1			P2
+	--------------------	--------------------	--------------------
+	rcu_read_lock()
+	WRITE_ONCE(y, 1)
+				r1 = READ_ONCE(y)
+				synchronize_rcu() starts
+				.			rcu_read_lock()
+				.			WRITE_ONCE(x, 1)
+	r0 = READ_ONCE(x)	.
+	rcu_read_unlock()	.
+				synchronize_rcu() ends
+				WRITE_ONCE(z, 1)
+							r2 = READ_ONCE(z)
+							rcu_read_unlock()
 
 This requires P0 and P2 to execute their loads and stores out of
 program order, but of course they are allowed to do so.  And as you
@@ -1767,26 +1776,26 @@ The LKMM includes locking.  In fact, there is special code for locking
 in the formal model, added in order to make tools run faster.
 However, this special code is intended to be more or less equivalent
 to concepts we have already covered.  A spinlock_t variable is treated
-the same as an int, and spin_lock(&s) is treated almost the same as:
+the same as an int, and spin_lock(&s) is treated almost the same as::
 
 	while (cmpxchg_acquire(&s, 0, 1) != 0)
 		cpu_relax();
 
 This waits until s is equal to 0 and then atomically sets it to 1,
 and the read part of the cmpxchg operation acts as an acquire fence.
-An alternate way to express the same thing would be:
+An alternate way to express the same thing would be::
 
 	r = xchg_acquire(&s, 1);
 
 along with a requirement that at the end, r = 0.  Similarly,
-spin_trylock(&s) is treated almost the same as:
+spin_trylock(&s) is treated almost the same as::
 
 	return !cmpxchg_acquire(&s, 0, 1);
 
 which atomically sets s to 1 if it is currently equal to 0 and returns
 true if it succeeds (the read part of the cmpxchg operation acts as an
 acquire fence only if the operation is successful).  spin_unlock(&s)
-is treated almost the same as:
+is treated almost the same as::
 
 	smp_store_release(&s, 0);
 
@@ -1802,7 +1811,7 @@ requires that every instruction po-before the lock-release must
 execute before any instruction po-after the lock-acquire.  This would
 naturally hold if the release and acquire operations were on different
 CPUs, but the LKMM says it holds even when they are on the same CPU.
-For example:
+For example::
 
 	int x, y;
 	spinlock_t s;
@@ -1833,7 +1842,7 @@ MP pattern).
 
 This requirement does not apply to ordinary release and acquire
 fences, only to lock-related operations.  For instance, suppose P0()
-in the example had been written as:
+in the example had been written as::
 
 	P0()
 	{
@@ -1847,7 +1856,7 @@ in the example had been written as:
 
 Then the CPU would be allowed to forward the s = 1 value from the
 smp_store_release() to the smp_load_acquire(), executing the
-instructions in the following order:
+instructions in the following order::
 
 		r3 = smp_load_acquire(&s);	// Obtains r3 = 1
 		r2 = READ_ONCE(y);
@@ -1859,7 +1868,7 @@ and thus it could load y before x, obtaining r2 = 0 and r1 = 1.
 Second, when a lock-acquire reads from a lock-release, and some other
 stores W and W' occur po-before the lock-release and po-after the
 lock-acquire respectively, the LKMM requires that W must propagate to
-each CPU before W' does.  For example, consider:
+each CPU before W' does.  For example, consider::
 
 	int x, y;
 	spinlock_t x;
@@ -1928,7 +1937,7 @@ smp_store_release().)  The final effect is the same.
 Although we didn't mention it above, the instruction execution
 ordering provided by the smp_rmb() fence doesn't apply to read events
 that are part of a non-value-returning atomic update.  For instance,
-given:
+given::
 
 	atomic_inc(&x);
 	smp_rmb();
@@ -1967,14 +1976,14 @@ they behave as follows:
 	events.
 
 Interestingly, RCU and locking each introduce the possibility of
-deadlock.  When faced with code sequences such as:
+deadlock.  When faced with code sequences such as::
 
 	spin_lock(&s);
 	spin_lock(&s);
 	spin_unlock(&s);
 	spin_unlock(&s);
 
-or:
+or::
 
 	rcu_read_lock();
 	synchronize_rcu();
@@ -1984,7 +1993,7 @@ what does the LKMM have to say?  Answer: It says there are no allowed
 executions at all, which makes sense.  But this can also lead to
 misleading results, because if a piece of code has multiple possible
 executions, some of which deadlock, the model will report only on the
-non-deadlocking executions.  For example:
+non-deadlocking executions.  For example::
 
 	int x, y;
 
diff --git a/tools/memory-model/Documentation/index.rst b/tools/memory-model/Documentation/index.rst
new file mode 100644
index 000000000000..0e53d83a5a48
--- /dev/null
+++ b/tools/memory-model/Documentation/index.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+Linux Memory Model Tools
+========================
+
+.. toctree::
+   :maxdepth: 1
+
+   explanation
+   recipes
+   references
+   cheatsheet
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/tools/memory-model/Documentation/recipes.txt b/tools/memory-model/Documentation/recipes.rst
similarity index 96%
rename from tools/memory-model/Documentation/recipes.txt
rename to tools/memory-model/Documentation/recipes.rst
index 7fe8d7aa3029..0229a431b1a2 100644
--- a/tools/memory-model/Documentation/recipes.txt
+++ b/tools/memory-model/Documentation/recipes.rst
@@ -1,3 +1,8 @@
+=======
+Recipes
+=======
+
+
 This document provides "recipes", that is, litmus tests for commonly
 occurring situations, as well as a few that illustrate subtly broken but
 attractive nuisances.  Many of these recipes include example code from
@@ -67,7 +72,7 @@ has acquired a given lock sees any changes previously seen or made by any
 CPU before it released that same lock.  Note that this statement is a bit
 stronger than "Any CPU holding a given lock sees all changes made by any
 CPU during the time that CPU was holding this same lock".  For example,
-consider the following pair of code fragments:
+consider the following pair of code fragments::
 
 	/* See MP+polocks.litmus. */
 	void CPU0(void)
@@ -93,7 +98,7 @@ value of r1 must also be equal to 1.  In contrast, the weaker rule would
 say nothing about the final value of r1.
 
 The converse to the basic rule also holds, as illustrated by the
-following litmus test:
+following litmus test::
 
 	/* See MP+porevlocks.litmus. */
 	void CPU0(void)
@@ -124,7 +129,7 @@ across multiple CPUs.
 
 However, it is not necessarily the case that accesses ordered by
 locking will be seen as ordered by CPUs not holding that lock.
-Consider this example:
+Consider this example::
 
 	/* See Z6.0+pooncerelease+poacquirerelease+fencembonceonce.litmus. */
 	void CPU0(void)
@@ -157,7 +162,7 @@ CPU2() never acquired the lock, and thus did not benefit from the
 lock's ordering properties.
 
 Ordering can be extended to CPUs not holding the lock by careful use
-of smp_mb__after_spinlock():
+of smp_mb__after_spinlock()::
 
 	/* See Z6.0+pooncelock+poonceLock+pombonce.litmus. */
 	void CPU0(void)
@@ -214,7 +219,7 @@ Release and acquire
 ~~~~~~~~~~~~~~~~~~~
 
 Use of smp_store_release() and smp_load_acquire() is one way to force
-the desired MP ordering.  The general approach is shown below:
+the desired MP ordering.  The general approach is shown below::
 
 	/* See MP+pooncerelease+poacquireonce.litmus. */
 	void CPU0(void)
@@ -245,7 +250,7 @@ Assign and dereference
 Use of rcu_assign_pointer() and rcu_dereference() is quite similar to the
 use of smp_store_release() and smp_load_acquire(), except that both
 rcu_assign_pointer() and rcu_dereference() operate on RCU-protected
-pointers.  The general approach is shown below:
+pointers.  The general approach is shown below::
 
 	/* See MP+onceassign+derefonce.litmus. */
 	int z;
@@ -290,7 +295,7 @@ Write and read memory barriers
 It is usually better to use smp_store_release() instead of smp_wmb()
 and to use smp_load_acquire() instead of smp_rmb().  However, the older
 smp_wmb() and smp_rmb() APIs are still heavily used, so it is important
-to understand their use cases.  The general approach is shown below:
+to understand their use cases.  The general approach is shown below::
 
 	/* See MP+fencewmbonceonce+fencermbonceonce.litmus. */
 	void CPU0(void)
@@ -312,7 +317,7 @@ smp_rmb() macro orders prior loads against later loads.  Therefore, if
 the final value of r0 is 1, the final value of r1 must also be 1.
 
 The xlog_state_switch_iclogs() function in fs/xfs/xfs_log.c contains
-the following write-side code fragment:
+the following write-side code fragment::
 
 	log->l_curr_block -= log->l_logBBsize;
 	ASSERT(log->l_curr_block >= 0);
@@ -327,7 +332,7 @@ the corresponding read-side code fragment:
 	cur_block = READ_ONCE(log->l_curr_block);
 
 Alternatively, consider the following comment in function
-perf_output_put_handle() in kernel/events/ring_buffer.c:
+perf_output_put_handle() in kernel/events/ring_buffer.c::
 
 	 *   kernel				user
 	 *
@@ -358,7 +363,7 @@ absence of any ordering it is quite possible that this may happen, as
 can be seen in the LB+poonceonces.litmus litmus test.
 
 One way of avoiding the counter-intuitive outcome is through the use of a
-control dependency paired with a full memory barrier:
+control dependency paired with a full memory barrier::
 
 	/* See LB+fencembonceonce+ctrlonceonce.litmus. */
 	void CPU0(void)
@@ -382,7 +387,7 @@ The A/D pairing from the ring-buffer use case shown earlier also
 illustrates LB.  Here is a repeat of the comment in
 perf_output_put_handle() in kernel/events/ring_buffer.c, showing a
 control dependency on the kernel side and a full memory barrier on
-the user side:
+the user side::
 
 	 *   kernel				user
 	 *
@@ -407,7 +412,7 @@ Release-acquire chains
 
 Release-acquire chains are a low-overhead, flexible, and easy-to-use
 method of maintaining order.  However, they do have some limitations that
-need to be fully understood.  Here is an example that maintains order:
+need to be fully understood.  Here is an example that maintains order::
 
 	/* See ISA2+pooncerelease+poacquirerelease+poacquireonce.litmus. */
 	void CPU0(void)
@@ -436,7 +441,7 @@ example, ordering would still be preserved if CPU1()'s smp_load_acquire()
 invocation was replaced with READ_ONCE().
 
 It is tempting to assume that CPU0()'s store to x is globally ordered
-before CPU1()'s store to z, but this is not the case:
+before CPU1()'s store to z, but this is not the case::
 
 	/* See Z6.0+pooncerelease+poacquirerelease+mbonceonce.litmus. */
 	void CPU0(void)
@@ -474,7 +479,7 @@ Store buffering
 Store buffering can be thought of as upside-down load buffering, so
 that one CPU first stores to one variable and then loads from a second,
 while another CPU stores to the second variable and then loads from the
-first.  Preserving order requires nothing less than full barriers:
+first.  Preserving order requires nothing less than full barriers::
 
 	/* See SB+fencembonceonces.litmus. */
 	void CPU0(void)
@@ -498,7 +503,7 @@ this counter-intuitive outcome.
 This pattern most famously appears as part of Dekker's locking
 algorithm, but it has a much more practical use within the Linux kernel
 of ordering wakeups.  The following comment taken from waitqueue_active()
-in include/linux/wait.h shows the canonical pattern:
+in include/linux/wait.h shows the canonical pattern::
 
  *      CPU0 - waker                    CPU1 - waiter
  *
@@ -550,16 +555,16 @@ The strength of memory ordering required for a given litmus test to
 avoid a counter-intuitive outcome depends on the types of relations
 linking the memory accesses for the outcome in question:
 
-o	If all links are write-to-read links, then the weakest
+-	If all links are write-to-read links, then the weakest
 	possible ordering within each CPU suffices.  For example, in
 	the LB litmus test, a control dependency was enough to do the
 	job.
 
-o	If all but one of the links are write-to-read links, then a
+-	If all but one of the links are write-to-read links, then a
 	release-acquire chain suffices.  Both the MP and the ISA2
 	litmus tests illustrate this case.
 
-o	If more than one of the links are something other than
+-	If more than one of the links are something other than
 	write-to-read links, then a full memory barrier is required
 	between each successive pair of non-write-to-read links.  This
 	case is illustrated by the Z6.0 litmus tests, both in the
diff --git a/tools/memory-model/Documentation/references.txt b/tools/memory-model/Documentation/references.rst
similarity index 71%
rename from tools/memory-model/Documentation/references.txt
rename to tools/memory-model/Documentation/references.rst
index b177f3e4a614..275876cd10b8 100644
--- a/tools/memory-model/Documentation/references.txt
+++ b/tools/memory-model/Documentation/references.rst
@@ -1,3 +1,7 @@
+==========
+References
+==========
+
 This document provides background reading for memory models and related
 tools.  These documents are aimed at kernel hackers who are interested
 in memory models.
@@ -6,64 +10,64 @@ in memory models.
 Hardware manuals and models
 ===========================
 
-o	SPARC International Inc. (Ed.). 1994. "The SPARC Architecture
+-	SPARC International Inc. (Ed.). 1994. "The SPARC Architecture
 	Reference Manual Version 9". SPARC International Inc.
 
-o	Compaq Computer Corporation (Ed.). 2002. "Alpha Architecture
+-	Compaq Computer Corporation (Ed.). 2002. "Alpha Architecture
 	Reference Manual".  Compaq Computer Corporation.
 
-o	Intel Corporation (Ed.). 2002. "A Formal Specification of Intel
+-	Intel Corporation (Ed.). 2002. "A Formal Specification of Intel
 	Itanium Processor Family Memory Ordering". Intel Corporation.
 
-o	Intel Corporation (Ed.). 2002. "Intel 64 and IA-32 Architectures
+-	Intel Corporation (Ed.). 2002. "Intel 64 and IA-32 Architectures
 	Software Developer’s Manual". Intel Corporation.
 
-o	Peter Sewell, Susmit Sarkar, Scott Owens, Francesco Zappa Nardelli,
+-	Peter Sewell, Susmit Sarkar, Scott Owens, Francesco Zappa Nardelli,
 	and Magnus O. Myreen. 2010. "x86-TSO: A Rigorous and Usable
 	Programmer's Model for x86 Multiprocessors". Commun. ACM 53, 7
 	(July, 2010), 89-97. http://doi.acm.org/10.1145/1785414.1785443
 
-o	IBM Corporation (Ed.). 2009. "Power ISA Version 2.06". IBM
+-	IBM Corporation (Ed.). 2009. "Power ISA Version 2.06". IBM
 	Corporation.
 
-o	ARM Ltd. (Ed.). 2009. "ARM Barrier Litmus Tests and Cookbook".
+-	ARM Ltd. (Ed.). 2009. "ARM Barrier Litmus Tests and Cookbook".
 	ARM Ltd.
 
-o	Susmit Sarkar, Peter Sewell, Jade Alglave, Luc Maranget, and
+-	Susmit Sarkar, Peter Sewell, Jade Alglave, Luc Maranget, and
 	Derek Williams.  2011. "Understanding POWER Multiprocessors". In
 	Proceedings of the 32Nd ACM SIGPLAN Conference on Programming
 	Language Design and Implementation (PLDI ’11). ACM, New York,
 	NY, USA, 175–186.
 
-o	Susmit Sarkar, Kayvan Memarian, Scott Owens, Mark Batty,
+-	Susmit Sarkar, Kayvan Memarian, Scott Owens, Mark Batty,
 	Peter Sewell, Luc Maranget, Jade Alglave, and Derek Williams.
 	2012. "Synchronising C/C++ and POWER". In Proceedings of the 33rd
 	ACM SIGPLAN Conference on Programming Language Design and
 	Implementation (PLDI '12). ACM, New York, NY, USA, 311-322.
 
-o	ARM Ltd. (Ed.). 2014. "ARM Architecture Reference Manual (ARMv8,
+-	ARM Ltd. (Ed.). 2014. "ARM Architecture Reference Manual (ARMv8,
 	for ARMv8-A architecture profile)". ARM Ltd.
 
-o	Imagination Technologies, LTD. 2015. "MIPS(R) Architecture
+-	Imagination Technologies, LTD. 2015. "MIPS(R) Architecture
 	For Programmers, Volume II-A: The MIPS64(R) Instruction,
 	Set Reference Manual". Imagination Technologies,
 	LTD. https://imgtec.com/?do-download=4302.
 
-o	Shaked Flur, Kathryn E. Gray, Christopher Pulte, Susmit
+-	Shaked Flur, Kathryn E. Gray, Christopher Pulte, Susmit
 	Sarkar, Ali Sezgin, Luc Maranget, Will Deacon, and Peter
 	Sewell. 2016. "Modelling the ARMv8 Architecture, Operationally:
 	Concurrency and ISA". In Proceedings of the 43rd Annual ACM
 	SIGPLAN-SIGACT Symposium on Principles of Programming Languages
 	(POPL ’16). ACM, New York, NY, USA, 608–621.
 
-o	Shaked Flur, Susmit Sarkar, Christopher Pulte, Kyndylan Nienhuis,
+-	Shaked Flur, Susmit Sarkar, Christopher Pulte, Kyndylan Nienhuis,
 	Luc Maranget, Kathryn E. Gray, Ali Sezgin, Mark Batty, and Peter
 	Sewell. 2017. "Mixed-size Concurrency: ARM, POWER, C/C++11,
 	and SC". In Proceedings of the 44th ACM SIGPLAN Symposium on
 	Principles of Programming Languages (POPL 2017). ACM, New York,
 	NY, USA, 429–442.
 
-o	Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
+-	Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
 	Susmit Sarkar, and Peter Sewell. 2018. "Simplifying ARM concurrency:
 	multicopy-atomic axiomatic and operational models for ARMv8". In
 	Proceedings of the ACM on Programming Languages, Volume 2, Issue
@@ -73,18 +77,18 @@ o	Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
 Linux-kernel memory model
 =========================
 
-o	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
+-	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
 	Alan Stern.  2018. "Frightening small children and disconcerting
 	grown-ups: Concurrency in the Linux kernel". In Proceedings of
 	the 23rd International Conference on Architectural Support for
 	Programming Languages and Operating Systems (ASPLOS 2018). ACM,
 	New York, NY, USA, 405-418.  Webpage: http://diy.inria.fr/linux/.
 
-o	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
+-	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
 	Alan Stern.  2017.  "A formal kernel memory-ordering model (part 1)"
 	Linux Weekly News.  https://lwn.net/Articles/718628/
 
-o	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
+-	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
 	Alan Stern.  2017.  "A formal kernel memory-ordering model (part 2)"
 	Linux Weekly News.  https://lwn.net/Articles/720550/
 
@@ -92,16 +96,16 @@ o	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
 Memory-model tooling
 ====================
 
-o	Daniel Jackson. 2002. "Alloy: A Lightweight Object Modelling
+-	Daniel Jackson. 2002. "Alloy: A Lightweight Object Modelling
 	Notation". ACM Trans. Softw. Eng. Methodol. 11, 2 (April 2002),
 	256–290. http://doi.acm.org/10.1145/505145.505149
 
-o	Jade Alglave, Luc Maranget, and Michael Tautschnig. 2014. "Herding
+-	Jade Alglave, Luc Maranget, and Michael Tautschnig. 2014. "Herding
 	Cats: Modelling, Simulation, Testing, and Data Mining for Weak
 	Memory". ACM Trans. Program. Lang. Syst. 36, 2, Article 7 (July
 	2014), 7:1–7:74 pages.
 
-o	Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
+-	Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
 	semantics of the weak consistency model specification language
 	cat". CoRR abs/1608.07531 (2016). http://arxiv.org/abs/1608.07531
 
@@ -109,6 +113,6 @@ o	Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
 Memory-model comparisons
 ========================
 
-o	Paul E. McKenney, Ulrich Weigand, Andrea Parri, and Boqun
+-	Paul E. McKenney, Ulrich Weigand, Andrea Parri, and Boqun
 	Feng. 2016. "Linux-Kernel Memory Model". (6 June 2016).
 	http://open-std.org/JTC1/SC22/WG21/docs/papers/2016/p0124r2.html.
diff --git a/tools/memory-model/README b/tools/memory-model/README
index 2b87f3971548..04bb1fa9ed76 100644
--- a/tools/memory-model/README
+++ b/tools/memory-model/README
@@ -105,16 +105,16 @@ for more information.
 DESCRIPTION OF FILES
 ====================
 
-Documentation/cheatsheet.txt
+Documentation/cheatsheet.rst
 	Quick-reference guide to the Linux-kernel memory model.
 
-Documentation/explanation.txt
+Documentation/explanation.rst
 	Describes the memory model in detail.
 
-Documentation/recipes.txt
+Documentation/recipes.rst
 	Lists common memory-ordering patterns.
 
-Documentation/references.txt
+Documentation/references.rst
 	Provides background reading.
 
 linux-kernel.bell
@@ -173,7 +173,7 @@ The Linux-kernel memory model has the following limitations:
 	of READ_ONCE() and WRITE_ONCE() limits the compiler's ability
 	to optimize, but there is Linux-kernel code that uses bare C
 	memory accesses.  Handling this code is on the to-do list.
-	For more information, see Documentation/explanation.txt (in
+	For more information, see Documentation/explanation.rst (in
 	particular, the "THE PROGRAM ORDER RELATION: po AND po-loc"
 	and "A WARNING" sections).
 
-- 
2.21.0


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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
  2019-07-26 18:02   ` Joel Fernandes
  2019-07-26 19:01     ` [PATCH] tools: memory-model: add it to the Documentation body Mauro Carvalho Chehab
@ 2019-07-26 19:14     ` Mauro Carvalho Chehab
  2019-07-30 22:06       ` Joel Fernandes
  1 sibling, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-26 19:14 UTC (permalink / raw)
  To: Joel Fernandes
  Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
	Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
	linux-doc, Markus Heiser

Em Fri, 26 Jul 2019 14:02:01 -0400
Joel Fernandes <joel@joelfernandes.org> escreveu:

> On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> [snip]
> > +| until the assignment to ``gp``, by which time both fields are fully   |
> > +| initialized. So reordering the assignments to ``p->a`` and ``p->b``   |
> > +| cannot possibly cause any problems.                                   |
> > ++-----------------------------------------------------------------------+
> > +
> > +It is tempting to assume that the reader need not do anything special to
> > +control its accesses to the RCU-protected data, as shown in
> > +``do_something_gp_buggy()`` below:
> > +
> > +   ::
> > +
> > +       1 bool do_something_gp_buggy(void)
> > +       2 {
> > +       3   rcu_read_lock();
> > +       4   p = gp;  /* OPTIMIZATIONS GALORE!!! */
> > +       5   if (p) {
> > +       6     do_something(p->a, p->b);
> > +       7     rcu_read_unlock();
> > +       8     return true;
> > +       9   }
> > +      10   rcu_read_unlock();
> > +      11   return false;
> > +      12 }
> > +
> > +However, this temptation must be resisted because there are a
> > +surprisingly large number of ways that the compiler (to say nothing of
> > +`DEC Alpha CPUs <https://h71000.www7.hp.com/wizard/wiz_2637.html>`__)
> > +can trip this code up. For but one example, if the compiler were short
> > +of registers, it might choose to refetch from ``gp`` rather than keeping
> > +a separate copy in ``p`` as follows:
> > +
> > +   ::
> > +
> > +       1 bool do_something_gp_buggy_optimized(void)
> > +       2 {
> > +       3   rcu_read_lock();
> > +       4   if (gp) { /* OPTIMIZATIONS GALORE!!! */
> > +       5     do_something(gp->a, gp->b);
> > +       6     rcu_read_unlock();
> > +       7     return true;
> > +       8   }
> > +       9   rcu_read_unlock();
> > +      10   return false;
> > +      11 }
> > +
> > +If this function ran concurrently with a series of updates that replaced
> > +the current structure with a new one, the fetches of ``gp->a`` and
> > +``gp->b`` might well come from two different structures, which could
> > +cause serious confusion. To prevent this (and much else besides),
> > +``do_something_gp()`` uses ``rcu_dereference()`` to fetch from ``gp``:
> > +
> > +   ::
> > +
> > +       1 bool do_something_gp(void)
> > +       2 {
> > +       3   rcu_read_lock();
> > +       4   p = rcu_dereference(gp);
> > +       5   if (p) {
> > +       6     do_something(p->a, p->b);
> > +       7     rcu_read_unlock();
> > +       8     return true;
> > +       9   }
> > +      10   rcu_read_unlock();
> > +      11   return false;
> > +      12 }
> > +
> > +The ``rcu_dereference()`` uses volatile casts and (for DEC Alpha) memory
> > +barriers in the Linux kernel. Should a `high-quality implementation of
> > +C11 ``memory_order_consume``
> > +[PDF] <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__
> > +ever appear, then ``rcu_dereference()`` could be implemented as a
> > +``memory_order_consume`` load. Regardless of the exact implementation, a
> > +pointer fetched by ``rcu_dereference()`` may not be used outside of the
> > +outermost RCU read-side critical section containing that
> > +``rcu_dereference()``, unless protection of the corresponding data
> > +element has been passed from RCU to some other synchronization
> > +mechanism, most commonly locking or `reference
> > +counting <https://www.kernel.org/doc/Documentation/RCU/rcuref.txt>`__.  
> 
> From the make htmldocs output, this appears very poorly for me, I get
> something like this in the browser:
> 
> The rcu_dereference() uses volatile casts and (for DEC Alpha) memory barriers
> in the Linux kernel. Should a high-quality implementation of C11
> ``memory_order_consume` [PDF]
> <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__ ever
> appear, then rcu_dereference() could be implemented as a memory_order_consume
> load.
> 
> Is there a syntax issue here?

Maybe. I tested those with Sphinx 2.0.1. Didn't test with older versions.

I'll do some tests with Sphinx 1.7.9 (with is the current minimal
recommended version) and do some cleanup on those references.

> One more feedback,
> the image under "RCU read-side critical section that started before the current
> grace period:" should probably be blown up a bit.

Unfortunately, the Kernel Sphinx image extension doesn't allow image scaling.

We had to add our own image extension at the Kernel, as otherwise,
for every image, we would need to add one parser for PDF and another
one for SVG. 

We would also need an extra parser for DOT.

Markus solved all the 3 image formats with a single extension, but
it currently doesn't allow passing the image size.

-

Markus,

Any reason for the kernel-image extension to not support scaling?

-

If this can't be easily solved at the kernel-image.py extension, a
simple alternative would be to simply scale the SVG file
directly. It should be trivial to re-scale with inkscape, although
the diff may be big.




Thanks,
Mauro

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

* Re: [PATCH] tools: memory-model: add it to the Documentation body
  2019-07-26 19:01     ` [PATCH] tools: memory-model: add it to the Documentation body Mauro Carvalho Chehab
@ 2019-07-27 14:14       ` Joel Fernandes
  2019-07-27 15:37         ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 75+ messages in thread
From: Joel Fernandes @ 2019-07-27 14:14 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Alan Stern, Andrea Parri, Will Deacon,
	Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
	Jade Alglave, Luc Maranget, Paul E. McKenney, Akira Yokosawa,
	Daniel Lustig, Ingo Molnar, Jason Gunthorpe, SeongJae Park,
	linux-arch

On Fri, Jul 26, 2019 at 04:01:37PM -0300, Mauro Carvalho Chehab wrote:
> The books at tools/memory-model/Documentation are very well
> formatted. Congrats to the ones that wrote them!
> 
> The manual conversion to ReST is really trivial:
> 
> 	- Add document titles;
> 	- change the bullets on some lists;
> 	- mark code blocks.

Thanks so much, some feedback:
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

(1)
I could not find the table of contents appear in the HTML output for this.
Basically this list in the beginning doesn't render:
  1. INTRODUCTION
  2. BACKGROUND
  3. A SIMPLE EXAMPLE
  4. A SELECTION OF MEMORY MODELS
  5. ORDERING AND CYCLES
 
Could we add a proper TOC with sections? My motivation for ReST here would be
to make the sections jumpable since it is a large document.

Also could we make the different sections appear as a tree in the left
sidebar?

(2) Arguably several function names in the document HTML output should appear
in monospace fonting and/or referring to the documentation for real function
names, but these can be fixed as we go, I guess.

(3) Things like smp_load_acquire() and spin_lock() should probably refer to
the documentation for those elsewhere..

(4) I would argue that every occurence of
A ->(some dependency) B should be replaced with fixed size font in the HTML
results.

Arguably it is better IMO if the whole document is fixed size font in the
HTML output because so many things need to be fixed size, but that my just be
my opinion.

thanks,

 - Joel


> ---
>  Documentation/core-api/refcount-vs-atomic.rst |   2 +-
>  Documentation/index.rst                       |   1 +
>  Documentation/tools/memory-model              |   1 +
>  .../memory-model/Documentation/cheatsheet.rst |  36 +++++
>  .../memory-model/Documentation/cheatsheet.txt |  30 ----
>  .../{explanation.txt => explanation.rst}      | 151 ++++++++++--------
>  tools/memory-model/Documentation/index.rst    |  20 +++
>  .../{recipes.txt => recipes.rst}              |  41 ++---
>  .../{references.txt => references.rst}        |  46 +++---
>  tools/memory-model/README                     |  10 +-
>  10 files changed, 192 insertions(+), 146 deletions(-)
>  create mode 120000 Documentation/tools/memory-model
>  create mode 100644 tools/memory-model/Documentation/cheatsheet.rst
>  delete mode 100644 tools/memory-model/Documentation/cheatsheet.txt
>  rename tools/memory-model/Documentation/{explanation.txt => explanation.rst} (97%)
>  create mode 100644 tools/memory-model/Documentation/index.rst
>  rename tools/memory-model/Documentation/{recipes.txt => recipes.rst} (96%)
>  rename tools/memory-model/Documentation/{references.txt => references.rst} (71%)
 

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

* Re: [PATCH] tools: memory-model: add it to the Documentation body
  2019-07-27 14:14       ` Joel Fernandes
@ 2019-07-27 15:37         ` Mauro Carvalho Chehab
  2019-07-30 22:17           ` Joel Fernandes
  0 siblings, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-27 15:37 UTC (permalink / raw)
  To: Joel Fernandes
  Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Alan Stern, Andrea Parri, Will Deacon,
	Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
	Jade Alglave, Luc Maranget, Paul E. McKenney, Akira Yokosawa,
	Daniel Lustig, Ingo Molnar, Jason Gunthorpe, SeongJae Park,
	linux-arch

Em Sat, 27 Jul 2019 14:14:53 +0000
Joel Fernandes <joel@joelfernandes.org> escreveu:

> On Fri, Jul 26, 2019 at 04:01:37PM -0300, Mauro Carvalho Chehab wrote:
> > The books at tools/memory-model/Documentation are very well
> > formatted. Congrats to the ones that wrote them!
> > 
> > The manual conversion to ReST is really trivial:
> > 
> > 	- Add document titles;
> > 	- change the bullets on some lists;
> > 	- mark code blocks.  
> 
> Thanks so much, some feedback:
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>  
> 
> (1)
> I could not find the table of contents appear in the HTML output for this.
> Basically this list in the beginning doesn't render:
>   1. INTRODUCTION
>   2. BACKGROUND
>   3. A SIMPLE EXAMPLE
>   4. A SELECTION OF MEMORY MODELS
>   5. ORDERING AND CYCLES

Yes. It is written as a comment, like:

	.. foo  This is a comment block

	   Everything on this block

	   won't be parsed.

So it won't be parsed, but having a TOC like this isn't need, as
Sphinx generates it automatically via "toctree" markup. 

> Could we add a proper TOC with sections? My motivation for ReST here would be
> to make the sections jumpable since it is a large document.

Just change the toctree depth at index.rst to 2 and you'll see an index
produced by Sphinx with both levels 1 (doc name) and level 2 (chapters):

	.. toctree::
	   :maxdepth: 2

> Also could we make the different sections appear as a tree in the left
> sidebar?

The sidebar follows the maxdepth too.

> 
> (2) Arguably several function names in the document HTML output should appear
> in monospace fonting and/or referring to the documentation for real function
> names, but these can be fixed as we go, I guess.

If you want monospaced fonts, just use: ``monospaced_symbol_foo`` within
any paragraph, or place the monospaced data inside a code-block:

	::

		This will be monospaced.

> 
> (3) Things like smp_load_acquire() and spin_lock() should probably refer to
> the documentation for those elsewhere..

Jon added an automarkup extension on Kernel 5.2. So, all functions that
are defined elsewhere will automatically generate an hyperlink. For that to
happen, you need to add the kernel-doc markup at the *.h or *.c file where
the function is declared and use the kernel-doc markup somewhere within the
Kernel Documentation/.

> 
> (4) I would argue that every occurence of
> A ->(some dependency) B should be replaced with fixed size font in the HTML
> results.

Just place those with ``A -> (some dependency)``. This will make them use
a fixed size font.

> Arguably it is better IMO if the whole document is fixed size font in the
> HTML output because so many things need to be fixed size, but that my just be
> my opinion.

Just my 2 cents here, but having the entire document using a fixed size
font makes it more boring to read. Having just the symbols with a fixed size
is a common convention used on technical books, and helps to make easier
to identify the symbols while reading the docs.

That's said, Sphinx doesn't have any tag to switch the font for the entire
document. All it can be done is to define a CSS and apply it for the
doc - or to place everything within a code-block, with will suppress all
markup tags, including cross-references for functions.

The problem with CSS is that you need to write both an html CSS file
and add LaTeX macros associated to this "CSS style" (technically, LaTeX
doesn't have a CSS concept, but Sphinx emulates it).

Thanks,
Mauro

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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
       [not found] ` <8444797277eea7be474f40625bb190775a9cee33.1564145354.git.mchehab+samsung@kernel.org>
       [not found]   ` <20190726162002.GA146401@google.com>
  2019-07-26 18:02   ` Joel Fernandes
@ 2019-07-30 21:22   ` Paul E. McKenney
  2019-07-30 21:50     ` Joel Fernandes
  2019-07-30 21:50     ` Mauro Carvalho Chehab
  2 siblings, 2 replies; 75+ messages in thread
From: Paul E. McKenney @ 2019-07-30 21:22 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
	Joel Fernandes, Jonathan Corbet, rcu, linux-doc

On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> There are 4 RCU articles that are written on html format.
> 
> The way they are, they can't be part of the Linux Kernel
> documentation body nor share the styles and pdf output.
> 
> So, convert them to ReST format.
> 
> This way, make htmldocs and make pdfdocs will produce a
> documentation output that will be like the original ones, but
> will be part of the Linux Kernel documentation body.
> 
> Part of the conversion was done with the help of pandoc, but
> the result had some broken things that had to be manually
> fixed.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

I am having some trouble applying these, at least in part due to UTF-8
sequences, for example double left quotation mark.  These end up being
"=E2=80=9C", with a few space characters turned into "=20".

Any advice on how to apply these?  Should I just pull commits from
somewhere?

							Thanx, Paul

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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
  2019-07-30 21:22   ` Paul E. McKenney
@ 2019-07-30 21:50     ` Joel Fernandes
  2019-07-30 22:00       ` Mauro Carvalho Chehab
  2019-07-30 21:50     ` Mauro Carvalho Chehab
  1 sibling, 1 reply; 75+ messages in thread
From: Joel Fernandes @ 2019-07-30 21:50 UTC (permalink / raw)
  To: Paul E. McKenney
  Cc: Mauro Carvalho Chehab, Josh Triplett, Steven Rostedt,
	Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
	linux-doc

On Tue, Jul 30, 2019 at 02:22:50PM -0700, Paul E. McKenney wrote:
> On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > There are 4 RCU articles that are written on html format.
> > 
> > The way they are, they can't be part of the Linux Kernel
> > documentation body nor share the styles and pdf output.
> > 
> > So, convert them to ReST format.
> > 
> > This way, make htmldocs and make pdfdocs will produce a
> > documentation output that will be like the original ones, but
> > will be part of the Linux Kernel documentation body.
> > 
> > Part of the conversion was done with the help of pandoc, but
> > the result had some broken things that had to be manually
> > fixed.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> 
> I am having some trouble applying these, at least in part due to UTF-8
> sequences, for example double left quotation mark.  These end up being
> "=E2=80=9C", with a few space characters turned into "=20".
> 
> Any advice on how to apply these?  Should I just pull commits from
> somewhere?

I was able to successfully apply and build this particular patch. I think
this is the only one in the series that applies to RCU.

Sadly, I can't find the patch in any of the public archives, but I could
perhaps email it to you as an .mbox attach which 'git am' should be able to
apply.

Mauro did say he was going to add some more details to changelog, or it could
be added when it is applied:
https://lore.kernel.org/rcu/20190726154550.5eeae294@coco.lan/

Let me know how else I can help! I am reviewing this patch further today.

thanks,

 - Joel


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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
  2019-07-30 21:22   ` Paul E. McKenney
  2019-07-30 21:50     ` Joel Fernandes
@ 2019-07-30 21:50     ` Mauro Carvalho Chehab
  2019-07-30 23:37       ` Paul E. McKenney
  1 sibling, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-30 21:50 UTC (permalink / raw)
  To: Paul E. McKenney
  Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
	Joel Fernandes, Jonathan Corbet, rcu, linux-doc

Em Tue, 30 Jul 2019 14:22:50 -0700
"Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:

> On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > There are 4 RCU articles that are written on html format.
> > 
> > The way they are, they can't be part of the Linux Kernel
> > documentation body nor share the styles and pdf output.
> > 
> > So, convert them to ReST format.
> > 
> > This way, make htmldocs and make pdfdocs will produce a
> > documentation output that will be like the original ones, but
> > will be part of the Linux Kernel documentation body.
> > 
> > Part of the conversion was done with the help of pandoc, but
> > the result had some broken things that had to be manually
> > fixed.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>  
> 
> I am having some trouble applying these, at least in part due to UTF-8
> sequences, for example double left quotation mark.  These end up being
> "=E2=80=9C", with a few space characters turned into "=20".
> 
> Any advice on how to apply these?

Didn't notice it ended with UTF-8 chars. It is probably because it came
from the html conversion.

I guess it shouldn't hurt keeping those, but if you prefer I can find 
some time later to replace them.

> Should I just pull commits from somewhere?

Yeah, if you prefer, you can pull from this branch:

	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rcu-v1

It has just two patches: the RCU and tools/memory-model ones.

It is based on v5.3-rc2.

Thanks,
Mauro

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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
  2019-07-30 21:50     ` Joel Fernandes
@ 2019-07-30 22:00       ` Mauro Carvalho Chehab
  2019-07-30 22:21         ` Joel Fernandes
  0 siblings, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-30 22:00 UTC (permalink / raw)
  To: Joel Fernandes
  Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
	Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
	linux-doc

Em Tue, 30 Jul 2019 17:50:07 -0400
Joel Fernandes <joel@joelfernandes.org> escreveu:

> On Tue, Jul 30, 2019 at 02:22:50PM -0700, Paul E. McKenney wrote:
> > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:  
> > > There are 4 RCU articles that are written on html format.
> > > 
> > > The way they are, they can't be part of the Linux Kernel
> > > documentation body nor share the styles and pdf output.
> > > 
> > > So, convert them to ReST format.
> > > 
> > > This way, make htmldocs and make pdfdocs will produce a
> > > documentation output that will be like the original ones, but
> > > will be part of the Linux Kernel documentation body.
> > > 
> > > Part of the conversion was done with the help of pandoc, but
> > > the result had some broken things that had to be manually
> > > fixed.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>  
> > 
> > I am having some trouble applying these, at least in part due to UTF-8
> > sequences, for example double left quotation mark.  These end up being
> > "=E2=80=9C", with a few space characters turned into "=20".
> > 
> > Any advice on how to apply these?  Should I just pull commits from
> > somewhere?  
> 
> I was able to successfully apply and build this particular patch. I think
> this is the only one in the series that applies to RCU.
> 
> Sadly, I can't find the patch in any of the public archives, but I could
> perhaps email it to you as an .mbox attach which 'git am' should be able to
> apply.
> 
> Mauro did say he was going to add some more details to changelog, or it could
> be added when it is applied:
> https://lore.kernel.org/rcu/20190726154550.5eeae294@coco.lan/

Yeah, I'm also planning to address at least some of the issues you
pointed, in order to improve the html output, but got sidetracked by something 
else and didn't find any time yet to finish. I'm adding some CI automation for
the media subsystem in order to help us dealing with the huge amount of patches
we receive there.

Feel free to add those details to the changelog. I may find some spare time 
this week or the next one for the improvements you suggested, but those 
could be sent on followup patches, once done.

Thanks,
Mauro

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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
  2019-07-26 19:14     ` [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST Mauro Carvalho Chehab
@ 2019-07-30 22:06       ` Joel Fernandes
  0 siblings, 0 replies; 75+ messages in thread
From: Joel Fernandes @ 2019-07-30 22:06 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
	Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
	linux-doc, Markus Heiser

On Fri, Jul 26, 2019 at 04:14:05PM -0300, Mauro Carvalho Chehab wrote:
> Em Fri, 26 Jul 2019 14:02:01 -0400
> Joel Fernandes <joel@joelfernandes.org> escreveu:
> 
> > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > [snip]
> > > +| until the assignment to ``gp``, by which time both fields are fully   |
> > > +| initialized. So reordering the assignments to ``p->a`` and ``p->b``   |
> > > +| cannot possibly cause any problems.                                   |
> > > ++-----------------------------------------------------------------------+
> > > +
> > > +It is tempting to assume that the reader need not do anything special to
> > > +control its accesses to the RCU-protected data, as shown in
> > > +``do_something_gp_buggy()`` below:
> > > +
> > > +   ::
> > > +
> > > +       1 bool do_something_gp_buggy(void)
> > > +       2 {
> > > +       3   rcu_read_lock();
> > > +       4   p = gp;  /* OPTIMIZATIONS GALORE!!! */
> > > +       5   if (p) {
> > > +       6     do_something(p->a, p->b);
> > > +       7     rcu_read_unlock();
> > > +       8     return true;
> > > +       9   }
> > > +      10   rcu_read_unlock();
> > > +      11   return false;
> > > +      12 }
> > > +
> > > +However, this temptation must be resisted because there are a
> > > +surprisingly large number of ways that the compiler (to say nothing of
> > > +`DEC Alpha CPUs <https://h71000.www7.hp.com/wizard/wiz_2637.html>`__)
> > > +can trip this code up. For but one example, if the compiler were short
> > > +of registers, it might choose to refetch from ``gp`` rather than keeping
> > > +a separate copy in ``p`` as follows:
> > > +
> > > +   ::
> > > +
> > > +       1 bool do_something_gp_buggy_optimized(void)
> > > +       2 {
> > > +       3   rcu_read_lock();
> > > +       4   if (gp) { /* OPTIMIZATIONS GALORE!!! */
> > > +       5     do_something(gp->a, gp->b);
> > > +       6     rcu_read_unlock();
> > > +       7     return true;
> > > +       8   }
> > > +       9   rcu_read_unlock();
> > > +      10   return false;
> > > +      11 }
> > > +
> > > +If this function ran concurrently with a series of updates that replaced
> > > +the current structure with a new one, the fetches of ``gp->a`` and
> > > +``gp->b`` might well come from two different structures, which could
> > > +cause serious confusion. To prevent this (and much else besides),
> > > +``do_something_gp()`` uses ``rcu_dereference()`` to fetch from ``gp``:
> > > +
> > > +   ::
> > > +
> > > +       1 bool do_something_gp(void)
> > > +       2 {
> > > +       3   rcu_read_lock();
> > > +       4   p = rcu_dereference(gp);
> > > +       5   if (p) {
> > > +       6     do_something(p->a, p->b);
> > > +       7     rcu_read_unlock();
> > > +       8     return true;
> > > +       9   }
> > > +      10   rcu_read_unlock();
> > > +      11   return false;
> > > +      12 }
> > > +
> > > +The ``rcu_dereference()`` uses volatile casts and (for DEC Alpha) memory
> > > +barriers in the Linux kernel. Should a `high-quality implementation of
> > > +C11 ``memory_order_consume``
> > > +[PDF] <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__
> > > +ever appear, then ``rcu_dereference()`` could be implemented as a
> > > +``memory_order_consume`` load. Regardless of the exact implementation, a
> > > +pointer fetched by ``rcu_dereference()`` may not be used outside of the
> > > +outermost RCU read-side critical section containing that
> > > +``rcu_dereference()``, unless protection of the corresponding data
> > > +element has been passed from RCU to some other synchronization
> > > +mechanism, most commonly locking or `reference
> > > +counting <https://www.kernel.org/doc/Documentation/RCU/rcuref.txt>`__.  
> > 
> > From the make htmldocs output, this appears very poorly for me, I get
> > something like this in the browser:
> > 
> > The rcu_dereference() uses volatile casts and (for DEC Alpha) memory barriers
> > in the Linux kernel. Should a high-quality implementation of C11
> > ``memory_order_consume` [PDF]
> > <http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf>`__ ever
> > appear, then rcu_dereference() could be implemented as a memory_order_consume
> > load.
> > 
> > Is there a syntax issue here?
> 
> Maybe. I tested those with Sphinx 2.0.1. Didn't test with older versions.
> 
> I'll do some tests with Sphinx 1.7.9 (with is the current minimal
> recommended version) and do some cleanup on those references.

Ok, one more thing is broken, clicking links such as "Parallelism Facts of
Life" does not jump to the corresponding section.

Would you mind fixing this, add the description of changes you made (which
you shared in an earlier reply), fixing the above Sphinx issue, and then
resend it?

Otherwise, I believe it looks sane.

> > One more feedback,
> > the image under "RCU read-side critical section that started before the current
> > grace period:" should probably be blown up a bit.
> 
> Unfortunately, the Kernel Sphinx image extension doesn't allow image scaling.

The current scale appears fine to me, it is not a big deal since it is clear.

> We had to add our own image extension at the Kernel, as otherwise,
> for every image, we would need to add one parser for PDF and another
> one for SVG. 
> 
> We would also need an extra parser for DOT.
> 
> Markus solved all the 3 image formats with a single extension, but
> it currently doesn't allow passing the image size.

Cool.


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

* Re: [PATCH] tools: memory-model: add it to the Documentation body
  2019-07-27 15:37         ` Mauro Carvalho Chehab
@ 2019-07-30 22:17           ` Joel Fernandes
  2019-07-30 22:57             ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 75+ messages in thread
From: Joel Fernandes @ 2019-07-30 22:17 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Alan Stern, Andrea Parri, Will Deacon,
	Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
	Jade Alglave, Luc Maranget, Paul E. McKenney, Akira Yokosawa,
	Daniel Lustig, Ingo Molnar, Jason Gunthorpe, SeongJae Park,
	linux-arch

On Sat, Jul 27, 2019 at 12:37:54PM -0300, Mauro Carvalho Chehab wrote:
> Em Sat, 27 Jul 2019 14:14:53 +0000
> Joel Fernandes <joel@joelfernandes.org> escreveu:
> 
> > On Fri, Jul 26, 2019 at 04:01:37PM -0300, Mauro Carvalho Chehab wrote:
> > > The books at tools/memory-model/Documentation are very well
> > > formatted. Congrats to the ones that wrote them!
> > > 
> > > The manual conversion to ReST is really trivial:
> > > 
> > > 	- Add document titles;
> > > 	- change the bullets on some lists;
> > > 	- mark code blocks.  
> > 
> > Thanks so much, some feedback:
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>  
> > 
> > (1)
> > I could not find the table of contents appear in the HTML output for this.
> > Basically this list in the beginning doesn't render:
> >   1. INTRODUCTION
> >   2. BACKGROUND
> >   3. A SIMPLE EXAMPLE
> >   4. A SELECTION OF MEMORY MODELS
> >   5. ORDERING AND CYCLES
> 
> Yes. It is written as a comment, like:
> 
> 	.. foo  This is a comment block
> 
> 	   Everything on this block
> 
> 	   won't be parsed.
> 
> So it won't be parsed, but having a TOC like this isn't need, as
> Sphinx generates it automatically via "toctree" markup. 

Ok.

> > Could we add a proper TOC with sections? My motivation for ReST here would be
> > to make the sections jumpable since it is a large document.
> 
> Just change the toctree depth at index.rst to 2 and you'll see an index
> produced by Sphinx with both levels 1 (doc name) and level 2 (chapters):
> 
> 	.. toctree::
> 	   :maxdepth: 2

Admittedly, I don't have much time at the moment to do these experiments :(

> > Also could we make the different sections appear as a tree in the left
> > sidebar?
> 
> The sidebar follows the maxdepth too.
> 
> > 
> > (2) Arguably several function names in the document HTML output should appear
> > in monospace fonting and/or referring to the documentation for real function
> > names, but these can be fixed as we go, I guess.
> 
> If you want monospaced fonts, just use: ``monospaced_symbol_foo`` within
> any paragraph, or place the monospaced data inside a code-block:
> 
> 	::
> 
> 		This will be monospaced.
> 
> > 
> > (3) Things like smp_load_acquire() and spin_lock() should probably refer to
> > the documentation for those elsewhere..
> 
> Jon added an automarkup extension on Kernel 5.2. So, all functions that
> are defined elsewhere will automatically generate an hyperlink. For that to
> happen, you need to add the kernel-doc markup at the *.h or *.c file where
> the function is declared and use the kernel-doc markup somewhere within the
> Kernel Documentation/.
> 
> > 
> > (4) I would argue that every occurence of
> > A ->(some dependency) B should be replaced with fixed size font in the HTML
> > results.
> 
> Just place those with ``A -> (some dependency)``. This will make them use
> a fixed size font.

Ok, understood all these. I guess my point was all of these will need to be
done to make this document useful from a ReST conversion standpoint. Until
then it is probably just better off being plain text - since there are so
many of those ``A -> (dep) B`` things.

> > Arguably it is better IMO if the whole document is fixed size font in the
> > HTML output because so many things need to be fixed size, but that my just be
> > my opinion.
> 
> Just my 2 cents here, but having the entire document using a fixed size
> font makes it more boring to read. Having just the symbols with a fixed size
> is a common convention used on technical books, and helps to make easier
> to identify the symbols while reading the docs.
> 
> That's said, Sphinx doesn't have any tag to switch the font for the entire
> document. All it can be done is to define a CSS and apply it for the
> doc - or to place everything within a code-block, with will suppress all
> markup tags, including cross-references for functions.

Ok, got it.

> The problem with CSS is that you need to write both an html CSS file
> and add LaTeX macros associated to this "CSS style" (technically, LaTeX
> doesn't have a CSS concept, but Sphinx emulates it).

Yeah I don't think we want to do CSS here. So the correct thing to do would
be to place all fixed-width things within double backticks, if someone had
the time to do it. I am currently spending time understanding the document's
content itself..

thanks for the effort, it could probably serve as a good future reference,

 - Joel


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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
  2019-07-30 22:00       ` Mauro Carvalho Chehab
@ 2019-07-30 22:21         ` Joel Fernandes
  2019-07-30 23:00           ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 75+ messages in thread
From: Joel Fernandes @ 2019-07-30 22:21 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
	Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
	linux-doc

On Tue, Jul 30, 2019 at 07:00:28PM -0300, Mauro Carvalho Chehab wrote:
> Em Tue, 30 Jul 2019 17:50:07 -0400
> Joel Fernandes <joel@joelfernandes.org> escreveu:
> 
> > On Tue, Jul 30, 2019 at 02:22:50PM -0700, Paul E. McKenney wrote:
> > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:  
> > > > There are 4 RCU articles that are written on html format.
> > > > 
> > > > The way they are, they can't be part of the Linux Kernel
> > > > documentation body nor share the styles and pdf output.
> > > > 
> > > > So, convert them to ReST format.
> > > > 
> > > > This way, make htmldocs and make pdfdocs will produce a
> > > > documentation output that will be like the original ones, but
> > > > will be part of the Linux Kernel documentation body.
> > > > 
> > > > Part of the conversion was done with the help of pandoc, but
> > > > the result had some broken things that had to be manually
> > > > fixed.
> > > > 
> > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>  
> > > 
> > > I am having some trouble applying these, at least in part due to UTF-8
> > > sequences, for example double left quotation mark.  These end up being
> > > "=E2=80=9C", with a few space characters turned into "=20".
> > > 
> > > Any advice on how to apply these?  Should I just pull commits from
> > > somewhere?  
> > 
> > I was able to successfully apply and build this particular patch. I think
> > this is the only one in the series that applies to RCU.
> > 
> > Sadly, I can't find the patch in any of the public archives, but I could
> > perhaps email it to you as an .mbox attach which 'git am' should be able to
> > apply.
> > 
> > Mauro did say he was going to add some more details to changelog, or it could
> > be added when it is applied:
> > https://lore.kernel.org/rcu/20190726154550.5eeae294@coco.lan/
> 
> Yeah, I'm also planning to address at least some of the issues you
> pointed, in order to improve the html output, but got sidetracked by something 
> else and didn't find any time yet to finish. I'm adding some CI automation for
> the media subsystem in order to help us dealing with the huge amount of patches
> we receive there.
> 
> Feel free to add those details to the changelog. I may find some spare time 
> this week or the next one for the improvements you suggested, but those 
> could be sent on followup patches, once done.

Ok, I will re-send this RCU patch with the changes, leave this one to me.

The other memory model one, needs a lot more work so we can keep that aside
for now till someone has the time.

thanks,

 - Joel


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

* Re: [PATCH] tools: memory-model: add it to the Documentation body
  2019-07-30 22:17           ` Joel Fernandes
@ 2019-07-30 22:57             ` Mauro Carvalho Chehab
  2019-07-31 13:52                 ` Alan Stern
  0 siblings, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-30 22:57 UTC (permalink / raw)
  To: Joel Fernandes
  Cc: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Alan Stern, Andrea Parri, Will Deacon,
	Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
	Jade Alglave, Luc Maranget, Paul E. McKenney, Akira Yokosawa,
	Daniel Lustig, Ingo Molnar, Jason Gunthorpe, SeongJae Park,
	linux-arch

Em Tue, 30 Jul 2019 18:17:01 -0400
Joel Fernandes <joel@joelfernandes.org> escreveu:

> On Sat, Jul 27, 2019 at 12:37:54PM -0300, Mauro Carvalho Chehab wrote:
> > Em Sat, 27 Jul 2019 14:14:53 +0000
> > Joel Fernandes <joel@joelfernandes.org> escreveu:
> >   
> > > On Fri, Jul 26, 2019 at 04:01:37PM -0300, Mauro Carvalho Chehab wrote:  
> > > > The books at tools/memory-model/Documentation are very well
> > > > formatted. Congrats to the ones that wrote them!
> > > > 
> > > > The manual conversion to ReST is really trivial:
> > > > 
> > > > 	- Add document titles;
> > > > 	- change the bullets on some lists;
> > > > 	- mark code blocks.    
> > > 
> > > Thanks so much, some feedback:  
> > > > 
> > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>    
> > > 
> > > (1)
> > > I could not find the table of contents appear in the HTML output for this.
> > > Basically this list in the beginning doesn't render:
> > >   1. INTRODUCTION
> > >   2. BACKGROUND
> > >   3. A SIMPLE EXAMPLE
> > >   4. A SELECTION OF MEMORY MODELS
> > >   5. ORDERING AND CYCLES  
> > 
> > Yes. It is written as a comment, like:
> > 
> > 	.. foo  This is a comment block
> > 
> > 	   Everything on this block
> > 
> > 	   won't be parsed.
> > 
> > So it won't be parsed, but having a TOC like this isn't need, as
> > Sphinx generates it automatically via "toctree" markup.   
> 
> Ok.
> 
> > > Could we add a proper TOC with sections? My motivation for ReST here would be
> > > to make the sections jumpable since it is a large document.  
> > 
> > Just change the toctree depth at index.rst to 2 and you'll see an index
> > produced by Sphinx with both levels 1 (doc name) and level 2 (chapters):
> > 
> > 	.. toctree::
> > 	   :maxdepth: 2  
> 
> Admittedly, I don't have much time at the moment to do these experiments :(
> 
> > > Also could we make the different sections appear as a tree in the left
> > > sidebar?  
> > 
> > The sidebar follows the maxdepth too.
> >   
> > > 
> > > (2) Arguably several function names in the document HTML output should appear
> > > in monospace fonting and/or referring to the documentation for real function
> > > names, but these can be fixed as we go, I guess.  
> > 
> > If you want monospaced fonts, just use: ``monospaced_symbol_foo`` within
> > any paragraph, or place the monospaced data inside a code-block:
> > 
> > 	::
> > 
> > 		This will be monospaced.
> >   
> > > 
> > > (3) Things like smp_load_acquire() and spin_lock() should probably refer to
> > > the documentation for those elsewhere..  
> > 
> > Jon added an automarkup extension on Kernel 5.2. So, all functions that
> > are defined elsewhere will automatically generate an hyperlink. For that to
> > happen, you need to add the kernel-doc markup at the *.h or *.c file where
> > the function is declared and use the kernel-doc markup somewhere within the
> > Kernel Documentation/.
> >   
> > > 
> > > (4) I would argue that every occurence of
> > > A ->(some dependency) B should be replaced with fixed size font in the HTML
> > > results.  
> > 
> > Just place those with ``A -> (some dependency)``. This will make them use
> > a fixed size font.  
> 
> Ok, understood all these. I guess my point was all of these will need to be
> done to make this document useful from a ReST conversion standpoint. Until
> then it is probably just better off being plain text - since there are so
> many of those ``A -> (dep) B`` things.
> 
> > > Arguably it is better IMO if the whole document is fixed size font in the
> > > HTML output because so many things need to be fixed size, but that my just be
> > > my opinion.  
> > 
> > Just my 2 cents here, but having the entire document using a fixed size
> > font makes it more boring to read. Having just the symbols with a fixed size
> > is a common convention used on technical books, and helps to make easier
> > to identify the symbols while reading the docs.
> > 
> > That's said, Sphinx doesn't have any tag to switch the font for the entire
> > document. All it can be done is to define a CSS and apply it for the
> > doc - or to place everything within a code-block, with will suppress all
> > markup tags, including cross-references for functions.  
> 
> Ok, got it.
> 
> > The problem with CSS is that you need to write both an html CSS file
> > and add LaTeX macros associated to this "CSS style" (technically, LaTeX
> > doesn't have a CSS concept, but Sphinx emulates it).  
> 
> Yeah I don't think we want to do CSS here. So the correct thing to do would
> be to place all fixed-width things within double backticks, if someone had
> the time to do it. I am currently spending time understanding the document's
> content itself..
> 
> thanks for the effort, it could probably serve as a good future reference,

On a very quick look, it seems that, if we replace:

	(\S+\s->\S*\s\w+)

by:
	``\1``


On an editor that would allow to manually replace the regex (like kate),
most of those can be get.

See patch enclosed.


Thanks,
Mauro

[PATCH] Use monotonic fonts for ``A -> (dep) B`` 

Manually replace:

	(\S+\s->\S*\s\w+)

by:
	``\1``

On their occurrences and fix a couple of places where it doesn't
hit well.

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

diff --git a/tools/memory-model/Documentation/explanation.rst b/tools/memory-model/Documentation/explanation.rst
index 227ec75f8dc4..9b5d10cef0c2 100644
--- a/tools/memory-model/Documentation/explanation.rst
+++ b/tools/memory-model/Documentation/explanation.rst
@@ -332,7 +332,7 @@ can think of it as the order in which statements occur in the source
 code after branches are taken into account and loops have been
 unrolled.  A better description might be the order in which
 instructions are presented to a CPU's execution unit.  Thus, we say
-that X is po-before Y (written as "X ->po Y" in formulas) if X occurs
+that X is po-before Y (written as ``X ->po Y`` in formulas) if X occurs
 before Y in the instruction stream.
 
 This is inherently a single-CPU relation; two instructions executing
@@ -485,9 +485,9 @@ which depends on the value obtained by the READ_ONCE(); hence there is
 a control dependency from the load to the store.
 
 It should be pretty obvious that events can only depend on reads that
-come earlier in program order.  Symbolically, if we have R ->data X,
-R ->addr X, or R ->ctrl X (where R is a read event), then we must also
-have R ->po X.  It wouldn't make sense for a computation to depend
+come earlier in program order.  Symbolically, if we have ``R ->data X``,
+``R ->addr X``, or ``R ->ctrl X`` (where R is a read event), then we must also
+have ``R ->po X``.  It wouldn't make sense for a computation to depend
 somehow on a value that doesn't get loaded from shared memory until
 later in the code!
 
@@ -498,7 +498,7 @@ THE READS-FROM RELATION: rf, rfi, and rfe
 The reads-from relation (rf) links a write event to a read event when
 the value loaded by the read is the value that was stored by the
 write.  In colloquial terms, the load "reads from" the store.  We
-write W ->rf R to indicate that the load R reads from the store W.  We
+write ``W ->rf R`` to indicate that the load R reads from the store W.  We
 further distinguish the cases where the load and the store occur on
 the same CPU (internal reads-from, or rfi) and where they occur on
 different CPUs (external reads-from, or rfe).
@@ -579,26 +579,26 @@ that value comes third, and so on.
 You can think of the coherence order as being the order in which the
 stores reach x's location in memory (or if you prefer a more
 hardware-centric view, the order in which the stores get written to
-x's cache line).  We write W ->co W' if W comes before W' in the
+x's cache line).  We write ``W ->co W'`` if W comes before W' in the
 coherence order, that is, if the value stored by W gets overwritten,
 directly or indirectly, by the value stored by W'.
 
 Coherence order is required to be consistent with program order.  This
 requirement takes the form of four coherency rules:
 
-	Write-write coherence: If W ->po-loc W' (i.e., W comes before
+	Write-write coherence: If ``W ->po-loc W'`` (i.e., W comes before
 	W' in program order and they access the same location), where W
-	and W' are two stores, then W ->co W'.
+	and W' are two stores, then ``W ->co W'``.
 
-	Write-read coherence: If W ->po-loc R, where W is a store and R
+	Write-read coherence: If ``W ->po-loc R``, where W is a store and R
 	is a load, then R must read from W or from some other store
 	which comes after W in the coherence order.
 
-	Read-write coherence: If R ->po-loc W, where R is a load and W
+	Read-write coherence: If ``R ->po-loc W``, where R is a load and W
 	is a store, then the store which R reads from must come before
 	W in the coherence order.
 
-	Read-read coherence: If R ->po-loc R', where R and R' are two
+	Read-read coherence: If ``R ->po-loc R'``, where R and R' are two
 	loads, then either they read from the same store or else the
 	store read by R comes before the store read by R' in the
 	coherence order.
@@ -694,7 +694,7 @@ THE FROM-READS RELATION: fr, fri, and fre
 
 The from-reads relation (fr) can be a little difficult for people to
 grok.  It describes the situation where a load reads a value that gets
-overwritten by a store.  In other words, we have R ->fr W when the
+overwritten by a store.  In other words, we have ``R ->fr W`` when the
 value that R reads is overwritten (directly or indirectly) by W, or
 equivalently, when R reads from a store which comes earlier than W in
 the coherence order.
@@ -723,7 +723,7 @@ different CPUs).
 
 Note that the fr relation is determined entirely by the rf and co
 relations; it is not independent.  Given a read event R and a write
-event W for the same location, we will have R ->fr W if and only if
+event W for the same location, we will have ``R ->fr W`` if and only if
 the write which R reads from is co-before W.  In symbols,
 
 ::
@@ -850,13 +850,13 @@ defined to link memory access events E and F whenever:
 	event occurs between them in program order; or
 
 	F is a release fence and some X comes before F in program order,
-	where either X = E or else E ->rf X; or
+	where either ``X = E`` or else ``E ->rf X``; or
 
 	A strong fence event occurs between some X and F in program
-	order, where either X = E or else E ->rf X.
+	order, where either ``X = E`` or else ``E ->rf X``.
 
 The operational model requires that whenever W and W' are both stores
-and W ->cumul-fence W', then W must propagate to any given CPU
+and ``W ->cumul-fence W'``, then W must propagate to any given CPU
 before W' does.  However, for different CPUs C and C', it does not
 require W to propagate to C before W' propagates to C'.
 
@@ -910,7 +910,7 @@ first for CPU 0, then CPU 1, etc.
 
 You can check that the four coherency rules imply that the rf, co, fr,
 and po-loc relations agree with this global ordering; in other words,
-whenever we have X ->rf Y or X ->co Y or X ->fr Y or X ->po-loc Y, the
+whenever we have ``X ->rf Y`` or ``X ->co Y`` or ``X ->fr Y`` or ``X ->po-loc Y``, the
 X event comes before the Y event in the global ordering.  The LKMM's
 "coherence" axiom expresses this by requiring the union of these
 relations not to have any cycles.  This means it must not be possible
@@ -977,7 +977,7 @@ po.
 
 The operational model already includes a description of one such
 situation: Fences are a source of ppo links.  Suppose X and Y are
-memory accesses with X ->po Y; then the CPU must execute X before Y if
+memory accesses with ``X ->po Y``; then the CPU must execute X before Y if
 any of the following hold:
 
 	A strong (smp_mb() or synchronize_rcu()) fence occurs between
@@ -996,7 +996,7 @@ any of the following hold:
 Another possibility, not mentioned earlier but discussed in the next
 section, is:
 
-	X and Y are both loads, X ->addr Y (i.e., there is an address
+	X and Y are both loads, ``X ->addr Y`` (i.e., there is an address
 	dependency from X to Y), and X is a READ_ONCE() or an atomic
 	access.
 
@@ -1176,25 +1176,25 @@ The happens-before relation (hb) links memory accesses that have to
 execute in a certain order.  hb includes the ppo relation and two
 others, one of which is rfe.
 
-W ->rfe R implies that W and R are on different CPUs.  It also means
+``W ->rfe R`` implies that W and R are on different CPUs.  It also means
 that W's store must have propagated to R's CPU before R executed;
 otherwise R could not have read the value stored by W.  Therefore W
-must have executed before R, and so we have W ->hb R.
+must have executed before R, and so we have ``W ->hb R``.
 
-The equivalent fact need not hold if W ->rfi R (i.e., W and R are on
+The equivalent fact need not hold if ``W ->rfi R`` (i.e., W and R are on
 the same CPU).  As we have already seen, the operational model allows
 W's value to be forwarded to R in such cases, meaning that R may well
 execute before W does.
 
 It's important to understand that neither coe nor fre is included in
 hb, despite their similarities to rfe.  For example, suppose we have
-W ->coe W'.  This means that W and W' are stores to the same location,
+``W ->coe W'``.  This means that W and W' are stores to the same location,
 they execute on different CPUs, and W comes before W' in the coherence
 order (i.e., W' overwrites W).  Nevertheless, it is possible for W' to
 execute before W, because the decision as to which store overwrites
 the other is made later by the memory subsystem.  When the stores are
 nearly simultaneous, either one can come out on top.  Similarly,
-R ->fre W means that W overwrites the value which R reads, but it
+``R ->fre W`` means that W overwrites the value which R reads, but it
 doesn't mean that W has to execute after R.  All that's necessary is
 for the memory subsystem not to propagate W to R's CPU until after R
 has executed, which is possible if W executes shortly before R.
@@ -1393,10 +1393,10 @@ The existence of a pb link from E to F implies that E must execute
 before F.  To see why, suppose that F executed first.  Then W would
 have propagated to E's CPU before E executed.  If E was a store, the
 memory subsystem would then be forced to make E come after W in the
-coherence order, contradicting the fact that E ->coe W.  If E was a
+coherence order, contradicting the fact that ``E ->coe W``.  If E was a
 load, the memory subsystem would then be forced to satisfy E's read
 request with the value stored by W or an even later store,
-contradicting the fact that E ->fre W.
+contradicting the fact that ``E ->fre W``.
 
 A good example illustrating how pb works is the SB pattern with strong
 fences::
@@ -1518,9 +1518,9 @@ entirely clear.  The LKMM formalizes this notion by means of the
 rcu-link relation.  rcu-link encompasses a very general notion of
 "before": If E and F are RCU fence events (i.e., rcu_read_lock(),
 rcu_read_unlock(), or synchronize_rcu()) then among other things,
-E ->rcu-link F includes cases where E is po-before some memory-access
+``E ->rcu-link F`` includes cases where E is po-before some memory-access
 event X, F is po-after some memory-access event Y, and we have any of
-X ->rfe Y, X ->co Y, or X ->fr Y.
+``X ->rfe Y``, ``X ->co Y``, or ``X ->fr Y``.
 
 The formal definition of the rcu-link relation is more than a little
 obscure, and we won't give it here.  It is closely related to the pb
@@ -1532,22 +1532,22 @@ The LKMM also defines the rcu-gp and rcu-rscsi relations.  They bring
 grace periods and read-side critical sections into the picture, in the
 following way:
 
-	E ->rcu-gp F means that E and F are in fact the same event,
+	``E ->rcu-gp F`` means that E and F are in fact the same event,
 	and that event is a synchronize_rcu() fence (i.e., a grace
 	period).
 
-	E ->rcu-rscsi F means that E and F are the rcu_read_unlock()
+	``E ->rcu-rscsi F`` means that E and F are the rcu_read_unlock()
 	and rcu_read_lock() fence events delimiting some read-side
 	critical section.  (The 'i' at the end of the name emphasizes
 	that this relation is "inverted": It links the end of the
 	critical section to the start.)
 
 If we think of the rcu-link relation as standing for an extended
-"before", then X ->rcu-gp Y ->rcu-link Z roughly says that X is a
+"before", then ``X ->rcu-gp Y ->rcu-link Z`` roughly says that X is a
 grace period which ends before Z begins.  (In fact it covers more than
 this, because it also includes cases where some store propagates to
 Z's CPU before Z begins but doesn't propagate to some other CPU until
-after X ends.)  Similarly, X ->rcu-rscsi Y ->rcu-link Z says that X is
+after X ends.)  Similarly, ``X ->rcu-rscsi Y ->rcu-link Z`` says that X is
 the end of a critical section which starts before Z begins.
 
 The LKMM goes on to define the rcu-fence relation as a sequence of
@@ -1557,18 +1557,18 @@ example::
 
 	X ->rcu-gp Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
 
-would imply that X ->rcu-fence V, because this sequence contains two
+would imply that ``X ->rcu-fence V``, because this sequence contains two
 rcu-gp links and one rcu-rscsi link.  (It also implies that
-X ->rcu-fence T and Z ->rcu-fence V.)  On the other hand::
+``X ->rcu-fence T`` and ``Z ->rcu-fence V``.)  On the other hand::
 
 	X ->rcu-rscsi Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
 
-does not imply X ->rcu-fence V, because the sequence contains only
+does not imply ``X ->rcu-fence V``, because the sequence contains only
 one rcu-gp link but two rcu-rscsi links.
 
 The rcu-fence relation is important because the Grace Period Guarantee
 means that rcu-fence acts kind of like a strong fence.  In particular,
-E ->rcu-fence F implies not only that E begins before F ends, but also
+``E ->rcu-fence F`` implies not only that E begins before F ends, but also
 that any write po-before E will propagate to every CPU before any
 instruction po-after F can execute.  (However, it does not imply that
 E must execute before F; in fact, each synchronize_rcu() fence event
@@ -1604,13 +1604,13 @@ covered by rcu-fence.
 Finally, the LKMM defines the RCU-before (rb) relation in terms of
 rcu-fence.  This is done in essentially the same way as the pb
 relation was defined in terms of strong-fence.  We will omit the
-details; the end result is that E ->rb F implies E must execute
-before F, just as E ->pb F does (and for much the same reasons).
+details; the end result is that ``E ->rb F`` implies E must execute
+before F, just as ``E ->pb F`` does (and for much the same reasons).
 
 Putting this all together, the LKMM expresses the Grace Period
 Guarantee by requiring that the rb relation does not contain a cycle.
 Equivalently, this "rcu" axiom requires that there are no events E
-and F with E ->rcu-link F ->rcu-fence E.  Or to put it a third way,
+and F with ``E ->rcu-link F ->rcu-fence E``.  Or to put it a third way,
 the axiom requires that there are no cycles consisting of rcu-gp and
 rcu-rscsi alternating with rcu-link, where the number of rcu-gp links
 is >= the number of rcu-rscsi links.
@@ -1649,8 +1649,8 @@ by rcu-link::
 
 	S ->rcu-link U.
 
-Since S is a grace period we have S ->rcu-gp S, and since L and U are
-the start and end of the critical section C we have U ->rcu-rscsi L.
+Since S is a grace period we have ``S ->rcu-gp S``, and since L and U are
+the start and end of the critical section C we have ``U ->rcu-rscsi L``.
 From this we obtain::
 
 	S ->rcu-gp S ->rcu-link U ->rcu-rscsi L ->rcu-link S,
@@ -1683,16 +1683,16 @@ time with statement labels added::
 
 
 If r2 = 0 at the end then P0's store at Y overwrites the value that
-P1's load at W reads from, so we have W ->fre Y.  Since S ->po W and
-also Y ->po U, we get S ->rcu-link U.  In addition, S ->rcu-gp S
+P1's load at W reads from, so we have ``W ->fre Y``.  Since ``S ->po W`` and
+also ``Y ->po U``, we get ``S ->rcu-link U``.  In addition, ``S ->rcu-gp S``
 because S is a grace period.
 
 If r1 = 1 at the end then P1's load at Z reads from P0's store at X,
-so we have X ->rfe Z.  Together with L ->po X and Z ->po S, this
-yields L ->rcu-link S.  And since L and U are the start and end of a
-critical section, we have U ->rcu-rscsi L.
+so we have ``X ->rfe Z``.  Together with ``L ->po X`` and ``Z ->po S``, this
+yields ``L ->rcu-link S``.  And since L and U are the start and end of a
+critical section, we have ``U ->rcu-rscsi L``.
 
-Then U ->rcu-rscsi L ->rcu-link S ->rcu-gp S ->rcu-link U is a
+Then ``U ->rcu-rscsi L ->rcu-link S ->rcu-gp S ->rcu-link U`` is a
 forbidden cycle, violating the "rcu" axiom.  Hence the outcome is not
 allowed by the LKMM, as we would expect.
 
@@ -1729,9 +1729,9 @@ For contrast, let's see what can happen in a more complicated example::
 		U2: rcu_read_unlock();
 	}
 
-If r0 = r1 = r2 = 1 at the end, then similar reasoning to before shows
-that U0 ->rcu-rscsi L0 ->rcu-link S1 ->rcu-gp S1 ->rcu-link U2 ->rcu-rscsi
-L2 ->rcu-link U0.  However this cycle is not forbidden, because the
+If ``r0 = r1 = r2 = 1`` at the end, then similar reasoning to before shows
+that ``U0 ->rcu-rscsi L0 ->rcu-link S1 ->rcu-gp S1 ->rcu-link U2 ->rcu-rscsi
+L2 ->rcu-link U0``.  However this cycle is not forbidden, because the
 sequence of relations contains fewer instances of rcu-gp (one) than of
 rcu-rscsi (two).  Consequently the outcome is allowed by the LKMM.
 The following instruction timing diagram shows how it might actually


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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
  2019-07-30 22:21         ` Joel Fernandes
@ 2019-07-30 23:00           ` Mauro Carvalho Chehab
  2019-07-30 23:15             ` Joel Fernandes
  0 siblings, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-30 23:00 UTC (permalink / raw)
  To: Joel Fernandes
  Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
	Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
	linux-doc

Em Tue, 30 Jul 2019 18:21:30 -0400
Joel Fernandes <joel@joelfernandes.org> escreveu:

> On Tue, Jul 30, 2019 at 07:00:28PM -0300, Mauro Carvalho Chehab wrote:
> > Em Tue, 30 Jul 2019 17:50:07 -0400
> > Joel Fernandes <joel@joelfernandes.org> escreveu:
> >   
> > > On Tue, Jul 30, 2019 at 02:22:50PM -0700, Paul E. McKenney wrote:  
> > > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:    
> > > > > There are 4 RCU articles that are written on html format.
> > > > > 
> > > > > The way they are, they can't be part of the Linux Kernel
> > > > > documentation body nor share the styles and pdf output.
> > > > > 
> > > > > So, convert them to ReST format.
> > > > > 
> > > > > This way, make htmldocs and make pdfdocs will produce a
> > > > > documentation output that will be like the original ones, but
> > > > > will be part of the Linux Kernel documentation body.
> > > > > 
> > > > > Part of the conversion was done with the help of pandoc, but
> > > > > the result had some broken things that had to be manually
> > > > > fixed.
> > > > > 
> > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>    
> > > > 
> > > > I am having some trouble applying these, at least in part due to UTF-8
> > > > sequences, for example double left quotation mark.  These end up being
> > > > "=E2=80=9C", with a few space characters turned into "=20".
> > > > 
> > > > Any advice on how to apply these?  Should I just pull commits from
> > > > somewhere?    
> > > 
> > > I was able to successfully apply and build this particular patch. I think
> > > this is the only one in the series that applies to RCU.
> > > 
> > > Sadly, I can't find the patch in any of the public archives, but I could
> > > perhaps email it to you as an .mbox attach which 'git am' should be able to
> > > apply.
> > > 
> > > Mauro did say he was going to add some more details to changelog, or it could
> > > be added when it is applied:
> > > https://lore.kernel.org/rcu/20190726154550.5eeae294@coco.lan/  
> > 
> > Yeah, I'm also planning to address at least some of the issues you
> > pointed, in order to improve the html output, but got sidetracked by something 
> > else and didn't find any time yet to finish. I'm adding some CI automation for
> > the media subsystem in order to help us dealing with the huge amount of patches
> > we receive there.
> > 
> > Feel free to add those details to the changelog. I may find some spare time 
> > this week or the next one for the improvements you suggested, but those 
> > could be sent on followup patches, once done.  
> 
> Ok, I will re-send this RCU patch with the changes, leave this one to me.
> 
> The other memory model one, needs a lot more work so we can keep that aside
> for now till someone has the time.

Yeah, feel free to do what fits best with regards to this one.

If you prefer to merge it instead, I'm enclosing the last version of it,
with that quick hack I just wrote, plus the change of the toctree for
it to produce the 2-level index.

Thanks,
Mauro

[PATCH] tools: memory-model: add it to the Documentation body

The books at tools/memory-model/Documentation are very well
formatted. Congrats to the ones that wrote them!

The manual conversion to ReST is really trivial:

	- Add document titles;
	- change the bullets on some lists;
	- mark code blocks.

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

diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst
index 976e85adffe8..7e6500a6fa76 100644
--- a/Documentation/core-api/refcount-vs-atomic.rst
+++ b/Documentation/core-api/refcount-vs-atomic.rst
@@ -17,7 +17,7 @@ in order to help maintainers validate their code against the change in
 these memory ordering guarantees.
 
 The terms used through this document try to follow the formal LKMM defined in
-tools/memory-model/Documentation/explanation.txt.
+tools/memory-model/Documentation/explanation.rst.
 
 memory-barriers.txt and atomic_t.txt provide more background to the
 memory ordering in general and for atomic operations specifically.
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 2df5a3da563c..5123770ba77e 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -36,6 +36,7 @@ trying to get it to work optimally on a given system.
 
    admin-guide/index
    kbuild/index
+   tools/index
 
 Firmware-related documentation
 ------------------------------
diff --git a/Documentation/tools/index.rst b/Documentation/tools/index.rst
new file mode 100644
index 000000000000..f540d9cc75a1
--- /dev/null
+++ b/Documentation/tools/index.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========
+Linux Tools
+===========
+
+.. toctree::
+   :maxdepth: 2
+
+   memory-model/index
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/Documentation/tools/memory-model b/Documentation/tools/memory-model
new file mode 120000
index 000000000000..020ed38ce302
--- /dev/null
+++ b/Documentation/tools/memory-model
@@ -0,0 +1 @@
+../../tools/memory-model/Documentation/
\ No newline at end of file
diff --git a/tools/memory-model/Documentation/cheatsheet.rst b/tools/memory-model/Documentation/cheatsheet.rst
new file mode 100644
index 000000000000..35f8749b8a53
--- /dev/null
+++ b/tools/memory-model/Documentation/cheatsheet.rst
@@ -0,0 +1,36 @@
+===========
+Cheat Sheet
+===========
+
+::
+
+				    Prior Operation     Subsequent Operation
+				    ---------------  ---------------------------
+				 C  Self  R  W  RMW  Self  R  W  DR  DW  RMW  SV
+				--  ----  -  -  ---  ----  -  -  --  --  ---  --
+
+  Store, e.g., WRITE_ONCE()            Y                                       Y
+  Load, e.g., READ_ONCE()              Y                          Y   Y        Y
+  Unsuccessful RMW operation           Y                          Y   Y        Y
+  rcu_dereference()                    Y                          Y   Y        Y
+  Successful *_acquire()               R                   Y  Y   Y   Y    Y   Y
+  Successful *_release()         C        Y  Y    Y     W                      Y
+  smp_rmb()                               Y       R        Y      Y        R
+  smp_wmb()                                  Y    W           Y       Y    W
+  smp_mb() & synchronize_rcu()  CP        Y  Y    Y        Y  Y   Y   Y    Y
+  Successful full non-void RMW  CP     Y  Y  Y    Y     Y  Y  Y   Y   Y    Y   Y
+  smp_mb__before_atomic()       CP        Y  Y    Y        a  a   a   a    Y
+  smp_mb__after_atomic()        CP        a  a    Y        Y  Y   Y   Y    Y
+
+
+  Key:    C:      Ordering is cumulative
+	  P:      Ordering propagates
+	  R:      Read, for example, READ_ONCE(), or read portion of RMW
+	  W:      Write, for example, WRITE_ONCE(), or write portion of RMW
+	  Y:      Provides ordering
+	  a:      Provides ordering given intervening RMW atomic operation
+	  DR:     Dependent read (address dependency)
+	  DW:     Dependent write (address, data, or control dependency)
+	  RMW:    Atomic read-modify-write operation
+	  SELF:   Orders self, as opposed to accesses before and/or after
+	  SV:     Orders later accesses to the same variable
diff --git a/tools/memory-model/Documentation/cheatsheet.txt b/tools/memory-model/Documentation/cheatsheet.txt
deleted file mode 100644
index 33ba98d72b16..000000000000
--- a/tools/memory-model/Documentation/cheatsheet.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-                                  Prior Operation     Subsequent Operation
-                                  ---------------  ---------------------------
-                               C  Self  R  W  RMW  Self  R  W  DR  DW  RMW  SV
-                              --  ----  -  -  ---  ----  -  -  --  --  ---  --
-
-Store, e.g., WRITE_ONCE()            Y                                       Y
-Load, e.g., READ_ONCE()              Y                          Y   Y        Y
-Unsuccessful RMW operation           Y                          Y   Y        Y
-rcu_dereference()                    Y                          Y   Y        Y
-Successful *_acquire()               R                   Y  Y   Y   Y    Y   Y
-Successful *_release()         C        Y  Y    Y     W                      Y
-smp_rmb()                               Y       R        Y      Y        R
-smp_wmb()                                  Y    W           Y       Y    W
-smp_mb() & synchronize_rcu()  CP        Y  Y    Y        Y  Y   Y   Y    Y
-Successful full non-void RMW  CP     Y  Y  Y    Y     Y  Y  Y   Y   Y    Y   Y
-smp_mb__before_atomic()       CP        Y  Y    Y        a  a   a   a    Y
-smp_mb__after_atomic()        CP        a  a    Y        Y  Y   Y   Y    Y
-
-
-Key:	C:	Ordering is cumulative
-	P:	Ordering propagates
-	R:	Read, for example, READ_ONCE(), or read portion of RMW
-	W:	Write, for example, WRITE_ONCE(), or write portion of RMW
-	Y:	Provides ordering
-	a:	Provides ordering given intervening RMW atomic operation
-	DR:	Dependent read (address dependency)
-	DW:	Dependent write (address, data, or control dependency)
-	RMW:	Atomic read-modify-write operation
-	SELF:	Orders self, as opposed to accesses before and/or after
-	SV:	Orders later accesses to the same variable
diff --git a/tools/memory-model/Documentation/explanation.txt b/tools/memory-model/Documentation/explanation.rst
similarity index 92%
rename from tools/memory-model/Documentation/explanation.txt
rename to tools/memory-model/Documentation/explanation.rst
index 68caa9a976d0..9b5d10cef0c2 100644
--- a/tools/memory-model/Documentation/explanation.txt
+++ b/tools/memory-model/Documentation/explanation.rst
@@ -1,5 +1,6 @@
+========================================================
 Explanation of the Linux-Kernel Memory Consistency Model
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+========================================================
 
 :Author: Alan Stern <stern@rowland.harvard.edu>
 :Created: October 2017
@@ -107,7 +108,7 @@ and the flag are memory locations shared between the two CPUs.
 
 We can abstract out the important pieces of the driver code as follows
 (the reason for using WRITE_ONCE() and READ_ONCE() instead of simple
-assignment statements is discussed later):
+assignment statements is discussed later)::
 
 	int buf = 0, flag = 0;
 
@@ -219,7 +220,7 @@ Ordering).  This model predicts that the undesired outcome for the MP
 pattern cannot occur, but in other respects it differs from Sequential
 Consistency.  One example is the Store Buffer (SB) pattern, in which
 each CPU stores to its own shared location and then loads from the
-other CPU's location:
+other CPU's location::
 
 	int x = 0, y = 0;
 
@@ -264,7 +265,7 @@ The counterpart to ordering is a cycle.  Ordering rules out cycles:
 It's not possible to have X ordered before Y, Y ordered before Z, and
 Z ordered before X, because this would mean that X is ordered before
 itself.  The analysis of the MP example under Sequential Consistency
-involved just such an impossible cycle:
+involved just such an impossible cycle::
 
 	W: P0 stores 1 to flag   executes before
 	X: P1 loads 1 from flag  executes before
@@ -331,7 +332,7 @@ can think of it as the order in which statements occur in the source
 code after branches are taken into account and loops have been
 unrolled.  A better description might be the order in which
 instructions are presented to a CPU's execution unit.  Thus, we say
-that X is po-before Y (written as "X ->po Y" in formulas) if X occurs
+that X is po-before Y (written as ``X ->po Y`` in formulas) if X occurs
 before Y in the instruction stream.
 
 This is inherently a single-CPU relation; two instructions executing
@@ -388,7 +389,7 @@ The protections provided by READ_ONCE(), WRITE_ONCE(), and others are
 not perfect; and under some circumstances it is possible for the
 compiler to undermine the memory model.  Here is an example.  Suppose
 both branches of an "if" statement store the same value to the same
-location:
+location::
 
 	r1 = READ_ONCE(x);
 	if (r1) {
@@ -402,7 +403,7 @@ location:
 For this code, the LKMM predicts that the load from x will always be
 executed before either of the stores to y.  However, a compiler could
 lift the stores out of the conditional, transforming the code into
-something resembling:
+something resembling::
 
 	r1 = READ_ONCE(x);
 	WRITE_ONCE(y, 2);
@@ -418,7 +419,7 @@ model's original prediction could be invalidated by the compiler.
 
 Another issue arises from the fact that in C, arguments to many
 operators and function calls can be evaluated in any order.  For
-example:
+example::
 
 	r1 = f(5) + g(6);
 
@@ -440,7 +441,7 @@ control (ctrl).
 
 A read and a write event are linked by a data dependency if the value
 obtained by the read affects the value stored by the write.  As a very
-simple example:
+simple example::
 
 	int x, y;
 
@@ -455,7 +456,7 @@ values of multiple reads.
 A read event and another memory access event are linked by an address
 dependency if the value obtained by the read affects the location
 accessed by the other event.  The second event can be either a read or
-a write.  Here's another simple example:
+a write.  Here's another simple example::
 
 	int a[20];
 	int i;
@@ -471,7 +472,7 @@ pointer.
 
 Finally, a read event and another memory access event are linked by a
 control dependency if the value obtained by the read affects whether
-the second event is executed at all.  Simple example:
+the second event is executed at all.  Simple example::
 
 	int x, y;
 
@@ -484,9 +485,9 @@ which depends on the value obtained by the READ_ONCE(); hence there is
 a control dependency from the load to the store.
 
 It should be pretty obvious that events can only depend on reads that
-come earlier in program order.  Symbolically, if we have R ->data X,
-R ->addr X, or R ->ctrl X (where R is a read event), then we must also
-have R ->po X.  It wouldn't make sense for a computation to depend
+come earlier in program order.  Symbolically, if we have ``R ->data X``,
+``R ->addr X``, or ``R ->ctrl X`` (where R is a read event), then we must also
+have ``R ->po X``.  It wouldn't make sense for a computation to depend
 somehow on a value that doesn't get loaded from shared memory until
 later in the code!
 
@@ -497,7 +498,7 @@ THE READS-FROM RELATION: rf, rfi, and rfe
 The reads-from relation (rf) links a write event to a read event when
 the value loaded by the read is the value that was stored by the
 write.  In colloquial terms, the load "reads from" the store.  We
-write W ->rf R to indicate that the load R reads from the store W.  We
+write ``W ->rf R`` to indicate that the load R reads from the store W.  We
 further distinguish the cases where the load and the store occur on
 the same CPU (internal reads-from, or rfi) and where they occur on
 different CPUs (external reads-from, or rfe).
@@ -510,7 +511,7 @@ Usage of the rf relation implicitly assumes that loads will always
 read from a single store.  It doesn't apply properly in the presence
 of load-tearing, where a load obtains some of its bits from one store
 and some of them from another store.  Fortunately, use of READ_ONCE()
-and WRITE_ONCE() will prevent load-tearing; it's not possible to have:
+and WRITE_ONCE() will prevent load-tearing; it's not possible to have::
 
 	int x = 0;
 
@@ -530,7 +531,7 @@ and end up with r1 = 0x1200 (partly from x's initial value and partly
 from the value stored by P0).
 
 On the other hand, load-tearing is unavoidable when mixed-size
-accesses are used.  Consider this example:
+accesses are used.  Consider this example::
 
 	union {
 		u32	w;
@@ -578,26 +579,26 @@ that value comes third, and so on.
 You can think of the coherence order as being the order in which the
 stores reach x's location in memory (or if you prefer a more
 hardware-centric view, the order in which the stores get written to
-x's cache line).  We write W ->co W' if W comes before W' in the
+x's cache line).  We write ``W ->co W'`` if W comes before W' in the
 coherence order, that is, if the value stored by W gets overwritten,
 directly or indirectly, by the value stored by W'.
 
 Coherence order is required to be consistent with program order.  This
 requirement takes the form of four coherency rules:
 
-	Write-write coherence: If W ->po-loc W' (i.e., W comes before
+	Write-write coherence: If ``W ->po-loc W'`` (i.e., W comes before
 	W' in program order and they access the same location), where W
-	and W' are two stores, then W ->co W'.
+	and W' are two stores, then ``W ->co W'``.
 
-	Write-read coherence: If W ->po-loc R, where W is a store and R
+	Write-read coherence: If ``W ->po-loc R``, where W is a store and R
 	is a load, then R must read from W or from some other store
 	which comes after W in the coherence order.
 
-	Read-write coherence: If R ->po-loc W, where R is a load and W
+	Read-write coherence: If ``R ->po-loc W``, where R is a load and W
 	is a store, then the store which R reads from must come before
 	W in the coherence order.
 
-	Read-read coherence: If R ->po-loc R', where R and R' are two
+	Read-read coherence: If ``R ->po-loc R'``, where R and R' are two
 	loads, then either they read from the same store or else the
 	store read by R comes before the store read by R' in the
 	coherence order.
@@ -612,7 +613,7 @@ requirement that every store eventually becomes visible to every CPU.)
 Any reasonable memory model will include cache coherence.  Indeed, our
 expectation of cache coherence is so deeply ingrained that violations
 of its requirements look more like hardware bugs than programming
-errors:
+errors::
 
 	int x;
 
@@ -628,6 +629,8 @@ write-write coherence rule: Since the store of 23 comes later in
 program order, it must also come later in x's coherence order and
 thus must overwrite the store of 17.
 
+::
+
 	int x = 0;
 
 	P0()
@@ -644,6 +647,8 @@ program order, so it must not read from that store but rather from one
 coming earlier in the coherence order (in this case, x's initial
 value).
 
+::
+
 	int x = 0;
 
 	P0()
@@ -689,12 +694,12 @@ THE FROM-READS RELATION: fr, fri, and fre
 
 The from-reads relation (fr) can be a little difficult for people to
 grok.  It describes the situation where a load reads a value that gets
-overwritten by a store.  In other words, we have R ->fr W when the
+overwritten by a store.  In other words, we have ``R ->fr W`` when the
 value that R reads is overwritten (directly or indirectly) by W, or
 equivalently, when R reads from a store which comes earlier than W in
 the coherence order.
 
-For example:
+For example::
 
 	int x = 0;
 
@@ -718,9 +723,11 @@ different CPUs).
 
 Note that the fr relation is determined entirely by the rf and co
 relations; it is not independent.  Given a read event R and a write
-event W for the same location, we will have R ->fr W if and only if
+event W for the same location, we will have ``R ->fr W`` if and only if
 the write which R reads from is co-before W.  In symbols,
 
+::
+
 	(R ->fr W) := (there exists W' with W' ->rf R and W' ->co W).
 
 
@@ -843,13 +850,13 @@ defined to link memory access events E and F whenever:
 	event occurs between them in program order; or
 
 	F is a release fence and some X comes before F in program order,
-	where either X = E or else E ->rf X; or
+	where either ``X = E`` or else ``E ->rf X``; or
 
 	A strong fence event occurs between some X and F in program
-	order, where either X = E or else E ->rf X.
+	order, where either ``X = E`` or else ``E ->rf X``.
 
 The operational model requires that whenever W and W' are both stores
-and W ->cumul-fence W', then W must propagate to any given CPU
+and ``W ->cumul-fence W'``, then W must propagate to any given CPU
 before W' does.  However, for different CPUs C and C', it does not
 require W to propagate to C before W' propagates to C'.
 
@@ -903,11 +910,11 @@ first for CPU 0, then CPU 1, etc.
 
 You can check that the four coherency rules imply that the rf, co, fr,
 and po-loc relations agree with this global ordering; in other words,
-whenever we have X ->rf Y or X ->co Y or X ->fr Y or X ->po-loc Y, the
+whenever we have ``X ->rf Y`` or ``X ->co Y`` or ``X ->fr Y`` or ``X ->po-loc Y``, the
 X event comes before the Y event in the global ordering.  The LKMM's
 "coherence" axiom expresses this by requiring the union of these
 relations not to have any cycles.  This means it must not be possible
-to find events
+to find events::
 
 	X0 -> X1 -> X2 -> ... -> Xn -> X0,
 
@@ -929,7 +936,7 @@ this case) does not get altered between the read and the write events
 making up the atomic operation.  In particular, if two CPUs perform
 atomic_inc(&x) concurrently, it must be guaranteed that the final
 value of x will be the initial value plus two.  We should never have
-the following sequence of events:
+the following sequence of events::
 
 	CPU 0 loads x obtaining 13;
 					CPU 1 loads x obtaining 13;
@@ -951,6 +958,8 @@ atomic read-modify-write and W' is the write event which R reads from,
 there must not be any stores coming between W' and W in the coherence
 order.  Equivalently,
 
+::
+
 	(R ->rmw W) implies (there is no X with R ->fr X and X ->co W),
 
 where the rmw relation links the read and write events making up each
@@ -968,7 +977,7 @@ po.
 
 The operational model already includes a description of one such
 situation: Fences are a source of ppo links.  Suppose X and Y are
-memory accesses with X ->po Y; then the CPU must execute X before Y if
+memory accesses with ``X ->po Y``; then the CPU must execute X before Y if
 any of the following hold:
 
 	A strong (smp_mb() or synchronize_rcu()) fence occurs between
@@ -987,7 +996,7 @@ any of the following hold:
 Another possibility, not mentioned earlier but discussed in the next
 section, is:
 
-	X and Y are both loads, X ->addr Y (i.e., there is an address
+	X and Y are both loads, ``X ->addr Y`` (i.e., there is an address
 	dependency from X to Y), and X is a READ_ONCE() or an atomic
 	access.
 
@@ -1021,7 +1030,7 @@ includes address dependencies to loads in the ppo relation.
 
 On the other hand, dependencies can indirectly affect the ordering of
 two loads.  This happens when there is a dependency from a load to a
-store and a second, po-later load reads from that store:
+store and a second, po-later load reads from that store::
 
 	R ->dep W ->rfi R',
 
@@ -1036,7 +1045,7 @@ R; if the speculation turns out to be wrong then the CPU merely has to
 restart or abandon R'.
 
 (In theory, a CPU might forward a store to a load when it runs across
-an address dependency like this:
+an address dependency like this::
 
 	r1 = READ_ONCE(ptr);
 	WRITE_ONCE(*r1, 17);
@@ -1048,7 +1057,7 @@ However, none of the architectures supported by the Linux kernel do
 this.)
 
 Two memory accesses of the same location must always be executed in
-program order if the second access is a store.  Thus, if we have
+program order if the second access is a store.  Thus, if we have::
 
 	R ->po-loc W
 
@@ -1056,7 +1065,7 @@ program order if the second access is a store.  Thus, if we have
 access the same location), the CPU is obliged to execute W after R.
 If it executed W first then the memory subsystem would respond to R's
 read request with the value stored by W (or an even later store), in
-violation of the read-write coherence rule.  Similarly, if we had
+violation of the read-write coherence rule.  Similarly, if we had::
 
 	W ->po-loc W'
 
@@ -1074,7 +1083,7 @@ AND THEN THERE WAS ALPHA
 
 As mentioned above, the Alpha architecture is unique in that it does
 not appear to respect address dependencies to loads.  This means that
-code such as the following:
+code such as the following::
 
 	int x = 0;
 	int y = -1;
@@ -1128,7 +1137,7 @@ nothing at all on non-Alpha builds) after every READ_ONCE() and atomic
 load.  The effect of the fence is to cause the CPU not to execute any
 po-later instructions until after the local cache has finished
 processing all the stores it has already received.  Thus, if the code
-was changed to:
+was changed to::
 
 	P1()
 	{
@@ -1167,25 +1176,25 @@ The happens-before relation (hb) links memory accesses that have to
 execute in a certain order.  hb includes the ppo relation and two
 others, one of which is rfe.
 
-W ->rfe R implies that W and R are on different CPUs.  It also means
+``W ->rfe R`` implies that W and R are on different CPUs.  It also means
 that W's store must have propagated to R's CPU before R executed;
 otherwise R could not have read the value stored by W.  Therefore W
-must have executed before R, and so we have W ->hb R.
+must have executed before R, and so we have ``W ->hb R``.
 
-The equivalent fact need not hold if W ->rfi R (i.e., W and R are on
+The equivalent fact need not hold if ``W ->rfi R`` (i.e., W and R are on
 the same CPU).  As we have already seen, the operational model allows
 W's value to be forwarded to R in such cases, meaning that R may well
 execute before W does.
 
 It's important to understand that neither coe nor fre is included in
 hb, despite their similarities to rfe.  For example, suppose we have
-W ->coe W'.  This means that W and W' are stores to the same location,
+``W ->coe W'``.  This means that W and W' are stores to the same location,
 they execute on different CPUs, and W comes before W' in the coherence
 order (i.e., W' overwrites W).  Nevertheless, it is possible for W' to
 execute before W, because the decision as to which store overwrites
 the other is made later by the memory subsystem.  When the stores are
 nearly simultaneous, either one can come out on top.  Similarly,
-R ->fre W means that W overwrites the value which R reads, but it
+``R ->fre W`` means that W overwrites the value which R reads, but it
 doesn't mean that W has to execute after R.  All that's necessary is
 for the memory subsystem not to propagate W to R's CPU until after R
 has executed, which is possible if W executes shortly before R.
@@ -1199,7 +1208,7 @@ the first event in the coherence order and propagates to C before the
 second event executes.
 
 This is best explained with some examples.  The simplest case looks
-like this:
+like this::
 
 	int x;
 
@@ -1225,7 +1234,7 @@ event, because P1's store came after P0's store in x's coherence
 order, and P1's store propagated to P0 before P0's load executed.
 
 An equally simple case involves two loads of the same location that
-read from different stores:
+read from different stores::
 
 	int x = 0;
 
@@ -1252,7 +1261,7 @@ P1's store propagated to P0 before P0's second load executed.
 
 Less trivial examples of prop all involve fences.  Unlike the simple
 examples above, they can require that some instructions are executed
-out of program order.  This next one should look familiar:
+out of program order.  This next one should look familiar::
 
 	int buf = 0, flag = 0;
 
@@ -1303,7 +1312,7 @@ rfe link.  You can concoct more exotic examples, containing more than
 one fence, although this quickly leads to diminishing returns in terms
 of complexity.  For instance, here's an example containing a coe link
 followed by two fences and an rfe link, utilizing the fact that
-release fences are A-cumulative:
+release fences are A-cumulative::
 
 	int x, y, z;
 
@@ -1363,7 +1372,7 @@ links.  Let's see how this definition works out.
 
 Consider first the case where E is a store (implying that the sequence
 of links begins with coe).  Then there are events W, X, Y, and Z such
-that:
+that::
 
 	E ->coe W ->cumul-fence* X ->rfe? Y ->strong-fence Z ->hb* F,
 
@@ -1384,13 +1393,13 @@ The existence of a pb link from E to F implies that E must execute
 before F.  To see why, suppose that F executed first.  Then W would
 have propagated to E's CPU before E executed.  If E was a store, the
 memory subsystem would then be forced to make E come after W in the
-coherence order, contradicting the fact that E ->coe W.  If E was a
+coherence order, contradicting the fact that ``E ->coe W``.  If E was a
 load, the memory subsystem would then be forced to satisfy E's read
 request with the value stored by W or an even later store,
-contradicting the fact that E ->fre W.
+contradicting the fact that ``E ->fre W``.
 
 A good example illustrating how pb works is the SB pattern with strong
-fences:
+fences::
 
 	int x = 0, y = 0;
 
@@ -1449,18 +1458,18 @@ span a full grace period.  In more detail, the Guarantee says:
 	For any critical section C and any grace period G, at least
 	one of the following statements must hold:
 
-(1)	C ends before G does, and in addition, every store that
-	propagates to C's CPU before the end of C must propagate to
-	every CPU before G ends.
+	(1)	C ends before G does, and in addition, every store that
+		propagates to C's CPU before the end of C must propagate to
+		every CPU before G ends.
 
-(2)	G starts before C does, and in addition, every store that
-	propagates to G's CPU before the start of G must propagate
-	to every CPU before C starts.
+	(2)	G starts before C does, and in addition, every store that
+		propagates to G's CPU before the start of G must propagate
+		to every CPU before C starts.
 
 In particular, it is not possible for a critical section to both start
 before and end after a grace period.
 
-Here is a simple example of RCU in action:
+Here is a simple example of RCU in action::
 
 	int x, y;
 
@@ -1509,9 +1518,9 @@ entirely clear.  The LKMM formalizes this notion by means of the
 rcu-link relation.  rcu-link encompasses a very general notion of
 "before": If E and F are RCU fence events (i.e., rcu_read_lock(),
 rcu_read_unlock(), or synchronize_rcu()) then among other things,
-E ->rcu-link F includes cases where E is po-before some memory-access
+``E ->rcu-link F`` includes cases where E is po-before some memory-access
 event X, F is po-after some memory-access event Y, and we have any of
-X ->rfe Y, X ->co Y, or X ->fr Y.
+``X ->rfe Y``, ``X ->co Y``, or ``X ->fr Y``.
 
 The formal definition of the rcu-link relation is more than a little
 obscure, and we won't give it here.  It is closely related to the pb
@@ -1523,50 +1532,50 @@ The LKMM also defines the rcu-gp and rcu-rscsi relations.  They bring
 grace periods and read-side critical sections into the picture, in the
 following way:
 
-	E ->rcu-gp F means that E and F are in fact the same event,
+	``E ->rcu-gp F`` means that E and F are in fact the same event,
 	and that event is a synchronize_rcu() fence (i.e., a grace
 	period).
 
-	E ->rcu-rscsi F means that E and F are the rcu_read_unlock()
+	``E ->rcu-rscsi F`` means that E and F are the rcu_read_unlock()
 	and rcu_read_lock() fence events delimiting some read-side
 	critical section.  (The 'i' at the end of the name emphasizes
 	that this relation is "inverted": It links the end of the
 	critical section to the start.)
 
 If we think of the rcu-link relation as standing for an extended
-"before", then X ->rcu-gp Y ->rcu-link Z roughly says that X is a
+"before", then ``X ->rcu-gp Y ->rcu-link Z`` roughly says that X is a
 grace period which ends before Z begins.  (In fact it covers more than
 this, because it also includes cases where some store propagates to
 Z's CPU before Z begins but doesn't propagate to some other CPU until
-after X ends.)  Similarly, X ->rcu-rscsi Y ->rcu-link Z says that X is
+after X ends.)  Similarly, ``X ->rcu-rscsi Y ->rcu-link Z`` says that X is
 the end of a critical section which starts before Z begins.
 
 The LKMM goes on to define the rcu-fence relation as a sequence of
 rcu-gp and rcu-rscsi links separated by rcu-link links, in which the
 number of rcu-gp links is >= the number of rcu-rscsi links.  For
-example:
+example::
 
 	X ->rcu-gp Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
 
-would imply that X ->rcu-fence V, because this sequence contains two
+would imply that ``X ->rcu-fence V``, because this sequence contains two
 rcu-gp links and one rcu-rscsi link.  (It also implies that
-X ->rcu-fence T and Z ->rcu-fence V.)  On the other hand:
+``X ->rcu-fence T`` and ``Z ->rcu-fence V``.)  On the other hand::
 
 	X ->rcu-rscsi Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
 
-does not imply X ->rcu-fence V, because the sequence contains only
+does not imply ``X ->rcu-fence V``, because the sequence contains only
 one rcu-gp link but two rcu-rscsi links.
 
 The rcu-fence relation is important because the Grace Period Guarantee
 means that rcu-fence acts kind of like a strong fence.  In particular,
-E ->rcu-fence F implies not only that E begins before F ends, but also
+``E ->rcu-fence F`` implies not only that E begins before F ends, but also
 that any write po-before E will propagate to every CPU before any
 instruction po-after F can execute.  (However, it does not imply that
 E must execute before F; in fact, each synchronize_rcu() fence event
 is linked to itself by rcu-fence as a degenerate case.)
 
 To prove this in full generality requires some intellectual effort.
-We'll consider just a very simple case:
+We'll consider just a very simple case::
 
 	G ->rcu-gp W ->rcu-link Z ->rcu-rscsi F.
 
@@ -1595,13 +1604,13 @@ covered by rcu-fence.
 Finally, the LKMM defines the RCU-before (rb) relation in terms of
 rcu-fence.  This is done in essentially the same way as the pb
 relation was defined in terms of strong-fence.  We will omit the
-details; the end result is that E ->rb F implies E must execute
-before F, just as E ->pb F does (and for much the same reasons).
+details; the end result is that ``E ->rb F`` implies E must execute
+before F, just as ``E ->pb F`` does (and for much the same reasons).
 
 Putting this all together, the LKMM expresses the Grace Period
 Guarantee by requiring that the rb relation does not contain a cycle.
 Equivalently, this "rcu" axiom requires that there are no events E
-and F with E ->rcu-link F ->rcu-fence E.  Or to put it a third way,
+and F with ``E ->rcu-link F ->rcu-fence E``.  Or to put it a third way,
 the axiom requires that there are no cycles consisting of rcu-gp and
 rcu-rscsi alternating with rcu-link, where the number of rcu-gp links
 is >= the number of rcu-rscsi links.
@@ -1621,7 +1630,7 @@ question, and let S be the synchronize_rcu() fence event for the grace
 period.  Saying that the critical section starts before S means there
 are events Q and R where Q is po-after L (which marks the start of the
 critical section), Q is "before" R in the sense used by the rcu-link
-relation, and R is po-before the grace period S.  Thus we have:
+relation, and R is po-before the grace period S.  Thus we have::
 
 	L ->rcu-link S.
 
@@ -1629,20 +1638,20 @@ Let W be the store mentioned above, let Y come before the end of the
 critical section and witness that W propagates to the critical
 section's CPU by reading from W, and let Z on some arbitrary CPU be a
 witness that W has not propagated to that CPU, where Z happens after
-some event X which is po-after S.  Symbolically, this amounts to:
+some event X which is po-after S.  Symbolically, this amounts to::
 
 	S ->po X ->hb* Z ->fr W ->rf Y ->po U.
 
 The fr link from Z to W indicates that W has not propagated to Z's CPU
 at the time that Z executes.  From this, it can be shown (see the
 discussion of the rcu-link relation earlier) that S and U are related
-by rcu-link:
+by rcu-link::
 
 	S ->rcu-link U.
 
-Since S is a grace period we have S ->rcu-gp S, and since L and U are
-the start and end of the critical section C we have U ->rcu-rscsi L.
-From this we obtain:
+Since S is a grace period we have ``S ->rcu-gp S``, and since L and U are
+the start and end of the critical section C we have ``U ->rcu-rscsi L``.
+From this we obtain::
 
 	S ->rcu-gp S ->rcu-link U ->rcu-rscsi L ->rcu-link S,
 
@@ -1651,7 +1660,7 @@ the Grace Period Guarantee.
 
 For something a little more down-to-earth, let's see how the axiom
 works out in practice.  Consider the RCU code example from above, this
-time with statement labels added:
+time with statement labels added::
 
 	int x, y;
 
@@ -1674,20 +1683,20 @@ time with statement labels added:
 
 
 If r2 = 0 at the end then P0's store at Y overwrites the value that
-P1's load at W reads from, so we have W ->fre Y.  Since S ->po W and
-also Y ->po U, we get S ->rcu-link U.  In addition, S ->rcu-gp S
+P1's load at W reads from, so we have ``W ->fre Y``.  Since ``S ->po W`` and
+also ``Y ->po U``, we get ``S ->rcu-link U``.  In addition, ``S ->rcu-gp S``
 because S is a grace period.
 
 If r1 = 1 at the end then P1's load at Z reads from P0's store at X,
-so we have X ->rfe Z.  Together with L ->po X and Z ->po S, this
-yields L ->rcu-link S.  And since L and U are the start and end of a
-critical section, we have U ->rcu-rscsi L.
+so we have ``X ->rfe Z``.  Together with ``L ->po X`` and ``Z ->po S``, this
+yields ``L ->rcu-link S``.  And since L and U are the start and end of a
+critical section, we have ``U ->rcu-rscsi L``.
 
-Then U ->rcu-rscsi L ->rcu-link S ->rcu-gp S ->rcu-link U is a
+Then ``U ->rcu-rscsi L ->rcu-link S ->rcu-gp S ->rcu-link U`` is a
 forbidden cycle, violating the "rcu" axiom.  Hence the outcome is not
 allowed by the LKMM, as we would expect.
 
-For contrast, let's see what can happen in a more complicated example:
+For contrast, let's see what can happen in a more complicated example::
 
 	int x, y, z;
 
@@ -1720,28 +1729,28 @@ For contrast, let's see what can happen in a more complicated example:
 		U2: rcu_read_unlock();
 	}
 
-If r0 = r1 = r2 = 1 at the end, then similar reasoning to before shows
-that U0 ->rcu-rscsi L0 ->rcu-link S1 ->rcu-gp S1 ->rcu-link U2 ->rcu-rscsi
-L2 ->rcu-link U0.  However this cycle is not forbidden, because the
+If ``r0 = r1 = r2 = 1`` at the end, then similar reasoning to before shows
+that ``U0 ->rcu-rscsi L0 ->rcu-link S1 ->rcu-gp S1 ->rcu-link U2 ->rcu-rscsi
+L2 ->rcu-link U0``.  However this cycle is not forbidden, because the
 sequence of relations contains fewer instances of rcu-gp (one) than of
 rcu-rscsi (two).  Consequently the outcome is allowed by the LKMM.
 The following instruction timing diagram shows how it might actually
-occur:
-
-P0			P1			P2
---------------------	--------------------	--------------------
-rcu_read_lock()
-WRITE_ONCE(y, 1)
-			r1 = READ_ONCE(y)
-			synchronize_rcu() starts
-			.			rcu_read_lock()
-			.			WRITE_ONCE(x, 1)
-r0 = READ_ONCE(x)	.
-rcu_read_unlock()	.
-			synchronize_rcu() ends
-			WRITE_ONCE(z, 1)
-						r2 = READ_ONCE(z)
-						rcu_read_unlock()
+occur::
+
+	P0			P1			P2
+	--------------------	--------------------	--------------------
+	rcu_read_lock()
+	WRITE_ONCE(y, 1)
+				r1 = READ_ONCE(y)
+				synchronize_rcu() starts
+				.			rcu_read_lock()
+				.			WRITE_ONCE(x, 1)
+	r0 = READ_ONCE(x)	.
+	rcu_read_unlock()	.
+				synchronize_rcu() ends
+				WRITE_ONCE(z, 1)
+							r2 = READ_ONCE(z)
+							rcu_read_unlock()
 
 This requires P0 and P2 to execute their loads and stores out of
 program order, but of course they are allowed to do so.  And as you
@@ -1767,26 +1776,26 @@ The LKMM includes locking.  In fact, there is special code for locking
 in the formal model, added in order to make tools run faster.
 However, this special code is intended to be more or less equivalent
 to concepts we have already covered.  A spinlock_t variable is treated
-the same as an int, and spin_lock(&s) is treated almost the same as:
+the same as an int, and spin_lock(&s) is treated almost the same as::
 
 	while (cmpxchg_acquire(&s, 0, 1) != 0)
 		cpu_relax();
 
 This waits until s is equal to 0 and then atomically sets it to 1,
 and the read part of the cmpxchg operation acts as an acquire fence.
-An alternate way to express the same thing would be:
+An alternate way to express the same thing would be::
 
 	r = xchg_acquire(&s, 1);
 
 along with a requirement that at the end, r = 0.  Similarly,
-spin_trylock(&s) is treated almost the same as:
+spin_trylock(&s) is treated almost the same as::
 
 	return !cmpxchg_acquire(&s, 0, 1);
 
 which atomically sets s to 1 if it is currently equal to 0 and returns
 true if it succeeds (the read part of the cmpxchg operation acts as an
 acquire fence only if the operation is successful).  spin_unlock(&s)
-is treated almost the same as:
+is treated almost the same as::
 
 	smp_store_release(&s, 0);
 
@@ -1802,7 +1811,7 @@ requires that every instruction po-before the lock-release must
 execute before any instruction po-after the lock-acquire.  This would
 naturally hold if the release and acquire operations were on different
 CPUs, but the LKMM says it holds even when they are on the same CPU.
-For example:
+For example::
 
 	int x, y;
 	spinlock_t s;
@@ -1833,7 +1842,7 @@ MP pattern).
 
 This requirement does not apply to ordinary release and acquire
 fences, only to lock-related operations.  For instance, suppose P0()
-in the example had been written as:
+in the example had been written as::
 
 	P0()
 	{
@@ -1847,7 +1856,7 @@ in the example had been written as:
 
 Then the CPU would be allowed to forward the s = 1 value from the
 smp_store_release() to the smp_load_acquire(), executing the
-instructions in the following order:
+instructions in the following order::
 
 		r3 = smp_load_acquire(&s);	// Obtains r3 = 1
 		r2 = READ_ONCE(y);
@@ -1859,7 +1868,7 @@ and thus it could load y before x, obtaining r2 = 0 and r1 = 1.
 Second, when a lock-acquire reads from a lock-release, and some other
 stores W and W' occur po-before the lock-release and po-after the
 lock-acquire respectively, the LKMM requires that W must propagate to
-each CPU before W' does.  For example, consider:
+each CPU before W' does.  For example, consider::
 
 	int x, y;
 	spinlock_t x;
@@ -1928,7 +1937,7 @@ smp_store_release().)  The final effect is the same.
 Although we didn't mention it above, the instruction execution
 ordering provided by the smp_rmb() fence doesn't apply to read events
 that are part of a non-value-returning atomic update.  For instance,
-given:
+given::
 
 	atomic_inc(&x);
 	smp_rmb();
@@ -1967,14 +1976,14 @@ they behave as follows:
 	events.
 
 Interestingly, RCU and locking each introduce the possibility of
-deadlock.  When faced with code sequences such as:
+deadlock.  When faced with code sequences such as::
 
 	spin_lock(&s);
 	spin_lock(&s);
 	spin_unlock(&s);
 	spin_unlock(&s);
 
-or:
+or::
 
 	rcu_read_lock();
 	synchronize_rcu();
@@ -1984,7 +1993,7 @@ what does the LKMM have to say?  Answer: It says there are no allowed
 executions at all, which makes sense.  But this can also lead to
 misleading results, because if a piece of code has multiple possible
 executions, some of which deadlock, the model will report only on the
-non-deadlocking executions.  For example:
+non-deadlocking executions.  For example::
 
 	int x, y;
 
diff --git a/tools/memory-model/Documentation/index.rst b/tools/memory-model/Documentation/index.rst
new file mode 100644
index 000000000000..0e53d83a5a48
--- /dev/null
+++ b/tools/memory-model/Documentation/index.rst
@@ -0,0 +1,20 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+Linux Memory Model Tools
+========================
+
+.. toctree::
+   :maxdepth: 1
+
+   explanation
+   recipes
+   references
+   cheatsheet
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
diff --git a/tools/memory-model/Documentation/recipes.txt b/tools/memory-model/Documentation/recipes.rst
similarity index 96%
rename from tools/memory-model/Documentation/recipes.txt
rename to tools/memory-model/Documentation/recipes.rst
index 7fe8d7aa3029..0229a431b1a2 100644
--- a/tools/memory-model/Documentation/recipes.txt
+++ b/tools/memory-model/Documentation/recipes.rst
@@ -1,3 +1,8 @@
+=======
+Recipes
+=======
+
+
 This document provides "recipes", that is, litmus tests for commonly
 occurring situations, as well as a few that illustrate subtly broken but
 attractive nuisances.  Many of these recipes include example code from
@@ -67,7 +72,7 @@ has acquired a given lock sees any changes previously seen or made by any
 CPU before it released that same lock.  Note that this statement is a bit
 stronger than "Any CPU holding a given lock sees all changes made by any
 CPU during the time that CPU was holding this same lock".  For example,
-consider the following pair of code fragments:
+consider the following pair of code fragments::
 
 	/* See MP+polocks.litmus. */
 	void CPU0(void)
@@ -93,7 +98,7 @@ value of r1 must also be equal to 1.  In contrast, the weaker rule would
 say nothing about the final value of r1.
 
 The converse to the basic rule also holds, as illustrated by the
-following litmus test:
+following litmus test::
 
 	/* See MP+porevlocks.litmus. */
 	void CPU0(void)
@@ -124,7 +129,7 @@ across multiple CPUs.
 
 However, it is not necessarily the case that accesses ordered by
 locking will be seen as ordered by CPUs not holding that lock.
-Consider this example:
+Consider this example::
 
 	/* See Z6.0+pooncerelease+poacquirerelease+fencembonceonce.litmus. */
 	void CPU0(void)
@@ -157,7 +162,7 @@ CPU2() never acquired the lock, and thus did not benefit from the
 lock's ordering properties.
 
 Ordering can be extended to CPUs not holding the lock by careful use
-of smp_mb__after_spinlock():
+of smp_mb__after_spinlock()::
 
 	/* See Z6.0+pooncelock+poonceLock+pombonce.litmus. */
 	void CPU0(void)
@@ -214,7 +219,7 @@ Release and acquire
 ~~~~~~~~~~~~~~~~~~~
 
 Use of smp_store_release() and smp_load_acquire() is one way to force
-the desired MP ordering.  The general approach is shown below:
+the desired MP ordering.  The general approach is shown below::
 
 	/* See MP+pooncerelease+poacquireonce.litmus. */
 	void CPU0(void)
@@ -245,7 +250,7 @@ Assign and dereference
 Use of rcu_assign_pointer() and rcu_dereference() is quite similar to the
 use of smp_store_release() and smp_load_acquire(), except that both
 rcu_assign_pointer() and rcu_dereference() operate on RCU-protected
-pointers.  The general approach is shown below:
+pointers.  The general approach is shown below::
 
 	/* See MP+onceassign+derefonce.litmus. */
 	int z;
@@ -290,7 +295,7 @@ Write and read memory barriers
 It is usually better to use smp_store_release() instead of smp_wmb()
 and to use smp_load_acquire() instead of smp_rmb().  However, the older
 smp_wmb() and smp_rmb() APIs are still heavily used, so it is important
-to understand their use cases.  The general approach is shown below:
+to understand their use cases.  The general approach is shown below::
 
 	/* See MP+fencewmbonceonce+fencermbonceonce.litmus. */
 	void CPU0(void)
@@ -312,7 +317,7 @@ smp_rmb() macro orders prior loads against later loads.  Therefore, if
 the final value of r0 is 1, the final value of r1 must also be 1.
 
 The xlog_state_switch_iclogs() function in fs/xfs/xfs_log.c contains
-the following write-side code fragment:
+the following write-side code fragment::
 
 	log->l_curr_block -= log->l_logBBsize;
 	ASSERT(log->l_curr_block >= 0);
@@ -327,7 +332,7 @@ the corresponding read-side code fragment:
 	cur_block = READ_ONCE(log->l_curr_block);
 
 Alternatively, consider the following comment in function
-perf_output_put_handle() in kernel/events/ring_buffer.c:
+perf_output_put_handle() in kernel/events/ring_buffer.c::
 
 	 *   kernel				user
 	 *
@@ -358,7 +363,7 @@ absence of any ordering it is quite possible that this may happen, as
 can be seen in the LB+poonceonces.litmus litmus test.
 
 One way of avoiding the counter-intuitive outcome is through the use of a
-control dependency paired with a full memory barrier:
+control dependency paired with a full memory barrier::
 
 	/* See LB+fencembonceonce+ctrlonceonce.litmus. */
 	void CPU0(void)
@@ -382,7 +387,7 @@ The A/D pairing from the ring-buffer use case shown earlier also
 illustrates LB.  Here is a repeat of the comment in
 perf_output_put_handle() in kernel/events/ring_buffer.c, showing a
 control dependency on the kernel side and a full memory barrier on
-the user side:
+the user side::
 
 	 *   kernel				user
 	 *
@@ -407,7 +412,7 @@ Release-acquire chains
 
 Release-acquire chains are a low-overhead, flexible, and easy-to-use
 method of maintaining order.  However, they do have some limitations that
-need to be fully understood.  Here is an example that maintains order:
+need to be fully understood.  Here is an example that maintains order::
 
 	/* See ISA2+pooncerelease+poacquirerelease+poacquireonce.litmus. */
 	void CPU0(void)
@@ -436,7 +441,7 @@ example, ordering would still be preserved if CPU1()'s smp_load_acquire()
 invocation was replaced with READ_ONCE().
 
 It is tempting to assume that CPU0()'s store to x is globally ordered
-before CPU1()'s store to z, but this is not the case:
+before CPU1()'s store to z, but this is not the case::
 
 	/* See Z6.0+pooncerelease+poacquirerelease+mbonceonce.litmus. */
 	void CPU0(void)
@@ -474,7 +479,7 @@ Store buffering
 Store buffering can be thought of as upside-down load buffering, so
 that one CPU first stores to one variable and then loads from a second,
 while another CPU stores to the second variable and then loads from the
-first.  Preserving order requires nothing less than full barriers:
+first.  Preserving order requires nothing less than full barriers::
 
 	/* See SB+fencembonceonces.litmus. */
 	void CPU0(void)
@@ -498,7 +503,7 @@ this counter-intuitive outcome.
 This pattern most famously appears as part of Dekker's locking
 algorithm, but it has a much more practical use within the Linux kernel
 of ordering wakeups.  The following comment taken from waitqueue_active()
-in include/linux/wait.h shows the canonical pattern:
+in include/linux/wait.h shows the canonical pattern::
 
  *      CPU0 - waker                    CPU1 - waiter
  *
@@ -550,16 +555,16 @@ The strength of memory ordering required for a given litmus test to
 avoid a counter-intuitive outcome depends on the types of relations
 linking the memory accesses for the outcome in question:
 
-o	If all links are write-to-read links, then the weakest
+-	If all links are write-to-read links, then the weakest
 	possible ordering within each CPU suffices.  For example, in
 	the LB litmus test, a control dependency was enough to do the
 	job.
 
-o	If all but one of the links are write-to-read links, then a
+-	If all but one of the links are write-to-read links, then a
 	release-acquire chain suffices.  Both the MP and the ISA2
 	litmus tests illustrate this case.
 
-o	If more than one of the links are something other than
+-	If more than one of the links are something other than
 	write-to-read links, then a full memory barrier is required
 	between each successive pair of non-write-to-read links.  This
 	case is illustrated by the Z6.0 litmus tests, both in the
diff --git a/tools/memory-model/Documentation/references.txt b/tools/memory-model/Documentation/references.rst
similarity index 71%
rename from tools/memory-model/Documentation/references.txt
rename to tools/memory-model/Documentation/references.rst
index b177f3e4a614..275876cd10b8 100644
--- a/tools/memory-model/Documentation/references.txt
+++ b/tools/memory-model/Documentation/references.rst
@@ -1,3 +1,7 @@
+==========
+References
+==========
+
 This document provides background reading for memory models and related
 tools.  These documents are aimed at kernel hackers who are interested
 in memory models.
@@ -6,64 +10,64 @@ in memory models.
 Hardware manuals and models
 ===========================
 
-o	SPARC International Inc. (Ed.). 1994. "The SPARC Architecture
+-	SPARC International Inc. (Ed.). 1994. "The SPARC Architecture
 	Reference Manual Version 9". SPARC International Inc.
 
-o	Compaq Computer Corporation (Ed.). 2002. "Alpha Architecture
+-	Compaq Computer Corporation (Ed.). 2002. "Alpha Architecture
 	Reference Manual".  Compaq Computer Corporation.
 
-o	Intel Corporation (Ed.). 2002. "A Formal Specification of Intel
+-	Intel Corporation (Ed.). 2002. "A Formal Specification of Intel
 	Itanium Processor Family Memory Ordering". Intel Corporation.
 
-o	Intel Corporation (Ed.). 2002. "Intel 64 and IA-32 Architectures
+-	Intel Corporation (Ed.). 2002. "Intel 64 and IA-32 Architectures
 	Software Developer’s Manual". Intel Corporation.
 
-o	Peter Sewell, Susmit Sarkar, Scott Owens, Francesco Zappa Nardelli,
+-	Peter Sewell, Susmit Sarkar, Scott Owens, Francesco Zappa Nardelli,
 	and Magnus O. Myreen. 2010. "x86-TSO: A Rigorous and Usable
 	Programmer's Model for x86 Multiprocessors". Commun. ACM 53, 7
 	(July, 2010), 89-97. http://doi.acm.org/10.1145/1785414.1785443
 
-o	IBM Corporation (Ed.). 2009. "Power ISA Version 2.06". IBM
+-	IBM Corporation (Ed.). 2009. "Power ISA Version 2.06". IBM
 	Corporation.
 
-o	ARM Ltd. (Ed.). 2009. "ARM Barrier Litmus Tests and Cookbook".
+-	ARM Ltd. (Ed.). 2009. "ARM Barrier Litmus Tests and Cookbook".
 	ARM Ltd.
 
-o	Susmit Sarkar, Peter Sewell, Jade Alglave, Luc Maranget, and
+-	Susmit Sarkar, Peter Sewell, Jade Alglave, Luc Maranget, and
 	Derek Williams.  2011. "Understanding POWER Multiprocessors". In
 	Proceedings of the 32Nd ACM SIGPLAN Conference on Programming
 	Language Design and Implementation (PLDI ’11). ACM, New York,
 	NY, USA, 175–186.
 
-o	Susmit Sarkar, Kayvan Memarian, Scott Owens, Mark Batty,
+-	Susmit Sarkar, Kayvan Memarian, Scott Owens, Mark Batty,
 	Peter Sewell, Luc Maranget, Jade Alglave, and Derek Williams.
 	2012. "Synchronising C/C++ and POWER". In Proceedings of the 33rd
 	ACM SIGPLAN Conference on Programming Language Design and
 	Implementation (PLDI '12). ACM, New York, NY, USA, 311-322.
 
-o	ARM Ltd. (Ed.). 2014. "ARM Architecture Reference Manual (ARMv8,
+-	ARM Ltd. (Ed.). 2014. "ARM Architecture Reference Manual (ARMv8,
 	for ARMv8-A architecture profile)". ARM Ltd.
 
-o	Imagination Technologies, LTD. 2015. "MIPS(R) Architecture
+-	Imagination Technologies, LTD. 2015. "MIPS(R) Architecture
 	For Programmers, Volume II-A: The MIPS64(R) Instruction,
 	Set Reference Manual". Imagination Technologies,
 	LTD. https://imgtec.com/?do-download=4302.
 
-o	Shaked Flur, Kathryn E. Gray, Christopher Pulte, Susmit
+-	Shaked Flur, Kathryn E. Gray, Christopher Pulte, Susmit
 	Sarkar, Ali Sezgin, Luc Maranget, Will Deacon, and Peter
 	Sewell. 2016. "Modelling the ARMv8 Architecture, Operationally:
 	Concurrency and ISA". In Proceedings of the 43rd Annual ACM
 	SIGPLAN-SIGACT Symposium on Principles of Programming Languages
 	(POPL ’16). ACM, New York, NY, USA, 608–621.
 
-o	Shaked Flur, Susmit Sarkar, Christopher Pulte, Kyndylan Nienhuis,
+-	Shaked Flur, Susmit Sarkar, Christopher Pulte, Kyndylan Nienhuis,
 	Luc Maranget, Kathryn E. Gray, Ali Sezgin, Mark Batty, and Peter
 	Sewell. 2017. "Mixed-size Concurrency: ARM, POWER, C/C++11,
 	and SC". In Proceedings of the 44th ACM SIGPLAN Symposium on
 	Principles of Programming Languages (POPL 2017). ACM, New York,
 	NY, USA, 429–442.
 
-o	Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
+-	Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
 	Susmit Sarkar, and Peter Sewell. 2018. "Simplifying ARM concurrency:
 	multicopy-atomic axiomatic and operational models for ARMv8". In
 	Proceedings of the ACM on Programming Languages, Volume 2, Issue
@@ -73,18 +77,18 @@ o	Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
 Linux-kernel memory model
 =========================
 
-o	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
+-	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
 	Alan Stern.  2018. "Frightening small children and disconcerting
 	grown-ups: Concurrency in the Linux kernel". In Proceedings of
 	the 23rd International Conference on Architectural Support for
 	Programming Languages and Operating Systems (ASPLOS 2018). ACM,
 	New York, NY, USA, 405-418.  Webpage: http://diy.inria.fr/linux/.
 
-o	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
+-	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
 	Alan Stern.  2017.  "A formal kernel memory-ordering model (part 1)"
 	Linux Weekly News.  https://lwn.net/Articles/718628/
 
-o	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
+-	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
 	Alan Stern.  2017.  "A formal kernel memory-ordering model (part 2)"
 	Linux Weekly News.  https://lwn.net/Articles/720550/
 
@@ -92,16 +96,16 @@ o	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
 Memory-model tooling
 ====================
 
-o	Daniel Jackson. 2002. "Alloy: A Lightweight Object Modelling
+-	Daniel Jackson. 2002. "Alloy: A Lightweight Object Modelling
 	Notation". ACM Trans. Softw. Eng. Methodol. 11, 2 (April 2002),
 	256–290. http://doi.acm.org/10.1145/505145.505149
 
-o	Jade Alglave, Luc Maranget, and Michael Tautschnig. 2014. "Herding
+-	Jade Alglave, Luc Maranget, and Michael Tautschnig. 2014. "Herding
 	Cats: Modelling, Simulation, Testing, and Data Mining for Weak
 	Memory". ACM Trans. Program. Lang. Syst. 36, 2, Article 7 (July
 	2014), 7:1–7:74 pages.
 
-o	Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
+-	Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
 	semantics of the weak consistency model specification language
 	cat". CoRR abs/1608.07531 (2016). http://arxiv.org/abs/1608.07531
 
@@ -109,6 +113,6 @@ o	Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
 Memory-model comparisons
 ========================
 
-o	Paul E. McKenney, Ulrich Weigand, Andrea Parri, and Boqun
+-	Paul E. McKenney, Ulrich Weigand, Andrea Parri, and Boqun
 	Feng. 2016. "Linux-Kernel Memory Model". (6 June 2016).
 	http://open-std.org/JTC1/SC22/WG21/docs/papers/2016/p0124r2.html.
diff --git a/tools/memory-model/README b/tools/memory-model/README
index 2b87f3971548..04bb1fa9ed76 100644
--- a/tools/memory-model/README
+++ b/tools/memory-model/README
@@ -105,16 +105,16 @@ for more information.
 DESCRIPTION OF FILES
 ====================
 
-Documentation/cheatsheet.txt
+Documentation/cheatsheet.rst
 	Quick-reference guide to the Linux-kernel memory model.
 
-Documentation/explanation.txt
+Documentation/explanation.rst
 	Describes the memory model in detail.
 
-Documentation/recipes.txt
+Documentation/recipes.rst
 	Lists common memory-ordering patterns.
 
-Documentation/references.txt
+Documentation/references.rst
 	Provides background reading.
 
 linux-kernel.bell
@@ -173,7 +173,7 @@ The Linux-kernel memory model has the following limitations:
 	of READ_ONCE() and WRITE_ONCE() limits the compiler's ability
 	to optimize, but there is Linux-kernel code that uses bare C
 	memory accesses.  Handling this code is on the to-do list.
-	For more information, see Documentation/explanation.txt (in
+	For more information, see Documentation/explanation.rst (in
 	particular, the "THE PROGRAM ORDER RELATION: po AND po-loc"
 	and "A WARNING" sections).
 



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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
  2019-07-30 23:00           ` Mauro Carvalho Chehab
@ 2019-07-30 23:15             ` Joel Fernandes
  0 siblings, 0 replies; 75+ messages in thread
From: Joel Fernandes @ 2019-07-30 23:15 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Paul E. McKenney, Josh Triplett, Steven Rostedt,
	Mathieu Desnoyers, Lai Jiangshan, Jonathan Corbet, rcu,
	linux-doc

On Tue, Jul 30, 2019 at 08:00:57PM -0300, Mauro Carvalho Chehab wrote:
> Em Tue, 30 Jul 2019 18:21:30 -0400
> Joel Fernandes <joel@joelfernandes.org> escreveu:
> 
> > On Tue, Jul 30, 2019 at 07:00:28PM -0300, Mauro Carvalho Chehab wrote:
> > > Em Tue, 30 Jul 2019 17:50:07 -0400
> > > Joel Fernandes <joel@joelfernandes.org> escreveu:
> > >   
> > > > On Tue, Jul 30, 2019 at 02:22:50PM -0700, Paul E. McKenney wrote:  
> > > > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:    
> > > > > > There are 4 RCU articles that are written on html format.
> > > > > > 
> > > > > > The way they are, they can't be part of the Linux Kernel
> > > > > > documentation body nor share the styles and pdf output.
> > > > > > 
> > > > > > So, convert them to ReST format.
> > > > > > 
> > > > > > This way, make htmldocs and make pdfdocs will produce a
> > > > > > documentation output that will be like the original ones, but
> > > > > > will be part of the Linux Kernel documentation body.
> > > > > > 
> > > > > > Part of the conversion was done with the help of pandoc, but
> > > > > > the result had some broken things that had to be manually
> > > > > > fixed.
> > > > > > 
> > > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>    
> > > > > 
> > > > > I am having some trouble applying these, at least in part due to UTF-8
> > > > > sequences, for example double left quotation mark.  These end up being
> > > > > "=E2=80=9C", with a few space characters turned into "=20".
> > > > > 
> > > > > Any advice on how to apply these?  Should I just pull commits from
> > > > > somewhere?    
> > > > 
> > > > I was able to successfully apply and build this particular patch. I think
> > > > this is the only one in the series that applies to RCU.
> > > > 
> > > > Sadly, I can't find the patch in any of the public archives, but I could
> > > > perhaps email it to you as an .mbox attach which 'git am' should be able to
> > > > apply.
> > > > 
> > > > Mauro did say he was going to add some more details to changelog, or it could
> > > > be added when it is applied:
> > > > https://lore.kernel.org/rcu/20190726154550.5eeae294@coco.lan/  
> > > 
> > > Yeah, I'm also planning to address at least some of the issues you
> > > pointed, in order to improve the html output, but got sidetracked by something 
> > > else and didn't find any time yet to finish. I'm adding some CI automation for
> > > the media subsystem in order to help us dealing with the huge amount of patches
> > > we receive there.
> > > 
> > > Feel free to add those details to the changelog. I may find some spare time 
> > > this week or the next one for the improvements you suggested, but those 
> > > could be sent on followup patches, once done.  
> > 
> > Ok, I will re-send this RCU patch with the changes, leave this one to me.
> > 
> > The other memory model one, needs a lot more work so we can keep that aside
> > for now till someone has the time.
> 
> Yeah, feel free to do what fits best with regards to this one.
> 
> If you prefer to merge it instead, I'm enclosing the last version of it,
> with that quick hack I just wrote, plus the change of the toctree for
> it to produce the 2-level index.

Ok thanks a lot Mauro! It looks much better to me now. I can probably send
this one out too to Paul after the RCU ones are in, after some more careful
review..

However, I am curious what Paul and Alan think about it since some folks such
as PeterZ actively deal with memory model stuff and probably refer a lot to
this document, but don't like ReST (unlike us) and prefer plain text editors
without any markup. Hopefully this is not the case any more..

thanks,

 - Joel


> Thanks,
> Mauro
> 
> [PATCH] tools: memory-model: add it to the Documentation body
> 
> The books at tools/memory-model/Documentation are very well
> formatted. Congrats to the ones that wrote them!
> 
> The manual conversion to ReST is really trivial:
> 
> 	- Add document titles;
> 	- change the bullets on some lists;
> 	- mark code blocks.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
> 
> diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst
> index 976e85adffe8..7e6500a6fa76 100644
> --- a/Documentation/core-api/refcount-vs-atomic.rst
> +++ b/Documentation/core-api/refcount-vs-atomic.rst
> @@ -17,7 +17,7 @@ in order to help maintainers validate their code against the change in
>  these memory ordering guarantees.
>  
>  The terms used through this document try to follow the formal LKMM defined in
> -tools/memory-model/Documentation/explanation.txt.
> +tools/memory-model/Documentation/explanation.rst.
>  
>  memory-barriers.txt and atomic_t.txt provide more background to the
>  memory ordering in general and for atomic operations specifically.
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index 2df5a3da563c..5123770ba77e 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -36,6 +36,7 @@ trying to get it to work optimally on a given system.
>  
>     admin-guide/index
>     kbuild/index
> +   tools/index
>  
>  Firmware-related documentation
>  ------------------------------
> diff --git a/Documentation/tools/index.rst b/Documentation/tools/index.rst
> new file mode 100644
> index 000000000000..f540d9cc75a1
> --- /dev/null
> +++ b/Documentation/tools/index.rst
> @@ -0,0 +1,17 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===========
> +Linux Tools
> +===========
> +
> +.. toctree::
> +   :maxdepth: 2
> +
> +   memory-model/index
> +
> +.. only::  subproject and html
> +
> +   Indices
> +   =======
> +
> +   * :ref:`genindex`
> diff --git a/Documentation/tools/memory-model b/Documentation/tools/memory-model
> new file mode 120000
> index 000000000000..020ed38ce302
> --- /dev/null
> +++ b/Documentation/tools/memory-model
> @@ -0,0 +1 @@
> +../../tools/memory-model/Documentation/
> \ No newline at end of file
> diff --git a/tools/memory-model/Documentation/cheatsheet.rst b/tools/memory-model/Documentation/cheatsheet.rst
> new file mode 100644
> index 000000000000..35f8749b8a53
> --- /dev/null
> +++ b/tools/memory-model/Documentation/cheatsheet.rst
> @@ -0,0 +1,36 @@
> +===========
> +Cheat Sheet
> +===========
> +
> +::
> +
> +				    Prior Operation     Subsequent Operation
> +				    ---------------  ---------------------------
> +				 C  Self  R  W  RMW  Self  R  W  DR  DW  RMW  SV
> +				--  ----  -  -  ---  ----  -  -  --  --  ---  --
> +
> +  Store, e.g., WRITE_ONCE()            Y                                       Y
> +  Load, e.g., READ_ONCE()              Y                          Y   Y        Y
> +  Unsuccessful RMW operation           Y                          Y   Y        Y
> +  rcu_dereference()                    Y                          Y   Y        Y
> +  Successful *_acquire()               R                   Y  Y   Y   Y    Y   Y
> +  Successful *_release()         C        Y  Y    Y     W                      Y
> +  smp_rmb()                               Y       R        Y      Y        R
> +  smp_wmb()                                  Y    W           Y       Y    W
> +  smp_mb() & synchronize_rcu()  CP        Y  Y    Y        Y  Y   Y   Y    Y
> +  Successful full non-void RMW  CP     Y  Y  Y    Y     Y  Y  Y   Y   Y    Y   Y
> +  smp_mb__before_atomic()       CP        Y  Y    Y        a  a   a   a    Y
> +  smp_mb__after_atomic()        CP        a  a    Y        Y  Y   Y   Y    Y
> +
> +
> +  Key:    C:      Ordering is cumulative
> +	  P:      Ordering propagates
> +	  R:      Read, for example, READ_ONCE(), or read portion of RMW
> +	  W:      Write, for example, WRITE_ONCE(), or write portion of RMW
> +	  Y:      Provides ordering
> +	  a:      Provides ordering given intervening RMW atomic operation
> +	  DR:     Dependent read (address dependency)
> +	  DW:     Dependent write (address, data, or control dependency)
> +	  RMW:    Atomic read-modify-write operation
> +	  SELF:   Orders self, as opposed to accesses before and/or after
> +	  SV:     Orders later accesses to the same variable
> diff --git a/tools/memory-model/Documentation/cheatsheet.txt b/tools/memory-model/Documentation/cheatsheet.txt
> deleted file mode 100644
> index 33ba98d72b16..000000000000
> --- a/tools/memory-model/Documentation/cheatsheet.txt
> +++ /dev/null
> @@ -1,30 +0,0 @@
> -                                  Prior Operation     Subsequent Operation
> -                                  ---------------  ---------------------------
> -                               C  Self  R  W  RMW  Self  R  W  DR  DW  RMW  SV
> -                              --  ----  -  -  ---  ----  -  -  --  --  ---  --
> -
> -Store, e.g., WRITE_ONCE()            Y                                       Y
> -Load, e.g., READ_ONCE()              Y                          Y   Y        Y
> -Unsuccessful RMW operation           Y                          Y   Y        Y
> -rcu_dereference()                    Y                          Y   Y        Y
> -Successful *_acquire()               R                   Y  Y   Y   Y    Y   Y
> -Successful *_release()         C        Y  Y    Y     W                      Y
> -smp_rmb()                               Y       R        Y      Y        R
> -smp_wmb()                                  Y    W           Y       Y    W
> -smp_mb() & synchronize_rcu()  CP        Y  Y    Y        Y  Y   Y   Y    Y
> -Successful full non-void RMW  CP     Y  Y  Y    Y     Y  Y  Y   Y   Y    Y   Y
> -smp_mb__before_atomic()       CP        Y  Y    Y        a  a   a   a    Y
> -smp_mb__after_atomic()        CP        a  a    Y        Y  Y   Y   Y    Y
> -
> -
> -Key:	C:	Ordering is cumulative
> -	P:	Ordering propagates
> -	R:	Read, for example, READ_ONCE(), or read portion of RMW
> -	W:	Write, for example, WRITE_ONCE(), or write portion of RMW
> -	Y:	Provides ordering
> -	a:	Provides ordering given intervening RMW atomic operation
> -	DR:	Dependent read (address dependency)
> -	DW:	Dependent write (address, data, or control dependency)
> -	RMW:	Atomic read-modify-write operation
> -	SELF:	Orders self, as opposed to accesses before and/or after
> -	SV:	Orders later accesses to the same variable
> diff --git a/tools/memory-model/Documentation/explanation.txt b/tools/memory-model/Documentation/explanation.rst
> similarity index 92%
> rename from tools/memory-model/Documentation/explanation.txt
> rename to tools/memory-model/Documentation/explanation.rst
> index 68caa9a976d0..9b5d10cef0c2 100644
> --- a/tools/memory-model/Documentation/explanation.txt
> +++ b/tools/memory-model/Documentation/explanation.rst
> @@ -1,5 +1,6 @@
> +========================================================
>  Explanation of the Linux-Kernel Memory Consistency Model
> -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +========================================================
>  
>  :Author: Alan Stern <stern@rowland.harvard.edu>
>  :Created: October 2017
> @@ -107,7 +108,7 @@ and the flag are memory locations shared between the two CPUs.
>  
>  We can abstract out the important pieces of the driver code as follows
>  (the reason for using WRITE_ONCE() and READ_ONCE() instead of simple
> -assignment statements is discussed later):
> +assignment statements is discussed later)::
>  
>  	int buf = 0, flag = 0;
>  
> @@ -219,7 +220,7 @@ Ordering).  This model predicts that the undesired outcome for the MP
>  pattern cannot occur, but in other respects it differs from Sequential
>  Consistency.  One example is the Store Buffer (SB) pattern, in which
>  each CPU stores to its own shared location and then loads from the
> -other CPU's location:
> +other CPU's location::
>  
>  	int x = 0, y = 0;
>  
> @@ -264,7 +265,7 @@ The counterpart to ordering is a cycle.  Ordering rules out cycles:
>  It's not possible to have X ordered before Y, Y ordered before Z, and
>  Z ordered before X, because this would mean that X is ordered before
>  itself.  The analysis of the MP example under Sequential Consistency
> -involved just such an impossible cycle:
> +involved just such an impossible cycle::
>  
>  	W: P0 stores 1 to flag   executes before
>  	X: P1 loads 1 from flag  executes before
> @@ -331,7 +332,7 @@ can think of it as the order in which statements occur in the source
>  code after branches are taken into account and loops have been
>  unrolled.  A better description might be the order in which
>  instructions are presented to a CPU's execution unit.  Thus, we say
> -that X is po-before Y (written as "X ->po Y" in formulas) if X occurs
> +that X is po-before Y (written as ``X ->po Y`` in formulas) if X occurs
>  before Y in the instruction stream.
>  
>  This is inherently a single-CPU relation; two instructions executing
> @@ -388,7 +389,7 @@ The protections provided by READ_ONCE(), WRITE_ONCE(), and others are
>  not perfect; and under some circumstances it is possible for the
>  compiler to undermine the memory model.  Here is an example.  Suppose
>  both branches of an "if" statement store the same value to the same
> -location:
> +location::
>  
>  	r1 = READ_ONCE(x);
>  	if (r1) {
> @@ -402,7 +403,7 @@ location:
>  For this code, the LKMM predicts that the load from x will always be
>  executed before either of the stores to y.  However, a compiler could
>  lift the stores out of the conditional, transforming the code into
> -something resembling:
> +something resembling::
>  
>  	r1 = READ_ONCE(x);
>  	WRITE_ONCE(y, 2);
> @@ -418,7 +419,7 @@ model's original prediction could be invalidated by the compiler.
>  
>  Another issue arises from the fact that in C, arguments to many
>  operators and function calls can be evaluated in any order.  For
> -example:
> +example::
>  
>  	r1 = f(5) + g(6);
>  
> @@ -440,7 +441,7 @@ control (ctrl).
>  
>  A read and a write event are linked by a data dependency if the value
>  obtained by the read affects the value stored by the write.  As a very
> -simple example:
> +simple example::
>  
>  	int x, y;
>  
> @@ -455,7 +456,7 @@ values of multiple reads.
>  A read event and another memory access event are linked by an address
>  dependency if the value obtained by the read affects the location
>  accessed by the other event.  The second event can be either a read or
> -a write.  Here's another simple example:
> +a write.  Here's another simple example::
>  
>  	int a[20];
>  	int i;
> @@ -471,7 +472,7 @@ pointer.
>  
>  Finally, a read event and another memory access event are linked by a
>  control dependency if the value obtained by the read affects whether
> -the second event is executed at all.  Simple example:
> +the second event is executed at all.  Simple example::
>  
>  	int x, y;
>  
> @@ -484,9 +485,9 @@ which depends on the value obtained by the READ_ONCE(); hence there is
>  a control dependency from the load to the store.
>  
>  It should be pretty obvious that events can only depend on reads that
> -come earlier in program order.  Symbolically, if we have R ->data X,
> -R ->addr X, or R ->ctrl X (where R is a read event), then we must also
> -have R ->po X.  It wouldn't make sense for a computation to depend
> +come earlier in program order.  Symbolically, if we have ``R ->data X``,
> +``R ->addr X``, or ``R ->ctrl X`` (where R is a read event), then we must also
> +have ``R ->po X``.  It wouldn't make sense for a computation to depend
>  somehow on a value that doesn't get loaded from shared memory until
>  later in the code!
>  
> @@ -497,7 +498,7 @@ THE READS-FROM RELATION: rf, rfi, and rfe
>  The reads-from relation (rf) links a write event to a read event when
>  the value loaded by the read is the value that was stored by the
>  write.  In colloquial terms, the load "reads from" the store.  We
> -write W ->rf R to indicate that the load R reads from the store W.  We
> +write ``W ->rf R`` to indicate that the load R reads from the store W.  We
>  further distinguish the cases where the load and the store occur on
>  the same CPU (internal reads-from, or rfi) and where they occur on
>  different CPUs (external reads-from, or rfe).
> @@ -510,7 +511,7 @@ Usage of the rf relation implicitly assumes that loads will always
>  read from a single store.  It doesn't apply properly in the presence
>  of load-tearing, where a load obtains some of its bits from one store
>  and some of them from another store.  Fortunately, use of READ_ONCE()
> -and WRITE_ONCE() will prevent load-tearing; it's not possible to have:
> +and WRITE_ONCE() will prevent load-tearing; it's not possible to have::
>  
>  	int x = 0;
>  
> @@ -530,7 +531,7 @@ and end up with r1 = 0x1200 (partly from x's initial value and partly
>  from the value stored by P0).
>  
>  On the other hand, load-tearing is unavoidable when mixed-size
> -accesses are used.  Consider this example:
> +accesses are used.  Consider this example::
>  
>  	union {
>  		u32	w;
> @@ -578,26 +579,26 @@ that value comes third, and so on.
>  You can think of the coherence order as being the order in which the
>  stores reach x's location in memory (or if you prefer a more
>  hardware-centric view, the order in which the stores get written to
> -x's cache line).  We write W ->co W' if W comes before W' in the
> +x's cache line).  We write ``W ->co W'`` if W comes before W' in the
>  coherence order, that is, if the value stored by W gets overwritten,
>  directly or indirectly, by the value stored by W'.
>  
>  Coherence order is required to be consistent with program order.  This
>  requirement takes the form of four coherency rules:
>  
> -	Write-write coherence: If W ->po-loc W' (i.e., W comes before
> +	Write-write coherence: If ``W ->po-loc W'`` (i.e., W comes before
>  	W' in program order and they access the same location), where W
> -	and W' are two stores, then W ->co W'.
> +	and W' are two stores, then ``W ->co W'``.
>  
> -	Write-read coherence: If W ->po-loc R, where W is a store and R
> +	Write-read coherence: If ``W ->po-loc R``, where W is a store and R
>  	is a load, then R must read from W or from some other store
>  	which comes after W in the coherence order.
>  
> -	Read-write coherence: If R ->po-loc W, where R is a load and W
> +	Read-write coherence: If ``R ->po-loc W``, where R is a load and W
>  	is a store, then the store which R reads from must come before
>  	W in the coherence order.
>  
> -	Read-read coherence: If R ->po-loc R', where R and R' are two
> +	Read-read coherence: If ``R ->po-loc R'``, where R and R' are two
>  	loads, then either they read from the same store or else the
>  	store read by R comes before the store read by R' in the
>  	coherence order.
> @@ -612,7 +613,7 @@ requirement that every store eventually becomes visible to every CPU.)
>  Any reasonable memory model will include cache coherence.  Indeed, our
>  expectation of cache coherence is so deeply ingrained that violations
>  of its requirements look more like hardware bugs than programming
> -errors:
> +errors::
>  
>  	int x;
>  
> @@ -628,6 +629,8 @@ write-write coherence rule: Since the store of 23 comes later in
>  program order, it must also come later in x's coherence order and
>  thus must overwrite the store of 17.
>  
> +::
> +
>  	int x = 0;
>  
>  	P0()
> @@ -644,6 +647,8 @@ program order, so it must not read from that store but rather from one
>  coming earlier in the coherence order (in this case, x's initial
>  value).
>  
> +::
> +
>  	int x = 0;
>  
>  	P0()
> @@ -689,12 +694,12 @@ THE FROM-READS RELATION: fr, fri, and fre
>  
>  The from-reads relation (fr) can be a little difficult for people to
>  grok.  It describes the situation where a load reads a value that gets
> -overwritten by a store.  In other words, we have R ->fr W when the
> +overwritten by a store.  In other words, we have ``R ->fr W`` when the
>  value that R reads is overwritten (directly or indirectly) by W, or
>  equivalently, when R reads from a store which comes earlier than W in
>  the coherence order.
>  
> -For example:
> +For example::
>  
>  	int x = 0;
>  
> @@ -718,9 +723,11 @@ different CPUs).
>  
>  Note that the fr relation is determined entirely by the rf and co
>  relations; it is not independent.  Given a read event R and a write
> -event W for the same location, we will have R ->fr W if and only if
> +event W for the same location, we will have ``R ->fr W`` if and only if
>  the write which R reads from is co-before W.  In symbols,
>  
> +::
> +
>  	(R ->fr W) := (there exists W' with W' ->rf R and W' ->co W).
>  
>  
> @@ -843,13 +850,13 @@ defined to link memory access events E and F whenever:
>  	event occurs between them in program order; or
>  
>  	F is a release fence and some X comes before F in program order,
> -	where either X = E or else E ->rf X; or
> +	where either ``X = E`` or else ``E ->rf X``; or
>  
>  	A strong fence event occurs between some X and F in program
> -	order, where either X = E or else E ->rf X.
> +	order, where either ``X = E`` or else ``E ->rf X``.
>  
>  The operational model requires that whenever W and W' are both stores
> -and W ->cumul-fence W', then W must propagate to any given CPU
> +and ``W ->cumul-fence W'``, then W must propagate to any given CPU
>  before W' does.  However, for different CPUs C and C', it does not
>  require W to propagate to C before W' propagates to C'.
>  
> @@ -903,11 +910,11 @@ first for CPU 0, then CPU 1, etc.
>  
>  You can check that the four coherency rules imply that the rf, co, fr,
>  and po-loc relations agree with this global ordering; in other words,
> -whenever we have X ->rf Y or X ->co Y or X ->fr Y or X ->po-loc Y, the
> +whenever we have ``X ->rf Y`` or ``X ->co Y`` or ``X ->fr Y`` or ``X ->po-loc Y``, the
>  X event comes before the Y event in the global ordering.  The LKMM's
>  "coherence" axiom expresses this by requiring the union of these
>  relations not to have any cycles.  This means it must not be possible
> -to find events
> +to find events::
>  
>  	X0 -> X1 -> X2 -> ... -> Xn -> X0,
>  
> @@ -929,7 +936,7 @@ this case) does not get altered between the read and the write events
>  making up the atomic operation.  In particular, if two CPUs perform
>  atomic_inc(&x) concurrently, it must be guaranteed that the final
>  value of x will be the initial value plus two.  We should never have
> -the following sequence of events:
> +the following sequence of events::
>  
>  	CPU 0 loads x obtaining 13;
>  					CPU 1 loads x obtaining 13;
> @@ -951,6 +958,8 @@ atomic read-modify-write and W' is the write event which R reads from,
>  there must not be any stores coming between W' and W in the coherence
>  order.  Equivalently,
>  
> +::
> +
>  	(R ->rmw W) implies (there is no X with R ->fr X and X ->co W),
>  
>  where the rmw relation links the read and write events making up each
> @@ -968,7 +977,7 @@ po.
>  
>  The operational model already includes a description of one such
>  situation: Fences are a source of ppo links.  Suppose X and Y are
> -memory accesses with X ->po Y; then the CPU must execute X before Y if
> +memory accesses with ``X ->po Y``; then the CPU must execute X before Y if
>  any of the following hold:
>  
>  	A strong (smp_mb() or synchronize_rcu()) fence occurs between
> @@ -987,7 +996,7 @@ any of the following hold:
>  Another possibility, not mentioned earlier but discussed in the next
>  section, is:
>  
> -	X and Y are both loads, X ->addr Y (i.e., there is an address
> +	X and Y are both loads, ``X ->addr Y`` (i.e., there is an address
>  	dependency from X to Y), and X is a READ_ONCE() or an atomic
>  	access.
>  
> @@ -1021,7 +1030,7 @@ includes address dependencies to loads in the ppo relation.
>  
>  On the other hand, dependencies can indirectly affect the ordering of
>  two loads.  This happens when there is a dependency from a load to a
> -store and a second, po-later load reads from that store:
> +store and a second, po-later load reads from that store::
>  
>  	R ->dep W ->rfi R',
>  
> @@ -1036,7 +1045,7 @@ R; if the speculation turns out to be wrong then the CPU merely has to
>  restart or abandon R'.
>  
>  (In theory, a CPU might forward a store to a load when it runs across
> -an address dependency like this:
> +an address dependency like this::
>  
>  	r1 = READ_ONCE(ptr);
>  	WRITE_ONCE(*r1, 17);
> @@ -1048,7 +1057,7 @@ However, none of the architectures supported by the Linux kernel do
>  this.)
>  
>  Two memory accesses of the same location must always be executed in
> -program order if the second access is a store.  Thus, if we have
> +program order if the second access is a store.  Thus, if we have::
>  
>  	R ->po-loc W
>  
> @@ -1056,7 +1065,7 @@ program order if the second access is a store.  Thus, if we have
>  access the same location), the CPU is obliged to execute W after R.
>  If it executed W first then the memory subsystem would respond to R's
>  read request with the value stored by W (or an even later store), in
> -violation of the read-write coherence rule.  Similarly, if we had
> +violation of the read-write coherence rule.  Similarly, if we had::
>  
>  	W ->po-loc W'
>  
> @@ -1074,7 +1083,7 @@ AND THEN THERE WAS ALPHA
>  
>  As mentioned above, the Alpha architecture is unique in that it does
>  not appear to respect address dependencies to loads.  This means that
> -code such as the following:
> +code such as the following::
>  
>  	int x = 0;
>  	int y = -1;
> @@ -1128,7 +1137,7 @@ nothing at all on non-Alpha builds) after every READ_ONCE() and atomic
>  load.  The effect of the fence is to cause the CPU not to execute any
>  po-later instructions until after the local cache has finished
>  processing all the stores it has already received.  Thus, if the code
> -was changed to:
> +was changed to::
>  
>  	P1()
>  	{
> @@ -1167,25 +1176,25 @@ The happens-before relation (hb) links memory accesses that have to
>  execute in a certain order.  hb includes the ppo relation and two
>  others, one of which is rfe.
>  
> -W ->rfe R implies that W and R are on different CPUs.  It also means
> +``W ->rfe R`` implies that W and R are on different CPUs.  It also means
>  that W's store must have propagated to R's CPU before R executed;
>  otherwise R could not have read the value stored by W.  Therefore W
> -must have executed before R, and so we have W ->hb R.
> +must have executed before R, and so we have ``W ->hb R``.
>  
> -The equivalent fact need not hold if W ->rfi R (i.e., W and R are on
> +The equivalent fact need not hold if ``W ->rfi R`` (i.e., W and R are on
>  the same CPU).  As we have already seen, the operational model allows
>  W's value to be forwarded to R in such cases, meaning that R may well
>  execute before W does.
>  
>  It's important to understand that neither coe nor fre is included in
>  hb, despite their similarities to rfe.  For example, suppose we have
> -W ->coe W'.  This means that W and W' are stores to the same location,
> +``W ->coe W'``.  This means that W and W' are stores to the same location,
>  they execute on different CPUs, and W comes before W' in the coherence
>  order (i.e., W' overwrites W).  Nevertheless, it is possible for W' to
>  execute before W, because the decision as to which store overwrites
>  the other is made later by the memory subsystem.  When the stores are
>  nearly simultaneous, either one can come out on top.  Similarly,
> -R ->fre W means that W overwrites the value which R reads, but it
> +``R ->fre W`` means that W overwrites the value which R reads, but it
>  doesn't mean that W has to execute after R.  All that's necessary is
>  for the memory subsystem not to propagate W to R's CPU until after R
>  has executed, which is possible if W executes shortly before R.
> @@ -1199,7 +1208,7 @@ the first event in the coherence order and propagates to C before the
>  second event executes.
>  
>  This is best explained with some examples.  The simplest case looks
> -like this:
> +like this::
>  
>  	int x;
>  
> @@ -1225,7 +1234,7 @@ event, because P1's store came after P0's store in x's coherence
>  order, and P1's store propagated to P0 before P0's load executed.
>  
>  An equally simple case involves two loads of the same location that
> -read from different stores:
> +read from different stores::
>  
>  	int x = 0;
>  
> @@ -1252,7 +1261,7 @@ P1's store propagated to P0 before P0's second load executed.
>  
>  Less trivial examples of prop all involve fences.  Unlike the simple
>  examples above, they can require that some instructions are executed
> -out of program order.  This next one should look familiar:
> +out of program order.  This next one should look familiar::
>  
>  	int buf = 0, flag = 0;
>  
> @@ -1303,7 +1312,7 @@ rfe link.  You can concoct more exotic examples, containing more than
>  one fence, although this quickly leads to diminishing returns in terms
>  of complexity.  For instance, here's an example containing a coe link
>  followed by two fences and an rfe link, utilizing the fact that
> -release fences are A-cumulative:
> +release fences are A-cumulative::
>  
>  	int x, y, z;
>  
> @@ -1363,7 +1372,7 @@ links.  Let's see how this definition works out.
>  
>  Consider first the case where E is a store (implying that the sequence
>  of links begins with coe).  Then there are events W, X, Y, and Z such
> -that:
> +that::
>  
>  	E ->coe W ->cumul-fence* X ->rfe? Y ->strong-fence Z ->hb* F,
>  
> @@ -1384,13 +1393,13 @@ The existence of a pb link from E to F implies that E must execute
>  before F.  To see why, suppose that F executed first.  Then W would
>  have propagated to E's CPU before E executed.  If E was a store, the
>  memory subsystem would then be forced to make E come after W in the
> -coherence order, contradicting the fact that E ->coe W.  If E was a
> +coherence order, contradicting the fact that ``E ->coe W``.  If E was a
>  load, the memory subsystem would then be forced to satisfy E's read
>  request with the value stored by W or an even later store,
> -contradicting the fact that E ->fre W.
> +contradicting the fact that ``E ->fre W``.
>  
>  A good example illustrating how pb works is the SB pattern with strong
> -fences:
> +fences::
>  
>  	int x = 0, y = 0;
>  
> @@ -1449,18 +1458,18 @@ span a full grace period.  In more detail, the Guarantee says:
>  	For any critical section C and any grace period G, at least
>  	one of the following statements must hold:
>  
> -(1)	C ends before G does, and in addition, every store that
> -	propagates to C's CPU before the end of C must propagate to
> -	every CPU before G ends.
> +	(1)	C ends before G does, and in addition, every store that
> +		propagates to C's CPU before the end of C must propagate to
> +		every CPU before G ends.
>  
> -(2)	G starts before C does, and in addition, every store that
> -	propagates to G's CPU before the start of G must propagate
> -	to every CPU before C starts.
> +	(2)	G starts before C does, and in addition, every store that
> +		propagates to G's CPU before the start of G must propagate
> +		to every CPU before C starts.
>  
>  In particular, it is not possible for a critical section to both start
>  before and end after a grace period.
>  
> -Here is a simple example of RCU in action:
> +Here is a simple example of RCU in action::
>  
>  	int x, y;
>  
> @@ -1509,9 +1518,9 @@ entirely clear.  The LKMM formalizes this notion by means of the
>  rcu-link relation.  rcu-link encompasses a very general notion of
>  "before": If E and F are RCU fence events (i.e., rcu_read_lock(),
>  rcu_read_unlock(), or synchronize_rcu()) then among other things,
> -E ->rcu-link F includes cases where E is po-before some memory-access
> +``E ->rcu-link F`` includes cases where E is po-before some memory-access
>  event X, F is po-after some memory-access event Y, and we have any of
> -X ->rfe Y, X ->co Y, or X ->fr Y.
> +``X ->rfe Y``, ``X ->co Y``, or ``X ->fr Y``.
>  
>  The formal definition of the rcu-link relation is more than a little
>  obscure, and we won't give it here.  It is closely related to the pb
> @@ -1523,50 +1532,50 @@ The LKMM also defines the rcu-gp and rcu-rscsi relations.  They bring
>  grace periods and read-side critical sections into the picture, in the
>  following way:
>  
> -	E ->rcu-gp F means that E and F are in fact the same event,
> +	``E ->rcu-gp F`` means that E and F are in fact the same event,
>  	and that event is a synchronize_rcu() fence (i.e., a grace
>  	period).
>  
> -	E ->rcu-rscsi F means that E and F are the rcu_read_unlock()
> +	``E ->rcu-rscsi F`` means that E and F are the rcu_read_unlock()
>  	and rcu_read_lock() fence events delimiting some read-side
>  	critical section.  (The 'i' at the end of the name emphasizes
>  	that this relation is "inverted": It links the end of the
>  	critical section to the start.)
>  
>  If we think of the rcu-link relation as standing for an extended
> -"before", then X ->rcu-gp Y ->rcu-link Z roughly says that X is a
> +"before", then ``X ->rcu-gp Y ->rcu-link Z`` roughly says that X is a
>  grace period which ends before Z begins.  (In fact it covers more than
>  this, because it also includes cases where some store propagates to
>  Z's CPU before Z begins but doesn't propagate to some other CPU until
> -after X ends.)  Similarly, X ->rcu-rscsi Y ->rcu-link Z says that X is
> +after X ends.)  Similarly, ``X ->rcu-rscsi Y ->rcu-link Z`` says that X is
>  the end of a critical section which starts before Z begins.
>  
>  The LKMM goes on to define the rcu-fence relation as a sequence of
>  rcu-gp and rcu-rscsi links separated by rcu-link links, in which the
>  number of rcu-gp links is >= the number of rcu-rscsi links.  For
> -example:
> +example::
>  
>  	X ->rcu-gp Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
>  
> -would imply that X ->rcu-fence V, because this sequence contains two
> +would imply that ``X ->rcu-fence V``, because this sequence contains two
>  rcu-gp links and one rcu-rscsi link.  (It also implies that
> -X ->rcu-fence T and Z ->rcu-fence V.)  On the other hand:
> +``X ->rcu-fence T`` and ``Z ->rcu-fence V``.)  On the other hand::
>  
>  	X ->rcu-rscsi Y ->rcu-link Z ->rcu-rscsi T ->rcu-link U ->rcu-gp V
>  
> -does not imply X ->rcu-fence V, because the sequence contains only
> +does not imply ``X ->rcu-fence V``, because the sequence contains only
>  one rcu-gp link but two rcu-rscsi links.
>  
>  The rcu-fence relation is important because the Grace Period Guarantee
>  means that rcu-fence acts kind of like a strong fence.  In particular,
> -E ->rcu-fence F implies not only that E begins before F ends, but also
> +``E ->rcu-fence F`` implies not only that E begins before F ends, but also
>  that any write po-before E will propagate to every CPU before any
>  instruction po-after F can execute.  (However, it does not imply that
>  E must execute before F; in fact, each synchronize_rcu() fence event
>  is linked to itself by rcu-fence as a degenerate case.)
>  
>  To prove this in full generality requires some intellectual effort.
> -We'll consider just a very simple case:
> +We'll consider just a very simple case::
>  
>  	G ->rcu-gp W ->rcu-link Z ->rcu-rscsi F.
>  
> @@ -1595,13 +1604,13 @@ covered by rcu-fence.
>  Finally, the LKMM defines the RCU-before (rb) relation in terms of
>  rcu-fence.  This is done in essentially the same way as the pb
>  relation was defined in terms of strong-fence.  We will omit the
> -details; the end result is that E ->rb F implies E must execute
> -before F, just as E ->pb F does (and for much the same reasons).
> +details; the end result is that ``E ->rb F`` implies E must execute
> +before F, just as ``E ->pb F`` does (and for much the same reasons).
>  
>  Putting this all together, the LKMM expresses the Grace Period
>  Guarantee by requiring that the rb relation does not contain a cycle.
>  Equivalently, this "rcu" axiom requires that there are no events E
> -and F with E ->rcu-link F ->rcu-fence E.  Or to put it a third way,
> +and F with ``E ->rcu-link F ->rcu-fence E``.  Or to put it a third way,
>  the axiom requires that there are no cycles consisting of rcu-gp and
>  rcu-rscsi alternating with rcu-link, where the number of rcu-gp links
>  is >= the number of rcu-rscsi links.
> @@ -1621,7 +1630,7 @@ question, and let S be the synchronize_rcu() fence event for the grace
>  period.  Saying that the critical section starts before S means there
>  are events Q and R where Q is po-after L (which marks the start of the
>  critical section), Q is "before" R in the sense used by the rcu-link
> -relation, and R is po-before the grace period S.  Thus we have:
> +relation, and R is po-before the grace period S.  Thus we have::
>  
>  	L ->rcu-link S.
>  
> @@ -1629,20 +1638,20 @@ Let W be the store mentioned above, let Y come before the end of the
>  critical section and witness that W propagates to the critical
>  section's CPU by reading from W, and let Z on some arbitrary CPU be a
>  witness that W has not propagated to that CPU, where Z happens after
> -some event X which is po-after S.  Symbolically, this amounts to:
> +some event X which is po-after S.  Symbolically, this amounts to::
>  
>  	S ->po X ->hb* Z ->fr W ->rf Y ->po U.
>  
>  The fr link from Z to W indicates that W has not propagated to Z's CPU
>  at the time that Z executes.  From this, it can be shown (see the
>  discussion of the rcu-link relation earlier) that S and U are related
> -by rcu-link:
> +by rcu-link::
>  
>  	S ->rcu-link U.
>  
> -Since S is a grace period we have S ->rcu-gp S, and since L and U are
> -the start and end of the critical section C we have U ->rcu-rscsi L.
> -From this we obtain:
> +Since S is a grace period we have ``S ->rcu-gp S``, and since L and U are
> +the start and end of the critical section C we have ``U ->rcu-rscsi L``.
> +From this we obtain::
>  
>  	S ->rcu-gp S ->rcu-link U ->rcu-rscsi L ->rcu-link S,
>  
> @@ -1651,7 +1660,7 @@ the Grace Period Guarantee.
>  
>  For something a little more down-to-earth, let's see how the axiom
>  works out in practice.  Consider the RCU code example from above, this
> -time with statement labels added:
> +time with statement labels added::
>  
>  	int x, y;
>  
> @@ -1674,20 +1683,20 @@ time with statement labels added:
>  
>  
>  If r2 = 0 at the end then P0's store at Y overwrites the value that
> -P1's load at W reads from, so we have W ->fre Y.  Since S ->po W and
> -also Y ->po U, we get S ->rcu-link U.  In addition, S ->rcu-gp S
> +P1's load at W reads from, so we have ``W ->fre Y``.  Since ``S ->po W`` and
> +also ``Y ->po U``, we get ``S ->rcu-link U``.  In addition, ``S ->rcu-gp S``
>  because S is a grace period.
>  
>  If r1 = 1 at the end then P1's load at Z reads from P0's store at X,
> -so we have X ->rfe Z.  Together with L ->po X and Z ->po S, this
> -yields L ->rcu-link S.  And since L and U are the start and end of a
> -critical section, we have U ->rcu-rscsi L.
> +so we have ``X ->rfe Z``.  Together with ``L ->po X`` and ``Z ->po S``, this
> +yields ``L ->rcu-link S``.  And since L and U are the start and end of a
> +critical section, we have ``U ->rcu-rscsi L``.
>  
> -Then U ->rcu-rscsi L ->rcu-link S ->rcu-gp S ->rcu-link U is a
> +Then ``U ->rcu-rscsi L ->rcu-link S ->rcu-gp S ->rcu-link U`` is a
>  forbidden cycle, violating the "rcu" axiom.  Hence the outcome is not
>  allowed by the LKMM, as we would expect.
>  
> -For contrast, let's see what can happen in a more complicated example:
> +For contrast, let's see what can happen in a more complicated example::
>  
>  	int x, y, z;
>  
> @@ -1720,28 +1729,28 @@ For contrast, let's see what can happen in a more complicated example:
>  		U2: rcu_read_unlock();
>  	}
>  
> -If r0 = r1 = r2 = 1 at the end, then similar reasoning to before shows
> -that U0 ->rcu-rscsi L0 ->rcu-link S1 ->rcu-gp S1 ->rcu-link U2 ->rcu-rscsi
> -L2 ->rcu-link U0.  However this cycle is not forbidden, because the
> +If ``r0 = r1 = r2 = 1`` at the end, then similar reasoning to before shows
> +that ``U0 ->rcu-rscsi L0 ->rcu-link S1 ->rcu-gp S1 ->rcu-link U2 ->rcu-rscsi
> +L2 ->rcu-link U0``.  However this cycle is not forbidden, because the
>  sequence of relations contains fewer instances of rcu-gp (one) than of
>  rcu-rscsi (two).  Consequently the outcome is allowed by the LKMM.
>  The following instruction timing diagram shows how it might actually
> -occur:
> -
> -P0			P1			P2
> ---------------------	--------------------	--------------------
> -rcu_read_lock()
> -WRITE_ONCE(y, 1)
> -			r1 = READ_ONCE(y)
> -			synchronize_rcu() starts
> -			.			rcu_read_lock()
> -			.			WRITE_ONCE(x, 1)
> -r0 = READ_ONCE(x)	.
> -rcu_read_unlock()	.
> -			synchronize_rcu() ends
> -			WRITE_ONCE(z, 1)
> -						r2 = READ_ONCE(z)
> -						rcu_read_unlock()
> +occur::
> +
> +	P0			P1			P2
> +	--------------------	--------------------	--------------------
> +	rcu_read_lock()
> +	WRITE_ONCE(y, 1)
> +				r1 = READ_ONCE(y)
> +				synchronize_rcu() starts
> +				.			rcu_read_lock()
> +				.			WRITE_ONCE(x, 1)
> +	r0 = READ_ONCE(x)	.
> +	rcu_read_unlock()	.
> +				synchronize_rcu() ends
> +				WRITE_ONCE(z, 1)
> +							r2 = READ_ONCE(z)
> +							rcu_read_unlock()
>  
>  This requires P0 and P2 to execute their loads and stores out of
>  program order, but of course they are allowed to do so.  And as you
> @@ -1767,26 +1776,26 @@ The LKMM includes locking.  In fact, there is special code for locking
>  in the formal model, added in order to make tools run faster.
>  However, this special code is intended to be more or less equivalent
>  to concepts we have already covered.  A spinlock_t variable is treated
> -the same as an int, and spin_lock(&s) is treated almost the same as:
> +the same as an int, and spin_lock(&s) is treated almost the same as::
>  
>  	while (cmpxchg_acquire(&s, 0, 1) != 0)
>  		cpu_relax();
>  
>  This waits until s is equal to 0 and then atomically sets it to 1,
>  and the read part of the cmpxchg operation acts as an acquire fence.
> -An alternate way to express the same thing would be:
> +An alternate way to express the same thing would be::
>  
>  	r = xchg_acquire(&s, 1);
>  
>  along with a requirement that at the end, r = 0.  Similarly,
> -spin_trylock(&s) is treated almost the same as:
> +spin_trylock(&s) is treated almost the same as::
>  
>  	return !cmpxchg_acquire(&s, 0, 1);
>  
>  which atomically sets s to 1 if it is currently equal to 0 and returns
>  true if it succeeds (the read part of the cmpxchg operation acts as an
>  acquire fence only if the operation is successful).  spin_unlock(&s)
> -is treated almost the same as:
> +is treated almost the same as::
>  
>  	smp_store_release(&s, 0);
>  
> @@ -1802,7 +1811,7 @@ requires that every instruction po-before the lock-release must
>  execute before any instruction po-after the lock-acquire.  This would
>  naturally hold if the release and acquire operations were on different
>  CPUs, but the LKMM says it holds even when they are on the same CPU.
> -For example:
> +For example::
>  
>  	int x, y;
>  	spinlock_t s;
> @@ -1833,7 +1842,7 @@ MP pattern).
>  
>  This requirement does not apply to ordinary release and acquire
>  fences, only to lock-related operations.  For instance, suppose P0()
> -in the example had been written as:
> +in the example had been written as::
>  
>  	P0()
>  	{
> @@ -1847,7 +1856,7 @@ in the example had been written as:
>  
>  Then the CPU would be allowed to forward the s = 1 value from the
>  smp_store_release() to the smp_load_acquire(), executing the
> -instructions in the following order:
> +instructions in the following order::
>  
>  		r3 = smp_load_acquire(&s);	// Obtains r3 = 1
>  		r2 = READ_ONCE(y);
> @@ -1859,7 +1868,7 @@ and thus it could load y before x, obtaining r2 = 0 and r1 = 1.
>  Second, when a lock-acquire reads from a lock-release, and some other
>  stores W and W' occur po-before the lock-release and po-after the
>  lock-acquire respectively, the LKMM requires that W must propagate to
> -each CPU before W' does.  For example, consider:
> +each CPU before W' does.  For example, consider::
>  
>  	int x, y;
>  	spinlock_t x;
> @@ -1928,7 +1937,7 @@ smp_store_release().)  The final effect is the same.
>  Although we didn't mention it above, the instruction execution
>  ordering provided by the smp_rmb() fence doesn't apply to read events
>  that are part of a non-value-returning atomic update.  For instance,
> -given:
> +given::
>  
>  	atomic_inc(&x);
>  	smp_rmb();
> @@ -1967,14 +1976,14 @@ they behave as follows:
>  	events.
>  
>  Interestingly, RCU and locking each introduce the possibility of
> -deadlock.  When faced with code sequences such as:
> +deadlock.  When faced with code sequences such as::
>  
>  	spin_lock(&s);
>  	spin_lock(&s);
>  	spin_unlock(&s);
>  	spin_unlock(&s);
>  
> -or:
> +or::
>  
>  	rcu_read_lock();
>  	synchronize_rcu();
> @@ -1984,7 +1993,7 @@ what does the LKMM have to say?  Answer: It says there are no allowed
>  executions at all, which makes sense.  But this can also lead to
>  misleading results, because if a piece of code has multiple possible
>  executions, some of which deadlock, the model will report only on the
> -non-deadlocking executions.  For example:
> +non-deadlocking executions.  For example::
>  
>  	int x, y;
>  
> diff --git a/tools/memory-model/Documentation/index.rst b/tools/memory-model/Documentation/index.rst
> new file mode 100644
> index 000000000000..0e53d83a5a48
> --- /dev/null
> +++ b/tools/memory-model/Documentation/index.rst
> @@ -0,0 +1,20 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +========================
> +Linux Memory Model Tools
> +========================
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   explanation
> +   recipes
> +   references
> +   cheatsheet
> +
> +.. only::  subproject and html
> +
> +   Indices
> +   =======
> +
> +   * :ref:`genindex`
> diff --git a/tools/memory-model/Documentation/recipes.txt b/tools/memory-model/Documentation/recipes.rst
> similarity index 96%
> rename from tools/memory-model/Documentation/recipes.txt
> rename to tools/memory-model/Documentation/recipes.rst
> index 7fe8d7aa3029..0229a431b1a2 100644
> --- a/tools/memory-model/Documentation/recipes.txt
> +++ b/tools/memory-model/Documentation/recipes.rst
> @@ -1,3 +1,8 @@
> +=======
> +Recipes
> +=======
> +
> +
>  This document provides "recipes", that is, litmus tests for commonly
>  occurring situations, as well as a few that illustrate subtly broken but
>  attractive nuisances.  Many of these recipes include example code from
> @@ -67,7 +72,7 @@ has acquired a given lock sees any changes previously seen or made by any
>  CPU before it released that same lock.  Note that this statement is a bit
>  stronger than "Any CPU holding a given lock sees all changes made by any
>  CPU during the time that CPU was holding this same lock".  For example,
> -consider the following pair of code fragments:
> +consider the following pair of code fragments::
>  
>  	/* See MP+polocks.litmus. */
>  	void CPU0(void)
> @@ -93,7 +98,7 @@ value of r1 must also be equal to 1.  In contrast, the weaker rule would
>  say nothing about the final value of r1.
>  
>  The converse to the basic rule also holds, as illustrated by the
> -following litmus test:
> +following litmus test::
>  
>  	/* See MP+porevlocks.litmus. */
>  	void CPU0(void)
> @@ -124,7 +129,7 @@ across multiple CPUs.
>  
>  However, it is not necessarily the case that accesses ordered by
>  locking will be seen as ordered by CPUs not holding that lock.
> -Consider this example:
> +Consider this example::
>  
>  	/* See Z6.0+pooncerelease+poacquirerelease+fencembonceonce.litmus. */
>  	void CPU0(void)
> @@ -157,7 +162,7 @@ CPU2() never acquired the lock, and thus did not benefit from the
>  lock's ordering properties.
>  
>  Ordering can be extended to CPUs not holding the lock by careful use
> -of smp_mb__after_spinlock():
> +of smp_mb__after_spinlock()::
>  
>  	/* See Z6.0+pooncelock+poonceLock+pombonce.litmus. */
>  	void CPU0(void)
> @@ -214,7 +219,7 @@ Release and acquire
>  ~~~~~~~~~~~~~~~~~~~
>  
>  Use of smp_store_release() and smp_load_acquire() is one way to force
> -the desired MP ordering.  The general approach is shown below:
> +the desired MP ordering.  The general approach is shown below::
>  
>  	/* See MP+pooncerelease+poacquireonce.litmus. */
>  	void CPU0(void)
> @@ -245,7 +250,7 @@ Assign and dereference
>  Use of rcu_assign_pointer() and rcu_dereference() is quite similar to the
>  use of smp_store_release() and smp_load_acquire(), except that both
>  rcu_assign_pointer() and rcu_dereference() operate on RCU-protected
> -pointers.  The general approach is shown below:
> +pointers.  The general approach is shown below::
>  
>  	/* See MP+onceassign+derefonce.litmus. */
>  	int z;
> @@ -290,7 +295,7 @@ Write and read memory barriers
>  It is usually better to use smp_store_release() instead of smp_wmb()
>  and to use smp_load_acquire() instead of smp_rmb().  However, the older
>  smp_wmb() and smp_rmb() APIs are still heavily used, so it is important
> -to understand their use cases.  The general approach is shown below:
> +to understand their use cases.  The general approach is shown below::
>  
>  	/* See MP+fencewmbonceonce+fencermbonceonce.litmus. */
>  	void CPU0(void)
> @@ -312,7 +317,7 @@ smp_rmb() macro orders prior loads against later loads.  Therefore, if
>  the final value of r0 is 1, the final value of r1 must also be 1.
>  
>  The xlog_state_switch_iclogs() function in fs/xfs/xfs_log.c contains
> -the following write-side code fragment:
> +the following write-side code fragment::
>  
>  	log->l_curr_block -= log->l_logBBsize;
>  	ASSERT(log->l_curr_block >= 0);
> @@ -327,7 +332,7 @@ the corresponding read-side code fragment:
>  	cur_block = READ_ONCE(log->l_curr_block);
>  
>  Alternatively, consider the following comment in function
> -perf_output_put_handle() in kernel/events/ring_buffer.c:
> +perf_output_put_handle() in kernel/events/ring_buffer.c::
>  
>  	 *   kernel				user
>  	 *
> @@ -358,7 +363,7 @@ absence of any ordering it is quite possible that this may happen, as
>  can be seen in the LB+poonceonces.litmus litmus test.
>  
>  One way of avoiding the counter-intuitive outcome is through the use of a
> -control dependency paired with a full memory barrier:
> +control dependency paired with a full memory barrier::
>  
>  	/* See LB+fencembonceonce+ctrlonceonce.litmus. */
>  	void CPU0(void)
> @@ -382,7 +387,7 @@ The A/D pairing from the ring-buffer use case shown earlier also
>  illustrates LB.  Here is a repeat of the comment in
>  perf_output_put_handle() in kernel/events/ring_buffer.c, showing a
>  control dependency on the kernel side and a full memory barrier on
> -the user side:
> +the user side::
>  
>  	 *   kernel				user
>  	 *
> @@ -407,7 +412,7 @@ Release-acquire chains
>  
>  Release-acquire chains are a low-overhead, flexible, and easy-to-use
>  method of maintaining order.  However, they do have some limitations that
> -need to be fully understood.  Here is an example that maintains order:
> +need to be fully understood.  Here is an example that maintains order::
>  
>  	/* See ISA2+pooncerelease+poacquirerelease+poacquireonce.litmus. */
>  	void CPU0(void)
> @@ -436,7 +441,7 @@ example, ordering would still be preserved if CPU1()'s smp_load_acquire()
>  invocation was replaced with READ_ONCE().
>  
>  It is tempting to assume that CPU0()'s store to x is globally ordered
> -before CPU1()'s store to z, but this is not the case:
> +before CPU1()'s store to z, but this is not the case::
>  
>  	/* See Z6.0+pooncerelease+poacquirerelease+mbonceonce.litmus. */
>  	void CPU0(void)
> @@ -474,7 +479,7 @@ Store buffering
>  Store buffering can be thought of as upside-down load buffering, so
>  that one CPU first stores to one variable and then loads from a second,
>  while another CPU stores to the second variable and then loads from the
> -first.  Preserving order requires nothing less than full barriers:
> +first.  Preserving order requires nothing less than full barriers::
>  
>  	/* See SB+fencembonceonces.litmus. */
>  	void CPU0(void)
> @@ -498,7 +503,7 @@ this counter-intuitive outcome.
>  This pattern most famously appears as part of Dekker's locking
>  algorithm, but it has a much more practical use within the Linux kernel
>  of ordering wakeups.  The following comment taken from waitqueue_active()
> -in include/linux/wait.h shows the canonical pattern:
> +in include/linux/wait.h shows the canonical pattern::
>  
>   *      CPU0 - waker                    CPU1 - waiter
>   *
> @@ -550,16 +555,16 @@ The strength of memory ordering required for a given litmus test to
>  avoid a counter-intuitive outcome depends on the types of relations
>  linking the memory accesses for the outcome in question:
>  
> -o	If all links are write-to-read links, then the weakest
> +-	If all links are write-to-read links, then the weakest
>  	possible ordering within each CPU suffices.  For example, in
>  	the LB litmus test, a control dependency was enough to do the
>  	job.
>  
> -o	If all but one of the links are write-to-read links, then a
> +-	If all but one of the links are write-to-read links, then a
>  	release-acquire chain suffices.  Both the MP and the ISA2
>  	litmus tests illustrate this case.
>  
> -o	If more than one of the links are something other than
> +-	If more than one of the links are something other than
>  	write-to-read links, then a full memory barrier is required
>  	between each successive pair of non-write-to-read links.  This
>  	case is illustrated by the Z6.0 litmus tests, both in the
> diff --git a/tools/memory-model/Documentation/references.txt b/tools/memory-model/Documentation/references.rst
> similarity index 71%
> rename from tools/memory-model/Documentation/references.txt
> rename to tools/memory-model/Documentation/references.rst
> index b177f3e4a614..275876cd10b8 100644
> --- a/tools/memory-model/Documentation/references.txt
> +++ b/tools/memory-model/Documentation/references.rst
> @@ -1,3 +1,7 @@
> +==========
> +References
> +==========
> +
>  This document provides background reading for memory models and related
>  tools.  These documents are aimed at kernel hackers who are interested
>  in memory models.
> @@ -6,64 +10,64 @@ in memory models.
>  Hardware manuals and models
>  ===========================
>  
> -o	SPARC International Inc. (Ed.). 1994. "The SPARC Architecture
> +-	SPARC International Inc. (Ed.). 1994. "The SPARC Architecture
>  	Reference Manual Version 9". SPARC International Inc.
>  
> -o	Compaq Computer Corporation (Ed.). 2002. "Alpha Architecture
> +-	Compaq Computer Corporation (Ed.). 2002. "Alpha Architecture
>  	Reference Manual".  Compaq Computer Corporation.
>  
> -o	Intel Corporation (Ed.). 2002. "A Formal Specification of Intel
> +-	Intel Corporation (Ed.). 2002. "A Formal Specification of Intel
>  	Itanium Processor Family Memory Ordering". Intel Corporation.
>  
> -o	Intel Corporation (Ed.). 2002. "Intel 64 and IA-32 Architectures
> +-	Intel Corporation (Ed.). 2002. "Intel 64 and IA-32 Architectures
>  	Software Developer’s Manual". Intel Corporation.
>  
> -o	Peter Sewell, Susmit Sarkar, Scott Owens, Francesco Zappa Nardelli,
> +-	Peter Sewell, Susmit Sarkar, Scott Owens, Francesco Zappa Nardelli,
>  	and Magnus O. Myreen. 2010. "x86-TSO: A Rigorous and Usable
>  	Programmer's Model for x86 Multiprocessors". Commun. ACM 53, 7
>  	(July, 2010), 89-97. http://doi.acm.org/10.1145/1785414.1785443
>  
> -o	IBM Corporation (Ed.). 2009. "Power ISA Version 2.06". IBM
> +-	IBM Corporation (Ed.). 2009. "Power ISA Version 2.06". IBM
>  	Corporation.
>  
> -o	ARM Ltd. (Ed.). 2009. "ARM Barrier Litmus Tests and Cookbook".
> +-	ARM Ltd. (Ed.). 2009. "ARM Barrier Litmus Tests and Cookbook".
>  	ARM Ltd.
>  
> -o	Susmit Sarkar, Peter Sewell, Jade Alglave, Luc Maranget, and
> +-	Susmit Sarkar, Peter Sewell, Jade Alglave, Luc Maranget, and
>  	Derek Williams.  2011. "Understanding POWER Multiprocessors". In
>  	Proceedings of the 32Nd ACM SIGPLAN Conference on Programming
>  	Language Design and Implementation (PLDI ’11). ACM, New York,
>  	NY, USA, 175–186.
>  
> -o	Susmit Sarkar, Kayvan Memarian, Scott Owens, Mark Batty,
> +-	Susmit Sarkar, Kayvan Memarian, Scott Owens, Mark Batty,
>  	Peter Sewell, Luc Maranget, Jade Alglave, and Derek Williams.
>  	2012. "Synchronising C/C++ and POWER". In Proceedings of the 33rd
>  	ACM SIGPLAN Conference on Programming Language Design and
>  	Implementation (PLDI '12). ACM, New York, NY, USA, 311-322.
>  
> -o	ARM Ltd. (Ed.). 2014. "ARM Architecture Reference Manual (ARMv8,
> +-	ARM Ltd. (Ed.). 2014. "ARM Architecture Reference Manual (ARMv8,
>  	for ARMv8-A architecture profile)". ARM Ltd.
>  
> -o	Imagination Technologies, LTD. 2015. "MIPS(R) Architecture
> +-	Imagination Technologies, LTD. 2015. "MIPS(R) Architecture
>  	For Programmers, Volume II-A: The MIPS64(R) Instruction,
>  	Set Reference Manual". Imagination Technologies,
>  	LTD. https://imgtec.com/?do-download=4302.
>  
> -o	Shaked Flur, Kathryn E. Gray, Christopher Pulte, Susmit
> +-	Shaked Flur, Kathryn E. Gray, Christopher Pulte, Susmit
>  	Sarkar, Ali Sezgin, Luc Maranget, Will Deacon, and Peter
>  	Sewell. 2016. "Modelling the ARMv8 Architecture, Operationally:
>  	Concurrency and ISA". In Proceedings of the 43rd Annual ACM
>  	SIGPLAN-SIGACT Symposium on Principles of Programming Languages
>  	(POPL ’16). ACM, New York, NY, USA, 608–621.
>  
> -o	Shaked Flur, Susmit Sarkar, Christopher Pulte, Kyndylan Nienhuis,
> +-	Shaked Flur, Susmit Sarkar, Christopher Pulte, Kyndylan Nienhuis,
>  	Luc Maranget, Kathryn E. Gray, Ali Sezgin, Mark Batty, and Peter
>  	Sewell. 2017. "Mixed-size Concurrency: ARM, POWER, C/C++11,
>  	and SC". In Proceedings of the 44th ACM SIGPLAN Symposium on
>  	Principles of Programming Languages (POPL 2017). ACM, New York,
>  	NY, USA, 429–442.
>  
> -o	Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
> +-	Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
>  	Susmit Sarkar, and Peter Sewell. 2018. "Simplifying ARM concurrency:
>  	multicopy-atomic axiomatic and operational models for ARMv8". In
>  	Proceedings of the ACM on Programming Languages, Volume 2, Issue
> @@ -73,18 +77,18 @@ o	Christopher Pulte, Shaked Flur, Will Deacon, Jon French,
>  Linux-kernel memory model
>  =========================
>  
> -o	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
> +-	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
>  	Alan Stern.  2018. "Frightening small children and disconcerting
>  	grown-ups: Concurrency in the Linux kernel". In Proceedings of
>  	the 23rd International Conference on Architectural Support for
>  	Programming Languages and Operating Systems (ASPLOS 2018). ACM,
>  	New York, NY, USA, 405-418.  Webpage: http://diy.inria.fr/linux/.
>  
> -o	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
> +-	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
>  	Alan Stern.  2017.  "A formal kernel memory-ordering model (part 1)"
>  	Linux Weekly News.  https://lwn.net/Articles/718628/
>  
> -o	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
> +-	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
>  	Alan Stern.  2017.  "A formal kernel memory-ordering model (part 2)"
>  	Linux Weekly News.  https://lwn.net/Articles/720550/
>  
> @@ -92,16 +96,16 @@ o	Jade Alglave, Luc Maranget, Paul E. McKenney, Andrea Parri, and
>  Memory-model tooling
>  ====================
>  
> -o	Daniel Jackson. 2002. "Alloy: A Lightweight Object Modelling
> +-	Daniel Jackson. 2002. "Alloy: A Lightweight Object Modelling
>  	Notation". ACM Trans. Softw. Eng. Methodol. 11, 2 (April 2002),
>  	256–290. http://doi.acm.org/10.1145/505145.505149
>  
> -o	Jade Alglave, Luc Maranget, and Michael Tautschnig. 2014. "Herding
> +-	Jade Alglave, Luc Maranget, and Michael Tautschnig. 2014. "Herding
>  	Cats: Modelling, Simulation, Testing, and Data Mining for Weak
>  	Memory". ACM Trans. Program. Lang. Syst. 36, 2, Article 7 (July
>  	2014), 7:1–7:74 pages.
>  
> -o	Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
> +-	Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
>  	semantics of the weak consistency model specification language
>  	cat". CoRR abs/1608.07531 (2016). http://arxiv.org/abs/1608.07531
>  
> @@ -109,6 +113,6 @@ o	Jade Alglave, Patrick Cousot, and Luc Maranget. 2016. "Syntax and
>  Memory-model comparisons
>  ========================
>  
> -o	Paul E. McKenney, Ulrich Weigand, Andrea Parri, and Boqun
> +-	Paul E. McKenney, Ulrich Weigand, Andrea Parri, and Boqun
>  	Feng. 2016. "Linux-Kernel Memory Model". (6 June 2016).
>  	http://open-std.org/JTC1/SC22/WG21/docs/papers/2016/p0124r2.html.
> diff --git a/tools/memory-model/README b/tools/memory-model/README
> index 2b87f3971548..04bb1fa9ed76 100644
> --- a/tools/memory-model/README
> +++ b/tools/memory-model/README
> @@ -105,16 +105,16 @@ for more information.
>  DESCRIPTION OF FILES
>  ====================
>  
> -Documentation/cheatsheet.txt
> +Documentation/cheatsheet.rst
>  	Quick-reference guide to the Linux-kernel memory model.
>  
> -Documentation/explanation.txt
> +Documentation/explanation.rst
>  	Describes the memory model in detail.
>  
> -Documentation/recipes.txt
> +Documentation/recipes.rst
>  	Lists common memory-ordering patterns.
>  
> -Documentation/references.txt
> +Documentation/references.rst
>  	Provides background reading.
>  
>  linux-kernel.bell
> @@ -173,7 +173,7 @@ The Linux-kernel memory model has the following limitations:
>  	of READ_ONCE() and WRITE_ONCE() limits the compiler's ability
>  	to optimize, but there is Linux-kernel code that uses bare C
>  	memory accesses.  Handling this code is on the to-do list.
> -	For more information, see Documentation/explanation.txt (in
> +	For more information, see Documentation/explanation.rst (in
>  	particular, the "THE PROGRAM ORDER RELATION: po AND po-loc"
>  	and "A WARNING" sections).
>  
> 
> 

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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
  2019-07-30 21:50     ` Mauro Carvalho Chehab
@ 2019-07-30 23:37       ` Paul E. McKenney
  2019-07-31  0:04         ` Paul E. McKenney
  0 siblings, 1 reply; 75+ messages in thread
From: Paul E. McKenney @ 2019-07-30 23:37 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
	Joel Fernandes, Jonathan Corbet, rcu, linux-doc

On Tue, Jul 30, 2019 at 06:50:51PM -0300, Mauro Carvalho Chehab wrote:
> Em Tue, 30 Jul 2019 14:22:50 -0700
> "Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:
> 
> > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > > There are 4 RCU articles that are written on html format.
> > > 
> > > The way they are, they can't be part of the Linux Kernel
> > > documentation body nor share the styles and pdf output.
> > > 
> > > So, convert them to ReST format.
> > > 
> > > This way, make htmldocs and make pdfdocs will produce a
> > > documentation output that will be like the original ones, but
> > > will be part of the Linux Kernel documentation body.
> > > 
> > > Part of the conversion was done with the help of pandoc, but
> > > the result had some broken things that had to be manually
> > > fixed.
> > > 
> > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>  
> > 
> > I am having some trouble applying these, at least in part due to UTF-8
> > sequences, for example double left quotation mark.  These end up being
> > "=E2=80=9C", with a few space characters turned into "=20".
> > 
> > Any advice on how to apply these?
> 
> Didn't notice it ended with UTF-8 chars. It is probably because it came
> from the html conversion.

Or maybe there are some email issues somewhere along the way.

> I guess it shouldn't hurt keeping those, but if you prefer I can find 
> some time later to replace them.
> 
> > Should I just pull commits from somewhere?
> 
> Yeah, if you prefer, you can pull from this branch:
> 
> 	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rcu-v1
> 
> It has just two patches: the RCU and tools/memory-model ones.
> 
> It is based on v5.3-rc2.

And that does apply, thank you!

							Thanx, Paul


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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
  2019-07-30 23:37       ` Paul E. McKenney
@ 2019-07-31  0:04         ` Paul E. McKenney
  2019-07-31  0:47           ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 75+ messages in thread
From: Paul E. McKenney @ 2019-07-31  0:04 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
	Joel Fernandes, Jonathan Corbet, rcu, linux-doc

On Tue, Jul 30, 2019 at 04:37:20PM -0700, Paul E. McKenney wrote:
> On Tue, Jul 30, 2019 at 06:50:51PM -0300, Mauro Carvalho Chehab wrote:
> > Em Tue, 30 Jul 2019 14:22:50 -0700
> > "Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:
> > 
> > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:
> > > > There are 4 RCU articles that are written on html format.
> > > > 
> > > > The way they are, they can't be part of the Linux Kernel
> > > > documentation body nor share the styles and pdf output.
> > > > 
> > > > So, convert them to ReST format.
> > > > 
> > > > This way, make htmldocs and make pdfdocs will produce a
> > > > documentation output that will be like the original ones, but
> > > > will be part of the Linux Kernel documentation body.
> > > > 
> > > > Part of the conversion was done with the help of pandoc, but
> > > > the result had some broken things that had to be manually
> > > > fixed.
> > > > 
> > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>  
> > > 
> > > I am having some trouble applying these, at least in part due to UTF-8
> > > sequences, for example double left quotation mark.  These end up being
> > > "=E2=80=9C", with a few space characters turned into "=20".
> > > 
> > > Any advice on how to apply these?
> > 
> > Didn't notice it ended with UTF-8 chars. It is probably because it came
> > from the html conversion.
> 
> Or maybe there are some email issues somewhere along the way.
> 
> > I guess it shouldn't hurt keeping those, but if you prefer I can find 
> > some time later to replace them.
> > 
> > > Should I just pull commits from somewhere?
> > 
> > Yeah, if you prefer, you can pull from this branch:
> > 
> > 	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rcu-v1
> > 
> > It has just two patches: the RCU and tools/memory-model ones.
> > 
> > It is based on v5.3-rc2.
> 
> And that does apply, thank you!

And "make htmldocs" does produce real HTML!  At first glance anyway,
quite impressive.

However, "make pdfdocs" gives me this complaint:

	! Dimension too large.
	\color@b@x ... #3}\kern \fboxsep }\dimen@ \ht \z@ 
							  \advance \dimen@ \fboxsep ...
	l.5092 \end{sphinxVerbatim}

This appears to come from Documentation/output/latex/RCU.tex.
There is nevertheless an RCU.pdf in this directory.  It is not
bad, but has a figure full of XML on PDF page 21.  And a few later
on as well.

On the HTML side, the quick quizzes have immediately visible answers,
which defeats the purpose.  The original HTML used a white font,
so that you selected the answer with your mouse to make it visible.
Can something similar be done with Sphinx?  Another approach is to
gather the answers into a separate file and link to them.

I believe that Joel already noted that internal links are not working.
The external links that I tried work just fine, though.  As do the
links from the table of contents.

							Thanx, Paul

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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
  2019-07-31  0:04         ` Paul E. McKenney
@ 2019-07-31  0:47           ` Mauro Carvalho Chehab
  2019-07-31  1:06             ` Paul E. McKenney
  0 siblings, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-31  0:47 UTC (permalink / raw)
  To: Paul E. McKenney
  Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
	Joel Fernandes, Jonathan Corbet, rcu, linux-doc

Em Tue, 30 Jul 2019 17:04:55 -0700
"Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:

> On Tue, Jul 30, 2019 at 04:37:20PM -0700, Paul E. McKenney wrote:
> > On Tue, Jul 30, 2019 at 06:50:51PM -0300, Mauro Carvalho Chehab wrote:  
> > > Em Tue, 30 Jul 2019 14:22:50 -0700
> > > "Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:
> > >   
> > > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:  
> > > > > There are 4 RCU articles that are written on html format.
> > > > > 
> > > > > The way they are, they can't be part of the Linux Kernel
> > > > > documentation body nor share the styles and pdf output.
> > > > > 
> > > > > So, convert them to ReST format.
> > > > > 
> > > > > This way, make htmldocs and make pdfdocs will produce a
> > > > > documentation output that will be like the original ones, but
> > > > > will be part of the Linux Kernel documentation body.
> > > > > 
> > > > > Part of the conversion was done with the help of pandoc, but
> > > > > the result had some broken things that had to be manually
> > > > > fixed.
> > > > > 
> > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>    
> > > > 
> > > > I am having some trouble applying these, at least in part due to UTF-8
> > > > sequences, for example double left quotation mark.  These end up being
> > > > "=E2=80=9C", with a few space characters turned into "=20".
> > > > 
> > > > Any advice on how to apply these?  
> > > 
> > > Didn't notice it ended with UTF-8 chars. It is probably because it came
> > > from the html conversion.  
> > 
> > Or maybe there are some email issues somewhere along the way.
> >   
> > > I guess it shouldn't hurt keeping those, but if you prefer I can find 
> > > some time later to replace them.
> > >   
> > > > Should I just pull commits from somewhere?  
> > > 
> > > Yeah, if you prefer, you can pull from this branch:
> > > 
> > > 	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rcu-v1
> > > 
> > > It has just two patches: the RCU and tools/memory-model ones.
> > > 
> > > It is based on v5.3-rc2.  
> > 
> > And that does apply, thank you!  
> 
> And "make htmldocs" does produce real HTML!  At first glance anyway,
> quite impressive.

Yeah, its output is pretty decent.

> However, "make pdfdocs" gives me this complaint:
> 
> 	! Dimension too large.
> 	\color@b@x ... #3}\kern \fboxsep }\dimen@ \ht \z@ 
> 							  \advance \dimen@ \fboxsep ...
> 	l.5092 \end{sphinxVerbatim}
> 
> This appears to come from Documentation/output/latex/RCU.tex.
> There is nevertheless an RCU.pdf in this directory.  It is not
> bad, but has a figure full of XML on PDF page 21.  And a few later
> on as well.

PDF output is indeed an issue. The way it works is that it first
generates a LaTeX and then it uses texlive to produce the PDF. 

There is a rst2pdf tool with handles it directly, but it is a way more
 problematic. I have an experimental patch with enables it. Maybe
some day it could be applied, but upstream for the tool needs a lot 
more work.

With regards to the LaTeX/PDF output, on media, we had to tweak the
documents in order for them to produce a good LaTeX/PDF output on tables.

Usually, before some tables, we add something like this:

.. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}|

in order to teach LaTeX the size of each column.

If the table is really big, the only way for it to fit is to reduce
the font size, using a raw LaTeX syntax. See, for example:

	Documentation/media/uapi/v4l/dev-subdev.rst

There, we use things like:

.. raw:: latex

    \scriptsize

.. tabularcolumns:: |p{2.0cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|


	+-----------------+ ...
	| Some long table | ...
	+-----------------+ ...
	...
	+-----------------+ ...


.. raw:: latex

    \normalsize

In order to use a small font for the table.

Neither "raw:: latex" nor "tabularcolumns" tag affect html.

There is another trick too. By default, Sphinx LaTeX output uses a
type of table that should fit into a single page ("tabular").

If the table has more than 30 columns, it switches to another type
("longtable"), with can be split into multiple pages.

As the quiz tables usually have only 4 columns, it will always try
the unbreakable tabular table. If it doesn't fit, PDF will break.

In order to avoid that, just add:

.. cssclass:: longtable

Before the offended table. This will make Sphinx to use LaTeX
longtable instead of tabular ones.

This won't affect html output.

> On the HTML side, the quick quizzes have immediately visible answers,
> which defeats the purpose.  The original HTML used a white font,
> so that you selected the answer with your mouse to make it visible.
>
> Can something similar be done with Sphinx?  Another approach is to
> gather the answers into a separate file and link to them.

Yeah, I guess you used a css style that would make the answer visible
when the mouse is inside it on your original lwn.net set of articles. 

Sphinx has a directive to use css, so, the short answer is: yes, you
can. 

For html, you would need to add a css specific for the RCU quiz,
placing it under Documentation/sphinx directory. Then, use the
 ".. css" directive to handle that.

You should notice, however, that this will be ignored for 
LaTeX/pdf output.

I guess you can place this on another file, or perhaps place at the
end of the document, having a link for the quiz answers. 

Another alternative would be to make the answer as a footnote.

> I believe that Joel already noted that internal links are not working.
> The external links that I tried work just fine, though.  As do the
> links from the table of contents.

Yeah. Funny enough, when I tested here, they worked fine. Maybe
this is due to the Sphinx version I used here at the time I wrote
it.

Anyway, Joel already submitted a patch addressing this one. 


Thanks,
Mauro

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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
  2019-07-31  0:47           ` Mauro Carvalho Chehab
@ 2019-07-31  1:06             ` Paul E. McKenney
  2019-07-31  1:33               ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 75+ messages in thread
From: Paul E. McKenney @ 2019-07-31  1:06 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
	Joel Fernandes, Jonathan Corbet, rcu, linux-doc

On Tue, Jul 30, 2019 at 09:47:22PM -0300, Mauro Carvalho Chehab wrote:
> Em Tue, 30 Jul 2019 17:04:55 -0700
> "Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:
> 
> > On Tue, Jul 30, 2019 at 04:37:20PM -0700, Paul E. McKenney wrote:
> > > On Tue, Jul 30, 2019 at 06:50:51PM -0300, Mauro Carvalho Chehab wrote:  
> > > > Em Tue, 30 Jul 2019 14:22:50 -0700
> > > > "Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:
> > > >   
> > > > > On Fri, Jul 26, 2019 at 09:51:35AM -0300, Mauro Carvalho Chehab wrote:  
> > > > > > There are 4 RCU articles that are written on html format.
> > > > > > 
> > > > > > The way they are, they can't be part of the Linux Kernel
> > > > > > documentation body nor share the styles and pdf output.
> > > > > > 
> > > > > > So, convert them to ReST format.
> > > > > > 
> > > > > > This way, make htmldocs and make pdfdocs will produce a
> > > > > > documentation output that will be like the original ones, but
> > > > > > will be part of the Linux Kernel documentation body.
> > > > > > 
> > > > > > Part of the conversion was done with the help of pandoc, but
> > > > > > the result had some broken things that had to be manually
> > > > > > fixed.
> > > > > > 
> > > > > > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>    
> > > > > 
> > > > > I am having some trouble applying these, at least in part due to UTF-8
> > > > > sequences, for example double left quotation mark.  These end up being
> > > > > "=E2=80=9C", with a few space characters turned into "=20".
> > > > > 
> > > > > Any advice on how to apply these?  
> > > > 
> > > > Didn't notice it ended with UTF-8 chars. It is probably because it came
> > > > from the html conversion.  
> > > 
> > > Or maybe there are some email issues somewhere along the way.
> > >   
> > > > I guess it shouldn't hurt keeping those, but if you prefer I can find 
> > > > some time later to replace them.
> > > >   
> > > > > Should I just pull commits from somewhere?  
> > > > 
> > > > Yeah, if you prefer, you can pull from this branch:
> > > > 
> > > > 	https://git.linuxtv.org/mchehab/experimental.git/log/?h=rcu-v1
> > > > 
> > > > It has just two patches: the RCU and tools/memory-model ones.
> > > > 
> > > > It is based on v5.3-rc2.  
> > > 
> > > And that does apply, thank you!  
> > 
> > And "make htmldocs" does produce real HTML!  At first glance anyway,
> > quite impressive.
> 
> Yeah, its output is pretty decent.
> 
> > However, "make pdfdocs" gives me this complaint:
> > 
> > 	! Dimension too large.
> > 	\color@b@x ... #3}\kern \fboxsep }\dimen@ \ht \z@ 
> > 							  \advance \dimen@ \fboxsep ...
> > 	l.5092 \end{sphinxVerbatim}
> > 
> > This appears to come from Documentation/output/latex/RCU.tex.
> > There is nevertheless an RCU.pdf in this directory.  It is not
> > bad, but has a figure full of XML on PDF page 21.  And a few later
> > on as well.
> 
> PDF output is indeed an issue. The way it works is that it first
> generates a LaTeX and then it uses texlive to produce the PDF. 
> 
> There is a rst2pdf tool with handles it directly, but it is a way more
>  problematic. I have an experimental patch with enables it. Maybe
> some day it could be applied, but upstream for the tool needs a lot 
> more work.
> 
> With regards to the LaTeX/PDF output, on media, we had to tweak the
> documents in order for them to produce a good LaTeX/PDF output on tables.
> 
> Usually, before some tables, we add something like this:
> 
> .. tabularcolumns:: |p{1.2cm}|p{2.9cm}|p{13.4cm}|
> 
> in order to teach LaTeX the size of each column.
> 
> If the table is really big, the only way for it to fit is to reduce
> the font size, using a raw LaTeX syntax. See, for example:
> 
> 	Documentation/media/uapi/v4l/dev-subdev.rst
> 
> There, we use things like:
> 
> .. raw:: latex
> 
>     \scriptsize
> 
> .. tabularcolumns:: |p{2.0cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|p{2.3cm}|
> 
> 
> 	+-----------------+ ...
> 	| Some long table | ...
> 	+-----------------+ ...
> 	...
> 	+-----------------+ ...
> 
> 
> .. raw:: latex
> 
>     \normalsize
> 
> In order to use a small font for the table.
> 
> Neither "raw:: latex" nor "tabularcolumns" tag affect html.
> 
> There is another trick too. By default, Sphinx LaTeX output uses a
> type of table that should fit into a single page ("tabular").
> 
> If the table has more than 30 columns, it switches to another type
> ("longtable"), with can be split into multiple pages.
> 
> As the quiz tables usually have only 4 columns, it will always try
> the unbreakable tabular table. If it doesn't fit, PDF will break.
> 
> In order to avoid that, just add:
> 
> .. cssclass:: longtable
> 
> Before the offended table. This will make Sphinx to use LaTeX
> longtable instead of tabular ones.
> 
> This won't affect html output.

Would it be fair to say that html output is what is currently supported,
and that PDF output is a future thing?

> > On the HTML side, the quick quizzes have immediately visible answers,
> > which defeats the purpose.  The original HTML used a white font,
> > so that you selected the answer with your mouse to make it visible.
> >
> > Can something similar be done with Sphinx?  Another approach is to
> > gather the answers into a separate file and link to them.
> 
> Yeah, I guess you used a css style that would make the answer visible
> when the mouse is inside it on your original lwn.net set of articles. 
> 
> Sphinx has a directive to use css, so, the short answer is: yes, you
> can. 
> 
> For html, you would need to add a css specific for the RCU quiz,
> placing it under Documentation/sphinx directory. Then, use the
>  ".. css" directive to handle that.
> 
> You should notice, however, that this will be ignored for 
> LaTeX/pdf output.
> 
> I guess you can place this on another file, or perhaps place at the
> end of the document, having a link for the quiz answers. 
> 
> Another alternative would be to make the answer as a footnote.

Making it CSS for HTML and a footnote for PDF seems eminently
reasonable to me!

> > I believe that Joel already noted that internal links are not working.
> > The external links that I tried work just fine, though.  As do the
> > links from the table of contents.
> 
> Yeah. Funny enough, when I tested here, they worked fine. Maybe
> this is due to the Sphinx version I used here at the time I wrote
> it.
> 
> Anyway, Joel already submitted a patch addressing this one. 

And it works for me, anyway!  ;-)

							Thanx, Paul

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

* Re: [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST
  2019-07-31  1:06             ` Paul E. McKenney
@ 2019-07-31  1:33               ` Mauro Carvalho Chehab
  0 siblings, 0 replies; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-31  1:33 UTC (permalink / raw)
  To: Paul E. McKenney
  Cc: Josh Triplett, Steven Rostedt, Mathieu Desnoyers, Lai Jiangshan,
	Joel Fernandes, Jonathan Corbet, rcu, linux-doc

Em Tue, 30 Jul 2019 18:06:24 -0700
"Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:

> On Tue, Jul 30, 2019 at 09:47:22PM -0300, Mauro Carvalho Chehab wrote:
> > Em Tue, 30 Jul 2019 17:04:55 -0700
> > "Paul E. McKenney" <paulmck@linux.ibm.com> escreveu:

> > > This appears to come from Documentation/output/latex/RCU.tex.
> > > There is nevertheless an RCU.pdf in this directory.  It is not
> > > bad, but has a figure full of XML on PDF page 21.  And a few later
> > > on as well.  
> > 
> > PDF output is indeed an issue. The way it works is that it first
> > generates a LaTeX and then it uses texlive to produce the PDF. 
> 
> Would it be fair to say that html output is what is currently supported,
> and that PDF output is a future thing?

Sure.

Anyway, if you want to fix PDF later, I suspect that simply adding:

	.. cssclass:: longtable

Before each quiz table should be enough to fix, as the tables there seem
to be simple enough. 

After fixed, the PDF and LaTeX output are usually decent.

> > > On the HTML side, the quick quizzes have immediately visible answers,
> > > which defeats the purpose.  The original HTML used a white font,
> > > so that you selected the answer with your mouse to make it visible.
> > >
> > > Can something similar be done with Sphinx?  Another approach is to
> > > gather the answers into a separate file and link to them.  
> > 
> > Yeah, I guess you used a css style that would make the answer visible
> > when the mouse is inside it on your original lwn.net set of articles. 
> > 
> > Sphinx has a directive to use css, so, the short answer is: yes, you
> > can. 
> > 
> > For html, you would need to add a css specific for the RCU quiz,
> > placing it under Documentation/sphinx directory. Then, use the
> >  ".. css" directive to handle that.
> > 
> > You should notice, however, that this will be ignored for 
> > LaTeX/pdf output.
> > 
> > I guess you can place this on another file, or perhaps place at the
> > end of the document, having a link for the quiz answers. 
> > 
> > Another alternative would be to make the answer as a footnote.  
> 
> Making it CSS for HTML and a footnote for PDF seems eminently
> reasonable to me!

You should either do CSS or PDF, as otherwise you will end with dirty
hacks like:

.. only:: html

	<some quiz table with answers using css>

.. only: latex

	<some quiz table with answers using footnotes>

E. g. you'll need to place the quiz twice, making it harder to maintain
and messier.

Btw, the LaTeX may also parse a css tag, processing it via some custom
macro (with should be added at Documentation/conf.py.

> > > I believe that Joel already noted that internal links are not working.
> > > The external links that I tried work just fine, though.  As do the
> > > links from the table of contents.  
> > 
> > Yeah. Funny enough, when I tested here, they worked fine. Maybe
> > this is due to the Sphinx version I used here at the time I wrote
> > it.
> > 
> > Anyway, Joel already submitted a patch addressing this one.   
> 
> And it works for me, anyway!  ;-)

Great!

Thanks,
Mauro

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

* Re: [PATCH] tools: memory-model: add it to the Documentation body
  2019-07-30 22:57             ` Mauro Carvalho Chehab
@ 2019-07-31 13:52                 ` Alan Stern
  0 siblings, 0 replies; 75+ messages in thread
From: Alan Stern @ 2019-07-31 13:52 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Joel Fernandes, Linux Doc Mailing List, Mauro Carvalho Chehab,
	linux-kernel, Jonathan Corbet, Andrea Parri, Will Deacon,
	Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
	Jade Alglave, Luc Maranget, Paul E. McKenney, Akira Yokosawa,
	Daniel Lustig, Ingo Molnar, Jason Gunthorpe, SeongJae Park,
	linux-arch

On Tue, 30 Jul 2019, Mauro Carvalho Chehab wrote:

> Em Tue, 30 Jul 2019 18:17:01 -0400
> Joel Fernandes <joel@joelfernandes.org> escreveu:

> > > > (4) I would argue that every occurence of
> > > > A ->(some dependency) B should be replaced with fixed size font in the HTML
> > > > results.  
> > > 
> > > Just place those with ``A -> (some dependency)``. This will make them use
> > > a fixed size font.  
> > 
> > Ok, understood all these. I guess my point was all of these will need to be
> > done to make this document useful from a ReST conversion standpoint. Until
> > then it is probably just better off being plain text - since there are so
> > many of those ``A -> (dep) B`` things.

> On a very quick look, it seems that, if we replace:
> 
> 	(\S+\s->\S*\s\w+)
> 
> by:
> 	``\1``
> 
> 
> On an editor that would allow to manually replace the regex (like kate),
> most of those can be get.
> 
> See patch enclosed.

Some time ago I considered the problem of converting this file to ReST 
format.  But I gave up on the idea, because the necessary changes were 
so widespread and the resulting text file would not be easily readable.

Replacing things of the form "A ->dep B" just scratches the surface.  
That document teems with variable names, formulas, code extracts, and
other things which would all need to be rendered in a different font
style.  The density of the markup required to do this would be
phenomenally high.

In my opinion it simply was not worthwhile.

Alan Stern


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

* Re: [PATCH] tools: memory-model: add it to the Documentation body
@ 2019-07-31 13:52                 ` Alan Stern
  0 siblings, 0 replies; 75+ messages in thread
From: Alan Stern @ 2019-07-31 13:52 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Joel Fernandes, Linux Doc Mailing List, Mauro Carvalho Chehab,
	linux-kernel, Jonathan Corbet, Andrea Parri, Will Deacon,
	Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
	Jade Alglave, Luc Maranget, Paul E. McKenney, Akira Yokosawa,
	Daniel Lustig, Ingo Molnar, Jason Gunthorpe, SeongJae Park,
	linux-arch

On Tue, 30 Jul 2019, Mauro Carvalho Chehab wrote:

> Em Tue, 30 Jul 2019 18:17:01 -0400
> Joel Fernandes <joel@joelfernandes.org> escreveu:

> > > > (4) I would argue that every occurence of
> > > > A ->(some dependency) B should be replaced with fixed size font in the HTML
> > > > results.  
> > > 
> > > Just place those with ``A -> (some dependency)``. This will make them use
> > > a fixed size font.  
> > 
> > Ok, understood all these. I guess my point was all of these will need to be
> > done to make this document useful from a ReST conversion standpoint. Until
> > then it is probably just better off being plain text - since there are so
> > many of those ``A -> (dep) B`` things.

> On a very quick look, it seems that, if we replace:
> 
> 	(\S+\s->\S*\s\w+)
> 
> by:
> 	``\1``
> 
> 
> On an editor that would allow to manually replace the regex (like kate),
> most of those can be get.
> 
> See patch enclosed.

Some time ago I considered the problem of converting this file to ReST 
format.  But I gave up on the idea, because the necessary changes were 
so widespread and the resulting text file would not be easily readable.

Replacing things of the form "A ->dep B" just scratches the surface.  
That document teems with variable names, formulas, code extracts, and
other things which would all need to be rendered in a different font
style.  The density of the markup required to do this would be
phenomenally high.

In my opinion it simply was not worthwhile.

Alan Stern

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

* Re: [PATCH] tools: memory-model: add it to the Documentation body
  2019-07-31 13:52                 ` Alan Stern
  (?)
@ 2019-07-31 15:19                 ` Akira Yokosawa
  2019-07-31 20:25                   ` Paul E. McKenney
  -1 siblings, 1 reply; 75+ messages in thread
From: Akira Yokosawa @ 2019-07-31 15:19 UTC (permalink / raw)
  To: Alan Stern, Mauro Carvalho Chehab
  Cc: Joel Fernandes, Linux Doc Mailing List, Mauro Carvalho Chehab,
	linux-kernel, Jonathan Corbet, Andrea Parri, Will Deacon,
	Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells,
	Jade Alglave, Luc Maranget, Paul E. McKenney, Daniel Lustig,
	Ingo Molnar, Jason Gunthorpe, SeongJae Park, linux-arch

On Wed, 31 Jul 2019 09:52:05 -0400, Alan Stern wrote:
> On Tue, 30 Jul 2019, Mauro Carvalho Chehab wrote:
> 
>> Em Tue, 30 Jul 2019 18:17:01 -0400
>> Joel Fernandes <joel@joelfernandes.org> escreveu:
> 
>>>>> (4) I would argue that every occurence of
>>>>> A ->(some dependency) B should be replaced with fixed size font in the HTML
>>>>> results.  
>>>>
>>>> Just place those with ``A -> (some dependency)``. This will make them use
>>>> a fixed size font.  
>>>
>>> Ok, understood all these. I guess my point was all of these will need to be
>>> done to make this document useful from a ReST conversion standpoint. Until
>>> then it is probably just better off being plain text - since there are so
>>> many of those ``A -> (dep) B`` things.
> 
>> On a very quick look, it seems that, if we replace:
>>
>> 	(\S+\s->\S*\s\w+)
>>
>> by:
>> 	``\1``
>>
>>
>> On an editor that would allow to manually replace the regex (like kate),
>> most of those can be get.
>>
>> See patch enclosed.
> 
> Some time ago I considered the problem of converting this file to ReST 
> format.  But I gave up on the idea, because the necessary changes were 
> so widespread and the resulting text file would not be easily readable.
> 
> Replacing things of the form "A ->dep B" just scratches the surface.  
> That document teems with variable names, formulas, code extracts, and
> other things which would all need to be rendered in a different font
> style.  The density of the markup required to do this would be
> phenomenally high.
> 
> In my opinion it simply was not worthwhile.

+1 on keeping this and the other .txt files of LKMM intact.

        Thanks, Akira

> 
> Alan Stern
> 


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

* Re: [PATCH v2 01/26] docs: power: add it to to the main documentation index
  2019-07-26 12:51 ` [PATCH v2 01/26] docs: power: add it to to the main documentation index Mauro Carvalho Chehab
@ 2019-07-31 19:03   ` Jonathan Corbet
  2019-07-31 19:16     ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 75+ messages in thread
From: Jonathan Corbet @ 2019-07-31 19:03 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Rafael J. Wysocki, Len Brown, Pavel Machek, linux-doc, linux-pm

On Fri, 26 Jul 2019 09:51:11 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> The power docs are orphaned at the documentation body.
> 
> While it could likely be moved to be inside some guide, I'm opting to just
> adding it to the main index.rst, removing the :orphan: and adding the SPDX
> header.
> 
> The reason is similar to what it was done for other driver-specific
> subsystems: the docs there contain a mix of Kernelspace, uAPI and
> admin-guide. So, better to keep them on its own directory,
> while the docs there are not properly classified.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

So this one went upstream with the PDF fixes pull, right?  I'm a little
surprised to see it here now.

Thanks,

jon

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

* Re: [PATCH v2 01/26] docs: power: add it to to the main documentation index
  2019-07-31 19:03   ` Jonathan Corbet
@ 2019-07-31 19:16     ` Mauro Carvalho Chehab
  2019-07-31 19:34       ` Jonathan Corbet
  0 siblings, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-31 19:16 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: Rafael J. Wysocki, Len Brown, Pavel Machek, linux-doc, linux-pm

Em Wed, 31 Jul 2019 13:03:38 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Fri, 26 Jul 2019 09:51:11 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> 
> > The power docs are orphaned at the documentation body.
> > 
> > While it could likely be moved to be inside some guide, I'm opting to just
> > adding it to the main index.rst, removing the :orphan: and adding the SPDX
> > header.
> > 
> > The reason is similar to what it was done for other driver-specific
> > subsystems: the docs there contain a mix of Kernelspace, uAPI and
> > admin-guide. So, better to keep them on its own directory,
> > while the docs there are not properly classified.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>  
> 
> So this one went upstream with the PDF fixes pull, right?  I'm a little
> surprised to see it here now.

Yeah, this specific patch went together with the PDF fixes. 

The remaining ones in this series aren't there yet.

From this series, besides this patch, you can also exclude patch
25/26, as it seems that Paul will merge via RCU tree.

The remaining ones apply cleanly on the top of docs-next
(I tested applying them on the top of your tree yesterday).

Thanks,
Mauro

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

* Re: [PATCH v2 01/26] docs: power: add it to to the main documentation index
  2019-07-31 19:16     ` Mauro Carvalho Chehab
@ 2019-07-31 19:34       ` Jonathan Corbet
  2019-07-31 19:58         ` Mauro Carvalho Chehab
  0 siblings, 1 reply; 75+ messages in thread
From: Jonathan Corbet @ 2019-07-31 19:34 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Rafael J. Wysocki, Len Brown, Pavel Machek, linux-doc, linux-pm

On Wed, 31 Jul 2019 16:16:06 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> The remaining ones in this series aren't there yet.
> 
> From this series, besides this patch, you can also exclude patch
> 25/26, as it seems that Paul will merge via RCU tree.
> 
> The remaining ones apply cleanly on the top of docs-next
> (I tested applying them on the top of your tree yesterday).

Hmm...really?

- [PATCH v2 03/26] docs: powerpc: convert docs to ReST and rename to *.rst

	Seems to already be applied.

- [PATCH v2 07/26] docs: w1: convert to ReST and add to the kAPI group of
  docs

	Gives me the dreaded "could not build fake ancestor" error, I
	don't really understand why.

- [PATCH v2 08/26] spi: docs: convert to ReST and add it to the kABI
  bookset
- [PATCH v2 16/26] docs: fs: cifs: convert to ReST and add to admin-guide
  book

	Likewise

I've applied the others, so we're getting closer...

jon

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

* Re: [PATCH v2 01/26] docs: power: add it to to the main documentation index
  2019-07-31 19:34       ` Jonathan Corbet
@ 2019-07-31 19:58         ` Mauro Carvalho Chehab
  2019-07-31 20:02           ` Jonathan Corbet
  0 siblings, 1 reply; 75+ messages in thread
From: Mauro Carvalho Chehab @ 2019-07-31 19:58 UTC (permalink / raw)
  To: Jonathan Corbet
  Cc: Rafael J. Wysocki, Len Brown, Pavel Machek, linux-doc, linux-pm

Em Wed, 31 Jul 2019 13:34:43 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Wed, 31 Jul 2019 16:16:06 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> 
> > The remaining ones in this series aren't there yet.
> > 
> > From this series, besides this patch, you can also exclude patch
> > 25/26, as it seems that Paul will merge via RCU tree.
> > 
> > The remaining ones apply cleanly on the top of docs-next
> > (I tested applying them on the top of your tree yesterday).  
> 
> Hmm...really?
> 
> - [PATCH v2 03/26] docs: powerpc: convert docs to ReST and rename to *.rst
> 
> 	Seems to already be applied.
> 
> - [PATCH v2 07/26] docs: w1: convert to ReST and add to the kAPI group of
>   docs
> 
> 	Gives me the dreaded "could not build fake ancestor" error, I
> 	don't really understand why.

That's new! What Sphinx version are you using?

Btw, on my build here (Sphinx 2.0.1 on Python3), I can't see this error.

> 
> - [PATCH v2 08/26] spi: docs: convert to ReST and add it to the kABI
>   bookset
> - [PATCH v2 16/26] docs: fs: cifs: convert to ReST and add to admin-guide
>   book
> 
> 	Likewise
> 
> I've applied the others, so we're getting closer...

Weird...

I did a rebase here on the top of your current docs/docs-next... they
apply fine. Had to do just a small trivial fix on one of the patches.

Anyway, thanks for merging those... I have now just 5 patches.

Btw, it seems that there are now 5 new broken links:

MAINTAINERS: Documentation/filesystems/jfs.txt
MAINTAINERS: Documentation/filesystems/ufs.txt
drivers/hwtracing/coresight/Kconfig: Documentation/trace/coresight-cpu-debug.txt
fs/jfs/Kconfig: file:Documentation/filesystems/jfs.txt
fs/ufs/Kconfig: file:Documentation/filesystems/ufs.txt

4 of them related to the two fs patches applied today.

I'll send you a fix together with the remaining patches in a few.

Thanks,
Mauro

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

* Re: [PATCH v2 01/26] docs: power: add it to to the main documentation index
  2019-07-31 19:58         ` Mauro Carvalho Chehab
@ 2019-07-31 20:02           ` Jonathan Corbet
  0 siblings, 0 replies; 75+ messages in thread
From: Jonathan Corbet @ 2019-07-31 20:02 UTC (permalink / raw)
  To: Mauro Carvalho Chehab
  Cc: Rafael J. Wysocki, Len Brown, Pavel Machek, linux-doc, linux-pm

On Wed, 31 Jul 2019 16:58:59 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> > - [PATCH v2 07/26] docs: w1: convert to ReST and add to the kAPI group of
> >   docs
> > 
> > 	Gives me the dreaded "could not build fake ancestor" error, I
> > 	don't really understand why.  
> 
> That's new! What Sphinx version are you using?

That's a "git am" error, sphinx doesn't enter into the picture...

jon

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

* Re: [PATCH] tools: memory-model: add it to the Documentation body
  2019-07-31 15:19                 ` Akira Yokosawa
@ 2019-07-31 20:25                   ` Paul E. McKenney
  2019-08-30 11:32                     ` Peter Zijlstra
  0 siblings, 1 reply; 75+ messages in thread
From: Paul E. McKenney @ 2019-07-31 20:25 UTC (permalink / raw)
  To: Akira Yokosawa
  Cc: Alan Stern, Mauro Carvalho Chehab, Joel Fernandes,
	Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel,
	Jonathan Corbet, Andrea Parri, Will Deacon, Peter Zijlstra,
	Boqun Feng, Nicholas Piggin, David Howells, Jade Alglave,
	Luc Maranget, Daniel Lustig, Ingo Molnar, Jason Gunthorpe,
	SeongJae Park, linux-arch

On Thu, Aug 01, 2019 at 12:19:25AM +0900, Akira Yokosawa wrote:
> On Wed, 31 Jul 2019 09:52:05 -0400, Alan Stern wrote:
> > On Tue, 30 Jul 2019, Mauro Carvalho Chehab wrote:
> > 
> >> Em Tue, 30 Jul 2019 18:17:01 -0400
> >> Joel Fernandes <joel@joelfernandes.org> escreveu:
> > 
> >>>>> (4) I would argue that every occurence of
> >>>>> A ->(some dependency) B should be replaced with fixed size font in the HTML
> >>>>> results.  
> >>>>
> >>>> Just place those with ``A -> (some dependency)``. This will make them use
> >>>> a fixed size font.  
> >>>
> >>> Ok, understood all these. I guess my point was all of these will need to be
> >>> done to make this document useful from a ReST conversion standpoint. Until
> >>> then it is probably just better off being plain text - since there are so
> >>> many of those ``A -> (dep) B`` things.
> > 
> >> On a very quick look, it seems that, if we replace:
> >>
> >> 	(\S+\s->\S*\s\w+)
> >>
> >> by:
> >> 	``\1``
> >>
> >>
> >> On an editor that would allow to manually replace the regex (like kate),
> >> most of those can be get.
> >>
> >> See patch enclosed.
> > 
> > Some time ago I considered the problem of converting this file to ReST 
> > format.  But I gave up on the idea, because the necessary changes were 
> > so widespread and the resulting text file would not be easily readable.
> > 
> > Replacing things of the form "A ->dep B" just scratches the surface.  
> > That document teems with variable names, formulas, code extracts, and
> > other things which would all need to be rendered in a different font
> > style.  The density of the markup required to do this would be
> > phenomenally high.
> > 
> > In my opinion it simply was not worthwhile.
> 
> +1 on keeping this and the other .txt files of LKMM intact.

Looks like a pretty clear consensus thus far.  Any objections to keeping
these .txt for the time being?

							Thanx, Paul


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

* Re: [PATCH] tools: memory-model: add it to the Documentation body
  2019-07-31 20:25                   ` Paul E. McKenney
@ 2019-08-30 11:32                     ` Peter Zijlstra
  2019-09-01 13:35                       ` Paul E. McKenney
  0 siblings, 1 reply; 75+ messages in thread
From: Peter Zijlstra @ 2019-08-30 11:32 UTC (permalink / raw)
  To: Paul E. McKenney
  Cc: Akira Yokosawa, Alan Stern, Mauro Carvalho Chehab,
	Joel Fernandes, Linux Doc Mailing List, Mauro Carvalho Chehab,
	linux-kernel, Jonathan Corbet, Andrea Parri, Will Deacon,
	Boqun Feng, Nicholas Piggin, David Howells, Jade Alglave,
	Luc Maranget, Daniel Lustig, Ingo Molnar, Jason Gunthorpe,
	SeongJae Park, linux-arch

On Wed, Jul 31, 2019 at 01:25:17PM -0700, Paul E. McKenney wrote:
> Looks like a pretty clear consensus thus far.  Any objections to keeping
> these .txt for the time being?

Obviously I'm a huge proponent of abandoning RST and an advocate for
normal .txt files ;-)

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

* Re: [PATCH] tools: memory-model: add it to the Documentation body
  2019-08-30 11:32                     ` Peter Zijlstra
@ 2019-09-01 13:35                       ` Paul E. McKenney
  0 siblings, 0 replies; 75+ messages in thread
From: Paul E. McKenney @ 2019-09-01 13:35 UTC (permalink / raw)
  To: Peter Zijlstra
  Cc: Akira Yokosawa, Alan Stern, Mauro Carvalho Chehab,
	Joel Fernandes, Linux Doc Mailing List, Mauro Carvalho Chehab,
	linux-kernel, Jonathan Corbet, Andrea Parri, Will Deacon,
	Boqun Feng, Nicholas Piggin, David Howells, Jade Alglave,
	Luc Maranget, Daniel Lustig, Ingo Molnar, Jason Gunthorpe,
	SeongJae Park, linux-arch

On Fri, Aug 30, 2019 at 01:32:16PM +0200, Peter Zijlstra wrote:
> On Wed, Jul 31, 2019 at 01:25:17PM -0700, Paul E. McKenney wrote:
> > Looks like a pretty clear consensus thus far.  Any objections to keeping
> > these .txt for the time being?
> 
> Obviously I'm a huge proponent of abandoning RST and an advocate for
> normal .txt files ;-)

Oh?  I hadn't noticed.  ;-)

							Thanx, Paul

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

end of thread, other threads:[~2019-09-01 13:36 UTC | newest]

Thread overview: 75+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-07-26 12:51 [PATCH v2 00/26] ReST conversion of text files without .txt extension Mauro Carvalho Chehab
2019-07-26 12:51 ` [OpenRISC] " Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 01/26] docs: power: add it to to the main documentation index Mauro Carvalho Chehab
2019-07-31 19:03   ` Jonathan Corbet
2019-07-31 19:16     ` Mauro Carvalho Chehab
2019-07-31 19:34       ` Jonathan Corbet
2019-07-31 19:58         ` Mauro Carvalho Chehab
2019-07-31 20:02           ` Jonathan Corbet
2019-07-26 12:51 ` [PATCH v2 02/26] docs: thermal: add it to the driver API Mauro Carvalho Chehab
2019-07-26 12:51   ` Mauro Carvalho Chehab
2019-07-26 12:51   ` Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 03/26] docs: powerpc: convert docs to ReST and rename to *.rst Mauro Carvalho Chehab
2019-07-26 12:51   ` Mauro Carvalho Chehab
2019-07-26 12:51   ` Mauro Carvalho Chehab
2019-07-26 12:51   ` Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 04/26] docs: ubifs-authentication.md: convert to ReST Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 05/26] docs: writing-schema.md: convert from markdown " Mauro Carvalho Chehab
2019-07-26 12:51   ` Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 06/26] docs: i2c: convert to ReST and add to driver-api bookset Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 07/26] docs: w1: convert to ReST and add to the kAPI group of docs Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 08/26] spi: docs: convert to ReST and add it to the kABI bookset Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 09/26] docs: ipmb: place it at driver-api and convert to ReST Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 10/26] docs: packing: move it to core-api book and adjust markups Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 11/26] docs: admin-guide: add auxdisplay files to it after conversion to ReST Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 12/26] docs: README.buddha: convert to ReST and add to m68k book Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 13/26] docs: parisc: convert to ReST and add to documentation body Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 14/26] docs: openrisc: " Mauro Carvalho Chehab
2019-07-26 12:51   ` [OpenRISC] " Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 15/26] docs: isdn: convert to ReST and add to kAPI bookset Mauro Carvalho Chehab
2019-07-26 12:51 ` Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 16/26] docs: fs: cifs: convert to ReST and add to admin-guide book Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 17/26] docs: fs: convert docs without extension to ReST Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 18/26] docs: fs: convert porting " Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 19/26] docs: index.rst: don't use genindex for pdf output Mauro Carvalho Chehab
2019-07-26 12:51   ` Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 20/26] docs: wimax: convert to ReST and add to admin-guide Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 21/26] docs: mips: add to the documentation body as ReST Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 22/26] docs: hwmon: pxe1610: convert to ReST format and add to the index Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 23/26] docs: nios2: add it to the main Documentation body Mauro Carvalho Chehab
2019-07-26 12:51 ` [PATCH v2 24/26] docs: net: convert two README files to ReST format Mauro Carvalho Chehab
2019-07-26 13:05 ` [PATCH v2 00/26] ReST conversion of text files without .txt extension Mauro Carvalho Chehab
2019-07-26 13:05   ` [OpenRISC] " Mauro Carvalho Chehab
2019-07-26 13:05   ` Mauro Carvalho Chehab
2019-07-26 13:05   ` Mauro Carvalho Chehab
     [not found] ` <8444797277eea7be474f40625bb190775a9cee33.1564145354.git.mchehab+samsung@kernel.org>
     [not found]   ` <20190726162002.GA146401@google.com>
     [not found]     ` <20190726140028.38abb5fa@coco.lan>
2019-07-26 17:55       ` [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST Joel Fernandes
2019-07-26 18:45         ` Mauro Carvalho Chehab
2019-07-26 18:02   ` Joel Fernandes
2019-07-26 19:01     ` [PATCH] tools: memory-model: add it to the Documentation body Mauro Carvalho Chehab
2019-07-27 14:14       ` Joel Fernandes
2019-07-27 15:37         ` Mauro Carvalho Chehab
2019-07-30 22:17           ` Joel Fernandes
2019-07-30 22:57             ` Mauro Carvalho Chehab
2019-07-31 13:52               ` Alan Stern
2019-07-31 13:52                 ` Alan Stern
2019-07-31 15:19                 ` Akira Yokosawa
2019-07-31 20:25                   ` Paul E. McKenney
2019-08-30 11:32                     ` Peter Zijlstra
2019-09-01 13:35                       ` Paul E. McKenney
2019-07-26 19:14     ` [PATCH v2 25/26] docs: rcu: convert some articles from html to ReST Mauro Carvalho Chehab
2019-07-30 22:06       ` Joel Fernandes
2019-07-30 21:22   ` Paul E. McKenney
2019-07-30 21:50     ` Joel Fernandes
2019-07-30 22:00       ` Mauro Carvalho Chehab
2019-07-30 22:21         ` Joel Fernandes
2019-07-30 23:00           ` Mauro Carvalho Chehab
2019-07-30 23:15             ` Joel Fernandes
2019-07-30 21:50     ` Mauro Carvalho Chehab
2019-07-30 23:37       ` Paul E. McKenney
2019-07-31  0:04         ` Paul E. McKenney
2019-07-31  0:47           ` Mauro Carvalho Chehab
2019-07-31  1:06             ` Paul E. McKenney
2019-07-31  1:33               ` Mauro Carvalho Chehab

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.