RE: [PATCH v2 31/39] docs: ABI: cleanup several ABI documents

RE: [PATCH v2 31/39] docs: ABI: cleanup several ABI documents

[Rojewski, Cezary]

On 2020-10-30 8:40 AM, Mauro Carvalho Chehab wrote:
> There are some ABI documents that, while they don't generate
> any warnings, they have issues when parsed by get_abi.pl script
> on its output result.
> 
> Address them, in order to provide a clean output.
> 
> Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> #for IIO
> Reviewed-by: Tom Rix <trix@redhat.com> # for fpga-manager
> Reviewed-By: Kajol Jain<kjain@linux.ibm.com> # for sysfs-bus-event_source-devices-hv_gpci and sysfs-bus-event_source-devices-hv_24x7
> Acked-by: Oded Gabbay <oded.gabbay@gmail.com> # for Habanalabs
> Acked-by: Vaibhav Jain <vaibhav@linux.ibm.com> # for sysfs-bus-papr-pmem
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---

sysfs-bus-pci-devices-catpt changes LGTM, thanks.

Acked-by: Cezary Rojewski <cezary.rojewski@intel.com> # for catpt

Regards,
Czarek

>   Documentation/ABI/obsolete/sysfs-class-dax    |   8 +-
>   .../ABI/obsolete/sysfs-driver-hid-roccat-pyra |   3 +
>   Documentation/ABI/removed/devfs               |   1 +
>   Documentation/ABI/removed/raw1394             |   1 +
>   Documentation/ABI/removed/sysfs-class-rfkill  |   2 +-
>   Documentation/ABI/removed/video1394           |   1 +
>   Documentation/ABI/stable/firewire-cdev        |  63 ++---
>   Documentation/ABI/stable/sysfs-acpi-pmprofile |   4 +-
>   Documentation/ABI/stable/sysfs-bus-w1         |   1 +
>   Documentation/ABI/stable/sysfs-class-tpm      |   4 +-
>   Documentation/ABI/stable/sysfs-driver-speakup |   4 +
>   Documentation/ABI/testing/configfs-most       | 135 +++++++----
>   .../ABI/testing/configfs-usb-gadget-ecm       |  12 +-
>   .../ABI/testing/configfs-usb-gadget-eem       |  10 +-
>   .../ABI/testing/configfs-usb-gadget-loopback  |   6 +-
>   .../testing/configfs-usb-gadget-mass-storage  |  18 +-
>   .../ABI/testing/configfs-usb-gadget-midi      |  14 +-
>   .../ABI/testing/configfs-usb-gadget-printer   |   6 +-
>   .../testing/configfs-usb-gadget-sourcesink    |  18 +-
>   .../ABI/testing/configfs-usb-gadget-subset    |  10 +-
>   .../ABI/testing/configfs-usb-gadget-uac2      |  14 +-
>   .../ABI/testing/configfs-usb-gadget-uvc       |   2 +-
>   .../ABI/testing/debugfs-cec-error-inj         |   2 +-
>   .../ABI/testing/debugfs-driver-habanalabs     |  12 +-
>   .../ABI/testing/debugfs-pfo-nx-crypto         |  28 +--
>   Documentation/ABI/testing/debugfs-pktcdvd     |   2 +-
>   .../ABI/testing/debugfs-turris-mox-rwtm       |  10 +-
>   Documentation/ABI/testing/debugfs-wilco-ec    |  21 +-
>   Documentation/ABI/testing/dell-smbios-wmi     |  32 +--
>   Documentation/ABI/testing/gpio-cdev           |  13 +-
>   Documentation/ABI/testing/procfs-diskstats    |   6 +-
>   Documentation/ABI/testing/procfs-smaps_rollup |  48 ++--
>   Documentation/ABI/testing/pstore              |  19 +-
>   Documentation/ABI/testing/sysfs-block-rnbd    |   4 +-
>   Documentation/ABI/testing/sysfs-bus-acpi      |   1 +
>   .../testing/sysfs-bus-coresight-devices-etb10 |   5 +-
>   Documentation/ABI/testing/sysfs-bus-css       |   3 +
>   Documentation/ABI/testing/sysfs-bus-dfl       |   2 +
>   .../sysfs-bus-event_source-devices-hv_24x7    |   6 +-
>   .../sysfs-bus-event_source-devices-hv_gpci    |   7 +-
>   Documentation/ABI/testing/sysfs-bus-fcoe      |  68 ++++--
>   Documentation/ABI/testing/sysfs-bus-fsl-mc    |  12 +-
>   .../ABI/testing/sysfs-bus-i2c-devices-fsa9480 |  26 +-
>   Documentation/ABI/testing/sysfs-bus-i3c       |   2 +
>   Documentation/ABI/testing/sysfs-bus-iio       |  19 +-
>   .../ABI/testing/sysfs-bus-iio-adc-hi8435      |   5 +
>   .../ABI/testing/sysfs-bus-iio-adc-stm32       |   3 +
>   .../ABI/testing/sysfs-bus-iio-distance-srf08  |   7 +-
>   .../testing/sysfs-bus-iio-frequency-ad9523    |   2 +
>   .../testing/sysfs-bus-iio-frequency-adf4371   |  10 +-
>   .../ABI/testing/sysfs-bus-iio-health-afe440x  |  12 +-
>   .../ABI/testing/sysfs-bus-iio-light-isl29018  |   6 +-
>   .../testing/sysfs-bus-intel_th-devices-gth    |  11 +-
>   Documentation/ABI/testing/sysfs-bus-papr-pmem |  23 +-
>   Documentation/ABI/testing/sysfs-bus-pci       |  22 +-
>   .../ABI/testing/sysfs-bus-pci-devices-catpt   |   1 +
>   .../testing/sysfs-bus-pci-drivers-ehci_hcd    |   4 +-
>   Documentation/ABI/testing/sysfs-bus-rbd       |  37 ++-
>   Documentation/ABI/testing/sysfs-bus-siox      |   3 +
>   .../ABI/testing/sysfs-bus-thunderbolt         |  18 +-
>   Documentation/ABI/testing/sysfs-bus-usb       |   2 +
>   .../sysfs-class-backlight-driver-lm3533       |  26 +-
>   Documentation/ABI/testing/sysfs-class-bdi     |   1 -
>   .../ABI/testing/sysfs-class-chromeos          |  15 +-
>   Documentation/ABI/testing/sysfs-class-cxl     |   8 +-
>   Documentation/ABI/testing/sysfs-class-devlink |  30 ++-
>   Documentation/ABI/testing/sysfs-class-extcon  |  34 +--
>   .../ABI/testing/sysfs-class-fpga-manager      |   5 +-
>   Documentation/ABI/testing/sysfs-class-gnss    |   2 +
>   Documentation/ABI/testing/sysfs-class-led     |   1 +
>   .../testing/sysfs-class-led-driver-el15203000 |  30 +--
>   .../ABI/testing/sysfs-class-led-driver-lm3533 |  44 ++--
>   .../ABI/testing/sysfs-class-led-flash         |  27 ++-
>   .../testing/sysfs-class-led-trigger-netdev    |   7 +
>   .../testing/sysfs-class-led-trigger-usbport   |   1 +
>   .../ABI/testing/sysfs-class-leds-gt683r       |   8 +-
>   Documentation/ABI/testing/sysfs-class-net     |  61 +++--
>   .../ABI/testing/sysfs-class-net-cdc_ncm       |   6 +-
>   .../ABI/testing/sysfs-class-net-phydev        |   2 +
>   Documentation/ABI/testing/sysfs-class-pktcdvd |  36 +--
>   Documentation/ABI/testing/sysfs-class-power   |  12 +-
>   .../ABI/testing/sysfs-class-power-mp2629      |   1 +
>   .../ABI/testing/sysfs-class-power-twl4030     |   4 +-
>   Documentation/ABI/testing/sysfs-class-rapidio |  46 ++--
>   .../ABI/testing/sysfs-class-regulator         |  36 +--
>   .../ABI/testing/sysfs-class-remoteproc        |  14 +-
>   ...ysfs-class-rtc-rtc0-device-rtc_calibration |   1 +
>   Documentation/ABI/testing/sysfs-class-uwb_rc  |  13 +-
>   .../ABI/testing/sysfs-class-watchdog          |   7 +-
>   Documentation/ABI/testing/sysfs-dev           |   7 +-
>   .../ABI/testing/sysfs-devices-mapping         |  41 ++--
>   .../ABI/testing/sysfs-devices-memory          |  15 +-
>   .../sysfs-devices-platform-_UDC_-gadget       |  10 +-
>   .../ABI/testing/sysfs-devices-platform-ipmi   |  52 ++--
>   .../ABI/testing/sysfs-devices-system-cpu      |   4 +-
>   .../ABI/testing/sysfs-driver-hid-lenovo       |  10 +
>   .../ABI/testing/sysfs-driver-hid-ntrig        |  13 +-
>   .../ABI/testing/sysfs-driver-hid-roccat-kone  |  19 ++
>   .../ABI/testing/sysfs-driver-hid-wiimote      |   1 +
>   .../ABI/testing/sysfs-driver-input-exc3000    |   2 +
>   .../ABI/testing/sysfs-driver-jz4780-efuse     |   6 +-
>   .../ABI/testing/sysfs-driver-pciback          |   6 +-
>   Documentation/ABI/testing/sysfs-driver-ufs    | 228 ++++++++++++++----
>   .../ABI/testing/sysfs-driver-w1_ds28e17       |   3 +
>   Documentation/ABI/testing/sysfs-firmware-acpi |  16 +-
>   .../ABI/testing/sysfs-firmware-efi-esrt       |  28 ++-
>   .../testing/sysfs-firmware-efi-runtime-map    |  14 +-
>   .../ABI/testing/sysfs-firmware-qemu_fw_cfg    |  20 +-
>   Documentation/ABI/testing/sysfs-firmware-sfi  |   6 +-
>   .../ABI/testing/sysfs-firmware-sgi_uv         |   6 +-
>   Documentation/ABI/testing/sysfs-fs-f2fs       |  48 ++--
>   Documentation/ABI/testing/sysfs-kernel-mm-ksm |   5 +-
>   Documentation/ABI/testing/sysfs-kernel-slab   |   3 +
>   Documentation/ABI/testing/sysfs-module        |  17 +-
>   .../ABI/testing/sysfs-platform-dell-laptop    |  10 +-
>   .../ABI/testing/sysfs-platform-dell-smbios    |   4 +-
>   .../testing/sysfs-platform-i2c-demux-pinctrl  |   4 +-
>   Documentation/ABI/testing/sysfs-platform-kim  |   1 +
>   .../testing/sysfs-platform-phy-rcar-gen3-usb2 |  10 +-
>   .../ABI/testing/sysfs-platform-renesas_usb3   |  10 +-
>   Documentation/ABI/testing/sysfs-power         |  21 +-
>   Documentation/ABI/testing/sysfs-profiling     |   2 +-
>   Documentation/ABI/testing/sysfs-wusb_cbaf     |   3 +-
>   Documentation/ABI/testing/usb-charger-uevent  |  82 ++++---
>   Documentation/ABI/testing/usb-uevent          |  32 +--
>   scripts/get_abi.pl                            |   2 -
>   126 files changed, 1323 insertions(+), 767 deletions(-)
>

