Received-SPF: softfail (google.com: domain of transitioning linux-kernel-owner@vger.kernel.org does not designate 23.128.96.19 as permitted sender) client-ip=23.128.96.19;
Date:   Mon, 6 Jun 2022 09:33:02 +1000
From:   Stephen Rothwell <sfr@canb.auug.org.au>
To:     Marc Zyngier <maz@kernel.org>
Cc:     Mauro Carvalho Chehab <mchehab@kernel.org>,
        Linus Walleij <linus.walleij@linaro.org>,
        Jonathan Corbet <corbet@lwn.net>,
        Joey Gouly <joey.gouly@arm.com>,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
        Linux Next Mailing List <linux-next@vger.kernel.org>
Subject: Re: linux-next: build warning after merge of the pinctrl tree
Message-ID: <20220606093302.21febee3@canb.auug.org.au>
In-Reply-To: <20220318183101.16b8d056@canb.auug.org.au>
References: <20211027220118.71a229ab@canb.auug.org.au>
        <874k92bu4q.wl-maz@kernel.org>
        <20211028080331.6d199082@sal.lan>
        <20220120142539.6d1fac12@canb.auug.org.au>
        <20220318183101.16b8d056@canb.auug.org.au>
MIME-Version: 1.0
Content-Type: multipart/signed; boundary="Sig_/j/Z+F3kNQCDQiZbzMTn7/sf";
 protocol="application/pgp-signature"; micalg=pgp-sha256
Precedence: bulk

--Sig_/j/Z+F3kNQCDQiZbzMTn7/sf
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: quoted-printable

Hi all,

On Fri, 18 Mar 2022 18:31:01 +1100 Stephen Rothwell <sfr@canb.auug.org.au> =
wrote:
>
> On Thu, 20 Jan 2022 14:25:39 +1100 Stephen Rothwell <sfr@canb.auug.org.au=
> wrote:
> >
> > On Thu, 28 Oct 2021 08:03:31 +0100 Mauro Carvalho Chehab <mchehab@kerne=
l.org> wrote: =20
> > >
> > > Em Wed, 27 Oct 2021 12:10:45 +0100
> > > Marc Zyngier <maz@kernel.org> escreveu:
> > >    =20
> > > > On Wed, 27 Oct 2021 12:01:18 +0100, Stephen Rothwell <sfr@canb.auug=
.org.au> wrote:     =20
> > > > >=20
> > > > > After merging the pinctrl tree, today's linux-next build (htmldoc=
s)
> > > > > produced this warning:
> > > > >=20
> > > > > include/linux/gpio/driver.h:284: warning: Function parameter or m=
ember 'parent_handler_data_array' not described in 'gpio_irq_chip'
> > > > >=20
> > > > > Introduced by commit
> > > > >=20
> > > > >   cfe6807d82e9 ("gpio: Allow per-parent interrupt data")
> > > > >=20
> > > > > But may actually be a problem with the tool :-(       =20
> > > >=20
> > > > I guess the tool doesn't like having two fields that are part of a
> > > > union documented together... Happy to tweak it if someone tells me =
how
> > > > this should be written.     =20
> > >=20
> > > Yes, that's the case. See, when you do:
> > >=20
> > > 	/**
> > > 	 * @parent_handler_data:
> > > 	 * @parent_handler_data_array:
> > > 	 *
> > > 	 * Data associated, and passed to, the handler for the parent
> > > 	 * interrupt. Can either be a single pointer if @per_parent_data
> > > 	 * is false, or an array of @num_parents pointers otherwise.  If
> > > 	 * @per_parent_data is true, @parent_handler_data_array cannot be
> > > 	 * NULL.
> > > 	 */
> > > 	union {
> > > 		void *parent_handler_data;
> > > 		void **parent_handler_data_array;
> > > 	};
> > >=20
> > > The tool will understand it as an undocumented "parent_handler_data" =
and
> > > a documented "parent_handler_data_array".
> > >=20
> > > It has to do that, as otherwise it won't get cases where people just =
adds a
> > > @foo: as a template but actually forgets to fill it.
> > >=20
> > > The solution would be to add a description for both, e. g. something
> > > similar to:
> > >=20
> > > 	/**
> > > 	 * @parent_handler_data:
> > > 	 *
> > > 	 * If @per_parent_data is false, contains a single pointer=20
> > > 	 * with the data associated, and passed to, the handler for the=20
> > > 	 * parent interrupt.
> > > 	 *
> > > 	 * @parent_handler_data_array:
> > > 	 *
> > > 	 * If @per_parent_data is true, it should contain an array of=20
> > > 	 * @num_parents pointers with the data associated, and passed to,
> > > 	 * the handler for the parent interrupt. Cannot be NULL.
> > > 	 */   =20
> >=20
> > I am still getting this warning. =20
>=20
> I am still getting this warning.

I am still getting this warning.

--=20
Cheers,
Stephen Rothwell

--Sig_/j/Z+F3kNQCDQiZbzMTn7/sf
Content-Type: application/pgp-signature
Content-Description: OpenPGP digital signature

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

iQEzBAEBCAAdFiEENIC96giZ81tWdLgKAVBC80lX0GwFAmKdPS4ACgkQAVBC80lX
0GwGjQf/Wpxw16OGellQTN1Pi7+LZv4dT0ZGhL2c5FwQJxKYcGMyrljxCvU5pWot
xzunVUcaed1twyrAZw6hEmWPobS1tBuXcSwGUZAKQmH/zS5obZZ9B534qHTXkSDg
mIvx/xi9EW//ZG51tzbE214iSnD9S01ZJQw5PRm5s621/QAfPGFyHmEskAAx5S0p
xohvRT3l1Q35PJLeFHovPFIQSmbTCV6SObtUWxAJNpnh+x94uI2nCq1z2CXWtB2p
2rUmyCB7XLSsr5LI9pLu8dVpeCGfrnaakKploIhymAsQ07ZDSv7ZwoWu/Ig8/NHa
d6UKuIDmpHzxowhNHlBP+GfOs1xu/g==
=9smW
-----END PGP SIGNATURE-----

--Sig_/j/Z+F3kNQCDQiZbzMTn7/sf--