* [PATCH 2/4] mm/doc: Fix page_maybe_dma_pinned kerneldoc
2021-03-22 19:50 [PATCH 1/4] mm/doc: Fix fault_flag_allow_retry_first kerneldoc Matthew Wilcox (Oracle)
@ 2021-03-22 19:50 ` Matthew Wilcox (Oracle)
2021-03-23 7:27 ` Mike Rapoport
2021-03-24 2:50 ` John Hubbard
2021-03-22 19:50 ` [PATCH 3/4] mm/doc: Turn fault flags into an enum Matthew Wilcox (Oracle)
` (2 subsequent siblings)
3 siblings, 2 replies; 9+ messages in thread
From: Matthew Wilcox (Oracle) @ 2021-03-22 19:50 UTC (permalink / raw)
To: linux-mm, Andrew Morton
Cc: Matthew Wilcox (Oracle), linux-doc, John Hubbard, Mike Rapoport
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
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH 2/4] mm/doc: Fix page_maybe_dma_pinned kerneldoc
2021-03-22 19:50 ` [PATCH 2/4] mm/doc: Fix page_maybe_dma_pinned kerneldoc Matthew Wilcox (Oracle)
@ 2021-03-23 7:27 ` Mike Rapoport
2021-03-24 2:50 ` John Hubbard
1 sibling, 0 replies; 9+ messages in thread
From: Mike Rapoport @ 2021-03-23 7:27 UTC (permalink / raw)
To: Matthew Wilcox (Oracle); +Cc: linux-mm, Andrew Morton, linux-doc, John Hubbard
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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH 2/4] mm/doc: Fix page_maybe_dma_pinned kerneldoc
2021-03-22 19:50 ` [PATCH 2/4] mm/doc: Fix page_maybe_dma_pinned kerneldoc Matthew Wilcox (Oracle)
2021-03-23 7:27 ` Mike Rapoport
@ 2021-03-24 2:50 ` John Hubbard
1 sibling, 0 replies; 9+ messages in thread
From: John Hubbard @ 2021-03-24 2:50 UTC (permalink / raw)
To: Matthew Wilcox (Oracle), linux-mm, Andrew Morton; +Cc: linux-doc, Mike Rapoport
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)
> {
>
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH 3/4] mm/doc: Turn fault flags into an enum
2021-03-22 19:50 [PATCH 1/4] mm/doc: Fix fault_flag_allow_retry_first kerneldoc Matthew Wilcox (Oracle)
2021-03-22 19:50 ` [PATCH 2/4] mm/doc: Fix page_maybe_dma_pinned kerneldoc Matthew Wilcox (Oracle)
@ 2021-03-22 19:50 ` Matthew Wilcox (Oracle)
2021-03-23 7:28 ` Mike Rapoport
2021-03-22 19:50 ` [PATCH 4/4] mm/doc: Add mm.h and mm_types.h to the mm-api document Matthew Wilcox (Oracle)
2021-03-23 7:27 ` [PATCH 1/4] mm/doc: Fix fault_flag_allow_retry_first kerneldoc Mike Rapoport
3 siblings, 1 reply; 9+ messages in thread
From: Matthew Wilcox (Oracle) @ 2021-03-22 19:50 UTC (permalink / raw)
To: linux-mm, Andrew Morton
Cc: Matthew Wilcox (Oracle), linux-doc, John Hubbard, Mike Rapoport
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
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH 3/4] mm/doc: Turn fault flags into an enum
2021-03-22 19:50 ` [PATCH 3/4] mm/doc: Turn fault flags into an enum Matthew Wilcox (Oracle)
@ 2021-03-23 7:28 ` Mike Rapoport
0 siblings, 0 replies; 9+ messages in thread
From: Mike Rapoport @ 2021-03-23 7:28 UTC (permalink / raw)
To: Matthew Wilcox (Oracle); +Cc: linux-mm, Andrew Morton, linux-doc, John Hubbard
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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH 4/4] mm/doc: Add mm.h and mm_types.h to the mm-api document
2021-03-22 19:50 [PATCH 1/4] mm/doc: Fix fault_flag_allow_retry_first kerneldoc Matthew Wilcox (Oracle)
2021-03-22 19:50 ` [PATCH 2/4] mm/doc: Fix page_maybe_dma_pinned kerneldoc Matthew Wilcox (Oracle)
2021-03-22 19:50 ` [PATCH 3/4] mm/doc: Turn fault flags into an enum Matthew Wilcox (Oracle)
@ 2021-03-22 19:50 ` Matthew Wilcox (Oracle)
2021-03-23 7:28 ` Mike Rapoport
2021-03-23 7:27 ` [PATCH 1/4] mm/doc: Fix fault_flag_allow_retry_first kerneldoc Mike Rapoport
3 siblings, 1 reply; 9+ messages in thread
From: Matthew Wilcox (Oracle) @ 2021-03-22 19:50 UTC (permalink / raw)
To: linux-mm, Andrew Morton
Cc: Matthew Wilcox (Oracle), linux-doc, John Hubbard, Mike Rapoport
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
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH 4/4] mm/doc: Add mm.h and mm_types.h to the mm-api document
2021-03-22 19:50 ` [PATCH 4/4] mm/doc: Add mm.h and mm_types.h to the mm-api document Matthew Wilcox (Oracle)
@ 2021-03-23 7:28 ` Mike Rapoport
0 siblings, 0 replies; 9+ messages in thread
From: Mike Rapoport @ 2021-03-23 7:28 UTC (permalink / raw)
To: Matthew Wilcox (Oracle); +Cc: linux-mm, Andrew Morton, linux-doc, John Hubbard
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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH 1/4] mm/doc: Fix fault_flag_allow_retry_first kerneldoc
2021-03-22 19:50 [PATCH 1/4] mm/doc: Fix fault_flag_allow_retry_first kerneldoc Matthew Wilcox (Oracle)
` (2 preceding siblings ...)
2021-03-22 19:50 ` [PATCH 4/4] mm/doc: Add mm.h and mm_types.h to the mm-api document Matthew Wilcox (Oracle)
@ 2021-03-23 7:27 ` Mike Rapoport
3 siblings, 0 replies; 9+ messages in thread
From: Mike Rapoport @ 2021-03-23 7:27 UTC (permalink / raw)
To: Matthew Wilcox (Oracle); +Cc: linux-mm, Andrew Morton, linux-doc, John Hubbard
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.
^ permalink raw reply [flat|nested] 9+ messages in thread