Re: [PATCH v2 31/39] docs: ABI: cleanup several ABI documents

[Suzuki K Poulose]

On 10/30/20 7:40 AM, Mauro Carvalho Chehab wrote:
> There are some ABI documents that, while they don't generate
> any warnings, they have issues when parsed by get_abi.pl script
> on its output result.
> 
> Address them, in order to provide a clean output.
> 
> Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> #for IIO
> Reviewed-by: Tom Rix <trix@redhat.com> # for fpga-manager
> Reviewed-By: Kajol Jain<kjain@linux.ibm.com> # for sysfs-bus-event_source-devices-hv_gpci and sysfs-bus-event_source-devices-hv_24x7
> Acked-by: Oded Gabbay <oded.gabbay@gmail.com> # for Habanalabs
> Acked-by: Vaibhav Jain <vaibhav@linux.ibm.com> # for sysfs-bus-papr-pmem
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>



>   .../testing/sysfs-bus-coresight-devices-etb10 |   5 +-
For the above,

Acked-by: Suzuki K Poulose <suzuki.poulose@arm.com>

Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Mauro Carvalho Chehab]

Em Fri, 30 Oct 2020 10:19:12 +0100
Fabrice Gasnier <fabrice.gasnier@st.com> escreveu:

> Hi Mauro,
> 
> [...]
> 
> >  
> > +What:		/sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> > +KernelVersion:	4.12
> > +Contact:	benjamin.gaignard@st.com
> > +Description:
> > +		Reading returns the list possible quadrature modes.
> > +
> > +What:		/sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode
> > +KernelVersion:	4.12
> > +Contact:	benjamin.gaignard@st.com
> > +Description:
> > +		Configure the device counter quadrature modes:
> > +
> > +		channel_A:
> > +			Encoder A input servers as the count input and B as
> > +			the UP/DOWN direction control input.
> > +
> > +		channel_B:
> > +			Encoder B input serves as the count input and A as
> > +			the UP/DOWN direction control input.
> > +
> > +		quadrature:
> > +			Encoder A and B inputs are mixed to get direction
> > +			and count with a scale of 0.25.
> > +  
> 

