Re: [PATCH v2 0/7] Fix some issues at get_abi.pl script

2021-03-31 Thread Jonathan Corbet 
Mauro Carvalho Chehab  writes:

> This series replace this patch:
>   https://lore.kernel.org/linux-doc/20210324191722.08d35...@coco.lan/T/#t
>
> It turns that there were multiple bugs at the get_abi.pl code that
> create cross-references.
>
> Patches 1 to 6 fix those issues, and should apply cleanly on the top of
> the docs tree (although I tested against next-20210323).
>
> Patch 7 is optional, and independent from the other patches. It is meant
> to be applied against akpm's tree.  It makes the description (IMHO) 
> clearer, while producing cross references for the two mentioned symbols.

I've gone ahead and applied the set, with the exception of #7 which
doesn't apply here.

Thanks,

jon

Re: [PATCH v2 0/7] Fix some issues at get_abi.pl script

2021-03-25 Thread Mauro Carvalho Chehab 
Em Thu, 25 Mar 2021 13:01:14 -0600
Jonathan Corbet  escreveu:

> Mauro Carvalho Chehab  writes:
> 
> > This series replace this patch:
> > https://lore.kernel.org/linux-doc/20210324191722.08d35...@coco.lan/T/#t
> >
> > It turns that there were multiple bugs at the get_abi.pl code that
> > create cross-references.
> >
> > Patches 1 to 6 fix those issues, and should apply cleanly on the top of
> > the docs tree (although I tested against next-20210323).
> >
> > Patch 7 is optional, and independent from the other patches. It is meant
> > to be applied against akpm's tree.  It makes the description (IMHO) 
> > clearer, while producing cross references for the two mentioned symbols.  
> 
> So perhaps this is the best solution to the problem, but I must confess
> to not being entirely happy with it.  get_abi.pl is becoming another
> unreadable perlpile like kerneldoc, and this makes it worse.  Doing RST
> parsing there seems particularly unwelcome.

Nah, it is not that complex ;-) 
It has 628 lines of code; kernel-doc has 2488. It is 1/4 the size of
kernel-doc :-D

Btw, 20 lines can be removed from it, if we drop support for --no-rst-source. 
I almost dropped it this time :-)

Ah, the entire code that outputs the rst description and does the
xref has just 34 lines (with 5 lines with comments and 5 blank lines).

It is not much, and some cleanups could be done to make it a little
shorter.

Most of the script complexity is actually at the parsing part. The
thing is that the ABI files are somewhat free-style: some files 
don't strictly follow the format, which requires some extra steps in
order to cope with some "soft" violations, as well as to report
problems when the violation is more severe.

> Should the cross-reference generation, it now occurs to me, be done in
> the automarkup module instead?  Then there's no need to interpret RST,
> and we'd get cross-references throughout the kernel docs rather than in
> just the ABI stuff.  Am I completely out to lunch here?

Yes, I guess we can move the Xref code to automarkup some day,
that is if we can ensure that get_abi.pl will run before automarkup.

There's currently an issue, though. We need first to get rid of those
duplicated symbols:

Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias is 
defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:0  
Documentation/ABI/testing/sysfs-bus-iio:395
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias is 
defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:1  
Documentation/ABI/testing/sysfs-bus-iio:396
Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias is 
defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:2  
Documentation/ABI/testing/sysfs-bus-iio:397
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias is 
defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:3  
Documentation/ABI/testing/sysfs-bus-iio:398
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias is 
defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:4  
Documentation/ABI/testing/sysfs-bus-iio:399
Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias is 
defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-icm42600:5  
Documentation/ABI/testing/sysfs-bus-iio:400
Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_preset is defined 2 
times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:100  
Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:0
Warning: 
/sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 
2 times:  Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2  
Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:8
Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency is 
defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:0  
Documentation/ABI/testing/sysfs-bus-iio:600
Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown is 
defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371:36  
Documentation/ABI/testing/sysfs-bus-iio:589
Warning: /sys/bus/iio/devices/iio:deviceX/out_currentY_raw is defined 2 
times:  Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als:43  
Documentation/ABI/testing/sysfs-bus-iio-health-afe440x:38
Warning: /sys/bus/iio/devices/iio:deviceX/out_current_heater_raw is 
defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:0  
Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:0
Warning: 
/sys/bus/iio/devices/iio:deviceX/out_current_heater_raw_available is defined 2 
times:  Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010:1  
Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:1
Warning: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity is defined 
2 times:

Re: [PATCH v2 0/7] Fix some issues at get_abi.pl script

2021-03-25 Thread Jonathan Corbet 
Mauro Carvalho Chehab  writes:

> This series replace this patch:
>   https://lore.kernel.org/linux-doc/20210324191722.08d35...@coco.lan/T/#t
>
> It turns that there were multiple bugs at the get_abi.pl code that
> create cross-references.
>
> Patches 1 to 6 fix those issues, and should apply cleanly on the top of
> the docs tree (although I tested against next-20210323).
>
> Patch 7 is optional, and independent from the other patches. It is meant
> to be applied against akpm's tree.  It makes the description (IMHO) 
> clearer, while producing cross references for the two mentioned symbols.

So perhaps this is the best solution to the problem, but I must confess
to not being entirely happy with it.  get_abi.pl is becoming another
unreadable perlpile like kerneldoc, and this makes it worse.  Doing RST
parsing there seems particularly unwelcome.

Should the cross-reference generation, it now occurs to me, be done in
the automarkup module instead?  Then there's no need to interpret RST,
and we'd get cross-references throughout the kernel docs rather than in
just the ABI stuff.  Am I completely out to lunch here?

Thanks,

jon

[PATCH v2 0/7] Fix some issues at get_abi.pl script

2021-03-25 Thread Mauro Carvalho Chehab 
This series replace this patch:
https://lore.kernel.org/linux-doc/20210324191722.08d35...@coco.lan/T/#t

It turns that there were multiple bugs at the get_abi.pl code that
create cross-references.

Patches 1 to 6 fix those issues, and should apply cleanly on the top of
the docs tree (although I tested against next-20210323).

Patch 7 is optional, and independent from the other patches. It is meant
to be applied against akpm's tree.  It makes the description (IMHO) 
clearer, while producing cross references for the two mentioned symbols.

The fix patches are:

patch 1: fix some regexes that match the symbols that need to be
  escaped when parsing "What:". The same regex is also used when
  generating cross-references;

patch 2: makes the check for Documentation/ABI references more
  robust, as right now, it stops at the first occurrence;

patch 3: fix the parser for /sys/foo -> xref conversion. Basically,
  the logic that seeks for start and end boundaries were broken.
  The new logic is a way more robust.

patch 4: generate cross-references for /config/foo and other less
  common ABI occurrences;

patch 5 and 6: don't generate cross-references inside literal blocks.
  Right now, there are a couple of places that would otherwise
  generate references, producing a bad output.

Mauro Carvalho Chehab (7):
  scripts: get_abi.pl: better handle escape chars on what:
  get_abi.pl: seek for all occurrences for Documentation/ABI
  get_abi.pl: fix xref boundaries
  scripts: get_abi.pl: extend xref match to other types
  scripts: get_abi.pl: parse description line per line
  scripts: get_abi: ignore code blocks for cross-references
  ABI: sysfs-kernel-mm-cma: fix two cross-references

 Documentation/ABI/testing/sysfs-kernel-mm-cma |  8 +-
 scripts/get_abi.pl| 76 +--
 2 files changed, 57 insertions(+), 27 deletions(-)

-- 
2.30.2