[PATCH 0/2] genpt documentation fixes

[PATCH 0/2] genpt documentation fixes

[Bagas Sanjaya]

Hi,

Here are fixes for two htmldocs warnings in generic radix page table
documentation. The first one is reported in linux-next [1], and the
second one is also found when making htmldocs locally to reproduce the
former.

Enjoy!

[1]: https://lore.kernel.org/linux-next/20251106143925.578e411b@canb.auug.org.au/

Bagas Sanjaya (2):
  Documentation: genpt: Don't use code block marker before iommu_amdv1.c
    include listing
  iommupt: Describe @bitnr parameter

 Documentation/driver-api/generic_pt.rst | 2 +-
 drivers/iommu/generic_pt/pt_common.h    | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)


base-commit: 75d9ef7cf1e694e5c0fb387be99f04acc7f864a4
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 1/2] Documentation: genpt: Don't use code block marker before iommu_amdv1.c include listing

[Bagas Sanjaya]

Stephen Rothwell reports htmldocs warning when merging iommu tree:

Documentation/driver-api/generic_pt.rst:32: WARNING: Literal block expected; none found. [docutils]

This is because of duplicate double colon code block markers: one after
generic_pt/fmt/iommu_amdv1.c and the one in its preceding paragraph. The
resulting htmldocs, however, only marks the include listing (after the
former) up as it should be.

Drop the latter to fix the warning.

Fixes: ab0b572847ac ("genpt: Add Documentation/ files")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/linux-next/20251106143925.578e411b@canb.auug.org.au/
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/driver-api/generic_pt.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/driver-api/generic_pt.rst b/Documentation/driver-api/generic_pt.rst
index 210d1229aa1c1f..7a9ca9f2878d4f 100644
--- a/Documentation/driver-api/generic_pt.rst
+++ b/Documentation/driver-api/generic_pt.rst
@@ -27,7 +27,7 @@ compiled into a per-format IOMMU operations kernel module.
 For this to work the .c file for each compilation unit will include both the
 format headers and the generic code for the implementation. For instance in an
 implementation compilation unit the headers would normally be included as
-follows::
+follows:
 
 generic_pt/fmt/iommu_amdv1.c::
 
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 2/2] iommupt: Describe @bitnr parameter

[Bagas Sanjaya]

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

Re: [PATCH 0/2] genpt documentation fixes

[Jason Gunthorpe]

On Thu, Nov 06, 2025 at 02:38:43PM +0700, Bagas Sanjaya wrote:
> Hi,
> 
> Here are fixes for two htmldocs warnings in generic radix page table
> documentation. The first one is reported in linux-next [1], and the
> second one is also found when making htmldocs locally to reproduce the
> former.
> 
> Enjoy!
> 
> [1]: https://lore.kernel.org/linux-next/20251106143925.578e411b@canb.auug.org.au/
> 
> Bagas Sanjaya (2):
>   Documentation: genpt: Don't use code block marker before iommu_amdv1.c
>     include listing
>   iommupt: Describe @bitnr parameter
> 
>  Documentation/driver-api/generic_pt.rst | 2 +-
>  drivers/iommu/generic_pt/pt_common.h    | 2 ++
>  2 files changed, 3 insertions(+), 1 deletion(-)

Reviewed-by: Jason Gunthorpe <jgg@nvidia.com>

Thanks,
Jason

Re: [PATCH 2/2] iommupt: Describe @bitnr parameter

[Randy Dunlap]

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

Re: [PATCH 1/2] Documentation: genpt: Don't use code block marker before iommu_amdv1.c include listing

[Randy Dunlap]

On 11/5/25 11:38 PM, Bagas Sanjaya wrote:
> Stephen Rothwell reports htmldocs warning when merging iommu tree:
> 
> Documentation/driver-api/generic_pt.rst:32: WARNING: Literal block expected; none found. [docutils]
> 
> This is because of duplicate double colon code block markers: one after
> generic_pt/fmt/iommu_amdv1.c and the one in its preceding paragraph. The
> resulting htmldocs, however, only marks the include listing (after the
> former) up as it should be.
> 
> Drop the latter to fix the warning.
> 
> Fixes: ab0b572847ac ("genpt: Add Documentation/ files")
> Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
> Closes: https://lore.kernel.org/linux-next/20251106143925.578e411b@canb.auug.org.au/
> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
> ---
>  Documentation/driver-api/generic_pt.rst | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/Documentation/driver-api/generic_pt.rst b/Documentation/driver-api/generic_pt.rst
> index 210d1229aa1c1f..7a9ca9f2878d4f 100644
> --- a/Documentation/driver-api/generic_pt.rst
> +++ b/Documentation/driver-api/generic_pt.rst
> @@ -27,7 +27,7 @@ compiled into a per-format IOMMU operations kernel module.
>  For this to work the .c file for each compilation unit will include both the
>  format headers and the generic code for the implementation. For instance in an
>  implementation compilation unit the headers would normally be included as
> -follows::
> +follows:
>  
>  generic_pt/fmt/iommu_amdv1.c::
>  


Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

-- 
~Randy

Re: [PATCH 2/2] iommupt: Describe @bitnr parameter

[Jason Gunthorpe]

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

Re: [PATCH 2/2] iommupt: Describe @bitnr parameter

[Bagas Sanjaya]

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

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]