Hi Fabrice,

> I just noticed that since Jonathan question in v1.
> 
> Above ABI has been moved in the past as discussed in [1]. You can take a
> look at:
> b299d00 IIO: stm32: Remove quadrature related functions from trigger driver
> 
> Could you please remove the above chunk ?
> 
> With that, for the stm32 part:
> Acked-by: Fabrice Gasnier <fabrice.gasnier@st.com>


Hmm... probably those were re-introduced due to a rebase. This
series were originally written about 1,5 years ago.

I'll drop those hunks.

Thanks!
Mauro

Re: [PATCH v2 31/39] docs: ABI: cleanup several ABI documents

[Ilya Dryomov]

On Fri, Oct 30, 2020 at 8:41 AM Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> There are some ABI documents that, while they don't generate
> any warnings, they have issues when parsed by get_abi.pl script
> on its output result.
>
> Address them, in order to provide a clean output.
>
> Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> #for IIO
> Reviewed-by: Tom Rix <trix@redhat.com> # for fpga-manager
> Reviewed-By: Kajol Jain<kjain@linux.ibm.com> # for sysfs-bus-event_source-devices-hv_gpci and sysfs-bus-event_source-devices-hv_24x7
> Acked-by: Oded Gabbay <oded.gabbay@gmail.com> # for Habanalabs
> Acked-by: Vaibhav Jain <vaibhav@linux.ibm.com> # for sysfs-bus-papr-pmem
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
>
> [...]
>
>  Documentation/ABI/testing/sysfs-bus-rbd       |  37 ++-

Acked-by: Ilya Dryomov <idryomov@gmail.com> # for rbd

Thanks,

                Ilya

Re: [PATCH v2 31/39] docs: ABI: cleanup several ABI documents

[Mathieu Poirier]

On Fri, 30 Oct 2020 at 01:41, Mauro Carvalho Chehab
<mchehab+huawei@kernel.org> wrote:
>
> There are some ABI documents that, while they don't generate
> any warnings, they have issues when parsed by get_abi.pl script
> on its output result.
>
> Address them, in order to provide a clean output.
>
> Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> #for IIO
> Reviewed-by: Tom Rix <trix@redhat.com> # for fpga-manager
> Reviewed-By: Kajol Jain<kjain@linux.ibm.com> # for sysfs-bus-event_source-devices-hv_gpci and sysfs-bus-event_source-devices-hv_24x7
> Acked-by: Oded Gabbay <oded.gabbay@gmail.com> # for Habanalabs
> Acked-by: Vaibhav Jain <vaibhav@linux.ibm.com> # for sysfs-bus-papr-pmem
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> ---

