[PATCH 00/14] Add support to generate ABI documentation at admin-guide

[PATCH 00/14] Add support to generate ABI documentation at admin-guide

[Mauro Carvalho Chehab]

Greg,

As promised, I'm resending the patch series with adds the Kernel ABI to
Documentation/admin-guide.

Those patches are basically the version 3 patchset I sent back in 2017,
rebased on the top of linux-next (next-20190613), and with some fixes
in order for it to work.

- The 4 initial patches to fix some ABI descriptions that are violating 
  the syntax described at Documentation/ABI/README;

- The next 6 patches are the ones originally written in 2017 with a
  script with parses the ABI files;

- The 11th patch is a new one: it relaxes a little bit the parser in 
  order to parse file headers that contains colons on it;

- The 12th patch adds the new script to the documentation build
  system, together with a new python Sphinx extension with calls it;

- The 13th patch fixes the python script when running with newer
  Sphinx versions (1.7 and upper);

- The final patch fixes an UTF-8 trouble. I noticed it only with Sphinx
  1.4, but it could affect other versions too. So, I ended by changing
  the UTF-8 encoding logit to work version-independent, just like
  what happens with kerneldoc.py extension.

Mauro Carvalho Chehab (14):
  ABI: fix some syntax issues at the ABI database
  ABI: sysfs-driver-hid: the "What" field doesn't parse fine
  ABI: sysfs-class-uwb_rc: remove a duplicated incomplete entry
  ABI: better identificate tables
  scripts: add an script to parse the ABI files
  scripts/get_abi.pl: parse files with text at beginning
  scripts/get_abi.pl: avoid use literal blocks when not needed
  scripts/get_abi.pl: split label naming from xref logic
  scripts/get_abi.pl: add support for searching for ABI symbols
  scripts/get_abi.pl: represent what in tables
  scripts/get_abi.pl: fix parse issues with some files
  doc-rst: add ABI documentation to the admin-guide book
  sphinx/kernel_abi.py: make it compatible with Sphinx 1.7+
  docs: sphinx/kernel_abi.py: fix UTF-8 support

 .../ABI/obsolete/sysfs-driver-hid-roccat-pyra |   2 +-
 Documentation/ABI/testing/pstore              |   2 +-
 .../sysfs-bus-event_source-devices-format     |   2 +-
 .../ABI/testing/sysfs-bus-i2c-devices-hm6352  |   6 +-
 .../ABI/testing/sysfs-bus-iio-distance-srf08  |   4 +-
 .../testing/sysfs-bus-iio-proximity-as3935    |   4 +-
 .../ABI/testing/sysfs-bus-pci-devices-cciss   |  22 +-
 .../testing/sysfs-bus-usb-devices-usbsevseg   |  12 +-
 .../sysfs-class-backlight-driver-lm3533       |   6 +-
 Documentation/ABI/testing/sysfs-class-cxl     |   6 +-
 Documentation/ABI/testing/sysfs-class-devfreq |   2 +-
 .../ABI/testing/sysfs-class-led-driver-lm3533 |   8 +-
 .../ABI/testing/sysfs-class-leds-gt683r       |   4 +-
 .../ABI/testing/sysfs-class-powercap          |   2 +-
 Documentation/ABI/testing/sysfs-class-uwb_rc  |   6 -
 Documentation/ABI/testing/sysfs-driver-hid    |  12 +-
 .../ABI/testing/sysfs-driver-hid-roccat-kone  |   2 +-
 Documentation/ABI/testing/sysfs-kernel-fscaps |   2 +-
 .../ABI/testing/sysfs-kernel-vmcoreinfo       |   2 +-
 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           |   1 +
 Documentation/conf.py                         |   2 +-
 Documentation/sphinx/kernel_abi.py            | 172 +++++++
 scripts/get_abi.pl                            | 450 ++++++++++++++++++
 28 files changed, 731 insertions(+), 57 deletions(-)
 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/sphinx/kernel_abi.py
 create mode 100755 scripts/get_abi.pl

-- 
2.21.0

[PATCH 01/14] ABI: fix some syntax issues at the ABI database

[Mauro Carvalho Chehab]

From: Mauro Carvalho Chehab <mchehab@s-opensource.com>

On those three files, the ABI representation described at
README are violated.

- at sysfs-bus-iio-proximity-as3935:
	a ':' character is missing after "What"

- at sysfs-class-devfreq:
	there's a typo at Description

