[PATCH] mm/pagewalk: document missing struct members

[PATCH] mm/pagewalk: document missing struct members

[Oscar Alejandro Sánchez Lucero]

Add missing kernel-doc entries for @walk_lock in struct mm_walk_ops, and
for @ptep, @pudp, @pmdp, and @vma in struct folio_walk. Also fix @pte,
@pud, and @pmd descriptions to state they hold entry values, not pointers.

Signed-off-by: Oscar Alejandro Sánchez Lucero <aleszlucero@gmail.com>
---
 include/linux/pagewalk.h | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/include/linux/pagewalk.h b/include/linux/pagewalk.h
index b41d7265c01b..978714d5e32f 100644
--- a/include/linux/pagewalk.h
+++ b/include/linux/pagewalk.h
@@ -63,6 +63,8 @@ enum page_walk_lock {
  *                      install. If allocations fail, the walk is aborted. This
  *                      operation is only available for userland memory. Not
  *                      usable for hugetlb ranges.
+ * @walk_lock:          locking requirement during the page walk (see
+ *                      enum page_walk_lock).
  *
  * p?d_entry callbacks are called even if those levels are folded on a
  * particular architecture/configuration.
@@ -161,10 +163,14 @@ enum folio_walk_level {
  * struct folio_walk - folio_walk_start() / folio_walk_end() data
  * @page:	exact folio page referenced (if applicable)
  * @level:	page table level identifying the entry type
- * @pte:	pointer to the page table entry (FW_LEVEL_PTE).
- * @pmd:	pointer to the page table entry (FW_LEVEL_PMD).
- * @pud:	pointer to the page table entry (FW_LEVEL_PUD).
- * @ptl:	pointer to the page table lock.
+ * @ptep:	pointer to the page table entry (FW_LEVEL_PTE).
+ * @pudp:	pointer to the page table entry (FW_LEVEL_PUD).
+ * @pmdp:	pointer to the page table entry (FW_LEVEL_PMD).
+ * @pte:	page table entry value (FW_LEVEL_PTE).
+ * @pud:	page table entry value (FW_LEVEL_PUD).
+ * @pmd:	page table entry value (FW_LEVEL_PMD).
+ * @vma:	pointer to the VMA (for internal use only).
+ * @ptl:	pointer to the page table lock (for internal use only).
  *
  * (see folio_walk_start() documentation for more details)
  */

---
base-commit: 9d66f26fefacebfeed15de31c1123451a17ff119
change-id: 20261112-pagewalk-doc-d4f0de5c03c2

Best regards,
-- 
Oscar Alejandro Sánchez Lucero <aleszlucero@gmail.com>

Re: [PATCH] mm/pagewalk: document missing struct members

[David Hildenbrand (Arm)]

On 11/13/26 01:44, Oscar Alejandro Sánchez Lucero wrote:
> Add missing kernel-doc entries for @walk_lock in struct mm_walk_ops, and
> for @ptep, @pudp, @pmdp, and @vma in struct folio_walk. Also fix @pte,
> @pud, and @pmd descriptions to state they hold entry values, not pointers.
> 
> Signed-off-by: Oscar Alejandro Sánchez Lucero <aleszlucero@gmail.com>
> ---
>  include/linux/pagewalk.h | 14 ++++++++++----
>  1 file changed, 10 insertions(+), 4 deletions(-)
> 
> diff --git a/include/linux/pagewalk.h b/include/linux/pagewalk.h
> index b41d7265c01b..978714d5e32f 100644
> --- a/include/linux/pagewalk.h
> +++ b/include/linux/pagewalk.h
> @@ -63,6 +63,8 @@ enum page_walk_lock {
>   *                      install. If allocations fail, the walk is aborted. This
>   *                      operation is only available for userland memory. Not
>   *                      usable for hugetlb ranges.
> + * @walk_lock:          locking requirement during the page walk (see
> + *                      enum page_walk_lock).
>   *
>   * p?d_entry callbacks are called even if those levels are folded on a
>   * particular architecture/configuration.
> @@ -161,10 +163,14 @@ enum folio_walk_level {
>   * struct folio_walk - folio_walk_start() / folio_walk_end() data
>   * @page:	exact folio page referenced (if applicable)
>   * @level:	page table level identifying the entry type
> - * @pte:	pointer to the page table entry (FW_LEVEL_PTE).
> - * @pmd:	pointer to the page table entry (FW_LEVEL_PMD).
> - * @pud:	pointer to the page table entry (FW_LEVEL_PUD).
> - * @ptl:	pointer to the page table lock.
> + * @ptep:	pointer to the page table entry (FW_LEVEL_PTE).
> + * @pudp:	pointer to the page table entry (FW_LEVEL_PUD).
> + * @pmdp:	pointer to the page table entry (FW_LEVEL_PMD).
> + * @pte:	page table entry value (FW_LEVEL_PTE).
> + * @pud:	page table entry value (FW_LEVEL_PUD).
> + * @pmd:	page table entry value (FW_LEVEL_PMD).
> + * @vma:	pointer to the VMA (for internal use only).
> + * @ptl:	pointer to the page table lock (for internal use only).

Reviewed-by: David Hildenbrand (Arm) <david@kernel.org>

-- 
Cheers,

David

Re: [PATCH] mm/pagewalk: document missing struct members

[David Hildenbrand]

On Thu, 12 Nov 2026 18:44:07 -0600, Oscar Alejandro Sánchez Lucero wrote:
> Add missing kernel-doc entries for @walk_lock in struct mm_walk_ops, and
> for @ptep, @pudp, @pmdp, and @vma in struct folio_walk. Also fix @pte,
> @pud, and @pmd descriptions to state they hold entry values, not pointers.

Applied, thanks!

tree: mm/core.git
branch: core-7.5.misc

Applied patches will appear soon in mm-next, followed by linux-next.

Please report any outstanding bugs that were missed during review, so we
can either drop the patch series or decide how to fix it up.

It is encouraged to provide Acked-bys, Reviewed-bys, and Tested-bys even
though the patches have already been applied. If possible, patch trailers
will be updated.

Note that commit hashes shown below are subject to change due to rebase,
trailer updates or similar. Further, this is not a guarantee that the
patches will go upstream. If in doubt, please check the listed branch.

[1/1] mm/pagewalk: document missing struct members
      https://git.kernel.org/mm/core/c/8a834f42

-- 
Cheers,

David

Re: [PATCH] mm/pagewalk: document missing struct members

[Lorenzo Stoakes (ARM)]

On Thu, Nov 12, 2026 at 06:44:07PM -0600, Oscar Alejandro Sánchez Lucero wrote:
> Add missing kernel-doc entries for @walk_lock in struct mm_walk_ops, and
> for @ptep, @pudp, @pmdp, and @vma in struct folio_walk. Also fix @pte,
> @pud, and @pmd descriptions to state they hold entry values, not pointers.
>
> Signed-off-by: Oscar Alejandro Sánchez Lucero <aleszlucero@gmail.com>

Looks sensible to me so:

Reviewed-by: Lorenzo Stoakes (ARM) <ljs@kernel.org>

> ---
>  include/linux/pagewalk.h | 14 ++++++++++----
>  1 file changed, 10 insertions(+), 4 deletions(-)
>
> diff --git a/include/linux/pagewalk.h b/include/linux/pagewalk.h
> index b41d7265c01b..978714d5e32f 100644
> --- a/include/linux/pagewalk.h
> +++ b/include/linux/pagewalk.h
> @@ -63,6 +63,8 @@ enum page_walk_lock {
>   *                      install. If allocations fail, the walk is aborted. This
>   *                      operation is only available for userland memory. Not
>   *                      usable for hugetlb ranges.
> + * @walk_lock:          locking requirement during the page walk (see
> + *                      enum page_walk_lock).
>   *
>   * p?d_entry callbacks are called even if those levels are folded on a
>   * particular architecture/configuration.
> @@ -161,10 +163,14 @@ enum folio_walk_level {
>   * struct folio_walk - folio_walk_start() / folio_walk_end() data
>   * @page:	exact folio page referenced (if applicable)
>   * @level:	page table level identifying the entry type
> - * @pte:	pointer to the page table entry (FW_LEVEL_PTE).
> - * @pmd:	pointer to the page table entry (FW_LEVEL_PMD).
> - * @pud:	pointer to the page table entry (FW_LEVEL_PUD).
> - * @ptl:	pointer to the page table lock.
> + * @ptep:	pointer to the page table entry (FW_LEVEL_PTE).
> + * @pudp:	pointer to the page table entry (FW_LEVEL_PUD).
> + * @pmdp:	pointer to the page table entry (FW_LEVEL_PMD).
> + * @pte:	page table entry value (FW_LEVEL_PTE).
> + * @pud:	page table entry value (FW_LEVEL_PUD).
> + * @pmd:	page table entry value (FW_LEVEL_PMD).
> + * @vma:	pointer to the VMA (for internal use only).
> + * @ptl:	pointer to the page table lock (for internal use only).
>   *
>   * (see folio_walk_start() documentation for more details)
>   */
>
> ---
> base-commit: 9d66f26fefacebfeed15de31c1123451a17ff119
> change-id: 20261112-pagewalk-doc-d4f0de5c03c2
>
> Best regards,
> --
> Oscar Alejandro Sánchez Lucero <aleszlucero@gmail.com>
>

--
Cheers, Lorenzo