| Message ID | 20230926054013.11450-1-rdunlap@infradead.org (mailing list archive) |
|---|---|
| State | Accepted, archived |
| Delegated to: | Hans de Goede |
| Headers | show |
| Series | platform/mellanox: tmfifo: fix kernel-doc warnings | expand |
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?
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
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)); > >
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));
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(-)