* [PATCH 00/14] Add support to generate ABI documentation at admin-guide
@ 2019-06-14 2:04 Mauro Carvalho Chehab
2019-06-14 2:04 ` [PATCH 01/14] ABI: fix some syntax issues at the ABI database Mauro Carvalho Chehab
2019-06-14 16:20 ` [PATCH 00/14] Add support to generate ABI documentation at admin-guide Greg Kroah-Hartman
0 siblings, 2 replies; 6+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Lars-Peter Clausen, Andrew Donnellan, Kees Cook, Jonathan Corbet,
linux-iio, linux-pm, Anton Vorontsov, linux-kernel,
Andreas Klinger, Mauro Carvalho Chehab, Frederic Barrat,
Tony Luck, Sebastian Reichel, Peter Meerwald-Stadler,
Colin Cross, Mauro Carvalho Chehab, linuxppc-dev, Stefan Achatz,
Jonathan Cameron, Hartmut Knaack
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH 01/14] ABI: fix some syntax issues at the ABI database
2019-06-14 2:04 [PATCH 00/14] Add support to generate ABI documentation at admin-guide Mauro Carvalho Chehab
@ 2019-06-14 2:04 ` Mauro Carvalho Chehab
2019-06-14 7:20 ` Andrew Donnellan
2019-06-14 8:30 ` Rafael J. Wysocki
2019-06-14 16:20 ` [PATCH 00/14] Add support to generate ABI documentation at admin-guide Greg Kroah-Hartman
1 sibling, 2 replies; 6+ messages in thread
From: Mauro Carvalho Chehab @ 2019-06-14 2:04 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Tony Luck, Lars-Peter Clausen, Andrew Donnellan, Jonathan Corbet,
linux-iio, Sebastian Reichel, Anton Vorontsov, linux-kernel,
Mauro Carvalho Chehab, Mauro Carvalho Chehab,
Mauro Carvalho Chehab, Colin Cross, linux-pm, Andreas Klinger,
Peter Meerwald-Stadler, Hartmut Knaack, Frederic Barrat,
linuxppc-dev, Jonathan Cameron, Kees Cook
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
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH 01/14] ABI: fix some syntax issues at the ABI database
2019-06-14 2:04 ` [PATCH 01/14] ABI: fix some syntax issues at the ABI database Mauro Carvalho Chehab
@ 2019-06-14 7:20 ` Andrew Donnellan
2019-06-14 16:16 ` Greg Kroah-Hartman
2019-06-14 8:30 ` Rafael J. Wysocki
1 sibling, 1 reply; 6+ messages in thread
From: Andrew Donnellan @ 2019-06-14 7:20 UTC (permalink / raw)
To: Mauro Carvalho Chehab, Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Tony Luck, Lars-Peter Clausen, Kees Cook, Jonathan Corbet,
linux-iio, Sebastian Reichel, Anton Vorontsov, linux-kernel,
Mauro Carvalho Chehab, Mauro Carvalho Chehab, Colin Cross,
linux-pm, Andreas Klinger, Peter Meerwald-Stadler,
Hartmut Knaack, Frederic Barrat, linuxppc-dev, Jonathan Cameron
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 01/14] ABI: fix some syntax issues at the ABI database
2019-06-14 2:04 ` [PATCH 01/14] ABI: fix some syntax issues at the ABI database Mauro Carvalho Chehab
2019-06-14 7:20 ` Andrew Donnellan
@ 2019-06-14 8:30 ` Rafael J. Wysocki
1 sibling, 0 replies; 6+ messages in thread
From: Rafael J. Wysocki @ 2019-06-14 8:30 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Tony Luck, Lars-Peter Clausen, Andrew Donnellan, Jonathan Corbet,
linux-iio, Greg Kroah-Hartman, Sebastian Reichel,
Linux Doc Mailing List, Linux Kernel Mailing List,
Mauro Carvalho Chehab, Mauro Carvalho Chehab, Colin Cross,
Linux PM, Andreas Klinger, Peter Meerwald-Stadler,
Hartmut Knaack, Frederic Barrat, linuxppc-dev, Anton Vorontsov,
Jonathan Cameron, Kees Cook
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
>
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 01/14] ABI: fix some syntax issues at the ABI database
2019-06-14 7:20 ` Andrew Donnellan
@ 2019-06-14 16:16 ` Greg Kroah-Hartman
0 siblings, 0 replies; 6+ messages in thread
From: Greg Kroah-Hartman @ 2019-06-14 16:16 UTC (permalink / raw)
To: Andrew Donnellan
Cc: Tony Luck, Lars-Peter Clausen, Kees Cook, Jonathan Corbet,
linux-iio, Sebastian Reichel, Linux Doc Mailing List,
linux-kernel, Mauro Carvalho Chehab, Mauro Carvalho Chehab,
Frederic Barrat, Colin Cross, linux-pm, Andreas Klinger,
Peter Meerwald-Stadler, Hartmut Knaack, Mauro Carvalho Chehab,
linuxppc-dev, Anton Vorontsov, Jonathan Cameron
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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 00/14] Add support to generate ABI documentation at admin-guide
2019-06-14 2:04 [PATCH 00/14] Add support to generate ABI documentation at admin-guide Mauro Carvalho Chehab
2019-06-14 2:04 ` [PATCH 01/14] ABI: fix some syntax issues at the ABI database Mauro Carvalho Chehab
@ 2019-06-14 16:20 ` Greg Kroah-Hartman
1 sibling, 0 replies; 6+ messages in thread
From: Greg Kroah-Hartman @ 2019-06-14 16:20 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Sebastian Reichel, Lars-Peter Clausen, Andrew Donnellan,
Kees Cook, Jonathan Corbet, linux-iio, linux-pm,
Linux Doc Mailing List, linux-kernel, Andreas Klinger,
Mauro Carvalho Chehab, Tony Luck, Anton Vorontsov,
Peter Meerwald-Stadler, Colin Cross, Frederic Barrat,
linuxppc-dev, Stefan Achatz, Jonathan Cameron, Hartmut Knaack
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
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2019-06-14 16:22 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-06-14 2:04 [PATCH 00/14] Add support to generate ABI documentation at admin-guide Mauro Carvalho Chehab
2019-06-14 2:04 ` [PATCH 01/14] ABI: fix some syntax issues at the ABI database Mauro Carvalho Chehab
2019-06-14 7:20 ` Andrew Donnellan
2019-06-14 16:16 ` Greg Kroah-Hartman
2019-06-14 8:30 ` Rafael J. Wysocki
2019-06-14 16:20 ` [PATCH 00/14] Add support to generate ABI documentation at admin-guide Greg Kroah-Hartman
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).