>  .../testing/sysfs-bus-coresight-devices-etb10 |   5 +-

For the CoreSight part:

Reviewed-by: Mathieu Poirier <mathieu.poirier@linaro.org>

Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Frederic Barrat]

Le 30/10/2020 à 08:40, Mauro Carvalho Chehab a écrit :
> Some files over there won't parse well by Sphinx.
> 
> Fix them.
> 
> Acked-by: Jonathan Cameron<Jonathan.Cameron@huawei.com>  # for IIO
> Signed-off-by: Mauro Carvalho Chehab<mchehab+huawei@kernel.org>
> ---
...
>   Documentation/ABI/testing/sysfs-class-cxl     |  15 +-
...
>   Documentation/ABI/testing/sysfs-class-ocxl    |   3 +


Patches 20, 28 and 31 look good for cxl and ocxl.
Acked-by: Frederic Barrat <fbarrat@linux.ibm.com>

   Fred

RE: [PATCH v2 31/39] docs: ABI: cleanup several ABI documents

[Peter Chen]

Acked-by: Peter Chen <peter.chen@nxp.com> 

For:
Documentation/ABI/testing/usb-charger-uevent

Peter

Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Fabrice Gasnier]

On 10/30/20 11:09 AM, Mauro Carvalho Chehab wrote:
> Em Fri, 30 Oct 2020 10:19:12 +0100
> Fabrice Gasnier <fabrice.gasnier@st.com> escreveu:
> 
>> Hi Mauro,
>>
>> [...]
>>
>>>  
>>> +What:		/sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
>>> +KernelVersion:	4.12
>>> +Contact:	benjamin.gaignard@st.com
>>> +Description:
>>> +		Reading returns the list possible quadrature modes.
>>> +
>>> +What:		/sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode
>>> +KernelVersion:	4.12
>>> +Contact:	benjamin.gaignard@st.com
>>> +Description:
>>> +		Configure the device counter quadrature modes:
>>> +
>>> +		channel_A:
>>> +			Encoder A input servers as the count input and B as
>>> +			the UP/DOWN direction control input.
>>> +
>>> +		channel_B:
>>> +			Encoder B input serves as the count input and A as
>>> +			the UP/DOWN direction control input.
>>> +
>>> +		quadrature:
>>> +			Encoder A and B inputs are mixed to get direction
>>> +			and count with a scale of 0.25.
>>> +  
>>
> 
> Hi Fabrice,
> 
>> I just noticed that since Jonathan question in v1.
>>
>> Above ABI has been moved in the past as discussed in [1]. You can take a
>> look at:
>> b299d00 IIO: stm32: Remove quadrature related functions from trigger driver
>>
>> Could you please remove the above chunk ?
>>
>> With that, for the stm32 part:
>> Acked-by: Fabrice Gasnier <fabrice.gasnier@st.com>
> 
> 
> Hmm... probably those were re-introduced due to a rebase. This
> series were originally written about 1,5 years ago.
> 
> I'll drop those hunks.

Hi Mauro, Greg,

I just figured out this patch has been applied with above hunk.

This should be dropped: is there a fix on its way already ?
(I may have missed it)

Please advise,
Fabrice
> 
> Thanks!
> Mauro
> 

Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Greg Kroah-Hartman]

On Mon, Nov 02, 2020 at 12:04:36PM +0100, Fabrice Gasnier wrote:
> On 10/30/20 11:09 AM, Mauro Carvalho Chehab wrote:
> > Em Fri, 30 Oct 2020 10:19:12 +0100
> > Fabrice Gasnier <fabrice.gasnier@st.com> escreveu:
> > 
> >> Hi Mauro,
> >>
> >> [...]
> >>
> >>>  
> >>> +What:		/sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> >>> +KernelVersion:	4.12
> >>> +Contact:	benjamin.gaignard@st.com
> >>> +Description:
> >>> +		Reading returns the list possible quadrature modes.
> >>> +
> >>> +What:		/sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode
> >>> +KernelVersion:	4.12
> >>> +Contact:	benjamin.gaignard@st.com
> >>> +Description:
> >>> +		Configure the device counter quadrature modes:
> >>> +
> >>> +		channel_A:
> >>> +			Encoder A input servers as the count input and B as
> >>> +			the UP/DOWN direction control input.
> >>> +
> >>> +		channel_B:
> >>> +			Encoder B input serves as the count input and A as
> >>> +			the UP/DOWN direction control input.
> >>> +
> >>> +		quadrature:
> >>> +			Encoder A and B inputs are mixed to get direction
> >>> +			and count with a scale of 0.25.
> >>> +  
> >>
> > 
> > Hi Fabrice,
> > 
> >> I just noticed that since Jonathan question in v1.
> >>
> >> Above ABI has been moved in the past as discussed in [1]. You can take a
> >> look at:
> >> b299d00 IIO: stm32: Remove quadrature related functions from trigger driver
> >>
> >> Could you please remove the above chunk ?
> >>
> >> With that, for the stm32 part:
> >> Acked-by: Fabrice Gasnier <fabrice.gasnier@st.com>
> > 
> > 
> > Hmm... probably those were re-introduced due to a rebase. This
> > series were originally written about 1,5 years ago.
> > 
> > I'll drop those hunks.
> 
> Hi Mauro, Greg,
> 
> I just figured out this patch has been applied with above hunk.
> 
> This should be dropped: is there a fix on its way already ?
> (I may have missed it)