- at sysfs-class-cxl, it is using the ":" character at a
	file preamble, causing it to be misinterpreted as a
	tag.

- On the other files, instead of "What", they use "Where".

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/ABI/testing/pstore              |  2 +-
 .../sysfs-bus-event_source-devices-format     |  2 +-
 .../ABI/testing/sysfs-bus-i2c-devices-hm6352  |  6 ++---
 .../ABI/testing/sysfs-bus-iio-distance-srf08  |  4 ++--
 .../testing/sysfs-bus-iio-proximity-as3935    |  4 ++--
 .../ABI/testing/sysfs-bus-pci-devices-cciss   | 22 +++++++++----------
 .../testing/sysfs-bus-usb-devices-usbsevseg   | 12 +++++-----
 Documentation/ABI/testing/sysfs-class-cxl     |  6 ++---
 Documentation/ABI/testing/sysfs-class-devfreq |  2 +-
 .../ABI/testing/sysfs-class-powercap          |  2 +-
 Documentation/ABI/testing/sysfs-kernel-fscaps |  2 +-
 .../ABI/testing/sysfs-kernel-vmcoreinfo       |  2 +-
 12 files changed, 33 insertions(+), 33 deletions(-)

diff --git a/Documentation/ABI/testing/pstore b/Documentation/ABI/testing/pstore
index 5fca9f5e10a3..8d6e48f4e8ef 100644
--- a/Documentation/ABI/testing/pstore
+++ b/Documentation/ABI/testing/pstore
@@ -1,4 +1,4 @@
-Where:		/sys/fs/pstore/... (or /dev/pstore/...)
+What:		/sys/fs/pstore/... (or /dev/pstore/...)
 Date:		March 2011
 Kernel Version: 2.6.39
 Contact:	tony.luck@intel.com
diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
index 77f47ff5ee02..b6f8748e0200 100644
--- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
+++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
@@ -1,4 +1,4 @@
-Where:		/sys/bus/event_source/devices/<dev>/format
+What:		/sys/bus/event_source/devices/<dev>/format
 Date:		January 2012
 Kernel Version: 3.3
 Contact:	Jiri Olsa <jolsa@redhat.com>
diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352 b/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352
index feb2e4a87075..29bd447e50a0 100644
--- a/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352
+++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352
@@ -1,18 +1,18 @@
-Where:		/sys/bus/i2c/devices/.../heading0_input
+What:		/sys/bus/i2c/devices/.../heading0_input
 Date:		April 2010
 Kernel Version: 2.6.36?
 Contact:	alan.cox@intel.com
 Description:	Reports the current heading from the compass as a floating
 		point value in degrees.
 
-Where:		/sys/bus/i2c/devices/.../power_state
+What:		/sys/bus/i2c/devices/.../power_state
 Date:		April 2010
 Kernel Version: 2.6.36?
 Contact:	alan.cox@intel.com
 Description:	Sets the power state of the device. 0 sets the device into
 		sleep mode, 1 wakes it up.
 
-Where:		/sys/bus/i2c/devices/.../calibration
+What:		/sys/bus/i2c/devices/.../calibration
 Date:		April 2010
 Kernel Version: 2.6.36?
 Contact:	alan.cox@intel.com
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
index 0a1ca1487fa9..a133fd8d081a 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
+++ b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
@@ -1,4 +1,4 @@
-What		/sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
+What:		/sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
 Date:		January 2017
 KernelVersion:	4.11
 Contact:	linux-iio@vger.kernel.org
@@ -6,7 +6,7 @@ Description:
 		Show or set the gain boost of the amp, from 0-31 range.
 		default 31
 
-What		/sys/bus/iio/devices/iio:deviceX/sensor_max_range
+What:		/sys/bus/iio/devices/iio:deviceX/sensor_max_range
 Date:		January 2017
 KernelVersion:	4.11
 Contact:	linux-iio@vger.kernel.org
diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
index 9a17ab5036a4..c59d95346341 100644
--- a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
+++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
@@ -1,4 +1,4 @@
-What		/sys/bus/iio/devices/iio:deviceX/in_proximity_input
+What:		/sys/bus/iio/devices/iio:deviceX/in_proximity_input
 Date:		March 2014
 KernelVersion:	3.15
 Contact:	Matt Ranostay <matt.ranostay@konsulko.com>
@@ -6,7 +6,7 @@ Description:
 		Get the current distance in meters of storm (1km steps)
 		1000-40000 = distance in meters
 
