[PATCH v2] spi: <linux/spi/spi.h>: Add missing documentation for struct members

[PATCH v2] spi: <linux/spi/spi.h>: Add missing documentation for struct members

[David Jander]

Fixes these "make htmldocs" warnings:

include/linux/spi/spi.h:82: warning: Function parameter or member 'syncp' not described in 'spi_statistics'
include/linux/spi/spi.h:213: warning: Function parameter or member 'pcpu_statistics' not described in 'spi_device'
include/linux/spi/spi.h:676: warning: Function parameter or member 'pcpu_statistics' not described in 'spi_controller'

Fixes: 6598b91b5ac3 ("spi: spi.c: Convert statistics to per-cpu u64_stats_t")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Signed-off-by: David Jander <david@protonic.nl>
---
v2:
 - Correct patch subject line style
 - Add the text of the actual warnings that are being fixed
 - Add a Fixes: tag
---
 include/linux/spi/spi.h | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/include/linux/spi/spi.h b/include/linux/spi/spi.h
index eac8d3caf954..2e63b4935deb 100644
--- a/include/linux/spi/spi.h
+++ b/include/linux/spi/spi.h
@@ -35,7 +35,8 @@ extern struct bus_type spi_bus_type;
 
 /**
  * struct spi_statistics - statistics for spi transfers
- * @lock:          lock protecting this structure
+ * @syncp:         seqcount to protect members in this struct for per-cpu udate
+ *                 on 32-bit systems
  *
  * @messages:      number of spi-messages handled
  * @transfers:     number of spi_transfers handled
@@ -155,7 +156,7 @@ extern int spi_delay_exec(struct spi_delay *_delay, struct spi_transfer *xfer);
  * @cs_inactive: delay to be introduced by the controller after CS is
  *	deasserted. If @cs_change_delay is used from @spi_transfer, then the
  *	two delays will be added up.
- * @statistics: statistics for the spi_device
+ * @pcpu_statistics: statistics for the spi_device
  *
  * A @spi_device is used to interchange data between an SPI slave
  * (usually a discrete chip) and CPU memory.
@@ -439,7 +440,7 @@ extern struct spi_device *spi_new_ancillary_device(struct spi_device *spi, u8 ch
  * @max_native_cs: When cs_gpiods is used, and this field is filled in,
  *	spi_register_controller() will validate all native CS (including the
  *	unused native CS) against this value.
- * @statistics: statistics for the spi_controller
+ * @pcpu_statistics: statistics for the spi_controller
  * @dma_tx: DMA transmit channel
  * @dma_rx: DMA receive channel
  * @dummy_rx: dummy receive buffer for full-duplex devices
-- 
2.32.0

Re: [PATCH v2] spi: <linux/spi/spi.h>: Add missing documentation for struct members

[Andy Shevchenko]

On Wed, Jun 8, 2022 at 5:33 PM David Jander <david@protonic.nl> wrote:
>
> Fixes these "make htmldocs" warnings:
>
> include/linux/spi/spi.h:82: warning: Function parameter or member 'syncp' not described in 'spi_statistics'
> include/linux/spi/spi.h:213: warning: Function parameter or member 'pcpu_statistics' not described in 'spi_device'
> include/linux/spi/spi.h:676: warning: Function parameter or member 'pcpu_statistics' not described in 'spi_controller'

Thanks, you may add my
Reviewed-by: Andy Shevchenko <andy.shevchenko@gmail.com>

However, you don't need to put that "<include/...>:" part in the subject line.

> Fixes: 6598b91b5ac3 ("spi: spi.c: Convert statistics to per-cpu u64_stats_t")
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Signed-off-by: David Jander <david@protonic.nl>
> ---
> v2:
>  - Correct patch subject line style
>  - Add the text of the actual warnings that are being fixed
>  - Add a Fixes: tag
> ---
>  include/linux/spi/spi.h | 7 ++++---
>  1 file changed, 4 insertions(+), 3 deletions(-)
>
> diff --git a/include/linux/spi/spi.h b/include/linux/spi/spi.h
> index eac8d3caf954..2e63b4935deb 100644
> --- a/include/linux/spi/spi.h
> +++ b/include/linux/spi/spi.h
> @@ -35,7 +35,8 @@ extern struct bus_type spi_bus_type;
>
>  /**
>   * struct spi_statistics - statistics for spi transfers
> - * @lock:          lock protecting this structure
> + * @syncp:         seqcount to protect members in this struct for per-cpu udate
> + *                 on 32-bit systems
>   *
>   * @messages:      number of spi-messages handled
>   * @transfers:     number of spi_transfers handled
> @@ -155,7 +156,7 @@ extern int spi_delay_exec(struct spi_delay *_delay, struct spi_transfer *xfer);
>   * @cs_inactive: delay to be introduced by the controller after CS is
>   *     deasserted. If @cs_change_delay is used from @spi_transfer, then the
>   *     two delays will be added up.
> - * @statistics: statistics for the spi_device
> + * @pcpu_statistics: statistics for the spi_device
>   *
>   * A @spi_device is used to interchange data between an SPI slave
>   * (usually a discrete chip) and CPU memory.
> @@ -439,7 +440,7 @@ extern struct spi_device *spi_new_ancillary_device(struct spi_device *spi, u8 ch
>   * @max_native_cs: When cs_gpiods is used, and this field is filled in,
>   *     spi_register_controller() will validate all native CS (including the
>   *     unused native CS) against this value.
> - * @statistics: statistics for the spi_controller
> + * @pcpu_statistics: statistics for the spi_controller
>   * @dma_tx: DMA transmit channel
>   * @dma_rx: DMA receive channel
>   * @dummy_rx: dummy receive buffer for full-duplex devices
> --
> 2.32.0
>


-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH v2] spi: <linux/spi/spi.h>: Add missing documentation for struct members

[Mark Brown]

On Wed, 8 Jun 2022 17:33:09 +0200, David Jander wrote:
> Fixes these "make htmldocs" warnings:
> 
> include/linux/spi/spi.h:82: warning: Function parameter or member 'syncp' not described in 'spi_statistics'
> include/linux/spi/spi.h:213: warning: Function parameter or member 'pcpu_statistics' not described in 'spi_device'
> include/linux/spi/spi.h:676: warning: Function parameter or member 'pcpu_statistics' not described in 'spi_controller'
> 
> 
> [...]

Applied to

   https://git.kernel.org/pub/scm/linux/kernel/git/broonie/spi.git for-next

Thanks!

[1/1] spi: <linux/spi/spi.h>: Add missing documentation for struct members
      commit: 5dfac65b621733e69b789150a0a3f1bf2f9095a3

All being well this means that it will be integrated into the linux-next
tree (usually sometime in the next 24 hours) and sent to Linus during
the next merge window (or sooner if it is a bug fix), however if
problems are discovered then the patch may be dropped or reverted.

You may get further e-mails resulting from automated or manual testing
and review of the tree, please engage with people reporting problems and
send followup patches addressing any issues that are reported if needed.

If any updates are required or you are submitting further changes they
should be sent as incremental updates against current git, existing
patches will not be replaced.

Please add any relevant lists and maintainers to the CCs when replying
to this mail.

Thanks,
Mark