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@xxxxxxxxxxxxx>
> Reported-by: kernel test robot <lkp@xxxxxxxxx>
> Closes: lore.kernel.org/r/202309252330.saRU491h-lkp@xxxxxxxxx
> Cc: Liming Sun <lsun@xxxxxxxxxxxx>
> Cc: Hans de Goede <hdegoede@xxxxxxxxxx>
> Cc: Ilpo Järvinen <ilpo.jarvinen@xxxxxxxxxxxxxxx>
> Cc: Mark Gross <markgross@xxxxxxxxxx>
> Cc: Vadim Pasternak <vadimp@xxxxxxxxxx>
> Cc: platform-driver-x86@xxxxxxxxxxxxxxx
> ---
> 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));
>
>