-What		/sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
+What:		/sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
 Date:		March 2014
 KernelVersion:	3.15
 Contact:	Matt Ranostay <matt.ranostay@konsulko.com>
diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss b/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
index 53d99edd1d75..eb449169c30b 100644
--- a/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
+++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
@@ -1,66 +1,66 @@
-Where:		/sys/bus/pci/devices/<dev>/ccissX/cXdY/model
+What:		/sys/bus/pci/devices/<dev>/ccissX/cXdY/model
 Date:		March 2009
 Kernel Version: 2.6.30
 Contact:	iss_storagedev@hp.com
 Description:	Displays the SCSI INQUIRY page 0 model for logical drive
 		Y of controller X.
 
-Where:		/sys/bus/pci/devices/<dev>/ccissX/cXdY/rev
+What:		/sys/bus/pci/devices/<dev>/ccissX/cXdY/rev
 Date:		March 2009
 Kernel Version: 2.6.30
 Contact:	iss_storagedev@hp.com
 Description:	Displays the SCSI INQUIRY page 0 revision for logical
 		drive Y of controller X.
 
-Where:		/sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id
+What:		/sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id
 Date:		March 2009
 Kernel Version: 2.6.30
 Contact:	iss_storagedev@hp.com
 Description:	Displays the SCSI INQUIRY page 83 serial number for logical
 		drive Y of controller X.
 
-Where:		/sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor
+What:		/sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor
 Date:		March 2009
 Kernel Version: 2.6.30
 Contact:	iss_storagedev@hp.com
 Description:	Displays the SCSI INQUIRY page 0 vendor for logical drive
 		Y of controller X.
 
-Where:		/sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY
+What:		/sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY
 Date:		March 2009
 Kernel Version: 2.6.30
 Contact:	iss_storagedev@hp.com
 Description:	A symbolic link to /sys/block/cciss!cXdY
 
-Where:		/sys/bus/pci/devices/<dev>/ccissX/rescan
+What:		/sys/bus/pci/devices/<dev>/ccissX/rescan
 Date:		August 2009
 Kernel Version:	2.6.31
 Contact:	iss_storagedev@hp.com
 Description:	Kicks of a rescan of the controller to discover logical
 		drive topology changes.
 
-Where:		/sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid
+What:		/sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid
 Date:		August 2009
 Kernel Version: 2.6.31
 Contact:	iss_storagedev@hp.com
 Description:	Displays the 8-byte LUN ID used to address logical
 		drive Y of controller X.
 
-Where:		/sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level
+What:		/sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level
 Date:		August 2009
 Kernel Version: 2.6.31
 Contact:	iss_storagedev@hp.com
 Description:	Displays the RAID level of logical drive Y of
 		controller X.
 
-Where:		/sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count
+What:		/sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count
 Date:		August 2009
 Kernel Version: 2.6.31
 Contact:	iss_storagedev@hp.com
 Description:	Displays the usage count (number of opens) of logical drive Y
 		of controller X.
 
-Where:		/sys/bus/pci/devices/<dev>/ccissX/resettable
+What:		/sys/bus/pci/devices/<dev>/ccissX/resettable
 Date:		February 2011
 Kernel Version:	2.6.38
 Contact:	iss_storagedev@hp.com
@@ -71,7 +71,7 @@ Description:	Value of 1 indicates the controller can honor the reset_devices
 		a dump device, as kdump requires resetting the device in order
 		to work reliably.
 
-Where:		/sys/bus/pci/devices/<dev>/ccissX/transport_mode
+What:		/sys/bus/pci/devices/<dev>/ccissX/transport_mode
 Date:		July 2011
 Kernel Version:	3.0
 Contact:	iss_storagedev@hp.com
diff --git a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
index 70d00dfa443d..f6199b314196 100644
--- a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
+++ b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
@@ -1,12 +1,12 @@
-Where:		/sys/bus/usb/.../powered
+What:		/sys/bus/usb/.../powered
 Date:		August 2008
 Kernel Version:	2.6.26
 Contact:	Harrison Metzger <harrisonmetz@gmail.com>
 Description:	Controls whether the device's display will powered.
 		A value of 0 is off and a non-zero value is on.
 