Can you send a fix for just this hunk?

thanks,

greg k-h

Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Mauro Carvalho Chehab]

Em Mon, 2 Nov 2020 13:46:41 +0100
Greg Kroah-Hartman <gregkh@linuxfoundation.org> escreveu:

> On Mon, Nov 02, 2020 at 12:04:36PM +0100, Fabrice Gasnier wrote:
> > On 10/30/20 11:09 AM, Mauro Carvalho Chehab wrote:  
> > > Em Fri, 30 Oct 2020 10:19:12 +0100
> > > Fabrice Gasnier <fabrice.gasnier@st.com> escreveu:
> > >   
> > >> Hi Mauro,
> > >>
> > >> [...]
> > >>  
> > >>>  
> > >>> +What:		/sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> > >>> +KernelVersion:	4.12
> > >>> +Contact:	benjamin.gaignard@st.com
> > >>> +Description:
> > >>> +		Reading returns the list possible quadrature modes.
> > >>> +
> > >>> +What:		/sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode
> > >>> +KernelVersion:	4.12
> > >>> +Contact:	benjamin.gaignard@st.com
> > >>> +Description:
> > >>> +		Configure the device counter quadrature modes:
> > >>> +
> > >>> +		channel_A:
> > >>> +			Encoder A input servers as the count input and B as
> > >>> +			the UP/DOWN direction control input.
> > >>> +
> > >>> +		channel_B:
> > >>> +			Encoder B input serves as the count input and A as
> > >>> +			the UP/DOWN direction control input.
> > >>> +
> > >>> +		quadrature:
> > >>> +			Encoder A and B inputs are mixed to get direction
> > >>> +			and count with a scale of 0.25.
> > >>> +    
> > >>  
> > > 
> > > Hi Fabrice,
> > >   
> > >> I just noticed that since Jonathan question in v1.
> > >>
> > >> Above ABI has been moved in the past as discussed in [1]. You can take a
> > >> look at:
> > >> b299d00 IIO: stm32: Remove quadrature related functions from trigger driver
> > >>
> > >> Could you please remove the above chunk ?
> > >>
> > >> With that, for the stm32 part:
> > >> Acked-by: Fabrice Gasnier <fabrice.gasnier@st.com>  
> > > 
> > > 
> > > Hmm... probably those were re-introduced due to a rebase. This
> > > series were originally written about 1,5 years ago.
> > > 
> > > I'll drop those hunks.  
> > 
> > Hi Mauro, Greg,
> > 
> > I just figured out this patch has been applied with above hunk.
> > 
> > This should be dropped: is there a fix on its way already ?
> > (I may have missed it)  
> 
> Can you send a fix for just this hunk?

Hmm...

	$ git grep /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
	Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:What:                /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
	Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:What:             /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
	Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:What:               /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available

Even re-doing the changes from 
changeset b299d00420e2 ("IIO: stm32: Remove quadrature related functions from trigger driver")
at Documentation/ABI/testing/sysfs-bus-iio-timer-stm32, there's still
a third duplicate of some of those, as reported by the script:

	$ ./scripts/get_abi.pl validate 2>&1|grep quadra
	Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:117  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:14
	Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 3 times:  Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:111  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:8

As in_count_quadrature_mode_available is also defined at:
	Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2

The best here seems to have a patch that will also drop the other
duplication of this, probably moving in_count_quadrature_mode_available
to a generic node probably placing it inside 
Documentation/ABI/testing/sysfs-bus-iio.

Comments?

Thanks,
Mauro

PS.: the IIO subsystem is the one that currently has more duplicated
ABI entries:

$ ./scripts/get_abi.pl validate 2>&1|grep iio
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:394
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:395
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:396
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:397
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:398
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:399
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_count0_quadrature_mode is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:117  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:14
Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 3 times:  Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:111  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:599
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:588
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:  Documentation/ABI/testing/sysfs-bus-iio-distance-srf08:0  Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935:8
Warning: /sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  Documentation/ABI/testing/sysfs-bus-iio:45

Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Jonathan Cameron]

