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