-Where:		/sys/bus/usb/.../mode_msb
-Where:		/sys/bus/usb/.../mode_lsb
+What:		/sys/bus/usb/.../mode_msb
+What:		/sys/bus/usb/.../mode_lsb
 Date:		August 2008
 Kernel Version:	2.6.26
 Contact:	Harrison Metzger <harrisonmetz@gmail.com>
@@ -16,7 +16,7 @@ Description:	Controls the devices display mode.
 		for an 8 character display the values are
 			MSB 0x08; LSB 0xFF.
 
-Where:		/sys/bus/usb/.../textmode
+What:		/sys/bus/usb/.../textmode
 Date:		August 2008
 Kernel Version:	2.6.26
 Contact:	Harrison Metzger <harrisonmetz@gmail.com>
@@ -25,13 +25,13 @@ Description:	Controls the way the device interprets its text buffer.
 		hex:	each character is between 0-15
 		ascii:	each character is between '0'-'9' and 'A'-'F'.
 
-Where:		/sys/bus/usb/.../text
+What:		/sys/bus/usb/.../text
 Date:		August 2008
 Kernel Version:	2.6.26
 Contact:	Harrison Metzger <harrisonmetz@gmail.com>
 Description:	The text (or data) for the device to display
 
-Where:		/sys/bus/usb/.../decimals
+What:		/sys/bus/usb/.../decimals
 Date:		August 2008
 Kernel Version:	2.6.26
 Contact:	Harrison Metzger <harrisonmetz@gmail.com>
diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl
index bbbabffc682a..fc7c6f7c21b3 100644
--- a/Documentation/ABI/testing/sysfs-class-cxl
+++ b/Documentation/ABI/testing/sysfs-class-cxl
@@ -1,6 +1,6 @@
-Note: Attributes that are shared between devices are stored in the directory
-pointed to by the symlink device/.
-Example: The real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is
+Please notice that attributes that are shared between devices are stored in
+the directory pointed to by the symlink device/.
+For example, the real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is
 /sys/class/cxl/afu0.0s/device/irqs_max, i.e. /sys/class/cxl/afu0.0/irqs_max.
 
 
diff --git a/Documentation/ABI/testing/sysfs-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq
index ee39acacf6f8..01196e19afca 100644
--- a/Documentation/ABI/testing/sysfs-class-devfreq
+++ b/Documentation/ABI/testing/sysfs-class-devfreq
@@ -47,7 +47,7 @@ Description:
 What:		/sys/class/devfreq/.../trans_stat
 Date:		October 2012
 Contact:	MyungJoo Ham <myungjoo.ham@samsung.com>
-Descrtiption:
+Description:
 		This ABI shows the statistics of devfreq behavior on a
 		specific device. It shows the time spent in each state and
 		the number of transitions between states.
diff --git a/Documentation/ABI/testing/sysfs-class-powercap b/Documentation/ABI/testing/sysfs-class-powercap
index db3b3ff70d84..f333a0ccc29b 100644
--- a/Documentation/ABI/testing/sysfs-class-powercap
+++ b/Documentation/ABI/testing/sysfs-class-powercap
@@ -147,6 +147,6 @@ What:		/sys/class/powercap/.../<power zone>/enabled
 Date:		September 2013
 KernelVersion:	3.13
 Contact:	linux-pm@vger.kernel.org
-Description
+Description:
 		This allows to enable/disable power capping at power zone level.
 		This applies to current power zone and its children.
diff --git a/Documentation/ABI/testing/sysfs-kernel-fscaps b/Documentation/ABI/testing/sysfs-kernel-fscaps
index 50a3033b5e15..bcff34665192 100644
--- a/Documentation/ABI/testing/sysfs-kernel-fscaps
+++ b/Documentation/ABI/testing/sysfs-kernel-fscaps
@@ -2,7 +2,7 @@ What:		/sys/kernel/fscaps
 Date:		February 2011
 KernelVersion:	2.6.38
 Contact:	Ludwig Nussel <ludwig.nussel@suse.de>
-Description
+Description:
 		Shows whether file system capabilities are honored
 		when executing a binary
 
diff --git a/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo b/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo
index 7bd81168e063..1f1087a5f075 100644
--- a/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo
+++ b/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo
@@ -4,7 +4,7 @@ KernelVersion:	2.6.24
 Contact:	Ken'ichi Ohmichi <oomichi@mxs.nes.nec.co.jp>
 		Kexec Mailing List <kexec@lists.infradead.org>
 		Vivek Goyal <vgoyal@redhat.com>
