Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Date:   Tue, 19 Jan 2021 18:17:05 +0900
From:   William Breathitt Gray <vilhelm.gray@gmail.com>
To:     Jonathan Cameron <jic23@kernel.org>
Cc:     Jonathan Cameron <Jonathan.Cameron@Huawei.com>,
        Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
        Lukas Bulwahn <lukas.bulwahn@gmail.com>, corbet@lwn.net,
        linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
        linux-iio@vger.kernel.org,
        Fabrice Gasnier <fabrice.gasnier@st.com>,
        Benjamin Gaignard <benjamin.gaignard@st.com>
Subject: Re: [PATCH 00/10] Fix documentation warnings at linux-next
Message-ID: <YAajkfaXPqkZUB/2@shinobu>
References: <CAKXUXMziQ2H7_oiVSxbt1=bDFkjLQYOiOgd00YGyDnCTVDhbqA@mail.gmail.com>
 <20210115104947.71d99e87@coco.lan>
 <20210115134720.000011f9@Huawei.com>
 <20210117154218.634dd5fa@archlinux>
MIME-Version: 1.0
Content-Type: multipart/signed; micalg=pgp-sha512;
        protocol="application/pgp-signature"; boundary="MjKgfLFDy3EUHZT3"
Content-Disposition: inline
In-Reply-To: <20210117154218.634dd5fa@archlinux>
Precedence: bulk


--MjKgfLFDy3EUHZT3
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: quoted-printable

On Sun, Jan 17, 2021 at 03:42:18PM +0000, Jonathan Cameron wrote:
> On Fri, 15 Jan 2021 13:47:20 +0000
> Jonathan Cameron <Jonathan.Cameron@Huawei.com> wrote:
>=20
> > On Fri, 15 Jan 2021 10:49:47 +0100
> > Mauro Carvalho Chehab <mchehab+huawei@kernel.org> wrote:
> >=20
> > > Hi Lukas,
> > >=20
> > > Em Fri, 15 Jan 2021 07:12:38 +0100
> > > Lukas Bulwahn <lukas.bulwahn@gmail.com> escreveu:
> > >  =20
> > > > [reduced the recipient list to the main responsible ones and list]
> > > >=20
> > > > Hi Mauro, hi Jonathan,
> > > >=20
> > > > We both, Mauro and I, have been submitting patches to address the
> > > > documentation warnings on linux-next. If it is okay with you, Mauro=
, I
> > > > would like to take responsibility for the task to send out the patc=
hes
> > > > to address all warnings on linux-next in make htmldocs and follow up
> > > > with all the discussions. I can also provide a short weekly summary
> > > > (probably always on Friday) on what is pending where and what I cou=
ld
> > > > not resolve by myself.
> > > >=20
> > > > Is that okay for you?
> > > >=20
> > > > If at some point I do not have the time to take care anymore, I will
> > > > let you know.   =20
> > >=20
> > > Yeah, sure!
> > >=20
> > > Anyway, after applying the patches I sent this week, the warnings
> > > I'm getting are all due to the validation scripts I wrote. So, if=20
> > > everything gets merged (either yours or my version), we'll have zero
> > > Sphinx/kernel-doc warnings again.
> > >=20
> > > The script-validation warnings are:
> > >=20
> > > 1. Broken cross references
> > > --------------------------
> > >=20
> > > $ scripts/documentation-file-ref-check
> > > Warning: Documentation/arm/booting.rst references a file that doesn't=
 exist: Documentation/devicetree/booting-without-of.rst
