[PATCH] platform/mellanox: tmfifo: fix kernel-doc warnings

[PATCH] platform/mellanox: tmfifo: fix kernel-doc warnings

[Randy Dunlap]

Fix kernel-doc notation for structs and struct members to prevent
these warnings:

mlxbf-tmfifo.c:73: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_vring '
mlxbf-tmfifo.c:128: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_vdev '
mlxbf-tmfifo.c:146: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_irq_info '
mlxbf-tmfifo.c:158: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_io '
mlxbf-tmfifo.c:182: warning: cannot understand function prototype: 'struct mlxbf_tmfifo '
mlxbf-tmfifo.c:208: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_msg_hdr '
mlxbf-tmfifo.c:138: warning: Function parameter or member 'config' not described in 'mlxbf_tmfifo_vdev'
mlxbf-tmfifo.c:212: warning: Function parameter or member 'unused' not described in 'mlxbf_tmfifo_msg_hdr'

Fixes: 1357dfd7261f ("platform/mellanox: Add TmFifo driver for Mellanox BlueField Soc")
Fixes: bc05ea63b394 ("platform/mellanox: Add BlueField-3 support in the tmfifo driver")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Reported-by: kernel test robot <lkp@intel.com>
Closes: lore.kernel.org/r/202309252330.saRU491h-lkp@intel.com
Cc: Liming Sun <lsun@mellanox.com>
Cc: Hans de Goede <hdegoede@redhat.com>
Cc: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
Cc: Mark Gross <markgross@kernel.org>
Cc: Vadim Pasternak <vadimp@nvidia.com>
Cc: platform-driver-x86@vger.kernel.org
---
 drivers/platform/mellanox/mlxbf-tmfifo.c |   14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff -- a/drivers/platform/mellanox/mlxbf-tmfifo.c b/drivers/platform/mellanox/mlxbf-tmfifo.c
--- a/drivers/platform/mellanox/mlxbf-tmfifo.c
+++ b/drivers/platform/mellanox/mlxbf-tmfifo.c
@@ -53,7 +53,7 @@
 struct mlxbf_tmfifo;
 
 /**
- * mlxbf_tmfifo_vring - Structure of the TmFifo virtual ring
+ * struct mlxbf_tmfifo_vring - Structure of the TmFifo virtual ring
  * @va: virtual address of the ring
  * @dma: dma address of the ring
  * @vq: pointer to the virtio virtqueue
@@ -113,12 +113,13 @@ enum {
 };
 
 /**
- * mlxbf_tmfifo_vdev - Structure of the TmFifo virtual device
+ * struct mlxbf_tmfifo_vdev - Structure of the TmFifo virtual device
  * @vdev: virtio device, in which the vdev.id.device field has the
  *        VIRTIO_ID_xxx id to distinguish the virtual device.
  * @status: status of the device
  * @features: supported features of the device
  * @vrings: array of tmfifo vrings of this device
+ * @config: non-anonymous union for cons and net
  * @config.cons: virtual console config -
  *               select if vdev.id.device is VIRTIO_ID_CONSOLE
  * @config.net: virtual network config -
@@ -138,7 +139,7 @@ struct mlxbf_tmfifo_vdev {
 };
 
 /**
- * mlxbf_tmfifo_irq_info - Structure of the interrupt information
+ * struct mlxbf_tmfifo_irq_info - Structure of the interrupt information
  * @fifo: pointer to the tmfifo structure
  * @irq: interrupt number
  * @index: index into the interrupt array
@@ -150,7 +151,7 @@ struct mlxbf_tmfifo_irq_info {
 };
 
 /**
- * mlxbf_tmfifo_io - Structure of the TmFifo IO resource (for both rx & tx)
+ * struct mlxbf_tmfifo_io - Structure of the TmFifo IO resource (for both rx & tx)
  * @ctl: control register offset (TMFIFO_RX_CTL / TMFIFO_TX_CTL)
  * @sts: status register offset (TMFIFO_RX_STS / TMFIFO_TX_STS)
  * @data: data register offset (TMFIFO_RX_DATA / TMFIFO_TX_DATA)
@@ -162,7 +163,7 @@ struct mlxbf_tmfifo_io {
 };
 
 /**
- * mlxbf_tmfifo - Structure of the TmFifo
+ * struct mlxbf_tmfifo - Structure of the TmFifo
  * @vdev: array of the virtual devices running over the TmFifo
  * @lock: lock to protect the TmFifo access
  * @res0: mapped resource block 0
@@ -198,7 +199,7 @@ struct mlxbf_tmfifo {
 };
 
 /**
- * mlxbf_tmfifo_msg_hdr - Structure of the TmFifo message header
+ * struct mlxbf_tmfifo_msg_hdr - Structure of the TmFifo message header
  * @type: message type
  * @len: payload length in network byte order. Messages sent into the FIFO
  *       will be read by the other side as data stream in the same byte order.
@@ -208,6 +209,7 @@ struct mlxbf_tmfifo {
 struct mlxbf_tmfifo_msg_hdr {
 	u8 type;
 	__be16 len;
+	/* private: */
 	u8 unused[5];
 } __packed __aligned(sizeof(u64));
 