-Description
+Description:
 		Shows physical address and size of vmcoreinfo ELF note.
 		First value contains physical address of note in hex and
 		second value contains the size of note in hex. This ELF
-- 
2.21.0

Re: [PATCH 01/14] ABI: fix some syntax issues at the ABI database

[Andrew Donnellan]

On 14/6/19 12:04 pm, Mauro Carvalho Chehab wrote:
> diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl
> index bbbabffc682a..fc7c6f7c21b3 100644
> --- a/Documentation/ABI/testing/sysfs-class-cxl
> +++ b/Documentation/ABI/testing/sysfs-class-cxl
> @@ -1,6 +1,6 @@
> -Note: Attributes that are shared between devices are stored in the directory
> -pointed to by the symlink device/.
> -Example: The real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is
> +Please notice that attributes that are shared between devices are stored in

Would prefer "Please note" over "Please notice".

Acked-by: Andrew Donnellan <ajd@linux.ibm.com>  # cxl


-- 
Andrew Donnellan              OzLabs, ADL Canberra
ajd@linux.ibm.com             IBM Australia Limited

Re: [PATCH 01/14] ABI: fix some syntax issues at the ABI database

[Rafael J. Wysocki]

On Fri, Jun 14, 2019 at 4:04 AM Mauro Carvalho Chehab
<mchehab+samsung@kernel.org> wrote:
>
> From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
>
> On those three files, the ABI representation described at
> README are violated.
>
> - at sysfs-bus-iio-proximity-as3935:
>         a ':' character is missing after "What"
>
> - at sysfs-class-devfreq:
>         there's a typo at Description
>
> - at sysfs-class-cxl, it is using the ":" character at a
>         file preamble, causing it to be misinterpreted as a
>         tag.
>
> - On the other files, instead of "What", they use "Where".
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>

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