On Mon, 2 Nov 2020 15:42:50 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> Em Mon, 2 Nov 2020 13:46:41 +0100
> Greg Kroah-Hartman <gregkh@linuxfoundation.org> escreveu:
> 
> > On Mon, Nov 02, 2020 at 12:04:36PM +0100, Fabrice Gasnier wrote:  
> > > On 10/30/20 11:09 AM, Mauro Carvalho Chehab wrote:    
> > > > Em Fri, 30 Oct 2020 10:19:12 +0100
> > > > Fabrice Gasnier <fabrice.gasnier@st.com> escreveu:
> > > >     
> > > >> Hi Mauro,
> > > >>
> > > >> [...]
> > > >>    
> > > >>>  
> > > >>> +What:		/sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> > > >>> +KernelVersion:	4.12
> > > >>> +Contact:	benjamin.gaignard@st.com
> > > >>> +Description:
> > > >>> +		Reading returns the list possible quadrature modes.
> > > >>> +
> > > >>> +What:		/sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode
> > > >>> +KernelVersion:	4.12
> > > >>> +Contact:	benjamin.gaignard@st.com
> > > >>> +Description:
> > > >>> +		Configure the device counter quadrature modes:
> > > >>> +
> > > >>> +		channel_A:
> > > >>> +			Encoder A input servers as the count input and B as
> > > >>> +			the UP/DOWN direction control input.
> > > >>> +
> > > >>> +		channel_B:
> > > >>> +			Encoder B input serves as the count input and A as
> > > >>> +			the UP/DOWN direction control input.
> > > >>> +
> > > >>> +		quadrature:
> > > >>> +			Encoder A and B inputs are mixed to get direction
> > > >>> +			and count with a scale of 0.25.
> > > >>> +      
> > > >>    
> > > > 
> > > > Hi Fabrice,
> > > >     
> > > >> I just noticed that since Jonathan question in v1.
> > > >>
> > > >> Above ABI has been moved in the past as discussed in [1]. You can take a
> > > >> look at:
> > > >> b299d00 IIO: stm32: Remove quadrature related functions from trigger driver
> > > >>
> > > >> Could you please remove the above chunk ?
> > > >>
> > > >> With that, for the stm32 part:
> > > >> Acked-by: Fabrice Gasnier <fabrice.gasnier@st.com>    
> > > > 
> > > > 
> > > > Hmm... probably those were re-introduced due to a rebase. This
> > > > series were originally written about 1,5 years ago.
> > > > 
> > > > I'll drop those hunks.    
> > > 
> > > Hi Mauro, Greg,
> > > 
> > > I just figured out this patch has been applied with above hunk.
> > > 
> > > This should be dropped: is there a fix on its way already ?
> > > (I may have missed it)    
> > 
> > Can you send a fix for just this hunk?  
> 
> Hmm...
> 
> 	$ git grep /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> 	Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:What:                /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> 	Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:What:             /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> 	Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:What:               /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available
> 
> Even re-doing the changes from 
> changeset b299d00420e2 ("IIO: stm32: Remove quadrature related functions from trigger driver")
> at Documentation/ABI/testing/sysfs-bus-iio-timer-stm32, there's still
> a third duplicate of some of those, as reported by the script:
> 
> 	$ ./scripts/get_abi.pl validate 2>&1|grep quadra
> 	Warning: /sys/bus/iio/devices/iio:deviceX/in_count0_quadrature_mode is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:117  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:14
> 	Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 3 times:  Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:111  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:8
> 
> As in_count_quadrature_mode_available is also defined at:
> 	Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2
> 
> The best here seems to have a patch that will also drop the other
> duplication of this, probably moving in_count_quadrature_mode_available
> to a generic node probably placing it inside 
> Documentation/ABI/testing/sysfs-bus-iio.

In this particular case it may be valid to do that, but it's not in
general without loosing information - see below.

> 
> Comments?
> 
> Thanks,
> Mauro
> 
> PS.: the IIO subsystem is the one that currently has more duplicated
> ABI entries:

That was intentional.  Often these provide more information on the
ABI for a particular device than is present in the base ABI doc.

A bit like when we have additional description for dt binding properties
for a particular device, even though they are standard properties.

Often a standard property allows for more values than the specific
one for a particular device.  There can also be obscuring coupling
between sysfs attributes due to hardware restrictions that we would
like to provide some explanatory info on.

I suppose we could add all this information to the parent doc but
that is pretty ugly and will make that doc very nasty to read.

Jonathan

> 
> $ ./scripts/get_abi.pl validate 2>&1|grep iio
> 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:394
> 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:395
> 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:396
> 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:397
> 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:398
> 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:399
> 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_count0_quadrature_mode is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:117  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:14
> Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 3 times:  Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:111  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:599
> 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:588
> 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:  Documentation/ABI/testing/sysfs-bus-iio-distance-srf08:0  Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935:8
> Warning: /sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  Documentation/ABI/testing/sysfs-bus-iio:45

Duplicated ABI entries - Was: Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Mauro Carvalho Chehab]

Hi Jonathan,

Em Sun, 8 Nov 2020 16:56:21 +0000
Jonathan Cameron <jic23@kernel.org> escreveu:

> > PS.: the IIO subsystem is the one that currently has more duplicated
> > ABI entries:  
> > $ ./scripts/get_abi.pl validate 2>&1|grep iio
> > 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:394
> > 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:395
> > 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:396
> > 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:397
> > 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:398
> > 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:399
> > 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_count0_quadrature_mode is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:117  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:14
> > Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 3 times:  Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:111  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:599
> > 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:588
> > 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:  Documentation/ABI/testing/sysfs-bus-iio-distance-srf08:0  Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935:8
> > Warning: /sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  Documentation/ABI/testing/sysfs-bus-iio:45  

> 
> That was intentional.  Often these provide more information on the
> ABI for a particular device than is present in the base ABI doc.

FYI, right now, there are 20 duplicated entries, being 16 of them
from IIO, on those files:

	$ ./scripts/get_abi.pl validate 2>&1|perl -ne 'if (m,(Documentation/\S+)\:,g) { print "$1\n" }'|sort|uniq
	Documentation/ABI/stable/sysfs-driver-w1_ds28e04
	Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8
	Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
	Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
	Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010
	Documentation/ABI/testing/sysfs-bus-iio-icm42600
	Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als
	Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
	Documentation/ABI/testing/sysfs-class-backlight-adp8860
	Documentation/ABI/testing/sysfs-class-led-trigger-pattern
	Documentation/ABI/testing/sysfs-kernel-iommu_groups