> > > Warning: Documentation/devicetree/bindings/hwmon/ntc_thermistor.txt r=
eferences a file that doesn't exist: Documentation/devicetree/bindings/iio/=
iio-bindings.txt
> > > Warning: Documentation/devicetree/bindings/input/adc-joystick.yaml re=
ferences a file that doesn't exist: Documentation/devicetree/bindings/iio/i=
io-bindings.txt
> > > Warning: Documentation/devicetree/bindings/power/supply/da9150-charge=
r.txt references a file that doesn't exist: Documentation/devicetree/bindin=
gs/iio/iio-bindings.txt
> > > Warning: Documentation/devicetree/bindings/regulator/rohm,bd9576-regu=
lator.yaml references a file that doesn't exist: Documentation/devicetree/b=
indings/mfd/rohm,bd9576-pmic.yaml
> > > Warning: Documentation/translations/zh_CN/arm/Booting references a fi=
le that doesn't exist: Documentation/devicetree/booting-without-of.rst
> > > Warning: Documentation/virt/kvm/vcpu-requests.rst references a file t=
hat doesn't exist: Documentation/core-api/atomic_ops.rst
> > > Warning: MAINTAINERS references a file that doesn't exist: Documentat=
ion/devicetree/bindings/pinctrl/toshiba,tmpv7700-pinctrl.yaml
> > > Warning: MAINTAINERS references a file that doesn't exist: Documentat=
ion/devicetree/bindings/misc/hisilicon-hikey-usb.yaml
> > > Warning: MAINTAINERS references a file that doesn't exist: Documentat=
ion/devicetree/bindings/display/intel,kmb_display.yaml
> > > Warning: MAINTAINERS references a file that doesn't exist: Documentat=
ion/devicetree/bindings/media/i2c/ov2680.yaml
> > > Warning: include/linux/rculist_nulls.h references a file that doesn't=
 exist: Documentation/core-api/atomic_ops.rst
> > > Warning: tools/memory-model/Documentation/simple.txt references a fil=
e that doesn't exist: Documentation/core-api/atomic_ops.rst
> > >=20
> > > It sounds that part of the above is due to DT patches that weren't
> > > merged yet, but there are a few others that can be solved, but may
> > > require discussions with some Kernel developers/maintainers.
> > >=20
> > > 2. Duplicated ABI definitions
> > > -----------------------------
> > >=20
> > > $ scripts/get_abi.pl validate
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_x_calibbias is def=
ined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:0  ./Docu=
mentation/ABI/testing/sysfs-bus-iio:394
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_y_calibbias is def=
ined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:1  ./Docu=
mentation/ABI/testing/sysfs-bus-iio:395
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias is def=
ined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:2  ./Docu=
mentation/ABI/testing/sysfs-bus-iio:396
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias is d=
efined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:3  ./Do=
cumentation/ABI/testing/sysfs-bus-iio:397
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias is d=
efined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:4  ./Do=
cumentation/ABI/testing/sysfs-bus-iio:398
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias is d=
efined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-icm42600:5  ./Do=
cumentation/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  ./Doc=
umentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:0
> > > Warning: /sys/bus/iio/devices/iio:deviceX/in_count_quadrature_mode_av=
ailable is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-coun=
ter-104-quad-8:2  ./Documentation/ABI/testing/sysfs-bus-iio-lptimer-stm32:8
> > > Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency i=
s defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-frequency-adf=
4371:0  ./Documentation/ABI/testing/sysfs-bus-iio:599
> > > Warning: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown i=
s defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-frequency-adf=
4371: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 d=
efined 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_avai=
lable is defined 2 times:  ./Documentation/ABI/testing/sysfs-bus-iio-humidi=
ty-hdc2010:1  ./Documentation/ABI/testing/sysfs-bus-iio-humidity-hdc100x:1
> > > Warning: /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity is defin=
ed 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  ./Docum=
entation/ABI/testing/sysfs-bus-iio:45
> > > Warning: /sys/class/backlight/<backlight>/l1_daylight_max is defined =
2 times:  ./Documentation/ABI/testing/sysfs-class-backlight-adp8860:12  ./D=
ocumentation/ABI/testing/sysfs-class-backlight-driver-adp8870:4
> > > Warning: /sys/class/leds/<led>/repeat is defined 2 times:  ./Document=
ation/ABI/testing/sysfs-class-led-trigger-pattern:28  ./Documentation/ABI/t=
esting/sysfs-class-led-driver-el15203000:0
> > > Warning: /sys/kernel/iommu_groups/reserved_regions is defined 2 times=
:  ./Documentation/ABI/testing/sysfs-kernel-iommu_groups:15  ./Documentatio=
n/ABI/testing/sysfs-kernel-iommu_groups:27
> > >=20
> > > Perhaps you could check with Jonathan Cameron some strategy to address
> > > the IIO warnings. =20
> >=20
> > I'm being a bit rubbish on those ones. All need a bit of thought...
> >=20
> > I'll try to kill off a few of them this weekend as *touch wood* my
> > review queue is looking fairly short.
>=20
> As I mentioned in the cover letter for the series I've just sent out, I r=
an into
> a bit of an understanding gap around the two counter cases.  This isn't h=
elped
> by the fact it is at least partly deprecated ABI given the counter subsys=
tem
> has much richer ABI for these types of devices.
>=20
> @Fabrice, Benjamin and William.
> What do we do about that one?
>=20
> Thanks,
>=20
> Jonathan

