* [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: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet, linuxppc-dev, Andrew Donnellan, Jonathan Cameron, Lars-Peter Clausen, Anton Vorontsov, linux-pm, Colin Cross, linux-iio, Hartmut Knaack, Sebastian Reichel, Frederic Barrat, Andreas Klinger, Tony Luck, Peter Meerwald-Stadler, Stefan Achatz, Kees Cook 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: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet, Andreas Klinger, Jonathan Cameron, Hartmut Knaack, Lars-Peter Clausen, Peter Meerwald-Stadler, Frederic Barrat, Andrew Donnellan, Sebastian Reichel, Kees Cook, Anton Vorontsov, Colin Cross, Tony Luck, linux-iio, linuxppc-dev, linux-pm, 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 ^ 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: Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet, Andreas Klinger, Jonathan Cameron, Hartmut Knaack, Lars-Peter Clausen, Peter Meerwald-Stadler, Frederic Barrat, Sebastian Reichel, Kees Cook, Anton Vorontsov, Colin Cross, Tony Luck, linux-iio, linuxppc-dev, linux-pm 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 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: Mauro Carvalho Chehab, Linux Doc Mailing List, Mauro Carvalho Chehab, Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet, Andreas Klinger, Jonathan Cameron, Hartmut Knaack, Lars-Peter Clausen, Peter Meerwald-Stadler, Frederic Barrat, Sebastian Reichel, Kees Cook, Anton Vorontsov, Colin Cross, Tony Luck, linux-iio, linuxppc-dev, linux-pm 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 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: Linux Doc Mailing List, Greg Kroah-Hartman, Mauro Carvalho Chehab, Mauro Carvalho Chehab, Linux Kernel Mailing List, Jonathan Corbet, Andreas Klinger, Jonathan Cameron, Hartmut Knaack, Lars-Peter Clausen, Peter Meerwald-Stadler, Frederic Barrat, Andrew Donnellan, Sebastian Reichel, Kees Cook, Anton Vorontsov, Colin Cross, Tony Luck, linux-iio, linuxppc-dev, Linux PM 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 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: Linux Doc Mailing List, Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet, linuxppc-dev, Andrew Donnellan, Jonathan Cameron, Lars-Peter Clausen, Anton Vorontsov, linux-pm, Colin Cross, linux-iio, Hartmut Knaack, Sebastian Reichel, Frederic Barrat, Andreas Klinger, Tony Luck, Peter Meerwald-Stadler, Stefan Achatz, Kees Cook 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:20 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).