> 
> A bit like when we have additional description for dt binding properties
> for a particular device, even though they are standard properties.
> 
> Often a standard property allows for more values than the specific
> one for a particular device.  There can also be obscuring coupling
> between sysfs attributes due to hardware restrictions that we would
> like to provide some explanatory info on.
> 
> I suppose we could add all this information to the parent doc but
> that is pretty ugly and will make that doc very nasty to read.

I understand what you meant to do, but right now, it is is actually
a lot uglier than merging into a single entry ;-)

Let's view ABI from the PoV of a system admin that doesn't know
yet about a certain ABI symbol.

He'll try to seek for the symbol, more likely using the HTML 
documentation. Only very senior system admins might try to take
a look at the Kernel.

This is what happens when one would seek for a duplicated symbol
via command line:

	$ ./scripts/get_abi.pl search /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency$
	
	/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency
	----------------------------------------------------------
	
	Kernel version:		3.4.0
	Contact:		linux-iio@vger.kernel.org
	Defined on file(s):	Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 Documentation/ABI/testing/sysfs-bus-iio
	
	Description:
	
	Stores the PLL frequency in Hz for channel Y.
	Reading returns the actual frequency in Hz.
	The ADF4371 has an integrated VCO with fundamendal output
	frequency ranging from 4000000000 Hz 8000000000 Hz.
	
	out_altvoltage0_frequency:
	        A divide by 1, 2, 4, 8, 16, 32 or circuit generates
	        frequencies from 62500000 Hz to 8000000000 Hz.
	out_altvoltage1_frequency:
	        This channel duplicates the channel 0 frequency
	out_altvoltage2_frequency:
	        A frequency doubler generates frequencies from
	        8000000000 Hz to 16000000000 Hz.
	out_altvoltage3_frequency:
	        A frequency quadrupler generates frequencies from
	        16000000000 Hz to 32000000000 Hz.
	
	Note: writes to one of the channels will affect the frequency of
	all the other channels, since it involves changing the VCO
	fundamental output frequency.
	
	Output frequency for channel Y in Hz. The number must always be
	specified and unique if the output corresponds to a single
	channel.

As the "What:" field is identical on both sysfs-bus-iio-frequency-adf4371
and sysfs-bus-iio, those entries are merged, which produces an ABI
documentation mixing both the generic one and the board specific one
into a single output.

Worse than that, the "generic" content is at the end.

The same happens when generating the HTML output.

See, entries at the HTML output are ordered by the What: field,
which is considered within the script as an unique key, as it is
unique (except for IIO and a couple of other cases).

-

As I commented on an e-mail I sent to Greg, I see a few ways
to solve it.

The most trivial one (which I used to solve a few conflicts on
other places), is to place driver-specific details on a separate
file under Documentation/driver-api, and mention it at the
generic entries. The docs building system will generate cross
references for Documentation/.../foo.rst files, so, everything
should be OK.

The second alternative that I also used on a couple of places
is to modify the generic entry for it to contain the generic
definition first, followed by per-device details.

There is a third possible alternative: add a new optional field
(something like Scope:) which would be part of the unique key,
if present. Implementing support for it could be tricky, as the
produced output would likely need to create cross-references
between the generic field (if present) and the per-device details.

Thanks,
Mauro

PS.: I'm taking a few days of PTO during this week. So, it
could take a while for me to reply again to this thread.

Re: Duplicated ABI entries - Was: Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Randy Dunlap]

On 11/9/20 11:26 PM, Mauro Carvalho Chehab wrote:
> Hi Jonathan,
> 
> Let's view ABI from the PoV of a system admin that doesn't know
> yet about a certain ABI symbol.
> 
> He'll try to seek for the symbol, more likely using the HTML 
> documentation. Only very senior system admins might try to take
> a look at the Kernel.

FWIW, I think that the likely search methods are $search_engine
and 'grep'.

Have a good few days off.

-- 
~Randy

Re: Duplicated ABI entries - Was: Re: [PATCH v2 20/39] docs: ABI: testing: make the files compatible with ReST output

[Jonathan Cameron]

On Tue, 10 Nov 2020 08:26:58 +0100
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:

