Skip to contentSkip to conversation

linux-next: build warning after merge of the pinctrl tree

DISCUSSION Stephen Rothwell 3 participants 6 messages Oct 27, 2021 – Jun 5, 2022 Linux-next tree

lore
Share & tools
lore
#0 lore raw

Hi all,

After merging the pinctrl tree, today's linux-next build (htmldocs) produced this warning:

include/linux/gpio/driver.h:284: warning: Function parameter or member 'parent_handler_data_array' not described in 'gpio_irq_chip'

Introduced by commit

cfe6807d82e9 ("gpio: Allow per-parent interrupt data")

But may actually be a problem with the tool :-(

Signature · 2 lines
Cheers,
Stephen Rothwell
#1 lore raw
Quoted 6 lines · Stephen Rothwell

Hi all,

After merging the pinctrl tree, today's linux-next build (htmldocs) produced this warning:

Quoted 7 lines

include/linux/gpio/driver.h:284: warning: Function parameter or member 'parent_handler_data_array' not described in 'gpio_irq_chip'

Introduced by commit

cfe6807d82e9 ("gpio: Allow per-parent interrupt data")

But may actually be a problem with the tool :-(

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.

	M.
Signature · 1 line
Without deviation from the norm, progress is not possible.
#2 lore raw

Em Wed, 27 Oct 2021 12:10:45 +0100
Marc Zyngier <[email protected]> escreveu:

Quoted 12 lines
Quoted 10 lines · Stephen Rothwell

Hi all,

After merging the pinctrl tree, today's linux-next build (htmldocs) produced this warning:

include/linux/gpio/driver.h:284: warning: Function parameter or member 'parent_handler_data_array' not described in 'gpio_irq_chip'

Introduced by commit

Quoted 7 lines
Quoted 3 lines

cfe6807d82e9 ("gpio: Allow per-parent interrupt data")

But may actually be a problem with the tool :-(

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.

Yes, that's the case. See, when you do:

	/**
	 * @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;
	};

The tool will understand it as an undocumented "parent_handler_data" and a documented "parent_handler_data_array".

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.

The solution would be to add a description for both, e. g. something similar to:

/**
* @parent_handler_data:
*
* If @per_parent_data is false, contains a single pointer
* with the data associated, and passed to, the handler for the
* parent interrupt.
*
* @parent_handler_data_array:
*
* If @per_parent_data is true, it should contain an array of
* @num_parents pointers with the data associated, and passed to,
* the handler for the parent interrupt. Cannot be NULL. */

Regards,
Mauro

#3 lore raw

Hi all,

Quoted 47 lines · On Thu, 28 Oct 2021 08:03:31 +0100 Mauro Carvalho Chehab <[email protected]>…

Em Wed, 27 Oct 2021 12:10:45 +0100
Marc Zyngier <[email protected]> escreveu:

Quoted 9 lines · Stephen Rothwell
Quoted 8 lines

After merging the pinctrl tree, today's linux-next build (htmldocs) produced this warning:

include/linux/gpio/driver.h:284: warning: Function parameter or member 'parent_handler_data_array' not described in 'gpio_irq_chip'

Introduced by commit

Quoted 7 lines
Quoted 3 lines

cfe6807d82e9 ("gpio: Allow per-parent interrupt data")

But may actually be a problem with the tool :-(

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.

Yes, that's the case. See, when you do:

	/**
	 * @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;
	};

The tool will understand it as an undocumented "parent_handler_data" and a documented "parent_handler_data_array".

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.

The solution would be to add a description for both, e. g. something similar to:

Quoted 13 lines

/**
* @parent_handler_data:
*
* If @per_parent_data is false, contains a single pointer
* with the data associated, and passed to, the handler for the
* parent interrupt.
*
* @parent_handler_data_array:
*
* If @per_parent_data is true, it should contain an array of
* @num_parents pointers with the data associated, and passed to,
* the handler for the parent interrupt. Cannot be NULL. */

I am still getting this warning.

Signature · 2 lines
Cheers,
Stephen Rothwell
#4 lore raw

Hi all,

Quoted 63 lines · On Thu, 20 Jan 2022 14:25:39 +1100 Stephen Rothwell <[email protected]>…
Quoted 47 lines · On Thu, 28 Oct 2021 08:03:31 +0100 Mauro Carvalho Chehab <[email protected]>…

Em Wed, 27 Oct 2021 12:10:45 +0100
Marc Zyngier <[email protected]> escreveu:

Quoted 9 lines · Stephen Rothwell
Quoted 8 lines

After merging the pinctrl tree, today's linux-next build (htmldocs) produced this warning:

include/linux/gpio/driver.h:284: warning: Function parameter or member 'parent_handler_data_array' not described in 'gpio_irq_chip'

Introduced by commit

Quoted 7 lines
Quoted 3 lines

cfe6807d82e9 ("gpio: Allow per-parent interrupt data")

But may actually be a problem with the tool :-(

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.

Yes, that's the case. See, when you do:

	/**
	 * @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;
	};

The tool will understand it as an undocumented "parent_handler_data" and a documented "parent_handler_data_array".

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.

The solution would be to add a description for both, e. g. something similar to:

Quoted 13 lines

/**
* @parent_handler_data:
*
* If @per_parent_data is false, contains a single pointer
* with the data associated, and passed to, the handler for the
* parent interrupt.
*
* @parent_handler_data_array:
*
* If @per_parent_data is true, it should contain an array of
* @num_parents pointers with the data associated, and passed to,
* the handler for the parent interrupt. Cannot be NULL. */

Quoted 1 line

I am still getting this warning.

I am still getting this warning.

Signature · 2 lines
Cheers,
Stephen Rothwell
#5 lore raw

Hi all,

Quoted 65 lines · On Fri, 18 Mar 2022 18:31:01 +1100 Stephen Rothwell <[email protected]>…
Quoted 63 lines · On Thu, 20 Jan 2022 14:25:39 +1100 Stephen Rothwell <[email protected]>…
Quoted 60 lines · On Thu, 28 Oct 2021 08:03:31 +0100 Mauro Carvalho Chehab <[email protected]>…

Em Wed, 27 Oct 2021 12:10:45 +0100
Marc Zyngier <[email protected]> escreveu:

Quoted 9 lines · Stephen Rothwell
Quoted 8 lines

After merging the pinctrl tree, today's linux-next build (htmldocs) produced this warning:

include/linux/gpio/driver.h:284: warning: Function parameter or member 'parent_handler_data_array' not described in 'gpio_irq_chip'

Introduced by commit

Quoted 7 lines
Quoted 3 lines

cfe6807d82e9 ("gpio: Allow per-parent interrupt data")

But may actually be a problem with the tool :-(

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.

Yes, that's the case. See, when you do:

	/**
	 * @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;
	};

The tool will understand it as an undocumented "parent_handler_data" and a documented "parent_handler_data_array".

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.

The solution would be to add a description for both, e. g. something similar to:

/**
* @parent_handler_data:
*
* If @per_parent_data is false, contains a single pointer
* with the data associated, and passed to, the handler for the
* parent interrupt.
*
* @parent_handler_data_array:
*
* If @per_parent_data is true, it should contain an array of
* @num_parents pointers with the data associated, and passed to,
* the handler for the parent interrupt. Cannot be NULL. */

Quoted 3 lines
Quoted 1 line

I am still getting this warning.

I am still getting this warning.

I am still getting this warning.

Signature · 2 lines
Cheers,
Stephen Rothwell