Add ABI and features docs to the Kernel documentation
Subsystems (3)
v2 cover Add ABI and features docs to the Kernel documentation
This is a rebased version of the scripts with parse Documentation/ABI and Documentation/feature files and produce a ReST output. Those scripts are added to the Kernel building system, in order to output their contents inside the Kernel documentation.
Please notice that, as discussed, I added support at get_abi.pl to handle ABI files as if they're compatible with ReST. Right now, this feature can't be enabled for normal builds, as it will cause Sphinx crashes. After getting the offending ABI files fixed, a single line change will be enough to make it default.
a version "0" was sent back on 2017.
v1:
- rebased version of ABI scripts requested during KS/2019 discussions,
with some additional changes for it to parse newer ABI files;
v2:
- Some additional fixes and improvements to get_abi.pl script;
- get_abi.pl script now optionally suports parsing ABI files with
uses ReST format (by default, this is disabled);
- Added scripts/get_feat.pl to parse Documentation/features;
- Added SPDX headers.
Mauro Carvalho Chehab (22):
ABI: sysfs-bus-pci-devices-aer_stats uses an invalid tag
ABI: Fix KernelVersion tags
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 scripts/get_abi.pl: avoid creating duplicate names scripts/get_abi.pl: add a handler for invalid "where" tag scripts/get_abi.pl: add a validate command
doc-rst: add ABI documentation to the admin-guide book
docs: sphinx/kernel_abi.py: fix UTF-8 support sphinx/kernel_abi.py: make it compatible with Sphinx 1.7+
docs: Kconfig/Makefile: add a check for broken ABI files
docs: kernel_abi.py: Update copyrights
doc: ABI scripts: add a SPDX header file
scripts: add a script to handle Documentation/features
docs: admin-guide, x86: add a features list scripts/get_feat.pl: handle ".." special case scripts/get_abi.pl: change script to allow parsing in ReST mode
Documentation/ABI/testing/pstore | 2 +- .../sysfs-bus-event_source-devices-format | 2 +- .../ABI/testing/sysfs-bus-i2c-devices-hm6352 | 6 +- .../testing/sysfs-bus-pci-devices-aer_stats | 24 +- .../ABI/testing/sysfs-bus-pci-devices-cciss | 22 +- .../testing/sysfs-bus-usb-devices-usbsevseg | 10 +- .../ABI/testing/sysfs-driver-altera-cvp | 2 +- Documentation/ABI/testing/sysfs-driver-ppi | 2 +- Documentation/ABI/testing/sysfs-driver-st | 2 +- Documentation/ABI/testing/sysfs-driver-wacom | 2 +- Documentation/Kconfig | 11 + Documentation/Makefile | 5 + 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/features.rst | 3 + Documentation/admin-guide/index.rst | 2 + Documentation/conf.py | 2 +- Documentation/sphinx/kernel_abi.py | 166 ++++++ Documentation/sphinx/kernel_feat.py | 169 ++++++ Documentation/x86/features.rst | 3 + Documentation/x86/index.rst | 1 + lib/Kconfig.debug | 2 + scripts/get_abi.pl | 498 ++++++++++++++++++ scripts/get_feat.pl | 474 +++++++++++++++++ 27 files changed, 1429 insertions(+), 38 deletions(-) create mode 100644 Documentation/Kconfig 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/admin-guide/features.rst create mode 100644 Documentation/sphinx/kernel_abi.py create mode 100644 Documentation/sphinx/kernel_feat.py create mode 100644 Documentation/x86/features.rst create mode 100755 scripts/get_abi.pl create mode 100755 scripts/get_feat.pl
Signature · 1 line
2.21.0
PATCH v2 1/22 ABI: sysfs-bus-pci-devices-aer_stats uses an invalid tag
According with Documentation/ABI/, the right tag to describe an ABI symbol is "What:", and not "Where:".
--- .../ABI/testing/sysfs-bus-pci-devices-aer_stats | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)
Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats +6 -6
@@ -9,7 +9,7 @@ errors may be "seen" / reported by the link partner and not the problematic endpoint itself (which may report all counters as 0 as it never saw any problems). -Where: /sys/bus/pci/devices/<dev>/aer_dev_correctable +What: /sys/bus/pci/devices/<dev>/aer_dev_correctable Date: July 2018 Kernel Version: 4.19.0 Contact: [email protected], [email protected]
@@ -31,7 +31,7 @@ Header Log Overflow 0 TOTAL_ERR_COR 2 ------------------------------------------------------------------------- -Where: /sys/bus/pci/devices/<dev>/aer_dev_fatal +What: /sys/bus/pci/devices/<dev>/aer_dev_fatal Date: July 2018 Kernel Version: 4.19.0 Contact: [email protected], [email protected]
@@ -62,7 +62,7 @@ TLP Prefix Blocked Error 0 TOTAL_ERR_FATAL 0 ------------------------------------------------------------------------- -Where: /sys/bus/pci/devices/<dev>/aer_dev_nonfatal +What: /sys/bus/pci/devices/<dev>/aer_dev_nonfatal Date: July 2018 Kernel Version: 4.19.0 Contact: [email protected], [email protected]
@@ -103,19 +103,19 @@ collectors) that are AER capable. These indicate the number of error messages as device, so these counters include them and are thus cumulative of all the error messages on the PCI hierarchy originating at that root port. -Where: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor +What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor Date: July 2018 Kernel Version: 4.19.0 Contact: [email protected], [email protected] Description: Total number of ERR_COR messages reported to rootport. -Where: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal +What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal Date: July 2018 Kernel Version: 4.19.0 Contact: [email protected], [email protected] Description: Total number of ERR_FATAL messages reported to rootport. -Where: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_nonfatal +What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_nonfatal Date: July 2018 Kernel Version: 4.19.0 Contact: [email protected], [email protected]
Signature · 1 line
2.21.0
Re: [PATCH v2 01/22] ABI: sysfs-bus-pci-devices-aer_stats uses an invalid tag
Quoted 5 lines · Mauro Carvalho Chehab
According with
Documentation/ABI/, the right tag to describe an ABI symbol is "What:", and not "Where:".Signed-off-by Mauro Carvalho Chehab <[email protected]>
I assume somebody else will merge this series as a whole.
Quoted 61 lines
--- .../ABI/testing/sysfs-bus-pci-devices-aer_stats | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats +6
-7@@ -9,7 +9,7 @@ errors may be "seen" / reported by the link partner and not the problematic endpoint itself (which may report all counters as 0 as it never saw any problems). -Where: /sys/bus/pci/devices/<dev>/aer_dev_correctable +What: /sys/bus/pci/devices/<dev>/aer_dev_correctable Date: July 2018 Kernel Version: 4.19.0 Contact: [email protected], [email protected]@@ -31,7 +31,7 @@ Header Log Overflow 0 TOTAL_ERR_COR 2 ------------------------------------------------------------------------- -Where: /sys/bus/pci/devices/<dev>/aer_dev_fatal +What: /sys/bus/pci/devices/<dev>/aer_dev_fatal Date: July 2018 Kernel Version: 4.19.0 Contact: [email protected], [email protected]@@ -62,7 +62,7 @@ TLP Prefix Blocked Error 0 TOTAL_ERR_FATAL 0 ------------------------------------------------------------------------- -Where: /sys/bus/pci/devices/<dev>/aer_dev_nonfatal +What: /sys/bus/pci/devices/<dev>/aer_dev_nonfatal Date: July 2018 Kernel Version: 4.19.0 Contact: [email protected], [email protected]@@ -103,19 +103,19 @@ collectors) that are AER capable. These indicate the number of error messages as device, so these counters include them and are thus cumulative of all the error messages on the PCI hierarchy originating at that root port. -Where: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor +What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor Date: July 2018 Kernel Version: 4.19.0 Contact: [email protected], [email protected] Description: Total number of ERR_COR messages reported to rootport. -Where: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal +What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal Date: July 2018 Kernel Version: 4.19.0 Contact: [email protected], [email protected] Description: Total number of ERR_FATAL messages reported to rootport. -Where: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_nonfatal +What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_nonfatal Date: July 2018 Kernel Version: 4.19.0 Contact: [email protected], [email protected] --2.21.0
PATCH v2 2/22 ABI: Fix KernelVersion tags
In reply to Mauro Carvalho ChehabIt is "KernelVersion:" and not "Kernel Version:".
--- Documentation/ABI/testing/pstore | 2 +- .../sysfs-bus-event_source-devices-format | 2 +- .../ABI/testing/sysfs-bus-i2c-devices-hm6352 | 6 ++--- .../testing/sysfs-bus-pci-devices-aer_stats | 12 +++++----- .../ABI/testing/sysfs-bus-pci-devices-cciss | 22 +++++++++---------- .../testing/sysfs-bus-usb-devices-usbsevseg | 10 ++++----- .../ABI/testing/sysfs-driver-altera-cvp | 2 +- Documentation/ABI/testing/sysfs-driver-ppi | 2 +- Documentation/ABI/testing/sysfs-driver-st | 2 +- Documentation/ABI/testing/sysfs-driver-wacom | 2 +- 10 files changed, 31 insertions(+), 31 deletions(-)
Documentation/ABI/testing/pstore +1 -1
@@ -1,6 +1,6 @@ What: /sys/fs/pstore/... (or /dev/pstore/...) Date: March 2011 -Kernel Version: 2.6.39 +KernelVersion: 2.6.39 Contact: [email protected] Description: Generic interface to platform dependent persistent storage.
Documentation/ABI/testing/sysfs-bus-event_source-devices-format +1 -1
@@ -1,6 +1,6 @@ What: /sys/bus/event_source/devices/<dev>/format Date: January 2012 -Kernel Version: 3.3 +KernelVersion: 3.3 Contact: Jiri Olsa <[email protected]> Description: Attribute group to describe the magic bits that go into
Documentation/ABI/testing/sysfs-bus-i2c-devices-hm6352 +3 -3
@@ -1,20 +1,20 @@ What: /sys/bus/i2c/devices/.../heading0_input Date: April 2010 -Kernel Version: 2.6.36? +KernelVersion: 2.6.36? Contact: [email protected] Description: Reports the current heading from the compass as a floating point value in degrees. What: /sys/bus/i2c/devices/.../power_state Date: April 2010 -Kernel Version: 2.6.36? +KernelVersion: 2.6.36? Contact: [email protected] Description: Sets the power state of the device. 0 sets the device into sleep mode, 1 wakes it up. What: /sys/bus/i2c/devices/.../calibration Date: April 2010 -Kernel Version: 2.6.36? +KernelVersion: 2.6.36? Contact: [email protected] Description: Sets the calibration on or off (1 = on, 0 = off). See the chip data sheet.
Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats +6 -6
@@ -11,7 +11,7 @@ saw any problems). What: /sys/bus/pci/devices/<dev>/aer_dev_correctable Date: July 2018 -Kernel Version: 4.19.0 +KernelVersion: 4.19.0 Contact: [email protected], [email protected] Description: List of correctable errors seen and reported by this PCI device using ERR_COR. Note that since multiple errors may
@@ -33,7 +33,7 @@ TOTAL_ERR_COR 2 What: /sys/bus/pci/devices/<dev>/aer_dev_fatal Date: July 2018 -Kernel Version: 4.19.0 +KernelVersion: 4.19.0 Contact: [email protected], [email protected] Description: List of uncorrectable fatal errors seen and reported by this PCI device using ERR_FATAL. Note that since multiple errors may
@@ -64,7 +64,7 @@ TOTAL_ERR_FATAL 0 What: /sys/bus/pci/devices/<dev>/aer_dev_nonfatal Date: July 2018 -Kernel Version: 4.19.0 +KernelVersion: 4.19.0 Contact: [email protected], [email protected] Description: List of uncorrectable nonfatal errors seen and reported by this PCI device using ERR_NONFATAL. Note that since multiple errors
@@ -105,18 +105,18 @@ messages on the PCI hierarchy originating at that root port. What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor Date: July 2018 -Kernel Version: 4.19.0 +KernelVersion: 4.19.0 Contact: [email protected], [email protected] Description: Total number of ERR_COR messages reported to rootport. What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal Date: July 2018 -Kernel Version: 4.19.0 +KernelVersion: 4.19.0 Contact: [email protected], [email protected] Description: Total number of ERR_FATAL messages reported to rootport. What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_nonfatal Date: July 2018 -Kernel Version: 4.19.0 +KernelVersion: 4.19.0 Contact: [email protected], [email protected] Description: Total number of ERR_NONFATAL messages reported to rootport.
Documentation/ABI/testing/sysfs-bus-pci-devices-cciss +11 -11
@@ -1,68 +1,68 @@ What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/model Date: March 2009 -Kernel Version: 2.6.30 +KernelVersion: 2.6.30 Contact: [email protected] Description: Displays the SCSI INQUIRY page 0 model for logical drive Y of controller X. What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev Date: March 2009 -Kernel Version: 2.6.30 +KernelVersion: 2.6.30 Contact: [email protected] Description: Displays the SCSI INQUIRY page 0 revision for logical drive Y of controller X. What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id Date: March 2009 -Kernel Version: 2.6.30 +KernelVersion: 2.6.30 Contact: [email protected] Description: Displays the SCSI INQUIRY page 83 serial number for logical drive Y of controller X. What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor Date: March 2009 -Kernel Version: 2.6.30 +KernelVersion: 2.6.30 Contact: [email protected] Description: Displays the SCSI INQUIRY page 0 vendor for logical drive Y of controller X. What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY Date: March 2009 -Kernel Version: 2.6.30 +KernelVersion: 2.6.30 Contact: [email protected] Description: A symbolic link to /sys/block/cciss!cXdY What: /sys/bus/pci/devices/<dev>/ccissX/rescan Date: August 2009 -Kernel Version: 2.6.31 +KernelVersion: 2.6.31 Contact: [email protected] Description: Kicks of a rescan of the controller to discover logical drive topology changes. What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid Date: August 2009 -Kernel Version: 2.6.31 +KernelVersion: 2.6.31 Contact: [email protected] Description: Displays the 8-byte LUN ID used to address logical drive Y of controller X. What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level Date: August 2009 -Kernel Version: 2.6.31 +KernelVersion: 2.6.31 Contact: [email protected] Description: Displays the RAID level of logical drive Y of controller X. What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count Date: August 2009 -Kernel Version: 2.6.31 +KernelVersion: 2.6.31 Contact: [email protected] Description: Displays the usage count (number of opens) of logical drive Y of controller X. What: /sys/bus/pci/devices/<dev>/ccissX/resettable Date: February 2011 -Kernel Version: 2.6.38 +KernelVersion: 2.6.38 Contact: [email protected] Description: Value of 1 indicates the controller can honor the reset_devices kernel parameter. Value of 0 indicates reset_devices cannot be
@@ -73,7 +73,7 @@ Description: Value of 1 indicates the controller can honor the reset_devices What: /sys/bus/pci/devices/<dev>/ccissX/transport_mode Date: July 2011 -Kernel Version: 3.0 +KernelVersion: 3.0 Contact: [email protected] Description: Value of "simple" indicates that the controller has been placed in "simple mode". Value of "performant" indicates that the
Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg +5 -5
@@ -1,6 +1,6 @@ What: /sys/bus/usb/.../powered Date: August 2008 -Kernel Version: 2.6.26 +KernelVersion: 2.6.26 Contact: Harrison Metzger <[email protected]> Description: Controls whether the device's display will powered. A value of 0 is off and a non-zero value is on.
@@ -8,7 +8,7 @@ Description: Controls whether the device's display will powered. What: /sys/bus/usb/.../mode_msb What: /sys/bus/usb/.../mode_lsb Date: August 2008 -Kernel Version: 2.6.26 +KernelVersion: 2.6.26 Contact: Harrison Metzger <[email protected]> Description: Controls the devices display mode. For a 6 character display the values are
@@ -18,7 +18,7 @@ Description: Controls the devices display mode. What: /sys/bus/usb/.../textmode Date: August 2008 -Kernel Version: 2.6.26 +KernelVersion: 2.6.26 Contact: Harrison Metzger <[email protected]> Description: Controls the way the device interprets its text buffer. raw: each character controls its segment manually
@@ -27,13 +27,13 @@ Description: Controls the way the device interprets its text buffer. What: /sys/bus/usb/.../text Date: August 2008 -Kernel Version: 2.6.26 +KernelVersion: 2.6.26 Contact: Harrison Metzger <[email protected]> Description: The text (or data) for the device to display What: /sys/bus/usb/.../decimals Date: August 2008 -Kernel Version: 2.6.26 +KernelVersion: 2.6.26 Contact: Harrison Metzger <[email protected]> Description: Controls the decimal places on the device. To set the nth decimal place, give this field
Documentation/ABI/testing/sysfs-driver-altera-cvp +1 -1
@@ -1,6 +1,6 @@ What: /sys/bus/pci/drivers/altera-cvp/chkcfg Date: May 2017 -Kernel Version: 4.13 +KernelVersion: 4.13 Contact: Anatolij Gustschin <[email protected]> Description: Contains either 1 or 0 and controls if configuration
Documentation/ABI/testing/sysfs-driver-ppi +1 -1
@@ -1,6 +1,6 @@ What: /sys/class/tpm/tpmX/ppi/ Date: August 2012 -Kernel Version: 3.6 +KernelVersion: 3.6 Contact: [email protected] Description: This folder includes the attributes related with PPI (Physical
Documentation/ABI/testing/sysfs-driver-st +1 -1
@@ -1,6 +1,6 @@ What: /sys/bus/scsi/drivers/st/debug_flag Date: October 2015 -Kernel Version: ?.? +KernelVersion: ?.? Contact: [email protected] Description: This file allows you to turn debug output from the st driver
Documentation/ABI/testing/sysfs-driver-wacom +1 -1
@@ -1,6 +1,6 @@ What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/speed Date: April 2010 -Kernel Version: 2.6.35 +KernelVersion: 2.6.35 Contact: [email protected] Description: The /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/speed file
Signature · 1 line
2.21.0
Re: [PATCH v2 02/22] ABI: Fix KernelVersion tags
Quoted 3 lines · Mauro Carvalho Chehab
It is "KernelVersion:" and not "Kernel Version:".
Signed-off-by Mauro Carvalho Chehab <[email protected]>
-Kees
Quoted 307 lines
--- Documentation/ABI/testing/pstore | 2 +- .../sysfs-bus-event_source-devices-format | 2 +- .../ABI/testing/sysfs-bus-i2c-devices-hm6352 | 6 ++--- .../testing/sysfs-bus-pci-devices-aer_stats | 12 +++++----- .../ABI/testing/sysfs-bus-pci-devices-cciss | 22 +++++++++---------- .../testing/sysfs-bus-usb-devices-usbsevseg | 10 ++++----- .../ABI/testing/sysfs-driver-altera-cvp | 2 +- Documentation/ABI/testing/sysfs-driver-ppi | 2 +- Documentation/ABI/testing/sysfs-driver-st | 2 +- Documentation/ABI/testing/sysfs-driver-wacom | 2 +- 10 files changed, 31 insertions(+), 31 deletions(-)Documentation/ABI/testing/pstore +1
-1@@ -1,6 +1,6 @@ What: /sys/fs/pstore/... (or /dev/pstore/...) Date: March 2011 -Kernel Version: 2.6.39 +KernelVersion: 2.6.39 Contact: [email protected] Description: Generic interface to platform dependent persistent storage.Documentation/ABI/testing/sysfs-bus-event_source-devices-format +1
-1@@ -1,6 +1,6 @@ What: /sys/bus/event_source/devices/<dev>/format Date: January 2012 -Kernel Version: 3.3 +KernelVersion: 3.3 Contact: Jiri Olsa <[email protected]> Description: Attribute group to describe the magic bits that go intoDocumentation/ABI/testing/sysfs-bus-i2c-devices-hm6352 +3
-3@@ -1,20 +1,20 @@ What: /sys/bus/i2c/devices/.../heading0_input Date: April 2010 -Kernel Version: 2.6.36? +KernelVersion: 2.6.36? Contact: [email protected] Description: Reports the current heading from the compass as a floating point value in degrees. What: /sys/bus/i2c/devices/.../power_state Date: April 2010 -Kernel Version: 2.6.36? +KernelVersion: 2.6.36? Contact: [email protected] Description: Sets the power state of the device. 0 sets the device into sleep mode, 1 wakes it up. What: /sys/bus/i2c/devices/.../calibration Date: April 2010 -Kernel Version: 2.6.36? +KernelVersion: 2.6.36? Contact: [email protected] Description: Sets the calibration on or off (1 = on, 0 = off). See the chip data sheet.Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats +6
-6@@ -11,7 +11,7 @@ saw any problems). What: /sys/bus/pci/devices/<dev>/aer_dev_correctable Date: July 2018 -Kernel Version: 4.19.0 +KernelVersion: 4.19.0 Contact: [email protected], [email protected] Description: List of correctable errors seen and reported by this PCI device using ERR_COR. Note that since multiple errors may@@ -33,7 +33,7 @@ TOTAL_ERR_COR 2 What: /sys/bus/pci/devices/<dev>/aer_dev_fatal Date: July 2018 -Kernel Version: 4.19.0 +KernelVersion: 4.19.0 Contact: [email protected], [email protected] Description: List of uncorrectable fatal errors seen and reported by this PCI device using ERR_FATAL. Note that since multiple errors may@@ -64,7 +64,7 @@ TOTAL_ERR_FATAL 0 What: /sys/bus/pci/devices/<dev>/aer_dev_nonfatal Date: July 2018 -Kernel Version: 4.19.0 +KernelVersion: 4.19.0 Contact: [email protected], [email protected] Description: List of uncorrectable nonfatal errors seen and reported by this PCI device using ERR_NONFATAL. Note that since multiple errors@@ -105,18 +105,18 @@ messages on the PCI hierarchy originating at that root port. What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor Date: July 2018 -Kernel Version: 4.19.0 +KernelVersion: 4.19.0 Contact: [email protected], [email protected] Description: Total number of ERR_COR messages reported to rootport. What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal Date: July 2018 -Kernel Version: 4.19.0 +KernelVersion: 4.19.0 Contact: [email protected], [email protected] Description: Total number of ERR_FATAL messages reported to rootport. What: /sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_nonfatal Date: July 2018 -Kernel Version: 4.19.0 +KernelVersion: 4.19.0 Contact: [email protected], [email protected] Description: Total number of ERR_NONFATAL messages reported to rootport.Documentation/ABI/testing/sysfs-bus-pci-devices-cciss +11
-11@@ -1,68 +1,68 @@ What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/model Date: March 2009 -Kernel Version: 2.6.30 +KernelVersion: 2.6.30 Contact: [email protected] Description: Displays the SCSI INQUIRY page 0 model for logical drive Y of controller X. What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/rev Date: March 2009 -Kernel Version: 2.6.30 +KernelVersion: 2.6.30 Contact: [email protected] Description: Displays the SCSI INQUIRY page 0 revision for logical drive Y of controller X. What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/unique_id Date: March 2009 -Kernel Version: 2.6.30 +KernelVersion: 2.6.30 Contact: [email protected] Description: Displays the SCSI INQUIRY page 83 serial number for logical drive Y of controller X. What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/vendor Date: March 2009 -Kernel Version: 2.6.30 +KernelVersion: 2.6.30 Contact: [email protected] Description: Displays the SCSI INQUIRY page 0 vendor for logical drive Y of controller X. What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/block:cciss!cXdY Date: March 2009 -Kernel Version: 2.6.30 +KernelVersion: 2.6.30 Contact: [email protected] Description: A symbolic link to /sys/block/cciss!cXdY What: /sys/bus/pci/devices/<dev>/ccissX/rescan Date: August 2009 -Kernel Version: 2.6.31 +KernelVersion: 2.6.31 Contact: [email protected] Description: Kicks of a rescan of the controller to discover logical drive topology changes. What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/lunid Date: August 2009 -Kernel Version: 2.6.31 +KernelVersion: 2.6.31 Contact: [email protected] Description: Displays the 8-byte LUN ID used to address logical drive Y of controller X. What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/raid_level Date: August 2009 -Kernel Version: 2.6.31 +KernelVersion: 2.6.31 Contact: [email protected] Description: Displays the RAID level of logical drive Y of controller X. What: /sys/bus/pci/devices/<dev>/ccissX/cXdY/usage_count Date: August 2009 -Kernel Version: 2.6.31 +KernelVersion: 2.6.31 Contact: [email protected] Description: Displays the usage count (number of opens) of logical drive Y of controller X. What: /sys/bus/pci/devices/<dev>/ccissX/resettable Date: February 2011 -Kernel Version: 2.6.38 +KernelVersion: 2.6.38 Contact: [email protected] Description: Value of 1 indicates the controller can honor the reset_devices kernel parameter. Value of 0 indicates reset_devices cannot be@@ -73,7 +73,7 @@ Description: Value of 1 indicates the controller can honor the reset_devices What: /sys/bus/pci/devices/<dev>/ccissX/transport_mode Date: July 2011 -Kernel Version: 3.0 +KernelVersion: 3.0 Contact: [email protected] Description: Value of "simple" indicates that the controller has been placed in "simple mode". Value of "performant" indicates that theDocumentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg +5
-5@@ -1,6 +1,6 @@ What: /sys/bus/usb/.../powered Date: August 2008 -Kernel Version: 2.6.26 +KernelVersion: 2.6.26 Contact: Harrison Metzger <[email protected]> Description: Controls whether the device's display will powered. A value of 0 is off and a non-zero value is on.@@ -8,7 +8,7 @@ Description: Controls whether the device's display will powered. What: /sys/bus/usb/.../mode_msb What: /sys/bus/usb/.../mode_lsb Date: August 2008 -Kernel Version: 2.6.26 +KernelVersion: 2.6.26 Contact: Harrison Metzger <[email protected]> Description: Controls the devices display mode. For a 6 character display the values are@@ -18,7 +18,7 @@ Description: Controls the devices display mode. What: /sys/bus/usb/.../textmode Date: August 2008 -Kernel Version: 2.6.26 +KernelVersion: 2.6.26 Contact: Harrison Metzger <[email protected]> Description: Controls the way the device interprets its text buffer. raw: each character controls its segment manually@@ -27,13 +27,13 @@ Description: Controls the way the device interprets its text buffer. What: /sys/bus/usb/.../text Date: August 2008 -Kernel Version: 2.6.26 +KernelVersion: 2.6.26 Contact: Harrison Metzger <[email protected]> Description: The text (or data) for the device to display What: /sys/bus/usb/.../decimals Date: August 2008 -Kernel Version: 2.6.26 +KernelVersion: 2.6.26 Contact: Harrison Metzger <[email protected]> Description: Controls the decimal places on the device. To set the nth decimal place, give this fieldDocumentation/ABI/testing/sysfs-driver-altera-cvp +1
-1@@ -1,6 +1,6 @@ What: /sys/bus/pci/drivers/altera-cvp/chkcfg Date: May 2017 -Kernel Version: 4.13 +KernelVersion: 4.13 Contact: Anatolij Gustschin <[email protected]> Description: Contains either 1 or 0 and controls if configurationDocumentation/ABI/testing/sysfs-driver-ppi +1
-1@@ -1,6 +1,6 @@ What: /sys/class/tpm/tpmX/ppi/ Date: August 2012 -Kernel Version: 3.6 +KernelVersion: 3.6 Contact: [email protected] Description: This folder includes the attributes related with PPI (PhysicalDocumentation/ABI/testing/sysfs-driver-st +1
-1@@ -1,6 +1,6 @@ What: /sys/bus/scsi/drivers/st/debug_flag Date: October 2015 -Kernel Version: ?.? +KernelVersion: ?.? Contact: [email protected] Description: This file allows you to turn debug output from the st driverDocumentation/ABI/testing/sysfs-driver-wacom +1
-1@@ -1,6 +1,6 @@ What: /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/speed Date: April 2010 -Kernel Version: 2.6.35 +KernelVersion: 2.6.35 Contact: [email protected] Description: The /sys/bus/hid/devices/<bus>:<vid>:<pid>.<n>/speed fileSignature · 1 line
2.21.0
Signature · 1 line
Kees Cook
PATCH v2 3/22 scripts: add an script to parse the ABI files
In reply to Mauro Carvalho ChehabAdd a script to parse the Documentation/ABI files and produce an output with all entries inside an ABI (sub)directory.
Right now, it outputs its contents on ReST format. It shouldn't be hard to make it produce other kind of outputs, since the ABI file parser is implemented in separate than the output generator.
--- scripts/get_abi.pl | 212 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100755 scripts/get_abi.pl
scripts/get_abi.pl new file +212 -0
@@ -0,0 +1,212 @@ +#!/usr/bin/perl + +use strict; +use Pod::Usage; +use Getopt::Long; +use File::Find; +use Fcntl ':mode'; + +my $help; +my $man; +my $debug; + +GetOptions( + "debug|d+" => \$debug, + 'help|?' => \$help, + man => \$man +) or pod2usage(2); + +pod2usage(1) if $help; +pod2usage(-exitstatus => 0, -verbose => 2) if $man; + +pod2usage(2) if (scalar @ARGV != 1); + +my ($prefix) = @ARGV; + +require Data::Dumper if ($debug); + +my %data; + +# +# Displays an error message, printing file name and line +# +sub parse_error($$$$) { + my ($file, $ln, $msg, $data) = @_; + + print STDERR "file $file#$ln: $msg at\n\t$data"; +} + +# +# Parse an ABI file, storing its contents at %data +# +sub parse_abi { + my $file = $File::Find::name; + + my $mode = (stat($file))[2]; + return if ($mode & S_IFDIR); + return if ($file =~ m,/README,); + + my $name = $file; + $name =~ s,.*/,,; + + my $type = $file; + $type =~ s,.*/(.*)/.*,$1,; + + my $what; + my $new_what; + my $tag; + my $ln; + + print STDERR "Opening $file\n" if ($debug > 1); + open IN, $file; + while(<IN>) { + $ln++; + if (m/^(\S+):\s*(.*)/i) { + my $new_tag = lc($1); + my $content = $2; + + if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) { + if ($tag eq "description") { + $data{$what}->{$tag} .= "\n$content";; + $data{$what}->{$tag} =~ s/\n+$//; + next; + } else { + parse_error($file, $ln, "tag '$tag' is invalid", $_); + } + } + + if ($new_tag =~ m/what/) { + if ($tag =~ m/what/) { + $what .= ", " . $content; + } else { + $what = $content; + $new_what = 1; + } + $tag = $new_tag; + next; + } + + $tag = $new_tag; + + if ($new_what) { + $new_what = 0; + + $data{$what}->{type} = $type; + $data{$what}->{file} = $name; + print STDERR "\twhat: $what\n" if ($debug > 1); + } + + if (!$what) { + parse_error($file, $ln, "'What:' should come first:", $_); + next; + } + $data{$what}->{$tag} = $content; + next; + } + + # Silently ignore any headers before the database + next if (!$tag); + + if (m/^\s*(.*)/) { + $data{$what}->{$tag} .= "\n$1"; + $data{$what}->{$tag} =~ s/\n+$//; + next; + } + + # Everything else is error + parse_error($file, $ln, "Unexpected line:", $_); + } + close IN; +} + +# Outputs the output on ReST format +sub output_rest { + foreach my $what (sort keys %data) { + my $type = $data{$what}->{type}; + my $file = $data{$what}->{file}; + + my $w = $what; + $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; + + print "$w\n\n"; + print "- defined on file $file (type: $type)\n\n::\n\n"; + + my $desc = $data{$what}->{description}; + $desc =~ s/^\s+//; + + # Remove title markups from the description, as they won't work + $desc =~ s/\n[\-\*\=\^\~]+\n/\n/g; + + # put everything inside a code block + $desc =~ s/\n/\n /g; + + + if (!($desc =~ /^\s*$/)) { + print " $desc\n\n"; + } else { + print " DESCRIPTION MISSING\n\n"; + } + } +} + +# +# Parses all ABI files located at $prefix dir +# +find({wanted =>\&parse_abi, no_chdir => 1}, $prefix); + +print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug); + +# +# Outputs an ReST file with the ABI contents +# +output_rest + + +__END__ + +=head1 NAME + +abi_book.pl - parse the Linux ABI files and produce a ReST book. + +=head1 SYNOPSIS + +B<abi_book.pl> [--debug] <ABI_DIR>] + +=head1 OPTIONS + +=over 8 + +=item B<--debug> + +Put the script in verbose mode, useful for debugging. Can be called multiple +times, to increase verbosity. + +=item B<--help> + +Prints a brief help message and exits. + +=item B<--man> + +Prints the manual page and exits. + +=back + +=head1 DESCRIPTION + +Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI) +and produce a ReST book containing the Linux ABI. + +=head1 BUGS + +Report bugs to Mauro Carvalho Chehab <[email protected]> + +=head1 COPYRIGHT + +Copyright (c) 2016 by Mauro Carvalho Chehab <[email protected]>. + +License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>. + +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +=cut
Signature · 1 line
2.21.0
PATCH v2 4/22 scripts/get_abi.pl: parse files with text at beginning
In reply to Mauro Carvalho ChehabIt sounds usefult o parse files with has some text at the beginning. Add support for it.
--- scripts/get_abi.pl | 59 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 54 insertions(+), 5 deletions(-)
scripts/get_abi.pl +54 -5
@@ -55,7 +55,10 @@ sub parse_abi { my $what; my $new_what; my $tag; + my $label; my $ln; + my $has_file; + my $xrefs; print STDERR "Opening $file\n" if ($debug > 1); open IN, $file;
@@ -67,7 +70,7 @@ sub parse_abi { if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) { if ($tag eq "description") { - $data{$what}->{$tag} .= "\n$content";; + $data{$what}->{$tag} .= "\n$content"; $data{$what}->{$tag} =~ s/\n+$//; next; } else {
@@ -83,6 +86,25 @@ sub parse_abi { $new_what = 1; } $tag = $new_tag; + + if ($has_file) { + $label = "abi_" . $content . " "; + $label =~ tr/A-Z/a-z/; + + # Convert special chars to "_" + $label =~s/[\x00-\x2f]+/_/g; + $label =~s/[\x3a-\x40]+/_/g; + $label =~s/[\x7b-\xff]+/_/g; + $label =~ s,_+,_,g; + $label =~ s,_$,,; + + $data{$what}->{label} .= $label; + + # Escape special chars from content + $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g; + + $xrefs .= "- :ref:`$content <$label>`\n\n"; + } next; }
@@ -104,8 +126,18 @@ sub parse_abi { next; } - # Silently ignore any headers before the database - next if (!$tag); + # Store any contents before the database + if (!$tag) { + next if (/^\n/); + + my $my_what = "File $name"; + $data{$my_what}->{what} = "File $name"; + $data{$my_what}->{type} = "File"; + $data{$my_what}->{file} = $name; + $data{$my_what}->{description} .= $_; + $has_file = 1; + next; + } if (m/^\s*(.*)/) { $data{$what}->{$tag} .= "\n$1";
@@ -117,6 +149,11 @@ sub parse_abi { parse_error($file, $ln, "Unexpected line:", $_); } close IN; + + if ($has_file) { + my $my_what = "File $name"; + $data{$my_what}->{xrefs} = $xrefs; + } } # Outputs the output on ReST format
@@ -128,8 +165,17 @@ sub output_rest { my $w = $what; $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; + if ($data{$what}->{label}) { + my @labels = split(/\s/, $data{$what}->{label}); + foreach my $label (@labels) { + printf ".. _%s:\n\n", $label; + } + } + print "$w\n\n"; - print "- defined on file $file (type: $type)\n\n::\n\n"; + + print "- defined on file $file (type: $type)\n\n" if ($type ne "File"); + print "::\n\n"; my $desc = $data{$what}->{description}; $desc =~ s/^\s+//;
@@ -144,8 +190,11 @@ sub output_rest { if (!($desc =~ /^\s*$/)) { print " $desc\n\n"; } else { - print " DESCRIPTION MISSING\n\n"; + print " DESCRIPTION MISSING for $what\n\n"; } + + printf "Has the following ABI:\n\n%s", $data{$what}->{xrefs} if ($data{$what}->{xrefs}); + } }
Signature · 1 line
2.21.0
PATCH v2 5/22 scripts/get_abi.pl: avoid use literal blocks when not needed
In reply to Mauro Carvalho ChehabThe usage of literal blocks make the document very complex, causing the browser to take a long time to load.
On most ABI descriptions, they're a plain text, and don't require a literal block.
So, add a logic there with identifies when a literal block is needed.
As, on literal blocks, we need to respect the original document space, the most complex part of this patch is to preserve the original spacing where needed.
--- scripts/get_abi.pl | 104 +++++++++++++++++++++++++++++++++------------ 1 file changed, 78 insertions(+), 26 deletions(-)
scripts/get_abi.pl +78 -26
@@ -59,29 +59,34 @@ sub parse_abi { my $ln; my $has_file; my $xrefs; + my $space; print STDERR "Opening $file\n" if ($debug > 1); open IN, $file; while(<IN>) { $ln++; - if (m/^(\S+):\s*(.*)/i) { + if (m/^(\S+)(:\s*)(.*)/i) { my $new_tag = lc($1); - my $content = $2; + my $sep = $2; + my $content = $3; if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) { if ($tag eq "description") { - $data{$what}->{$tag} .= "\n$content"; - $data{$what}->{$tag} =~ s/\n+$//; - next; + # New "tag" is actually part of + # description. Don't consider it a tag + $new_tag = ""; } else { parse_error($file, $ln, "tag '$tag' is invalid", $_); } } if ($new_tag =~ m/what/) { + $space = ""; if ($tag =~ m/what/) { $what .= ", " . $content; } else { + parse_error($file, $ln, "What '$what' doesn't have a description", "") if ($what && !$data{$what}->{description}); + $what = $content; $new_what = 1; }
@@ -108,25 +113,38 @@ sub parse_abi { next; } - $tag = $new_tag; + if ($new_tag) { + $tag = $new_tag; - if ($new_what) { - $new_what = 0; + if ($new_what) { + $new_what = 0; - $data{$what}->{type} = $type; - $data{$what}->{file} = $name; - print STDERR "\twhat: $what\n" if ($debug > 1); - } + $data{$what}->{type} = $type; + $data{$what}->{file} = $name; + print STDERR "\twhat: $what\n" if ($debug > 1); + } - if (!$what) { - parse_error($file, $ln, "'What:' should come first:", $_); + if (!$what) { + parse_error($file, $ln, "'What:' should come first:", $_); + next; + } + if ($tag eq "description") { + next if ($content =~ m/^\s*$/); + if ($content =~ m/^(\s*)(.*)/) { + my $new_content = $2; + $space = $new_tag . $sep . $1; + while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} + $space =~ s/./ /g; + $data{$what}->{$tag} .= "$new_content\n"; + } + } else { + $data{$what}->{$tag} = $content; + } next; } - $data{$what}->{$tag} = $content; - next; } - # Store any contents before the database + # Store any contents before tags at the database if (!$tag) { next if (/^\n/);
@@ -139,6 +157,32 @@ sub parse_abi { next; } + if ($tag eq "description") { + if (!$data{$what}->{description}) { + next if (m/^\s*\n/); + if (m/^(\s*)(.*)/) { + $space = $1; + while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} + $data{$what}->{$tag} .= "$2\n"; + } + } else { + my $content = $_; + if (m/^\s*\n/) { + $data{$what}->{$tag} .= $content; + next; + } + + while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} + $space = "" if (!($content =~ s/^($space)//)); + + # Compress spaces with tabs + $content =~ s<^ {8}> <\t>; + $content =~ s<^ {1,7}\t> <\t>; + $content =~ s< {1,7}\t> <\t>; + $data{$what}->{$tag} .= $content; + } + next; + } if (m/^\s*(.*)/) { $data{$what}->{$tag} .= "\n$1"; $data{$what}->{$tag} =~ s/\n+$//;
@@ -165,6 +209,9 @@ sub output_rest { my $w = $what; $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; + my $bar = $w; + $bar =~ s/./-/g; + if ($data{$what}->{label}) { my @labels = split(/\s/, $data{$what}->{label}); foreach my $label (@labels) {
@@ -172,10 +219,9 @@ sub output_rest { } } - print "$w\n\n"; + print "$w\n$bar\n\n"; print "- defined on file $file (type: $type)\n\n" if ($type ne "File"); - print "::\n\n"; my $desc = $data{$what}->{description}; $desc =~ s/^\s+//;
@@ -183,18 +229,24 @@ sub output_rest { # Remove title markups from the description, as they won't work $desc =~ s/\n[\-\*\=\^\~]+\n/\n/g; - # put everything inside a code block - $desc =~ s/\n/\n /g; - - if (!($desc =~ /^\s*$/)) { - print " $desc\n\n"; + if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) { + # put everything inside a code block + $desc =~ s/\n/\n /g; + + print "::\n\n"; + print " $desc\n\n"; + } else { + # Escape any special chars from description + $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g; + + print "$desc\n\n"; + } } else { - print " DESCRIPTION MISSING for $what\n\n"; + print "DESCRIPTION MISSING for $what\n\n"; } printf "Has the following ABI:\n\n%s", $data{$what}->{xrefs} if ($data{$what}->{xrefs}); - } }
Signature · 1 line
2.21.0
PATCH v2 6/22 scripts/get_abi.pl: split label naming from xref logic
In reply to Mauro Carvalho ChehabInstead of using a ReST compilant label while parsing, move the label to ReST output. That makes the parsing logic more generic, allowing it to provide other types of output.
As a side effect, now all files used to generate the output will be output. We can later add command line arguments to filter.
--- scripts/get_abi.pl | 94 ++++++++++++++++++++++++++-------------------- 1 file changed, 53 insertions(+), 41 deletions(-)
scripts/get_abi.pl +53 -41
@@ -49,17 +49,23 @@ sub parse_abi { my $name = $file; $name =~ s,.*/,,; + my $nametag = "File $name"; + $data{$nametag}->{what} = "File $name"; + $data{$nametag}->{type} = "File"; + $data{$nametag}->{file} = $name; + $data{$nametag}->{is_file} = 1; + my $type = $file; $type =~ s,.*/(.*)/.*,$1,; my $what; my $new_what; my $tag; - my $label; my $ln; - my $has_file; my $xrefs; my $space; + my @labels; + my $label; print STDERR "Opening $file\n" if ($debug > 1); open IN, $file;
@@ -88,28 +94,13 @@ sub parse_abi { parse_error($file, $ln, "What '$what' doesn't have a description", "") if ($what && !$data{$what}->{description}); $what = $content; + $label = $content; $new_what = 1; } + push @labels, [($content, $label)]; $tag = $new_tag; - if ($has_file) { - $label = "abi_" . $content . " "; - $label =~ tr/A-Z/a-z/; - - # Convert special chars to "_" - $label =~s/[\x00-\x2f]+/_/g; - $label =~s/[\x3a-\x40]+/_/g; - $label =~s/[\x7b-\xff]+/_/g; - $label =~ s,_+,_,g; - $label =~ s,_$,,; - - $data{$what}->{label} .= $label; - - # Escape special chars from content - $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g; - - $xrefs .= "- :ref:`$content <$label>`\n\n"; - } + push @{$data{$nametag}->{xrefs}}, [($content, $label)] if ($data{$nametag}->{what}); next; }
@@ -117,6 +108,9 @@ sub parse_abi { $tag = $new_tag; if ($new_what) { + @{$data{$what}->{label}} = @labels if ($data{$nametag}->{what}); + @labels = (); + $label = ""; $new_what = 0; $data{$what}->{type} = $type;
@@ -145,15 +139,8 @@ sub parse_abi { } # Store any contents before tags at the database - if (!$tag) { - next if (/^\n/); - - my $my_what = "File $name"; - $data{$my_what}->{what} = "File $name"; - $data{$my_what}->{type} = "File"; - $data{$my_what}->{file} = $name; - $data{$my_what}->{description} .= $_; - $has_file = 1; + if (!$tag && $data{$nametag}->{what}) { + $data{$nametag}->{description} .= $_; next; }
@@ -192,12 +179,8 @@ sub parse_abi { # Everything else is error parse_error($file, $ln, "Unexpected line:", $_); } + $data{$nametag}->{description} =~ s/^\n+//; close IN; - - if ($has_file) { - my $my_what = "File $name"; - $data{$my_what}->{xrefs} = $xrefs; - } } # Outputs the output on ReST format
@@ -212,11 +195,22 @@ sub output_rest { my $bar = $w; $bar =~ s/./-/g; - if ($data{$what}->{label}) { - my @labels = split(/\s/, $data{$what}->{label}); - foreach my $label (@labels) { - printf ".. _%s:\n\n", $label; - } + foreach my $p (@{$data{$what}->{label}}) { + my ($content, $label) = @{$p}; + $label = "abi_" . $label . " "; + $label =~ tr/A-Z/a-z/; + + # Convert special chars to "_" + $label =~s/([\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xff])/_/g; + $label =~ s,_+,_,g; + $label =~ s,_$,,; + + $data{$what}->{label} .= $label; + + printf ".. _%s:\n\n", $label; + + # only one label is enough + last; } print "$w\n$bar\n\n";
@@ -243,10 +237,28 @@ sub output_rest { print "$desc\n\n"; } } else { - print "DESCRIPTION MISSING for $what\n\n"; + print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file}); } - printf "Has the following ABI:\n\n%s", $data{$what}->{xrefs} if ($data{$what}->{xrefs}); + if ($data{$what}->{xrefs}) { + printf "Has the following ABI:\n\n"; + + foreach my $p(@{$data{$what}->{xrefs}}) { + my ($content, $label) = @{$p}; + $label = "abi_" . $label . " "; + $label =~ tr/A-Z/a-z/; + + # Convert special chars to "_" + $label =~s/([\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\xff])/_/g; + $label =~ s,_+,_,g; + $label =~ s,_$,,; + + # Escape special chars from content + $content =~s/([\x00-\x1f\x21-\x2f\x3a-\x40\x7b-\xff])/\\$1/g; + + print "- :ref:`$content <$label>`\n\n"; + } + } } }
Signature · 1 line
2.21.0
PATCH v2 7/22 scripts/get_abi.pl: add support for searching for ABI symbols
In reply to Mauro Carvalho ChehabChange its syntax to allow switching between ReST output mode and a new search mode, with allows to seek for ABI symbols using regex.
--- scripts/get_abi.pl | 112 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 103 insertions(+), 9 deletions(-)
scripts/get_abi.pl +103 -9
@@ -9,9 +9,11 @@ use Fcntl ':mode'; my $help; my $man; my $debug; +my $prefix="Documentation/ABI"; GetOptions( "debug|d+" => \$debug, + "dir=s" => \$prefix, 'help|?' => \$help, man => \$man ) or pod2usage(2);
@@ -19,9 +21,12 @@ GetOptions( pod2usage(1) if $help; pod2usage(-exitstatus => 0, -verbose => 2) if $man; -pod2usage(2) if (scalar @ARGV != 1); +pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2); -my ($prefix) = @ARGV; +my ($cmd, $arg) = @ARGV; + +pod2usage(2) if ($cmd ne "search" && $cmd ne "rest"); +pod2usage(2) if ($cmd eq "search" && !$arg); require Data::Dumper if ($debug);
@@ -53,6 +58,7 @@ sub parse_abi { $data{$nametag}->{what} = "File $name"; $data{$nametag}->{type} = "File"; $data{$nametag}->{file} = $name; + $data{$nametag}->{filepath} = $file; $data{$nametag}->{is_file} = 1; my $type = $file;
@@ -115,6 +121,7 @@ sub parse_abi { $data{$what}->{type} = $type; $data{$what}->{file} = $name; + $data{$what}->{filepath} = $file; print STDERR "\twhat: $what\n" if ($debug > 1); }
@@ -183,7 +190,9 @@ sub parse_abi { close IN; } -# Outputs the output on ReST format +# +# Outputs the book on ReST format +# sub output_rest { foreach my $what (sort keys %data) { my $type = $data{$what}->{type};
@@ -262,6 +271,45 @@ sub output_rest { } } +# +# Searches for ABI symbols +# +sub search_symbols { + foreach my $what (sort keys %data) { + next if (!($what =~ m/($arg)/)); + + my $type = $data{$what}->{type}; + next if ($type eq "File"); + + my $file = $data{$what}->{filepath}; + + my $bar = $what; + $bar =~ s/./-/g; + + print "\n$what\n$bar\n\n"; + + my $kernelversion = $data{$what}->{kernelversion}; + my $contact = $data{$what}->{contact}; + my $users = $data{$what}->{users}; + my $date = $data{$what}->{date}; + my $desc = $data{$what}->{description}; + $kernelversion =~ s/^\s+//; + $contact =~ s/^\s+//; + $users =~ s/^\s+//; + $users =~ s/\n//g; + $date =~ s/^\s+//; + $desc =~ s/^\s+//; + + printf "Kernel version:\t\t%s\n", $kernelversion if ($kernelversion); + printf "Date:\t\t\t%s\n", $date if ($date); + printf "Contact:\t\t%s\n", $contact if ($contact); + printf "Users:\t\t\t%s\n", $users if ($users); + print "Defined on file:\t$file\n\n"; + print "Description:\n\n$desc"; + } +} + + # # Parses all ABI files located at $prefix dir #
@@ -270,9 +318,13 @@ find({wanted =>\&parse_abi, no_chdir => 1}, $prefix); print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug); # -# Outputs an ReST file with the ABI contents +# Handles the command # -output_rest +if ($cmd eq "rest") { + output_rest; +} else { + search_symbols; +} __END__
@@ -283,12 +335,27 @@ abi_book.pl - parse the Linux ABI files and produce a ReST book. =head1 SYNOPSIS -B<abi_book.pl> [--debug] <ABI_DIR>] +B<abi_book.pl> [--debug] <COMAND> [<ARGUMENT>] + +Where <COMMAND> can be: + +=over 8 + +B<search> [SEARCH_REGEX] - search for [SEARCH_REGEX] inside ABI + +B<rest> - output the ABI in ReST markup language + +=back =head1 OPTIONS =over 8 +=item B<--dir> + +Changes the location of the ABI search. By default, it uses +the Documentation/ABI directory. + =item B<--debug> Put the script in verbose mode, useful for debugging. Can be called multiple
@@ -306,8 +373,35 @@ Prints the manual page and exits. =head1 DESCRIPTION -Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI) -and produce a ReST book containing the Linux ABI. +Parse the Linux ABI files from ABI DIR (usually located at Documentation/ABI), +allowing to search for ABI symbols or to produce a ReST book containing +the Linux ABI documentation. + +=head1 EXAMPLES + +Search for all stable symbols with the word "usb": + +=over 8 + +$ scripts/get_abi.pl search usb --dir Documentation/ABI/stable + +=back + +Search for all symbols that match the regex expression "usb.*cap": + +=over 8 + +$ scripts/get_abi.pl search usb.*cap + +=back + +Output all obsoleted symbols in ReST format + +=over 8 + +$ scripts/get_abi.pl rest --dir Documentation/ABI/obsolete + +=back =head1 BUGS
@@ -315,7 +409,7 @@ Report bugs to Mauro Carvalho Chehab <[email protected]> =head1 COPYRIGHT -Copyright (c) 2016 by Mauro Carvalho Chehab <[email protected]>. +Copyright (c) 2016-2017 by Mauro Carvalho Chehab <[email protected]>. License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
Signature · 1 line
2.21.0
PATCH v2 8/22 scripts/get_abi.pl: represent what in tables
In reply to Mauro Carvalho ChehabSeveral entries at the ABI have multiple What: with the same description.
Instead of showing those symbols as sections, let's show them as tables. That makes easier to read on the final output, and avoid too much recursion at Sphinx parsing.
We need to put file references at the end, as we don't want non-file tables to be mangled with other entries.
--- scripts/get_abi.pl | 41 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 5 deletions(-)
scripts/get_abi.pl +36 -5
@@ -193,16 +193,19 @@ sub parse_abi { # # Outputs the book on ReST format # + sub output_rest { - foreach my $what (sort keys %data) { + foreach my $what (sort { + ($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") || + $a cmp $b + } keys %data) { my $type = $data{$what}->{type}; my $file = $data{$what}->{file}; + my $filepath = $data{$what}->{filepath}; my $w = $what; $w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g; - my $bar = $w; - $bar =~ s/./-/g; foreach my $p (@{$data{$what}->{label}}) { my ($content, $label) = @{$p};
@@ -222,9 +225,37 @@ sub output_rest { last; } - print "$w\n$bar\n\n"; - print "- defined on file $file (type: $type)\n\n" if ($type ne "File"); + $filepath =~ s,.*/(.*/.*),\1,;; + $filepath =~ s,[/\-],_,g;; + my $fileref = "abi_file_".$filepath; + + if ($type eq "File") { + my $bar = $w; + $bar =~ s/./-/g; + + print ".. _$fileref:\n\n"; + print "$w\n$bar\n\n"; + } else { + my @names = split /\s*,\s*/,$w; + + my $len = 0; + + foreach my $name (@names) { + $len = length($name) if (length($name) > $len); + } + + print "What:\n\n"; + + print "+-" . "-" x $len . "-+\n"; + foreach my $name (@names) { + printf "| %s", $name . " " x ($len - length($name)) . " |\n"; + print "+-" . "-" x $len . "-+\n"; + } + print "\n"; + } + + print "Defined on file :ref:`$file <$fileref>`\n\n" if ($type ne "File"); my $desc = $data{$what}->{description}; $desc =~ s/^\s+//;
Signature · 1 line
2.21.0
PATCH v2 9/22 scripts/get_abi.pl: fix parse issues with some files
In reply to Mauro Carvalho ChehabA few files are failing to parse:
Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats Documentation/ABI/testing/sysfs-class-pktcdvd Documentation/ABI/testing/sysfs-bus-nfit
On all three files, the problem is that there is a ":" character at the initial file description.
Improve the parse in order to handle those special cases.
--- scripts/get_abi.pl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
scripts/get_abi.pl +2 -2
@@ -87,7 +87,7 @@ sub parse_abi { # New "tag" is actually part of # description. Don't consider it a tag $new_tag = ""; - } else { + } elsif ($tag ne "") { parse_error($file, $ln, "tag '$tag' is invalid", $_); } }
@@ -110,7 +110,7 @@ sub parse_abi { next; } - if ($new_tag) { + if ($tag ne "" && $new_tag) { $tag = $new_tag; if ($new_what) {
Signature · 1 line
2.21.0
PATCH v2 10/22 scripts/get_abi.pl: avoid creating duplicate names
In reply to Mauro Carvalho ChehabThe file the Documentation/ABI/testing/sysfs-class-power has voltage_min, voltage_max and voltage_now symbols duplicated.
They are defined first for "General Properties" and then for "USB Properties".
This cause those warnings:
get_abi.pl rest --dir $srctree/Documentation/ABI/testing:26933: WARNING: Duplicate explicit target name: "abi_sys_class_power_supply_supply_name_voltage_max". get_abi.pl rest --dir $srctree/Documentation/ABI/testing:26968: WARNING: Duplicate explicit target name: "abi_sys_class_power_supply_supply_name_voltage_min". get_abi.pl rest --dir $srctree/Documentation/ABI/testing:27008: WARNING: Duplicate explicit target name: "abi_sys_class_power_supply_supply_name_voltage_now".
And, as the references are not valid, it will also generate warnings about links to undefined references.
Fix it by storing labels into a hash table and, when a duplicated one is found, appending random characters at the end.
--- scripts/get_abi.pl | 9 +++++++++ 1 file changed, 9 insertions(+)
scripts/get_abi.pl +9 -0
@@ -194,6 +194,8 @@ sub parse_abi { # Outputs the book on ReST format # +my %labels; + sub output_rest { foreach my $what (sort { ($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") ||
@@ -217,6 +219,13 @@ sub output_rest { $label =~ s,_+,_,g; $label =~ s,_$,,; + # Avoid duplicated labels + while (defined($labels{$label})) { + my @chars = ("A".."Z", "a".."z"); + $label .= $chars[rand @chars]; + } + $labels{$label} = 1; + $data{$what}->{label} .= $label; printf ".. _%s:\n\n", $label;
Signature · 1 line
2.21.0
PATCH v2 11/22 scripts/get_abi.pl: add a handler for invalid "where" tag
In reply to Mauro Carvalho ChehabThe ABI README file doesn't provide any meaning for a Where:
tag. Yet, a few ABI symbols use it. So, make the parser handle it, emitting a warning.
--- scripts/get_abi.pl | 6 ++++++ 1 file changed, 6 insertions(+)
scripts/get_abi.pl +6 -0
@@ -92,6 +92,12 @@ sub parse_abi { } } + # Invalid, but it is a common mistake + if ($new_tag eq "where") { + parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", $_); + $new_tag = "what"; + } + if ($new_tag =~ m/what/) { $space = ""; if ($tag =~ m/what/) {
Signature · 1 line
2.21.0
PATCH v2 12/22 scripts/get_abi.pl: add a validate command
In reply to Mauro Carvalho ChehabSometimes, we just want the parser to retrieve all symbols from ABI, in order to check for parsing errors. So, add a new "validate" command.
While here, update the man/help pages.
--- scripts/get_abi.pl | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-)
scripts/get_abi.pl +9 -7
@@ -25,7 +25,7 @@ pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2); my ($cmd, $arg) = @ARGV; -pod2usage(2) if ($cmd ne "search" && $cmd ne "rest"); +pod2usage(2) if ($cmd ne "search" && $cmd ne "rest" && $cmd ne "validate"); pod2usage(2) if ($cmd eq "search" && !$arg); require Data::Dumper if ($debug);
@@ -82,7 +82,7 @@ sub parse_abi { my $sep = $2; my $content = $3; - if (!($new_tag =~ m/(what|date|kernelversion|contact|description|users)/)) { + if (!($new_tag =~ m/(what|where|date|kernelversion|contact|description|users)/)) { if ($tag eq "description") { # New "tag" is actually part of # description. Don't consider it a tag
@@ -368,7 +368,7 @@ print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug); # if ($cmd eq "rest") { output_rest; -} else { +} elsif ($cmd eq "search") { search_symbols; }
@@ -381,7 +381,7 @@ abi_book.pl - parse the Linux ABI files and produce a ReST book. =head1 SYNOPSIS -B<abi_book.pl> [--debug] <COMAND> [<ARGUMENT>] +B<abi_book.pl> [--debug] [--man] [--help] [--dir=<dir>] <COMAND> [<ARGUMENT>] Where <COMMAND> can be:
@@ -389,7 +389,9 @@ Where <COMMAND> can be: B<search> [SEARCH_REGEX] - search for [SEARCH_REGEX] inside ABI -B<rest> - output the ABI in ReST markup language +B<rest> - output the ABI in ReST markup language + +B<validate> - validate the ABI contents =back
@@ -451,11 +453,11 @@ $ scripts/get_abi.pl rest --dir Documentation/ABI/obsolete =head1 BUGS -Report bugs to Mauro Carvalho Chehab <[email protected]> +Report bugs to Mauro Carvalho Chehab <[email protected]> =head1 COPYRIGHT -Copyright (c) 2016-2017 by Mauro Carvalho Chehab <[email protected]>. +Copyright (c) 2016-2019 by Mauro Carvalho Chehab <[email protected]>. License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>.
Signature · 1 line
2.21.0
PATCH v2 13/22 doc-rst: add ABI documentation to the admin-guide book
In reply to Mauro Carvalho ChehabAs we don't want a generic Sphinx extension to execute commands, change the one proposed to Markus to call the abi_book.pl script.
Use a script to parse the Documentation/ABI directory and output it at the admin-guide.
--- 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 | 155 +++++++++++++++++++++ 8 files changed, 214 insertions(+), 1 deletion(-) create mode 100644 Documentation/admin-guide/abi-obsolete.rst create mode 100644 Documentation/admin-guide/abi-removed.rst create mode 100644 Documentation/admin-guide/abi-stable.rst create mode 100644 Documentation/admin-guide/abi-testing.rst create mode 100644 Documentation/admin-guide/abi.rst create mode 100644 Documentation/sphinx/kernel_abi.py
Documentation/admin-guide/abi-obsolete.rst new file +10 -0
@@ -0,0 +1,10 @@ +ABI obsolete symbols +==================== + +Documents interfaces that are still remaining in the kernel, but are +marked to be removed at some later point in time. + +The description of the interface will document the reason why it is +obsolete and when it can be expected to be removed. + +.. kernel-abi:: $srctree/Documentation/ABI/obsolete
Documentation/admin-guide/abi-removed.rst new file +4 -0
@@ -0,0 +1,4 @@ +ABI removed symbols +=================== + +.. kernel-abi:: $srctree/Documentation/ABI/removed
Documentation/admin-guide/abi-stable.rst new file +13 -0
@@ -0,0 +1,13 @@ +ABI stable symbols +================== + +Documents the interfaces that the developer has defined to be stable. + +Userspace programs are free to use these interfaces with no +restrictions, and backward compatibility for them will be guaranteed +for at least 2 years. + +Most interfaces (like syscalls) are expected to never change and always +be available. + +.. kernel-abi:: $srctree/Documentation/ABI/stable
Documentation/admin-guide/abi-testing.rst new file +19 -0
@@ -0,0 +1,19 @@ +ABI testing symbols +=================== + +Documents interfaces that are felt to be stable, +as the main development of this interface has been completed. + +The interface can be changed to add new features, but the +current interface will not break by doing this, unless grave +errors or security problems are found in them. + +Userspace programs can start to rely on these interfaces, but they must +be aware of changes that can occur before these interfaces move to +be marked stable. + +Programs that use these interfaces are strongly encouraged to add their +name to the description of these interfaces, so that the kernel +developers can easily notify them if any changes occur. + +.. kernel-abi:: $srctree/Documentation/ABI/testing
Documentation/admin-guide/abi.rst new file +11 -0
@@ -0,0 +1,11 @@ +===================== +Linux ABI description +===================== + +.. toctree:: + :maxdepth: 1 + + abi-stable + abi-testing + abi-obsolete + abi-removed
Documentation/admin-guide/index.rst +1 -0
@@ -16,6 +16,7 @@ etc. README kernel-parameters devices + abi This section describes CPU vulnerabilities and their mitigations.
Documentation/conf.py +1 -1
@@ -34,7 +34,7 @@ needs_sphinx = '1.3' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure', 'sphinx.ext.ifconfig'] +extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure', 'sphinx.ext.ifconfig', 'kernel_abi'] # The name of the math extension changed on Sphinx 1.4 if (major == 1 and minor > 3) or (major > 1):
Documentation/sphinx/kernel_abi.py new file +155 -0
155 lines not on this page · raw message
Signature · 1 line
2.21.0
PATCH v2 14/22 docs: sphinx/kernel_abi.py: fix UTF-8 support
In reply to Mauro Carvalho ChehabThe parser breaks with UTF-8 characters with Sphinx 1.4.
--- Documentation/sphinx/kernel_abi.py | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-)
Documentation/sphinx/kernel_abi.py +7 -13
@@ -1,4 +1,5 @@ -# -*- coding: utf-8; mode: python -*- +# coding=utf-8 +# u""" kernel-abi ~~~~~~~~~~
@@ -28,6 +29,7 @@ u""" """ +import codecs import sys import os from os import path
@@ -43,14 +45,6 @@ from docutils.utils.error_reporting import ErrorString __version__ = '1.0' -# We can't assume that six is installed -PY3 = sys.version_info[0] == 3 -PY2 = sys.version_info[0] == 2 -if PY3: - # pylint: disable=C0103, W0622 - unicode = str - basestring = str - def setup(app): app.add_directive("kernel-abi", KernelCmd)
@@ -115,12 +109,12 @@ class KernelCmd(Directive): cmd , stdout = subprocess.PIPE , stderr = subprocess.PIPE - , universal_newlines = True , **kwargs ) out, err = proc.communicate() - if err: - self.warn(err) + + out, err = codecs.decode(out, 'utf-8'), codecs.decode(err, 'utf-8') + if proc.returncode != 0: raise self.severe( u"command '%s' failed with return code %d"
@@ -129,7 +123,7 @@ class KernelCmd(Directive): except OSError as exc: raise self.severe(u"problems with '%s' directive: %s." % (self.name, ErrorString(exc))) - return unicode(out) + return out def nestedParse(self, lines, fname): content = ViewList()
Signature · 1 line
2.21.0
PATCH v2 15/22 sphinx/kernel_abi.py: make it compatible with Sphinx 1.7+
In reply to Mauro Carvalho ChehabThe same way kerneldoc.py needed changes to work with newer Sphinx, this script needs the same changes.
While here, reorganize the include order to match kerneldoc.py.
--- Documentation/sphinx/kernel_abi.py | 39 +++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 12 deletions(-)
Documentation/sphinx/kernel_abi.py +27 -12
@@ -30,18 +30,27 @@ u""" """ import codecs -import sys import os -from os import path import subprocess +import sys -from sphinx.ext.autodoc import AutodocReporter +from os import path -from docutils import nodes -from docutils.parsers.rst import Directive, directives +from docutils import nodes, statemachine from docutils.statemachine import ViewList +from docutils.parsers.rst import directives, Directive from docutils.utils.error_reporting import ErrorString +# +# AutodocReporter is only good up to Sphinx 1.7 +# +import sphinx + +Use_SSI = sphinx.__version__[:3] >= '1.7' +if Use_SSI: + from sphinx.util.docutils import switch_source_input +else: + from sphinx.ext.autodoc import AutodocReporter __version__ = '1.0'
@@ -139,11 +148,17 @@ class KernelCmd(Directive): content.append(l, fname, c) buf = self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter - self.state.memo.title_styles = [] - self.state.memo.section_level = 0 - self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter) - try: - self.state.nested_parse(content, 0, node, match_titles=1) - finally: - self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf + + if Use_SSI: + with switch_source_input(self.state, content): + self.state.nested_parse(content, 0, node, match_titles=1) + else: + self.state.memo.title_styles = [] + self.state.memo.section_level = 0 + self.state.memo.reporter = AutodocReporter(content, self.state.memo.reporter) + try: + self.state.nested_parse(content, 0, node, match_titles=1) + finally: + self.state.memo.title_styles, self.state.memo.section_level, self.state.memo.reporter = buf + return node.children
Signature · 1 line
2.21.0
PATCH v2 16/22 docs: Kconfig/Makefile: add a check for broken ABI files
In reply to Mauro Carvalho ChehabThe files under Documentation/ABI should follow the syntax as defined at Documentation/ABI/README.
Allow checking if they're following the syntax by running the ABI parser script on COMPILE_TEST.
With that, when there's a problem with a file under Documentation/ABI, it would produce a warning like:
Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#14:
What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor' doesn't have a description
Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#21:
What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal' doesn't have a description
--- Documentation/Kconfig | 11 +++++++++++ Documentation/Makefile | 5 +++++ lib/Kconfig.debug | 2 ++ scripts/get_abi.pl | 14 +++++++++++--- 4 files changed, 29 insertions(+), 3 deletions(-) create mode 100644 Documentation/Kconfig
Documentation/Kconfig new file +11 -0
@@ -0,0 +1,11 @@ +config WARN_ABI_ERRORS + bool "Warn if there are errors at ABI files" + depends on COMPILE_TEST + help + The files under Documentation/ABI should follow what's + described at Documentation/ABI/README. Yet, as they're manually + written, it would be possible that some of those files would + have errors that would break them for being parsed by + scripts/get_abi.pl. Add a check to verify them. + + If unsure, select 'N'.
Documentation/Makefile +5 -0
@@ -4,6 +4,11 @@ subdir-y := devicetree/bindings/ +# Check for broken ABI files +ifeq ($(CONFIG_WARN_ABI_ERRORS),y) +$(shell $(srctree)/scripts/get_abi.pl validate --dir $(srctree)/Documentation/ABI) +endif + # You can set these variables from the command line. SPHINXBUILD = sphinx-build SPHINXOPTS =
lib/Kconfig.debug +2 -0
@@ -2110,4 +2110,6 @@ config IO_STRICT_DEVMEM source "arch/$(SRCARCH)/Kconfig.debug" +source "Documentation/Kconfig" + endmenu # Kernel hacking
scripts/get_abi.pl +11 -3
@@ -38,7 +38,15 @@ my %data; sub parse_error($$$$) { my ($file, $ln, $msg, $data) = @_; - print STDERR "file $file#$ln: $msg at\n\t$data"; + $data =~ s/\s+$/\n/; + + print STDERR "Warning: file $file#$ln:\n\t$msg"; + + if ($data ne "") { + print STDERR ". Line\n\t\t$data"; + } else { + print STDERR "\n"; + } } #
@@ -94,7 +102,7 @@ sub parse_abi { # Invalid, but it is a common mistake if ($new_tag eq "where") { - parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", $_); + parse_error($file, $ln, "tag 'Where' is invalid. Should be 'What:' instead", ""); $new_tag = "what"; }
@@ -190,7 +198,7 @@ sub parse_abi { } # Everything else is error - parse_error($file, $ln, "Unexpected line:", $_); + parse_error($file, $ln, "Unexpected content", $_); } $data{$nametag}->{description} =~ s/^\n+//; close IN;
Signature · 1 line
2.21.0
PATCH v2 17/22 docs: kernel_abi.py: Update copyrights
In reply to Mauro Carvalho ChehabAs Markus doesn't want to maintain ths file, update it to put me as its maintainer.
--- Documentation/sphinx/kernel_abi.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
Documentation/sphinx/kernel_abi.py +2 -1
@@ -7,7 +7,8 @@ u""" Implementation of the ``kernel-abi`` reST-directive. :copyright: Copyright (C) 2016 Markus Heiser - :copyright: Copyright (C) 2016 Mauro Carvalho Chehab + :copyright: Copyright (C) 2016-2019 Mauro Carvalho Chehab + :maintained-by: Mauro Carvalho Chehab <[email protected]> :license: GPL Version 2, June 1991 see Linux/COPYING for details. The ``kernel-abi`` (:py:class:`KernelCmd`) directive calls the
Signature · 1 line
2.21.0
PATCH v2 18/22 doc: ABI scripts: add a SPDX header file
In reply to Mauro Carvalho ChehabBoth are released under GPL v2.
--- Documentation/sphinx/kernel_abi.py | 1 + scripts/get_abi.pl | 1 + 2 files changed, 2 insertions(+)
Documentation/sphinx/kernel_abi.py +1 -0
@@ -1,4 +1,5 @@ # coding=utf-8 +# SPDX-License-Identifier: GPL-2.0 # u""" kernel-abi
scripts/get_abi.pl +1 -0
@@ -1,4 +1,5 @@ #!/usr/bin/perl +# SPDX-License-Identifier: GPL-2.0 use strict; use Pod::Usage;
Signature · 1 line
2.21.0
PATCH v2 19/22 scripts: add a script to handle Documentation/features
In reply to Mauro Carvalho ChehabThe Documentation/features contains a set of parseable files. It is not worth converting them to ReST format, as they're useful the way it is. It is, however, interesting to parse them and produce output on different formats:
1) Output the contents of a feature in ReST format;
2) Output what features a given architecture supports;
3) Output a matrix with features x architectures.
--- scripts/get_feat.pl | 472 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 472 insertions(+) create mode 100755 scripts/get_feat.pl
scripts/get_feat.pl new file +472 -0
@@ -0,0 +1,472 @@ +#!/usr/bin/perl +# SPDX-License-Identifier: GPL-2.0 + +use strict; +use Pod::Usage; +use Getopt::Long; +use File::Find; +use Fcntl ':mode'; + +my $help; +my $man; +my $debug; +my $arch; +my $feat; +my $prefix="Documentation/features"; + +GetOptions( + "debug|d+" => \$debug, + "dir=s" => \$prefix, + 'help|?' => \$help, + 'arch=s' => \$arch, + 'feat=s' => \$feat, + man => \$man +) or pod2usage(2); + +pod2usage(1) if $help; +pod2usage(-exitstatus => 0, -verbose => 2) if $man; + +pod2usage(2) if (scalar @ARGV < 1 || @ARGV > 2); + +my ($cmd, $arg) = @ARGV; + +pod2usage(2) if ($cmd ne "current" && $cmd ne "rest" && $cmd ne "validate"); + +require Data::Dumper if ($debug); + +my %data; +my %archs; + +# +# Displays an error message, printing file name and line +# +sub parse_error($$$$) { + my ($file, $ln, $msg, $data) = @_; + + $data =~ s/\s+$/\n/; + + print STDERR "Warning: file $file#$ln:\n\t$msg"; + + if ($data ne "") { + print STDERR ". Line\n\t\t$data"; + } else { + print STDERR "\n"; + } +} + +# +# Parse a features file, storing its contents at %data +# + +my $h_name = "Feature"; +my $h_kconfig = "Kconfig"; +my $h_description = "Description"; +my $h_subsys = "Subsystem"; +my $h_status = "Status"; +my $h_arch = "Architecture"; + +my $max_size_name = length($h_name); +my $max_size_kconfig = length($h_kconfig); +my $max_size_description = length($h_description); +my $max_size_subsys = length($h_subsys); +my $max_size_status = length($h_status); +my $max_size_arch = length($h_arch); + +sub parse_feat { + my $file = $File::Find::name; + + my $mode = (stat($file))[2]; + return if ($mode & S_IFDIR); + return if ($file =~ m,($prefix)/arch-support.txt,); + return if (!($file =~ m,arch-support.txt$,)); + + my $subsys = ""; + $subsys = $2 if ( m,.*($prefix)/([^/]+).*,); + + if (length($subsys) > $max_size_subsys) { + $max_size_subsys = length($subsys); + } + + my $name; + my $kconfig; + my $description; + my $comments = ""; + my $last_status; + my $ln; + my %arch_table; + + print STDERR "Opening $file\n" if ($debug > 1); + open IN, $file; + + while(<IN>) { + $ln++; + + if (m/^\#\s+Feature\s+name:\s*(.*\S)/) { + $name = $1; + if (length($name) > $max_size_name) { + $max_size_name = length($name); + } + next; + } + if (m/^\#\s+Kconfig:\s*(.*\S)/) { + $kconfig = $1; + if (length($kconfig) > $max_size_kconfig) { + $max_size_kconfig = length($kconfig); + } + next; + } + if (m/^\#\s+description:\s*(.*\S)/) { + $description = $1; + if (length($description) > $max_size_description) { + $max_size_description = length($description); + } + next; + } + next if (m/^\\s*$/); + next if (m/^\s*\-+\s*$/); + next if (m/^\s*\|\s*arch\s*\|\s*status\s*\|\s*$/); + + if (m/^\#\s*(.*)/) { + $comments .= "$1\n"; + next; + } + if (m/^\s*\|\s*(\S+):\s*\|\s*(\S+)\s*\|\s*$/) { + my $a = $1; + my $status = $2; + + if (length($status) > $max_size_status) { + $max_size_status = length($status); + } + if (length($a) > $max_size_arch) { + $max_size_arch = length($a); + } + + $archs{$a} = 1; + $arch_table{$a} = $status; + next; + } + + #Everything else is an error + parse_error($file, $ln, "line is invalid", $_); + } + close IN; + + if (!$name) { + parse_error($file, $ln, "Feature name not found", ""); + return; + } + + parse_error($file, $ln, "Subsystem not found", "") if (!$subsys); + parse_error($file, $ln, "Kconfig not found", "") if (!$kconfig); + parse_error($file, $ln, "Description not found", "") if (!$description); + + if (!%arch_table) { + parse_error($file, $ln, "Architecture table not found", ""); + return; + } + + $data{$name}->{where} = $file; + $data{$name}->{subsys} = $subsys; + $data{$name}->{kconfig} = $kconfig; + $data{$name}->{description} = $description; + $data{$name}->{comments} = $comments; + $data{$name}->{table} = \%arch_table; +} + +# +# Output feature(s) for a given architecture +# +sub output_arch_table { + my $title = "Feature status on $arch architecture"; + + print "=" x length($title) . "\n"; + print "$title\n"; + print "=" x length($title) . "\n\n"; + + print "=" x $max_size_subsys; + print " "; + print "=" x $max_size_name; + print " "; + print "=" x $max_size_kconfig; + print " "; + print "=" x $max_size_status; + print " "; + print "=" x $max_size_description; + print "\n"; + printf "%-${max_size_subsys}s ", $h_subsys; + printf "%-${max_size_name}s ", $h_name; + printf "%-${max_size_kconfig}s ", $h_kconfig; + printf "%-${max_size_status}s ", $h_status; + printf "%-${max_size_description}s\n", $h_description; + print "=" x $max_size_subsys; + print " "; + print "=" x $max_size_name; + print " "; + print "=" x $max_size_kconfig; + print " "; + print "=" x $max_size_status; + print " "; + print "=" x $max_size_description; + print "\n"; + + foreach my $name (sort { + ($data{$a}->{subsys} cmp $data{$b}->{subsys}) || + ($data{$a}->{name} cmp $data{$b}->{name}) + } keys %data) { + next if ($feat && $name ne $feat); + + my %arch_table = %{$data{$name}->{table}}; + printf "%-${max_size_subsys}s ", $data{$name}->{subsys}; + printf "%-${max_size_name}s ", $name; + printf "%-${max_size_kconfig}s ", $data{$name}->{kconfig}; + printf "%-${max_size_status}s ", $arch_table{$arch}; + printf "%-${max_size_description}s\n", $data{$name}->{description}; + } + + print "=" x $max_size_subsys; + print " "; + print "=" x $max_size_name; + print " "; + print "=" x $max_size_kconfig; + print " "; + print "=" x $max_size_status; + print " "; + print "=" x $max_size_description; + print "\n"; +} + +# +# Output a feature on all architectures +# +sub output_feature { + my $title = "Feature $feat"; + + print "=" x length($title) . "\n"; + print "$title\n"; + print "=" x length($title) . "\n\n"; + + print ":Subsystem: $data{$feat}->{subsys} \n" if ($data{$feat}->{subsys}); + print ":Kconfig: $data{$feat}->{kconfig} \n" if ($data{$feat}->{kconfig}); + + my $desc = $data{$feat}->{description}; + $desc =~ s/^([a-z])/\U$1/; + $desc =~ s/\.?\s*//; + print "\n$desc.\n\n"; + + my $com = $data{$feat}->{comments}; + $com =~ s/^\s+//; + $com =~ s/\s+$//; + if ($com) { + print "Comments\n"; + print "--------\n\n"; + print "$com\n\n"; + } + + print "=" x $max_size_arch; + print " "; + print "=" x $max_size_status; + print "\n"; + + printf "%-${max_size_arch}s ", $h_arch; + printf "%-${max_size_status}s", $h_status . "\n"; + + print "=" x $max_size_arch; + print " "; + print "=" x $max_size_status; + print "\n"; + + my %arch_table = %{$data{$feat}->{table}}; + foreach my $arch (sort keys %arch_table) { + printf "%-${max_size_arch}s ", $arch; + printf "%-${max_size_status}s\n", $arch_table{$arch}; + } + + print "=" x $max_size_arch; + print " "; + print "=" x $max_size_status; + print "\n"; +} + +# +# Output all features for all architectures +# + +sub matrix_lines { + print "=" x $max_size_subsys; + print " "; + print "=" x $max_size_name; + print " "; + + foreach my $arch (sort keys %archs) { + my $len = $max_size_status; + + $len = length($arch) if ($len < length($arch)); + + print "=" x $len; + print " "; + } + print "=" x $max_size_kconfig; + print " "; + print "=" x $max_size_description; + print "\n"; +} + +sub output_matrix { + + my $title = "Feature List (feature x architecture)"; + + print "=" x length($title) . "\n"; + print "$title\n"; + print "=" x length($title) . "\n\n"; + + matrix_lines; + + printf "%-${max_size_subsys}s ", $h_subsys; + printf "%-${max_size_name}s ", $h_name; + + foreach my $arch (sort keys %archs) { + printf "%-${max_size_status}s ", $arch; + } + printf "%-${max_size_kconfig}s ", $h_kconfig; + printf "%-${max_size_description}s\n", $h_description; + + matrix_lines; + + foreach my $name (sort { + ($data{$a}->{subsys} cmp $data{$b}->{subsys}) || + ($data{$a}->{name} cmp $data{$b}->{name}) + } keys %data) { + printf "%-${max_size_subsys}s ", $data{$name}->{subsys}; + printf "%-${max_size_name}s ", $name; + + my %arch_table = %{$data{$name}->{table}}; + + foreach my $arch (sort keys %arch_table) { + my $len = $max_size_status; + + $len = length($arch) if ($len < length($arch)); + + printf "%-${len}s ", $arch_table{$arch}; + } + printf "%-${max_size_kconfig}s ", $data{$name}->{kconfig}; + printf "%-${max_size_description}s\n", $data{$name}->{description}; + } + + matrix_lines; +} + + +# +# Parses all feature files located at $prefix dir +# +find({wanted =>\&parse_feat, no_chdir => 1}, $prefix); + +print STDERR Data::Dumper->Dump([\%data], [qw(*data)]) if ($debug); + +# +# Handles the command +# +if ($cmd eq "current") { + $arch = qx(uname -m | sed 's/x86_64/x86/' | sed 's/i386/x86/'); + $arch =~s/\s+$//; +} + +if ($cmd ne "validate") { + if ($arch) { + output_arch_table; + } elsif ($feat) { + output_feature; + } else { + output_matrix; + } +} + +__END__ + +=head1 NAME + +get_feat.pl - parse the Linux Feature files and produce a ReST book. + +=head1 SYNOPSIS + +B<get_feat.pl> [--debug] [--man] [--help] [--dir=<dir>] + [--arch=<arch>] [--feat=<feature>] <COMAND> [<ARGUMENT>] + +Where <COMMAND> can be: + +=over 8 + +B<current> - output features for this machine's architecture + +B<rest> - output features in ReST markup language + +B<validate> - validate the feature contents + +=back + +=head1 OPTIONS + +=over 8 + +=item B<--arch> + +Output features for an specific architecture, optionally filtering for +a single specific feature. + +=item B<--feat> + +Output features for a single specific architecture. + +=item B<--dir> + +Changes the location of the Feature files. By default, it uses +the Documentation/features directory. + +=item B<--debug> + +Put the script in verbose mode, useful for debugging. Can be called multiple +times, to increase verbosity. + +=item B<--help> + +Prints a brief help message and exits. + +=item B<--man> + +Prints the manual page and exits. + +=back + +=head1 DESCRIPTION + +Parse the Linux feature files from Documentation/features (by default), +optionally producing results at ReST format. + +It supports output data per architecture, per feature or a +feature x arch matrix. + +When used with B<rest> command, it will use either one of the tree formats: + +If neither B<--arch> or B<--feature> arguments are used, it will output a +matrix with features per architecture. + +If B<--arch> argument is used, it will output the features availability for +a given architecture. + +If B<--feat> argument is used, it will output the content of the feature +file using ReStructured Text markup. + +=head1 BUGS + +Report bugs to Mauro Carvalho Chehab <[email protected]> + +=head1 COPYRIGHT + +Copyright (c) 2019 by Mauro Carvalho Chehab <[email protected]>. + +License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl.html>. + +This is free software: you are free to change and redistribute it. +There is NO WARRANTY, to the extent permitted by law. + +=cut
Signature · 1 line
2.21.0
PATCH v2 20/22 docs: admin-guide, x86: add a features list
In reply to Mauro Carvalho ChehabAdd a feature list matrix at the admin-guide and a x86-specific feature list to the respective Kernel books.
--- Documentation/admin-guide/features.rst | 3 + Documentation/admin-guide/index.rst | 1 + Documentation/conf.py | 2 +- Documentation/sphinx/kernel_feat.py | 169 +++++++++++++++++++++++++ Documentation/x86/features.rst | 3 + Documentation/x86/index.rst | 1 + 6 files changed, 178 insertions(+), 1 deletion(-) create mode 100644 Documentation/admin-guide/features.rst create mode 100644 Documentation/sphinx/kernel_feat.py create mode 100644 Documentation/x86/features.rst
Documentation/admin-guide/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features
Documentation/admin-guide/index.rst +1 -0
@@ -17,6 +17,7 @@ etc. kernel-parameters devices abi + features This section describes CPU vulnerabilities and their mitigations.
Documentation/conf.py +1 -1
@@ -34,7 +34,7 @@ needs_sphinx = '1.3' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure', 'sphinx.ext.ifconfig', 'kernel_abi'] +extensions = ['kerneldoc', 'rstFlatTable', 'kernel_include', 'cdomain', 'kfigure', 'sphinx.ext.ifconfig', 'kernel_abi', 'kernel_feat'] # The name of the math extension changed on Sphinx 1.4 if (major == 1 and minor > 3) or (major > 1):
Documentation/sphinx/kernel_feat.py new file +169 -0
169 lines not on this page · raw message
Documentation/x86/features.rst new file +3 -0
@@ -0,0 +1,3 @@ +.. SPDX-License-Identifier: GPL-2.0 + +.. kernel-feat:: $srctree/Documentation/features x86
Documentation/x86/index.rst +1 -0
@@ -29,3 +29,4 @@ x86-specific Documentation usb-legacy-support i386/index x86_64/index + features
Signature · 1 line
2.21.0
PATCH v2 21/22 scripts/get_feat.pl: handle ".." special case
In reply to Mauro Carvalho ChehabThe status ".." Means that the feature can't be implemented on a given architecture.
The problem is that this doesn't show anything at the output, so replace it by "---", with is a markup for a long hyphen.
--- scripts/get_feat.pl | 2 ++ 1 file changed, 2 insertions(+)
scripts/get_feat.pl +2 -0
@@ -141,6 +141,8 @@ sub parse_feat { $max_size_arch = length($a); } + $status = "---" if ($status =~ m/^\.\.$/); + $archs{$a} = 1; $arch_table{$a} = $status; next;
Signature · 1 line
2.21.0
PATCH v2 22/22 scripts/get_abi.pl: change script to allow parsing in ReST mode
In reply to Mauro Carvalho ChehabRight now, several ABI files won't parse as ReST, as they contain severe violations to the spec, with makes the script to crash.
So, the code has a sanity logic with escapes bad code and cleans tags that can cause Sphinx to crash.
Add support for disabling this mode.
Right now, as enabling rst-mode causes crash, it is disabled by default.
--- scripts/get_abi.pl | 74 ++++++++++++++++++++++++++++++---------------- 1 file changed, 48 insertions(+), 26 deletions(-)
scripts/get_abi.pl +48 -26
@@ -12,8 +12,14 @@ my $man; my $debug; my $prefix="Documentation/ABI"; +# +# If true, assumes that the description is formatted with ReST +# +my $description_is_rst = 0; + GetOptions( "debug|d+" => \$debug, + "rst-source!" => \$description_is_rst, "dir=s" => \$prefix, 'help|?' => \$help, man => \$man
@@ -145,14 +151,15 @@ sub parse_abi { next; } if ($tag eq "description") { - next if ($content =~ m/^\s*$/); - if ($content =~ m/^(\s*)(.*)/) { - my $new_content = $2; - $space = $new_tag . $sep . $1; - while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} - $space =~ s/./ /g; - $data{$what}->{$tag} .= "$new_content\n"; + # Preserve initial spaces for the first line + $content = ' ' x length($new_tag) . $sep . $content; + $content =~ s,^(\s*):,$1 ,; + if ($content =~ m/^(\s*)(.*)$/) { + $space = $1; + $content = $2; } + while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} + $data{$what}->{$tag} .= $content; } else { $data{$what}->{$tag} = $content; }
@@ -168,11 +175,15 @@ sub parse_abi { if ($tag eq "description") { if (!$data{$what}->{description}) { - next if (m/^\s*\n/); + s/^($space)//; if (m/^(\s*)(.*)/) { - $space = $1; - while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} - $data{$what}->{$tag} .= "$2\n"; + my $sp = $1; + while ($sp =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {} + my $content = "$sp$2"; + + $content =~ s/^($space)//; + + $data{$what}->{$tag} .= "$content"; } } else { my $content = $_;
@@ -282,23 +293,27 @@ sub output_rest { print "Defined on file :ref:`$file <$fileref>`\n\n" if ($type ne "File"); my $desc = $data{$what}->{description}; - $desc =~ s/^\s+//; - - # Remove title markups from the description, as they won't work - $desc =~ s/\n[\-\*\=\^\~]+\n/\n/g; if (!($desc =~ /^\s*$/)) { - if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) { - # put everything inside a code block - $desc =~ s/\n/\n /g; - - print "::\n\n"; - print " $desc\n\n"; - } else { - # Escape any special chars from description - $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g; - + if ($description_is_rst) { print "$desc\n\n"; + } else { + $desc =~ s/^\s+//; + + # Remove title markups from the description, as they won't work + $desc =~ s/\n[\-\*\=\^\~]+\n/\n\n/g; + + if ($desc =~ m/\:\n/ || $desc =~ m/\n[\t ]+/ || $desc =~ m/[\x00-\x08\x0b-\x1f\x7b-\xff]/) { + # put everything inside a code block + $desc =~ s/\n/\n /g; + + print "::\n\n"; + print " $desc\n\n"; + } else { + # Escape any special chars from description + $desc =~s/([\x00-\x08\x0b-\x1f\x21-\x2a\x2d\x2f\x3c-\x40\x5c\x5e-\x60\x7b-\xff])/\\$1/g; + print "$desc\n\n"; + } } } else { print "DESCRIPTION MISSING for $what\n\n" if (!$data{$what}->{is_file});
@@ -390,7 +405,7 @@ abi_book.pl - parse the Linux ABI files and produce a ReST book. =head1 SYNOPSIS -B<abi_book.pl> [--debug] [--man] [--help] [--dir=<dir>] <COMAND> [<ARGUMENT>] +B<abi_book.pl> [--debug] [--man] [--help] --[(no-)rst-source] [--dir=<dir>] <COMAND> [<ARGUMENT>] Where <COMMAND> can be:
@@ -413,6 +428,13 @@ B<validate> - validate the ABI contents Changes the location of the ABI search. By default, it uses the Documentation/ABI directory. +=item B<--rst-source> and B<--no-rst-source> + +The input file may be using ReST syntax or not. Those two options allow +selecting between a rst-compliant source ABI (--rst-source), or a +plain text that may be violating ReST spec, so it requres some escaping +logic (--no-rst-source). + =item B<--debug> Put the script in verbose mode, useful for debugging. Can be called multiple
Signature · 1 line
2.21.0
Quoted 6 lines · Mauro Carvalho Chehab
This is a rebased version of the scripts with parse
Documentation/ABIandDocumentation/featurefiles and produce a ReST output. Those scripts are added to the Kernel building system, in order to output their contents inside the Kernel documentation.
Quoted 7 lines
Please notice that, as discussed, I added support at get_abi.pl to handle ABI files as if they're compatible with ReST. Right now, this feature can't be enabled for normal builds, as it will cause Sphinx crashes. After getting the offending ABI files fixed, a single line change will be enough to make it default.
a version "0" was sent back on 2017.
Ok, I added the first chunk of these patches to my tree, that add the get_abi.pl file to the tree. I didn't touch the others that touched the documentation build or other scripts just yet, as I wanted to get others to agree with them before accepting them.
Or we can just wait until after 5.3-rc1 is out and then the rest can go through the documentation tree.
thanks,
greg k-h
Em Fri, 21 Jun 2019 17:04:45 +0200
Greg KH <[email protected]> escreveu:
Quoted 15 lines · Mauro Carvalho Chehab
Quoted 6 lines
This is a rebased version of the scripts with parse
Documentation/ABIandDocumentation/featurefiles and produce a ReST output. Those scripts are added to the Kernel building system, in order to output their contents inside the Kernel documentation.Quoted 7 lines
Please notice that, as discussed, I added support at get_abi.pl to handle ABI files as if they're compatible with ReST. Right now, this feature can't be enabled for normal builds, as it will cause Sphinx crashes. After getting the offending ABI files fixed, a single line change will be enough to make it default.
a version "0" was sent back on 2017.
Quoted 7 lines
Ok, I added the first chunk of these patches to my tree, that add the get_abi.pl file to the tree. I didn't touch the others that touched the documentation build or other scripts just yet, as I wanted to get others to agree with them before accepting them.
Or we can just wait until after 5.3-rc1 is out and then the rest can go through the documentation tree.
Ok.
Whatever works best for you and Jon.
I'm keeping a tree with the remaining patches on the top of driver-core-next at:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=abi_patches_v4.2
I'll rebase it on the top of yours as new patches get merged there, or if I develop more patches related to it (I may try to fix the ReST issues with the files at ABI/testing if I have some spare time).
Note that it contains the RFC patches for parsing ABI files as-is, with ReST markups on them, if needed.
If you want to pick the hole thing including the RFC ones, there's one patch there with probably needs to be either split and/or submitted to ABI file authors:
https://git.linuxtv.org/mchehab/experimental.git/commit/?h=abi_patches_v4.2&id=58f73907d21f1c93038196c42dab65be969f4104
Thanks,
Mauro