> Hi Jonathan,
> 
> Em Sun, 8 Nov 2020 16:56:21 +0000
> Jonathan Cameron <jic23@kernel.org> escreveu:
> 
> > > PS.: the IIO subsystem is the one that currently has more duplicated
> > > ABI entries:  
> > > $ ./scripts/get_abi.pl validate 2>&1|grep iio
> > > 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:394
> > > 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:395
> > > 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:396
> > > 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:397
> > > 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:398
> > > 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:399
> > > 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_count0_quadrature_mode is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:117  Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:14
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_available is defined 3 times:  Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8:2  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:111  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:599
> > > 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:588
> > > 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:  Documentation/ABI/testing/sysfs-bus-iio-distance-srf08:0  Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935:8
> > > Warning: /sys/bus/iio/devices/triggerX/sampling_frequency is defined 2 times:  Documentation/ABI/testing/sysfs-bus-iio-timer-stm32:92  Documentation/ABI/testing/sysfs-bus-iio:45    
> 
> > 
> > That was intentional.  Often these provide more information on the
> > ABI for a particular device than is present in the base ABI doc.  
> 
> FYI, right now, there are 20 duplicated entries, being 16 of them
> from IIO, on those files:
> 
> 	$ ./scripts/get_abi.pl validate 2>&1|perl -ne 'if (m,(Documentation/\S+)\:,g) { print "$1\n" }'|sort|uniq
> 	Documentation/ABI/stable/sysfs-driver-w1_ds28e04
> 	Documentation/ABI/testing/sysfs-bus-iio-counter-104-quad-8
> 	Documentation/ABI/testing/sysfs-bus-iio-distance-srf08
> 	Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371
> 	Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc2010
> 	Documentation/ABI/testing/sysfs-bus-iio-icm42600
> 	Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als
> 	Documentation/ABI/testing/sysfs-bus-iio-timer-stm32
> 	Documentation/ABI/testing/sysfs-class-backlight-adp8860
> 	Documentation/ABI/testing/sysfs-class-led-trigger-pattern
> 	Documentation/ABI/testing/sysfs-kernel-iommu_groups
> 
> > 
> > A bit like when we have additional description for dt binding properties
> > for a particular device, even though they are standard properties.
> > 
> > Often a standard property allows for more values than the specific
> > one for a particular device.  There can also be obscuring coupling
> > between sysfs attributes due to hardware restrictions that we would
> > like to provide some explanatory info on.
> > 
> > I suppose we could add all this information to the parent doc but
> > that is pretty ugly and will make that doc very nasty to read.  
> 
> I understand what you meant to do, but right now, it is is actually
> a lot uglier than merging into a single entry ;-)
> 
> Let's view ABI from the PoV of a system admin that doesn't know
> yet about a certain ABI symbol.

I'd be surprised if a sys admin is looking at these at all. They
tend to be used only by userspace software writers.  But I guess the
point stands.

> 
> He'll try to seek for the symbol, more likely using the HTML 
> documentation. Only very senior system admins might try to take
> a look at the Kernel.

Sad truth here is that before these were in the html docs, they'd
have grepped and the right option would fairly obvious as it
would be the more specific file.  Ah well, sometimes progress bites :)

> 
> This is what happens when one would seek for a duplicated symbol
> via command line:
> 
> 	$ ./scripts/get_abi.pl search /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency$
> 	
> 	/sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency
> 	----------------------------------------------------------
> 	
> 	Kernel version:		3.4.0
> 	Contact:		linux-iio@vger.kernel.org
> 	Defined on file(s):	Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4371 Documentation/ABI/testing/sysfs-bus-iio
> 	
> 	Description:
> 	
> 	Stores the PLL frequency in Hz for channel Y.
> 	Reading returns the actual frequency in Hz.
> 	The ADF4371 has an integrated VCO with fundamendal output
> 	frequency ranging from 4000000000 Hz 8000000000 Hz.
> 	
> 	out_altvoltage0_frequency:
> 	        A divide by 1, 2, 4, 8, 16, 32 or circuit generates
> 	        frequencies from 62500000 Hz to 8000000000 Hz.
> 	out_altvoltage1_frequency:
> 	        This channel duplicates the channel 0 frequency
> 	out_altvoltage2_frequency:
> 	        A frequency doubler generates frequencies from
> 	        8000000000 Hz to 16000000000 Hz.
> 	out_altvoltage3_frequency:
> 	        A frequency quadrupler generates frequencies from
> 	        16000000000 Hz to 32000000000 Hz.
> 	
> 	Note: writes to one of the channels will affect the frequency of
> 	all the other channels, since it involves changing the VCO
> 	fundamental output frequency.
> 	
> 	Output frequency for channel Y in Hz. The number must always be
> 	specified and unique if the output corresponds to a single
> 	channel.
> 
> As the "What:" field is identical on both sysfs-bus-iio-frequency-adf4371
> and sysfs-bus-iio, those entries are merged, which produces an ABI
> documentation mixing both the generic one and the board specific one
> into a single output.
> 
> Worse than that, the "generic" content is at the end.
> 
> The same happens when generating the HTML output.
> 
> See, entries at the HTML output are ordered by the What: field,
> which is considered within the script as an unique key, as it is
> unique (except for IIO and a couple of other cases).
> 
> -
> 
> As I commented on an e-mail I sent to Greg, I see a few ways
> to solve it.
> 
> The most trivial one (which I used to solve a few conflicts on
> other places), is to place driver-specific details on a separate
> file under Documentation/driver-api, and mention it at the
> generic entries. The docs building system will generate cross
> references for Documentation/.../foo.rst files, so, everything
> should be OK.

Hmm. That might work out OK.  These devices tend to be weird enough
that they probably could do with some additional explanation anyway. 

> 
> The second alternative that I also used on a couple of places
> is to modify the generic entry for it to contain the generic
> definition first, followed by per-device details.

I'll do an audit of what we actually have here. Perhaps we end
up with a mixture of these two options.

Might take a little while though.

> 
> There is a third possible alternative: add a new optional field
> (something like Scope:) which would be part of the unique key,
> if present. Implementing support for it could be tricky, as the
> produced output would likely need to create cross-references
> between the generic field (if present) and the per-device details.
That would be lovely but probably not worth the effort for something
that occurs so rarely currently.

Jonathan

> 
> Thanks,
> Mauro
> 
> PS.: I'm taking a few days of PTO during this week. So, it
> could take a while for me to reply again to this thread.