Sphinx reports kernel-doc warnings when making htmldocs:

WARNING: ./drivers/iommu/generic_pt/pt_common.h:361 function parameter 'bitnr' not described in 'pt_test_sw_bit_acquire'
WARNING: ./drivers/iommu/generic_pt/pt_common.h:371 function parameter 'bitnr' not described in 'pt_set_sw_bit_release'

Describe @bitnr to squash them.

Fixes: bcc64b57b48e ("iommupt: Add basic support for SW bits in the page table")
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 drivers/iommu/generic_pt/pt_common.h | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/drivers/iommu/generic_pt/pt_common.h b/drivers/iommu/generic_pt/pt_common.h
index b5628f47e0db40..54c16355be2842 100644
--- a/drivers/iommu/generic_pt/pt_common.h
+++ b/drivers/iommu/generic_pt/pt_common.h
@@ -354,6 +354,7 @@ static inline unsigned int pt_max_sw_bit(struct pt_common *common);
 /**
  * pt_test_sw_bit_acquire() - Read a software bit in an item
  * @pts: Entry to set
+ * @bitnr: Bit to set
  *
  * Software bits are ignored by HW and can be used for any purpose by the
  * software. This does a test bit and acquire operation.
@@ -364,6 +365,7 @@ static inline bool pt_test_sw_bit_acquire(struct pt_state *pts,
 /**
  * pt_set_sw_bit_release() - Set a software bit in an item
  * @pts: Entry to set
+ * @bitnr: Bit to set
  *
  * Software bits are ignored by HW and can be used for any purpose by the
  * software. This does a set bit and release operation.
-- 
An old man doll... just what I always wanted! - Clara

On 11/5/25 11:38 PM, Bagas Sanjaya wrote:
> Sphinx reports kernel-doc warnings when making htmldocs:
> 
> WARNING: ./drivers/iommu/generic_pt/pt_common.h:361 function parameter 'bitnr' not described in 'pt_test_sw_bit_acquire'
> WARNING: ./drivers/iommu/generic_pt/pt_common.h:371 function parameter 'bitnr' not described in 'pt_set_sw_bit_release'
> 
> Describe @bitnr to squash them.
> 
> Fixes: bcc64b57b48e ("iommupt: Add basic support for SW bits in the page table")
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  drivers/iommu/generic_pt/pt_common.h | 2 ++
>  1 file changed, 2 insertions(+)
> 
> diff --git a/drivers/iommu/generic_pt/pt_common.h b/drivers/iommu/generic_pt/pt_common.h
> index b5628f47e0db40..54c16355be2842 100644
> --- a/drivers/iommu/generic_pt/pt_common.h
> +++ b/drivers/iommu/generic_pt/pt_common.h
> @@ -354,6 +354,7 @@ static inline unsigned int pt_max_sw_bit(struct pt_common *common);
>  /**
>   * pt_test_sw_bit_acquire() - Read a software bit in an item
>   * @pts: Entry to set
> + * @bitnr: Bit to set

Shouldn't both of these (above) to "to read" instead of "to set"?

>   *
>   * Software bits are ignored by HW and can be used for any purpose by the
>   * software. This does a test bit and acquire operation.
> @@ -364,6 +365,7 @@ static inline bool pt_test_sw_bit_acquire(struct pt_state *pts,
>  /**
>   * pt_set_sw_bit_release() - Set a software bit in an item
>   * @pts: Entry to set
> + * @bitnr: Bit to set
>   *
>   * Software bits are ignored by HW and can be used for any purpose by the
>   * software. This does a set bit and release operation.

-- 
~Randy

On Thu, Nov 06, 2025 at 03:48:10PM -0800, Randy Dunlap wrote:
> > diff --git a/drivers/iommu/generic_pt/pt_common.h b/drivers/iommu/generic_pt/pt_common.h
> > index b5628f47e0db40..54c16355be2842 100644
> > --- a/drivers/iommu/generic_pt/pt_common.h
> > +++ b/drivers/iommu/generic_pt/pt_common.h
> > @@ -354,6 +354,7 @@ static inline unsigned int pt_max_sw_bit(struct pt_common *common);
> >  /**
> >   * pt_test_sw_bit_acquire() - Read a software bit in an item
> >   * @pts: Entry to set
> > + * @bitnr: Bit to set
> 
> Shouldn't both of these (above) to "to read" instead of "to set"?

Yes, that's right, Bagas could you fold that into a v2?

Jason

On Thu, Nov 06, 2025 at 08:35:41PM -0400, Jason Gunthorpe wrote:
> On Thu, Nov 06, 2025 at 03:48:10PM -0800, Randy Dunlap wrote:
> > > diff --git a/drivers/iommu/generic_pt/pt_common.h b/drivers/iommu/generic_pt/pt_common.h
> > > index b5628f47e0db40..54c16355be2842 100644
> > > --- a/drivers/iommu/generic_pt/pt_common.h
> > > +++ b/drivers/iommu/generic_pt/pt_common.h
> > > @@ -354,6 +354,7 @@ static inline unsigned int pt_max_sw_bit(struct pt_common *common);
> > >  /**
> > >   * pt_test_sw_bit_acquire() - Read a software bit in an item
> > >   * @pts: Entry to set
> > > + * @bitnr: Bit to set
> > 
> > Shouldn't both of these (above) to "to read" instead of "to set"?
> 
> Yes, that's right, Bagas could you fold that into a v2?

OK, thanks!

-- 
An old man doll... just what I always wanted! - Clara