Re: [PATCH] platform/mellanox: tmfifo: fix kernel-doc warnings

[Ilpo Järvinen]

[-- Attachment #1: Type: text/plain, Size: 4700 bytes --]

On Mon, 25 Sep 2023, Randy Dunlap wrote:

> Fix kernel-doc notation for structs and struct members to prevent
> these warnings:
> 
> mlxbf-tmfifo.c:73: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_vring '
> mlxbf-tmfifo.c:128: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_vdev '
> mlxbf-tmfifo.c:146: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_irq_info '
> mlxbf-tmfifo.c:158: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_io '
> mlxbf-tmfifo.c:182: warning: cannot understand function prototype: 'struct mlxbf_tmfifo '
> mlxbf-tmfifo.c:208: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_msg_hdr '
> mlxbf-tmfifo.c:138: warning: Function parameter or member 'config' not described in 'mlxbf_tmfifo_vdev'
> mlxbf-tmfifo.c:212: warning: Function parameter or member 'unused' not described in 'mlxbf_tmfifo_msg_hdr'
> 
> Fixes: 1357dfd7261f ("platform/mellanox: Add TmFifo driver for Mellanox BlueField Soc")
> Fixes: bc05ea63b394 ("platform/mellanox: Add BlueField-3 support in the tmfifo driver")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Reported-by: kernel test robot <lkp@intel.com>
> Closes: lore.kernel.org/r/202309252330.saRU491h-lkp@intel.com
> Cc: Liming Sun <lsun@mellanox.com>
> Cc: Hans de Goede <hdegoede@redhat.com>
> Cc: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
> Cc: Mark Gross <markgross@kernel.org>
> Cc: Vadim Pasternak <vadimp@nvidia.com>
> Cc: platform-driver-x86@vger.kernel.org
> ---
>  drivers/platform/mellanox/mlxbf-tmfifo.c |   14 ++++++++------
>  1 file changed, 8 insertions(+), 6 deletions(-)
> 
> diff -- a/drivers/platform/mellanox/mlxbf-tmfifo.c b/drivers/platform/mellanox/mlxbf-tmfifo.c
> --- a/drivers/platform/mellanox/mlxbf-tmfifo.c
> +++ b/drivers/platform/mellanox/mlxbf-tmfifo.c
> @@ -53,7 +53,7 @@
>  struct mlxbf_tmfifo;
>  
>  /**
> - * mlxbf_tmfifo_vring - Structure of the TmFifo virtual ring
> + * struct mlxbf_tmfifo_vring - Structure of the TmFifo virtual ring
>   * @va: virtual address of the ring
>   * @dma: dma address of the ring
>   * @vq: pointer to the virtio virtqueue
> @@ -113,12 +113,13 @@ enum {
>  };
>  
>  /**
> - * mlxbf_tmfifo_vdev - Structure of the TmFifo virtual device
> + * struct mlxbf_tmfifo_vdev - Structure of the TmFifo virtual device
>   * @vdev: virtio device, in which the vdev.id.device field has the
>   *        VIRTIO_ID_xxx id to distinguish the virtual device.
>   * @status: status of the device
>   * @features: supported features of the device
>   * @vrings: array of tmfifo vrings of this device
> + * @config: non-anonymous union for cons and net

I wonder what information this adds? It's not documenting anything else 
than C syntax, IMO.

Would it be possible to make kerneldoc not give warning from a named union 
which is already fully documented?

-- 
 i.

>   * @config.cons: virtual console config -
>   *               select if vdev.id.device is VIRTIO_ID_CONSOLE
>   * @config.net: virtual network config -
> @@ -138,7 +139,7 @@ struct mlxbf_tmfifo_vdev {
>  };
>  
>  /**
> - * mlxbf_tmfifo_irq_info - Structure of the interrupt information
> + * struct mlxbf_tmfifo_irq_info - Structure of the interrupt information
>   * @fifo: pointer to the tmfifo structure
>   * @irq: interrupt number
>   * @index: index into the interrupt array
> @@ -150,7 +151,7 @@ struct mlxbf_tmfifo_irq_info {
>  };
>  
>  /**
> - * mlxbf_tmfifo_io - Structure of the TmFifo IO resource (for both rx & tx)
> + * struct mlxbf_tmfifo_io - Structure of the TmFifo IO resource (for both rx & tx)
>   * @ctl: control register offset (TMFIFO_RX_CTL / TMFIFO_TX_CTL)
>   * @sts: status register offset (TMFIFO_RX_STS / TMFIFO_TX_STS)
>   * @data: data register offset (TMFIFO_RX_DATA / TMFIFO_TX_DATA)
> @@ -162,7 +163,7 @@ struct mlxbf_tmfifo_io {
>  };
>  
>  /**
> - * mlxbf_tmfifo - Structure of the TmFifo
> + * struct mlxbf_tmfifo - Structure of the TmFifo
>   * @vdev: array of the virtual devices running over the TmFifo
>   * @lock: lock to protect the TmFifo access
>   * @res0: mapped resource block 0
> @@ -198,7 +199,7 @@ struct mlxbf_tmfifo {
>  };
>  
>  /**
> - * mlxbf_tmfifo_msg_hdr - Structure of the TmFifo message header
> + * struct mlxbf_tmfifo_msg_hdr - Structure of the TmFifo message header
>   * @type: message type
>   * @len: payload length in network byte order. Messages sent into the FIFO
>   *       will be read by the other side as data stream in the same byte order.
> @@ -208,6 +209,7 @@ struct mlxbf_tmfifo {
>  struct mlxbf_tmfifo_msg_hdr {
>  	u8 type;
>  	__be16 len;
> +	/* private: */
>  	u8 unused[5];
>  } __packed __aligned(sizeof(u64));
>  
> 

