[PATCH 1/4] mm/doc: Fix fault_flag_allow_retry_first kerneldoc

[PATCH 1/4] mm/doc: Fix fault_flag_allow_retry_first kerneldoc

[Matthew Wilcox (Oracle)]

make htmldocs reports:

./include/linux/mm.h:496: warning: Function parameter or member 'flags' not described in 'fault_flag_allow_retry_first'

Add a description.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
---
 include/linux/mm.h | 1 +
 1 file changed, 1 insertion(+)

diff --git a/include/linux/mm.h b/include/linux/mm.h
index cb1e191da319..9c149e945bf9 100644
--- a/include/linux/mm.h
+++ b/include/linux/mm.h
@@ -482,6 +482,7 @@ extern pgprot_t protection_map[16];
 
 /**
  * fault_flag_allow_retry_first - check ALLOW_RETRY the first time
+ * @flags: Fault flags.
  *
  * This is mostly used for places where we want to try to avoid taking
  * the mmap_lock for too long a time when waiting for another condition
-- 
2.30.2

[PATCH 2/4] mm/doc: Fix page_maybe_dma_pinned kerneldoc

[Matthew Wilcox (Oracle)]

make htmldocs reports:

./include/linux/mm.h:1341: warning: Excess function parameter 'Return' description in 'page_maybe_dma_pinned'

Fix a few other formatting nits while I'm editing this description.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
---
 include/linux/mm.h | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/include/linux/mm.h b/include/linux/mm.h
index 9c149e945bf9..96e5ceffce09 100644
--- a/include/linux/mm.h
+++ b/include/linux/mm.h
@@ -1273,10 +1273,11 @@ void unpin_user_page_range_dirty_lock(struct page *page, unsigned long npages,
 void unpin_user_pages(struct page **pages, unsigned long npages);
 
 /**
- * page_maybe_dma_pinned() - report if a page is pinned for DMA.
+ * page_maybe_dma_pinned - Report if a page is pinned for DMA.
+ * @page: The page.
  *
  * This function checks if a page has been pinned via a call to
- * pin_user_pages*().
+ * a function in the pin_user_pages() family.
  *
  * For non-huge pages, the return value is partially fuzzy: false is not fuzzy,
  * because it means "definitely not pinned for DMA", but true means "probably
@@ -1294,9 +1295,8 @@ void unpin_user_pages(struct page **pages, unsigned long npages);
  *
  * For more information, please see Documentation/core-api/pin_user_pages.rst.
  *
- * @page:	pointer to page to be queried.
- * @Return:	True, if it is likely that the page has been "dma-pinned".
- *		False, if the page is definitely not dma-pinned.
+ * Return: True, if it is likely that the page has been "dma-pinned".
+ * False, if the page is definitely not dma-pinned.
  */
 static inline bool page_maybe_dma_pinned(struct page *page)
 {
-- 
2.30.2

[PATCH 3/4] mm/doc: Turn fault flags into an enum

[Matthew Wilcox (Oracle)]

The kernel-doc script complains about
./include/linux/mm.h:425: warning: wrong kernel-doc identifier on line:
 * Fault flag definitions.

I don't know how to document a series of #defines, so turn these
definitions into an enum and document that instead.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
---
 include/linux/mm.h | 29 +++++++++++++++--------------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/include/linux/mm.h b/include/linux/mm.h
index 96e5ceffce09..58df4027dd4d 100644
--- a/include/linux/mm.h
+++ b/include/linux/mm.h
@@ -429,8 +429,7 @@ extern unsigned int kobjsize(const void *objp);
 extern pgprot_t protection_map[16];
 
 /**
- * Fault flag definitions.
- *
+ * enum fault_flag - Fault flag definitions.
  * @FAULT_FLAG_WRITE: Fault was a write fault.
  * @FAULT_FLAG_MKWRITE: Fault was mkwrite of existing PTE.
  * @FAULT_FLAG_ALLOW_RETRY: Allow to retry the fault if blocked.
@@ -461,16 +460,18 @@ extern pgprot_t protection_map[16];
  * signals before a retry to make sure the continuous page faults can still be
  * interrupted if necessary.
  */
-#define FAULT_FLAG_WRITE			0x01
-#define FAULT_FLAG_MKWRITE			0x02
-#define FAULT_FLAG_ALLOW_RETRY			0x04
-#define FAULT_FLAG_RETRY_NOWAIT			0x08
-#define FAULT_FLAG_KILLABLE			0x10
-#define FAULT_FLAG_TRIED			0x20
-#define FAULT_FLAG_USER				0x40
-#define FAULT_FLAG_REMOTE			0x80
-#define FAULT_FLAG_INSTRUCTION  		0x100
-#define FAULT_FLAG_INTERRUPTIBLE		0x200
+enum fault_flag {
+	FAULT_FLAG_WRITE =		1 << 0,
+	FAULT_FLAG_MKWRITE =		1 << 1,
+	FAULT_FLAG_ALLOW_RETRY =	1 << 2,
+	FAULT_FLAG_RETRY_NOWAIT = 	1 << 3,
+	FAULT_FLAG_KILLABLE =		1 << 4,
+	FAULT_FLAG_TRIED = 		1 << 5,
+	FAULT_FLAG_USER =		1 << 6,
+	FAULT_FLAG_REMOTE =		1 << 7,
+	FAULT_FLAG_INSTRUCTION =	1 << 8,
+	FAULT_FLAG_INTERRUPTIBLE =	1 << 9,
+};
 
 /*
  * The default fault flags that should be used by most of the
@@ -493,7 +494,7 @@ extern pgprot_t protection_map[16];
  * Return: true if the page fault allows retry and this is the first
  * attempt of the fault handling; false otherwise.
  */
-static inline bool fault_flag_allow_retry_first(unsigned int flags)
+static inline bool fault_flag_allow_retry_first(enum fault_flag flags)
 {
 	return (flags & FAULT_FLAG_ALLOW_RETRY) &&
 	    (!(flags & FAULT_FLAG_TRIED));
@@ -528,7 +529,7 @@ struct vm_fault {
 		pgoff_t pgoff;			/* Logical page offset based on vma */
 		unsigned long address;		/* Faulting virtual address */
 	};
-	unsigned int flags;		/* FAULT_FLAG_xxx flags
+	enum fault_flag flags;		/* FAULT_FLAG_xxx flags
 					 * XXX: should really be 'const' */
 	pmd_t *pmd;			/* Pointer to pmd entry matching
 					 * the 'address' */
-- 
2.30.2

[PATCH 4/4] mm/doc: Add mm.h and mm_types.h to the mm-api document

[Matthew Wilcox (Oracle)]

kerneldoc in include/linux/mm.h and include/linux/mm_types.h wasn't
being included in the html build.

Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
---
 Documentation/core-api/mm-api.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
index 874ae1250258..34f46df91a8b 100644
--- a/Documentation/core-api/mm-api.rst
+++ b/Documentation/core-api/mm-api.rst
@@ -93,3 +93,7 @@ More Memory Management Functions
 
 .. kernel-doc:: mm/page_alloc.c
 .. kernel-doc:: mm/mempolicy.c
+.. kernel-doc:: include/linux/mm_types.h
+   :internal:
+.. kernel-doc:: include/linux/mm.h
+   :internal:
-- 
2.30.2

Re: [PATCH 1/4] mm/doc: Fix fault_flag_allow_retry_first kerneldoc

[Mike Rapoport]

On Mon, Mar 22, 2021 at 07:50:19PM +0000, Matthew Wilcox (Oracle) wrote:
> make htmldocs reports:
> 
> ./include/linux/mm.h:496: warning: Function parameter or member 'flags' not described in 'fault_flag_allow_retry_first'
> 
> Add a description.
> 
> Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>

Acked-by: Mike Rapoport <rppt@linux.ibm.com>

> ---
>  include/linux/mm.h | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/include/linux/mm.h b/include/linux/mm.h
> index cb1e191da319..9c149e945bf9 100644
> --- a/include/linux/mm.h
> +++ b/include/linux/mm.h
> @@ -482,6 +482,7 @@ extern pgprot_t protection_map[16];
>  
>  /**
>   * fault_flag_allow_retry_first - check ALLOW_RETRY the first time
> + * @flags: Fault flags.
>   *
>   * This is mostly used for places where we want to try to avoid taking
>   * the mmap_lock for too long a time when waiting for another condition
> -- 
> 2.30.2
> 

-- 
Sincerely yours,
Mike.

Re: [PATCH 2/4] mm/doc: Fix page_maybe_dma_pinned kerneldoc

[Mike Rapoport]

On Mon, Mar 22, 2021 at 07:50:20PM +0000, Matthew Wilcox (Oracle) wrote:
> make htmldocs reports:
> 
> ./include/linux/mm.h:1341: warning: Excess function parameter 'Return' description in 'page_maybe_dma_pinned'
> 
> Fix a few other formatting nits while I'm editing this description.
> 
> Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>

Acked-by: Mike Rapoport <rppt@linux.ibm.com>

> ---
>  include/linux/mm.h | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
> 
> diff --git a/include/linux/mm.h b/include/linux/mm.h
> index 9c149e945bf9..96e5ceffce09 100644
> --- a/include/linux/mm.h
> +++ b/include/linux/mm.h
> @@ -1273,10 +1273,11 @@ void unpin_user_page_range_dirty_lock(struct page *page, unsigned long npages,
>  void unpin_user_pages(struct page **pages, unsigned long npages);
>  
>  /**
> - * page_maybe_dma_pinned() - report if a page is pinned for DMA.
> + * page_maybe_dma_pinned - Report if a page is pinned for DMA.
> + * @page: The page.
>   *
>   * This function checks if a page has been pinned via a call to
> - * pin_user_pages*().
> + * a function in the pin_user_pages() family.
>   *
>   * For non-huge pages, the return value is partially fuzzy: false is not fuzzy,
>   * because it means "definitely not pinned for DMA", but true means "probably
> @@ -1294,9 +1295,8 @@ void unpin_user_pages(struct page **pages, unsigned long npages);
>   *
>   * For more information, please see Documentation/core-api/pin_user_pages.rst.
>   *
> - * @page:	pointer to page to be queried.
> - * @Return:	True, if it is likely that the page has been "dma-pinned".
> - *		False, if the page is definitely not dma-pinned.
> + * Return: True, if it is likely that the page has been "dma-pinned".
> + * False, if the page is definitely not dma-pinned.
>   */
>  static inline bool page_maybe_dma_pinned(struct page *page)
>  {
> -- 
> 2.30.2
> 

-- 
Sincerely yours,
Mike.

Re: [PATCH 3/4] mm/doc: Turn fault flags into an enum

[Mike Rapoport]

On Mon, Mar 22, 2021 at 07:50:21PM +0000, Matthew Wilcox (Oracle) wrote:
> The kernel-doc script complains about
> ./include/linux/mm.h:425: warning: wrong kernel-doc identifier on line:
>  * Fault flag definitions.
> 
> I don't know how to document a series of #defines, so turn these
> definitions into an enum and document that instead.
> 
> Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>

Acked-by: Mike Rapoport <rppt@linux.ibm.com>

> ---
>  include/linux/mm.h | 29 +++++++++++++++--------------
>  1 file changed, 15 insertions(+), 14 deletions(-)
> 
> diff --git a/include/linux/mm.h b/include/linux/mm.h
> index 96e5ceffce09..58df4027dd4d 100644
> --- a/include/linux/mm.h
> +++ b/include/linux/mm.h
> @@ -429,8 +429,7 @@ extern unsigned int kobjsize(const void *objp);
>  extern pgprot_t protection_map[16];
>  
>  /**
> - * Fault flag definitions.
> - *
> + * enum fault_flag - Fault flag definitions.
>   * @FAULT_FLAG_WRITE: Fault was a write fault.
>   * @FAULT_FLAG_MKWRITE: Fault was mkwrite of existing PTE.
>   * @FAULT_FLAG_ALLOW_RETRY: Allow to retry the fault if blocked.
> @@ -461,16 +460,18 @@ extern pgprot_t protection_map[16];
>   * signals before a retry to make sure the continuous page faults can still be
>   * interrupted if necessary.
>   */
> -#define FAULT_FLAG_WRITE			0x01
> -#define FAULT_FLAG_MKWRITE			0x02
> -#define FAULT_FLAG_ALLOW_RETRY			0x04
> -#define FAULT_FLAG_RETRY_NOWAIT			0x08
> -#define FAULT_FLAG_KILLABLE			0x10
> -#define FAULT_FLAG_TRIED			0x20
> -#define FAULT_FLAG_USER				0x40
> -#define FAULT_FLAG_REMOTE			0x80
> -#define FAULT_FLAG_INSTRUCTION  		0x100
> -#define FAULT_FLAG_INTERRUPTIBLE		0x200
> +enum fault_flag {
> +	FAULT_FLAG_WRITE =		1 << 0,
> +	FAULT_FLAG_MKWRITE =		1 << 1,
> +	FAULT_FLAG_ALLOW_RETRY =	1 << 2,
> +	FAULT_FLAG_RETRY_NOWAIT = 	1 << 3,
> +	FAULT_FLAG_KILLABLE =		1 << 4,
> +	FAULT_FLAG_TRIED = 		1 << 5,
> +	FAULT_FLAG_USER =		1 << 6,
> +	FAULT_FLAG_REMOTE =		1 << 7,
> +	FAULT_FLAG_INSTRUCTION =	1 << 8,
> +	FAULT_FLAG_INTERRUPTIBLE =	1 << 9,
> +};
>  
>  /*
>   * The default fault flags that should be used by most of the
> @@ -493,7 +494,7 @@ extern pgprot_t protection_map[16];
>   * Return: true if the page fault allows retry and this is the first
>   * attempt of the fault handling; false otherwise.
>   */
> -static inline bool fault_flag_allow_retry_first(unsigned int flags)
> +static inline bool fault_flag_allow_retry_first(enum fault_flag flags)
>  {
>  	return (flags & FAULT_FLAG_ALLOW_RETRY) &&
>  	    (!(flags & FAULT_FLAG_TRIED));
> @@ -528,7 +529,7 @@ struct vm_fault {
>  		pgoff_t pgoff;			/* Logical page offset based on vma */
>  		unsigned long address;		/* Faulting virtual address */
>  	};
> -	unsigned int flags;		/* FAULT_FLAG_xxx flags
> +	enum fault_flag flags;		/* FAULT_FLAG_xxx flags
>  					 * XXX: should really be 'const' */
>  	pmd_t *pmd;			/* Pointer to pmd entry matching
>  					 * the 'address' */
> -- 
> 2.30.2
> 

-- 
Sincerely yours,
Mike.

Re: [PATCH 4/4] mm/doc: Add mm.h and mm_types.h to the mm-api document

[Mike Rapoport]

On Mon, Mar 22, 2021 at 07:50:22PM +0000, Matthew Wilcox (Oracle) wrote:
> kerneldoc in include/linux/mm.h and include/linux/mm_types.h wasn't
> being included in the html build.
> 
> Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>

Acked-by: Mike Rapoport <rppt@linux.ibm.com>

> ---
>  Documentation/core-api/mm-api.rst | 4 ++++
>  1 file changed, 4 insertions(+)
> 
> diff --git a/Documentation/core-api/mm-api.rst b/Documentation/core-api/mm-api.rst
> index 874ae1250258..34f46df91a8b 100644
> --- a/Documentation/core-api/mm-api.rst
> +++ b/Documentation/core-api/mm-api.rst
> @@ -93,3 +93,7 @@ More Memory Management Functions
>  
>  .. kernel-doc:: mm/page_alloc.c
>  .. kernel-doc:: mm/mempolicy.c
> +.. kernel-doc:: include/linux/mm_types.h
> +   :internal:
> +.. kernel-doc:: include/linux/mm.h
> +   :internal:
> -- 
> 2.30.2
> 

-- 
Sincerely yours,
Mike.

Re: [PATCH 2/4] mm/doc: Fix page_maybe_dma_pinned kerneldoc

[John Hubbard]

On 3/22/21 12:50 PM, Matthew Wilcox (Oracle) wrote:
> make htmldocs reports:
> 
> ./include/linux/mm.h:1341: warning: Excess function parameter 'Return' description in 'page_maybe_dma_pinned'
> 
> Fix a few other formatting nits while I'm editing this description.
> 
> Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
> ---
>   include/linux/mm.h | 10 +++++-----
>   1 file changed, 5 insertions(+), 5 deletions(-)

Looks nice, thanks for fixing this up.

There was a slight delay, during which I re-learned that Sphinx 3 still causes
a "nearly indefinite" delay in "make htmldocs". But eventually I got this to
build and verified that the output made it through intact. I guess I'm grateful
that Sphinx 3 works at all, though.

Reviewed-by: John Hubbard <jhubbard@nvidia.com>

thanks,
-- 
John Hubbard
NVIDIA

> 
> diff --git a/include/linux/mm.h b/include/linux/mm.h
> index 9c149e945bf9..96e5ceffce09 100644
> --- a/include/linux/mm.h
> +++ b/include/linux/mm.h
> @@ -1273,10 +1273,11 @@ void unpin_user_page_range_dirty_lock(struct page *page, unsigned long npages,
>   void unpin_user_pages(struct page **pages, unsigned long npages);
>   
>   /**
> - * page_maybe_dma_pinned() - report if a page is pinned for DMA.
> + * page_maybe_dma_pinned - Report if a page is pinned for DMA.
> + * @page: The page.
>    *
>    * This function checks if a page has been pinned via a call to
> - * pin_user_pages*().
> + * a function in the pin_user_pages() family.
>    *
>    * For non-huge pages, the return value is partially fuzzy: false is not fuzzy,
>    * because it means "definitely not pinned for DMA", but true means "probably
> @@ -1294,9 +1295,8 @@ void unpin_user_pages(struct page **pages, unsigned long npages);
>    *
>    * For more information, please see Documentation/core-api/pin_user_pages.rst.
>    *
> - * @page:	pointer to page to be queried.
> - * @Return:	True, if it is likely that the page has been "dma-pinned".
> - *		False, if the page is definitely not dma-pinned.
> + * Return: True, if it is likely that the page has been "dma-pinned".
> + * False, if the page is definitely not dma-pinned.
>    */
>   static inline bool page_maybe_dma_pinned(struct page *page)
>   {
>