[PATCH v2 00/39] ABI: add it to the documentation build system

[PATCH v2 00/39] ABI: add it to the documentation build system

[Mauro Carvalho Chehab]

Hi Greg,

That's the second version of the ABI documentation patches,
adding support for having the Linux ABI documentted inside
the Linux admin manual.

When compared with the version I sent years ago, this
version has:

- a logic to detect duplicated ABI symbols;
- it auto-generate cross-reference markups for ABI symbols,
  ABI files and .rst files;
- Other files from 5.10-rc1 required adjustments in order
  to be accepted by the script in rst-source mode;
- Some bug fixes.

v2:
- fixed pedantic warnings with "search command;
- fixed the duplicated warning output in order to report properly the files;
- added a few more patches addressing ABI duplication.

Mauro Carvalho Chehab (39):
  scripts: get_abi.pl: change script to allow parsing in ReST mode
  scripts: get_abi.pl: fix parsing on ReST mode
  scripts: get_abi.pl: Allow optionally record from where a line came
    from
  scripts: get_abi.pl: improve its parser to better catch up indentation
  scripts: get_abi.pl: cleanup ABI cross-reference logic
  scripts: get_abi.pl: detect duplicated ABI definitions
  scripts: get_abi.pl: output users in ReST format
  scripts: get_abi.pl: prevent duplicated file names
  scripts: get_abi.pl: use bold font for ABI definitions
  scripts: get_abi.pl: auto-generate cross references
  docs: kernellog.py: add support for info()
  docs: kernel_abi.py: add a script to parse ABI documentation
  docs: kernel_abi.py: fix UTF-8 support
  docs: kernel_abi.py: make it compatible with Sphinx 1.7+
  docs: kernel_abi.py: use --enable-lineno for get_abi.pl
  docs: kernel_abi.py: Handle with a lazy Sphinx parser
  docs: add ABI documentation to the admin-guide book
  docs: ABI: README: specify that files should be ReST compatible
  docs: ABI: stable: make files ReST compatible
  docs: ABI: testing: make the files compatible with ReST output
  docs: ABI: sysfs-uevent: make it compatible with ReST output
  docs: ABI: make it parse ABI/stable as ReST-compatible files
  docs: ABI: create a 2-depth index for ABI
  docs: ABI: don't escape ReST-incompatible chars from obsolete and
    removed
  docs: abi-testing.rst: enable --rst-sources when building docs
  docs: Kconfig/Makefile: add a check for broken ABI files
  docs: ABI: convert testing/configfs-acpi to ReST
  docs: ABI: fix syntax to be parsed using ReST notation
  docs: ABI: vdso: use the right format for ABI
  docs: ABI: sysfs-bus-nvdimm: use the right format for ABI
  docs: ABI: cleanup several ABI documents
  docs: ABI: change read/write attributes
  docs: ABI: stable: remove a duplicated documentation
  docs: ABI: unify /sys/class/leds/<led>/brightness documentation
  docs: ABI: sysfs-class-power: unify duplicated properties
  docs: ABI: sysfs-c2port: remove a duplicated entry
  docs: ABI: sysfs-class-backlight: unify ABI documentation
  docs: ABI: sysfs-class-led-trigger-pattern: remove hw_pattern
    duplication
  scripts: get_abi.pl: assume ReST format by default

 Documentation/ABI/README                      |  10 +-
 Documentation/ABI/obsolete/sysfs-class-dax    |   8 +-
 .../ABI/obsolete/sysfs-driver-hid-roccat-pyra |   3 +
 Documentation/ABI/obsolete/sysfs-gpio         |   2 +
 Documentation/ABI/removed/devfs               |   1 +
 Documentation/ABI/removed/raw1394             |   1 +
 Documentation/ABI/removed/sysfs-class-rfkill  |   2 +-
 Documentation/ABI/removed/video1394           |   1 +
 Documentation/ABI/stable/firewire-cdev        |  67 ++-
 Documentation/ABI/stable/sysfs-acpi-pmprofile |  26 +-
 Documentation/ABI/stable/sysfs-bus-firewire   |   3 +
 Documentation/ABI/stable/sysfs-bus-nvmem      |  19 +-
 Documentation/ABI/stable/sysfs-bus-usb        |   6 +-
 Documentation/ABI/stable/sysfs-bus-vmbus      |   7 -
 Documentation/ABI/stable/sysfs-bus-w1         |   1 +
 .../ABI/stable/sysfs-class-backlight          |   1 +
 .../ABI/stable/sysfs-class-infiniband         |  93 +++-
 Documentation/ABI/stable/sysfs-class-rfkill   |  13 +-
 Documentation/ABI/stable/sysfs-class-tpm      |  94 ++--
 Documentation/ABI/stable/sysfs-devices        |   5 +-
 .../ABI/stable/sysfs-driver-firmware-zynqmp   |  62 ++-
 Documentation/ABI/stable/sysfs-driver-ib_srp  |   1 +
 Documentation/ABI/stable/sysfs-driver-speakup |   4 +
 .../ABI/stable/sysfs-firmware-efi-vars        |   4 +
 .../ABI/stable/sysfs-firmware-opal-dump       |   5 +
 .../ABI/stable/sysfs-firmware-opal-elog       |   2 +
 Documentation/ABI/stable/sysfs-hypervisor-xen |   3 +
 Documentation/ABI/stable/vdso                 |  11 +-
 Documentation/ABI/testing/configfs-acpi       |  34 +-
 Documentation/ABI/testing/configfs-most       | 135 +++--
 .../ABI/testing/configfs-spear-pcie-gadget    |  36 +-
 Documentation/ABI/testing/configfs-usb-gadget |  83 +--
 .../ABI/testing/configfs-usb-gadget-ecm       |  12 +-
 .../ABI/testing/configfs-usb-gadget-eem       |  10 +-
 .../ABI/testing/configfs-usb-gadget-hid       |  10 +-
 .../ABI/testing/configfs-usb-gadget-loopback  |   6 +-
 .../testing/configfs-usb-gadget-mass-storage  |  18 +-
 .../ABI/testing/configfs-usb-gadget-midi      |  14 +-
 .../ABI/testing/configfs-usb-gadget-printer   |   6 +-
 .../ABI/testing/configfs-usb-gadget-rndis     |  16 +-
 .../testing/configfs-usb-gadget-sourcesink    |  18 +-
 .../ABI/testing/configfs-usb-gadget-subset    |  10 +-
 .../ABI/testing/configfs-usb-gadget-uac1      |  18 +-
 .../ABI/testing/configfs-usb-gadget-uac2      |  14 +-
 .../ABI/testing/configfs-usb-gadget-uvc       | 220 ++++----
 .../ABI/testing/debugfs-cec-error-inj         |   2 +-
 .../ABI/testing/debugfs-driver-habanalabs     |  12 +-
 Documentation/ABI/testing/debugfs-ec          |  11 +-
 Documentation/ABI/testing/debugfs-moxtet      |  30 +-
 .../ABI/testing/debugfs-pfo-nx-crypto         |  28 +-
 Documentation/ABI/testing/debugfs-pktcdvd     |  13 +-
 .../ABI/testing/debugfs-turris-mox-rwtm       |  15 +-
 Documentation/ABI/testing/debugfs-wilco-ec    |  21 +-
 Documentation/ABI/testing/dell-smbios-wmi     |  32 +-
 Documentation/ABI/testing/dev-kmsg            |  27 +-
 Documentation/ABI/testing/evm                 |  17 +-
 Documentation/ABI/testing/gpio-cdev           |  13 +-
 Documentation/ABI/testing/ima_policy          |  30 +-
 Documentation/ABI/testing/procfs-diskstats    |  46 +-
 Documentation/ABI/testing/procfs-smaps_rollup |  48 +-
 Documentation/ABI/testing/pstore              |  19 +-
 Documentation/ABI/testing/sysfs-block         |  38 +-
 Documentation/ABI/testing/sysfs-block-device  |   2 +
 Documentation/ABI/testing/sysfs-block-rnbd    |   4 +-
 Documentation/ABI/testing/sysfs-bus-acpi      |  19 +-
 .../testing/sysfs-bus-coresight-devices-cti   |  60 +-
 .../testing/sysfs-bus-coresight-devices-etb10 |  21 +-
 .../testing/sysfs-bus-coresight-devices-etm3x |  10 +-
 .../testing/sysfs-bus-coresight-devices-etm4x |  76 +--
 .../testing/sysfs-bus-coresight-devices-stm   |   2 +-
 .../testing/sysfs-bus-coresight-devices-tmc   |  20 +-
 Documentation/ABI/testing/sysfs-bus-css       |   3 +
 Documentation/ABI/testing/sysfs-bus-dfl       |   2 +
 .../sysfs-bus-event_source-devices-dfl_fme    |  14 +-
 .../sysfs-bus-event_source-devices-format     |   3 +-
 .../sysfs-bus-event_source-devices-hv_24x7    |   6 +-
 .../sysfs-bus-event_source-devices-hv_gpci    |   7 +-
 Documentation/ABI/testing/sysfs-bus-fcoe      |  68 ++-
 Documentation/ABI/testing/sysfs-bus-fsl-mc    |  12 +-
 .../ABI/testing/sysfs-bus-i2c-devices-fsa9480 |  26 +-
 .../ABI/testing/sysfs-bus-i2c-devices-pca954x |  27 +-
 Documentation/ABI/testing/sysfs-bus-i3c       |   2 +
 Documentation/ABI/testing/sysfs-bus-iio       |  30 +-
 .../sysfs-bus-iio-adc-envelope-detector       |   5 +-
 .../ABI/testing/sysfs-bus-iio-adc-hi8435      |   5 +
 .../ABI/testing/sysfs-bus-iio-adc-stm32       |   3 +
 .../ABI/testing/sysfs-bus-iio-cros-ec         |   2 +-
 .../ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 |   8 +-
 .../ABI/testing/sysfs-bus-iio-distance-srf08  |   7 +-
 .../testing/sysfs-bus-iio-frequency-ad9523    |   2 +
 .../testing/sysfs-bus-iio-frequency-adf4371   |  10 +-
 .../ABI/testing/sysfs-bus-iio-health-afe440x  |  12 +-
 .../ABI/testing/sysfs-bus-iio-light-isl29018  |   6 +-
 .../ABI/testing/sysfs-bus-iio-lptimer-stm32   |  29 +-
 .../sysfs-bus-iio-magnetometer-hmc5843        |  19 +-
 .../sysfs-bus-iio-temperature-max31856        |  19 +-
 .../ABI/testing/sysfs-bus-iio-timer-stm32     | 137 +++--
 .../testing/sysfs-bus-intel_th-devices-gth    |  11 +-
 .../testing/sysfs-bus-intel_th-devices-msc    |   4 +
 Documentation/ABI/testing/sysfs-bus-most      |   6 +-
 .../ABI/testing/sysfs-bus-moxtet-devices      |   6 +-
 Documentation/ABI/testing/sysfs-bus-nfit      |   2 +-
 Documentation/ABI/testing/sysfs-bus-nvdimm    |   6 +
 Documentation/ABI/testing/sysfs-bus-papr-pmem |  23 +-
 Documentation/ABI/testing/sysfs-bus-pci       |  22 +-
 .../testing/sysfs-bus-pci-devices-aer_stats   | 119 ++--
 .../ABI/testing/sysfs-bus-pci-devices-catpt   |   1 +
 .../testing/sysfs-bus-pci-drivers-ehci_hcd    |   4 +-
 Documentation/ABI/testing/sysfs-bus-rapidio   |  23 +-
 Documentation/ABI/testing/sysfs-bus-rbd       |  37 +-
 Documentation/ABI/testing/sysfs-bus-siox      |   3 +
 .../ABI/testing/sysfs-bus-thunderbolt         |  58 +-
 Documentation/ABI/testing/sysfs-bus-usb       |  32 +-
 .../testing/sysfs-bus-usb-devices-usbsevseg   |   7 +-
 Documentation/ABI/testing/sysfs-bus-vfio-mdev |  10 +-
 Documentation/ABI/testing/sysfs-c2port        |   7 -
 .../ABI/testing/sysfs-class-backlight         |  60 ++
 .../ABI/testing/sysfs-class-backlight-adp8860 |  21 +-
 .../sysfs-class-backlight-driver-adp8870      |  30 +-
 .../sysfs-class-backlight-driver-lm3533       |  26 +-
 Documentation/ABI/testing/sysfs-class-bdi     |   1 -
 .../ABI/testing/sysfs-class-chromeos          |  15 +-
 Documentation/ABI/testing/sysfs-class-cxl     |  23 +-
 Documentation/ABI/testing/sysfs-class-devfreq |   6 +-
 Documentation/ABI/testing/sysfs-class-devlink |  30 +-
 Documentation/ABI/testing/sysfs-class-extcon  |  34 +-
 .../ABI/testing/sysfs-class-fpga-manager      |   5 +-
 Documentation/ABI/testing/sysfs-class-gnss    |   2 +
 Documentation/ABI/testing/sysfs-class-led     |  28 +-
 .../testing/sysfs-class-led-driver-el15203000 | 130 -----
 .../ABI/testing/sysfs-class-led-driver-lm3533 |  44 +-
 .../ABI/testing/sysfs-class-led-driver-sc27xx |  22 -
 .../ABI/testing/sysfs-class-led-flash         |  27 +-
 .../ABI/testing/sysfs-class-led-multicolor    |  23 +-
 .../testing/sysfs-class-led-trigger-netdev    |   7 +
 .../testing/sysfs-class-led-trigger-pattern   |   4 +-
 .../testing/sysfs-class-led-trigger-usbport   |   1 +
 .../ABI/testing/sysfs-class-leds-gt683r       |   8 +-
 Documentation/ABI/testing/sysfs-class-mic     |  52 +-
 Documentation/ABI/testing/sysfs-class-net     |  61 +-
 .../ABI/testing/sysfs-class-net-cdc_ncm       |   6 +-
 .../ABI/testing/sysfs-class-net-phydev        |   2 +
 Documentation/ABI/testing/sysfs-class-ocxl    |  17 +-
 Documentation/ABI/testing/sysfs-class-pktcdvd |  36 +-
 Documentation/ABI/testing/sysfs-class-power   | 525 +++++++++---------
 .../ABI/testing/sysfs-class-power-mp2629      |   1 +
 .../ABI/testing/sysfs-class-power-twl4030     |  33 +-
 .../ABI/testing/sysfs-class-power-wilco       |  18 +-
 Documentation/ABI/testing/sysfs-class-rapidio |  46 +-
 Documentation/ABI/testing/sysfs-class-rc      |  30 +-
 .../ABI/testing/sysfs-class-regulator         |  36 +-
 .../ABI/testing/sysfs-class-remoteproc        |  14 +-
 .../ABI/testing/sysfs-class-rnbd-client       |  93 ++--
 ...ysfs-class-rtc-rtc0-device-rtc_calibration |   1 +
 .../ABI/testing/sysfs-class-rtrs-client       |  23 +-
 .../ABI/testing/sysfs-class-scsi_host         |   7 +-
 Documentation/ABI/testing/sysfs-class-typec   |  12 +-
 Documentation/ABI/testing/sysfs-class-uwb_rc  |  13 +-
 .../ABI/testing/sysfs-class-watchdog          |   7 +-
 Documentation/ABI/testing/sysfs-dev           |   7 +-
 .../ABI/testing/sysfs-devices-mapping         |  41 +-
 .../ABI/testing/sysfs-devices-memory          |  15 +-
 .../testing/sysfs-devices-platform-ACPI-TAD   |   4 +
 .../sysfs-devices-platform-_UDC_-gadget       |  10 +-
 .../ABI/testing/sysfs-devices-platform-docg3  |  10 +-
 .../ABI/testing/sysfs-devices-platform-ipmi   |  52 +-
 .../sysfs-devices-platform-sh_mobile_lcdc_fb  |   8 +-
 .../sysfs-devices-platform-stratix10-rsu      |  10 +
 .../ABI/testing/sysfs-devices-system-cpu      | 101 ++--
 .../ABI/testing/sysfs-devices-system-ibm-rtl  |   6 +-
 .../testing/sysfs-driver-bd9571mwv-regulator  |   4 +
 Documentation/ABI/testing/sysfs-driver-genwqe |  11 +-
 .../ABI/testing/sysfs-driver-hid-lenovo       |  10 +
 .../testing/sysfs-driver-hid-logitech-lg4ff   |  18 +-
 .../ABI/testing/sysfs-driver-hid-ntrig        |  13 +-
 .../ABI/testing/sysfs-driver-hid-roccat-kone  |  19 +
 .../ABI/testing/sysfs-driver-hid-wiimote      |  12 +-
 .../ABI/testing/sysfs-driver-input-exc3000    |   2 +
 .../ABI/testing/sysfs-driver-jz4780-efuse     |   6 +-
 .../ABI/testing/sysfs-driver-pciback          |   6 +-
 .../ABI/testing/sysfs-driver-samsung-laptop   |  13 +-
 .../ABI/testing/sysfs-driver-toshiba_acpi     |  26 +
 .../ABI/testing/sysfs-driver-toshiba_haps     |   2 +
 Documentation/ABI/testing/sysfs-driver-ufs    | 228 ++++++--
 .../ABI/testing/sysfs-driver-w1_ds28e17       |   3 +
 .../ABI/testing/sysfs-driver-w1_therm         |  75 ++-
 Documentation/ABI/testing/sysfs-driver-wacom  |   4 +-
 Documentation/ABI/testing/sysfs-firmware-acpi | 237 ++++----
 .../ABI/testing/sysfs-firmware-dmi-entries    |  50 +-
 .../ABI/testing/sysfs-firmware-efi-esrt       |  28 +-
 .../testing/sysfs-firmware-efi-runtime-map    |  14 +-
 Documentation/ABI/testing/sysfs-firmware-gsmi |   2 +-
 .../ABI/testing/sysfs-firmware-memmap         |  16 +-
 .../ABI/testing/sysfs-firmware-qemu_fw_cfg    |  20 +-
 Documentation/ABI/testing/sysfs-firmware-sfi  |   6 +-
 .../ABI/testing/sysfs-firmware-sgi_uv         |   6 +-
 .../testing/sysfs-firmware-turris-mox-rwtm    |  10 +-
 Documentation/ABI/testing/sysfs-fs-ext4       |   4 +-
 Documentation/ABI/testing/sysfs-fs-f2fs       |  48 +-
 .../ABI/testing/sysfs-hypervisor-xen          |  13 +-
 .../ABI/testing/sysfs-kernel-boot_params      |  23 +-
 .../ABI/testing/sysfs-kernel-mm-hugepages     |  12 +-
 Documentation/ABI/testing/sysfs-kernel-mm-ksm |   5 +-
 Documentation/ABI/testing/sysfs-kernel-slab   |   3 +
 Documentation/ABI/testing/sysfs-module        |  17 +-
 .../ABI/testing/sysfs-platform-asus-laptop    |  21 +-
 .../ABI/testing/sysfs-platform-asus-wmi       |   1 +
 Documentation/ABI/testing/sysfs-platform-at91 |  10 +-
 .../ABI/testing/sysfs-platform-dell-laptop    |  10 +-
 .../ABI/testing/sysfs-platform-dell-smbios    |   4 +-
 .../ABI/testing/sysfs-platform-dfl-fme        |  14 +-
 Documentation/ABI/testing/sysfs-platform-dptf |  11 +-
 .../ABI/testing/sysfs-platform-eeepc-laptop   |  14 +-
 .../testing/sysfs-platform-i2c-demux-pinctrl  |   4 +-
 .../ABI/testing/sysfs-platform-ideapad-laptop |   9 +-
 .../sysfs-platform-intel-wmi-sbl-fw-update    |   1 +
 .../sysfs-platform-intel-wmi-thunderbolt      |   1 +
 Documentation/ABI/testing/sysfs-platform-kim  |   1 +
 .../testing/sysfs-platform-mellanox-bootctl   |  50 +-
 .../testing/sysfs-platform-phy-rcar-gen3-usb2 |  10 +-
 .../ABI/testing/sysfs-platform-renesas_usb3   |  10 +-
 .../ABI/testing/sysfs-platform-sst-atom       |  13 +-
 .../ABI/testing/sysfs-platform-usbip-vudc     |  11 +-
 .../ABI/testing/sysfs-platform-wilco-ec       |   1 +
 Documentation/ABI/testing/sysfs-power         |  21 +-
 Documentation/ABI/testing/sysfs-profiling     |   2 +-
 Documentation/ABI/testing/sysfs-ptp           |   2 +-
 Documentation/ABI/testing/sysfs-uevent        |  28 +-
 Documentation/ABI/testing/sysfs-wusb_cbaf     |   3 +-
 Documentation/ABI/testing/usb-charger-uevent  |  82 +--
 Documentation/ABI/testing/usb-uevent          |  32 +-
 Documentation/Kconfig                         |  10 +
 Documentation/Makefile                        |   5 +
 Documentation/admin-guide/abi-obsolete.rst    |  11 +
 Documentation/admin-guide/abi-removed.rst     |   5 +
 Documentation/admin-guide/abi-stable.rst      |  14 +
 Documentation/admin-guide/abi-testing.rst     |  20 +
 Documentation/admin-guide/abi.rst             |  11 +
 Documentation/admin-guide/index.rst           |   2 +
 Documentation/conf.py                         |   3 +-
 Documentation/leds/index.rst                  |   1 +
 Documentation/leds/leds-el15203000.rst        | 140 +++++
 Documentation/leds/leds-sc27xx.rst            |  27 +
 Documentation/sphinx/kernel_abi.py            | 194 +++++++
 Documentation/sphinx/kernellog.py             |   6 +-
 lib/Kconfig.debug                             |   2 +
 scripts/get_abi.pl                            | 367 ++++++++----
 247 files changed, 4107 insertions(+), 2463 deletions(-)
 delete mode 100644 Documentation/ABI/testing/sysfs-class-led-driver-sc27xx
 create mode 100644 Documentation/admin-guide/abi-obsolete.rst
 create mode 100644 Documentation/admin-guide/abi-removed.rst
 create mode 100644 Documentation/admin-guide/abi-stable.rst
 create mode 100644 Documentation/admin-guide/abi-testing.rst
 create mode 100644 Documentation/admin-guide/abi.rst
 create mode 100644 Documentation/leds/leds-el15203000.rst
 create mode 100644 Documentation/leds/leds-sc27xx.rst
 create mode 100644 Documentation/sphinx/kernel_abi.py

-- 
2.26.2

[PATCH v2 01/39] scripts: get_abi.pl: change script to allow parsing in ReST mode

[Mauro Carvalho Chehab]

Right now, several ABI files won't parse as ReST, as they
contain severe violations to the spec, with makes the script
to crash.

So, the code has a sanity logic with escapes bad code and
cleans tags that can cause Sphinx to crash.

Add support for disabling this mode.

Right now, as enabling rst-mode causes crash, it is disabled
by default.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/get_abi.pl | 74 ++++++++++++++++++++++++++++++----------------
 1 file changed, 48 insertions(+), 26 deletions(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index c738cb795514..107672cdacb3 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -12,8 +12,14 @@ my $man;
 my $debug;
 my $prefix="Documentation/ABI";
 
+#
+# If true, assumes that the description is formatted with ReST
+#
+my $description_is_rst = 0;
+
 GetOptions(
 	"debug|d+" => \$debug,
+	"rst-source!" => \$description_is_rst,
 	"dir=s" => \$prefix,
 	'help|?' => \$help,
 	man => \$man
@@ -137,14 +143,15 @@ sub parse_abi {
 					next;
 				}
 				if ($tag eq "description") {
-					next if ($content =~ m/^\s*$/);
-					if ($content =~ m/^(\s*)(.*)/) {
-						my $new_content = $2;
-						$space = $new_tag . $sep . $1;
-						while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
-						$space =~ s/./ /g;
-						$data{$what}->{$tag} .= "$new_content\n";
+					# Preserve initial spaces for the first line
+					$content = ' ' x length($new_tag) . $sep . $content;
+					$content =~ s,^(\s*):,$1 ,;
+					if ($content =~ m/^(\s*)(.*)$/) {
+						$space = $1;
+						$content = $2;
 					}
+					while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
+					$data{$what}->{$tag} .= $content;
 				} else {
 					$data{$what}->{$tag} = $content;
 				}
@@ -160,11 +167,15 @@ sub parse_abi {
 
 		if ($tag eq "description") {
 			if (!$data{$what}->{description}) {
-				next if (m/^\s*\n/);
+				s/^($space)//;
 				if (m/^(\s*)(.*)/) {
-					$space = $1;
-					while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
-					$data{$what}->{$tag} .= "$2\n";
+					my $sp = $1;
+					while ($sp =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
+					my $content = "$sp$2";
+
+					$content =~ s/^($space)//;
+
+					$data{$what}->{$tag} .= "$content";
 				}
 			} else {
 				my $content = $_;
@@ -274,23 +285,27 @@ sub output_rest {
 		print "Defined on file :ref:`$file <$fileref>`\n\n" if ($type ne "File");
 
 		my $desc = $data{$what}->{description};
-		$desc =~ s/^\s+//;
-
-		# Remove title markups from the description, as they won't work
-		$desc =~ s/\n[\-\*\=\^\~]+\n/\n/g;
 
 		if (!($desc =~ /^\s*$/)) {
-			if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/  || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) {
-				# put everything inside a code block
-				$desc =~ s/\n/\n /g;
-
-				print "::\n\n";
-				print " $desc\n\n";
-			} else {
-				# Escape any special chars from description
-				$desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g;
-
+			if ($description_is_rst) {
 				print "$desc\n\n";
+			} else {
+				$desc =~ s/^\s+//;
+
+				# Remove title markups from the description, as they won't work
+				$desc =~ s/\n[\-\*\=\^\~]+\n/\n\n/g;
+
+				if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/  || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) {
+					# put everything inside a code block
+					$desc =~ s/\n/\n /g;
+
+					print "::\n\n";
+					print " $desc\n\n";
+				} else {
+					# Escape any special chars from description
+					$desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g;
+					print "$desc\n\n";
+				}
 			}
 		} else {
 			print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file});
@@ -382,7 +397,7 @@ abi_book.pl - parse the Linux ABI files and produce a ReST book.
 
 =head1 SYNOPSIS
 
-B<abi_book.pl> [--debug] [--man] [--help] [--dir=<dir>] <COMAND> [<ARGUMENT>]
+B<abi_book.pl> [--debug] [--man] [--help] --[(no-)rst-source] [--dir=<dir>] <COMAND> [<ARGUMENT>]
 
 Where <COMMAND> can be:
 
@@ -405,6 +420,13 @@ B<validate>              - validate the ABI contents
 Changes the location of the ABI search. By default, it uses
 the Documentation/ABI directory.
 
+=item B<--rst-source> and B<--no-rst-source>
+
+The input file may be using ReST syntax or not. Those two options allow
+selecting between a rst-compliant source ABI (--rst-source), or a
+plain text that may be violating ReST spec, so it requres some escaping
+logic (--no-rst-source).
+
 =item B<--debug>
 
 Put the script in verbose mode, useful for debugging. Can be called multiple
-- 
2.26.2

[PATCH v2 02/39] scripts: get_abi.pl: fix parsing on ReST mode

[Mauro Carvalho Chehab]

When the source ABI file is using ReST notation, the script
should handle whitespaces and lines with care, as otherwise
the file won't be properly recognized.

Address the bugs that are on such part of the script.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/get_abi.pl | 30 ++++++++++++++----------------
 1 file changed, 14 insertions(+), 16 deletions(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 107672cdacb3..0c403af86fd5 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -151,7 +151,8 @@ sub parse_abi {
 						$content = $2;
 					}
 					while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
-					$data{$what}->{$tag} .= $content;
+
+					$data{$what}->{$tag} .= "$content\n" if ($content);
 				} else {
 					$data{$what}->{$tag} = $content;
 				}
@@ -166,31 +167,28 @@ sub parse_abi {
 		}
 
 		if ($tag eq "description") {
+			my $content = $_;
+			while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
 			if (!$data{$what}->{description}) {
-				s/^($space)//;
-				if (m/^(\s*)(.*)/) {
-					my $sp = $1;
-					while ($sp =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
-					my $content = "$sp$2";
-
-					$content =~ s/^($space)//;
-
-					$data{$what}->{$tag} .= "$content";
+				# Preserve initial spaces for the first line
+				if ($content =~ m/^(\s*)(.*)$/) {
+					$space = $1;
+					$content = $2;
 				}
+
+				$data{$what}->{$tag} .= "$content\n" if ($content);
 			} else {
-				my $content = $_;
 				if (m/^\s*\n/) {
 					$data{$what}->{$tag} .= $content;
 					next;
 				}
 
-				while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
 				$space = "" if (!($content =~ s/^($space)//));
 
-				# Compress spaces with tabs
-				$content =~ s<^ {8}> <\t>;
-				$content =~ s<^ {1,7}\t> <\t>;
-				$content =~ s< {1,7}\t> <\t>;
+#				# Compress spaces with tabs
+#				$content =~ s<^ {8}> <\t>;
+#				$content =~ s<^ {1,7}\t> <\t>;
+#				$content =~ s< {1,7}\t> <\t>;
 				$data{$what}->{$tag} .= $content;
 			}
 			next;
-- 
2.26.2

[PATCH v2 03/39] scripts: get_abi.pl: Allow optionally record from where a line came from

[Mauro Carvalho Chehab]

The get_abi.pl reads a lot of files and can join them on a
single output file. Store where each "What:" output came from,
in order to be able to optionally display it.

This is useful for the Sphinx extension, with can now be
able to blame what ABI file has issues, and on what line
the What: description with problems begin.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/get_abi.pl | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 0c403af86fd5..6a4d387ebf3b 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -10,6 +10,7 @@ use Fcntl ':mode';
 my $help;
 my $man;
 my $debug;
+my $enable_lineno;
 my $prefix="Documentation/ABI";
 
 #
@@ -19,6 +20,7 @@ my $description_is_rst = 0;
 
 GetOptions(
 	"debug|d+" => \$debug,
+	"enable-lineno" => \$enable_lineno,
 	"rst-source!" => \$description_is_rst,
 	"dir=s" => \$prefix,
 	'help|?' => \$help,
@@ -67,6 +69,7 @@ sub parse_abi {
 	$data{$nametag}->{file} = $name;
 	$data{$nametag}->{filepath} = $file;
 	$data{$nametag}->{is_file} = 1;
+	$data{$nametag}->{line_no} = 1;
 
 	my $type = $file;
 	$type =~ s,.*/(.*)/.*,$1,;
@@ -126,6 +129,8 @@ sub parse_abi {
 			if ($tag ne "" && $new_tag) {
 				$tag = $new_tag;
 
+				$data{$what}->{line_no} = $ln;
+
 				if ($new_what) {
 					@{$data{$what}->{label}} = @labels if ($data{$nametag}->{what});
 					@labels = ();
@@ -221,6 +226,12 @@ sub output_rest {
 		my $file = $data{$what}->{file};
 		my $filepath = $data{$what}->{filepath};
 
+		if ($enable_lineno) {
+			printf "#define LINENO %s%s#%s\n\n",
+			       $prefix, $data{$what}->{file},
+			       $data{$what}->{line_no};
+		}
+
 		my $w = $what;
 		$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
 
@@ -369,6 +380,10 @@ sub search_symbols {
 	}
 }
 
+# Ensure that the prefix will always end with a slash
+# While this is not needed for find, it makes the patch nicer
+# with --enable-lineno
+$prefix =~ s,/?$,/,;
 
 #
 # Parses all ABI files located at $prefix dir
@@ -395,7 +410,8 @@ abi_book.pl - parse the Linux ABI files and produce a ReST book.
 
 =head1 SYNOPSIS
 
-B<abi_book.pl> [--debug] [--man] [--help] --[(no-)rst-source] [--dir=<dir>] <COMAND> [<ARGUMENT>]
+B<abi_book.pl> [--debug] [--enable-lineno] [--man] [--help]
+	       [--(no-)rst-source] [--dir=<dir>] <COMAND> [<ARGUMENT>]
 
 Where <COMMAND> can be:
 
@@ -425,6 +441,10 @@ selecting between a rst-compliant source ABI (--rst-source), or a
 plain text that may be violating ReST spec, so it requres some escaping
 logic (--no-rst-source).
 
+=item B<--enable-lineno>
+
+Enable output of #define LINENO lines.
+
 =item B<--debug>
 
 Put the script in verbose mode, useful for debugging. Can be called multiple
-- 
2.26.2

[PATCH v2 04/39] scripts: get_abi.pl: improve its parser to better catch up indentation

[Mauro Carvalho Chehab]

The original parser for indentation were relying on having
just one description for each "what". However, that's not
the case: there are a number of ABI symbols that got defined
multiple times.

Improve the parser for it to better handle descriptions
if entries are duplicated.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/get_abi.pl | 42 +++++++++++++++++++-----------------------
 1 file changed, 19 insertions(+), 23 deletions(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 6a4d387ebf3b..bd018eb3815b 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -147,17 +147,19 @@ sub parse_abi {
 					parse_error($file, $ln, "'What:' should come first:", $_);
 					next;
 				}
-				if ($tag eq "description") {
-					# Preserve initial spaces for the first line
+				if ($new_tag eq "description") {
+					$sep =~ s,:, ,;
 					$content = ' ' x length($new_tag) . $sep . $content;
-					$content =~ s,^(\s*):,$1 ,;
-					if ($content =~ m/^(\s*)(.*)$/) {
+					while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
+					if ($content =~ m/^(\s*)(\S.*)$/) {
+						# Preserve initial spaces for the first line
 						$space = $1;
-						$content = $2;
+						$content = "$2\n";
+						$data{$what}->{$tag} .= $content;
+					} else {
+						undef($space);
 					}
-					while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
 
-					$data{$what}->{$tag} .= "$content\n" if ($content);
 				} else {
 					$data{$what}->{$tag} = $content;
 				}
@@ -174,28 +176,22 @@ sub parse_abi {
 		if ($tag eq "description") {
 			my $content = $_;
 			while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
-			if (!$data{$what}->{description}) {
+			if (m/^\s*\n/) {
+				$data{$what}->{$tag} .= "\n";
+				next;
+			}
+
+			if (!defined($space)) {
 				# Preserve initial spaces for the first line
-				if ($content =~ m/^(\s*)(.*)$/) {
+				if ($content =~ m/^(\s*)(\S.*)$/) {
 					$space = $1;
-					$content = $2;
+					$content = "$2\n";
 				}
-
-				$data{$what}->{$tag} .= "$content\n" if ($content);
 			} else {
-				if (m/^\s*\n/) {
-					$data{$what}->{$tag} .= $content;
-					next;
-				}
-
 				$space = "" if (!($content =~ s/^($space)//));
-
-#				# Compress spaces with tabs
-#				$content =~ s<^ {8}> <\t>;
-#				$content =~ s<^ {1,7}\t> <\t>;
-#				$content =~ s< {1,7}\t> <\t>;
-				$data{$what}->{$tag} .= $content;
 			}
+			$data{$what}->{$tag} .= $content;
+
 			next;
 		}
 		if (m/^\s*(.*)/) {
-- 
2.26.2

[PATCH v2 05/39] scripts: get_abi.pl: cleanup ABI cross-reference logic

[Mauro Carvalho Chehab]

Right now, the cross-references are generated on a single
step, when doing ReST output.

While this is nice optimization, it prevents auto-creating
cross-references for ABI symbols.

So, split it into a separate logic.

While here, turn on Perl warnings, as it helps to debug
problems inside the script.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/get_abi.pl | 147 +++++++++++++++++++++++++--------------------
 1 file changed, 83 insertions(+), 64 deletions(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index bd018eb3815b..d134cc1692ee 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -2,15 +2,16 @@
 # SPDX-License-Identifier: GPL-2.0
 
 use strict;
+use warnings;
 use Pod::Usage;
 use Getopt::Long;
 use File::Find;
 use Fcntl ':mode';
 
-my $help;
-my $man;
-my $debug;
-my $enable_lineno;
+my $help = 0;
+my $man = 0;
+my $debug = 0;
+my $enable_lineno = 0;
 my $prefix="Documentation/ABI";
 
 #
@@ -40,6 +41,7 @@ pod2usage(2) if ($cmd eq "search" && !$arg);
 require Data::Dumper if ($debug);
 
 my %data;
+my %symbols;
 
 #
 # Displays an error message, printing file name and line
@@ -76,12 +78,12 @@ sub parse_abi {
 
 	my $what;
 	my $new_what;
-	my $tag;
+	my $tag = "";
 	my $ln;
 	my $xrefs;
 	my $space;
 	my @labels;
-	my $label;
+	my $label = "";
 
 	print STDERR "Opening $file\n" if ($debug > 1);
 	open IN, $file;
@@ -110,10 +112,18 @@ sub parse_abi {
 
 			if ($new_tag =~ m/what/) {
 				$space = "";
+				$content =~ s/[,.;]$//;
+
 				if ($tag =~ m/what/) {
 					$what .= ", " . $content;
 				} else {
-					parse_error($file, $ln, "What '$what' doesn't have a description", "") if ($what && !$data{$what}->{description});
+					if ($what) {
+						parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description});
+
+						foreach my $w(split /, /, $what) {
+							$symbols{$w} = $what;
+						};
+					}
 
 					$what = $content;
 					$label = $content;
@@ -122,7 +132,7 @@ sub parse_abi {
 				push @labels, [($content, $label)];
 				$tag = $new_tag;
 
-				push @{$data{$nametag}->{xrefs}}, [($content, $label)] if ($data{$nametag}->{what});
+				push @{$data{$nametag}->{symbols}}, $content if ($data{$nametag}->{what});
 				next;
 			}
 
@@ -132,7 +142,7 @@ sub parse_abi {
 				$data{$what}->{line_no} = $ln;
 
 				if ($new_what) {
-					@{$data{$what}->{label}} = @labels if ($data{$nametag}->{what});
+					@{$data{$what}->{label_list}} = @labels if ($data{$nametag}->{what});
 					@labels = ();
 					$label = "";
 					$new_what = 0;
@@ -203,36 +213,24 @@ sub parse_abi {
 		# Everything else is error
 		parse_error($file, $ln, "Unexpected line:", $_);
 	}
-	$data{$nametag}->{description} =~ s/^\n+//;
+	$data{$nametag}->{description} =~ s/^\n+// if ($data{$nametag}->{description});
+	if ($what) {
+		parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description});
+
+		foreach my $w(split /, /,$what) {
+			$symbols{$w} = $what;
+		};
+	}
 	close IN;
 }
 
-#
-# Outputs the book on ReST format
-#
+sub create_labels {
+	my %labels;
 
-my %labels;
+	foreach my $what (keys %data) {
+		next if ($data{$what}->{file} eq "File");
 
-sub output_rest {
-	foreach my $what (sort {
-				($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") ||
-				$a cmp $b
-			       } keys %data) {
-		my $type = $data{$what}->{type};
-		my $file = $data{$what}->{file};
-		my $filepath = $data{$what}->{filepath};
-
-		if ($enable_lineno) {
-			printf "#define LINENO %s%s#%s\n\n",
-			       $prefix, $data{$what}->{file},
-			       $data{$what}->{line_no};
-		}
-
-		my $w = $what;
-		$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
-
-
-		foreach my $p (@{$data{$what}->{label}}) {
+		foreach my $p (@{$data{$what}->{label_list}}) {
 			my ($content, $label) = @{$p};
 			$label = "abi_" . $label . " ";
 			$label =~ tr/A-Z/a-z/;
@@ -249,16 +247,39 @@ sub output_rest {
 			}
 			$labels{$label} = 1;
 
-			$data{$what}->{label} .= $label;
-
-			printf ".. _%s:\n\n", $label;
+			$data{$what}->{label} = $label;
 
 			# only one label is enough
 			last;
 		}
+	}
+}
 
+#
+# Outputs the book on ReST format
+#
 
-		$filepath =~ s,.*/(.*/.*),\1,;;
+sub output_rest {
+	create_labels();
+
+	foreach my $what (sort {
+				($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") ||
+				$a cmp $b
+			       } keys %data) {
+		my $type = $data{$what}->{type};
+		my $file = $data{$what}->{file};
+		my $filepath = $data{$what}->{filepath};
+
+		if ($enable_lineno) {
+			printf "#define LINENO %s%s#%s\n\n",
+			       $prefix, $data{$what}->{file},
+			       $data{$what}->{line_no};
+		}
+
+		my $w = $what;
+		$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
+
+		$filepath =~ s,.*/(.*/.*),$1,;;
 		$filepath =~ s,[/\-],_,g;;
 		my $fileref = "abi_file_".$filepath;
 
@@ -269,8 +290,9 @@ sub output_rest {
 			print ".. _$fileref:\n\n";
 			print "$w\n$bar\n\n";
 		} else {
-			my @names = split /\s*,\s*/,$w;
+			printf ".. _%s:\n\n", $data{$what}->{label};
 
+			my @names = split /, /,$w;
 			my $len = 0;
 
 			foreach my $name (@names) {
@@ -284,12 +306,13 @@ sub output_rest {
 				printf "| %s", $name . " " x ($len - length($name)) . " |\n";
 				print "+-" . "-" x $len . "-+\n";
 			}
-			print "\n";
+
+			print "\nDefined on file :ref:`$file <$fileref>`\n\n";
 		}
 
-		print "Defined on file :ref:`$file <$fileref>`\n\n" if ($type ne "File");
-
-		my $desc = $data{$what}->{description};
+		my $desc = "";
+		$desc = $data{$what}->{description} if (defined($data{$what}->{description}));
+		$desc =~ s/\s+$/\n/;
 
 		if (!($desc =~ /^\s*$/)) {
 			if ($description_is_rst) {
@@ -316,18 +339,11 @@ sub output_rest {
 			print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file});
 		}
 
-		if ($data{$what}->{xrefs}) {
+		if ($data{$what}->{symbols}) {
 			printf "Has the following ABI:\n\n";
 
-			foreach my $p(@{$data{$what}->{xrefs}}) {
-				my ($content, $label) = @{$p};
-				$label = "abi_" . $label . " ";
-				$label =~ tr/A-Z/a-z/;
-
-				# Convert special chars to "_"
-				$label =~s/([\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xff])/_/g;
-				$label =~ s,_+,_,g;
-				$label =~ s,_$,,;
+			foreach my $content(@{$data{$what}->{symbols}}) {
+				my $label = $data{$symbols{$content}}->{label};
 
 				# Escape special chars from content
 				$content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g;
@@ -355,17 +371,20 @@ sub search_symbols {
 
 		print "\n$what\n$bar\n\n";
 
-		my $kernelversion = $data{$what}->{kernelversion};
-		my $contact = $data{$what}->{contact};
-		my $users = $data{$what}->{users};
-		my $date = $data{$what}->{date};
-		my $desc = $data{$what}->{description};
-		$kernelversion =~ s/^\s+//;
-		$contact =~ s/^\s+//;
-		$users =~ s/^\s+//;
-		$users =~ s/\n//g;
-		$date =~ s/^\s+//;
-		$desc =~ s/^\s+//;
+		my $kernelversion = $data{$what}->{kernelversion} if (defined($data{$what}->{kernelversion}));
+		my $contact = $data{$what}->{contact} if (defined($data{$what}->{contact}));
+		my $users = $data{$what}->{users} if (defined($data{$what}->{users}));
+		my $date = $data{$what}->{date} if (defined($data{$what}->{date}));
+		my $desc = $data{$what}->{description} if (defined($data{$what}->{description}));
+
+		$kernelversion =~ s/^\s+// if ($kernelversion);
+		$contact =~ s/^\s+// if ($contact);
+		if ($users) {
+			$users =~ s/^\s+//;
+			$users =~ s/\n//g;
+		}
+		$date =~ s/^\s+// if ($date);
+		$desc =~ s/^\s+// if ($desc);
 
 		printf "Kernel version:\t\t%s\n", $kernelversion if ($kernelversion);
 		printf "Date:\t\t\t%s\n", $date if ($date);
-- 
2.26.2

[PATCH v2 06/39] scripts: get_abi.pl: detect duplicated ABI definitions

[Mauro Carvalho Chehab]

The ABI should define only once each What. The current script
logic assumes that.

However, that's not the case, currently: there are several
symbols with a generic definition, and per-driver ones.

Better handle such cases, by preserving the cross-references
with the files that define them, but also track such
cases, producing warnings, as they should be fixed.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/get_abi.pl | 85 +++++++++++++++++++++++++++++++---------------
 1 file changed, 58 insertions(+), 27 deletions(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index d134cc1692ee..1d1408fad130 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -114,6 +114,8 @@ sub parse_abi {
 				$space = "";
 				$content =~ s/[,.;]$//;
 
+				push @{$symbols{$content}->{file}}, " $file:" . ($ln - 1);
+
 				if ($tag =~ m/what/) {
 					$what .= ", " . $content;
 				} else {
@@ -121,7 +123,7 @@ sub parse_abi {
 						parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description});
 
 						foreach my $w(split /, /, $what) {
-							$symbols{$w} = $what;
+							$symbols{$w}->{xref} = $what;
 						};
 					}
 
@@ -139,8 +141,6 @@ sub parse_abi {
 			if ($tag ne "" && $new_tag) {
 				$tag = $new_tag;
 
-				$data{$what}->{line_no} = $ln;
-
 				if ($new_what) {
 					@{$data{$what}->{label_list}} = @labels if ($data{$nametag}->{what});
 					@labels = ();
@@ -148,9 +148,19 @@ sub parse_abi {
 					$new_what = 0;
 
 					$data{$what}->{type} = $type;
-					$data{$what}->{file} = $name;
-					$data{$what}->{filepath} = $file;
+					if (!defined($data{$what}->{file})) {
+						$data{$what}->{file} = $name;
+						$data{$what}->{filepath} = $file;
+					} else {
+						if ($name ne $data{$what}->{file}) {
+							$data{$what}->{file} .= " " . $name;
+							$data{$what}->{filepath} .= " " . $file;
+						}
+					}
 					print STDERR "\twhat: $what\n" if ($debug > 1);
+					$data{$what}->{line_no} = $ln;
+				} else {
+					$data{$what}->{line_no} = $ln if (!defined($data{$what}->{line_no}));
 				}
 
 				if (!$what) {
@@ -218,7 +228,7 @@ sub parse_abi {
 		parse_error($file, $ln, "What '$what' doesn't have a description", "") if (!$data{$what}->{description});
 
 		foreach my $w(split /, /,$what) {
-			$symbols{$w} = $what;
+			$symbols{$w}->{xref} = $what;
 		};
 	}
 	close IN;
@@ -267,29 +277,20 @@ sub output_rest {
 				$a cmp $b
 			       } keys %data) {
 		my $type = $data{$what}->{type};
-		my $file = $data{$what}->{file};
-		my $filepath = $data{$what}->{filepath};
+
+		my @file = split / /, $data{$what}->{file};
+		my @filepath = split / /, $data{$what}->{filepath};
 
 		if ($enable_lineno) {
 			printf "#define LINENO %s%s#%s\n\n",
-			       $prefix, $data{$what}->{file},
+			       $prefix, $file[0],
 			       $data{$what}->{line_no};
 		}
 
 		my $w = $what;
 		$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
 
-		$filepath =~ s,.*/(.*/.*),$1,;;
-		$filepath =~ s,[/\-],_,g;;
-		my $fileref = "abi_file_".$filepath;
-
-		if ($type eq "File") {
-			my $bar = $w;
-			$bar =~ s/./-/g;
-
-			print ".. _$fileref:\n\n";
-			print "$w\n$bar\n\n";
-		} else {
+		if ($type ne "File") {
 			printf ".. _%s:\n\n", $data{$what}->{label};
 
 			my @names = split /, /,$w;
@@ -307,7 +308,26 @@ sub output_rest {
 				print "+-" . "-" x $len . "-+\n";
 			}
 
-			print "\nDefined on file :ref:`$file <$fileref>`\n\n";
+			print "\n";
+		}
+
+		for (my $i = 0; $i < scalar(@filepath); $i++) {
+			my $path = $filepath[$i];
+			my $f = $file[$i];
+
+			$path =~ s,.*/(.*/.*),$1,;;
+			$path =~ s,[/\-],_,g;;
+			my $fileref = "abi_file_".$path;
+
+			if ($type eq "File") {
+				my $bar = $w;
+				$bar =~ s/./-/g;
+
+				print ".. _$fileref:\n\n";
+				print "$w\n$bar\n\n";
+			} else {
+				print "Defined on file :ref:`$f <$fileref>`\n\n";
+			}
 		}
 
 		my $desc = "";
@@ -343,7 +363,7 @@ sub output_rest {
 			printf "Has the following ABI:\n\n";
 
 			foreach my $content(@{$data{$what}->{symbols}}) {
-				my $label = $data{$symbols{$content}}->{label};
+				my $label = $data{$symbols{$content}->{xref}}->{label};
 
 				# Escape special chars from content
 				$content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g;
@@ -390,7 +410,7 @@ sub search_symbols {
 		printf "Date:\t\t\t%s\n", $date if ($date);
 		printf "Contact:\t\t%s\n", $contact if ($contact);
 		printf "Users:\t\t\t%s\n", $users if ($users);
-		print "Defined on file:\t$file\n\n";
+		print "Defined on file(s):\t$file\n\n";
 		print "Description:\n\n$desc";
 	}
 }
@@ -410,13 +430,24 @@ print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug);
 #
 # Handles the command
 #
-if ($cmd eq "rest") {
-	output_rest;
-} elsif ($cmd eq "search") {
+if ($cmd eq "search") {
 	search_symbols;
+} else {
+	if ($cmd eq "rest") {
+		output_rest;
+	}
+
+	# Warn about duplicated ABI entries
+	foreach my $what(sort keys %symbols) {
+		my @files = @{$symbols{$what}->{file}};
+
+		next if (scalar(@files) == 1);
+
+		printf STDERR "Warning: $what is defined %d times: @files\n",
+		    scalar(@files);
+	}
 }
 
-
 __END__
 
 =head1 NAME
-- 
2.26.2

[PATCH v2 07/39] scripts: get_abi.pl: output users in ReST format

[Mauro Carvalho Chehab]

Right now, the script only outputs Users on search. Print it
also in ReST format.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/get_abi.pl | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 1d1408fad130..e5a5588a8639 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -371,6 +371,14 @@ sub output_rest {
 				print "- :ref:`$content <$label>`\n\n";
 			}
 		}
+
+		if (defined($data{$what}->{users})) {
+			my $users = $data{$what}->{users};
+
+			$users =~ s/\n/\n\t/g;
+			printf "Users:\n\t%s\n\n", $users if ($users ne "");
+		}
+
 	}
 }
 
-- 
2.26.2

[PATCH v2 08/39] scripts: get_abi.pl: prevent duplicated file names

[Mauro Carvalho Chehab]

The same filename may exist on multiple directories within
ABI. Create separate entries at the internal database for
each of them.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/get_abi.pl | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index e5a5588a8639..5612f019fae0 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -65,7 +65,10 @@ sub parse_abi {
 	my $name = $file;
 	$name =~ s,.*/,,;
 
-	my $nametag = "File $name";
+	my $fn = $file;
+	$fn =~ s,Documentation/ABI/,,;
+
+	my $nametag = "File $fn";
 	$data{$nametag}->{what} = "File $name";
 	$data{$nametag}->{type} = "File";
 	$data{$nametag}->{file} = $name;
@@ -320,16 +323,18 @@ sub output_rest {
 			my $fileref = "abi_file_".$path;
 
 			if ($type eq "File") {
-				my $bar = $w;
-				$bar =~ s/./-/g;
-
 				print ".. _$fileref:\n\n";
-				print "$w\n$bar\n\n";
 			} else {
 				print "Defined on file :ref:`$f <$fileref>`\n\n";
 			}
 		}
 
+		if ($type eq "File") {
+			my $bar = $w;
+			$bar =~ s/./-/g;
+			print "$w\n$bar\n\n";
+		}
+
 		my $desc = "";
 		$desc = $data{$what}->{description} if (defined($data{$what}->{description}));
 		$desc =~ s/\s+$/\n/;
-- 
2.26.2

[PATCH v2 09/39] scripts: get_abi.pl: use bold font for ABI definitions

[Mauro Carvalho Chehab]

As we're using tables, let's distinguish the ones used by ABI
by using a bold font.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/get_abi.pl | 1 +
 1 file changed, 1 insertion(+)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 5612f019fae0..12a23f9a2f86 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -300,6 +300,7 @@ sub output_rest {
 			my $len = 0;
 
 			foreach my $name (@names) {
+				$name = "**$name**";
 				$len = length($name) if (length($name) > $len);
 			}
 
-- 
2.26.2

[PATCH v2 10/39] scripts: get_abi.pl: auto-generate cross references

[Mauro Carvalho Chehab]

There are several cross-references that can be automatically
generated:

	- References to .rst files inside Documentation/
	- References to other ABI files;
	- References to ABI symbols at /sys/*.

Add a logic to automatically parse them and convert into
cross references.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/get_abi.pl | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 12a23f9a2f86..ff4f9f82ecad 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -3,6 +3,7 @@
 
 use strict;
 use warnings;
+use utf8;
 use Pod::Usage;
 use Getopt::Long;
 use File::Find;
@@ -272,6 +273,9 @@ sub create_labels {
 # Outputs the book on ReST format
 #
 
+# \b doesn't work well with paths. So, we need to define something else
+my $bondary = qr { (?<![\w\/\`\{])(?=[\w\/\`\{])|(?<=[\w\/\`\{])(?![\w\/\`\{]) }x;
+
 sub output_rest {
 	create_labels();
 
@@ -342,6 +346,33 @@ sub output_rest {
 
 		if (!($desc =~ /^\s*$/)) {
 			if ($description_is_rst) {
+				# Enrich text by creating cross-references
+
+				$desc =~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g;
+
+				my @matches = $desc =~ m,Documentation/ABI/([\w\/\-]+),;
+				foreach my $f (@matches) {
+					my $xref = $f;
+					my $path = $f;
+					$path =~ s,.*/(.*/.*),$1,;;
+					$path =~ s,[/\-],_,g;;
+					$xref .= " <abi_file_" . $path . ">";
+					$desc =~ s,\bDocumentation/ABI/$f\b,:ref:`$xref`,g;
+				}
+
+				@matches = $desc =~ m,$bondary(/sys/[^\s\.\,\;\:\*\s\`\'\(\)]+)$bondary,;
+
+				foreach my $s (@matches) {
+					if (defined($data{$s}) && defined($data{$s}->{label})) {
+						my $xref = $s;
+
+						$xref =~ s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g;
+						$xref = ":ref:`$xref <" . $data{$s}->{label} . ">`";
+
+						$desc =~ s,$bondary$s$bondary,$xref,g;
+					}
+				}
+
 				print "$desc\n\n";
 			} else {
 				$desc =~ s/^\s+//;
-- 
2.26.2

[PATCH v2 11/39] docs: kernellog.py: add support for info()

[Mauro Carvalho Chehab]

An extension may want to just inform about something. So, add
support for it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/kernellog.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Documentation/sphinx/kernellog.py b/Documentation/sphinx/kernellog.py
index af924f51a7dc..8ac7d274f542 100644
--- a/Documentation/sphinx/kernellog.py
+++ b/Documentation/sphinx/kernellog.py
@@ -25,4 +25,8 @@ def verbose(app, message):
     else:
         app.verbose(message)
 
-
+def info(app, message):
+    if UseLogging:
+        logger.info(message)
+    else:
+        app.info(message)
-- 
2.26.2

[PATCH v2 12/39] docs: kernel_abi.py: add a script to parse ABI documentation

[Mauro Carvalho Chehab]

The ABI documentation is special: it is not plain text files,
but, instead, files with an strict format, as specified by
Documentation/ABI/README.

Add a parser for it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/kernel_abi.py | 157 +++++++++++++++++++++++++++++
 1 file changed, 157 insertions(+)
 create mode 100644 Documentation/sphinx/kernel_abi.py

diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
new file mode 100644
index 000000000000..f8e7a02066c2
--- /dev/null
+++ b/Documentation/sphinx/kernel_abi.py
@@ -0,0 +1,157 @@
+# -*- coding: utf-8; mode: python -*-
+# SPDX-License-Identifier: GPL-2.0
+u"""
+    kernel-abi
+    ~~~~~~~~~~
+
+    Implementation of the ``kernel-abi`` reST-directive.
+
+    :copyright:  Copyright (C) 2016  Markus Heiser
+    :copyright:  Copyright (C) 2016-2020  Mauro Carvalho Chehab
+    :maintained-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
+    :license:    GPL Version 2, June 1991 see Linux/COPYING for details.
+
+    The ``kernel-abi`` (:py:class:`KernelCmd`) directive calls the
+    scripts/get_abi.pl script to parse the Kernel ABI files.
+
+    Overview of directive's argument and options.
+
+    .. code-block:: rst
+
+        .. kernel-abi:: <ABI directory location>
+            :debug:
+
+    The argument ``<ABI directory location>`` is required. It contains the
+    location of the ABI files to be parsed.
+
+    ``debug``
+      Inserts a code-block with the *raw* reST. Sometimes it is helpful to see
+      what reST is generated.
+
+"""
+
+import sys
+import os
+from os import path
+import subprocess
+
+from sphinx.ext.autodoc import AutodocReporter
+
+from docutils import nodes
+from docutils.parsers.rst import Directive, directives
+from docutils.statemachine import ViewList
+from docutils.utils.error_reporting import ErrorString
+
+
+__version__  = '1.0'
+
+# We can't assume that six is installed
+PY3 = sys.version_info[0] == 3
+PY2 = sys.version_info[0] == 2
+if PY3:
+    # pylint: disable=C0103, W0622
+    unicode     = str
+    basestring  = str
+
+def setup(app):
+
+    app.add_directive("kernel-abi", KernelCmd)
+    return dict(
+        version = __version__
+        , parallel_read_safe = True
+        , parallel_write_safe = True
+    )
+
+class KernelCmd(Directive):
+
+    u"""KernelABI (``kernel-abi``) directive"""
+
+    required_arguments = 1
+    optional_arguments = 0
+    has_content = False
+    final_argument_whitespace = True
+
+    option_spec = {
+        "debug"     : directives.flag
+    }
+
+    def warn(self, message, **replace):
+        replace["fname"]   = self.state.document.current_source
+        replace["line_no"] = replace.get("line_no", self.lineno)
+        message = ("%(fname)s:%(line_no)s: [kernel-abi WARN] : " + message) % replace
+        self.state.document.settings.env.app.warn(message, prefix="")
+
+    def run(self):
+
+        doc = self.state.document
+        if not doc.settings.file_insertion_enabled:
+            raise self.warning("docutils: file insertion disabled")
+
+        env = doc.settings.env
+        cwd = path.dirname(doc.current_source)
+        cmd = "get_abi.pl rest --dir "
+        cmd += self.arguments[0]
+
+        srctree = path.abspath(os.environ["srctree"])
+
+        fname = cmd
+
+        # extend PATH with $(srctree)/scripts
+        path_env = os.pathsep.join([
+            srctree + os.sep + "scripts",
+            os.environ["PATH"]
+        ])
+        shell_env = os.environ.copy()
+        shell_env["PATH"]    = path_env
+        shell_env["srctree"] = srctree
+
+        lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env)
+        nodeList = self.nestedParse(lines, fname)
+        return nodeList
+
+    def runCmd(self, cmd, **kwargs):
+        u"""Run command ``cmd`` and return it's stdout as unicode."""
+
+        try:
+            proc = subprocess.Popen(
+                cmd
+                , stdout = subprocess.PIPE
+                , stderr = subprocess.PIPE
+                , universal_newlines = True
+                , **kwargs
+            )
+            out, err = proc.communicate()
+            if err:
+                self.warn(err)
+            if proc.returncode != 0:
+                raise self.severe(
+                    u"command '%s' failed with return code %d"
+                    % (cmd, proc.returncode)
+                )
+        except OSError as exc:
+            raise self.severe(u"problems with '%s' directive: %s."
+                              % (self.name, ErrorString(exc)))
+        return unicode(out)
+
+    def nestedParse(self, lines, fname):
+        content = ViewList()
+        node    = nodes.section()
+
+        if "debug" in self.options:
+            code_block = "\n\n.. code-block:: rst\n    :linenos:\n"
+            for l in lines.split("\n"):
+                code_block += "\n    " + l
+            lines = code_block + "\n\n"
+
+        for c, l in enumerate(lines.split("\n")):
+            content.append(l, fname, c)
+
+        buf  = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
+        self.state.memo.title_styles  = []
+        self.state.memo.section_level = 0
+        self.state.memo.reporter      = AutodocReporter(content, self.state.memo.reporter)
+        try:
+            self.state.nested_parse(content, 0, node, match_titles=1)
+        finally:
+            self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
+        return node.children
-- 
2.26.2

[PATCH v2 13/39] docs: kernel_abi.py: fix UTF-8 support

[Mauro Carvalho Chehab]

The parser breaks with UTF-8 characters with Sphinx 1.4.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/kernel_abi.py | 19 +++++++------------
 1 file changed, 7 insertions(+), 12 deletions(-)

diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index f8e7a02066c2..fe69c213716d 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -1,5 +1,7 @@
 # -*- coding: utf-8; mode: python -*-
+# coding=utf-8
 # SPDX-License-Identifier: GPL-2.0
+#
 u"""
     kernel-abi
     ~~~~~~~~~~
@@ -30,6 +32,7 @@ u"""
 
 """
 
+import codecs
 import sys
 import os
 from os import path
@@ -45,14 +48,6 @@ from docutils.utils.error_reporting import ErrorString
 
 __version__  = '1.0'
 
-# We can't assume that six is installed
-PY3 = sys.version_info[0] == 3
-PY2 = sys.version_info[0] == 2
-if PY3:
-    # pylint: disable=C0103, W0622
-    unicode     = str
-    basestring  = str
-
 def setup(app):
 
     app.add_directive("kernel-abi", KernelCmd)
@@ -117,12 +112,12 @@ class KernelCmd(Directive):
                 cmd
                 , stdout = subprocess.PIPE
                 , stderr = subprocess.PIPE
-                , universal_newlines = True
                 , **kwargs
             )
             out, err = proc.communicate()
-            if err:
-                self.warn(err)
+
+            out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8')
+
             if proc.returncode != 0:
                 raise self.severe(
                     u"command '%s' failed with return code %d"
@@ -131,7 +126,7 @@ class KernelCmd(Directive):
         except OSError as exc:
             raise self.severe(u"problems with '%s' directive: %s."
                               % (self.name, ErrorString(exc)))
-        return unicode(out)
+        return out
 
     def nestedParse(self, lines, fname):
         content = ViewList()
-- 
2.26.2

[PATCH v2 14/39] docs: kernel_abi.py: make it compatible with Sphinx 1.7+

[Mauro Carvalho Chehab]

The same way kerneldoc.py needed changes to work with newer
Sphinx, this script needs the same changes.

While here, reorganize the include order to match kerneldoc.py.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/kernel_abi.py | 39 +++++++++++++++++++++---------
 1 file changed, 27 insertions(+), 12 deletions(-)

diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index fe69c213716d..8601a3b75a28 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -33,18 +33,27 @@ u"""
 """
 
 import codecs
-import sys
 import os
-from os import path
 import subprocess
+import sys
 
-from sphinx.ext.autodoc import AutodocReporter
+from os import path
 
-from docutils import nodes
-from docutils.parsers.rst import Directive, directives
+from docutils import nodes, statemachine
 from docutils.statemachine import ViewList
+from docutils.parsers.rst import directives, Directive
 from docutils.utils.error_reporting import ErrorString
 
+#
+# AutodocReporter is only good up to Sphinx 1.7
+#
+import sphinx
+
+Use_SSI = sphinx.__version__[:3] >= '1.7'
+if Use_SSI:
+    from sphinx.util.docutils import switch_source_input
+else:
+    from sphinx.ext.autodoc import AutodocReporter
 
 __version__  = '1.0'
 
@@ -142,11 +151,17 @@ class KernelCmd(Directive):
             content.append(l, fname, c)
 
         buf  = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
-        self.state.memo.title_styles  = []
-        self.state.memo.section_level = 0
-        self.state.memo.reporter      = AutodocReporter(content, self.state.memo.reporter)
-        try:
-            self.state.nested_parse(content, 0, node, match_titles=1)
-        finally:
-            self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
+
+        if Use_SSI:
+            with switch_source_input(self.state, content):
+                self.state.nested_parse(content, 0, node, match_titles=1)
+        else:
+            self.state.memo.title_styles  = []
+            self.state.memo.section_level = 0
+            self.state.memo.reporter      = AutodocReporter(content, self.state.memo.reporter)
+            try:
+                self.state.nested_parse(content, 0, node, match_titles=1)
+            finally:
+                self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
+
         return node.children
-- 
2.26.2

[PATCH v2 15/39] docs: kernel_abi.py: use --enable-lineno for get_abi.pl

[Mauro Carvalho Chehab]

Just like kernel-doc extension, we need to be able to identify
what part of an imported document has issues, as reporting them
as:

	get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1689: ERROR: Unexpected indentation.

Makes a lot harder for someone to fix.

It should be noticed that it the line which will be reported is
the line where the "What:" definition is, and not the line
with actually has an error.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/kernel_abi.py | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index 8601a3b75a28..096dec482e96 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -36,6 +36,7 @@ import codecs
 import os
 import subprocess
 import sys
+import re
 
 from os import path
 
@@ -93,7 +94,7 @@ class KernelCmd(Directive):
 
         env = doc.settings.env
         cwd = path.dirname(doc.current_source)
-        cmd = "get_abi.pl rest --dir "
+        cmd = "get_abi.pl rest --enable-lineno --dir "
         cmd += self.arguments[0]
 
         srctree = path.abspath(os.environ["srctree"])
@@ -137,7 +138,7 @@ class KernelCmd(Directive):
                               % (self.name, ErrorString(exc)))
         return out
 
-    def nestedParse(self, lines, fname):
+    def nestedParse(self, lines, f):
         content = ViewList()
         node    = nodes.section()
 
@@ -147,8 +148,17 @@ class KernelCmd(Directive):
                 code_block += "\n    " + l
             lines = code_block + "\n\n"
 
-        for c, l in enumerate(lines.split("\n")):
-            content.append(l, fname, c)
+        line_regex = re.compile("^#define LINENO (\S+)\#([0-9]+)$")
+        ln = 0
+
+        for line in lines.split("\n"):
+            match = line_regex.search(line)
+            if match:
+                f = match.group(1)
+                # sphinx counts lines from 0
+                ln = int(match.group(2)) - 1
+            else:
+                content.append(line, f, ln)
 
         buf  = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
 
-- 
2.26.2

[PATCH v2 16/39] docs: kernel_abi.py: Handle with a lazy Sphinx parser

[Mauro Carvalho Chehab]

The Sphinx docutils parser is lazy: if the content is bigger than
a certain number of lines, it silenlty stops parsing it,
producing an incomplete content. This seems to be worse on newer
Sphinx versions, like 2.0.

So, change the logic to parse the contents per input file.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/sphinx/kernel_abi.py | 39 ++++++++++++++++++++----------
 1 file changed, 26 insertions(+), 13 deletions(-)

diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index 096dec482e96..ce5f3b0ae811 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -37,6 +37,7 @@ import os
 import subprocess
 import sys
 import re
+import kernellog
 
 from os import path
 
@@ -80,12 +81,6 @@ class KernelCmd(Directive):
         "debug"     : directives.flag
     }
 
-    def warn(self, message, **replace):
-        replace["fname"]   = self.state.document.current_source
-        replace["line_no"] = replace.get("line_no", self.lineno)
-        message = ("%(fname)s:%(line_no)s: [kernel-abi WARN] : " + message) % replace
-        self.state.document.settings.env.app.warn(message, prefix="")
-
     def run(self):
 
         doc = self.state.document
@@ -111,7 +106,7 @@ class KernelCmd(Directive):
         shell_env["srctree"] = srctree
 
         lines = self.runCmd(cmd, shell=True, cwd=cwd, env=shell_env)
-        nodeList = self.nestedParse(lines, fname)
+        nodeList = self.nestedParse(lines, self.arguments[0])
         return nodeList
 
     def runCmd(self, cmd, **kwargs):
@@ -138,9 +133,9 @@ class KernelCmd(Directive):
                               % (self.name, ErrorString(exc)))
         return out
 
-    def nestedParse(self, lines, f):
+    def nestedParse(self, lines, fname):
         content = ViewList()
-        node    = nodes.section()
+        node = nodes.section()
 
         if "debug" in self.options:
             code_block = "\n\n.. code-block:: rst\n    :linenos:\n"
@@ -150,22 +145,42 @@ class KernelCmd(Directive):
 
         line_regex = re.compile("^#define LINENO (\S+)\#([0-9]+)$")
         ln = 0
+        n = 0
+        f = fname
 
         for line in lines.split("\n"):
+            n = n + 1
             match = line_regex.search(line)
             if match:
-                f = match.group(1)
+                new_f = match.group(1)
+
+                # Sphinx parser is lazy: it stops parsing contents in the
+                # middle, if it is too big. So, handle it per input file
+                if new_f != f and content:
+                    self.do_parse(content, node)
+                    content = ViewList()
+
+                f = new_f
+
                 # sphinx counts lines from 0
                 ln = int(match.group(2)) - 1
             else:
                 content.append(line, f, ln)
 
-        buf  = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
+        kernellog.info(self.state.document.settings.env.app, "%s: parsed %i lines" % (fname, n))
 
+        if content:
+            self.do_parse(content, node)
+
+        return node.children
+
+    def do_parse(self, content, node):
         if Use_SSI:
             with switch_source_input(self.state, content):
                 self.state.nested_parse(content, 0, node, match_titles=1)
         else:
+            buf  = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter
+
             self.state.memo.title_styles  = []
             self.state.memo.section_level = 0
             self.state.memo.reporter      = AutodocReporter(content, self.state.memo.reporter)
@@ -173,5 +188,3 @@ class KernelCmd(Directive):
                 self.state.nested_parse(content, 0, node, match_titles=1)
             finally:
                 self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf
-
-        return node.children
-- 
2.26.2

[PATCH v2 17/39] docs: add ABI documentation to the admin-guide book

[Mauro Carvalho Chehab]

As we don't want a generic Sphinx extension to execute commands,
change the one proposed to Markus to call the abi_book.pl
script.

Use a script to parse the Documentation/ABI directory and output
it at the admin-guide.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/abi-obsolete.rst | 10 ++++++++++
 Documentation/admin-guide/abi-removed.rst  |  4 ++++
 Documentation/admin-guide/abi-stable.rst   | 13 +++++++++++++
 Documentation/admin-guide/abi-testing.rst  | 19 +++++++++++++++++++
 Documentation/admin-guide/abi.rst          | 11 +++++++++++
 Documentation/admin-guide/index.rst        |  2 ++
 Documentation/conf.py                      |  3 ++-
 7 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/admin-guide/abi-obsolete.rst
 create mode 100644 Documentation/admin-guide/abi-removed.rst
 create mode 100644 Documentation/admin-guide/abi-stable.rst
 create mode 100644 Documentation/admin-guide/abi-testing.rst
 create mode 100644 Documentation/admin-guide/abi.rst

diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/admin-guide/abi-obsolete.rst
new file mode 100644
index 000000000000..cda9168445a5
--- /dev/null
+++ b/Documentation/admin-guide/abi-obsolete.rst
@@ -0,0 +1,10 @@
+ABI obsolete symbols
+====================
+
+Documents interfaces that are still remaining in the kernel, but are
+marked to be removed at some later point in time.
+
+The description of the interface will document the reason why it is
+obsolete and when it can be expected to be removed.
+
+.. kernel-abi:: $srctree/Documentation/ABI/obsolete
diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admin-guide/abi-removed.rst
new file mode 100644
index 000000000000..497978fc9632
--- /dev/null
+++ b/Documentation/admin-guide/abi-removed.rst
@@ -0,0 +1,4 @@
+ABI removed symbols
+===================
+
+.. kernel-abi:: $srctree/Documentation/ABI/removed
diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/admin-guide/abi-stable.rst
new file mode 100644
index 000000000000..7495d7a35048
--- /dev/null
+++ b/Documentation/admin-guide/abi-stable.rst
@@ -0,0 +1,13 @@
+ABI stable symbols
+==================
+
+Documents the interfaces that the developer has defined to be stable.
+
+Userspace programs are free to use these interfaces with no
+restrictions, and backward compatibility for them will be guaranteed
+for at least 2 years.
+
+Most interfaces (like syscalls) are expected to never change and always
+be available.
+
+.. kernel-abi:: $srctree/Documentation/ABI/stable
diff --git a/Documentation/admin-guide/abi-testing.rst b/Documentation/admin-guide/abi-testing.rst
new file mode 100644
index 000000000000..5c886fc50b9e
--- /dev/null
+++ b/Documentation/admin-guide/abi-testing.rst
@@ -0,0 +1,19 @@
+ABI testing symbols
+===================
+
+Documents interfaces that are felt to be stable,
+as the main development of this interface has been completed.
+
+The interface can be changed to add new features, but the
+current interface will not break by doing this, unless grave
+errors or security problems are found in them.
+
+Userspace programs can start to rely on these interfaces, but they must
+be aware of changes that can occur before these interfaces move to
+be marked stable.
+
+Programs that use these interfaces are strongly encouraged to add their
+name to the description of these interfaces, so that the kernel
+developers can easily notify them if any changes occur.
+
+.. kernel-abi:: $srctree/Documentation/ABI/testing
diff --git a/Documentation/admin-guide/abi.rst b/Documentation/admin-guide/abi.rst
new file mode 100644
index 000000000000..3b9645c77469
--- /dev/null
+++ b/Documentation/admin-guide/abi.rst
@@ -0,0 +1,11 @@
+=====================
+Linux ABI description
+=====================
+
+.. toctree::
+   :maxdepth: 1
+
+   abi-stable
+   abi-testing
+   abi-obsolete
+   abi-removed
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index ed1cf94ea50c..4e0c4ae44acd 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -18,6 +18,8 @@ etc.
    devices
    sysctl/index
 
+   abi
+
 This section describes CPU vulnerabilities and their mitigations.
 
 .. toctree::
diff --git a/Documentation/conf.py b/Documentation/conf.py
index 7ee05fd4cb17..ed2b43ec7754 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -38,7 +38,8 @@ needs_sphinx = '1.3'
 # ones.
 extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include',
               'kfigure', 'sphinx.ext.ifconfig', 'automarkup',
-              'maintainers_include', 'sphinx.ext.autosectionlabel' ]
+              'maintainers_include', 'sphinx.ext.autosectionlabel',
+              'kernel_abi']
 
 #
 # cdomain is badly broken in Sphinx 3+.  Leaving it out generates *most*
-- 
2.26.2

[PATCH v2 18/39] docs: ABI: README: specify that files should be ReST compatible

[Mauro Carvalho Chehab]

As we plan to remove the escaping code from the scripts/get_abi.pl,
specify at the ABI README file that the content of the file should
be ReST compatible.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/README | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/Documentation/ABI/README b/Documentation/ABI/README
index 3121029dce21..8bac9cb09a6d 100644
--- a/Documentation/ABI/README
+++ b/Documentation/ABI/README
@@ -32,7 +32,7 @@ The different levels of stability are:
 	layout of the files below for details on how to do this.)
 
   obsolete/
-  	This directory documents interfaces that are still remaining in
+	This directory documents interfaces that are still remaining in
 	the kernel, but are marked to be removed at some later point in
 	time.  The description of the interface will document the reason
 	why it is obsolete and when it can be expected to be removed.
@@ -58,6 +58,14 @@ Users:		All users of this interface who wish to be notified when
 		be changed further.
 
 
+Note:
+   The fields should be use a simple notation, compatible with ReST markup.
+   Also, the file **should not** have a top-level index, like::
+
+	===
+	foo
+	===
+
 How things move between levels:
 
 Interfaces in stable may move to obsolete, as long as the proper
-- 
2.26.2

[PATCH v2 19/39] docs: ABI: stable: make files ReST compatible

[Mauro Carvalho Chehab]

Several entries at the stable ABI files won't parse if we pass
them directly to the ReST output.

Adjust them, in order to allow adding their contents as-is at
the stable ABI book.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/stable/firewire-cdev        |  4 +
 Documentation/ABI/stable/sysfs-acpi-pmprofile | 22 +++--
 Documentation/ABI/stable/sysfs-bus-firewire   |  3 +
 Documentation/ABI/stable/sysfs-bus-nvmem      | 19 ++--
 Documentation/ABI/stable/sysfs-bus-usb        |  6 +-
 .../ABI/stable/sysfs-class-backlight          |  1 +
 .../ABI/stable/sysfs-class-infiniband         | 93 +++++++++++++------
 Documentation/ABI/stable/sysfs-class-rfkill   | 13 ++-
 Documentation/ABI/stable/sysfs-class-tpm      | 90 +++++++++---------
 Documentation/ABI/stable/sysfs-devices        |  5 +-
 Documentation/ABI/stable/sysfs-driver-ib_srp  |  1 +
 .../ABI/stable/sysfs-firmware-efi-vars        |  4 +
 .../ABI/stable/sysfs-firmware-opal-dump       |  5 +
 .../ABI/stable/sysfs-firmware-opal-elog       |  2 +
 Documentation/ABI/stable/sysfs-hypervisor-xen |  3 +
 Documentation/ABI/stable/vdso                 |  5 +-
 16 files changed, 176 insertions(+), 100 deletions(-)

diff --git a/Documentation/ABI/stable/firewire-cdev b/Documentation/ABI/stable/firewire-cdev
index f72ed653878a..c9e8ff026154 100644
--- a/Documentation/ABI/stable/firewire-cdev
+++ b/Documentation/ABI/stable/firewire-cdev
@@ -14,12 +14,14 @@ Description:
 		Each /dev/fw* is associated with one IEEE 1394 node, which can
 		be remote or local nodes.  Operations on a /dev/fw* file have
 		different scope:
+
 		  - The 1394 node which is associated with the file:
 			  - Asynchronous request transmission
 			  - Get the Configuration ROM
 			  - Query node ID
 			  - Query maximum speed of the path between this node
 			    and local node
+
 		  - The 1394 bus (i.e. "card") to which the node is attached to:
 			  - Isochronous stream transmission and reception
 			  - Asynchronous stream transmission and reception
@@ -31,6 +33,7 @@ Description:
 			    manager
 			  - Query cycle time
 			  - Bus reset initiation, bus reset event reception
+
 		  - All 1394 buses:
 			  - Allocation of IEEE 1212 address ranges on the local
 			    link layers, reception of inbound requests to such
@@ -43,6 +46,7 @@ Description:
 		userland implement different access permission models, some
 		operations are restricted to /dev/fw* files that are associated
 		with a local node:
+
 			  - Addition of descriptors or directories to the local
 			    nodes' Configuration ROM
 			  - PHY packet transmission and reception
diff --git a/Documentation/ABI/stable/sysfs-acpi-pmprofile b/Documentation/ABI/stable/sysfs-acpi-pmprofile
index 964c7a8afb26..fd97d22b677f 100644
--- a/Documentation/ABI/stable/sysfs-acpi-pmprofile
+++ b/Documentation/ABI/stable/sysfs-acpi-pmprofile
@@ -6,17 +6,21 @@ Description: 	The ACPI pm_profile sysfs interface exports the platform
 		power management (and performance) requirement expectations
 		as provided by BIOS. The integer value is directly passed as
 		retrieved from the FADT ACPI table.
-Values:         For possible values see ACPI specification:
+
+Values:	        For possible values see ACPI specification:
 		5.2.9 Fixed ACPI Description Table (FADT)
 		Field: Preferred_PM_Profile
 
 		Currently these values are defined by spec:
-		0 Unspecified
-		1 Desktop
-		2 Mobile
-		3 Workstation
-		4 Enterprise Server
-		5 SOHO Server
-		6 Appliance PC
-		7 Performance Server
+
+		== =================
+		0  Unspecified
+		1  Desktop
+		2  Mobile
+		3  Workstation
+		4  Enterprise Server
+		5  SOHO Server
+		6  Appliance PC
+		7  Performance Server
 		>7 Reserved
+		== =================
diff --git a/Documentation/ABI/stable/sysfs-bus-firewire b/Documentation/ABI/stable/sysfs-bus-firewire
index 41e5a0cd1e3e..9ac9eddb82ef 100644
--- a/Documentation/ABI/stable/sysfs-bus-firewire
+++ b/Documentation/ABI/stable/sysfs-bus-firewire
@@ -47,6 +47,7 @@ Description:
 		IEEE 1394 node device attribute.
 		Read-only and immutable.
 Values:		1: The sysfs entry represents a local node (a controller card).
+
 		0: The sysfs entry represents a remote node.
 
 
@@ -125,7 +126,9 @@ Description:
 		Read-only attribute, immutable during the target's lifetime.
 		Format, as exposed by firewire-sbp2 since 2.6.22, May 2007:
 		Colon-separated hexadecimal string representations of
+
 			u64 EUI-64 : u24 directory_ID : u16 LUN
+
 		without 0x prefixes, without whitespace.  The former sbp2 driver
 		(removed in 2.6.37 after being superseded by firewire-sbp2) used
 		a somewhat shorter format which was not as close to SAM.
diff --git a/Documentation/ABI/stable/sysfs-bus-nvmem b/Documentation/ABI/stable/sysfs-bus-nvmem
index 9ffba8576f7b..c399323f37de 100644
--- a/Documentation/ABI/stable/sysfs-bus-nvmem
+++ b/Documentation/ABI/stable/sysfs-bus-nvmem
@@ -9,13 +9,14 @@ Description:
 		Note: This file is only present if CONFIG_NVMEM_SYSFS
 		is enabled
 
-		ex:
-		hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+		ex::
 
-		0000000 0000 0000 0000 0000 0000 0000 0000 0000
-		*
-		00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
-		0000000 0000 0000 0000 0000 0000 0000 0000 0000
-		...
-		*
-		0001000
+		  hexdump /sys/bus/nvmem/devices/qfprom0/nvmem
+
+		  0000000 0000 0000 0000 0000 0000 0000 0000 0000
+		  *
+		  00000a0 db10 2240 0000 e000 0c00 0c00 0000 0c00
+		  0000000 0000 0000 0000 0000 0000 0000 0000 0000
+		  ...
+		  *
+		  0001000
diff --git a/Documentation/ABI/stable/sysfs-bus-usb b/Documentation/ABI/stable/sysfs-bus-usb
index b832eeff9999..cad4bc232520 100644
--- a/Documentation/ABI/stable/sysfs-bus-usb
+++ b/Documentation/ABI/stable/sysfs-bus-usb
@@ -50,8 +50,10 @@ Description:
 
 		Tools can use this file and the connected_duration file to
 		compute the percentage of time that a device has been active.
-		For example,
-		echo $((100 * `cat active_duration` / `cat connected_duration`))
+		For example::
+
+		  echo $((100 * `cat active_duration` / `cat connected_duration`))
+
 		will give an integer percentage.  Note that this does not
 		account for counter wrap.
 Users:
diff --git a/Documentation/ABI/stable/sysfs-class-backlight b/Documentation/ABI/stable/sysfs-class-backlight
index 70302f370e7e..023fb52645f8 100644
--- a/Documentation/ABI/stable/sysfs-class-backlight
+++ b/Documentation/ABI/stable/sysfs-class-backlight
@@ -4,6 +4,7 @@ KernelVersion:	2.6.12
 Contact:	Richard Purdie <rpurdie@rpsys.net>
 Description:
 		Control BACKLIGHT power, values are FB_BLANK_* from fb.h
+
 		 - FB_BLANK_UNBLANK (0)   : power on.
 		 - FB_BLANK_POWERDOWN (4) : power off
 Users:		HAL
diff --git a/Documentation/ABI/stable/sysfs-class-infiniband b/Documentation/ABI/stable/sysfs-class-infiniband
index 87b11f91b425..348c4ac803ad 100644
--- a/Documentation/ABI/stable/sysfs-class-infiniband
+++ b/Documentation/ABI/stable/sysfs-class-infiniband
@@ -8,12 +8,14 @@ Date:		Apr, 2005
 KernelVersion:	v2.6.12
 Contact:	linux-rdma@vger.kernel.org
 Description:
+		=============== ===========================================
 		node_type:	(RO) Node type (CA, RNIC, usNIC, usNIC UDP,
 				switch or router)
 
 		node_guid:	(RO) Node GUID
 
 		sys_image_guid:	(RO) System image GUID
+		=============== ===========================================
 
 
 What:		/sys/class/infiniband/<device>/node_desc
@@ -47,6 +49,7 @@ KernelVersion:	v2.6.12
 Contact:	linux-rdma@vger.kernel.org
 Description:
 
+		=============== ===============================================
 		lid:		(RO) Port LID
 
 		rate:		(RO) Port data rate (active width * active
@@ -66,8 +69,9 @@ Description:
 
 		cap_mask:	(RO) Port capability mask. 2 bits here are
 				settable- IsCommunicationManagementSupported
-				(set when CM module is loaded) and IsSM (set via
-				open of issmN file).
+				(set when CM module is loaded) and IsSM (set
+				via open of issmN file).
+		=============== ===============================================
 
 
 What:		/sys/class/infiniband/<device>/ports/<port-num>/link_layer
@@ -103,8 +107,7 @@ Date:		Apr, 2005
 KernelVersion:	v2.6.12
 Contact:	linux-rdma@vger.kernel.org
 Description:
-		Errors info:
-		-----------
+		**Errors info**:
 
 		symbol_error: (RO) Total number of minor link errors detected on
 		one or more physical lanes.
@@ -142,8 +145,7 @@ Description:
 		intervention. It can also indicate hardware issues or extremely
 		poor link signal integrity
 
-		Data info:
-		---------
+		**Data info**:
 
 		port_xmit_data: (RO) Total number of data octets, divided by 4
 		(lanes), transmitted on all VLs. This is 64 bit counter
@@ -176,8 +178,7 @@ Description:
 		transmitted on all VLs from the port. This may include multicast
 		packets with errors.
 
-		Misc info:
-		---------
+		**Misc info**:
 
 		port_xmit_discards: (RO) Total number of outbound packets
 		discarded by the port because the port is down or congested.
@@ -244,9 +245,11 @@ Description:
 		two umad devices and two issm devices, while a switch will have
 		one device of each type (for switch port 0).
 
+		======= =====================================
 		ibdev:	(RO) Show Infiniband (IB) device name
 
 		port:	(RO) Display port number
+		======= =====================================
 
 
 What:		/sys/class/infiniband_mad/abi_version
@@ -264,10 +267,12 @@ Date:		Sept, 2005
 KernelVersion:	v2.6.14
 Contact:	linux-rdma@vger.kernel.org
 Description:
+		=============== ===========================================
 		ibdev:		(RO) Display Infiniband (IB) device name
 
 		abi_version:	(RO) Show ABI version of IB device specific
 				interfaces.
+		=============== ===========================================
 
 
 What:		/sys/class/infiniband_verbs/abi_version
@@ -289,12 +294,14 @@ Date:		Apr, 2005
 KernelVersion:	v2.6.12
 Contact:	linux-rdma@vger.kernel.org
 Description:
+		=============== ================================================
 		hw_rev:		(RO) Hardware revision number
 
 		hca_type:	(RO) Host Channel Adapter type: MT23108, MT25208
 				(MT23108 compat mode), MT25208 or MT25204
 
 		board_id:	(RO) Manufacturing board ID
+		=============== ================================================
 
 
 sysfs interface for Mellanox ConnectX HCA IB driver (mlx4)
@@ -307,11 +314,13 @@ Date:		Sep, 2007
 KernelVersion:	v2.6.24
 Contact:	linux-rdma@vger.kernel.org
 Description:
+		=============== ===============================
 		hw_rev:		(RO) Hardware revision number
 
 		hca_type:	(RO) Host channel adapter type
 
 		board_id:	(RO) Manufacturing board ID
+		=============== ===============================
 
 
 What:		/sys/class/infiniband/mlx4_X/iov/ports/<port-num>/gids/<n>
@@ -337,6 +346,7 @@ Description:
 		example, ports/1/pkeys/10 contains the value at index 10 in port
 		1's P_Key table.
 
+		======================= ==========================================
 		gids/<n>:		(RO) The physical port gids n = 0..127
 
 		admin_guids/<n>:	(RW) Allows examining or changing the
@@ -365,6 +375,7 @@ Description:
 					guest, whenever it uses its pkey index
 					1, will actually be using the real pkey
 					index 10.
+		======================= ==========================================
 
 
 What:		/sys/class/infiniband/mlx4_X/iov/<pci-slot-num>/ports/<m>/smi_enabled
@@ -376,12 +387,14 @@ Description:
 		Enabling QP0 on VFs for selected VF/port. By default, no VFs are
 		enabled for QP0 operation.
 
-		smi_enabled:	(RO) Indicates whether smi is currently enabled
-				for the indicated VF/port
+		================= ==== ===========================================
+		smi_enabled:	  (RO) Indicates whether smi is currently enabled
+				       for the indicated VF/port
 
-		enable_smi_admin:(RW) Used by the admin to request that smi
-				capability be enabled or disabled for the
-				indicated VF/port. 0 = disable, 1 = enable.
+		enable_smi_admin: (RW) Used by the admin to request that smi
+				       capability be enabled or disabled for the
+				       indicated VF/port. 0 = disable, 1 = enable.
+		================= ==== ===========================================
 
 		The requested enablement will occur at the next reset of the VF
 		(e.g. driver restart on the VM which owns the VF).
@@ -398,6 +411,7 @@ KernelVersion:	v2.6.35
 Contact:	linux-rdma@vger.kernel.org
 Description:
 
+		=============== =============================================
 		hw_rev:		(RO) Hardware revision number
 
 		hca_type:	(RO) Driver short name. Should normally match
@@ -406,6 +420,7 @@ Description:
 
 		board_id:	(RO) Manufacturing board id. (Vendor + device
 				information)
+		=============== =============================================
 
 
 sysfs interface for Intel IB driver qib
@@ -426,6 +441,7 @@ Date:		May, 2010
 KernelVersion:	v2.6.35
 Contact:	linux-rdma@vger.kernel.org
 Description:
+		=============== ======================================================
 		version:	(RO) Display version information of installed software
 				and drivers.
 
@@ -452,6 +468,7 @@ Description:
 		chip_reset:	(WO) Reset the chip if possible by writing
 				"reset" to this file. Only allowed if no user
 				contexts are open that use chip resources.
+		=============== ======================================================
 
 
 What:		/sys/class/infiniband/qibX/ports/N/sl2vl/[0-15]
@@ -471,14 +488,16 @@ Contact:	linux-rdma@vger.kernel.org
 Description:
 		Per-port congestion control. Both are binary attributes.
 
-		cc_table_bin:	(RO) Congestion control table size followed by
+		=============== ================================================
+		cc_table_bin	(RO) Congestion control table size followed by
 				table entries.
 
-		cc_settings_bin:(RO) Congestion settings: port control, control
+		cc_settings_bin (RO) Congestion settings: port control, control
 				map and an array of 16 entries for the
 				congestion entries - increase, timer, event log
 				trigger threshold and the minimum injection rate
 				delay.
+		=============== ================================================
 
 What:		/sys/class/infiniband/qibX/ports/N/linkstate/loopback
 What:		/sys/class/infiniband/qibX/ports/N/linkstate/led_override
@@ -491,6 +510,7 @@ Contact:	linux-rdma@vger.kernel.org
 Description:
 		[to be documented]
 
+		=============== ===============================================
 		loopback:	(WO)
 		led_override:	(WO)
 		hrtbt_enable:	(RW)
@@ -501,6 +521,7 @@ Description:
 				errors. Possible states are- "Initted",
 				"Present", "IB_link_up", "IB_configured" or
 				"Fatal_Hardware_Error".
+		=============== ===============================================
 
 What:		/sys/class/infiniband/qibX/ports/N/diag_counters/rc_resends
 What:		/sys/class/infiniband/qibX/ports/N/diag_counters/seq_naks
@@ -549,6 +570,7 @@ Contact:	Christian Benvenuti <benve@cisco.com>,
 		linux-rdma@vger.kernel.org
 Description:
 
+		=============== ===============================================
 		board_id:	(RO) Manufacturing board id
 
 		config:		(RO) Report the configuration for this PF
@@ -561,6 +583,7 @@ Description:
 
 		iface:		(RO) Shows which network interface this usNIC
 				entry is associated to (visible with ifconfig).
+		=============== ===============================================
 
 What:		/sys/class/infiniband/usnic_X/qpn/summary
 What:		/sys/class/infiniband/usnic_X/qpn/context
@@ -605,6 +628,7 @@ Date:		May, 2016
 KernelVersion:	v4.6
 Contact:	linux-rdma@vger.kernel.org
 Description:
+		=============== =============================================
 		hw_rev:		(RO) Hardware revision number
 
 		board_id:	(RO) Manufacturing board id
@@ -623,6 +647,7 @@ Description:
 				available.
 
 		tempsense:	(RO) Thermal sense information
+		=============== =============================================
 
 
 What:		/sys/class/infiniband/hfi1_X/ports/N/CCMgtA/cc_settings_bin
@@ -634,19 +659,21 @@ Contact:	linux-rdma@vger.kernel.org
 Description:
 		Per-port congestion control.
 
-		cc_table_bin:	(RO) CCA tables used by PSM2 Congestion control
+		=============== ================================================
+		cc_table_bin	(RO) CCA tables used by PSM2 Congestion control
 				table size followed by table entries. Binary
 				attribute.
 
-		cc_settings_bin:(RO) Congestion settings: port control, control
+		cc_settings_bin (RO) Congestion settings: port control, control
 				map and an array of 16 entries for the
 				congestion entries - increase, timer, event log
 				trigger threshold and the minimum injection rate
 				delay. Binary attribute.
 
-		cc_prescan:	(RW) enable prescanning for faster BECN
+		cc_prescan	(RW) enable prescanning for faster BECN
 				response. Write "on" to enable and "off" to
 				disable.
+		=============== ================================================
 
 What:		/sys/class/infiniband/hfi1_X/ports/N/sc2vl/[0-31]
 What:		/sys/class/infiniband/hfi1_X/ports/N/sl2sc/[0-31]
@@ -655,11 +682,13 @@ Date:		May, 2016
 KernelVersion:	v4.6
 Contact:	linux-rdma@vger.kernel.org
 Description:
+		=============== ===================================================
 		sc2vl/:		(RO) 32 files (0 - 31) used to translate sl->vl
 
 		sl2sc/:		(RO) 32 files (0 - 31) used to translate sl->sc
 
 		vl2mtu/:	(RO) 16 files (0 - 15) used to determine MTU for vl
+		=============== ===================================================
 
 
 What:		/sys/class/infiniband/hfi1_X/sdma_N/cpu_list
@@ -670,26 +699,28 @@ Contact:	linux-rdma@vger.kernel.org
 Description:
 		sdma<N>/ contains one directory per sdma engine (0 - 15)
 
+		=============== ==============================================
 		cpu_list:	(RW) List of cpus for user-process to sdma
 				engine assignment.
 
 		vl:		(RO) Displays the virtual lane (vl) the sdma
 				engine maps to.
+		=============== ==============================================
 
 		This interface gives the user control on the affinity settings
 		for the device. As an example, to set an sdma engine irq
 		affinity and thread affinity of a user processes to use the
 		sdma engine, which is "near" in terms of NUMA configuration, or
-		physical cpu location, the user will do:
+		physical cpu location, the user will do::
 
-		echo "3" > /proc/irq/<N>/smp_affinity_list
-		echo "4-7" > /sys/devices/.../sdma3/cpu_list
-		cat /sys/devices/.../sdma3/vl
-		0
-		echo "8" > /proc/irq/<M>/smp_affinity_list
-		echo "9-12" > /sys/devices/.../sdma4/cpu_list
-		cat /sys/devices/.../sdma4/vl
-		1
+		  echo "3" > /proc/irq/<N>/smp_affinity_list
+		  echo "4-7" > /sys/devices/.../sdma3/cpu_list
+		  cat /sys/devices/.../sdma3/vl
+		  0
+		  echo "8" > /proc/irq/<M>/smp_affinity_list
+		  echo "9-12" > /sys/devices/.../sdma4/cpu_list
+		  cat /sys/devices/.../sdma4/vl
+		  1
 
 		to make sure that when a process runs on cpus 4,5,6, or 7, and
 		uses vl=0, then sdma engine 3 is selected by the driver, and
@@ -711,11 +742,13 @@ Date:		Jan, 2016
 KernelVersion:	v4.10
 Contact:	linux-rdma@vger.kernel.org
 Description:
+		=============== ==== ========================
 		hw_rev:		(RO) Hardware revision number
 
 		hca_type:	(RO) Show HCA type (I40IW)
 
 		board_id:	(RO) I40IW board ID
+		=============== ==== ========================
 
 
 sysfs interface for QLogic qedr NIC Driver
@@ -728,9 +761,11 @@ KernelVersion:	v4.10
 Contact:	linux-rdma@vger.kernel.org
 Description:
 
+		=============== ==== ========================
 		hw_rev:		(RO) Hardware revision number
 
 		hca_type:	(RO) Display HCA type
+		=============== ==== ========================
 
 
 sysfs interface for VMware Paravirtual RDMA driver
@@ -744,11 +779,13 @@ KernelVersion:	v4.10
 Contact:	linux-rdma@vger.kernel.org
 Description:
 
+		=============== ==== =====================================
 		hw_rev:		(RO) Hardware revision number
 
 		hca_type:	(RO) Host channel adapter type
 
 		board_id:	(RO) Display PVRDMA manufacturing board ID
+		=============== ==== =====================================
 
 
 sysfs interface for Broadcom NetXtreme-E RoCE driver
@@ -760,6 +797,8 @@ Date:		Feb, 2017
 KernelVersion:	v4.11
 Contact:	linux-rdma@vger.kernel.org
 Description:
+		=============== ==== =========================
 		hw_rev:		(RO) Hardware revision number
 
 		hca_type:	(RO) Host channel adapter type
+		=============== ==== =========================
diff --git a/Documentation/ABI/stable/sysfs-class-rfkill b/Documentation/ABI/stable/sysfs-class-rfkill
index 5b154f922643..037979f7dc4b 100644
--- a/Documentation/ABI/stable/sysfs-class-rfkill
+++ b/Documentation/ABI/stable/sysfs-class-rfkill
@@ -2,7 +2,7 @@ rfkill - radio frequency (RF) connector kill switch support
 
 For details to this subsystem look at Documentation/driver-api/rfkill.rst.
 
-For the deprecated /sys/class/rfkill/*/claim knobs of this interface look in
+For the deprecated ``/sys/class/rfkill/*/claim`` knobs of this interface look in
 Documentation/ABI/removed/sysfs-class-rfkill.
 
 What: 		/sys/class/rfkill
@@ -36,9 +36,10 @@ KernelVersion	v2.6.22
 Contact:	linux-wireless@vger.kernel.org
 Description: 	Whether the soft blocked state is initialised from non-volatile
 		storage at startup.
-Values: 	A numeric value.
-		0: false
-		1: true
+Values: 	A numeric value:
+
+		- 0: false
+		- 1: true
 
 
 What:		/sys/class/rfkill/rfkill[0-9]+/state
@@ -54,6 +55,7 @@ Description: 	Current state of the transmitter.
 		through this interface. There will likely be another attempt to
 		remove it in the future.
 Values: 	A numeric value.
+
 		0: RFKILL_STATE_SOFT_BLOCKED
 			transmitter is turned off by software
 		1: RFKILL_STATE_UNBLOCKED
@@ -69,6 +71,7 @@ KernelVersion	v2.6.34
 Contact:	linux-wireless@vger.kernel.org
 Description: 	Current hardblock state. This file is read only.
 Values: 	A numeric value.
+
 		0: inactive
 			The transmitter is (potentially) active.
 		1: active
@@ -82,7 +85,9 @@ KernelVersion	v2.6.34
 Contact:	linux-wireless@vger.kernel.org
 Description:	Current softblock state. This file is read and write.
 Values: 	A numeric value.
+
 		0: inactive
 			The transmitter is (potentially) active.
+
 		1: active
 			The transmitter is turned off by software.
diff --git a/Documentation/ABI/stable/sysfs-class-tpm b/Documentation/ABI/stable/sysfs-class-tpm
index 58e94e7d55be..ec464cf7861a 100644
--- a/Documentation/ABI/stable/sysfs-class-tpm
+++ b/Documentation/ABI/stable/sysfs-class-tpm
@@ -32,11 +32,11 @@ KernelVersion:	2.6.12
 Contact:	linux-integrity@vger.kernel.org
 Description:	The "caps" property contains TPM manufacturer and version info.
 
-		Example output:
+		Example output::
 
-		Manufacturer: 0x53544d20
-		TCG version: 1.2
-		Firmware version: 8.16
+		  Manufacturer: 0x53544d20
+		  TCG version: 1.2
+		  Firmware version: 8.16
 
 		Manufacturer is a hex dump of the 4 byte manufacturer info
 		space in a TPM. TCG version shows the TCG TPM spec level that
@@ -54,9 +54,9 @@ Description:	The "durations" property shows the 3 vendor-specific values
 		any longer than necessary before starting to poll for a
 		result.
 
-		Example output:
+		Example output::
 
-		3015000 4508000 180995000 [original]
+		  3015000 4508000 180995000 [original]
 
 		Here the short, medium and long durations are displayed in
 		usecs. "[original]" indicates that the values are displayed
@@ -92,14 +92,14 @@ Description:	The "pcrs" property will dump the current value of all Platform
 		values may be constantly changing, the output is only valid
 		for a snapshot in time.
 
-		Example output:
+		Example output::
 
-		PCR-00: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
-		PCR-01: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
-		PCR-02: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
-		PCR-03: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
-		PCR-04: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
-		...
+		  PCR-00: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+		  PCR-01: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+		  PCR-02: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+		  PCR-03: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+		  PCR-04: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75
+		  ...
 
 		The number of PCRs and hex bytes needed to represent a PCR
 		value will vary depending on TPM chip version. For TPM 1.1 and
@@ -119,44 +119,44 @@ Description:	The "pubek" property will return the TPM's public endorsement
 		ated at TPM manufacture time and exists for the life of the
 		chip.
 
-		Example output:
+		Example output::
 
-		Algorithm: 00 00 00 01
-		Encscheme: 00 03
-		Sigscheme: 00 01
-		Parameters: 00 00 08 00 00 00 00 02 00 00 00 00
-		Modulus length: 256
-		Modulus:
-		B4 76 41 82 C9 20 2C 10 18 40 BC 8B E5 44 4C 6C
-		3A B2 92 0C A4 9B 2A 83 EB 5C 12 85 04 48 A0 B6
-		1E E4 81 84 CE B2 F2 45 1C F0 85 99 61 02 4D EB
-		86 C4 F7 F3 29 60 52 93 6B B2 E5 AB 8B A9 09 E3
-		D7 0E 7D CA 41 BF 43 07 65 86 3C 8C 13 7A D0 8B
-		82 5E 96 0B F8 1F 5F 34 06 DA A2 52 C1 A9 D5 26
-		0F F4 04 4B D9 3F 2D F2 AC 2F 74 64 1F 8B CD 3E
-		1E 30 38 6C 70 63 69 AB E2 50 DF 49 05 2E E1 8D
-		6F 78 44 DA 57 43 69 EE 76 6C 38 8A E9 8E A3 F0
-		A7 1F 3C A8 D0 12 15 3E CA 0E BD FA 24 CD 33 C6
-		47 AE A4 18 83 8E 22 39 75 93 86 E6 FD 66 48 B6
-		10 AD 94 14 65 F9 6A 17 78 BD 16 53 84 30 BF 70
-		E0 DC 65 FD 3C C6 B0 1E BF B9 C1 B5 6C EF B1 3A
-		F8 28 05 83 62 26 11 DC B4 6B 5A 97 FF 32 26 B6
-		F7 02 71 CF 15 AE 16 DD D1 C1 8E A8 CF 9B 50 7B
-		C3 91 FF 44 1E CF 7C 39 FE 17 77 21 20 BD CE 9B
+		  Algorithm: 00 00 00 01
+		  Encscheme: 00 03
+		  Sigscheme: 00 01
+		  Parameters: 00 00 08 00 00 00 00 02 00 00 00 00
+		  Modulus length: 256
+		  Modulus:
+		  B4 76 41 82 C9 20 2C 10 18 40 BC 8B E5 44 4C 6C
+		  3A B2 92 0C A4 9B 2A 83 EB 5C 12 85 04 48 A0 B6
+		  1E E4 81 84 CE B2 F2 45 1C F0 85 99 61 02 4D EB
+		  86 C4 F7 F3 29 60 52 93 6B B2 E5 AB 8B A9 09 E3
+		  D7 0E 7D CA 41 BF 43 07 65 86 3C 8C 13 7A D0 8B
+		  82 5E 96 0B F8 1F 5F 34 06 DA A2 52 C1 A9 D5 26
+		  0F F4 04 4B D9 3F 2D F2 AC 2F 74 64 1F 8B CD 3E
+		  1E 30 38 6C 70 63 69 AB E2 50 DF 49 05 2E E1 8D
+		  6F 78 44 DA 57 43 69 EE 76 6C 38 8A E9 8E A3 F0
+		  A7 1F 3C A8 D0 12 15 3E CA 0E BD FA 24 CD 33 C6
+		  47 AE A4 18 83 8E 22 39 75 93 86 E6 FD 66 48 B6
+		  10 AD 94 14 65 F9 6A 17 78 BD 16 53 84 30 BF 70
+		  E0 DC 65 FD 3C C6 B0 1E BF B9 C1 B5 6C EF B1 3A
+		  F8 28 05 83 62 26 11 DC B4 6B 5A 97 FF 32 26 B6
+		  F7 02 71 CF 15 AE 16 DD D1 C1 8E A8 CF 9B 50 7B
+		  C3 91 FF 44 1E CF 7C 39 FE 17 77 21 20 BD CE 9B
 
-		Possible values:
+		Possible values::
 
-		Algorithm:	TPM_ALG_RSA			(1)
-		Encscheme:	TPM_ES_RSAESPKCSv15		(2)
+		  Algorithm:	TPM_ALG_RSA			(1)
+		  Encscheme:	TPM_ES_RSAESPKCSv15		(2)
 				TPM_ES_RSAESOAEP_SHA1_MGF1	(3)
-		Sigscheme:	TPM_SS_NONE			(1)
-		Parameters, a byte string of 3 u32 values:
+		  Sigscheme:	TPM_SS_NONE			(1)
+		  Parameters, a byte string of 3 u32 values:
 			Key Length (bits):	00 00 08 00	(2048)
 			Num primes:		00 00 00 02	(2)
 			Exponent Size:		00 00 00 00	(0 means the
 								 default exp)
-		Modulus Length: 256 (bytes)
-		Modulus:	The 256 byte Endorsement Key modulus
+		  Modulus Length: 256 (bytes)
+		  Modulus:	The 256 byte Endorsement Key modulus
 
 What:		/sys/class/tpm/tpmX/device/temp_deactivated
 Date:		April 2006
@@ -176,9 +176,9 @@ Description:	The "timeouts" property shows the 4 vendor-specific values
 		timeouts is defined by the TPM interface spec that the chip
 		conforms to.
 
-		Example output:
+		Example output::
 
-		750000 750000 750000 750000 [original]
+		  750000 750000 750000 750000 [original]
 
 		The four timeout values are shown in usecs, with a trailing
 		"[original]" or "[adjusted]" depending on whether the values
diff --git a/Documentation/ABI/stable/sysfs-devices b/Documentation/ABI/stable/sysfs-devices
index 4404bd9b96c1..42bf1eab5677 100644
--- a/Documentation/ABI/stable/sysfs-devices
+++ b/Documentation/ABI/stable/sysfs-devices
@@ -1,5 +1,6 @@
-# Note: This documents additional properties of any device beyond what
-# is documented in Documentation/admin-guide/sysfs-rules.rst
+Note:
+  This documents additional properties of any device beyond what
+  is documented in Documentation/admin-guide/sysfs-rules.rst
 
 What:		/sys/devices/*/of_node
 Date:		February 2015
diff --git a/Documentation/ABI/stable/sysfs-driver-ib_srp b/Documentation/ABI/stable/sysfs-driver-ib_srp
index 84972a57caae..bada15a329f7 100644
--- a/Documentation/ABI/stable/sysfs-driver-ib_srp
+++ b/Documentation/ABI/stable/sysfs-driver-ib_srp
@@ -6,6 +6,7 @@ Description:	Interface for making ib_srp connect to a new target.
 		One can request ib_srp to connect to a new target by writing
 		a comma-separated list of login parameters to this sysfs
 		attribute. The supported parameters are:
+
 		* id_ext, a 16-digit hexadecimal number specifying the eight
 		  byte identifier extension in the 16-byte SRP target port
 		  identifier. The target port identifier is sent by ib_srp
diff --git a/Documentation/ABI/stable/sysfs-firmware-efi-vars b/Documentation/ABI/stable/sysfs-firmware-efi-vars
index 5def20b9019e..46ccd233e359 100644
--- a/Documentation/ABI/stable/sysfs-firmware-efi-vars
+++ b/Documentation/ABI/stable/sysfs-firmware-efi-vars
@@ -17,6 +17,7 @@ Description:
 		directory has a name of the form "<key>-<vendor guid>"
 		and contains the following files:
 
+		=============== ========================================
 		attributes:	A read-only text file enumerating the
 				EFI variable flags.  Potential values
 				include:
@@ -59,12 +60,14 @@ Description:
 
 		size:		As ASCII representation of the size of
 				the variable's value.
+		=============== ========================================
 
 
 		In addition, two other magic binary files are provided
 		in the top-level directory and are used for adding and
 		removing variables:
 
+		=============== ========================================
 		new_var:	Takes a "struct efi_variable" and
 				instructs the EFI firmware to create a
 				new variable.
@@ -73,3 +76,4 @@ Description:
 				instructs the EFI firmware to remove any
 				variable that has a matching vendor GUID
 				and variable key name.
+		=============== ========================================
diff --git a/Documentation/ABI/stable/sysfs-firmware-opal-dump b/Documentation/ABI/stable/sysfs-firmware-opal-dump
index 32fe7f5c4880..1f74f45327ba 100644
--- a/Documentation/ABI/stable/sysfs-firmware-opal-dump
+++ b/Documentation/ABI/stable/sysfs-firmware-opal-dump
@@ -7,6 +7,7 @@ Description:
 
 		This is only for the powerpc/powernv platform.
 
+		=============== ===============================================
 		initiate_dump:	When '1' is written to it,
 				we will initiate a dump.
 				Read this file for supported commands.
@@ -19,8 +20,11 @@ Description:
 				and ID of the dump, use the id and type files.
 				Do not rely on any particular size of dump
 				type or dump id.
+		=============== ===============================================
 
 		Each dump has the following files:
+
+		=============== ===============================================
 		id:		An ASCII representation of the dump ID
 				in hex (e.g. '0x01')
 		type:		An ASCII representation of the type of
@@ -39,3 +43,4 @@ Description:
 				inaccessible.
 				Reading this file will get a list of
 				supported actions.
+		=============== ===============================================
diff --git a/Documentation/ABI/stable/sysfs-firmware-opal-elog b/Documentation/ABI/stable/sysfs-firmware-opal-elog
index 2536434d49d0..7c8a61a2d005 100644
--- a/Documentation/ABI/stable/sysfs-firmware-opal-elog
+++ b/Documentation/ABI/stable/sysfs-firmware-opal-elog
@@ -38,6 +38,7 @@ Description:
 		For each log entry (directory), there are the following
 		files:
 
+		==============  ================================================
 		id:		An ASCII representation of the ID of the
 				error log, in hex - e.g. "0x01".
 
@@ -58,3 +59,4 @@ Description:
 				entry will be removed from sysfs.
 				Reading this file will list the supported
 				operations (currently just acknowledge).
+		==============  ================================================
diff --git a/Documentation/ABI/stable/sysfs-hypervisor-xen b/Documentation/ABI/stable/sysfs-hypervisor-xen
index 3cf5cdfcd9a8..748593c64568 100644
--- a/Documentation/ABI/stable/sysfs-hypervisor-xen
+++ b/Documentation/ABI/stable/sysfs-hypervisor-xen
@@ -33,6 +33,8 @@ Description:	If running under Xen:
 		Space separated list of supported guest system types. Each type
 		is in the format: <class>-<major>.<minor>-<arch>
 		With:
+
+			======== ============================================
 			<class>: "xen" -- x86: paravirtualized, arm: standard
 				 "hvm" -- x86 only: fully virtualized
 			<major>: major guest interface version
@@ -43,6 +45,7 @@ Description:	If running under Xen:
 				 "x86_64": 64 bit x86 guest
 				 "armv7l": 32 bit arm guest
 				 "aarch64": 64 bit arm guest
+			======== ============================================
 
 What:		/sys/hypervisor/properties/changeset
 Date:		March 2009
diff --git a/Documentation/ABI/stable/vdso b/Documentation/ABI/stable/vdso
index 55406ec8a35a..73ed1240a5c0 100644
--- a/Documentation/ABI/stable/vdso
+++ b/Documentation/ABI/stable/vdso
@@ -23,6 +23,7 @@ Unless otherwise noted, the set of symbols with any given version and the
 ABI of those symbols is considered stable.  It may vary across architectures,
 though.
 
-(As of this writing, this ABI documentation as been confirmed for x86_64.
+Note:
+ As of this writing, this ABI documentation as been confirmed for x86_64.
  The maintainers of the other vDSO-using architectures should confirm
- that it is correct for their architecture.)
+ that it is correct for their architecture.
-- 
2.26.2

[PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Mauro Carvalho Chehab]

Some files over there won't parse well by Sphinx.

Fix them.

Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> # for IIO
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../ABI/testing/configfs-spear-pcie-gadget    |  36 +--
 Documentation/ABI/testing/configfs-usb-gadget |  83 +++---
 .../ABI/testing/configfs-usb-gadget-hid       |  10 +-
 .../ABI/testing/configfs-usb-gadget-rndis     |  16 +-
 .../ABI/testing/configfs-usb-gadget-uac1      |  18 +-
 .../ABI/testing/configfs-usb-gadget-uvc       | 220 +++++++++-------
 Documentation/ABI/testing/debugfs-ec          |  11 +-
 Documentation/ABI/testing/debugfs-pktcdvd     |  11 +-
 Documentation/ABI/testing/dev-kmsg            |  27 +-
 Documentation/ABI/testing/evm                 |  17 +-
 Documentation/ABI/testing/ima_policy          |  30 ++-
 Documentation/ABI/testing/procfs-diskstats    |  40 +--
 Documentation/ABI/testing/sysfs-block         |  38 +--
 Documentation/ABI/testing/sysfs-block-device  |   2 +
 Documentation/ABI/testing/sysfs-bus-acpi      |  18 +-
 .../sysfs-bus-event_source-devices-format     |   3 +-
 .../ABI/testing/sysfs-bus-i2c-devices-pca954x |  27 +-
 Documentation/ABI/testing/sysfs-bus-iio       |  11 +
 .../sysfs-bus-iio-adc-envelope-detector       |   5 +-
 .../ABI/testing/sysfs-bus-iio-cros-ec         |   2 +-
 .../ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 |   8 +-
 .../ABI/testing/sysfs-bus-iio-lptimer-stm32   |  29 ++-
 .../sysfs-bus-iio-magnetometer-hmc5843        |  19 +-
 .../sysfs-bus-iio-temperature-max31856        |  19 +-
 .../ABI/testing/sysfs-bus-iio-timer-stm32     | 137 ++++++----
 .../testing/sysfs-bus-intel_th-devices-msc    |   4 +
 Documentation/ABI/testing/sysfs-bus-nfit      |   2 +-
 .../testing/sysfs-bus-pci-devices-aer_stats   | 119 +++++----
 Documentation/ABI/testing/sysfs-bus-rapidio   |  23 +-
 .../ABI/testing/sysfs-bus-thunderbolt         |  40 +--
 Documentation/ABI/testing/sysfs-bus-usb       |  30 ++-
 .../testing/sysfs-bus-usb-devices-usbsevseg   |   7 +-
 Documentation/ABI/testing/sysfs-bus-vfio-mdev |  10 +-
 Documentation/ABI/testing/sysfs-class-cxl     |  15 +-
 Documentation/ABI/testing/sysfs-class-led     |   2 +-
 .../testing/sysfs-class-led-driver-el15203000 | 229 ++++++++---------
 .../ABI/testing/sysfs-class-led-driver-sc27xx |   4 +-
 Documentation/ABI/testing/sysfs-class-mic     |  52 ++--
 Documentation/ABI/testing/sysfs-class-ocxl    |   3 +
 Documentation/ABI/testing/sysfs-class-power   |  73 +++++-
 .../ABI/testing/sysfs-class-power-twl4030     |  33 +--
 Documentation/ABI/testing/sysfs-class-rc      |  30 ++-
 .../ABI/testing/sysfs-class-scsi_host         |   7 +-
 Documentation/ABI/testing/sysfs-class-typec   |  12 +-
 .../testing/sysfs-devices-platform-ACPI-TAD   |   4 +
 .../ABI/testing/sysfs-devices-platform-docg3  |  10 +-
 .../sysfs-devices-platform-sh_mobile_lcdc_fb  |   8 +-
 .../ABI/testing/sysfs-devices-system-cpu      |  99 +++++---
 .../ABI/testing/sysfs-devices-system-ibm-rtl  |   6 +-
 .../testing/sysfs-driver-bd9571mwv-regulator  |   4 +
 Documentation/ABI/testing/sysfs-driver-genwqe |  11 +-
 .../testing/sysfs-driver-hid-logitech-lg4ff   |  18 +-
 .../ABI/testing/sysfs-driver-hid-wiimote      |  11 +-
 .../ABI/testing/sysfs-driver-samsung-laptop   |  13 +-
 .../ABI/testing/sysfs-driver-toshiba_acpi     |  26 ++
 .../ABI/testing/sysfs-driver-toshiba_haps     |   2 +
 Documentation/ABI/testing/sysfs-driver-wacom  |   4 +-
 Documentation/ABI/testing/sysfs-firmware-acpi | 237 +++++++++---------
 .../ABI/testing/sysfs-firmware-dmi-entries    |  50 ++--
 Documentation/ABI/testing/sysfs-firmware-gsmi |   2 +-
 .../ABI/testing/sysfs-firmware-memmap         |  16 +-
 Documentation/ABI/testing/sysfs-fs-ext4       |   4 +-
 .../ABI/testing/sysfs-hypervisor-xen          |  13 +-
 .../ABI/testing/sysfs-kernel-boot_params      |  23 +-
 .../ABI/testing/sysfs-kernel-mm-hugepages     |  12 +-
 .../ABI/testing/sysfs-platform-asus-laptop    |  21 +-
 .../ABI/testing/sysfs-platform-asus-wmi       |   1 +
 Documentation/ABI/testing/sysfs-platform-at91 |  10 +-
 .../ABI/testing/sysfs-platform-eeepc-laptop   |  14 +-
 .../ABI/testing/sysfs-platform-ideapad-laptop |   9 +-
 .../sysfs-platform-intel-wmi-thunderbolt      |   1 +
 .../ABI/testing/sysfs-platform-sst-atom       |  13 +-
 .../ABI/testing/sysfs-platform-usbip-vudc     |  11 +-
 Documentation/ABI/testing/sysfs-ptp           |   2 +-
 74 files changed, 1322 insertions(+), 865 deletions(-)

diff --git a/Documentation/ABI/testing/configfs-spear-pcie-gadget b/Documentation/ABI/testing/configfs-spear-pcie-gadget
index 840c324ef34d..cf877bd341df 100644
--- a/Documentation/ABI/testing/configfs-spear-pcie-gadget
+++ b/Documentation/ABI/testing/configfs-spear-pcie-gadget
@@ -10,22 +10,24 @@ Description:
 	This interfaces can be used to show spear's PCIe device capability.
 
 	Nodes are only visible when configfs is mounted. To mount configfs
-	in /config directory use:
-	# mount -t configfs none /config/
+	in /config directory use::
 
-	For nth PCIe Device Controller
-	/config/pcie-gadget.n/
-		link ... used to enable ltssm and read its status.
-		int_type ...used to configure and read type of supported
-			interrupt
-		no_of_msi ... used to configure number of MSI vector needed and
+	  # mount -t configfs none /config/
+
+	For nth PCIe Device Controller /config/pcie-gadget.n/:
+
+	=============== ======================================================
+	link		used to enable ltssm and read its status.
+	int_type	used to configure and read type of supported interrupt
+	no_of_msi	used to configure number of MSI vector needed and
 			to read no of MSI granted.
-		inta ... write 1 to assert INTA and 0 to de-assert.
-		send_msi ... write MSI vector to be sent.
-		vendor_id ... used to write and read vendor id (hex)
-		device_id ... used to write and read device id (hex)
-		bar0_size ... used to write and read bar0_size
-		bar0_address ... used to write and read bar0 mapped area in hex.
-		bar0_rw_offset ... used to write and read offset of bar0 where
-			bar0_data will be written or read.
-		bar0_data ... used to write and read data at bar0_rw_offset.
+	inta		write 1 to assert INTA and 0 to de-assert.
+	send_msi	write MSI vector to be sent.
+	vendor_id	used to write and read vendor id (hex)
+	device_id	used to write and read device id (hex)
+	bar0_size	used to write and read bar0_size
+	bar0_address	used to write and read bar0 mapped area in hex.
+	bar0_rw_offset	used to write and read offset of bar0 where bar0_data
+			will be written or read.
+	bar0_data	used to write and read data at bar0_rw_offset.
+	=============== ======================================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget b/Documentation/ABI/testing/configfs-usb-gadget
index 4594cc2435e8..dc351e9af80a 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget
+++ b/Documentation/ABI/testing/configfs-usb-gadget
@@ -12,22 +12,24 @@ Description:
 
 		The attributes of a gadget:
 
-		UDC		- bind a gadget to UDC/unbind a gadget;
-				write UDC's name found in /sys/class/udc/*
-				to bind a gadget, empty string "" to unbind.
+		================  ============================================
+		UDC		  bind a gadget to UDC/unbind a gadget;
+				  write UDC's name found in /sys/class/udc/*
+				  to bind a gadget, empty string "" to unbind.
 
-		max_speed	- maximum speed the driver supports. Valid
-				names are super-speed-plus, super-speed,
-				high-speed, full-speed, and low-speed.
+		max_speed	  maximum speed the driver supports. Valid
+				  names are super-speed-plus, super-speed,
+				  high-speed, full-speed, and low-speed.
 
-		bDeviceClass	- USB device class code
-		bDeviceSubClass	- USB device subclass code
-		bDeviceProtocol	- USB device protocol code
-		bMaxPacketSize0	- maximum endpoint 0 packet size
-		bcdDevice	- bcd device release number
-		bcdUSB		- bcd USB specification version number
-		idProduct	- product ID
-		idVendor	- vendor ID
+		bDeviceClass	  USB device class code
+		bDeviceSubClass	  USB device subclass code
+		bDeviceProtocol	  USB device protocol code
+		bMaxPacketSize0	  maximum endpoint 0 packet size
+		bcdDevice	  bcd device release number
+		bcdUSB		  bcd USB specification version number
+		idProduct	  product ID
+		idVendor	  vendor ID
+		================  ============================================
 
 What:		/config/usb-gadget/gadget/configs
 Date:		Jun 2013
@@ -41,8 +43,10 @@ KernelVersion:	3.11
 Description:
 		The attributes of a configuration:
 
-		bmAttributes	- configuration characteristics
-		MaxPower	- maximum power consumption from the bus
+		================  ======================================
+		bmAttributes	  configuration characteristics
+		MaxPower	  maximum power consumption from the bus
+		================  ======================================
 
 What:		/config/usb-gadget/gadget/configs/config/strings
 Date:		Jun 2013
@@ -57,7 +61,9 @@ KernelVersion:	3.11
 Description:
 		The attributes:
 
-		configuration	- configuration description
+		================  =========================
+		configuration	  configuration description
+		================  =========================
 
 
 What:		/config/usb-gadget/gadget/functions
@@ -76,8 +82,10 @@ Description:
 
 		The attributes:
 
-		compatible_id		- 8-byte string for "Compatible ID"
-		sub_compatible_id	- 8-byte string for "Sub Compatible ID"
+		=================	=====================================
+		compatible_id		8-byte string for "Compatible ID"
+		sub_compatible_id	8-byte string for "Sub Compatible ID"
+		=================	=====================================
 
 What:		/config/usb-gadget/gadget/functions/<func>.<inst>/interface.<n>/<property>
 Date:		May 2014
@@ -89,16 +97,19 @@ Description:
 
 		The attributes:
 
-		type		- value 1..7 for interpreting the data
-				1: unicode string
-				2: unicode string with environment variable
-				3: binary
-				4: little-endian 32-bit
-				5: big-endian 32-bit
-				6: unicode string with a symbolic link
-				7: multiple unicode strings
-		data		- blob of data to be interpreted depending on
+		=====		===============================================
+		type		value 1..7 for interpreting the data
+
+				- 1: unicode string
+				- 2: unicode string with environment variable
+				- 3: binary
+				- 4: little-endian 32-bit
+				- 5: big-endian 32-bit
+				- 6: unicode string with a symbolic link
+				- 7: multiple unicode strings
+		data		blob of data to be interpreted depending on
 				type
+		=====		===============================================
 
 What:		/config/usb-gadget/gadget/strings
 Date:		Jun 2013
@@ -113,9 +124,11 @@ KernelVersion:	3.11
 Description:
 		The attributes:
 
-		serialnumber	- gadget's serial number (string)
-		product		- gadget's product description
-		manufacturer	- gadget's manufacturer description
+		============	=================================
+		serialnumber	gadget's serial number (string)
+		product		gadget's product description
+		manufacturer	gadget's manufacturer description
+		============	=================================
 
 What:		/config/usb-gadget/gadget/os_desc
 Date:		May 2014
@@ -123,8 +136,10 @@ KernelVersion:	3.16
 Description:
 		This group contains "OS String" extension handling attributes.
 
-		use		- flag turning "OS Desctiptors" support on/off
-		b_vendor_code	- one-byte value used for custom per-device and
+		=============	===============================================
+		use		flag turning "OS Desctiptors" support on/off
+		b_vendor_code	one-byte value used for custom per-device and
 				per-interface requests
-		qw_sign		- an identifier to be reported as "OS String"
+		qw_sign		an identifier to be reported as "OS String"
 				proper
+		=============	===============================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-hid b/Documentation/ABI/testing/configfs-usb-gadget-hid
index f12e00e6baa3..748705c4cb58 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-hid
+++ b/Documentation/ABI/testing/configfs-usb-gadget-hid
@@ -4,8 +4,10 @@ KernelVersion:	3.19
 Description:
 		The attributes:
 
-		protocol	- HID protocol to use
-		report_desc	- blob corresponding to HID report descriptors
+		=============	============================================
+		protocol	HID protocol to use
+		report_desc	blob corresponding to HID report descriptors
 				except the data passed through /dev/hidg<N>
-		report_length	- HID report length
-		subclass	- HID device subclass to use
+		report_length	HID report length
+		subclass	HID device subclass to use
+		=============	============================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-rndis b/Documentation/ABI/testing/configfs-usb-gadget-rndis
index 137399095d74..9416eda7fe93 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-rndis
+++ b/Documentation/ABI/testing/configfs-usb-gadget-rndis
@@ -4,14 +4,16 @@ KernelVersion:	3.11
 Description:
 		The attributes:
 
-		ifname		- network device interface name associated with
+		=========	=============================================
+		ifname		network device interface name associated with
 				this function instance
-		qmult		- queue length multiplier for high and
+		qmult		queue length multiplier for high and
 				super speed
-		host_addr	- MAC address of host's end of this
+		host_addr	MAC address of host's end of this
 				Ethernet over USB link
-		dev_addr	- MAC address of device's end of this
+		dev_addr	MAC address of device's end of this
 				Ethernet over USB link
-		class		- USB interface class, default is 02 (hex)
-		subclass	- USB interface subclass, default is 06 (hex)
-		protocol	- USB interface protocol, default is 00 (hex)
+		class		USB interface class, default is 02 (hex)
+		subclass	USB interface subclass, default is 06 (hex)
+		protocol	USB interface protocol, default is 00 (hex)
+		=========	=============================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac1 b/Documentation/ABI/testing/configfs-usb-gadget-uac1
index abfe447c848f..dc23fd776943 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-uac1
+++ b/Documentation/ABI/testing/configfs-usb-gadget-uac1
@@ -4,11 +4,13 @@ KernelVersion:	4.14
 Description:
 		The attributes:
 
-		c_chmask - capture channel mask
-		c_srate - capture sampling rate
-		c_ssize - capture sample size (bytes)
-		p_chmask - playback channel mask
-		p_srate - playback sampling rate
-		p_ssize - playback sample size (bytes)
-		req_number - the number of pre-allocated request
-			for both capture and playback
+		==========	===================================
+		c_chmask	capture channel mask
+		c_srate		capture sampling rate
+		c_ssize		capture sample size (bytes)
+		p_chmask	playback channel mask
+		p_srate		playback sampling rate
+		p_ssize		playback sample size (bytes)
+		req_number	the number of pre-allocated request
+				for both capture and playback
+		==========	===================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uvc b/Documentation/ABI/testing/configfs-usb-gadget-uvc
index 809765bd9573..cee81b0347bb 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-uvc
+++ b/Documentation/ABI/testing/configfs-usb-gadget-uvc
@@ -3,9 +3,11 @@ Date:		Dec 2014
 KernelVersion:	4.0
 Description:	UVC function directory
 
-		streaming_maxburst	- 0..15 (ss only)
-		streaming_maxpacket	- 1..1023 (fs), 1..3072 (hs/ss)
-		streaming_interval	- 1..16
+		===================	=============================
+		streaming_maxburst	0..15 (ss only)
+		streaming_maxpacket	1..1023 (fs), 1..3072 (hs/ss)
+		streaming_interval	1..16
+		===================	=============================
 
 What:		/config/usb-gadget/gadget/functions/uvc.name/control
 Date:		Dec 2014
@@ -13,8 +15,11 @@ KernelVersion:	4.0
 Description:	Control descriptors
 
 		All attributes read only:
-		bInterfaceNumber	- USB interface number for this
-					  streaming interface
+
+		================	=============================
+		bInterfaceNumber	USB interface number for this
+					streaming interface
+		================	=============================
 
 What:		/config/usb-gadget/gadget/functions/uvc.name/control/class
 Date:		Dec 2014
@@ -47,13 +52,16 @@ KernelVersion:	4.0
 Description:	Default output terminal descriptors
 
 		All attributes read only:
-		iTerminal	- index of string descriptor
-		bSourceID 	- id of the terminal to which this terminal
+
+		==============	=============================================
+		iTerminal	index of string descriptor
+		bSourceID 	id of the terminal to which this terminal
 				is connected
-		bAssocTerminal	- id of the input terminal to which this output
+		bAssocTerminal	id of the input terminal to which this output
 				terminal is associated
-		wTerminalType	- terminal type
-		bTerminalID	- a non-zero id of this terminal
+		wTerminalType	terminal type
+		bTerminalID	a non-zero id of this terminal
+		==============	=============================================
 
 What:		/config/usb-gadget/gadget/functions/uvc.name/control/terminal/camera
 Date:		Dec 2014
@@ -66,16 +74,19 @@ KernelVersion:	4.0
 Description:	Default camera terminal descriptors
 
 		All attributes read only:
-		bmControls		- bitmap specifying which controls are
-					supported for the video stream
-		wOcularFocalLength	- the value of Locular
-		wObjectiveFocalLengthMax- the value of Lmin
-		wObjectiveFocalLengthMin- the value of Lmax
-		iTerminal		- index of string descriptor
-		bAssocTerminal		- id of the output terminal to which
-					this terminal is connected
-		wTerminalType		- terminal type
-		bTerminalID		- a non-zero id of this terminal
+
+		========================  ====================================
+		bmControls		  bitmap specifying which controls are
+					  supported for the video stream
+		wOcularFocalLength	  the value of Locular
+		wObjectiveFocalLengthMax  the value of Lmin
+		wObjectiveFocalLengthMin  the value of Lmax
+		iTerminal		  index of string descriptor
+		bAssocTerminal		  id of the output terminal to which
+					  this terminal is connected
+		wTerminalType		  terminal type
+		bTerminalID		  a non-zero id of this terminal
+		========================  ====================================
 
 What:		/config/usb-gadget/gadget/functions/uvc.name/control/processing
 Date:		Dec 2014
@@ -88,13 +99,16 @@ KernelVersion:	4.0
 Description:	Default processing unit descriptors
 
 		All attributes read only:
-		iProcessing	- index of string descriptor
-		bmControls	- bitmap specifying which controls are
+
+		===============	========================================
+		iProcessing	index of string descriptor
+		bmControls	bitmap specifying which controls are
 				supported for the video stream
-		wMaxMultiplier	- maximum digital magnification x100
-		bSourceID	- id of the terminal to which this unit is
+		wMaxMultiplier	maximum digital magnification x100
+		bSourceID	id of the terminal to which this unit is
 				connected
-		bUnitID		- a non-zero id of this unit
+		bUnitID		a non-zero id of this unit
+		===============	========================================
 
 What:		/config/usb-gadget/gadget/functions/uvc.name/control/header
 Date:		Dec 2014
@@ -114,8 +128,11 @@ KernelVersion:	4.0
 Description:	Streaming descriptors
 
 		All attributes read only:
-		bInterfaceNumber	- USB interface number for this
-					  streaming interface
+
+		================	=============================
+		bInterfaceNumber	USB interface number for this
+					streaming interface
+		================	=============================
 
 What:		/config/usb-gadget/gadget/functions/uvc.name/streaming/class
 Date:		Dec 2014
@@ -148,13 +165,16 @@ KernelVersion:	4.0
 Description:	Default color matching descriptors
 
 		All attributes read only:
-		bMatrixCoefficients	- matrix used to compute luma and
-					chroma values from the color primaries
-		bTransferCharacteristics- optoelectronic transfer
-					characteristic of the source picutre,
-					also called the gamma function
-		bColorPrimaries		- color primaries and the reference
-					white
+
+		========================  ======================================
+		bMatrixCoefficients	  matrix used to compute luma and
+					  chroma values from the color primaries
+		bTransferCharacteristics  optoelectronic transfer
+					  characteristic of the source picutre,
+					  also called the gamma function
+		bColorPrimaries		  color primaries and the reference
+					  white
+		========================  ======================================
 
 What:		/config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg
 Date:		Dec 2014
@@ -168,47 +188,52 @@ Description:	Specific MJPEG format descriptors
 
 		All attributes read only,
 		except bmaControls and bDefaultFrameIndex:
-		bFormatIndex		- unique id for this format descriptor;
+
+		===================	=====================================
+		bFormatIndex		unique id for this format descriptor;
 					only defined after parent header is
 					linked into the streaming class;
 					read-only
-		bmaControls		- this format's data for bmaControls in
+		bmaControls		this format's data for bmaControls in
 					the streaming header
-		bmInterfaceFlags	- specifies interlace information,
+		bmInterfaceFlags	specifies interlace information,
 					read-only
-		bAspectRatioY		- the X dimension of the picture aspect
+		bAspectRatioY		the X dimension of the picture aspect
 					ratio, read-only
-		bAspectRatioX		- the Y dimension of the picture aspect
+		bAspectRatioX		the Y dimension of the picture aspect
 					ratio, read-only
-		bmFlags			- characteristics of this format,
+		bmFlags			characteristics of this format,
 					read-only
-		bDefaultFrameIndex	- optimum frame index for this stream
+		bDefaultFrameIndex	optimum frame index for this stream
+		===================	=====================================
 
 What:		/config/usb-gadget/gadget/functions/uvc.name/streaming/mjpeg/name/name
 Date:		Dec 2014
 KernelVersion:	4.0
 Description:	Specific MJPEG frame descriptors
 
-		bFrameIndex		- unique id for this framedescriptor;
-					only defined after parent format is
-					linked into the streaming header;
-					read-only
-		dwFrameInterval		- indicates how frame interval can be
-					programmed; a number of values
-					separated by newline can be specified
-		dwDefaultFrameInterval	- the frame interval the device would
-					like to use as default
-		dwMaxVideoFrameBufferSize- the maximum number of bytes the
-					compressor will produce for a video
-					frame or still image
-		dwMaxBitRate		- the maximum bit rate at the shortest
-					frame interval in bps
-		dwMinBitRate		- the minimum bit rate at the longest
-					frame interval in bps
-		wHeight			- height of decoded bitmap frame in px
-		wWidth			- width of decoded bitmam frame in px
-		bmCapabilities		- still image support, fixed frame-rate
-					support
+		=========================  =====================================
+		bFrameIndex		   unique id for this framedescriptor;
+					   only defined after parent format is
+					   linked into the streaming header;
+					   read-only
+		dwFrameInterval		   indicates how frame interval can be
+					   programmed; a number of values
+					   separated by newline can be specified
+		dwDefaultFrameInterval	   the frame interval the device would
+					   like to use as default
+		dwMaxVideoFrameBufferSize  the maximum number of bytes the
+					   compressor will produce for a video
+					   frame or still image
+		dwMaxBitRate		   the maximum bit rate at the shortest
+					   frame interval in bps
+		dwMinBitRate		   the minimum bit rate at the longest
+					   frame interval in bps
+		wHeight			   height of decoded bitmap frame in px
+		wWidth			   width of decoded bitmam frame in px
+		bmCapabilities		   still image support, fixed frame-rate
+					   support
+		=========================  =====================================
 
 What:		/config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed
 Date:		Dec 2014
@@ -220,50 +245,54 @@ Date:		Dec 2014
 KernelVersion:	4.0
 Description:	Specific uncompressed format descriptors
 
-		bFormatIndex		- unique id for this format descriptor;
+		==================	=======================================
+		bFormatIndex		unique id for this format descriptor;
 					only defined after parent header is
 					linked into the streaming class;
 					read-only
-		bmaControls		- this format's data for bmaControls in
+		bmaControls		this format's data for bmaControls in
 					the streaming header
-		bmInterfaceFlags	- specifies interlace information,
+		bmInterfaceFlags	specifies interlace information,
 					read-only
-		bAspectRatioY		- the X dimension of the picture aspect
+		bAspectRatioY		the X dimension of the picture aspect
 					ratio, read-only
-		bAspectRatioX		- the Y dimension of the picture aspect
+		bAspectRatioX		the Y dimension of the picture aspect
 					ratio, read-only
-		bDefaultFrameIndex	- optimum frame index for this stream
-		bBitsPerPixel		- number of bits per pixel used to
+		bDefaultFrameIndex	optimum frame index for this stream
+		bBitsPerPixel		number of bits per pixel used to
 					specify color in the decoded video
 					frame
-		guidFormat		- globally unique id used to identify
+		guidFormat		globally unique id used to identify
 					stream-encoding format
+		==================	=======================================
 
 What:		/config/usb-gadget/gadget/functions/uvc.name/streaming/uncompressed/name/name
 Date:		Dec 2014
 KernelVersion:	4.0
 Description:	Specific uncompressed frame descriptors
 
-		bFrameIndex		- unique id for this framedescriptor;
-					only defined after parent format is
-					linked into the streaming header;
-					read-only
-		dwFrameInterval		- indicates how frame interval can be
-					programmed; a number of values
-					separated by newline can be specified
-		dwDefaultFrameInterval	- the frame interval the device would
-					like to use as default
-		dwMaxVideoFrameBufferSize- the maximum number of bytes the
-					compressor will produce for a video
-					frame or still image
-		dwMaxBitRate		- the maximum bit rate at the shortest
-					frame interval in bps
-		dwMinBitRate		- the minimum bit rate at the longest
-					frame interval in bps
-		wHeight			- height of decoded bitmap frame in px
-		wWidth			- width of decoded bitmam frame in px
-		bmCapabilities		- still image support, fixed frame-rate
-					support
+		=========================  =====================================
+		bFrameIndex		   unique id for this framedescriptor;
+					   only defined after parent format is
+					   linked into the streaming header;
+					   read-only
+		dwFrameInterval		   indicates how frame interval can be
+					   programmed; a number of values
+					   separated by newline can be specified
+		dwDefaultFrameInterval	   the frame interval the device would
+					   like to use as default
+		dwMaxVideoFrameBufferSize  the maximum number of bytes the
+					   compressor will produce for a video
+					   frame or still image
+		dwMaxBitRate		   the maximum bit rate at the shortest
+					   frame interval in bps
+		dwMinBitRate		   the minimum bit rate at the longest
+					   frame interval in bps
+		wHeight			   height of decoded bitmap frame in px
+		wWidth			   width of decoded bitmam frame in px
+		bmCapabilities		   still image support, fixed frame-rate
+					   support
+		=========================  =====================================
 
 What:		/config/usb-gadget/gadget/functions/uvc.name/streaming/header
 Date:		Dec 2014
@@ -276,17 +305,20 @@ KernelVersion:	4.0
 Description:	Specific streaming header descriptors
 
 		All attributes read only:
-		bTriggerUsage		- how the host software will respond to
+
+		====================	=====================================
+		bTriggerUsage		how the host software will respond to
 					a hardware trigger interrupt event
-		bTriggerSupport		- flag specifying if hardware
+		bTriggerSupport		flag specifying if hardware
 					triggering is supported
-		bStillCaptureMethod	- method of still image caputre
+		bStillCaptureMethod	method of still image caputre
 					supported
-		bTerminalLink		- id of the output terminal to which
+		bTerminalLink		id of the output terminal to which
 					the video endpoint of this interface
 					is connected
-		bmInfo			- capabilities of this video streaming
+		bmInfo			capabilities of this video streaming
 					interface
+		====================	=====================================
 
 What:		/sys/class/udc/udc.name/device/gadget/video4linux/video.name/function_name
 Date:		May 2018
diff --git a/Documentation/ABI/testing/debugfs-ec b/Documentation/ABI/testing/debugfs-ec
index 6546115a94da..ab6099daa8f5 100644
--- a/Documentation/ABI/testing/debugfs-ec
+++ b/Documentation/ABI/testing/debugfs-ec
@@ -6,7 +6,7 @@ Description:
 General information like which GPE is assigned to the EC and whether
 the global lock should get used.
 Knowing the EC GPE one can watch the amount of HW events related to
-the EC here (XY -> GPE number from /sys/kernel/debug/ec/*/gpe):
+the EC here (XY -> GPE number from `/sys/kernel/debug/ec/*/gpe`):
 /sys/firmware/acpi/interrupts/gpeXY
 
 The io file is binary and a userspace tool located here:
@@ -14,7 +14,8 @@ ftp://ftp.suse.com/pub/people/trenn/sources/ec/
 should get used to read out the 256 Embedded Controller registers
 or writing to them.
 
-CAUTION: Do not write to the Embedded Controller if you don't know
-what you are doing! Rebooting afterwards also is a good idea.
-This can influence the way your machine is cooled and fans may
-not get switched on again after you did a wrong write.
+CAUTION:
+  Do not write to the Embedded Controller if you don't know
+  what you are doing! Rebooting afterwards also is a good idea.
+  This can influence the way your machine is cooled and fans may
+  not get switched on again after you did a wrong write.
diff --git a/Documentation/ABI/testing/debugfs-pktcdvd b/Documentation/ABI/testing/debugfs-pktcdvd
index cf11736acb76..787907d70462 100644
--- a/Documentation/ABI/testing/debugfs-pktcdvd
+++ b/Documentation/ABI/testing/debugfs-pktcdvd
@@ -4,16 +4,15 @@ KernelVersion:  2.6.20
 Contact:        Thomas Maier <balagi@justmail.de>
 Description:
 
-debugfs interface
------------------
-
 The pktcdvd module (packet writing driver) creates
 these files in debugfs:
 
 /sys/kernel/debug/pktcdvd/pktcdvd[0-7]/
+
+    ====            ====== ====================================
     info            (0444) Lots of driver statistics and infos.
+    ====            ====== ====================================
 
-Example:
--------
+Example::
 
-cat /sys/kernel/debug/pktcdvd/pktcdvd0/info
+    cat /sys/kernel/debug/pktcdvd/pktcdvd0/info
diff --git a/Documentation/ABI/testing/dev-kmsg b/Documentation/ABI/testing/dev-kmsg
index 3c0bb76e3417..a377b6c093c9 100644
--- a/Documentation/ABI/testing/dev-kmsg
+++ b/Documentation/ABI/testing/dev-kmsg
@@ -6,6 +6,7 @@ Description:	The /dev/kmsg character device node provides userspace access
 		to the kernel's printk buffer.
 
 		Injecting messages:
+
 		Every write() to the opened device node places a log entry in
 		the kernel's printk buffer.
 
@@ -21,6 +22,7 @@ Description:	The /dev/kmsg character device node provides userspace access
 		the messages can always be reliably determined.
 
 		Accessing the buffer:
+
 		Every read() from the opened device node receives one record
 		of the kernel's printk buffer.
 
@@ -48,6 +50,7 @@ Description:	The /dev/kmsg character device node provides userspace access
 		if needed, without limiting the interface to a single reader.
 
 		The device supports seek with the following parameters:
+
 		SEEK_SET, 0
 		  seek to the first entry in the buffer
 		SEEK_END, 0
@@ -87,18 +90,22 @@ Description:	The /dev/kmsg character device node provides userspace access
 		readable context of the message, for reliable processing in
 		userspace.
 
-		Example:
-		7,160,424069,-;pci_root PNP0A03:00: host bridge window [io  0x0000-0x0cf7] (ignored)
-		 SUBSYSTEM=acpi
-		 DEVICE=+acpi:PNP0A03:00
-		6,339,5140900,-;NET: Registered protocol family 10
-		30,340,5690716,-;udevd[80]: starting version 181
+		Example::
+
+		  7,160,424069,-;pci_root PNP0A03:00: host bridge window [io  0x0000-0x0cf7] (ignored)
+		   SUBSYSTEM=acpi
+		   DEVICE=+acpi:PNP0A03:00
+		  6,339,5140900,-;NET: Registered protocol family 10
+		  30,340,5690716,-;udevd[80]: starting version 181
 
 		The DEVICE= key uniquely identifies devices the following way:
-		  b12:8        - block dev_t
-		  c127:3       - char dev_t
-		  n8           - netdev ifindex
-		  +sound:card0 - subsystem:devname
+
+		  ============  =================
+		  b12:8         block dev_t
+		  c127:3        char dev_t
+		  n8            netdev ifindex
+		  +sound:card0  subsystem:devname
+		  ============  =================
 
 		The flags field carries '-' by default. A 'c' indicates a
 		fragment of a line. Note, that these hints about continuation
diff --git a/Documentation/ABI/testing/evm b/Documentation/ABI/testing/evm
index 201d10319fa1..3c477ba48a31 100644
--- a/Documentation/ABI/testing/evm
+++ b/Documentation/ABI/testing/evm
@@ -17,26 +17,33 @@ Description:
 		echoing a value to <securityfs>/evm made up of the
 		following bits:
 
+		===	  ==================================================
 		Bit	  Effect
+		===	  ==================================================
 		0	  Enable HMAC validation and creation
 		1	  Enable digital signature validation
 		2	  Permit modification of EVM-protected metadata at
 			  runtime. Not supported if HMAC validation and
 			  creation is enabled.
 		31	  Disable further runtime modification of EVM policy
+		===	  ==================================================
 
-		For example:
+		For example::
 
-		echo 1 ><securityfs>/evm
+		  echo 1 ><securityfs>/evm
 
 		will enable HMAC validation and creation
 
-		echo 0x80000003 ><securityfs>/evm
+		::
+
+		  echo 0x80000003 ><securityfs>/evm
 
 		will enable HMAC and digital signature validation and
 		HMAC creation and disable all further modification of policy.
 
-		echo 0x80000006 ><securityfs>/evm
+		::
+
+		  echo 0x80000006 ><securityfs>/evm
 
 		will enable digital signature validation, permit
 		modification of EVM-protected metadata and
@@ -65,7 +72,7 @@ Description:
 		Shows the set of extended attributes used to calculate or
 		validate the EVM signature, and allows additional attributes
 		to be added at runtime. Any signatures generated after
-		additional attributes are added (and on files posessing those
+		additional attributes are added (and on files possessing those
 		additional attributes) will only be valid if the same
 		additional attributes are configured on system boot. Writing
 		a single period (.) will lock the xattr list from any further
diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy
index cd572912c593..e35263f97fc1 100644
--- a/Documentation/ABI/testing/ima_policy
+++ b/Documentation/ABI/testing/ima_policy
@@ -15,19 +15,22 @@ Description:
 		IMA appraisal, if configured, uses these file measurements
 		for local measurement appraisal.
 
-		rule format: action [condition ...]
+		::
 
-		action: measure | dont_measure | appraise | dont_appraise |
-			audit | hash | dont_hash
-		condition:= base | lsm  [option]
+		  rule format: action [condition ...]
+
+		  action: measure | dont_measure | appraise | dont_appraise |
+			  audit | hash | dont_hash
+		  condition:= base | lsm  [option]
 			base:	[[func=] [mask=] [fsmagic=] [fsuuid=] [uid=]
 				[euid=] [fowner=] [fsname=]]
 			lsm:	[[subj_user=] [subj_role=] [subj_type=]
 				 [obj_user=] [obj_role=] [obj_type=]]
 			option:	[[appraise_type=]] [template=] [permit_directio]
 				[appraise_flag=] [keyrings=]
-		base: 	func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK][MODULE_CHECK]
-				[FIRMWARE_CHECK]
+		  base:
+			func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK]MODULE_CHECK]
+			        [FIRMWARE_CHECK]
 				[KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK]
 				[KEXEC_CMDLINE] [KEY_CHECK]
 			mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND]
@@ -37,8 +40,9 @@ Description:
 			uid:= decimal value
 			euid:= decimal value
 			fowner:= decimal value
-		lsm:  	are LSM specific
-		option:	appraise_type:= [imasig] [imasig|modsig]
+		  lsm:  are LSM specific
+		  option:
+			appraise_type:= [imasig] [imasig|modsig]
 			appraise_flag:= [check_blacklist]
 			Currently, blacklist check is only for files signed with appended
 			signature.
@@ -49,7 +53,7 @@ Description:
 			(eg, ima-ng). Only valid when action is "measure".
 			pcr:= decimal value
 
-		default policy:
+		  default policy:
 			# PROC_SUPER_MAGIC
 			dont_measure fsmagic=0x9fa0
 			dont_appraise fsmagic=0x9fa0
@@ -97,7 +101,8 @@ Description:
 
 		Examples of LSM specific definitions:
 
-		SELinux:
+		SELinux::
+
 			dont_measure obj_type=var_log_t
 			dont_appraise obj_type=var_log_t
 			dont_measure obj_type=auditd_log_t
@@ -105,10 +110,11 @@ Description:
 			measure subj_user=system_u func=FILE_CHECK mask=MAY_READ
 			measure subj_role=system_r func=FILE_CHECK mask=MAY_READ
 
-		Smack:
+		Smack::
+
 			measure subj_user=_ func=FILE_CHECK mask=MAY_READ
 
-		Example of measure rules using alternate PCRs:
+		Example of measure rules using alternate PCRs::
 
 			measure func=KEXEC_KERNEL_CHECK pcr=4
 			measure func=KEXEC_INITRAMFS_CHECK pcr=5
diff --git a/Documentation/ABI/testing/procfs-diskstats b/Documentation/ABI/testing/procfs-diskstats
index 70dcaf2481f4..df5a3a8c1edf 100644
--- a/Documentation/ABI/testing/procfs-diskstats
+++ b/Documentation/ABI/testing/procfs-diskstats
@@ -6,28 +6,32 @@ Description:
 		of block devices. Each line contains the following 14
 		fields:
 
-		 1 - major number
-		 2 - minor mumber
-		 3 - device name
-		 4 - reads completed successfully
-		 5 - reads merged
-		 6 - sectors read
-		 7 - time spent reading (ms)
-		 8 - writes completed
-		 9 - writes merged
-		10 - sectors written
-		11 - time spent writing (ms)
-		12 - I/Os currently in progress
-		13 - time spent doing I/Os (ms)
-		14 - weighted time spent doing I/Os (ms)
+		==  ===================================
+		 1  major number
+		 2  minor mumber
+		 3  device name
+		 4  reads completed successfully
+		 5  reads merged
+		 6  sectors read
+		 7  time spent reading (ms)
+		 8  writes completed
+		 9  writes merged
+		10  sectors written
+		11  time spent writing (ms)
+		12  I/Os currently in progress
+		13  time spent doing I/Os (ms)
+		14  weighted time spent doing I/Os (ms)
+		==  ===================================
 
 		Kernel 4.18+ appends four more fields for discard
 		tracking putting the total at 18:
 
-		15 - discards completed successfully
-		16 - discards merged
-		17 - sectors discarded
-		18 - time spent discarding
+		==  ===================================
+		15  discards completed successfully
+		16  discards merged
+		17  sectors discarded
+		18  time spent discarding
+		==  ===================================
 
 		Kernel 5.5+ appends two more fields for flush requests:
 
diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block
index 2322eb748b38..e34cdeeeb9d4 100644
--- a/Documentation/ABI/testing/sysfs-block
+++ b/Documentation/ABI/testing/sysfs-block
@@ -4,23 +4,27 @@ Contact:	Jerome Marchand <jmarchan@redhat.com>
 Description:
 		The /sys/block/<disk>/stat files displays the I/O
 		statistics of disk <disk>. They contain 11 fields:
-		 1 - reads completed successfully
-		 2 - reads merged
-		 3 - sectors read
-		 4 - time spent reading (ms)
-		 5 - writes completed
-		 6 - writes merged
-		 7 - sectors written
-		 8 - time spent writing (ms)
-		 9 - I/Os currently in progress
-		10 - time spent doing I/Os (ms)
-		11 - weighted time spent doing I/Os (ms)
-		12 - discards completed
-		13 - discards merged
-		14 - sectors discarded
-		15 - time spent discarding (ms)
-		16 - flush requests completed
-		17 - time spent flushing (ms)
+
+		==  ==============================================
+		 1  reads completed successfully
+		 2  reads merged
+		 3  sectors read
+		 4  time spent reading (ms)
+		 5  writes completed
+		 6  writes merged
+		 7  sectors written
+		 8  time spent writing (ms)
+		 9  I/Os currently in progress
+		10  time spent doing I/Os (ms)
+		11  weighted time spent doing I/Os (ms)
+		12  discards completed
+		13  discards merged
+		14  sectors discarded
+		15  time spent discarding (ms)
+		16  flush requests completed
+		17  time spent flushing (ms)
+		==  ==============================================
+
 		For more details refer Documentation/admin-guide/iostats.rst
 
 
diff --git a/Documentation/ABI/testing/sysfs-block-device b/Documentation/ABI/testing/sysfs-block-device
index 17f2bc7dd261..aa0fb500e3c9 100644
--- a/Documentation/ABI/testing/sysfs-block-device
+++ b/Documentation/ABI/testing/sysfs-block-device
@@ -8,11 +8,13 @@ Description:
 
 		It has the following valid values:
 
+		==	========================================================
 		0	OFF - the LED is not activated on activity
 		1	BLINK_ON - the LED blinks on every 10ms when activity is
 			detected.
 		2	BLINK_OFF - the LED is on when idle, and blinks off
 			every 10ms when activity is detected.
+		==	========================================================
 
 		Note that the user must turn sw_activity OFF it they wish to
 		control the activity LED via the em_message file.
diff --git a/Documentation/ABI/testing/sysfs-bus-acpi b/Documentation/ABI/testing/sysfs-bus-acpi
index e7898cfe5fb1..c78603497b97 100644
--- a/Documentation/ABI/testing/sysfs-bus-acpi
+++ b/Documentation/ABI/testing/sysfs-bus-acpi
@@ -67,14 +67,16 @@ Description:
 		The return value is a decimal integer representing the device's
 		status bitmap:
 
-		Bit [0] –  Set if the device is present.
-		Bit [1] –  Set if the device is enabled and decoding its
-		           resources.
-		Bit [2] –  Set if the device should be shown in the UI.
-		Bit [3] –  Set if the device is functioning properly (cleared if
-		           device failed its diagnostics).
-		Bit [4] –  Set if the battery is present.
-		Bits [31:5] –  Reserved (must be cleared)
+		===========  ==================================================
+		Bit [0]      Set if the device is present.
+		Bit [1]      Set if the device is enabled and decoding its
+		             resources.
+		Bit [2]      Set if the device should be shown in the UI.
+		Bit [3]      Set if the device is functioning properly (cleared
+			     if device failed its diagnostics).
+		Bit [4]      Set if the battery is present.
+		Bits [31:5]  Reserved (must be cleared)
+		===========  ==================================================
 
 		If bit [0] is clear, then bit 1 must also be clear (a device
 		that is not present cannot be enabled).
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
index 5bb793ec926c..df7ccc1b2fba 100644
--- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
@@ -10,7 +10,8 @@ Description:
 		name/value pairs.
 
 		Userspace must be prepared for the possibility that attributes
-		define overlapping bit ranges. For example:
+		define overlapping bit ranges. For example::
+
 			attr1 = 'config:0-23'
 			attr2 = 'config:0-7'
 			attr3 = 'config:12-35'
diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x b/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x
index 0b0de8cd0d13..b6c69eb80ca4 100644
--- a/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x
+++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-pca954x
@@ -6,15 +6,18 @@ Description:
 		Value that exists only for mux devices that can be
 		written to control the behaviour of the multiplexer on
 		idle. Possible values:
-		-2 - disconnect on idle, i.e. deselect the last used
-		     channel, which is useful when there is a device
-		     with an address that conflicts with another
-		     device on another mux on the same parent bus.
-		-1 - leave the mux as-is, which is the most optimal
-		     setting in terms of I2C operations and is the
-		     default mode.
-		0..<nchans> - set the mux to a predetermined channel,
-		     which is useful if there is one channel that is
-		     used almost always, and you want to reduce the
-		     latency for normal operations after rare
-		     transactions on other channels
+
+		===========  ===============================================
+		-2	     disconnect on idle, i.e. deselect the last used
+			     channel, which is useful when there is a device
+			     with an address that conflicts with another
+			     device on another mux on the same parent bus.
+		-1	     leave the mux as-is, which is the most optimal
+			     setting in terms of I2C operations and is the
+			     default mode.
+		0..<nchans>  set the mux to a predetermined channel,
+			     which is useful if there is one channel that is
+			     used almost always, and you want to reduce the
+			     latency for normal operations after rare
+			     transactions on other channels
+		===========  ===============================================
diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index a9d51810a3ba..e3df71987eff 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -65,6 +65,7 @@ Contact:	linux-iio@vger.kernel.org
 Description:
 		When the internal sampling clock can only take a specific set of
 		frequencies, we can specify the available values with:
+
 		- a small discrete set of values like "0 2 4 6 8"
 		- a range with minimum, step and maximum frequencies like
 		  "[min step max]"
@@ -1627,17 +1628,21 @@ Description:
 		Mounting matrix for IIO sensors. This is a rotation matrix which
 		informs userspace about sensor chip's placement relative to the
 		main hardware it is mounted on.
+
 		Main hardware placement is defined according to the local
 		reference frame related to the physical quantity the sensor
 		measures.
+
 		Given that the rotation matrix is defined in a board specific
 		way (platform data and / or device-tree), the main hardware
 		reference frame definition is left to the implementor's choice
 		(see below for a magnetometer example).
+
 		Applications should apply this rotation matrix to samples so
 		that when main hardware reference frame is aligned onto local
 		reference frame, then sensor chip reference frame is also
 		perfectly aligned with it.
+
 		Matrix is a 3x3 unitary matrix and typically looks like
 		[0, 1, 0; 1, 0, 0; 0, 0, -1]. Identity matrix
 		[1, 0, 0; 0, 1, 0; 0, 0, 1] means sensor chip and main hardware
@@ -1646,8 +1651,10 @@ Description:
 		For example, a mounting matrix for a magnetometer sensor informs
 		userspace about sensor chip's ORIENTATION relative to the main
 		hardware.
+
 		More specifically, main hardware orientation is defined with
 		respect to the LOCAL EARTH GEOMAGNETIC REFERENCE FRAME where :
+
 		* Y is in the ground plane and positive towards magnetic North ;
 		* X is in the ground plane, perpendicular to the North axis and
 		  positive towards the East ;
@@ -1656,13 +1663,16 @@ Description:
 		An implementor might consider that for a hand-held device, a
 		'natural' orientation would be 'front facing camera at the top'.
 		The main hardware reference frame could then be described as :
+
 		* Y is in the plane of the screen and is positive towards the
 		  top of the screen ;
 		* X is in the plane of the screen, perpendicular to Y axis, and
 		  positive towards the right hand side of the screen ;
 		* Z is perpendicular to the screen plane and positive out of the
 		  screen.
+
 		Another example for a quadrotor UAV might be :
+
 		* Y is in the plane of the propellers and positive towards the
 		  front-view camera;
 		* X is in the plane of the propellers, perpendicular to Y axis,
@@ -1704,6 +1714,7 @@ Description:
 		This interface is deprecated; please use the Counter subsystem.
 
 		A list of possible counting directions which are:
+
 		- "up"	: counter device is increasing.
 		- "down": counter device is decreasing.
 
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector b/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector
index 2071f9bcfaa5..1c2a07f7a75e 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-envelope-detector
@@ -5,7 +5,8 @@ Contact:	Peter Rosin <peda@axentia.se>
 Description:
 		The DAC is used to find the peak level of an alternating
 		voltage input signal by a binary search using the output
-		of a comparator wired to an interrupt pin. Like so:
+		of a comparator wired to an interrupt pin. Like so::
+
 		                           _
 		                          | \
 		     input +------>-------|+ \
@@ -19,10 +20,12 @@ Description:
 		            |    irq|------<-------'
 		            |       |
 		            '-------'
+
 		The boolean invert attribute (0/1) should be set when the
 		input signal is centered around the maximum value of the
 		dac instead of zero. The envelope detector will search
 		from below in this case and will also invert the result.
+
 		The edge/level of the interrupt is also switched to its
 		opposite value.
 
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-cros-ec b/Documentation/ABI/testing/sysfs-bus-iio-cros-ec
index 6158f831c761..adf24c40126f 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-cros-ec
+++ b/Documentation/ABI/testing/sysfs-bus-iio-cros-ec
@@ -4,7 +4,7 @@ KernelVersion:	4.7
 Contact:	linux-iio@vger.kernel.org
 Description:
 		Writing '1' will perform a FOC (Fast Online Calibration). The
-                corresponding calibration offsets can be read from *_calibbias
+                corresponding calibration offsets can be read from `*_calibbias`
                 entries.
 
 What:		/sys/bus/iio/devices/iio:deviceX/location
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32
index 0e66ae9b0071..91439d6d60b5 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32
+++ b/Documentation/ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32
@@ -3,14 +3,20 @@ KernelVersion:	4.14
 Contact:	arnaud.pouliquen@st.com
 Description:
 		For audio purpose only.
+
 		Used by audio driver to set/get the spi input frequency.
+
 		This is mandatory if DFSDM is slave on SPI bus, to
 		provide information on the SPI clock frequency during runtime
 		Notice that the SPI frequency should be a multiple of sample
 		frequency to ensure the precision.
-		if DFSDM input is SPI master
+
+		if DFSDM input is SPI master:
+
 			Reading  SPI clkout frequency,
 			error on writing
+
 		If DFSDM input is SPI Slave:
+
 			Reading returns value previously set.
 			Writing value before starting conversions.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32
index ad2cc63e4bf8..73498ff666bd 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32
+++ b/Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32
@@ -17,9 +17,11 @@ KernelVersion:	4.13
 Contact:	fabrice.gasnier@st.com
 Description:
 		Configure the device counter quadrature modes:
+
 		- non-quadrature:
 			Encoder IN1 input servers as the count input (up
 			direction).
+
 		- quadrature:
 			Encoder IN1 and IN2 inputs are mixed to get direction
 			and count.
@@ -35,23 +37,26 @@ KernelVersion:	4.13
 Contact:	fabrice.gasnier@st.com
 Description:
 		Configure the device encoder/counter active edge:
+
 		- rising-edge
 		- falling-edge
 		- both-edges
 
 		In non-quadrature mode, device counts up on active edge.
+
 		In quadrature mode, encoder counting scenarios are as follows:
-		----------------------------------------------------------------
+
+		+---------+----------+--------------------+--------------------+
 		| Active  | Level on |      IN1 signal    |     IN2 signal     |
-		| edge    | opposite |------------------------------------------
+		| edge    | opposite +----------+---------+----------+---------+
 		|         | signal   |  Rising  | Falling |  Rising  | Falling |
-		----------------------------------------------------------------
-		| Rising  | High ->  |   Down   |    -    |    Up    |    -    |
-		| edge    | Low  ->  |    Up    |    -    |   Down   |    -    |
-		----------------------------------------------------------------
-		| Falling | High ->  |    -     |    Up   |    -     |   Down  |
-		| edge    | Low  ->  |    -     |   Down  |    -     |    Up   |
-		----------------------------------------------------------------
-		| Both    | High ->  |   Down   |    Up   |    Up    |   Down  |
-		| edges   | Low  ->  |    Up    |   Down  |   Down   |    Up   |
-		----------------------------------------------------------------
+		+---------+----------+----------+---------+----------+---------+
+		| Rising  | High ->  |   Down   |    -    |   Up     |    -    |
+		| edge    | Low  ->  |   Up     |    -    |   Down   |    -    |
+		+---------+----------+----------+---------+----------+---------+
+		| Falling | High ->  |    -     |   Up    |    -     |   Down  |
+		| edge    | Low  ->  |    -     |   Down  |    -     |   Up    |
+		+---------+----------+----------+---------+----------+---------+
+		| Both    | High ->  |   Down   |   Up    |   Up     |   Down  |
+		| edges   | Low  ->  |   Up     |   Down  |   Down   |   Up    |
+		+---------+----------+----------+---------+----------+---------+
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843 b/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843
index 6275e9f56e6c..13f099ef6a95 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843
+++ b/Documentation/ABI/testing/sysfs-bus-iio-magnetometer-hmc5843
@@ -5,11 +5,16 @@ Contact:        linux-iio@vger.kernel.org
 Description:
                 Current configuration and available configurations
 		for the bias current.
-		normal		- Normal measurement configurations (default)
-		positivebias	- Positive bias configuration
-		negativebias	- Negative bias configuration
-		disabled	- Only available on HMC5983. Disables magnetic
+
+		============	  ============================================
+		normal		  Normal measurement configurations (default)
+		positivebias	  Positive bias configuration
+		negativebias	  Negative bias configuration
+		disabled	  Only available on HMC5983. Disables magnetic
 				  sensor and enables temperature sensor.
-		Note: The effect of this configuration may vary
-		according to the device. For exact documentation
-		check the device's datasheet.
+		============	  ============================================
+
+		Note:
+		  The effect of this configuration may vary
+		  according to the device. For exact documentation
+		  check the device's datasheet.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856 b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856
index 3b3509a3ef2f..e5ef6d8e5da1 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856
+++ b/Documentation/ABI/testing/sysfs-bus-iio-temperature-max31856
@@ -5,9 +5,12 @@ Description:
 		Open-circuit fault. The detection of open-circuit faults,
 		such as those caused by broken thermocouple wires.
 		Reading returns either '1' or '0'.
-		'1' = An open circuit such as broken thermocouple wires
-		      has been detected.
-		'0' = No open circuit or broken thermocouple wires are detected
+
+		===  =======================================================
+		'1'  An open circuit such as broken thermocouple wires
+		     has been detected.
+		'0'  No open circuit or broken thermocouple wires are detected
+		===  =======================================================
 
 What:		/sys/bus/iio/devices/iio:deviceX/fault_ovuv
 KernelVersion:	5.1
@@ -18,7 +21,11 @@ Description:
 		cables by integrated MOSFETs at the T+ and T- inputs, and the
 		BIAS output. These MOSFETs turn off when the input voltage is
 		negative or greater than VDD.
+
 		Reading returns either '1' or '0'.
-		'1' = The input voltage is negative or greater than VDD.
-		'0' = The input voltage is positive and less than VDD (normal
-		state).
+
+		===  =======================================================
+		'1'  The input voltage is negative or greater than VDD.
+		'0'  The input voltage is positive and less than VDD (normal
+		     state).
+		===  =======================================================
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
index b7259234ad70..a10a4de3e5fe 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
+++ b/Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
@@ -3,67 +3,85 @@ KernelVersion:	4.11
 Contact:	benjamin.gaignard@st.com
 Description:
 		Reading returns the list possible master modes which are:
-		- "reset"     :	The UG bit from the TIMx_EGR register is
+
+
+		- "reset"
+				The UG bit from the TIMx_EGR register is
 				used as trigger output (TRGO).
-		- "enable"    : The Counter Enable signal CNT_EN is used
+		- "enable"
+				The Counter Enable signal CNT_EN is used
 				as trigger output.
-		- "update"    : The update event is selected as trigger output.
+		- "update"
+				The update event is selected as trigger output.
 				For instance a master timer can then be used
 				as a prescaler for a slave timer.
-		- "compare_pulse" : The trigger output send a positive pulse
-				    when the CC1IF flag is to be set.
-		- "OC1REF"    : OC1REF signal is used as trigger output.
-		- "OC2REF"    : OC2REF signal is used as trigger output.
-		- "OC3REF"    : OC3REF signal is used as trigger output.
-		- "OC4REF"    : OC4REF signal is used as trigger output.
+		- "compare_pulse"
+				The trigger output send a positive pulse
+				when the CC1IF flag is to be set.
+		- "OC1REF"
+				OC1REF signal is used as trigger output.
+		- "OC2REF"
+				OC2REF signal is used as trigger output.
+		- "OC3REF"
+				OC3REF signal is used as trigger output.
+		- "OC4REF"
+				OC4REF signal is used as trigger output.
+
 		Additional modes (on TRGO2 only):
-		- "OC5REF"    : OC5REF signal is used as trigger output.
-		- "OC6REF"    : OC6REF signal is used as trigger output.
+
+		- "OC5REF"
+				OC5REF signal is used as trigger output.
+		- "OC6REF"
+				OC6REF signal is used as trigger output.
 		- "compare_pulse_OC4REF":
-		  OC4REF rising or falling edges generate pulses.
+				OC4REF rising or falling edges generate pulses.
 		- "compare_pulse_OC6REF":
-		  OC6REF rising or falling edges generate pulses.
+				OC6REF rising or falling edges generate pulses.
 		- "compare_pulse_OC4REF_r_or_OC6REF_r":
-		  OC4REF or OC6REF rising edges generate pulses.
+				OC4REF or OC6REF rising edges generate pulses.
 		- "compare_pulse_OC4REF_r_or_OC6REF_f":
-		  OC4REF rising or OC6REF falling edges generate pulses.
+				OC4REF rising or OC6REF falling edges generate
+				pulses.
 		- "compare_pulse_OC5REF_r_or_OC6REF_r":
-		  OC5REF or OC6REF rising edges generate pulses.
+				OC5REF or OC6REF rising edges generate pulses.
 		- "compare_pulse_OC5REF_r_or_OC6REF_f":
-		  OC5REF rising or OC6REF falling edges generate pulses.
+				OC5REF rising or OC6REF falling edges generate
+				pulses.
 
-		+-----------+   +-------------+            +---------+
-		| Prescaler +-> | Counter     |        +-> | Master  | TRGO(2)
-		+-----------+   +--+--------+-+        |-> | Control +-->
-		                   |        |          ||  +---------+
-		                +--v--------+-+ OCxREF ||  +---------+
-		                | Chx compare +----------> | Output  | ChX
-		                +-----------+-+         |  | Control +-->
-		                      .     |           |  +---------+
-		                      .     |           |    .
-		                +-----------v-+ OC6REF  |    .
-		                | Ch6 compare +---------+>
-		                +-------------+
+		::
 
-		Example with: "compare_pulse_OC4REF_r_or_OC6REF_r":
+		  +-----------+   +-------------+            +---------+
+		  | Prescaler +-> | Counter     |        +-> | Master  | TRGO(2)
+		  +-----------+   +--+--------+-+        |-> | Control +-->
+		                     |        |          ||  +---------+
+		                  +--v--------+-+ OCxREF ||  +---------+
+		                  | Chx compare +----------> | Output  | ChX
+		                  +-----------+-+         |  | Control +-->
+		                        .     |           |  +---------+
+		                        .     |           |    .
+		                  +-----------v-+ OC6REF  |    .
+		                  | Ch6 compare +---------+>
+		                  +-------------+
 
-		                X
-		              X   X
-		            X .   . X
-		          X   .   .   X
-		        X     .   .     X
-		count X .     .   .     . X
-		        .     .   .     .
-		        .     .   .     .
-		        +---------------+
-		OC4REF  |     .   .     |
-		      +-+     .   .     +-+
-		        .     +---+     .
-		OC6REF  .     |   |     .
-		      +-------+   +-------+
-		        +-+   +-+
-		TRGO2   | |   | |
-		      +-+ +---+ +---------+
+		Example with: "compare_pulse_OC4REF_r_or_OC6REF_r"::
+
+		                  X
+		                X   X
+		              X .   . X
+		            X   .   .   X
+		          X     .   .     X
+		  count X .     .   .     . X
+		          .     .   .     .
+		          .     .   .     .
+		          +---------------+
+		  OC4REF  |     .   .     |
+		        +-+     .   .     +-+
+		          .     +---+     .
+		  OC6REF  .     |   |     .
+		        +-------+   +-------+
+		          +-+   +-+
+		  TRGO2   | |   | |
+		        +-+ +---+ +---------+
 
 What:		/sys/bus/iio/devices/triggerX/master_mode
 KernelVersion:	4.11
@@ -91,6 +109,30 @@ Description:
 		When counting down the counter start from preset value
 		and fire event when reach 0.
 
+What:		/sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
+KernelVersion:	4.12
+Contact:	benjamin.gaignard@st.com
+Description:
+		Reading returns the list possible quadrature modes.
+
+What:		/sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode
+KernelVersion:	4.12
+Contact:	benjamin.gaignard@st.com
+Description:
+		Configure the device counter quadrature modes:
+
+		channel_A:
+			Encoder A input servers as the count input and B as
+			the UP/DOWN direction control input.
+
+		channel_B:
+			Encoder B input serves as the count input and A as
+			the UP/DOWN direction control input.
+
+		quadrature:
+			Encoder A and B inputs are mixed to get direction
+			and count with a scale of 0.25.
+
 What:		/sys/bus/iio/devices/iio:deviceX/in_count_enable_mode_available
 KernelVersion:	4.12
 Contact:	benjamin.gaignard@st.com
@@ -104,6 +146,7 @@ Description:
 		Configure the device counter enable modes, in all case
 		counting direction is set by in_count0_count_direction
 		attribute and the counter is clocked by the internal clock.
+
 		always:
 			Counter is always ON.
 
diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc
index 7fd2601c2831..a74252e580a5 100644
--- a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc
+++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc
@@ -9,11 +9,13 @@ Date:		June 2015
 KernelVersion:	4.3
 Contact:	Alexander Shishkin <alexander.shishkin@linux.intel.com>
 Description:	(RW) Configure MSC operating mode:
+
 		  - "single", for contiguous buffer mode (high-order alloc);
 		  - "multi", for multiblock mode;
 		  - "ExI", for DCI handler mode;
 		  - "debug", for debug mode;
 		  - any of the currently loaded buffer sinks.
+
 		If operating mode changes, existing buffer is deallocated,
 		provided there are no active users and tracing is not enabled,
 		otherwise the write will fail.
@@ -23,10 +25,12 @@ Date:		June 2015
 KernelVersion:	4.3
 Contact:	Alexander Shishkin <alexander.shishkin@linux.intel.com>
 Description:	(RW) Configure MSC buffer size for "single" or "multi" modes.
+
 		In single mode, this is a single number of pages, has to be
 		power of 2. In multiblock mode, this is a comma-separated list
 		of numbers of pages for each window to be allocated. Number of
 		windows is not limited.
+
 		Writing to this file deallocates existing buffer (provided
 		there are no active users and tracing is not enabled) and then
 		allocates a new one.
diff --git a/Documentation/ABI/testing/sysfs-bus-nfit b/Documentation/ABI/testing/sysfs-bus-nfit
index e4f76e7eab93..63ef0b9ecce7 100644
--- a/Documentation/ABI/testing/sysfs-bus-nfit
+++ b/Documentation/ABI/testing/sysfs-bus-nfit
@@ -1,4 +1,4 @@
-For all of the nmem device attributes under nfit/*, see the 'NVDIMM Firmware
+For all of the nmem device attributes under ``nfit/*``, see the 'NVDIMM Firmware
 Interface Table (NFIT)' section in the ACPI specification
 (http://www.uefi.org/specifications) for more details.
 
diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats b/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats
index 3c9a8c4a25eb..860db53037a5 100644
--- a/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats
+++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats
@@ -1,6 +1,6 @@
-==========================
 PCIe Device AER statistics
-==========================
+--------------------------
+
 These attributes show up under all the devices that are AER capable. These
 statistical counters indicate the errors "as seen/reported by the device".
 Note that this may mean that if an endpoint is causing problems, the AER
@@ -17,19 +17,18 @@ Description:	List of correctable errors seen and reported by this
 		PCI device using ERR_COR. Note that since multiple errors may
 		be reported using a single ERR_COR message, thus
 		TOTAL_ERR_COR at the end of the file may not match the actual
-		total of all the errors in the file. Sample output:
--------------------------------------------------------------------------
-localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_correctable
-Receiver Error 2
-Bad TLP 0
-Bad DLLP 0
-RELAY_NUM Rollover 0
-Replay Timer Timeout 0
-Advisory Non-Fatal 0
-Corrected Internal Error 0
-Header Log Overflow 0
-TOTAL_ERR_COR 2
--------------------------------------------------------------------------
+		total of all the errors in the file. Sample output::
+
+		    localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_correctable
+		    Receiver Error 2
+		    Bad TLP 0
+		    Bad DLLP 0
+		    RELAY_NUM Rollover 0
+		    Replay Timer Timeout 0
+		    Advisory Non-Fatal 0
+		    Corrected Internal Error 0
+		    Header Log Overflow 0
+		    TOTAL_ERR_COR 2
 
 What:		/sys/bus/pci/devices/<dev>/aer_dev_fatal
 Date:		July 2018
@@ -39,28 +38,27 @@ Description:	List of uncorrectable fatal errors seen and reported by this
 		PCI device using ERR_FATAL. Note that since multiple errors may
 		be reported using a single ERR_FATAL message, thus
 		TOTAL_ERR_FATAL at the end of the file may not match the actual
-		total of all the errors in the file. Sample output:
--------------------------------------------------------------------------
-localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_fatal
-Undefined 0
-Data Link Protocol 0
-Surprise Down Error 0
-Poisoned TLP 0
-Flow Control Protocol 0
-Completion Timeout 0
-Completer Abort 0
-Unexpected Completion 0
-Receiver Overflow 0
-Malformed TLP 0
-ECRC 0
-Unsupported Request 0
-ACS Violation 0
-Uncorrectable Internal Error 0
-MC Blocked TLP 0
-AtomicOp Egress Blocked 0
-TLP Prefix Blocked Error 0
-TOTAL_ERR_FATAL 0
--------------------------------------------------------------------------
+		total of all the errors in the file. Sample output::
+
+		    localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_fatal
+		    Undefined 0
+		    Data Link Protocol 0
+		    Surprise Down Error 0
+		    Poisoned TLP 0
+		    Flow Control Protocol 0
+		    Completion Timeout 0
+		    Completer Abort 0
+		    Unexpected Completion 0
+		    Receiver Overflow 0
+		    Malformed TLP 0
+		    ECRC 0
+		    Unsupported Request 0
+		    ACS Violation 0
+		    Uncorrectable Internal Error 0
+		    MC Blocked TLP 0
+		    AtomicOp Egress Blocked 0
+		    TLP Prefix Blocked Error 0
+		    TOTAL_ERR_FATAL 0
 
 What:		/sys/bus/pci/devices/<dev>/aer_dev_nonfatal
 Date:		July 2018
@@ -70,32 +68,31 @@ Description:	List of uncorrectable nonfatal errors seen and reported by this
 		PCI device using ERR_NONFATAL. Note that since multiple errors
 		may be reported using a single ERR_FATAL message, thus
 		TOTAL_ERR_NONFATAL at the end of the file may not match the
-		actual total of all the errors in the file. Sample output:
--------------------------------------------------------------------------
-localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_nonfatal
-Undefined 0
-Data Link Protocol 0
-Surprise Down Error 0
-Poisoned TLP 0
-Flow Control Protocol 0
-Completion Timeout 0
-Completer Abort 0
-Unexpected Completion 0
-Receiver Overflow 0
-Malformed TLP 0
-ECRC 0
-Unsupported Request 0
-ACS Violation 0
-Uncorrectable Internal Error 0
-MC Blocked TLP 0
-AtomicOp Egress Blocked 0
-TLP Prefix Blocked Error 0
-TOTAL_ERR_NONFATAL 0
--------------------------------------------------------------------------
+		actual total of all the errors in the file. Sample output::
+
+		    localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_nonfatal
+		    Undefined 0
+		    Data Link Protocol 0
+		    Surprise Down Error 0
+		    Poisoned TLP 0
+		    Flow Control Protocol 0
+		    Completion Timeout 0
+		    Completer Abort 0
+		    Unexpected Completion 0
+		    Receiver Overflow 0
+		    Malformed TLP 0
+		    ECRC 0
+		    Unsupported Request 0
+		    ACS Violation 0
+		    Uncorrectable Internal Error 0
+		    MC Blocked TLP 0
+		    AtomicOp Egress Blocked 0
+		    TLP Prefix Blocked Error 0
+		    TOTAL_ERR_NONFATAL 0
 
-============================
 PCIe Rootport AER statistics
-============================
+----------------------------
+
 These attributes show up under only the rootports (or root complex event
 collectors) that are AER capable. These indicate the number of error messages as
 "reported to" the rootport. Please note that the rootports also transmit
diff --git a/Documentation/ABI/testing/sysfs-bus-rapidio b/Documentation/ABI/testing/sysfs-bus-rapidio
index 13208b27dd87..634ea207a50a 100644
--- a/Documentation/ABI/testing/sysfs-bus-rapidio
+++ b/Documentation/ABI/testing/sysfs-bus-rapidio
@@ -4,24 +4,27 @@ Description:
 		an individual subdirectory with the following name format of
 		device_name "nn:d:iiii", where:
 
-		nn   - two-digit hexadecimal ID of RapidIO network where the
+		====   ========================================================
+		nn     two-digit hexadecimal ID of RapidIO network where the
 		       device resides
-		d    - device type: 'e' - for endpoint or 's' - for switch
-		iiii - four-digit device destID for endpoints, or switchID for
+		d      device type: 'e' - for endpoint or 's' - for switch
+		iiii   four-digit device destID for endpoints, or switchID for
 		       switches
+		====   ========================================================
 
 		For example, below is a list of device directories that
 		represents a typical RapidIO network with one switch, one host,
 		and two agent endpoints, as it is seen by the enumerating host
-		(with destID = 1):
+		(with destID = 1)::
 
-		/sys/bus/rapidio/devices/00:e:0000
-		/sys/bus/rapidio/devices/00:e:0002
-		/sys/bus/rapidio/devices/00:s:0001
+		  /sys/bus/rapidio/devices/00:e:0000
+		  /sys/bus/rapidio/devices/00:e:0002
+		  /sys/bus/rapidio/devices/00:s:0001
 
-		NOTE: An enumerating or discovering endpoint does not create a
-		sysfs entry for itself, this is why an endpoint with destID=1 is
-		not shown in the list.
+		NOTE:
+		  An enumerating or discovering endpoint does not create a
+		  sysfs entry for itself, this is why an endpoint with destID=1
+		  is not shown in the list.
 
 Attributes Common for All RapidIO Devices
 -----------------------------------------
diff --git a/Documentation/ABI/testing/sysfs-bus-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt
index dd565c378b40..171127294674 100644
--- a/Documentation/ABI/testing/sysfs-bus-thunderbolt
+++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt
@@ -37,16 +37,18 @@ Contact:	thunderbolt-software@lists.01.org
 Description:	This attribute holds current Thunderbolt security level
 		set by the system BIOS. Possible values are:
 
-		none: All devices are automatically authorized
-		user: Devices are only authorized based on writing
-		      appropriate value to the authorized attribute
-		secure: Require devices that support secure connect at
-			minimum. User needs to authorize each device.
-		dponly: Automatically tunnel Display port (and USB). No
-			PCIe tunnels are created.
-		usbonly: Automatically tunnel USB controller of the
+		=======  ==================================================
+		none     All devices are automatically authorized
+		user     Devices are only authorized based on writing
+		         appropriate value to the authorized attribute
+		secure   Require devices that support secure connect at
+			 minimum. User needs to authorize each device.
+		dponly   Automatically tunnel Display port (and USB). No
+			 PCIe tunnels are created.
+		usbonly  Automatically tunnel USB controller of the
 			 connected Thunderbolt dock (and Display Port). All
 			 PCIe links downstream of the dock are removed.
+		=======  ==================================================
 
 What: /sys/bus/thunderbolt/devices/.../authorized
 Date:		Sep 2017
@@ -61,17 +63,23 @@ Description:	This attribute is used to authorize Thunderbolt devices
 		yet authorized.
 
 		Possible values are supported:
-		1: The device will be authorized and connected
+
+		==  ===========================================
+		1   The device will be authorized and connected
+		==  ===========================================
 
 		When key attribute contains 32 byte hex string the possible
 		values are:
-		1: The 32 byte hex string is added to the device NVM and
-		   the device is authorized.
-		2: Send a challenge based on the 32 byte hex string. If the
-		   challenge response from device is valid, the device is
-		   authorized. In case of failure errno will be ENOKEY if
-		   the device did not contain a key at all, and
-		   EKEYREJECTED if the challenge response did not match.
+
+		==  ========================================================
+		1   The 32 byte hex string is added to the device NVM and
+		    the device is authorized.
+		2   Send a challenge based on the 32 byte hex string. If the
+		    challenge response from device is valid, the device is
+		    authorized. In case of failure errno will be ENOKEY if
+		    the device did not contain a key at all, and
+		    EKEYREJECTED if the challenge response did not match.
+		==  ========================================================
 
 What: /sys/bus/thunderbolt/devices/.../boot
 Date:		Jun 2018
diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb
index 614d216dff1d..e449b8374f6a 100644
--- a/Documentation/ABI/testing/sysfs-bus-usb
+++ b/Documentation/ABI/testing/sysfs-bus-usb
@@ -72,24 +72,27 @@ Description:
 		table at compile time. The format for the device ID is:
 		idVendor idProduct bInterfaceClass RefIdVendor RefIdProduct
 		The vendor ID and device ID fields are required, the
-		rest is optional. The Ref* tuple can be used to tell the
+		rest is optional. The `Ref*` tuple can be used to tell the
 		driver to use the same driver_data for the new device as
 		it is used for the reference device.
 		Upon successfully adding an ID, the driver will probe
-		for the device and attempt to bind to it.  For example:
-		# echo "8086 10f5" > /sys/bus/usb/drivers/foo/new_id
+		for the device and attempt to bind to it.  For example::
+
+		  # echo "8086 10f5" > /sys/bus/usb/drivers/foo/new_id
 
 		Here add a new device (0458:7045) using driver_data from
-		an already supported device (0458:704c):
-		# echo "0458 7045 0 0458 704c" > /sys/bus/usb/drivers/foo/new_id
+		an already supported device (0458:704c)::
+
+		  # echo "0458 7045 0 0458 704c" > /sys/bus/usb/drivers/foo/new_id
 
 		Reading from this file will list all dynamically added
 		device IDs in the same format, with one entry per
-		line. For example:
-		# cat /sys/bus/usb/drivers/foo/new_id
-		8086 10f5
-		dead beef 06
-		f00d cafe
+		line. For example::
+
+		  # cat /sys/bus/usb/drivers/foo/new_id
+		  8086 10f5
+		  dead beef 06
+		  f00d cafe
 
 		The list will be truncated at PAGE_SIZE bytes due to
 		sysfs restrictions.
@@ -209,6 +212,7 @@ Description:
 		advance, and behaves well according to the specification.
 		This attribute is a bit-field that controls the behavior of
 		a specific port:
+
 		 - Bit 0 of this field selects the "old" enumeration scheme,
 		   as it is considerably faster (it only causes one USB reset
 		   instead of 2).
@@ -233,10 +237,10 @@ Description:
 		poll() for monitoring changes to this value in user space.
 
 		Any time this value changes the corresponding hub device will send a
-		udev event with the following attributes:
+		udev event with the following attributes::
 
-		OVER_CURRENT_PORT=/sys/bus/usb/devices/.../(hub interface)/portX
-		OVER_CURRENT_COUNT=[current value of this sysfs attribute]
+		  OVER_CURRENT_PORT=/sys/bus/usb/devices/.../(hub interface)/portX
+		  OVER_CURRENT_COUNT=[current value of this sysfs attribute]
 
 What:		/sys/bus/usb/devices/.../(hub interface)/portX/usb3_lpm_permit
 Date:		November 2015
diff --git a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
index 9ade80f81f96..2f86e4223bfc 100644
--- a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
+++ b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
@@ -12,8 +12,11 @@ KernelVersion:	2.6.26
 Contact:	Harrison Metzger <harrisonmetz@gmail.com>
 Description:	Controls the devices display mode.
 		For a 6 character display the values are
+
 			MSB 0x06; LSB 0x3F, and
+
 		for an 8 character display the values are
+
 			MSB 0x08; LSB 0xFF.
 
 What:		/sys/bus/usb/.../textmode
@@ -37,7 +40,7 @@ KernelVersion:	2.6.26
 Contact:	Harrison Metzger <harrisonmetz@gmail.com>
 Description:	Controls the decimal places on the device.
 		To set the nth decimal place, give this field
-		the value of 10 ** n. Assume this field has
+		the value of ``10 ** n``. Assume this field has
 		the value k and has 1 or more decimal places set,
 		to set the mth place (where m is not already set),
-		change this fields value to k + 10 ** m.
+		change this fields value to ``k + 10 ** m``.
diff --git a/Documentation/ABI/testing/sysfs-bus-vfio-mdev b/Documentation/ABI/testing/sysfs-bus-vfio-mdev
index 452dbe39270e..59fc804265db 100644
--- a/Documentation/ABI/testing/sysfs-bus-vfio-mdev
+++ b/Documentation/ABI/testing/sysfs-bus-vfio-mdev
@@ -28,8 +28,9 @@ Description:
 		Writing UUID to this file will create mediated device of
 		type <type-id> for parent device <device>. This is a
 		write-only file.
-		For example:
-		# echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" >	\
+		For example::
+
+		  # echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" >	\
 		       /sys/devices/foo/mdev_supported_types/foo-1/create
 
 What:           /sys/.../mdev_supported_types/<type-id>/devices/
@@ -107,5 +108,6 @@ Description:
 		Writing '1' to this file destroys the mediated device. The
 		vendor driver can fail the remove() callback if that device
 		is active and the vendor driver doesn't support hot unplug.
-		Example:
-		# echo 1 > /sys/bus/mdev/devices/<UUID>/remove
+		Example::
+
+		  # echo 1 > /sys/bus/mdev/devices/<UUID>/remove
diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl
index 7970e3713e70..a6f51a104c44 100644
--- a/Documentation/ABI/testing/sysfs-class-cxl
+++ b/Documentation/ABI/testing/sysfs-class-cxl
@@ -72,11 +72,16 @@ Description:    read/write
                 when performing the START_WORK ioctl. Only applicable when
                 running under hashed page table mmu.
                 Possible values:
-                        none: No prefaulting (default)
-                        work_element_descriptor: Treat the work element
-                                 descriptor as an effective address and
-                                 prefault what it points to.
-                        all: all segments process calling START_WORK maps.
+
+                =======================  ======================================
+		none			 No prefaulting (default)
+		work_element_descriptor  Treat the work element
+					 descriptor as an effective address and
+					 prefault what it points to.
+                all			 all segments process calling
+					 START_WORK maps.
+                =======================  ======================================
+
 Users:		https://github.com/ibm-capi/libcxl
 
 What:           /sys/class/cxl/<afu>/reset
diff --git a/Documentation/ABI/testing/sysfs-class-led b/Documentation/ABI/testing/sysfs-class-led
index 5f67f7ab277b..65e040978f73 100644
--- a/Documentation/ABI/testing/sysfs-class-led
+++ b/Documentation/ABI/testing/sysfs-class-led
@@ -50,7 +50,7 @@ Description:
 		You can change triggers in a similar manner to the way an IO
 		scheduler is chosen. Trigger specific parameters can appear in
 		/sys/class/leds/<led> once a given trigger is selected. For
-		their documentation see sysfs-class-led-trigger-*.
+		their documentation see `sysfs-class-led-trigger-*`.
 
 What:		/sys/class/leds/<led>/inverted
 Date:		January 2011
diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-el15203000 b/Documentation/ABI/testing/sysfs-class-led-driver-el15203000
index f520ece9b64c..69befe947d7e 100644
--- a/Documentation/ABI/testing/sysfs-class-led-driver-el15203000
+++ b/Documentation/ABI/testing/sysfs-class-led-driver-el15203000
@@ -6,127 +6,132 @@ Description:
 		The LEDs board supports only predefined patterns by firmware
 		for specific LEDs.
 
-		Breathing mode for Screen frame light tube:
-		"0 4000 1 4000"
+		Breathing mode for Screen frame light tube::
 
-		    ^
-		    |
-		Max-|     ---
-		    |    /   \
-		    |   /     \
-		    |  /       \     /
-		    | /         \   /
-		Min-|-           ---
-		    |
-		    0------4------8--> time (sec)
+		    "0 4000 1 4000"
 
-		Cascade mode for Pipe LED:
-		"1 800 2 800 4 800 8 800 16 800"
+			^
+			|
+		    Max-|     ---
+			|    /   \
+			|   /     \
+			|  /       \     /
+			| /         \   /
+		    Min-|-           ---
+			|
+			0------4------8--> time (sec)
 
-		      ^
-		      |
-		0 On -|----+                   +----+                   +---
-		      |    |                   |    |                   |
-		  Off-|    +-------------------+    +-------------------+
-		      |
-		1 On -|    +----+                   +----+
-		      |    |    |                   |    |
-		  Off |----+    +-------------------+    +------------------
-		      |
-		2 On -|         +----+                   +----+
-		      |         |    |                   |    |
-		  Off-|---------+    +-------------------+    +-------------
-		      |
-		3 On -|              +----+                   +----+
-		      |              |    |                   |    |
-		  Off-|--------------+    +-------------------+    +--------
-		      |
-		4 On -|                   +----+                   +----+
-		      |                   |    |                   |    |
-		  Off-|-------------------+    +-------------------+    +---
-		      |
-		      0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
+		Cascade mode for Pipe LED::
 
-		Inverted cascade mode for Pipe LED:
-		"30 800 29 800 27 800 23 800 15 800"
+		    "1 800 2 800 4 800 8 800 16 800"
 
-		      ^
-		      |
-		0 On -|    +-------------------+    +-------------------+
-		      |    |                   |    |                   |
-		  Off-|----+                   +----+                   +---
-		      |
-		1 On -|----+    +-------------------+    +------------------
-		      |    |    |                   |    |
-		  Off |    +----+                   +----+
-		      |
-		2 On -|---------+    +-------------------+    +-------------
-		      |         |    |                   |    |
-		  Off-|         +----+                   +----+
-		      |
-		3 On -|--------------+    +-------------------+    +--------
-		      |              |    |                   |    |
-		  Off-|              +----+                   +----+
-		      |
-		4 On -|-------------------+    +-------------------+    +---
-		      |                   |    |                   |    |
-		  Off-|                   +----+                   +----+
-		      |
-		      0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
+			^
+			|
+		    0 On -|----+                   +----+                   +---
+			|    |                   |    |                   |
+		    Off-|    +-------------------+    +-------------------+
+			|
+		    1 On -|    +----+                   +----+
+			|    |    |                   |    |
+		    Off |----+    +-------------------+    +------------------
+			|
+		    2 On -|         +----+                   +----+
+			|         |    |                   |    |
+		    Off-|---------+    +-------------------+    +-------------
+			|
+		    3 On -|              +----+                   +----+
+			|              |    |                   |    |
+		    Off-|--------------+    +-------------------+    +--------
+			|
+		    4 On -|                   +----+                   +----+
+			|                   |    |                   |    |
+		    Off-|-------------------+    +-------------------+    +---
+			|
+			0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
 
-		Bounce mode for Pipe LED:
-		"1 800 2 800 4 800 8 800 16 800 16 800 8 800 4 800 2 800 1 800"
+		Inverted cascade mode for Pipe LED::
 
-		      ^
-		      |
-		0 On -|----+                                       +--------
-		      |    |                                       |
-		  Off-|    +---------------------------------------+
-		      |
-		1 On -|    +----+                             +----+
-		      |    |    |                             |    |
-		  Off |----+    +-----------------------------+    +--------
-		      |
-		2 On -|         +----+                   +----+
-		      |         |    |                   |    |
-		  Off-|---------+    +-------------------+    +-------------
-		      |
-		3 On -|              +----+         +----+
-		      |              |    |         |    |
-		  Off-|--------------+    +---------+    +------------------
-		      |
-		4 On -|                   +---------+
-		      |                   |         |
-		  Off-|-------------------+         +-----------------------
-		      |
-		      0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
+		    "30 800 29 800 27 800 23 800 15 800"
 
-		Inverted bounce mode for Pipe LED:
-		"30 800 29 800 27 800 23 800 15 800 15 800 23 800 27 800 29 800 30 800"
+			^
+			|
+		    0 On -|    +-------------------+    +-------------------+
+			|    |                   |    |                   |
+		    Off-|----+                   +----+                   +---
+			|
+		    1 On -|----+    +-------------------+    +------------------
+			|    |    |                   |    |
+		    Off |    +----+                   +----+
+			|
+		    2 On -|---------+    +-------------------+    +-------------
+			|         |    |                   |    |
+		    Off-|         +----+                   +----+
+			|
+		    3 On -|--------------+    +-------------------+    +--------
+			|              |    |                   |    |
+		    Off-|              +----+                   +----+
+			|
+		    4 On -|-------------------+    +-------------------+    +---
+			|                   |    |                   |    |
+		    Off-|                   +----+                   +----+
+			|
+			0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
 
-		      ^
-		      |
-		0 On -|    +---------------------------------------+
-		      |    |                                       |
-		  Off-|----+                                       +--------
-		      |
-		1 On -|----+    +-----------------------------+    +--------
-		      |    |    |                             |    |
-		  Off |    +----+                             +----+
-		      |
-		2 On -|---------+    +-------------------+    +-------------
-		      |         |    |                   |    |
-		  Off-|         +----+                   +----+
-		      |
-		3 On -|--------------+    +---------+    +------------------
-		      |              |    |         |    |
-		  Off-|              +----+         +----+
-		      |
-		4 On -|-------------------+         +-----------------------
-		      |                   |         |
-		  Off-|                   +---------+
-		      |
-		      0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
+		Bounce mode for Pipe LED::
+
+		    "1 800 2 800 4 800 8 800 16 800 16 800 8 800 4 800 2 800 1 800"
+
+			^
+			|
+		    0 On -|----+                                       +--------
+			|    |                                       |
+		    Off-|    +---------------------------------------+
+			|
+		    1 On -|    +----+                             +----+
+			|    |    |                             |    |
+		    Off |----+    +-----------------------------+    +--------
+			|
+		    2 On -|         +----+                   +----+
+			|         |    |                   |    |
+		    Off-|---------+    +-------------------+    +-------------
+			|
+		    3 On -|              +----+         +----+
+			|              |    |         |    |
+		    Off-|--------------+    +---------+    +------------------
+			|
+		    4 On -|                   +---------+
+			|                   |         |
+		    Off-|-------------------+         +-----------------------
+			|
+			0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
+
+		Inverted bounce mode for Pipe LED::
+
+		    "30 800 29 800 27 800 23 800 15 800 15 800 23 800 27 800 29 800 30 800"
+
+			^
+			|
+		    0 On -|    +---------------------------------------+
+			|    |                                       |
+		    Off-|----+                                       +--------
+			|
+		    1 On -|----+    +-----------------------------+    +--------
+			|    |    |                             |    |
+		    Off |    +----+                             +----+
+			|
+		    2 On -|---------+    +-------------------+    +-------------
+			|         |    |                   |    |
+		    Off-|         +----+                   +----+
+			|
+		    3 On -|--------------+    +---------+    +------------------
+			|              |    |         |    |
+		    Off-|              +----+         +----+
+			|
+		    4 On -|-------------------+         +-----------------------
+			|                   |         |
+		    Off-|                   +---------+
+			|
+			0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
 
 What:		/sys/class/leds/<led>/repeat
 Date:		September 2019
diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx b/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx
index 45b1e605d355..215482379580 100644
--- a/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx
+++ b/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx
@@ -12,8 +12,8 @@ Description:
 		format, we should set brightness as 0 for rise stage, fall
 		stage and low stage.
 
-		Min stage duration: 125 ms
-		Max stage duration: 31875 ms
+		- Min stage duration: 125 ms
+		- Max stage duration: 31875 ms
 
 		Since the stage duration step is 125 ms, the duration should be
 		a multiplier of 125, like 125ms, 250ms, 375ms, 500ms ... 31875ms.
diff --git a/Documentation/ABI/testing/sysfs-class-mic b/Documentation/ABI/testing/sysfs-class-mic
index 6ef682603179..bd0e780c3760 100644
--- a/Documentation/ABI/testing/sysfs-class-mic
+++ b/Documentation/ABI/testing/sysfs-class-mic
@@ -41,24 +41,33 @@ Description:
 		When read, this entry provides the current state of an Intel
 		MIC device in the context of the card OS. Possible values that
 		will be read are:
-		"ready" - The MIC device is ready to boot the card OS. On
-		reading this entry after an OSPM resume, a "boot" has to be
-		written to this entry if the card was previously shutdown
-		during OSPM suspend.
-		"booting" - The MIC device has initiated booting a card OS.
-		"online" - The MIC device has completed boot and is online
-		"shutting_down" - The card OS is shutting down.
-		"resetting" - A reset has been initiated for the MIC device
-		"reset_failed" - The MIC device has failed to reset.
+
+
+		===============  ===============================================
+		"ready"		 The MIC device is ready to boot the card OS.
+				 On reading this entry after an OSPM resume,
+				 a "boot" has to be written to this entry if
+				 the card was previously shutdown during OSPM
+				 suspend.
+		"booting"	 The MIC device has initiated booting a card OS.
+		"online"	 The MIC device has completed boot and is online
+		"shutting_down"	 The card OS is shutting down.
+		"resetting"	 A reset has been initiated for the MIC device
+		"reset_failed"	 The MIC device has failed to reset.
+		===============  ===============================================
 
 		When written, this sysfs entry triggers different state change
 		operations depending upon the current state of the card OS.
 		Acceptable values are:
-		"boot" - Boot the card OS image specified by the combination
-			 of firmware, ramdisk, cmdline and bootmode
-			sysfs entries.
-		"reset" - Initiates device reset.
-		"shutdown" - Initiates card OS shutdown.
+
+
+		==========  ===================================================
+		"boot"      Boot the card OS image specified by the combination
+			    of firmware, ramdisk, cmdline and bootmode
+			    sysfs entries.
+		"reset"     Initiates device reset.
+		"shutdown"  Initiates card OS shutdown.
+		==========  ===================================================
 
 What:		/sys/class/mic/mic(x)/shutdown_status
 Date:		October 2013
@@ -69,12 +78,15 @@ Description:
 		OS can shutdown because of various reasons. When read, this
 		entry provides the status on why the card OS was shutdown.
 		Possible values are:
-		"nop" -  shutdown status is not applicable, when the card OS is
-			"online"
-		"crashed" - Shutdown because of a HW or SW crash.
-		"halted" - Shutdown because of a halt command.
-		"poweroff" - Shutdown because of a poweroff command.
-		"restart" - Shutdown because of a restart command.
+
+		==========  ===================================================
+		"nop"       shutdown status is not applicable, when the card OS
+			    is "online"
+		"crashed"   Shutdown because of a HW or SW crash.
+		"halted"    Shutdown because of a halt command.
+		"poweroff"  Shutdown because of a poweroff command.
+		"restart"   Shutdown because of a restart command.
+		==========  ===================================================
 
 What:		/sys/class/mic/mic(x)/cmdline
 Date:		October 2013
diff --git a/Documentation/ABI/testing/sysfs-class-ocxl b/Documentation/ABI/testing/sysfs-class-ocxl
index ae1276efa45a..bf33f4fda58f 100644
--- a/Documentation/ABI/testing/sysfs-class-ocxl
+++ b/Documentation/ABI/testing/sysfs-class-ocxl
@@ -11,8 +11,11 @@ Contact:	linuxppc-dev@lists.ozlabs.org
 Description:	read only
 		Number of contexts for the AFU, in the format <n>/<max>
 		where:
+
+			====	===============================================
 			n:	number of currently active contexts, for debug
 			max:	maximum number of contexts supported by the AFU
+			====	===============================================
 
 What:		/sys/class/ocxl/<afu name>/pp_mmio_size
 Date:		January 2018
diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
index dbccb2fcd7ce..d4319a04c302 100644
--- a/Documentation/ABI/testing/sysfs-class-power
+++ b/Documentation/ABI/testing/sysfs-class-power
@@ -1,4 +1,4 @@
-===== General Properties =====
+**General Properties**
 
 What:		/sys/class/power_supply/<supply_name>/manufacturer
 Date:		May 2007
@@ -72,6 +72,7 @@ Description:
 		critically low).
 
 		Access: Read, Write
+
 		Valid values: 0 - 100 (percent)
 
 What:		/sys/class/power_supply/<supply_name>/capacity_error_margin
@@ -96,7 +97,9 @@ Description:
 		Coarse representation of battery capacity.
 
 		Access: Read
-		Valid values: "Unknown", "Critical", "Low", "Normal", "High",
+
+		Valid values:
+			      "Unknown", "Critical", "Low", "Normal", "High",
 			      "Full"
 
 What:		/sys/class/power_supply/<supply_name>/current_avg
@@ -139,6 +142,7 @@ Description:
 		throttling for thermal cooling or improving battery health.
 
 		Access: Read, Write
+
 		Valid values: Represented in microamps
 
 What:		/sys/class/power_supply/<supply_name>/charge_control_limit_max
@@ -148,6 +152,7 @@ Description:
 		Maximum legal value for the charge_control_limit property.
 
 		Access: Read
+
 		Valid values: Represented in microamps
 
 What:		/sys/class/power_supply/<supply_name>/charge_control_start_threshold
@@ -168,6 +173,7 @@ Description:
 		stop.
 
 		Access: Read, Write
+
 		Valid values: 0 - 100 (percent)
 
 What:		/sys/class/power_supply/<supply_name>/charge_type
@@ -183,7 +189,9 @@ Description:
 		different algorithm.
 
 		Access: Read, Write
-		Valid values: "Unknown", "N/A", "Trickle", "Fast", "Standard",
+
+		Valid values:
+			      "Unknown", "N/A", "Trickle", "Fast", "Standard",
 			      "Adaptive", "Custom"
 
 What:		/sys/class/power_supply/<supply_name>/charge_term_current
@@ -194,6 +202,7 @@ Description:
 		when the battery is considered full and charging should end.
 
 		Access: Read
+
 		Valid values: Represented in microamps
 
 What:		/sys/class/power_supply/<supply_name>/health
@@ -204,7 +213,9 @@ Description:
 		functionality.
 
 		Access: Read
-		Valid values: "Unknown", "Good", "Overheat", "Dead",
+
+		Valid values:
+			      "Unknown", "Good", "Overheat", "Dead",
 			      "Over voltage", "Unspecified failure", "Cold",
 			      "Watchdog timer expire", "Safety timer expire",
 			      "Over current", "Calibration required", "Warm",
@@ -218,6 +229,7 @@ Description:
 		for a battery charge cycle.
 
 		Access: Read
+
 		Valid values: Represented in microamps
 
 What:		/sys/class/power_supply/<supply_name>/present
@@ -227,9 +239,13 @@ Description:
 		Reports whether a battery is present or not in the system.
 
 		Access: Read
+
 		Valid values:
+
+			== =======
 			0: Absent
 			1: Present
+			== =======
 
 What:		/sys/class/power_supply/<supply_name>/status
 Date:		May 2007
@@ -240,7 +256,9 @@ Description:
 		used to enable/disable charging to the battery.
 
 		Access: Read, Write
-		Valid values: "Unknown", "Charging", "Discharging",
+
+		Valid values:
+			      "Unknown", "Charging", "Discharging",
 			      "Not charging", "Full"
 
 What:		/sys/class/power_supply/<supply_name>/technology
@@ -250,7 +268,9 @@ Description:
 		Describes the battery technology supported by the supply.
 
 		Access: Read
-		Valid values: "Unknown", "NiMH", "Li-ion", "Li-poly", "LiFe",
+
+		Valid values:
+			      "Unknown", "NiMH", "Li-ion", "Li-poly", "LiFe",
 			      "NiCd", "LiMn"
 
 What:		/sys/class/power_supply/<supply_name>/temp
@@ -260,6 +280,7 @@ Description:
 		Reports the current TBAT battery temperature reading.
 
 		Access: Read
+
 		Valid values: Represented in 1/10 Degrees Celsius
 
 What:		/sys/class/power_supply/<supply_name>/temp_alert_max
@@ -274,6 +295,7 @@ Description:
 		critically high, and charging has stopped).
 
 		Access: Read
+
 		Valid values: Represented in 1/10 Degrees Celsius
 
 What:		/sys/class/power_supply/<supply_name>/temp_alert_min
@@ -289,6 +311,7 @@ Description:
 		remedy the situation).
 
 		Access: Read
+
 		Valid values: Represented in 1/10 Degrees Celsius
 
 What:		/sys/class/power_supply/<supply_name>/temp_max
@@ -299,6 +322,7 @@ Description:
 		charging.
 
 		Access: Read
+
 		Valid values: Represented in 1/10 Degrees Celsius
 
 What:		/sys/class/power_supply/<supply_name>/temp_min
@@ -309,6 +333,7 @@ Description:
 		charging.
 
 		Access: Read
+
 		Valid values: Represented in 1/10 Degrees Celsius
 
 What:		/sys/class/power_supply/<supply_name>/voltage_avg,
@@ -320,6 +345,7 @@ Description:
 		which they average readings to smooth out the reported value.
 
 		Access: Read
+
 		Valid values: Represented in microvolts
 
 What:		/sys/class/power_supply/<supply_name>/voltage_max,
@@ -330,6 +356,7 @@ Description:
 		during charging.
 
 		Access: Read
+
 		Valid values: Represented in microvolts
 
 What:		/sys/class/power_supply/<supply_name>/voltage_min,
@@ -340,6 +367,7 @@ Description:
 		during discharging.
 
 		Access: Read
+
 		Valid values: Represented in microvolts
 
 What:		/sys/class/power_supply/<supply_name>/voltage_now,
@@ -350,9 +378,10 @@ Description:
 		This value is not averaged/smoothed.
 
 		Access: Read
+
 		Valid values: Represented in microvolts
 
-===== USB Properties =====
+**USB Properties**
 
 What: 		/sys/class/power_supply/<supply_name>/current_avg
 Date:		May 2007
@@ -363,6 +392,7 @@ Description:
 		average readings to smooth out the reported value.
 
 		Access: Read
+
 		Valid values: Represented in microamps
 
 
@@ -373,6 +403,7 @@ Description:
 		Reports the maximum IBUS current the supply can support.
 
 		Access: Read
+
 		Valid values: Represented in microamps
 
 What: 		/sys/class/power_supply/<supply_name>/current_now
@@ -385,6 +416,7 @@ Description:
 		within the reported min/max range.
 
 		Access: Read, Write
+
 		Valid values: Represented in microamps
 
 What:		/sys/class/power_supply/<supply_name>/input_current_limit
@@ -399,6 +431,7 @@ Description:
 		solved using power limit use input_current_limit.
 
 		Access: Read, Write
+
 		Valid values: Represented in microamps
 
 What:		/sys/class/power_supply/<supply_name>/input_voltage_limit
@@ -441,10 +474,14 @@ Description:
 		USB supply so voltage and current can be controlled).
 
 		Access: Read, Write
+
 		Valid values:
+
+			== ==================================================
 			0: Offline
 			1: Online Fixed - Fixed Voltage Supply
 			2: Online Programmable - Programmable Voltage Supply
+			== ==================================================
 
 What:		/sys/class/power_supply/<supply_name>/temp
 Date:		May 2007
@@ -455,6 +492,7 @@ Description:
 		TJUNC temperature of an IC)
 
 		Access: Read
+
 		Valid values: Represented in 1/10 Degrees Celsius
 
 What:		/sys/class/power_supply/<supply_name>/temp_alert_max
@@ -470,6 +508,7 @@ Description:
 		remedy the situation).
 
 		Access: Read
+
 		Valid values: Represented in 1/10 Degrees Celsius
 
 What:		/sys/class/power_supply/<supply_name>/temp_alert_min
@@ -485,6 +524,7 @@ Description:
 		accordingly to remedy the situation).
 
 		Access: Read
+
 		Valid values: Represented in 1/10 Degrees Celsius
 
 What:		/sys/class/power_supply/<supply_name>/temp_max
@@ -494,6 +534,7 @@ Description:
 		Reports the maximum allowed supply temperature for operation.
 
 		Access: Read
+
 		Valid values: Represented in 1/10 Degrees Celsius
 
 What:		/sys/class/power_supply/<supply_name>/temp_min
@@ -503,6 +544,7 @@ Description:
 		Reports the mainimum allowed supply temperature for operation.
 
 		Access: Read
+
 		Valid values: Represented in 1/10 Degrees Celsius
 
 What: 		/sys/class/power_supply/<supply_name>/usb_type
@@ -514,7 +556,9 @@ Description:
 		is attached.
 
 		Access: Read-Only
-		Valid values: "Unknown", "SDP", "DCP", "CDP", "ACA", "C", "PD",
+
+		Valid values:
+			      "Unknown", "SDP", "DCP", "CDP", "ACA", "C", "PD",
 			      "PD_DRP", "PD_PPS", "BrickID"
 
 What: 		/sys/class/power_supply/<supply_name>/voltage_max
@@ -524,6 +568,7 @@ Description:
 		Reports the maximum VBUS voltage the supply can support.
 
 		Access: Read
+
 		Valid values: Represented in microvolts
 
 What: 		/sys/class/power_supply/<supply_name>/voltage_min
@@ -533,6 +578,7 @@ Description:
 		Reports the minimum VBUS voltage the supply can support.
 
 		Access: Read
+
 		Valid values: Represented in microvolts
 
 What: 		/sys/class/power_supply/<supply_name>/voltage_now
@@ -545,9 +591,10 @@ Description:
 		within the reported min/max range.
 
 		Access: Read, Write
+
 		Valid values: Represented in microvolts
 
-===== Device Specific Properties =====
+**Device Specific Properties**
 
 What:		/sys/class/power/ds2760-battery.*/charge_now
 Date:		May 2010
@@ -581,6 +628,7 @@ Description:
 		will drop to 0 A) and will trigger interrupt.
 
 		Valid values:
+
 		- 5, 6 or 7 (hours),
 		- 0: disabled.
 
@@ -595,6 +643,7 @@ Description:
 		will drop to 0 A) and will trigger interrupt.
 
 		Valid values:
+
 		- 4 - 16 (hours), step by 2 (rounded down)
 		- 0: disabled.
 
@@ -609,6 +658,7 @@ Description:
 		interrupt and start top-off charging mode.
 
 		Valid values:
+
 		- 100000 - 200000 (microamps), step by 25000 (rounded down)
 		- 200000 - 350000 (microamps), step by 50000 (rounded down)
 		- 0: disabled.
@@ -624,6 +674,7 @@ Description:
 		will drop to 0 A) and will trigger interrupt.
 
 		Valid values:
+
 		- 0 - 70 (minutes), step by 10 (rounded down)
 
 What:		/sys/class/power_supply/bq24257-charger/ovp_voltage
@@ -637,6 +688,7 @@ Description:
 		device datasheet for details.
 
 		Valid values:
+
 		- 6000000, 6500000, 7000000, 8000000, 9000000, 9500000, 10000000,
 		  10500000 (all uV)
 
@@ -652,6 +704,7 @@ Description:
 		lower than the set value. See device datasheet for details.
 
 		Valid values:
+
 		- 4200000, 4280000, 4360000, 4440000, 4520000, 4600000, 4680000,
 		  4760000 (all uV)
 
@@ -666,6 +719,7 @@ Description:
 		the charger operates normally. See device datasheet for details.
 
 		Valid values:
+
 		- 1: enabled
 		- 0: disabled
 
@@ -681,6 +735,7 @@ Description:
 		from the system. See device datasheet for details.
 
 		Valid values:
+
 		- 1: enabled
 		- 0: disabled
 
diff --git a/Documentation/ABI/testing/sysfs-class-power-twl4030 b/Documentation/ABI/testing/sysfs-class-power-twl4030
index b4fd32d210c5..7ac36dba87bc 100644
--- a/Documentation/ABI/testing/sysfs-class-power-twl4030
+++ b/Documentation/ABI/testing/sysfs-class-power-twl4030
@@ -4,18 +4,20 @@ Description:
 	Writing to this can disable charging.
 
 	Possible values are:
-		"auto" - draw power as appropriate for detected
-			 power source and battery status.
-		"off"  - do not draw any power.
-		"continuous"
-		       - activate mode described as "linear" in
-		         TWL data sheets.  This uses whatever
-			 current is available and doesn't switch off
-			 when voltage drops.
 
-			 This is useful for unstable power sources
-			 such as bicycle dynamo, but care should
-			 be taken that battery is not over-charged.
+		=============	===========================================
+		"auto" 		draw power as appropriate for detected
+				power source and battery status.
+		"off"  		do not draw any power.
+		"continuous"	activate mode described as "linear" in
+				TWL data sheets.  This uses whatever
+				current is available and doesn't switch off
+				when voltage drops.
+
+				This is useful for unstable power sources
+				such as bicycle dynamo, but care should
+				be taken that battery is not over-charged.
+		=============	===========================================
 
 What: /sys/class/power_supply/twl4030_ac/mode
 Description:
@@ -23,6 +25,9 @@ Description:
 	Writing to this can disable charging.
 
 	Possible values are:
-		"auto" - draw power as appropriate for detected
-			 power source and battery status.
-		"off"  - do not draw any power.
+
+		======	===========================================
+		"auto"	draw power as appropriate for detected
+			power source and battery status.
+		"off"	do not draw any power.
+		======	===========================================
diff --git a/Documentation/ABI/testing/sysfs-class-rc b/Documentation/ABI/testing/sysfs-class-rc
index 6c0d6c8cb911..9c8ff7910858 100644
--- a/Documentation/ABI/testing/sysfs-class-rc
+++ b/Documentation/ABI/testing/sysfs-class-rc
@@ -21,15 +21,22 @@ KernelVersion:	2.6.36
 Contact:	Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
 Description:
 		Reading this file returns a list of available protocols,
-		something like:
+		something like::
+
 		    "rc5 [rc6] nec jvc [sony]"
+
 		Enabled protocols are shown in [] brackets.
+
 		Writing "+proto" will add a protocol to the list of enabled
 		protocols.
+
 		Writing "-proto" will remove a protocol from the list of enabled
 		protocols.
+
 		Writing "proto" will enable only "proto".
+
 		Writing "none" will disable all protocols.
+
 		Write fails with EINVAL if an invalid protocol combination or
 		unknown protocol name is used.
 
@@ -39,11 +46,13 @@ KernelVersion:	3.15
 Contact:	Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
 Description:
 		Sets the scancode filter expected value.
+
 		Use in combination with /sys/class/rc/rcN/filter_mask to set the
 		expected value of the bits set in the filter mask.
 		If the hardware supports it then scancodes which do not match
 		the filter will be ignored. Otherwise the write will fail with
 		an error.
+
 		This value may be reset to 0 if the current protocol is altered.
 
 What:		/sys/class/rc/rcN/filter_mask
@@ -56,9 +65,11 @@ Description:
 		of the scancode which should be compared against the expected
 		value. A value of 0 disables the filter to allow all valid
 		scancodes to be processed.
+
 		If the hardware supports it then scancodes which do not match
 		the filter will be ignored. Otherwise the write will fail with
 		an error.
+
 		This value may be reset to 0 if the current protocol is altered.
 
 What:		/sys/class/rc/rcN/wakeup_protocols
@@ -67,15 +78,22 @@ KernelVersion:	4.11
 Contact:	Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
 Description:
 		Reading this file returns a list of available protocols to use
-		for the wakeup filter, something like:
+		for the wakeup filter, something like::
+
 		    "rc-5 nec nec-x rc-6-0 rc-6-6a-24 [rc-6-6a-32] rc-6-mce"
+
 		Note that protocol variants are listed, so "nec", "sony",
 		"rc-5", "rc-6" have their different bit length encodings
 		listed if available.
+
 		The enabled wakeup protocol is shown in [] brackets.
+
 		Only one protocol can be selected at a time.
+
 		Writing "proto" will use "proto" for wakeup events.
+
 		Writing "none" will disable wakeup.
+
 		Write fails with EINVAL if an invalid protocol combination or
 		unknown protocol name is used, or if wakeup is not supported by
 		the hardware.
@@ -86,13 +104,17 @@ KernelVersion:	3.15
 Contact:	Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
 Description:
 		Sets the scancode wakeup filter expected value.
+
 		Use in combination with /sys/class/rc/rcN/wakeup_filter_mask to
 		set the expected value of the bits set in the wakeup filter mask
 		to trigger a system wake event.
+
 		If the hardware supports it and wakeup_filter_mask is not 0 then
 		scancodes which match the filter will wake the system from e.g.
 		suspend to RAM or power off.
+
 		Otherwise the write will fail with an error.
+
 		This value may be reset to 0 if the wakeup protocol is altered.
 
 What:		/sys/class/rc/rcN/wakeup_filter_mask
@@ -101,11 +123,15 @@ KernelVersion:	3.15
 Contact:	Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
 Description:
 		Sets the scancode wakeup filter mask of bits to compare.
+
 		Use in combination with /sys/class/rc/rcN/wakeup_filter to set
 		the bits of the scancode which should be compared against the
 		expected value to trigger a system wake event.
+
 		If the hardware supports it and wakeup_filter_mask is not 0 then
 		scancodes which match the filter will wake the system from e.g.
 		suspend to RAM or power off.
+
 		Otherwise the write will fail with an error.
+
 		This value may be reset to 0 if the wakeup protocol is altered.
diff --git a/Documentation/ABI/testing/sysfs-class-scsi_host b/Documentation/ABI/testing/sysfs-class-scsi_host
index bafc59fd7b69..7c98d8f43c45 100644
--- a/Documentation/ABI/testing/sysfs-class-scsi_host
+++ b/Documentation/ABI/testing/sysfs-class-scsi_host
@@ -56,8 +56,9 @@ Description:
 		management) on top, which makes it match the Windows IRST (Intel
 		Rapid Storage Technology) driver settings. This setting is also
 		close to min_power, except that:
+
 		a) It does not use host-initiated slumber mode, but it does
-		allow device-initiated slumber
+		   allow device-initiated slumber
 		b) It does not enable low power device sleep mode (DevSlp).
 
 What:		/sys/class/scsi_host/hostX/em_message
@@ -70,8 +71,8 @@ Description:
 		protocol, writes and reads correspond to the LED message format
 		as defined in the AHCI spec.
 
-		The user must turn sw_activity (under /sys/block/*/device/) OFF
-		it they wish to control the activity LED via the em_message
+		The user must turn sw_activity (under `/sys/block/*/device/`)
+		OFF it they wish to control the activity LED via the em_message
 		file.
 
 		em_message_type: (RO) Displays the current enclosure management
diff --git a/Documentation/ABI/testing/sysfs-class-typec b/Documentation/ABI/testing/sysfs-class-typec
index b834671522d6..b7794e02ad20 100644
--- a/Documentation/ABI/testing/sysfs-class-typec
+++ b/Documentation/ABI/testing/sysfs-class-typec
@@ -40,10 +40,13 @@ Description:
 		attribute will not return until the operation has finished.
 
 		Valid values:
-		- source (The port will behave as source only DFP port)
-		- sink (The port will behave as sink only UFP port)
-		- dual (The port will behave as dual-role-data and
+
+		======  ==============================================
+		source  (The port will behave as source only DFP port)
+		sink    (The port will behave as sink only UFP port)
+		dual    (The port will behave as dual-role-data and
 			dual-role-power port)
+		======  ==============================================
 
 What:		/sys/class/typec/<port>/vconn_source
 Date:		April 2017
@@ -59,6 +62,7 @@ Description:
 		generates uevent KOBJ_CHANGE.
 
 		Valid values:
+
 		- "no" when the port is not the VCONN Source
 		- "yes" when the port is the VCONN Source
 
@@ -72,6 +76,7 @@ Description:
 		power operation mode should show "usb_power_delivery".
 
 		Valid values:
+
 		- default
 		- 1.5A
 		- 3.0A
@@ -191,6 +196,7 @@ Date:		April 2017
 Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>
 Description:
 		Shows type of the plug on the cable:
+
 		- type-a - Standard A
 		- type-b - Standard B
 		- type-c
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD b/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD
index 7e43cdce9a52..f7b360a61b21 100644
--- a/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD
+++ b/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD
@@ -7,6 +7,7 @@ Description:
 		(RO) Hexadecimal bitmask of the TAD attributes are reported by
 		the platform firmware (see ACPI 6.2, section 9.18.2):
 
+		======= ======================================================
 		BIT(0): AC wakeup implemented if set
 		BIT(1): DC wakeup implemented if set
 		BIT(2): Get/set real time features implemented if set
@@ -16,6 +17,7 @@ Description:
 		BIT(6): The AC timer wakes up from S5 if set
 		BIT(7): The DC timer wakes up from S4 if set
 		BIT(8): The DC timer wakes up from S5 if set
+		======= ======================================================
 
 		The other bits are reserved.
 
@@ -62,9 +64,11 @@ Description:
 		timer status with the following meaning of bits (see ACPI 6.2,
 		Section 9.18.5):
 
+		======= ======================================================
 		Bit(0): The timer has expired if set.
 		Bit(1): The timer has woken up the system from a sleep state
 		        (S3 or S4/S5 if supported) if set.
+		======= ======================================================
 
 		The other bits are reserved.
 
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-docg3 b/Documentation/ABI/testing/sysfs-devices-platform-docg3
index 8aa36716882f..378c42694bfb 100644
--- a/Documentation/ABI/testing/sysfs-devices-platform-docg3
+++ b/Documentation/ABI/testing/sysfs-devices-platform-docg3
@@ -9,8 +9,10 @@ Description:
 		The protection has information embedded whether it blocks reads,
 		writes or both.
 		The result is:
-		0 -> the DPS is not keylocked
-		1 -> the DPS is keylocked
+
+		- 0 -> the DPS is not keylocked
+		- 1 -> the DPS is keylocked
+
 Users:		None identified so far.
 
 What:		/sys/devices/platform/docg3/f[0-3]_dps[01]_protection_key
@@ -27,8 +29,12 @@ Description:
 		Entering the correct value toggle the lock, and can be observed
 		through f[0-3]_dps[01]_is_keylocked.
 		Possible values are:
+
 			- 8 bytes
+
 		Typical values are:
+
 			- "00000000"
 			- "12345678"
+
 Users:		None identified so far.
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb b/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb
index 2107082426da..e45ac2e865d5 100644
--- a/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb
+++ b/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb
@@ -17,10 +17,10 @@ Description:
 		to overlay planes.
 
 		Selects the composition mode for the overlay. Possible values
-		are
+		are:
 
-		0 - Alpha Blending
-		1 - ROP3
+		- 0 - Alpha Blending
+		- 1 - ROP3
 
 What:		/sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_position
 Date:		May 2012
@@ -30,7 +30,7 @@ Description:
 		to overlay planes.
 
 		Stores the x,y overlay position on the display in pixels. The
-		position format is `[0-9]+,[0-9]+'.
+		position format is `[0-9]+,[0-9]+`.
 
 What:		/sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_rop3
 Date:		May 2012
diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index b555df825447..274c337ec6a9 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -151,23 +151,28 @@ Description:
 		The processor idle states which are available for use have the
 		following attributes:
 
-		name: (RO) Name of the idle state (string).
+		======== ==== =================================================
+		name:	 (RO) Name of the idle state (string).
 
 		latency: (RO) The latency to exit out of this idle state (in
-		microseconds).
+			      microseconds).
 
-		power: (RO) The power consumed while in this idle state (in
-		milliwatts).
+		power:   (RO) The power consumed while in this idle state (in
+			      milliwatts).
 
-		time: (RO) The total time spent in this idle state (in microseconds).
+		time:    (RO) The total time spent in this idle state
+			      (in microseconds).
 
-		usage: (RO) Number of times this state was entered (a count).
+		usage:	 (RO) Number of times this state was entered (a count).
 
-		above: (RO) Number of times this state was entered, but the
-		       observed CPU idle duration was too short for it (a count).
+		above:	 (RO) Number of times this state was entered, but the
+			      observed CPU idle duration was too short for it
+			      (a count).
 
-		below: (RO) Number of times this state was entered, but the
-		       observed CPU idle duration was too long for it (a count).
+		below: 	 (RO) Number of times this state was entered, but the
+			      observed CPU idle duration was too long for it
+			      (a count).
+		======== ==== =================================================
 
 What:		/sys/devices/system/cpu/cpuX/cpuidle/stateN/desc
 Date:		February 2008
@@ -290,6 +295,7 @@ Description:	Processor frequency boosting control
 		This switch controls the boost setting for the whole system.
 		Boosting allows the CPU and the firmware to run at a frequency
 		beyound it's nominal limit.
+
 		More details can be found in
 		Documentation/admin-guide/pm/cpufreq.rst
 
@@ -337,43 +343,57 @@ Contact:	Sudeep Holla <sudeep.holla@arm.com>
 Description:	Parameters for the CPU cache attributes
 
 		allocation_policy:
-			- WriteAllocate: allocate a memory location to a cache line
-					 on a cache miss because of a write
-			- ReadAllocate: allocate a memory location to a cache line
+			- WriteAllocate:
+					allocate a memory location to a cache line
+					on a cache miss because of a write
+			- ReadAllocate:
+					allocate a memory location to a cache line
 					on a cache miss because of a read
-			- ReadWriteAllocate: both writeallocate and readallocate
+			- ReadWriteAllocate:
+					both writeallocate and readallocate
 
-		attributes: LEGACY used only on IA64 and is same as write_policy
+		attributes:
+			    LEGACY used only on IA64 and is same as write_policy
 
-		coherency_line_size: the minimum amount of data in bytes that gets
+		coherency_line_size:
+				     the minimum amount of data in bytes that gets
 				     transferred from memory to cache
 
-		level: the cache hierarchy in the multi-level cache configuration
+		level:
+			the cache hierarchy in the multi-level cache configuration
 
-		number_of_sets: total number of sets in the cache, a set is a
+		number_of_sets:
+				total number of sets in the cache, a set is a
 				collection of cache lines with the same cache index
 
-		physical_line_partition: number of physical cache line per cache tag
+		physical_line_partition:
+				number of physical cache line per cache tag
 
-		shared_cpu_list: the list of logical cpus sharing the cache
+		shared_cpu_list:
+				the list of logical cpus sharing the cache
 
-		shared_cpu_map: logical cpu mask containing the list of cpus sharing
+		shared_cpu_map:
+				logical cpu mask containing the list of cpus sharing
 				the cache
 
-		size: the total cache size in kB
+		size:
+			the total cache size in kB
 
 		type:
 			- Instruction: cache that only holds instructions
 			- Data: cache that only caches data
 			- Unified: cache that holds both data and instructions
 
-		ways_of_associativity: degree of freedom in placing a particular block
-					of memory in the cache
+		ways_of_associativity:
+			degree of freedom in placing a particular block
+			of memory in the cache
 
 		write_policy:
-			- WriteThrough: data is written to both the cache line
+			- WriteThrough:
+					data is written to both the cache line
 					and to the block in the lower-level memory
-			- WriteBack: data is written only to the cache line and
+			- WriteBack:
+				     data is written only to the cache line and
 				     the modified cache line is written to main
 				     memory only when it is replaced
 
@@ -414,30 +434,30 @@ Description:	POWERNV CPUFreq driver's frequency throttle stats directory and
 		throttle attributes exported in the 'throttle_stats' directory:
 
 		- turbo_stat : This file gives the total number of times the max
-		frequency is throttled to lower frequency in turbo (at and above
-		nominal frequency) range of frequencies.
+		  frequency is throttled to lower frequency in turbo (at and above
+		  nominal frequency) range of frequencies.
 
 		- sub_turbo_stat : This file gives the total number of times the
-		max frequency is throttled to lower frequency in sub-turbo(below
-		nominal frequency) range of frequencies.
+		  max frequency is throttled to lower frequency in sub-turbo(below
+		  nominal frequency) range of frequencies.
 
 		- unthrottle : This file gives the total number of times the max
-		frequency is unthrottled after being throttled.
+		  frequency is unthrottled after being throttled.
 
 		- powercap : This file gives the total number of times the max
-		frequency is throttled due to 'Power Capping'.
+		  frequency is throttled due to 'Power Capping'.
 
 		- overtemp : This file gives the total number of times the max
-		frequency is throttled due to 'CPU Over Temperature'.
+		  frequency is throttled due to 'CPU Over Temperature'.
 
 		- supply_fault : This file gives the total number of times the
-		max frequency is throttled due to 'Power Supply Failure'.
+		  max frequency is throttled due to 'Power Supply Failure'.
 
 		- overcurrent : This file gives the total number of times the
-		max frequency is throttled due to 'Overcurrent'.
+		  max frequency is throttled due to 'Overcurrent'.
 
 		- occ_reset : This file gives the total number of times the max
-		frequency is throttled due to 'OCC Reset'.
+		  frequency is throttled due to 'OCC Reset'.
 
 		The sysfs attributes representing different throttle reasons like
 		powercap, overtemp, supply_fault, overcurrent and occ_reset map to
@@ -469,8 +489,9 @@ What:		/sys/devices/system/cpu/cpuX/regs/
 Date:		June 2016
 Contact:	Linux ARM Kernel Mailing list <linux-arm-kernel@lists.infradead.org>
 Description:	AArch64 CPU registers
+
 		'identification' directory exposes the CPU ID registers for
-		 identifying model and revision of the CPU.
+		identifying model and revision of the CPU.
 
 What:		/sys/devices/system/cpu/cpu#/cpu_capacity
 Date:		December 2016
@@ -497,9 +518,11 @@ Description:	Information about CPU vulnerabilities
 		vulnerabilities. The output of those files reflects the
 		state of the CPUs in the system. Possible output values:
 
+		================  ==============================================
 		"Not affected"	  CPU is not affected by the vulnerability
 		"Vulnerable"	  CPU is affected and no mitigation in effect
 		"Mitigation: $M"  CPU is affected and mitigation $M is in effect
+		================  ==============================================
 
 		See also: Documentation/admin-guide/hw-vuln/index.rst
 
@@ -515,12 +538,14 @@ Description:	Control Symetric Multi Threading (SMT)
 		control: Read/write interface to control SMT. Possible
 			 values:
 
+			 ================ =========================================
 			 "on"		  SMT is enabled
 			 "off"		  SMT is disabled
 			 "forceoff"	  SMT is force disabled. Cannot be changed.
 			 "notsupported"   SMT is not supported by the CPU
 			 "notimplemented" SMT runtime toggling is not
 					  implemented for the architecture
+			 ================ =========================================
 
 			 If control status is "forceoff" or "notsupported" writes
 			 are rejected.
diff --git a/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl
index 470def06ab0a..1a8ee26e92ae 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl
+++ b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl
@@ -5,8 +5,10 @@ Contact:        Vernon Mauery <vernux@us.ibm.com>
 Description:    The state file allows a means by which to change in and
                 out of Premium Real-Time Mode (PRTM), as well as the
                 ability to query the current state.
-                    0 => PRTM off
-                    1 => PRTM enabled
+
+                    - 0 => PRTM off
+                    - 1 => PRTM enabled
+
 Users:          The ibm-prtm userspace daemon uses this interface.
 
 
diff --git a/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator b/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator
index 4d63a7904b94..42214b4ff14a 100644
--- a/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator
+++ b/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator
@@ -6,11 +6,13 @@ Description:	Read/write the current state of DDR Backup Mode, which controls
 		if DDR power rails will be kept powered during system suspend.
 		("on"/"1" = enabled, "off"/"0" = disabled).
 		Two types of power switches (or control signals) can be used:
+
 		  A. With a momentary power switch (or pulse signal), DDR
 		     Backup Mode is enabled by default when available, as the
 		     PMIC will be configured only during system suspend.
 		  B. With a toggle power switch (or level signal), the
 		     following steps must be followed exactly:
+
 		       1. Configure PMIC for backup mode, to change the role of
 			  the accessory power switch from a power switch to a
 			  wake-up switch,
@@ -20,8 +22,10 @@ Description:	Read/write the current state of DDR Backup Mode, which controls
 		       3. Suspend system,
 		       4. Switch accessory power switch on, to resume the
 			  system.
+
 		     DDR Backup Mode must be explicitly enabled by the user,
 		     to invoke step 1.
+
 		See also Documentation/devicetree/bindings/mfd/bd9571mwv.txt.
 Users:		User space applications for embedded boards equipped with a
 		BD9571MWV PMIC.
diff --git a/Documentation/ABI/testing/sysfs-driver-genwqe b/Documentation/ABI/testing/sysfs-driver-genwqe
index 64ac6d567c4b..69d855dc4c47 100644
--- a/Documentation/ABI/testing/sysfs-driver-genwqe
+++ b/Documentation/ABI/testing/sysfs-driver-genwqe
@@ -29,8 +29,12 @@ What:           /sys/class/genwqe/genwqe<n>_card/reload_bitstream
 Date:           May 2014
 Contact:        klebers@linux.vnet.ibm.com
 Description:    Interface to trigger a PCIe card reset to reload the bitstream.
+
+		::
+
                   sudo sh -c 'echo 1 > \
                     /sys/class/genwqe/genwqe0_card/reload_bitstream'
+
                 If successfully, the card will come back with the bitstream set
                 on 'next_bitstream'.
 
@@ -64,8 +68,11 @@ Description:    Base clock frequency of the card.
 What:           /sys/class/genwqe/genwqe<n>_card/device/sriov_numvfs
 Date:           Oct 2013
 Contact:        haver@linux.vnet.ibm.com
-Description:    Enable VFs (1..15):
+Description:    Enable VFs (1..15)::
+
                   sudo sh -c 'echo 15 > \
                     /sys/bus/pci/devices/0000\:1b\:00.0/sriov_numvfs'
-                Disable VFs:
+
+                Disable VFs::
+
                   Write a 0 into the same sysfs entry.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff b/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff
index 305dffd229a8..de07be314efc 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff
+++ b/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff
@@ -12,7 +12,9 @@ KernelVersion:	4.1
 Contact:	Michal Malý <madcatxster@devoid-pointer.net>
 Description:	Displays a set of alternate modes supported by a wheel. Each
 		mode is listed as follows:
+
 		  Tag: Mode Name
+
 		Currently active mode is marked with an asterisk. List also
 		contains an abstract item "native" which always denotes the
 		native mode of the wheel. Echoing the mode tag switches the
@@ -24,24 +26,30 @@ Description:	Displays a set of alternate modes supported by a wheel. Each
 		This entry is not created for devices that have only one mode.
 
 		Currently supported mode switches:
-		Driving Force Pro:
+
+		Driving Force Pro::
+
 		  DF-EX --> DFP
 
-		G25:
+		G25::
+
 		  DF-EX --> DFP --> G25
 
-		G27:
+		G27::
+
 		  DF-EX <*> DFP <-> G25 <-> G27
 		  DF-EX <*--------> G25 <-> G27
 		  DF-EX <*----------------> G27
 
-		G29:
+		G29::
+
 		  DF-EX <*> DFP <-> G25 <-> G27 <-> G29
 		  DF-EX <*--------> G25 <-> G27 <-> G29
 		  DF-EX <*----------------> G27 <-> G29
 		  DF-EX <*------------------------> G29
 
-		DFGT:
+		DFGT::
+
 		  DF-EX <*> DFP <-> DFGT
 		  DF-EX <*--------> DFGT
 
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-wiimote b/Documentation/ABI/testing/sysfs-driver-hid-wiimote
index 39dfa5cb1cc5..cd7b82a5c27d 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-wiimote
+++ b/Documentation/ABI/testing/sysfs-driver-hid-wiimote
@@ -39,9 +39,13 @@ Description:	While a device is initialized by the wiimote driver, we perform
 		Other strings for each device-type are available and may be
 		added if new device-specific detections are added.
 		Currently supported are:
-			gen10: First Wii Remote generation
-			gen20: Second Wii Remote Plus generation (builtin MP)
+
+			============= =======================================
+			gen10:        First Wii Remote generation
+			gen20:        Second Wii Remote Plus generation
+				      (builtin MP)
 			balanceboard: Wii Balance Board
+			============= =======================================
 
 What:		/sys/bus/hid/drivers/wiimote/<dev>/bboard_calib
 Date:		May 2013
@@ -54,6 +58,7 @@ Description:	This attribute is only provided if the device was detected as a
 		First, 0kg values for all 4 sensors are written, followed by the
 		17kg values for all 4 sensors and last the 34kg values for all 4
 		sensors.
+
 		Calibration data is already applied by the kernel to all input
 		values but may be used by user-space to perform other
 		transformations.
@@ -68,9 +73,11 @@ Description:	This attribute is only provided if the device was detected as a
 		is prefixed with a +/-. Each value is a signed 16bit number.
 		Data is encoded as decimal numbers and specifies the offsets of
 		the analog sticks of the pro-controller.
+
 		Calibration data is already applied by the kernel to all input
 		values but may be used by user-space to perform other
 		transformations.
+
 		Calibration data is detected by the kernel during device setup.
 		You can write "scan\n" into this file to re-trigger calibration.
 		You can also write data directly in the form "x1:y1 x2:y2" to
diff --git a/Documentation/ABI/testing/sysfs-driver-samsung-laptop b/Documentation/ABI/testing/sysfs-driver-samsung-laptop
index 34d3a3359cf4..28c9c040de5d 100644
--- a/Documentation/ABI/testing/sysfs-driver-samsung-laptop
+++ b/Documentation/ABI/testing/sysfs-driver-samsung-laptop
@@ -9,10 +9,12 @@ Description:	Some Samsung laptops have different "performance levels"
 		their fans quiet at all costs.  Reading from this file
 		will show the current performance level.  Writing to the
 		file can change this value.
+
 			Valid options:
-				"silent"
-				"normal"
-				"overclock"
+				- "silent"
+				- "normal"
+				- "overclock"
+
 		Note that not all laptops support all of these options.
 		Specifically, not all support the "overclock" option,
 		and it's still unknown if this value even changes
@@ -25,8 +27,9 @@ Contact:	Corentin Chary <corentin.chary@gmail.com>
 Description:	Max battery charge level can be modified, battery cycle
 		life can be extended by reducing the max battery charge
 		level.
-		0 means normal battery mode (100% charge)
-		1 means battery life extender mode (80% charge)
+
+		- 0 means normal battery mode (100% charge)
+		- 1 means battery life extender mode (80% charge)
 
 What:		/sys/devices/platform/samsung/usb_charge
 Date:		December 1, 2011
diff --git a/Documentation/ABI/testing/sysfs-driver-toshiba_acpi b/Documentation/ABI/testing/sysfs-driver-toshiba_acpi
index f34221b52b14..e5a438d84e1f 100644
--- a/Documentation/ABI/testing/sysfs-driver-toshiba_acpi
+++ b/Documentation/ABI/testing/sysfs-driver-toshiba_acpi
@@ -4,10 +4,12 @@ KernelVersion:	3.15
 Contact:	Azael Avalos <coproscefalo@gmail.com>
 Description:	This file controls the keyboard backlight operation mode, valid
 		values are:
+
 			* 0x1  -> FN-Z
 			* 0x2  -> AUTO (also called TIMER)
 			* 0x8  -> ON
 			* 0x10 -> OFF
+
 		Note that from kernel 3.16 onwards this file accepts all listed
 		parameters, kernel 3.15 only accepts the first two (FN-Z and
 		AUTO).
@@ -41,8 +43,10 @@ KernelVersion:	3.15
 Contact:	Azael Avalos <coproscefalo@gmail.com>
 Description:	This files controls the status of the touchpad and pointing
 		stick (if available), valid values are:
+
 			* 0 -> OFF
 			* 1 -> ON
+
 Users:		KToshiba
 
 What:		/sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/available_kbd_modes
@@ -51,10 +55,12 @@ KernelVersion:	3.16
 Contact:	Azael Avalos <coproscefalo@gmail.com>
 Description:	This file shows the supported keyboard backlight modes
 		the system supports, which can be:
+
 			* 0x1  -> FN-Z
 			* 0x2  -> AUTO (also called TIMER)
 			* 0x8  -> ON
 			* 0x10 -> OFF
+
 		Note that not all keyboard types support the listed modes.
 		See the entry named "available_kbd_modes"
 Users:		KToshiba
@@ -65,6 +71,7 @@ KernelVersion:	3.16
 Contact:	Azael Avalos <coproscefalo@gmail.com>
 Description:	This file shows the current keyboard backlight type,
 		which can be:
+
 			* 1 -> Type 1, supporting modes FN-Z and AUTO
 			* 2 -> Type 2, supporting modes TIMER, ON and OFF
 Users:		KToshiba
@@ -75,10 +82,12 @@ KernelVersion:	4.0
 Contact:	Azael Avalos <coproscefalo@gmail.com>
 Description:	This file controls the USB Sleep & Charge charging mode, which
 		can be:
+
 			* 0 -> Disabled		(0x00)
 			* 1 -> Alternate	(0x09)
 			* 2 -> Auto		(0x21)
 			* 3 -> Typical		(0x11)
+
 		Note that from kernel 4.1 onwards this file accepts all listed
 		values, kernel 4.0 only supports the first three.
 		Note that this feature only works when connected to power, if
@@ -93,8 +102,10 @@ Contact:	Azael Avalos <coproscefalo@gmail.com>
 Description:	This file controls the USB Sleep Functions under battery, and
 		set the level at which point they will be disabled, accepted
 		values can be:
+
 			* 0	-> Disabled
 			* 1-100	-> Battery level to disable sleep functions
+
 		Currently it prints two values, the first one indicates if the
 		feature is enabled or disabled, while the second one shows the
 		current battery level set.
@@ -107,8 +118,10 @@ Date:		January 23, 2015
 KernelVersion:	4.0
 Contact:	Azael Avalos <coproscefalo@gmail.com>
 Description:	This file controls the USB Rapid Charge state, which can be:
+
 			* 0 -> Disabled
 			* 1 -> Enabled
+
 		Note that toggling this value requires a reboot for changes to
 		take effect.
 Users:		KToshiba
@@ -118,8 +131,10 @@ Date:		January 23, 2015
 KernelVersion:	4.0
 Contact:	Azael Avalos <coproscefalo@gmail.com>
 Description:	This file controls the Sleep & Music state, which values can be:
+
 			* 0 -> Disabled
 			* 1 -> Enabled
+
 		Note that this feature only works when connected to power, if
 		you want to use it under battery, see the entry named
 		"sleep_functions_on_battery"
@@ -138,6 +153,7 @@ KernelVersion:	4.0
 Contact:	Azael Avalos <coproscefalo@gmail.com>
 Description:	This file controls the state of the internal fan, valid
 		values are:
+
 			* 0 -> OFF
 			* 1 -> ON
 
@@ -147,8 +163,10 @@ KernelVersion:	4.0
 Contact:	Azael Avalos <coproscefalo@gmail.com>
 Description:	This file controls the Special Functions (hotkeys) operation
 		mode, valid values are:
+
 			* 0 -> Normal Operation
 			* 1 -> Special Functions
+
 		In the "Normal Operation" mode, the F{1-12} keys are as usual
 		and the hotkeys are accessed via FN-F{1-12}.
 		In the "Special Functions" mode, the F{1-12} keys trigger the
@@ -163,8 +181,10 @@ KernelVersion:	4.0
 Contact:	Azael Avalos <coproscefalo@gmail.com>
 Description:	This file controls whether the laptop should turn ON whenever
 		the LID is opened, valid values are:
+
 			* 0 -> Disabled
 			* 1 -> Enabled
+
 		Note that toggling this value requires a reboot for changes to
 		take effect.
 Users:		KToshiba
@@ -174,8 +194,10 @@ Date:		February 12, 2015
 KernelVersion:	4.0
 Contact:	Azael Avalos <coproscefalo@gmail.com>
 Description:	This file controls the USB 3 functionality, valid values are:
+
 			* 0 -> Disabled (Acts as a regular USB 2)
 			* 1 -> Enabled (Full USB 3 functionality)
+
 		Note that toggling this value requires a reboot for changes to
 		take effect.
 Users:		KToshiba
@@ -188,10 +210,14 @@ Description:	This file controls the Cooling Method feature.
 		Reading this file prints two values, the first is the actual cooling method
 		and the second is the maximum cooling method supported.
 		When the maximum cooling method is ONE, valid values are:
+
 			* 0 -> Maximum Performance
 			* 1 -> Battery Optimized
+
 		When the maximum cooling method is TWO, valid values are:
+
 			* 0 -> Maximum Performance
 			* 1 -> Performance
 			* 2 -> Battery Optimized
+
 Users:		KToshiba
diff --git a/Documentation/ABI/testing/sysfs-driver-toshiba_haps b/Documentation/ABI/testing/sysfs-driver-toshiba_haps
index a662370b4dbf..c938690ce10d 100644
--- a/Documentation/ABI/testing/sysfs-driver-toshiba_haps
+++ b/Documentation/ABI/testing/sysfs-driver-toshiba_haps
@@ -4,10 +4,12 @@ KernelVersion:	3.17
 Contact:	Azael Avalos <coproscefalo@gmail.com>
 Description:	This file controls the built-in accelerometer protection level,
 		valid values are:
+
 			* 0 -> Disabled
 			* 1 -> Low
 			* 2 -> Medium
 			* 3 -> High
+
 		The default potection value is set to 2 (Medium).
 Users:		KToshiba
 
diff --git a/Documentation/ABI/testing/sysfs-driver-wacom b/Documentation/ABI/testing/sysfs-driver-wacom
index afc48fc163b5..16acaa5712ec 100644
--- a/Documentation/ABI/testing/sysfs-driver-wacom
+++ b/Documentation/ABI/testing/sysfs-driver-wacom
@@ -79,7 +79,9 @@ Description:
 		When the Wacom Intuos 4 is connected over Bluetooth, the
 		image has to contain 256 bytes (64x32 px 1 bit colour).
 		The format is also scrambled, like in the USB mode, and it can
-		be summarized by converting 76543210 into GECA6420.
+		be summarized by converting::
+
+					    76543210 into GECA6420.
 					    HGFEDCBA      HFDB7531
 
 What:		/sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_remote/unpair_remote
diff --git a/Documentation/ABI/testing/sysfs-firmware-acpi b/Documentation/ABI/testing/sysfs-firmware-acpi
index 613f42a9d5cd..e4afc2538210 100644
--- a/Documentation/ABI/testing/sysfs-firmware-acpi
+++ b/Documentation/ABI/testing/sysfs-firmware-acpi
@@ -12,11 +12,14 @@ Description:
 		image: The image bitmap. Currently a 32-bit BMP.
 		status: 1 if the image is valid, 0 if firmware invalidated it.
 		type: 0 indicates image is in BMP format.
+
+		======== ===================================================
 		version: The version of the BGRT. Currently 1.
 		xoffset: The number of pixels between the left of the screen
 			 and the left edge of the image.
 		yoffset: The number of pixels between the top of the screen
 			 and the top edge of the image.
+		======== ===================================================
 
 What:		/sys/firmware/acpi/hotplug/
 Date:		February 2013
@@ -33,12 +36,14 @@ Description:
 		The following setting is available to user space for each
 		hotplug profile:
 
+		======== =======================================================
 		enabled: If set, the ACPI core will handle notifications of
-			hotplug events associated with the given class of
-			devices and will allow those devices to be ejected with
-			the help of the _EJ0 control method.  Unsetting it
-			effectively disables hotplug for the correspoinding
-			class of devices.
+			 hotplug events associated with the given class of
+			 devices and will allow those devices to be ejected with
+			 the help of the _EJ0 control method.  Unsetting it
+			 effectively disables hotplug for the correspoinding
+			 class of devices.
+		======== =======================================================
 
 		The value of the above attribute is an integer number: 1 (set)
 		or 0 (unset).  Attempts to write any other values to it will
@@ -71,86 +76,90 @@ Description:
 		To figure out where all the SCI's are coming from,
 		/sys/firmware/acpi/interrupts contains a file listing
 		every possible source, and the count of how many
-		times it has triggered.
-
-		$ cd /sys/firmware/acpi/interrupts
-		$ grep . *
-		error:	     0
-		ff_gbl_lock:	   0   enable
-		ff_pmtimer:	  0  invalid
-		ff_pwr_btn:	  0   enable
-		ff_rt_clk:	 2  disable
-		ff_slp_btn:	  0  invalid
-		gpe00:	     0	invalid
-		gpe01:	     0	 enable
-		gpe02:	   108	 enable
-		gpe03:	     0	invalid
-		gpe04:	     0	invalid
-		gpe05:	     0	invalid
-		gpe06:	     0	 enable
-		gpe07:	     0	 enable
-		gpe08:	     0	invalid
-		gpe09:	     0	invalid
-		gpe0A:	     0	invalid
-		gpe0B:	     0	invalid
-		gpe0C:	     0	invalid
-		gpe0D:	     0	invalid
-		gpe0E:	     0	invalid
-		gpe0F:	     0	invalid
-		gpe10:	     0	invalid
-		gpe11:	     0	invalid
-		gpe12:	     0	invalid
-		gpe13:	     0	invalid
-		gpe14:	     0	invalid
-		gpe15:	     0	invalid
-		gpe16:	     0	invalid
-		gpe17:	  1084	 enable
-		gpe18:	     0	 enable
-		gpe19:	     0	invalid
-		gpe1A:	     0	invalid
-		gpe1B:	     0	invalid
-		gpe1C:	     0	invalid
-		gpe1D:	     0	invalid
-		gpe1E:	     0	invalid
-		gpe1F:	     0	invalid
-		gpe_all:    1192
-		sci:	1194
-		sci_not:     0	
-
-		sci - The number of times the ACPI SCI
-		has been called and claimed an interrupt.
-
-		sci_not - The number of times the ACPI SCI
-		has been called and NOT claimed an interrupt.
-
-		gpe_all - count of SCI caused by GPEs.
-
-		gpeXX - count for individual GPE source
-
-		ff_gbl_lock - Global Lock
-
-		ff_pmtimer - PM Timer
-
-		ff_pwr_btn - Power Button
-
-		ff_rt_clk - Real Time Clock
-
-		ff_slp_btn - Sleep Button
-
-		error - an interrupt that can't be accounted for above.
-
-		invalid: it's either a GPE or a Fixed Event that
-			doesn't have an event handler.
-
-		disable: the GPE/Fixed Event is valid but disabled.
-
-		enable: the GPE/Fixed Event is valid and enabled.
-
-		Root has permission to clear any of these counters.  Eg.
-		# echo 0 > gpe11
-
-		All counters can be cleared by clearing the total "sci":
-		# echo 0 > sci
+		times it has triggered::
+
+		  $ cd /sys/firmware/acpi/interrupts
+		  $ grep . *
+		  error:	     0
+		  ff_gbl_lock:	   0   enable
+		  ff_pmtimer:	  0  invalid
+		  ff_pwr_btn:	  0   enable
+		  ff_rt_clk:	 2  disable
+		  ff_slp_btn:	  0  invalid
+		  gpe00:	     0	invalid
+		  gpe01:	     0	 enable
+		  gpe02:	   108	 enable
+		  gpe03:	     0	invalid
+		  gpe04:	     0	invalid
+		  gpe05:	     0	invalid
+		  gpe06:	     0	 enable
+		  gpe07:	     0	 enable
+		  gpe08:	     0	invalid
+		  gpe09:	     0	invalid
+		  gpe0A:	     0	invalid
+		  gpe0B:	     0	invalid
+		  gpe0C:	     0	invalid
+		  gpe0D:	     0	invalid
+		  gpe0E:	     0	invalid
+		  gpe0F:	     0	invalid
+		  gpe10:	     0	invalid
+		  gpe11:	     0	invalid
+		  gpe12:	     0	invalid
+		  gpe13:	     0	invalid
+		  gpe14:	     0	invalid
+		  gpe15:	     0	invalid
+		  gpe16:	     0	invalid
+		  gpe17:	  1084	 enable
+		  gpe18:	     0	 enable
+		  gpe19:	     0	invalid
+		  gpe1A:	     0	invalid
+		  gpe1B:	     0	invalid
+		  gpe1C:	     0	invalid
+		  gpe1D:	     0	invalid
+		  gpe1E:	     0	invalid
+		  gpe1F:	     0	invalid
+		  gpe_all:    1192
+		  sci:	1194
+		  sci_not:     0
+
+		===========  ==================================================
+		sci	     The number of times the ACPI SCI
+			     has been called and claimed an interrupt.
+
+		sci_not	     The number of times the ACPI SCI
+			     has been called and NOT claimed an interrupt.
+
+		gpe_all	     count of SCI caused by GPEs.
+
+		gpeXX	     count for individual GPE source
+
+		ff_gbl_lock  Global Lock
+
+		ff_pmtimer   PM Timer
+
+		ff_pwr_btn   Power Button
+
+		ff_rt_clk    Real Time Clock
+
+		ff_slp_btn   Sleep Button
+
+		error	     an interrupt that can't be accounted for above.
+
+		invalid      it's either a GPE or a Fixed Event that
+			     doesn't have an event handler.
+
+		disable	     the GPE/Fixed Event is valid but disabled.
+
+		enable       the GPE/Fixed Event is valid and enabled.
+		===========  ==================================================
+
+		Root has permission to clear any of these counters.  Eg.::
+
+		  # echo 0 > gpe11
+
+		All counters can be cleared by clearing the total "sci"::
+
+		  # echo 0 > sci
 
 		None of these counters has an effect on the function
 		of the system, they are simply statistics.
@@ -165,32 +174,34 @@ Description:
 
 		Let's take power button fixed event for example, please kill acpid
 		and other user space applications so that the machine won't shutdown
-		when pressing the power button.
-		# cat ff_pwr_btn
-		0	enabled
-		# press the power button for 3 times;
-		# cat ff_pwr_btn
-		3	enabled
-		# echo disable > ff_pwr_btn
-		# cat ff_pwr_btn
-		3	disabled
-		# press the power button for 3 times;
-		# cat ff_pwr_btn
-		3	disabled
-		# echo enable > ff_pwr_btn
-		# cat ff_pwr_btn
-		4	enabled
-		/*
-		 * this is because the status bit is set even if the enable bit is cleared,
-		 * and it triggers an ACPI fixed event when the enable bit is set again
-		 */
-		# press the power button for 3 times;
-		# cat ff_pwr_btn
-		7	enabled
-		# echo disable > ff_pwr_btn
-		# press the power button for 3 times;
-		# echo clear > ff_pwr_btn	/* clear the status bit */
-		# echo disable > ff_pwr_btn
-		# cat ff_pwr_btn
-		7	enabled
+		when pressing the power button::
+
+		  # cat ff_pwr_btn
+		  0	enabled
+		  # press the power button for 3 times;
+		  # cat ff_pwr_btn
+		  3	enabled
+		  # echo disable > ff_pwr_btn
+		  # cat ff_pwr_btn
+		  3	disabled
+		  # press the power button for 3 times;
+		  # cat ff_pwr_btn
+		  3	disabled
+		  # echo enable > ff_pwr_btn
+		  # cat ff_pwr_btn
+		  4	enabled
+		  /*
+		   * this is because the status bit is set even if the enable
+		   * bit is cleared, and it triggers an ACPI fixed event when
+		   * the enable bit is set again
+		   */
+		  # press the power button for 3 times;
+		  # cat ff_pwr_btn
+		  7	enabled
+		  # echo disable > ff_pwr_btn
+		  # press the power button for 3 times;
+		  # echo clear > ff_pwr_btn	/* clear the status bit */
+		  # echo disable > ff_pwr_btn
+		  # cat ff_pwr_btn
+		  7	enabled
 
diff --git a/Documentation/ABI/testing/sysfs-firmware-dmi-entries b/Documentation/ABI/testing/sysfs-firmware-dmi-entries
index 210ad44b95a5..fe0289c87768 100644
--- a/Documentation/ABI/testing/sysfs-firmware-dmi-entries
+++ b/Documentation/ABI/testing/sysfs-firmware-dmi-entries
@@ -33,7 +33,7 @@ Description:
 		doesn't matter), they will be represented in sysfs as
 		entries "T-0" through "T-(N-1)":
 
-		Example entry directories:
+		Example entry directories::
 
 			/sys/firmware/dmi/entries/17-0
 			/sys/firmware/dmi/entries/17-1
@@ -50,61 +50,65 @@ Description:
 		Each DMI entry in sysfs has the common header values
 		exported as attributes:
 
-		handle	: The 16bit 'handle' that is assigned to this
+		========  =================================================
+		handle	  The 16bit 'handle' that is assigned to this
 			  entry by the firmware.  This handle may be
 			  referred to by other entries.
-		length	: The length of the entry, as presented in the
+		length	  The length of the entry, as presented in the
 			  entry itself.  Note that this is _not the
 			  total count of bytes associated with the
-			  entry_.  This value represents the length of
+			  entry.  This value represents the length of
 			  the "formatted" portion of the entry.  This
 			  "formatted" region is sometimes followed by
 			  the "unformatted" region composed of nul
 			  terminated strings, with termination signalled
 			  by a two nul characters in series.
-		raw	: The raw bytes of the entry. This includes the
+		raw	  The raw bytes of the entry. This includes the
 			  "formatted" portion of the entry, the
 			  "unformatted" strings portion of the entry,
 			  and the two terminating nul characters.
-		type	: The type of the entry.  This value is the same
+		type	  The type of the entry.  This value is the same
 			  as found in the directory name.  It indicates
 			  how the rest of the entry should be interpreted.
-		instance: The instance ordinal of the entry for the
+		instance  The instance ordinal of the entry for the
 			  given type.  This value is the same as found
 			  in the parent directory name.
-		position: The ordinal position (zero-based) of the entry
+		position  The ordinal position (zero-based) of the entry
 			  within the entirety of the DMI entry table.
+		========  =================================================
 
-		=== Entry Specialization ===
+		**Entry Specialization**
 
 		Some entry types may have other information available in
 		sysfs.  Not all types are specialized.
 
-		--- Type 15 - System Event Log ---
+		**Type 15 - System Event Log**
 
 		This entry allows the firmware to export a log of
 		events the system has taken.  This information is
 		typically backed by nvram, but the implementation
 		details are abstracted by this table.  This entry's data
-		is exported in the directory:
+		is exported in the directory::
 
-		/sys/firmware/dmi/entries/15-0/system_event_log
+		  /sys/firmware/dmi/entries/15-0/system_event_log
 
 		and has the following attributes (documented in the
 		SMBIOS / DMI specification under "System Event Log (Type 15)":
 
-		area_length
-		header_start_offset
-		data_start_offset
-		access_method
-		status
-		change_token
-		access_method_address
-		header_format
-		per_log_type_descriptor_length
-		type_descriptors_supported_count
+		- area_length
+		- header_start_offset
+		- data_start_offset
+		- access_method
+		- status
+		- change_token
+		- access_method_address
+		- header_format
+		- per_log_type_descriptor_length
+		- type_descriptors_supported_count
 
 		As well, the kernel exports the binary attribute:
 
-		raw_event_log	: The raw binary bits of the event log
+		=============	  ====================================
+		raw_event_log	  The raw binary bits of the event log
 				  as described by the DMI entry.
+		=============	  ====================================
diff --git a/Documentation/ABI/testing/sysfs-firmware-gsmi b/Documentation/ABI/testing/sysfs-firmware-gsmi
index 0faa0aaf4b6a..7a558354c1ee 100644
--- a/Documentation/ABI/testing/sysfs-firmware-gsmi
+++ b/Documentation/ABI/testing/sysfs-firmware-gsmi
@@ -20,7 +20,7 @@ Description:
 
 			This directory has the same layout (and
 			underlying implementation as /sys/firmware/efi/vars.
-			See Documentation/ABI/*/sysfs-firmware-efi-vars
+			See `Documentation/ABI/*/sysfs-firmware-efi-vars`
 			for more information on how to interact with
 			this structure.
 
diff --git a/Documentation/ABI/testing/sysfs-firmware-memmap b/Documentation/ABI/testing/sysfs-firmware-memmap
index eca0d65087dc..1f6f4d3a32c0 100644
--- a/Documentation/ABI/testing/sysfs-firmware-memmap
+++ b/Documentation/ABI/testing/sysfs-firmware-memmap
@@ -20,7 +20,7 @@ Description:
 		the raw memory map to userspace.
 
 		The structure is as follows: Under /sys/firmware/memmap there
-		are subdirectories with the number of the entry as their name:
+		are subdirectories with the number of the entry as their name::
 
 			/sys/firmware/memmap/0
 			/sys/firmware/memmap/1
@@ -34,14 +34,16 @@ Description:
 
 		Each directory contains three files:
 
-		start	: The start address (as hexadecimal number with the
+		========  =====================================================
+		start	  The start address (as hexadecimal number with the
 			  '0x' prefix).
-		end	: The end address, inclusive (regardless whether the
+		end	  The end address, inclusive (regardless whether the
 			  firmware provides inclusive or exclusive ranges).
-		type	: Type of the entry as string. See below for a list of
+		type	  Type of the entry as string. See below for a list of
 			  valid types.
+		========  =====================================================
 
-		So, for example:
+		So, for example::
 
 			/sys/firmware/memmap/0/start
 			/sys/firmware/memmap/0/end
@@ -57,9 +59,8 @@ Description:
 		  - reserved
 
 		Following shell snippet can be used to display that memory
-		map in a human-readable format:
+		map in a human-readable format::
 
-		-------------------- 8< ----------------------------------------
 		  #!/bin/bash
 		  cd /sys/firmware/memmap
 		  for dir in * ; do
@@ -68,4 +69,3 @@ Description:
 		      type=$(cat $dir/type)
 		      printf "%016x-%016x (%s)\n" $start $[ $end +1] "$type"
 		  done
-		-------------------- >8 ----------------------------------------
diff --git a/Documentation/ABI/testing/sysfs-fs-ext4 b/Documentation/ABI/testing/sysfs-fs-ext4
index 78604db56279..99e3d92f8299 100644
--- a/Documentation/ABI/testing/sysfs-fs-ext4
+++ b/Documentation/ABI/testing/sysfs-fs-ext4
@@ -45,8 +45,8 @@ Description:
 		parameter will have their blocks allocated out of a
 		block group specific preallocation pool, so that small
 		files are packed closely together.  Each large file
-		 will have its blocks allocated out of its own unique
-		 preallocation pool.
+		will have its blocks allocated out of its own unique
+		preallocation pool.
 
 What:		/sys/fs/ext4/<disk>/inode_readahead_blks
 Date:		March 2008
diff --git a/Documentation/ABI/testing/sysfs-hypervisor-xen b/Documentation/ABI/testing/sysfs-hypervisor-xen
index 53b7b2ea7515..4dbe0c49b393 100644
--- a/Documentation/ABI/testing/sysfs-hypervisor-xen
+++ b/Documentation/ABI/testing/sysfs-hypervisor-xen
@@ -15,14 +15,17 @@ KernelVersion:	4.3
 Contact:	Boris Ostrovsky <boris.ostrovsky@oracle.com>
 Description:	If running under Xen:
 		Describes mode that Xen's performance-monitoring unit (PMU)
-		uses. Accepted values are
-			"off"  -- PMU is disabled
-			"self" -- The guest can profile itself
-			"hv"   -- The guest can profile itself and, if it is
+		uses. Accepted values are:
+
+			======    ============================================
+			"off"     PMU is disabled
+			"self"    The guest can profile itself
+			"hv"      The guest can profile itself and, if it is
 				  privileged (e.g. dom0), the hypervisor
-			"all" --  The guest can profile itself, the hypervisor
+			"all"     The guest can profile itself, the hypervisor
 				  and all other guests. Only available to
 				  privileged guests.
+			======    ============================================
 
 What:           /sys/hypervisor/pmu/pmu_features
 Date:           August 2015
diff --git a/Documentation/ABI/testing/sysfs-kernel-boot_params b/Documentation/ABI/testing/sysfs-kernel-boot_params
index eca38ce2852d..7f9bda453c4d 100644
--- a/Documentation/ABI/testing/sysfs-kernel-boot_params
+++ b/Documentation/ABI/testing/sysfs-kernel-boot_params
@@ -23,16 +23,17 @@ Description:	The /sys/kernel/boot_params directory contains two
 		representation of setup_data type. "data" file is the binary
 		representation of setup_data payload.
 
-		The whole boot_params directory structure is like below:
-		/sys/kernel/boot_params
-		|__ data
-		|__ setup_data
-		|   |__ 0
-		|   |   |__ data
-		|   |   |__ type
-		|   |__ 1
-		|       |__ data
-		|       |__ type
-		|__ version
+		The whole boot_params directory structure is like below::
+
+		  /sys/kernel/boot_params
+		  |__ data
+		  |__ setup_data
+		  |   |__ 0
+		  |   |   |__ data
+		  |   |   |__ type
+		  |   |__ 1
+		  |       |__ data
+		  |       |__ type
+		  |__ version
 
 Users:		Kexec
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-hugepages b/Documentation/ABI/testing/sysfs-kernel-mm-hugepages
index fdaa2162fae1..294387e2c7fb 100644
--- a/Documentation/ABI/testing/sysfs-kernel-mm-hugepages
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-hugepages
@@ -7,9 +7,11 @@ Description:
 		of the hugepages supported by the kernel/CPU combination.
 
 		Under these directories are a number of files:
-			nr_hugepages
-			nr_overcommit_hugepages
-			free_hugepages
-			surplus_hugepages
-			resv_hugepages
+
+			- nr_hugepages
+			- nr_overcommit_hugepages
+			- free_hugepages
+			- surplus_hugepages
+			- resv_hugepages
+
 		See Documentation/admin-guide/mm/hugetlbpage.rst for details.
diff --git a/Documentation/ABI/testing/sysfs-platform-asus-laptop b/Documentation/ABI/testing/sysfs-platform-asus-laptop
index 8b0e8205a6a2..c78d358dbdbe 100644
--- a/Documentation/ABI/testing/sysfs-platform-asus-laptop
+++ b/Documentation/ABI/testing/sysfs-platform-asus-laptop
@@ -4,13 +4,16 @@ KernelVersion:	2.6.20
 Contact:	"Corentin Chary" <corentincj@iksaif.net>
 Description:
 		This file allows display switching. The value
-		is composed by 4 bits and defined as follow:
-		4321
-		|||`- LCD
-		||`-- CRT
-		|`--- TV
-		`---- DVI
-		Ex: - 0 (0000b) means no display
+		is composed by 4 bits and defined as follow::
+
+		  4321
+		  |||`- LCD
+		  ||`-- CRT
+		  |`--- TV
+		  `---- DVI
+
+		Ex:
+		    - 0 (0000b) means no display
 		    - 3 (0011b) CRT+LCD.
 
 What:		/sys/devices/platform/asus_laptop/gps
@@ -28,8 +31,10 @@ Contact:	"Corentin Chary" <corentincj@iksaif.net>
 Description:
 		Some models like the W1N have a LED display that can be
 		used to display several items of information.
-		To control the LED display, use the following :
+		To control the LED display, use the following::
+
 		    echo 0x0T000DDD > /sys/devices/platform/asus_laptop/
+
 		where T control the 3 letters display, and DDD the 3 digits display.
 		The DDD table can be found in Documentation/admin-guide/laptops/asus-laptop.rst
 
diff --git a/Documentation/ABI/testing/sysfs-platform-asus-wmi b/Documentation/ABI/testing/sysfs-platform-asus-wmi
index 1efac0ddb417..04885738cf15 100644
--- a/Documentation/ABI/testing/sysfs-platform-asus-wmi
+++ b/Documentation/ABI/testing/sysfs-platform-asus-wmi
@@ -5,6 +5,7 @@ Contact:	"Corentin Chary" <corentincj@iksaif.net>
 Description:
 		Change CPU clock configuration (write-only).
 		There are three available clock configuration:
+
 		    * 0 -> Super Performance Mode
 		    * 1 -> High Performance Mode
 		    * 2 -> Power Saving Mode
diff --git a/Documentation/ABI/testing/sysfs-platform-at91 b/Documentation/ABI/testing/sysfs-platform-at91
index 4cc6a865ae66..b146be74b8e0 100644
--- a/Documentation/ABI/testing/sysfs-platform-at91
+++ b/Documentation/ABI/testing/sysfs-platform-at91
@@ -18,8 +18,10 @@ Description:
 		In order to use an extended can_id add the
 		CAN_EFF_FLAG (0x80000000U) to the can_id. Example:
 
-		- standard id 0x7ff:
-		echo 0x7ff      > /sys/class/net/can0/mb0_id
+		- standard id 0x7ff::
 
-		- extended id 0x1fffffff:
-		echo 0x9fffffff > /sys/class/net/can0/mb0_id
+		    echo 0x7ff      > /sys/class/net/can0/mb0_id
+
+		- extended id 0x1fffffff::
+
+		    echo 0x9fffffff > /sys/class/net/can0/mb0_id
diff --git a/Documentation/ABI/testing/sysfs-platform-eeepc-laptop b/Documentation/ABI/testing/sysfs-platform-eeepc-laptop
index 5b026c69587a..70dbe0733cf6 100644
--- a/Documentation/ABI/testing/sysfs-platform-eeepc-laptop
+++ b/Documentation/ABI/testing/sysfs-platform-eeepc-laptop
@@ -4,9 +4,11 @@ KernelVersion:	2.6.26
 Contact:	"Corentin Chary" <corentincj@iksaif.net>
 Description:
 		This file allows display switching.
+
 		- 1 = LCD
 		- 2 = CRT
 		- 3 = LCD+CRT
+
 		If you run X11, you should use xrandr instead.
 
 What:		/sys/devices/platform/eeepc/camera
@@ -30,16 +32,20 @@ Contact:	"Corentin Chary" <corentincj@iksaif.net>
 Description:
 		Change CPU clock configuration.
 		On the Eee PC 1000H there are three available clock configuration:
+
 		    * 0 -> Super Performance Mode
 		    * 1 -> High Performance Mode
 		    * 2 -> Power Saving Mode
+
 		On Eee PC 701 there is only 2 available clock configurations.
 		Available configuration are listed in available_cpufv file.
 		Reading this file will show the raw hexadecimal value which
-		is defined as follow:
-		| 8 bit | 8 bit |
-		    |       `---- Current mode
-		    `------------ Availables modes
+		is defined as follow::
+
+		  | 8 bit | 8 bit |
+		      |       `---- Current mode
+		      `------------ Availables modes
+
 		For example, 0x301 means: mode 1 selected, 3 available modes.
 
 What:		/sys/devices/platform/eeepc/available_cpufv
diff --git a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop
index 1b31be3f996a..fd2ac02bc5bd 100644
--- a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop
+++ b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop
@@ -12,6 +12,7 @@ Contact:	"Maxim Mikityanskiy <maxtram95@gmail.com>"
 Description:
 		Change fan mode
 		There are four available modes:
+
 			* 0 -> Super Silent Mode
 			* 1 -> Standard Mode
 			* 2 -> Dust Cleaning
@@ -32,9 +33,11 @@ KernelVersion:	4.18
 Contact:	"Oleg Keri <ezhi99@gmail.com>"
 Description:
 		Control fn-lock mode.
+
 			* 1 -> Switched On
 			* 0 -> Switched Off
 
-		For example:
-		# echo "0" >	\
-		/sys/bus/pci/devices/0000:00:1f.0/PNP0C09:00/VPC2004:00/fn_lock
+		For example::
+
+		  # echo "0" >	\
+		  /sys/bus/pci/devices/0000:00:1f.0/PNP0C09:00/VPC2004:00/fn_lock
diff --git a/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt b/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt
index 8af65059d519..e19144fd5d86 100644
--- a/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt
+++ b/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt
@@ -7,5 +7,6 @@ Description:
 		Thunderbolt controllers to turn on or off when no
 		devices are connected (write-only)
 		There are two available states:
+
 		    * 0 -> Force power disabled
 		    * 1 -> Force power enabled
diff --git a/Documentation/ABI/testing/sysfs-platform-sst-atom b/Documentation/ABI/testing/sysfs-platform-sst-atom
index 0d07c0395660..d5f6e21f0e42 100644
--- a/Documentation/ABI/testing/sysfs-platform-sst-atom
+++ b/Documentation/ABI/testing/sysfs-platform-sst-atom
@@ -5,13 +5,22 @@ Contact:	"Sebastien Guiriec" <sebastien.guiriec@intel.com>
 Description:
 		LPE Firmware version for SST driver on all atom
 		plaforms (BYT/CHT/Merrifield/BSW).
-		If the FW has never been loaded it will display:
+		If the FW has never been loaded it will display::
+
 			"FW not yet loaded"
-		If FW has been loaded it will display:
+
+		If FW has been loaded it will display::
+
 			"v01.aa.bb.cc"
+
 		aa: Major version is reflecting SoC version:
+
+			=== =============
 			0d: BYT FW
 			0b: BSW FW
 			07: Merrifield FW
+			=== =============
+
 		bb: Minor version
+
 		cc: Build version
diff --git a/Documentation/ABI/testing/sysfs-platform-usbip-vudc b/Documentation/ABI/testing/sysfs-platform-usbip-vudc
index 81fcfb454913..53622d3ba27c 100644
--- a/Documentation/ABI/testing/sysfs-platform-usbip-vudc
+++ b/Documentation/ABI/testing/sysfs-platform-usbip-vudc
@@ -16,10 +16,13 @@ Contact:	Krzysztof Opasiak <k.opasiak@samsung.com>
 Description:
 		Current status of the device.
 		Allowed values:
-		1 - Device is available and can be exported
-		2 - Device is currently exported
-		3 - Fatal error occurred during communication
-		  with peer
+
+		==  ==========================================
+		1   Device is available and can be exported
+		2   Device is currently exported
+		3   Fatal error occurred during communication
+		    with peer
+		==  ==========================================
 
 What:		/sys/devices/platform/usbip-vudc.%d/usbip_sockfd
 Date:		April 2016
diff --git a/Documentation/ABI/testing/sysfs-ptp b/Documentation/ABI/testing/sysfs-ptp
index a17f817a9309..2363ad810ddb 100644
--- a/Documentation/ABI/testing/sysfs-ptp
+++ b/Documentation/ABI/testing/sysfs-ptp
@@ -69,7 +69,7 @@ Description:
 		pin offered by the PTP hardware clock. The file name
 		is the hardware dependent pin name. Reading from this
 		file produces two numbers, the assigned function (see
-		the PTP_PF_ enumeration values in linux/ptp_clock.h)
+		the `PTP_PF_` enumeration values in linux/ptp_clock.h)
 		and the channel number. The function and channel
 		assignment may be changed by two writing numbers into
 		the file.
-- 
2.26.2

[PATCH v2 21/39] docs: ABI: sysfs-uevent: make it compatible with ReST output

[Mauro Carvalho Chehab]

- Replace " by ``, in order to use monospaced fonts;
- mark literal blocks as such.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/testing/sysfs-uevent | 28 +++++++++++++++-----------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-uevent b/Documentation/ABI/testing/sysfs-uevent
index aa39f8d7bcdf..0b6227706b35 100644
--- a/Documentation/ABI/testing/sysfs-uevent
+++ b/Documentation/ABI/testing/sysfs-uevent
@@ -6,42 +6,46 @@ Description:
                 Enable passing additional variables for synthetic uevents that
                 are generated by writing /sys/.../uevent file.
 
-                Recognized extended format is ACTION [UUID [KEY=VALUE ...].
+                Recognized extended format is::
 
-                The ACTION is compulsory - it is the name of the uevent action
-                ("add", "change", "remove"). There is no change compared to
-                previous functionality here. The rest of the extended format
-                is optional.
+			ACTION [UUID [KEY=VALUE ...]
+
+                The ACTION is compulsory - it is the name of the uevent
+                action (``add``, ``change``, ``remove``). There is no change
+                compared to previous functionality here. The rest of the
+                extended format is optional.
 
                 You need to pass UUID first before any KEY=VALUE pairs.
-                The UUID must be in "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+                The UUID must be in ``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``
                 format where 'x' is a hex digit. The UUID is considered to be
                 a transaction identifier so it's possible to use the same UUID
                 value for one or more synthetic uevents in which case we
                 logically group these uevents together for any userspace
                 listeners. The UUID value appears in uevent as
-                "SYNTH_UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" environment
+                ``SYNTH_UUID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`` environment
                 variable.
 
                 If UUID is not passed in, the generated synthetic uevent gains
-                "SYNTH_UUID=0" environment variable automatically.
+                ``SYNTH_UUID=0`` environment variable automatically.
 
                 The KEY=VALUE pairs can contain alphanumeric characters only.
+
                 It's possible to define zero or more pairs - each pair is then
                 delimited by a space character ' '. Each pair appears in
-                synthetic uevent as "SYNTH_ARG_KEY=VALUE". That means the KEY
-                name gains "SYNTH_ARG_" prefix to avoid possible collisions
+                synthetic uevent as ``SYNTH_ARG_KEY=VALUE``. That means the KEY
+                name gains ``SYNTH_ARG_`` prefix to avoid possible collisions
                 with existing variables.
 
-                Example of valid sequence written to the uevent file:
+                Example of valid sequence written to the uevent file::
 
                     add fe4d7c9d-b8c6-4a70-9ef1-3d8a58d18eed A=1 B=abc
 
-                This generates synthetic uevent including these variables:
+                This generates synthetic uevent including these variables::
 
                     ACTION=add
                     SYNTH_ARG_A=1
                     SYNTH_ARG_B=abc
                     SYNTH_UUID=fe4d7c9d-b8c6-4a70-9ef1-3d8a58d18eed
+
 Users:
                 udev, userspace tools generating synthetic uevents
-- 
2.26.2

[PATCH v2 22/39] docs: ABI: make it parse ABI/stable as ReST-compatible files

[Mauro Carvalho Chehab]

Now that the stable ABI files are compatible with ReST,
parse them without converting complex descriptions as literal
blocks nor escaping special characters.

Please notice that escaping special characters will probably
be needed at descriptions, at least for the asterisk character.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/abi-stable.rst | 1 +
 Documentation/sphinx/kernel_abi.py       | 8 ++++++--
 2 files changed, 7 insertions(+), 2 deletions(-)

diff --git a/Documentation/admin-guide/abi-stable.rst b/Documentation/admin-guide/abi-stable.rst
index 7495d7a35048..70490736e0d3 100644
--- a/Documentation/admin-guide/abi-stable.rst
+++ b/Documentation/admin-guide/abi-stable.rst
@@ -11,3 +11,4 @@ Most interfaces (like syscalls) are expected to never change and always
 be available.
 
 .. kernel-abi:: $srctree/Documentation/ABI/stable
+   :rst:
diff --git a/Documentation/sphinx/kernel_abi.py b/Documentation/sphinx/kernel_abi.py
index ce5f3b0ae811..f3da859c9878 100644
--- a/Documentation/sphinx/kernel_abi.py
+++ b/Documentation/sphinx/kernel_abi.py
@@ -73,12 +73,13 @@ class KernelCmd(Directive):
     u"""KernelABI (``kernel-abi``) directive"""
 
     required_arguments = 1
-    optional_arguments = 0
+    optional_arguments = 2
     has_content = False
     final_argument_whitespace = True
 
     option_spec = {
-        "debug"     : directives.flag
+        "debug"     : directives.flag,
+        "rst"       : directives.unchanged
     }
 
     def run(self):
@@ -92,6 +93,9 @@ class KernelCmd(Directive):
         cmd = "get_abi.pl rest --enable-lineno --dir "
         cmd += self.arguments[0]
 
+        if 'rst' in self.options:
+            cmd += " --rst-source"
+
         srctree = path.abspath(os.environ["srctree"])
 
         fname = cmd
-- 
2.26.2

[PATCH v2 23/39] docs: ABI: create a 2-depth index for ABI

[Mauro Carvalho Chehab]

That helps to identify what ABI files are adding titles.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/abi.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/admin-guide/abi.rst b/Documentation/admin-guide/abi.rst
index 3b9645c77469..bcab3ef2597c 100644
--- a/Documentation/admin-guide/abi.rst
+++ b/Documentation/admin-guide/abi.rst
@@ -3,7 +3,7 @@ Linux ABI description
 =====================
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
 
    abi-stable
    abi-testing
-- 
2.26.2

[PATCH v2 24/39] docs: ABI: don't escape ReST-incompatible chars from obsolete and removed

[Mauro Carvalho Chehab]

With just a single fix, the contents there can be parsed properly
without the need to escape any ReST incompatible stuff.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/obsolete/sysfs-gpio      | 2 ++
 Documentation/admin-guide/abi-obsolete.rst | 1 +
 Documentation/admin-guide/abi-removed.rst  | 1 +
 3 files changed, 4 insertions(+)

diff --git a/Documentation/ABI/obsolete/sysfs-gpio b/Documentation/ABI/obsolete/sysfs-gpio
index e0d4e5e2dd90..b8b0fd341c17 100644
--- a/Documentation/ABI/obsolete/sysfs-gpio
+++ b/Documentation/ABI/obsolete/sysfs-gpio
@@ -13,6 +13,8 @@ Description:
   GPIOs are identified as they are inside the kernel, using integers in
   the range 0..INT_MAX.  See Documentation/admin-guide/gpio for more information.
 
+  ::
+
     /sys/class/gpio
 	/export ... asks the kernel to export a GPIO to userspace
 	/unexport ... to return a GPIO to the kernel
diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/admin-guide/abi-obsolete.rst
index cda9168445a5..d095867899c5 100644
--- a/Documentation/admin-guide/abi-obsolete.rst
+++ b/Documentation/admin-guide/abi-obsolete.rst
@@ -8,3 +8,4 @@ The description of the interface will document the reason why it is
 obsolete and when it can be expected to be removed.
 
 .. kernel-abi:: $srctree/Documentation/ABI/obsolete
+   :rst:
diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admin-guide/abi-removed.rst
index 497978fc9632..f7e9e43023c1 100644
--- a/Documentation/admin-guide/abi-removed.rst
+++ b/Documentation/admin-guide/abi-removed.rst
@@ -2,3 +2,4 @@ ABI removed symbols
 ===================
 
 .. kernel-abi:: $srctree/Documentation/ABI/removed
+   :rst:
-- 
2.26.2

[PATCH v2 25/39] docs: abi-testing.rst: enable --rst-sources when building docs

[Mauro Carvalho Chehab]

Now that ABI/testing documents were fixed, add --rst-sources to
the ABI/testing too.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/admin-guide/abi-testing.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/Documentation/admin-guide/abi-testing.rst b/Documentation/admin-guide/abi-testing.rst
index 5c886fc50b9e..b205b16a72d0 100644
--- a/Documentation/admin-guide/abi-testing.rst
+++ b/Documentation/admin-guide/abi-testing.rst
@@ -17,3 +17,4 @@ name to the description of these interfaces, so that the kernel
 developers can easily notify them if any changes occur.
 
 .. kernel-abi:: $srctree/Documentation/ABI/testing
+   :rst:
-- 
2.26.2

[PATCH v2 26/39] docs: Kconfig/Makefile: add a check for broken ABI files

[Mauro Carvalho Chehab]

The files under Documentation/ABI should follow the syntax
as defined at Documentation/ABI/README.

Allow checking if they're following the syntax by running
the ABI parser script on COMPILE_TEST.

With that, when there's a problem with a file under
Documentation/ABI, it would produce a warning like:

	Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#14:
		What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor' doesn't have a description
	Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#21:
		What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal' doesn't have a description

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/Kconfig  | 10 ++++++++++
 Documentation/Makefile |  5 +++++
 lib/Kconfig.debug      |  2 ++
 scripts/get_abi.pl     | 14 +++++++++++---
 4 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/Documentation/Kconfig b/Documentation/Kconfig
index 66046fa1c341..e549a61f4d96 100644
--- a/Documentation/Kconfig
+++ b/Documentation/Kconfig
@@ -10,4 +10,14 @@ config WARN_MISSING_DOCUMENTS
 
 	   If unsure, select 'N'.
 
+config WARN_ABI_ERRORS
+	bool "Warn if there are errors at ABI files"
+	depends on COMPILE_TEST
+	help
+	   The files under Documentation/ABI should follow what's
+	   described at Documentation/ABI/README. Yet, as they're manually
+	   written, it would be possible that some of those files would
+	   have errors that would break them for being parsed by
+	   scripts/get_abi.pl. Add a check to verify them.
 
+	   If unsure, select 'N'.
diff --git a/Documentation/Makefile b/Documentation/Makefile
index 4e47dff8b315..61a7310b49e0 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -10,6 +10,11 @@ ifeq ($(CONFIG_WARN_MISSING_DOCUMENTS),y)
 $(shell $(srctree)/scripts/documentation-file-ref-check --warn)
 endif
 
+# Check for broken ABI files
+ifeq ($(CONFIG_WARN_ABI_ERRORS),y)
+$(shell $(srctree)/scripts/get_abi.pl validate --dir $(srctree)/Documentation/ABI)
+endif
+
 # You can set these variables from the command line.
 SPHINXBUILD   = sphinx-build
 SPHINXOPTS    =
diff --git a/lib/Kconfig.debug b/lib/Kconfig.debug
index 537cf3c2937d..60f92c14d496 100644
--- a/lib/Kconfig.debug
+++ b/lib/Kconfig.debug
@@ -2449,4 +2449,6 @@ config HYPERV_TESTING
 
 endmenu # "Kernel Testing and Coverage"
 
+source "Documentation/Kconfig"
+
 endmenu # Kernel hacking
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index ff4f9f82ecad..f6adf4b38a2b 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -50,7 +50,15 @@ my %symbols;
 sub parse_error($$$$) {
 	my ($file, $ln, $msg, $data) = @_;
 
-	print STDERR "file $file#$ln: $msg at\n\t$data";
+	$data =~ s/\s+$/\n/;
+
+	print STDERR "Warning: file $file#$ln:\n\t$msg";
+
+	if ($data ne "") {
+		print STDERR ". Line\n\t\t$data";
+	} else {
+	    print STDERR "\n";
+	}
 }
 
 #
@@ -110,7 +118,7 @@ sub parse_abi {
 
 			# Invalid, but it is a common mistake
 			if ($new_tag eq "where") {
-				parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", $_);
+				parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", "");
 				$new_tag = "what";
 			}
 
@@ -225,7 +233,7 @@ sub parse_abi {
 		}
 
 		# Everything else is error
-		parse_error($file, $ln, "Unexpected line:", $_);
+		parse_error($file, $ln, "Unexpected content", $_);
 	}
 	$data{$nametag}->{description} =~ s/^\n+// if ($data{$nametag}->{description});
 	if ($what) {
-- 
2.26.2

[PATCH v2 27/39] docs: ABI: convert testing/configfs-acpi to ReST

[Mauro Carvalho Chehab]

There are some problems with this file when a ReST content
is produced. Fix it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/testing/configfs-acpi | 34 ++++++++++++++++++-------
 1 file changed, 25 insertions(+), 9 deletions(-)

diff --git a/Documentation/ABI/testing/configfs-acpi b/Documentation/ABI/testing/configfs-acpi
index 4ab4e99aa863..c09b640c3cb1 100644
--- a/Documentation/ABI/testing/configfs-acpi
+++ b/Documentation/ABI/testing/configfs-acpi
@@ -14,7 +14,8 @@ Description:
 		This group contains the configuration for user defined ACPI
 		tables. The attributes of a user define table are:
 
-		aml 		- a binary attribute that the user can use to
+		aml
+			      - a binary attribute that the user can use to
 				fill in the ACPI aml definitions. Once the aml
 				data is written to this file and the file is
 				closed the table will be loaded and ACPI devices
@@ -26,11 +27,26 @@ Description:
 		The rest of the attributes are read-only and are valid only
 		after the table has been loaded by filling the aml entry:
 
-		signature 	- ASCII table signature
-		length 		- length of table in bytes, including the header
-		revision 	- ACPI Specification minor version number
-		oem_id 		- ASCII OEM identification
-		oem_table_id 	- ASCII OEM table identification
-		oem_revision 	- OEM revision number
-		asl_compiler_id - ASCII ASL compiler vendor ID
-		asl_compiler_revision - ASL compiler version
+		signature
+				- ASCII table signature
+
+		length
+				- length of table in bytes, including the header
+
+		revision
+				- ACPI Specification minor version number
+
+		oem_id
+				- ASCII OEM identification
+
+		oem_table_id
+				- ASCII OEM table identification
+
+		oem_revision
+				- OEM revision number
+
+		asl_compiler_id
+				- ASCII ASL compiler vendor ID
+
+		asl_compiler_revision
+				- ASL compiler version
-- 
2.26.2

[PATCH v2 28/39] docs: ABI: fix syntax to be parsed using ReST notation

[Mauro Carvalho Chehab]

There are a number of new changes at the ABI files that cause
them to produce warnings when generating ABI output.

Fix them.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../ABI/stable/sysfs-driver-firmware-zynqmp   | 62 ++++++++-----
 Documentation/ABI/testing/debugfs-moxtet      | 28 ++++--
 .../ABI/testing/debugfs-turris-mox-rwtm       |  6 +-
 .../sysfs-bus-event_source-devices-dfl_fme    | 14 +--
 Documentation/ABI/testing/sysfs-bus-most      |  6 +-
 Documentation/ABI/testing/sysfs-class-devfreq |  6 +-
 Documentation/ABI/testing/sysfs-class-ocxl    | 14 +--
 .../ABI/testing/sysfs-class-power-wilco       | 18 ++--
 .../ABI/testing/sysfs-class-rnbd-client       | 93 ++++++++++---------
 .../ABI/testing/sysfs-class-rtrs-client       | 23 +++--
 .../sysfs-devices-platform-stratix10-rsu      | 10 ++
 .../ABI/testing/sysfs-driver-w1_therm         | 75 ++++++++++-----
 .../ABI/testing/sysfs-platform-dfl-fme        | 14 ++-
 Documentation/ABI/testing/sysfs-platform-dptf | 11 ++-
 .../sysfs-platform-intel-wmi-sbl-fw-update    |  1 +
 .../testing/sysfs-platform-mellanox-bootctl   | 50 ++++++----
 .../ABI/testing/sysfs-platform-wilco-ec       |  1 +
 17 files changed, 271 insertions(+), 161 deletions(-)

diff --git a/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp b/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
index 00fa04c76ff3..f5724bb5b462 100644
--- a/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
+++ b/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
@@ -12,13 +12,15 @@ Description:
 		resets. Three registers are used by the FSBL and
 		other Xilinx software products: GLOBAL_GEN_STORAGE{4:6}.
 
-		Usage:
-		# cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
-		# echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
+		Usage::
 
-		Example:
-		# cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
-		# echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
+		    # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
+		    # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
+
+		Example::
+
+		    # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
+		    # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
 
 Users:		Xilinx
 
@@ -39,13 +41,15 @@ Description:
 		software products: PERS_GLOB_GEN_STORAGE{4:7}.
 		Register is reset only by a POR reset.
 
-		Usage:
-		# cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
-		# echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
+		Usage::
 
-		Example:
-		# cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
-		# echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
+		    # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
+		    # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
+
+		Example::
+
+		    # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
+		    # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
 
 Users:		Xilinx
 
@@ -61,23 +65,28 @@ Description:
 
 		Following are available shutdown scopes(subtypes):
 
-		subsystem:	Only the APU along with all of its peripherals
+		subsystem:
+				Only the APU along with all of its peripherals
 				not used by other processing units will be
 				shut down. This may result in the FPD power
 				domain being shut down provided that no other
 				processing unit uses FPD peripherals or DRAM.
-		ps_only:	The complete PS will be shut down, including the
+		ps_only:
+				The complete PS will be shut down, including the
 				RPU, PMU, etc.  Only the PL domain (FPGA)
 				remains untouched.
-		system:		The complete system/device is shut down.
+		system:
+				The complete system/device is shut down.
 
-		Usage:
-		# cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
-		# echo <scope> > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
+		Usage::
 
-		Example:
-		# cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
-		# echo "subsystem" > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
+		    # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
+		    # echo <scope> > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
+
+		Example::
+
+		    # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
+		    # echo "subsystem" > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
 
 Users:		Xilinx
 
@@ -94,10 +103,13 @@ Description:
 		system restart.
 
 		Usage:
-		Set healthy bit
-		# echo 1 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status
 
-		Unset healthy bit
-		# echo 0 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status
+		Set healthy bit::
+
+		    # echo 1 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status
+
+		Unset healthy bit::
+
+		    # echo 0 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status
 
 Users:		Xilinx
diff --git a/Documentation/ABI/testing/debugfs-moxtet b/Documentation/ABI/testing/debugfs-moxtet
index 67b1717794d8..15dfaecb2892 100644
--- a/Documentation/ABI/testing/debugfs-moxtet
+++ b/Documentation/ABI/testing/debugfs-moxtet
@@ -5,10 +5,16 @@ Contact:	Marek Behún <marek.behun@nic.cz>
 Description:	(R) Read input from the shift registers, in hexadecimal.
 		Returns N+1 bytes, where N is the number of Moxtet connected
 		modules. The first byte is from the CPU board itself.
-		Example: 101214
-			 10: CPU board with SD card
-			 12: 2 = PCIe module, 1 = IRQ not active
-			 14: 4 = Peridot module, 1 = IRQ not active
+
+		Example::
+
+			101214
+
+		==  =======================================
+		10  CPU board with SD card
+		12  2 = PCIe module, 1 = IRQ not active
+		14  4 = Peridot module, 1 = IRQ not active
+		==  =======================================
 
 What:		/sys/kernel/debug/moxtet/output
 Date:		March 2019
@@ -17,7 +23,13 @@ Contact:	Marek Behún <marek.behun@nic.cz>
 Description:	(RW) Read last written value to the shift registers, in
 		hexadecimal, or write values to the shift registers, also
 		in hexadecimal.
-		Example: 0102
-			 01: 01 was last written, or is to be written, to the
-			     first module's shift register
-			 02: the same for second module
+
+		Example::
+
+		    0102
+
+		==  ================================================
+		01  01 was last written, or is to be written, to the
+		    first module's shift register
+		02  the same for second module
+		==  ================================================
diff --git a/Documentation/ABI/testing/debugfs-turris-mox-rwtm b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
index 2b3255ee68fd..c8f7dadd591c 100644
--- a/Documentation/ABI/testing/debugfs-turris-mox-rwtm
+++ b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
@@ -2,8 +2,10 @@ What:		/sys/kernel/debug/turris-mox-rwtm/do_sign
 Date:		Jun 2020
 KernelVersion:	5.8
 Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(W) Message to sign with the ECDSA private key stored in
+Description:	(W)
+		    Message to sign with the ECDSA private key stored in
 		    device's OTP. The message must be exactly 64 bytes (since
 		    this is intended for SHA-512 hashes).
-		(R) The resulting signature, 136 bytes. This contains the R and
+		(R)
+		    The resulting signature, 136 bytes. This contains the R and
 		    S values of the ECDSA signature, both in big-endian format.
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme b/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme
index c9278a3b3df1..63a32ddcb95e 100644
--- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme
@@ -8,13 +8,13 @@ Description:	Read-only. Attribute group to describe the magic bits
 
 		Each attribute under this group defines a bit range of the
 		perf_event_attr.config. All supported attributes are listed
-		below.
+		below::
 
 		    event  = "config:0-11"  - event ID
 		    evtype = "config:12-15" - event type
 		    portid = "config:16-23" - event source
 
-		For example,
+		For example::
 
 		    fab_mmio_read = "event=0x06,evtype=0x02,portid=0xff"
 
@@ -40,11 +40,11 @@ Description:	Read-only. Attribute group to describe performance monitoring
 
 		All supported performance monitoring events are listed below.
 
-		Basic events (evtype=0x00)
+		Basic events (evtype=0x00)::
 
 		    clock = "event=0x00,evtype=0x00,portid=0xff"
 
-		Cache events (evtype=0x01)
+		Cache events (evtype=0x01)::
 
 		    cache_read_hit      = "event=0x00,evtype=0x01,portid=0xff"
 		    cache_read_miss     = "event=0x01,evtype=0x01,portid=0xff"
@@ -59,7 +59,7 @@ Description:	Read-only. Attribute group to describe performance monitoring
 		    cache_rx_req_stall  = "event=0x09,evtype=0x01,portid=0xff"
 		    cache_eviction      = "event=0x0a,evtype=0x01,portid=0xff"
 
-		Fabric events (evtype=0x02)
+		Fabric events (evtype=0x02)::
 
 		    fab_pcie0_read       = "event=0x00,evtype=0x02,portid=0xff"
 		    fab_pcie0_write      = "event=0x01,evtype=0x02,portid=0xff"
@@ -78,7 +78,7 @@ Description:	Read-only. Attribute group to describe performance monitoring
 		    fab_port_mmio_read   = "event=0x06,evtype=0x02,portid=?"
 		    fab_port_mmio_write  = "event=0x07,evtype=0x02,portid=?"
 
-		VTD events (evtype=0x03)
+		VTD events (evtype=0x03)::
 
 		    vtd_port_read_transaction  = "event=0x00,evtype=0x03,portid=?"
 		    vtd_port_write_transaction = "event=0x01,evtype=0x03,portid=?"
@@ -88,7 +88,7 @@ Description:	Read-only. Attribute group to describe performance monitoring
 		    vtd_port_devtlb_2m_fill    = "event=0x05,evtype=0x03,portid=?"
 		    vtd_port_devtlb_1g_fill    = "event=0x06,evtype=0x03,portid=?"
 
-		VTD SIP events (evtype=0x04)
+		VTD SIP events (evtype=0x04)::
 
 		    vtd_sip_iotlb_4k_hit  = "event=0x00,evtype=0x04,portid=0xff"
 		    vtd_sip_iotlb_2m_hit  = "event=0x01,evtype=0x04,portid=0xff"
diff --git a/Documentation/ABI/testing/sysfs-bus-most b/Documentation/ABI/testing/sysfs-bus-most
index ec0a603d804b..38cc03e408e7 100644
--- a/Documentation/ABI/testing/sysfs-bus-most
+++ b/Documentation/ABI/testing/sysfs-bus-most
@@ -235,7 +235,8 @@ KernelVersion:	4.15
 Contact:	Christian Gromm <christian.gromm@microchip.com>
 Description:
 		This is to read back the configured direction of the channel.
-		The following strings will be accepted:
+		The following strings will be accepted::
+
 			'tx',
 			'rx'
 Users:
@@ -246,7 +247,8 @@ KernelVersion:	4.15
 Contact:	Christian Gromm <christian.gromm@microchip.com>
 Description:
 		This is to read back the configured data type of the channel.
-		The following strings will be accepted:
+		The following strings will be accepted::
+
 			'control',
 			'async',
 			'sync',
diff --git a/Documentation/ABI/testing/sysfs-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq
index 67af3f31e17c..386bc230a33d 100644
--- a/Documentation/ABI/testing/sysfs-class-devfreq
+++ b/Documentation/ABI/testing/sysfs-class-devfreq
@@ -48,7 +48,8 @@ Description:
 		driver should provide the list of available frequencies
 		with its profile. If need to reset the statistics of devfreq
 		behavior on a specific device, enter 0(zero) to 'trans_stat'
-		as following:
+		as following::
+
 			echo 0 > /sys/class/devfreq/.../trans_stat
 
 What:		/sys/class/devfreq/.../available_frequencies
@@ -124,7 +125,8 @@ Description:
 		This work timer is used by devfreq workqueue in order to
 		monitor the device status such as utilization. The user
 		can change the work timer on runtime according to their demand
-		as following:
+		as following::
+
 			echo deferrable > /sys/class/devfreq/.../timer
 			echo delayed > /sys/class/devfreq/.../timer
 
diff --git a/Documentation/ABI/testing/sysfs-class-ocxl b/Documentation/ABI/testing/sysfs-class-ocxl
index bf33f4fda58f..847a7edc3113 100644
--- a/Documentation/ABI/testing/sysfs-class-ocxl
+++ b/Documentation/ABI/testing/sysfs-class-ocxl
@@ -13,8 +13,8 @@ Description:	read only
 		where:
 
 			====	===============================================
-			n:	number of currently active contexts, for debug
-			max:	maximum number of contexts supported by the AFU
+			n	number of currently active contexts, for debug
+			max	maximum number of contexts supported by the AFU
 			====	===============================================
 
 What:		/sys/class/ocxl/<afu name>/pp_mmio_size
@@ -43,7 +43,9 @@ Contact:	linuxppc-dev@lists.ozlabs.org
 Description:	read/write
 		Control whether the FPGA is reloaded on a link reset. Enabled
 		through a vendor-specific logic block on the FPGA.
-			0	Do not reload FPGA image from flash
-			1	Reload FPGA image from flash
-			unavailable
-				The device does not support this capability
+
+			===========  ===========================================
+			0	     Do not reload FPGA image from flash
+			1	     Reload FPGA image from flash
+			unavailable  The device does not support this capability
+			===========  ===========================================
diff --git a/Documentation/ABI/testing/sysfs-class-power-wilco b/Documentation/ABI/testing/sysfs-class-power-wilco
index 84fde1d0ada0..82af180fcaab 100644
--- a/Documentation/ABI/testing/sysfs-class-power-wilco
+++ b/Documentation/ABI/testing/sysfs-class-power-wilco
@@ -4,17 +4,23 @@ KernelVersion:	5.2
 Description:
 		What charging algorithm to use:
 
-		Standard: Fully charges battery at a standard rate.
-		Adaptive: Battery settings adaptively optimized based on
+		Standard:
+			Fully charges battery at a standard rate.
+		Adaptive:
+			Battery settings adaptively optimized based on
 			typical battery usage pattern.
-		Fast: Battery charges over a shorter period.
-		Trickle: Extends battery lifespan, intended for users who
+		Fast:
+			Battery charges over a shorter period.
+		Trickle:
+			Extends battery lifespan, intended for users who
 			primarily use their Chromebook while connected to AC.
-		Custom: A low and high threshold percentage is specified.
+		Custom:
+			A low and high threshold percentage is specified.
 			Charging begins when level drops below
 			charge_control_start_threshold, and ceases when
 			level is above charge_control_end_threshold.
-		Long Life: Customized charge rate for last longer battery life.
+		Long Life:
+			Customized charge rate for last longer battery life.
 			On Wilco device this mode is pre-configured in the factory
 			through EC's private PID. Swiching to a different mode will
 			be denied by Wilco EC when Long Life mode is enabled.
diff --git a/Documentation/ABI/testing/sysfs-class-rnbd-client b/Documentation/ABI/testing/sysfs-class-rnbd-client
index c084f203b41e..00c0286733d4 100644
--- a/Documentation/ABI/testing/sysfs-class-rnbd-client
+++ b/Documentation/ABI/testing/sysfs-class-rnbd-client
@@ -5,62 +5,70 @@ Contact:	Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud
 Description:	Provide information about RNBD-client.
 		All sysfs files that are not read-only provide the usage information on read:
 
-		Example:
-		# cat /sys/class/rnbd-client/ctl/map_device
+		Example::
 
-		> Usage: echo "sessname=<name of the rtrs session> path=<[srcaddr,]dstaddr>
-		> [path=<[srcaddr,]dstaddr>] device_path=<full path on remote side>
-		> [access_mode=<ro|rw|migration>] > map_device
-		>
-		> addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ]
+		    # cat /sys/class/rnbd-client/ctl/map_device
+
+		    > Usage: echo "sessname=<name of the rtrs session> path=<[srcaddr,]dstaddr>
+		    > [path=<[srcaddr,]dstaddr>] device_path=<full path on remote side>
+		    > [access_mode=<ro|rw|migration>] > map_device
+		    >
+		    > addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ]
 
 What:		/sys/class/rnbd-client/ctl/map_device
 Date:		Feb 2020
 KernelVersion:	5.7
 Contact:	Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
-Description:	Expected format is the following:
+Description:	Expected format is the following::
 
-		sessname=<name of the rtrs session>
-		path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...]
-		device_path=<full path on remote side>
-		[access_mode=<ro|rw|migration>]
+		    sessname=<name of the rtrs session>
+		    path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...]
+		    device_path=<full path on remote side>
+		    [access_mode=<ro|rw|migration>]
 
 		Where:
 
-		sessname: accepts a string not bigger than 256 chars, which identifies
-		a given session on the client and on the server.
-		I.e. "clt_hostname-srv_hostname" could be a natural choice.
+		sessname:
+		    accepts a string not bigger than 256 chars, which identifies
+		    a given session on the client and on the server.
+		    I.e. "clt_hostname-srv_hostname" could be a natural choice.
 
-		path:     describes a connection between the client and the server by
-		specifying destination and, when required, the source address.
-		The addresses are to be provided in the following format:
+		path:
+		    describes a connection between the client and the server by
+		    specifying destination and, when required, the source address.
+		    The addresses are to be provided in the following format::
 
-		ip:<IPv6>
-		ip:<IPv4>
-		gid:<GID>
+			ip:<IPv6>
+			ip:<IPv4>
+			gid:<GID>
 
-		for example:
+		for example::
+
+		    path=ip:10.0.0.66
 
-		path=ip:10.0.0.66
 		The single addr is treated as the destination.
 		The connection will be established to this server from any client IP address.
 
-		path=ip:10.0.0.66,ip:10.0.1.66
+		::
+
+		    path=ip:10.0.0.66,ip:10.0.1.66
+
 		First addr is the source address and the second is the destination.
 
 		If multiple "path=" options are specified multiple connection
 		will be established and data will be sent according to
 		the selected multipath policy (see RTRS mp_policy sysfs entry description).
 
-		device_path: Path to the block device on the server side. Path is specified
-		relative to the directory on server side configured in the
-		'dev_search_path' module parameter of the rnbd_server.
-		The rnbd_server prepends the <device_path> received from client
-		with <dev_search_path> and tries to open the
-		<dev_search_path>/<device_path> block device.  On success,
-		a /dev/rnbd<N> device file, a /sys/block/rnbd_client/rnbd<N>/
-		directory and an entry in /sys/class/rnbd-client/ctl/devices
-		will be created.
+		device_path:
+		    Path to the block device on the server side. Path is specified
+		    relative to the directory on server side configured in the
+		    'dev_search_path' module parameter of the rnbd_server.
+		    The rnbd_server prepends the <device_path> received from client
+		    with <dev_search_path> and tries to open the
+		    <dev_search_path>/<device_path> block device.  On success,
+		    a /dev/rnbd<N> device file, a /sys/block/rnbd_client/rnbd<N>/
+		    directory and an entry in /sys/class/rnbd-client/ctl/devices
+		    will be created.
 
 		If 'dev_search_path' contains '%SESSNAME%', then each session can
 		have different devices namespace, e.g. server was configured with
@@ -68,11 +76,12 @@ Description:	Expected format is the following:
 		client has this string "sessname=blya device_path=sda", then server
 		will try to open: /run/rnbd-devs/blya/sda.
 
-		access_mode: the access_mode parameter specifies if the device is to be
-		mapped as "ro" read-only or "rw" read-write. The server allows
-		a device to be exported in rw mode only once. The "migration"
-		access mode has to be specified if a second mapping in read-write
-		mode is desired.
+		access_mode:
+		    the access_mode parameter specifies if the device is to be
+		    mapped as "ro" read-only or "rw" read-write. The server allows
+		    a device to be exported in rw mode only once. The "migration"
+		    access mode has to be specified if a second mapping in read-write
+		    mode is desired.
 
 		By default "rw" is used.
 
@@ -91,7 +100,7 @@ Description:	Expected format is the following:
 		is the same as the device name.  By extracting the last part of the
 		path the path to the device /dev/<dev-name> can be build.
 
-		o /dev/block/$(cat /sys/class/rnbd-client/ctl/devices/<device_id>/dev)
+		* /dev/block/$(cat /sys/class/rnbd-client/ctl/devices/<device_id>/dev)
 
 		How to find the <device_id> of the device is described on the next
 		section.
@@ -106,6 +115,6 @@ Description:	For each device mapped on the client a new symbolic link is created
 		The <device_id> of each device is created as follows:
 
 		- If the 'device_path' provided during mapping contains slashes ("/"),
-		they are replaced by exclamation mark ("!") and used as as the
-		<device_id>. Otherwise, the <device_id> will be the same as the
-		"device_path" provided.
+		  they are replaced by exclamation mark ("!") and used as as the
+		  <device_id>. Otherwise, the <device_id> will be the same as the
+		  "device_path" provided.
diff --git a/Documentation/ABI/testing/sysfs-class-rtrs-client b/Documentation/ABI/testing/sysfs-class-rtrs-client
index e7e718db8941..0f7165aab251 100644
--- a/Documentation/ABI/testing/sysfs-class-rtrs-client
+++ b/Documentation/ABI/testing/sysfs-class-rtrs-client
@@ -10,10 +10,10 @@ Date:		Feb 2020
 KernelVersion:	5.7
 Contact:	Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
 Description:	RW, adds a new path (connection) to an existing session. Expected format is the
-		following:
+		following::
 
-		<[source addr,]destination addr>
-		*addr ::= [ ip:<ipv4|ipv6> | gid:<gid> ]
+		    <[source addr,]destination addr>
+		    *addr ::= [ ip:<ipv4|ipv6> | gid:<gid> ]
 
 What:		/sys/class/rtrs-client/<session-name>/max_reconnect_attempts
 Date:		Feb 2020
@@ -29,10 +29,10 @@ Contact:	Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud
 Description:	Multipath policy specifies which path should be selected on each IO:
 
 		round-robin (0):
-		select path in per CPU round-robin manner.
+		    select path in per CPU round-robin manner.
 
 		min-inflight (1):
-		select path with minimum inflights.
+		    select path with minimum inflights.
 
 What:		/sys/class/rtrs-client/<session-name>/paths/
 Date:		Feb 2020
@@ -109,8 +109,11 @@ Description:	RTRS expects that each HCA IRQ is pinned to a separate CPU. If it's
 		not the case, the processing of an I/O response could be processed on a
 		different CPU than where it was originally submitted.  This file shows
 		how many interrupts where generated on a non expected CPU.
-		"from:" is the CPU on which the IRQ was expected, but not generated.
-		"to:" is the CPU on which the IRQ was generated, but not expected.
+
+		"from:"
+		    is the CPU on which the IRQ was expected, but not generated.
+		"to:"
+		    is the CPU on which the IRQ was generated, but not expected.
 
 What:		/sys/class/rtrs-client/<session-name>/paths/<src@dst>/stats/reconnects
 Date:		Feb 2020
@@ -125,7 +128,7 @@ Date:		Feb 2020
 KernelVersion:	5.7
 Contact:	Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
 Description:	Contains statistics regarding rdma operations and inflight operations.
-		The output consists of 6 values:
+		The output consists of 6 values::
 
-		<read-count> <read-total-size> <write-count> <write-total-size> \
-		<inflights> <failovered>
+		    <read-count> <read-total-size> <write-count> \
+		    <write-total-size> <inflights> <failovered>
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
index a8daceb4a956..ee253b033280 100644
--- a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
+++ b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
@@ -102,6 +102,8 @@ Description:
 		b[15:0]
 			inform firmware the current software execution
 			stage.
+
+			==	===========================================
 			0	the first stage bootloader didn't run or
 				didn't reach the point of launching second
 				stage bootloader.
@@ -111,21 +113,29 @@ Description:
 			2	both first and second stage bootloader ran
 				and the operating system launch was
 				attempted.
+			==	===========================================
 
 		b[16]
+			==	===========================================
 			1	firmware to reset current image retry
 				counter.
 			0	no action.
+			==	===========================================
 
 		b[17]
+			==	===========================================
 			1	firmware to clear RSU log
 			0	no action.
+			==	===========================================
 
 		b[18]
 			this is negative logic
+
+			==	===========================================
 			1	no action
 			0	firmware record the notify code defined
 				in b[15:0].
+			==	===========================================
 
 What:		/sys/devices/platform/stratix10-rsu.0/dcmf0
 Date:		June 2020
diff --git a/Documentation/ABI/testing/sysfs-driver-w1_therm b/Documentation/ABI/testing/sysfs-driver-w1_therm
index 8873bbb075cb..6a37dc33ffdb 100644
--- a/Documentation/ABI/testing/sysfs-driver-w1_therm
+++ b/Documentation/ABI/testing/sysfs-driver-w1_therm
@@ -22,8 +22,10 @@ Description:
 		device data to its embedded EEPROM, either restore data
 		embedded in device EEPROM. Be aware that devices support
 		limited EEPROM writing cycles (typical 50k)
+
 			* 'save': save device RAM to EEPROM
 			* 'restore': restore EEPROM data in device RAM
+
 Users:		any user space application which wants to communicate with
 		w1_term device
 
@@ -33,9 +35,11 @@ Date:		May 2020
 Contact:	Akira Shimahara <akira215corp@gmail.com>
 Description:
 		(RO) return the power status by asking the device
+
 			* '0': device parasite powered
 			* '1': device externally powered
 			* '-xx': xx is kernel error when reading power status
+
 Users:		any user space application which wants to communicate with
 		w1_term device
 
@@ -49,10 +53,12 @@ Description:
 		will be changed only in device RAM, so it will be cleared when
 		power is lost. Trigger a 'save' to EEPROM command to keep
 		values after power-on. Read or write are :
+
 			* '9..14': device resolution in bit
-			or resolution to set in bit
+			  or resolution to set in bit
 			* '-xx': xx is kernel error when reading the resolution
 			* Anything else: do nothing
+
 		Some DS18B20 clones are fixed in 12-bit resolution, so the
 		actual resolution is read back from the chip and verified. Error
 		is reported if the results differ.
@@ -65,16 +71,18 @@ Date:		May 2020
 Contact:	Akira Shimahara <akira215corp@gmail.com>
 Description:
 		(RO) return the temperature in 1/1000 degC.
+
 			* If a bulk read has been triggered, it will directly
-			return the temperature computed when the bulk read
-			occurred, if available. If not yet available, nothing
-			is returned (a debug kernel message is sent), you
-			should retry later on.
+			  return the temperature computed when the bulk read
+			  occurred, if available. If not yet available, nothing
+			  is returned (a debug kernel message is sent), you
+			  should retry later on.
 			* If no bulk read has been triggered, it will trigger
-			a conversion and send the result. Note that the
-			conversion duration depend on the resolution (if
-			device support this feature). It takes 94ms in 9bits
-			resolution, 750ms for 12bits.
+			  a conversion and send the result. Note that the
+			  conversion duration depend on the resolution (if
+			  device support this feature). It takes 94ms in 9bits
+			  resolution, 750ms for 12bits.
+
 Users:		any user space application which wants to communicate with
 		w1_term device
 
@@ -86,12 +94,14 @@ Description:
 		(RW) return the temperature in 1/1000 degC.
 		*read*: return 2 lines with the hexa output data sent on the
 		bus, return the CRC check and temperature in 1/1000 degC
-		*write* :
+		*write*:
+
 			* '0' : save the 2 or 3 bytes to the device EEPROM
-			(i.e. TH, TL and config register)
+			  (i.e. TH, TL and config register)
 			* '9..14' : set the device resolution in RAM
-			(if supported)
+			  (if supported)
 			* Anything else: do nothing
+
 		refer to Documentation/w1/slaves/w1_therm.rst for detailed
 		information.
 Users:		any user space application which wants to communicate with
@@ -103,14 +113,21 @@ Date:		May 2020
 Contact:	Akira Shimahara <akira215corp@gmail.com>
 Description:
 		(RW) trigger a bulk read conversion. read the status
+
 		*read*:
-			* '-1': conversion in progress on at least 1 sensor
-			* '1' :	conversion complete but at least one sensor
+			* '-1':
+				conversion in progress on at least 1 sensor
+			* '1' :
+				conversion complete but at least one sensor
 				value has not been read yet
-			* '0' :	no bulk operation. Reading temperature will
+			* '0' :
+				no bulk operation. Reading temperature will
 				trigger a conversion on each device
-		*write*: 'trigger': trigger a bulk read on all supporting
+
+		*write*:
+			'trigger': trigger a bulk read on all supporting
 			devices on the bus
+
 		Note that if a bulk read is sent but one sensor is not read
 		immediately, the next access to temperature on this device
 		will return the temperature measured at the time of issue
@@ -128,14 +145,19 @@ Description:
 		reset to default (datasheet) conversion time for a new
 		resolution.
 
-		*read*: Actual conversion time in milliseconds. *write*:
-			'0': Set the default conversion time from the datasheet.
-			'1': Measure and set the conversion time. Make a single
+		*read*:
+			Actual conversion time in milliseconds.
+
+		*write*:
+			* '0':
+			     Set the default conversion time from the datasheet.
+			* '1':
+			     Measure and set the conversion time. Make a single
 			     temperature conversion, measure an actual value.
 			     Increase it by 20% for temperature range. A new
 			     conversion time can be obtained by reading this
 			     same attribute.
-			other positive value:
+			* other positive value:
 			     Set the conversion time in milliseconds.
 
 Users:		An application using the w1_term device
@@ -148,16 +170,21 @@ Description:
 		(RW) Control optional driver settings.
 		Bit masks to read/write (bitwise OR):
 
-                1: Enable check for conversion success. If byte 6 of
+		== ============================================================
+                 1 Enable check for conversion success. If byte 6 of
                    scratchpad memory is 0xC after conversion, and
                    temperature reads 85.00 (powerup value) or 127.94
                    (insufficient power) - return a conversion error.
 
-                2: Enable poll for conversion completion. Generate read cycles
+                2  Enable poll for conversion completion. Generate read cycles
                    after the conversion start and wait for 1's. In parasite
                    power mode this feature is not available.
+		== ============================================================
 
-		*read*:  Currently selected features.
-		*write*: Select features.
+		*read*:
+		    Currently selected features.
+
+		*write*:
+		    Select features.
 
 Users:		An application using the w1_term device
diff --git a/Documentation/ABI/testing/sysfs-platform-dfl-fme b/Documentation/ABI/testing/sysfs-platform-dfl-fme
index 3683cb1cdc3d..d6ab34e81b9b 100644
--- a/Documentation/ABI/testing/sysfs-platform-dfl-fme
+++ b/Documentation/ABI/testing/sysfs-platform-dfl-fme
@@ -113,8 +113,11 @@ KernelVersion:	5.5
 Contact:	Wu Hao <hao.wu@intel.com>
 Description:	Read-Only. Read this file to get the name of hwmon device, it
 		supports values:
-		    'dfl_fme_thermal' - thermal hwmon device name
-		    'dfl_fme_power'   - power hwmon device name
+
+		=================  =========================
+		'dfl_fme_thermal'  thermal hwmon device name
+		'dfl_fme_power'    power hwmon device name
+		=================  =========================
 
 What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_input
 Date:		October 2019
@@ -169,8 +172,11 @@ KernelVersion:	5.5
 Contact:	Wu Hao <hao.wu@intel.com>
 Description:	Read-Only. Read this file to get the policy of hardware threshold1
 		(see 'temp1_max'). It only supports two values (policies):
-		    0 - AP2 state (90% throttling)
-		    1 - AP1 state (50% throttling)
+
+		==  ==========================
+		 0  AP2 state (90% throttling)
+	         1  AP1 state (50% throttling)
+		==  ==========================
 
 What:		/sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_input
 Date:		October 2019
diff --git a/Documentation/ABI/testing/sysfs-platform-dptf b/Documentation/ABI/testing/sysfs-platform-dptf
index 2cbc660d163b..141834342a4d 100644
--- a/Documentation/ABI/testing/sysfs-platform-dptf
+++ b/Documentation/ABI/testing/sysfs-platform-dptf
@@ -27,12 +27,15 @@ KernelVersion:	v4.10
 Contact:	linux-acpi@vger.kernel.org
 Description:
 		(RO) Display the platform power source
+
+		========= ============================
 		bits[3:0] Current power source
-			0x00 = DC
-			0x01 = AC
-			0x02 = USB
-			0x03 = Wireless Charger
+			  - 0x00 = DC
+			  - 0x01 = AC
+			  - 0x02 = USB
+			  - 0x03 = Wireless Charger
 		bits[7:4] Power source sequence number
+		========= ============================
 
 What:		/sys/bus/platform/devices/INT3407:00/dptf_power/battery_steady_power
 Date:		Jul, 2016
diff --git a/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update b/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update
index 5aa618987cad..02ae1e9bbfc8 100644
--- a/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update
+++ b/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update
@@ -8,5 +8,6 @@ Description:
 		of 0 and userspace can signal SBL to update firmware,
 		on next reboot, by writing a value of 1.
 		There are two available states:
+
 		    * 0 -> Skip firmware update while rebooting
 		    * 1 -> Attempt firmware update on next reboot
diff --git a/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
index 401d202f478b..e79ca22e2f45 100644
--- a/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
+++ b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
@@ -5,10 +5,13 @@ Contact:	"Liming Sun <lsun@mellanox.com>"
 Description:
 		The Life-cycle state of the SoC, which could be one of the
 		following values.
-		  Production - Production state and can be updated to secure
-		  GA Secured - Secure chip and not able to change state
-		  GA Non-Secured - Non-Secure chip and not able to change state
-		  RMA - Return Merchandise Authorization
+
+		==============  =============================================
+		Production      Production state and can be updated to secure
+		GA Secured      Secure chip and not able to change state
+		GA Non-Secured  Non-Secure chip and not able to change state
+		RMA             Return Merchandise Authorization
+		==============  =============================================
 
 What:		/sys/bus/platform/devices/MLNXBF04:00/post_reset_wdog
 Date:		Oct 2019
@@ -25,10 +28,13 @@ KernelVersion:	5.5
 Contact:	"Liming Sun <lsun@mellanox.com>"
 Description:
 		The source of the boot stream for the next reset. It could be
-		one of the following values.
-		  external - boot from external source (USB or PCIe)
-		  emmc - boot from the onchip eMMC
-		  emmc_legacy - boot from the onchip eMMC in legacy (slow) mode
+		one of the following values:
+
+		===========  ===============================================
+		external     boot from external source (USB or PCIe)
+		emmc         boot from the onchip eMMC
+		emmc_legacy  boot from the onchip eMMC in legacy (slow) mode
+		===========  ===============================================
 
 What:		/sys/bus/platform/devices/MLNXBF04:00/second_reset_action
 Date:		Oct 2019
@@ -38,11 +44,14 @@ Description:
 		Update the source of the boot stream after next reset. It could
 		be one of the following values and will be applied after next
 		reset.
-		  external - boot from external source (USB or PCIe)
-		  emmc - boot from the onchip eMMC
-		  emmc_legacy - boot from the onchip eMMC in legacy (slow) mode
-		  swap_emmc - swap the primary / secondary boot partition
-		  none - cancel the action
+
+		===========  ===============================================
+		external     boot from external source (USB or PCIe)
+		emmc         boot from the onchip eMMC
+		emmc_legacy  boot from the onchip eMMC in legacy (slow) mode
+		swap_emmc    swap the primary / secondary boot partition
+		none         cancel the action
+		===========  ===============================================
 
 What:		/sys/bus/platform/devices/MLNXBF04:00/secure_boot_fuse_state
 Date:		Oct 2019
@@ -50,9 +59,12 @@ KernelVersion:	5.5
 Contact:	"Liming Sun <lsun@mellanox.com>"
 Description:
 		The state of eFuse versions with the following values.
-		  InUse - burnt, valid and currently in use
-		  Used - burnt and valid
-		  Free - not burnt and free to use
-		  Skipped - not burnt but not free (skipped)
-		  Wasted - burnt and invalid
-		  Invalid - not burnt but marked as valid (error state).
+
+		=======  ===============================================
+		InUse    burnt, valid and currently in use
+		Used     burnt and valid
+		Free     not burnt and free to use
+		Skipped  not burnt but not free (skipped)
+		Wasted   burnt and invalid
+		Invalid  not burnt but marked as valid (error state).
+		=======  ===============================================
diff --git a/Documentation/ABI/testing/sysfs-platform-wilco-ec b/Documentation/ABI/testing/sysfs-platform-wilco-ec
index 5f60b184a5a5..4439d0644091 100644
--- a/Documentation/ABI/testing/sysfs-platform-wilco-ec
+++ b/Documentation/ABI/testing/sysfs-platform-wilco-ec
@@ -39,6 +39,7 @@ Description:
                which affects charging via the special USB PowerShare port
                (marked with a small lightning bolt or battery icon) when in
                low power states:
+
                - In S0, the port will always provide power.
                - In S0ix, if usb_charge is enabled, then power will be
                  supplied to the port when on AC or if battery is > 50%.
-- 
2.26.2

[PATCH v2 29/39] docs: ABI: vdso: use the right format for ABI

[Mauro Carvalho Chehab]

This ABI is not following the format described at ABI/README.

Use it, filling in the blanks with the git log that added it,
and using the current e-mail from Andy.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/stable/vdso | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/ABI/stable/vdso b/Documentation/ABI/stable/vdso
index 73ed1240a5c0..951838d42781 100644
--- a/Documentation/ABI/stable/vdso
+++ b/Documentation/ABI/stable/vdso
@@ -1,3 +1,9 @@
+What:		vDSO
+Date:		July 2011
+KernelVersion:	3.0
+Contact:	Andy Lutomirski <luto@kernel.org>
+Description:
+
 On some architectures, when the kernel loads any userspace program it
 maps an ELF DSO into that program's address space.  This DSO is called
 the vDSO and it often contains useful and highly-optimized alternatives
-- 
2.26.2

[PATCH v2 30/39] docs: ABI: sysfs-bus-nvdimm: use the right format for ABI

[Mauro Carvalho Chehab]

This ABI is not following the format described at ABI/README.

Use it, filling in the blanks with the git log that added it,
and using the current e-mail from Dan.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/testing/sysfs-bus-nvdimm | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/ABI/testing/sysfs-bus-nvdimm b/Documentation/ABI/testing/sysfs-bus-nvdimm
index d64380262be8..bff84a16812a 100644
--- a/Documentation/ABI/testing/sysfs-bus-nvdimm
+++ b/Documentation/ABI/testing/sysfs-bus-nvdimm
@@ -1,2 +1,8 @@
+What:          nvdimm
+Date:          July 2020
+KernelVersion: 5.8
+Contact:       Dan Williams <dan.j.williams@intel.com>
+Description:
+
 The libnvdimm sub-system implements a common sysfs interface for
 platform nvdimm resources. See Documentation/driver-api/nvdimm/.
-- 
2.26.2

[PATCH v2 31/39] docs: ABI: cleanup several ABI documents

[Mauro Carvalho Chehab]

There are some ABI documents that, while they don't generate
any warnings, they have issues when parsed by get_abi.pl script
on its output result.

Address them, in order to provide a clean output.

Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> #for IIO
Reviewed-by: Tom Rix <trix@redhat.com> # for fpga-manager
Reviewed-By: Kajol Jain<kjain@linux.ibm.com> # for sysfs-bus-event_source-devices-hv_gpci and sysfs-bus-event_source-devices-hv_24x7
Acked-by: Oded Gabbay <oded.gabbay@gmail.com> # for Habanalabs
Acked-by: Vaibhav Jain <vaibhav@linux.ibm.com> # for sysfs-bus-papr-pmem
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/obsolete/sysfs-class-dax    |   8 +-
 .../ABI/obsolete/sysfs-driver-hid-roccat-pyra |   3 +
 Documentation/ABI/removed/devfs               |   1 +
 Documentation/ABI/removed/raw1394             |   1 +
 Documentation/ABI/removed/sysfs-class-rfkill  |   2 +-
 Documentation/ABI/removed/video1394           |   1 +
 Documentation/ABI/stable/firewire-cdev        |  63 ++---
 Documentation/ABI/stable/sysfs-acpi-pmprofile |   4 +-
 Documentation/ABI/stable/sysfs-bus-w1         |   1 +
 Documentation/ABI/stable/sysfs-class-tpm      |   4 +-
 Documentation/ABI/stable/sysfs-driver-speakup |   4 +
 Documentation/ABI/testing/configfs-most       | 135 +++++++----
 .../ABI/testing/configfs-usb-gadget-ecm       |  12 +-
 .../ABI/testing/configfs-usb-gadget-eem       |  10 +-
 .../ABI/testing/configfs-usb-gadget-loopback  |   6 +-
 .../testing/configfs-usb-gadget-mass-storage  |  18 +-
 .../ABI/testing/configfs-usb-gadget-midi      |  14 +-
 .../ABI/testing/configfs-usb-gadget-printer   |   6 +-
 .../testing/configfs-usb-gadget-sourcesink    |  18 +-
 .../ABI/testing/configfs-usb-gadget-subset    |  10 +-
 .../ABI/testing/configfs-usb-gadget-uac2      |  14 +-
 .../ABI/testing/configfs-usb-gadget-uvc       |   2 +-
 .../ABI/testing/debugfs-cec-error-inj         |   2 +-
 .../ABI/testing/debugfs-driver-habanalabs     |  12 +-
 .../ABI/testing/debugfs-pfo-nx-crypto         |  28 +--
 Documentation/ABI/testing/debugfs-pktcdvd     |   2 +-
 .../ABI/testing/debugfs-turris-mox-rwtm       |  10 +-
 Documentation/ABI/testing/debugfs-wilco-ec    |  21 +-
 Documentation/ABI/testing/dell-smbios-wmi     |  32 +--
 Documentation/ABI/testing/gpio-cdev           |  13 +-
 Documentation/ABI/testing/procfs-diskstats    |   6 +-
 Documentation/ABI/testing/procfs-smaps_rollup |  48 ++--
 Documentation/ABI/testing/pstore              |  19 +-
 Documentation/ABI/testing/sysfs-block-rnbd    |   4 +-
 Documentation/ABI/testing/sysfs-bus-acpi      |   1 +
 .../testing/sysfs-bus-coresight-devices-etb10 |   5 +-
 Documentation/ABI/testing/sysfs-bus-css       |   3 +
 Documentation/ABI/testing/sysfs-bus-dfl       |   2 +
 .../sysfs-bus-event_source-devices-hv_24x7    |   6 +-
 .../sysfs-bus-event_source-devices-hv_gpci    |   7 +-
 Documentation/ABI/testing/sysfs-bus-fcoe      |  68 ++++--
 Documentation/ABI/testing/sysfs-bus-fsl-mc    |  12 +-
 .../ABI/testing/sysfs-bus-i2c-devices-fsa9480 |  26 +-
 Documentation/ABI/testing/sysfs-bus-i3c       |   2 +
 Documentation/ABI/testing/sysfs-bus-iio       |  19 +-
 .../ABI/testing/sysfs-bus-iio-adc-hi8435      |   5 +
 .../ABI/testing/sysfs-bus-iio-adc-stm32       |   3 +
 .../ABI/testing/sysfs-bus-iio-distance-srf08  |   7 +-
 .../testing/sysfs-bus-iio-frequency-ad9523    |   2 +
 .../testing/sysfs-bus-iio-frequency-adf4371   |  10 +-
 .../ABI/testing/sysfs-bus-iio-health-afe440x  |  12 +-
 .../ABI/testing/sysfs-bus-iio-light-isl29018  |   6 +-
 .../testing/sysfs-bus-intel_th-devices-gth    |  11 +-
 Documentation/ABI/testing/sysfs-bus-papr-pmem |  23 +-
 Documentation/ABI/testing/sysfs-bus-pci       |  22 +-
 .../ABI/testing/sysfs-bus-pci-devices-catpt   |   1 +
 .../testing/sysfs-bus-pci-drivers-ehci_hcd    |   4 +-
 Documentation/ABI/testing/sysfs-bus-rbd       |  37 ++-
 Documentation/ABI/testing/sysfs-bus-siox      |   3 +
 .../ABI/testing/sysfs-bus-thunderbolt         |  18 +-
 Documentation/ABI/testing/sysfs-bus-usb       |   2 +
 .../sysfs-class-backlight-driver-lm3533       |  26 +-
 Documentation/ABI/testing/sysfs-class-bdi     |   1 -
 .../ABI/testing/sysfs-class-chromeos          |  15 +-
 Documentation/ABI/testing/sysfs-class-cxl     |   8 +-
 Documentation/ABI/testing/sysfs-class-devlink |  30 ++-
 Documentation/ABI/testing/sysfs-class-extcon  |  34 +--
 .../ABI/testing/sysfs-class-fpga-manager      |   5 +-
 Documentation/ABI/testing/sysfs-class-gnss    |   2 +
 Documentation/ABI/testing/sysfs-class-led     |   1 +
 .../testing/sysfs-class-led-driver-el15203000 |  30 +--
 .../ABI/testing/sysfs-class-led-driver-lm3533 |  44 ++--
 .../ABI/testing/sysfs-class-led-flash         |  27 ++-
 .../testing/sysfs-class-led-trigger-netdev    |   7 +
 .../testing/sysfs-class-led-trigger-usbport   |   1 +
 .../ABI/testing/sysfs-class-leds-gt683r       |   8 +-
 Documentation/ABI/testing/sysfs-class-net     |  61 +++--
 .../ABI/testing/sysfs-class-net-cdc_ncm       |   6 +-
 .../ABI/testing/sysfs-class-net-phydev        |   2 +
 Documentation/ABI/testing/sysfs-class-pktcdvd |  36 +--
 Documentation/ABI/testing/sysfs-class-power   |  12 +-
 .../ABI/testing/sysfs-class-power-mp2629      |   1 +
 .../ABI/testing/sysfs-class-power-twl4030     |   4 +-
 Documentation/ABI/testing/sysfs-class-rapidio |  46 ++--
 .../ABI/testing/sysfs-class-regulator         |  36 +--
 .../ABI/testing/sysfs-class-remoteproc        |  14 +-
 ...ysfs-class-rtc-rtc0-device-rtc_calibration |   1 +
 Documentation/ABI/testing/sysfs-class-uwb_rc  |  13 +-
 .../ABI/testing/sysfs-class-watchdog          |   7 +-
 Documentation/ABI/testing/sysfs-dev           |   7 +-
 .../ABI/testing/sysfs-devices-mapping         |  41 ++--
 .../ABI/testing/sysfs-devices-memory          |  15 +-
 .../sysfs-devices-platform-_UDC_-gadget       |  10 +-
 .../ABI/testing/sysfs-devices-platform-ipmi   |  52 ++--
 .../ABI/testing/sysfs-devices-system-cpu      |   4 +-
 .../ABI/testing/sysfs-driver-hid-lenovo       |  10 +
 .../ABI/testing/sysfs-driver-hid-ntrig        |  13 +-
 .../ABI/testing/sysfs-driver-hid-roccat-kone  |  19 ++
 .../ABI/testing/sysfs-driver-hid-wiimote      |   1 +
 .../ABI/testing/sysfs-driver-input-exc3000    |   2 +
 .../ABI/testing/sysfs-driver-jz4780-efuse     |   6 +-
 .../ABI/testing/sysfs-driver-pciback          |   6 +-
 Documentation/ABI/testing/sysfs-driver-ufs    | 228 ++++++++++++++----
 .../ABI/testing/sysfs-driver-w1_ds28e17       |   3 +
 Documentation/ABI/testing/sysfs-firmware-acpi |  16 +-
 .../ABI/testing/sysfs-firmware-efi-esrt       |  28 ++-
 .../testing/sysfs-firmware-efi-runtime-map    |  14 +-
 .../ABI/testing/sysfs-firmware-qemu_fw_cfg    |  20 +-
 Documentation/ABI/testing/sysfs-firmware-sfi  |   6 +-
 .../ABI/testing/sysfs-firmware-sgi_uv         |   6 +-
 Documentation/ABI/testing/sysfs-fs-f2fs       |  48 ++--
 Documentation/ABI/testing/sysfs-kernel-mm-ksm |   5 +-
 Documentation/ABI/testing/sysfs-kernel-slab   |   3 +
 Documentation/ABI/testing/sysfs-module        |  17 +-
 .../ABI/testing/sysfs-platform-dell-laptop    |  10 +-
 .../ABI/testing/sysfs-platform-dell-smbios    |   4 +-
 .../testing/sysfs-platform-i2c-demux-pinctrl  |   4 +-
 Documentation/ABI/testing/sysfs-platform-kim  |   1 +
 .../testing/sysfs-platform-phy-rcar-gen3-usb2 |  10 +-
 .../ABI/testing/sysfs-platform-renesas_usb3   |  10 +-
 Documentation/ABI/testing/sysfs-power         |  21 +-
 Documentation/ABI/testing/sysfs-profiling     |   2 +-
 Documentation/ABI/testing/sysfs-wusb_cbaf     |   3 +-
 Documentation/ABI/testing/usb-charger-uevent  |  82 ++++---
 Documentation/ABI/testing/usb-uevent          |  32 +--
 scripts/get_abi.pl                            |   2 -
 126 files changed, 1323 insertions(+), 767 deletions(-)

diff --git a/Documentation/ABI/obsolete/sysfs-class-dax b/Documentation/ABI/obsolete/sysfs-class-dax
index 2cb9fc5e8bd1..0faf1354cd05 100644
--- a/Documentation/ABI/obsolete/sysfs-class-dax
+++ b/Documentation/ABI/obsolete/sysfs-class-dax
@@ -8,11 +8,11 @@ Description:	Device DAX is the device-centric analogue of Filesystem
 		system.  Device DAX is strict, precise and predictable.
 		Specifically this interface:
 
-		1/ Guarantees fault granularity with respect to a given
-		page size (pte, pmd, or pud) set at configuration time.
+		1. Guarantees fault granularity with respect to a given
+		   page size (pte, pmd, or pud) set at configuration time.
 
-		2/ Enforces deterministic behavior by being strict about
-		what fault scenarios are supported.
+		2. Enforces deterministic behavior by being strict about
+		   what fault scenarios are supported.
 
 		The /sys/class/dax/ interface enumerates all the
 		device-dax instances in the system. The ABI is
diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra
index 5d41ebadf15e..66545c587a64 100644
--- a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra
+++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra
@@ -7,10 +7,13 @@ Description:	It is possible to switch the cpi setting of the mouse with the
 		setting reported by the mouse. This number has to be further
 		processed to receive the real dpi value:
 
+		===== ====
 		VALUE DPI
+		===== ====
 		1     400
 		2     800
 		4     1600
+		===== ====
 
 		This file is readonly.
 		Has never been used. If bookkeeping is done, it's done in userland tools.
diff --git a/Documentation/ABI/removed/devfs b/Documentation/ABI/removed/devfs
index 0020c49933c4..24fb35adf277 100644
--- a/Documentation/ABI/removed/devfs
+++ b/Documentation/ABI/removed/devfs
@@ -5,6 +5,7 @@ Description:
 	devfs has been unmaintained for a number of years, has unfixable
 	races, contains a naming policy within the kernel that is
 	against the LSB, and can be replaced by using udev.
+
 	The files fs/devfs/*, include/linux/devfs_fs*.h were removed,
 	along with the assorted devfs function calls throughout the
 	kernel tree.
diff --git a/Documentation/ABI/removed/raw1394 b/Documentation/ABI/removed/raw1394
index ec333e676322..9ec7ec493920 100644
--- a/Documentation/ABI/removed/raw1394
+++ b/Documentation/ABI/removed/raw1394
@@ -7,6 +7,7 @@ Description:
 	to implement sensible device security policies, and its low level
 	of abstraction that required userspace clients to duplicate much
 	of the kernel's ieee1394 core functionality.
+
 	Replaced by /dev/fw*, i.e. the <linux/firewire-cdev.h> ABI of
 	firewire-core.
 
diff --git a/Documentation/ABI/removed/sysfs-class-rfkill b/Documentation/ABI/removed/sysfs-class-rfkill
index 9c08c7f98ffb..f25174eafd55 100644
--- a/Documentation/ABI/removed/sysfs-class-rfkill
+++ b/Documentation/ABI/removed/sysfs-class-rfkill
@@ -10,4 +10,4 @@ Description:	This file was deprecated because there no longer was a way to
 		claim just control over a single rfkill instance.
 		This file was scheduled to be removed in 2012, and was removed
 		in 2016.
-Values: 	0: Kernel handles events
+Values:		0: Kernel handles events
diff --git a/Documentation/ABI/removed/video1394 b/Documentation/ABI/removed/video1394
index c39c25aee77b..1905d35a6619 100644
--- a/Documentation/ABI/removed/video1394
+++ b/Documentation/ABI/removed/video1394
@@ -8,6 +8,7 @@ Description:
 	performance issues in its first generation.  Any video1394 user had
 	to use raw1394 + libraw1394 too because video1394 did not provide
 	asynchronous I/O for device discovery and configuration.
+
 	Replaced by /dev/fw*, i.e. the <linux/firewire-cdev.h> ABI of
 	firewire-core.
 
diff --git a/Documentation/ABI/stable/firewire-cdev b/Documentation/ABI/stable/firewire-cdev
index c9e8ff026154..261f85b13154 100644
--- a/Documentation/ABI/stable/firewire-cdev
+++ b/Documentation/ABI/stable/firewire-cdev
@@ -16,6 +16,7 @@ Description:
 		different scope:
 
 		  - The 1394 node which is associated with the file:
+
 			  - Asynchronous request transmission
 			  - Get the Configuration ROM
 			  - Query node ID
@@ -23,6 +24,7 @@ Description:
 			    and local node
 
 		  - The 1394 bus (i.e. "card") to which the node is attached to:
+
 			  - Isochronous stream transmission and reception
 			  - Asynchronous stream transmission and reception
 			  - Asynchronous broadcast request transmission
@@ -35,6 +37,7 @@ Description:
 			  - Bus reset initiation, bus reset event reception
 
 		  - All 1394 buses:
+
 			  - Allocation of IEEE 1212 address ranges on the local
 			    link layers, reception of inbound requests to such
 			    an address range, asynchronous response transmission
@@ -59,50 +62,50 @@ Description:
 		The following file operations are supported:
 
 		open(2)
-		Currently the only useful flags are O_RDWR.
+		    Currently the only useful flags are O_RDWR.
 
 		ioctl(2)
-		Initiate various actions.  Some take immediate effect, others
-		are performed asynchronously while or after the ioctl returns.
-		See the inline documentation in <linux/firewire-cdev.h> for
-		descriptions of all ioctls.
+		    Initiate various actions.  Some take immediate effect, others
+		    are performed asynchronously while or after the ioctl returns.
+		    See the inline documentation in <linux/firewire-cdev.h> for
+		    descriptions of all ioctls.
 
 		poll(2), select(2), epoll_wait(2) etc.
-		Watch for events to become available to be read.
+		    Watch for events to become available to be read.
 
 		read(2)
-		Receive various events.  There are solicited events like
-		outbound asynchronous transaction completion or isochronous
-		buffer completion, and unsolicited events such as bus resets,
-		request reception, or PHY packet reception.  Always use a read
-		buffer which is large enough to receive the largest event that
-		could ever arrive.  See <linux/firewire-cdev.h> for descriptions
-		of all event types and for which ioctls affect reception of
-		events.
+		    Receive various events.  There are solicited events like
+		    outbound asynchronous transaction completion or isochronous
+		    buffer completion, and unsolicited events such as bus resets,
+		    request reception, or PHY packet reception.  Always use a read
+		    buffer which is large enough to receive the largest event that
+		    could ever arrive.  See <linux/firewire-cdev.h> for descriptions
+		    of all event types and for which ioctls affect reception of
+		    events.
 
 		mmap(2)
-		Allocate a DMA buffer for isochronous reception or transmission
-		and map it into the process address space.  The arguments should
-		be used as follows:  addr = NULL, length = the desired buffer
-		size, i.e. number of packets times size of largest packet,
-		prot = at least PROT_READ for reception and at least PROT_WRITE
-		for transmission, flags = MAP_SHARED, fd = the handle to the
-		/dev/fw*, offset = 0.
+		    Allocate a DMA buffer for isochronous reception or transmission
+		    and map it into the process address space.  The arguments should
+		    be used as follows:  addr = NULL, length = the desired buffer
+		    size, i.e. number of packets times size of largest packet,
+		    prot = at least PROT_READ for reception and at least PROT_WRITE
+		    for transmission, flags = MAP_SHARED, fd = the handle to the
+		    /dev/fw*, offset = 0.
 
 		Isochronous reception works in packet-per-buffer fashion except
 		for multichannel reception which works in buffer-fill mode.
 
 		munmap(2)
-		Unmap the isochronous I/O buffer from the process address space.
+		    Unmap the isochronous I/O buffer from the process address space.
 
 		close(2)
-		Besides stopping and freeing I/O contexts that were associated
-		with the file descriptor, back out any changes to the local
-		nodes' Configuration ROM.  Deallocate isochronous channels and
-		bandwidth at the IRM that were marked for kernel-assisted
-		re- and deallocation.
+		    Besides stopping and freeing I/O contexts that were associated
+		    with the file descriptor, back out any changes to the local
+		    nodes' Configuration ROM.  Deallocate isochronous channels and
+		    bandwidth at the IRM that were marked for kernel-assisted
+		    re- and deallocation.
 
-Users:		libraw1394
-		libdc1394
-		libhinawa
+Users:		libraw1394;
+		libdc1394;
+		libhinawa;
 		tools like linux-firewire-utils, fwhack, ...
diff --git a/Documentation/ABI/stable/sysfs-acpi-pmprofile b/Documentation/ABI/stable/sysfs-acpi-pmprofile
index fd97d22b677f..2d6314f0e4e4 100644
--- a/Documentation/ABI/stable/sysfs-acpi-pmprofile
+++ b/Documentation/ABI/stable/sysfs-acpi-pmprofile
@@ -1,8 +1,8 @@
-What: 		/sys/firmware/acpi/pm_profile
+What:		/sys/firmware/acpi/pm_profile
 Date:		03-Nov-2011
 KernelVersion:	v3.2
 Contact:	linux-acpi@vger.kernel.org
-Description: 	The ACPI pm_profile sysfs interface exports the platform
+Description:	The ACPI pm_profile sysfs interface exports the platform
 		power management (and performance) requirement expectations
 		as provided by BIOS. The integer value is directly passed as
 		retrieved from the FADT ACPI table.
diff --git a/Documentation/ABI/stable/sysfs-bus-w1 b/Documentation/ABI/stable/sysfs-bus-w1
index 992dfb183ed0..5cd5e872bcae 100644
--- a/Documentation/ABI/stable/sysfs-bus-w1
+++ b/Documentation/ABI/stable/sysfs-bus-w1
@@ -6,6 +6,7 @@ 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.rst for detailed information.
 Users:		any user space application which wants to know bus scanning
 		interval
diff --git a/Documentation/ABI/stable/sysfs-class-tpm b/Documentation/ABI/stable/sysfs-class-tpm
index ec464cf7861a..91ca63ec7581 100644
--- a/Documentation/ABI/stable/sysfs-class-tpm
+++ b/Documentation/ABI/stable/sysfs-class-tpm
@@ -191,6 +191,6 @@ Contact:	linux-integrity@vger.kernel.org
 Description:	The "tpm_version_major" property shows the TCG spec major version
 		implemented by the TPM device.
 
-		Example output:
+		Example output::
 
-		2
+		  2
diff --git a/Documentation/ABI/stable/sysfs-driver-speakup b/Documentation/ABI/stable/sysfs-driver-speakup
index c6a32c434ce9..792f58ba327d 100644
--- a/Documentation/ABI/stable/sysfs-driver-speakup
+++ b/Documentation/ABI/stable/sysfs-driver-speakup
@@ -69,6 +69,7 @@ Description:	Controls if typing interrupts output from speakup. With
 		speakup if for example
 		the say screen command is used before the
 		entire screen  is read.
+
 		With no_interrupt set to one, if the say
 		screen command is used, and one then types on the keyboard,
 		speakup will continue to say the whole screen regardless until
@@ -215,8 +216,10 @@ Description:	This file contains names for key states.
 		Again, these are part of the help system.  For instance, if you
 		had pressed speakup + keypad 3, you would hear:
 		"speakup keypad 3 is go to bottom edge."
+
 		The speakup key is depressed, so the name of the key state is
 		speakup.
+
 		This part of the message comes from the states collection.
 
 What:		/sys/accessibility/speakup/i18n/characters
@@ -297,6 +300,7 @@ KernelVersion:	2.6
 Contact:	speakup@linux-speakup.org
 Description:	Controls if punctuation is spoken by speakup, or by the
 		synthesizer.
+
 		For example, speakup speaks ">" as "greater", while
 		the espeak synthesizer used by the soft driver speaks "greater
 		than". Zero lets speakup speak the punctuation. One lets the
diff --git a/Documentation/ABI/testing/configfs-most b/Documentation/ABI/testing/configfs-most
index ed67a4d9f6d6..bc6b8bd18da4 100644
--- a/Documentation/ABI/testing/configfs-most
+++ b/Documentation/ABI/testing/configfs-most
@@ -15,22 +15,28 @@ KernelVersion:  5.2
 Description:
 		The attributes:
 
-		buffer_size	configure the buffer size for this channel
+		buffer_size
+				configure the buffer size for this channel
 
-		subbuffer_size	configure the sub-buffer size for this channel
+		subbuffer_size
+				configure the sub-buffer size for this channel
 				(needed for synchronous and isochrnous data)
 
 
-		num_buffers	configure number of buffers used for this
+		num_buffers
+				configure number of buffers used for this
 				channel
 
-		datatype	configure type of data that will travel over
+		datatype
+				configure type of data that will travel over
 				this channel
 
-		direction	configure whether this link will be an input
+		direction
+				configure whether this link will be an input
 				or output
 
-		dbr_size	configure DBR data buffer size (this is used
+		dbr_size
+				configure DBR data buffer size (this is used
 				for MediaLB communication only)
 
 		packets_per_xact
@@ -39,18 +45,23 @@ Description:
 				transmitted via USB (this is used for USB
 				communication only)
 
-		device		name of the device the link is to be attached to
+		device
+				name of the device the link is to be attached to
 
-		channel		name of the channel the link is to be attached to
+		channel
+				name of the channel the link is to be attached to
 
-		comp_params	pass parameters needed by some components
+		comp_params
+				pass parameters needed by some components
 
-		create_link	write '1' to this attribute to trigger the
+		create_link
+				write '1' to this attribute to trigger the
 				creation of the link. In case of speculative
 				configuration, the creation is post-poned until
 				a physical device is being attached to the bus.
 
-		destroy_link	write '1' to this attribute to destroy an
+		destroy_link
+				write '1' to this attribute to destroy an
 				active link
 
 What: 		/sys/kernel/config/most_video/<link>
@@ -59,22 +70,28 @@ KernelVersion:  5.2
 Description:
 		The attributes:
 
-		buffer_size	configure the buffer size for this channel
+		buffer_size
+				configure the buffer size for this channel
 
-		subbuffer_size	configure the sub-buffer size for this channel
+		subbuffer_size
+				configure the sub-buffer size for this channel
 				(needed for synchronous and isochrnous data)
 
 
-		num_buffers	configure number of buffers used for this
+		num_buffers
+				configure number of buffers used for this
 				channel
 
-		datatype	configure type of data that will travel over
+		datatype
+				configure type of data that will travel over
 				this channel
 
-		direction	configure whether this link will be an input
+		direction
+				configure whether this link will be an input
 				or output
 
-		dbr_size	configure DBR data buffer size (this is used
+		dbr_size
+				configure DBR data buffer size (this is used
 				for MediaLB communication only)
 
 		packets_per_xact
@@ -83,18 +100,23 @@ Description:
 				transmitted via USB (this is used for USB
 				communication only)
 
-		device		name of the device the link is to be attached to
+		device
+				name of the device the link is to be attached to
 
-		channel		name of the channel the link is to be attached to
+		channel
+				name of the channel the link is to be attached to
 
-		comp_params	pass parameters needed by some components
+		comp_params
+				pass parameters needed by some components
 
-		create_link	write '1' to this attribute to trigger the
+		create_link
+				write '1' to this attribute to trigger the
 				creation of the link. In case of speculative
 				configuration, the creation is post-poned until
 				a physical device is being attached to the bus.
 
-		destroy_link	write '1' to this attribute to destroy an
+		destroy_link
+				write '1' to this attribute to destroy an
 				active link
 
 What: 		/sys/kernel/config/most_net/<link>
@@ -103,22 +125,28 @@ KernelVersion:  5.2
 Description:
 		The attributes:
 
-		buffer_size	configure the buffer size for this channel
+		buffer_size
+				configure the buffer size for this channel
 
-		subbuffer_size	configure the sub-buffer size for this channel
+		subbuffer_size
+				configure the sub-buffer size for this channel
 				(needed for synchronous and isochrnous data)
 
 
-		num_buffers	configure number of buffers used for this
+		num_buffers
+				configure number of buffers used for this
 				channel
 
-		datatype	configure type of data that will travel over
+		datatype
+				configure type of data that will travel over
 				this channel
 
-		direction	configure whether this link will be an input
+		direction
+				configure whether this link will be an input
 				or output
 
-		dbr_size	configure DBR data buffer size (this is used
+		dbr_size
+				configure DBR data buffer size (this is used
 				for MediaLB communication only)
 
 		packets_per_xact
@@ -127,18 +155,23 @@ Description:
 				transmitted via USB (this is used for USB
 				communication only)
 
-		device		name of the device the link is to be attached to
+		device
+				name of the device the link is to be attached to
 
-		channel		name of the channel the link is to be attached to
+		channel
+				name of the channel the link is to be attached to
 
-		comp_params	pass parameters needed by some components
+		comp_params
+				pass parameters needed by some components
 
-		create_link	write '1' to this attribute to trigger the
+		create_link
+				write '1' to this attribute to trigger the
 				creation of the link. In case of speculative
 				configuration, the creation is post-poned until
 				a physical device is being attached to the bus.
 
-		destroy_link	write '1' to this attribute to destroy an
+		destroy_link
+				write '1' to this attribute to destroy an
 				active link
 
 What: 		/sys/kernel/config/most_sound/<card>
@@ -147,7 +180,8 @@ KernelVersion:  5.2
 Description:
 		The attributes:
 
-		create_card	write '1' to this attribute to trigger the
+		create_card
+				write '1' to this attribute to trigger the
                                 registration of the sound card with the ALSA
 				subsystem.
 
@@ -157,22 +191,28 @@ KernelVersion:  5.2
 Description:
 		The attributes:
 
-		buffer_size	configure the buffer size for this channel
+		buffer_size
+				configure the buffer size for this channel
 
-		subbuffer_size	configure the sub-buffer size for this channel
+		subbuffer_size
+				configure the sub-buffer size for this channel
 				(needed for synchronous and isochrnous data)
 
 
-		num_buffers	configure number of buffers used for this
+		num_buffers
+				configure number of buffers used for this
 				channel
 
-		datatype	configure type of data that will travel over
+		datatype
+				configure type of data that will travel over
 				this channel
 
-		direction	configure whether this link will be an input
+		direction
+				configure whether this link will be an input
 				or output
 
-		dbr_size	configure DBR data buffer size (this is used
+		dbr_size
+				configure DBR data buffer size (this is used
 				for MediaLB communication only)
 
 		packets_per_xact
@@ -181,16 +221,21 @@ Description:
 				transmitted via USB (this is used for USB
 				communication only)
 
-		device		name of the device the link is to be attached to
+		device
+				name of the device the link is to be attached to
 
-		channel		name of the channel the link is to be attached to
+		channel
+				name of the channel the link is to be attached to
 
-		comp_params	pass parameters needed by some components
+		comp_params
+				pass parameters needed by some components
 
-		create_link	write '1' to this attribute to trigger the
+		create_link
+				write '1' to this attribute to trigger the
 				creation of the link. In case of speculative
 				configuration, the creation is post-poned until
 				a physical device is being attached to the bus.
 
-		destroy_link	write '1' to this attribute to destroy an
+		destroy_link
+				write '1' to this attribute to destroy an
 				active link
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-ecm b/Documentation/ABI/testing/configfs-usb-gadget-ecm
index 0addf7704b4c..272bc1e4ce2e 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-ecm
+++ b/Documentation/ABI/testing/configfs-usb-gadget-ecm
@@ -4,13 +4,17 @@ KernelVersion:	3.11
 Description:
 		The attributes:
 
-		ifname		- network device interface name associated with
+		ifname
+			      - network device interface name associated with
 				this function instance
-		qmult		- queue length multiplier for high and
+		qmult	
+			      - queue length multiplier for high and
 				super speed
-		host_addr	- MAC address of host's end of this
+		host_addr
+			      - MAC address of host's end of this
 				Ethernet over USB link
-		dev_addr	- MAC address of device's end of this
+		dev_addr
+			      - MAC address of device's end of this
 				Ethernet over USB link
 
 
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-eem b/Documentation/ABI/testing/configfs-usb-gadget-eem
index a4c57158fcde..178c3d5fb647 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-eem
+++ b/Documentation/ABI/testing/configfs-usb-gadget-eem
@@ -4,11 +4,13 @@ KernelVersion:	3.11
 Description:
 		The attributes:
 
-		ifname		- network device interface name associated with
+		==========	=============================================
+		ifname		network device interface name associated with
 				this function instance
-		qmult		- queue length multiplier for high and
+		qmult		queue length multiplier for high and
 				super speed
-		host_addr	- MAC address of host's end of this
+		host_addr	MAC address of host's end of this
 				Ethernet over USB link
-		dev_addr	- MAC address of device's end of this
+		dev_addr	MAC address of device's end of this
 				Ethernet over USB link
+		==========	=============================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-loopback b/Documentation/ABI/testing/configfs-usb-gadget-loopback
index 06beefbcf061..e6c6ba5ac7ff 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-loopback
+++ b/Documentation/ABI/testing/configfs-usb-gadget-loopback
@@ -4,5 +4,7 @@ KernelVersion:	3.13
 Description:
 		The attributes:
 
-		qlen		- depth of loopback queue
-		buflen		- buffer length
+		=======		=======================
+		qlen		depth of loopback queue
+		buflen		buffer length
+		=======		=======================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-mass-storage b/Documentation/ABI/testing/configfs-usb-gadget-mass-storage
index 9931fb0d63ba..c86b63a7bb43 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-mass-storage
+++ b/Documentation/ABI/testing/configfs-usb-gadget-mass-storage
@@ -4,12 +4,14 @@ KernelVersion:	3.13
 Description:
 		The attributes:
 
-		stall		- Set to permit function to halt bulk endpoints.
+		===========	==============================================
+		stall		Set to permit function to halt bulk endpoints.
 				Disabled on some USB devices known not to work
 				correctly. You should set it to true.
-		num_buffers	- Number of pipeline buffers. Valid numbers
+		num_buffers	Number of pipeline buffers. Valid numbers
 				are 2..4. Available only if
 				CONFIG_USB_GADGET_DEBUG_FILES is set.
+		===========	==============================================
 
 What:		/config/usb-gadget/gadget/functions/mass_storage.name/lun.name
 Date:		Oct 2013
@@ -17,15 +19,17 @@ KernelVersion:	3.13
 Description:
 		The attributes:
 
-		file		- The path to the backing file for the LUN.
+		===========	==============================================
+		file		The path to the backing file for the LUN.
 				Required if LUN is not marked as removable.
-		ro		- Flag specifying access to the LUN shall be
+		ro		Flag specifying access to the LUN shall be
 				read-only. This is implied if CD-ROM emulation
 				is enabled as well as when it was impossible
 				to open "filename" in R/W mode.
-		removable	- Flag specifying that LUN shall be indicated as
+		removable	Flag specifying that LUN shall be indicated as
 				being removable.
-		cdrom		- Flag specifying that LUN shall be reported as
+		cdrom		Flag specifying that LUN shall be reported as
 				being a CD-ROM.
-		nofua		- Flag specifying that FUA flag
+		nofua		Flag specifying that FUA flag
 				in SCSI WRITE(10,12)
+		===========	==============================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-midi b/Documentation/ABI/testing/configfs-usb-gadget-midi
index 6b341df7249c..07389cddd51a 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-midi
+++ b/Documentation/ABI/testing/configfs-usb-gadget-midi
@@ -4,9 +4,11 @@ KernelVersion:	3.19
 Description:
 		The attributes:
 
-		index		- index value for the USB MIDI adapter
-		id		- ID string for the USB MIDI adapter
-		buflen		- MIDI buffer length
-		qlen		- USB read request queue length
-		in_ports	- number of MIDI input ports
-		out_ports	- number of MIDI output ports
+		==========	====================================
+		index		index value for the USB MIDI adapter
+		id		ID string for the USB MIDI adapter
+		buflen		MIDI buffer length
+		qlen		USB read request queue length
+		in_ports	number of MIDI input ports
+		out_ports	number of MIDI output ports
+		==========	====================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-printer b/Documentation/ABI/testing/configfs-usb-gadget-printer
index 6b0714e3c605..7aa731bac2da 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-printer
+++ b/Documentation/ABI/testing/configfs-usb-gadget-printer
@@ -4,6 +4,8 @@ KernelVersion:	4.1
 Description:
 		The attributes:
 
-		pnp_string	- Data to be passed to the host in pnp string
-		q_len		- Number of requests per endpoint
+		==========      ===========================================
+		pnp_string	Data to be passed to the host in pnp string
+		q_len		Number of requests per endpoint
+		==========      ===========================================
 
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-sourcesink b/Documentation/ABI/testing/configfs-usb-gadget-sourcesink
index f56335af2d88..1f3d31b607b7 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-sourcesink
+++ b/Documentation/ABI/testing/configfs-usb-gadget-sourcesink
@@ -4,11 +4,13 @@ KernelVersion:	3.13
 Description:
 		The attributes:
 
-		pattern		- 0 (all zeros), 1 (mod63), 2 (none)
-		isoc_interval	- 1..16
-		isoc_maxpacket	- 0 - 1023 (fs), 0 - 1024 (hs/ss)
-		isoc_mult	- 0..2 (hs/ss only)
-		isoc_maxburst	- 0..15 (ss only)
-		buflen		- buffer length
-		bulk_qlen	- depth of queue for bulk
-		iso_qlen	- depth of queue for iso
+		==============    ==================================
+		pattern		  0 (all zeros), 1 (mod63), 2 (none)
+		isoc_interval	  1..16
+		isoc_maxpacket	  0 - 1023 (fs), 0 - 1024 (hs/ss)
+		isoc_mult	  0..2 (hs/ss only)
+		isoc_maxburst	  0..15 (ss only)
+		buflen		  buffer length
+		bulk_qlen	  depth of queue for bulk
+		iso_qlen	  depth of queue for iso
+		==============    ==================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-subset b/Documentation/ABI/testing/configfs-usb-gadget-subset
index 9373e2c51ea4..0061b864351f 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-subset
+++ b/Documentation/ABI/testing/configfs-usb-gadget-subset
@@ -4,11 +4,13 @@ KernelVersion:	3.11
 Description:
 		The attributes:
 
-		ifname		- network device interface name associated with
+		==========	=============================================
+		ifname		network device interface name associated with
 				this function instance
-		qmult		- queue length multiplier for high and
+		qmult		queue length multiplier for high and
 				super speed
-		host_addr	- MAC address of host's end of this
+		host_addr	MAC address of host's end of this
 				Ethernet over USB link
-		dev_addr	- MAC address of device's end of this
+		dev_addr	MAC address of device's end of this
 				Ethernet over USB link
+		==========	=============================================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uac2 b/Documentation/ABI/testing/configfs-usb-gadget-uac2
index 2bfdd4efa9bd..d4356c8b8cd6 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-uac2
+++ b/Documentation/ABI/testing/configfs-usb-gadget-uac2
@@ -4,9 +4,11 @@ KernelVersion:	3.18
 Description:
 		The attributes:
 
-		c_chmask - capture channel mask
-		c_srate - capture sampling rate
-		c_ssize - capture sample size (bytes)
-		p_chmask - playback channel mask
-		p_srate - playback sampling rate
-		p_ssize - playback sample size (bytes)
+		=========  ============================
+		c_chmask   capture channel mask
+		c_srate    capture sampling rate
+		c_ssize    capture sample size (bytes)
+		p_chmask   playback channel mask
+		p_srate    playback sampling rate
+		p_ssize    playback sample size (bytes)
+		=========  ============================
diff --git a/Documentation/ABI/testing/configfs-usb-gadget-uvc b/Documentation/ABI/testing/configfs-usb-gadget-uvc
index cee81b0347bb..ac5e11af79a8 100644
--- a/Documentation/ABI/testing/configfs-usb-gadget-uvc
+++ b/Documentation/ABI/testing/configfs-usb-gadget-uvc
@@ -55,7 +55,7 @@ Description:	Default output terminal descriptors
 
 		==============	=============================================
 		iTerminal	index of string descriptor
-		bSourceID 	id of the terminal to which this terminal
+		bSourceID	id of the terminal to which this terminal
 				is connected
 		bAssocTerminal	id of the input terminal to which this output
 				terminal is associated
diff --git a/Documentation/ABI/testing/debugfs-cec-error-inj b/Documentation/ABI/testing/debugfs-cec-error-inj
index 5afcd78fbdb7..8debcb08a3b5 100644
--- a/Documentation/ABI/testing/debugfs-cec-error-inj
+++ b/Documentation/ABI/testing/debugfs-cec-error-inj
@@ -23,7 +23,7 @@ error injections without having to know the details of the driver-specific
 commands.
 
 Note that the output of 'error-inj' shall be valid as input to 'error-inj'.
-So this must work:
+So this must work::
 
 	$ cat error-inj >einj.txt
 	$ cat einj.txt >error-inj
diff --git a/Documentation/ABI/testing/debugfs-driver-habanalabs b/Documentation/ABI/testing/debugfs-driver-habanalabs
index 2e9ae311e02d..c5d678d39144 100644
--- a/Documentation/ABI/testing/debugfs-driver-habanalabs
+++ b/Documentation/ABI/testing/debugfs-driver-habanalabs
@@ -20,9 +20,13 @@ Description:    Allow the root user to disable/enable in runtime the clock
                 The user can supply a bitmask value, each bit represents
                 a different engine to disable/enable its clock gating feature.
                 The bitmask is composed of 20 bits:
-                0  -  7 : DMA channels
-                8  - 11 : MME engines
-                12 - 19 : TPC engines
+
+		=======   ============
+                0  -  7   DMA channels
+                8  - 11   MME engines
+                12 - 19   TPC engines
+		=======   ============
+
                 The bit's location of a specific engine can be determined
                 using (1 << GAUDI_ENGINE_ID_*). GAUDI_ENGINE_ID_* values
                 are defined in uapi habanalabs.h file in enum gaudi_engine_id
@@ -59,6 +63,7 @@ Description:    Allows the root user to read or write directly through the
                 the generic Linux user-space PCI mapping) because the DDR bar
                 is very small compared to the DDR memory and only the driver can
                 move the bar before and after the transaction.
+
                 If the IOMMU is disabled, it also allows the root user to read
                 or write from the host a device VA of a host mapped memory
 
@@ -73,6 +78,7 @@ Description:    Allows the root user to read or write 64 bit data directly
                 the generic Linux user-space PCI mapping) because the DDR bar
                 is very small compared to the DDR memory and only the driver can
                 move the bar before and after the transaction.
+
                 If the IOMMU is disabled, it also allows the root user to read
                 or write from the host a device VA of a host mapped memory
 
diff --git a/Documentation/ABI/testing/debugfs-pfo-nx-crypto b/Documentation/ABI/testing/debugfs-pfo-nx-crypto
index 685d5a448423..f75a655c1531 100644
--- a/Documentation/ABI/testing/debugfs-pfo-nx-crypto
+++ b/Documentation/ABI/testing/debugfs-pfo-nx-crypto
@@ -4,42 +4,42 @@ KernelVersion:	3.4
 Contact:	Kent Yoder <key@linux.vnet.ibm.com>
 Description:
 
-  These debugfs interfaces are built by the nx-crypto driver, built in
+These debugfs interfaces are built by the nx-crypto driver, built in
 arch/powerpc/crypto/nx.
 
 Error Detection
 ===============
 
 errors:
-- A u32 providing a total count of errors since the driver was loaded. The
-only errors counted here are those returned from the hcall, H_COP_OP.
+  A u32 providing a total count of errors since the driver was loaded. The
+  only errors counted here are those returned from the hcall, H_COP_OP.
 
 last_error:
-- The most recent non-zero return code from the H_COP_OP hcall. -EBUSY is not
-recorded here (the hcall will retry until -EBUSY goes away).
+  The most recent non-zero return code from the H_COP_OP hcall. -EBUSY is not
+  recorded here (the hcall will retry until -EBUSY goes away).
 
 last_error_pid:
-- The process ID of the process who received the most recent error from the
-hcall.
+  The process ID of the process who received the most recent error from the
+  hcall.
 
 Device Use
 ==========
 
 aes_bytes:
-- The total number of bytes encrypted using AES in any of the driver's
-supported modes.
+  The total number of bytes encrypted using AES in any of the driver's
+  supported modes.
 
 aes_ops:
-- The total number of AES operations submitted to the hardware.
+  The total number of AES operations submitted to the hardware.
 
 sha256_bytes:
-- The total number of bytes hashed by the hardware using SHA-256.
+  The total number of bytes hashed by the hardware using SHA-256.
 
 sha256_ops:
-- The total number of SHA-256 operations submitted to the hardware.
+  The total number of SHA-256 operations submitted to the hardware.
 
 sha512_bytes:
-- The total number of bytes hashed by the hardware using SHA-512.
+  The total number of bytes hashed by the hardware using SHA-512.
 
 sha512_ops:
-- The total number of SHA-512 operations submitted to the hardware.
+  The total number of SHA-512 operations submitted to the hardware.
diff --git a/Documentation/ABI/testing/debugfs-pktcdvd b/Documentation/ABI/testing/debugfs-pktcdvd
index 787907d70462..f6f65a4faea0 100644
--- a/Documentation/ABI/testing/debugfs-pktcdvd
+++ b/Documentation/ABI/testing/debugfs-pktcdvd
@@ -10,7 +10,7 @@ these files in debugfs:
 /sys/kernel/debug/pktcdvd/pktcdvd[0-7]/
 
     ====            ====== ====================================
-    info            (0444) Lots of driver statistics and infos.
+    info            0444   Lots of driver statistics and infos.
     ====            ====== ====================================
 
 Example::
diff --git a/Documentation/ABI/testing/debugfs-turris-mox-rwtm b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
index c8f7dadd591c..ad08f535af3b 100644
--- a/Documentation/ABI/testing/debugfs-turris-mox-rwtm
+++ b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
@@ -2,10 +2,12 @@ What:		/sys/kernel/debug/turris-mox-rwtm/do_sign
 Date:		Jun 2020
 KernelVersion:	5.8
 Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(W)
-		    Message to sign with the ECDSA private key stored in
+Description:
+
+		=== ===========================================================
+		(W) Message to sign with the ECDSA private key stored in
 		    device's OTP. The message must be exactly 64 bytes (since
 		    this is intended for SHA-512 hashes).
-		(R)
-		    The resulting signature, 136 bytes. This contains the R and
+		(R) The resulting signature, 136 bytes. This contains the R and
 		    S values of the ECDSA signature, both in big-endian format.
+		=== ===========================================================
diff --git a/Documentation/ABI/testing/debugfs-wilco-ec b/Documentation/ABI/testing/debugfs-wilco-ec
index 9d8d9d2def5b..682e3c09ef4d 100644
--- a/Documentation/ABI/testing/debugfs-wilco-ec
+++ b/Documentation/ABI/testing/debugfs-wilco-ec
@@ -27,16 +27,17 @@ Description:
 		for writing, two for the type and at least a single byte of
 		data.
 
-		Example:
-		// Request EC info type 3 (EC firmware build date)
-		// Corresponds with sending type 0x00f0 with
-		// MBOX = [38, 00, 03, 00]
-		$ echo 00 f0 38 00 03 00 > /sys/kernel/debug/wilco_ec/raw
-		// View the result. The decoded ASCII result "12/21/18" is
-		// included after the raw hex.
-		// Corresponds with MBOX = [00, 00, 31, 32, 2f, 32, 31, 38, ...]
-		$ cat /sys/kernel/debug/wilco_ec/raw
-		00 00 31 32 2f 32 31 2f 31 38 00 38 00 01 00 2f 00  ..12/21/18.8...
+		Example::
+
+		    // Request EC info type 3 (EC firmware build date)
+		    // Corresponds with sending type 0x00f0 with
+		    // MBOX = [38, 00, 03, 00]
+		    $ echo 00 f0 38 00 03 00 > /sys/kernel/debug/wilco_ec/raw
+		    // View the result. The decoded ASCII result "12/21/18" is
+		    // included after the raw hex.
+		    // Corresponds with MBOX = [00, 00, 31, 32, 2f, 32, 31, 38, ...]
+		    $ cat /sys/kernel/debug/wilco_ec/raw
+		    00 00 31 32 2f 32 31 2f 31 38 00 38 00 01 00 2f 00  ..12/21/18.8...
 
 		Note that the first 16 bytes of the received MBOX[] will be
 		printed, even if some of the data is junk, and skipping bytes
diff --git a/Documentation/ABI/testing/dell-smbios-wmi b/Documentation/ABI/testing/dell-smbios-wmi
index fc919ce16008..5f3a0dc67050 100644
--- a/Documentation/ABI/testing/dell-smbios-wmi
+++ b/Documentation/ABI/testing/dell-smbios-wmi
@@ -10,29 +10,29 @@ Description:
 		<uapi/linux/wmi.h>
 
 		1) To perform an SMBIOS call from userspace, you'll need to
-		first determine the minimum size of the calling interface
-		buffer for your machine.
-		Platforms that contain larger buffers can return larger
-		objects from the system firmware.
-		Commonly this size is either 4k or 32k.
+		   first determine the minimum size of the calling interface
+		   buffer for your machine.
+		   Platforms that contain larger buffers can return larger
+		   objects from the system firmware.
+		   Commonly this size is either 4k or 32k.
 
-		To determine the size of the buffer read() a u64 dword from
-		the WMI character device /dev/wmi/dell-smbios.
+		   To determine the size of the buffer read() a u64 dword from
+		   the WMI character device /dev/wmi/dell-smbios.
 
 		2) After you've determined the minimum size of the calling
-		interface buffer, you can allocate a structure that represents
-		the structure documented above.
+		   interface buffer, you can allocate a structure that represents
+		   the structure documented above.
 
 		3) In the 'length' object store the size of the buffer you
-		determined above and allocated.
+		   determined above and allocated.
 
 		4) In this buffer object, prepare as necessary for the SMBIOS
-		call you're interested in.  Typically SMBIOS buffers have
-		"class", "select", and "input" defined to values that coincide
-		with the data you are interested in.
-		Documenting class/select/input values is outside of the scope
-		of this documentation. Check with the libsmbios project for
-		further documentation on these values.
+		   call you're interested in.  Typically SMBIOS buffers have
+		   "class", "select", and "input" defined to values that coincide
+		   with the data you are interested in.
+		   Documenting class/select/input values is outside of the scope
+		   of this documentation. Check with the libsmbios project for
+		   further documentation on these values.
 
 		6) Run the call by using ioctl() as described in the header.
 
diff --git a/Documentation/ABI/testing/gpio-cdev b/Documentation/ABI/testing/gpio-cdev
index 7b265fbb47e3..66bdcd188b6c 100644
--- a/Documentation/ABI/testing/gpio-cdev
+++ b/Documentation/ABI/testing/gpio-cdev
@@ -12,15 +12,16 @@ Description:
 		The following file operations are supported:
 
 		open(2)
-		Currently the only useful flags are O_RDWR.
+		  Currently the only useful flags are O_RDWR.
 
 		ioctl(2)
-		Initiate various actions.
-		See the inline documentation in [include/uapi]<linux/gpio.h>
-		for descriptions of all ioctls.
+		  Initiate various actions.
+
+		  See the inline documentation in [include/uapi]<linux/gpio.h>
+		  for descriptions of all ioctls.
 
 		close(2)
-		Stops and free up the I/O contexts that was associated
-		with the file descriptor.
+		  Stops and free up the I/O contexts that was associated
+		  with the file descriptor.
 
 Users:		TBD
diff --git a/Documentation/ABI/testing/procfs-diskstats b/Documentation/ABI/testing/procfs-diskstats
index df5a3a8c1edf..e58d641443d3 100644
--- a/Documentation/ABI/testing/procfs-diskstats
+++ b/Documentation/ABI/testing/procfs-diskstats
@@ -35,7 +35,9 @@ Description:
 
 		Kernel 5.5+ appends two more fields for flush requests:
 
-		19 - flush requests completed successfully
-		20 - time spent flushing
+		==  =====================================
+		19  flush requests completed successfully
+		20  time spent flushing
+		==  =====================================
 
 		For more details refer to Documentation/admin-guide/iostats.rst
diff --git a/Documentation/ABI/testing/procfs-smaps_rollup b/Documentation/ABI/testing/procfs-smaps_rollup
index 046978193368..a4e31c465194 100644
--- a/Documentation/ABI/testing/procfs-smaps_rollup
+++ b/Documentation/ABI/testing/procfs-smaps_rollup
@@ -14,28 +14,28 @@ Description:
 		For more details, see Documentation/filesystems/proc.rst
 		and the procfs man page.
 
-		Typical output looks like this:
+		Typical output looks like this::
 
-		00100000-ff709000 ---p 00000000 00:00 0		 [rollup]
-		Size:               1192 kB
-		KernelPageSize:        4 kB
-		MMUPageSize:           4 kB
-		Rss:		     884 kB
-		Pss:		     385 kB
-		Pss_Anon:	     301 kB
-		Pss_File:	      80 kB
-		Pss_Shmem:	       4 kB
-		Shared_Clean:	     696 kB
-		Shared_Dirty:	       0 kB
-		Private_Clean:	     120 kB
-		Private_Dirty:	      68 kB
-		Referenced:	     884 kB
-		Anonymous:	      68 kB
-		LazyFree:	       0 kB
-		AnonHugePages:	       0 kB
-		ShmemPmdMapped:	       0 kB
-		Shared_Hugetlb:	       0 kB
-		Private_Hugetlb:       0 kB
-		Swap:		       0 kB
-		SwapPss:	       0 kB
-		Locked:		     385 kB
+			00100000-ff709000 ---p 00000000 00:00 0		 [rollup]
+			Size:               1192 kB
+			KernelPageSize:        4 kB
+			MMUPageSize:           4 kB
+			Rss:		     884 kB
+			Pss:		     385 kB
+			Pss_Anon:	     301 kB
+			Pss_File:	      80 kB
+			Pss_Shmem:	       4 kB
+			Shared_Clean:	     696 kB
+			Shared_Dirty:	       0 kB
+			Private_Clean:	     120 kB
+			Private_Dirty:	      68 kB
+			Referenced:	     884 kB
+			Anonymous:	      68 kB
+			LazyFree:	       0 kB
+			AnonHugePages:	       0 kB
+			ShmemPmdMapped:	       0 kB
+			Shared_Hugetlb:	       0 kB
+			Private_Hugetlb:       0 kB
+			Swap:		       0 kB
+			SwapPss:	       0 kB
+			Locked:		     385 kB
diff --git a/Documentation/ABI/testing/pstore b/Documentation/ABI/testing/pstore
index d45209abdb1b..5b02540781a2 100644
--- a/Documentation/ABI/testing/pstore
+++ b/Documentation/ABI/testing/pstore
@@ -9,25 +9,25 @@ Description:	Generic interface to platform dependent persistent storage.
 		provide a generic interface to show records captured in
 		the dying moments.  In the case of a panic the last part
 		of the console log is captured, but other interesting
-		data can also be saved.
+		data can also be saved::
 
-		# mount -t pstore -o kmsg_bytes=8000 - /sys/fs/pstore
+		    # mount -t pstore -o kmsg_bytes=8000 - /sys/fs/pstore
 
-		$ ls -l /sys/fs/pstore/
-		total 0
-		-r--r--r-- 1 root root 7896 Nov 30 15:38 dmesg-erst-1
+		    $ ls -l /sys/fs/pstore/
+		    total 0
+		    -r--r--r-- 1 root root 7896 Nov 30 15:38 dmesg-erst-1
 
 		Different users of this interface will result in different
 		filename prefixes.  Currently two are defined:
 
-		"dmesg"	- saved console log
-		"mce"	- architecture dependent data from fatal h/w error
+		- "dmesg" - saved console log
+		- "mce"   - architecture dependent data from fatal h/w error
 
 		Once the information in a file has been read, removing
 		the file will signal to the underlying persistent storage
-		device that it can reclaim the space for later re-use.
+		device that it can reclaim the space for later re-use::
 
-		$ rm /sys/fs/pstore/dmesg-erst-1
+		    $ rm /sys/fs/pstore/dmesg-erst-1
 
 		The expectation is that all files in /sys/fs/pstore/
 		will be saved elsewhere and erased from persistent store
@@ -44,4 +44,3 @@ Description:	Generic interface to platform dependent persistent storage.
 		backends are available, the preferred backend may be
 		set by passing the pstore.backend= argument to the kernel at
 		boot time.
-
diff --git a/Documentation/ABI/testing/sysfs-block-rnbd b/Documentation/ABI/testing/sysfs-block-rnbd
index 8f070b47f361..14a6fe9422b3 100644
--- a/Documentation/ABI/testing/sysfs-block-rnbd
+++ b/Documentation/ABI/testing/sysfs-block-rnbd
@@ -9,9 +9,9 @@ Description:	To unmap a volume, "normal" or "force" has to be written to:
 		is using the device.  When "force" is used, the device is also unmapped
 		when device is in use.  All I/Os that are in progress will fail.
 
-		Example:
+		Example::
 
-		# echo "normal" > /sys/block/rnbd0/rnbd/unmap_device
+		  # echo "normal" > /sys/block/rnbd0/rnbd/unmap_device
 
 What:		/sys/block/rnbd<N>/rnbd/state
 Date:		Feb 2020
diff --git a/Documentation/ABI/testing/sysfs-bus-acpi b/Documentation/ABI/testing/sysfs-bus-acpi
index c78603497b97..58abacf59b2a 100644
--- a/Documentation/ABI/testing/sysfs-bus-acpi
+++ b/Documentation/ABI/testing/sysfs-bus-acpi
@@ -5,6 +5,7 @@ Description:
 		This attribute indicates the full path of ACPI namespace
 		object associated with the device object.  For example,
 		\_SB_.PCI0.
+
 		This file is not present for device objects representing
 		fixed ACPI hardware features (like power and sleep
 		buttons).
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10 b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10
index b5f526081711..3e92cbd3fd83 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10
@@ -4,7 +4,10 @@ KernelVersion:	3.19
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
 Description:	(RW) Add/remove a sink from a trace path.  There can be multiple
 		source for a single sink.
-		ex: echo 1 > /sys/bus/coresight/devices/20010000.etb/enable_sink
+
+		ex::
+
+		  echo 1 > /sys/bus/coresight/devices/20010000.etb/enable_sink
 
 What:		/sys/bus/coresight/devices/<memory_map>.etb/trigger_cntr
 Date:		November 2014
diff --git a/Documentation/ABI/testing/sysfs-bus-css b/Documentation/ABI/testing/sysfs-bus-css
index 966f8504bd7b..12a733fe357f 100644
--- a/Documentation/ABI/testing/sysfs-bus-css
+++ b/Documentation/ABI/testing/sysfs-bus-css
@@ -20,6 +20,7 @@ Contact:	Cornelia Huck <cornelia.huck@de.ibm.com>
 Description:	Contains the ids of the channel paths used by this
 		subchannel, as reported by the channel subsystem
 		during subchannel recognition.
+
 		Note: This is an I/O-subchannel specific attribute.
 Users:		s390-tools, HAL
 
@@ -31,6 +32,7 @@ Description:	Contains the PIM/PAM/POM values, as reported by the
 		channel subsystem when last queried by the common I/O
 		layer (this implies that this attribute is not necessarily
 		in sync with the values current in the channel subsystem).
+
 		Note: This is an I/O-subchannel specific attribute.
 Users:		s390-tools, HAL
 
@@ -53,6 +55,7 @@ Description:	This file allows the driver for a device to be specified. When
 		opt-out of driver binding using a driver_override name such as
 		"none".  Only a single driver may be specified in the override,
 		there is no support for parsing delimiters.
+
 		Note that unlike the mechanism of the same name for pci, this
 		file does not allow to override basic matching rules. I.e.,
 		the driver must still match the subchannel type of the device.
diff --git a/Documentation/ABI/testing/sysfs-bus-dfl b/Documentation/ABI/testing/sysfs-bus-dfl
index 23543be904f2..b0265ab17200 100644
--- a/Documentation/ABI/testing/sysfs-bus-dfl
+++ b/Documentation/ABI/testing/sysfs-bus-dfl
@@ -4,6 +4,7 @@ KernelVersion:	5.10
 Contact:	Xu Yilun <yilun.xu@intel.com>
 Description:	Read-only. It returns type of DFL FIU of the device. Now DFL
 		supports 2 FIU types, 0 for FME, 1 for PORT.
+
 		Format: 0x%x
 
 What:		/sys/bus/dfl/devices/dfl_dev.X/feature_id
@@ -12,4 +13,5 @@ KernelVersion:	5.10
 Contact:	Xu Yilun <yilun.xu@intel.com>
 Description:	Read-only. It returns feature identifier local to its DFL FIU
 		type.
+
 		Format: 0x%x
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7 b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7
index 2273627df190..de390a010af8 100644
--- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_24x7
@@ -7,7 +7,7 @@ Description:    Read-only. Attribute group to describe the magic bits
 
                 Each attribute under this group defines a bit range of the
                 perf_event_attr.config. All supported attributes are listed
-                below.
+                below::
 
 				chip = "config:16-31"
 				core  = "config:16-31"
@@ -16,9 +16,9 @@ Description:    Read-only. Attribute group to describe the magic bits
 				offset = "config:32-63"
 				vcpu = "config:16-31"
 
-               For example,
+                For example::
 
-		PM_PB_CYC =  "domain=1,offset=0x80,chip=?,lpar=0x0"
+		  PM_PB_CYC =  "domain=1,offset=0x80,chip=?,lpar=0x0"
 
 		In this event, '?' after chip specifies that
 		this value will be provided by user while running this event.
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci
index 6a023b42486c..12e2bf92783f 100644
--- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-hv_gpci
@@ -7,7 +7,7 @@ Description:    Read-only. Attribute group to describe the magic bits
 
                 Each attribute under this group defines a bit range of the
                 perf_event_attr.config. All supported attributes are listed
-                below.
+                below::
 
 				counter_info_version  = "config:16-23"
 				length  = "config:24-31"
@@ -20,9 +20,9 @@ Description:    Read-only. Attribute group to describe the magic bits
 				secondary_index = "config:0-15"
 				starting_index = "config:32-63"
 
-               For example,
+                For example::
 
-		processor_core_utilization_instructions_completed = "request=0x94,
+		  processor_core_utilization_instructions_completed = "request=0x94,
 					phys_processor_idx=?,counter_info_version=0x8,
 					length=8,offset=0x18"
 
@@ -36,6 +36,7 @@ Description:
 		'0' if the hypervisor is configured to forbid access to event
 		counters being accumulated by other guests and to physical
 		domain event counters.
+
 		'1' if that access is allowed.
 
 What:		/sys/bus/event_source/devices/hv_gpci/interface/ga
diff --git a/Documentation/ABI/testing/sysfs-bus-fcoe b/Documentation/ABI/testing/sysfs-bus-fcoe
index 657df13b100d..8fe787cc4ab7 100644
--- a/Documentation/ABI/testing/sysfs-bus-fcoe
+++ b/Documentation/ABI/testing/sysfs-bus-fcoe
@@ -3,16 +3,19 @@ Date:		August 2012
 KernelVersion:	TBD
 Contact:	Robert Love <robert.w.love@intel.com>, devel@open-fcoe.org
 Description:	The FCoE bus. Attributes in this directory are control interfaces.
+
 Attributes:
 
-	ctlr_create: 'FCoE Controller' instance creation interface. Writing an
+	ctlr_create:
+		     'FCoE Controller' instance creation interface. Writing an
 		     <ifname> to this file will allocate and populate sysfs with a
 		     fcoe_ctlr_device (ctlr_X). The user can then configure any
 		     per-port settings and finally write to the fcoe_ctlr_device's
 		     'start' attribute to begin the kernel's discovery and login
 		     process.
 
-	ctlr_destroy: 'FCoE Controller' instance removal interface. Writing a
+	ctlr_destroy:
+		       'FCoE Controller' instance removal interface. Writing a
 		       fcoe_ctlr_device's sysfs name to this file will log the
 		       fcoe_ctlr_device out of the fabric or otherwise connected
 		       FCoE devices. It will also free all kernel memory allocated
@@ -32,11 +35,13 @@ Description:	'FCoE Controller' instances on the fcoe bus.
 
 Attributes:
 
-	fcf_dev_loss_tmo: Device loss timeout period (see below). Changing
+	fcf_dev_loss_tmo:
+			  Device loss timeout period (see below). Changing
 			  this value will change the dev_loss_tmo for all
 			  FCFs discovered by this controller.
 
-	mode:		  Display or change the FCoE Controller's mode. Possible
+	mode:
+			  Display or change the FCoE Controller's mode. Possible
 			  modes are 'Fabric' and 'VN2VN'. If a FCoE Controller
 			  is started in 'Fabric' mode then FIP FCF discovery is
 			  initiated and ultimately a fabric login is attempted.
@@ -44,23 +49,30 @@ Attributes:
 			  FIP VN2VN discovery and login is performed. A FCoE
 			  Controller only supports one mode at a time.
 
-	enabled:	  Whether an FCoE controller is enabled or disabled.
+	enabled:
+			  Whether an FCoE controller is enabled or disabled.
 			  0 if disabled, 1 if enabled. Writing either 0 or 1
 			  to this file will enable or disable the FCoE controller.
 
-	lesb/link_fail:   Link Error Status Block (LESB) link failure count.
+	lesb/link_fail:
+			  Link Error Status Block (LESB) link failure count.
 
-	lesb/vlink_fail:  Link Error Status Block (LESB) virtual link
+	lesb/vlink_fail:
+		          Link Error Status Block (LESB) virtual link
 			  failure count.
 
-	lesb/miss_fka:    Link Error Status Block (LESB) missed FCoE
+	lesb/miss_fka:
+			  Link Error Status Block (LESB) missed FCoE
 			  Initialization Protocol (FIP) Keep-Alives (FKA).
 
-	lesb/symb_err:    Link Error Status Block (LESB) symbolic error count.
+	lesb/symb_err:
+			  Link Error Status Block (LESB) symbolic error count.
 
-	lesb/err_block:   Link Error Status Block (LESB) block error count.
+	lesb/err_block:
+			  Link Error Status Block (LESB) block error count.
 
-	lesb/fcs_error:   Link Error Status Block (LESB) Fibre Channel
+	lesb/fcs_error:
+			  Link Error Status Block (LESB) Fibre Channel
 			  Services error count.
 
 Notes: ctlr_X (global increment starting at 0)
@@ -75,31 +87,41 @@ Description:	'FCoE FCF' instances on the fcoe bus. A FCF is a Fibre Channel
 		Fibre Channel frames into a FC fabric. It can also take
 		outbound FC frames and pack them in Ethernet packets to
 		be sent to their destination on the Ethernet segment.
+
 Attributes:
 
-	fabric_name: Identifies the fabric that the FCF services.
+	fabric_name:
+		     Identifies the fabric that the FCF services.
 
-	switch_name: Identifies the FCF.
+	switch_name:
+		     Identifies the FCF.
 
-	priority:    The switch's priority amongst other FCFs on the same
+	priority:
+		     The switch's priority amongst other FCFs on the same
 		     fabric.
 
-	selected:    1 indicates that the switch has been selected for use;
+	selected:
+		     1 indicates that the switch has been selected for use;
 		     0 indicates that the switch will not be used.
 
-	fc_map:      The Fibre Channel MAP
+	fc_map:
+		     The Fibre Channel MAP
 
-	vfid:	     The Virtual Fabric ID
+	vfid:
+		     The Virtual Fabric ID
 
-	mac:         The FCF's MAC address
+	mac:
+		     The FCF's MAC address
 
-	fka_period:  The FIP Keep-Alive period
+	fka_period:
+		     The FIP Keep-Alive period
 
 	fabric_state: The internal kernel state
-		      "Unknown" - Initialization value
-		      "Disconnected" - No link to the FCF/fabric
-		      "Connected" - Host is connected to the FCF
-		      "Deleted" - FCF is being removed from the system
+
+		      - "Unknown" - Initialization value
+		      - "Disconnected" - No link to the FCF/fabric
+		      - "Connected" - Host is connected to the FCF
+		      - "Deleted" - FCF is being removed from the system
 
 	dev_loss_tmo: The device loss timeout period for this FCF.
 
diff --git a/Documentation/ABI/testing/sysfs-bus-fsl-mc b/Documentation/ABI/testing/sysfs-bus-fsl-mc
index 80256b8b4f26..bf3c6af6ad89 100644
--- a/Documentation/ABI/testing/sysfs-bus-fsl-mc
+++ b/Documentation/ABI/testing/sysfs-bus-fsl-mc
@@ -6,8 +6,10 @@ Description:
 		the driver to attempt to bind to the device found at
 		this location. The format for the location is Object.Id
 		and is the same as found in /sys/bus/fsl-mc/devices/.
-                For example:
-		# echo dpni.2 > /sys/bus/fsl-mc/drivers/fsl_dpaa2_eth/bind
+
+                For example::
+
+		  # echo dpni.2 > /sys/bus/fsl-mc/drivers/fsl_dpaa2_eth/bind
 
 What:		/sys/bus/fsl-mc/drivers/.../unbind
 Date:		December 2016
@@ -17,5 +19,7 @@ Description:
 		driver to attempt to unbind from the device found at
 		this location. The format for the location is Object.Id
 		and is the same as found in /sys/bus/fsl-mc/devices/.
-                For example:
-		# echo dpni.2 > /sys/bus/fsl-mc/drivers/fsl_dpaa2_eth/unbind
+
+                For example::
+
+		  # echo dpni.2 > /sys/bus/fsl-mc/drivers/fsl_dpaa2_eth/unbind
diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480 b/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480
index 9de269bb0ae5..42dfc9399d2d 100644
--- a/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480
+++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-fsa9480
@@ -3,19 +3,25 @@ Date:		February 2011
 Contact:	Minkyu Kang <mk7.kang@samsung.com>
 Description:
 		show what device is attached
-		NONE - no device
-		USB - USB device is attached
-		UART - UART is attached
-		CHARGER - Charger is attaced
-		JIG - JIG is attached
+
+		=======  ======================
+		NONE     no device
+		USB      USB device is attached
+		UART     UART is attached
+		CHARGER  Charger is attaced
+		JIG      JIG is attached
+		=======  ======================
 
 What:		/sys/bus/i2c/devices/.../switch
 Date:		February 2011
 Contact:	Minkyu Kang <mk7.kang@samsung.com>
 Description:
 		show or set the state of manual switch
-		VAUDIO - switch to VAUDIO path
-		UART - switch to UART path
-		AUDIO - switch to AUDIO path
-		DHOST - switch to DHOST path
-		AUTO - switch automatically by device
+
+		=======  ==============================
+		VAUDIO   switch to VAUDIO path
+		UART     switch to UART path
+		AUDIO    switch to AUDIO path
+		DHOST    switch to DHOST path
+		AUTO     switch automatically by device
+		=======  ==============================
diff --git a/Documentation/ABI/testing/sysfs-bus-i3c b/Documentation/ABI/testing/sysfs-bus-i3c
index 2f332ec36f82..1f4a2662335b 100644
--- a/Documentation/ABI/testing/sysfs-bus-i3c
+++ b/Documentation/ABI/testing/sysfs-bus-i3c
@@ -84,6 +84,7 @@ Description:
 		by space. Modes can be "hdr-ddr", "hdr-tsp" and "hdr-tsl".
 		See the I3C specification for more details about these HDR
 		modes.
+
 		This entry describes the HDRCAP of the master controller
 		driving the bus.
 
@@ -135,6 +136,7 @@ Description:
 		Expose the HDR (High Data Rate) capabilities of a device.
 		Returns a list of supported HDR mode, each element is separated
 		by space. Modes can be "hdr-ddr", "hdr-tsp" and "hdr-tsl".
+
 		See the I3C specification for more details about these HDR
 		modes.
 
diff --git a/Documentation/ABI/testing/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio
index e3df71987eff..df42bed09f25 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio
+++ b/Documentation/ABI/testing/sysfs-bus-iio
@@ -15,6 +15,7 @@ Description:
 		based on hardware generated events (e.g. data ready) or
 		provided by a separate driver for other hardware (e.g.
 		periodic timer, GPIO or high resolution timer).
+
 		Contains trigger type specific elements. These do not
 		generalize well and hence are not documented in this file.
 		X is the IIO index of the trigger.
@@ -666,6 +667,7 @@ Description:
 		<type>[Y][_name]_<raw|input>_thresh_falling_value may take
 		different values, but the device can only enable both thresholds
 		or neither.
+
 		Note the driver will assume the last p events requested are
 		to be enabled where p is how many it supports (which may vary
 		depending on the exact set requested. So if you want to be
@@ -720,6 +722,7 @@ Description:
 		<type>[Y][_name]_<raw|input>_roc_falling_value may take
 		different values, but the device can only enable both rate of
 		change thresholds or neither.
+
 		Note the driver will assume the last p events requested are
 		to be enabled where p is however many it supports (which may
 		vary depending on the exact set requested. So if you want to be
@@ -775,9 +778,11 @@ Description:
 		Specifies the value of threshold that the device is comparing
 		against for the events enabled by
 		<type>Y[_name]_thresh[_rising|falling]_en.
+
 		If separate attributes exist for the two directions, but
 		direction is not specified for this attribute, then a single
 		threshold value applies to both directions.
+
 		The raw or input element of the name indicates whether the
 		value is in raw device units or in processed units (as _raw
 		and _input do on sysfs direct channel read attributes).
@@ -860,6 +865,7 @@ Description:
 		If separate attributes exist for the two directions, but
 		direction is not specified for this attribute, then a single
 		hysteresis value applies to both directions.
+
 		For falling events the hysteresis is added to the _value attribute for
 		this event to get the upper threshold for when the event goes back to
 		normal, for rising events the hysteresis is subtracted from the _value
@@ -906,6 +912,7 @@ Description:
 		Specifies the value of rate of change threshold that the
 		device is comparing against for the events enabled by
 		<type>[Y][_name]_roc[_rising|falling]_en.
+
 		If separate attributes exist for the two directions,
 		but direction is not specified for this attribute,
 		then a single threshold value applies to both directions.
@@ -1305,6 +1312,7 @@ Description:
 		Proximity measurement indicating that some
 		object is near the sensor, usually by observing
 		reflectivity of infrared or ultrasound emitted.
+
 		Often these sensors are unit less and as such conversion
 		to SI units is not possible. Higher proximity measurements
 		indicate closer objects, and vice versa. Units after
@@ -1450,9 +1458,12 @@ Contact:	linux-iio@vger.kernel.org
 Description:
 		A single positive integer specifying the maximum number of scan
 		elements to wait for.
+
 		Poll will block until the watermark is reached.
+
 		Blocking read will wait until the minimum between the requested
 		read amount or the low water mark is available.
+
 		Non-blocking read will retrieve the available samples from the
 		buffer even if there are less samples then watermark level. This
 		allows the application to block on poll with a timeout and read
@@ -1481,11 +1492,13 @@ Description:
 		device settings allows it (e.g. if a trigger is set that samples
 		data differently that the hardware fifo does then hardware fifo
 		will not enabled).
+
 		If the hardware fifo is enabled and the level of the hardware
 		fifo reaches the hardware fifo watermark level the device will
 		flush its hardware fifo to the device buffer. Doing a non
 		blocking read on the device when no samples are present in the
 		device buffer will also force a flush.
+
 		When the hardware fifo is enabled there is no need to use a
 		trigger to use buffer mode since the watermark settings
 		guarantees that the hardware fifo is flushed to the device
@@ -1523,6 +1536,7 @@ Description:
 		A single positive integer specifying the minimum watermark level
 		for the hardware fifo of this device. If the device does not
 		have a hardware fifo this entry is not present.
+
 		If the user sets buffer/watermark to a value less than this one,
 		then the hardware watermark will remain unset.
 
@@ -1533,6 +1547,7 @@ Description:
 		A single positive integer specifying the maximum watermark level
 		for the hardware fifo of this device. If the device does not
 		have a hardware fifo this entry is not present.
+
 		If the user sets buffer/watermark to a value greater than this
 		one, then the hardware watermark will be capped at this value.
 
@@ -1544,6 +1559,7 @@ Description:
 		levels for the hardware fifo. This entry is optional and if it
 		is not present it means that all the values between
 		hwfifo_watermark_min and hwfifo_watermark_max are supported.
+
 		If the user sets buffer/watermark to a value greater than
 		hwfifo_watermak_min but not equal to any of the values in this
 		list, the driver will chose an appropriate value for the
@@ -1605,7 +1621,8 @@ KernelVersion:	4.1.0
 Contact:	linux-iio@vger.kernel.org
 Description:
 		'1' (enable) or '0' (disable) specifying the enable
-		of heater function. Same reading values apply
+		of heater function. Same reading values apply.
+
 		This ABI is especially applicable for humidity sensors
 		to heatup the device and get rid of any condensation
 		in some humidity environment
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435 b/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435
index f30b4c424fb6..4b01150af397 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-hi8435
@@ -19,9 +19,11 @@ Description:
 		is separately set for "GND-Open" and "Supply-Open" modes.
 		Channels 0..31 have common low threshold values, but could have different
 		sensing_modes.
+
 		The low voltage threshold range is between 2..21V.
 		Hysteresis between low and high thresholds can not be lower then 2 and
 		can not be odd.
+
 		If falling threshold results hysteresis to odd value then rising
 		threshold is automatically subtracted by one.
 
@@ -34,10 +36,13 @@ Description:
 		this value then the threshold rising event is pushed.
 		Depending on in_voltageY_sensing_mode the high voltage threshold
 		is separately set for "GND-Open" and "Supply-Open" modes.
+
 		Channels 0..31 have common high threshold values, but could have different
 		sensing_modes.
+
 		The high voltage threshold range is between 3..22V.
 		Hysteresis between low and high thresholds can not be lower then 2 and
 		can not be odd.
+
 		If rising threshold results hysteresis to odd value then falling
 		threshold is automatically appended by one.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-adc-stm32 b/Documentation/ABI/testing/sysfs-bus-iio-adc-stm32
index efe4c85e3c8b..1975c7a1af34 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-adc-stm32
+++ b/Documentation/ABI/testing/sysfs-bus-iio-adc-stm32
@@ -5,10 +5,13 @@ Description:
 		The STM32 ADC can be configured to use external trigger sources
 		(e.g. timers, pwm or exti gpio). Then, it can be tuned to start
 		conversions on external trigger by either:
+
 		- "rising-edge"
 		- "falling-edge"
 		- "both-edges".
+
 		Reading returns current trigger polarity.
+
 		Writing value before enabling conversions sets trigger polarity.
 
 What:		/sys/bus/iio/devices/triggerX/trigger_polarity_available
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
index a133fd8d081a..40df5c9fef99 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
+++ b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
@@ -15,8 +15,11 @@ Description:
 		first object echoed in meters. Default value is 6.020.
 		This setting limits the time the driver is waiting for a
 		echo.
+
 		Showing the range of available values is represented as the
 		minimum value, the step and the maximum value, all enclosed
 		in square brackets.
-		Example:
-		[0.043 0.043 11.008]
+
+		Example::
+
+			[0.043 0.043 11.008]
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523
index a91aeabe7b24..d065cda7dd96 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523
+++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523
@@ -8,7 +8,9 @@ KernelVersion:	3.4.0
 Contact:	linux-iio@vger.kernel.org
 Description:
 		Reading returns either '1' or '0'.
+
 		'1' means that the clock in question is present.
+
 		'0' means that the clock is missing.
 
 What:		/sys/bus/iio/devices/iio:deviceX/pllY_locked
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
index 302de64cb424..544548ee794c 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
+++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
@@ -27,12 +27,12 @@ What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_name
 KernelVersion:
 Contact:	linux-iio@vger.kernel.org
 Description:
-		Reading returns the datasheet name for channel Y:
+		Reading returns the datasheet name for channel Y::
 
-		out_altvoltage0_name: RF8x
-		out_altvoltage1_name: RFAUX8x
-		out_altvoltage2_name: RF16x
-		out_altvoltage3_name: RF32x
+		  out_altvoltage0_name: RF8x
+		  out_altvoltage1_name: RFAUX8x
+		  out_altvoltage2_name: RF16x
+		  out_altvoltage3_name: RF32x
 
 What:		/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown
 KernelVersion:
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x b/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x
index 6adba9058b22..66b621f10223 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x
+++ b/Documentation/ABI/testing/sysfs-bus-iio-health-afe440x
@@ -6,10 +6,14 @@ Description:
 		Get measured values from the ADC for these stages. Y is the
 		specific stage number corresponding to datasheet stage names
 		as follows:
-		1 -> LED2
-		2 -> ALED2/LED3
-		3 -> LED1
-		4 -> ALED1/LED4
+
+		== ==========
+		1  LED2
+		2  ALED2/LED3
+		3  LED1
+		4  ALED1/LED4
+		== ==========
+
 		Note that channels 5 and 6 represent LED2-ALED2 and LED1-ALED1
 		respectively which simply helper channels containing the
 		calculated difference in the value of stage 1 - 2 and 3 - 4.
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-light-isl29018 b/Documentation/ABI/testing/sysfs-bus-iio-light-isl29018
index f0ce0a0476ea..220206a20d98 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-light-isl29018
+++ b/Documentation/ABI/testing/sysfs-bus-iio-light-isl29018
@@ -15,5 +15,7 @@ Description:
 		Scheme 0 has wider dynamic range, Scheme 1 proximity detection
 		is less affected by the ambient IR noise variation.
 
-		0 Sensing IR from LED and ambient
-		1 Sensing IR from LED with ambient IR rejection
+		== =============================================
+		0  Sensing IR from LED and ambient
+		1  Sensing IR from LED with ambient IR rejection
+		== =============================================
diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth
index 22d0843849a8..b7b2278fe042 100644
--- a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth
+++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-gth
@@ -10,10 +10,13 @@ Date:		June 2015
 KernelVersion:	4.3
 Contact:	Alexander Shishkin <alexander.shishkin@linux.intel.com>
 Description:	(RO) Output port type:
-		  0: not present,
-		  1: MSU (Memory Storage Unit)
-		  2: CTP (Common Trace Port)
-		  4: PTI (MIPI PTI).
+
+		 ==  =========================
+		  0  not present,
+		  1  MSU (Memory Storage Unit)
+		  2  CTP (Common Trace Port)
+		  4  PTI (MIPI PTI).
+		 ==  =========================
 
 What:		/sys/bus/intel_th/devices/<intel_th_id>-gth/outputs/[0-7]_drop
 Date:		June 2015
diff --git a/Documentation/ABI/testing/sysfs-bus-papr-pmem b/Documentation/ABI/testing/sysfs-bus-papr-pmem
index c1a67275c43f..8316c33862a0 100644
--- a/Documentation/ABI/testing/sysfs-bus-papr-pmem
+++ b/Documentation/ABI/testing/sysfs-bus-papr-pmem
@@ -11,19 +11,26 @@ Description:
 		at 'Documentation/powerpc/papr_hcalls.rst' . Below are
 		the flags reported in this sysfs file:
 
-		* "not_armed"	: Indicates that NVDIMM contents will not
+		* "not_armed"
+				  Indicates that NVDIMM contents will not
 				  survive a power cycle.
-		* "flush_fail"	: Indicates that NVDIMM contents
+		* "flush_fail"
+				  Indicates that NVDIMM contents
 				  couldn't be flushed during last
 				  shut-down event.
-		* "restore_fail": Indicates that NVDIMM contents
+		* "restore_fail"
+				  Indicates that NVDIMM contents
 				  couldn't be restored during NVDIMM
 				  initialization.
-		* "encrypted"	: NVDIMM contents are encrypted.
-		* "smart_notify": There is health event for the NVDIMM.
-		* "scrubbed"	: Indicating that contents of the
+		* "encrypted"
+				  NVDIMM contents are encrypted.
+		* "smart_notify"
+				  There is health event for the NVDIMM.
+		* "scrubbed"
+				  Indicating that contents of the
 				  NVDIMM have been scrubbed.
-		* "locked"	: Indicating that NVDIMM contents cant
+		* "locked"
+				  Indicating that NVDIMM contents cant
 				  be modified until next power cycle.
 
 What:		/sys/bus/nd/devices/nmemX/papr/perf_stats
@@ -51,4 +58,4 @@ Description:
 		* "MedWDur " : Media Write Duration
 		* "CchRHCnt" : Cache Read Hit Count
 		* "CchWHCnt" : Cache Write Hit Count
-		* "FastWCnt" : Fast Write Count
\ No newline at end of file
+		* "FastWCnt" : Fast Write Count
diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci
index 450296cc7948..77ad9ec3c801 100644
--- a/Documentation/ABI/testing/sysfs-bus-pci
+++ b/Documentation/ABI/testing/sysfs-bus-pci
@@ -7,8 +7,10 @@ Description:
 		this location.	This is useful for overriding default
 		bindings.  The format for the location is: DDDD:BB:DD.F.
 		That is Domain:Bus:Device.Function and is the same as
-		found in /sys/bus/pci/devices/.  For example:
-		# echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/bind
+		found in /sys/bus/pci/devices/.  For example::
+
+		  # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/bind
+
 		(Note: kernels before 2.6.28 may require echo -n).
 
 What:		/sys/bus/pci/drivers/.../unbind
@@ -20,8 +22,10 @@ Description:
 		this location.	This may be useful when overriding default
 		bindings.  The format for the location is: DDDD:BB:DD.F.
 		That is Domain:Bus:Device.Function and is the same as
-		found in /sys/bus/pci/devices/. For example:
-		# echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/unbind
+		found in /sys/bus/pci/devices/. For example::
+
+		  # echo 0000:00:19.0 > /sys/bus/pci/drivers/foo/unbind
+
 		(Note: kernels before 2.6.28 may require echo -n).
 
 What:		/sys/bus/pci/drivers/.../new_id
@@ -38,8 +42,9 @@ Description:
 		Class, Class Mask, and Private Driver Data.  The Vendor ID
 		and Device ID fields are required, the rest are optional.
 		Upon successfully adding an ID, the driver will probe
-		for the device and attempt to bind to it.  For example:
-		# echo "8086 10f5" > /sys/bus/pci/drivers/foo/new_id
+		for the device and attempt to bind to it.  For example::
+
+		  # echo "8086 10f5" > /sys/bus/pci/drivers/foo/new_id
 
 What:		/sys/bus/pci/drivers/.../remove_id
 Date:		February 2009
@@ -54,8 +59,9 @@ Description:
 		required, the rest are optional.  After successfully
 		removing an ID, the driver will no longer support the
 		device.  This is useful to ensure auto probing won't
-		match the driver to the device.  For example:
-		# echo "8086 10f5" > /sys/bus/pci/drivers/foo/remove_id
+		match the driver to the device.  For example::
+
+		  # echo "8086 10f5" > /sys/bus/pci/drivers/foo/remove_id
 
 What:		/sys/bus/pci/rescan
 Date:		January 2009
diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-catpt b/Documentation/ABI/testing/sysfs-bus-pci-devices-catpt
index 8a200f4eefbd..f85db86d63e8 100644
--- a/Documentation/ABI/testing/sysfs-bus-pci-devices-catpt
+++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-catpt
@@ -4,6 +4,7 @@ Contact:	Cezary Rojewski <cezary.rojewski@intel.com>
 Description:
 		Version of AudioDSP firmware ASoC catpt driver is
 		communicating with.
+
 		Format: %d.%d.%d.%d, type:major:minor:build.
 
 What:		/sys/devices/pci0000:00/<dev>/fw_info
diff --git a/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd b/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd
index 60c60fa624b2..c90d97a80855 100644
--- a/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd
+++ b/Documentation/ABI/testing/sysfs-bus-pci-drivers-ehci_hcd
@@ -21,11 +21,11 @@ Description:
 		number returns the port to normal operation.
 
 		For example: To force the high-speed device attached to
-		port 4 on bus 2 to run at full speed:
+		port 4 on bus 2 to run at full speed::
 
 			echo 4 >/sys/bus/usb/devices/usb2/../companion
 
-		To return the port to high-speed operation:
+		To return the port to high-speed operation::
 
 			echo -4 >/sys/bus/usb/devices/usb2/../companion
 
diff --git a/Documentation/ABI/testing/sysfs-bus-rbd b/Documentation/ABI/testing/sysfs-bus-rbd
index cc30bee8b5f4..417a2fe21be1 100644
--- a/Documentation/ABI/testing/sysfs-bus-rbd
+++ b/Documentation/ABI/testing/sysfs-bus-rbd
@@ -7,6 +7,8 @@ Description:
 
 		Usage: <mon ip addr> <options> <pool name> <rbd image name> [<snap name>]
 
+		Example::
+
 		 $ echo "192.168.0.1 name=admin rbd foo" > /sys/bus/rbd/add
 
 		The snapshot name can be "-" or omitted to map the image
@@ -23,6 +25,8 @@ Description:
 
 		Usage: <dev-id> [force]
 
+		Example::
+
 		 $ echo 2 > /sys/bus/rbd/remove
 
 		Optional "force" argument which when passed will wait for
@@ -80,26 +84,29 @@ Date:		Oct, 2010
 KernelVersion:	v2.6.37
 Contact:	Sage Weil <sage@newdream.net>
 Description:
-		size:		(RO) The size (in bytes) of the mapped block
+
+		==============	================================================
+		size		(RO) The size (in bytes) of the mapped block
 				device.
 
-		major:		(RO) The block device major number.
+		major		(RO) The block device major number.
 
-		client_id:	(RO) The ceph unique client id that was assigned
+		client_id	(RO) The ceph unique client id that was assigned
 				for this specific session.
 
-		pool:		(RO) The name of the storage pool where this rbd
+		pool		(RO) The name of the storage pool where this rbd
 				image resides. An rbd image name is unique
 				within its pool.
 
-		name:		(RO) The name of the rbd image.
+		name		(RO) The name of the rbd image.
 
-		refresh:	(WO) Writing to this file will reread the image
+		refresh		(WO) Writing to this file will reread the image
 				header data and set all relevant data structures
 				accordingly.
 
-		current_snap:	(RO) The current snapshot for which the device
+		current_snap	(RO) The current snapshot for which the device
 				is mapped.
+		==============	================================================
 
 
 What:		/sys/bus/rbd/devices/<dev-id>/pool_id
@@ -117,11 +124,13 @@ Date:		Oct, 2012
 KernelVersion:	v3.7
 Contact:	Sage Weil <sage@newdream.net>
 Description:
-		image_id:	(RO) The unique id for the rbd image. (For rbd
+		=========	===============================================
+		image_id	(RO) The unique id for the rbd image. (For rbd
 				image format 1 this is empty.)
 
-		features:	(RO) A hexadecimal encoding of the feature bits
+		features	(RO) A hexadecimal encoding of the feature bits
 				for this image.
+		=========	===============================================
 
 
 What:		/sys/bus/rbd/devices/<dev-id>/parent
@@ -149,14 +158,16 @@ Date:		Aug, 2016
 KernelVersion:	v4.9
 Contact:	Sage Weil <sage@newdream.net>
 Description:
-		snap_id:	(RO) The current snapshot's id.
+		============	================================================
+		snap_id		(RO) The current snapshot's id.
 
-		config_info:	(RO) The string written into
+		config_info	(RO) The string written into
 				/sys/bus/rbd/add{,_single_major}.
 
-		cluster_fsid:	(RO) The ceph cluster UUID.
+		cluster_fsid	(RO) The ceph cluster UUID.
 
-		client_addr:	(RO) The ceph unique client
+		client_addr	(RO) The ceph unique client
 				entity_addr_t (address + nonce). The format is
 				<address>:<port>/<nonce>: '1.2.3.4:1234/5678' or
 				'[1:2:3:4:5:6:7:8]:1234/5678'.
+		============	================================================
diff --git a/Documentation/ABI/testing/sysfs-bus-siox b/Documentation/ABI/testing/sysfs-bus-siox
index c2a403f20b90..50e80238f30d 100644
--- a/Documentation/ABI/testing/sysfs-bus-siox
+++ b/Documentation/ABI/testing/sysfs-bus-siox
@@ -8,6 +8,7 @@ Description:
 		When the file contains a "1" the bus is operated and periodically
 		does a push-pull cycle to write and read data from the
 		connected devices.
+
 		When writing a "0" or "1" the bus moves to the described state.
 
 What:		/sys/bus/siox/devices/siox-X/device_add
@@ -21,8 +22,10 @@ Description:
 		to add a new device dynamically. <type> is the name that is used to match
 		to a driver (similar to the platform bus). <inbytes> and <outbytes> define
 		the length of the input and output shift register in bytes respectively.
+
 		<statustype> defines the 4 bit device type that is check to identify connection
 		problems.
+
 		The new device is added to the end of the existing chain.
 
 What:		/sys/bus/siox/devices/siox-X/device_remove
diff --git a/Documentation/ABI/testing/sysfs-bus-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt
index 171127294674..0b4ab9e4b8f4 100644
--- a/Documentation/ABI/testing/sysfs-bus-thunderbolt
+++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt
@@ -193,10 +193,11 @@ Description:	When new NVM image is written to the non-active NVM
 		verification fails an error code is returned instead.
 
 		This file will accept writing values "1" or "2"
+
 		- Writing "1" will flush the image to the storage
-		area and authenticate the image in one action.
+		  area and authenticate the image in one action.
 		- Writing "2" will run some basic validation on the image
-		and flush it to the storage area.
+		  and flush it to the storage area.
 
 		When read holds status of the last authentication
 		operation if an error occurred during the process. This
@@ -213,9 +214,11 @@ Description:	This contains name of the property directory the XDomain
 		question. Following directories are already reserved by
 		the Apple XDomain specification:
 
-		network:  IP/ethernet over Thunderbolt
-		targetdm: Target disk mode protocol over Thunderbolt
-		extdisp:  External display mode protocol over Thunderbolt
+		========  ===============================================
+		network   IP/ethernet over Thunderbolt
+		targetdm  Target disk mode protocol over Thunderbolt
+		extdisp   External display mode protocol over Thunderbolt
+		========  ===============================================
 
 What:		/sys/bus/thunderbolt/devices/<xdomain>.<service>/modalias
 Date:		Jan 2018
@@ -293,7 +296,8 @@ Description:	For supported devices, automatically authenticate the new Thunderbo
 		image when the device is disconnected from the host system.
 
 		This file will accept writing values "1" or "2"
+
 		- Writing "1" will flush the image to the storage
-		area and prepare the device for authentication on disconnect.
+		  area and prepare the device for authentication on disconnect.
 		- Writing "2" will run some basic validation on the image
-		and flush it to the storage area.
+		  and flush it to the storage area.
diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb
index e449b8374f6a..bf2c1968525f 100644
--- a/Documentation/ABI/testing/sysfs-bus-usb
+++ b/Documentation/ABI/testing/sysfs-bus-usb
@@ -9,6 +9,7 @@ Description:
 		by writing INTERFACE to /sys/bus/usb/drivers_probe
 		This allows to avoid side-effects with drivers
 		that need multiple interfaces.
+
 		A deauthorized interface cannot be probed or claimed.
 
 What:		/sys/bus/usb/devices/usbX/interface_authorized_default
@@ -216,6 +217,7 @@ Description:
 		 - Bit 0 of this field selects the "old" enumeration scheme,
 		   as it is considerably faster (it only causes one USB reset
 		   instead of 2).
+
 		   The old enumeration scheme can also be selected globally
 		   using /sys/module/usbcore/parameters/old_scheme_first, but
 		   it is often not desirable as the new scheme was introduced to
diff --git a/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533 b/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533
index c0e0a9ae7b3d..8251e78abc49 100644
--- a/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533
+++ b/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533
@@ -6,8 +6,10 @@ Description:
 		Get the ALS output channel used as input in
 		ALS-current-control mode (0, 1), where:
 
-		0 - out_current0 (backlight 0)
-		1 - out_current1 (backlight 1)
+		==  ==========================
+		0   out_current0 (backlight 0)
+		1   out_current1 (backlight 1)
+		==  ==========================
 
 What:		/sys/class/backlight/<backlight>/als_en
 Date:		May 2012
@@ -30,8 +32,10 @@ Contact:	Johan Hovold <jhovold@gmail.com>
 Description:
 		Set the brightness-mapping mode (0, 1), where:
 
-		0 - exponential mode
-		1 - linear mode
+		==  ================
+		0   exponential mode
+		1   linear mode
+		==  ================
 
 What:		/sys/class/backlight/<backlight>/pwm
 Date:		April 2012
@@ -40,9 +44,11 @@ Contact:	Johan Hovold <jhovold@gmail.com>
 Description:
 		Set the PWM-input control mask (5 bits), where:
 
-		bit 5 - PWM-input enabled in Zone 4
-		bit 4 - PWM-input enabled in Zone 3
-		bit 3 - PWM-input enabled in Zone 2
-		bit 2 - PWM-input enabled in Zone 1
-		bit 1 - PWM-input enabled in Zone 0
-		bit 0 - PWM-input enabled
+		=====   ===========================
+		bit 5   PWM-input enabled in Zone 4
+		bit 4   PWM-input enabled in Zone 3
+		bit 3   PWM-input enabled in Zone 2
+		bit 2   PWM-input enabled in Zone 1
+		bit 1   PWM-input enabled in Zone 0
+		bit 0   PWM-input enabled
+		=====   ===========================
diff --git a/Documentation/ABI/testing/sysfs-class-bdi b/Documentation/ABI/testing/sysfs-class-bdi
index d773d5697cf5..5402bd74ba43 100644
--- a/Documentation/ABI/testing/sysfs-class-bdi
+++ b/Documentation/ABI/testing/sysfs-class-bdi
@@ -24,7 +24,6 @@ default
 	filesystems which do not provide their own BDI.
 
 Files under /sys/class/bdi/<bdi>/
----------------------------------
 
 read_ahead_kb (read-write)
 
diff --git a/Documentation/ABI/testing/sysfs-class-chromeos b/Documentation/ABI/testing/sysfs-class-chromeos
index 5819699d66ec..74ece942722e 100644
--- a/Documentation/ABI/testing/sysfs-class-chromeos
+++ b/Documentation/ABI/testing/sysfs-class-chromeos
@@ -17,13 +17,14 @@ Date:		August 2015
 KernelVersion:	4.2
 Description:
 		Tell the EC to reboot in various ways. Options are:
-		"cancel": Cancel a pending reboot.
-		"ro": Jump to RO without rebooting.
-		"rw": Jump to RW without rebooting.
-		"cold": Cold reboot.
-		"disable-jump": Disable jump until next reboot.
-		"hibernate": Hibernate the EC.
-		"at-shutdown": Reboot after an AP shutdown.
+
+		- "cancel": Cancel a pending reboot.
+		- "ro": Jump to RO without rebooting.
+		- "rw": Jump to RW without rebooting.
+		- "cold": Cold reboot.
+		- "disable-jump": Disable jump until next reboot.
+		- "hibernate": Hibernate the EC.
+		- "at-shutdown": Reboot after an AP shutdown.
 
 What:		/sys/class/chromeos/<ec-device-name>/version
 Date:		August 2015
diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl
index a6f51a104c44..818f55970efb 100644
--- a/Documentation/ABI/testing/sysfs-class-cxl
+++ b/Documentation/ABI/testing/sysfs-class-cxl
@@ -217,6 +217,7 @@ Description:    read/write
                 card.  A power cycle is required to load the image.
                 "none" could be useful for debugging because the trace arrays
                 are preserved.
+
                 "user" and "factory" means PERST will cause either the user or
                 user or factory image to be loaded.
                 Default is to reload on PERST whichever image the card has
@@ -240,8 +241,11 @@ Contact:	linuxppc-dev@lists.ozlabs.org
 Description:	read/write
 		Trust that when an image is reloaded via PERST, it will not
 		have changed.
-		0 = don't trust, the image may be different (default)
-		1 = trust that the image will not change.
+
+		==  =================================================
+		0   don't trust, the image may be different (default)
+		1   trust that the image will not change.
+		==  =================================================
 Users:		https://github.com/ibm-capi/libcxl
 
 What:           /sys/class/cxl/<card>/psl_timebase_synced
diff --git a/Documentation/ABI/testing/sysfs-class-devlink b/Documentation/ABI/testing/sysfs-class-devlink
index 64791b65c9a3..b662f747c83e 100644
--- a/Documentation/ABI/testing/sysfs-class-devlink
+++ b/Documentation/ABI/testing/sysfs-class-devlink
@@ -18,9 +18,9 @@ Description:
 
 		This will be one of the following strings:
 
-		'consumer unbind'
-		'supplier unbind'
-		'never'
+		- 'consumer unbind'
+		- 'supplier unbind'
+		- 'never'
 
 		'consumer unbind' means the device link will be removed when
 		the consumer's driver is unbound from the consumer device.
@@ -49,8 +49,10 @@ Description:
 
 		This will be one of the following strings:
 
-		'0' - Does not affect runtime power management
-		'1' - Affects runtime power management
+		===   ========================================
+		'0'   Does not affect runtime power management
+		'1'   Affects runtime power management
+		===   ========================================
 
 What:		/sys/class/devlink/.../status
 Date:		May 2020
@@ -68,13 +70,13 @@ Description:
 
 		This will be one of the following strings:
 
-		'not tracked'
-		'dormant'
-		'available'
-		'consumer probing'
-		'active'
-		'supplier unbinding'
-		'unknown'
+		- 'not tracked'
+		- 'dormant'
+		- 'available'
+		- 'consumer probing'
+		- 'active'
+		- 'supplier unbinding'
+		- 'unknown'
 
 		'not tracked' means this device link does not track the status
 		and has no impact on the binding, unbinding and syncing the
@@ -114,8 +116,10 @@ Description:
 
 		This will be one of the following strings:
 
+		===  ================================
 		'0'
-		'1' - Affects runtime power management
+		'1'  Affects runtime power management
+		===  ================================
 
 		'0' means the device link can affect other device behaviors
 		like binding/unbinding, suspend/resume, runtime power
diff --git a/Documentation/ABI/testing/sysfs-class-extcon b/Documentation/ABI/testing/sysfs-class-extcon
index 57a726232912..fde0fecd5de9 100644
--- a/Documentation/ABI/testing/sysfs-class-extcon
+++ b/Documentation/ABI/testing/sysfs-class-extcon
@@ -39,19 +39,22 @@ Description:
 		callback.
 
 		If the default callback for showing function is used, the
-		format is like this:
-		# cat state
-		USB_OTG=1
-		HDMI=0
-		TA=1
-		EAR_JACK=0
-		#
+		format is like this::
+
+		    # cat state
+		    USB_OTG=1
+		    HDMI=0
+		    TA=1
+		    EAR_JACK=0
+		    #
+
 		In this example, the extcon device has USB_OTG and TA
 		cables attached and HDMI and EAR_JACK cables detached.
 
 		In order to update the state of an extcon device, enter a hex
-		state number starting with 0x:
-		# echo 0xHEX > state
+		state number starting with 0x::
+
+		    # echo 0xHEX > state
 
 		This updates the whole state of the extcon device.
 		Inputs of all the methods are required to meet the
@@ -84,12 +87,13 @@ Contact:	MyungJoo Ham <myungjoo.ham@samsung.com>
 Description:
 		Shows the relations of mutually exclusiveness. For example,
 		if the mutually_exclusive array of extcon device is
-		{0x3, 0x5, 0xC, 0x0}, then the output is:
-		# ls mutually_exclusive/
-		0x3
-		0x5
-		0xc
-		#
+		{0x3, 0x5, 0xC, 0x0}, then the output is::
+
+		    # ls mutually_exclusive/
+		    0x3
+		    0x5
+		    0xc
+		    #
 
 		Note that mutually_exclusive is a sub-directory of the extcon
 		device and the file names under the mutually_exclusive
diff --git a/Documentation/ABI/testing/sysfs-class-fpga-manager b/Documentation/ABI/testing/sysfs-class-fpga-manager
index 5284fa33d4c5..d78689c357a5 100644
--- a/Documentation/ABI/testing/sysfs-class-fpga-manager
+++ b/Documentation/ABI/testing/sysfs-class-fpga-manager
@@ -28,8 +28,7 @@ Description:	Read fpga manager state as a string.
 		* firmware request	= firmware class request in progress
 		* firmware request error = firmware request failed
 		* write init		= preparing FPGA for programming
-		* write init error	= Error while preparing FPGA for
-					  programming
+		* write init error	= Error while preparing FPGA for programming
 		* write			= FPGA ready to receive image data
 		* write error		= Error while programming
 		* write complete	= Doing post programming steps
@@ -47,7 +46,7 @@ Description:	Read fpga manager status as a string.
 		programming errors to userspace. This is a list of strings for
 		the supported status.
 
-		* reconfig operation error 	- invalid operations detected by
+		* reconfig operation error	- invalid operations detected by
 						  reconfiguration hardware.
 						  e.g. start reconfiguration
 						  with errors not cleared
diff --git a/Documentation/ABI/testing/sysfs-class-gnss b/Documentation/ABI/testing/sysfs-class-gnss
index 2467b6900eae..c8553d972edd 100644
--- a/Documentation/ABI/testing/sysfs-class-gnss
+++ b/Documentation/ABI/testing/sysfs-class-gnss
@@ -6,9 +6,11 @@ Description:
 		The GNSS receiver type. The currently identified types reflect
 		the protocol(s) supported by the receiver:
 
+			======		===========
 			"NMEA"		NMEA 0183
 			"SiRF"		SiRF Binary
 			"UBX"		UBX
+			======		===========
 
 		Note that also non-"NMEA" type receivers typically support a
 		subset of NMEA 0183 with vendor extensions (e.g. to allow
diff --git a/Documentation/ABI/testing/sysfs-class-led b/Documentation/ABI/testing/sysfs-class-led
index 65e040978f73..0ed5c2629c6f 100644
--- a/Documentation/ABI/testing/sysfs-class-led
+++ b/Documentation/ABI/testing/sysfs-class-led
@@ -47,6 +47,7 @@ Contact:	Richard Purdie <rpurdie@rpsys.net>
 Description:
 		Set the trigger for this LED. A trigger is a kernel based source
 		of LED events.
+
 		You can change triggers in a similar manner to the way an IO
 		scheduler is chosen. Trigger specific parameters can appear in
 		/sys/class/leds/<led> once a given trigger is selected. For
diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-el15203000 b/Documentation/ABI/testing/sysfs-class-led-driver-el15203000
index 69befe947d7e..da546e86deb5 100644
--- a/Documentation/ABI/testing/sysfs-class-led-driver-el15203000
+++ b/Documentation/ABI/testing/sysfs-class-led-driver-el15203000
@@ -27,23 +27,23 @@ Description:
 
 			^
 			|
-		    0 On -|----+                   +----+                   +---
+		  0 On -|----+                   +----+                   +---
 			|    |                   |    |                   |
 		    Off-|    +-------------------+    +-------------------+
 			|
-		    1 On -|    +----+                   +----+
+		  1 On -|    +----+                   +----+
 			|    |    |                   |    |
 		    Off |----+    +-------------------+    +------------------
 			|
-		    2 On -|         +----+                   +----+
+		  2 On -|         +----+                   +----+
 			|         |    |                   |    |
 		    Off-|---------+    +-------------------+    +-------------
 			|
-		    3 On -|              +----+                   +----+
+		  3 On -|              +----+                   +----+
 			|              |    |                   |    |
 		    Off-|--------------+    +-------------------+    +--------
 			|
-		    4 On -|                   +----+                   +----+
+		  4 On -|                   +----+                   +----+
 			|                   |    |                   |    |
 		    Off-|-------------------+    +-------------------+    +---
 			|
@@ -55,23 +55,23 @@ Description:
 
 			^
 			|
-		    0 On -|    +-------------------+    +-------------------+
+		  0 On -|    +-------------------+    +-------------------+
 			|    |                   |    |                   |
 		    Off-|----+                   +----+                   +---
 			|
-		    1 On -|----+    +-------------------+    +------------------
+		  1 On -|----+    +-------------------+    +------------------
 			|    |    |                   |    |
 		    Off |    +----+                   +----+
 			|
-		    2 On -|---------+    +-------------------+    +-------------
+		  2 On -|---------+    +-------------------+    +-------------
 			|         |    |                   |    |
 		    Off-|         +----+                   +----+
 			|
-		    3 On -|--------------+    +-------------------+    +--------
+		  3 On -|--------------+    +-------------------+    +--------
 			|              |    |                   |    |
 		    Off-|              +----+                   +----+
 			|
-		    4 On -|-------------------+    +-------------------+    +---
+		  4 On -|-------------------+    +-------------------+    +---
 			|                   |    |                   |    |
 		    Off-|                   +----+                   +----+
 			|
@@ -83,23 +83,23 @@ Description:
 
 			^
 			|
-		    0 On -|----+                                       +--------
+		  0 On -|----+                                       +--------
 			|    |                                       |
 		    Off-|    +---------------------------------------+
 			|
-		    1 On -|    +----+                             +----+
+		  1 On -|    +----+                             +----+
 			|    |    |                             |    |
 		    Off |----+    +-----------------------------+    +--------
 			|
-		    2 On -|         +----+                   +----+
+		  2 On -|         +----+                   +----+
 			|         |    |                   |    |
 		    Off-|---------+    +-------------------+    +-------------
 			|
-		    3 On -|              +----+         +----+
+		  3 On -|              +----+         +----+
 			|              |    |         |    |
 		    Off-|--------------+    +---------+    +------------------
 			|
-		    4 On -|                   +---------+
+		  4 On -|                   +---------+
 			|                   |         |
 		    Off-|-------------------+         +-----------------------
 			|
diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-lm3533 b/Documentation/ABI/testing/sysfs-class-led-driver-lm3533
index e4c89b261546..e38a835d0a85 100644
--- a/Documentation/ABI/testing/sysfs-class-led-driver-lm3533
+++ b/Documentation/ABI/testing/sysfs-class-led-driver-lm3533
@@ -6,8 +6,10 @@ Description:
 		Set the ALS output channel to use as input in
 		ALS-current-control mode (1, 2), where:
 
-		1 - out_current1
-		2 - out_current2
+		==  ============
+		1   out_current1
+		2   out_current2
+		==  ============
 
 What:		/sys/class/leds/<led>/als_en
 Date:		May 2012
@@ -24,14 +26,16 @@ Contact:	Johan Hovold <jhovold@gmail.com>
 Description:
 		Set the pattern generator fall and rise times (0..7), where:
 
-		0 - 2048 us
-		1 - 262 ms
-		2 - 524 ms
-		3 - 1.049 s
-		4 - 2.097 s
-		5 - 4.194 s
-		6 - 8.389 s
-		7 - 16.78 s
+		==  =======
+		0   2048 us
+		1   262 ms
+		2   524 ms
+		3   1.049 s
+		4   2.097 s
+		5   4.194 s
+		6   8.389 s
+		7   16.78 s
+		==  =======
 
 What:		/sys/class/leds/<led>/id
 Date:		April 2012
@@ -47,8 +51,10 @@ Contact:	Johan Hovold <jhovold@gmail.com>
 Description:
 		Set the brightness-mapping mode (0, 1), where:
 
-		0 - exponential mode
-		1 - linear mode
+		==  ================
+		0   exponential mode
+		1   linear mode
+		==  ================
 
 What:		/sys/class/leds/<led>/pwm
 Date:		April 2012
@@ -57,9 +63,11 @@ Contact:	Johan Hovold <jhovold@gmail.com>
 Description:
 		Set the PWM-input control mask (5 bits), where:
 
-		bit 5 - PWM-input enabled in Zone 4
-		bit 4 - PWM-input enabled in Zone 3
-		bit 3 - PWM-input enabled in Zone 2
-		bit 2 - PWM-input enabled in Zone 1
-		bit 1 - PWM-input enabled in Zone 0
-		bit 0 - PWM-input enabled
+		=====  ===========================
+		bit 5  PWM-input enabled in Zone 4
+		bit 4  PWM-input enabled in Zone 3
+		bit 3  PWM-input enabled in Zone 2
+		bit 2  PWM-input enabled in Zone 1
+		bit 1  PWM-input enabled in Zone 0
+		bit 0  PWM-input enabled
+		=====  ===========================
diff --git a/Documentation/ABI/testing/sysfs-class-led-flash b/Documentation/ABI/testing/sysfs-class-led-flash
index 220a0270b47b..11e5677c3672 100644
--- a/Documentation/ABI/testing/sysfs-class-led-flash
+++ b/Documentation/ABI/testing/sysfs-class-led-flash
@@ -55,26 +55,35 @@ Description:	read only
 		Flash faults are re-read after strobing the flash. Possible
 		flash faults:
 
-		* led-over-voltage - flash controller voltage to the flash LED
+		* led-over-voltage
+			flash controller voltage to the flash LED
 			has exceeded the limit specific to the flash controller
-		* flash-timeout-exceeded - the flash strobe was still on when
+		* flash-timeout-exceeded
+			the flash strobe was still on when
 			the timeout set by the user has expired; not all flash
 			controllers may set this in all such conditions
-		* controller-over-temperature - the flash controller has
+		* controller-over-temperature
+			the flash controller has
 			overheated
-		* controller-short-circuit - the short circuit protection
+		* controller-short-circuit
+			the short circuit protection
 			of the flash controller has been triggered
-		* led-power-supply-over-current - current in the LED power
+		* led-power-supply-over-current
+			current in the LED power
 			supply has exceeded the limit specific to the flash
 			controller
-		* indicator-led-fault - the flash controller has detected
+		* indicator-led-fault
+			the flash controller has detected
 			a short or open circuit condition on the indicator LED
-		* led-under-voltage - flash controller voltage to the flash
+		* led-under-voltage
+			flash controller voltage to the flash
 			LED has been below the minimum limit specific to
 			the flash
-		* controller-under-voltage - the input voltage of the flash
+		* controller-under-voltage
+			the input voltage of the flash
 			controller is below the limit under which strobing the
 			flash at full current will not be possible;
 			the condition persists until this flag is no longer set
-		* led-over-temperature - the temperature of the LED has exceeded
+		* led-over-temperature
+			the temperature of the LED has exceeded
 			its allowed upper limit
diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-netdev b/Documentation/ABI/testing/sysfs-class-led-trigger-netdev
index 451af6d6768c..646540950e38 100644
--- a/Documentation/ABI/testing/sysfs-class-led-trigger-netdev
+++ b/Documentation/ABI/testing/sysfs-class-led-trigger-netdev
@@ -19,18 +19,23 @@ KernelVersion:	4.16
 Contact:	linux-leds@vger.kernel.org
 Description:
 		Signal the link state of the named network device.
+
 		If set to 0 (default), the LED's normal state is off.
+
 		If set to 1, the LED's normal state reflects the link state
 		of the named network device.
 		Setting this value also immediately changes the LED state.
 
+
 What:		/sys/class/leds/<led>/tx
 Date:		Dec 2017
 KernelVersion:	4.16
 Contact:	linux-leds@vger.kernel.org
 Description:
 		Signal transmission of data on the named network device.
+
 		If set to 0 (default), the LED will not blink on transmission.
+
 		If set to 1, the LED will blink for the milliseconds specified
 		in interval to signal transmission.
 
@@ -40,6 +45,8 @@ KernelVersion:	4.16
 Contact:	linux-leds@vger.kernel.org
 Description:
 		Signal reception of data on the named network device.
+
 		If set to 0 (default), the LED will not blink on reception.
+
 		If set to 1, the LED will blink for the milliseconds specified
 		in interval to signal reception.
diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-usbport b/Documentation/ABI/testing/sysfs-class-led-trigger-usbport
index f440e690daef..eb81152b8348 100644
--- a/Documentation/ABI/testing/sysfs-class-led-trigger-usbport
+++ b/Documentation/ABI/testing/sysfs-class-led-trigger-usbport
@@ -8,5 +8,6 @@ Description:
 		selected for the USB port trigger. Selecting ports makes trigger
 		observing them for any connected devices and lighting on LED if
 		there are any.
+
 		Echoing "1" value selects USB port. Echoing "0" unselects it.
 		Current state can be also read.
diff --git a/Documentation/ABI/testing/sysfs-class-leds-gt683r b/Documentation/ABI/testing/sysfs-class-leds-gt683r
index 6adab27f646e..b57ffb26e722 100644
--- a/Documentation/ABI/testing/sysfs-class-leds-gt683r
+++ b/Documentation/ABI/testing/sysfs-class-leds-gt683r
@@ -7,9 +7,11 @@ Description:
 		of one LED will update the mode of its two sibling devices as
 		well. Possible values are:
 
-		0 - normal
-		1 - audio
-		2 - breathing
+		==  =========
+		0   normal
+		1   audio
+		2   breathing
+		==  =========
 
 		Normal: LEDs are fully on when enabled
 		Audio:  LEDs brightness depends on sound level
diff --git a/Documentation/ABI/testing/sysfs-class-net b/Documentation/ABI/testing/sysfs-class-net
index 3b404577f380..7670012ae9b6 100644
--- a/Documentation/ABI/testing/sysfs-class-net
+++ b/Documentation/ABI/testing/sysfs-class-net
@@ -4,10 +4,13 @@ KernelVersion:	3.17
 Contact:	netdev@vger.kernel.org
 Description:
 		Indicates the name assignment type. Possible values are:
-		1: enumerated by the kernel, possibly in an unpredictable way
-		2: predictably named by the kernel
-		3: named by userspace
-		4: renamed
+
+		== ==========================================================
+		1  enumerated by the kernel, possibly in an unpredictable way
+		2  predictably named by the kernel
+		3  named by userspace
+		4  renamed
+		== ==========================================================
 
 What:		/sys/class/net/<iface>/addr_assign_type
 Date:		July 2010
@@ -15,10 +18,13 @@ KernelVersion:	3.2
 Contact:	netdev@vger.kernel.org
 Description:
 		Indicates the address assignment type. Possible values are:
-		0: permanent address
-		1: randomly generated
-		2: stolen from another device
-		3: set using dev_set_mac_address
+
+		== =============================
+		0  permanent address
+		1  randomly generated
+		2  stolen from another device
+		3  set using dev_set_mac_address
+		== =============================
 
 What:		/sys/class/net/<iface>/addr_len
 Date:		April 2005
@@ -51,9 +57,12 @@ Description:
 		Default value 0 does not forward any link local frames.
 
 		Restricted bits:
-		0: 01-80-C2-00-00-00 Bridge Group Address used for STP
-		1: 01-80-C2-00-00-01 (MAC Control) 802.3 used for MAC PAUSE
-		2: 01-80-C2-00-00-02 (Link Aggregation) 802.3ad
+
+		== ========================================================
+		0  01-80-C2-00-00-00 Bridge Group Address used for STP
+		1  01-80-C2-00-00-01 (MAC Control) 802.3 used for MAC PAUSE
+		2  01-80-C2-00-00-02 (Link Aggregation) 802.3ad
+		== ========================================================
 
 		Any values not setting these bits can be used. Take special
 		care when forwarding control frames e.g. 802.1X-PAE or LLDP.
@@ -74,8 +83,11 @@ Contact:	netdev@vger.kernel.org
 Description:
 		Indicates the current physical link state of the interface.
 		Posssible values are:
-		0: physical link is down
-		1: physical link is up
+
+		== =====================
+		0  physical link is down
+		1  physical link is up
+		== =====================
 
 		Note: some special devices, e.g: bonding and team drivers will
 		allow this attribute to be written to force a link state for
@@ -131,8 +143,11 @@ Contact:	netdev@vger.kernel.org
 Description:
 		Indicates whether the interface is under test. Possible
 		values are:
-		0: interface is not being tested
-		1: interface is being tested
+
+		== =============================
+		0  interface is not being tested
+		1  interface is being tested
+		== =============================
 
 		When an interface is under test, it cannot be expected
 		to pass packets as normal.
@@ -144,8 +159,11 @@ Contact:	netdev@vger.kernel.org
 Description:
 		Indicates the interface latest or current duplex value. Possible
 		values are:
-		half: half duplex
-		full: full duplex
+
+		====  ===========
+		half  half duplex
+		full  full duplex
+		====  ===========
 
 		Note: This attribute is only valid for interfaces that implement
 		the ethtool get_link_ksettings method (mostly Ethernet).
@@ -196,8 +214,11 @@ Description:
 		Indicates the interface link mode, as a decimal number. This
 		attribute should be used in conjunction with 'dormant' attribute
 		to determine the interface usability. Possible values:
-		0: default link mode
-		1: dormant link mode
+
+		==  =================
+		0   default link mode
+		1   dormant link mode
+		==  =================
 
 What:		/sys/class/net/<iface>/mtu
 Date:		April 2005
@@ -226,7 +247,9 @@ KernelVersion:	2.6.17
 Contact:	netdev@vger.kernel.org
 Description:
 		Indicates the interface RFC2863 operational state as a string.
+
 		Possible values are:
+
 		"unknown", "notpresent", "down", "lowerlayerdown", "testing",
 		"dormant", "up".
 
diff --git a/Documentation/ABI/testing/sysfs-class-net-cdc_ncm b/Documentation/ABI/testing/sysfs-class-net-cdc_ncm
index f7be0e88b139..06416d0e163d 100644
--- a/Documentation/ABI/testing/sysfs-class-net-cdc_ncm
+++ b/Documentation/ABI/testing/sysfs-class-net-cdc_ncm
@@ -91,9 +91,9 @@ Date:		May 2014
 KernelVersion:	3.16
 Contact:	Bjørn Mork <bjorn@mork.no>
 Description:
-		Bit 0: 16-bit NTB supported (set to 1)
-		Bit 1: 32-bit NTB supported
-		Bits 2 – 15: reserved (reset to zero; must be ignored by host)
+		- Bit 0: 16-bit NTB supported (set to 1)
+		- Bit 1: 32-bit NTB supported
+		- Bits 2 – 15: reserved (reset to zero; must be ignored by host)
 
 What:		/sys/class/net/<iface>/cdc_ncm/dwNtbInMaxSize
 Date:		May 2014
diff --git a/Documentation/ABI/testing/sysfs-class-net-phydev b/Documentation/ABI/testing/sysfs-class-net-phydev
index 206cbf538b59..40ced0ea4316 100644
--- a/Documentation/ABI/testing/sysfs-class-net-phydev
+++ b/Documentation/ABI/testing/sysfs-class-net-phydev
@@ -35,7 +35,9 @@ Description:
 		Ethernet driver during bus enumeration, encoded in string.
 		This interface mode is used to configure the Ethernet MAC with the
 		appropriate mode for its data lines to the PHY hardware.
+
 		Possible values are:
+
 		<empty> (not available), mii, gmii, sgmii, tbi, rev-mii,
 		rmii, rgmii, rgmii-id, rgmii-rxid, rgmii-txid, rtbi, smii
 		xgmii, moca, qsgmii, trgmii, 1000base-x, 2500base-x, rxaui,
diff --git a/Documentation/ABI/testing/sysfs-class-pktcdvd b/Documentation/ABI/testing/sysfs-class-pktcdvd
index dde4f26d0780..ba1ce626591d 100644
--- a/Documentation/ABI/testing/sysfs-class-pktcdvd
+++ b/Documentation/ABI/testing/sysfs-class-pktcdvd
@@ -11,15 +11,17 @@ KernelVersion:	2.6.20
 Contact:	Thomas Maier <balagi@justmail.de>
 Description:
 
-		add:		(WO) Write a block device id (major:minor) to
+		==========	==============================================
+		add		(WO) Write a block device id (major:minor) to
 				create a new pktcdvd device and map it to the
 				block device.
 
-		remove:		(WO) Write the pktcdvd device id (major:minor)
+		remove		(WO) Write the pktcdvd device id (major:minor)
 				to remove the pktcdvd device.
 
-		device_map:	(RO) Shows the device mapping in format:
+		device_map	(RO) Shows the device mapping in format:
 				pktcdvd[0-7] <pktdevid> <blkdevid>
+		==========	==============================================
 
 
 What:		/sys/class/pktcdvd/pktcdvd[0-7]/dev
@@ -65,29 +67,31 @@ Date:		Oct. 2006
 KernelVersion:	2.6.20
 Contact:	Thomas Maier <balagi@justmail.de>
 Description:
-		size:		(RO) Contains the size of the bio write queue.
+		==============	================================================
+		size		(RO) Contains the size of the bio write queue.
 
-		congestion_off:	(RW) If bio write queue size is below this mark,
+		congestion_off	(RW) If bio write queue size is below this mark,
 				accept new bio requests from the block layer.
 
-		congestion_on:	(RW) If bio write queue size is higher as this
+		congestion_on	(RW) If bio write queue size is higher as this
 				mark, do no longer accept bio write requests
 				from the block layer and wait till the pktcdvd
 				device has processed enough bio's so that bio
 				write queue size is below congestion off mark.
 				A value of <= 0 disables congestion control.
+		==============	================================================
 
 
 Example:
 --------
-To use the pktcdvd sysfs interface directly, you can do:
+To use the pktcdvd sysfs interface directly, you can do::
 
-# create a new pktcdvd device mapped to /dev/hdc
-echo "22:0" >/sys/class/pktcdvd/add
-cat /sys/class/pktcdvd/device_map
-# assuming device pktcdvd0 was created, look at stat's
-cat /sys/class/pktcdvd/pktcdvd0/stat/kb_written
-# print the device id of the mapped block device
-fgrep pktcdvd0 /sys/class/pktcdvd/device_map
-# remove device, using pktcdvd0 device id   253:0
-echo "253:0" >/sys/class/pktcdvd/remove
+    # create a new pktcdvd device mapped to /dev/hdc
+    echo "22:0" >/sys/class/pktcdvd/add
+    cat /sys/class/pktcdvd/device_map
+    # assuming device pktcdvd0 was created, look at stat's
+    cat /sys/class/pktcdvd/pktcdvd0/stat/kb_written
+    # print the device id of the mapped block device
+    fgrep pktcdvd0 /sys/class/pktcdvd/device_map
+    # remove device, using pktcdvd0 device id   253:0
+    echo "253:0" >/sys/class/pktcdvd/remove
diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
index d4319a04c302..d68ad528a8e5 100644
--- a/Documentation/ABI/testing/sysfs-class-power
+++ b/Documentation/ABI/testing/sysfs-class-power
@@ -43,7 +43,9 @@ Date:		May 2007
 Contact:	linux-pm@vger.kernel.org
 Description:
 		Fine grain representation of battery capacity.
+
 		Access: Read
+
 		Valid values: 0 - 100 (percent)
 
 What:		/sys/class/power_supply/<supply_name>/capacity_alert_max
@@ -58,6 +60,7 @@ Description:
 		low).
 
 		Access: Read, Write
+
 		Valid values: 0 - 100 (percent)
 
 What:		/sys/class/power_supply/<supply_name>/capacity_alert_min
@@ -88,6 +91,7 @@ Description:
 		completely useless.
 
 		Access: Read
+
 		Valid values: 0 - 100 (percent)
 
 What:		/sys/class/power_supply/<supply_name>/capacity_level
@@ -111,6 +115,7 @@ Description:
 		which they average readings to smooth out the reported value.
 
 		Access: Read
+
 		Valid values: Represented in microamps. Negative values are used
 		for discharging batteries, positive values for charging batteries.
 
@@ -131,6 +136,7 @@ Description:
 		This value is not averaged/smoothed.
 
 		Access: Read
+
 		Valid values: Represented in microamps. Negative values are used
 		for discharging batteries, positive values for charging batteries.
 
@@ -383,7 +389,7 @@ Description:
 
 **USB Properties**
 
-What: 		/sys/class/power_supply/<supply_name>/current_avg
+What:		/sys/class/power_supply/<supply_name>/current_avg
 Date:		May 2007
 Contact:	linux-pm@vger.kernel.org
 Description:
@@ -449,6 +455,7 @@ Description:
 		solved using power limit use input_voltage_limit.
 
 		Access: Read, Write
+
 		Valid values: Represented in microvolts
 
 What:		/sys/class/power_supply/<supply_name>/input_power_limit
@@ -462,6 +469,7 @@ Description:
 		limit only for problems that can be solved using power limit.
 
 		Access: Read, Write
+
 		Valid values: Represented in microwatts
 
 What:		/sys/class/power_supply/<supply_name>/online,
@@ -747,6 +755,7 @@ Description:
 		manufactured.
 
 		Access: Read
+
 		Valid values: Reported as integer
 
 What:		/sys/class/power_supply/<supply_name>/manufacture_month
@@ -756,6 +765,7 @@ Description:
 		Reports the month when the device has been manufactured.
 
 		Access: Read
+
 		Valid values: 1-12
 
 What:		/sys/class/power_supply/<supply_name>/manufacture_day
diff --git a/Documentation/ABI/testing/sysfs-class-power-mp2629 b/Documentation/ABI/testing/sysfs-class-power-mp2629
index 327a07e22805..914d67caac0d 100644
--- a/Documentation/ABI/testing/sysfs-class-power-mp2629
+++ b/Documentation/ABI/testing/sysfs-class-power-mp2629
@@ -5,4 +5,5 @@ Description:
 		Represents a battery impedance compensation to accelerate charging.
 
                 Access: Read, Write
+
                 Valid values: Represented in milli-ohms. Valid range is [0, 140].
diff --git a/Documentation/ABI/testing/sysfs-class-power-twl4030 b/Documentation/ABI/testing/sysfs-class-power-twl4030
index 7ac36dba87bc..b52f7023f8ba 100644
--- a/Documentation/ABI/testing/sysfs-class-power-twl4030
+++ b/Documentation/ABI/testing/sysfs-class-power-twl4030
@@ -6,9 +6,9 @@ Description:
 	Possible values are:
 
 		=============	===========================================
-		"auto" 		draw power as appropriate for detected
+		"auto"		draw power as appropriate for detected
 				power source and battery status.
-		"off"  		do not draw any power.
+		"off"		do not draw any power.
 		"continuous"	activate mode described as "linear" in
 				TWL data sheets.  This uses whatever
 				current is available and doesn't switch off
diff --git a/Documentation/ABI/testing/sysfs-class-rapidio b/Documentation/ABI/testing/sysfs-class-rapidio
index 8716beeb16c1..19aefb21b639 100644
--- a/Documentation/ABI/testing/sysfs-class-rapidio
+++ b/Documentation/ABI/testing/sysfs-class-rapidio
@@ -6,6 +6,7 @@ Description:
 		The /sys/class/rapidio_port subdirectory contains individual
 		subdirectories named as "rapidioN" where N = mport ID registered
 		with RapidIO subsystem.
+
 		NOTE: An mport ID is not a RapidIO destination ID assigned to a
 		given local mport device.
 
@@ -16,7 +17,9 @@ Contact:	Matt Porter <mporter@kernel.crashing.org>,
 		Alexandre Bounine <alexandre.bounine@idt.com>
 Description:
 		(RO) reports RapidIO common transport system size:
+
 		0 = small (8-bit destination ID, max. 256 devices),
+
 		1 = large (16-bit destination ID, max. 65536 devices).
 
 What:		/sys/class/rapidio_port/rapidioN/port_destid
@@ -25,31 +28,32 @@ KernelVersion:	v3.15
 Contact:	Matt Porter <mporter@kernel.crashing.org>,
 		Alexandre Bounine <alexandre.bounine@idt.com>
 Description:
-		(RO) reports RapidIO destination ID assigned to the given
-		RapidIO mport device. If value 0xFFFFFFFF is returned this means
-		that no valid destination ID have been assigned to the mport
-		(yet). Normally, before enumeration/discovery have been executed
-		only fabric enumerating mports have a valid destination ID
-		assigned to them using "hdid=..." rapidio module parameter.
+
+(RO) reports RapidIO destination ID assigned to the given
+RapidIO mport device. If value 0xFFFFFFFF is returned this means
+that no valid destination ID have been assigned to the mport
+(yet). Normally, before enumeration/discovery have been executed
+only fabric enumerating mports have a valid destination ID
+assigned to them using "hdid=..." rapidio module parameter.
 
 After enumeration or discovery was performed for a given mport device,
 the corresponding subdirectory will also contain subdirectories for each
 child RapidIO device connected to the mport.
 
 The example below shows mport device subdirectory with several child RapidIO
-devices attached to it.
+devices attached to it::
 
-[rio@rapidio ~]$ ls /sys/class/rapidio_port/rapidio0/ -l
-total 0
-drwxr-xr-x 3 root root    0 Feb 11 15:10 00:e:0001
-drwxr-xr-x 3 root root    0 Feb 11 15:10 00:e:0004
-drwxr-xr-x 3 root root    0 Feb 11 15:10 00:e:0007
-drwxr-xr-x 3 root root    0 Feb 11 15:10 00:s:0002
-drwxr-xr-x 3 root root    0 Feb 11 15:10 00:s:0003
-drwxr-xr-x 3 root root    0 Feb 11 15:10 00:s:0005
-lrwxrwxrwx 1 root root    0 Feb 11 15:11 device -> ../../../0000:01:00.0
--r--r--r-- 1 root root 4096 Feb 11 15:11 port_destid
-drwxr-xr-x 2 root root    0 Feb 11 15:11 power
-lrwxrwxrwx 1 root root    0 Feb 11 15:04 subsystem -> ../../../../../../class/rapidio_port
--r--r--r-- 1 root root 4096 Feb 11 15:11 sys_size
--rw-r--r-- 1 root root 4096 Feb 11 15:04 uevent
+    [rio@rapidio ~]$ ls /sys/class/rapidio_port/rapidio0/ -l
+    total 0
+    drwxr-xr-x 3 root root    0 Feb 11 15:10 00:e:0001
+    drwxr-xr-x 3 root root    0 Feb 11 15:10 00:e:0004
+    drwxr-xr-x 3 root root    0 Feb 11 15:10 00:e:0007
+    drwxr-xr-x 3 root root    0 Feb 11 15:10 00:s:0002
+    drwxr-xr-x 3 root root    0 Feb 11 15:10 00:s:0003
+    drwxr-xr-x 3 root root    0 Feb 11 15:10 00:s:0005
+    lrwxrwxrwx 1 root root    0 Feb 11 15:11 device -> ../../../0000:01:00.0
+    -r--r--r-- 1 root root 4096 Feb 11 15:11 port_destid
+    drwxr-xr-x 2 root root    0 Feb 11 15:11 power
+    lrwxrwxrwx 1 root root    0 Feb 11 15:04 subsystem -> ../../../../../../class/rapidio_port
+    -r--r--r-- 1 root root 4096 Feb 11 15:11 sys_size
+    -rw-r--r-- 1 root root 4096 Feb 11 15:04 uevent
diff --git a/Documentation/ABI/testing/sysfs-class-regulator b/Documentation/ABI/testing/sysfs-class-regulator
index bc578bc60628..8516f08806dd 100644
--- a/Documentation/ABI/testing/sysfs-class-regulator
+++ b/Documentation/ABI/testing/sysfs-class-regulator
@@ -35,13 +35,13 @@ Description:
 
 		This will be one of the following strings:
 
-			off
-			on
-			error
-			fast
-			normal
-			idle
-			standby
+			- off
+			- on
+			- error
+			- fast
+			- normal
+			- idle
+			- standby
 
 		"off" means the regulator is not supplying power to the
 		system.
@@ -74,9 +74,9 @@ Description:
 
 		This will be one of the following strings:
 
-		'voltage'
-		'current'
-		'unknown'
+		- 'voltage'
+		- 'current'
+		- 'unknown'
 
 		'voltage' means the regulator output voltage can be controlled
 		by software.
@@ -129,11 +129,11 @@ Description:
 
 		The opmode value can be one of the following strings:
 
-		'fast'
-		'normal'
-		'idle'
-		'standby'
-		'unknown'
+		- 'fast'
+		- 'normal'
+		- 'idle'
+		- 'standby'
+		- 'unknown'
 
 		The modes are described in include/linux/regulator/consumer.h
 
@@ -360,9 +360,9 @@ Description:
 
 		This will be one of the following strings:
 
-		'enabled'
-		'disabled'
-		'unknown'
+		- 'enabled'
+		- 'disabled'
+		- 'unknown'
 
 		'enabled' means the regulator is in bypass mode.
 
diff --git a/Documentation/ABI/testing/sysfs-class-remoteproc b/Documentation/ABI/testing/sysfs-class-remoteproc
index 066b9b6f4924..0c9ee55098b8 100644
--- a/Documentation/ABI/testing/sysfs-class-remoteproc
+++ b/Documentation/ABI/testing/sysfs-class-remoteproc
@@ -16,11 +16,11 @@ Description:	Remote processor state
 
 		Reports the state of the remote processor, which will be one of:
 
-		"offline"
-		"suspended"
-		"running"
-		"crashed"
-		"invalid"
+		- "offline"
+		- "suspended"
+		- "running"
+		- "crashed"
+		- "invalid"
 
 		"offline" means the remote processor is powered off.
 
@@ -38,8 +38,8 @@ Description:	Remote processor state
 		Writing this file controls the state of the remote processor.
 		The following states can be written:
 
-		"start"
-		"stop"
+		- "start"
+		- "stop"
 
 		Writing "start" will attempt to start the processor running the
 		firmware indicated by, or written to,
diff --git a/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration b/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration
index ec950c93e5c6..ee8ed6494a01 100644
--- a/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration
+++ b/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration
@@ -7,6 +7,7 @@ Description:    Attribute for calibrating ST-Ericsson AB8500 Real Time Clock
                 calibrate the AB8500.s 32KHz Real Time Clock.
                 Every 60 seconds the AB8500 will correct the RTC's value
                 by adding to it the value of this attribute.
+
                 The range of the attribute is -127 to +127 in units of
                 30.5 micro-seconds (half-parts-per-million of the 32KHz clock)
 Users:          The /vendor/st-ericsson/base_utilities/core/rtc_calibration
diff --git a/Documentation/ABI/testing/sysfs-class-uwb_rc b/Documentation/ABI/testing/sysfs-class-uwb_rc
index a0578751c1e3..6c5dcad21e19 100644
--- a/Documentation/ABI/testing/sysfs-class-uwb_rc
+++ b/Documentation/ABI/testing/sysfs-class-uwb_rc
@@ -66,11 +66,14 @@ Description:
                 <channel> <type> [<bpst offset>]
 
                 to start (or stop) scanning on a channel.  <type> is one of:
-                    0 - scan
-                    1 - scan outside BP
-                    2 - scan while inactive
-                    3 - scanning disabled
-                    4 - scan (with start time of <bpst offset>)
+
+		   ==   =======================================
+                    0   scan
+                    1   scan outside BP
+                    2   scan while inactive
+                    3   scanning disabled
+                    4   scan (with start time of <bpst offset>)
+		   ==   =======================================
 
 What:           /sys/class/uwb_rc/uwbN/mac_address
 Date:           July 2008
diff --git a/Documentation/ABI/testing/sysfs-class-watchdog b/Documentation/ABI/testing/sysfs-class-watchdog
index 9860a8b2ba75..585caecda3a5 100644
--- a/Documentation/ABI/testing/sysfs-class-watchdog
+++ b/Documentation/ABI/testing/sysfs-class-watchdog
@@ -91,10 +91,13 @@ Description:
 		h/w strapping (for WDT2 only).
 
 		At alternate flash the 'access_cs0' sysfs node provides:
-			ast2400: a way to get access to the primary SPI flash
+
+			ast2400:
+				a way to get access to the primary SPI flash
 				chip at CS0 after booting from the alternate
 				chip at CS1.
-			ast2500: a way to restore the normal address mapping
+			ast2500:
+				a way to restore the normal address mapping
 				from (CS0->CS1, CS1->CS0) to (CS0->CS0,
 				CS1->CS1).
 
diff --git a/Documentation/ABI/testing/sysfs-dev b/Documentation/ABI/testing/sysfs-dev
index a9f2b8b0530f..d1739063e762 100644
--- a/Documentation/ABI/testing/sysfs-dev
+++ b/Documentation/ABI/testing/sysfs-dev
@@ -9,9 +9,10 @@ Description:	The /sys/dev tree provides a method to look up the sysfs
 		the form "<major>:<minor>".  These links point to the
 		corresponding sysfs path for the given device.
 
-		Example:
-		$ readlink /sys/dev/block/8:32
-		../../block/sdc
+		Example::
+
+		  $ readlink /sys/dev/block/8:32
+		  ../../block/sdc
 
 		Entries in /sys/dev/char and /sys/dev/block will be
 		dynamically created and destroyed as devices enter and
diff --git a/Documentation/ABI/testing/sysfs-devices-mapping b/Documentation/ABI/testing/sysfs-devices-mapping
index 490ccfd67f12..8d202bac9394 100644
--- a/Documentation/ABI/testing/sysfs-devices-mapping
+++ b/Documentation/ABI/testing/sysfs-devices-mapping
@@ -8,26 +8,27 @@ Description:
                 block.
                 For example, on 4-die Xeon platform with up to 6 IIO stacks per
                 die and, therefore, 6 IIO PMON blocks per die, the mapping of
-                IIO PMON block 0 exposes as the following:
+                IIO PMON block 0 exposes as the following::
 
-                $ ls /sys/devices/uncore_iio_0/die*
-                -r--r--r-- /sys/devices/uncore_iio_0/die0
-                -r--r--r-- /sys/devices/uncore_iio_0/die1
-                -r--r--r-- /sys/devices/uncore_iio_0/die2
-                -r--r--r-- /sys/devices/uncore_iio_0/die3
+		    $ ls /sys/devices/uncore_iio_0/die*
+		    -r--r--r-- /sys/devices/uncore_iio_0/die0
+		    -r--r--r-- /sys/devices/uncore_iio_0/die1
+		    -r--r--r-- /sys/devices/uncore_iio_0/die2
+		    -r--r--r-- /sys/devices/uncore_iio_0/die3
 
-                $ tail /sys/devices/uncore_iio_0/die*
-                ==> /sys/devices/uncore_iio_0/die0 <==
-                0000:00
-                ==> /sys/devices/uncore_iio_0/die1 <==
-                0000:40
-                ==> /sys/devices/uncore_iio_0/die2 <==
-                0000:80
-                ==> /sys/devices/uncore_iio_0/die3 <==
-                0000:c0
+		    $ tail /sys/devices/uncore_iio_0/die*
+		    ==> /sys/devices/uncore_iio_0/die0 <==
+		    0000:00
+		    ==> /sys/devices/uncore_iio_0/die1 <==
+		    0000:40
+		    ==> /sys/devices/uncore_iio_0/die2 <==
+		    0000:80
+		    ==> /sys/devices/uncore_iio_0/die3 <==
+		    0000:c0
 
-                Which means:
-                IIO PMU 0 on die 0 belongs to PCI RP on bus 0x00, domain 0x0000
-                IIO PMU 0 on die 1 belongs to PCI RP on bus 0x40, domain 0x0000
-                IIO PMU 0 on die 2 belongs to PCI RP on bus 0x80, domain 0x0000
-                IIO PMU 0 on die 3 belongs to PCI RP on bus 0xc0, domain 0x0000
+                Which means::
+
+		    IIO PMU 0 on die 0 belongs to PCI RP on bus 0x00, domain 0x0000
+		    IIO PMU 0 on die 1 belongs to PCI RP on bus 0x40, domain 0x0000
+		    IIO PMU 0 on die 2 belongs to PCI RP on bus 0x80, domain 0x0000
+		    IIO PMU 0 on die 3 belongs to PCI RP on bus 0xc0, domain 0x0000
diff --git a/Documentation/ABI/testing/sysfs-devices-memory b/Documentation/ABI/testing/sysfs-devices-memory
index deef3b5723cf..2da2b1fba2c1 100644
--- a/Documentation/ABI/testing/sysfs-devices-memory
+++ b/Documentation/ABI/testing/sysfs-devices-memory
@@ -47,16 +47,19 @@ Description:
 		online/offline state of the memory section.  When written,
 		root can toggle the the online/offline state of a removable
 		memory section (see removable file description above)
-		using the following commands.
-		# echo online > /sys/devices/system/memory/memoryX/state
-		# echo offline > /sys/devices/system/memory/memoryX/state
+		using the following commands::
+
+		  # echo online > /sys/devices/system/memory/memoryX/state
+		  # echo offline > /sys/devices/system/memory/memoryX/state
 
 		For example, if /sys/devices/system/memory/memory22/removable
 		contains a value of 1 and
 		/sys/devices/system/memory/memory22/state contains the
 		string "online" the following command can be executed by
-		by root to offline that section.
-		# echo offline > /sys/devices/system/memory/memory22/state
+		by root to offline that section::
+
+		  # echo offline > /sys/devices/system/memory/memory22/state
+
 Users:		hotplug memory remove tools
 		http://www.ibm.com/developerworks/wikis/display/LinuxP/powerpc-utils
 
@@ -78,6 +81,7 @@ Description:
 
 		For example, the following symbolic link is created for
 		memory section 9 on node0:
+
 		/sys/devices/system/memory/memory9/node0 -> ../../node/node0
 
 
@@ -90,4 +94,5 @@ Description:
 		points to the corresponding /sys/devices/system/memory/memoryY
 		memory section directory.  For example, the following symbolic
 		link is created for memory section 9 on node0.
+
 		/sys/devices/system/node/node0/memory9 -> ../../memory/memory9
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget b/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget
index d548eaac230a..40f29a01fd14 100644
--- a/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget
+++ b/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget
@@ -3,8 +3,9 @@ Date:		April 2010
 Contact:	Fabien Chouteau <fabien.chouteau@barco.com>
 Description:
 		Show the suspend state of an USB composite gadget.
-		1 -> suspended
-		0 -> resumed
+
+		- 1 -> suspended
+		- 0 -> resumed
 
 		(_UDC_ is the name of the USB Device Controller driver)
 
@@ -17,5 +18,6 @@ Description:
 		Storage mode.
 
 		Possible values are:
-			1 -> ignore the FUA flag
-			0 -> obey the FUA flag
+
+			- 1 -> ignore the FUA flag
+			- 0 -> obey the FUA flag
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-ipmi b/Documentation/ABI/testing/sysfs-devices-platform-ipmi
index afb5db856e1c..07df0ddc0b69 100644
--- a/Documentation/ABI/testing/sysfs-devices-platform-ipmi
+++ b/Documentation/ABI/testing/sysfs-devices-platform-ipmi
@@ -123,38 +123,40 @@ KernelVersion:	v4.15
 Contact:	openipmi-developer@lists.sourceforge.net
 Description:
 
-		idles:			(RO) Number of times the interface was
+		======================	========================================
+		idles			(RO) Number of times the interface was
 					idle while being polled.
 
-		watchdog_pretimeouts:	(RO) Number of watchdog pretimeouts.
+		watchdog_pretimeouts	(RO) Number of watchdog pretimeouts.
 
-		complete_transactions:	(RO) Number of completed messages.
+		complete_transactions	(RO) Number of completed messages.
 
-		events:			(RO) Number of IPMI events received from
+		events			(RO) Number of IPMI events received from
 					the hardware.
 
-		interrupts:		(RO) Number of interrupts the driver
+		interrupts		(RO) Number of interrupts the driver
 					handled.
 
-		hosed_count:		(RO) Number of times the hardware didn't
+		hosed_count		(RO) Number of times the hardware didn't
 					follow the state machine.
 
-		long_timeouts:		(RO) Number of times the driver
+		long_timeouts		(RO) Number of times the driver
 					requested a timer while nothing was in
 					progress.
 
-		flag_fetches:		(RO) Number of times the driver
+		flag_fetches		(RO) Number of times the driver
 					requested flags from the hardware.
 
-		attentions:		(RO) Number of time the driver got an
+		attentions		(RO) Number of time the driver got an
 					ATTN from the hardware.
 
-		incoming_messages:	(RO) Number of asynchronous messages
+		incoming_messages	(RO) Number of asynchronous messages
 					received.
 
-		short_timeouts:		(RO) Number of times the driver
+		short_timeouts		(RO) Number of times the driver
 					requested a timer while an operation was
 					in progress.
+		======================	========================================
 
 
 What:		/sys/devices/platform/ipmi_si.*/interrupts_enabled
@@ -201,38 +203,40 @@ Date:		Sep, 2017
 KernelVersion:	v4.15
 Contact:	openipmi-developer@lists.sourceforge.net
 Description:
-		hosed:			(RO) Number of times the hardware didn't
+		======================	========================================
+		hosed			(RO) Number of times the hardware didn't
 					follow the state machine.
 
-		alerts:			(RO) Number of alerts received.
+		alerts			(RO) Number of alerts received.
 
-		sent_messages:		(RO) Number of total messages sent.
+		sent_messages		(RO) Number of total messages sent.
 
-		sent_message_parts:	(RO) Number of message parts sent.
+		sent_message_parts	(RO) Number of message parts sent.
 					Messages may be broken into parts if
 					they are long.
 
-		received_messages:	(RO) Number of message responses
+		received_messages	(RO) Number of message responses
 					received.
 
-		received_message_parts: (RO) Number of message fragments
+		received_message_parts	(RO) Number of message fragments
 					received.
 
-		events:			(RO) Number of received events.
+		events			(RO) Number of received events.
 
-		watchdog_pretimeouts:	(RO) Number of watchdog pretimeouts.
+		watchdog_pretimeouts	(RO) Number of watchdog pretimeouts.
 
-		flag_fetches:		(RO) Number of times a flag fetch was
+		flag_fetches		(RO) Number of times a flag fetch was
 					requested.
 
-		send_retries:		(RO) Number of time a message was
+		send_retries		(RO) Number of time a message was
 					retried.
 
-		receive_retries:	(RO) Number of times the receive of a
+		receive_retries		(RO) Number of times the receive of a
 					message was retried.
 
-		send_errors:		(RO) Number of times the send of a
+		send_errors		(RO) Number of times the send of a
 					message failed.
 
-		receive_errors:		(RO) Number of errors in receiving
+		receive_errors		(RO) Number of errors in receiving
 					messages.
+		======================	========================================
diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index 274c337ec6a9..1a04ca8162ad 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -169,7 +169,7 @@ Description:
 			      observed CPU idle duration was too short for it
 			      (a count).
 
-		below: 	 (RO) Number of times this state was entered, but the
+		below:	 (RO) Number of times this state was entered, but the
 			      observed CPU idle duration was too long for it
 			      (a count).
 		======== ==== =================================================
@@ -601,7 +601,7 @@ Description:	Secure Virtual Machine
 		Facility in POWER9 and newer processors. i.e., it is a Secure
 		Virtual Machine.
 
-What: 		/sys/devices/system/cpu/cpuX/purr
+What:		/sys/devices/system/cpu/cpuX/purr
 Date:		Apr 2005
 Contact:	Linux for PowerPC mailing list <linuxppc-dev@ozlabs.org>
 Description:	PURR ticks for this CPU since the system boot.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-lenovo b/Documentation/ABI/testing/sysfs-driver-hid-lenovo
index 53a0725962e1..aee85ca1f6be 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-lenovo
+++ b/Documentation/ABI/testing/sysfs-driver-hid-lenovo
@@ -3,14 +3,18 @@ Date:		July 2011
 Contact:	linux-input@vger.kernel.org
 Description:	This controls if mouse clicks should be generated if the trackpoint is quickly pressed. How fast this press has to be
 		is being controlled by press_speed.
+
 		Values are 0 or 1.
+
 		Applies to Thinkpad USB Keyboard with TrackPoint.
 
 What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/dragging
 Date:		July 2011
 Contact:	linux-input@vger.kernel.org
 Description:	If this setting is enabled, it is possible to do dragging by pressing the trackpoint. This requires press_to_select to be enabled.
+
 		Values are 0 or 1.
+
 		Applies to Thinkpad USB Keyboard with TrackPoint.
 
 What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/release_to_select
@@ -25,7 +29,9 @@ Date:		July 2011
 Contact:	linux-input@vger.kernel.org
 Description:	This setting controls if the mouse click events generated by pressing the trackpoint (if press_to_select is enabled) generate
 		a left or right mouse button click.
+
 		Values are 0 or 1.
+
 		Applies to Thinkpad USB Keyboard with TrackPoint.
 
 What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/sensitivity
@@ -39,12 +45,16 @@ What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-
 Date:		July 2011
 Contact:	linux-input@vger.kernel.org
 Description:	This setting controls how fast the trackpoint needs to be pressed to generate a mouse click if press_to_select is enabled.
+
 		Values are decimal integers from 1 (slowest) to 255 (fastest).
+
 		Applies to Thinkpad USB Keyboard with TrackPoint.
 
 What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/fn_lock
 Date:		July 2014
 Contact:	linux-input@vger.kernel.org
 Description:	This setting controls whether Fn Lock is enabled on the keyboard (i.e. if F1 is Mute or F1)
+
 		Values are 0 or 1
+
 		Applies to ThinkPad Compact (USB|Bluetooth) Keyboard with TrackPoint.
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-ntrig b/Documentation/ABI/testing/sysfs-driver-hid-ntrig
index e574a5625efe..0e323a5cec6c 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-ntrig
+++ b/Documentation/ABI/testing/sysfs-driver-hid-ntrig
@@ -29,12 +29,13 @@ Contact:	linux-input@vger.kernel.org
 Description:
 		Threholds to override activation slack.
 
-		activation_width:	(RW) Width threshold to immediately
+		=================	=====================================
+		activation_width	(RW) Width threshold to immediately
 					start processing touch events.
 
-		activation_height:	(RW) Height threshold to immediately
+		activation_height	(RW) Height threshold to immediately
 					start processing touch events.
-
+		=================	=====================================
 
 What:		/sys/bus/hid/drivers/ntrig/<dev>/min_width
 What:		/sys/bus/hid/drivers/ntrig/<dev>/min_height
@@ -44,11 +45,13 @@ Contact:	linux-input@vger.kernel.org
 Description:
 		Minimum size contact accepted.
 
-		min_width:	(RW) Minimum touch contact width to decide
+		==========	===========================================
+		min_width	(RW) Minimum touch contact width to decide
 				activation and activity.
 
-		min_height:	(RW) Minimum touch contact height to decide
+		min_height	(RW) Minimum touch contact height to decide
 				activation and activity.
+		==========	===========================================
 
 
 What:		/sys/bus/hid/drivers/ntrig/<dev>/sensor_physical_width
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone
index 8f7982c70d72..11cd9bf0ad18 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone
+++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kone
@@ -3,17 +3,21 @@ Date:		March 2010
 Contact:	Stefan Achatz <erazor_de@users.sourceforge.net>
 Description:	It is possible to switch the dpi setting of the mouse with the
 		press of a button.
+
 		When read, this file returns the raw number of the actual dpi
 		setting reported by the mouse. This number has to be further
 		processed to receive the real dpi value:
 
+		===== =====
 		VALUE DPI
+		===== =====
 		1     800
 		2     1200
 		3     1600
 		4     2000
 		5     2400
 		6     3200
+		===== =====
 
 		This file is readonly.
 Users:		http://roccat.sourceforge.net
@@ -22,6 +26,7 @@ What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-
 Date:		March 2010
 Contact:	Stefan Achatz <erazor_de@users.sourceforge.net>
 Description:	When read, this file returns the number of the actual profile.
+
 		This file is readonly.
 Users:		http://roccat.sourceforge.net
 
@@ -33,6 +38,7 @@ Description:	When read, this file returns the raw integer version number of the
 		further usage in other programs. To receive the real version
 		number the decimal point has to be shifted 2 positions to the
 		left. E.g. a returned value of 138 means 1.38
+
 		This file is readonly.
 Users:		http://roccat.sourceforge.net
 
@@ -43,10 +49,13 @@ Description:	The mouse can store 5 profiles which can be switched by the
                 press of a button. A profile holds information like button
                 mappings, sensitivity, the colors of the 5 leds and light
                 effects.
+
                 When read, these files return the respective profile. The
                 returned data is 975 bytes in size.
+
 		When written, this file lets one write the respective profile
 		data back to the mouse. The data has to be 975 bytes long.
+
 		The mouse will reject invalid data, whereas the profile number
 		stored in the profile doesn't need to fit the number of the
 		store.
@@ -58,6 +67,7 @@ Contact:	Stefan Achatz <erazor_de@users.sourceforge.net>
 Description:	When read, this file returns the settings stored in the mouse.
 		The size of the data is 36 bytes and holds information like the
 		startup_profile, tcu state and calibration_data.
+
 		When written, this file lets write settings back to the mouse.
 		The data has to be 36 bytes long. The mouse will reject invalid
 		data.
@@ -67,8 +77,10 @@ What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-
 Date:		March 2010
 Contact:	Stefan Achatz <erazor_de@users.sourceforge.net>
 Description:	The integer value of this attribute ranges from 1 to 5.
+
                 When read, this attribute returns the number of the profile
                 that's active when the mouse is powered on.
+
 		When written, this file sets the number of the startup profile
 		and the mouse activates this profile immediately.
 Users:		http://roccat.sourceforge.net
@@ -80,9 +92,12 @@ Description:	The mouse has a "Tracking Control Unit" which lets the user
 		calibrate the laser power to fit the mousepad surface.
 		When read, this file returns the current state of the TCU,
 		where 0 means off and 1 means on.
+
 		Writing 0 in this file will switch the TCU off.
+
 		Writing 1 in this file will start the calibration which takes
 		around 6 seconds to complete and activates the TCU.
+
 Users:		http://roccat.sourceforge.net
 
 What:		/sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kone/roccatkone<minor>/weight
@@ -93,14 +108,18 @@ Description:	The mouse can be equipped with one of four supplied weights
 		and its value can be read out. When read, this file returns the
 		raw value returned by the mouse which eases further processing
 		in other software.
+
 		The values map to the weights as follows:
 
+		===== ======
 		VALUE WEIGHT
+		===== ======
 		0     none
 		1     5g
 		2     10g
 		3     15g
 		4     20g
+		===== ======
 
 		This file is readonly.
 Users:		http://roccat.sourceforge.net
diff --git a/Documentation/ABI/testing/sysfs-driver-hid-wiimote b/Documentation/ABI/testing/sysfs-driver-hid-wiimote
index cd7b82a5c27d..3bf43d9dcdfe 100644
--- a/Documentation/ABI/testing/sysfs-driver-hid-wiimote
+++ b/Documentation/ABI/testing/sysfs-driver-hid-wiimote
@@ -20,6 +20,7 @@ Description:	This file contains the currently connected and initialized
 		the official Nintendo Nunchuck extension and classic is the
 		Nintendo Classic Controller extension. The motionp extension can
 		be combined with the other two.
+
 		Starting with kernel-version 3.11 Motion Plus hotplugging is
 		supported and if detected, it's no longer reported as static
 		extension. You will get uevent notifications for the motion-plus
diff --git a/Documentation/ABI/testing/sysfs-driver-input-exc3000 b/Documentation/ABI/testing/sysfs-driver-input-exc3000
index 3d316d54f81c..cd7c578aef2c 100644
--- a/Documentation/ABI/testing/sysfs-driver-input-exc3000
+++ b/Documentation/ABI/testing/sysfs-driver-input-exc3000
@@ -4,6 +4,7 @@ Contact:	linux-input@vger.kernel.org
 Description:    Reports the firmware version provided by the touchscreen, for example "00_T6" on a EXC80H60
 
 		Access: Read
+
 		Valid values: Represented as string
 
 What:		/sys/bus/i2c/devices/xxx/model
@@ -12,4 +13,5 @@ Contact:	linux-input@vger.kernel.org
 Description:    Reports the model identification provided by the touchscreen, for example "Orion_1320" on a EXC80H60
 
 		Access: Read
+
 		Valid values: Represented as string
diff --git a/Documentation/ABI/testing/sysfs-driver-jz4780-efuse b/Documentation/ABI/testing/sysfs-driver-jz4780-efuse
index bb6f5d6ceea0..4cf595d681e6 100644
--- a/Documentation/ABI/testing/sysfs-driver-jz4780-efuse
+++ b/Documentation/ABI/testing/sysfs-driver-jz4780-efuse
@@ -4,7 +4,9 @@ Contact:	PrasannaKumar Muralidharan <prasannatsmkumar@gmail.com>
 Description:	read-only access to the efuse on the Ingenic JZ4780 SoC
 		The SoC has a one time programmable 8K efuse that is
 		split into segments. The driver supports read only.
-		The segments are
+		The segments are:
+
+		===== ======== =================
 		0x000   64 bit Random Number
 		0x008  128 bit Ingenic Chip ID
 		0x018  128 bit Customer ID
@@ -12,5 +14,7 @@ Description:	read-only access to the efuse on the Ingenic JZ4780 SoC
 		0x1E0    8 bit Protect Segment
 		0x1E1 2296 bit HDMI Key
 		0x300 2048 bit Security boot key
+		===== ======== =================
+
 Users:		any user space application which wants to read the Chip
 		and Customer ID
diff --git a/Documentation/ABI/testing/sysfs-driver-pciback b/Documentation/ABI/testing/sysfs-driver-pciback
index 73308c2b81b0..49f5fd0c8bbd 100644
--- a/Documentation/ABI/testing/sysfs-driver-pciback
+++ b/Documentation/ABI/testing/sysfs-driver-pciback
@@ -7,8 +7,10 @@ Description:
                 the format of DDDD:BB:DD.F-REG:SIZE:MASK will allow the guest
                 to write and read from the PCI device. That is Domain:Bus:
                 Device.Function-Register:Size:Mask (Domain is optional).
-                For example:
-                #echo 00:19.0-E0:2:FF > /sys/bus/pci/drivers/pciback/quirks
+                For example::
+
+                  #echo 00:19.0-E0:2:FF > /sys/bus/pci/drivers/pciback/quirks
+
                 will allow the guest to read and write to the configuration
                 register 0x0E.
 
diff --git a/Documentation/ABI/testing/sysfs-driver-ufs b/Documentation/ABI/testing/sysfs-driver-ufs
index d1a352194d2e..adc0d0e91607 100644
--- a/Documentation/ABI/testing/sysfs-driver-ufs
+++ b/Documentation/ABI/testing/sysfs-driver-ufs
@@ -18,6 +18,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the device type. This is one of the UFS
 		device descriptor parameters. The full information about
 		the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/device_class
@@ -26,6 +27,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the device class. This is one of the UFS
 		device descriptor parameters. The full information about
 		the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/device_sub_class
@@ -34,6 +36,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the UFS storage subclass. This is one of
 		the UFS device descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/protocol
@@ -43,6 +46,7 @@ Description:	This file shows the protocol supported by an UFS device.
 		This is one of the UFS device descriptor parameters.
 		The full information about the descriptor could be found
 		at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/number_of_luns
@@ -51,6 +55,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows number of logical units. This is one of
 		the UFS device descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/number_of_wluns
@@ -60,6 +65,7 @@ Description:	This file shows number of well known logical units.
 		This is one of the UFS device descriptor parameters.
 		The full information about the descriptor could be found
 		at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/boot_enable
@@ -69,6 +75,7 @@ Description:	This file shows value that indicates whether the device is
 		enabled for boot. This is one of the UFS device descriptor
 		parameters. The full information about the descriptor could
 		be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/descriptor_access_enable
@@ -79,6 +86,7 @@ Description:	This file shows value that indicates whether the device
 		of the boot sequence. This is one of the UFS device descriptor
 		parameters. The full information about the descriptor could
 		be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/initial_power_mode
@@ -88,6 +96,7 @@ Description:	This file shows value that defines the power mode after
 		device initialization or hardware reset. This is one of
 		the UFS device descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/high_priority_lun
@@ -96,6 +105,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the high priority lun. This is one of
 		the UFS device descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/secure_removal_type
@@ -104,6 +114,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the secure removal type. This is one of
 		the UFS device descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/support_security_lun
@@ -113,6 +124,7 @@ Description:	This file shows whether the security lun is supported.
 		This is one of the UFS device descriptor parameters.
 		The full information about the descriptor could be found
 		at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/bkops_termination_latency
@@ -122,6 +134,7 @@ Description:	This file shows the background operations termination
 		latency. This is one of the UFS device descriptor parameters.
 		The full information about the descriptor could be found
 		at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/initial_active_icc_level
@@ -130,6 +143,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the initial active ICC level. This is one
 		of the UFS device descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/specification_version
@@ -138,6 +152,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the specification version. This is one
 		of the UFS device descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/manufacturing_date
@@ -147,6 +162,7 @@ Description:	This file shows the manufacturing date in BCD format.
 		This is one of the UFS device descriptor parameters.
 		The full information about the descriptor could be found
 		at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/manufacturer_id
@@ -155,6 +171,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the manufacturee ID. This is one of the
 		UFS device descriptor parameters. The full information about
 		the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/rtt_capability
@@ -164,6 +181,7 @@ Description:	This file shows the maximum number of outstanding RTTs
 		supported by the device. This is one of the UFS device
 		descriptor parameters. The full information about
 		the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/rtc_update
@@ -173,6 +191,7 @@ Description:	This file shows the frequency and method of the realtime
 		clock update. This is one of the UFS device descriptor
 		parameters. The full information about the descriptor
 		could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/ufs_features
@@ -182,6 +201,7 @@ Description:	This file shows which features are supported by the device.
 		This is one of the UFS device descriptor parameters.
 		The full information about the descriptor could be
 		found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/ffu_timeout
@@ -190,6 +210,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the FFU timeout. This is one of the
 		UFS device descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/queue_depth
@@ -198,6 +219,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the device queue depth. This is one of the
 		UFS device descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/device_version
@@ -206,6 +228,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the device version. This is one of the
 		UFS device descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/number_of_secure_wpa
@@ -215,6 +238,7 @@ Description:	This file shows number of secure write protect areas
 		supported by the device. This is one of the UFS device
 		descriptor parameters. The full information about
 		the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/psa_max_data_size
@@ -225,6 +249,7 @@ Description:	This file shows the maximum amount of data that may be
 		This is one of the UFS device descriptor parameters.
 		The full information about the descriptor could be found
 		at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/psa_state_timeout
@@ -234,6 +259,7 @@ Description:	This file shows the command maximum timeout for a change
 		in PSA state. This is one of the UFS device descriptor
 		parameters. The full information about the descriptor could
 		be found at UFS specifications 2.1.
+
 		The file is read only.
 
 
@@ -244,6 +270,7 @@ Description:	This file shows the MIPI UniPro version number in BCD format.
 		This is one of the UFS interconnect descriptor parameters.
 		The full information about the descriptor could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/interconnect_descriptor/mphy_version
@@ -253,6 +280,7 @@ Description:	This file shows the MIPI M-PHY version number in BCD format.
 		This is one of the UFS interconnect descriptor parameters.
 		The full information about the descriptor could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 
@@ -264,6 +292,7 @@ Description:	This file shows the total memory quantity available to
 		of the UFS geometry descriptor parameters. The full
 		information about the descriptor could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/max_number_of_luns
@@ -273,6 +302,7 @@ Description:	This file shows the maximum number of logical units
 		supported by the UFS device. This is one of the UFS
 		geometry descriptor parameters. The full information about
 		the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/segment_size
@@ -281,6 +311,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the segment size. This is one of the UFS
 		geometry descriptor parameters. The full information about
 		the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/allocation_unit_size
@@ -289,6 +320,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the allocation unit size. This is one of
 		the UFS geometry descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/min_addressable_block_size
@@ -298,6 +330,7 @@ Description:	This file shows the minimum addressable block size. This
 		is one of the UFS geometry descriptor parameters. The full
 		information about the descriptor could be found at UFS
 		specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/optimal_read_block_size
@@ -307,6 +340,7 @@ Description:	This file shows the optimal read block size. This is one
 		of the UFS geometry descriptor parameters. The full
 		information about the descriptor could be found at UFS
 		specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/optimal_write_block_size
@@ -316,6 +350,7 @@ Description:	This file shows the optimal write block size. This is one
 		of the UFS geometry descriptor parameters. The full
 		information about the descriptor could be found at UFS
 		specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/max_in_buffer_size
@@ -325,6 +360,7 @@ Description:	This file shows the maximum data-in buffer size. This
 		is one of the UFS geometry descriptor parameters. The full
 		information about the descriptor could be found at UFS
 		specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/max_out_buffer_size
@@ -334,6 +370,7 @@ Description:	This file shows the maximum data-out buffer size. This
 		is one of the UFS geometry descriptor parameters. The full
 		information about the descriptor could be found at UFS
 		specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/rpmb_rw_size
@@ -343,6 +380,7 @@ Description:	This file shows the maximum number of RPMB frames allowed
 		in Security Protocol In/Out. This is one of the UFS geometry
 		descriptor parameters. The full information about the
 		descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/dyn_capacity_resource_policy
@@ -352,6 +390,7 @@ Description:	This file shows the dynamic capacity resource policy. This
 		is one of the UFS geometry descriptor parameters. The full
 		information about the descriptor could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/data_ordering
@@ -361,6 +400,7 @@ Description:	This file shows support for out-of-order data transfer.
 		This is one of the UFS geometry descriptor parameters.
 		The full information about the descriptor could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/max_number_of_contexts
@@ -370,6 +410,7 @@ Description:	This file shows maximum available number of contexts which
 		are supported by the device. This is one of the UFS geometry
 		descriptor parameters. The full information about the
 		descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/sys_data_tag_unit_size
@@ -378,6 +419,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows system data tag unit size. This is one of
 		the UFS geometry descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/sys_data_tag_resource_size
@@ -388,6 +430,7 @@ Description:	This file shows maximum storage area size allocated by
 		This is one of the UFS geometry descriptor parameters.
 		The full information about the descriptor could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/secure_removal_types
@@ -397,6 +440,7 @@ Description:	This file shows supported secure removal types. This is
 		one of the UFS geometry descriptor parameters. The full
 		information about the descriptor could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/memory_types
@@ -406,6 +450,7 @@ Description:	This file shows supported memory types. This is one of
 		the UFS geometry descriptor parameters. The full
 		information about the descriptor could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/*_memory_max_alloc_units
@@ -416,6 +461,7 @@ Description:	This file shows the maximum number of allocation units for
 		enhanced type 1-4). This is one of the UFS geometry
 		descriptor parameters. The full information about the
 		descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/*_memory_capacity_adjustment_factor
@@ -426,6 +472,7 @@ Description:	This file shows the memory capacity adjustment factor for
 		enhanced type 1-4). This is one of the UFS geometry
 		descriptor parameters. The full information about the
 		descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 
@@ -436,6 +483,7 @@ Description:	This file shows preend of life information. This is one
 		of the UFS health descriptor parameters. The full
 		information about the descriptor could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/health_descriptor/life_time_estimation_a
@@ -445,6 +493,7 @@ Description:	This file shows indication of the device life time
 		(method a). This is one of the UFS health descriptor
 		parameters. The full information about the descriptor
 		could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/health_descriptor/life_time_estimation_b
@@ -454,6 +503,7 @@ Description:	This file shows indication of the device life time
 		(method b). This is one of the UFS health descriptor
 		parameters. The full information about the descriptor
 		could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 
@@ -464,6 +514,7 @@ Description:	This file shows maximum VCC, VCCQ and VCCQ2 value for
 		active ICC levels from 0 to 15. This is one of the UFS
 		power descriptor parameters. The full information about
 		the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 
@@ -473,6 +524,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file contains a device manufactureer name string.
 		The full information about the descriptor could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/string_descriptors/product_name
@@ -480,6 +532,7 @@ Date:		February 2018
 Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file contains a product name string. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/string_descriptors/oem_id
@@ -487,6 +540,7 @@ Date:		February 2018
 Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file contains a OEM ID string. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/string_descriptors/serial_number
@@ -495,6 +549,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file contains a device serial number string. The full
 		information about the descriptor could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/string_descriptors/product_revision
@@ -503,6 +558,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file contains a product revision string. The full
 		information about the descriptor could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 
@@ -512,6 +568,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows boot LUN information. This is one of
 		the UFS unit descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/class/scsi_device/*/device/unit_descriptor/lun_write_protect
@@ -520,6 +577,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows LUN write protection status. This is one of
 		the UFS unit descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/class/scsi_device/*/device/unit_descriptor/lun_queue_depth
@@ -528,6 +586,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows LUN queue depth. This is one of the UFS
 		unit descriptor parameters. The full information about
 		the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/class/scsi_device/*/device/unit_descriptor/psa_sensitive
@@ -536,6 +595,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows PSA sensitivity. This is one of the UFS
 		unit descriptor parameters. The full information about
 		the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/class/scsi_device/*/device/unit_descriptor/lun_memory_type
@@ -544,6 +604,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows LUN memory type. This is one of the UFS
 		unit descriptor parameters. The full information about
 		the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/class/scsi_device/*/device/unit_descriptor/data_reliability
@@ -553,6 +614,7 @@ Description:	This file defines the device behavior when a power failure
 		occurs during a write operation. This is one of the UFS
 		unit descriptor parameters. The full information about
 		the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/class/scsi_device/*/device/unit_descriptor/logical_block_size
@@ -562,6 +624,7 @@ Description:	This file shows the size of addressable logical blocks
 		(calculated as an exponent with base 2). This is one of
 		the UFS unit descriptor parameters. The full information about
 		the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/class/scsi_device/*/device/unit_descriptor/logical_block_count
@@ -571,6 +634,7 @@ Description:	This file shows total number of addressable logical blocks.
 		This is one of the UFS unit descriptor parameters. The full
 		information about the descriptor could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/class/scsi_device/*/device/unit_descriptor/erase_block_size
@@ -579,6 +643,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the erase block size. This is one of
 		the UFS unit descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/class/scsi_device/*/device/unit_descriptor/provisioning_type
@@ -587,6 +652,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the thin provisioning type. This is one of
 		the UFS unit descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/class/scsi_device/*/device/unit_descriptor/physical_memory_resourse_count
@@ -595,6 +661,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the total physical memory resources. This is
 		one of the UFS unit descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/class/scsi_device/*/device/unit_descriptor/context_capabilities
@@ -603,6 +670,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the context capabilities. This is one of
 		the UFS unit descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/class/scsi_device/*/device/unit_descriptor/large_unit_granularity
@@ -611,6 +679,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the granularity of the LUN. This is one of
 		the UFS unit descriptor parameters. The full information
 		about the descriptor could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 
@@ -619,6 +688,7 @@ Date:		February 2018
 Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the device init status. The full information
 		about the flag could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/flags/permanent_wpe
@@ -627,6 +697,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows whether permanent write protection is enabled.
 		The full information about the flag could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/flags/power_on_wpe
@@ -636,6 +707,7 @@ Description:	This file shows whether write protection is enabled on all
 		logical units configured as power on write protected. The
 		full information about the flag could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/flags/bkops_enable
@@ -644,6 +716,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows whether the device background operations are
 		enabled. The full information about the flag could be
 		found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/flags/life_span_mode_enable
@@ -652,6 +725,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows whether the device life span mode is enabled.
 		The full information about the flag could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/flags/phy_resource_removal
@@ -660,6 +734,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows whether physical resource removal is enable.
 		The full information about the flag could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/flags/busy_rtc
@@ -668,6 +743,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows whether the device is executing internal
 		operation related to real time clock. The full information
 		about the flag could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/flags/disable_fw_update
@@ -676,6 +752,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows whether the device FW update is permanently
 		disabled. The full information about the flag could be found
 		at UFS specifications 2.1.
+
 		The file is read only.
 
 
@@ -685,6 +762,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file provides the boot lun enabled UFS device attribute.
 		The full information about the attribute could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/current_power_mode
@@ -693,6 +771,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file provides the current power mode UFS device attribute.
 		The full information about the attribute could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/active_icc_level
@@ -701,6 +780,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file provides the active icc level UFS device attribute.
 		The full information about the attribute could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/ooo_data_enabled
@@ -709,6 +789,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file provides the out of order data transfer enabled UFS
 		device attribute. The full information about the attribute
 		could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/bkops_status
@@ -717,6 +798,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file provides the background operations status UFS device
 		attribute. The full information about the attribute could
 		be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/purge_status
@@ -725,6 +807,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file provides the purge operation status UFS device
 		attribute. The full information about the attribute could
 		be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/max_data_in_size
@@ -733,6 +816,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the maximum data size in a DATA IN
 		UPIU. The full information about the attribute could
 		be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/max_data_out_size
@@ -741,6 +825,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file shows the maximum number of bytes that can be
 		requested with a READY TO TRANSFER UPIU. The full information
 		about the attribute could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/reference_clock_frequency
@@ -749,6 +834,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file provides the reference clock frequency UFS device
 		attribute. The full information about the attribute could
 		be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/configuration_descriptor_lock
@@ -765,6 +851,7 @@ Description:	This file provides the maximum current number of
 		outstanding RTTs in device that is allowed. The full
 		information about the attribute could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/exception_event_control
@@ -773,6 +860,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file provides the exception event control UFS device
 		attribute. The full information about the attribute could
 		be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/exception_event_status
@@ -781,6 +869,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file provides the exception event status UFS device
 		attribute. The full information about the attribute could
 		be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/ffu_status
@@ -789,6 +878,7 @@ Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file provides the ffu status UFS device attribute.
 		The full information about the attribute could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/psa_state
@@ -796,6 +886,7 @@ Date:		February 2018
 Contact:	Stanislav Nijnikov <stanislav.nijnikov@wdc.com>
 Description:	This file show the PSA feature status. The full information
 		about the attribute could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/psa_data_size
@@ -805,6 +896,7 @@ Description:	This file shows the amount of data that the host plans to
 		load to all logical units in pre-soldering state.
 		The full information about the attribute could be found at
 		UFS specifications 2.1.
+
 		The file is read only.
 
 
@@ -815,6 +907,7 @@ Description:	This file shows the The amount of physical memory needed
 		to be removed from the physical memory resources pool of
 		the particular logical unit. The full information about
 		the attribute could be found at UFS specifications 2.1.
+
 		The file is read only.
 
 
@@ -824,24 +917,28 @@ Contact:	Subhash Jadavani <subhashj@codeaurora.org>
 Description:	This entry could be used to set or show the UFS device
 		runtime power management level. The current driver
 		implementation supports 6 levels with next target states:
-		0 - an UFS device will stay active, an UIC link will
-		stay active
-		1 - an UFS device will stay active, an UIC link will
-		hibernate
-		2 - an UFS device will moved to sleep, an UIC link will
-		stay active
-		3 - an UFS device will moved to sleep, an UIC link will
-		hibernate
-		4 - an UFS device will be powered off, an UIC link will
-		hibernate
-		5 - an UFS device will be powered off, an UIC link will
-		be powered off
+
+		==  ====================================================
+		0   an UFS device will stay active, an UIC link will
+		    stay active
+		1   an UFS device will stay active, an UIC link will
+		    hibernate
+		2   an UFS device will moved to sleep, an UIC link will
+		    stay active
+		3   an UFS device will moved to sleep, an UIC link will
+		    hibernate
+		4   an UFS device will be powered off, an UIC link will
+		    hibernate
+		5   an UFS device will be powered off, an UIC link will
+		    be powered off
+		==  ====================================================
 
 What:		/sys/bus/platform/drivers/ufshcd/*/rpm_target_dev_state
 Date:		February 2018
 Contact:	Subhash Jadavani <subhashj@codeaurora.org>
 Description:	This entry shows the target power mode of an UFS device
 		for the chosen runtime power management level.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/rpm_target_link_state
@@ -849,6 +946,7 @@ Date:		February 2018
 Contact:	Subhash Jadavani <subhashj@codeaurora.org>
 Description:	This entry shows the target state of an UFS UIC link
 		for the chosen runtime power management level.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/spm_lvl
@@ -857,24 +955,28 @@ Contact:	Subhash Jadavani <subhashj@codeaurora.org>
 Description:	This entry could be used to set or show the UFS device
 		system power management level. The current driver
 		implementation supports 6 levels with next target states:
-		0 - an UFS device will stay active, an UIC link will
-		stay active
-		1 - an UFS device will stay active, an UIC link will
-		hibernate
-		2 - an UFS device will moved to sleep, an UIC link will
-		stay active
-		3 - an UFS device will moved to sleep, an UIC link will
-		hibernate
-		4 - an UFS device will be powered off, an UIC link will
-		hibernate
-		5 - an UFS device will be powered off, an UIC link will
-		be powered off
+
+		==  ====================================================
+		0   an UFS device will stay active, an UIC link will
+		    stay active
+		1   an UFS device will stay active, an UIC link will
+		    hibernate
+		2   an UFS device will moved to sleep, an UIC link will
+		    stay active
+		3   an UFS device will moved to sleep, an UIC link will
+		    hibernate
+		4   an UFS device will be powered off, an UIC link will
+		    hibernate
+		5   an UFS device will be powered off, an UIC link will
+		    be powered off
+		==  ====================================================
 
 What:		/sys/bus/platform/drivers/ufshcd/*/spm_target_dev_state
 Date:		February 2018
 Contact:	Subhash Jadavani <subhashj@codeaurora.org>
 Description:	This entry shows the target power mode of an UFS device
 		for the chosen system power management level.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/spm_target_link_state
@@ -882,18 +984,21 @@ Date:		February 2018
 Contact:	Subhash Jadavani <subhashj@codeaurora.org>
 Description:	This entry shows the target state of an UFS UIC link
 		for the chosen system power management level.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_presv_us_en
 Date:		June 2020
 Contact:	Asutosh Das <asutoshd@codeaurora.org>
 Description:	This entry shows if preserve user-space was configured
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_shared_alloc_units
 Date:		June 2020
 Contact:	Asutosh Das <asutoshd@codeaurora.org>
 Description:	This entry shows the shared allocated units of WB buffer
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/device_descriptor/wb_type
@@ -901,6 +1006,7 @@ Date:		June 2020
 Contact:	Asutosh Das <asutoshd@codeaurora.org>
 Description:	This entry shows the configured WB type.
 		0x1 for shared buffer mode. 0x0 for dedicated buffer mode.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_buff_cap_adj
@@ -910,6 +1016,7 @@ Description:	This entry shows the total user-space decrease in shared
 		buffer mode.
 		The value of this parameter is 3 for TLC NAND when SLC mode
 		is used as WriteBooster Buffer. 2 for MLC NAND.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_max_alloc_units
@@ -917,6 +1024,7 @@ Date:		June 2020
 Contact:	Asutosh Das <asutoshd@codeaurora.org>
 Description:	This entry shows the Maximum total WriteBooster Buffer size
 		which is supported by the entire device.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_max_wb_luns
@@ -924,6 +1032,7 @@ Date:		June 2020
 Contact:	Asutosh Das <asutoshd@codeaurora.org>
 Description:	This entry shows the maximum number of luns that can support
 		WriteBooster.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_sup_red_type
@@ -937,46 +1046,59 @@ Description:	The supportability of user space reduction mode
 		preserve user space type.
 		02h: Device can be configured in either user space
 		reduction type or preserve user space type.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/geometry_descriptor/wb_sup_wb_type
 Date:		June 2020
 Contact:	Asutosh Das <asutoshd@codeaurora.org>
 Description:	The supportability of WriteBooster Buffer type.
-		00h: LU based WriteBooster Buffer configuration
-		01h: Single shared WriteBooster Buffer
-		configuration
-		02h: Supporting both LU based WriteBooster
-		Buffer and Single shared WriteBooster Buffer
-		configuration
+
+		===  ==========================================================
+		00h  LU based WriteBooster Buffer configuration
+		01h  Single shared WriteBooster Buffer configuration
+		02h  Supporting both LU based WriteBooster.
+		     Buffer and Single shared WriteBooster Buffer configuration
+		===  ==========================================================
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/flags/wb_enable
 Date:		June 2020
 Contact:	Asutosh Das <asutoshd@codeaurora.org>
 Description:	This entry shows the status of WriteBooster.
-		0: WriteBooster is not enabled.
-		1: WriteBooster is enabled
+
+		== ============================
+		0  WriteBooster is not enabled.
+		1  WriteBooster is enabled
+		== ============================
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/flags/wb_flush_en
 Date:		June 2020
 Contact:	Asutosh Das <asutoshd@codeaurora.org>
 Description:	This entry shows if flush is enabled.
-		0: Flush operation is not performed.
-		1: Flush operation is performed.
+
+		== =================================
+		0  Flush operation is not performed.
+		1  Flush operation is performed.
+		== =================================
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/flags/wb_flush_during_h8
 Date:		June 2020
 Contact:	Asutosh Das <asutoshd@codeaurora.org>
 Description:	Flush WriteBooster Buffer during hibernate state.
-		0: Device is not allowed to flush the
-		WriteBooster Buffer during link hibernate
-		state.
-		1: Device is allowed to flush the
-		WriteBooster Buffer during link hibernate
-		state
+
+		== =================================================
+		0  Device is not allowed to flush the
+		   WriteBooster Buffer during link hibernate state.
+		1  Device is allowed to flush the
+		   WriteBooster Buffer during link hibernate state.
+		== =================================================
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/wb_avail_buf
@@ -984,23 +1106,30 @@ Date:		June 2020
 Contact:	Asutosh Das <asutoshd@codeaurora.org>
 Description:	This entry shows the amount of unused WriteBooster buffer
 		available.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/wb_cur_buf
 Date:		June 2020
 Contact:	Asutosh Das <asutoshd@codeaurora.org>
 Description:	This entry shows the amount of unused current buffer.
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/wb_flush_status
 Date:		June 2020
 Contact:	Asutosh Das <asutoshd@codeaurora.org>
 Description:	This entry shows the flush operation status.
-		00h: idle
-		01h: Flush operation in progress
-		02h: Flush operation stopped prematurely.
-		03h: Flush operation completed successfully
-		04h: Flush operation general failure
+
+
+		===  ======================================
+		00h  idle
+		01h  Flush operation in progress
+		02h  Flush operation stopped prematurely.
+		03h  Flush operation completed successfully
+		04h  Flush operation general failure
+		===  ======================================
+
 		The file is read only.
 
 What:		/sys/bus/platform/drivers/ufshcd/*/attributes/wb_life_time_est
@@ -1008,9 +1137,13 @@ Date:		June 2020
 Contact:	Asutosh Das <asutoshd@codeaurora.org>
 Description:	This entry shows an indication of the WriteBooster Buffer
 		lifetime based on the amount of performed program/erase cycles
-		01h: 0% - 10% WriteBooster Buffer life time used
+
+		===  =============================================
+		01h  0% - 10% WriteBooster Buffer life time used
 		...
-		0Ah: 90% - 100% WriteBooster Buffer life time used
+		0Ah  90% - 100% WriteBooster Buffer life time used
+		===  =============================================
+
 		The file is read only.
 
 What:		/sys/class/scsi_device/*/device/unit_descriptor/wb_buf_alloc_units
@@ -1018,4 +1151,5 @@ Date:		June 2020
 Contact:	Asutosh Das <asutoshd@codeaurora.org>
 Description:	This entry shows the configured size of WriteBooster buffer.
 		0400h corresponds to 4GB.
+
 		The file is read only.
diff --git a/Documentation/ABI/testing/sysfs-driver-w1_ds28e17 b/Documentation/ABI/testing/sysfs-driver-w1_ds28e17
index d301e7017afe..e92aba4eb594 100644
--- a/Documentation/ABI/testing/sysfs-driver-w1_ds28e17
+++ b/Documentation/ABI/testing/sysfs-driver-w1_ds28e17
@@ -5,7 +5,9 @@ Contact:	Jan Kandziora <jjj@gmx.de>
 Description:	When written, this file sets the I2C speed on the connected
 		DS28E17 chip. When read, it reads the current setting from
 		the DS28E17 chip.
+
 		Valid values: 100, 400, 900 [kBaud].
+
 		Default 100, can be set by w1_ds28e17.speed= module parameter.
 Users:		w1_ds28e17 driver
 
@@ -17,5 +19,6 @@ Description:	When written, this file sets the multiplier used to calculate
 		the busy timeout for I2C operations on the connected DS28E17
 		chip. When read, returns the current setting.
 		Valid values: 1 to 9.
+
 		Default 1, can be set by w1_ds28e17.stretch= module parameter.
 Users:		w1_ds28e17 driver
diff --git a/Documentation/ABI/testing/sysfs-firmware-acpi b/Documentation/ABI/testing/sysfs-firmware-acpi
index e4afc2538210..b16d30a71709 100644
--- a/Documentation/ABI/testing/sysfs-firmware-acpi
+++ b/Documentation/ABI/testing/sysfs-firmware-acpi
@@ -81,11 +81,11 @@ Description:
 		  $ cd /sys/firmware/acpi/interrupts
 		  $ grep . *
 		  error:	     0
-		  ff_gbl_lock:	   0   enable
-		  ff_pmtimer:	  0  invalid
-		  ff_pwr_btn:	  0   enable
-		  ff_rt_clk:	 2  disable
-		  ff_slp_btn:	  0  invalid
+		  ff_gbl_lock:	     0   enable
+		  ff_pmtimer:	     0  invalid
+		  ff_pwr_btn:	     0   enable
+		  ff_rt_clk:	     2  disable
+		  ff_slp_btn:	     0  invalid
 		  gpe00:	     0	invalid
 		  gpe01:	     0	 enable
 		  gpe02:	   108	 enable
@@ -118,9 +118,9 @@ Description:
 		  gpe1D:	     0	invalid
 		  gpe1E:	     0	invalid
 		  gpe1F:	     0	invalid
-		  gpe_all:    1192
-		  sci:	1194
-		  sci_not:     0
+		  gpe_all:	  1192
+		  sci:		  1194
+		  sci_not:	     0
 
 		===========  ==================================================
 		sci	     The number of times the ACPI SCI
diff --git a/Documentation/ABI/testing/sysfs-firmware-efi-esrt b/Documentation/ABI/testing/sysfs-firmware-efi-esrt
index 6e431d1a4e79..31b57676d4ad 100644
--- a/Documentation/ABI/testing/sysfs-firmware-efi-esrt
+++ b/Documentation/ABI/testing/sysfs-firmware-efi-esrt
@@ -35,10 +35,13 @@ What:		/sys/firmware/efi/esrt/entries/entry$N/fw_type
 Date:		February 2015
 Contact:	Peter Jones <pjones@redhat.com>
 Description:	What kind of firmware entry this is:
-		0 - Unknown
-		1 - System Firmware
-		2 - Device Firmware
-		3 - UEFI Driver
+
+		==  ===============
+		0   Unknown
+		1   System Firmware
+		2   Device Firmware
+		3   UEFI Driver
+		==  ===============
 
 What:		/sys/firmware/efi/esrt/entries/entry$N/fw_class
 Date:		February 2015
@@ -71,11 +74,14 @@ Date:		February 2015
 Contact:	Peter Jones <pjones@redhat.com>
 Description:	The result of the last firmware update attempt for the
 		firmware resource entry.
-		0 - Success
-		1 - Insufficient resources
-		2 - Incorrect version
-		3 - Invalid format
-		4 - Authentication error
-		5 - AC power event
-		6 - Battery power event
+
+		==  ======================
+		0   Success
+		1   Insufficient resources
+		2   Incorrect version
+		3   Invalid format
+		4   Authentication error
+		5   AC power event
+		6   Battery power event
+		==  ======================
 
diff --git a/Documentation/ABI/testing/sysfs-firmware-efi-runtime-map b/Documentation/ABI/testing/sysfs-firmware-efi-runtime-map
index c61b9b348e99..9c4d581be396 100644
--- a/Documentation/ABI/testing/sysfs-firmware-efi-runtime-map
+++ b/Documentation/ABI/testing/sysfs-firmware-efi-runtime-map
@@ -14,7 +14,7 @@ Description:	Switching efi runtime services to virtual mode requires
 		/sys/firmware/efi/runtime-map/ is the directory the kernel
 		exports that information in.
 
-		subdirectories are named with the number of the memory range:
+		subdirectories are named with the number of the memory range::
 
 			/sys/firmware/efi/runtime-map/0
 			/sys/firmware/efi/runtime-map/1
@@ -24,11 +24,13 @@ Description:	Switching efi runtime services to virtual mode requires
 
 		Each subdirectory contains five files:
 
-		attribute : The attributes of the memory range.
-		num_pages : The size of the memory range in pages.
-		phys_addr : The physical address of the memory range.
-		type      : The type of the memory range.
-		virt_addr : The virtual address of the memory range.
+		=========   =========================================
+		attribute   The attributes of the memory range.
+		num_pages   The size of the memory range in pages.
+		phys_addr   The physical address of the memory range.
+		type        The type of the memory range.
+		virt_addr   The virtual address of the memory range.
+		=========   =========================================
 
 		Above values are all hexadecimal numbers with the '0x' prefix.
 Users:		Kexec
diff --git a/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg b/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg
index 011dda4f8e8a..ee0d6dbc810e 100644
--- a/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg
+++ b/Documentation/ABI/testing/sysfs-firmware-qemu_fw_cfg
@@ -15,7 +15,7 @@ Description:
 		to the fw_cfg device can be found in "docs/specs/fw_cfg.txt"
 		in the QEMU source tree.
 
-		=== SysFS fw_cfg Interface ===
+		**SysFS fw_cfg Interface**
 
 		The fw_cfg sysfs interface described in this document is only
 		intended to display discoverable blobs (i.e., those registered
@@ -31,7 +31,7 @@ Description:
 
 			/sys/firmware/qemu_fw_cfg/rev
 
-		--- Discoverable fw_cfg blobs by selector key ---
+		**Discoverable fw_cfg blobs by selector key**
 
 		All discoverable blobs listed in the fw_cfg file directory are
 		displayed as entries named after their unique selector key
@@ -45,24 +45,26 @@ Description:
 		Each such fw_cfg sysfs entry has the following values exported
 		as attributes:
 
-		name  	: The 56-byte nul-terminated ASCII string used as the
+		====	  ====================================================
+		name	  The 56-byte nul-terminated ASCII string used as the
 			  blob's 'file name' in the fw_cfg directory.
-		size  	: The length of the blob, as given in the fw_cfg
+		size	  The length of the blob, as given in the fw_cfg
 			  directory.
-		key	: The value of the blob's selector key as given in the
+		key	  The value of the blob's selector key as given in the
 			  fw_cfg directory. This value is the same as used in
 			  the parent directory name.
-		raw	: The raw bytes of the blob, obtained by selecting the
+		raw	  The raw bytes of the blob, obtained by selecting the
 			  entry via the control register, and reading a number
 			  of bytes equal to the blob size from the data
 			  register.
+		====	  ====================================================
 
-		--- Listing fw_cfg blobs by file name ---
+		**Listing fw_cfg blobs by file name**
 
 		While the fw_cfg device does not impose any specific naming
 		convention on the blobs registered in the file directory,
 		QEMU developers have traditionally used path name semantics
-		to give each blob a descriptive name. For example:
+		to give each blob a descriptive name. For example::
 
 			"bootorder"
 			"genroms/kvmvapic.bin"
@@ -81,7 +83,7 @@ Description:
 		of directories matching the path name components of fw_cfg
 		blob names, ending in symlinks to the by_key entry for each
 		"basename", as illustrated below (assume current directory is
-		/sys/firmware):
+		/sys/firmware)::
 
 		    qemu_fw_cfg/by_name/bootorder -> ../by_key/38
 		    qemu_fw_cfg/by_name/etc/e820 -> ../../by_key/35
diff --git a/Documentation/ABI/testing/sysfs-firmware-sfi b/Documentation/ABI/testing/sysfs-firmware-sfi
index 4be7d44aeacf..5210e0f06ddb 100644
--- a/Documentation/ABI/testing/sysfs-firmware-sfi
+++ b/Documentation/ABI/testing/sysfs-firmware-sfi
@@ -9,7 +9,7 @@ Description:
 		http://simplefirmware.org/documentation
 
 		While the tables are used by the kernel, user-space
-		can observe them this way:
+		can observe them this way::
 
-		# cd /sys/firmware/sfi/tables
-		# cat $TABLENAME > $TABLENAME.bin
+		  # cd /sys/firmware/sfi/tables
+		  # cat $TABLENAME > $TABLENAME.bin
diff --git a/Documentation/ABI/testing/sysfs-firmware-sgi_uv b/Documentation/ABI/testing/sysfs-firmware-sgi_uv
index 4573fd4b7876..66800baab096 100644
--- a/Documentation/ABI/testing/sysfs-firmware-sgi_uv
+++ b/Documentation/ABI/testing/sysfs-firmware-sgi_uv
@@ -5,7 +5,7 @@ Description:
 		The /sys/firmware/sgi_uv directory contains information
 		about the SGI UV platform.
 
-		Under that directory are a number of files:
+		Under that directory are a number of files::
 
 			partition_id
 			coherence_id
@@ -14,7 +14,7 @@ Description:
 		SGI UV systems can be partitioned into multiple physical
 		machines, which each partition running a unique copy
 		of the operating system.  Each partition will have a unique
-		partition id.  To display the partition id, use the command:
+		partition id.  To display the partition id, use the command::
 
 			cat /sys/firmware/sgi_uv/partition_id
 
@@ -22,6 +22,6 @@ Description:
 		A partitioned SGI UV system can have one or more coherence
 		domain.  The coherence id indicates which coherence domain
 		this partition is in.  To display the coherence id, use the
-		command:
+		command::
 
 			cat /sys/firmware/sgi_uv/coherence_id
diff --git a/Documentation/ABI/testing/sysfs-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs
index 834d0becae6d..67b3ed8e8c2f 100644
--- a/Documentation/ABI/testing/sysfs-fs-f2fs
+++ b/Documentation/ABI/testing/sysfs-fs-f2fs
@@ -20,10 +20,13 @@ What:		/sys/fs/f2fs/<disk>/gc_idle
 Date:		July 2013
 Contact:	"Namjae Jeon" <namjae.jeon@samsung.com>
 Description:	Controls the victim selection policy for garbage collection.
-		Setting gc_idle = 0(default) will disable this option. Setting
-		gc_idle = 1 will select the Cost Benefit approach & setting
-		gc_idle = 2 will select the greedy approach & setting
-		gc_idle = 3 will select the age-threshold based approach.
+		Setting gc_idle = 0(default) will disable this option. Setting:
+
+		===========  ===============================================
+		gc_idle = 1  will select the Cost Benefit approach & setting
+		gc_idle = 2  will select the greedy approach & setting
+		gc_idle = 3  will select the age-threshold based approach.
+		===========  ===============================================
 
 What:		/sys/fs/f2fs/<disk>/reclaim_segments
 Date:		October 2013
@@ -46,10 +49,17 @@ Date:		November 2013
 Contact:	"Jaegeuk Kim" <jaegeuk.kim@samsung.com>
 Description:	Controls the in-place-update policy.
 		updates in f2fs. User can set:
-		0x01: F2FS_IPU_FORCE, 0x02: F2FS_IPU_SSR,
-		0x04: F2FS_IPU_UTIL,  0x08: F2FS_IPU_SSR_UTIL,
-		0x10: F2FS_IPU_FSYNC, 0x20: F2FS_IPU_ASYNC,
-		0x40: F2FS_IPU_NOCACHE.
+
+		====  =================
+		0x01  F2FS_IPU_FORCE
+		0x02  F2FS_IPU_SSR
+		0x04  F2FS_IPU_UTIL
+		0x08  F2FS_IPU_SSR_UTIL
+		0x10  F2FS_IPU_FSYNC
+		0x20  F2FS_IPU_ASYNC,
+		0x40  F2FS_IPU_NOCACHE
+		====  =================
+
 		Refer segment.h for details.
 
 What:		/sys/fs/f2fs/<disk>/min_ipu_util
@@ -332,18 +342,28 @@ Date:		April 2020
 Contact:	"Jaegeuk Kim" <jaegeuk@kernel.org>
 Description:	Give a way to attach REQ_META|FUA to data writes
 		given temperature-based bits. Now the bits indicate:
-		*      REQ_META     |      REQ_FUA      |
-		*    5 |    4 |   3 |    2 |    1 |   0 |
-		* Cold | Warm | Hot | Cold | Warm | Hot |
+
+		+-------------------+-------------------+
+		|      REQ_META     |      REQ_FUA      |
+		+------+------+-----+------+------+-----+
+		|    5 |    4 |   3 |    2 |    1 |   0 |
+		+------+------+-----+------+------+-----+
+		| Cold | Warm | Hot | Cold | Warm | Hot |
+		+------+------+-----+------+------+-----+
 
 What:		/sys/fs/f2fs/<disk>/node_io_flag
 Date:		June 2020
 Contact:	"Jaegeuk Kim" <jaegeuk@kernel.org>
 Description:	Give a way to attach REQ_META|FUA to node writes
 		given temperature-based bits. Now the bits indicate:
-		*      REQ_META     |      REQ_FUA      |
-		*    5 |    4 |   3 |    2 |    1 |   0 |
-		* Cold | Warm | Hot | Cold | Warm | Hot |
+
+		+-------------------+-------------------+
+		|      REQ_META     |      REQ_FUA      |
+		+------+------+-----+------+------+-----+
+		|    5 |    4 |   3 |    2 |    1 |   0 |
+		+------+------+-----+------+------+-----+
+		| Cold | Warm | Hot | Cold | Warm | Hot |
+		+------+------+-----+------+------+-----+
 
 What:		/sys/fs/f2fs/<disk>/iostat_period_ms
 Date:		April 2020
diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-ksm b/Documentation/ABI/testing/sysfs-kernel-mm-ksm
index dfc13244cda3..1c9bed5595f5 100644
--- a/Documentation/ABI/testing/sysfs-kernel-mm-ksm
+++ b/Documentation/ABI/testing/sysfs-kernel-mm-ksm
@@ -34,8 +34,9 @@ Description:	Kernel Samepage Merging daemon sysfs interface
 		in a tree.
 
 		run: write 0 to disable ksm, read 0 while ksm is disabled.
-			write 1 to run ksm, read 1 while ksm is running.
-			write 2 to disable ksm and unmerge all its pages.
+
+			- write 1 to run ksm, read 1 while ksm is running.
+			- write 2 to disable ksm and unmerge all its pages.
 
 		sleep_millisecs: how many milliseconds ksm should sleep between
 		scans.
diff --git a/Documentation/ABI/testing/sysfs-kernel-slab b/Documentation/ABI/testing/sysfs-kernel-slab
index ed35833ad7f0..c9f12baf8baa 100644
--- a/Documentation/ABI/testing/sysfs-kernel-slab
+++ b/Documentation/ABI/testing/sysfs-kernel-slab
@@ -346,6 +346,7 @@ Description:
 		number of objects per slab.  If a slab cannot be allocated
 		because of fragmentation, SLUB will retry with the minimum order
 		possible depending on its characteristics.
+
 		When debug_guardpage_minorder=N (N > 0) parameter is specified
 		(see Documentation/admin-guide/kernel-parameters.rst), the minimum possible
 		order is used and this sysfs entry can not be used to change
@@ -361,6 +362,7 @@ Description:
 		new slab has not been possible at the cache's order and instead
 		fallen back to its minimum possible order.  It can be written to
 		clear the current count.
+
 		Available when CONFIG_SLUB_STATS is enabled.
 
 What:		/sys/kernel/slab/cache/partial
@@ -410,6 +412,7 @@ Description:
 		slab from a remote node as opposed to allocating a new slab on
 		the local node.  This reduces the amount of wasted memory over
 		the entire system but can be expensive.
+
 		Available when CONFIG_NUMA is enabled.
 
 What:		/sys/kernel/slab/cache/sanity_checks
diff --git a/Documentation/ABI/testing/sysfs-module b/Documentation/ABI/testing/sysfs-module
index 0aac02e7fb0e..353c0db5bc1f 100644
--- a/Documentation/ABI/testing/sysfs-module
+++ b/Documentation/ABI/testing/sysfs-module
@@ -17,14 +17,15 @@ KernelVersion:	3.1
 Contact:	Kirill Smelkov <kirr@mns.spb.ru>
 Description:	Maximum time allowed for periodic transfers per microframe (μs)
 
-		[ USB 2.0 sets maximum allowed time for periodic transfers per
+		Note:
+		  USB 2.0 sets maximum allowed time for periodic transfers per
 		  microframe to be 80%, that is 100 microseconds out of 125
 		  microseconds (full microframe).
 
 		  However there are cases, when 80% max isochronous bandwidth is
 		  too limiting. For example two video streams could require 110
 		  microseconds of isochronous bandwidth per microframe to work
-		  together. ]
+		  together. 
 
 		Through this setting it is possible to raise the limit so that
 		the host controller would allow allocating more than 100
@@ -45,8 +46,10 @@ Date:		Jan 2012
 KernelVersion:»·3.3
 Contact:	Kay Sievers <kay.sievers@vrfy.org>
 Description:	Module taint flags:
-			P - proprietary module
-			O - out-of-tree module
-			F - force-loaded module
-			C - staging driver module
-			E - unsigned module
+			==  =====================
+			P   proprietary module
+			O   out-of-tree module
+			F   force-loaded module
+			C   staging driver module
+			E   unsigned module
+			==  =====================
diff --git a/Documentation/ABI/testing/sysfs-platform-dell-laptop b/Documentation/ABI/testing/sysfs-platform-dell-laptop
index 9b917c7453de..82bcfe9df66e 100644
--- a/Documentation/ABI/testing/sysfs-platform-dell-laptop
+++ b/Documentation/ABI/testing/sysfs-platform-dell-laptop
@@ -34,9 +34,12 @@ Description:
 		this file. To disable a trigger, write its name preceded
 		by '-' instead.
 
-		For example, to enable the keyboard as trigger run:
+		For example, to enable the keyboard as trigger run::
+
 		    echo +keyboard > /sys/class/leds/dell::kbd_backlight/start_triggers
-		To disable it:
+
+		To disable it::
+
 		    echo -keyboard > /sys/class/leds/dell::kbd_backlight/start_triggers
 
 		Note that not all the available triggers can be configured.
@@ -57,7 +60,8 @@ Description:
 		with any the above units. If no unit is specified, the value
 		is assumed to be expressed in seconds.
 
-		For example, to set the timeout to 10 minutes run:
+		For example, to set the timeout to 10 minutes run::
+
 		    echo 10m > /sys/class/leds/dell::kbd_backlight/stop_timeout
 
 		Note that when this file is read, the returned value might be
diff --git a/Documentation/ABI/testing/sysfs-platform-dell-smbios b/Documentation/ABI/testing/sysfs-platform-dell-smbios
index 205d3b6361e0..e6e0f7f834a7 100644
--- a/Documentation/ABI/testing/sysfs-platform-dell-smbios
+++ b/Documentation/ABI/testing/sysfs-platform-dell-smbios
@@ -13,8 +13,8 @@ Description:
 		For example the token ID "5" would be available
 		as the following attributes:
 
-		0005_location
-		0005_value
+		- 0005_location
+		- 0005_value
 
 		Tokens will vary from machine to machine, and
 		only tokens available on that machine will be
diff --git a/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl b/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl
index c394b808be19..b6a138b50d99 100644
--- a/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl
+++ b/Documentation/ABI/testing/sysfs-platform-i2c-demux-pinctrl
@@ -5,9 +5,9 @@ Contact:	Wolfram Sang <wsa+renesas@sang-engineering.com>
 Description:
 		Reading the file will give you a list of masters which can be
 		selected for a demultiplexed bus. The format is
-		"<index>:<name>". Example from a Renesas Lager board:
+		"<index>:<name>". Example from a Renesas Lager board::
 
-		0:/i2c@e6500000 1:/i2c@e6508000
+		  0:/i2c@e6500000 1:/i2c@e6508000
 
 What:		/sys/devices/platform/<i2c-demux-name>/current_master
 Date:		January 2016
diff --git a/Documentation/ABI/testing/sysfs-platform-kim b/Documentation/ABI/testing/sysfs-platform-kim
index c1653271872a..a7f81de68046 100644
--- a/Documentation/ABI/testing/sysfs-platform-kim
+++ b/Documentation/ABI/testing/sysfs-platform-kim
@@ -5,6 +5,7 @@ Contact:	"Pavan Savoy" <pavan_savoy@ti.com>
 Description:
 		Name of the UART device at which the WL128x chip
 		is connected. example: "/dev/ttyS0".
+
 		The device name flows down to architecture specific board
 		initialization file from the SFI/ATAGS bootloader
 		firmware. The name exposed is read from the user-space
diff --git a/Documentation/ABI/testing/sysfs-platform-phy-rcar-gen3-usb2 b/Documentation/ABI/testing/sysfs-platform-phy-rcar-gen3-usb2
index 6212697bbf6f..bc510ccc37a7 100644
--- a/Documentation/ABI/testing/sysfs-platform-phy-rcar-gen3-usb2
+++ b/Documentation/ABI/testing/sysfs-platform-phy-rcar-gen3-usb2
@@ -7,9 +7,11 @@ Description:
 		The file can show/change the phy mode for role swap of usb.
 
 		Write the following strings to change the mode:
-		 "host" - switching mode from peripheral to host.
-		 "peripheral" - switching mode from host to peripheral.
+
+		 - "host" - switching mode from peripheral to host.
+		 - "peripheral" - switching mode from host to peripheral.
 
 		Read the file, then it shows the following strings:
-		 "host" - The mode is host now.
-		 "peripheral" - The mode is peripheral now.
+
+		 - "host" - The mode is host now.
+		 - "peripheral" - The mode is peripheral now.
diff --git a/Documentation/ABI/testing/sysfs-platform-renesas_usb3 b/Documentation/ABI/testing/sysfs-platform-renesas_usb3
index 5621c15d5dc0..8af5b9c3fabb 100644
--- a/Documentation/ABI/testing/sysfs-platform-renesas_usb3
+++ b/Documentation/ABI/testing/sysfs-platform-renesas_usb3
@@ -7,9 +7,11 @@ Description:
 		The file can show/change the drd mode of usb.
 
 		Write the following string to change the mode:
-		 "host" - switching mode from peripheral to host.
-		 "peripheral" - switching mode from host to peripheral.
+
+		- "host" - switching mode from peripheral to host.
+		- "peripheral" - switching mode from host to peripheral.
 
 		Read the file, then it shows the following strings:
-		 "host" - The mode is host now.
-		 "peripheral" - The mode is peripheral now.
+		
+		- "host" - The mode is host now.
+		- "peripheral" - The mode is peripheral now.
diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/testing/sysfs-power
index 5e6ead29124c..51c0f578bfce 100644
--- a/Documentation/ABI/testing/sysfs-power
+++ b/Documentation/ABI/testing/sysfs-power
@@ -47,14 +47,18 @@ Description:
 		suspend-to-disk mechanism.  Reading from this file returns
 		the name of the method by which the system will be put to
 		sleep on the next suspend.  There are four methods supported:
+
 		'firmware' - means that the memory image will be saved to disk
 		by some firmware, in which case we also assume that the
 		firmware will handle the system suspend.
+
 		'platform' - the memory image will be saved by the kernel and
 		the system will be put to sleep by the platform driver (e.g.
 		ACPI or other PM registers).
+
 		'shutdown' - the memory image will be saved by the kernel and
 		the system will be powered off.
+
 		'reboot' - the memory image will be saved by the kernel and
 		the system will be rebooted.
 
@@ -74,12 +78,12 @@ Description:
 		The suspend-to-disk method may be chosen by writing to this
 		file one of the accepted strings:
 
-		'firmware'
-		'platform'
-		'shutdown'
-		'reboot'
-		'testproc'
-		'test'
+		- 'firmware'
+		- 'platform'
+		- 'shutdown'
+		- 'reboot'
+		- 'testproc'
+		- 'test'
 
 		It will only change to 'firmware' or 'platform' if the system
 		supports that.
@@ -114,9 +118,9 @@ Description:
 		string representing a nonzero integer into it.
 
 		To use this debugging feature you should attempt to suspend
-		the machine, then reboot it and run
+		the machine, then reboot it and run::
 
-		dmesg -s 1000000 | grep 'hash matches'
+		  dmesg -s 1000000 | grep 'hash matches'
 
 		If you do not get any matches (or they appear to be false
 		positives), it is possible that the last PM event point
@@ -244,6 +248,7 @@ Description:
 		wakeup sources created with the help of /sys/power/wake_lock.
 		When a string is written to /sys/power/wake_unlock, it will be
 		assumed to represent the name of a wakeup source to deactivate.
+
 		If a wakeup source object of that name exists and is active at
 		the moment, it will be deactivated.
 
diff --git a/Documentation/ABI/testing/sysfs-profiling b/Documentation/ABI/testing/sysfs-profiling
index 8a8e466eb2c0..e39dd3a0ceef 100644
--- a/Documentation/ABI/testing/sysfs-profiling
+++ b/Documentation/ABI/testing/sysfs-profiling
@@ -5,7 +5,7 @@ Description:
 		/sys/kernel/profiling is the runtime equivalent
 		of the boot-time profile= option.
 
-		You can get the same effect running:
+		You can get the same effect running::
 
 			echo 2 > /sys/kernel/profiling
 
diff --git a/Documentation/ABI/testing/sysfs-wusb_cbaf b/Documentation/ABI/testing/sysfs-wusb_cbaf
index a99c5f86a37a..2969d3694ec0 100644
--- a/Documentation/ABI/testing/sysfs-wusb_cbaf
+++ b/Documentation/ABI/testing/sysfs-wusb_cbaf
@@ -45,7 +45,8 @@ Description:
                 7. Device is unplugged.
 
                 References:
-                  [WUSB-AM] Association Models Supplement to the
+                  [WUSB-AM]
+			    Association Models Supplement to the
                             Certified Wireless Universal Serial Bus
                             Specification, version 1.0.
 
diff --git a/Documentation/ABI/testing/usb-charger-uevent b/Documentation/ABI/testing/usb-charger-uevent
index 419a92dd0d86..1db89b0cf80f 100644
--- a/Documentation/ABI/testing/usb-charger-uevent
+++ b/Documentation/ABI/testing/usb-charger-uevent
@@ -3,44 +3,52 @@ Date:		2020-01-14
 KernelVersion:	5.6
 Contact:	linux-usb@vger.kernel.org
 Description:	There are two USB charger states:
-		USB_CHARGER_ABSENT
-		USB_CHARGER_PRESENT
+
+		- USB_CHARGER_ABSENT
+		- USB_CHARGER_PRESENT
+
 		There are five USB charger types:
-		USB_CHARGER_UNKNOWN_TYPE: Charger type is unknown
-		USB_CHARGER_SDP_TYPE: Standard Downstream Port
-		USB_CHARGER_CDP_TYPE: Charging Downstream Port
-		USB_CHARGER_DCP_TYPE: Dedicated Charging Port
-		USB_CHARGER_ACA_TYPE: Accessory Charging Adapter
+
+		========================  ==========================
+		USB_CHARGER_UNKNOWN_TYPE  Charger type is unknown
+		USB_CHARGER_SDP_TYPE      Standard Downstream Port
+		USB_CHARGER_CDP_TYPE      Charging Downstream Port
+		USB_CHARGER_DCP_TYPE      Dedicated Charging Port
+		USB_CHARGER_ACA_TYPE      Accessory Charging Adapter
+		========================  ==========================
+
 		https://www.usb.org/document-library/battery-charging-v12-spec-and-adopters-agreement
 
-		Here are two examples taken using udevadm monitor -p when
-		USB charger is online:
-		UDEV  change   /devices/soc0/usbphynop1 (platform)
-		ACTION=change
-		DEVPATH=/devices/soc0/usbphynop1
-		DRIVER=usb_phy_generic
-		MODALIAS=of:Nusbphynop1T(null)Cusb-nop-xceiv
-		OF_COMPATIBLE_0=usb-nop-xceiv
-		OF_COMPATIBLE_N=1
-		OF_FULLNAME=/usbphynop1
-		OF_NAME=usbphynop1
-		SEQNUM=2493
-		SUBSYSTEM=platform
-		USB_CHARGER_STATE=USB_CHARGER_PRESENT
-		USB_CHARGER_TYPE=USB_CHARGER_SDP_TYPE
-		USEC_INITIALIZED=227422826
+		Here are two examples taken using ``udevadm monitor -p`` when
+		USB charger is online::
 
-		USB charger is offline:
-		KERNEL change   /devices/soc0/usbphynop1 (platform)
-		ACTION=change
-		DEVPATH=/devices/soc0/usbphynop1
-		DRIVER=usb_phy_generic
-		MODALIAS=of:Nusbphynop1T(null)Cusb-nop-xceiv
-		OF_COMPATIBLE_0=usb-nop-xceiv
-		OF_COMPATIBLE_N=1
-		OF_FULLNAME=/usbphynop1
-		OF_NAME=usbphynop1
-		SEQNUM=2494
-		SUBSYSTEM=platform
-		USB_CHARGER_STATE=USB_CHARGER_ABSENT
-		USB_CHARGER_TYPE=USB_CHARGER_UNKNOWN_TYPE
+		    UDEV  change   /devices/soc0/usbphynop1 (platform)
+		    ACTION=change
+		    DEVPATH=/devices/soc0/usbphynop1
+		    DRIVER=usb_phy_generic
+		    MODALIAS=of:Nusbphynop1T(null)Cusb-nop-xceiv
+		    OF_COMPATIBLE_0=usb-nop-xceiv
+		    OF_COMPATIBLE_N=1
+		    OF_FULLNAME=/usbphynop1
+		    OF_NAME=usbphynop1
+		    SEQNUM=2493
+		    SUBSYSTEM=platform
+		    USB_CHARGER_STATE=USB_CHARGER_PRESENT
+		    USB_CHARGER_TYPE=USB_CHARGER_SDP_TYPE
+		    USEC_INITIALIZED=227422826
+
+		USB charger is offline::
+
+		    KERNEL change   /devices/soc0/usbphynop1 (platform)
+		    ACTION=change
+		    DEVPATH=/devices/soc0/usbphynop1
+		    DRIVER=usb_phy_generic
+		    MODALIAS=of:Nusbphynop1T(null)Cusb-nop-xceiv
+		    OF_COMPATIBLE_0=usb-nop-xceiv
+		    OF_COMPATIBLE_N=1
+		    OF_FULLNAME=/usbphynop1
+		    OF_NAME=usbphynop1
+		    SEQNUM=2494
+		    SUBSYSTEM=platform
+		    USB_CHARGER_STATE=USB_CHARGER_ABSENT
+		    USB_CHARGER_TYPE=USB_CHARGER_UNKNOWN_TYPE
diff --git a/Documentation/ABI/testing/usb-uevent b/Documentation/ABI/testing/usb-uevent
index d35c3cad892c..2b8eca4bf2b1 100644
--- a/Documentation/ABI/testing/usb-uevent
+++ b/Documentation/ABI/testing/usb-uevent
@@ -6,22 +6,22 @@ Description:	When the USB Host Controller has entered a state where it is no
 		longer functional a uevent will be raised. The uevent will
 		contain ACTION=offline and ERROR=DEAD.
 
-		Here is an example taken using udevadm monitor -p:
+		Here is an example taken using udevadm monitor -p::
 
-		KERNEL[130.428945] offline  /devices/pci0000:00/0000:00:10.0/usb2 (usb)
-		ACTION=offline
-		BUSNUM=002
-		DEVNAME=/dev/bus/usb/002/001
-		DEVNUM=001
-		DEVPATH=/devices/pci0000:00/0000:00:10.0/usb2
-		DEVTYPE=usb_device
-		DRIVER=usb
-		ERROR=DEAD
-		MAJOR=189
-		MINOR=128
-		PRODUCT=1d6b/2/414
-		SEQNUM=2168
-		SUBSYSTEM=usb
-		TYPE=9/0/1
+		    KERNEL[130.428945] offline  /devices/pci0000:00/0000:00:10.0/usb2 (usb)
+		    ACTION=offline
+		    BUSNUM=002
+		    DEVNAME=/dev/bus/usb/002/001
+		    DEVNUM=001
+		    DEVPATH=/devices/pci0000:00/0000:00:10.0/usb2
+		    DEVTYPE=usb_device
+		    DRIVER=usb
+		    ERROR=DEAD
+		    MAJOR=189
+		    MINOR=128
+		    PRODUCT=1d6b/2/414
+		    SEQNUM=2168
+		    SUBSYSTEM=usb
+		    TYPE=9/0/1
 
 Users:		chromium-os-dev@chromium.org
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index f6adf4b38a2b..d09bb37dd236 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -316,8 +316,6 @@ sub output_rest {
 				$len = length($name) if (length($name) > $len);
 			}
 
-			print "What:\n\n";
-
 			print "+-" . "-" x $len . "-+\n";
 			foreach my $name (@names) {
 				printf "| %s", $name . " " x ($len - length($name)) . " |\n";
-- 
2.26.2

[PATCH v2 32/39] docs: ABI: change read/write attributes

[Mauro Carvalho Chehab]

Unfortunately, (R) and (W) are valid markups for enumerated
lists, as described at:
	https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#enumerated-lists

So, we ned to replace them by:

	(R) -> (Read)
	(W) -> (Write)

As otherwise, (R) will be displayed as R., with is not what
it is desired.

There's no need to touch (RO) and (RW).

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/testing/debugfs-moxtet      |  2 +-
 .../ABI/testing/debugfs-turris-mox-rwtm       | 15 ++--
 .../testing/sysfs-bus-coresight-devices-cti   | 60 +++++++--------
 .../testing/sysfs-bus-coresight-devices-etb10 | 16 ++--
 .../testing/sysfs-bus-coresight-devices-etm3x | 10 +--
 .../testing/sysfs-bus-coresight-devices-etm4x | 76 +++++++++----------
 .../testing/sysfs-bus-coresight-devices-stm   |  2 +-
 .../testing/sysfs-bus-coresight-devices-tmc   | 20 ++---
 .../ABI/testing/sysfs-bus-moxtet-devices      |  6 +-
 .../testing/sysfs-firmware-turris-mox-rwtm    | 10 +--
 10 files changed, 109 insertions(+), 108 deletions(-)

diff --git a/Documentation/ABI/testing/debugfs-moxtet b/Documentation/ABI/testing/debugfs-moxtet
index 15dfaecb2892..6eee10c3d5a1 100644
--- a/Documentation/ABI/testing/debugfs-moxtet
+++ b/Documentation/ABI/testing/debugfs-moxtet
@@ -2,7 +2,7 @@ What:		/sys/kernel/debug/moxtet/input
 Date:		March 2019
 KernelVersion:	5.3
 Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) Read input from the shift registers, in hexadecimal.
+Description:	(Read) Read input from the shift registers, in hexadecimal.
 		Returns N+1 bytes, where N is the number of Moxtet connected
 		modules. The first byte is from the CPU board itself.
 
diff --git a/Documentation/ABI/testing/debugfs-turris-mox-rwtm b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
index ad08f535af3b..326df1b74707 100644
--- a/Documentation/ABI/testing/debugfs-turris-mox-rwtm
+++ b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
@@ -4,10 +4,11 @@ KernelVersion:	5.8
 Contact:	Marek Behún <marek.behun@nic.cz>
 Description:
 
-		=== ===========================================================
-		(W) Message to sign with the ECDSA private key stored in
-		    device's OTP. The message must be exactly 64 bytes (since
-		    this is intended for SHA-512 hashes).
-		(R) The resulting signature, 136 bytes. This contains the R and
-		    S values of the ECDSA signature, both in big-endian format.
-		=== ===========================================================
+		======= ===========================================================
+		(Write) Message to sign with the ECDSA private key stored in
+		        device's OTP. The message must be exactly 64 bytes
+		        (since this is intended for SHA-512 hashes).
+		(Read)  The resulting signature, 136 bytes. This contains the
+			R and S values of the ECDSA signature, both in
+			big-endian format.
+		======= ===========================================================
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti b/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti
index 9d11502b4390..bf2869c413e7 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-cti
@@ -8,50 +8,50 @@ What:		/sys/bus/coresight/devices/<cti-name>/powered
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) Indicate if the CTI hardware is powered.
+Description:	(Read) Indicate if the CTI hardware is powered.
 
 What:		/sys/bus/coresight/devices/<cti-name>/ctmid
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) Display the associated CTM ID
+Description:	(Read) Display the associated CTM ID
 
 What:		/sys/bus/coresight/devices/<cti-name>/nr_trigger_cons
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) Number of devices connected to triggers on this CTI
+Description:	(Read) Number of devices connected to triggers on this CTI
 
 What:		/sys/bus/coresight/devices/<cti-name>/triggers<N>/name
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) Name of connected device <N>
+Description:	(Read) Name of connected device <N>
 
 What:		/sys/bus/coresight/devices/<cti-name>/triggers<N>/in_signals
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) Input trigger signals from connected device <N>
+Description:	(Read) Input trigger signals from connected device <N>
 
 What:		/sys/bus/coresight/devices/<cti-name>/triggers<N>/in_types
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) Functional types for the input trigger signals
+Description:	(Read) Functional types for the input trigger signals
 		from connected device <N>
 
 What:		/sys/bus/coresight/devices/<cti-name>/triggers<N>/out_signals
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) Output trigger signals to connected device <N>
+Description:	(Read) Output trigger signals to connected device <N>
 
 What:		/sys/bus/coresight/devices/<cti-name>/triggers<N>/out_types
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) Functional types for the output trigger signals
+Description:	(Read) Functional types for the output trigger signals
 		to connected device <N>
 
 What:		/sys/bus/coresight/devices/<cti-name>/regs/inout_sel
@@ -88,7 +88,7 @@ What:		/sys/bus/coresight/devices/<cti-name>/regs/intack
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(W) Write the INTACK register.
+Description:	(Write) Write the INTACK register.
 
 What:		/sys/bus/coresight/devices/<cti-name>/regs/appset
 Date:		March 2020
@@ -101,99 +101,99 @@ What:		/sys/bus/coresight/devices/<cti-name>/regs/appclear
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(W) Write APPCLEAR register to deactivate channel.
+Description:	(Write) Write APPCLEAR register to deactivate channel.
 
 What:		/sys/bus/coresight/devices/<cti-name>/regs/apppulse
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(W) Write APPPULSE to pulse a channel active for one clock
+Description:	(Write) Write APPPULSE to pulse a channel active for one clock
 		cycle.
 
 What:		/sys/bus/coresight/devices/<cti-name>/regs/chinstatus
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) Read current status of channel inputs.
+Description:	(Read) Read current status of channel inputs.
 
 What:		/sys/bus/coresight/devices/<cti-name>/regs/choutstatus
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) read current status of channel outputs.
+Description:	(Read) read current status of channel outputs.
 
 What:		/sys/bus/coresight/devices/<cti-name>/regs/triginstatus
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) read current status of input trigger signals
+Description:	(Read) read current status of input trigger signals
 
 What:		/sys/bus/coresight/devices/<cti-name>/regs/trigoutstatus
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) read current status of output trigger signals.
+Description:	(Read) read current status of output trigger signals.
 
 What:		/sys/bus/coresight/devices/<cti-name>/channels/trigin_attach
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(W) Attach a CTI input trigger to a CTM channel.
+Description:	(Write) Attach a CTI input trigger to a CTM channel.
 
 What:		/sys/bus/coresight/devices/<cti-name>/channels/trigin_detach
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(W) Detach a CTI input trigger from a CTM channel.
+Description:	(Write) Detach a CTI input trigger from a CTM channel.
 
 What:		/sys/bus/coresight/devices/<cti-name>/channels/trigout_attach
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(W) Attach a CTI output trigger to a CTM channel.
+Description:	(Write) Attach a CTI output trigger to a CTM channel.
 
 What:		/sys/bus/coresight/devices/<cti-name>/channels/trigout_detach
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(W) Detach a CTI output trigger from a CTM channel.
+Description:	(Write) Detach a CTI output trigger from a CTM channel.
 
 What:		/sys/bus/coresight/devices/<cti-name>/channels/chan_gate_enable
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(RW) Enable CTIGATE for single channel (W) or list enabled
+Description:	(RW) Enable CTIGATE for single channel (Write) or list enabled
 		channels through the gate (R).
 
 What:		/sys/bus/coresight/devices/<cti-name>/channels/chan_gate_disable
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(W) Disable CTIGATE for single channel.
+Description:	(Write) Disable CTIGATE for single channel.
 
 What:		/sys/bus/coresight/devices/<cti-name>/channels/chan_set
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(W) Activate a single channel.
+Description:	(Write) Activate a single channel.
 
 What:		/sys/bus/coresight/devices/<cti-name>/channels/chan_clear
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(W) Deactivate a single channel.
+Description:	(Write) Deactivate a single channel.
 
 What:		/sys/bus/coresight/devices/<cti-name>/channels/chan_pulse
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(W) Pulse a single channel - activate for a single clock cycle.
+Description:	(Write) Pulse a single channel - activate for a single clock cycle.
 
 What:		/sys/bus/coresight/devices/<cti-name>/channels/trigout_filtered
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) List of output triggers filtered across all connections.
+Description:	(Read) List of output triggers filtered across all connections.
 
 What:		/sys/bus/coresight/devices/<cti-name>/channels/trig_filter_enable
 Date:		March 2020
@@ -205,13 +205,13 @@ What:		/sys/bus/coresight/devices/<cti-name>/channels/chan_inuse
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) show channels with at least one attached trigger signal.
+Description:	(Read) show channels with at least one attached trigger signal.
 
 What:		/sys/bus/coresight/devices/<cti-name>/channels/chan_free
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) show channels with no attached trigger signals.
+Description:	(Read) show channels with no attached trigger signals.
 
 What:		/sys/bus/coresight/devices/<cti-name>/channels/chan_xtrigs_sel
 Date:		March 2020
@@ -224,18 +224,18 @@ What:		/sys/bus/coresight/devices/<cti-name>/channels/chan_xtrigs_in
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) Read to see input triggers connected to selected view
+Description:	(Read) Read to see input triggers connected to selected view
 		channel.
 
 What:		/sys/bus/coresight/devices/<cti-name>/channels/chan_xtrigs_out
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(R) Read to see output triggers connected to selected view
+Description:	(Read) Read to see output triggers connected to selected view
 		channel.
 
 What:		/sys/bus/coresight/devices/<cti-name>/channels/chan_xtrigs_reset
 Date:		March 2020
 KernelVersion	5.7
 Contact:	Mike Leach or Mathieu Poirier
-Description:	(W) Clear all channel / trigger programming.
+Description:	(Write) Clear all channel / trigger programming.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10 b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10
index 3e92cbd3fd83..9a383f6a74eb 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etb10
@@ -23,21 +23,21 @@ What:		/sys/bus/coresight/devices/<memory_map>.etb/mgmt/rdp
 Date:		March 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Defines the depth, in words, of the trace RAM in powers of
+Description:	(Read) Defines the depth, in words, of the trace RAM in powers of
 		2.  The value is read directly from HW register RDP, 0x004.
 
 What:		/sys/bus/coresight/devices/<memory_map>.etb/mgmt/sts
 Date:		March 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Shows the value held by the ETB status register.  The value
+Description:	(Read) Shows the value held by the ETB status register.  The value
 		is read directly from HW register STS, 0x00C.
 
 What:		/sys/bus/coresight/devices/<memory_map>.etb/mgmt/rrp
 Date:		March 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Shows the value held by the ETB RAM Read Pointer register
+Description:	(Read) Shows the value held by the ETB RAM Read Pointer register
 		that is used to read entries from the Trace RAM over the APB
 		interface.  The value is read directly from HW register RRP,
 		0x014.
@@ -46,7 +46,7 @@ What:		/sys/bus/coresight/devices/<memory_map>.etb/mgmt/rwp
 Date:		March 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Shows the value held by the ETB RAM Write Pointer register
+Description:	(Read) Shows the value held by the ETB RAM Write Pointer register
 		that is used to sets the write pointer to write entries from
 		the CoreSight bus into the Trace RAM. The value is read directly
 		from HW register RWP, 0x018.
@@ -55,21 +55,21 @@ What:		/sys/bus/coresight/devices/<memory_map>.etb/mgmt/trg
 Date:		March 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Similar to "trigger_cntr" above except that this value is
+Description:	(Read) Similar to "trigger_cntr" above except that this value is
 		read directly from HW register TRG, 0x01C.
 
 What:		/sys/bus/coresight/devices/<memory_map>.etb/mgmt/ctl
 Date:		March 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Shows the value held by the ETB Control register. The value
+Description:	(Read) Shows the value held by the ETB Control register. The value
 		is read directly from HW register CTL, 0x020.
 
 What:		/sys/bus/coresight/devices/<memory_map>.etb/mgmt/ffsr
 Date:		March 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Shows the value held by the ETB Formatter and Flush Status
+Description:	(Read) Shows the value held by the ETB Formatter and Flush Status
 		register.  The value is read directly from HW register FFSR,
 		0x300.
 
@@ -77,6 +77,6 @@ What:		/sys/bus/coresight/devices/<memory_map>.etb/mgmt/ffcr
 Date:		March 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Shows the value held by the ETB Formatter and Flush Control
+Description:	(Read) Shows the value held by the ETB Formatter and Flush Control
 		register.  The value is read directly from HW register FFCR,
 		0x304.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x
index 924265a1295d..651602a61eac 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm3x
@@ -146,28 +146,28 @@ What:		/sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_addr_cmp
 Date:		November 2014
 KernelVersion:	3.19
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description: 	(R) Provides the number of address comparators pairs accessible
+Description: 	(Read) Provides the number of address comparators pairs accessible
 		on a trace unit, as specified by bit 3:0 of register ETMCCR.
 
 What:		/sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_cntr
 Date:		November 2014
 KernelVersion:	3.19
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description: 	(R) Provides the number of counters accessible on a trace unit,
+Description: 	(Read) Provides the number of counters accessible on a trace unit,
 		as specified by bit 15:13 of register ETMCCR.
 
 What:		/sys/bus/coresight/devices/<memory_map>.[etm|ptm]/nr_ctxid_cmp
 Date:		November 2014
 KernelVersion:	3.19
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description: 	(R) Provides the number of context ID comparator available on a
+Description: 	(Read) Provides the number of context ID comparator available on a
 		trace unit, as specified by bit 25:24 of register ETMCCR.
 
 What:		/sys/bus/coresight/devices/<memory_map>.[etm|ptm]/reset
 Date:		November 2014
 KernelVersion:	3.19
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description: 	(W) Cancels all configuration on a trace unit and set it back
+Description: 	(Write) Cancels all configuration on a trace unit and set it back
 		to its boot configuration.
 
 What:		/sys/bus/coresight/devices/<memory_map>.[etm|ptm]/seq_12_event
@@ -216,7 +216,7 @@ What:		/sys/bus/coresight/devices/<memory_map>.[etm|ptm]/curr_seq_state
 Date:		November 2014
 KernelVersion:	3.19
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description: 	(R) Holds the current state of the sequencer.
+Description: 	(Read) Holds the current state of the sequencer.
 
 What:		/sys/bus/coresight/devices/<memory_map>.[etm|ptm]/sync_freq
 Date:		November 2014
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x
index 614874e2cf53..881f0cd99ce4 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-etm4x
@@ -12,75 +12,75 @@ What:		/sys/bus/coresight/devices/etm<N>/cpu
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) The CPU this tracing entity is associated with.
+Description:	(Read) The CPU this tracing entity is associated with.
 
 What:		/sys/bus/coresight/devices/etm<N>/nr_pe_cmp
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Indicates the number of PE comparator inputs that are
+Description:	(Read) Indicates the number of PE comparator inputs that are
 		available for tracing.
 
 What:		/sys/bus/coresight/devices/etm<N>/nr_addr_cmp
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Indicates the number of address comparator pairs that are
+Description:	(Read) Indicates the number of address comparator pairs that are
 		available for tracing.
 
 What:		/sys/bus/coresight/devices/etm<N>/nr_cntr
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Indicates the number of counters that are available for
+Description:	(Read) Indicates the number of counters that are available for
 		tracing.
 
 What:		/sys/bus/coresight/devices/etm<N>/nr_ext_inp
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Indicates how many external inputs are implemented.
+Description:	(Read) Indicates how many external inputs are implemented.
 
 What:		/sys/bus/coresight/devices/etm<N>/numcidc
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Indicates the number of Context ID comparators that are
+Description:	(Read) Indicates the number of Context ID comparators that are
 		available for tracing.
 
 What:		/sys/bus/coresight/devices/etm<N>/numvmidc
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Indicates the number of VMID comparators that are available
+Description:	(Read) Indicates the number of VMID comparators that are available
 		for tracing.
 
 What:		/sys/bus/coresight/devices/etm<N>/nrseqstate
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Indicates the number of sequencer states that are
+Description:	(Read) Indicates the number of sequencer states that are
 		implemented.
 
 What:		/sys/bus/coresight/devices/etm<N>/nr_resource
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Indicates the number of resource selection pairs that are
+Description:	(Read) Indicates the number of resource selection pairs that are
 		available for tracing.
 
 What:		/sys/bus/coresight/devices/etm<N>/nr_ss_cmp
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Indicates the number of single-shot comparator controls that
+Description:	(Read) Indicates the number of single-shot comparator controls that
 		are available for tracing.
 
 What:		/sys/bus/coresight/devices/etm<N>/reset
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description: 	(W) Cancels all configuration on a trace unit and set it back
+Description: 	(Write) Cancels all configuration on a trace unit and set it back
 		to its boot configuration.
 
 What:		/sys/bus/coresight/devices/etm<N>/mode
@@ -300,7 +300,7 @@ What:		/sys/bus/coresight/devices/etm<N>/addr_cmp_view
 Date:		December 2019
 KernelVersion:	5.5
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the current settings for the selected address
+Description:	(Read) Print the current settings for the selected address
 		comparator.
 
 What:		/sys/bus/coresight/devices/etm<N>/sshot_idx
@@ -319,7 +319,7 @@ What:		/sys/bus/coresight/devices/etm<N>/sshot_status
 Date:		December 2019
 KernelVersion:	5.5
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the current value of the selected single shot
+Description:	(Read) Print the current value of the selected single shot
 		status register.
 
 What:		/sys/bus/coresight/devices/etm<N>/sshot_pe_ctrl
@@ -333,111 +333,111 @@ What:		/sys/bus/coresight/devices/etm<N>/mgmt/trcoslsr
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the content of the OS Lock Status Register (0x304).
+Description:	(Read) Print the content of the OS Lock Status Register (0x304).
 		The value it taken directly  from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/mgmt/trcpdcr
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the content of the Power Down Control Register
+Description:	(Read) Print the content of the Power Down Control Register
 		(0x310).  The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/mgmt/trcpdsr
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the content of the Power Down Status Register
+Description:	(Read) Print the content of the Power Down Status Register
 		(0x314).  The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/mgmt/trclsr
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the content of the SW Lock Status Register
+Description:	(Read) Print the content of the SW Lock Status Register
 		(0xFB4).  The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/mgmt/trcauthstatus
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the content of the Authentication Status Register
+Description:	(Read) Print the content of the Authentication Status Register
 		(0xFB8).  The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/mgmt/trcdevid
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the content of the Device ID Register
+Description:	(Read) Print the content of the Device ID Register
 		(0xFC8).  The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/mgmt/trcdevtype
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the content of the Device Type Register
+Description:	(Read) Print the content of the Device Type Register
 		(0xFCC).  The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/mgmt/trcpidr0
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the content of the Peripheral ID0 Register
+Description:	(Read) Print the content of the Peripheral ID0 Register
 		(0xFE0).  The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/mgmt/trcpidr1
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the content of the Peripheral ID1 Register
+Description:	(Read) Print the content of the Peripheral ID1 Register
 		(0xFE4).  The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/mgmt/trcpidr2
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the content of the Peripheral ID2 Register
+Description:	(Read) Print the content of the Peripheral ID2 Register
 		(0xFE8).  The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/mgmt/trcpidr3
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the content of the Peripheral ID3 Register
+Description:	(Read) Print the content of the Peripheral ID3 Register
 		(0xFEC).  The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/mgmt/trcconfig
 Date:		February 2016
 KernelVersion:	4.07
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the content of the trace configuration register
+Description:	(Read) Print the content of the trace configuration register
 		(0x010) as currently set by SW.
 
 What:		/sys/bus/coresight/devices/etm<N>/mgmt/trctraceid
 Date:		February 2016
 KernelVersion:	4.07
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Print the content of the trace ID register (0x040).
+Description:	(Read) Print the content of the trace ID register (0x040).
 
 What:		/sys/bus/coresight/devices/etm<N>/trcidr/trcidr0
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Returns the tracing capabilities of the trace unit (0x1E0).
+Description:	(Read) Returns the tracing capabilities of the trace unit (0x1E0).
 		The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/trcidr/trcidr1
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Returns the tracing capabilities of the trace unit (0x1E4).
+Description:	(Read) Returns the tracing capabilities of the trace unit (0x1E4).
 		The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/trcidr/trcidr2
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Returns the maximum size of the data value, data address,
+Description:	(Read) Returns the maximum size of the data value, data address,
 		VMID, context ID and instuction address in the trace unit
 		(0x1E8).  The value is taken directly from the HW.
 
@@ -445,7 +445,7 @@ What:		/sys/bus/coresight/devices/etm<N>/trcidr/trcidr3
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Returns the value associated with various resources
+Description:	(Read) Returns the value associated with various resources
 		available to the trace unit.  See the Trace Macrocell
 		architecture specification for more details (0x1E8).
 		The value is taken directly from the HW.
@@ -454,42 +454,42 @@ What:		/sys/bus/coresight/devices/etm<N>/trcidr/trcidr4
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Returns how many resources the trace unit supports (0x1F0).
+Description:	(Read) Returns how many resources the trace unit supports (0x1F0).
 		The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/trcidr/trcidr5
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Returns how many resources the trace unit supports (0x1F4).
+Description:	(Read) Returns how many resources the trace unit supports (0x1F4).
 		The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/trcidr/trcidr8
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Returns the maximum speculation depth of the instruction
+Description:	(Read) Returns the maximum speculation depth of the instruction
 		trace stream. (0x180).  The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/trcidr/trcidr9
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Returns the number of P0 right-hand keys that the trace unit
+Description:	(Read) Returns the number of P0 right-hand keys that the trace unit
 		can use (0x184).  The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/trcidr/trcidr10
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Returns the number of P1 right-hand keys that the trace unit
+Description:	(Read) Returns the number of P1 right-hand keys that the trace unit
 		can use (0x188).  The value is taken directly from the HW.
 
 What:		/sys/bus/coresight/devices/etm<N>/trcidr/trcidr11
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Returns the number of special P1 right-hand keys that the
+Description:	(Read) Returns the number of special P1 right-hand keys that the
 		trace unit can use (0x18C).  The value is taken directly from
 		the HW.
 
@@ -497,7 +497,7 @@ What:		/sys/bus/coresight/devices/etm<N>/trcidr/trcidr12
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Returns the number of conditional P1 right-hand keys that
+Description:	(Read) Returns the number of conditional P1 right-hand keys that
 		the trace unit can use (0x190).  The value is taken directly
 		from the HW.
 
@@ -505,6 +505,6 @@ What:		/sys/bus/coresight/devices/etm<N>/trcidr/trcidr13
 Date:		April 2015
 KernelVersion:	4.01
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Returns the number of special conditional P1 right-hand keys
+Description:	(Read) Returns the number of special conditional P1 right-hand keys
 		that the trace unit can use (0x194).  The value is taken
 		directly from the HW.
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm b/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
index 1dffabe7f48d..53e1f4815d64 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-stm
@@ -42,7 +42,7 @@ What:		/sys/bus/coresight/devices/<memory_map>.stm/status
 Date:		April 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) List various control and status registers.  The specific
+Description:	(Read) List various control and status registers.  The specific
 		layout and content is driver specific.
 
 What:		/sys/bus/coresight/devices/<memory_map>.stm/traceid
diff --git a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc
index ab49b9ac3bcb..6aa527296c71 100644
--- a/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc
+++ b/Documentation/ABI/testing/sysfs-bus-coresight-devices-tmc
@@ -11,21 +11,21 @@ What:           /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/rsz
 Date:           March 2016
 KernelVersion:  4.7
 Contact:        Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:    (R) Defines the size, in 32-bit words, of the local RAM buffer.
+Description:    (Read) Defines the size, in 32-bit words, of the local RAM buffer.
                 The value is read directly from HW register RSZ, 0x004.
 
 What:           /sys/bus/coresight/devices/<memory_map>.tmc/mgmt/sts
 Date:           March 2016
 KernelVersion:  4.7
 Contact:        Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Shows the value held by the TMC status register.  The value
+Description:	(Read) Shows the value held by the TMC status register.  The value
                 is read directly from HW register STS, 0x00C.
 
 What:		/sys/bus/coresight/devices/<memory_map>.tmc/mgmt/rrp
 Date:		March 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Shows the value held by the TMC RAM Read Pointer register
+Description:	(Read) Shows the value held by the TMC RAM Read Pointer register
 		that is used to read entries from the Trace RAM over the APB
 		interface.  The value is read directly from HW register RRP,
 		0x014.
@@ -34,7 +34,7 @@ What:		/sys/bus/coresight/devices/<memory_map>.tmc/mgmt/rwp
 Date:		March 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Shows the value held by the TMC RAM Write Pointer register
+Description:	(Read) Shows the value held by the TMC RAM Write Pointer register
 		that is used to sets the write pointer to write entries from
 		the CoreSight bus into the Trace RAM. The value is read directly
 		from HW register RWP, 0x018.
@@ -43,21 +43,21 @@ What:		/sys/bus/coresight/devices/<memory_map>.tmc/mgmt/trg
 Date:		March 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Similar to "trigger_cntr" above except that this value is
+Description:	(Read) Similar to "trigger_cntr" above except that this value is
 		read directly from HW register TRG, 0x01C.
 
 What:		/sys/bus/coresight/devices/<memory_map>.tmc/mgmt/ctl
 Date:		March 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Shows the value held by the TMC Control register. The value
+Description:	(Read) Shows the value held by the TMC Control register. The value
 		is read directly from HW register CTL, 0x020.
 
 What:		/sys/bus/coresight/devices/<memory_map>.tmc/mgmt/ffsr
 Date:		March 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Shows the value held by the TMC Formatter and Flush Status
+Description:	(Read) Shows the value held by the TMC Formatter and Flush Status
 		register.  The value is read directly from HW register FFSR,
 		0x300.
 
@@ -65,7 +65,7 @@ What:		/sys/bus/coresight/devices/<memory_map>.tmc/mgmt/ffcr
 Date:		March 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Shows the value held by the TMC Formatter and Flush Control
+Description:	(Read) Shows the value held by the TMC Formatter and Flush Control
 		register.  The value is read directly from HW register FFCR,
 		0x304.
 
@@ -73,7 +73,7 @@ What:		/sys/bus/coresight/devices/<memory_map>.tmc/mgmt/mode
 Date:		March 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Shows the value held by the TMC Mode register, which
+Description:	(Read) Shows the value held by the TMC Mode register, which
 		indicate the mode the device has been configured to enact.  The
 		The value is read directly from the MODE register, 0x028.
 
@@ -81,7 +81,7 @@ What:		/sys/bus/coresight/devices/<memory_map>.tmc/mgmt/devid
 Date:		March 2016
 KernelVersion:	4.7
 Contact:	Mathieu Poirier <mathieu.poirier@linaro.org>
-Description:	(R) Indicates the capabilities of the Coresight TMC.
+Description:	(Read) Indicates the capabilities of the Coresight TMC.
 		The value is read directly from the DEVID register, 0xFC8,
 
 What:		/sys/bus/coresight/devices/<memory_map>.tmc/buffer_size
diff --git a/Documentation/ABI/testing/sysfs-bus-moxtet-devices b/Documentation/ABI/testing/sysfs-bus-moxtet-devices
index 355958527fa3..4a6d61b44f3f 100644
--- a/Documentation/ABI/testing/sysfs-bus-moxtet-devices
+++ b/Documentation/ABI/testing/sysfs-bus-moxtet-devices
@@ -2,16 +2,16 @@ What:		/sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_description
 Date:		March 2019
 KernelVersion:	5.3
 Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) Moxtet module description. Format: string
+Description:	(Read) Moxtet module description. Format: string
 
 What:		/sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_id
 Date:		March 2019
 KernelVersion:	5.3
 Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) Moxtet module ID. Format: %x
+Description:	(Read) Moxtet module ID. Format: %x
 
 What:		/sys/bus/moxtet/devices/moxtet-<name>.<addr>/module_name
 Date:		March 2019
 KernelVersion:	5.3
 Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) Moxtet module name. Format: string
+Description:	(Read) Moxtet module name. Format: string
diff --git a/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm b/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm
index 15595fab88d1..b8631f5a29c4 100644
--- a/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm
+++ b/Documentation/ABI/testing/sysfs-firmware-turris-mox-rwtm
@@ -2,21 +2,21 @@ What:		/sys/firmware/turris-mox-rwtm/board_version
 Date:		August 2019
 KernelVersion:	5.4
 Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) Board version burned into eFuses of this Turris Mox board.
+Description:	(Read) Board version burned into eFuses of this Turris Mox board.
 		Format: %i
 
 What:		/sys/firmware/turris-mox-rwtm/mac_address*
 Date:		August 2019
 KernelVersion:	5.4
 Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) MAC addresses burned into eFuses of this Turris Mox board.
+Description:	(Read) MAC addresses burned into eFuses of this Turris Mox board.
 		Format: %pM
 
 What:		/sys/firmware/turris-mox-rwtm/pubkey
 Date:		August 2019
 KernelVersion:	5.4
 Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) ECDSA public key (in pubkey hex compressed form) computed
+Description:	(Read) ECDSA public key (in pubkey hex compressed form) computed
 		as pair to the ECDSA private key burned into eFuses of this
 		Turris Mox Board.
 		Format: string
@@ -25,7 +25,7 @@ What:		/sys/firmware/turris-mox-rwtm/ram_size
 Date:		August 2019
 KernelVersion:	5.4
 Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) RAM size in MiB of this Turris Mox board as was detected
+Description:	(Read) RAM size in MiB of this Turris Mox board as was detected
 		during manufacturing and burned into eFuses. Can be 512 or 1024.
 		Format: %i
 
@@ -33,5 +33,5 @@ What:		/sys/firmware/turris-mox-rwtm/serial_number
 Date:		August 2019
 KernelVersion:	5.4
 Contact:	Marek Behún <marek.behun@nic.cz>
-Description:	(R) Serial number burned into eFuses of this Turris Mox device.
+Description:	(Read) Serial number burned into eFuses of this Turris Mox device.
 		Format: %016X
-- 
2.26.2

[PATCH v2 33/39] docs: ABI: stable: remove a duplicated documentation

[Mauro Carvalho Chehab]

Perhaps due to a wrong cut-and-paste, this entry:

	What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>/cpu

was added twice by the same patch, one following the other.

Remove the duplication.

Fixes: c2e5df616e1a ("vmbus: add per-channel sysfs info")
Acked-by: Wei Liu <wei.liu@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/stable/sysfs-bus-vmbus | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/Documentation/ABI/stable/sysfs-bus-vmbus b/Documentation/ABI/stable/sysfs-bus-vmbus
index 8e8d167eca31..c27b7b89477c 100644
--- a/Documentation/ABI/stable/sysfs-bus-vmbus
+++ b/Documentation/ABI/stable/sysfs-bus-vmbus
@@ -63,13 +63,6 @@ Contact:	Stephen Hemminger <sthemmin@microsoft.com>
 Description:	VCPU (sub)channel is affinitized to
 Users:		tools/hv/lsvmbus and other debugging tools
 
-What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>/cpu
-Date:		September. 2017
-KernelVersion:	4.14
-Contact:	Stephen Hemminger <sthemmin@microsoft.com>
-Description:	VCPU (sub)channel is affinitized to
-Users:		tools/hv/lsvmbus and other debugging tools
-
 What:		/sys/bus/vmbus/devices/<UUID>/channels/<N>/in_mask
 Date:		September. 2017
 KernelVersion:	4.14
-- 
2.26.2

[PATCH v2 34/39] docs: ABI: unify /sys/class/leds/<led>/brightness documentation

[Mauro Carvalho Chehab]

This ABI is defined twice, one for normal leds and another
one for multicolor ones.

Ensure that just one definition is there at ABI.

Acked-by: Pavel Machek <pavel@ucw.cz>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/testing/sysfs-class-led     | 25 ++++++++++++++++---
 .../ABI/testing/sysfs-class-led-multicolor    | 23 +++++------------
 2 files changed, 28 insertions(+), 20 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-class-led b/Documentation/ABI/testing/sysfs-class-led
index 0ed5c2629c6f..2e24ac3bd7ef 100644
--- a/Documentation/ABI/testing/sysfs-class-led
+++ b/Documentation/ABI/testing/sysfs-class-led
@@ -3,9 +3,26 @@ Date:		March 2006
 KernelVersion:	2.6.17
 Contact:	Richard Purdie <rpurdie@rpsys.net>
 Description:
-		Set the brightness of the LED. Most LEDs don't
-		have hardware brightness support, so will just be turned on for
-		non-zero brightness settings. The value is between 0 and
+		Set the brightness of the LED.
+
+		Most LEDs don't have hardware brightness support, so will
+		just be turned on for non-zero brightness settings.
+
+		.. Note::
+
+		  For multicolor LEDs, writing to this file will update all
+		  LEDs within the group to a calculated percentage of what
+		  each color LED intensity is set to.
+
+		  The percentage is calculated for each grouped LED via
+		  the equation below::
+
+		    led_brightness = brightness * multi_intensity/max_brightness
+
+		  For additional details please refer to
+		  Documentation/leds/leds-class-multicolor.rst.
+
+		The value is between 0 and
 		/sys/class/leds/<led>/max_brightness.
 
 		Writing 0 to this file clears active trigger.
@@ -13,6 +30,8 @@ Description:
 		Writing non-zero to this file while trigger is active changes the
 		top brightness trigger is going to use.
 
+
+
 What:		/sys/class/leds/<led>/max_brightness
 Date:		March 2006
 KernelVersion:	2.6.17
diff --git a/Documentation/ABI/testing/sysfs-class-led-multicolor b/Documentation/ABI/testing/sysfs-class-led-multicolor
index eeeddcbdbbe3..16fc827b10cb 100644
--- a/Documentation/ABI/testing/sysfs-class-led-multicolor
+++ b/Documentation/ABI/testing/sysfs-class-led-multicolor
@@ -1,20 +1,3 @@
-What:		/sys/class/leds/<led>/brightness
-Date:		March 2020
-KernelVersion:	5.9
-Contact:	Dan Murphy <dmurphy@ti.com>
-Description:	read/write
-		Writing to this file will update all LEDs within the group to a
-		calculated percentage of what each color LED intensity is set
-		to. The percentage is calculated for each grouped LED via the
-		equation below:
-
-		led_brightness = brightness * multi_intensity/max_brightness
-
-		For additional details please refer to
-		Documentation/leds/leds-class-multicolor.rst.
-
-		The value of the LED is from 0 to
-		/sys/class/leds/<led>/max_brightness.
 
 What:		/sys/class/leds/<led>/multi_index
 Date:		March 2020
@@ -25,6 +8,9 @@ Description:	read
 		as an array of strings as they are indexed in the
 		multi_intensity file.
 
+		For additional details please refer to
+		Documentation/leds/leds-class-multicolor.rst.
+
 What:		/sys/class/leds/<led>/multi_intensity
 Date:		March 2020
 KernelVersion:	5.9
@@ -33,3 +19,6 @@ Description:	read/write
 		This file contains array of integers. Order of components is
 		described by the multi_index array. The maximum intensity should
 		not exceed /sys/class/leds/<led>/max_brightness.
+
+		For additional details please refer to
+		Documentation/leds/leds-class-multicolor.rst.
-- 
2.26.2

[PATCH v2 35/39] docs: ABI: sysfs-class-power: unify duplicated properties

[Mauro Carvalho Chehab]

The ABI is not supposed to have duplicated entries, as warned
by get_abi.pl:

	$ ./scripts/get_abi.pl validate 2>&1|grep sysfs-class-power
	Warning: /sys/class/power_supply/<supply_name>/current_avg is defined 2 times:  Documentation/ABI/testing/sysfs-class-power:108  Documentation/ABI/testing/sysfs-class-power:391
	Warning: /sys/class/power_supply/<supply_name>/current_max is defined 2 times:  Documentation/ABI/testing/sysfs-class-power:121  Documentation/ABI/testing/sysfs-class-power:404
	Warning: /sys/class/power_supply/<supply_name>/current_now is defined 2 times:  Documentation/ABI/testing/sysfs-class-power:130  Documentation/ABI/testing/sysfs-class-power:414
	Warning: /sys/class/power_supply/<supply_name>/temp is defined 2 times:  Documentation/ABI/testing/sysfs-class-power:281  Documentation/ABI/testing/sysfs-class-power:493
	Warning: /sys/class/power_supply/<supply_name>/temp_alert_max is defined 2 times:  Documentation/ABI/testing/sysfs-class-power:291  Documentation/ABI/testing/sysfs-class-power:505
	Warning: /sys/class/power_supply/<supply_name>/temp_alert_min is defined 2 times:  Documentation/ABI/testing/sysfs-class-power:306  Documentation/ABI/testing/sysfs-class-power:521
	Warning: /sys/class/power_supply/<supply_name>/temp_max is defined 2 times:  Documentation/ABI/testing/sysfs-class-power:322  Documentation/ABI/testing/sysfs-class-power:537
	Warning: /sys/class/power_supply/<supply_name>/temp_min is defined 2 times:  Documentation/ABI/testing/sysfs-class-power:333  Documentation/ABI/testing/sysfs-class-power:547
	Warning: /sys/class/power_supply/<supply_name>/voltage_max is defined 2 times:  Documentation/ABI/testing/sysfs-class-power:356  Documentation/ABI/testing/sysfs-class-power:571
	Warning: /sys/class/power_supply/<supply_name>/voltage_min is defined 2 times:  Documentation/ABI/testing/sysfs-class-power:367  Documentation/ABI/testing/sysfs-class-power:581
	Warning: /sys/class/power_supply/<supply_name>/voltage_now is defined 2 times:  Documentation/ABI/testing/sysfs-class-power:378  Documentation/ABI/testing/sysfs-class-power:591

Yet, both USB and Battery share a common set of charging-related
properties.

Unify the entries for such properties in order to avoid
duplication, while preserving the battery and USB-specific
data properly documented.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/testing/sysfs-class-power | 486 +++++++++-----------
 1 file changed, 223 insertions(+), 263 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
index d68ad528a8e5..ca830c6cd809 100644
--- a/Documentation/ABI/testing/sysfs-class-power
+++ b/Documentation/ABI/testing/sysfs-class-power
@@ -36,7 +36,229 @@ Description:
 		Access: Read
 		Valid values: "Battery", "UPS", "Mains", "USB", "Wireless"
 
-===== Battery Properties =====
+**Battery and USB properties**
+
+What:		/sys/class/power_supply/<supply_name>/current_avg
+Date:		May 2007
+Contact:	linux-pm@vger.kernel.org
+Description:
+		Battery:
+
+		  Reports an average IBAT current reading for the battery, over
+		  a fixed period. Normally devices will provide a fixed interval
+		  in which they average readings to smooth out the reported
+		  value.
+
+		USB:
+
+		  Reports an average IBUS current reading over a fixed period.
+		  Normally devices will provide a fixed interval in which they
+		  average readings to smooth out the reported value.
+
+		Access: Read
+
+		Valid values: Represented in microamps. Negative values are
+		used for discharging batteries, positive values for charging
+		batteries and for USB IBUS current.
+
+What:		/sys/class/power_supply/<supply_name>/current_max
+Date:		October 2010
+Contact:	linux-pm@vger.kernel.org
+Description:
+		Battery:
+
+		  Reports the maximum IBAT current allowed into the battery.
+
+		USB:
+
+		  Reports the maximum IBUS current the supply can support.
+
+		Access: Read
+		Valid values: Represented in microamps
+
+What: 		/sys/class/power_supply/<supply_name>/current_now
+Date:		May 2007
+Contact:	linux-pm@vger.kernel.org
+Description:
+
+		Battery:
+
+		  Reports an instant, single IBAT current reading for the
+		  battery. This value is not averaged/smoothed.
+
+		  Access: Read
+
+		USB:
+
+		  Reports the IBUS current supplied now. This value is generally
+		  read-only reporting, unless the 'online' state of the supply
+		  is set to be programmable, in which case this value can be set
+		  within the reported min/max range.
+
+		  Access: Read, Write
+
+		Valid values: Represented in microamps. Negative values are
+		used for discharging batteries, positive values for charging
+		batteries and for USB IBUS current.
+
+What:		/sys/class/power_supply/<supply_name>/temp
+Date:		May 2007
+Contact:	linux-pm@vger.kernel.org
+Description:
+		Battery:
+
+		  Reports the current TBAT battery temperature reading.
+
+		USB:
+
+		  Reports the current supply temperature reading. This would
+		  normally be the internal temperature of the device itself
+		  (e.g TJUNC temperature of an IC)
+
+		Access: Read
+
+		Valid values: Represented in 1/10 Degrees Celsius
+
+What:		/sys/class/power_supply/<supply_name>/temp_alert_max
+Date:		July 2012
+Contact:	linux-pm@vger.kernel.org
+Description:
+		Battery:
+
+		  Maximum TBAT temperature trip-wire value where the supply will
+		  notify user-space of the event.
+
+		USB:
+
+		  Maximum supply temperature trip-wire value where the supply
+		  will notify user-space of the event.
+
+		This is normally used for the charging scenario where
+		user-space needs to know if the temperature has crossed an
+		upper threshold so it can take appropriate action (e.g. warning
+		user that the temperature is critically high, and charging has
+		stopped).
+
+		Access: Read
+
+		Valid values: Represented in 1/10 Degrees Celsius
+
+What:		/sys/class/power_supply/<supply_name>/temp_alert_min
+Date:		July 2012
+Contact:	linux-pm@vger.kernel.org
+Description:
+
+		Battery:
+
+		  Minimum TBAT temperature trip-wire value where the supply will
+		  notify user-space of the event.
+
+		USB:
+
+		  Minimum supply temperature trip-wire value where the supply
+		  will notify user-space of the event.
+
+		This is normally used for the charging scenario where user-space
+		needs to know if the temperature has crossed a lower threshold
+		so it can take appropriate action (e.g. warning user that
+		temperature level is high, and charging current has been
+		reduced accordingly to remedy the situation).
+
+		Access: Read
+
+		Valid values: Represented in 1/10 Degrees Celsius
+
+What:		/sys/class/power_supply/<supply_name>/temp_max
+Date:		July 2014
+Contact:	linux-pm@vger.kernel.org
+Description:
+		Battery:
+
+		  Reports the maximum allowed TBAT battery temperature for
+		  charging.
+
+		USB:
+
+		  Reports the maximum allowed supply temperature for operation.
+
+		Access: Read
+
+		Valid values: Represented in 1/10 Degrees Celsius
+
+What:		/sys/class/power_supply/<supply_name>/temp_min
+Date:		July 2014
+Contact:	linux-pm@vger.kernel.org
+Description:
+		Battery:
+
+		  Reports the minimum allowed TBAT battery temperature for
+		  charging.
+
+		USB:
+
+		  Reports the minimum allowed supply temperature for operation.
+
+		Access: Read
+
+		Valid values: Represented in 1/10 Degrees Celsius
+
+What:		/sys/class/power_supply/<supply_name>/voltage_max,
+Date:		January 2008
+Contact:	linux-pm@vger.kernel.org
+Description:
+		Battery:
+
+		  Reports the maximum safe VBAT voltage permitted for the
+		  battery, during charging.
+
+		USB:
+
+		  Reports the maximum VBUS voltage the supply can support.
+
+		Access: Read
+
+		Valid values: Represented in microvolts
+
+What:		/sys/class/power_supply/<supply_name>/voltage_min,
+Date:		January 2008
+Contact:	linux-pm@vger.kernel.org
+Description:
+		Battery:
+
+		  Reports the minimum safe VBAT voltage permitted for the
+		  battery, during discharging.
+
+		USB:
+
+		  Reports the minimum VBUS voltage the supply can support.
+
+		Access: Read
+
+		Valid values: Represented in microvolts
+
+What:		/sys/class/power_supply/<supply_name>/voltage_now,
+Date:		May 2007
+Contact:	linux-pm@vger.kernel.org
+Description:
+		Battery:
+
+		  Reports an instant, single VBAT voltage reading for the
+		  battery. This value is not averaged/smoothed.
+
+		  Access: Read
+
+		USB:
+
+		  Reports the VBUS voltage supplied now. This value is generally
+		  read-only reporting, unless the 'online' state of the supply
+		  is set to be programmable, in which case this value can be set
+		  within the reported min/max range.
+
+		  Access: Read, Write
+
+		Valid values: Represented in microvolts
+
+**Battery Properties**
 
 What:		/sys/class/power_supply/<supply_name>/capacity
 Date:		May 2007
@@ -106,40 +328,6 @@ Description:
 			      "Unknown", "Critical", "Low", "Normal", "High",
 			      "Full"
 
-What:		/sys/class/power_supply/<supply_name>/current_avg
-Date:		May 2007
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports an average IBAT current reading for the battery, over a
-		fixed period. Normally devices will provide a fixed interval in
-		which they average readings to smooth out the reported value.
-
-		Access: Read
-
-		Valid values: Represented in microamps. Negative values are used
-		for discharging batteries, positive values for charging batteries.
-
-What:		/sys/class/power_supply/<supply_name>/current_max
-Date:		October 2010
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports the maximum IBAT current allowed into the battery.
-
-		Access: Read
-		Valid values: Represented in microamps
-
-What:		/sys/class/power_supply/<supply_name>/current_now
-Date:		May 2007
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports an instant, single IBAT current reading for the battery.
-		This value is not averaged/smoothed.
-
-		Access: Read
-
-		Valid values: Represented in microamps. Negative values are used
-		for discharging batteries, positive values for charging batteries.
-
 What:		/sys/class/power_supply/<supply_name>/charge_control_limit
 Date:		Oct 2012
 Contact:	linux-pm@vger.kernel.org
@@ -279,68 +467,6 @@ Description:
 			      "Unknown", "NiMH", "Li-ion", "Li-poly", "LiFe",
 			      "NiCd", "LiMn"
 
-What:		/sys/class/power_supply/<supply_name>/temp
-Date:		May 2007
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports the current TBAT battery temperature reading.
-
-		Access: Read
-
-		Valid values: Represented in 1/10 Degrees Celsius
-
-What:		/sys/class/power_supply/<supply_name>/temp_alert_max
-Date:		July 2012
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Maximum TBAT temperature trip-wire value where the supply will
-		notify user-space of the event. This is normally used for the
-		battery charging scenario where user-space needs to know the
-		battery temperature has crossed an upper threshold so it can
-		take appropriate action (e.g. warning user that battery level is
-		critically high, and charging has stopped).
-
-		Access: Read
-
-		Valid values: Represented in 1/10 Degrees Celsius
-
-What:		/sys/class/power_supply/<supply_name>/temp_alert_min
-Date:		July 2012
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Minimum TBAT temperature trip-wire value where the supply will
-		notify user-space of the event. This is normally used for the
-		battery charging scenario where user-space needs to know the
-		battery temperature has crossed a lower threshold so it can take
-		appropriate action (e.g. warning user that battery level is
-		high, and charging current has been reduced accordingly to
-		remedy the situation).
-
-		Access: Read
-
-		Valid values: Represented in 1/10 Degrees Celsius
-
-What:		/sys/class/power_supply/<supply_name>/temp_max
-Date:		July 2014
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports the maximum allowed TBAT battery temperature for
-		charging.
-
-		Access: Read
-
-		Valid values: Represented in 1/10 Degrees Celsius
-
-What:		/sys/class/power_supply/<supply_name>/temp_min
-Date:		July 2014
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports the minimum allowed TBAT battery temperature for
-		charging.
-
-		Access: Read
-
-		Valid values: Represented in 1/10 Degrees Celsius
 
 What:		/sys/class/power_supply/<supply_name>/voltage_avg,
 Date:		May 2007
@@ -354,77 +480,8 @@ Description:
 
 		Valid values: Represented in microvolts
 
-What:		/sys/class/power_supply/<supply_name>/voltage_max,
-Date:		January 2008
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports the maximum safe VBAT voltage permitted for the battery,
-		during charging.
-
-		Access: Read
-
-		Valid values: Represented in microvolts
-
-What:		/sys/class/power_supply/<supply_name>/voltage_min,
-Date:		January 2008
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports the minimum safe VBAT voltage permitted for the battery,
-		during discharging.
-
-		Access: Read
-
-		Valid values: Represented in microvolts
-
-What:		/sys/class/power_supply/<supply_name>/voltage_now,
-Date:		May 2007
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports an instant, single VBAT voltage reading for the battery.
-		This value is not averaged/smoothed.
-
-		Access: Read
-
-		Valid values: Represented in microvolts
-
 **USB Properties**
 
-What:		/sys/class/power_supply/<supply_name>/current_avg
-Date:		May 2007
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports an average IBUS current reading over a fixed period.
-		Normally devices will provide a fixed interval in which they
-		average readings to smooth out the reported value.
-
-		Access: Read
-
-		Valid values: Represented in microamps
-
-
-What: 		/sys/class/power_supply/<supply_name>/current_max
-Date:		October 2010
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports the maximum IBUS current the supply can support.
-
-		Access: Read
-
-		Valid values: Represented in microamps
-
-What: 		/sys/class/power_supply/<supply_name>/current_now
-Date:		May 2007
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports the IBUS current supplied now. This value is generally
-		read-only reporting, unless the 'online' state of the supply
-		is set to be programmable, in which case this value can be set
-		within the reported min/max range.
-
-		Access: Read, Write
-
-		Valid values: Represented in microamps
-
 What:		/sys/class/power_supply/<supply_name>/input_current_limit
 Date:		July 2014
 Contact:	linux-pm@vger.kernel.org
@@ -491,70 +548,6 @@ Description:
 			2: Online Programmable - Programmable Voltage Supply
 			== ==================================================
 
-What:		/sys/class/power_supply/<supply_name>/temp
-Date:		May 2007
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports the current supply temperature reading. This would
-		normally be the internal temperature of the device itself (e.g
-		TJUNC temperature of an IC)
-
-		Access: Read
-
-		Valid values: Represented in 1/10 Degrees Celsius
-
-What:		/sys/class/power_supply/<supply_name>/temp_alert_max
-Date:		July 2012
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Maximum supply temperature trip-wire value where the supply will
-		notify user-space of the event. This is normally used for the
-		charging scenario where user-space needs to know the supply
-		temperature has crossed an upper threshold so it can take
-		appropriate action (e.g. warning user that the supply
-		temperature is critically high, and charging has stopped to
-		remedy the situation).
-
-		Access: Read
-
-		Valid values: Represented in 1/10 Degrees Celsius
-
-What:		/sys/class/power_supply/<supply_name>/temp_alert_min
-Date:		July 2012
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Minimum supply temperature trip-wire value where the supply will
-		notify user-space of the event. This is normally used for the
-		charging scenario where user-space needs to know the supply
-		temperature has crossed a lower threshold so it can take
-		appropriate action (e.g. warning user that the supply
-		temperature is high, and charging current has been reduced
-		accordingly to remedy the situation).
-
-		Access: Read
-
-		Valid values: Represented in 1/10 Degrees Celsius
-
-What:		/sys/class/power_supply/<supply_name>/temp_max
-Date:		July 2014
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports the maximum allowed supply temperature for operation.
-
-		Access: Read
-
-		Valid values: Represented in 1/10 Degrees Celsius
-
-What:		/sys/class/power_supply/<supply_name>/temp_min
-Date:		July 2014
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports the mainimum allowed supply temperature for operation.
-
-		Access: Read
-
-		Valid values: Represented in 1/10 Degrees Celsius
-
 What: 		/sys/class/power_supply/<supply_name>/usb_type
 Date:		March 2018
 Contact:	linux-pm@vger.kernel.org
@@ -569,39 +562,6 @@ Description:
 			      "Unknown", "SDP", "DCP", "CDP", "ACA", "C", "PD",
 			      "PD_DRP", "PD_PPS", "BrickID"
 
-What: 		/sys/class/power_supply/<supply_name>/voltage_max
-Date:		January 2008
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports the maximum VBUS voltage the supply can support.
-
-		Access: Read
-
-		Valid values: Represented in microvolts
-
-What: 		/sys/class/power_supply/<supply_name>/voltage_min
-Date:		January 2008
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports the minimum VBUS voltage the supply can support.
-
-		Access: Read
-
-		Valid values: Represented in microvolts
-
-What: 		/sys/class/power_supply/<supply_name>/voltage_now
-Date:		May 2007
-Contact:	linux-pm@vger.kernel.org
-Description:
-		Reports the VBUS voltage supplied now. This value is generally
-		read-only reporting, unless the 'online' state of the supply
-		is set to be programmable, in which case this value can be set
-		within the reported min/max range.
-
-		Access: Read, Write
-
-		Valid values: Represented in microvolts
-
 **Device Specific Properties**
 
 What:		/sys/class/power/ds2760-battery.*/charge_now
-- 
2.26.2

[PATCH v2 36/39] docs: ABI: sysfs-c2port: remove a duplicated entry

[Mauro Carvalho Chehab]

As warned by scripts/get_abi.pl:
	Warning: /sys/class/c2port/c2portX/flash_erase is defined 2 times:  Documentation/ABI/testing/sysfs-c2port:60  Documentation/ABI/testing/sysfs-c2port:68

This entry was added twice at the same patch. Probalby a
cut-and paste issue.

Fixes: 4e17e1db9647 ("Add c2 port support")

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/ABI/testing/sysfs-c2port | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-c2port b/Documentation/ABI/testing/sysfs-c2port
index 716cffc457e9..f7b8cf6e4398 100644
--- a/Documentation/ABI/testing/sysfs-c2port
+++ b/Documentation/ABI/testing/sysfs-c2port
@@ -66,13 +66,6 @@ Description:
 		the "erase" command on the on-board flash of the connected
 		micro.
 
-What:		/sys/class/c2port/c2portX/flash_erase
-Date:		October 2008
-Contact:	Rodolfo Giometti <giometti@linux.it>
-Description:
-		The /sys/class/c2port/c2portX/flash_erase file show the
-		on-board flash size of the connected micro.
-
 What:		/sys/class/c2port/c2portX/reset
 Date:		October 2008
 Contact:	Rodolfo Giometti <giometti@linux.it>
-- 
2.26.2

[PATCH v2 37/39] docs: ABI: sysfs-class-backlight: unify ABI documentation

[Mauro Carvalho Chehab]

Both adp8860 and adp8870 define some extensions to the
backlight class. This causes warnings:

	Warning: /sys/class/backlight/<backlight>/ambient_light_level is defined 2 times:  /sys/class/backlight/<backlight>/ambient_light_level:8  /sys/class/backlight/<backlight>/ambient_light_level:30
	Warning: /sys/class/backlight/<backlight>/ambient_light_zone is defined 2 times:  /sys/class/backlight/<backlight>/ambient_light_zone:18  /sys/class/backlight/<backlight>/ambient_light_zone:40

As ABI definitions shouldn't be duplicated.

Unfortunately, the ABI is dependent on the specific device
features. As such, ambient_light_level range is somewhat
different among the supported devices.

The ambient_light_zone is even worse: the meanings of each
preset are different, and there's no ABI to retrieve
the supported types nor their meanins. Unfortunately,
it is too late to fix it without causing regressions,
as this has been used since Kernel v2.6.35.

Rewrite those ABI documentation using the current documentation
as a reference, and double-checking at the datasheets:

	https://www.analog.com/media/en/technical-documentation/data-sheets/ADP8870.pdf
	https://www.analog.com/media/en/technical-documentation/data-sheets/ADP8860.pdf

in order to properly document the differences between those two
drivers.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../ABI/testing/sysfs-class-backlight         | 60 +++++++++++++++++++
 .../ABI/testing/sysfs-class-backlight-adp8860 | 21 +------
 .../sysfs-class-backlight-driver-adp8870      | 30 +---------
 3 files changed, 65 insertions(+), 46 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-class-backlight b/Documentation/ABI/testing/sysfs-class-backlight
index 3ab175a3f5cb..1fc86401bf95 100644
--- a/Documentation/ABI/testing/sysfs-class-backlight
+++ b/Documentation/ABI/testing/sysfs-class-backlight
@@ -24,3 +24,63 @@ Description:
 		non-linear
 		  The brightness changes non-linearly with each step. Brightness
 		  controls should use a linear mapping for a linear perception.
+
+What:		/sys/class/backlight/<backlight>/ambient_light_level
+Date:		Apr, 2010
+KernelVersion:	v2.6.35
+Contact:	Michael Hennerich <michael.hennerich@analog.com>
+Description:
+		(RO) Get conversion value of the light sensor.
+
+		The value is automatically updated every 80 ms when the
+		light sensor is enabled.
+
+		The value range is device-driver specific:
+
+		For ADP8870:
+
+		  It returns integer between 0 (dark) and 8000 (max ambient
+		  brightness).
+
+		For ADP8860:
+
+		  It returns a 13-bits integer.
+
+What:		/sys/class/backlight/<backlight>/ambient_light_zone
+Date:		Apr, 2010
+KernelVersion:	v2.6.35
+Contact:	Michael Hennerich <michael.hennerich@analog.com>,
+		device-drivers-devel@blackfin.uclinux.org
+
+Description:
+		(RW) Read or write the specific brightness level at which the
+		backlight operates.
+
+		The value meaning is device-driver specific:
+
+		For ADP8860:
+
+		  ==	==========================
+		   0	Off: Backlight set to 0 mA
+		   1	Level 1: daylight
+		   2	Level 2: bright
+		   3	Level 3: dark
+		  ==	==========================
+
+		For ADP8870:
+
+		  ==	==========================
+		   0	Off: Backlight set to 0 mA
+		   1	Level 1: daylight
+		   2	Level 2: bright
+		   3	Level 3: office
+		   4	Level 4: indoor
+		   5	Level 5: dark
+		  ==	==========================
+
+		Writing 0 returns to normal/automatic ambient light level
+		operation.
+
+		It can be enabled by writing the value stored in
+		/sys/class/backlight/<backlight>/max_brightness to
+		/sys/class/backlight/<backlight>/brightness.
diff --git a/Documentation/ABI/testing/sysfs-class-backlight-adp8860 b/Documentation/ABI/testing/sysfs-class-backlight-adp8860
index 54d61c788b1b..6610ac73f9ba 100644
--- a/Documentation/ABI/testing/sysfs-class-backlight-adp8860
+++ b/Documentation/ABI/testing/sysfs-class-backlight-adp8860
@@ -6,25 +6,8 @@ adp8860, adp8861 and adp8863 devices: daylight (level 1), office (level 2) and
 dark (level 3). By default the brightness operates at the daylight brightness
 level.
 
-What:		/sys/class/backlight/<backlight>/ambient_light_level
-Date:		Apr, 2010
-KernelVersion:	v2.6.35
-Contact:	Michael Hennerich <michael.hennerich@analog.com>
-Description:
-		(RO) 13-bit conversion value for the first light sensor—high
-		byte (Bit 12 to Bit 8). The value is updated every 80 ms (when
-		the light sensor is enabled).
-
-
-What:		/sys/class/backlight/<backlight>/ambient_light_zone
-Date:		Apr, 2010
-KernelVersion:	v2.6.35
-Contact:	Michael Hennerich <michael.hennerich@analog.com>
-Description:
-		(RW) Read or write the specific level at which the backlight
-		operates. Value "0" enables automatic ambient light sensing, and
-		values "1", "2" or "3" set the control to daylight, office or
-		dark respectively.
+See also /sys/class/backlight/<backlight>/ambient_light_level and
+/sys/class/backlight/<backlight>/ambient_light_zone.
 
 
 What:		/sys/class/backlight/<backlight>/l1_daylight_max
diff --git a/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 b/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870
index 33e648808117..b08ca912cad4 100644
--- a/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870
+++ b/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870
@@ -1,3 +1,6 @@
+See also /sys/class/backlight/<backlight>/ambient_light_level and
+/sys/class/backlight/<backlight>/ambient_light_zone.
+
 What:		/sys/class/backlight/<backlight>/<ambient light zone>_max
 What:		/sys/class/backlight/<backlight>/l1_daylight_max
 What:		/sys/class/backlight/<backlight>/l2_bright_max
@@ -27,30 +30,3 @@ Description:
 		set to 0. Full off when the backlight is disabled.
 		This file will also show the dim brightness level stored for
 		this <ambient light zone>.
-
-What:		/sys/class/backlight/<backlight>/ambient_light_level
-Date:		May 2011
-KernelVersion:	3.0
-Contact:	device-drivers-devel@blackfin.uclinux.org
-Description:
-		Get conversion value of the light sensor.
-		This value is updated every 80 ms (when the light sensor
-		is enabled). Returns integer between 0 (dark) and
-		8000 (max ambient brightness)
-
-What:		/sys/class/backlight/<backlight>/ambient_light_zone
-Date:		May 2011
-KernelVersion:	3.0
-Contact:	device-drivers-devel@blackfin.uclinux.org
-Description:
-		Get/Set current ambient light zone. Reading returns
-		integer between 1..5 (1 = daylight, 2 = bright, ..., 5 = dark).
-		Writing a value between 1..5 forces the backlight controller
-		to enter the corresponding ambient light zone.
-		Writing 0 returns to normal/automatic ambient light level
-		operation. The ambient light sensing feature on these devices
-		is an extension to the API documented in
-		Documentation/ABI/stable/sysfs-class-backlight.
-		It can be enabled by writing the value stored in
-		/sys/class/backlight/<backlight>/max_brightness to
-		/sys/class/backlight/<backlight>/brightness.
-- 
2.26.2

[PATCH v2 38/39] docs: ABI: sysfs-class-led-trigger-pattern: remove hw_pattern duplication

[Mauro Carvalho Chehab]

The ABI files are supposed to be unique. Yet,
in the specific case of hw_pattern, there are some duplicated
entries as warned by scripts/get_abi.pl:

	Warning: /sys/class/leds/<led>/hw_pattern is defined 3 times:  Documentation/ABI/testing/sysfs-class-led-trigger-pattern:14  Documentation/ABI/testing/sysfs-class-led-driver-sc27xx:0  Documentation/ABI/testing/sysfs-class-led-driver-el15203000:0

Drop the duplication from the ABI files, moving the specific
definitions to files inside Documentation/leds.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 .../testing/sysfs-class-led-driver-el15203000 | 135 -----------------
 .../ABI/testing/sysfs-class-led-driver-sc27xx |  22 ---
 .../testing/sysfs-class-led-trigger-pattern   |   4 +-
 Documentation/leds/index.rst                  |   1 +
 Documentation/leds/leds-el15203000.rst        | 140 ++++++++++++++++++
 Documentation/leds/leds-sc27xx.rst            |  27 ++++
 6 files changed, 170 insertions(+), 159 deletions(-)
 delete mode 100644 Documentation/ABI/testing/sysfs-class-led-driver-sc27xx
 create mode 100644 Documentation/leds/leds-el15203000.rst
 create mode 100644 Documentation/leds/leds-sc27xx.rst

diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-el15203000 b/Documentation/ABI/testing/sysfs-class-led-driver-el15203000
index da546e86deb5..04f3ffdc5936 100644
--- a/Documentation/ABI/testing/sysfs-class-led-driver-el15203000
+++ b/Documentation/ABI/testing/sysfs-class-led-driver-el15203000
@@ -1,138 +1,3 @@
-What:		/sys/class/leds/<led>/hw_pattern
-Date:		September 2019
-KernelVersion:	5.5
-Description:
-		Specify a hardware pattern for the EL15203000 LED.
-		The LEDs board supports only predefined patterns by firmware
-		for specific LEDs.
-
-		Breathing mode for Screen frame light tube::
-
-		    "0 4000 1 4000"
-
-			^
-			|
-		    Max-|     ---
-			|    /   \
-			|   /     \
-			|  /       \     /
-			| /         \   /
-		    Min-|-           ---
-			|
-			0------4------8--> time (sec)
-
-		Cascade mode for Pipe LED::
-
-		    "1 800 2 800 4 800 8 800 16 800"
-
-			^
-			|
-		  0 On -|----+                   +----+                   +---
-			|    |                   |    |                   |
-		    Off-|    +-------------------+    +-------------------+
-			|
-		  1 On -|    +----+                   +----+
-			|    |    |                   |    |
-		    Off |----+    +-------------------+    +------------------
-			|
-		  2 On -|         +----+                   +----+
-			|         |    |                   |    |
-		    Off-|---------+    +-------------------+    +-------------
-			|
-		  3 On -|              +----+                   +----+
-			|              |    |                   |    |
-		    Off-|--------------+    +-------------------+    +--------
-			|
-		  4 On -|                   +----+                   +----+
-			|                   |    |                   |    |
-		    Off-|-------------------+    +-------------------+    +---
-			|
-			0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
-
-		Inverted cascade mode for Pipe LED::
-
-		    "30 800 29 800 27 800 23 800 15 800"
-
-			^
-			|
-		  0 On -|    +-------------------+    +-------------------+
-			|    |                   |    |                   |
-		    Off-|----+                   +----+                   +---
-			|
-		  1 On -|----+    +-------------------+    +------------------
-			|    |    |                   |    |
-		    Off |    +----+                   +----+
-			|
-		  2 On -|---------+    +-------------------+    +-------------
-			|         |    |                   |    |
-		    Off-|         +----+                   +----+
-			|
-		  3 On -|--------------+    +-------------------+    +--------
-			|              |    |                   |    |
-		    Off-|              +----+                   +----+
-			|
-		  4 On -|-------------------+    +-------------------+    +---
-			|                   |    |                   |    |
-		    Off-|                   +----+                   +----+
-			|
-			0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
-
-		Bounce mode for Pipe LED::
-
-		    "1 800 2 800 4 800 8 800 16 800 16 800 8 800 4 800 2 800 1 800"
-
-			^
-			|
-		  0 On -|----+                                       +--------
-			|    |                                       |
-		    Off-|    +---------------------------------------+
-			|
-		  1 On -|    +----+                             +----+
-			|    |    |                             |    |
-		    Off |----+    +-----------------------------+    +--------
-			|
-		  2 On -|         +----+                   +----+
-			|         |    |                   |    |
-		    Off-|---------+    +-------------------+    +-------------
-			|
-		  3 On -|              +----+         +----+
-			|              |    |         |    |
-		    Off-|--------------+    +---------+    +------------------
-			|
-		  4 On -|                   +---------+
-			|                   |         |
-		    Off-|-------------------+         +-----------------------
-			|
-			0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
-
-		Inverted bounce mode for Pipe LED::
-
-		    "30 800 29 800 27 800 23 800 15 800 15 800 23 800 27 800 29 800 30 800"
-
-			^
-			|
-		    0 On -|    +---------------------------------------+
-			|    |                                       |
-		    Off-|----+                                       +--------
-			|
-		    1 On -|----+    +-----------------------------+    +--------
-			|    |    |                             |    |
-		    Off |    +----+                             +----+
-			|
-		    2 On -|---------+    +-------------------+    +-------------
-			|         |    |                   |    |
-		    Off-|         +----+                   +----+
-			|
-		    3 On -|--------------+    +---------+    +------------------
-			|              |    |         |    |
-		    Off-|              +----+         +----+
-			|
-		    4 On -|-------------------+         +-----------------------
-			|                   |         |
-		    Off-|                   +---------+
-			|
-			0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
-
 What:		/sys/class/leds/<led>/repeat
 Date:		September 2019
 KernelVersion:	5.5
diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx b/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx
deleted file mode 100644
index 215482379580..000000000000
--- a/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx
+++ /dev/null
@@ -1,22 +0,0 @@
-What:		/sys/class/leds/<led>/hw_pattern
-Date:		September 2018
-KernelVersion:	4.20
-Description:
-		Specify a hardware pattern for the SC27XX LED. For the SC27XX
-		LED controller, it only supports 4 stages to make a single
-		hardware pattern, which is used to configure the rise time,
-		high time, fall time and low time for the breathing mode.
-
-		For the breathing mode, the SC27XX LED only expects one brightness
-		for the high stage. To be compatible with the hardware pattern
-		format, we should set brightness as 0 for rise stage, fall
-		stage and low stage.
-
-		- Min stage duration: 125 ms
-		- Max stage duration: 31875 ms
-
-		Since the stage duration step is 125 ms, the duration should be
-		a multiplier of 125, like 125ms, 250ms, 375ms, 500ms ... 31875ms.
-
-		Thus the format of the hardware pattern values should be:
-		"0 rise_duration brightness high_duration 0 fall_duration 0 low_duration".
diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-pattern b/Documentation/ABI/testing/sysfs-class-led-trigger-pattern
index bd92ef9d6faa..d91a07767adf 100644
--- a/Documentation/ABI/testing/sysfs-class-led-trigger-pattern
+++ b/Documentation/ABI/testing/sysfs-class-led-trigger-pattern
@@ -23,8 +23,8 @@ Description:
 
 		Since different LED hardware can have different semantics of
 		hardware patterns, each driver is expected to provide its own
-		description for the hardware patterns in their ABI documentation
-		file.
+		description for the hardware patterns in their documentation
+		file at Documentation/leds/.
 
 What:		/sys/class/leds/<led>/repeat
 Date:		September 2018
diff --git a/Documentation/leds/index.rst b/Documentation/leds/index.rst
index bc70c6aa7138..53e6090454af 100644
--- a/Documentation/leds/index.rst
+++ b/Documentation/leds/index.rst
@@ -17,6 +17,7 @@ LEDs
    uleds
 
    leds-blinkm
+   leds-el15203000
    leds-lm3556
    leds-lp3944
    leds-lp5521
diff --git a/Documentation/leds/leds-el15203000.rst b/Documentation/leds/leds-el15203000.rst
new file mode 100644
index 000000000000..12c23d79724d
--- /dev/null
+++ b/Documentation/leds/leds-el15203000.rst
@@ -0,0 +1,140 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==================================
+Kernel driver for Crane EL15203000
+==================================
+
+/sys/class/leds/<led>/hw_pattern
+--------------------------------
+
+Specify a hardware pattern for the EL15203000 LED.
+
+The LEDs board supports only predefined patterns by firmware
+for specific LEDs.
+
+Breathing mode for Screen frame light tube::
+
+    "0 4000 1 4000"
+
+	^
+	|
+    Max-|     ---
+	|    /   \
+	|   /     \
+	|  /       \     /
+	| /         \   /
+    Min-|-           ---
+	|
+	0------4------8--> time (sec)
+
+Cascade mode for Pipe LED::
+
+    "1 800 2 800 4 800 8 800 16 800"
+
+	^
+	|
+  0 On -|----+                   +----+                   +---
+	|    |                   |    |                   |
+    Off-|    +-------------------+    +-------------------+
+	|
+  1 On -|    +----+                   +----+
+	|    |    |                   |    |
+    Off |----+    +-------------------+    +------------------
+	|
+  2 On -|         +----+                   +----+
+	|         |    |                   |    |
+    Off-|---------+    +-------------------+    +-------------
+	|
+  3 On -|              +----+                   +----+
+	|              |    |                   |    |
+    Off-|--------------+    +-------------------+    +--------
+	|
+  4 On -|                   +----+                   +----+
+	|                   |    |                   |    |
+    Off-|-------------------+    +-------------------+    +---
+	|
+	0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
+
+Inverted cascade mode for Pipe LED::
+
+    "30 800 29 800 27 800 23 800 15 800"
+
+	^
+	|
+  0 On -|    +-------------------+    +-------------------+
+	|    |                   |    |                   |
+    Off-|----+                   +----+                   +---
+	|
+  1 On -|----+    +-------------------+    +------------------
+	|    |    |                   |    |
+    Off |    +----+                   +----+
+	|
+  2 On -|---------+    +-------------------+    +-------------
+	|         |    |                   |    |
+    Off-|         +----+                   +----+
+	|
+  3 On -|--------------+    +-------------------+    +--------
+	|              |    |                   |    |
+    Off-|              +----+                   +----+
+	|
+  4 On -|-------------------+    +-------------------+    +---
+	|                   |    |                   |    |
+    Off-|                   +----+                   +----+
+	|
+	0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
+
+Bounce mode for Pipe LED::
+
+    "1 800 2 800 4 800 8 800 16 800 16 800 8 800 4 800 2 800 1 800"
+
+	^
+	|
+  0 On -|----+                                       +--------
+	|    |                                       |
+    Off-|    +---------------------------------------+
+	|
+  1 On -|    +----+                             +----+
+	|    |    |                             |    |
+    Off |----+    +-----------------------------+    +--------
+	|
+  2 On -|         +----+                   +----+
+	|         |    |                   |    |
+    Off-|---------+    +-------------------+    +-------------
+	|
+  3 On -|              +----+         +----+
+	|              |    |         |    |
+    Off-|--------------+    +---------+    +------------------
+	|
+  4 On -|                   +---------+
+	|                   |         |
+    Off-|-------------------+         +-----------------------
+	|
+	0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
+
+Inverted bounce mode for Pipe LED::
+
+    "30 800 29 800 27 800 23 800 15 800 15 800 23 800 27 800 29 800 30 800"
+
+	^
+	|
+  0 On -|    +---------------------------------------+
+	|    |                                       |
+    Off-|----+                                       +--------
+	|
+  1 On -|----+    +-----------------------------+    +--------
+	|    |    |                             |    |
+    Off |    +----+                             +----+
+	|
+  2 On -|---------+    +-------------------+    +-------------
+	|         |    |                   |    |
+    Off-|         +----+                   +----+
+	|
+  3 On -|--------------+    +---------+    +------------------
+	|              |    |         |    |
+    Off-|              +----+         +----+
+	|
+  4 On -|-------------------+         +-----------------------
+	|                   |         |
+    Off-|                   +---------+
+	|
+	0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
diff --git a/Documentation/leds/leds-sc27xx.rst b/Documentation/leds/leds-sc27xx.rst
new file mode 100644
index 000000000000..6bdf6ba3c9fd
--- /dev/null
+++ b/Documentation/leds/leds-sc27xx.rst
@@ -0,0 +1,27 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================
+Kernel driver for Spreadtrum SC27XX
+===================================
+
+/sys/class/leds/<led>/hw_pattern
+--------------------------------
+
+Specify a hardware pattern for the SC27XX LED. For the SC27XX
+LED controller, it only supports 4 stages to make a single
+hardware pattern, which is used to configure the rise time,
+high time, fall time and low time for the breathing mode.
+
+For the breathing mode, the SC27XX LED only expects one brightness
+for the high stage. To be compatible with the hardware pattern
+format, we should set brightness as 0 for rise stage, fall
+stage and low stage.
+
+- Min stage duration: 125 ms
+- Max stage duration: 31875 ms
+
+Since the stage duration step is 125 ms, the duration should be
+a multiplier of 125, like 125ms, 250ms, 375ms, 500ms ... 31875ms.
+
+Thus the format of the hardware pattern values should be:
+"0 rise_duration brightness high_duration 0 fall_duration 0 low_duration".
-- 
2.26.2

[PATCH v2 39/39] scripts: get_abi.pl: assume ReST format by default

[Mauro Carvalho Chehab]

All ABI files are now compatible with ReST format. So, change
the script default to assume that the ABI source files
are compatible with ReST.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 scripts/get_abi.pl | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index d09bb37dd236..2cb592f8eba4 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -18,7 +18,7 @@ my $prefix="Documentation/ABI";
 #
 # If true, assumes that the description is formatted with ReST
 #
-my $description_is_rst = 0;
+my $description_is_rst = 1;
 
 GetOptions(
 	"debug|d+" => \$debug,
-- 
2.26.2

RE: [PATCH v2 31/39] docs: ABI: cleanup several ABI documents

[Rojewski, Cezary]

On 2020-10-30 8:40 AM, Mauro Carvalho Chehab wrote:
> There are some ABI documents that, while they don't generate
> any warnings, they have issues when parsed by get_abi.pl script
> on its output result.
> 
> Address them, in order to provide a clean output.
> 
> Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> #for IIO
> Reviewed-by: Tom Rix <trix@redhat.com> # for fpga-manager
> Reviewed-By: Kajol Jain<kjain@linux.ibm.com> # for sysfs-bus-event_source-devices-hv_gpci and sysfs-bus-event_source-devices-hv_24x7
> Acked-by: Oded Gabbay <oded.gabbay@gmail.com> # for Habanalabs
> Acked-by: Vaibhav Jain <vaibhav@linux.ibm.com> # for sysfs-bus-papr-pmem
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---

sysfs-bus-pci-devices-catpt changes LGTM, thanks.

Acked-by: Cezary Rojewski <cezary.rojewski@intel.com> # for catpt

Regards,
Czarek

>   Documentation/ABI/obsolete/sysfs-class-dax    |   8 +-
>   .../ABI/obsolete/sysfs-driver-hid-roccat-pyra |   3 +
>   Documentation/ABI/removed/devfs               |   1 +
>   Documentation/ABI/removed/raw1394             |   1 +
>   Documentation/ABI/removed/sysfs-class-rfkill  |   2 +-
>   Documentation/ABI/removed/video1394           |   1 +
>   Documentation/ABI/stable/firewire-cdev        |  63 ++---
>   Documentation/ABI/stable/sysfs-acpi-pmprofile |   4 +-
>   Documentation/ABI/stable/sysfs-bus-w1         |   1 +
>   Documentation/ABI/stable/sysfs-class-tpm      |   4 +-
>   Documentation/ABI/stable/sysfs-driver-speakup |   4 +
>   Documentation/ABI/testing/configfs-most       | 135 +++++++----
>   .../ABI/testing/configfs-usb-gadget-ecm       |  12 +-
>   .../ABI/testing/configfs-usb-gadget-eem       |  10 +-
>   .../ABI/testing/configfs-usb-gadget-loopback  |   6 +-
>   .../testing/configfs-usb-gadget-mass-storage  |  18 +-
>   .../ABI/testing/configfs-usb-gadget-midi      |  14 +-
>   .../ABI/testing/configfs-usb-gadget-printer   |   6 +-
>   .../testing/configfs-usb-gadget-sourcesink    |  18 +-
>   .../ABI/testing/configfs-usb-gadget-subset    |  10 +-
>   .../ABI/testing/configfs-usb-gadget-uac2      |  14 +-
>   .../ABI/testing/configfs-usb-gadget-uvc       |   2 +-
>   .../ABI/testing/debugfs-cec-error-inj         |   2 +-
>   .../ABI/testing/debugfs-driver-habanalabs     |  12 +-
>   .../ABI/testing/debugfs-pfo-nx-crypto         |  28 +--
>   Documentation/ABI/testing/debugfs-pktcdvd     |   2 +-
>   .../ABI/testing/debugfs-turris-mox-rwtm       |  10 +-
>   Documentation/ABI/testing/debugfs-wilco-ec    |  21 +-
>   Documentation/ABI/testing/dell-smbios-wmi     |  32 +--
>   Documentation/ABI/testing/gpio-cdev           |  13 +-
>   Documentation/ABI/testing/procfs-diskstats    |   6 +-
>   Documentation/ABI/testing/procfs-smaps_rollup |  48 ++--
>   Documentation/ABI/testing/pstore              |  19 +-
>   Documentation/ABI/testing/sysfs-block-rnbd    |   4 +-
>   Documentation/ABI/testing/sysfs-bus-acpi      |   1 +
>   .../testing/sysfs-bus-coresight-devices-etb10 |   5 +-
>   Documentation/ABI/testing/sysfs-bus-css       |   3 +
>   Documentation/ABI/testing/sysfs-bus-dfl       |   2 +
>   .../sysfs-bus-event_source-devices-hv_24x7    |   6 +-
>   .../sysfs-bus-event_source-devices-hv_gpci    |   7 +-
>   Documentation/ABI/testing/sysfs-bus-fcoe      |  68 ++++--
>   Documentation/ABI/testing/sysfs-bus-fsl-mc    |  12 +-
>   .../ABI/testing/sysfs-bus-i2c-devices-fsa9480 |  26 +-
>   Documentation/ABI/testing/sysfs-bus-i3c       |   2 +
>   Documentation/ABI/testing/sysfs-bus-iio       |  19 +-
>   .../ABI/testing/sysfs-bus-iio-adc-hi8435      |   5 +
>   .../ABI/testing/sysfs-bus-iio-adc-stm32       |   3 +
>   .../ABI/testing/sysfs-bus-iio-distance-srf08  |   7 +-
>   .../testing/sysfs-bus-iio-frequency-ad9523    |   2 +
>   .../testing/sysfs-bus-iio-frequency-adf4371   |  10 +-
>   .../ABI/testing/sysfs-bus-iio-health-afe440x  |  12 +-
>   .../ABI/testing/sysfs-bus-iio-light-isl29018  |   6 +-
>   .../testing/sysfs-bus-intel_th-devices-gth    |  11 +-
>   Documentation/ABI/testing/sysfs-bus-papr-pmem |  23 +-
>   Documentation/ABI/testing/sysfs-bus-pci       |  22 +-
>   .../ABI/testing/sysfs-bus-pci-devices-catpt   |   1 +
>   .../testing/sysfs-bus-pci-drivers-ehci_hcd    |   4 +-
>   Documentation/ABI/testing/sysfs-bus-rbd       |  37 ++-
>   Documentation/ABI/testing/sysfs-bus-siox      |   3 +
>   .../ABI/testing/sysfs-bus-thunderbolt         |  18 +-
>   Documentation/ABI/testing/sysfs-bus-usb       |   2 +
>   .../sysfs-class-backlight-driver-lm3533       |  26 +-
>   Documentation/ABI/testing/sysfs-class-bdi     |   1 -
>   .../ABI/testing/sysfs-class-chromeos          |  15 +-
>   Documentation/ABI/testing/sysfs-class-cxl     |   8 +-
>   Documentation/ABI/testing/sysfs-class-devlink |  30 ++-
>   Documentation/ABI/testing/sysfs-class-extcon  |  34 +--
>   .../ABI/testing/sysfs-class-fpga-manager      |   5 +-
>   Documentation/ABI/testing/sysfs-class-gnss    |   2 +
>   Documentation/ABI/testing/sysfs-class-led     |   1 +
>   .../testing/sysfs-class-led-driver-el15203000 |  30 +--
>   .../ABI/testing/sysfs-class-led-driver-lm3533 |  44 ++--
>   .../ABI/testing/sysfs-class-led-flash         |  27 ++-
>   .../testing/sysfs-class-led-trigger-netdev    |   7 +
>   .../testing/sysfs-class-led-trigger-usbport   |   1 +
>   .../ABI/testing/sysfs-class-leds-gt683r       |   8 +-
>   Documentation/ABI/testing/sysfs-class-net     |  61 +++--
>   .../ABI/testing/sysfs-class-net-cdc_ncm       |   6 +-
>   .../ABI/testing/sysfs-class-net-phydev        |   2 +
>   Documentation/ABI/testing/sysfs-class-pktcdvd |  36 +--
>   Documentation/ABI/testing/sysfs-class-power   |  12 +-
>   .../ABI/testing/sysfs-class-power-mp2629      |   1 +
>   .../ABI/testing/sysfs-class-power-twl4030     |   4 +-
>   Documentation/ABI/testing/sysfs-class-rapidio |  46 ++--
>   .../ABI/testing/sysfs-class-regulator         |  36 +--
>   .../ABI/testing/sysfs-class-remoteproc        |  14 +-
>   ...ysfs-class-rtc-rtc0-device-rtc_calibration |   1 +
>   Documentation/ABI/testing/sysfs-class-uwb_rc  |  13 +-
>   .../ABI/testing/sysfs-class-watchdog          |   7 +-
>   Documentation/ABI/testing/sysfs-dev           |   7 +-
>   .../ABI/testing/sysfs-devices-mapping         |  41 ++--
>   .../ABI/testing/sysfs-devices-memory          |  15 +-
>   .../sysfs-devices-platform-_UDC_-gadget       |  10 +-
>   .../ABI/testing/sysfs-devices-platform-ipmi   |  52 ++--
>   .../ABI/testing/sysfs-devices-system-cpu      |   4 +-
>   .../ABI/testing/sysfs-driver-hid-lenovo       |  10 +
>   .../ABI/testing/sysfs-driver-hid-ntrig        |  13 +-
>   .../ABI/testing/sysfs-driver-hid-roccat-kone  |  19 ++
>   .../ABI/testing/sysfs-driver-hid-wiimote      |   1 +
>   .../ABI/testing/sysfs-driver-input-exc3000    |   2 +
>   .../ABI/testing/sysfs-driver-jz4780-efuse     |   6 +-
>   .../ABI/testing/sysfs-driver-pciback          |   6 +-
>   Documentation/ABI/testing/sysfs-driver-ufs    | 228 ++++++++++++++----
>   .../ABI/testing/sysfs-driver-w1_ds28e17       |   3 +
>   Documentation/ABI/testing/sysfs-firmware-acpi |  16 +-
>   .../ABI/testing/sysfs-firmware-efi-esrt       |  28 ++-
>   .../testing/sysfs-firmware-efi-runtime-map    |  14 +-
>   .../ABI/testing/sysfs-firmware-qemu_fw_cfg    |  20 +-
>   Documentation/ABI/testing/sysfs-firmware-sfi  |   6 +-
>   .../ABI/testing/sysfs-firmware-sgi_uv         |   6 +-
>   Documentation/ABI/testing/sysfs-fs-f2fs       |  48 ++--
>   Documentation/ABI/testing/sysfs-kernel-mm-ksm |   5 +-
>   Documentation/ABI/testing/sysfs-kernel-slab   |   3 +
>   Documentation/ABI/testing/sysfs-module        |  17 +-
>   .../ABI/testing/sysfs-platform-dell-laptop    |  10 +-
>   .../ABI/testing/sysfs-platform-dell-smbios    |   4 +-
>   .../testing/sysfs-platform-i2c-demux-pinctrl  |   4 +-
>   Documentation/ABI/testing/sysfs-platform-kim  |   1 +
>   .../testing/sysfs-platform-phy-rcar-gen3-usb2 |  10 +-
>   .../ABI/testing/sysfs-platform-renesas_usb3   |  10 +-
>   Documentation/ABI/testing/sysfs-power         |  21 +-
>   Documentation/ABI/testing/sysfs-profiling     |   2 +-
>   Documentation/ABI/testing/sysfs-wusb_cbaf     |   3 +-
>   Documentation/ABI/testing/usb-charger-uevent  |  82 ++++---
>   Documentation/ABI/testing/usb-uevent          |  32 +--
>   scripts/get_abi.pl                            |   2 -
>   126 files changed, 1323 insertions(+), 767 deletions(-)
>

Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Fabrice Gasnier]

On 10/30/20 8:40 AM, Mauro Carvalho Chehab wrote:
> Some files over there won't parse well by Sphinx.
> 
> Fix them.
> 
> Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> # for IIO
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  .../ABI/testing/configfs-spear-pcie-gadget    |  36 +--
>  Documentation/ABI/testing/configfs-usb-gadget |  83 +++---
>  .../ABI/testing/configfs-usb-gadget-hid       |  10 +-
>  .../ABI/testing/configfs-usb-gadget-rndis     |  16 +-
>  .../ABI/testing/configfs-usb-gadget-uac1      |  18 +-
>  .../ABI/testing/configfs-usb-gadget-uvc       | 220 +++++++++-------
>  Documentation/ABI/testing/debugfs-ec          |  11 +-
>  Documentation/ABI/testing/debugfs-pktcdvd     |  11 +-
>  Documentation/ABI/testing/dev-kmsg            |  27 +-
>  Documentation/ABI/testing/evm                 |  17 +-
>  Documentation/ABI/testing/ima_policy          |  30 ++-
>  Documentation/ABI/testing/procfs-diskstats    |  40 +--
>  Documentation/ABI/testing/sysfs-block         |  38 +--
>  Documentation/ABI/testing/sysfs-block-device  |   2 +
>  Documentation/ABI/testing/sysfs-bus-acpi      |  18 +-
>  .../sysfs-bus-event_source-devices-format     |   3 +-
>  .../ABI/testing/sysfs-bus-i2c-devices-pca954x |  27 +-
>  Documentation/ABI/testing/sysfs-bus-iio       |  11 +
>  .../sysfs-bus-iio-adc-envelope-detector       |   5 +-
>  .../ABI/testing/sysfs-bus-iio-cros-ec         |   2 +-
>  .../ABI/testing/sysfs-bus-iio-dfsdm-adc-stm32 |   8 +-
>  .../ABI/testing/sysfs-bus-iio-lptimer-stm32   |  29 ++-
>  .../sysfs-bus-iio-magnetometer-hmc5843        |  19 +-
>  .../sysfs-bus-iio-temperature-max31856        |  19 +-
>  .../ABI/testing/sysfs-bus-iio-timer-stm32     | 137 ++++++----
>  .../testing/sysfs-bus-intel_th-devices-msc    |   4 +
>  Documentation/ABI/testing/sysfs-bus-nfit      |   2 +-
>  .../testing/sysfs-bus-pci-devices-aer_stats   | 119 +++++----
>  Documentation/ABI/testing/sysfs-bus-rapidio   |  23 +-
>  .../ABI/testing/sysfs-bus-thunderbolt         |  40 +--
>  Documentation/ABI/testing/sysfs-bus-usb       |  30 ++-
>  .../testing/sysfs-bus-usb-devices-usbsevseg   |   7 +-
>  Documentation/ABI/testing/sysfs-bus-vfio-mdev |  10 +-
>  Documentation/ABI/testing/sysfs-class-cxl     |  15 +-
>  Documentation/ABI/testing/sysfs-class-led     |   2 +-
>  .../testing/sysfs-class-led-driver-el15203000 | 229 ++++++++---------
>  .../ABI/testing/sysfs-class-led-driver-sc27xx |   4 +-
>  Documentation/ABI/testing/sysfs-class-mic     |  52 ++--
>  Documentation/ABI/testing/sysfs-class-ocxl    |   3 +
>  Documentation/ABI/testing/sysfs-class-power   |  73 +++++-
>  .../ABI/testing/sysfs-class-power-twl4030     |  33 +--
>  Documentation/ABI/testing/sysfs-class-rc      |  30 ++-
>  .../ABI/testing/sysfs-class-scsi_host         |   7 +-
>  Documentation/ABI/testing/sysfs-class-typec   |  12 +-
>  .../testing/sysfs-devices-platform-ACPI-TAD   |   4 +
>  .../ABI/testing/sysfs-devices-platform-docg3  |  10 +-
>  .../sysfs-devices-platform-sh_mobile_lcdc_fb  |   8 +-
>  .../ABI/testing/sysfs-devices-system-cpu      |  99 +++++---
>  .../ABI/testing/sysfs-devices-system-ibm-rtl  |   6 +-
>  .../testing/sysfs-driver-bd9571mwv-regulator  |   4 +
>  Documentation/ABI/testing/sysfs-driver-genwqe |  11 +-
>  .../testing/sysfs-driver-hid-logitech-lg4ff   |  18 +-
>  .../ABI/testing/sysfs-driver-hid-wiimote      |  11 +-
>  .../ABI/testing/sysfs-driver-samsung-laptop   |  13 +-
>  .../ABI/testing/sysfs-driver-toshiba_acpi     |  26 ++
>  .../ABI/testing/sysfs-driver-toshiba_haps     |   2 +
>  Documentation/ABI/testing/sysfs-driver-wacom  |   4 +-
>  Documentation/ABI/testing/sysfs-firmware-acpi | 237 +++++++++---------
>  .../ABI/testing/sysfs-firmware-dmi-entries    |  50 ++--
>  Documentation/ABI/testing/sysfs-firmware-gsmi |   2 +-
>  .../ABI/testing/sysfs-firmware-memmap         |  16 +-
>  Documentation/ABI/testing/sysfs-fs-ext4       |   4 +-
>  .../ABI/testing/sysfs-hypervisor-xen          |  13 +-
>  .../ABI/testing/sysfs-kernel-boot_params      |  23 +-
>  .../ABI/testing/sysfs-kernel-mm-hugepages     |  12 +-
>  .../ABI/testing/sysfs-platform-asus-laptop    |  21 +-
>  .../ABI/testing/sysfs-platform-asus-wmi       |   1 +
>  Documentation/ABI/testing/sysfs-platform-at91 |  10 +-
>  .../ABI/testing/sysfs-platform-eeepc-laptop   |  14 +-
>  .../ABI/testing/sysfs-platform-ideapad-laptop |   9 +-
>  .../sysfs-platform-intel-wmi-thunderbolt      |   1 +
>  .../ABI/testing/sysfs-platform-sst-atom       |  13 +-
>  .../ABI/testing/sysfs-platform-usbip-vudc     |  11 +-
>  Documentation/ABI/testing/sysfs-ptp           |   2 +-
>  74 files changed, 1322 insertions(+), 865 deletions(-)
> 

Hi Mauro,

[...]

>  
> +What:		/sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> +KernelVersion:	4.12
> +Contact:	benjamin.gaignard@st.com
> +Description:
> +		Reading returns the list possible quadrature modes.
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode
> +KernelVersion:	4.12
> +Contact:	benjamin.gaignard@st.com
> +Description:
> +		Configure the device counter quadrature modes:
> +
> +		channel_A:
> +			Encoder A input servers as the count input and B as
> +			the UP/DOWN direction control input.
> +
> +		channel_B:
> +			Encoder B input serves as the count input and A as
> +			the UP/DOWN direction control input.
> +
> +		quadrature:
> +			Encoder A and B inputs are mixed to get direction
> +			and count with a scale of 0.25.
> +

I just noticed that since Jonathan question in v1.

Above ABI has been moved in the past as discussed in [1]. You can take a
look at:
b299d00 IIO: stm32: Remove quadrature related functions from trigger driver

Could you please remove the above chunk ?

With that, for the stm32 part:
Acked-by: Fabrice Gasnier <fabrice.gasnier@st.com>

[1] https://lkml.org/lkml/2019/5/7/698

Best Regards,
Fabrice

>  What:		/sys/bus/iio/devices/iio:deviceX/in_count_enable_mode_available
>  KernelVersion:	4.12
>  Contact:	benjamin.gaignard@st.com
> @@ -104,6 +146,7 @@ Description:
>  		Configure the device counter enable modes, in all case
>  		counting direction is set by in_count0_count_direction
>  		attribute and the counter is clocked by the internal clock.
> +
>  		always:
>  			Counter is always ON.
>  
> diff --git a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc
> index 7fd2601c2831..a74252e580a5 100644
> --- a/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc
> +++ b/Documentation/ABI/testing/sysfs-bus-intel_th-devices-msc
> @@ -9,11 +9,13 @@ Date:		June 2015
>  KernelVersion:	4.3
>  Contact:	Alexander Shishkin <alexander.shishkin@linux.intel.com>
>  Description:	(RW) Configure MSC operating mode:
> +
>  		  - "single", for contiguous buffer mode (high-order alloc);
>  		  - "multi", for multiblock mode;
>  		  - "ExI", for DCI handler mode;
>  		  - "debug", for debug mode;
>  		  - any of the currently loaded buffer sinks.
> +
>  		If operating mode changes, existing buffer is deallocated,
>  		provided there are no active users and tracing is not enabled,
>  		otherwise the write will fail.
> @@ -23,10 +25,12 @@ Date:		June 2015
>  KernelVersion:	4.3
>  Contact:	Alexander Shishkin <alexander.shishkin@linux.intel.com>
>  Description:	(RW) Configure MSC buffer size for "single" or "multi" modes.
> +
>  		In single mode, this is a single number of pages, has to be
>  		power of 2. In multiblock mode, this is a comma-separated list
>  		of numbers of pages for each window to be allocated. Number of
>  		windows is not limited.
> +
>  		Writing to this file deallocates existing buffer (provided
>  		there are no active users and tracing is not enabled) and then
>  		allocates a new one.
> diff --git a/Documentation/ABI/testing/sysfs-bus-nfit b/Documentation/ABI/testing/sysfs-bus-nfit
> index e4f76e7eab93..63ef0b9ecce7 100644
> --- a/Documentation/ABI/testing/sysfs-bus-nfit
> +++ b/Documentation/ABI/testing/sysfs-bus-nfit
> @@ -1,4 +1,4 @@
> -For all of the nmem device attributes under nfit/*, see the 'NVDIMM Firmware
> +For all of the nmem device attributes under ``nfit/*``, see the 'NVDIMM Firmware
>  Interface Table (NFIT)' section in the ACPI specification
>  (http://www.uefi.org/specifications) for more details.
>  
> diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats b/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats
> index 3c9a8c4a25eb..860db53037a5 100644
> --- a/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats
> +++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats
> @@ -1,6 +1,6 @@
> -==========================
>  PCIe Device AER statistics
> -==========================
> +--------------------------
> +
>  These attributes show up under all the devices that are AER capable. These
>  statistical counters indicate the errors "as seen/reported by the device".
>  Note that this may mean that if an endpoint is causing problems, the AER
> @@ -17,19 +17,18 @@ Description:	List of correctable errors seen and reported by this
>  		PCI device using ERR_COR. Note that since multiple errors may
>  		be reported using a single ERR_COR message, thus
>  		TOTAL_ERR_COR at the end of the file may not match the actual
> -		total of all the errors in the file. Sample output:
> --------------------------------------------------------------------------
> -localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_correctable
> -Receiver Error 2
> -Bad TLP 0
> -Bad DLLP 0
> -RELAY_NUM Rollover 0
> -Replay Timer Timeout 0
> -Advisory Non-Fatal 0
> -Corrected Internal Error 0
> -Header Log Overflow 0
> -TOTAL_ERR_COR 2
> --------------------------------------------------------------------------
> +		total of all the errors in the file. Sample output::
> +
> +		    localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_correctable
> +		    Receiver Error 2
> +		    Bad TLP 0
> +		    Bad DLLP 0
> +		    RELAY_NUM Rollover 0
> +		    Replay Timer Timeout 0
> +		    Advisory Non-Fatal 0
> +		    Corrected Internal Error 0
> +		    Header Log Overflow 0
> +		    TOTAL_ERR_COR 2
>  
>  What:		/sys/bus/pci/devices/<dev>/aer_dev_fatal
>  Date:		July 2018
> @@ -39,28 +38,27 @@ Description:	List of uncorrectable fatal errors seen and reported by this
>  		PCI device using ERR_FATAL. Note that since multiple errors may
>  		be reported using a single ERR_FATAL message, thus
>  		TOTAL_ERR_FATAL at the end of the file may not match the actual
> -		total of all the errors in the file. Sample output:
> --------------------------------------------------------------------------
> -localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_fatal
> -Undefined 0
> -Data Link Protocol 0
> -Surprise Down Error 0
> -Poisoned TLP 0
> -Flow Control Protocol 0
> -Completion Timeout 0
> -Completer Abort 0
> -Unexpected Completion 0
> -Receiver Overflow 0
> -Malformed TLP 0
> -ECRC 0
> -Unsupported Request 0
> -ACS Violation 0
> -Uncorrectable Internal Error 0
> -MC Blocked TLP 0
> -AtomicOp Egress Blocked 0
> -TLP Prefix Blocked Error 0
> -TOTAL_ERR_FATAL 0
> --------------------------------------------------------------------------
> +		total of all the errors in the file. Sample output::
> +
> +		    localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_fatal
> +		    Undefined 0
> +		    Data Link Protocol 0
> +		    Surprise Down Error 0
> +		    Poisoned TLP 0
> +		    Flow Control Protocol 0
> +		    Completion Timeout 0
> +		    Completer Abort 0
> +		    Unexpected Completion 0
> +		    Receiver Overflow 0
> +		    Malformed TLP 0
> +		    ECRC 0
> +		    Unsupported Request 0
> +		    ACS Violation 0
> +		    Uncorrectable Internal Error 0
> +		    MC Blocked TLP 0
> +		    AtomicOp Egress Blocked 0
> +		    TLP Prefix Blocked Error 0
> +		    TOTAL_ERR_FATAL 0
>  
>  What:		/sys/bus/pci/devices/<dev>/aer_dev_nonfatal
>  Date:		July 2018
> @@ -70,32 +68,31 @@ Description:	List of uncorrectable nonfatal errors seen and reported by this
>  		PCI device using ERR_NONFATAL. Note that since multiple errors
>  		may be reported using a single ERR_FATAL message, thus
>  		TOTAL_ERR_NONFATAL at the end of the file may not match the
> -		actual total of all the errors in the file. Sample output:
> --------------------------------------------------------------------------
> -localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_nonfatal
> -Undefined 0
> -Data Link Protocol 0
> -Surprise Down Error 0
> -Poisoned TLP 0
> -Flow Control Protocol 0
> -Completion Timeout 0
> -Completer Abort 0
> -Unexpected Completion 0
> -Receiver Overflow 0
> -Malformed TLP 0
> -ECRC 0
> -Unsupported Request 0
> -ACS Violation 0
> -Uncorrectable Internal Error 0
> -MC Blocked TLP 0
> -AtomicOp Egress Blocked 0
> -TLP Prefix Blocked Error 0
> -TOTAL_ERR_NONFATAL 0
> --------------------------------------------------------------------------
> +		actual total of all the errors in the file. Sample output::
> +
> +		    localhost /sys/devices/pci0000:00/0000:00:1c.0 # cat aer_dev_nonfatal
> +		    Undefined 0
> +		    Data Link Protocol 0
> +		    Surprise Down Error 0
> +		    Poisoned TLP 0
> +		    Flow Control Protocol 0
> +		    Completion Timeout 0
> +		    Completer Abort 0
> +		    Unexpected Completion 0
> +		    Receiver Overflow 0
> +		    Malformed TLP 0
> +		    ECRC 0
> +		    Unsupported Request 0
> +		    ACS Violation 0
> +		    Uncorrectable Internal Error 0
> +		    MC Blocked TLP 0
> +		    AtomicOp Egress Blocked 0
> +		    TLP Prefix Blocked Error 0
> +		    TOTAL_ERR_NONFATAL 0
>  
> -============================
>  PCIe Rootport AER statistics
> -============================
> +----------------------------
> +
>  These attributes show up under only the rootports (or root complex event
>  collectors) that are AER capable. These indicate the number of error messages as
>  "reported to" the rootport. Please note that the rootports also transmit
> diff --git a/Documentation/ABI/testing/sysfs-bus-rapidio b/Documentation/ABI/testing/sysfs-bus-rapidio
> index 13208b27dd87..634ea207a50a 100644
> --- a/Documentation/ABI/testing/sysfs-bus-rapidio
> +++ b/Documentation/ABI/testing/sysfs-bus-rapidio
> @@ -4,24 +4,27 @@ Description:
>  		an individual subdirectory with the following name format of
>  		device_name "nn:d:iiii", where:
>  
> -		nn   - two-digit hexadecimal ID of RapidIO network where the
> +		====   ========================================================
> +		nn     two-digit hexadecimal ID of RapidIO network where the
>  		       device resides
> -		d    - device type: 'e' - for endpoint or 's' - for switch
> -		iiii - four-digit device destID for endpoints, or switchID for
> +		d      device type: 'e' - for endpoint or 's' - for switch
> +		iiii   four-digit device destID for endpoints, or switchID for
>  		       switches
> +		====   ========================================================
>  
>  		For example, below is a list of device directories that
>  		represents a typical RapidIO network with one switch, one host,
>  		and two agent endpoints, as it is seen by the enumerating host
> -		(with destID = 1):
> +		(with destID = 1)::
>  
> -		/sys/bus/rapidio/devices/00:e:0000
> -		/sys/bus/rapidio/devices/00:e:0002
> -		/sys/bus/rapidio/devices/00:s:0001
> +		  /sys/bus/rapidio/devices/00:e:0000
> +		  /sys/bus/rapidio/devices/00:e:0002
> +		  /sys/bus/rapidio/devices/00:s:0001
>  
> -		NOTE: An enumerating or discovering endpoint does not create a
> -		sysfs entry for itself, this is why an endpoint with destID=1 is
> -		not shown in the list.
> +		NOTE:
> +		  An enumerating or discovering endpoint does not create a
> +		  sysfs entry for itself, this is why an endpoint with destID=1
> +		  is not shown in the list.
>  
>  Attributes Common for All RapidIO Devices
>  -----------------------------------------
> diff --git a/Documentation/ABI/testing/sysfs-bus-thunderbolt b/Documentation/ABI/testing/sysfs-bus-thunderbolt
> index dd565c378b40..171127294674 100644
> --- a/Documentation/ABI/testing/sysfs-bus-thunderbolt
> +++ b/Documentation/ABI/testing/sysfs-bus-thunderbolt
> @@ -37,16 +37,18 @@ Contact:	thunderbolt-software@lists.01.org
>  Description:	This attribute holds current Thunderbolt security level
>  		set by the system BIOS. Possible values are:
>  
> -		none: All devices are automatically authorized
> -		user: Devices are only authorized based on writing
> -		      appropriate value to the authorized attribute
> -		secure: Require devices that support secure connect at
> -			minimum. User needs to authorize each device.
> -		dponly: Automatically tunnel Display port (and USB). No
> -			PCIe tunnels are created.
> -		usbonly: Automatically tunnel USB controller of the
> +		=======  ==================================================
> +		none     All devices are automatically authorized
> +		user     Devices are only authorized based on writing
> +		         appropriate value to the authorized attribute
> +		secure   Require devices that support secure connect at
> +			 minimum. User needs to authorize each device.
> +		dponly   Automatically tunnel Display port (and USB). No
> +			 PCIe tunnels are created.
> +		usbonly  Automatically tunnel USB controller of the
>  			 connected Thunderbolt dock (and Display Port). All
>  			 PCIe links downstream of the dock are removed.
> +		=======  ==================================================
>  
>  What: /sys/bus/thunderbolt/devices/.../authorized
>  Date:		Sep 2017
> @@ -61,17 +63,23 @@ Description:	This attribute is used to authorize Thunderbolt devices
>  		yet authorized.
>  
>  		Possible values are supported:
> -		1: The device will be authorized and connected
> +
> +		==  ===========================================
> +		1   The device will be authorized and connected
> +		==  ===========================================
>  
>  		When key attribute contains 32 byte hex string the possible
>  		values are:
> -		1: The 32 byte hex string is added to the device NVM and
> -		   the device is authorized.
> -		2: Send a challenge based on the 32 byte hex string. If the
> -		   challenge response from device is valid, the device is
> -		   authorized. In case of failure errno will be ENOKEY if
> -		   the device did not contain a key at all, and
> -		   EKEYREJECTED if the challenge response did not match.
> +
> +		==  ========================================================
> +		1   The 32 byte hex string is added to the device NVM and
> +		    the device is authorized.
> +		2   Send a challenge based on the 32 byte hex string. If the
> +		    challenge response from device is valid, the device is
> +		    authorized. In case of failure errno will be ENOKEY if
> +		    the device did not contain a key at all, and
> +		    EKEYREJECTED if the challenge response did not match.
> +		==  ========================================================
>  
>  What: /sys/bus/thunderbolt/devices/.../boot
>  Date:		Jun 2018
> diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb
> index 614d216dff1d..e449b8374f6a 100644
> --- a/Documentation/ABI/testing/sysfs-bus-usb
> +++ b/Documentation/ABI/testing/sysfs-bus-usb
> @@ -72,24 +72,27 @@ Description:
>  		table at compile time. The format for the device ID is:
>  		idVendor idProduct bInterfaceClass RefIdVendor RefIdProduct
>  		The vendor ID and device ID fields are required, the
> -		rest is optional. The Ref* tuple can be used to tell the
> +		rest is optional. The `Ref*` tuple can be used to tell the
>  		driver to use the same driver_data for the new device as
>  		it is used for the reference device.
>  		Upon successfully adding an ID, the driver will probe
> -		for the device and attempt to bind to it.  For example:
> -		# echo "8086 10f5" > /sys/bus/usb/drivers/foo/new_id
> +		for the device and attempt to bind to it.  For example::
> +
> +		  # echo "8086 10f5" > /sys/bus/usb/drivers/foo/new_id
>  
>  		Here add a new device (0458:7045) using driver_data from
> -		an already supported device (0458:704c):
> -		# echo "0458 7045 0 0458 704c" > /sys/bus/usb/drivers/foo/new_id
> +		an already supported device (0458:704c)::
> +
> +		  # echo "0458 7045 0 0458 704c" > /sys/bus/usb/drivers/foo/new_id
>  
>  		Reading from this file will list all dynamically added
>  		device IDs in the same format, with one entry per
> -		line. For example:
> -		# cat /sys/bus/usb/drivers/foo/new_id
> -		8086 10f5
> -		dead beef 06
> -		f00d cafe
> +		line. For example::
> +
> +		  # cat /sys/bus/usb/drivers/foo/new_id
> +		  8086 10f5
> +		  dead beef 06
> +		  f00d cafe
>  
>  		The list will be truncated at PAGE_SIZE bytes due to
>  		sysfs restrictions.
> @@ -209,6 +212,7 @@ Description:
>  		advance, and behaves well according to the specification.
>  		This attribute is a bit-field that controls the behavior of
>  		a specific port:
> +
>  		 - Bit 0 of this field selects the "old" enumeration scheme,
>  		   as it is considerably faster (it only causes one USB reset
>  		   instead of 2).
> @@ -233,10 +237,10 @@ Description:
>  		poll() for monitoring changes to this value in user space.
>  
>  		Any time this value changes the corresponding hub device will send a
> -		udev event with the following attributes:
> +		udev event with the following attributes::
>  
> -		OVER_CURRENT_PORT=/sys/bus/usb/devices/.../(hub interface)/portX
> -		OVER_CURRENT_COUNT=[current value of this sysfs attribute]
> +		  OVER_CURRENT_PORT=/sys/bus/usb/devices/.../(hub interface)/portX
> +		  OVER_CURRENT_COUNT=[current value of this sysfs attribute]
>  
>  What:		/sys/bus/usb/devices/.../(hub interface)/portX/usb3_lpm_permit
>  Date:		November 2015
> diff --git a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
> index 9ade80f81f96..2f86e4223bfc 100644
> --- a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
> +++ b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
> @@ -12,8 +12,11 @@ KernelVersion:	2.6.26
>  Contact:	Harrison Metzger <harrisonmetz@gmail.com>
>  Description:	Controls the devices display mode.
>  		For a 6 character display the values are
> +
>  			MSB 0x06; LSB 0x3F, and
> +
>  		for an 8 character display the values are
> +
>  			MSB 0x08; LSB 0xFF.
>  
>  What:		/sys/bus/usb/.../textmode
> @@ -37,7 +40,7 @@ KernelVersion:	2.6.26
>  Contact:	Harrison Metzger <harrisonmetz@gmail.com>
>  Description:	Controls the decimal places on the device.
>  		To set the nth decimal place, give this field
> -		the value of 10 ** n. Assume this field has
> +		the value of ``10 ** n``. Assume this field has
>  		the value k and has 1 or more decimal places set,
>  		to set the mth place (where m is not already set),
> -		change this fields value to k + 10 ** m.
> +		change this fields value to ``k + 10 ** m``.
> diff --git a/Documentation/ABI/testing/sysfs-bus-vfio-mdev b/Documentation/ABI/testing/sysfs-bus-vfio-mdev
> index 452dbe39270e..59fc804265db 100644
> --- a/Documentation/ABI/testing/sysfs-bus-vfio-mdev
> +++ b/Documentation/ABI/testing/sysfs-bus-vfio-mdev
> @@ -28,8 +28,9 @@ Description:
>  		Writing UUID to this file will create mediated device of
>  		type <type-id> for parent device <device>. This is a
>  		write-only file.
> -		For example:
> -		# echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" >	\
> +		For example::
> +
> +		  # echo "83b8f4f2-509f-382f-3c1e-e6bfe0fa1001" >	\
>  		       /sys/devices/foo/mdev_supported_types/foo-1/create
>  
>  What:           /sys/.../mdev_supported_types/<type-id>/devices/
> @@ -107,5 +108,6 @@ Description:
>  		Writing '1' to this file destroys the mediated device. The
>  		vendor driver can fail the remove() callback if that device
>  		is active and the vendor driver doesn't support hot unplug.
> -		Example:
> -		# echo 1 > /sys/bus/mdev/devices/<UUID>/remove
> +		Example::
> +
> +		  # echo 1 > /sys/bus/mdev/devices/<UUID>/remove
> diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl
> index 7970e3713e70..a6f51a104c44 100644
> --- a/Documentation/ABI/testing/sysfs-class-cxl
> +++ b/Documentation/ABI/testing/sysfs-class-cxl
> @@ -72,11 +72,16 @@ Description:    read/write
>                  when performing the START_WORK ioctl. Only applicable when
>                  running under hashed page table mmu.
>                  Possible values:
> -                        none: No prefaulting (default)
> -                        work_element_descriptor: Treat the work element
> -                                 descriptor as an effective address and
> -                                 prefault what it points to.
> -                        all: all segments process calling START_WORK maps.
> +
> +                =======================  ======================================
> +		none			 No prefaulting (default)
> +		work_element_descriptor  Treat the work element
> +					 descriptor as an effective address and
> +					 prefault what it points to.
> +                all			 all segments process calling
> +					 START_WORK maps.
> +                =======================  ======================================
> +
>  Users:		https://github.com/ibm-capi/libcxl
>  
>  What:           /sys/class/cxl/<afu>/reset
> diff --git a/Documentation/ABI/testing/sysfs-class-led b/Documentation/ABI/testing/sysfs-class-led
> index 5f67f7ab277b..65e040978f73 100644
> --- a/Documentation/ABI/testing/sysfs-class-led
> +++ b/Documentation/ABI/testing/sysfs-class-led
> @@ -50,7 +50,7 @@ Description:
>  		You can change triggers in a similar manner to the way an IO
>  		scheduler is chosen. Trigger specific parameters can appear in
>  		/sys/class/leds/<led> once a given trigger is selected. For
> -		their documentation see sysfs-class-led-trigger-*.
> +		their documentation see `sysfs-class-led-trigger-*`.
>  
>  What:		/sys/class/leds/<led>/inverted
>  Date:		January 2011
> diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-el15203000 b/Documentation/ABI/testing/sysfs-class-led-driver-el15203000
> index f520ece9b64c..69befe947d7e 100644
> --- a/Documentation/ABI/testing/sysfs-class-led-driver-el15203000
> +++ b/Documentation/ABI/testing/sysfs-class-led-driver-el15203000
> @@ -6,127 +6,132 @@ Description:
>  		The LEDs board supports only predefined patterns by firmware
>  		for specific LEDs.
>  
> -		Breathing mode for Screen frame light tube:
> -		"0 4000 1 4000"
> +		Breathing mode for Screen frame light tube::
>  
> -		    ^
> -		    |
> -		Max-|     ---
> -		    |    /   \
> -		    |   /     \
> -		    |  /       \     /
> -		    | /         \   /
> -		Min-|-           ---
> -		    |
> -		    0------4------8--> time (sec)
> +		    "0 4000 1 4000"
>  
> -		Cascade mode for Pipe LED:
> -		"1 800 2 800 4 800 8 800 16 800"
> +			^
> +			|
> +		    Max-|     ---
> +			|    /   \
> +			|   /     \
> +			|  /       \     /
> +			| /         \   /
> +		    Min-|-           ---
> +			|
> +			0------4------8--> time (sec)
>  
> -		      ^
> -		      |
> -		0 On -|----+                   +----+                   +---
> -		      |    |                   |    |                   |
> -		  Off-|    +-------------------+    +-------------------+
> -		      |
> -		1 On -|    +----+                   +----+
> -		      |    |    |                   |    |
> -		  Off |----+    +-------------------+    +------------------
> -		      |
> -		2 On -|         +----+                   +----+
> -		      |         |    |                   |    |
> -		  Off-|---------+    +-------------------+    +-------------
> -		      |
> -		3 On -|              +----+                   +----+
> -		      |              |    |                   |    |
> -		  Off-|--------------+    +-------------------+    +--------
> -		      |
> -		4 On -|                   +----+                   +----+
> -		      |                   |    |                   |    |
> -		  Off-|-------------------+    +-------------------+    +---
> -		      |
> -		      0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
> +		Cascade mode for Pipe LED::
>  
> -		Inverted cascade mode for Pipe LED:
> -		"30 800 29 800 27 800 23 800 15 800"
> +		    "1 800 2 800 4 800 8 800 16 800"
>  
> -		      ^
> -		      |
> -		0 On -|    +-------------------+    +-------------------+
> -		      |    |                   |    |                   |
> -		  Off-|----+                   +----+                   +---
> -		      |
> -		1 On -|----+    +-------------------+    +------------------
> -		      |    |    |                   |    |
> -		  Off |    +----+                   +----+
> -		      |
> -		2 On -|---------+    +-------------------+    +-------------
> -		      |         |    |                   |    |
> -		  Off-|         +----+                   +----+
> -		      |
> -		3 On -|--------------+    +-------------------+    +--------
> -		      |              |    |                   |    |
> -		  Off-|              +----+                   +----+
> -		      |
> -		4 On -|-------------------+    +-------------------+    +---
> -		      |                   |    |                   |    |
> -		  Off-|                   +----+                   +----+
> -		      |
> -		      0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
> +			^
> +			|
> +		    0 On -|----+                   +----+                   +---
> +			|    |                   |    |                   |
> +		    Off-|    +-------------------+    +-------------------+
> +			|
> +		    1 On -|    +----+                   +----+
> +			|    |    |                   |    |
> +		    Off |----+    +-------------------+    +------------------
> +			|
> +		    2 On -|         +----+                   +----+
> +			|         |    |                   |    |
> +		    Off-|---------+    +-------------------+    +-------------
> +			|
> +		    3 On -|              +----+                   +----+
> +			|              |    |                   |    |
> +		    Off-|--------------+    +-------------------+    +--------
> +			|
> +		    4 On -|                   +----+                   +----+
> +			|                   |    |                   |    |
> +		    Off-|-------------------+    +-------------------+    +---
> +			|
> +			0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
>  
> -		Bounce mode for Pipe LED:
> -		"1 800 2 800 4 800 8 800 16 800 16 800 8 800 4 800 2 800 1 800"
> +		Inverted cascade mode for Pipe LED::
>  
> -		      ^
> -		      |
> -		0 On -|----+                                       +--------
> -		      |    |                                       |
> -		  Off-|    +---------------------------------------+
> -		      |
> -		1 On -|    +----+                             +----+
> -		      |    |    |                             |    |
> -		  Off |----+    +-----------------------------+    +--------
> -		      |
> -		2 On -|         +----+                   +----+
> -		      |         |    |                   |    |
> -		  Off-|---------+    +-------------------+    +-------------
> -		      |
> -		3 On -|              +----+         +----+
> -		      |              |    |         |    |
> -		  Off-|--------------+    +---------+    +------------------
> -		      |
> -		4 On -|                   +---------+
> -		      |                   |         |
> -		  Off-|-------------------+         +-----------------------
> -		      |
> -		      0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
> +		    "30 800 29 800 27 800 23 800 15 800"
>  
> -		Inverted bounce mode for Pipe LED:
> -		"30 800 29 800 27 800 23 800 15 800 15 800 23 800 27 800 29 800 30 800"
> +			^
> +			|
> +		    0 On -|    +-------------------+    +-------------------+
> +			|    |                   |    |                   |
> +		    Off-|----+                   +----+                   +---
> +			|
> +		    1 On -|----+    +-------------------+    +------------------
> +			|    |    |                   |    |
> +		    Off |    +----+                   +----+
> +			|
> +		    2 On -|---------+    +-------------------+    +-------------
> +			|         |    |                   |    |
> +		    Off-|         +----+                   +----+
> +			|
> +		    3 On -|--------------+    +-------------------+    +--------
> +			|              |    |                   |    |
> +		    Off-|              +----+                   +----+
> +			|
> +		    4 On -|-------------------+    +-------------------+    +---
> +			|                   |    |                   |    |
> +		    Off-|                   +----+                   +----+
> +			|
> +			0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
>  
> -		      ^
> -		      |
> -		0 On -|    +---------------------------------------+
> -		      |    |                                       |
> -		  Off-|----+                                       +--------
> -		      |
> -		1 On -|----+    +-----------------------------+    +--------
> -		      |    |    |                             |    |
> -		  Off |    +----+                             +----+
> -		      |
> -		2 On -|---------+    +-------------------+    +-------------
> -		      |         |    |                   |    |
> -		  Off-|         +----+                   +----+
> -		      |
> -		3 On -|--------------+    +---------+    +------------------
> -		      |              |    |         |    |
> -		  Off-|              +----+         +----+
> -		      |
> -		4 On -|-------------------+         +-----------------------
> -		      |                   |         |
> -		  Off-|                   +---------+
> -		      |
> -		      0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
> +		Bounce mode for Pipe LED::
> +
> +		    "1 800 2 800 4 800 8 800 16 800 16 800 8 800 4 800 2 800 1 800"
> +
> +			^
> +			|
> +		    0 On -|----+                                       +--------
> +			|    |                                       |
> +		    Off-|    +---------------------------------------+
> +			|
> +		    1 On -|    +----+                             +----+
> +			|    |    |                             |    |
> +		    Off |----+    +-----------------------------+    +--------
> +			|
> +		    2 On -|         +----+                   +----+
> +			|         |    |                   |    |
> +		    Off-|---------+    +-------------------+    +-------------
> +			|
> +		    3 On -|              +----+         +----+
> +			|              |    |         |    |
> +		    Off-|--------------+    +---------+    +------------------
> +			|
> +		    4 On -|                   +---------+
> +			|                   |         |
> +		    Off-|-------------------+         +-----------------------
> +			|
> +			0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
> +
> +		Inverted bounce mode for Pipe LED::
> +
> +		    "30 800 29 800 27 800 23 800 15 800 15 800 23 800 27 800 29 800 30 800"
> +
> +			^
> +			|
> +		    0 On -|    +---------------------------------------+
> +			|    |                                       |
> +		    Off-|----+                                       +--------
> +			|
> +		    1 On -|----+    +-----------------------------+    +--------
> +			|    |    |                             |    |
> +		    Off |    +----+                             +----+
> +			|
> +		    2 On -|---------+    +-------------------+    +-------------
> +			|         |    |                   |    |
> +		    Off-|         +----+                   +----+
> +			|
> +		    3 On -|--------------+    +---------+    +------------------
> +			|              |    |         |    |
> +		    Off-|              +----+         +----+
> +			|
> +		    4 On -|-------------------+         +-----------------------
> +			|                   |         |
> +		    Off-|                   +---------+
> +			|
> +			0---0.8--1.6--2.4--3.2---4---4.8--5.6--6.4--7.2---8--> time (sec)
>  
>  What:		/sys/class/leds/<led>/repeat
>  Date:		September 2019
> diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx b/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx
> index 45b1e605d355..215482379580 100644
> --- a/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx
> +++ b/Documentation/ABI/testing/sysfs-class-led-driver-sc27xx
> @@ -12,8 +12,8 @@ Description:
>  		format, we should set brightness as 0 for rise stage, fall
>  		stage and low stage.
>  
> -		Min stage duration: 125 ms
> -		Max stage duration: 31875 ms
> +		- Min stage duration: 125 ms
> +		- Max stage duration: 31875 ms
>  
>  		Since the stage duration step is 125 ms, the duration should be
>  		a multiplier of 125, like 125ms, 250ms, 375ms, 500ms ... 31875ms.
> diff --git a/Documentation/ABI/testing/sysfs-class-mic b/Documentation/ABI/testing/sysfs-class-mic
> index 6ef682603179..bd0e780c3760 100644
> --- a/Documentation/ABI/testing/sysfs-class-mic
> +++ b/Documentation/ABI/testing/sysfs-class-mic
> @@ -41,24 +41,33 @@ Description:
>  		When read, this entry provides the current state of an Intel
>  		MIC device in the context of the card OS. Possible values that
>  		will be read are:
> -		"ready" - The MIC device is ready to boot the card OS. On
> -		reading this entry after an OSPM resume, a "boot" has to be
> -		written to this entry if the card was previously shutdown
> -		during OSPM suspend.
> -		"booting" - The MIC device has initiated booting a card OS.
> -		"online" - The MIC device has completed boot and is online
> -		"shutting_down" - The card OS is shutting down.
> -		"resetting" - A reset has been initiated for the MIC device
> -		"reset_failed" - The MIC device has failed to reset.
> +
> +
> +		===============  ===============================================
> +		"ready"		 The MIC device is ready to boot the card OS.
> +				 On reading this entry after an OSPM resume,
> +				 a "boot" has to be written to this entry if
> +				 the card was previously shutdown during OSPM
> +				 suspend.
> +		"booting"	 The MIC device has initiated booting a card OS.
> +		"online"	 The MIC device has completed boot and is online
> +		"shutting_down"	 The card OS is shutting down.
> +		"resetting"	 A reset has been initiated for the MIC device
> +		"reset_failed"	 The MIC device has failed to reset.
> +		===============  ===============================================
>  
>  		When written, this sysfs entry triggers different state change
>  		operations depending upon the current state of the card OS.
>  		Acceptable values are:
> -		"boot" - Boot the card OS image specified by the combination
> -			 of firmware, ramdisk, cmdline and bootmode
> -			sysfs entries.
> -		"reset" - Initiates device reset.
> -		"shutdown" - Initiates card OS shutdown.
> +
> +
> +		==========  ===================================================
> +		"boot"      Boot the card OS image specified by the combination
> +			    of firmware, ramdisk, cmdline and bootmode
> +			    sysfs entries.
> +		"reset"     Initiates device reset.
> +		"shutdown"  Initiates card OS shutdown.
> +		==========  ===================================================
>  
>  What:		/sys/class/mic/mic(x)/shutdown_status
>  Date:		October 2013
> @@ -69,12 +78,15 @@ Description:
>  		OS can shutdown because of various reasons. When read, this
>  		entry provides the status on why the card OS was shutdown.
>  		Possible values are:
> -		"nop" -  shutdown status is not applicable, when the card OS is
> -			"online"
> -		"crashed" - Shutdown because of a HW or SW crash.
> -		"halted" - Shutdown because of a halt command.
> -		"poweroff" - Shutdown because of a poweroff command.
> -		"restart" - Shutdown because of a restart command.
> +
> +		==========  ===================================================
> +		"nop"       shutdown status is not applicable, when the card OS
> +			    is "online"
> +		"crashed"   Shutdown because of a HW or SW crash.
> +		"halted"    Shutdown because of a halt command.
> +		"poweroff"  Shutdown because of a poweroff command.
> +		"restart"   Shutdown because of a restart command.
> +		==========  ===================================================
>  
>  What:		/sys/class/mic/mic(x)/cmdline
>  Date:		October 2013
> diff --git a/Documentation/ABI/testing/sysfs-class-ocxl b/Documentation/ABI/testing/sysfs-class-ocxl
> index ae1276efa45a..bf33f4fda58f 100644
> --- a/Documentation/ABI/testing/sysfs-class-ocxl
> +++ b/Documentation/ABI/testing/sysfs-class-ocxl
> @@ -11,8 +11,11 @@ Contact:	linuxppc-dev@lists.ozlabs.org
>  Description:	read only
>  		Number of contexts for the AFU, in the format <n>/<max>
>  		where:
> +
> +			====	===============================================
>  			n:	number of currently active contexts, for debug
>  			max:	maximum number of contexts supported by the AFU
> +			====	===============================================
>  
>  What:		/sys/class/ocxl/<afu name>/pp_mmio_size
>  Date:		January 2018
> diff --git a/Documentation/ABI/testing/sysfs-class-power b/Documentation/ABI/testing/sysfs-class-power
> index dbccb2fcd7ce..d4319a04c302 100644
> --- a/Documentation/ABI/testing/sysfs-class-power
> +++ b/Documentation/ABI/testing/sysfs-class-power
> @@ -1,4 +1,4 @@
> -===== General Properties =====
> +**General Properties**
>  
>  What:		/sys/class/power_supply/<supply_name>/manufacturer
>  Date:		May 2007
> @@ -72,6 +72,7 @@ Description:
>  		critically low).
>  
>  		Access: Read, Write
> +
>  		Valid values: 0 - 100 (percent)
>  
>  What:		/sys/class/power_supply/<supply_name>/capacity_error_margin
> @@ -96,7 +97,9 @@ Description:
>  		Coarse representation of battery capacity.
>  
>  		Access: Read
> -		Valid values: "Unknown", "Critical", "Low", "Normal", "High",
> +
> +		Valid values:
> +			      "Unknown", "Critical", "Low", "Normal", "High",
>  			      "Full"
>  
>  What:		/sys/class/power_supply/<supply_name>/current_avg
> @@ -139,6 +142,7 @@ Description:
>  		throttling for thermal cooling or improving battery health.
>  
>  		Access: Read, Write
> +
>  		Valid values: Represented in microamps
>  
>  What:		/sys/class/power_supply/<supply_name>/charge_control_limit_max
> @@ -148,6 +152,7 @@ Description:
>  		Maximum legal value for the charge_control_limit property.
>  
>  		Access: Read
> +
>  		Valid values: Represented in microamps
>  
>  What:		/sys/class/power_supply/<supply_name>/charge_control_start_threshold
> @@ -168,6 +173,7 @@ Description:
>  		stop.
>  
>  		Access: Read, Write
> +
>  		Valid values: 0 - 100 (percent)
>  
>  What:		/sys/class/power_supply/<supply_name>/charge_type
> @@ -183,7 +189,9 @@ Description:
>  		different algorithm.
>  
>  		Access: Read, Write
> -		Valid values: "Unknown", "N/A", "Trickle", "Fast", "Standard",
> +
> +		Valid values:
> +			      "Unknown", "N/A", "Trickle", "Fast", "Standard",
>  			      "Adaptive", "Custom"
>  
>  What:		/sys/class/power_supply/<supply_name>/charge_term_current
> @@ -194,6 +202,7 @@ Description:
>  		when the battery is considered full and charging should end.
>  
>  		Access: Read
> +
>  		Valid values: Represented in microamps
>  
>  What:		/sys/class/power_supply/<supply_name>/health
> @@ -204,7 +213,9 @@ Description:
>  		functionality.
>  
>  		Access: Read
> -		Valid values: "Unknown", "Good", "Overheat", "Dead",
> +
> +		Valid values:
> +			      "Unknown", "Good", "Overheat", "Dead",
>  			      "Over voltage", "Unspecified failure", "Cold",
>  			      "Watchdog timer expire", "Safety timer expire",
>  			      "Over current", "Calibration required", "Warm",
> @@ -218,6 +229,7 @@ Description:
>  		for a battery charge cycle.
>  
>  		Access: Read
> +
>  		Valid values: Represented in microamps
>  
>  What:		/sys/class/power_supply/<supply_name>/present
> @@ -227,9 +239,13 @@ Description:
>  		Reports whether a battery is present or not in the system.
>  
>  		Access: Read
> +
>  		Valid values:
> +
> +			== =======
>  			0: Absent
>  			1: Present
> +			== =======
>  
>  What:		/sys/class/power_supply/<supply_name>/status
>  Date:		May 2007
> @@ -240,7 +256,9 @@ Description:
>  		used to enable/disable charging to the battery.
>  
>  		Access: Read, Write
> -		Valid values: "Unknown", "Charging", "Discharging",
> +
> +		Valid values:
> +			      "Unknown", "Charging", "Discharging",
>  			      "Not charging", "Full"
>  
>  What:		/sys/class/power_supply/<supply_name>/technology
> @@ -250,7 +268,9 @@ Description:
>  		Describes the battery technology supported by the supply.
>  
>  		Access: Read
> -		Valid values: "Unknown", "NiMH", "Li-ion", "Li-poly", "LiFe",
> +
> +		Valid values:
> +			      "Unknown", "NiMH", "Li-ion", "Li-poly", "LiFe",
>  			      "NiCd", "LiMn"
>  
>  What:		/sys/class/power_supply/<supply_name>/temp
> @@ -260,6 +280,7 @@ Description:
>  		Reports the current TBAT battery temperature reading.
>  
>  		Access: Read
> +
>  		Valid values: Represented in 1/10 Degrees Celsius
>  
>  What:		/sys/class/power_supply/<supply_name>/temp_alert_max
> @@ -274,6 +295,7 @@ Description:
>  		critically high, and charging has stopped).
>  
>  		Access: Read
> +
>  		Valid values: Represented in 1/10 Degrees Celsius
>  
>  What:		/sys/class/power_supply/<supply_name>/temp_alert_min
> @@ -289,6 +311,7 @@ Description:
>  		remedy the situation).
>  
>  		Access: Read
> +
>  		Valid values: Represented in 1/10 Degrees Celsius
>  
>  What:		/sys/class/power_supply/<supply_name>/temp_max
> @@ -299,6 +322,7 @@ Description:
>  		charging.
>  
>  		Access: Read
> +
>  		Valid values: Represented in 1/10 Degrees Celsius
>  
>  What:		/sys/class/power_supply/<supply_name>/temp_min
> @@ -309,6 +333,7 @@ Description:
>  		charging.
>  
>  		Access: Read
> +
>  		Valid values: Represented in 1/10 Degrees Celsius
>  
>  What:		/sys/class/power_supply/<supply_name>/voltage_avg,
> @@ -320,6 +345,7 @@ Description:
>  		which they average readings to smooth out the reported value.
>  
>  		Access: Read
> +
>  		Valid values: Represented in microvolts
>  
>  What:		/sys/class/power_supply/<supply_name>/voltage_max,
> @@ -330,6 +356,7 @@ Description:
>  		during charging.
>  
>  		Access: Read
> +
>  		Valid values: Represented in microvolts
>  
>  What:		/sys/class/power_supply/<supply_name>/voltage_min,
> @@ -340,6 +367,7 @@ Description:
>  		during discharging.
>  
>  		Access: Read
> +
>  		Valid values: Represented in microvolts
>  
>  What:		/sys/class/power_supply/<supply_name>/voltage_now,
> @@ -350,9 +378,10 @@ Description:
>  		This value is not averaged/smoothed.
>  
>  		Access: Read
> +
>  		Valid values: Represented in microvolts
>  
> -===== USB Properties =====
> +**USB Properties**
>  
>  What: 		/sys/class/power_supply/<supply_name>/current_avg
>  Date:		May 2007
> @@ -363,6 +392,7 @@ Description:
>  		average readings to smooth out the reported value.
>  
>  		Access: Read
> +
>  		Valid values: Represented in microamps
>  
>  
> @@ -373,6 +403,7 @@ Description:
>  		Reports the maximum IBUS current the supply can support.
>  
>  		Access: Read
> +
>  		Valid values: Represented in microamps
>  
>  What: 		/sys/class/power_supply/<supply_name>/current_now
> @@ -385,6 +416,7 @@ Description:
>  		within the reported min/max range.
>  
>  		Access: Read, Write
> +
>  		Valid values: Represented in microamps
>  
>  What:		/sys/class/power_supply/<supply_name>/input_current_limit
> @@ -399,6 +431,7 @@ Description:
>  		solved using power limit use input_current_limit.
>  
>  		Access: Read, Write
> +
>  		Valid values: Represented in microamps
>  
>  What:		/sys/class/power_supply/<supply_name>/input_voltage_limit
> @@ -441,10 +474,14 @@ Description:
>  		USB supply so voltage and current can be controlled).
>  
>  		Access: Read, Write
> +
>  		Valid values:
> +
> +			== ==================================================
>  			0: Offline
>  			1: Online Fixed - Fixed Voltage Supply
>  			2: Online Programmable - Programmable Voltage Supply
> +			== ==================================================
>  
>  What:		/sys/class/power_supply/<supply_name>/temp
>  Date:		May 2007
> @@ -455,6 +492,7 @@ Description:
>  		TJUNC temperature of an IC)
>  
>  		Access: Read
> +
>  		Valid values: Represented in 1/10 Degrees Celsius
>  
>  What:		/sys/class/power_supply/<supply_name>/temp_alert_max
> @@ -470,6 +508,7 @@ Description:
>  		remedy the situation).
>  
>  		Access: Read
> +
>  		Valid values: Represented in 1/10 Degrees Celsius
>  
>  What:		/sys/class/power_supply/<supply_name>/temp_alert_min
> @@ -485,6 +524,7 @@ Description:
>  		accordingly to remedy the situation).
>  
>  		Access: Read
> +
>  		Valid values: Represented in 1/10 Degrees Celsius
>  
>  What:		/sys/class/power_supply/<supply_name>/temp_max
> @@ -494,6 +534,7 @@ Description:
>  		Reports the maximum allowed supply temperature for operation.
>  
>  		Access: Read
> +
>  		Valid values: Represented in 1/10 Degrees Celsius
>  
>  What:		/sys/class/power_supply/<supply_name>/temp_min
> @@ -503,6 +544,7 @@ Description:
>  		Reports the mainimum allowed supply temperature for operation.
>  
>  		Access: Read
> +
>  		Valid values: Represented in 1/10 Degrees Celsius
>  
>  What: 		/sys/class/power_supply/<supply_name>/usb_type
> @@ -514,7 +556,9 @@ Description:
>  		is attached.
>  
>  		Access: Read-Only
> -		Valid values: "Unknown", "SDP", "DCP", "CDP", "ACA", "C", "PD",
> +
> +		Valid values:
> +			      "Unknown", "SDP", "DCP", "CDP", "ACA", "C", "PD",
>  			      "PD_DRP", "PD_PPS", "BrickID"
>  
>  What: 		/sys/class/power_supply/<supply_name>/voltage_max
> @@ -524,6 +568,7 @@ Description:
>  		Reports the maximum VBUS voltage the supply can support.
>  
>  		Access: Read
> +
>  		Valid values: Represented in microvolts
>  
>  What: 		/sys/class/power_supply/<supply_name>/voltage_min
> @@ -533,6 +578,7 @@ Description:
>  		Reports the minimum VBUS voltage the supply can support.
>  
>  		Access: Read
> +
>  		Valid values: Represented in microvolts
>  
>  What: 		/sys/class/power_supply/<supply_name>/voltage_now
> @@ -545,9 +591,10 @@ Description:
>  		within the reported min/max range.
>  
>  		Access: Read, Write
> +
>  		Valid values: Represented in microvolts
>  
> -===== Device Specific Properties =====
> +**Device Specific Properties**
>  
>  What:		/sys/class/power/ds2760-battery.*/charge_now
>  Date:		May 2010
> @@ -581,6 +628,7 @@ Description:
>  		will drop to 0 A) and will trigger interrupt.
>  
>  		Valid values:
> +
>  		- 5, 6 or 7 (hours),
>  		- 0: disabled.
>  
> @@ -595,6 +643,7 @@ Description:
>  		will drop to 0 A) and will trigger interrupt.
>  
>  		Valid values:
> +
>  		- 4 - 16 (hours), step by 2 (rounded down)
>  		- 0: disabled.
>  
> @@ -609,6 +658,7 @@ Description:
>  		interrupt and start top-off charging mode.
>  
>  		Valid values:
> +
>  		- 100000 - 200000 (microamps), step by 25000 (rounded down)
>  		- 200000 - 350000 (microamps), step by 50000 (rounded down)
>  		- 0: disabled.
> @@ -624,6 +674,7 @@ Description:
>  		will drop to 0 A) and will trigger interrupt.
>  
>  		Valid values:
> +
>  		- 0 - 70 (minutes), step by 10 (rounded down)
>  
>  What:		/sys/class/power_supply/bq24257-charger/ovp_voltage
> @@ -637,6 +688,7 @@ Description:
>  		device datasheet for details.
>  
>  		Valid values:
> +
>  		- 6000000, 6500000, 7000000, 8000000, 9000000, 9500000, 10000000,
>  		  10500000 (all uV)
>  
> @@ -652,6 +704,7 @@ Description:
>  		lower than the set value. See device datasheet for details.
>  
>  		Valid values:
> +
>  		- 4200000, 4280000, 4360000, 4440000, 4520000, 4600000, 4680000,
>  		  4760000 (all uV)
>  
> @@ -666,6 +719,7 @@ Description:
>  		the charger operates normally. See device datasheet for details.
>  
>  		Valid values:
> +
>  		- 1: enabled
>  		- 0: disabled
>  
> @@ -681,6 +735,7 @@ Description:
>  		from the system. See device datasheet for details.
>  
>  		Valid values:
> +
>  		- 1: enabled
>  		- 0: disabled
>  
> diff --git a/Documentation/ABI/testing/sysfs-class-power-twl4030 b/Documentation/ABI/testing/sysfs-class-power-twl4030
> index b4fd32d210c5..7ac36dba87bc 100644
> --- a/Documentation/ABI/testing/sysfs-class-power-twl4030
> +++ b/Documentation/ABI/testing/sysfs-class-power-twl4030
> @@ -4,18 +4,20 @@ Description:
>  	Writing to this can disable charging.
>  
>  	Possible values are:
> -		"auto" - draw power as appropriate for detected
> -			 power source and battery status.
> -		"off"  - do not draw any power.
> -		"continuous"
> -		       - activate mode described as "linear" in
> -		         TWL data sheets.  This uses whatever
> -			 current is available and doesn't switch off
> -			 when voltage drops.
>  
> -			 This is useful for unstable power sources
> -			 such as bicycle dynamo, but care should
> -			 be taken that battery is not over-charged.
> +		=============	===========================================
> +		"auto" 		draw power as appropriate for detected
> +				power source and battery status.
> +		"off"  		do not draw any power.
> +		"continuous"	activate mode described as "linear" in
> +				TWL data sheets.  This uses whatever
> +				current is available and doesn't switch off
> +				when voltage drops.
> +
> +				This is useful for unstable power sources
> +				such as bicycle dynamo, but care should
> +				be taken that battery is not over-charged.
> +		=============	===========================================
>  
>  What: /sys/class/power_supply/twl4030_ac/mode
>  Description:
> @@ -23,6 +25,9 @@ Description:
>  	Writing to this can disable charging.
>  
>  	Possible values are:
> -		"auto" - draw power as appropriate for detected
> -			 power source and battery status.
> -		"off"  - do not draw any power.
> +
> +		======	===========================================
> +		"auto"	draw power as appropriate for detected
> +			power source and battery status.
> +		"off"	do not draw any power.
> +		======	===========================================
> diff --git a/Documentation/ABI/testing/sysfs-class-rc b/Documentation/ABI/testing/sysfs-class-rc
> index 6c0d6c8cb911..9c8ff7910858 100644
> --- a/Documentation/ABI/testing/sysfs-class-rc
> +++ b/Documentation/ABI/testing/sysfs-class-rc
> @@ -21,15 +21,22 @@ KernelVersion:	2.6.36
>  Contact:	Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>  Description:
>  		Reading this file returns a list of available protocols,
> -		something like:
> +		something like::
> +
>  		    "rc5 [rc6] nec jvc [sony]"
> +
>  		Enabled protocols are shown in [] brackets.
> +
>  		Writing "+proto" will add a protocol to the list of enabled
>  		protocols.
> +
>  		Writing "-proto" will remove a protocol from the list of enabled
>  		protocols.
> +
>  		Writing "proto" will enable only "proto".
> +
>  		Writing "none" will disable all protocols.
> +
>  		Write fails with EINVAL if an invalid protocol combination or
>  		unknown protocol name is used.
>  
> @@ -39,11 +46,13 @@ KernelVersion:	3.15
>  Contact:	Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>  Description:
>  		Sets the scancode filter expected value.
> +
>  		Use in combination with /sys/class/rc/rcN/filter_mask to set the
>  		expected value of the bits set in the filter mask.
>  		If the hardware supports it then scancodes which do not match
>  		the filter will be ignored. Otherwise the write will fail with
>  		an error.
> +
>  		This value may be reset to 0 if the current protocol is altered.
>  
>  What:		/sys/class/rc/rcN/filter_mask
> @@ -56,9 +65,11 @@ Description:
>  		of the scancode which should be compared against the expected
>  		value. A value of 0 disables the filter to allow all valid
>  		scancodes to be processed.
> +
>  		If the hardware supports it then scancodes which do not match
>  		the filter will be ignored. Otherwise the write will fail with
>  		an error.
> +
>  		This value may be reset to 0 if the current protocol is altered.
>  
>  What:		/sys/class/rc/rcN/wakeup_protocols
> @@ -67,15 +78,22 @@ KernelVersion:	4.11
>  Contact:	Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>  Description:
>  		Reading this file returns a list of available protocols to use
> -		for the wakeup filter, something like:
> +		for the wakeup filter, something like::
> +
>  		    "rc-5 nec nec-x rc-6-0 rc-6-6a-24 [rc-6-6a-32] rc-6-mce"
> +
>  		Note that protocol variants are listed, so "nec", "sony",
>  		"rc-5", "rc-6" have their different bit length encodings
>  		listed if available.
> +
>  		The enabled wakeup protocol is shown in [] brackets.
> +
>  		Only one protocol can be selected at a time.
> +
>  		Writing "proto" will use "proto" for wakeup events.
> +
>  		Writing "none" will disable wakeup.
> +
>  		Write fails with EINVAL if an invalid protocol combination or
>  		unknown protocol name is used, or if wakeup is not supported by
>  		the hardware.
> @@ -86,13 +104,17 @@ KernelVersion:	3.15
>  Contact:	Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>  Description:
>  		Sets the scancode wakeup filter expected value.
> +
>  		Use in combination with /sys/class/rc/rcN/wakeup_filter_mask to
>  		set the expected value of the bits set in the wakeup filter mask
>  		to trigger a system wake event.
> +
>  		If the hardware supports it and wakeup_filter_mask is not 0 then
>  		scancodes which match the filter will wake the system from e.g.
>  		suspend to RAM or power off.
> +
>  		Otherwise the write will fail with an error.
> +
>  		This value may be reset to 0 if the wakeup protocol is altered.
>  
>  What:		/sys/class/rc/rcN/wakeup_filter_mask
> @@ -101,11 +123,15 @@ KernelVersion:	3.15
>  Contact:	Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
>  Description:
>  		Sets the scancode wakeup filter mask of bits to compare.
> +
>  		Use in combination with /sys/class/rc/rcN/wakeup_filter to set
>  		the bits of the scancode which should be compared against the
>  		expected value to trigger a system wake event.
> +
>  		If the hardware supports it and wakeup_filter_mask is not 0 then
>  		scancodes which match the filter will wake the system from e.g.
>  		suspend to RAM or power off.
> +
>  		Otherwise the write will fail with an error.
> +
>  		This value may be reset to 0 if the wakeup protocol is altered.
> diff --git a/Documentation/ABI/testing/sysfs-class-scsi_host b/Documentation/ABI/testing/sysfs-class-scsi_host
> index bafc59fd7b69..7c98d8f43c45 100644
> --- a/Documentation/ABI/testing/sysfs-class-scsi_host
> +++ b/Documentation/ABI/testing/sysfs-class-scsi_host
> @@ -56,8 +56,9 @@ Description:
>  		management) on top, which makes it match the Windows IRST (Intel
>  		Rapid Storage Technology) driver settings. This setting is also
>  		close to min_power, except that:
> +
>  		a) It does not use host-initiated slumber mode, but it does
> -		allow device-initiated slumber
> +		   allow device-initiated slumber
>  		b) It does not enable low power device sleep mode (DevSlp).
>  
>  What:		/sys/class/scsi_host/hostX/em_message
> @@ -70,8 +71,8 @@ Description:
>  		protocol, writes and reads correspond to the LED message format
>  		as defined in the AHCI spec.
>  
> -		The user must turn sw_activity (under /sys/block/*/device/) OFF
> -		it they wish to control the activity LED via the em_message
> +		The user must turn sw_activity (under `/sys/block/*/device/`)
> +		OFF it they wish to control the activity LED via the em_message
>  		file.
>  
>  		em_message_type: (RO) Displays the current enclosure management
> diff --git a/Documentation/ABI/testing/sysfs-class-typec b/Documentation/ABI/testing/sysfs-class-typec
> index b834671522d6..b7794e02ad20 100644
> --- a/Documentation/ABI/testing/sysfs-class-typec
> +++ b/Documentation/ABI/testing/sysfs-class-typec
> @@ -40,10 +40,13 @@ Description:
>  		attribute will not return until the operation has finished.
>  
>  		Valid values:
> -		- source (The port will behave as source only DFP port)
> -		- sink (The port will behave as sink only UFP port)
> -		- dual (The port will behave as dual-role-data and
> +
> +		======  ==============================================
> +		source  (The port will behave as source only DFP port)
> +		sink    (The port will behave as sink only UFP port)
> +		dual    (The port will behave as dual-role-data and
>  			dual-role-power port)
> +		======  ==============================================
>  
>  What:		/sys/class/typec/<port>/vconn_source
>  Date:		April 2017
> @@ -59,6 +62,7 @@ Description:
>  		generates uevent KOBJ_CHANGE.
>  
>  		Valid values:
> +
>  		- "no" when the port is not the VCONN Source
>  		- "yes" when the port is the VCONN Source
>  
> @@ -72,6 +76,7 @@ Description:
>  		power operation mode should show "usb_power_delivery".
>  
>  		Valid values:
> +
>  		- default
>  		- 1.5A
>  		- 3.0A
> @@ -191,6 +196,7 @@ Date:		April 2017
>  Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>
>  Description:
>  		Shows type of the plug on the cable:
> +
>  		- type-a - Standard A
>  		- type-b - Standard B
>  		- type-c
> diff --git a/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD b/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD
> index 7e43cdce9a52..f7b360a61b21 100644
> --- a/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD
> +++ b/Documentation/ABI/testing/sysfs-devices-platform-ACPI-TAD
> @@ -7,6 +7,7 @@ Description:
>  		(RO) Hexadecimal bitmask of the TAD attributes are reported by
>  		the platform firmware (see ACPI 6.2, section 9.18.2):
>  
> +		======= ======================================================
>  		BIT(0): AC wakeup implemented if set
>  		BIT(1): DC wakeup implemented if set
>  		BIT(2): Get/set real time features implemented if set
> @@ -16,6 +17,7 @@ Description:
>  		BIT(6): The AC timer wakes up from S5 if set
>  		BIT(7): The DC timer wakes up from S4 if set
>  		BIT(8): The DC timer wakes up from S5 if set
> +		======= ======================================================
>  
>  		The other bits are reserved.
>  
> @@ -62,9 +64,11 @@ Description:
>  		timer status with the following meaning of bits (see ACPI 6.2,
>  		Section 9.18.5):
>  
> +		======= ======================================================
>  		Bit(0): The timer has expired if set.
>  		Bit(1): The timer has woken up the system from a sleep state
>  		        (S3 or S4/S5 if supported) if set.
> +		======= ======================================================
>  
>  		The other bits are reserved.
>  
> diff --git a/Documentation/ABI/testing/sysfs-devices-platform-docg3 b/Documentation/ABI/testing/sysfs-devices-platform-docg3
> index 8aa36716882f..378c42694bfb 100644
> --- a/Documentation/ABI/testing/sysfs-devices-platform-docg3
> +++ b/Documentation/ABI/testing/sysfs-devices-platform-docg3
> @@ -9,8 +9,10 @@ Description:
>  		The protection has information embedded whether it blocks reads,
>  		writes or both.
>  		The result is:
> -		0 -> the DPS is not keylocked
> -		1 -> the DPS is keylocked
> +
> +		- 0 -> the DPS is not keylocked
> +		- 1 -> the DPS is keylocked
> +
>  Users:		None identified so far.
>  
>  What:		/sys/devices/platform/docg3/f[0-3]_dps[01]_protection_key
> @@ -27,8 +29,12 @@ Description:
>  		Entering the correct value toggle the lock, and can be observed
>  		through f[0-3]_dps[01]_is_keylocked.
>  		Possible values are:
> +
>  			- 8 bytes
> +
>  		Typical values are:
> +
>  			- "00000000"
>  			- "12345678"
> +
>  Users:		None identified so far.
> diff --git a/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb b/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb
> index 2107082426da..e45ac2e865d5 100644
> --- a/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb
> +++ b/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb
> @@ -17,10 +17,10 @@ Description:
>  		to overlay planes.
>  
>  		Selects the composition mode for the overlay. Possible values
> -		are
> +		are:
>  
> -		0 - Alpha Blending
> -		1 - ROP3
> +		- 0 - Alpha Blending
> +		- 1 - ROP3
>  
>  What:		/sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_position
>  Date:		May 2012
> @@ -30,7 +30,7 @@ Description:
>  		to overlay planes.
>  
>  		Stores the x,y overlay position on the display in pixels. The
> -		position format is `[0-9]+,[0-9]+'.
> +		position format is `[0-9]+,[0-9]+`.
>  
>  What:		/sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_rop3
>  Date:		May 2012
> diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
> index b555df825447..274c337ec6a9 100644
> --- a/Documentation/ABI/testing/sysfs-devices-system-cpu
> +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
> @@ -151,23 +151,28 @@ Description:
>  		The processor idle states which are available for use have the
>  		following attributes:
>  
> -		name: (RO) Name of the idle state (string).
> +		======== ==== =================================================
> +		name:	 (RO) Name of the idle state (string).
>  
>  		latency: (RO) The latency to exit out of this idle state (in
> -		microseconds).
> +			      microseconds).
>  
> -		power: (RO) The power consumed while in this idle state (in
> -		milliwatts).
> +		power:   (RO) The power consumed while in this idle state (in
> +			      milliwatts).
>  
> -		time: (RO) The total time spent in this idle state (in microseconds).
> +		time:    (RO) The total time spent in this idle state
> +			      (in microseconds).
>  
> -		usage: (RO) Number of times this state was entered (a count).
> +		usage:	 (RO) Number of times this state was entered (a count).
>  
> -		above: (RO) Number of times this state was entered, but the
> -		       observed CPU idle duration was too short for it (a count).
> +		above:	 (RO) Number of times this state was entered, but the
> +			      observed CPU idle duration was too short for it
> +			      (a count).
>  
> -		below: (RO) Number of times this state was entered, but the
> -		       observed CPU idle duration was too long for it (a count).
> +		below: 	 (RO) Number of times this state was entered, but the
> +			      observed CPU idle duration was too long for it
> +			      (a count).
> +		======== ==== =================================================
>  
>  What:		/sys/devices/system/cpu/cpuX/cpuidle/stateN/desc
>  Date:		February 2008
> @@ -290,6 +295,7 @@ Description:	Processor frequency boosting control
>  		This switch controls the boost setting for the whole system.
>  		Boosting allows the CPU and the firmware to run at a frequency
>  		beyound it's nominal limit.
> +
>  		More details can be found in
>  		Documentation/admin-guide/pm/cpufreq.rst
>  
> @@ -337,43 +343,57 @@ Contact:	Sudeep Holla <sudeep.holla@arm.com>
>  Description:	Parameters for the CPU cache attributes
>  
>  		allocation_policy:
> -			- WriteAllocate: allocate a memory location to a cache line
> -					 on a cache miss because of a write
> -			- ReadAllocate: allocate a memory location to a cache line
> +			- WriteAllocate:
> +					allocate a memory location to a cache line
> +					on a cache miss because of a write
> +			- ReadAllocate:
> +					allocate a memory location to a cache line
>  					on a cache miss because of a read
> -			- ReadWriteAllocate: both writeallocate and readallocate
> +			- ReadWriteAllocate:
> +					both writeallocate and readallocate
>  
> -		attributes: LEGACY used only on IA64 and is same as write_policy
> +		attributes:
> +			    LEGACY used only on IA64 and is same as write_policy
>  
> -		coherency_line_size: the minimum amount of data in bytes that gets
> +		coherency_line_size:
> +				     the minimum amount of data in bytes that gets
>  				     transferred from memory to cache
>  
> -		level: the cache hierarchy in the multi-level cache configuration
> +		level:
> +			the cache hierarchy in the multi-level cache configuration
>  
> -		number_of_sets: total number of sets in the cache, a set is a
> +		number_of_sets:
> +				total number of sets in the cache, a set is a
>  				collection of cache lines with the same cache index
>  
> -		physical_line_partition: number of physical cache line per cache tag
> +		physical_line_partition:
> +				number of physical cache line per cache tag
>  
> -		shared_cpu_list: the list of logical cpus sharing the cache
> +		shared_cpu_list:
> +				the list of logical cpus sharing the cache
>  
> -		shared_cpu_map: logical cpu mask containing the list of cpus sharing
> +		shared_cpu_map:
> +				logical cpu mask containing the list of cpus sharing
>  				the cache
>  
> -		size: the total cache size in kB
> +		size:
> +			the total cache size in kB
>  
>  		type:
>  			- Instruction: cache that only holds instructions
>  			- Data: cache that only caches data
>  			- Unified: cache that holds both data and instructions
>  
> -		ways_of_associativity: degree of freedom in placing a particular block
> -					of memory in the cache
> +		ways_of_associativity:
> +			degree of freedom in placing a particular block
> +			of memory in the cache
>  
>  		write_policy:
> -			- WriteThrough: data is written to both the cache line
> +			- WriteThrough:
> +					data is written to both the cache line
>  					and to the block in the lower-level memory
> -			- WriteBack: data is written only to the cache line and
> +			- WriteBack:
> +				     data is written only to the cache line and
>  				     the modified cache line is written to main
>  				     memory only when it is replaced
>  
> @@ -414,30 +434,30 @@ Description:	POWERNV CPUFreq driver's frequency throttle stats directory and
>  		throttle attributes exported in the 'throttle_stats' directory:
>  
>  		- turbo_stat : This file gives the total number of times the max
> -		frequency is throttled to lower frequency in turbo (at and above
> -		nominal frequency) range of frequencies.
> +		  frequency is throttled to lower frequency in turbo (at and above
> +		  nominal frequency) range of frequencies.
>  
>  		- sub_turbo_stat : This file gives the total number of times the
> -		max frequency is throttled to lower frequency in sub-turbo(below
> -		nominal frequency) range of frequencies.
> +		  max frequency is throttled to lower frequency in sub-turbo(below
> +		  nominal frequency) range of frequencies.
>  
>  		- unthrottle : This file gives the total number of times the max
> -		frequency is unthrottled after being throttled.
> +		  frequency is unthrottled after being throttled.
>  
>  		- powercap : This file gives the total number of times the max
> -		frequency is throttled due to 'Power Capping'.
> +		  frequency is throttled due to 'Power Capping'.
>  
>  		- overtemp : This file gives the total number of times the max
> -		frequency is throttled due to 'CPU Over Temperature'.
> +		  frequency is throttled due to 'CPU Over Temperature'.
>  
>  		- supply_fault : This file gives the total number of times the
> -		max frequency is throttled due to 'Power Supply Failure'.
> +		  max frequency is throttled due to 'Power Supply Failure'.
>  
>  		- overcurrent : This file gives the total number of times the
> -		max frequency is throttled due to 'Overcurrent'.
> +		  max frequency is throttled due to 'Overcurrent'.
>  
>  		- occ_reset : This file gives the total number of times the max
> -		frequency is throttled due to 'OCC Reset'.
> +		  frequency is throttled due to 'OCC Reset'.
>  
>  		The sysfs attributes representing different throttle reasons like
>  		powercap, overtemp, supply_fault, overcurrent and occ_reset map to
> @@ -469,8 +489,9 @@ What:		/sys/devices/system/cpu/cpuX/regs/
>  Date:		June 2016
>  Contact:	Linux ARM Kernel Mailing list <linux-arm-kernel@lists.infradead.org>
>  Description:	AArch64 CPU registers
> +
>  		'identification' directory exposes the CPU ID registers for
> -		 identifying model and revision of the CPU.
> +		identifying model and revision of the CPU.
>  
>  What:		/sys/devices/system/cpu/cpu#/cpu_capacity
>  Date:		December 2016
> @@ -497,9 +518,11 @@ Description:	Information about CPU vulnerabilities
>  		vulnerabilities. The output of those files reflects the
>  		state of the CPUs in the system. Possible output values:
>  
> +		================  ==============================================
>  		"Not affected"	  CPU is not affected by the vulnerability
>  		"Vulnerable"	  CPU is affected and no mitigation in effect
>  		"Mitigation: $M"  CPU is affected and mitigation $M is in effect
> +		================  ==============================================
>  
>  		See also: Documentation/admin-guide/hw-vuln/index.rst
>  
> @@ -515,12 +538,14 @@ Description:	Control Symetric Multi Threading (SMT)
>  		control: Read/write interface to control SMT. Possible
>  			 values:
>  
> +			 ================ =========================================
>  			 "on"		  SMT is enabled
>  			 "off"		  SMT is disabled
>  			 "forceoff"	  SMT is force disabled. Cannot be changed.
>  			 "notsupported"   SMT is not supported by the CPU
>  			 "notimplemented" SMT runtime toggling is not
>  					  implemented for the architecture
> +			 ================ =========================================
>  
>  			 If control status is "forceoff" or "notsupported" writes
>  			 are rejected.
> diff --git a/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl
> index 470def06ab0a..1a8ee26e92ae 100644
> --- a/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl
> +++ b/Documentation/ABI/testing/sysfs-devices-system-ibm-rtl
> @@ -5,8 +5,10 @@ Contact:        Vernon Mauery <vernux@us.ibm.com>
>  Description:    The state file allows a means by which to change in and
>                  out of Premium Real-Time Mode (PRTM), as well as the
>                  ability to query the current state.
> -                    0 => PRTM off
> -                    1 => PRTM enabled
> +
> +                    - 0 => PRTM off
> +                    - 1 => PRTM enabled
> +
>  Users:          The ibm-prtm userspace daemon uses this interface.
>  
>  
> diff --git a/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator b/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator
> index 4d63a7904b94..42214b4ff14a 100644
> --- a/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator
> +++ b/Documentation/ABI/testing/sysfs-driver-bd9571mwv-regulator
> @@ -6,11 +6,13 @@ Description:	Read/write the current state of DDR Backup Mode, which controls
>  		if DDR power rails will be kept powered during system suspend.
>  		("on"/"1" = enabled, "off"/"0" = disabled).
>  		Two types of power switches (or control signals) can be used:
> +
>  		  A. With a momentary power switch (or pulse signal), DDR
>  		     Backup Mode is enabled by default when available, as the
>  		     PMIC will be configured only during system suspend.
>  		  B. With a toggle power switch (or level signal), the
>  		     following steps must be followed exactly:
> +
>  		       1. Configure PMIC for backup mode, to change the role of
>  			  the accessory power switch from a power switch to a
>  			  wake-up switch,
> @@ -20,8 +22,10 @@ Description:	Read/write the current state of DDR Backup Mode, which controls
>  		       3. Suspend system,
>  		       4. Switch accessory power switch on, to resume the
>  			  system.
> +
>  		     DDR Backup Mode must be explicitly enabled by the user,
>  		     to invoke step 1.
> +
>  		See also Documentation/devicetree/bindings/mfd/bd9571mwv.txt.
>  Users:		User space applications for embedded boards equipped with a
>  		BD9571MWV PMIC.
> diff --git a/Documentation/ABI/testing/sysfs-driver-genwqe b/Documentation/ABI/testing/sysfs-driver-genwqe
> index 64ac6d567c4b..69d855dc4c47 100644
> --- a/Documentation/ABI/testing/sysfs-driver-genwqe
> +++ b/Documentation/ABI/testing/sysfs-driver-genwqe
> @@ -29,8 +29,12 @@ What:           /sys/class/genwqe/genwqe<n>_card/reload_bitstream
>  Date:           May 2014
>  Contact:        klebers@linux.vnet.ibm.com
>  Description:    Interface to trigger a PCIe card reset to reload the bitstream.
> +
> +		::
> +
>                    sudo sh -c 'echo 1 > \
>                      /sys/class/genwqe/genwqe0_card/reload_bitstream'
> +
>                  If successfully, the card will come back with the bitstream set
>                  on 'next_bitstream'.
>  
> @@ -64,8 +68,11 @@ Description:    Base clock frequency of the card.
>  What:           /sys/class/genwqe/genwqe<n>_card/device/sriov_numvfs
>  Date:           Oct 2013
>  Contact:        haver@linux.vnet.ibm.com
> -Description:    Enable VFs (1..15):
> +Description:    Enable VFs (1..15)::
> +
>                    sudo sh -c 'echo 15 > \
>                      /sys/bus/pci/devices/0000\:1b\:00.0/sriov_numvfs'
> -                Disable VFs:
> +
> +                Disable VFs::
> +
>                    Write a 0 into the same sysfs entry.
> diff --git a/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff b/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff
> index 305dffd229a8..de07be314efc 100644
> --- a/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff
> +++ b/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff
> @@ -12,7 +12,9 @@ KernelVersion:	4.1
>  Contact:	Michal Malý <madcatxster@devoid-pointer.net>
>  Description:	Displays a set of alternate modes supported by a wheel. Each
>  		mode is listed as follows:
> +
>  		  Tag: Mode Name
> +
>  		Currently active mode is marked with an asterisk. List also
>  		contains an abstract item "native" which always denotes the
>  		native mode of the wheel. Echoing the mode tag switches the
> @@ -24,24 +26,30 @@ Description:	Displays a set of alternate modes supported by a wheel. Each
>  		This entry is not created for devices that have only one mode.
>  
>  		Currently supported mode switches:
> -		Driving Force Pro:
> +
> +		Driving Force Pro::
> +
>  		  DF-EX --> DFP
>  
> -		G25:
> +		G25::
> +
>  		  DF-EX --> DFP --> G25
>  
> -		G27:
> +		G27::
> +
>  		  DF-EX <*> DFP <-> G25 <-> G27
>  		  DF-EX <*--------> G25 <-> G27
>  		  DF-EX <*----------------> G27
>  
> -		G29:
> +		G29::
> +
>  		  DF-EX <*> DFP <-> G25 <-> G27 <-> G29
>  		  DF-EX <*--------> G25 <-> G27 <-> G29
>  		  DF-EX <*----------------> G27 <-> G29
>  		  DF-EX <*------------------------> G29
>  
> -		DFGT:
> +		DFGT::
> +
>  		  DF-EX <*> DFP <-> DFGT
>  		  DF-EX <*--------> DFGT
>  
> diff --git a/Documentation/ABI/testing/sysfs-driver-hid-wiimote b/Documentation/ABI/testing/sysfs-driver-hid-wiimote
> index 39dfa5cb1cc5..cd7b82a5c27d 100644
> --- a/Documentation/ABI/testing/sysfs-driver-hid-wiimote
> +++ b/Documentation/ABI/testing/sysfs-driver-hid-wiimote
> @@ -39,9 +39,13 @@ Description:	While a device is initialized by the wiimote driver, we perform
>  		Other strings for each device-type are available and may be
>  		added if new device-specific detections are added.
>  		Currently supported are:
> -			gen10: First Wii Remote generation
> -			gen20: Second Wii Remote Plus generation (builtin MP)
> +
> +			============= =======================================
> +			gen10:        First Wii Remote generation
> +			gen20:        Second Wii Remote Plus generation
> +				      (builtin MP)
>  			balanceboard: Wii Balance Board
> +			============= =======================================
>  
>  What:		/sys/bus/hid/drivers/wiimote/<dev>/bboard_calib
>  Date:		May 2013
> @@ -54,6 +58,7 @@ Description:	This attribute is only provided if the device was detected as a
>  		First, 0kg values for all 4 sensors are written, followed by the
>  		17kg values for all 4 sensors and last the 34kg values for all 4
>  		sensors.
> +
>  		Calibration data is already applied by the kernel to all input
>  		values but may be used by user-space to perform other
>  		transformations.
> @@ -68,9 +73,11 @@ Description:	This attribute is only provided if the device was detected as a
>  		is prefixed with a +/-. Each value is a signed 16bit number.
>  		Data is encoded as decimal numbers and specifies the offsets of
>  		the analog sticks of the pro-controller.
> +
>  		Calibration data is already applied by the kernel to all input
>  		values but may be used by user-space to perform other
>  		transformations.
> +
>  		Calibration data is detected by the kernel during device setup.
>  		You can write "scan\n" into this file to re-trigger calibration.
>  		You can also write data directly in the form "x1:y1 x2:y2" to
> diff --git a/Documentation/ABI/testing/sysfs-driver-samsung-laptop b/Documentation/ABI/testing/sysfs-driver-samsung-laptop
> index 34d3a3359cf4..28c9c040de5d 100644
> --- a/Documentation/ABI/testing/sysfs-driver-samsung-laptop
> +++ b/Documentation/ABI/testing/sysfs-driver-samsung-laptop
> @@ -9,10 +9,12 @@ Description:	Some Samsung laptops have different "performance levels"
>  		their fans quiet at all costs.  Reading from this file
>  		will show the current performance level.  Writing to the
>  		file can change this value.
> +
>  			Valid options:
> -				"silent"
> -				"normal"
> -				"overclock"
> +				- "silent"
> +				- "normal"
> +				- "overclock"
> +
>  		Note that not all laptops support all of these options.
>  		Specifically, not all support the "overclock" option,
>  		and it's still unknown if this value even changes
> @@ -25,8 +27,9 @@ Contact:	Corentin Chary <corentin.chary@gmail.com>
>  Description:	Max battery charge level can be modified, battery cycle
>  		life can be extended by reducing the max battery charge
>  		level.
> -		0 means normal battery mode (100% charge)
> -		1 means battery life extender mode (80% charge)
> +
> +		- 0 means normal battery mode (100% charge)
> +		- 1 means battery life extender mode (80% charge)
>  
>  What:		/sys/devices/platform/samsung/usb_charge
>  Date:		December 1, 2011
> diff --git a/Documentation/ABI/testing/sysfs-driver-toshiba_acpi b/Documentation/ABI/testing/sysfs-driver-toshiba_acpi
> index f34221b52b14..e5a438d84e1f 100644
> --- a/Documentation/ABI/testing/sysfs-driver-toshiba_acpi
> +++ b/Documentation/ABI/testing/sysfs-driver-toshiba_acpi
> @@ -4,10 +4,12 @@ KernelVersion:	3.15
>  Contact:	Azael Avalos <coproscefalo@gmail.com>
>  Description:	This file controls the keyboard backlight operation mode, valid
>  		values are:
> +
>  			* 0x1  -> FN-Z
>  			* 0x2  -> AUTO (also called TIMER)
>  			* 0x8  -> ON
>  			* 0x10 -> OFF
> +
>  		Note that from kernel 3.16 onwards this file accepts all listed
>  		parameters, kernel 3.15 only accepts the first two (FN-Z and
>  		AUTO).
> @@ -41,8 +43,10 @@ KernelVersion:	3.15
>  Contact:	Azael Avalos <coproscefalo@gmail.com>
>  Description:	This files controls the status of the touchpad and pointing
>  		stick (if available), valid values are:
> +
>  			* 0 -> OFF
>  			* 1 -> ON
> +
>  Users:		KToshiba
>  
>  What:		/sys/devices/LNXSYSTM:00/LNXSYBUS:00/TOS{1900,620{0,7,8}}:00/available_kbd_modes
> @@ -51,10 +55,12 @@ KernelVersion:	3.16
>  Contact:	Azael Avalos <coproscefalo@gmail.com>
>  Description:	This file shows the supported keyboard backlight modes
>  		the system supports, which can be:
> +
>  			* 0x1  -> FN-Z
>  			* 0x2  -> AUTO (also called TIMER)
>  			* 0x8  -> ON
>  			* 0x10 -> OFF
> +
>  		Note that not all keyboard types support the listed modes.
>  		See the entry named "available_kbd_modes"
>  Users:		KToshiba
> @@ -65,6 +71,7 @@ KernelVersion:	3.16
>  Contact:	Azael Avalos <coproscefalo@gmail.com>
>  Description:	This file shows the current keyboard backlight type,
>  		which can be:
> +
>  			* 1 -> Type 1, supporting modes FN-Z and AUTO
>  			* 2 -> Type 2, supporting modes TIMER, ON and OFF
>  Users:		KToshiba
> @@ -75,10 +82,12 @@ KernelVersion:	4.0
>  Contact:	Azael Avalos <coproscefalo@gmail.com>
>  Description:	This file controls the USB Sleep & Charge charging mode, which
>  		can be:
> +
>  			* 0 -> Disabled		(0x00)
>  			* 1 -> Alternate	(0x09)
>  			* 2 -> Auto		(0x21)
>  			* 3 -> Typical		(0x11)
> +
>  		Note that from kernel 4.1 onwards this file accepts all listed
>  		values, kernel 4.0 only supports the first three.
>  		Note that this feature only works when connected to power, if
> @@ -93,8 +102,10 @@ Contact:	Azael Avalos <coproscefalo@gmail.com>
>  Description:	This file controls the USB Sleep Functions under battery, and
>  		set the level at which point they will be disabled, accepted
>  		values can be:
> +
>  			* 0	-> Disabled
>  			* 1-100	-> Battery level to disable sleep functions
> +
>  		Currently it prints two values, the first one indicates if the
>  		feature is enabled or disabled, while the second one shows the
>  		current battery level set.
> @@ -107,8 +118,10 @@ Date:		January 23, 2015
>  KernelVersion:	4.0
>  Contact:	Azael Avalos <coproscefalo@gmail.com>
>  Description:	This file controls the USB Rapid Charge state, which can be:
> +
>  			* 0 -> Disabled
>  			* 1 -> Enabled
> +
>  		Note that toggling this value requires a reboot for changes to
>  		take effect.
>  Users:		KToshiba
> @@ -118,8 +131,10 @@ Date:		January 23, 2015
>  KernelVersion:	4.0
>  Contact:	Azael Avalos <coproscefalo@gmail.com>
>  Description:	This file controls the Sleep & Music state, which values can be:
> +
>  			* 0 -> Disabled
>  			* 1 -> Enabled
> +
>  		Note that this feature only works when connected to power, if
>  		you want to use it under battery, see the entry named
>  		"sleep_functions_on_battery"
> @@ -138,6 +153,7 @@ KernelVersion:	4.0
>  Contact:	Azael Avalos <coproscefalo@gmail.com>
>  Description:	This file controls the state of the internal fan, valid
>  		values are:
> +
>  			* 0 -> OFF
>  			* 1 -> ON
>  
> @@ -147,8 +163,10 @@ KernelVersion:	4.0
>  Contact:	Azael Avalos <coproscefalo@gmail.com>
>  Description:	This file controls the Special Functions (hotkeys) operation
>  		mode, valid values are:
> +
>  			* 0 -> Normal Operation
>  			* 1 -> Special Functions
> +
>  		In the "Normal Operation" mode, the F{1-12} keys are as usual
>  		and the hotkeys are accessed via FN-F{1-12}.
>  		In the "Special Functions" mode, the F{1-12} keys trigger the
> @@ -163,8 +181,10 @@ KernelVersion:	4.0
>  Contact:	Azael Avalos <coproscefalo@gmail.com>
>  Description:	This file controls whether the laptop should turn ON whenever
>  		the LID is opened, valid values are:
> +
>  			* 0 -> Disabled
>  			* 1 -> Enabled
> +
>  		Note that toggling this value requires a reboot for changes to
>  		take effect.
>  Users:		KToshiba
> @@ -174,8 +194,10 @@ Date:		February 12, 2015
>  KernelVersion:	4.0
>  Contact:	Azael Avalos <coproscefalo@gmail.com>
>  Description:	This file controls the USB 3 functionality, valid values are:
> +
>  			* 0 -> Disabled (Acts as a regular USB 2)
>  			* 1 -> Enabled (Full USB 3 functionality)
> +
>  		Note that toggling this value requires a reboot for changes to
>  		take effect.
>  Users:		KToshiba
> @@ -188,10 +210,14 @@ Description:	This file controls the Cooling Method feature.
>  		Reading this file prints two values, the first is the actual cooling method
>  		and the second is the maximum cooling method supported.
>  		When the maximum cooling method is ONE, valid values are:
> +
>  			* 0 -> Maximum Performance
>  			* 1 -> Battery Optimized
> +
>  		When the maximum cooling method is TWO, valid values are:
> +
>  			* 0 -> Maximum Performance
>  			* 1 -> Performance
>  			* 2 -> Battery Optimized
> +
>  Users:		KToshiba
> diff --git a/Documentation/ABI/testing/sysfs-driver-toshiba_haps b/Documentation/ABI/testing/sysfs-driver-toshiba_haps
> index a662370b4dbf..c938690ce10d 100644
> --- a/Documentation/ABI/testing/sysfs-driver-toshiba_haps
> +++ b/Documentation/ABI/testing/sysfs-driver-toshiba_haps
> @@ -4,10 +4,12 @@ KernelVersion:	3.17
>  Contact:	Azael Avalos <coproscefalo@gmail.com>
>  Description:	This file controls the built-in accelerometer protection level,
>  		valid values are:
> +
>  			* 0 -> Disabled
>  			* 1 -> Low
>  			* 2 -> Medium
>  			* 3 -> High
> +
>  		The default potection value is set to 2 (Medium).
>  Users:		KToshiba
>  
> diff --git a/Documentation/ABI/testing/sysfs-driver-wacom b/Documentation/ABI/testing/sysfs-driver-wacom
> index afc48fc163b5..16acaa5712ec 100644
> --- a/Documentation/ABI/testing/sysfs-driver-wacom
> +++ b/Documentation/ABI/testing/sysfs-driver-wacom
> @@ -79,7 +79,9 @@ Description:
>  		When the Wacom Intuos 4 is connected over Bluetooth, the
>  		image has to contain 256 bytes (64x32 px 1 bit colour).
>  		The format is also scrambled, like in the USB mode, and it can
> -		be summarized by converting 76543210 into GECA6420.
> +		be summarized by converting::
> +
> +					    76543210 into GECA6420.
>  					    HGFEDCBA      HFDB7531
>  
>  What:		/sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/wacom_remote/unpair_remote
> diff --git a/Documentation/ABI/testing/sysfs-firmware-acpi b/Documentation/ABI/testing/sysfs-firmware-acpi
> index 613f42a9d5cd..e4afc2538210 100644
> --- a/Documentation/ABI/testing/sysfs-firmware-acpi
> +++ b/Documentation/ABI/testing/sysfs-firmware-acpi
> @@ -12,11 +12,14 @@ Description:
>  		image: The image bitmap. Currently a 32-bit BMP.
>  		status: 1 if the image is valid, 0 if firmware invalidated it.
>  		type: 0 indicates image is in BMP format.
> +
> +		======== ===================================================
>  		version: The version of the BGRT. Currently 1.
>  		xoffset: The number of pixels between the left of the screen
>  			 and the left edge of the image.
>  		yoffset: The number of pixels between the top of the screen
>  			 and the top edge of the image.
> +		======== ===================================================
>  
>  What:		/sys/firmware/acpi/hotplug/
>  Date:		February 2013
> @@ -33,12 +36,14 @@ Description:
>  		The following setting is available to user space for each
>  		hotplug profile:
>  
> +		======== =======================================================
>  		enabled: If set, the ACPI core will handle notifications of
> -			hotplug events associated with the given class of
> -			devices and will allow those devices to be ejected with
> -			the help of the _EJ0 control method.  Unsetting it
> -			effectively disables hotplug for the correspoinding
> -			class of devices.
> +			 hotplug events associated with the given class of
> +			 devices and will allow those devices to be ejected with
> +			 the help of the _EJ0 control method.  Unsetting it
> +			 effectively disables hotplug for the correspoinding
> +			 class of devices.
> +		======== =======================================================
>  
>  		The value of the above attribute is an integer number: 1 (set)
>  		or 0 (unset).  Attempts to write any other values to it will
> @@ -71,86 +76,90 @@ Description:
>  		To figure out where all the SCI's are coming from,
>  		/sys/firmware/acpi/interrupts contains a file listing
>  		every possible source, and the count of how many
> -		times it has triggered.
> -
> -		$ cd /sys/firmware/acpi/interrupts
> -		$ grep . *
> -		error:	     0
> -		ff_gbl_lock:	   0   enable
> -		ff_pmtimer:	  0  invalid
> -		ff_pwr_btn:	  0   enable
> -		ff_rt_clk:	 2  disable
> -		ff_slp_btn:	  0  invalid
> -		gpe00:	     0	invalid
> -		gpe01:	     0	 enable
> -		gpe02:	   108	 enable
> -		gpe03:	     0	invalid
> -		gpe04:	     0	invalid
> -		gpe05:	     0	invalid
> -		gpe06:	     0	 enable
> -		gpe07:	     0	 enable
> -		gpe08:	     0	invalid
> -		gpe09:	     0	invalid
> -		gpe0A:	     0	invalid
> -		gpe0B:	     0	invalid
> -		gpe0C:	     0	invalid
> -		gpe0D:	     0	invalid
> -		gpe0E:	     0	invalid
> -		gpe0F:	     0	invalid
> -		gpe10:	     0	invalid
> -		gpe11:	     0	invalid
> -		gpe12:	     0	invalid
> -		gpe13:	     0	invalid
> -		gpe14:	     0	invalid
> -		gpe15:	     0	invalid
> -		gpe16:	     0	invalid
> -		gpe17:	  1084	 enable
> -		gpe18:	     0	 enable
> -		gpe19:	     0	invalid
> -		gpe1A:	     0	invalid
> -		gpe1B:	     0	invalid
> -		gpe1C:	     0	invalid
> -		gpe1D:	     0	invalid
> -		gpe1E:	     0	invalid
> -		gpe1F:	     0	invalid
> -		gpe_all:    1192
> -		sci:	1194
> -		sci_not:     0	
> -
> -		sci - The number of times the ACPI SCI
> -		has been called and claimed an interrupt.
> -
> -		sci_not - The number of times the ACPI SCI
> -		has been called and NOT claimed an interrupt.
> -
> -		gpe_all - count of SCI caused by GPEs.
> -
> -		gpeXX - count for individual GPE source
> -
> -		ff_gbl_lock - Global Lock
> -
> -		ff_pmtimer - PM Timer
> -
> -		ff_pwr_btn - Power Button
> -
> -		ff_rt_clk - Real Time Clock
> -
> -		ff_slp_btn - Sleep Button
> -
> -		error - an interrupt that can't be accounted for above.
> -
> -		invalid: it's either a GPE or a Fixed Event that
> -			doesn't have an event handler.
> -
> -		disable: the GPE/Fixed Event is valid but disabled.
> -
> -		enable: the GPE/Fixed Event is valid and enabled.
> -
> -		Root has permission to clear any of these counters.  Eg.
> -		# echo 0 > gpe11
> -
> -		All counters can be cleared by clearing the total "sci":
> -		# echo 0 > sci
> +		times it has triggered::
> +
> +		  $ cd /sys/firmware/acpi/interrupts
> +		  $ grep . *
> +		  error:	     0
> +		  ff_gbl_lock:	   0   enable
> +		  ff_pmtimer:	  0  invalid
> +		  ff_pwr_btn:	  0   enable
> +		  ff_rt_clk:	 2  disable
> +		  ff_slp_btn:	  0  invalid
> +		  gpe00:	     0	invalid
> +		  gpe01:	     0	 enable
> +		  gpe02:	   108	 enable
> +		  gpe03:	     0	invalid
> +		  gpe04:	     0	invalid
> +		  gpe05:	     0	invalid
> +		  gpe06:	     0	 enable
> +		  gpe07:	     0	 enable
> +		  gpe08:	     0	invalid
> +		  gpe09:	     0	invalid
> +		  gpe0A:	     0	invalid
> +		  gpe0B:	     0	invalid
> +		  gpe0C:	     0	invalid
> +		  gpe0D:	     0	invalid
> +		  gpe0E:	     0	invalid
> +		  gpe0F:	     0	invalid
> +		  gpe10:	     0	invalid
> +		  gpe11:	     0	invalid
> +		  gpe12:	     0	invalid
> +		  gpe13:	     0	invalid
> +		  gpe14:	     0	invalid
> +		  gpe15:	     0	invalid
> +		  gpe16:	     0	invalid
> +		  gpe17:	  1084	 enable
> +		  gpe18:	     0	 enable
> +		  gpe19:	     0	invalid
> +		  gpe1A:	     0	invalid
> +		  gpe1B:	     0	invalid
> +		  gpe1C:	     0	invalid
> +		  gpe1D:	     0	invalid
> +		  gpe1E:	     0	invalid
> +		  gpe1F:	     0	invalid
> +		  gpe_all:    1192
> +		  sci:	1194
> +		  sci_not:     0
> +
> +		===========  ==================================================
> +		sci	     The number of times the ACPI SCI
> +			     has been called and claimed an interrupt.
> +
> +		sci_not	     The number of times the ACPI SCI
> +			     has been called and NOT claimed an interrupt.
> +
> +		gpe_all	     count of SCI caused by GPEs.
> +
> +		gpeXX	     count for individual GPE source
> +
> +		ff_gbl_lock  Global Lock
> +
> +		ff_pmtimer   PM Timer
> +
> +		ff_pwr_btn   Power Button
> +
> +		ff_rt_clk    Real Time Clock
> +
> +		ff_slp_btn   Sleep Button
> +
> +		error	     an interrupt that can't be accounted for above.
> +
> +		invalid      it's either a GPE or a Fixed Event that
> +			     doesn't have an event handler.
> +
> +		disable	     the GPE/Fixed Event is valid but disabled.
> +
> +		enable       the GPE/Fixed Event is valid and enabled.
> +		===========  ==================================================
> +
> +		Root has permission to clear any of these counters.  Eg.::
> +
> +		  # echo 0 > gpe11
> +
> +		All counters can be cleared by clearing the total "sci"::
> +
> +		  # echo 0 > sci
>  
>  		None of these counters has an effect on the function
>  		of the system, they are simply statistics.
> @@ -165,32 +174,34 @@ Description:
>  
>  		Let's take power button fixed event for example, please kill acpid
>  		and other user space applications so that the machine won't shutdown
> -		when pressing the power button.
> -		# cat ff_pwr_btn
> -		0	enabled
> -		# press the power button for 3 times;
> -		# cat ff_pwr_btn
> -		3	enabled
> -		# echo disable > ff_pwr_btn
> -		# cat ff_pwr_btn
> -		3	disabled
> -		# press the power button for 3 times;
> -		# cat ff_pwr_btn
> -		3	disabled
> -		# echo enable > ff_pwr_btn
> -		# cat ff_pwr_btn
> -		4	enabled
> -		/*
> -		 * this is because the status bit is set even if the enable bit is cleared,
> -		 * and it triggers an ACPI fixed event when the enable bit is set again
> -		 */
> -		# press the power button for 3 times;
> -		# cat ff_pwr_btn
> -		7	enabled
> -		# echo disable > ff_pwr_btn
> -		# press the power button for 3 times;
> -		# echo clear > ff_pwr_btn	/* clear the status bit */
> -		# echo disable > ff_pwr_btn
> -		# cat ff_pwr_btn
> -		7	enabled
> +		when pressing the power button::
> +
> +		  # cat ff_pwr_btn
> +		  0	enabled
> +		  # press the power button for 3 times;
> +		  # cat ff_pwr_btn
> +		  3	enabled
> +		  # echo disable > ff_pwr_btn
> +		  # cat ff_pwr_btn
> +		  3	disabled
> +		  # press the power button for 3 times;
> +		  # cat ff_pwr_btn
> +		  3	disabled
> +		  # echo enable > ff_pwr_btn
> +		  # cat ff_pwr_btn
> +		  4	enabled
> +		  /*
> +		   * this is because the status bit is set even if the enable
> +		   * bit is cleared, and it triggers an ACPI fixed event when
> +		   * the enable bit is set again
> +		   */
> +		  # press the power button for 3 times;
> +		  # cat ff_pwr_btn
> +		  7	enabled
> +		  # echo disable > ff_pwr_btn
> +		  # press the power button for 3 times;
> +		  # echo clear > ff_pwr_btn	/* clear the status bit */
> +		  # echo disable > ff_pwr_btn
> +		  # cat ff_pwr_btn
> +		  7	enabled
>  
> diff --git a/Documentation/ABI/testing/sysfs-firmware-dmi-entries b/Documentation/ABI/testing/sysfs-firmware-dmi-entries
> index 210ad44b95a5..fe0289c87768 100644
> --- a/Documentation/ABI/testing/sysfs-firmware-dmi-entries
> +++ b/Documentation/ABI/testing/sysfs-firmware-dmi-entries
> @@ -33,7 +33,7 @@ Description:
>  		doesn't matter), they will be represented in sysfs as
>  		entries "T-0" through "T-(N-1)":
>  
> -		Example entry directories:
> +		Example entry directories::
>  
>  			/sys/firmware/dmi/entries/17-0
>  			/sys/firmware/dmi/entries/17-1
> @@ -50,61 +50,65 @@ Description:
>  		Each DMI entry in sysfs has the common header values
>  		exported as attributes:
>  
> -		handle	: The 16bit 'handle' that is assigned to this
> +		========  =================================================
> +		handle	  The 16bit 'handle' that is assigned to this
>  			  entry by the firmware.  This handle may be
>  			  referred to by other entries.
> -		length	: The length of the entry, as presented in the
> +		length	  The length of the entry, as presented in the
>  			  entry itself.  Note that this is _not the
>  			  total count of bytes associated with the
> -			  entry_.  This value represents the length of
> +			  entry.  This value represents the length of
>  			  the "formatted" portion of the entry.  This
>  			  "formatted" region is sometimes followed by
>  			  the "unformatted" region composed of nul
>  			  terminated strings, with termination signalled
>  			  by a two nul characters in series.
> -		raw	: The raw bytes of the entry. This includes the
> +		raw	  The raw bytes of the entry. This includes the
>  			  "formatted" portion of the entry, the
>  			  "unformatted" strings portion of the entry,
>  			  and the two terminating nul characters.
> -		type	: The type of the entry.  This value is the same
> +		type	  The type of the entry.  This value is the same
>  			  as found in the directory name.  It indicates
>  			  how the rest of the entry should be interpreted.
> -		instance: The instance ordinal of the entry for the
> +		instance  The instance ordinal of the entry for the
>  			  given type.  This value is the same as found
>  			  in the parent directory name.
> -		position: The ordinal position (zero-based) of the entry
> +		position  The ordinal position (zero-based) of the entry
>  			  within the entirety of the DMI entry table.
> +		========  =================================================
>  
> -		=== Entry Specialization ===
> +		**Entry Specialization**
>  
>  		Some entry types may have other information available in
>  		sysfs.  Not all types are specialized.
>  
> -		--- Type 15 - System Event Log ---
> +		**Type 15 - System Event Log**
>  
>  		This entry allows the firmware to export a log of
>  		events the system has taken.  This information is
>  		typically backed by nvram, but the implementation
>  		details are abstracted by this table.  This entry's data
> -		is exported in the directory:
> +		is exported in the directory::
>  
> -		/sys/firmware/dmi/entries/15-0/system_event_log
> +		  /sys/firmware/dmi/entries/15-0/system_event_log
>  
>  		and has the following attributes (documented in the
>  		SMBIOS / DMI specification under "System Event Log (Type 15)":
>  
> -		area_length
> -		header_start_offset
> -		data_start_offset
> -		access_method
> -		status
> -		change_token
> -		access_method_address
> -		header_format
> -		per_log_type_descriptor_length
> -		type_descriptors_supported_count
> +		- area_length
> +		- header_start_offset
> +		- data_start_offset
> +		- access_method
> +		- status
> +		- change_token
> +		- access_method_address
> +		- header_format
> +		- per_log_type_descriptor_length
> +		- type_descriptors_supported_count
>  
>  		As well, the kernel exports the binary attribute:
>  
> -		raw_event_log	: The raw binary bits of the event log
> +		=============	  ====================================
> +		raw_event_log	  The raw binary bits of the event log
>  				  as described by the DMI entry.
> +		=============	  ====================================
> diff --git a/Documentation/ABI/testing/sysfs-firmware-gsmi b/Documentation/ABI/testing/sysfs-firmware-gsmi
> index 0faa0aaf4b6a..7a558354c1ee 100644
> --- a/Documentation/ABI/testing/sysfs-firmware-gsmi
> +++ b/Documentation/ABI/testing/sysfs-firmware-gsmi
> @@ -20,7 +20,7 @@ Description:
>  
>  			This directory has the same layout (and
>  			underlying implementation as /sys/firmware/efi/vars.
> -			See Documentation/ABI/*/sysfs-firmware-efi-vars
> +			See `Documentation/ABI/*/sysfs-firmware-efi-vars`
>  			for more information on how to interact with
>  			this structure.
>  
> diff --git a/Documentation/ABI/testing/sysfs-firmware-memmap b/Documentation/ABI/testing/sysfs-firmware-memmap
> index eca0d65087dc..1f6f4d3a32c0 100644
> --- a/Documentation/ABI/testing/sysfs-firmware-memmap
> +++ b/Documentation/ABI/testing/sysfs-firmware-memmap
> @@ -20,7 +20,7 @@ Description:
>  		the raw memory map to userspace.
>  
>  		The structure is as follows: Under /sys/firmware/memmap there
> -		are subdirectories with the number of the entry as their name:
> +		are subdirectories with the number of the entry as their name::
>  
>  			/sys/firmware/memmap/0
>  			/sys/firmware/memmap/1
> @@ -34,14 +34,16 @@ Description:
>  
>  		Each directory contains three files:
>  
> -		start	: The start address (as hexadecimal number with the
> +		========  =====================================================
> +		start	  The start address (as hexadecimal number with the
>  			  '0x' prefix).
> -		end	: The end address, inclusive (regardless whether the
> +		end	  The end address, inclusive (regardless whether the
>  			  firmware provides inclusive or exclusive ranges).
> -		type	: Type of the entry as string. See below for a list of
> +		type	  Type of the entry as string. See below for a list of
>  			  valid types.
> +		========  =====================================================
>  
> -		So, for example:
> +		So, for example::
>  
>  			/sys/firmware/memmap/0/start
>  			/sys/firmware/memmap/0/end
> @@ -57,9 +59,8 @@ Description:
>  		  - reserved
>  
>  		Following shell snippet can be used to display that memory
> -		map in a human-readable format:
> +		map in a human-readable format::
>  
> -		-------------------- 8< ----------------------------------------
>  		  #!/bin/bash
>  		  cd /sys/firmware/memmap
>  		  for dir in * ; do
> @@ -68,4 +69,3 @@ Description:
>  		      type=$(cat $dir/type)
>  		      printf "%016x-%016x (%s)\n" $start $[ $end +1] "$type"
>  		  done
> -		-------------------- >8 ----------------------------------------
> diff --git a/Documentation/ABI/testing/sysfs-fs-ext4 b/Documentation/ABI/testing/sysfs-fs-ext4
> index 78604db56279..99e3d92f8299 100644
> --- a/Documentation/ABI/testing/sysfs-fs-ext4
> +++ b/Documentation/ABI/testing/sysfs-fs-ext4
> @@ -45,8 +45,8 @@ Description:
>  		parameter will have their blocks allocated out of a
>  		block group specific preallocation pool, so that small
>  		files are packed closely together.  Each large file
> -		 will have its blocks allocated out of its own unique
> -		 preallocation pool.
> +		will have its blocks allocated out of its own unique
> +		preallocation pool.
>  
>  What:		/sys/fs/ext4/<disk>/inode_readahead_blks
>  Date:		March 2008
> diff --git a/Documentation/ABI/testing/sysfs-hypervisor-xen b/Documentation/ABI/testing/sysfs-hypervisor-xen
> index 53b7b2ea7515..4dbe0c49b393 100644
> --- a/Documentation/ABI/testing/sysfs-hypervisor-xen
> +++ b/Documentation/ABI/testing/sysfs-hypervisor-xen
> @@ -15,14 +15,17 @@ KernelVersion:	4.3
>  Contact:	Boris Ostrovsky <boris.ostrovsky@oracle.com>
>  Description:	If running under Xen:
>  		Describes mode that Xen's performance-monitoring unit (PMU)
> -		uses. Accepted values are
> -			"off"  -- PMU is disabled
> -			"self" -- The guest can profile itself
> -			"hv"   -- The guest can profile itself and, if it is
> +		uses. Accepted values are:
> +
> +			======    ============================================
> +			"off"     PMU is disabled
> +			"self"    The guest can profile itself
> +			"hv"      The guest can profile itself and, if it is
>  				  privileged (e.g. dom0), the hypervisor
> -			"all" --  The guest can profile itself, the hypervisor
> +			"all"     The guest can profile itself, the hypervisor
>  				  and all other guests. Only available to
>  				  privileged guests.
> +			======    ============================================
>  
>  What:           /sys/hypervisor/pmu/pmu_features
>  Date:           August 2015
> diff --git a/Documentation/ABI/testing/sysfs-kernel-boot_params b/Documentation/ABI/testing/sysfs-kernel-boot_params
> index eca38ce2852d..7f9bda453c4d 100644
> --- a/Documentation/ABI/testing/sysfs-kernel-boot_params
> +++ b/Documentation/ABI/testing/sysfs-kernel-boot_params
> @@ -23,16 +23,17 @@ Description:	The /sys/kernel/boot_params directory contains two
>  		representation of setup_data type. "data" file is the binary
>  		representation of setup_data payload.
>  
> -		The whole boot_params directory structure is like below:
> -		/sys/kernel/boot_params
> -		|__ data
> -		|__ setup_data
> -		|   |__ 0
> -		|   |   |__ data
> -		|   |   |__ type
> -		|   |__ 1
> -		|       |__ data
> -		|       |__ type
> -		|__ version
> +		The whole boot_params directory structure is like below::
> +
> +		  /sys/kernel/boot_params
> +		  |__ data
> +		  |__ setup_data
> +		  |   |__ 0
> +		  |   |   |__ data
> +		  |   |   |__ type
> +		  |   |__ 1
> +		  |       |__ data
> +		  |       |__ type
> +		  |__ version
>  
>  Users:		Kexec
> diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-hugepages b/Documentation/ABI/testing/sysfs-kernel-mm-hugepages
> index fdaa2162fae1..294387e2c7fb 100644
> --- a/Documentation/ABI/testing/sysfs-kernel-mm-hugepages
> +++ b/Documentation/ABI/testing/sysfs-kernel-mm-hugepages
> @@ -7,9 +7,11 @@ Description:
>  		of the hugepages supported by the kernel/CPU combination.
>  
>  		Under these directories are a number of files:
> -			nr_hugepages
> -			nr_overcommit_hugepages
> -			free_hugepages
> -			surplus_hugepages
> -			resv_hugepages
> +
> +			- nr_hugepages
> +			- nr_overcommit_hugepages
> +			- free_hugepages
> +			- surplus_hugepages
> +			- resv_hugepages
> +
>  		See Documentation/admin-guide/mm/hugetlbpage.rst for details.
> diff --git a/Documentation/ABI/testing/sysfs-platform-asus-laptop b/Documentation/ABI/testing/sysfs-platform-asus-laptop
> index 8b0e8205a6a2..c78d358dbdbe 100644
> --- a/Documentation/ABI/testing/sysfs-platform-asus-laptop
> +++ b/Documentation/ABI/testing/sysfs-platform-asus-laptop
> @@ -4,13 +4,16 @@ KernelVersion:	2.6.20
>  Contact:	"Corentin Chary" <corentincj@iksaif.net>
>  Description:
>  		This file allows display switching. The value
> -		is composed by 4 bits and defined as follow:
> -		4321
> -		|||`- LCD
> -		||`-- CRT
> -		|`--- TV
> -		`---- DVI
> -		Ex: - 0 (0000b) means no display
> +		is composed by 4 bits and defined as follow::
> +
> +		  4321
> +		  |||`- LCD
> +		  ||`-- CRT
> +		  |`--- TV
> +		  `---- DVI
> +
> +		Ex:
> +		    - 0 (0000b) means no display
>  		    - 3 (0011b) CRT+LCD.
>  
>  What:		/sys/devices/platform/asus_laptop/gps
> @@ -28,8 +31,10 @@ Contact:	"Corentin Chary" <corentincj@iksaif.net>
>  Description:
>  		Some models like the W1N have a LED display that can be
>  		used to display several items of information.
> -		To control the LED display, use the following :
> +		To control the LED display, use the following::
> +
>  		    echo 0x0T000DDD > /sys/devices/platform/asus_laptop/
> +
>  		where T control the 3 letters display, and DDD the 3 digits display.
>  		The DDD table can be found in Documentation/admin-guide/laptops/asus-laptop.rst
>  
> diff --git a/Documentation/ABI/testing/sysfs-platform-asus-wmi b/Documentation/ABI/testing/sysfs-platform-asus-wmi
> index 1efac0ddb417..04885738cf15 100644
> --- a/Documentation/ABI/testing/sysfs-platform-asus-wmi
> +++ b/Documentation/ABI/testing/sysfs-platform-asus-wmi
> @@ -5,6 +5,7 @@ Contact:	"Corentin Chary" <corentincj@iksaif.net>
>  Description:
>  		Change CPU clock configuration (write-only).
>  		There are three available clock configuration:
> +
>  		    * 0 -> Super Performance Mode
>  		    * 1 -> High Performance Mode
>  		    * 2 -> Power Saving Mode
> diff --git a/Documentation/ABI/testing/sysfs-platform-at91 b/Documentation/ABI/testing/sysfs-platform-at91
> index 4cc6a865ae66..b146be74b8e0 100644
> --- a/Documentation/ABI/testing/sysfs-platform-at91
> +++ b/Documentation/ABI/testing/sysfs-platform-at91
> @@ -18,8 +18,10 @@ Description:
>  		In order to use an extended can_id add the
>  		CAN_EFF_FLAG (0x80000000U) to the can_id. Example:
>  
> -		- standard id 0x7ff:
> -		echo 0x7ff      > /sys/class/net/can0/mb0_id
> +		- standard id 0x7ff::
>  
> -		- extended id 0x1fffffff:
> -		echo 0x9fffffff > /sys/class/net/can0/mb0_id
> +		    echo 0x7ff      > /sys/class/net/can0/mb0_id
> +
> +		- extended id 0x1fffffff::
> +
> +		    echo 0x9fffffff > /sys/class/net/can0/mb0_id
> diff --git a/Documentation/ABI/testing/sysfs-platform-eeepc-laptop b/Documentation/ABI/testing/sysfs-platform-eeepc-laptop
> index 5b026c69587a..70dbe0733cf6 100644
> --- a/Documentation/ABI/testing/sysfs-platform-eeepc-laptop
> +++ b/Documentation/ABI/testing/sysfs-platform-eeepc-laptop
> @@ -4,9 +4,11 @@ KernelVersion:	2.6.26
>  Contact:	"Corentin Chary" <corentincj@iksaif.net>
>  Description:
>  		This file allows display switching.
> +
>  		- 1 = LCD
>  		- 2 = CRT
>  		- 3 = LCD+CRT
> +
>  		If you run X11, you should use xrandr instead.
>  
>  What:		/sys/devices/platform/eeepc/camera
> @@ -30,16 +32,20 @@ Contact:	"Corentin Chary" <corentincj@iksaif.net>
>  Description:
>  		Change CPU clock configuration.
>  		On the Eee PC 1000H there are three available clock configuration:
> +
>  		    * 0 -> Super Performance Mode
>  		    * 1 -> High Performance Mode
>  		    * 2 -> Power Saving Mode
> +
>  		On Eee PC 701 there is only 2 available clock configurations.
>  		Available configuration are listed in available_cpufv file.
>  		Reading this file will show the raw hexadecimal value which
> -		is defined as follow:
> -		| 8 bit | 8 bit |
> -		    |       `---- Current mode
> -		    `------------ Availables modes
> +		is defined as follow::
> +
> +		  | 8 bit | 8 bit |
> +		      |       `---- Current mode
> +		      `------------ Availables modes
> +
>  		For example, 0x301 means: mode 1 selected, 3 available modes.
>  
>  What:		/sys/devices/platform/eeepc/available_cpufv
> diff --git a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop
> index 1b31be3f996a..fd2ac02bc5bd 100644
> --- a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop
> +++ b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop
> @@ -12,6 +12,7 @@ Contact:	"Maxim Mikityanskiy <maxtram95@gmail.com>"
>  Description:
>  		Change fan mode
>  		There are four available modes:
> +
>  			* 0 -> Super Silent Mode
>  			* 1 -> Standard Mode
>  			* 2 -> Dust Cleaning
> @@ -32,9 +33,11 @@ KernelVersion:	4.18
>  Contact:	"Oleg Keri <ezhi99@gmail.com>"
>  Description:
>  		Control fn-lock mode.
> +
>  			* 1 -> Switched On
>  			* 0 -> Switched Off
>  
> -		For example:
> -		# echo "0" >	\
> -		/sys/bus/pci/devices/0000:00:1f.0/PNP0C09:00/VPC2004:00/fn_lock
> +		For example::
> +
> +		  # echo "0" >	\
> +		  /sys/bus/pci/devices/0000:00:1f.0/PNP0C09:00/VPC2004:00/fn_lock
> diff --git a/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt b/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt
> index 8af65059d519..e19144fd5d86 100644
> --- a/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt
> +++ b/Documentation/ABI/testing/sysfs-platform-intel-wmi-thunderbolt
> @@ -7,5 +7,6 @@ Description:
>  		Thunderbolt controllers to turn on or off when no
>  		devices are connected (write-only)
>  		There are two available states:
> +
>  		    * 0 -> Force power disabled
>  		    * 1 -> Force power enabled
> diff --git a/Documentation/ABI/testing/sysfs-platform-sst-atom b/Documentation/ABI/testing/sysfs-platform-sst-atom
> index 0d07c0395660..d5f6e21f0e42 100644
> --- a/Documentation/ABI/testing/sysfs-platform-sst-atom
> +++ b/Documentation/ABI/testing/sysfs-platform-sst-atom
> @@ -5,13 +5,22 @@ Contact:	"Sebastien Guiriec" <sebastien.guiriec@intel.com>
>  Description:
>  		LPE Firmware version for SST driver on all atom
>  		plaforms (BYT/CHT/Merrifield/BSW).
> -		If the FW has never been loaded it will display:
> +		If the FW has never been loaded it will display::
> +
>  			"FW not yet loaded"
> -		If FW has been loaded it will display:
> +
> +		If FW has been loaded it will display::
> +
>  			"v01.aa.bb.cc"
> +
>  		aa: Major version is reflecting SoC version:
> +
> +			=== =============
>  			0d: BYT FW
>  			0b: BSW FW
>  			07: Merrifield FW
> +			=== =============
> +
>  		bb: Minor version
> +
>  		cc: Build version
> diff --git a/Documentation/ABI/testing/sysfs-platform-usbip-vudc b/Documentation/ABI/testing/sysfs-platform-usbip-vudc
> index 81fcfb454913..53622d3ba27c 100644
> --- a/Documentation/ABI/testing/sysfs-platform-usbip-vudc
> +++ b/Documentation/ABI/testing/sysfs-platform-usbip-vudc
> @@ -16,10 +16,13 @@ Contact:	Krzysztof Opasiak <k.opasiak@samsung.com>
>  Description:
>  		Current status of the device.
>  		Allowed values:
> -		1 - Device is available and can be exported
> -		2 - Device is currently exported
> -		3 - Fatal error occurred during communication
> -		  with peer
> +
> +		==  ==========================================
> +		1   Device is available and can be exported
> +		2   Device is currently exported
> +		3   Fatal error occurred during communication
> +		    with peer
> +		==  ==========================================
>  
>  What:		/sys/devices/platform/usbip-vudc.%d/usbip_sockfd
>  Date:		April 2016
> diff --git a/Documentation/ABI/testing/sysfs-ptp b/Documentation/ABI/testing/sysfs-ptp
> index a17f817a9309..2363ad810ddb 100644
> --- a/Documentation/ABI/testing/sysfs-ptp
> +++ b/Documentation/ABI/testing/sysfs-ptp
> @@ -69,7 +69,7 @@ Description:
>  		pin offered by the PTP hardware clock. The file name
>  		is the hardware dependent pin name. Reading from this
>  		file produces two numbers, the assigned function (see
> -		the PTP_PF_ enumeration values in linux/ptp_clock.h)
> +		the `PTP_PF_` enumeration values in linux/ptp_clock.h)
>  		and the channel number. The function and channel
>  		assignment may be changed by two writing numbers into
>  		the file.
> 

Re: [PATCH v2 31/39] docs: ABI: cleanup several ABI documents

[Suzuki K Poulose]

On 10/30/20 7:40 AM, Mauro Carvalho Chehab wrote:
> There are some ABI documents that, while they don't generate
> any warnings, they have issues when parsed by get_abi.pl script
> on its output result.
> 
> Address them, in order to provide a clean output.
> 
> Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> #for IIO
> Reviewed-by: Tom Rix <trix@redhat.com> # for fpga-manager
> Reviewed-By: Kajol Jain<kjain@linux.ibm.com> # for sysfs-bus-event_source-devices-hv_gpci and sysfs-bus-event_source-devices-hv_24x7
> Acked-by: Oded Gabbay <oded.gabbay@gmail.com> # for Habanalabs
> Acked-by: Vaibhav Jain <vaibhav@linux.ibm.com> # for sysfs-bus-papr-pmem
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>



>   .../testing/sysfs-bus-coresight-devices-etb10 |   5 +-
For the above,

Acked-by: Suzuki K Poulose <suzuki.poulose@arm.com>

Re: [PATCH v2 19/39] docs: ABI: stable: make files ReST compatible

[Srinivas Kandagatla]

On 30/10/2020 07:40, Mauro Carvalho Chehab wrote:
> Several entries at the stable ABI files won't parse if we pass
> them directly to the ReST output.
> 
> Adjust them, in order to allow adding their contents as-is at
> the stable ABI book.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>   Documentation/ABI/stable/firewire-cdev        |  4 +
>   Documentation/ABI/stable/sysfs-acpi-pmprofile | 22 +++--
>   Documentation/ABI/stable/sysfs-bus-firewire   |  3 +
>   Documentation/ABI/stable/sysfs-bus-nvmem      | 19 ++--

for nvmem parts:

Acked-by: Srinivas Kandagatla <srinivas.kandagatla@linaro.org>

--srini

>   Documentation/ABI/stable/sysfs-bus-usb        |  6 +-
>   .../ABI/stable/sysfs-class-backlight          |  1 +
>   .../ABI/stable/sysfs-class-infiniband         | 93 +++++++++++++------
>   Documentation/ABI/stable/sysfs-class-rfkill   | 13 ++-
>   Documentation/ABI/stable/sysfs-class-tpm      | 90 +++++++++---------
>   Documentation/ABI/stable/sysfs-devices        |  5 +-
>   Documentation/ABI/stable/sysfs-driver-ib_srp  |  1 +
>   .../ABI/stable/sysfs-firmware-efi-vars        |  4 +
>   .../ABI/stable/sysfs-firmware-opal-dump       |  5 +
>   .../ABI/stable/sysfs-firmware-opal-elog       |  2 +
>   Documentation/ABI/stable/sysfs-hypervisor-xen |  3 +
>   Documentation/ABI/stable/vdso                 |  5 +-
>   16 files changed, 176 insertions(+), 100 deletions(-)
> 

Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Mauro Carvalho Chehab]

Em Fri, 30 Oct 2020 10:19:12 +0100
Fabrice Gasnier <fabrice.gasnier@st.com> escreveu:

> Hi Mauro,
> 
> [...]
> 
> >  
> > +What:		/sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> > +KernelVersion:	4.12
> > +Contact:	benjamin.gaignard@st.com
> > +Description:
> > +		Reading returns the list possible quadrature modes.
> > +
> > +What:		/sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode
> > +KernelVersion:	4.12
> > +Contact:	benjamin.gaignard@st.com
> > +Description:
> > +		Configure the device counter quadrature modes:
> > +
> > +		channel_A:
> > +			Encoder A input servers as the count input and B as
> > +			the UP/DOWN direction control input.
> > +
> > +		channel_B:
> > +			Encoder B input serves as the count input and A as
> > +			the UP/DOWN direction control input.
> > +
> > +		quadrature:
> > +			Encoder A and B inputs are mixed to get direction
> > +			and count with a scale of 0.25.
> > +  
> 

Hi Fabrice,

> I just noticed that since Jonathan question in v1.
> 
> Above ABI has been moved in the past as discussed in [1]. You can take a
> look at:
> b299d00 IIO: stm32: Remove quadrature related functions from trigger driver
> 
> Could you please remove the above chunk ?
> 
> With that, for the stm32 part:
> Acked-by: Fabrice Gasnier <fabrice.gasnier@st.com>


Hmm... probably those were re-introduced due to a rebase. This
series were originally written about 1,5 years ago.

I'll drop those hunks.

Thanks!
Mauro

Re: [PATCH v2 31/39] docs: ABI: cleanup several ABI documents

[Ilya Dryomov]

On Fri, Oct 30, 2020 at 8:41 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> There are some ABI documents that, while they don't generate
> any warnings, they have issues when parsed by get_abi.pl script
> on its output result.
>
> Address them, in order to provide a clean output.
>
> Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> #for IIO
> Reviewed-by: Tom Rix <trix@redhat.com> # for fpga-manager
> Reviewed-By: Kajol Jain<kjain@linux.ibm.com> # for sysfs-bus-event_source-devices-hv_gpci and sysfs-bus-event_source-devices-hv_24x7
> Acked-by: Oded Gabbay <oded.gabbay@gmail.com> # for Habanalabs
> Acked-by: Vaibhav Jain <vaibhav@linux.ibm.com> # for sysfs-bus-papr-pmem
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>
> [...]
>
>  Documentation/ABI/testing/sysfs-bus-rbd       |  37 ++-

Acked-by: Ilya Dryomov <idryomov@gmail.com> # for rbd

Thanks,

                Ilya

Re: [PATCH v2 27/39] docs: ABI: convert testing/configfs-acpi to ReST

[Rafael J. Wysocki]

On Fri, Oct 30, 2020 at 8:42 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> There are some problems with this file when a ReST content
> is produced. Fix it.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

Acked-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

and I assume this to go in via the documentation tree.

> ---
>  Documentation/ABI/testing/configfs-acpi | 34 ++++++++++++++++++-------
>  1 file changed, 25 insertions(+), 9 deletions(-)
>
> diff --git a/Documentation/ABI/testing/configfs-acpi b/Documentation/ABI/testing/configfs-acpi
> index 4ab4e99aa863..c09b640c3cb1 100644
> --- a/Documentation/ABI/testing/configfs-acpi
> +++ b/Documentation/ABI/testing/configfs-acpi
> @@ -14,7 +14,8 @@ Description:
>                 This group contains the configuration for user defined ACPI
>                 tables. The attributes of a user define table are:
>
> -               aml             - a binary attribute that the user can use to
> +               aml
> +                             - a binary attribute that the user can use to
>                                 fill in the ACPI aml definitions. Once the aml
>                                 data is written to this file and the file is
>                                 closed the table will be loaded and ACPI devices
> @@ -26,11 +27,26 @@ Description:
>                 The rest of the attributes are read-only and are valid only
>                 after the table has been loaded by filling the aml entry:
>
> -               signature       - ASCII table signature
> -               length          - length of table in bytes, including the header
> -               revision        - ACPI Specification minor version number
> -               oem_id          - ASCII OEM identification
> -               oem_table_id    - ASCII OEM table identification
> -               oem_revision    - OEM revision number
> -               asl_compiler_id - ASCII ASL compiler vendor ID
> -               asl_compiler_revision - ASL compiler version
> +               signature
> +                               - ASCII table signature
> +
> +               length
> +                               - length of table in bytes, including the header
> +
> +               revision
> +                               - ACPI Specification minor version number
> +
> +               oem_id
> +                               - ASCII OEM identification
> +
> +               oem_table_id
> +                               - ASCII OEM table identification
> +
> +               oem_revision
> +                               - OEM revision number
> +
> +               asl_compiler_id
> +                               - ASCII ASL compiler vendor ID
> +
> +               asl_compiler_revision
> +                               - ASL compiler version
> --
> 2.26.2
>

Re: [PATCH v2 28/39] docs: ABI: fix syntax to be parsed using ReST notation

[Rafael J. Wysocki]

On Fri, Oct 30, 2020 at 8:41 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> There are a number of new changes at the ABI files that cause
> them to produce warnings when generating ABI output.
>
> Fix them.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  .../ABI/stable/sysfs-driver-firmware-zynqmp   | 62 ++++++++-----
>  Documentation/ABI/testing/debugfs-moxtet      | 28 ++++--
>  .../ABI/testing/debugfs-turris-mox-rwtm       |  6 +-
>  .../sysfs-bus-event_source-devices-dfl_fme    | 14 +--
>  Documentation/ABI/testing/sysfs-bus-most      |  6 +-
>  Documentation/ABI/testing/sysfs-class-devfreq |  6 +-
>  Documentation/ABI/testing/sysfs-class-ocxl    | 14 +--
>  .../ABI/testing/sysfs-class-power-wilco       | 18 ++--
>  .../ABI/testing/sysfs-class-rnbd-client       | 93 ++++++++++---------
>  .../ABI/testing/sysfs-class-rtrs-client       | 23 +++--
>  .../sysfs-devices-platform-stratix10-rsu      | 10 ++
>  .../ABI/testing/sysfs-driver-w1_therm         | 75 ++++++++++-----
>  .../ABI/testing/sysfs-platform-dfl-fme        | 14 ++-
>  Documentation/ABI/testing/sysfs-platform-dptf | 11 ++-

For the DPTF part

Acked-by: Rafael J. Wysocki <rafael.j.wysocki@intel.com>

>  .../sysfs-platform-intel-wmi-sbl-fw-update    |  1 +
>  .../testing/sysfs-platform-mellanox-bootctl   | 50 ++++++----
>  .../ABI/testing/sysfs-platform-wilco-ec       |  1 +
>  17 files changed, 271 insertions(+), 161 deletions(-)
>
> diff --git a/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp b/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
> index 00fa04c76ff3..f5724bb5b462 100644
> --- a/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
> +++ b/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
> @@ -12,13 +12,15 @@ Description:
>                 resets. Three registers are used by the FSBL and
>                 other Xilinx software products: GLOBAL_GEN_STORAGE{4:6}.
>
> -               Usage:
> -               # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> -               # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> +               Usage::
>
> -               Example:
> -               # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> -               # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> +                   # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> +                   # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> +
> +               Example::
> +
> +                   # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> +                   # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
>
>  Users:         Xilinx
>
> @@ -39,13 +41,15 @@ Description:
>                 software products: PERS_GLOB_GEN_STORAGE{4:7}.
>                 Register is reset only by a POR reset.
>
> -               Usage:
> -               # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> -               # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> +               Usage::
>
> -               Example:
> -               # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> -               # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> +                   # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> +                   # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> +
> +               Example::
> +
> +                   # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> +                   # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
>
>  Users:         Xilinx
>
> @@ -61,23 +65,28 @@ Description:
>
>                 Following are available shutdown scopes(subtypes):
>
> -               subsystem:      Only the APU along with all of its peripherals
> +               subsystem:
> +                               Only the APU along with all of its peripherals
>                                 not used by other processing units will be
>                                 shut down. This may result in the FPD power
>                                 domain being shut down provided that no other
>                                 processing unit uses FPD peripherals or DRAM.
> -               ps_only:        The complete PS will be shut down, including the
> +               ps_only:
> +                               The complete PS will be shut down, including the
>                                 RPU, PMU, etc.  Only the PL domain (FPGA)
>                                 remains untouched.
> -               system:         The complete system/device is shut down.
> +               system:
> +                               The complete system/device is shut down.
>
> -               Usage:
> -               # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> -               # echo <scope> > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> +               Usage::
>
> -               Example:
> -               # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> -               # echo "subsystem" > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> +                   # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> +                   # echo <scope> > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> +
> +               Example::
> +
> +                   # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> +                   # echo "subsystem" > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
>
>  Users:         Xilinx
>
> @@ -94,10 +103,13 @@ Description:
>                 system restart.
>
>                 Usage:
> -               Set healthy bit
> -               # echo 1 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status
>
> -               Unset healthy bit
> -               # echo 0 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status
> +               Set healthy bit::
> +
> +                   # echo 1 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status
> +
> +               Unset healthy bit::
> +
> +                   # echo 0 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status
>
>  Users:         Xilinx
> diff --git a/Documentation/ABI/testing/debugfs-moxtet b/Documentation/ABI/testing/debugfs-moxtet
> index 67b1717794d8..15dfaecb2892 100644
> --- a/Documentation/ABI/testing/debugfs-moxtet
> +++ b/Documentation/ABI/testing/debugfs-moxtet
> @@ -5,10 +5,16 @@ Contact:      Marek Behún <marek.behun@nic.cz>
>  Description:   (R) Read input from the shift registers, in hexadecimal.
>                 Returns N+1 bytes, where N is the number of Moxtet connected
>                 modules. The first byte is from the CPU board itself.
> -               Example: 101214
> -                        10: CPU board with SD card
> -                        12: 2 = PCIe module, 1 = IRQ not active
> -                        14: 4 = Peridot module, 1 = IRQ not active
> +
> +               Example::
> +
> +                       101214
> +
> +               ==  =======================================
> +               10  CPU board with SD card
> +               12  2 = PCIe module, 1 = IRQ not active
> +               14  4 = Peridot module, 1 = IRQ not active
> +               ==  =======================================
>
>  What:          /sys/kernel/debug/moxtet/output
>  Date:          March 2019
> @@ -17,7 +23,13 @@ Contact:     Marek Behún <marek.behun@nic.cz>
>  Description:   (RW) Read last written value to the shift registers, in
>                 hexadecimal, or write values to the shift registers, also
>                 in hexadecimal.
> -               Example: 0102
> -                        01: 01 was last written, or is to be written, to the
> -                            first module's shift register
> -                        02: the same for second module
> +
> +               Example::
> +
> +                   0102
> +
> +               ==  ================================================
> +               01  01 was last written, or is to be written, to the
> +                   first module's shift register
> +               02  the same for second module
> +               ==  ================================================
> diff --git a/Documentation/ABI/testing/debugfs-turris-mox-rwtm b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
> index 2b3255ee68fd..c8f7dadd591c 100644
> --- a/Documentation/ABI/testing/debugfs-turris-mox-rwtm
> +++ b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
> @@ -2,8 +2,10 @@ What:          /sys/kernel/debug/turris-mox-rwtm/do_sign
>  Date:          Jun 2020
>  KernelVersion: 5.8
>  Contact:       Marek Behún <marek.behun@nic.cz>
> -Description:   (W) Message to sign with the ECDSA private key stored in
> +Description:   (W)
> +                   Message to sign with the ECDSA private key stored in
>                     device's OTP. The message must be exactly 64 bytes (since
>                     this is intended for SHA-512 hashes).
> -               (R) The resulting signature, 136 bytes. This contains the R and
> +               (R)
> +                   The resulting signature, 136 bytes. This contains the R and
>                     S values of the ECDSA signature, both in big-endian format.
> diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme b/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme
> index c9278a3b3df1..63a32ddcb95e 100644
> --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme
> +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme
> @@ -8,13 +8,13 @@ Description:  Read-only. Attribute group to describe the magic bits
>
>                 Each attribute under this group defines a bit range of the
>                 perf_event_attr.config. All supported attributes are listed
> -               below.
> +               below::
>
>                     event  = "config:0-11"  - event ID
>                     evtype = "config:12-15" - event type
>                     portid = "config:16-23" - event source
>
> -               For example,
> +               For example::
>
>                     fab_mmio_read = "event=0x06,evtype=0x02,portid=0xff"
>
> @@ -40,11 +40,11 @@ Description:        Read-only. Attribute group to describe performance monitoring
>
>                 All supported performance monitoring events are listed below.
>
> -               Basic events (evtype=0x00)
> +               Basic events (evtype=0x00)::
>
>                     clock = "event=0x00,evtype=0x00,portid=0xff"
>
> -               Cache events (evtype=0x01)
> +               Cache events (evtype=0x01)::
>
>                     cache_read_hit      = "event=0x00,evtype=0x01,portid=0xff"
>                     cache_read_miss     = "event=0x01,evtype=0x01,portid=0xff"
> @@ -59,7 +59,7 @@ Description:  Read-only. Attribute group to describe performance monitoring
>                     cache_rx_req_stall  = "event=0x09,evtype=0x01,portid=0xff"
>                     cache_eviction      = "event=0x0a,evtype=0x01,portid=0xff"
>
> -               Fabric events (evtype=0x02)
> +               Fabric events (evtype=0x02)::
>
>                     fab_pcie0_read       = "event=0x00,evtype=0x02,portid=0xff"
>                     fab_pcie0_write      = "event=0x01,evtype=0x02,portid=0xff"
> @@ -78,7 +78,7 @@ Description:  Read-only. Attribute group to describe performance monitoring
>                     fab_port_mmio_read   = "event=0x06,evtype=0x02,portid=?"
>                     fab_port_mmio_write  = "event=0x07,evtype=0x02,portid=?"
>
> -               VTD events (evtype=0x03)
> +               VTD events (evtype=0x03)::
>
>                     vtd_port_read_transaction  = "event=0x00,evtype=0x03,portid=?"
>                     vtd_port_write_transaction = "event=0x01,evtype=0x03,portid=?"
> @@ -88,7 +88,7 @@ Description:  Read-only. Attribute group to describe performance monitoring
>                     vtd_port_devtlb_2m_fill    = "event=0x05,evtype=0x03,portid=?"
>                     vtd_port_devtlb_1g_fill    = "event=0x06,evtype=0x03,portid=?"
>
> -               VTD SIP events (evtype=0x04)
> +               VTD SIP events (evtype=0x04)::
>
>                     vtd_sip_iotlb_4k_hit  = "event=0x00,evtype=0x04,portid=0xff"
>                     vtd_sip_iotlb_2m_hit  = "event=0x01,evtype=0x04,portid=0xff"
> diff --git a/Documentation/ABI/testing/sysfs-bus-most b/Documentation/ABI/testing/sysfs-bus-most
> index ec0a603d804b..38cc03e408e7 100644
> --- a/Documentation/ABI/testing/sysfs-bus-most
> +++ b/Documentation/ABI/testing/sysfs-bus-most
> @@ -235,7 +235,8 @@ KernelVersion:      4.15
>  Contact:       Christian Gromm <christian.gromm@microchip.com>
>  Description:
>                 This is to read back the configured direction of the channel.
> -               The following strings will be accepted:
> +               The following strings will be accepted::
> +
>                         'tx',
>                         'rx'
>  Users:
> @@ -246,7 +247,8 @@ KernelVersion:      4.15
>  Contact:       Christian Gromm <christian.gromm@microchip.com>
>  Description:
>                 This is to read back the configured data type of the channel.
> -               The following strings will be accepted:
> +               The following strings will be accepted::
> +
>                         'control',
>                         'async',
>                         'sync',
> diff --git a/Documentation/ABI/testing/sysfs-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq
> index 67af3f31e17c..386bc230a33d 100644
> --- a/Documentation/ABI/testing/sysfs-class-devfreq
> +++ b/Documentation/ABI/testing/sysfs-class-devfreq
> @@ -48,7 +48,8 @@ Description:
>                 driver should provide the list of available frequencies
>                 with its profile. If need to reset the statistics of devfreq
>                 behavior on a specific device, enter 0(zero) to 'trans_stat'
> -               as following:
> +               as following::
> +
>                         echo 0 > /sys/class/devfreq/.../trans_stat
>
>  What:          /sys/class/devfreq/.../available_frequencies
> @@ -124,7 +125,8 @@ Description:
>                 This work timer is used by devfreq workqueue in order to
>                 monitor the device status such as utilization. The user
>                 can change the work timer on runtime according to their demand
> -               as following:
> +               as following::
> +
>                         echo deferrable > /sys/class/devfreq/.../timer
>                         echo delayed > /sys/class/devfreq/.../timer
>
> diff --git a/Documentation/ABI/testing/sysfs-class-ocxl b/Documentation/ABI/testing/sysfs-class-ocxl
> index bf33f4fda58f..847a7edc3113 100644
> --- a/Documentation/ABI/testing/sysfs-class-ocxl
> +++ b/Documentation/ABI/testing/sysfs-class-ocxl
> @@ -13,8 +13,8 @@ Description:  read only
>                 where:
>
>                         ====    ===============================================
> -                       n:      number of currently active contexts, for debug
> -                       max:    maximum number of contexts supported by the AFU
> +                       n       number of currently active contexts, for debug
> +                       max     maximum number of contexts supported by the AFU
>                         ====    ===============================================
>
>  What:          /sys/class/ocxl/<afu name>/pp_mmio_size
> @@ -43,7 +43,9 @@ Contact:      linuxppc-dev@lists.ozlabs.org
>  Description:   read/write
>                 Control whether the FPGA is reloaded on a link reset. Enabled
>                 through a vendor-specific logic block on the FPGA.
> -                       0       Do not reload FPGA image from flash
> -                       1       Reload FPGA image from flash
> -                       unavailable
> -                               The device does not support this capability
> +
> +                       ===========  ===========================================
> +                       0            Do not reload FPGA image from flash
> +                       1            Reload FPGA image from flash
> +                       unavailable  The device does not support this capability
> +                       ===========  ===========================================
> diff --git a/Documentation/ABI/testing/sysfs-class-power-wilco b/Documentation/ABI/testing/sysfs-class-power-wilco
> index 84fde1d0ada0..82af180fcaab 100644
> --- a/Documentation/ABI/testing/sysfs-class-power-wilco
> +++ b/Documentation/ABI/testing/sysfs-class-power-wilco
> @@ -4,17 +4,23 @@ KernelVersion:        5.2
>  Description:
>                 What charging algorithm to use:
>
> -               Standard: Fully charges battery at a standard rate.
> -               Adaptive: Battery settings adaptively optimized based on
> +               Standard:
> +                       Fully charges battery at a standard rate.
> +               Adaptive:
> +                       Battery settings adaptively optimized based on
>                         typical battery usage pattern.
> -               Fast: Battery charges over a shorter period.
> -               Trickle: Extends battery lifespan, intended for users who
> +               Fast:
> +                       Battery charges over a shorter period.
> +               Trickle:
> +                       Extends battery lifespan, intended for users who
>                         primarily use their Chromebook while connected to AC.
> -               Custom: A low and high threshold percentage is specified.
> +               Custom:
> +                       A low and high threshold percentage is specified.
>                         Charging begins when level drops below
>                         charge_control_start_threshold, and ceases when
>                         level is above charge_control_end_threshold.
> -               Long Life: Customized charge rate for last longer battery life.
> +               Long Life:
> +                       Customized charge rate for last longer battery life.
>                         On Wilco device this mode is pre-configured in the factory
>                         through EC's private PID. Swiching to a different mode will
>                         be denied by Wilco EC when Long Life mode is enabled.
> diff --git a/Documentation/ABI/testing/sysfs-class-rnbd-client b/Documentation/ABI/testing/sysfs-class-rnbd-client
> index c084f203b41e..00c0286733d4 100644
> --- a/Documentation/ABI/testing/sysfs-class-rnbd-client
> +++ b/Documentation/ABI/testing/sysfs-class-rnbd-client
> @@ -5,62 +5,70 @@ Contact:      Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud
>  Description:   Provide information about RNBD-client.
>                 All sysfs files that are not read-only provide the usage information on read:
>
> -               Example:
> -               # cat /sys/class/rnbd-client/ctl/map_device
> +               Example::
>
> -               > Usage: echo "sessname=<name of the rtrs session> path=<[srcaddr,]dstaddr>
> -               > [path=<[srcaddr,]dstaddr>] device_path=<full path on remote side>
> -               > [access_mode=<ro|rw|migration>] > map_device
> -               >
> -               > addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ]
> +                   # cat /sys/class/rnbd-client/ctl/map_device
> +
> +                   > Usage: echo "sessname=<name of the rtrs session> path=<[srcaddr,]dstaddr>
> +                   > [path=<[srcaddr,]dstaddr>] device_path=<full path on remote side>
> +                   > [access_mode=<ro|rw|migration>] > map_device
> +                   >
> +                   > addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ]
>
>  What:          /sys/class/rnbd-client/ctl/map_device
>  Date:          Feb 2020
>  KernelVersion: 5.7
>  Contact:       Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
> -Description:   Expected format is the following:
> +Description:   Expected format is the following::
>
> -               sessname=<name of the rtrs session>
> -               path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...]
> -               device_path=<full path on remote side>
> -               [access_mode=<ro|rw|migration>]
> +                   sessname=<name of the rtrs session>
> +                   path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...]
> +                   device_path=<full path on remote side>
> +                   [access_mode=<ro|rw|migration>]
>
>                 Where:
>
> -               sessname: accepts a string not bigger than 256 chars, which identifies
> -               a given session on the client and on the server.
> -               I.e. "clt_hostname-srv_hostname" could be a natural choice.
> +               sessname:
> +                   accepts a string not bigger than 256 chars, which identifies
> +                   a given session on the client and on the server.
> +                   I.e. "clt_hostname-srv_hostname" could be a natural choice.
>
> -               path:     describes a connection between the client and the server by
> -               specifying destination and, when required, the source address.
> -               The addresses are to be provided in the following format:
> +               path:
> +                   describes a connection between the client and the server by
> +                   specifying destination and, when required, the source address.
> +                   The addresses are to be provided in the following format::
>
> -               ip:<IPv6>
> -               ip:<IPv4>
> -               gid:<GID>
> +                       ip:<IPv6>
> +                       ip:<IPv4>
> +                       gid:<GID>
>
> -               for example:
> +               for example::
> +
> +                   path=ip:10.0.0.66
>
> -               path=ip:10.0.0.66
>                 The single addr is treated as the destination.
>                 The connection will be established to this server from any client IP address.
>
> -               path=ip:10.0.0.66,ip:10.0.1.66
> +               ::
> +
> +                   path=ip:10.0.0.66,ip:10.0.1.66
> +
>                 First addr is the source address and the second is the destination.
>
>                 If multiple "path=" options are specified multiple connection
>                 will be established and data will be sent according to
>                 the selected multipath policy (see RTRS mp_policy sysfs entry description).
>
> -               device_path: Path to the block device on the server side. Path is specified
> -               relative to the directory on server side configured in the
> -               'dev_search_path' module parameter of the rnbd_server.
> -               The rnbd_server prepends the <device_path> received from client
> -               with <dev_search_path> and tries to open the
> -               <dev_search_path>/<device_path> block device.  On success,
> -               a /dev/rnbd<N> device file, a /sys/block/rnbd_client/rnbd<N>/
> -               directory and an entry in /sys/class/rnbd-client/ctl/devices
> -               will be created.
> +               device_path:
> +                   Path to the block device on the server side. Path is specified
> +                   relative to the directory on server side configured in the
> +                   'dev_search_path' module parameter of the rnbd_server.
> +                   The rnbd_server prepends the <device_path> received from client
> +                   with <dev_search_path> and tries to open the
> +                   <dev_search_path>/<device_path> block device.  On success,
> +                   a /dev/rnbd<N> device file, a /sys/block/rnbd_client/rnbd<N>/
> +                   directory and an entry in /sys/class/rnbd-client/ctl/devices
> +                   will be created.
>
>                 If 'dev_search_path' contains '%SESSNAME%', then each session can
>                 have different devices namespace, e.g. server was configured with
> @@ -68,11 +76,12 @@ Description:        Expected format is the following:
>                 client has this string "sessname=blya device_path=sda", then server
>                 will try to open: /run/rnbd-devs/blya/sda.
>
> -               access_mode: the access_mode parameter specifies if the device is to be
> -               mapped as "ro" read-only or "rw" read-write. The server allows
> -               a device to be exported in rw mode only once. The "migration"
> -               access mode has to be specified if a second mapping in read-write
> -               mode is desired.
> +               access_mode:
> +                   the access_mode parameter specifies if the device is to be
> +                   mapped as "ro" read-only or "rw" read-write. The server allows
> +                   a device to be exported in rw mode only once. The "migration"
> +                   access mode has to be specified if a second mapping in read-write
> +                   mode is desired.
>
>                 By default "rw" is used.
>
> @@ -91,7 +100,7 @@ Description: Expected format is the following:
>                 is the same as the device name.  By extracting the last part of the
>                 path the path to the device /dev/<dev-name> can be build.
>
> -               o /dev/block/$(cat /sys/class/rnbd-client/ctl/devices/<device_id>/dev)
> +               * /dev/block/$(cat /sys/class/rnbd-client/ctl/devices/<device_id>/dev)
>
>                 How to find the <device_id> of the device is described on the next
>                 section.
> @@ -106,6 +115,6 @@ Description:        For each device mapped on the client a new symbolic link is created
>                 The <device_id> of each device is created as follows:
>
>                 - If the 'device_path' provided during mapping contains slashes ("/"),
> -               they are replaced by exclamation mark ("!") and used as as the
> -               <device_id>. Otherwise, the <device_id> will be the same as the
> -               "device_path" provided.
> +                 they are replaced by exclamation mark ("!") and used as as the
> +                 <device_id>. Otherwise, the <device_id> will be the same as the
> +                 "device_path" provided.
> diff --git a/Documentation/ABI/testing/sysfs-class-rtrs-client b/Documentation/ABI/testing/sysfs-class-rtrs-client
> index e7e718db8941..0f7165aab251 100644
> --- a/Documentation/ABI/testing/sysfs-class-rtrs-client
> +++ b/Documentation/ABI/testing/sysfs-class-rtrs-client
> @@ -10,10 +10,10 @@ Date:               Feb 2020
>  KernelVersion: 5.7
>  Contact:       Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
>  Description:   RW, adds a new path (connection) to an existing session. Expected format is the
> -               following:
> +               following::
>
> -               <[source addr,]destination addr>
> -               *addr ::= [ ip:<ipv4|ipv6> | gid:<gid> ]
> +                   <[source addr,]destination addr>
> +                   *addr ::= [ ip:<ipv4|ipv6> | gid:<gid> ]
>
>  What:          /sys/class/rtrs-client/<session-name>/max_reconnect_attempts
>  Date:          Feb 2020
> @@ -29,10 +29,10 @@ Contact:    Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud
>  Description:   Multipath policy specifies which path should be selected on each IO:
>
>                 round-robin (0):
> -               select path in per CPU round-robin manner.
> +                   select path in per CPU round-robin manner.
>
>                 min-inflight (1):
> -               select path with minimum inflights.
> +                   select path with minimum inflights.
>
>  What:          /sys/class/rtrs-client/<session-name>/paths/
>  Date:          Feb 2020
> @@ -109,8 +109,11 @@ Description:       RTRS expects that each HCA IRQ is pinned to a separate CPU. If it's
>                 not the case, the processing of an I/O response could be processed on a
>                 different CPU than where it was originally submitted.  This file shows
>                 how many interrupts where generated on a non expected CPU.
> -               "from:" is the CPU on which the IRQ was expected, but not generated.
> -               "to:" is the CPU on which the IRQ was generated, but not expected.
> +
> +               "from:"
> +                   is the CPU on which the IRQ was expected, but not generated.
> +               "to:"
> +                   is the CPU on which the IRQ was generated, but not expected.
>
>  What:          /sys/class/rtrs-client/<session-name>/paths/<src@dst>/stats/reconnects
>  Date:          Feb 2020
> @@ -125,7 +128,7 @@ Date:               Feb 2020
>  KernelVersion: 5.7
>  Contact:       Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
>  Description:   Contains statistics regarding rdma operations and inflight operations.
> -               The output consists of 6 values:
> +               The output consists of 6 values::
>
> -               <read-count> <read-total-size> <write-count> <write-total-size> \
> -               <inflights> <failovered>
> +                   <read-count> <read-total-size> <write-count> \
> +                   <write-total-size> <inflights> <failovered>
> diff --git a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
> index a8daceb4a956..ee253b033280 100644
> --- a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
> +++ b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
> @@ -102,6 +102,8 @@ Description:
>                 b[15:0]
>                         inform firmware the current software execution
>                         stage.
> +
> +                       ==      ===========================================
>                         0       the first stage bootloader didn't run or
>                                 didn't reach the point of launching second
>                                 stage bootloader.
> @@ -111,21 +113,29 @@ Description:
>                         2       both first and second stage bootloader ran
>                                 and the operating system launch was
>                                 attempted.
> +                       ==      ===========================================
>
>                 b[16]
> +                       ==      ===========================================
>                         1       firmware to reset current image retry
>                                 counter.
>                         0       no action.
> +                       ==      ===========================================
>
>                 b[17]
> +                       ==      ===========================================
>                         1       firmware to clear RSU log
>                         0       no action.
> +                       ==      ===========================================
>
>                 b[18]
>                         this is negative logic
> +
> +                       ==      ===========================================
>                         1       no action
>                         0       firmware record the notify code defined
>                                 in b[15:0].
> +                       ==      ===========================================
>
>  What:          /sys/devices/platform/stratix10-rsu.0/dcmf0
>  Date:          June 2020
> diff --git a/Documentation/ABI/testing/sysfs-driver-w1_therm b/Documentation/ABI/testing/sysfs-driver-w1_therm
> index 8873bbb075cb..6a37dc33ffdb 100644
> --- a/Documentation/ABI/testing/sysfs-driver-w1_therm
> +++ b/Documentation/ABI/testing/sysfs-driver-w1_therm
> @@ -22,8 +22,10 @@ Description:
>                 device data to its embedded EEPROM, either restore data
>                 embedded in device EEPROM. Be aware that devices support
>                 limited EEPROM writing cycles (typical 50k)
> +
>                         * 'save': save device RAM to EEPROM
>                         * 'restore': restore EEPROM data in device RAM
> +
>  Users:         any user space application which wants to communicate with
>                 w1_term device
>
> @@ -33,9 +35,11 @@ Date:                May 2020
>  Contact:       Akira Shimahara <akira215corp@gmail.com>
>  Description:
>                 (RO) return the power status by asking the device
> +
>                         * '0': device parasite powered
>                         * '1': device externally powered
>                         * '-xx': xx is kernel error when reading power status
> +
>  Users:         any user space application which wants to communicate with
>                 w1_term device
>
> @@ -49,10 +53,12 @@ Description:
>                 will be changed only in device RAM, so it will be cleared when
>                 power is lost. Trigger a 'save' to EEPROM command to keep
>                 values after power-on. Read or write are :
> +
>                         * '9..14': device resolution in bit
> -                       or resolution to set in bit
> +                         or resolution to set in bit
>                         * '-xx': xx is kernel error when reading the resolution
>                         * Anything else: do nothing
> +
>                 Some DS18B20 clones are fixed in 12-bit resolution, so the
>                 actual resolution is read back from the chip and verified. Error
>                 is reported if the results differ.
> @@ -65,16 +71,18 @@ Date:               May 2020
>  Contact:       Akira Shimahara <akira215corp@gmail.com>
>  Description:
>                 (RO) return the temperature in 1/1000 degC.
> +
>                         * If a bulk read has been triggered, it will directly
> -                       return the temperature computed when the bulk read
> -                       occurred, if available. If not yet available, nothing
> -                       is returned (a debug kernel message is sent), you
> -                       should retry later on.
> +                         return the temperature computed when the bulk read
> +                         occurred, if available. If not yet available, nothing
> +                         is returned (a debug kernel message is sent), you
> +                         should retry later on.
>                         * If no bulk read has been triggered, it will trigger
> -                       a conversion and send the result. Note that the
> -                       conversion duration depend on the resolution (if
> -                       device support this feature). It takes 94ms in 9bits
> -                       resolution, 750ms for 12bits.
> +                         a conversion and send the result. Note that the
> +                         conversion duration depend on the resolution (if
> +                         device support this feature). It takes 94ms in 9bits
> +                         resolution, 750ms for 12bits.
> +
>  Users:         any user space application which wants to communicate with
>                 w1_term device
>
> @@ -86,12 +94,14 @@ Description:
>                 (RW) return the temperature in 1/1000 degC.
>                 *read*: return 2 lines with the hexa output data sent on the
>                 bus, return the CRC check and temperature in 1/1000 degC
> -               *write* :
> +               *write*:
> +
>                         * '0' : save the 2 or 3 bytes to the device EEPROM
> -                       (i.e. TH, TL and config register)
> +                         (i.e. TH, TL and config register)
>                         * '9..14' : set the device resolution in RAM
> -                       (if supported)
> +                         (if supported)
>                         * Anything else: do nothing
> +
>                 refer to Documentation/w1/slaves/w1_therm.rst for detailed
>                 information.
>  Users:         any user space application which wants to communicate with
> @@ -103,14 +113,21 @@ Date:             May 2020
>  Contact:       Akira Shimahara <akira215corp@gmail.com>
>  Description:
>                 (RW) trigger a bulk read conversion. read the status
> +
>                 *read*:
> -                       * '-1': conversion in progress on at least 1 sensor
> -                       * '1' : conversion complete but at least one sensor
> +                       * '-1':
> +                               conversion in progress on at least 1 sensor
> +                       * '1' :
> +                               conversion complete but at least one sensor
>                                 value has not been read yet
> -                       * '0' : no bulk operation. Reading temperature will
> +                       * '0' :
> +                               no bulk operation. Reading temperature will
>                                 trigger a conversion on each device
> -               *write*: 'trigger': trigger a bulk read on all supporting
> +
> +               *write*:
> +                       'trigger': trigger a bulk read on all supporting
>                         devices on the bus
> +
>                 Note that if a bulk read is sent but one sensor is not read
>                 immediately, the next access to temperature on this device
>                 will return the temperature measured at the time of issue
> @@ -128,14 +145,19 @@ Description:
>                 reset to default (datasheet) conversion time for a new
>                 resolution.
>
> -               *read*: Actual conversion time in milliseconds. *write*:
> -                       '0': Set the default conversion time from the datasheet.
> -                       '1': Measure and set the conversion time. Make a single
> +               *read*:
> +                       Actual conversion time in milliseconds.
> +
> +               *write*:
> +                       * '0':
> +                            Set the default conversion time from the datasheet.
> +                       * '1':
> +                            Measure and set the conversion time. Make a single
>                              temperature conversion, measure an actual value.
>                              Increase it by 20% for temperature range. A new
>                              conversion time can be obtained by reading this
>                              same attribute.
> -                       other positive value:
> +                       * other positive value:
>                              Set the conversion time in milliseconds.
>
>  Users:         An application using the w1_term device
> @@ -148,16 +170,21 @@ Description:
>                 (RW) Control optional driver settings.
>                 Bit masks to read/write (bitwise OR):
>
> -                1: Enable check for conversion success. If byte 6 of
> +               == ============================================================
> +                 1 Enable check for conversion success. If byte 6 of
>                     scratchpad memory is 0xC after conversion, and
>                     temperature reads 85.00 (powerup value) or 127.94
>                     (insufficient power) - return a conversion error.
>
> -                2: Enable poll for conversion completion. Generate read cycles
> +                2  Enable poll for conversion completion. Generate read cycles
>                     after the conversion start and wait for 1's. In parasite
>                     power mode this feature is not available.
> +               == ============================================================
>
> -               *read*:  Currently selected features.
> -               *write*: Select features.
> +               *read*:
> +                   Currently selected features.
> +
> +               *write*:
> +                   Select features.
>
>  Users:         An application using the w1_term device
> diff --git a/Documentation/ABI/testing/sysfs-platform-dfl-fme b/Documentation/ABI/testing/sysfs-platform-dfl-fme
> index 3683cb1cdc3d..d6ab34e81b9b 100644
> --- a/Documentation/ABI/testing/sysfs-platform-dfl-fme
> +++ b/Documentation/ABI/testing/sysfs-platform-dfl-fme
> @@ -113,8 +113,11 @@ KernelVersion:     5.5
>  Contact:       Wu Hao <hao.wu@intel.com>
>  Description:   Read-Only. Read this file to get the name of hwmon device, it
>                 supports values:
> -                   'dfl_fme_thermal' - thermal hwmon device name
> -                   'dfl_fme_power'   - power hwmon device name
> +
> +               =================  =========================
> +               'dfl_fme_thermal'  thermal hwmon device name
> +               'dfl_fme_power'    power hwmon device name
> +               =================  =========================
>
>  What:          /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_input
>  Date:          October 2019
> @@ -169,8 +172,11 @@ KernelVersion:     5.5
>  Contact:       Wu Hao <hao.wu@intel.com>
>  Description:   Read-Only. Read this file to get the policy of hardware threshold1
>                 (see 'temp1_max'). It only supports two values (policies):
> -                   0 - AP2 state (90% throttling)
> -                   1 - AP1 state (50% throttling)
> +
> +               ==  ==========================
> +                0  AP2 state (90% throttling)
> +                1  AP1 state (50% throttling)
> +               ==  ==========================
>
>  What:          /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_input
>  Date:          October 2019
> diff --git a/Documentation/ABI/testing/sysfs-platform-dptf b/Documentation/ABI/testing/sysfs-platform-dptf
> index 2cbc660d163b..141834342a4d 100644
> --- a/Documentation/ABI/testing/sysfs-platform-dptf
> +++ b/Documentation/ABI/testing/sysfs-platform-dptf
> @@ -27,12 +27,15 @@ KernelVersion:      v4.10
>  Contact:       linux-acpi@vger.kernel.org
>  Description:
>                 (RO) Display the platform power source
> +
> +               ========= ============================
>                 bits[3:0] Current power source
> -                       0x00 = DC
> -                       0x01 = AC
> -                       0x02 = USB
> -                       0x03 = Wireless Charger
> +                         - 0x00 = DC
> +                         - 0x01 = AC
> +                         - 0x02 = USB
> +                         - 0x03 = Wireless Charger
>                 bits[7:4] Power source sequence number
> +               ========= ============================
>
>  What:          /sys/bus/platform/devices/INT3407:00/dptf_power/battery_steady_power
>  Date:          Jul, 2016
> diff --git a/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update b/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update
> index 5aa618987cad..02ae1e9bbfc8 100644
> --- a/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update
> +++ b/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update
> @@ -8,5 +8,6 @@ Description:
>                 of 0 and userspace can signal SBL to update firmware,
>                 on next reboot, by writing a value of 1.
>                 There are two available states:
> +
>                     * 0 -> Skip firmware update while rebooting
>                     * 1 -> Attempt firmware update on next reboot
> diff --git a/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
> index 401d202f478b..e79ca22e2f45 100644
> --- a/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
> +++ b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
> @@ -5,10 +5,13 @@ Contact:      "Liming Sun <lsun@mellanox.com>"
>  Description:
>                 The Life-cycle state of the SoC, which could be one of the
>                 following values.
> -                 Production - Production state and can be updated to secure
> -                 GA Secured - Secure chip and not able to change state
> -                 GA Non-Secured - Non-Secure chip and not able to change state
> -                 RMA - Return Merchandise Authorization
> +
> +               ==============  =============================================
> +               Production      Production state and can be updated to secure
> +               GA Secured      Secure chip and not able to change state
> +               GA Non-Secured  Non-Secure chip and not able to change state
> +               RMA             Return Merchandise Authorization
> +               ==============  =============================================
>
>  What:          /sys/bus/platform/devices/MLNXBF04:00/post_reset_wdog
>  Date:          Oct 2019
> @@ -25,10 +28,13 @@ KernelVersion:      5.5
>  Contact:       "Liming Sun <lsun@mellanox.com>"
>  Description:
>                 The source of the boot stream for the next reset. It could be
> -               one of the following values.
> -                 external - boot from external source (USB or PCIe)
> -                 emmc - boot from the onchip eMMC
> -                 emmc_legacy - boot from the onchip eMMC in legacy (slow) mode
> +               one of the following values:
> +
> +               ===========  ===============================================
> +               external     boot from external source (USB or PCIe)
> +               emmc         boot from the onchip eMMC
> +               emmc_legacy  boot from the onchip eMMC in legacy (slow) mode
> +               ===========  ===============================================
>
>  What:          /sys/bus/platform/devices/MLNXBF04:00/second_reset_action
>  Date:          Oct 2019
> @@ -38,11 +44,14 @@ Description:
>                 Update the source of the boot stream after next reset. It could
>                 be one of the following values and will be applied after next
>                 reset.
> -                 external - boot from external source (USB or PCIe)
> -                 emmc - boot from the onchip eMMC
> -                 emmc_legacy - boot from the onchip eMMC in legacy (slow) mode
> -                 swap_emmc - swap the primary / secondary boot partition
> -                 none - cancel the action
> +
> +               ===========  ===============================================
> +               external     boot from external source (USB or PCIe)
> +               emmc         boot from the onchip eMMC
> +               emmc_legacy  boot from the onchip eMMC in legacy (slow) mode
> +               swap_emmc    swap the primary / secondary boot partition
> +               none         cancel the action
> +               ===========  ===============================================
>
>  What:          /sys/bus/platform/devices/MLNXBF04:00/secure_boot_fuse_state
>  Date:          Oct 2019
> @@ -50,9 +59,12 @@ KernelVersion:       5.5
>  Contact:       "Liming Sun <lsun@mellanox.com>"
>  Description:
>                 The state of eFuse versions with the following values.
> -                 InUse - burnt, valid and currently in use
> -                 Used - burnt and valid
> -                 Free - not burnt and free to use
> -                 Skipped - not burnt but not free (skipped)
> -                 Wasted - burnt and invalid
> -                 Invalid - not burnt but marked as valid (error state).
> +
> +               =======  ===============================================
> +               InUse    burnt, valid and currently in use
> +               Used     burnt and valid
> +               Free     not burnt and free to use
> +               Skipped  not burnt but not free (skipped)
> +               Wasted   burnt and invalid
> +               Invalid  not burnt but marked as valid (error state).
> +               =======  ===============================================
> diff --git a/Documentation/ABI/testing/sysfs-platform-wilco-ec b/Documentation/ABI/testing/sysfs-platform-wilco-ec
> index 5f60b184a5a5..4439d0644091 100644
> --- a/Documentation/ABI/testing/sysfs-platform-wilco-ec
> +++ b/Documentation/ABI/testing/sysfs-platform-wilco-ec
> @@ -39,6 +39,7 @@ Description:
>                 which affects charging via the special USB PowerShare port
>                 (marked with a small lightning bolt or battery icon) when in
>                 low power states:
> +
>                 - In S0, the port will always provide power.
>                 - In S0ix, if usb_charge is enabled, then power will be
>                   supplied to the port when on AC or if battery is > 50%.
> --
> 2.26.2
>

Re: [PATCH v2 31/39] docs: ABI: cleanup several ABI documents

[Mathieu Poirier]

On Fri, 30 Oct 2020 at 01:41, Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> There are some ABI documents that, while they don't generate
> any warnings, they have issues when parsed by get_abi.pl script
> on its output result.
>
> Address them, in order to provide a clean output.
>
> Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> #for IIO
> Reviewed-by: Tom Rix <trix@redhat.com> # for fpga-manager
> Reviewed-By: Kajol Jain<kjain@linux.ibm.com> # for sysfs-bus-event_source-devices-hv_gpci and sysfs-bus-event_source-devices-hv_24x7
> Acked-by: Oded Gabbay <oded.gabbay@gmail.com> # for Habanalabs
> Acked-by: Vaibhav Jain <vaibhav@linux.ibm.com> # for sysfs-bus-papr-pmem
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---

>  .../testing/sysfs-bus-coresight-devices-etb10 |   5 +-

For the CoreSight part:

Reviewed-by: Mathieu Poirier <mathieu.poirier@linaro.org>

Re: [PATCH v2 26/39] docs: Kconfig/Makefile: add a check for broken ABI files

[Randy Dunlap]

Hi Mauro,


On 10/30/20 12:40 AM, Mauro Carvalho Chehab wrote:
> The files under Documentation/ABI should follow the syntax
> as defined at Documentation/ABI/README.
> 
> Allow checking if they're following the syntax by running
> the ABI parser script on COMPILE_TEST.
> 
> With that, when there's a problem with a file under
> Documentation/ABI, it would produce a warning like:
> 
> 	Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#14:
> 		What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor' doesn't have a description
> 	Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#21:
> 		What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal' doesn't have a description
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  Documentation/Kconfig  | 10 ++++++++++
>  Documentation/Makefile |  5 +++++
>  lib/Kconfig.debug      |  2 ++
>  scripts/get_abi.pl     | 14 +++++++++++---
>  4 files changed, 28 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/Kconfig b/Documentation/Kconfig
> index 66046fa1c341..e549a61f4d96 100644
> --- a/Documentation/Kconfig
> +++ b/Documentation/Kconfig
> @@ -10,4 +10,14 @@ config WARN_MISSING_DOCUMENTS
>  
>  	   If unsure, select 'N'.
>  
> +config WARN_ABI_ERRORS
> +	bool "Warn if there are errors at ABI files"
> +	depends on COMPILE_TEST
> +	help
> +	   The files under Documentation/ABI should follow what's
> +	   described at Documentation/ABI/README. Yet, as they're manually
> +	   written, it would be possible that some of those files would
> +	   have errors that would break them for being parsed by
> +	   scripts/get_abi.pl. Add a check to verify them.
>  
> +	   If unsure, select 'N'.

I need a bot for this:

Please follow coding-style for Kconfig files:

from Documentation/process/coding-style.rst, section 10):

For all of the Kconfig* configuration files throughout the source tree,
the indentation is somewhat different.  Lines under a ``config`` definition
are indented with one tab, while help text is indented an additional two
spaces.



thanks.
-- 
~Randy

Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Frederic Barrat]

Le 30/10/2020 à 08:40, Mauro Carvalho Chehab a écrit :
> Some files over there won't parse well by Sphinx.
> 
> Fix them.
> 
> Acked-by: Jonathan Cameron<Jonathan.Cameron@huawei.com>  # for IIO
> Signed-off-by: Mauro Carvalho Chehab<mchehab+huawei@kernel.org>
> ---
...
>   Documentation/ABI/testing/sysfs-class-cxl     |  15 +-
...
>   Documentation/ABI/testing/sysfs-class-ocxl    |   3 +


Patches 20, 28 and 31 look good for cxl and ocxl.
Acked-by: Frederic Barrat <fbarrat@linux.ibm.com>

   Fred

RE: [PATCH v2 31/39] docs: ABI: cleanup several ABI documents

[Peter Chen]

Acked-by: Peter Chen <peter.chen@nxp.com> 

For:
Documentation/ABI/testing/usb-charger-uevent

Peter

Re: [PATCH v2 31/39] docs: ABI: cleanup several ABI documents

[Dmitry Torokhov]

On Fri, Oct 30, 2020 at 08:40:50AM +0100, Mauro Carvalho Chehab wrote:
> There are some ABI documents that, while they don't generate
> any warnings, they have issues when parsed by get_abi.pl script
> on its output result.
> 
> Address them, in order to provide a clean output.
> 

...

>  .../ABI/testing/sysfs-driver-input-exc3000    |   2 +

Acked-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>

Thanks.

-- 
Dmitry

Re: [PATCH v2 28/39] docs: ABI: fix syntax to be parsed using ReST notation

[Jinpu Wang]

On Fri, Oct 30, 2020 at 8:41 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> There are a number of new changes at the ABI files that cause
> them to produce warnings when generating ABI output.
>
> Fix them.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  .../ABI/stable/sysfs-driver-firmware-zynqmp   | 62 ++++++++-----
>  Documentation/ABI/testing/debugfs-moxtet      | 28 ++++--
>  .../ABI/testing/debugfs-turris-mox-rwtm       |  6 +-
>  .../sysfs-bus-event_source-devices-dfl_fme    | 14 +--
>  Documentation/ABI/testing/sysfs-bus-most      |  6 +-
>  Documentation/ABI/testing/sysfs-class-devfreq |  6 +-
>  Documentation/ABI/testing/sysfs-class-ocxl    | 14 +--
>  .../ABI/testing/sysfs-class-power-wilco       | 18 ++--
>  .../ABI/testing/sysfs-class-rnbd-client       | 93 ++++++++++---------
>  .../ABI/testing/sysfs-class-rtrs-client       | 23 +++--
For rnbd/rtrs, looks good to me, thanks!
Acked-by: Jack Wang <jinpu.wang@cloud.ionos.com>
>  .../sysfs-devices-platform-stratix10-rsu      | 10 ++
>  .../ABI/testing/sysfs-driver-w1_therm         | 75 ++++++++++-----
>  .../ABI/testing/sysfs-platform-dfl-fme        | 14 ++-
>  Documentation/ABI/testing/sysfs-platform-dptf | 11 ++-
>  .../sysfs-platform-intel-wmi-sbl-fw-update    |  1 +
>  .../testing/sysfs-platform-mellanox-bootctl   | 50 ++++++----
>  .../ABI/testing/sysfs-platform-wilco-ec       |  1 +
>  17 files changed, 271 insertions(+), 161 deletions(-)
>
> diff --git a/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp b/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
> index 00fa04c76ff3..f5724bb5b462 100644
> --- a/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
> +++ b/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
> @@ -12,13 +12,15 @@ Description:
>                 resets. Three registers are used by the FSBL and
>                 other Xilinx software products: GLOBAL_GEN_STORAGE{4:6}.
>
> -               Usage:
> -               # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> -               # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> +               Usage::
>
> -               Example:
> -               # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> -               # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> +                   # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> +                   # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> +
> +               Example::
> +
> +                   # cat /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> +                   # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
>
>  Users:         Xilinx
>
> @@ -39,13 +41,15 @@ Description:
>                 software products: PERS_GLOB_GEN_STORAGE{4:7}.
>                 Register is reset only by a POR reset.
>
> -               Usage:
> -               # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> -               # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> +               Usage::
>
> -               Example:
> -               # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> -               # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> +                   # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> +                   # echo <value> > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> +
> +               Example::
> +
> +                   # cat /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> +                   # echo 0x1234ABCD > /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
>
>  Users:         Xilinx
>
> @@ -61,23 +65,28 @@ Description:
>
>                 Following are available shutdown scopes(subtypes):
>
> -               subsystem:      Only the APU along with all of its peripherals
> +               subsystem:
> +                               Only the APU along with all of its peripherals
>                                 not used by other processing units will be
>                                 shut down. This may result in the FPD power
>                                 domain being shut down provided that no other
>                                 processing unit uses FPD peripherals or DRAM.
> -               ps_only:        The complete PS will be shut down, including the
> +               ps_only:
> +                               The complete PS will be shut down, including the
>                                 RPU, PMU, etc.  Only the PL domain (FPGA)
>                                 remains untouched.
> -               system:         The complete system/device is shut down.
> +               system:
> +                               The complete system/device is shut down.
>
> -               Usage:
> -               # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> -               # echo <scope> > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> +               Usage::
>
> -               Example:
> -               # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> -               # echo "subsystem" > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> +                   # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> +                   # echo <scope> > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> +
> +               Example::
> +
> +                   # cat /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> +                   # echo "subsystem" > /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
>
>  Users:         Xilinx
>
> @@ -94,10 +103,13 @@ Description:
>                 system restart.
>
>                 Usage:
> -               Set healthy bit
> -               # echo 1 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status
>
> -               Unset healthy bit
> -               # echo 0 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status
> +               Set healthy bit::
> +
> +                   # echo 1 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status
> +
> +               Unset healthy bit::
> +
> +                   # echo 0 > /sys/devices/platform/firmware\:zynqmp-firmware/health_status
>
>  Users:         Xilinx
> diff --git a/Documentation/ABI/testing/debugfs-moxtet b/Documentation/ABI/testing/debugfs-moxtet
> index 67b1717794d8..15dfaecb2892 100644
> --- a/Documentation/ABI/testing/debugfs-moxtet
> +++ b/Documentation/ABI/testing/debugfs-moxtet
> @@ -5,10 +5,16 @@ Contact:      Marek Behún <marek.behun@nic.cz>
>  Description:   (R) Read input from the shift registers, in hexadecimal.
>                 Returns N+1 bytes, where N is the number of Moxtet connected
>                 modules. The first byte is from the CPU board itself.
> -               Example: 101214
> -                        10: CPU board with SD card
> -                        12: 2 = PCIe module, 1 = IRQ not active
> -                        14: 4 = Peridot module, 1 = IRQ not active
> +
> +               Example::
> +
> +                       101214
> +
> +               ==  =======================================
> +               10  CPU board with SD card
> +               12  2 = PCIe module, 1 = IRQ not active
> +               14  4 = Peridot module, 1 = IRQ not active
> +               ==  =======================================
>
>  What:          /sys/kernel/debug/moxtet/output
>  Date:          March 2019
> @@ -17,7 +23,13 @@ Contact:     Marek Behún <marek.behun@nic.cz>
>  Description:   (RW) Read last written value to the shift registers, in
>                 hexadecimal, or write values to the shift registers, also
>                 in hexadecimal.
> -               Example: 0102
> -                        01: 01 was last written, or is to be written, to the
> -                            first module's shift register
> -                        02: the same for second module
> +
> +               Example::
> +
> +                   0102
> +
> +               ==  ================================================
> +               01  01 was last written, or is to be written, to the
> +                   first module's shift register
> +               02  the same for second module
> +               ==  ================================================
> diff --git a/Documentation/ABI/testing/debugfs-turris-mox-rwtm b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
> index 2b3255ee68fd..c8f7dadd591c 100644
> --- a/Documentation/ABI/testing/debugfs-turris-mox-rwtm
> +++ b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
> @@ -2,8 +2,10 @@ What:          /sys/kernel/debug/turris-mox-rwtm/do_sign
>  Date:          Jun 2020
>  KernelVersion: 5.8
>  Contact:       Marek Behún <marek.behun@nic.cz>
> -Description:   (W) Message to sign with the ECDSA private key stored in
> +Description:   (W)
> +                   Message to sign with the ECDSA private key stored in
>                     device's OTP. The message must be exactly 64 bytes (since
>                     this is intended for SHA-512 hashes).
> -               (R) The resulting signature, 136 bytes. This contains the R and
> +               (R)
> +                   The resulting signature, 136 bytes. This contains the R and
>                     S values of the ECDSA signature, both in big-endian format.
> diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme b/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme
> index c9278a3b3df1..63a32ddcb95e 100644
> --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme
> +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-dfl_fme
> @@ -8,13 +8,13 @@ Description:  Read-only. Attribute group to describe the magic bits
>
>                 Each attribute under this group defines a bit range of the
>                 perf_event_attr.config. All supported attributes are listed
> -               below.
> +               below::
>
>                     event  = "config:0-11"  - event ID
>                     evtype = "config:12-15" - event type
>                     portid = "config:16-23" - event source
>
> -               For example,
> +               For example::
>
>                     fab_mmio_read = "event=0x06,evtype=0x02,portid=0xff"
>
> @@ -40,11 +40,11 @@ Description:        Read-only. Attribute group to describe performance monitoring
>
>                 All supported performance monitoring events are listed below.
>
> -               Basic events (evtype=0x00)
> +               Basic events (evtype=0x00)::
>
>                     clock = "event=0x00,evtype=0x00,portid=0xff"
>
> -               Cache events (evtype=0x01)
> +               Cache events (evtype=0x01)::
>
>                     cache_read_hit      = "event=0x00,evtype=0x01,portid=0xff"
>                     cache_read_miss     = "event=0x01,evtype=0x01,portid=0xff"
> @@ -59,7 +59,7 @@ Description:  Read-only. Attribute group to describe performance monitoring
>                     cache_rx_req_stall  = "event=0x09,evtype=0x01,portid=0xff"
>                     cache_eviction      = "event=0x0a,evtype=0x01,portid=0xff"
>
> -               Fabric events (evtype=0x02)
> +               Fabric events (evtype=0x02)::
>
>                     fab_pcie0_read       = "event=0x00,evtype=0x02,portid=0xff"
>                     fab_pcie0_write      = "event=0x01,evtype=0x02,portid=0xff"
> @@ -78,7 +78,7 @@ Description:  Read-only. Attribute group to describe performance monitoring
>                     fab_port_mmio_read   = "event=0x06,evtype=0x02,portid=?"
>                     fab_port_mmio_write  = "event=0x07,evtype=0x02,portid=?"
>
> -               VTD events (evtype=0x03)
> +               VTD events (evtype=0x03)::
>
>                     vtd_port_read_transaction  = "event=0x00,evtype=0x03,portid=?"
>                     vtd_port_write_transaction = "event=0x01,evtype=0x03,portid=?"
> @@ -88,7 +88,7 @@ Description:  Read-only. Attribute group to describe performance monitoring
>                     vtd_port_devtlb_2m_fill    = "event=0x05,evtype=0x03,portid=?"
>                     vtd_port_devtlb_1g_fill    = "event=0x06,evtype=0x03,portid=?"
>
> -               VTD SIP events (evtype=0x04)
> +               VTD SIP events (evtype=0x04)::
>
>                     vtd_sip_iotlb_4k_hit  = "event=0x00,evtype=0x04,portid=0xff"
>                     vtd_sip_iotlb_2m_hit  = "event=0x01,evtype=0x04,portid=0xff"
> diff --git a/Documentation/ABI/testing/sysfs-bus-most b/Documentation/ABI/testing/sysfs-bus-most
> index ec0a603d804b..38cc03e408e7 100644
> --- a/Documentation/ABI/testing/sysfs-bus-most
> +++ b/Documentation/ABI/testing/sysfs-bus-most
> @@ -235,7 +235,8 @@ KernelVersion:      4.15
>  Contact:       Christian Gromm <christian.gromm@microchip.com>
>  Description:
>                 This is to read back the configured direction of the channel.
> -               The following strings will be accepted:
> +               The following strings will be accepted::
> +
>                         'tx',
>                         'rx'
>  Users:
> @@ -246,7 +247,8 @@ KernelVersion:      4.15
>  Contact:       Christian Gromm <christian.gromm@microchip.com>
>  Description:
>                 This is to read back the configured data type of the channel.
> -               The following strings will be accepted:
> +               The following strings will be accepted::
> +
>                         'control',
>                         'async',
>                         'sync',
> diff --git a/Documentation/ABI/testing/sysfs-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq
> index 67af3f31e17c..386bc230a33d 100644
> --- a/Documentation/ABI/testing/sysfs-class-devfreq
> +++ b/Documentation/ABI/testing/sysfs-class-devfreq
> @@ -48,7 +48,8 @@ Description:
>                 driver should provide the list of available frequencies
>                 with its profile. If need to reset the statistics of devfreq
>                 behavior on a specific device, enter 0(zero) to 'trans_stat'
> -               as following:
> +               as following::
> +
>                         echo 0 > /sys/class/devfreq/.../trans_stat
>
>  What:          /sys/class/devfreq/.../available_frequencies
> @@ -124,7 +125,8 @@ Description:
>                 This work timer is used by devfreq workqueue in order to
>                 monitor the device status such as utilization. The user
>                 can change the work timer on runtime according to their demand
> -               as following:
> +               as following::
> +
>                         echo deferrable > /sys/class/devfreq/.../timer
>                         echo delayed > /sys/class/devfreq/.../timer
>
> diff --git a/Documentation/ABI/testing/sysfs-class-ocxl b/Documentation/ABI/testing/sysfs-class-ocxl
> index bf33f4fda58f..847a7edc3113 100644
> --- a/Documentation/ABI/testing/sysfs-class-ocxl
> +++ b/Documentation/ABI/testing/sysfs-class-ocxl
> @@ -13,8 +13,8 @@ Description:  read only
>                 where:
>
>                         ====    ===============================================
> -                       n:      number of currently active contexts, for debug
> -                       max:    maximum number of contexts supported by the AFU
> +                       n       number of currently active contexts, for debug
> +                       max     maximum number of contexts supported by the AFU
>                         ====    ===============================================
>
>  What:          /sys/class/ocxl/<afu name>/pp_mmio_size
> @@ -43,7 +43,9 @@ Contact:      linuxppc-dev@lists.ozlabs.org
>  Description:   read/write
>                 Control whether the FPGA is reloaded on a link reset. Enabled
>                 through a vendor-specific logic block on the FPGA.
> -                       0       Do not reload FPGA image from flash
> -                       1       Reload FPGA image from flash
> -                       unavailable
> -                               The device does not support this capability
> +
> +                       ===========  ===========================================
> +                       0            Do not reload FPGA image from flash
> +                       1            Reload FPGA image from flash
> +                       unavailable  The device does not support this capability
> +                       ===========  ===========================================
> diff --git a/Documentation/ABI/testing/sysfs-class-power-wilco b/Documentation/ABI/testing/sysfs-class-power-wilco
> index 84fde1d0ada0..82af180fcaab 100644
> --- a/Documentation/ABI/testing/sysfs-class-power-wilco
> +++ b/Documentation/ABI/testing/sysfs-class-power-wilco
> @@ -4,17 +4,23 @@ KernelVersion:        5.2
>  Description:
>                 What charging algorithm to use:
>
> -               Standard: Fully charges battery at a standard rate.
> -               Adaptive: Battery settings adaptively optimized based on
> +               Standard:
> +                       Fully charges battery at a standard rate.
> +               Adaptive:
> +                       Battery settings adaptively optimized based on
>                         typical battery usage pattern.
> -               Fast: Battery charges over a shorter period.
> -               Trickle: Extends battery lifespan, intended for users who
> +               Fast:
> +                       Battery charges over a shorter period.
> +               Trickle:
> +                       Extends battery lifespan, intended for users who
>                         primarily use their Chromebook while connected to AC.
> -               Custom: A low and high threshold percentage is specified.
> +               Custom:
> +                       A low and high threshold percentage is specified.
>                         Charging begins when level drops below
>                         charge_control_start_threshold, and ceases when
>                         level is above charge_control_end_threshold.
> -               Long Life: Customized charge rate for last longer battery life.
> +               Long Life:
> +                       Customized charge rate for last longer battery life.
>                         On Wilco device this mode is pre-configured in the factory
>                         through EC's private PID. Swiching to a different mode will
>                         be denied by Wilco EC when Long Life mode is enabled.
> diff --git a/Documentation/ABI/testing/sysfs-class-rnbd-client b/Documentation/ABI/testing/sysfs-class-rnbd-client
> index c084f203b41e..00c0286733d4 100644
> --- a/Documentation/ABI/testing/sysfs-class-rnbd-client
> +++ b/Documentation/ABI/testing/sysfs-class-rnbd-client
> @@ -5,62 +5,70 @@ Contact:      Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud
>  Description:   Provide information about RNBD-client.
>                 All sysfs files that are not read-only provide the usage information on read:
>
> -               Example:
> -               # cat /sys/class/rnbd-client/ctl/map_device
> +               Example::
>
> -               > Usage: echo "sessname=<name of the rtrs session> path=<[srcaddr,]dstaddr>
> -               > [path=<[srcaddr,]dstaddr>] device_path=<full path on remote side>
> -               > [access_mode=<ro|rw|migration>] > map_device
> -               >
> -               > addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ]
> +                   # cat /sys/class/rnbd-client/ctl/map_device
> +
> +                   > Usage: echo "sessname=<name of the rtrs session> path=<[srcaddr,]dstaddr>
> +                   > [path=<[srcaddr,]dstaddr>] device_path=<full path on remote side>
> +                   > [access_mode=<ro|rw|migration>] > map_device
> +                   >
> +                   > addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ]
>
>  What:          /sys/class/rnbd-client/ctl/map_device
>  Date:          Feb 2020
>  KernelVersion: 5.7
>  Contact:       Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
> -Description:   Expected format is the following:
> +Description:   Expected format is the following::
>
> -               sessname=<name of the rtrs session>
> -               path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...]
> -               device_path=<full path on remote side>
> -               [access_mode=<ro|rw|migration>]
> +                   sessname=<name of the rtrs session>
> +                   path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...]
> +                   device_path=<full path on remote side>
> +                   [access_mode=<ro|rw|migration>]
>
>                 Where:
>
> -               sessname: accepts a string not bigger than 256 chars, which identifies
> -               a given session on the client and on the server.
> -               I.e. "clt_hostname-srv_hostname" could be a natural choice.
> +               sessname:
> +                   accepts a string not bigger than 256 chars, which identifies
> +                   a given session on the client and on the server.
> +                   I.e. "clt_hostname-srv_hostname" could be a natural choice.
>
> -               path:     describes a connection between the client and the server by
> -               specifying destination and, when required, the source address.
> -               The addresses are to be provided in the following format:
> +               path:
> +                   describes a connection between the client and the server by
> +                   specifying destination and, when required, the source address.
> +                   The addresses are to be provided in the following format::
>
> -               ip:<IPv6>
> -               ip:<IPv4>
> -               gid:<GID>
> +                       ip:<IPv6>
> +                       ip:<IPv4>
> +                       gid:<GID>
>
> -               for example:
> +               for example::
> +
> +                   path=ip:10.0.0.66
>
> -               path=ip:10.0.0.66
>                 The single addr is treated as the destination.
>                 The connection will be established to this server from any client IP address.
>
> -               path=ip:10.0.0.66,ip:10.0.1.66
> +               ::
> +
> +                   path=ip:10.0.0.66,ip:10.0.1.66
> +
>                 First addr is the source address and the second is the destination.
>
>                 If multiple "path=" options are specified multiple connection
>                 will be established and data will be sent according to
>                 the selected multipath policy (see RTRS mp_policy sysfs entry description).
>
> -               device_path: Path to the block device on the server side. Path is specified
> -               relative to the directory on server side configured in the
> -               'dev_search_path' module parameter of the rnbd_server.
> -               The rnbd_server prepends the <device_path> received from client
> -               with <dev_search_path> and tries to open the
> -               <dev_search_path>/<device_path> block device.  On success,
> -               a /dev/rnbd<N> device file, a /sys/block/rnbd_client/rnbd<N>/
> -               directory and an entry in /sys/class/rnbd-client/ctl/devices
> -               will be created.
> +               device_path:
> +                   Path to the block device on the server side. Path is specified
> +                   relative to the directory on server side configured in the
> +                   'dev_search_path' module parameter of the rnbd_server.
> +                   The rnbd_server prepends the <device_path> received from client
> +                   with <dev_search_path> and tries to open the
> +                   <dev_search_path>/<device_path> block device.  On success,
> +                   a /dev/rnbd<N> device file, a /sys/block/rnbd_client/rnbd<N>/
> +                   directory and an entry in /sys/class/rnbd-client/ctl/devices
> +                   will be created.
>
>                 If 'dev_search_path' contains '%SESSNAME%', then each session can
>                 have different devices namespace, e.g. server was configured with
> @@ -68,11 +76,12 @@ Description:        Expected format is the following:
>                 client has this string "sessname=blya device_path=sda", then server
>                 will try to open: /run/rnbd-devs/blya/sda.
>
> -               access_mode: the access_mode parameter specifies if the device is to be
> -               mapped as "ro" read-only or "rw" read-write. The server allows
> -               a device to be exported in rw mode only once. The "migration"
> -               access mode has to be specified if a second mapping in read-write
> -               mode is desired.
> +               access_mode:
> +                   the access_mode parameter specifies if the device is to be
> +                   mapped as "ro" read-only or "rw" read-write. The server allows
> +                   a device to be exported in rw mode only once. The "migration"
> +                   access mode has to be specified if a second mapping in read-write
> +                   mode is desired.
>
>                 By default "rw" is used.
>
> @@ -91,7 +100,7 @@ Description: Expected format is the following:
>                 is the same as the device name.  By extracting the last part of the
>                 path the path to the device /dev/<dev-name> can be build.
>
> -               o /dev/block/$(cat /sys/class/rnbd-client/ctl/devices/<device_id>/dev)
> +               * /dev/block/$(cat /sys/class/rnbd-client/ctl/devices/<device_id>/dev)
>
>                 How to find the <device_id> of the device is described on the next
>                 section.
> @@ -106,6 +115,6 @@ Description:        For each device mapped on the client a new symbolic link is created
>                 The <device_id> of each device is created as follows:
>
>                 - If the 'device_path' provided during mapping contains slashes ("/"),
> -               they are replaced by exclamation mark ("!") and used as as the
> -               <device_id>. Otherwise, the <device_id> will be the same as the
> -               "device_path" provided.
> +                 they are replaced by exclamation mark ("!") and used as as the
> +                 <device_id>. Otherwise, the <device_id> will be the same as the
> +                 "device_path" provided.
> diff --git a/Documentation/ABI/testing/sysfs-class-rtrs-client b/Documentation/ABI/testing/sysfs-class-rtrs-client
> index e7e718db8941..0f7165aab251 100644
> --- a/Documentation/ABI/testing/sysfs-class-rtrs-client
> +++ b/Documentation/ABI/testing/sysfs-class-rtrs-client
> @@ -10,10 +10,10 @@ Date:               Feb 2020
>  KernelVersion: 5.7
>  Contact:       Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
>  Description:   RW, adds a new path (connection) to an existing session. Expected format is the
> -               following:
> +               following::
>
> -               <[source addr,]destination addr>
> -               *addr ::= [ ip:<ipv4|ipv6> | gid:<gid> ]
> +                   <[source addr,]destination addr>
> +                   *addr ::= [ ip:<ipv4|ipv6> | gid:<gid> ]
>
>  What:          /sys/class/rtrs-client/<session-name>/max_reconnect_attempts
>  Date:          Feb 2020
> @@ -29,10 +29,10 @@ Contact:    Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud
>  Description:   Multipath policy specifies which path should be selected on each IO:
>
>                 round-robin (0):
> -               select path in per CPU round-robin manner.
> +                   select path in per CPU round-robin manner.
>
>                 min-inflight (1):
> -               select path with minimum inflights.
> +                   select path with minimum inflights.
>
>  What:          /sys/class/rtrs-client/<session-name>/paths/
>  Date:          Feb 2020
> @@ -109,8 +109,11 @@ Description:       RTRS expects that each HCA IRQ is pinned to a separate CPU. If it's
>                 not the case, the processing of an I/O response could be processed on a
>                 different CPU than where it was originally submitted.  This file shows
>                 how many interrupts where generated on a non expected CPU.
> -               "from:" is the CPU on which the IRQ was expected, but not generated.
> -               "to:" is the CPU on which the IRQ was generated, but not expected.
> +
> +               "from:"
> +                   is the CPU on which the IRQ was expected, but not generated.
> +               "to:"
> +                   is the CPU on which the IRQ was generated, but not expected.
>
>  What:          /sys/class/rtrs-client/<session-name>/paths/<src@dst>/stats/reconnects
>  Date:          Feb 2020
> @@ -125,7 +128,7 @@ Date:               Feb 2020
>  KernelVersion: 5.7
>  Contact:       Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <danil.kipnis@cloud.ionos.com>
>  Description:   Contains statistics regarding rdma operations and inflight operations.
> -               The output consists of 6 values:
> +               The output consists of 6 values::
>
> -               <read-count> <read-total-size> <write-count> <write-total-size> \
> -               <inflights> <failovered>
> +                   <read-count> <read-total-size> <write-count> \
> +                   <write-total-size> <inflights> <failovered>
> diff --git a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
> index a8daceb4a956..ee253b033280 100644
> --- a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
> +++ b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
> @@ -102,6 +102,8 @@ Description:
>                 b[15:0]
>                         inform firmware the current software execution
>                         stage.
> +
> +                       ==      ===========================================
>                         0       the first stage bootloader didn't run or
>                                 didn't reach the point of launching second
>                                 stage bootloader.
> @@ -111,21 +113,29 @@ Description:
>                         2       both first and second stage bootloader ran
>                                 and the operating system launch was
>                                 attempted.
> +                       ==      ===========================================
>
>                 b[16]
> +                       ==      ===========================================
>                         1       firmware to reset current image retry
>                                 counter.
>                         0       no action.
> +                       ==      ===========================================
>
>                 b[17]
> +                       ==      ===========================================
>                         1       firmware to clear RSU log
>                         0       no action.
> +                       ==      ===========================================
>
>                 b[18]
>                         this is negative logic
> +
> +                       ==      ===========================================
>                         1       no action
>                         0       firmware record the notify code defined
>                                 in b[15:0].
> +                       ==      ===========================================
>
>  What:          /sys/devices/platform/stratix10-rsu.0/dcmf0
>  Date:          June 2020
> diff --git a/Documentation/ABI/testing/sysfs-driver-w1_therm b/Documentation/ABI/testing/sysfs-driver-w1_therm
> index 8873bbb075cb..6a37dc33ffdb 100644
> --- a/Documentation/ABI/testing/sysfs-driver-w1_therm
> +++ b/Documentation/ABI/testing/sysfs-driver-w1_therm
> @@ -22,8 +22,10 @@ Description:
>                 device data to its embedded EEPROM, either restore data
>                 embedded in device EEPROM. Be aware that devices support
>                 limited EEPROM writing cycles (typical 50k)
> +
>                         * 'save': save device RAM to EEPROM
>                         * 'restore': restore EEPROM data in device RAM
> +
>  Users:         any user space application which wants to communicate with
>                 w1_term device
>
> @@ -33,9 +35,11 @@ Date:                May 2020
>  Contact:       Akira Shimahara <akira215corp@gmail.com>
>  Description:
>                 (RO) return the power status by asking the device
> +
>                         * '0': device parasite powered
>                         * '1': device externally powered
>                         * '-xx': xx is kernel error when reading power status
> +
>  Users:         any user space application which wants to communicate with
>                 w1_term device
>
> @@ -49,10 +53,12 @@ Description:
>                 will be changed only in device RAM, so it will be cleared when
>                 power is lost. Trigger a 'save' to EEPROM command to keep
>                 values after power-on. Read or write are :
> +
>                         * '9..14': device resolution in bit
> -                       or resolution to set in bit
> +                         or resolution to set in bit
>                         * '-xx': xx is kernel error when reading the resolution
>                         * Anything else: do nothing
> +
>                 Some DS18B20 clones are fixed in 12-bit resolution, so the
>                 actual resolution is read back from the chip and verified. Error
>                 is reported if the results differ.
> @@ -65,16 +71,18 @@ Date:               May 2020
>  Contact:       Akira Shimahara <akira215corp@gmail.com>
>  Description:
>                 (RO) return the temperature in 1/1000 degC.
> +
>                         * If a bulk read has been triggered, it will directly
> -                       return the temperature computed when the bulk read
> -                       occurred, if available. If not yet available, nothing
> -                       is returned (a debug kernel message is sent), you
> -                       should retry later on.
> +                         return the temperature computed when the bulk read
> +                         occurred, if available. If not yet available, nothing
> +                         is returned (a debug kernel message is sent), you
> +                         should retry later on.
>                         * If no bulk read has been triggered, it will trigger
> -                       a conversion and send the result. Note that the
> -                       conversion duration depend on the resolution (if
> -                       device support this feature). It takes 94ms in 9bits
> -                       resolution, 750ms for 12bits.
> +                         a conversion and send the result. Note that the
> +                         conversion duration depend on the resolution (if
> +                         device support this feature). It takes 94ms in 9bits
> +                         resolution, 750ms for 12bits.
> +
>  Users:         any user space application which wants to communicate with
>                 w1_term device
>
> @@ -86,12 +94,14 @@ Description:
>                 (RW) return the temperature in 1/1000 degC.
>                 *read*: return 2 lines with the hexa output data sent on the
>                 bus, return the CRC check and temperature in 1/1000 degC
> -               *write* :
> +               *write*:
> +
>                         * '0' : save the 2 or 3 bytes to the device EEPROM
> -                       (i.e. TH, TL and config register)
> +                         (i.e. TH, TL and config register)
>                         * '9..14' : set the device resolution in RAM
> -                       (if supported)
> +                         (if supported)
>                         * Anything else: do nothing
> +
>                 refer to Documentation/w1/slaves/w1_therm.rst for detailed
>                 information.
>  Users:         any user space application which wants to communicate with
> @@ -103,14 +113,21 @@ Date:             May 2020
>  Contact:       Akira Shimahara <akira215corp@gmail.com>
>  Description:
>                 (RW) trigger a bulk read conversion. read the status
> +
>                 *read*:
> -                       * '-1': conversion in progress on at least 1 sensor
> -                       * '1' : conversion complete but at least one sensor
> +                       * '-1':
> +                               conversion in progress on at least 1 sensor
> +                       * '1' :
> +                               conversion complete but at least one sensor
>                                 value has not been read yet
> -                       * '0' : no bulk operation. Reading temperature will
> +                       * '0' :
> +                               no bulk operation. Reading temperature will
>                                 trigger a conversion on each device
> -               *write*: 'trigger': trigger a bulk read on all supporting
> +
> +               *write*:
> +                       'trigger': trigger a bulk read on all supporting
>                         devices on the bus
> +
>                 Note that if a bulk read is sent but one sensor is not read
>                 immediately, the next access to temperature on this device
>                 will return the temperature measured at the time of issue
> @@ -128,14 +145,19 @@ Description:
>                 reset to default (datasheet) conversion time for a new
>                 resolution.
>
> -               *read*: Actual conversion time in milliseconds. *write*:
> -                       '0': Set the default conversion time from the datasheet.
> -                       '1': Measure and set the conversion time. Make a single
> +               *read*:
> +                       Actual conversion time in milliseconds.
> +
> +               *write*:
> +                       * '0':
> +                            Set the default conversion time from the datasheet.
> +                       * '1':
> +                            Measure and set the conversion time. Make a single
>                              temperature conversion, measure an actual value.
>                              Increase it by 20% for temperature range. A new
>                              conversion time can be obtained by reading this
>                              same attribute.
> -                       other positive value:
> +                       * other positive value:
>                              Set the conversion time in milliseconds.
>
>  Users:         An application using the w1_term device
> @@ -148,16 +170,21 @@ Description:
>                 (RW) Control optional driver settings.
>                 Bit masks to read/write (bitwise OR):
>
> -                1: Enable check for conversion success. If byte 6 of
> +               == ============================================================
> +                 1 Enable check for conversion success. If byte 6 of
>                     scratchpad memory is 0xC after conversion, and
>                     temperature reads 85.00 (powerup value) or 127.94
>                     (insufficient power) - return a conversion error.
>
> -                2: Enable poll for conversion completion. Generate read cycles
> +                2  Enable poll for conversion completion. Generate read cycles
>                     after the conversion start and wait for 1's. In parasite
>                     power mode this feature is not available.
> +               == ============================================================
>
> -               *read*:  Currently selected features.
> -               *write*: Select features.
> +               *read*:
> +                   Currently selected features.
> +
> +               *write*:
> +                   Select features.
>
>  Users:         An application using the w1_term device
> diff --git a/Documentation/ABI/testing/sysfs-platform-dfl-fme b/Documentation/ABI/testing/sysfs-platform-dfl-fme
> index 3683cb1cdc3d..d6ab34e81b9b 100644
> --- a/Documentation/ABI/testing/sysfs-platform-dfl-fme
> +++ b/Documentation/ABI/testing/sysfs-platform-dfl-fme
> @@ -113,8 +113,11 @@ KernelVersion:     5.5
>  Contact:       Wu Hao <hao.wu@intel.com>
>  Description:   Read-Only. Read this file to get the name of hwmon device, it
>                 supports values:
> -                   'dfl_fme_thermal' - thermal hwmon device name
> -                   'dfl_fme_power'   - power hwmon device name
> +
> +               =================  =========================
> +               'dfl_fme_thermal'  thermal hwmon device name
> +               'dfl_fme_power'    power hwmon device name
> +               =================  =========================
>
>  What:          /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/temp1_input
>  Date:          October 2019
> @@ -169,8 +172,11 @@ KernelVersion:     5.5
>  Contact:       Wu Hao <hao.wu@intel.com>
>  Description:   Read-Only. Read this file to get the policy of hardware threshold1
>                 (see 'temp1_max'). It only supports two values (policies):
> -                   0 - AP2 state (90% throttling)
> -                   1 - AP1 state (50% throttling)
> +
> +               ==  ==========================
> +                0  AP2 state (90% throttling)
> +                1  AP1 state (50% throttling)
> +               ==  ==========================
>
>  What:          /sys/bus/platform/devices/dfl-fme.0/hwmon/hwmonX/power1_input
>  Date:          October 2019
> diff --git a/Documentation/ABI/testing/sysfs-platform-dptf b/Documentation/ABI/testing/sysfs-platform-dptf
> index 2cbc660d163b..141834342a4d 100644
> --- a/Documentation/ABI/testing/sysfs-platform-dptf
> +++ b/Documentation/ABI/testing/sysfs-platform-dptf
> @@ -27,12 +27,15 @@ KernelVersion:      v4.10
>  Contact:       linux-acpi@vger.kernel.org
>  Description:
>                 (RO) Display the platform power source
> +
> +               ========= ============================
>                 bits[3:0] Current power source
> -                       0x00 = DC
> -                       0x01 = AC
> -                       0x02 = USB
> -                       0x03 = Wireless Charger
> +                         - 0x00 = DC
> +                         - 0x01 = AC
> +                         - 0x02 = USB
> +                         - 0x03 = Wireless Charger
>                 bits[7:4] Power source sequence number
> +               ========= ============================
>
>  What:          /sys/bus/platform/devices/INT3407:00/dptf_power/battery_steady_power
>  Date:          Jul, 2016
> diff --git a/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update b/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update
> index 5aa618987cad..02ae1e9bbfc8 100644
> --- a/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update
> +++ b/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-update
> @@ -8,5 +8,6 @@ Description:
>                 of 0 and userspace can signal SBL to update firmware,
>                 on next reboot, by writing a value of 1.
>                 There are two available states:
> +
>                     * 0 -> Skip firmware update while rebooting
>                     * 1 -> Attempt firmware update on next reboot
> diff --git a/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
> index 401d202f478b..e79ca22e2f45 100644
> --- a/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
> +++ b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
> @@ -5,10 +5,13 @@ Contact:      "Liming Sun <lsun@mellanox.com>"
>  Description:
>                 The Life-cycle state of the SoC, which could be one of the
>                 following values.
> -                 Production - Production state and can be updated to secure
> -                 GA Secured - Secure chip and not able to change state
> -                 GA Non-Secured - Non-Secure chip and not able to change state
> -                 RMA - Return Merchandise Authorization
> +
> +               ==============  =============================================
> +               Production      Production state and can be updated to secure
> +               GA Secured      Secure chip and not able to change state
> +               GA Non-Secured  Non-Secure chip and not able to change state
> +               RMA             Return Merchandise Authorization
> +               ==============  =============================================
>
>  What:          /sys/bus/platform/devices/MLNXBF04:00/post_reset_wdog
>  Date:          Oct 2019
> @@ -25,10 +28,13 @@ KernelVersion:      5.5
>  Contact:       "Liming Sun <lsun@mellanox.com>"
>  Description:
>                 The source of the boot stream for the next reset. It could be
> -               one of the following values.
> -                 external - boot from external source (USB or PCIe)
> -                 emmc - boot from the onchip eMMC
> -                 emmc_legacy - boot from the onchip eMMC in legacy (slow) mode
> +               one of the following values:
> +
> +               ===========  ===============================================
> +               external     boot from external source (USB or PCIe)
> +               emmc         boot from the onchip eMMC
> +               emmc_legacy  boot from the onchip eMMC in legacy (slow) mode
> +               ===========  ===============================================
>
>  What:          /sys/bus/platform/devices/MLNXBF04:00/second_reset_action
>  Date:          Oct 2019
> @@ -38,11 +44,14 @@ Description:
>                 Update the source of the boot stream after next reset. It could
>                 be one of the following values and will be applied after next
>                 reset.
> -                 external - boot from external source (USB or PCIe)
> -                 emmc - boot from the onchip eMMC
> -                 emmc_legacy - boot from the onchip eMMC in legacy (slow) mode
> -                 swap_emmc - swap the primary / secondary boot partition
> -                 none - cancel the action
> +
> +               ===========  ===============================================
> +               external     boot from external source (USB or PCIe)
> +               emmc         boot from the onchip eMMC
> +               emmc_legacy  boot from the onchip eMMC in legacy (slow) mode
> +               swap_emmc    swap the primary / secondary boot partition
> +               none         cancel the action
> +               ===========  ===============================================
>
>  What:          /sys/bus/platform/devices/MLNXBF04:00/secure_boot_fuse_state
>  Date:          Oct 2019
> @@ -50,9 +59,12 @@ KernelVersion:       5.5
>  Contact:       "Liming Sun <lsun@mellanox.com>"
>  Description:
>                 The state of eFuse versions with the following values.
> -                 InUse - burnt, valid and currently in use
> -                 Used - burnt and valid
> -                 Free - not burnt and free to use
> -                 Skipped - not burnt but not free (skipped)
> -                 Wasted - burnt and invalid
> -                 Invalid - not burnt but marked as valid (error state).
> +
> +               =======  ===============================================
> +               InUse    burnt, valid and currently in use
> +               Used     burnt and valid
> +               Free     not burnt and free to use
> +               Skipped  not burnt but not free (skipped)
> +               Wasted   burnt and invalid
> +               Invalid  not burnt but marked as valid (error state).
> +               =======  ===============================================
> diff --git a/Documentation/ABI/testing/sysfs-platform-wilco-ec b/Documentation/ABI/testing/sysfs-platform-wilco-ec
> index 5f60b184a5a5..4439d0644091 100644
> --- a/Documentation/ABI/testing/sysfs-platform-wilco-ec
> +++ b/Documentation/ABI/testing/sysfs-platform-wilco-ec
> @@ -39,6 +39,7 @@ Description:
>                 which affects charging via the special USB PowerShare port
>                 (marked with a small lightning bolt or battery icon) when in
>                 low power states:
> +
>                 - In S0, the port will always provide power.
>                 - In S0ix, if usb_charge is enabled, then power will be
>                   supplied to the port when on AC or if battery is > 50%.
> --
> 2.26.2
>

Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Fabrice Gasnier]

On 10/30/20 11:09 AM, Mauro Carvalho Chehab wrote:
> Em Fri, 30 Oct 2020 10:19:12 +0100
> Fabrice Gasnier <fabrice.gasnier@st.com> escreveu:
> 
>> Hi Mauro,
>>
>> [...]
>>
>>>  
>>> +What:		/sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
>>> +KernelVersion:	4.12
>>> +Contact:	benjamin.gaignard@st.com
>>> +Description:
>>> +		Reading returns the list possible quadrature modes.
>>> +
>>> +What:		/sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode
>>> +KernelVersion:	4.12
>>> +Contact:	benjamin.gaignard@st.com
>>> +Description:
>>> +		Configure the device counter quadrature modes:
>>> +
>>> +		channel_A:
>>> +			Encoder A input servers as the count input and B as
>>> +			the UP/DOWN direction control input.
>>> +
>>> +		channel_B:
>>> +			Encoder B input serves as the count input and A as
>>> +			the UP/DOWN direction control input.
>>> +
>>> +		quadrature:
>>> +			Encoder A and B inputs are mixed to get direction
>>> +			and count with a scale of 0.25.
>>> +  
>>
> 
> Hi Fabrice,
> 
>> I just noticed that since Jonathan question in v1.
>>
>> Above ABI has been moved in the past as discussed in [1]. You can take a
>> look at:
>> b299d00 IIO: stm32: Remove quadrature related functions from trigger driver
>>
>> Could you please remove the above chunk ?
>>
>> With that, for the stm32 part:
>> Acked-by: Fabrice Gasnier <fabrice.gasnier@st.com>
> 
> 
> Hmm... probably those were re-introduced due to a rebase. This
> series were originally written about 1,5 years ago.
> 
> I'll drop those hunks.

Hi Mauro, Greg,

I just figured out this patch has been applied with above hunk.

This should be dropped: is there a fix on its way already ?
(I may have missed it)

Please advise,
Fabrice
> 
> Thanks!
> Mauro
> 

Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Greg Kroah-Hartman]

On Mon, Nov 02, 2020 at 12:04:36PM +0100, Fabrice Gasnier wrote:
> On 10/30/20 11:09 AM, Mauro Carvalho Chehab wrote:
> > Em Fri, 30 Oct 2020 10:19:12 +0100
> > Fabrice Gasnier <fabrice.gasnier@st.com> escreveu:
> > 
> >> Hi Mauro,
> >>
> >> [...]
> >>
> >>>  
> >>> +What:		/sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> >>> +KernelVersion:	4.12
> >>> +Contact:	benjamin.gaignard@st.com
> >>> +Description:
> >>> +		Reading returns the list possible quadrature modes.
> >>> +
> >>> +What:		/sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode
> >>> +KernelVersion:	4.12
> >>> +Contact:	benjamin.gaignard@st.com
> >>> +Description:
> >>> +		Configure the device counter quadrature modes:
> >>> +
> >>> +		channel_A:
> >>> +			Encoder A input servers as the count input and B as
> >>> +			the UP/DOWN direction control input.
> >>> +
> >>> +		channel_B:
> >>> +			Encoder B input serves as the count input and A as
> >>> +			the UP/DOWN direction control input.
> >>> +
> >>> +		quadrature:
> >>> +			Encoder A and B inputs are mixed to get direction
> >>> +			and count with a scale of 0.25.
> >>> +  
> >>
> > 
> > Hi Fabrice,
> > 
> >> I just noticed that since Jonathan question in v1.
> >>
> >> Above ABI has been moved in the past as discussed in [1]. You can take a
> >> look at:
> >> b299d00 IIO: stm32: Remove quadrature related functions from trigger driver
> >>
> >> Could you please remove the above chunk ?
> >>
> >> With that, for the stm32 part:
> >> Acked-by: Fabrice Gasnier <fabrice.gasnier@st.com>
> > 
> > 
> > Hmm... probably those were re-introduced due to a rebase. This
> > series were originally written about 1,5 years ago.
> > 
> > I'll drop those hunks.
> 
> Hi Mauro, Greg,
> 
> I just figured out this patch has been applied with above hunk.
> 
> This should be dropped: is there a fix on its way already ?
> (I may have missed it)

Can you send a fix for just this hunk?

thanks,

greg k-h

Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Mauro Carvalho Chehab]

Em Mon, 2 Nov 2020 13:46:41 +0100
Greg Kroah-Hartman <gregkh@linuxfoundation.org> escreveu:

> On Mon, Nov 02, 2020 at 12:04:36PM +0100, Fabrice Gasnier wrote:
> > On 10/30/20 11:09 AM, Mauro Carvalho Chehab wrote:  
> > > Em Fri, 30 Oct 2020 10:19:12 +0100
> > > Fabrice Gasnier <fabrice.gasnier@st.com> escreveu:
> > >   
> > >> Hi Mauro,
> > >>
> > >> [...]
> > >>  
> > >>>  
> > >>> +What:		/sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> > >>> +KernelVersion:	4.12
> > >>> +Contact:	benjamin.gaignard@st.com
> > >>> +Description:
> > >>> +		Reading returns the list possible quadrature modes.
> > >>> +
> > >>> +What:		/sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode
> > >>> +KernelVersion:	4.12
> > >>> +Contact:	benjamin.gaignard@st.com
> > >>> +Description:
> > >>> +		Configure the device counter quadrature modes:
> > >>> +
> > >>> +		channel_A:
> > >>> +			Encoder A input servers as the count input and B as
> > >>> +			the UP/DOWN direction control input.
> > >>> +
> > >>> +		channel_B:
> > >>> +			Encoder B input serves as the count input and A as
> > >>> +			the UP/DOWN direction control input.
> > >>> +
> > >>> +		quadrature:
> > >>> +			Encoder A and B inputs are mixed to get direction
> > >>> +			and count with a scale of 0.25.
> > >>> +    
> > >>  
> > > 
> > > Hi Fabrice,
> > >   
> > >> I just noticed that since Jonathan question in v1.
> > >>
> > >> Above ABI has been moved in the past as discussed in [1]. You can take a
> > >> look at:
> > >> b299d00 IIO: stm32: Remove quadrature related functions from trigger driver
> > >>
> > >> Could you please remove the above chunk ?
> > >>
> > >> With that, for the stm32 part:
> > >> Acked-by: Fabrice Gasnier <fabrice.gasnier@st.com>  
> > > 
> > > 
> > > Hmm... probably those were re-introduced due to a rebase. This
> > > series were originally written about 1,5 years ago.
> > > 
> > > I'll drop those hunks.  
> > 
> > Hi Mauro, Greg,
> > 
> > I just figured out this patch has been applied with above hunk.
> > 
> > This should be dropped: is there a fix on its way already ?
> > (I may have missed it)  
> 
> Can you send a fix for just this hunk?

Hmm...

	$ git grep /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
	Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:What:                /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
	Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:What:             /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
	Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:What:               /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available

Even re-doing the changes from 
changeset b299d00420e2 ("IIO: stm32: Remove quadrature related functions from trigger driver")
at Documentation/ABI/testing/sysfs-bus-iio-timer-stm32, there's still
a third duplicate of some of those, as reported by the script:

	$ ./scripts/get_abi.pl validate 2>&1|grep quadra
	Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:117  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:14
	Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 3 times:  Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:111  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:8

As in_count_quadrature_mode_available is also defined at:
	Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2

The best here seems to have a patch that will also drop the other
duplication of this, probably moving in_count_quadrature_mode_available
to a generic node probably placing it inside 
Documentation/ABI/testing/sysfs-bus-iio.

Comments?

Thanks,
Mauro

PS.: the IIO subsystem is the one that currently has more duplicated
ABI entries:

$ ./scripts/get_abi.pl validate 2>&1|grep iio
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:0  Documentation/ABI/testing/sysfs-bus-iio:394
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:1  Documentation/ABI/testing/sysfs-bus-iio:395
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:2  Documentation/ABI/testing/sysfs-bus-iio:396
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:3  Documentation/ABI/testing/sysfs-bus-iio:397
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:4  Documentation/ABI/testing/sysfs-bus-iio:398
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:5  Documentation/ABI/testing/sysfs-bus-iio:399
Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_preset is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:100  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:0
Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:117  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:14
Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 3 times:  Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:111  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:8
Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:0  Documentation/ABI/testing/sysfs-bus-iio:599
Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:36  Documentation/ABI/testing/sysfs-bus-iio:588
Warning: /sys/bus/iio/devices/iio:deviceX/out_currentY_raw is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als:43  Documentation/ABI/testing/sysfs-bus-iio-health-afe440x:38
Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:0  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:0
Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:1  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:1
Warning: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-distance-srf08:0  Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935:8
Warning: /sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  Documentation/ABI/testing/sysfs-bus-iio:45

Re: [PATCH v2 28/39] docs: ABI: fix syntax to be parsed using ReST notation

[Joseph, Jithu]

On Fri, 2020-10-30 at 08:40 +0100, Mauro Carvalho Chehab wrote:
> There are a number of new changes at the ABI files that cause
> them to produce warnings when generating ABI output.
> 
> Fix them.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---
>  .../ABI/stable/sysfs-driver-firmware-zynqmp   | 62 ++++++++-----
>  Documentation/ABI/testing/debugfs-moxtet      | 28 ++++--
>  .../ABI/testing/debugfs-turris-mox-rwtm       |  6 +-
>  .../sysfs-bus-event_source-devices-dfl_fme    | 14 +--
>  Documentation/ABI/testing/sysfs-bus-most      |  6 +-
>  Documentation/ABI/testing/sysfs-class-devfreq |  6 +-
>  Documentation/ABI/testing/sysfs-class-ocxl    | 14 +--
>  .../ABI/testing/sysfs-class-power-wilco       | 18 ++--
>  .../ABI/testing/sysfs-class-rnbd-client       | 93 ++++++++++-------
> --
>  .../ABI/testing/sysfs-class-rtrs-client       | 23 +++--
>  .../sysfs-devices-platform-stratix10-rsu      | 10 ++
>  .../ABI/testing/sysfs-driver-w1_therm         | 75 ++++++++++-----
>  .../ABI/testing/sysfs-platform-dfl-fme        | 14 ++-
>  Documentation/ABI/testing/sysfs-platform-dptf | 11 ++-
>  .../sysfs-platform-intel-wmi-sbl-fw-update    |  1 +

For intel-wmi-sbl-fw-update part
Acked-by: Jithu Joseph<jithu.joseph@intel.com>

>  .../testing/sysfs-platform-mellanox-bootctl   | 50 ++++++----
>  .../ABI/testing/sysfs-platform-wilco-ec       |  1 +
>  17 files changed, 271 insertions(+), 161 deletions(-)
> 
> diff --git a/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
> b/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
> index 00fa04c76ff3..f5724bb5b462 100644
> --- a/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
> +++ b/Documentation/ABI/stable/sysfs-driver-firmware-zynqmp
> @@ -12,13 +12,15 @@ Description:
>  		resets. Three registers are used by the FSBL and
>  		other Xilinx software products:
> GLOBAL_GEN_STORAGE{4:6}.
>  
> -		Usage:
> -		# cat /sys/devices/platform/firmware\:zynqmp-
> firmware/ggs0
> -		# echo <value> >
> /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> +		Usage::
>  
> -		Example:
> -		# cat /sys/devices/platform/firmware\:zynqmp-
> firmware/ggs0
> -		# echo 0x1234ABCD >
> /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> +		    # cat /sys/devices/platform/firmware\:zynqmp-
> firmware/ggs0
> +		    # echo <value> >
> /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
> +
> +		Example::
> +
> +		    # cat /sys/devices/platform/firmware\:zynqmp-
> firmware/ggs0
> +		    # echo 0x1234ABCD >
> /sys/devices/platform/firmware\:zynqmp-firmware/ggs0
>  
>  Users:		Xilinx
>  
> @@ -39,13 +41,15 @@ Description:
>  		software products: PERS_GLOB_GEN_STORAGE{4:7}.
>  		Register is reset only by a POR reset.
>  
> -		Usage:
> -		# cat /sys/devices/platform/firmware\:zynqmp-
> firmware/pggs0
> -		# echo <value> >
> /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> +		Usage::
>  
> -		Example:
> -		# cat /sys/devices/platform/firmware\:zynqmp-
> firmware/pggs0
> -		# echo 0x1234ABCD >
> /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> +		    # cat /sys/devices/platform/firmware\:zynqmp-
> firmware/pggs0
> +		    # echo <value> >
> /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
> +
> +		Example::
> +
> +		    # cat /sys/devices/platform/firmware\:zynqmp-
> firmware/pggs0
> +		    # echo 0x1234ABCD >
> /sys/devices/platform/firmware\:zynqmp-firmware/pggs0
>  
>  Users:		Xilinx
>  
> @@ -61,23 +65,28 @@ Description:
>  
>  		Following are available shutdown scopes(subtypes):
>  
> -		subsystem:	Only the APU along with all of its
> peripherals
> +		subsystem:
> +				Only the APU along with all of its
> peripherals
>  				not used by other processing units will
> be
>  				shut down. This may result in the FPD
> power
>  				domain being shut down provided that no
> other
>  				processing unit uses FPD peripherals or
> DRAM.
> -		ps_only:	The complete PS will be shut down, including
> the
> +		ps_only:
> +				The complete PS will be shut down,
> including the
>  				RPU, PMU, etc.  Only the PL domain
> (FPGA)
>  				remains untouched.
> -		system:		The complete system/device is shut
> down.
> +		system:
> +				The complete system/device is shut
> down.
>  
> -		Usage:
> -		# cat /sys/devices/platform/firmware\:zynqmp-
> firmware/shutdown_scope
> -		# echo <scope> >
> /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> +		Usage::
>  
> -		Example:
> -		# cat /sys/devices/platform/firmware\:zynqmp-
> firmware/shutdown_scope
> -		# echo "subsystem" >
> /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> +		    # cat /sys/devices/platform/firmware\:zynqmp-
> firmware/shutdown_scope
> +		    # echo <scope> >
> /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
> +
> +		Example::
> +
> +		    # cat /sys/devices/platform/firmware\:zynqmp-
> firmware/shutdown_scope
> +		    # echo "subsystem" >
> /sys/devices/platform/firmware\:zynqmp-firmware/shutdown_scope
>  
>  Users:		Xilinx
>  
> @@ -94,10 +103,13 @@ Description:
>  		system restart.
>  
>  		Usage:
> -		Set healthy bit
> -		# echo 1 > /sys/devices/platform/firmware\:zynqmp-
> firmware/health_status
>  
> -		Unset healthy bit
> -		# echo 0 > /sys/devices/platform/firmware\:zynqmp-
> firmware/health_status
> +		Set healthy bit::
> +
> +		    # echo 1 > /sys/devices/platform/firmware\:zynqmp-
> firmware/health_status
> +
> +		Unset healthy bit::
> +
> +		    # echo 0 > /sys/devices/platform/firmware\:zynqmp-
> firmware/health_status
>  
>  Users:		Xilinx
> diff --git a/Documentation/ABI/testing/debugfs-moxtet
> b/Documentation/ABI/testing/debugfs-moxtet
> index 67b1717794d8..15dfaecb2892 100644
> --- a/Documentation/ABI/testing/debugfs-moxtet
> +++ b/Documentation/ABI/testing/debugfs-moxtet
> @@ -5,10 +5,16 @@ Contact:	Marek Behún <marek.behun@nic.cz>
>  Description:	(R) Read input from the shift registers, in
> hexadecimal.
>  		Returns N+1 bytes, where N is the number of Moxtet
> connected
>  		modules. The first byte is from the CPU board itself.
> -		Example: 101214
> -			 10: CPU board with SD card
> -			 12: 2 = PCIe module, 1 = IRQ not active
> -			 14: 4 = Peridot module, 1 = IRQ not active
> +
> +		Example::
> +
> +			101214
> +
> +		==  =======================================
> +		10  CPU board with SD card
> +		12  2 = PCIe module, 1 = IRQ not active
> +		14  4 = Peridot module, 1 = IRQ not active
> +		==  =======================================
>  
>  What:		/sys/kernel/debug/moxtet/output
>  Date:		March 2019
> @@ -17,7 +23,13 @@ Contact:	Marek Behún <marek.behun@nic.cz>
>  Description:	(RW) Read last written value to the shift registers, in
>  		hexadecimal, or write values to the shift registers,
> also
>  		in hexadecimal.
> -		Example: 0102
> -			 01: 01 was last written, or is to be written,
> to the
> -			     first module's shift register
> -			 02: the same for second module
> +
> +		Example::
> +
> +		    0102
> +
> +		==  ================================================
> +		01  01 was last written, or is to be written, to the
> +		    first module's shift register
> +		02  the same for second module
> +		==  ================================================
> diff --git a/Documentation/ABI/testing/debugfs-turris-mox-rwtm
> b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
> index 2b3255ee68fd..c8f7dadd591c 100644
> --- a/Documentation/ABI/testing/debugfs-turris-mox-rwtm
> +++ b/Documentation/ABI/testing/debugfs-turris-mox-rwtm
> @@ -2,8 +2,10 @@ What:		/sys/kernel/debug/turris-mox-
> rwtm/do_sign
>  Date:		Jun 2020
>  KernelVersion:	5.8
>  Contact:	Marek Behún <marek.behun@nic.cz>
> -Description:	(W) Message to sign with the ECDSA private key stored
> in
> +Description:	(W)
> +		    Message to sign with the ECDSA private key stored
> in
>  		    device's OTP. The message must be exactly 64 bytes
> (since
>  		    this is intended for SHA-512 hashes).
> -		(R) The resulting signature, 136 bytes. This contains
> the R and
> +		(R)
> +		    The resulting signature, 136 bytes. This contains
> the R and
>  		    S values of the ECDSA signature, both in big-endian 
> format.
> diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-
> devices-dfl_fme b/Documentation/ABI/testing/sysfs-bus-event_source-
> devices-dfl_fme
> index c9278a3b3df1..63a32ddcb95e 100644
> --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-
> dfl_fme
> +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-
> dfl_fme
> @@ -8,13 +8,13 @@ Description:	Read-only. Attribute group to
> describe the magic bits
>  
>  		Each attribute under this group defines a bit range of
> the
>  		perf_event_attr.config. All supported attributes are
> listed
> -		below.
> +		below::
>  
>  		    event  = "config:0-11"  - event ID
>  		    evtype = "config:12-15" - event type
>  		    portid = "config:16-23" - event source
>  
> -		For example,
> +		For example::
>  
>  		    fab_mmio_read =
> "event=0x06,evtype=0x02,portid=0xff"
>  
> @@ -40,11 +40,11 @@ Description:	Read-only. Attribute group to
> describe performance monitoring
>  
>  		All supported performance monitoring events are listed
> below.
>  
> -		Basic events (evtype=0x00)
> +		Basic events (evtype=0x00)::
>  
>  		    clock = "event=0x00,evtype=0x00,portid=0xff"
>  
> -		Cache events (evtype=0x01)
> +		Cache events (evtype=0x01)::
>  
>  		    cache_read_hit      =
> "event=0x00,evtype=0x01,portid=0xff"
>  		    cache_read_miss     =
> "event=0x01,evtype=0x01,portid=0xff"
> @@ -59,7 +59,7 @@ Description:	Read-only. Attribute group to
> describe performance monitoring
>  		    cache_rx_req_stall  =
> "event=0x09,evtype=0x01,portid=0xff"
>  		    cache_eviction      =
> "event=0x0a,evtype=0x01,portid=0xff"
>  
> -		Fabric events (evtype=0x02)
> +		Fabric events (evtype=0x02)::
>  
>  		    fab_pcie0_read       =
> "event=0x00,evtype=0x02,portid=0xff"
>  		    fab_pcie0_write      =
> "event=0x01,evtype=0x02,portid=0xff"
> @@ -78,7 +78,7 @@ Description:	Read-only. Attribute group to
> describe performance monitoring
>  		    fab_port_mmio_read   =
> "event=0x06,evtype=0x02,portid=?"
>  		    fab_port_mmio_write  =
> "event=0x07,evtype=0x02,portid=?"
>  
> -		VTD events (evtype=0x03)
> +		VTD events (evtype=0x03)::
>  
>  		    vtd_port_read_transaction  =
> "event=0x00,evtype=0x03,portid=?"
>  		    vtd_port_write_transaction =
> "event=0x01,evtype=0x03,portid=?"
> @@ -88,7 +88,7 @@ Description:	Read-only. Attribute group to
> describe performance monitoring
>  		    vtd_port_devtlb_2m_fill    =
> "event=0x05,evtype=0x03,portid=?"
>  		    vtd_port_devtlb_1g_fill    =
> "event=0x06,evtype=0x03,portid=?"
>  
> -		VTD SIP events (evtype=0x04)
> +		VTD SIP events (evtype=0x04)::
>  
>  		    vtd_sip_iotlb_4k_hit  =
> "event=0x00,evtype=0x04,portid=0xff"
>  		    vtd_sip_iotlb_2m_hit  =
> "event=0x01,evtype=0x04,portid=0xff"
> diff --git a/Documentation/ABI/testing/sysfs-bus-most
> b/Documentation/ABI/testing/sysfs-bus-most
> index ec0a603d804b..38cc03e408e7 100644
> --- a/Documentation/ABI/testing/sysfs-bus-most
> +++ b/Documentation/ABI/testing/sysfs-bus-most
> @@ -235,7 +235,8 @@ KernelVersion:	4.15
>  Contact:	Christian Gromm <christian.gromm@microchip.com>
>  Description:
>  		This is to read back the configured direction of the
> channel.
> -		The following strings will be accepted:
> +		The following strings will be accepted::
> +
>  			'tx',
>  			'rx'
>  Users:
> @@ -246,7 +247,8 @@ KernelVersion:	4.15
>  Contact:	Christian Gromm <christian.gromm@microchip.com>
>  Description:
>  		This is to read back the configured data type of the
> channel.
> -		The following strings will be accepted:
> +		The following strings will be accepted::
> +
>  			'control',
>  			'async',
>  			'sync',
> diff --git a/Documentation/ABI/testing/sysfs-class-devfreq
> b/Documentation/ABI/testing/sysfs-class-devfreq
> index 67af3f31e17c..386bc230a33d 100644
> --- a/Documentation/ABI/testing/sysfs-class-devfreq
> +++ b/Documentation/ABI/testing/sysfs-class-devfreq
> @@ -48,7 +48,8 @@ Description:
>  		driver should provide the list of available frequencies
>  		with its profile. If need to reset the statistics of
> devfreq
>  		behavior on a specific device, enter 0(zero) to
> 'trans_stat'
> -		as following:
> +		as following::
> +
>  			echo 0 > /sys/class/devfreq/.../trans_stat
>  
>  What:		/sys/class/devfreq/.../available_frequencies
> @@ -124,7 +125,8 @@ Description:
>  		This work timer is used by devfreq workqueue in order
> to
>  		monitor the device status such as utilization. The user
>  		can change the work timer on runtime according to their
> demand
> -		as following:
> +		as following::
> +
>  			echo deferrable > /sys/class/devfreq/.../timer
>  			echo delayed > /sys/class/devfreq/.../timer
>  
> diff --git a/Documentation/ABI/testing/sysfs-class-ocxl
> b/Documentation/ABI/testing/sysfs-class-ocxl
> index bf33f4fda58f..847a7edc3113 100644
> --- a/Documentation/ABI/testing/sysfs-class-ocxl
> +++ b/Documentation/ABI/testing/sysfs-class-ocxl
> @@ -13,8 +13,8 @@ Description:	read only
>  		where:
>  
>  			====	=====================================
> ==========
> -			n:	number of currently active contexts,
> for debug
> -			max:	maximum number of contexts supported
> by the AFU
> +			n	number of currently active contexts, for
> debug
> +			max	maximum number of contexts supported
> by the AFU
>  			====	=====================================
> ==========
>  
>  What:		/sys/class/ocxl/<afu name>/pp_mmio_size
> @@ -43,7 +43,9 @@ Contact:	linuxppc-dev@lists.ozlabs.org
>  Description:	read/write
>  		Control whether the FPGA is reloaded on a link reset.
> Enabled
>  		through a vendor-specific logic block on the FPGA.
> -			0	Do not reload FPGA image from flash
> -			1	Reload FPGA image from flash
> -			unavailable
> -				The device does not support this
> capability
> +
> +			===========  ==================================
> =========
> +			0	     Do not reload FPGA image from flash
> +			1	     Reload FPGA image from flash
> +			unavailable  The device does not support this
> capability
> +			===========  ==================================
> =========
> diff --git a/Documentation/ABI/testing/sysfs-class-power-wilco
> b/Documentation/ABI/testing/sysfs-class-power-wilco
> index 84fde1d0ada0..82af180fcaab 100644
> --- a/Documentation/ABI/testing/sysfs-class-power-wilco
> +++ b/Documentation/ABI/testing/sysfs-class-power-wilco
> @@ -4,17 +4,23 @@ KernelVersion:	5.2
>  Description:
>  		What charging algorithm to use:
>  
> -		Standard: Fully charges battery at a standard rate.
> -		Adaptive: Battery settings adaptively optimized based
> on
> +		Standard:
> +			Fully charges battery at a standard rate.
> +		Adaptive:
> +			Battery settings adaptively optimized based on
>  			typical battery usage pattern.
> -		Fast: Battery charges over a shorter period.
> -		Trickle: Extends battery lifespan, intended for users
> who
> +		Fast:
> +			Battery charges over a shorter period.
> +		Trickle:
> +			Extends battery lifespan, intended for users
> who
>  			primarily use their Chromebook while connected
> to AC.
> -		Custom: A low and high threshold percentage is
> specified.
> +		Custom:
> +			A low and high threshold percentage is
> specified.
>  			Charging begins when level drops below
>  			charge_control_start_threshold, and ceases when
>  			level is above charge_control_end_threshold.
> -		Long Life: Customized charge rate for last longer
> battery life.
> +		Long Life:
> +			Customized charge rate for last longer battery
> life.
>  			On Wilco device this mode is pre-configured in
> the factory
>  			through EC's private PID. Swiching to a
> different mode will
>  			be denied by Wilco EC when Long Life mode is
> enabled.
> diff --git a/Documentation/ABI/testing/sysfs-class-rnbd-client
> b/Documentation/ABI/testing/sysfs-class-rnbd-client
> index c084f203b41e..00c0286733d4 100644
> --- a/Documentation/ABI/testing/sysfs-class-rnbd-client
> +++ b/Documentation/ABI/testing/sysfs-class-rnbd-client
> @@ -5,62 +5,70 @@ Contact:	Jack Wang <jinpu.wang@cloud.ionos.com>
> Danil Kipnis <danil.kipnis@cloud
>  Description:	Provide information about RNBD-client.
>  		All sysfs files that are not read-only provide the
> usage information on read:
>  
> -		Example:
> -		# cat /sys/class/rnbd-client/ctl/map_device
> +		Example::
>  
> -		> Usage: echo "sessname=<name of the rtrs session>
> path=<[srcaddr,]dstaddr>
> -		> [path=<[srcaddr,]dstaddr>] device_path=<full path on
> remote side>
> -		> [access_mode=<ro|rw|migration>] > map_device
> -		>
> -		> addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ]
> +		    # cat /sys/class/rnbd-client/ctl/map_device
> +
> +		    > Usage: echo "sessname=<name of the rtrs session>
> path=<[srcaddr,]dstaddr>
> +		    > [path=<[srcaddr,]dstaddr>] device_path=<full path
> on remote side>
> +		    > [access_mode=<ro|rw|migration>] > map_device
> +		    >
> +		    > addr ::= [ ip:<ipv4> | ip:<ipv6> | gid:<gid> ]
>  
>  What:		/sys/class/rnbd-client/ctl/map_device
>  Date:		Feb 2020
>  KernelVersion:	5.7
>  Contact:	Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <
> danil.kipnis@cloud.ionos.com>
> -Description:	Expected format is the following:
> +Description:	Expected format is the following::
>  
> -		sessname=<name of the rtrs session>
> -		path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr> ...]
> -		device_path=<full path on remote side>
> -		[access_mode=<ro|rw|migration>]
> +		    sessname=<name of the rtrs session>
> +		    path=<[srcaddr,]dstaddr> [path=<[srcaddr,]dstaddr>
> ...]
> +		    device_path=<full path on remote side>
> +		    [access_mode=<ro|rw|migration>]
>  
>  		Where:
>  
> -		sessname: accepts a string not bigger than 256 chars,
> which identifies
> -		a given session on the client and on the server.
> -		I.e. "clt_hostname-srv_hostname" could be a natural
> choice.
> +		sessname:
> +		    accepts a string not bigger than 256 chars, which
> identifies
> +		    a given session on the client and on the server.
> +		    I.e. "clt_hostname-srv_hostname" could be a natural
> choice.
>  
> -		path:     describes a connection between the client and
> the server by
> -		specifying destination and, when required, the source
> address.
> -		The addresses are to be provided in the following
> format:
> +		path:
> +		    describes a connection between the client and the
> server by
> +		    specifying destination and, when required, the
> source address.
> +		    The addresses are to be provided in the following
> format::
>  
> -		ip:<IPv6>
> -		ip:<IPv4>
> -		gid:<GID>
> +			ip:<IPv6>
> +			ip:<IPv4>
> +			gid:<GID>
>  
> -		for example:
> +		for example::
> +
> +		    path=ip:10.0.0.66
>  
> -		path=ip:10.0.0.66
>  		The single addr is treated as the destination.
>  		The connection will be established to this server from
> any client IP address.
>  
> -		path=ip:10.0.0.66,ip:10.0.1.66
> +		::
> +
> +		    path=ip:10.0.0.66,ip:10.0.1.66
> +
>  		First addr is the source address and the second is the
> destination.
>  
>  		If multiple "path=" options are specified multiple
> connection
>  		will be established and data will be sent according to
>  		the selected multipath policy (see RTRS mp_policy sysfs
> entry description).
>  
> -		device_path: Path to the block device on the server
> side. Path is specified
> -		relative to the directory on server side configured in
> the
> -		'dev_search_path' module parameter of the rnbd_server.
> -		The rnbd_server prepends the <device_path> received
> from client
> -		with <dev_search_path> and tries to open the
> -		<dev_search_path>/<device_path> block device.  On
> success,
> -		a /dev/rnbd<N> device file, a
> /sys/block/rnbd_client/rnbd<N>/
> -		directory and an entry in /sys/class/rnbd-
> client/ctl/devices
> -		will be created.
> +		device_path:
> +		    Path to the block device on the server side. Path
> is specified
> +		    relative to the directory on server side configured
> in the
> +		    'dev_search_path' module parameter of the
> rnbd_server.
> +		    The rnbd_server prepends the <device_path> received
> from client
> +		    with <dev_search_path> and tries to open the
> +		    <dev_search_path>/<device_path> block device.  On
> success,
> +		    a /dev/rnbd<N> device file, a
> /sys/block/rnbd_client/rnbd<N>/
> +		    directory and an entry in /sys/class/rnbd-
> client/ctl/devices
> +		    will be created.
>  
>  		If 'dev_search_path' contains '%SESSNAME%', then each
> session can
>  		have different devices namespace, e.g. server was
> configured with
> @@ -68,11 +76,12 @@ Description:	Expected format is the
> following:
>  		client has this string "sessname=blya device_path=sda",
> then server
>  		will try to open: /run/rnbd-devs/blya/sda.
>  
> -		access_mode: the access_mode parameter specifies if the
> device is to be
> -		mapped as "ro" read-only or "rw" read-write. The server
> allows
> -		a device to be exported in rw mode only once. The
> "migration"
> -		access mode has to be specified if a second mapping in
> read-write
> -		mode is desired.
> +		access_mode:
> +		    the access_mode parameter specifies if the device
> is to be
> +		    mapped as "ro" read-only or "rw" read-write. The
> server allows
> +		    a device to be exported in rw mode only once. The
> "migration"
> +		    access mode has to be specified if a second mapping
> in read-write
> +		    mode is desired.
>  
>  		By default "rw" is used.
>  
> @@ -91,7 +100,7 @@ Description:	Expected format is the
> following:
>  		is the same as the device name.  By extracting the last
> part of the
>  		path the path to the device /dev/<dev-name> can be
> build.
>  
> -		o /dev/block/$(cat /sys/class/rnbd-
> client/ctl/devices/<device_id>/dev)
> +		* /dev/block/$(cat /sys/class/rnbd-
> client/ctl/devices/<device_id>/dev)
>  
>  		How to find the <device_id> of the device is described
> on the next
>  		section.
> @@ -106,6 +115,6 @@ Description:	For each device mapped on the
> client a new symbolic link is created
>  		The <device_id> of each device is created as follows:
>  
>  		- If the 'device_path' provided during mapping contains
> slashes ("/"),
> -		they are replaced by exclamation mark ("!") and used as
> as the
> -		<device_id>. Otherwise, the <device_id> will be the
> same as the
> -		"device_path" provided.
> +		  they are replaced by exclamation mark ("!") and used
> as as the
> +		  <device_id>. Otherwise, the <device_id> will be the
> same as the
> +		  "device_path" provided.
> diff --git a/Documentation/ABI/testing/sysfs-class-rtrs-client
> b/Documentation/ABI/testing/sysfs-class-rtrs-client
> index e7e718db8941..0f7165aab251 100644
> --- a/Documentation/ABI/testing/sysfs-class-rtrs-client
> +++ b/Documentation/ABI/testing/sysfs-class-rtrs-client
> @@ -10,10 +10,10 @@ Date:		Feb 2020
>  KernelVersion:	5.7
>  Contact:	Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <
> danil.kipnis@cloud.ionos.com>
>  Description:	RW, adds a new path (connection) to an existing
> session. Expected format is the
> -		following:
> +		following::
>  
> -		<[source addr,]destination addr>
> -		*addr ::= [ ip:<ipv4|ipv6> | gid:<gid> ]
> +		    <[source addr,]destination addr>
> +		    *addr ::= [ ip:<ipv4|ipv6> | gid:<gid> ]
>  
>  What:		/sys/class/rtrs-client/<session-
> name>/max_reconnect_attempts
>  Date:		Feb 2020
> @@ -29,10 +29,10 @@ Contact:	Jack Wang <jinpu.wang@cloud.ionos.com>
> Danil Kipnis <danil.kipnis@cloud
>  Description:	Multipath policy specifies which path should be
> selected on each IO:
>  
>  		round-robin (0):
> -		select path in per CPU round-robin manner.
> +		    select path in per CPU round-robin manner.
>  
>  		min-inflight (1):
> -		select path with minimum inflights.
> +		    select path with minimum inflights.
>  
>  What:		/sys/class/rtrs-client/<session-name>/paths/
>  Date:		Feb 2020
> @@ -109,8 +109,11 @@ Description:	RTRS expects that each HCA IRQ
> is pinned to a separate CPU. If it's
>  		not the case, the processing of an I/O response could
> be processed on a
>  		different CPU than where it was originally
> submitted.  This file shows
>  		how many interrupts where generated on a non expected
> CPU.
> -		"from:" is the CPU on which the IRQ was expected, but
> not generated.
> -		"to:" is the CPU on which the IRQ was generated, but
> not expected.
> +
> +		"from:"
> +		    is the CPU on which the IRQ was expected, but not
> generated.
> +		"to:"
> +		    is the CPU on which the IRQ was generated, but not
> expected.
>  
>  What:		/sys/class/rtrs-client/<session-name>/paths/<
> src@dst>/stats/reconnects
>  Date:		Feb 2020
> @@ -125,7 +128,7 @@ Date:		Feb 2020
>  KernelVersion:	5.7
>  Contact:	Jack Wang <jinpu.wang@cloud.ionos.com> Danil Kipnis <
> danil.kipnis@cloud.ionos.com>
>  Description:	Contains statistics regarding rdma operations and
> inflight operations.
> -		The output consists of 6 values:
> +		The output consists of 6 values::
>  
> -		<read-count> <read-total-size> <write-count> <write-
> total-size> \
> -		<inflights> <failovered>
> +		    <read-count> <read-total-size> <write-count> \
> +		    <write-total-size> <inflights> <failovered>
> diff --git a/Documentation/ABI/testing/sysfs-devices-platform-
> stratix10-rsu b/Documentation/ABI/testing/sysfs-devices-platform-
> stratix10-rsu
> index a8daceb4a956..ee253b033280 100644
> --- a/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
> +++ b/Documentation/ABI/testing/sysfs-devices-platform-stratix10-rsu
> @@ -102,6 +102,8 @@ Description:
>  		b[15:0]
>  			inform firmware the current software execution
>  			stage.
> +
> +			==	=====================================
> ======
>  			0	the first stage bootloader didn't run or
>  				didn't reach the point of launching
> second
>  				stage bootloader.
> @@ -111,21 +113,29 @@ Description:
>  			2	both first and second stage bootloader ran
>  				and the operating system launch was
>  				attempted.
> +			==	=====================================
> ======
>  
>  		b[16]
> +			==	=====================================
> ======
>  			1	firmware to reset current image retry
>  				counter.
>  			0	no action.
> +			==	=====================================
> ======
>  
>  		b[17]
> +			==	=====================================
> ======
>  			1	firmware to clear RSU log
>  			0	no action.
> +			==	=====================================
> ======
>  
>  		b[18]
>  			this is negative logic
> +
> +			==	=====================================
> ======
>  			1	no action
>  			0	firmware record the notify code defined
>  				in b[15:0].
> +			==	=====================================
> ======
>  
>  What:		/sys/devices/platform/stratix10-rsu.0/dcmf0
>  Date:		June 2020
> diff --git a/Documentation/ABI/testing/sysfs-driver-w1_therm
> b/Documentation/ABI/testing/sysfs-driver-w1_therm
> index 8873bbb075cb..6a37dc33ffdb 100644
> --- a/Documentation/ABI/testing/sysfs-driver-w1_therm
> +++ b/Documentation/ABI/testing/sysfs-driver-w1_therm
> @@ -22,8 +22,10 @@ Description:
>  		device data to its embedded EEPROM, either restore data
>  		embedded in device EEPROM. Be aware that devices
> support
>  		limited EEPROM writing cycles (typical 50k)
> +
>  			* 'save': save device RAM to EEPROM
>  			* 'restore': restore EEPROM data in device RAM
> +
>  Users:		any user space application which wants to
> communicate with
>  		w1_term device
>  
> @@ -33,9 +35,11 @@ Date:		May 2020
>  Contact:	Akira Shimahara <akira215corp@gmail.com>
>  Description:
>  		(RO) return the power status by asking the device
> +
>  			* '0': device parasite powered
>  			* '1': device externally powered
>  			* '-xx': xx is kernel error when reading power
> status
> +
>  Users:		any user space application which wants to
> communicate with
>  		w1_term device
>  
> @@ -49,10 +53,12 @@ Description:
>  		will be changed only in device RAM, so it will be
> cleared when
>  		power is lost. Trigger a 'save' to EEPROM command to
> keep
>  		values after power-on. Read or write are :
> +
>  			* '9..14': device resolution in bit
> -			or resolution to set in bit
> +			  or resolution to set in bit
>  			* '-xx': xx is kernel error when reading the
> resolution
>  			* Anything else: do nothing
> +
>  		Some DS18B20 clones are fixed in 12-bit resolution, so
> the
>  		actual resolution is read back from the chip and
> verified. Error
>  		is reported if the results differ.
> @@ -65,16 +71,18 @@ Date:		May 2020
>  Contact:	Akira Shimahara <akira215corp@gmail.com>
>  Description:
>  		(RO) return the temperature in 1/1000 degC.
> +
>  			* If a bulk read has been triggered, it will
> directly
> -			return the temperature computed when the bulk
> read
> -			occurred, if available. If not yet available,
> nothing
> -			is returned (a debug kernel message is sent),
> you
> -			should retry later on.
> +			  return the temperature computed when the bulk
> read
> +			  occurred, if available. If not yet available,
> nothing
> +			  is returned (a debug kernel message is sent),
> you
> +			  should retry later on.
>  			* If no bulk read has been triggered, it will
> trigger
> -			a conversion and send the result. Note that the
> -			conversion duration depend on the resolution
> (if
> -			device support this feature). It takes 94ms in
> 9bits
> -			resolution, 750ms for 12bits.
> +			  a conversion and send the result. Note that
> the
> +			  conversion duration depend on the resolution
> (if
> +			  device support this feature). It takes 94ms
> in 9bits
> +			  resolution, 750ms for 12bits.
> +
>  Users:		any user space application which wants to
> communicate with
>  		w1_term device
>  
> @@ -86,12 +94,14 @@ Description:
>  		(RW) return the temperature in 1/1000 degC.
>  		*read*: return 2 lines with the hexa output data sent
> on the
>  		bus, return the CRC check and temperature in 1/1000
> degC
> -		*write* :
> +		*write*:
> +
>  			* '0' : save the 2 or 3 bytes to the device
> EEPROM
> -			(i.e. TH, TL and config register)
> +			  (i.e. TH, TL and config register)
>  			* '9..14' : set the device resolution in RAM
> -			(if supported)
> +			  (if supported)
>  			* Anything else: do nothing
> +
>  		refer to Documentation/w1/slaves/w1_therm.rst for
> detailed
>  		information.
>  Users:		any user space application which wants to
> communicate with
> @@ -103,14 +113,21 @@ Date:		May 2020
>  Contact:	Akira Shimahara <akira215corp@gmail.com>
>  Description:
>  		(RW) trigger a bulk read conversion. read the status
> +
>  		*read*:
> -			* '-1': conversion in progress on at least 1
> sensor
> -			* '1' :	conversion complete but at least one
> sensor
> +			* '-1':
> +				conversion in progress on at least 1
> sensor
> +			* '1' :
> +				conversion complete but at least one
> sensor
>  				value has not been read yet
> -			* '0' :	no bulk operation. Reading
> temperature will
> +			* '0' :
> +				no bulk operation. Reading temperature
> will
>  				trigger a conversion on each device
> -		*write*: 'trigger': trigger a bulk read on all
> supporting
> +
> +		*write*:
> +			'trigger': trigger a bulk read on all
> supporting
>  			devices on the bus
> +
>  		Note that if a bulk read is sent but one sensor is not
> read
>  		immediately, the next access to temperature on this
> device
>  		will return the temperature measured at the time of
> issue
> @@ -128,14 +145,19 @@ Description:
>  		reset to default (datasheet) conversion time for a new
>  		resolution.
>  
> -		*read*: Actual conversion time in milliseconds.
> *write*:
> -			'0': Set the default conversion time from the
> datasheet.
> -			'1': Measure and set the conversion time. Make
> a single
> +		*read*:
> +			Actual conversion time in milliseconds.
> +
> +		*write*:
> +			* '0':
> +			     Set the default conversion time from the
> datasheet.
> +			* '1':
> +			     Measure and set the conversion time. Make
> a single
>  			     temperature conversion, measure an actual
> value.
>  			     Increase it by 20% for temperature range.
> A new
>  			     conversion time can be obtained by reading
> this
>  			     same attribute.
> -			other positive value:
> +			* other positive value:
>  			     Set the conversion time in milliseconds.
>  
>  Users:		An application using the w1_term device
> @@ -148,16 +170,21 @@ Description:
>  		(RW) Control optional driver settings.
>  		Bit masks to read/write (bitwise OR):
>  
> -                1: Enable check for conversion success. If byte 6 of
> +		==
> ============================================================
> +                 1 Enable check for conversion success. If byte 6 of
>                     scratchpad memory is 0xC after conversion, and
>                     temperature reads 85.00 (powerup value) or 127.94
>                     (insufficient power) - return a conversion error.
>  
> -                2: Enable poll for conversion completion. Generate
> read cycles
> +                2  Enable poll for conversion completion. Generate
> read cycles
>                     after the conversion start and wait for 1's. In
> parasite
>                     power mode this feature is not available.
> +		==
> ============================================================
>  
> -		*read*:  Currently selected features.
> -		*write*: Select features.
> +		*read*:
> +		    Currently selected features.
> +
> +		*write*:
> +		    Select features.
>  
>  Users:		An application using the w1_term device
> diff --git a/Documentation/ABI/testing/sysfs-platform-dfl-fme
> b/Documentation/ABI/testing/sysfs-platform-dfl-fme
> index 3683cb1cdc3d..d6ab34e81b9b 100644
> --- a/Documentation/ABI/testing/sysfs-platform-dfl-fme
> +++ b/Documentation/ABI/testing/sysfs-platform-dfl-fme
> @@ -113,8 +113,11 @@ KernelVersion:	5.5
>  Contact:	Wu Hao <hao.wu@intel.com>
>  Description:	Read-Only. Read this file to get the name of hwmon
> device, it
>  		supports values:
> -		    'dfl_fme_thermal' - thermal hwmon device name
> -		    'dfl_fme_power'   - power hwmon device name
> +
> +		=================  =========================
> +		'dfl_fme_thermal'  thermal hwmon device name
> +		'dfl_fme_power'    power hwmon device name
> +		=================  =========================
>  
>  What:		/sys/bus/platform/devices/dfl-
> fme.0/hwmon/hwmonX/temp1_input
>  Date:		October 2019
> @@ -169,8 +172,11 @@ KernelVersion:	5.5
>  Contact:	Wu Hao <hao.wu@intel.com>
>  Description:	Read-Only. Read this file to get the policy of hardware
> threshold1
>  		(see 'temp1_max'). It only supports two values
> (policies):
> -		    0 - AP2 state (90% throttling)
> -		    1 - AP1 state (50% throttling)
> +
> +		==  ==========================
> +		 0  AP2 state (90% throttling)
> +	         1  AP1 state (50% throttling)
> +		==  ==========================
>  
>  What:		/sys/bus/platform/devices/dfl-
> fme.0/hwmon/hwmonX/power1_input
>  Date:		October 2019
> diff --git a/Documentation/ABI/testing/sysfs-platform-dptf
> b/Documentation/ABI/testing/sysfs-platform-dptf
> index 2cbc660d163b..141834342a4d 100644
> --- a/Documentation/ABI/testing/sysfs-platform-dptf
> +++ b/Documentation/ABI/testing/sysfs-platform-dptf
> @@ -27,12 +27,15 @@ KernelVersion:	v4.10
>  Contact:	linux-acpi@vger.kernel.org
>  Description:
>  		(RO) Display the platform power source
> +
> +		========= ============================
>  		bits[3:0] Current power source
> -			0x00 = DC
> -			0x01 = AC
> -			0x02 = USB
> -			0x03 = Wireless Charger
> +			  - 0x00 = DC
> +			  - 0x01 = AC
> +			  - 0x02 = USB
> +			  - 0x03 = Wireless Charger
>  		bits[7:4] Power source sequence number
> +		========= ============================
>  
>  What:		/sys/bus/platform/devices/INT3407:00/dptf_power
> /battery_steady_power
>  Date:		Jul, 2016
> diff --git a/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-
> fw-update b/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-
> fw-update
> index 5aa618987cad..02ae1e9bbfc8 100644
> --- a/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-
> update
> +++ b/Documentation/ABI/testing/sysfs-platform-intel-wmi-sbl-fw-
> update
> @@ -8,5 +8,6 @@ Description:
>  		of 0 and userspace can signal SBL to update firmware,
>  		on next reboot, by writing a value of 1.
>  		There are two available states:
> +
>  		    * 0 -> Skip firmware update while rebooting
>  		    * 1 -> Attempt firmware update on next reboot
> diff --git a/Documentation/ABI/testing/sysfs-platform-mellanox-
> bootctl b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
> index 401d202f478b..e79ca22e2f45 100644
> --- a/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
> +++ b/Documentation/ABI/testing/sysfs-platform-mellanox-bootctl
> @@ -5,10 +5,13 @@ Contact:	"Liming Sun <lsun@mellanox.com>"
>  Description:
>  		The Life-cycle state of the SoC, which could be one of
> the
>  		following values.
> -		  Production - Production state and can be updated to
> secure
> -		  GA Secured - Secure chip and not able to change state
> -		  GA Non-Secured - Non-Secure chip and not able to
> change state
> -		  RMA - Return Merchandise Authorization
> +
> +		==============  =======================================
> ======
> +		Production      Production state and can be updated to
> secure
> +		GA Secured      Secure chip and not able to change
> state
> +		GA Non-Secured  Non-Secure chip and not able to change
> state
> +		RMA             Return Merchandise Authorization
> +		==============  =======================================
> ======
>  
>  What:		/sys/bus/platform/devices/MLNXBF04:00/post_rese
> t_wdog
>  Date:		Oct 2019
> @@ -25,10 +28,13 @@ KernelVersion:	5.5
>  Contact:	"Liming Sun <lsun@mellanox.com>"
>  Description:
>  		The source of the boot stream for the next reset. It
> could be
> -		one of the following values.
> -		  external - boot from external source (USB or PCIe)
> -		  emmc - boot from the onchip eMMC
> -		  emmc_legacy - boot from the onchip eMMC in legacy
> (slow) mode
> +		one of the following values:
> +
> +		===========  ==========================================
> =====
> +		external     boot from external source (USB or PCIe)
> +		emmc         boot from the onchip eMMC
> +		emmc_legacy  boot from the onchip eMMC in legacy (slow)
> mode
> +		===========  ==========================================
> =====
>  
>  What:		/sys/bus/platform/devices/MLNXBF04:00/second_re
> set_action
>  Date:		Oct 2019
> @@ -38,11 +44,14 @@ Description:
>  		Update the source of the boot stream after next reset.
> It could
>  		be one of the following values and will be applied
> after next
>  		reset.
> -		  external - boot from external source (USB or PCIe)
> -		  emmc - boot from the onchip eMMC
> -		  emmc_legacy - boot from the onchip eMMC in legacy
> (slow) mode
> -		  swap_emmc - swap the primary / secondary boot
> partition
> -		  none - cancel the action
> +
> +		===========  ==========================================
> =====
> +		external     boot from external source (USB or PCIe)
> +		emmc         boot from the onchip eMMC
> +		emmc_legacy  boot from the onchip eMMC in legacy (slow)
> mode
> +		swap_emmc    swap the primary / secondary boot
> partition
> +		none         cancel the action
> +		===========  ==========================================
> =====
>  
>  What:		/sys/bus/platform/devices/MLNXBF04:00/secure_bo
> ot_fuse_state
>  Date:		Oct 2019
> @@ -50,9 +59,12 @@ KernelVersion:	5.5
>  Contact:	"Liming Sun <lsun@mellanox.com>"
>  Description:
>  		The state of eFuse versions with the following values.
> -		  InUse - burnt, valid and currently in use
> -		  Used - burnt and valid
> -		  Free - not burnt and free to use
> -		  Skipped - not burnt but not free (skipped)
> -		  Wasted - burnt and invalid
> -		  Invalid - not burnt but marked as valid (error
> state).
> +
> +		=======  ==============================================
> =
> +		InUse    burnt, valid and currently in use
> +		Used     burnt and valid
> +		Free     not burnt and free to use
> +		Skipped  not burnt but not free (skipped)
> +		Wasted   burnt and invalid
> +		Invalid  not burnt but marked as valid (error state).
> +		=======  ==============================================
> =
> diff --git a/Documentation/ABI/testing/sysfs-platform-wilco-ec
> b/Documentation/ABI/testing/sysfs-platform-wilco-ec
> index 5f60b184a5a5..4439d0644091 100644
> --- a/Documentation/ABI/testing/sysfs-platform-wilco-ec
> +++ b/Documentation/ABI/testing/sysfs-platform-wilco-ec
> @@ -39,6 +39,7 @@ Description:
>                 which affects charging via the special USB PowerShare
> port
>                 (marked with a small lightning bolt or battery icon)
> when in
>                 low power states:
> +
>                 - In S0, the port will always provide power.
>                 - In S0ix, if usb_charge is enabled, then power will
> be
>                   supplied to the port when on AC or if battery is >
> 50%.

Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Jonathan Cameron]

On Mon, 2 Nov 2020 15:42:50 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> Em Mon, 2 Nov 2020 13:46:41 +0100
> Greg Kroah-Hartman <gregkh@linuxfoundation.org> escreveu:
> 
> > On Mon, Nov 02, 2020 at 12:04:36PM +0100, Fabrice Gasnier wrote:  
> > > On 10/30/20 11:09 AM, Mauro Carvalho Chehab wrote:    
> > > > Em Fri, 30 Oct 2020 10:19:12 +0100
> > > > Fabrice Gasnier <fabrice.gasnier@st.com> escreveu:
> > > >     
> > > >> Hi Mauro,
> > > >>
> > > >> [...]
> > > >>    
> > > >>>  
> > > >>> +What:		/sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> > > >>> +KernelVersion:	4.12
> > > >>> +Contact:	benjamin.gaignard@st.com
> > > >>> +Description:
> > > >>> +		Reading returns the list possible quadrature modes.
> > > >>> +
> > > >>> +What:		/sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode
> > > >>> +KernelVersion:	4.12
> > > >>> +Contact:	benjamin.gaignard@st.com
> > > >>> +Description:
> > > >>> +		Configure the device counter quadrature modes:
> > > >>> +
> > > >>> +		channel_A:
> > > >>> +			Encoder A input servers as the count input and B as
> > > >>> +			the UP/DOWN direction control input.
> > > >>> +
> > > >>> +		channel_B:
> > > >>> +			Encoder B input serves as the count input and A as
> > > >>> +			the UP/DOWN direction control input.
> > > >>> +
> > > >>> +		quadrature:
> > > >>> +			Encoder A and B inputs are mixed to get direction
> > > >>> +			and count with a scale of 0.25.
> > > >>> +      
> > > >>    
> > > > 
> > > > Hi Fabrice,
> > > >     
> > > >> I just noticed that since Jonathan question in v1.
> > > >>
> > > >> Above ABI has been moved in the past as discussed in [1]. You can take a
> > > >> look at:
> > > >> b299d00 IIO: stm32: Remove quadrature related functions from trigger driver
> > > >>
> > > >> Could you please remove the above chunk ?
> > > >>
> > > >> With that, for the stm32 part:
> > > >> Acked-by: Fabrice Gasnier <fabrice.gasnier@st.com>    
> > > > 
> > > > 
> > > > Hmm... probably those were re-introduced due to a rebase. This
> > > > series were originally written about 1,5 years ago.
> > > > 
> > > > I'll drop those hunks.    
> > > 
> > > Hi Mauro, Greg,
> > > 
> > > I just figured out this patch has been applied with above hunk.
> > > 
> > > This should be dropped: is there a fix on its way already ?
> > > (I may have missed it)    
> > 
> > Can you send a fix for just this hunk?  
> 
> Hmm...
> 
> 	$ git grep /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> 	Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:What:                /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> 	Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:What:             /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> 	Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:What:               /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> 
> Even re-doing the changes from 
> changeset b299d00420e2 ("IIO: stm32: Remove quadrature related functions from trigger driver")
> at Documentation/ABI/testing/sysfs-bus-iio-timer-stm32, there's still
> a third duplicate of some of those, as reported by the script:
> 
> 	$ ./scripts/get_abi.pl validate 2>&1|grep quadra
> 	Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:117  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:14
> 	Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 3 times:  Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:111  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:8
> 
> As in_count_quadrature_mode_available is also defined at:
> 	Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2
> 
> The best here seems to have a patch that will also drop the other
> duplication of this, probably moving in_count_quadrature_mode_available
> to a generic node probably placing it inside 
> Documentation/ABI/testing/sysfs-bus-iio.

In this particular case it may be valid to do that, but it's not in
general without loosing information - see below.

> 
> Comments?
> 
> Thanks,
> Mauro
> 
> PS.: the IIO subsystem is the one that currently has more duplicated
> ABI entries:

That was intentional.  Often these provide more information on the
ABI for a particular device than is present in the base ABI doc.

A bit like when we have additional description for dt binding properties
for a particular device, even though they are standard properties.

Often a standard property allows for more values than the specific
one for a particular device.  There can also be obscuring coupling
between sysfs attributes due to hardware restrictions that we would
like to provide some explanatory info on.

I suppose we could add all this information to the parent doc but
that is pretty ugly and will make that doc very nasty to read.

Jonathan

> 
> $ ./scripts/get_abi.pl validate 2>&1|grep iio
> Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:0  Documentation/ABI/testing/sysfs-bus-iio:394
> Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:1  Documentation/ABI/testing/sysfs-bus-iio:395
> Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:2  Documentation/ABI/testing/sysfs-bus-iio:396
> Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:3  Documentation/ABI/testing/sysfs-bus-iio:397
> Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:4  Documentation/ABI/testing/sysfs-bus-iio:398
> Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:5  Documentation/ABI/testing/sysfs-bus-iio:399
> Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_preset is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:100  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:0
> Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:117  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:14
> Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 3 times:  Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:111  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:8
> Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:0  Documentation/ABI/testing/sysfs-bus-iio:599
> Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:36  Documentation/ABI/testing/sysfs-bus-iio:588
> Warning: /sys/bus/iio/devices/iio:deviceX/out_currentY_raw is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als:43  Documentation/ABI/testing/sysfs-bus-iio-health-afe440x:38
> Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:0  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:0
> Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:1  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:1
> Warning: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-distance-srf08:0  Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935:8
> Warning: /sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  Documentation/ABI/testing/sysfs-bus-iio:45

Duplicated ABI entries - Was: Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Mauro Carvalho Chehab]

Hi Jonathan,

Em Sun, 8 Nov 2020 16:56:21 +0000
Jonathan Cameron <jic23@kernel.org> escreveu:

> > PS.: the IIO subsystem is the one that currently has more duplicated
> > ABI entries:  
> > $ ./scripts/get_abi.pl validate 2>&1|grep iio
> > Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:0  Documentation/ABI/testing/sysfs-bus-iio:394
> > Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:1  Documentation/ABI/testing/sysfs-bus-iio:395
> > Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:2  Documentation/ABI/testing/sysfs-bus-iio:396
> > Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:3  Documentation/ABI/testing/sysfs-bus-iio:397
> > Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:4  Documentation/ABI/testing/sysfs-bus-iio:398
> > Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:5  Documentation/ABI/testing/sysfs-bus-iio:399
> > Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_preset is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:100  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:0
> > Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:117  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:14
> > Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 3 times:  Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:111  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:8
> > Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:0  Documentation/ABI/testing/sysfs-bus-iio:599
> > Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:36  Documentation/ABI/testing/sysfs-bus-iio:588
> > Warning: /sys/bus/iio/devices/iio:deviceX/out_currentY_raw is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als:43  Documentation/ABI/testing/sysfs-bus-iio-health-afe440x:38
> > Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:0  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:0
> > Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:1  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:1
> > Warning: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-distance-srf08:0  Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935:8
> > Warning: /sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  Documentation/ABI/testing/sysfs-bus-iio:45  

> 
> That was intentional.  Often these provide more information on the
> ABI for a particular device than is present in the base ABI doc.

FYI, right now, there are 20 duplicated entries, being 16 of them
from IIO, on those files:

	$ ./scripts/get_abi.pl validate 2>&1|perl -ne 'if (m,(Documentation/\S+)\:,g) { print "$1\n" }'|sort|uniq
	Documentation/ABI/stable/sysfs-driver-w1_ds28e04
	Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8
	Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
	Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
	Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010
	Documentation/ABI/testing/sysfs-bus-iio-icm42600
	Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als
	Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
	Documentation/ABI/testing/sysfs-class-backlight-adp8860
	Documentation/ABI/testing/sysfs-class-led-trigger-pattern
	Documentation/ABI/testing/sysfs-kernel-iommu_groups

> 
> A bit like when we have additional description for dt binding properties
> for a particular device, even though they are standard properties.
> 
> Often a standard property allows for more values than the specific
> one for a particular device.  There can also be obscuring coupling
> between sysfs attributes due to hardware restrictions that we would
> like to provide some explanatory info on.
> 
> I suppose we could add all this information to the parent doc but
> that is pretty ugly and will make that doc very nasty to read.

I understand what you meant to do, but right now, it is is actually
a lot uglier than merging into a single entry ;-)

Let's view ABI from the PoV of a system admin that doesn't know
yet about a certain ABI symbol.

He'll try to seek for the symbol, more likely using the HTML 
documentation. Only very senior system admins might try to take
a look at the Kernel.

This is what happens when one would seek for a duplicated symbol
via command line:

	$ ./scripts/get_abi.pl search /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency$
	
	/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency
	----------------------------------------------------------
	
	Kernel version:		3.4.0
	Contact:		linux-iio@vger.kernel.org
	Defined on file(s):	Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 Documentation/ABI/testing/sysfs-bus-iio
	
	Description:
	
	Stores the PLL frequency in Hz for channel Y.
	Reading returns the actual frequency in Hz.
	The ADF4371 has an integrated VCO with fundamendal output
	frequency ranging from 4000000000 Hz 8000000000 Hz.
	
	out_altvoltage0_frequency:
	        A divide by 1, 2, 4, 8, 16, 32 or circuit generates
	        frequencies from 62500000 Hz to 8000000000 Hz.
	out_altvoltage1_frequency:
	        This channel duplicates the channel 0 frequency
	out_altvoltage2_frequency:
	        A frequency doubler generates frequencies from
	        8000000000 Hz to 16000000000 Hz.
	out_altvoltage3_frequency:
	        A frequency quadrupler generates frequencies from
	        16000000000 Hz to 32000000000 Hz.
	
	Note: writes to one of the channels will affect the frequency of
	all the other channels, since it involves changing the VCO
	fundamental output frequency.
	
	Output frequency for channel Y in Hz. The number must always be
	specified and unique if the output corresponds to a single
	channel.

As the "What:" field is identical on both sysfs-bus-iio-frequency-adf4371
and sysfs-bus-iio, those entries are merged, which produces an ABI
documentation mixing both the generic one and the board specific one
into a single output.

Worse than that, the "generic" content is at the end.

The same happens when generating the HTML output.

See, entries at the HTML output are ordered by the What: field,
which is considered within the script as an unique key, as it is
unique (except for IIO and a couple of other cases).

-

As I commented on an e-mail I sent to Greg, I see a few ways
to solve it.

The most trivial one (which I used to solve a few conflicts on
other places), is to place driver-specific details on a separate
file under Documentation/driver-api, and mention it at the
generic entries. The docs building system will generate cross
references for Documentation/.../foo.rst files, so, everything
should be OK.

The second alternative that I also used on a couple of places
is to modify the generic entry for it to contain the generic
definition first, followed by per-device details.

There is a third possible alternative: add a new optional field
(something like Scope:) which would be part of the unique key,
if present. Implementing support for it could be tricky, as the
produced output would likely need to create cross-references
between the generic field (if present) and the per-device details.

Thanks,
Mauro

PS.: I'm taking a few days of PTO during this week. So, it
could take a while for me to reply again to this thread.

Re: Duplicated ABI entries - Was: Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Randy Dunlap]

On 11/9/20 11:26 PM, Mauro Carvalho Chehab wrote:
> Hi Jonathan,
> 
> Let's view ABI from the PoV of a system admin that doesn't know
> yet about a certain ABI symbol.
> 
> He'll try to seek for the symbol, more likely using the HTML 
> documentation. Only very senior system admins might try to take
> a look at the Kernel.

FWIW, I think that the likely search methods are $search_engine
and 'grep'.

Have a good few days off.

-- 
~Randy

Re: Duplicated ABI entries - Was: Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Jonathan Cameron]

On Tue, 10 Nov 2020 08:26:58 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> Hi Jonathan,
> 
> Em Sun, 8 Nov 2020 16:56:21 +0000
> Jonathan Cameron <jic23@kernel.org> escreveu:
> 
> > > PS.: the IIO subsystem is the one that currently has more duplicated
> > > ABI entries:  
> > > $ ./scripts/get_abi.pl validate 2>&1|grep iio
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:0  Documentation/ABI/testing/sysfs-bus-iio:394
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:1  Documentation/ABI/testing/sysfs-bus-iio:395
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:2  Documentation/ABI/testing/sysfs-bus-iio:396
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:3  Documentation/ABI/testing/sysfs-bus-iio:397
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:4  Documentation/ABI/testing/sysfs-bus-iio:398
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:5  Documentation/ABI/testing/sysfs-bus-iio:399
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_preset is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:100  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:0
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:117  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:14
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 3 times:  Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:111  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:8
> > > Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:0  Documentation/ABI/testing/sysfs-bus-iio:599
> > > Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:36  Documentation/ABI/testing/sysfs-bus-iio:588
> > > Warning: /sys/bus/iio/devices/iio:deviceX/out_currentY_raw is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als:43  Documentation/ABI/testing/sysfs-bus-iio-health-afe440x:38
> > > Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:0  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:0
> > > Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:1  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:1
> > > Warning: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-distance-srf08:0  Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935:8
> > > Warning: /sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  Documentation/ABI/testing/sysfs-bus-iio:45    
> 
> > 
> > That was intentional.  Often these provide more information on the
> > ABI for a particular device than is present in the base ABI doc.  
> 
> FYI, right now, there are 20 duplicated entries, being 16 of them
> from IIO, on those files:
> 
> 	$ ./scripts/get_abi.pl validate 2>&1|perl -ne 'if (m,(Documentation/\S+)\:,g) { print "$1\n" }'|sort|uniq
> 	Documentation/ABI/stable/sysfs-driver-w1_ds28e04
> 	Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8
> 	Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
> 	Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
> 	Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010
> 	Documentation/ABI/testing/sysfs-bus-iio-icm42600
> 	Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als
> 	Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> 	Documentation/ABI/testing/sysfs-class-backlight-adp8860
> 	Documentation/ABI/testing/sysfs-class-led-trigger-pattern
> 	Documentation/ABI/testing/sysfs-kernel-iommu_groups
> 
> > 
> > A bit like when we have additional description for dt binding properties
> > for a particular device, even though they are standard properties.
> > 
> > Often a standard property allows for more values than the specific
> > one for a particular device.  There can also be obscuring coupling
> > between sysfs attributes due to hardware restrictions that we would
> > like to provide some explanatory info on.
> > 
> > I suppose we could add all this information to the parent doc but
> > that is pretty ugly and will make that doc very nasty to read.  
> 
> I understand what you meant to do, but right now, it is is actually
> a lot uglier than merging into a single entry ;-)
> 
> Let's view ABI from the PoV of a system admin that doesn't know
> yet about a certain ABI symbol.

I'd be surprised if a sys admin is looking at these at all. They
tend to be used only by userspace software writers.  But I guess the
point stands.

> 
> He'll try to seek for the symbol, more likely using the HTML 
> documentation. Only very senior system admins might try to take
> a look at the Kernel.

Sad truth here is that before these were in the html docs, they'd
have grepped and the right option would fairly obvious as it
would be the more specific file.  Ah well, sometimes progress bites :)

> 
> This is what happens when one would seek for a duplicated symbol
> via command line:
> 
> 	$ ./scripts/get_abi.pl search /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency$
> 	
> 	/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency
> 	----------------------------------------------------------
> 	
> 	Kernel version:		3.4.0
> 	Contact:		linux-iio@vger.kernel.org
> 	Defined on file(s):	Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 Documentation/ABI/testing/sysfs-bus-iio
> 	
> 	Description:
> 	
> 	Stores the PLL frequency in Hz for channel Y.
> 	Reading returns the actual frequency in Hz.
> 	The ADF4371 has an integrated VCO with fundamendal output
> 	frequency ranging from 4000000000 Hz 8000000000 Hz.
> 	
> 	out_altvoltage0_frequency:
> 	        A divide by 1, 2, 4, 8, 16, 32 or circuit generates
> 	        frequencies from 62500000 Hz to 8000000000 Hz.
> 	out_altvoltage1_frequency:
> 	        This channel duplicates the channel 0 frequency
> 	out_altvoltage2_frequency:
> 	        A frequency doubler generates frequencies from
> 	        8000000000 Hz to 16000000000 Hz.
> 	out_altvoltage3_frequency:
> 	        A frequency quadrupler generates frequencies from
> 	        16000000000 Hz to 32000000000 Hz.
> 	
> 	Note: writes to one of the channels will affect the frequency of
> 	all the other channels, since it involves changing the VCO
> 	fundamental output frequency.
> 	
> 	Output frequency for channel Y in Hz. The number must always be
> 	specified and unique if the output corresponds to a single
> 	channel.
> 
> As the "What:" field is identical on both sysfs-bus-iio-frequency-adf4371
> and sysfs-bus-iio, those entries are merged, which produces an ABI
> documentation mixing both the generic one and the board specific one
> into a single output.
> 
> Worse than that, the "generic" content is at the end.
> 
> The same happens when generating the HTML output.
> 
> See, entries at the HTML output are ordered by the What: field,
> which is considered within the script as an unique key, as it is
> unique (except for IIO and a couple of other cases).
> 
> -
> 
> As I commented on an e-mail I sent to Greg, I see a few ways
> to solve it.
> 
> The most trivial one (which I used to solve a few conflicts on
> other places), is to place driver-specific details on a separate
> file under Documentation/driver-api, and mention it at the
> generic entries. The docs building system will generate cross
> references for Documentation/.../foo.rst files, so, everything
> should be OK.

Hmm. That might work out OK.  These devices tend to be weird enough
that they probably could do with some additional explanation anyway. 

> 
> The second alternative that I also used on a couple of places
> is to modify the generic entry for it to contain the generic
> definition first, followed by per-device details.

I'll do an audit of what we actually have here. Perhaps we end
up with a mixture of these two options.

Might take a little while though.

> 
> There is a third possible alternative: add a new optional field
> (something like Scope:) which would be part of the unique key,
> if present. Implementing support for it could be tricky, as the
> produced output would likely need to create cross-references
> between the generic field (if present) and the per-device details.
That would be lovely but probably not worth the effort for something
that occurs so rarely currently.

Jonathan

> 
> Thanks,
> Mauro
> 
> PS.: I'm taking a few days of PTO during this week. So, it
> could take a while for me to reply again to this thread.