[RFC,00/10] Improve ABI documentation generation

Message

Mauro Carvalho Chehab Jan. 17, 2025, 5:59 p.m. UTC

Hi Jon/Greg,

The main goal of this RFC is to give a heads up of a work I've been doing to
replace the get_abi.pl script with a python version.

Patches 1-6 are OK to be applied:
- Patch 1 changes the sort criteria of the ABI generation to use alphabetic order:
  currently, it is *almost* alphabetic, but, on some cases, it orders on a different
  way. No changes at the content, just at the order. 
  I wrote it mainly to use the same sort criteria as the new tool, but IMO it is
  worth applying even before we switch to the python version.

- Patches 2-6 fix some ABI tag problems. They're independent of the rest and
  can also be applied without  other patches on this series.

The remaining patches (7-10) are RFC for a new tool.

The new tool uses a cleaned-up version of the same algorithms I wrote in Perl,
re-writen in Python. While doing the conversion, I got rid of some stuff that aren't
needed anymore.

The new tool has two additional changes:
- the validate tool now detects a duplicate definition when files with the same name
  exists on different parts of the ABI documentation (if one asks to build them altogether);
- it fixes a bug on one of the files whose "what" keys weren't properly parsed.

Patches 7 and 8 are already in good shape (IMHO).

Patch 9 replaces "get_abi.pl" by "get_abi.py" exec for htmldocs/pdfdocs targets.
It is not on its final shape, as my end goal is to do a python include and use the
class directly there instead of calling an exec file, but such change will require
some work (I'll likely implement an interactor at the class instead of just returning
a big amount of text).

Patch 10 is just a boilerplate to one additional functionality of the perl script that
would require a lot of work to implement: check undefined/bad defined symbols
at the local machine's sysfs and compare with ABI.

Before getting patches 7-10 merged, I'd like to implement patch 10. This may
take some time, as the ABI check there is not the simplest code I wrote.

Yet, I'd like to get some feedback about patches 7-9 while I'm working on 
patch 10, so, let me send what I have so far as a RFC.

I hope this would make more people look at the code, as right now, we had only
6 persons/6 patches besides me that touched the code.

Mauro Carvalho Chehab (10):
  scripts/get_abi.pl use label to better sort ABI symbols and files
  ABI: sysfs-class-rfkill: fix kernelversion tags
  ABI: sysfs-bus-coresight-*: fix kernelversion tags
  ABI: sysfs-driver-dma-idxd: fix date tags
  ABI: sysfs-fs-f2fs: fix date tags
  ABI: sysfs-power: fix a what tag
  [RFC] scripts: add a get_abi.py tool to generate ReST output
  [RFC] scripts/get_abi.py: add support for symbol search
  [RFC] docs: use get_abi.py for ABI generation
  [RFC BOILERPLATE] scripts/get_abi.py: add support for undefined ABIs

 Documentation/ABI/removed/sysfs-class-rfkill  |   2 +-
 Documentation/ABI/stable/sysfs-class-rfkill   |  12 +-
 .../ABI/stable/sysfs-driver-dma-idxd          |   4 +-
 .../testing/sysfs-bus-coresight-devices-cti   |  78 +-
 .../testing/sysfs-bus-coresight-devices-tpdm  |  52 +-
 Documentation/ABI/testing/sysfs-fs-f2fs       |   4 +-
 Documentation/ABI/testing/sysfs-power         |   2 +-
 Documentation/admin-guide/abi-obsolete.rst    |   1 -
 Documentation/admin-guide/abi-removed.rst     |   1 -
 Documentation/admin-guide/abi-stable.rst      |   1 -
 Documentation/admin-guide/abi-testing.rst     |   1 -
 Documentation/sphinx/kernel_abi.py            |  10 +-
 scripts/get_abi.pl                            |   3 +-
 scripts/get_abi.py                            | 678 ++++++++++++++++++
 14 files changed, 760 insertions(+), 89 deletions(-)
 create mode 100755 scripts/get_abi.py