Re: [PATCH] platform/mellanox: tmfifo: fix kernel-doc warnings

[Randy Dunlap]

Hi,

On 9/26/23 09:18, Ilpo Järvinen wrote:
> On Mon, 25 Sep 2023, Randy Dunlap wrote:
> 
>> Fix kernel-doc notation for structs and struct members to prevent
>> these warnings:
>>
>> mlxbf-tmfifo.c:73: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_vring '
>> mlxbf-tmfifo.c:128: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_vdev '
>> mlxbf-tmfifo.c:146: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_irq_info '
>> mlxbf-tmfifo.c:158: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_io '
>> mlxbf-tmfifo.c:182: warning: cannot understand function prototype: 'struct mlxbf_tmfifo '
>> mlxbf-tmfifo.c:208: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_msg_hdr '
>> mlxbf-tmfifo.c:138: warning: Function parameter or member 'config' not described in 'mlxbf_tmfifo_vdev'
>> mlxbf-tmfifo.c:212: warning: Function parameter or member 'unused' not described in 'mlxbf_tmfifo_msg_hdr'
>>
>> Fixes: 1357dfd7261f ("platform/mellanox: Add TmFifo driver for Mellanox BlueField Soc")
>> Fixes: bc05ea63b394 ("platform/mellanox: Add BlueField-3 support in the tmfifo driver")
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> Reported-by: kernel test robot <lkp@intel.com>
>> Closes: lore.kernel.org/r/202309252330.saRU491h-lkp@intel.com
>> Cc: Liming Sun <lsun@mellanox.com>
>> Cc: Hans de Goede <hdegoede@redhat.com>
>> Cc: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
>> Cc: Mark Gross <markgross@kernel.org>
>> Cc: Vadim Pasternak <vadimp@nvidia.com>
>> Cc: platform-driver-x86@vger.kernel.org
>> ---
>>  drivers/platform/mellanox/mlxbf-tmfifo.c |   14 ++++++++------
>>  1 file changed, 8 insertions(+), 6 deletions(-)
>>
>> diff -- a/drivers/platform/mellanox/mlxbf-tmfifo.c b/drivers/platform/mellanox/mlxbf-tmfifo.c
>> --- a/drivers/platform/mellanox/mlxbf-tmfifo.c
>> +++ b/drivers/platform/mellanox/mlxbf-tmfifo.c
>> @@ -53,7 +53,7 @@
>>  struct mlxbf_tmfifo;
>>  
>>  /**
>> - * mlxbf_tmfifo_vring - Structure of the TmFifo virtual ring
>> + * struct mlxbf_tmfifo_vring - Structure of the TmFifo virtual ring
>>   * @va: virtual address of the ring
>>   * @dma: dma address of the ring
>>   * @vq: pointer to the virtio virtqueue
>> @@ -113,12 +113,13 @@ enum {
>>  };
>>  
>>  /**
>> - * mlxbf_tmfifo_vdev - Structure of the TmFifo virtual device
>> + * struct mlxbf_tmfifo_vdev - Structure of the TmFifo virtual device
>>   * @vdev: virtio device, in which the vdev.id.device field has the
>>   *        VIRTIO_ID_xxx id to distinguish the virtual device.
>>   * @status: status of the device
>>   * @features: supported features of the device
>>   * @vrings: array of tmfifo vrings of this device
>> + * @config: non-anonymous union for cons and net
> 
> I wonder what information this adds? It's not documenting anything else 
> than C syntax, IMO.
> 
> Would it be possible to make kerneldoc not give warning from a named union 
> which is already fully documented?

I don't know. Maybe.
I have no idea if anyone has ever looked into doing that.

I'm adding Mauro since he did the nested struct/union kernel-doc code.

~Randy

Re: [PATCH] platform/mellanox: tmfifo: fix kernel-doc warnings

[Hans de Goede]

Hi,

On 9/26/23 07:40, Randy Dunlap wrote:
> Fix kernel-doc notation for structs and struct members to prevent
> these warnings:
> 
> mlxbf-tmfifo.c:73: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_vring '
> mlxbf-tmfifo.c:128: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_vdev '
> mlxbf-tmfifo.c:146: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_irq_info '
> mlxbf-tmfifo.c:158: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_io '
> mlxbf-tmfifo.c:182: warning: cannot understand function prototype: 'struct mlxbf_tmfifo '
> mlxbf-tmfifo.c:208: warning: cannot understand function prototype: 'struct mlxbf_tmfifo_msg_hdr '
> mlxbf-tmfifo.c:138: warning: Function parameter or member 'config' not described in 'mlxbf_tmfifo_vdev'
> mlxbf-tmfifo.c:212: warning: Function parameter or member 'unused' not described in 'mlxbf_tmfifo_msg_hdr'
> 
> Fixes: 1357dfd7261f ("platform/mellanox: Add TmFifo driver for Mellanox BlueField Soc")
> Fixes: bc05ea63b394 ("platform/mellanox: Add BlueField-3 support in the tmfifo driver")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Reported-by: kernel test robot <lkp@intel.com>
> Closes: lore.kernel.org/r/202309252330.saRU491h-lkp@intel.com
> Cc: Liming Sun <lsun@mellanox.com>
> Cc: Hans de Goede <hdegoede@redhat.com>
> Cc: Ilpo Järvinen <ilpo.jarvinen@linux.intel.com>
> Cc: Mark Gross <markgross@kernel.org>
> Cc: Vadim Pasternak <vadimp@nvidia.com>
> Cc: platform-driver-x86@vger.kernel.org

Thank you for your patch/series, I've applied this patch
(series) to the pdx86 fixes branch:
https://git.kernel.org/pub/scm/linux/kernel/git/pdx86/platform-drivers-x86.git/log/?h=fixes

Note it will show up in the pdx86 fixes branch once I've pushed
my local branch there, which might take a while.

I will include this patch in my next fixes pull-req to Linus
for the current kernel development cycle.

Regards,

Hans




> ---
>  drivers/platform/mellanox/mlxbf-tmfifo.c |   14 ++++++++------
>  1 file changed, 8 insertions(+), 6 deletions(-)
> 
> diff -- a/drivers/platform/mellanox/mlxbf-tmfifo.c b/drivers/platform/mellanox/mlxbf-tmfifo.c
> --- a/drivers/platform/mellanox/mlxbf-tmfifo.c
> +++ b/drivers/platform/mellanox/mlxbf-tmfifo.c
> @@ -53,7 +53,7 @@
>  struct mlxbf_tmfifo;
>  
>  /**
> - * mlxbf_tmfifo_vring - Structure of the TmFifo virtual ring
> + * struct mlxbf_tmfifo_vring - Structure of the TmFifo virtual ring
>   * @va: virtual address of the ring
>   * @dma: dma address of the ring
>   * @vq: pointer to the virtio virtqueue
> @@ -113,12 +113,13 @@ enum {
>  };
>  
>  /**
> - * mlxbf_tmfifo_vdev - Structure of the TmFifo virtual device
> + * struct mlxbf_tmfifo_vdev - Structure of the TmFifo virtual device
>   * @vdev: virtio device, in which the vdev.id.device field has the
>   *        VIRTIO_ID_xxx id to distinguish the virtual device.
>   * @status: status of the device
>   * @features: supported features of the device
>   * @vrings: array of tmfifo vrings of this device
> + * @config: non-anonymous union for cons and net
>   * @config.cons: virtual console config -
>   *               select if vdev.id.device is VIRTIO_ID_CONSOLE
>   * @config.net: virtual network config -
> @@ -138,7 +139,7 @@ struct mlxbf_tmfifo_vdev {
>  };
>  
>  /**
> - * mlxbf_tmfifo_irq_info - Structure of the interrupt information
> + * struct mlxbf_tmfifo_irq_info - Structure of the interrupt information
>   * @fifo: pointer to the tmfifo structure
>   * @irq: interrupt number
>   * @index: index into the interrupt array
> @@ -150,7 +151,7 @@ struct mlxbf_tmfifo_irq_info {
>  };
>  
>  /**
> - * mlxbf_tmfifo_io - Structure of the TmFifo IO resource (for both rx & tx)
> + * struct mlxbf_tmfifo_io - Structure of the TmFifo IO resource (for both rx & tx)
>   * @ctl: control register offset (TMFIFO_RX_CTL / TMFIFO_TX_CTL)
>   * @sts: status register offset (TMFIFO_RX_STS / TMFIFO_TX_STS)
>   * @data: data register offset (TMFIFO_RX_DATA / TMFIFO_TX_DATA)
> @@ -162,7 +163,7 @@ struct mlxbf_tmfifo_io {
>  };
>  
>  /**
> - * mlxbf_tmfifo - Structure of the TmFifo
> + * struct mlxbf_tmfifo - Structure of the TmFifo
>   * @vdev: array of the virtual devices running over the TmFifo
>   * @lock: lock to protect the TmFifo access
>   * @res0: mapped resource block 0
> @@ -198,7 +199,7 @@ struct mlxbf_tmfifo {
>  };
>  
>  /**
> - * mlxbf_tmfifo_msg_hdr - Structure of the TmFifo message header
> + * struct mlxbf_tmfifo_msg_hdr - Structure of the TmFifo message header
>   * @type: message type
>   * @len: payload length in network byte order. Messages sent into the FIFO
>   *       will be read by the other side as data stream in the same byte order.
> @@ -208,6 +209,7 @@ struct mlxbf_tmfifo {
>  struct mlxbf_tmfifo_msg_hdr {
>  	u8 type;
>  	__be16 len;
> +	/* private: */
>  	u8 unused[5];
>  } __packed __aligned(sizeof(u64));
>  
>