> ---
>  Documentation/ABI/testing/pstore              |  2 +-
>  .../sysfs-bus-event_source-devices-format     |  2 +-
>  .../ABI/testing/sysfs-bus-i2c-devices-hm6352  |  6 ++---
>  .../ABI/testing/sysfs-bus-iio-distance-srf08  |  4 ++--
>  .../testing/sysfs-bus-iio-proximity-as3935    |  4 ++--
>  .../ABI/testing/sysfs-bus-pci-devices-cciss   | 22 +++++++++----------
>  .../testing/sysfs-bus-usb-devices-usbsevseg   | 12 +++++-----
>  Documentation/ABI/testing/sysfs-class-cxl     |  6 ++---
>  Documentation/ABI/testing/sysfs-class-devfreq |  2 +-
>  .../ABI/testing/sysfs-class-powercap          |  2 +-
>  Documentation/ABI/testing/sysfs-kernel-fscaps |  2 +-
>  .../ABI/testing/sysfs-kernel-vmcoreinfo       |  2 +-
>  12 files changed, 33 insertions(+), 33 deletions(-)
>
> diff --git a/Documentation/ABI/testing/pstore b/Documentation/ABI/testing/pstore
> index 5fca9f5e10a3..8d6e48f4e8ef 100644
> --- a/Documentation/ABI/testing/pstore
> +++ b/Documentation/ABI/testing/pstore
> @@ -1,4 +1,4 @@
> -Where:         /sys/fs/pstore/... (or /dev/pstore/...)
> +What:          /sys/fs/pstore/... (or /dev/pstore/...)
>  Date:          March 2011
>  Kernel Version: 2.6.39
>  Contact:       tony.luck@intel.com
> diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
> index 77f47ff5ee02..b6f8748e0200 100644
> --- a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
> +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format
> @@ -1,4 +1,4 @@
> -Where:         /sys/bus/event_source/devices/<dev>/format
> +What:          /sys/bus/event_source/devices/<dev>/format
>  Date:          January 2012
>  Kernel Version: 3.3
>  Contact:       Jiri Olsa <jolsa@redhat.com>
> diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352 b/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352
> index feb2e4a87075..29bd447e50a0 100644
> --- a/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352
> +++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352
> @@ -1,18 +1,18 @@
> -Where:         /sys/bus/i2c/devices/.../heading0_input
> +What:          /sys/bus/i2c/devices/.../heading0_input
>  Date:          April 2010
>  Kernel Version: 2.6.36?
>  Contact:       alan.cox@intel.com
>  Description:   Reports the current heading from the compass as a floating
>                 point value in degrees.
>
> -Where:         /sys/bus/i2c/devices/.../power_state
> +What:          /sys/bus/i2c/devices/.../power_state
>  Date:          April 2010
>  Kernel Version: 2.6.36?
>  Contact:       alan.cox@intel.com
>  Description:   Sets the power state of the device. 0 sets the device into
>                 sleep mode, 1 wakes it up.
>
> -Where:         /sys/bus/i2c/devices/.../calibration
> +What:          /sys/bus/i2c/devices/.../calibration
>  Date:          April 2010
>  Kernel Version: 2.6.36?
>  Contact:       alan.cox@intel.com
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08 b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
> index 0a1ca1487fa9..a133fd8d081a 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
> @@ -1,4 +1,4 @@
> -What           /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
> +What:          /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
>  Date:          January 2017
>  KernelVersion: 4.11
>  Contact:       linux-iio@vger.kernel.org
> @@ -6,7 +6,7 @@ Description:
>                 Show or set the gain boost of the amp, from 0-31 range.
>                 default 31
>
> -What           /sys/bus/iio/devices/iio:deviceX/sensor_max_range
> +What:          /sys/bus/iio/devices/iio:deviceX/sensor_max_range
>  Date:          January 2017
>  KernelVersion: 4.11
>  Contact:       linux-iio@vger.kernel.org
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
> index 9a17ab5036a4..c59d95346341 100644
> --- a/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935
> @@ -1,4 +1,4 @@
> -What           /sys/bus/iio/devices/iio:deviceX/in_proximity_input
> +What:          /sys/bus/iio/devices/iio:deviceX/in_proximity_input
>  Date:          March 2014
>  KernelVersion: 3.15
>  Contact:       Matt Ranostay <matt.ranostay@konsulko.com>
> @@ -6,7 +6,7 @@ Description:
>                 Get the current distance in meters of storm (1km steps)
>                 1000-40000 = distance in meters
>
> -What           /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
> +What:          /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
>  Date:          March 2014
>  KernelVersion: 3.15
>  Contact:       Matt Ranostay <matt.ranostay@konsulko.com>
> diff --git a/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss b/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
> index 53d99edd1d75..eb449169c30b 100644
> --- a/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
> +++ b/Documentation/ABI/testing/sysfs-bus-pci-devices-cciss
> @@ -1,66 +1,66 @@
> -Where:         /sys/bus/pci/devices/<dev>/ccissX/cXdY/model
> +What:          /sys/bus/pci/devices/<dev>/ccissX/cXdY/model
>  Date:          March 2009
>  Kernel Version: 2.6.30
>  Contact:       iss_storagedev@hp.com
>  Description:   Displays the SCSI INQUIRY page 0 model for logical drive
>                 Y of controller X.
>
> -Where:         /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev
> +What:          /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev
>  Date:          March 2009
>  Kernel Version: 2.6.30
>  Contact:       iss_storagedev@hp.com
>  Description:   Displays the SCSI INQUIRY page 0 revision for logical
>                 drive Y of controller X.
>
> -Where:         /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id
> +What:          /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id
>  Date:          March 2009
>  Kernel Version: 2.6.30
>  Contact:       iss_storagedev@hp.com
>  Description:   Displays the SCSI INQUIRY page 83 serial number for logical
>                 drive Y of controller X.
>
> -Where:         /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor
> +What:          /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor
>  Date:          March 2009
>  Kernel Version: 2.6.30
>  Contact:       iss_storagedev@hp.com
>  Description:   Displays the SCSI INQUIRY page 0 vendor for logical drive
>                 Y of controller X.
>
> -Where:         /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY
> +What:          /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY
>  Date:          March 2009
>  Kernel Version: 2.6.30
>  Contact:       iss_storagedev@hp.com
>  Description:   A symbolic link to /sys/block/cciss!cXdY
>
> -Where:         /sys/bus/pci/devices/<dev>/ccissX/rescan
> +What:          /sys/bus/pci/devices/<dev>/ccissX/rescan
>  Date:          August 2009
>  Kernel Version:        2.6.31
>  Contact:       iss_storagedev@hp.com
>  Description:   Kicks of a rescan of the controller to discover logical
>                 drive topology changes.
>
> -Where:         /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid
> +What:          /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid
>  Date:          August 2009
>  Kernel Version: 2.6.31
>  Contact:       iss_storagedev@hp.com
>  Description:   Displays the 8-byte LUN ID used to address logical
>                 drive Y of controller X.
>
> -Where:         /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level
> +What:          /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level
>  Date:          August 2009
>  Kernel Version: 2.6.31
>  Contact:       iss_storagedev@hp.com
>  Description:   Displays the RAID level of logical drive Y of
>                 controller X.
>
> -Where:         /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count
> +What:          /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count
>  Date:          August 2009
>  Kernel Version: 2.6.31
>  Contact:       iss_storagedev@hp.com
>  Description:   Displays the usage count (number of opens) of logical drive Y
>                 of controller X.
>
> -Where:         /sys/bus/pci/devices/<dev>/ccissX/resettable
> +What:          /sys/bus/pci/devices/<dev>/ccissX/resettable
>  Date:          February 2011
>  Kernel Version:        2.6.38
>  Contact:       iss_storagedev@hp.com
> @@ -71,7 +71,7 @@ Description:  Value of 1 indicates the controller can honor the reset_devices
>                 a dump device, as kdump requires resetting the device in order
>                 to work reliably.
>
> -Where:         /sys/bus/pci/devices/<dev>/ccissX/transport_mode
> +What:          /sys/bus/pci/devices/<dev>/ccissX/transport_mode
>  Date:          July 2011
>  Kernel Version:        3.0
>  Contact:       iss_storagedev@hp.com
> diff --git a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
> index 70d00dfa443d..f6199b314196 100644
> --- a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
> +++ b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg
> @@ -1,12 +1,12 @@
> -Where:         /sys/bus/usb/.../powered
> +What:          /sys/bus/usb/.../powered
>  Date:          August 2008
>  Kernel Version:        2.6.26
>  Contact:       Harrison Metzger <harrisonmetz@gmail.com>
>  Description:   Controls whether the device's display will powered.
>                 A value of 0 is off and a non-zero value is on.
>
> -Where:         /sys/bus/usb/.../mode_msb
> -Where:         /sys/bus/usb/.../mode_lsb
> +What:          /sys/bus/usb/.../mode_msb
> +What:          /sys/bus/usb/.../mode_lsb
>  Date:          August 2008
>  Kernel Version:        2.6.26
>  Contact:       Harrison Metzger <harrisonmetz@gmail.com>
> @@ -16,7 +16,7 @@ Description:  Controls the devices display mode.
>                 for an 8 character display the values are
>                         MSB 0x08; LSB 0xFF.
>
> -Where:         /sys/bus/usb/.../textmode
> +What:          /sys/bus/usb/.../textmode
>  Date:          August 2008
>  Kernel Version:        2.6.26
>  Contact:       Harrison Metzger <harrisonmetz@gmail.com>
> @@ -25,13 +25,13 @@ Description:        Controls the way the device interprets its text buffer.
>                 hex:    each character is between 0-15
>                 ascii:  each character is between '0'-'9' and 'A'-'F'.
>
> -Where:         /sys/bus/usb/.../text
> +What:          /sys/bus/usb/.../text
>  Date:          August 2008
>  Kernel Version:        2.6.26
>  Contact:       Harrison Metzger <harrisonmetz@gmail.com>
>  Description:   The text (or data) for the device to display
>
> -Where:         /sys/bus/usb/.../decimals
> +What:          /sys/bus/usb/.../decimals
>  Date:          August 2008
>  Kernel Version:        2.6.26
>  Contact:       Harrison Metzger <harrisonmetz@gmail.com>
> diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl
> index bbbabffc682a..fc7c6f7c21b3 100644
> --- a/Documentation/ABI/testing/sysfs-class-cxl
> +++ b/Documentation/ABI/testing/sysfs-class-cxl
> @@ -1,6 +1,6 @@
> -Note: Attributes that are shared between devices are stored in the directory
> -pointed to by the symlink device/.
> -Example: The real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is
> +Please notice that attributes that are shared between devices are stored in
> +the directory pointed to by the symlink device/.
> +For example, the real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is
>  /sys/class/cxl/afu0.0s/device/irqs_max, i.e. /sys/class/cxl/afu0.0/irqs_max.
>
>
> diff --git a/Documentation/ABI/testing/sysfs-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq
> index ee39acacf6f8..01196e19afca 100644
> --- a/Documentation/ABI/testing/sysfs-class-devfreq
> +++ b/Documentation/ABI/testing/sysfs-class-devfreq
> @@ -47,7 +47,7 @@ Description:
>  What:          /sys/class/devfreq/.../trans_stat
>  Date:          October 2012
>  Contact:       MyungJoo Ham <myungjoo.ham@samsung.com>
> -Descrtiption:
> +Description:
>                 This ABI shows the statistics of devfreq behavior on a
>                 specific device. It shows the time spent in each state and
>                 the number of transitions between states.
> diff --git a/Documentation/ABI/testing/sysfs-class-powercap b/Documentation/ABI/testing/sysfs-class-powercap
> index db3b3ff70d84..f333a0ccc29b 100644
> --- a/Documentation/ABI/testing/sysfs-class-powercap
> +++ b/Documentation/ABI/testing/sysfs-class-powercap
> @@ -147,6 +147,6 @@ What:               /sys/class/powercap/.../<power zone>/enabled
>  Date:          September 2013
>  KernelVersion: 3.13
>  Contact:       linux-pm@vger.kernel.org
> -Description
> +Description:
>                 This allows to enable/disable power capping at power zone level.
>                 This applies to current power zone and its children.
> diff --git a/Documentation/ABI/testing/sysfs-kernel-fscaps b/Documentation/ABI/testing/sysfs-kernel-fscaps
> index 50a3033b5e15..bcff34665192 100644
> --- a/Documentation/ABI/testing/sysfs-kernel-fscaps
> +++ b/Documentation/ABI/testing/sysfs-kernel-fscaps
> @@ -2,7 +2,7 @@ What:           /sys/kernel/fscaps
>  Date:          February 2011
>  KernelVersion: 2.6.38
>  Contact:       Ludwig Nussel <ludwig.nussel@suse.de>
> -Description
> +Description:
>                 Shows whether file system capabilities are honored
>                 when executing a binary
>
> diff --git a/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo b/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo
> index 7bd81168e063..1f1087a5f075 100644
> --- a/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo
> +++ b/Documentation/ABI/testing/sysfs-kernel-vmcoreinfo
> @@ -4,7 +4,7 @@ KernelVersion:  2.6.24
>  Contact:       Ken'ichi Ohmichi <oomichi@mxs.nes.nec.co.jp>
>                 Kexec Mailing List <kexec@lists.infradead.org>
>                 Vivek Goyal <vgoyal@redhat.com>
> -Description
> +Description:
>                 Shows physical address and size of vmcoreinfo ELF note.
>                 First value contains physical address of note in hex and
>                 second value contains the size of note in hex. This ELF
> --
> 2.21.0
>