I'd consider the IIO counter ABI as entirely deprecated -- the Counter
subsystem supports all the functionality that's provided by the IIO
counter ABI, as well as additional functionality that is missing.=20

Regarding the iio:deviceX/in_count_quadrature_mode_available attribute:
superseded by the Counter subsystem counterX/countY/function attribute.
The IIO counter ABI allows users to select between a quadrature counting
mode or a non-quadrature counting mode; unfortunately, it does not
specify what kind of quadrature or what kind of non-quadrature counting
is actually being performed by the device.

Because the 104-quad-8 and stm32-lptimer-cnt drivers were the only ones
to use this attribute, they are luckily in sync -- both define the same
possible modes available: "quadrature" and "non-quadrature". You could
simply consolidate this attribute to the main sys-bus-iio file in order
to resolve this warning.

Given that it has already been superceded by the Counter subsystem, I'd
also be all right with just removing the IIO Counter ABI entirely from
the codebase, or alternatively setting a future date for removal.

William Breathitt Gray

> >=20
> > Jonathan
> >=20
> > >=20
> > > Thanks,
> > > Mauro =20
> >=20
>=20

--MjKgfLFDy3EUHZT3
Content-Type: application/pgp-signature; name="signature.asc"

-----BEGIN PGP SIGNATURE-----

iQIzBAABCgAdFiEEk5I4PDJ2w1cDf/bghvpINdm7VJIFAmAGo4YACgkQhvpINdm7
VJIZxA/9H7SZZN2VLQOm+wRMOdsAFk+N+mS5eYaod2XmO5DkJxJjV6JSyOoglH9U
KYDZBG2otHyEe4YdBGFkgzUE58NEzSDKqmruuE1VlcCvBB1AfzU+0l+7wtmbxywJ
Ye+fbpX8WJYiTiI3kDPibIqgNMMo3xKTIitNsCMHlgRS+Fm8ph2Xlt6wZU2830tf
WGut29VTI/D1hYf6a1woaoHg6G6sWUkhdviszi9pnDZD2bngVsXqxUdrRb3v/Ssn
gVwvXBC9TYwTQQue5/Ah29lW4KBFrVEI2Lw+8HJ8srpaBwZlKbRdGw6k/nAkrWgx
9KVGFTs12hNhHXFThcAjSDq1nwY7Ss8L9Jk6WNTVekiie9b0LY0fmH/sCU/2UlQ2
LHwtmkG41UiRvJ+NE6d5K860oEShCPsVW5n+esKDGN2welc+0d/7kCITgtzH0Kvt
EbDqmXKx/bls02Tg2b3NxtSQz+W6hsqWCFrLNioZEMoowW1LaES1nSsfAxnyRL62
ELw2h9bsPamXUm4AvK244WDTU40Lt1Utzu1vQ+scX4L9goiZim4+Tyx01qkRq6+2
RML3c+05F/oQ3xe9rKKG0mbb8Dun1QdoObYEbLKLI3vkrZDzwXdL/hDH2xwmbuYn
eWhku4AEcq0GZfofSocGzJh0l2jQKa8TGNd3ZZIqd9z2E5dRKPg=
=npAt
-----END PGP SIGNATURE-----

--MjKgfLFDy3EUHZT3--