[PATCH rdma-rc 0/2] W=1 compilation fixes leftovers

[PATCH rdma-rc 0/2] W=1 compilation fixes leftovers

[Leon Romanovsky]

From: Leon Romanovsky <leonro@nvidia.com>

Two extra fixes that were missed in Lee's W=1 cleanup.

Leon Romanovsky (2):
  RDMA/mlx5: Set correct kernel-doc identifier
  RDMA/uverbs: Fix kernel-doc warning of _uverbs_alloc

 drivers/infiniband/core/uverbs_ioctl.c | 4 ++--
 drivers/infiniband/hw/mlx5/odp.c       | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

--
2.29.2

[PATCH rdma-rc 1/2] RDMA/mlx5: Set correct kernel-doc identifier

[Leon Romanovsky]

From: Leon Romanovsky <leonro@nvidia.com>

The W=1 allmodconfig build produces the following warning:
drivers/infiniband/hw/mlx5/odp.c:1086: warning: wrong kernel-doc identifier on line:
  * Parse a series of data segments for page fault handling.

Fix it by changing /** to be /* as it is written in kernel-doc documentation.

Fixes: 5e769e444d26 ("RDMA/hw/mlx5/odp: Fix formatting and add missing descriptions in 'pagefault_data_segments()'")
Signed-off-by: Leon Romanovsky <leonro@nvidia.com>
---
 drivers/infiniband/hw/mlx5/odp.c | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/drivers/infiniband/hw/mlx5/odp.c b/drivers/infiniband/hw/mlx5/odp.c
index 374698186662..b103555b1f5d 100644
--- a/drivers/infiniband/hw/mlx5/odp.c
+++ b/drivers/infiniband/hw/mlx5/odp.c
@@ -1082,7 +1082,7 @@ static int pagefault_single_data_segment(struct mlx5_ib_dev *dev,
 	return ret ? ret : npages;
 }

-/**
+/*
  * Parse a series of data segments for page fault handling.
  *
  * @dev:  Pointer to mlx5 IB device
--
2.29.2

Re: [PATCH rdma-rc 1/2] RDMA/mlx5: Set correct kernel-doc identifier

[Lee Jones]

On Tue, 02 Mar 2021, Leon Romanovsky wrote:

> From: Leon Romanovsky <leonro@nvidia.com>
> 
> The W=1 allmodconfig build produces the following warning:
> drivers/infiniband/hw/mlx5/odp.c:1086: warning: wrong kernel-doc identifier on line:
>   * Parse a series of data segments for page fault handling.
> 
> Fix it by changing /** to be /* as it is written in kernel-doc documentation.
> 
> Fixes: 5e769e444d26 ("RDMA/hw/mlx5/odp: Fix formatting and add missing descriptions in 'pagefault_data_segments()'")
> Signed-off-by: Leon Romanovsky <leonro@nvidia.com>
> ---
>  drivers/infiniband/hw/mlx5/odp.c | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/drivers/infiniband/hw/mlx5/odp.c b/drivers/infiniband/hw/mlx5/odp.c
> index 374698186662..b103555b1f5d 100644
> --- a/drivers/infiniband/hw/mlx5/odp.c
> +++ b/drivers/infiniband/hw/mlx5/odp.c
> @@ -1082,7 +1082,7 @@ static int pagefault_single_data_segment(struct mlx5_ib_dev *dev,
>  	return ret ? ret : npages;
>  }
> 
> -/**
> +/*

This is not the correct fix.

Kernel-doc is asking for the function name.

>   * Parse a series of data segments for page fault handling.
>   *
>   * @dev:  Pointer to mlx5 IB device

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog

Re: [PATCH rdma-rc 1/2] RDMA/mlx5: Set correct kernel-doc identifier

[Leon Romanovsky]

On Tue, Mar 02, 2021 at 09:31:09AM +0000, Lee Jones wrote:
> On Tue, 02 Mar 2021, Leon Romanovsky wrote:
>
> > From: Leon Romanovsky <leonro@nvidia.com>
> >
> > The W=1 allmodconfig build produces the following warning:
> > drivers/infiniband/hw/mlx5/odp.c:1086: warning: wrong kernel-doc identifier on line:
> >   * Parse a series of data segments for page fault handling.
> >
> > Fix it by changing /** to be /* as it is written in kernel-doc documentation.
> >
> > Fixes: 5e769e444d26 ("RDMA/hw/mlx5/odp: Fix formatting and add missing descriptions in 'pagefault_data_segments()'")
> > Signed-off-by: Leon Romanovsky <leonro@nvidia.com>
> > ---
> >  drivers/infiniband/hw/mlx5/odp.c | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> >
> > diff --git a/drivers/infiniband/hw/mlx5/odp.c b/drivers/infiniband/hw/mlx5/odp.c
> > index 374698186662..b103555b1f5d 100644
> > --- a/drivers/infiniband/hw/mlx5/odp.c
> > +++ b/drivers/infiniband/hw/mlx5/odp.c
> > @@ -1082,7 +1082,7 @@ static int pagefault_single_data_segment(struct mlx5_ib_dev *dev,
> >  	return ret ? ret : npages;
> >  }
> >
> > -/**
> > +/*
>
> This is not the correct fix.

I don't want kernel-doc comments on static function. It is local to this
file, so change from /** to /* was to mark that this is not kernel-doc.

>
> Kernel-doc is asking for the function name.

The thing is that I don't want it to be kernel-doc.

Thanks

Re: [PATCH rdma-rc 1/2] RDMA/mlx5: Set correct kernel-doc identifier

[Lee Jones]

On Tue, 02 Mar 2021, Leon Romanovsky wrote:

> On Tue, Mar 02, 2021 at 09:31:09AM +0000, Lee Jones wrote:
> > On Tue, 02 Mar 2021, Leon Romanovsky wrote:
> >
> > > From: Leon Romanovsky <leonro@nvidia.com>
> > >
> > > The W=1 allmodconfig build produces the following warning:
> > > drivers/infiniband/hw/mlx5/odp.c:1086: warning: wrong kernel-doc identifier on line:
> > >   * Parse a series of data segments for page fault handling.
> > >
> > > Fix it by changing /** to be /* as it is written in kernel-doc documentation.
> > >
> > > Fixes: 5e769e444d26 ("RDMA/hw/mlx5/odp: Fix formatting and add missing descriptions in 'pagefault_data_segments()'")
> > > Signed-off-by: Leon Romanovsky <leonro@nvidia.com>
> > > ---
> > >  drivers/infiniband/hw/mlx5/odp.c | 2 +-
> > >  1 file changed, 1 insertion(+), 1 deletion(-)
> > >
> > > diff --git a/drivers/infiniband/hw/mlx5/odp.c b/drivers/infiniband/hw/mlx5/odp.c
> > > index 374698186662..b103555b1f5d 100644
> > > --- a/drivers/infiniband/hw/mlx5/odp.c
> > > +++ b/drivers/infiniband/hw/mlx5/odp.c
> > > @@ -1082,7 +1082,7 @@ static int pagefault_single_data_segment(struct mlx5_ib_dev *dev,
> > >  	return ret ? ret : npages;
> > >  }
> > >
> > > -/**
> > > +/*
> >
> > This is not the correct fix.
> 
> I don't want kernel-doc comments on static function. It is local to this
> file, so change from /** to /* was to mark that this is not kernel-doc.
> 
> >
> > Kernel-doc is asking for the function name.
> 
> The thing is that I don't want it to be kernel-doc.

In the past, if the authors have made a good effort to document the
function, I have left the kernel-doc formatting in place.  It looks
odd / non-consistent to demote some, but not others.  Especially
considering there are 100's if not 1000's of other static functions
documented in the kernel with kernel-doc formatting.

There are also 1000's of uses that are left referenced by kernel-doc::
tags.  See: scripts/find-unused-docs.sh for more details.

If you're going to go through with this, you should at least say what
you're doing and why in the commit message.  Since demoting an
otherwise full and complete kernel-doc header seems a little harsh to
say the least.

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog

Re: [PATCH rdma-rc 1/2] RDMA/mlx5: Set correct kernel-doc identifier

[Leon Romanovsky]

On Tue, Mar 02, 2021 at 10:44:10AM +0000, Lee Jones wrote:
> On Tue, 02 Mar 2021, Leon Romanovsky wrote:
>
> > On Tue, Mar 02, 2021 at 09:31:09AM +0000, Lee Jones wrote:
> > > On Tue, 02 Mar 2021, Leon Romanovsky wrote:
> > >
> > > > From: Leon Romanovsky <leonro@nvidia.com>
> > > >
> > > > The W=1 allmodconfig build produces the following warning:
> > > > drivers/infiniband/hw/mlx5/odp.c:1086: warning: wrong kernel-doc identifier on line:
> > > >   * Parse a series of data segments for page fault handling.
> > > >
> > > > Fix it by changing /** to be /* as it is written in kernel-doc documentation.
> > > >
> > > > Fixes: 5e769e444d26 ("RDMA/hw/mlx5/odp: Fix formatting and add missing descriptions in 'pagefault_data_segments()'")
> > > > Signed-off-by: Leon Romanovsky <leonro@nvidia.com>
> > > > ---
> > > >  drivers/infiniband/hw/mlx5/odp.c | 2 +-
> > > >  1 file changed, 1 insertion(+), 1 deletion(-)
> > > >
> > > > diff --git a/drivers/infiniband/hw/mlx5/odp.c b/drivers/infiniband/hw/mlx5/odp.c
> > > > index 374698186662..b103555b1f5d 100644
> > > > --- a/drivers/infiniband/hw/mlx5/odp.c
> > > > +++ b/drivers/infiniband/hw/mlx5/odp.c
> > > > @@ -1082,7 +1082,7 @@ static int pagefault_single_data_segment(struct mlx5_ib_dev *dev,
> > > >  	return ret ? ret : npages;
> > > >  }
> > > >
> > > > -/**
> > > > +/*
> > >
> > > This is not the correct fix.
> >
> > I don't want kernel-doc comments on static function. It is local to this
> > file, so change from /** to /* was to mark that this is not kernel-doc.
> >
> > >
> > > Kernel-doc is asking for the function name.
> >
> > The thing is that I don't want it to be kernel-doc.
>
> In the past, if the authors have made a good effort to document the
> function, I have left the kernel-doc formatting in place.  It looks
> odd / non-consistent to demote some, but not others.  Especially
> considering there are 100's if not 1000's of other static functions
> documented in the kernel with kernel-doc formatting.

I'm not interested to solve all kernel-doc issues, but only specific to
drivers/infiniband and especially this mlx5 driver which is under my
responsibility.

>
> There are also 1000's of uses that are left referenced by kernel-doc::
> tags.  See: scripts/find-unused-docs.sh for more details.
>
> If you're going to go through with this, you should at least say what
> you're doing and why in the commit message.  Since demoting an
> otherwise full and complete kernel-doc header seems a little harsh to
> say the least.

It wasn't kernel-doc from the beginning.

Thanks

>
> --
> Lee Jones [李琼斯]
> Senior Technical Lead - Developer Services
> Linaro.org │ Open source software for Arm SoCs
> Follow Linaro: Facebook | Twitter | Blog

[PATCH rdma-rc 2/2] RDMA/uverbs: Fix kernel-doc warning of _uverbs_alloc

[Leon Romanovsky]

From: Leon Romanovsky <leonro@nvidia.com>

Fix the following W=1 compilation warning:
drivers/infiniband/core/uverbs_ioctl.c:108: warning: expecting prototype for uverbs_alloc(). Prototype was for _uverbs_alloc() instead

Fixes: 461bb2eee4e1 ("IB/uverbs: Add a simple allocator to uverbs_attr_bundle")
Signed-off-by: Leon Romanovsky <leonro@nvidia.com>
---
 drivers/infiniband/core/uverbs_ioctl.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/infiniband/core/uverbs_ioctl.c b/drivers/infiniband/core/uverbs_ioctl.c
index e47c5949013f..3871049a48f7 100644
--- a/drivers/infiniband/core/uverbs_ioctl.c
+++ b/drivers/infiniband/core/uverbs_ioctl.c
@@ -90,8 +90,8 @@ void uapi_compute_bundle_size(struct uverbs_api_ioctl_method *method_elm,
 	WARN_ON_ONCE(method_elm->bundle_size > PAGE_SIZE);
 }

-/**
- * uverbs_alloc() - Quickly allocate memory for use with a bundle
+/*
+ * _uverbs_alloc() - Quickly allocate memory for use with a bundle
  * @bundle: The bundle
  * @size: Number of bytes to allocate
  * @flags: Allocator flags
--
2.29.2

Re: [PATCH rdma-rc 2/2] RDMA/uverbs: Fix kernel-doc warning of _uverbs_alloc

[Lee Jones]

On Tue, 02 Mar 2021, Leon Romanovsky wrote:

> From: Leon Romanovsky <leonro@nvidia.com>
> 
> Fix the following W=1 compilation warning:
> drivers/infiniband/core/uverbs_ioctl.c:108: warning: expecting prototype for uverbs_alloc(). Prototype was for _uverbs_alloc() instead
> 
> Fixes: 461bb2eee4e1 ("IB/uverbs: Add a simple allocator to uverbs_attr_bundle")
> Signed-off-by: Leon Romanovsky <leonro@nvidia.com>
> ---
>  drivers/infiniband/core/uverbs_ioctl.c | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/infiniband/core/uverbs_ioctl.c b/drivers/infiniband/core/uverbs_ioctl.c
> index e47c5949013f..3871049a48f7 100644
> --- a/drivers/infiniband/core/uverbs_ioctl.c
> +++ b/drivers/infiniband/core/uverbs_ioctl.c
> @@ -90,8 +90,8 @@ void uapi_compute_bundle_size(struct uverbs_api_ioctl_method *method_elm,
>  	WARN_ON_ONCE(method_elm->bundle_size > PAGE_SIZE);
>  }
> 
> -/**
> - * uverbs_alloc() - Quickly allocate memory for use with a bundle
> +/*

Why are you also demoting the header?

It looks fine to me.  Just correct the function name.

> + * _uverbs_alloc() - Quickly allocate memory for use with a bundle
>   * @bundle: The bundle
>   * @size: Number of bytes to allocate
>   * @flags: Allocator flags

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog

Re: [PATCH rdma-rc 2/2] RDMA/uverbs: Fix kernel-doc warning of _uverbs_alloc

[Leon Romanovsky]

On Tue, Mar 02, 2021 at 09:32:23AM +0000, Lee Jones wrote:
> On Tue, 02 Mar 2021, Leon Romanovsky wrote:
>
> > From: Leon Romanovsky <leonro@nvidia.com>
> >
> > Fix the following W=1 compilation warning:
> > drivers/infiniband/core/uverbs_ioctl.c:108: warning: expecting prototype for uverbs_alloc(). Prototype was for _uverbs_alloc() instead
> >
> > Fixes: 461bb2eee4e1 ("IB/uverbs: Add a simple allocator to uverbs_attr_bundle")
> > Signed-off-by: Leon Romanovsky <leonro@nvidia.com>
> > ---
> >  drivers/infiniband/core/uverbs_ioctl.c | 4 ++--
> >  1 file changed, 2 insertions(+), 2 deletions(-)
> >
> > diff --git a/drivers/infiniband/core/uverbs_ioctl.c b/drivers/infiniband/core/uverbs_ioctl.c
> > index e47c5949013f..3871049a48f7 100644
> > --- a/drivers/infiniband/core/uverbs_ioctl.c
> > +++ b/drivers/infiniband/core/uverbs_ioctl.c
> > @@ -90,8 +90,8 @@ void uapi_compute_bundle_size(struct uverbs_api_ioctl_method *method_elm,
> >  	WARN_ON_ONCE(method_elm->bundle_size > PAGE_SIZE);
> >  }
> >
> > -/**
> > - * uverbs_alloc() - Quickly allocate memory for use with a bundle
> > +/*
>
> Why are you also demoting the header?

It is mistake. thanks

>
> It looks fine to me.  Just correct the function name.
>
> > + * _uverbs_alloc() - Quickly allocate memory for use with a bundle
> >   * @bundle: The bundle
> >   * @size: Number of bytes to allocate
> >   * @flags: Allocator flags
>
> --
> Lee Jones [李琼斯]
> Senior Technical Lead - Developer Services
> Linaro.org │ Open source software for Arm SoCs
> Follow Linaro: Facebook | Twitter | Blog

Re: [PATCH rdma-rc 0/2] W=1 compilation fixes leftovers

[Jason Gunthorpe]

On Tue, Mar 02, 2021 at 09:42:12AM +0200, Leon Romanovsky wrote:
> From: Leon Romanovsky <leonro@nvidia.com>
> 
> Two extra fixes that were missed in Lee's W=1 cleanup.
> 
> Leon Romanovsky (2):
>   RDMA/mlx5: Set correct kernel-doc identifier
>   RDMA/uverbs: Fix kernel-doc warning of _uverbs_alloc

Applied to for-rc, thanks

Jason