Re: [PATCH 01/14] ABI: fix some syntax issues at the ABI database

[Greg Kroah-Hartman]

On Fri, Jun 14, 2019 at 05:20:29PM +1000, Andrew Donnellan wrote:
> On 14/6/19 12:04 pm, Mauro Carvalho Chehab wrote:
> > diff --git a/Documentation/ABI/testing/sysfs-class-cxl b/Documentation/ABI/testing/sysfs-class-cxl
> > index bbbabffc682a..fc7c6f7c21b3 100644
> > --- a/Documentation/ABI/testing/sysfs-class-cxl
> > +++ b/Documentation/ABI/testing/sysfs-class-cxl
> > @@ -1,6 +1,6 @@
> > -Note: Attributes that are shared between devices are stored in the directory
> > -pointed to by the symlink device/.
> > -Example: The real path of the attribute /sys/class/cxl/afu0.0s/irqs_max is
> > +Please notice that attributes that are shared between devices are stored in
> 
> Would prefer "Please note" over "Please notice".

Now changed, but that's a minor grammer thing, both are correct. :)

> Acked-by: Andrew Donnellan <ajd@linux.ibm.com>  # cxl

thanks,

greg k-h

Re: [PATCH 00/14] Add support to generate ABI documentation at admin-guide

[Greg Kroah-Hartman]

On Thu, Jun 13, 2019 at 11:04:06PM -0300, Mauro Carvalho Chehab wrote:
> Greg,
> 
> As promised, I'm resending the patch series with adds the Kernel ABI to
> Documentation/admin-guide.
> 
> Those patches are basically the version 3 patchset I sent back in 2017,
> rebased on the top of linux-next (next-20190613), and with some fixes
> in order for it to work.
> 
> - The 4 initial patches to fix some ABI descriptions that are violating 
>   the syntax described at Documentation/ABI/README;

These 4 are now applied to my driver-core tree, thanks.

greg k-h