* [PATCH 1/2] ioctl_userfaultfd.2: add UFFD_FEATURE_WP_ASYNC
@ 2023-10-19 13:12 Muhammad Usama Anjum
2023-10-19 13:12 ` [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL Muhammad Usama Anjum
` (2 more replies)
0 siblings, 3 replies; 18+ messages in thread
From: Muhammad Usama Anjum @ 2023-10-19 13:12 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: Muhammad Usama Anjum, kernel, linux-man
Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
---
Changes since v1:
- Employ sementic new lines by breaking sentence before "by"
---
man2/ioctl_userfaultfd.2 | 5 +++++
1 file changed, 5 insertions(+)
diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2
index e68085262..f6cafd9a2 100644
--- a/man2/ioctl_userfaultfd.2
+++ b/man2/ioctl_userfaultfd.2
@@ -244,6 +244,11 @@ If this feature bit is set,
the kernel supports resolving faults with the
.B UFFDIO_POISON
ioctl.
+.TP
+.BR UFFD_FEATURE_WP_ASYNC " (since Linux 6.7)"
+If this feature bit is set,
+the write protection faults would be asynchronously resolved
+by the kernel.
.PP
The returned
.I ioctls
--
2.42.0
^ permalink raw reply related [flat|nested] 18+ messages in thread
* [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL
2023-10-19 13:12 [PATCH 1/2] ioctl_userfaultfd.2: add UFFD_FEATURE_WP_ASYNC Muhammad Usama Anjum
@ 2023-10-19 13:12 ` Muhammad Usama Anjum
2023-10-23 21:52 ` Alejandro Colomar
2023-10-19 13:27 ` [PATCH 1/2] ioctl_userfaultfd.2: add UFFD_FEATURE_WP_ASYNC Alejandro Colomar
2023-10-19 13:29 ` Alejandro Colomar
2 siblings, 1 reply; 18+ messages in thread
From: Muhammad Usama Anjum @ 2023-10-19 13:12 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: Muhammad Usama Anjum, kernel, linux-man
Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
---
The feature has been added to mm-stable:
https://lore.kernel.org/all/20231018213453.BF1ACC43395@smtp.kernel.org
Changes since v1:
- Several formatting updates
- Added some additional sentences
---
man2/ioctl_pagemap_scan.2 | 203 ++++++++++++++++++++++++++++++++++++++
1 file changed, 203 insertions(+)
create mode 100644 man2/ioctl_pagemap_scan.2
diff --git a/man2/ioctl_pagemap_scan.2 b/man2/ioctl_pagemap_scan.2
new file mode 100644
index 000000000..c257072d7
--- /dev/null
+++ b/man2/ioctl_pagemap_scan.2
@@ -0,0 +1,203 @@
+.\" This manpage is Copyright (C) 2023 Collabora;
+.\" Written by Muhammad Usama Anjum <usama.anjum@collabora.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH ioctl_pagemap_scan 2 2023-10-17 "Linux man-pages (unreleased)"
+.SH NAME
+ioctl_pagemap_scan \- get and/or clear page flags
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/fs.h>" " /* Definition of " struct " " pm_scan_arg ", "
+.BR " struct page_region "and " PAGE_IS_* "constants " */"
+.B #include <sys/ioctl.h>
+.PP
+.BI "int ioctl(int " pagemap_fd ", PAGEMAP_SCAN, struct pm_scan_arg *" arg );
+.fi
+.SH DESCRIPTION
+This
+.BR ioctl (2)
+is used to get and optionally clear some specific flags from page table entries.
+The information is returned with
+.B PAGE_SIZE
+granularity.
+.PP
+To start tracking the written state (flag) of a page or range of memory,
+the
+.B UFFD_FEATURE_WP_ASYNC
+must be enabled by
+.B UFFDIO_API
+.BR ioctl (2)
+on
+.B userfaultfd
+and memory range must be registered with
+.B UFFDIO_REGISTER
+.BR ioctl (2)
+in
+.B UFFDIO_REGISTER_MODE_WP
+mode.
+.SS Supported page flags
+The following page table entry flags are supported:
+.TP
+.B PAGE_IS_WPALLOWED
+The page has asynchronous write-protection enabled.
+.TP
+.B PAGE_IS_WRITTEN
+The page has been written to from the time it was write protected.
+.TP
+.B PAGE_IS_FILE
+The page is file backed.
+.TP
+.B PAGE_IS_PRESENT
+The page is present in the memory.
+.TP
+.B PAGE_IS_SWAPPED
+The page is swapped.
+.TP
+.B PAGE_IS_PFNZERO
+The page has zero PFN.
+.TP
+.B PAGE_IS_HUGE
+The page is THP or Hugetlb backed.
+.SS Supported operations
+The get operation is always performed
+if the output buffer is specified.
+The other operations are as following:
+.TP
+.B PM_SCAN_WP_MATCHING
+Write protect the matched pages.
+.TP
+.B PM_SCAN_CHECK_WPASYNC
+Abort the scan
+when a page is found
+which doesn't have the Userfaultfd Asynchronous Write protection enabled.
+.SS The \f[I]struct pm_scan_arg\f[] argument
+.EX
+struct pm_scan_arg {
+ __u64 size;
+ __u64 flags;
+ __u64 start;
+ __u64 end;
+ __u64 walk_end;
+ __u64 vec;
+ __u64 vec_len;
+ __u64 max_pages
+ __u64 category_inverted;
+ __u64 category_mask;
+ __u64 category_anyof_mask
+ __u64 return_mask;
+};
+.EE
+.TP
+.B size
+This field should be set to the size of the structure in bytes,
+as in
+.IR "sizeof(struct pm_scan_arg)" .
+.TP
+.B flags
+The operations to be performed are specified in it.
+.TP
+.B start
+The starting address of the scan is specified in it.
+.TP
+.B end
+The ending address of the scan is specified in it.
+.TP
+.B walk_end
+The kernel returns the scan's ending address in it.
+The
+.I walk_end
+equal to
+.I end
+means that scan has completed on the entire range.
+.TP
+.B vec
+The address of
+.I page_region
+array for output.
+.PP
+.in +8n
+.EX
+struct page_region {
+ __u64 start;
+ __u64 end;
+ __u64 categories;
+};
+.EE
+.in
+.TP
+.B vec_len
+The length of the
+.I page_region
+struct array.
+.TP
+.B max_pages
+It is the optional limit for the number of output pages required.
+.TP
+.B category_inverted
+.BI PAGE_IS_ *
+categories which values match if 0 instead of 1.
+.TP
+.B category_mask
+Skip pages for which any
+.BI PAGE_IS_ *
+category doesn't match.
+.TP
+.B category_anyof_mask
+Skip pages for which no
+.BI PAGE_IS_ *
+category matches.
+.TP
+.B return_mask
+.BI PAGE_IS_ *
+categories that are to be reported in
+.IR page_region .
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EINVAL
+Invalid arguments i.e., invalid
+.I size
+of the argument, invalid
+.IR flags ,
+invalid
+.IR categories ,
+the
+.I start
+address isn't aligned with
+.B PAGE_SIZE
+or
+.I vec_len
+is specified when
+.I vec
+is
+.BR NULL .
+.TP
+.B EFAULT
+Invalid
+.I arg
+pointer, invalid
+.I vec
+pointer or invalid address range specified by
+.I start
+and
+.IR end .
+.TP
+.B ENOMEM
+No memory is available.
+.TP
+.B EINTR
+Fetal signal is pending.
+.SH STANDARDS
+Linux.
+.SH HISTORY
+Linux 6.7.
+.SH SEE ALSO
+.BR ioctl (2)
--
2.42.0
^ permalink raw reply related [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] ioctl_userfaultfd.2: add UFFD_FEATURE_WP_ASYNC
2023-10-19 13:12 [PATCH 1/2] ioctl_userfaultfd.2: add UFFD_FEATURE_WP_ASYNC Muhammad Usama Anjum
2023-10-19 13:12 ` [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL Muhammad Usama Anjum
@ 2023-10-19 13:27 ` Alejandro Colomar
2023-10-19 13:29 ` Alejandro Colomar
2 siblings, 0 replies; 18+ messages in thread
From: Alejandro Colomar @ 2023-10-19 13:27 UTC (permalink / raw)
To: Muhammad Usama Anjum; +Cc: kernel, linux-man
[-- Attachment #1: Type: text/plain, Size: 955 bytes --]
Hi Muhammad,
On Thu, Oct 19, 2023 at 06:12:44PM +0500, Muhammad Usama Anjum wrote:
> Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
Patch applied. Thanks,
Alex
> ---
> Changes since v1:
> - Employ sementic new lines by breaking sentence before "by"
> ---
> man2/ioctl_userfaultfd.2 | 5 +++++
> 1 file changed, 5 insertions(+)
>
> diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2
> index e68085262..f6cafd9a2 100644
> --- a/man2/ioctl_userfaultfd.2
> +++ b/man2/ioctl_userfaultfd.2
> @@ -244,6 +244,11 @@ If this feature bit is set,
> the kernel supports resolving faults with the
> .B UFFDIO_POISON
> ioctl.
> +.TP
> +.BR UFFD_FEATURE_WP_ASYNC " (since Linux 6.7)"
> +If this feature bit is set,
> +the write protection faults would be asynchronously resolved
> +by the kernel.
> .PP
> The returned
> .I ioctls
> --
> 2.42.0
>
--
<https://www.alejandro-colomar.es/>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] ioctl_userfaultfd.2: add UFFD_FEATURE_WP_ASYNC
2023-10-19 13:12 [PATCH 1/2] ioctl_userfaultfd.2: add UFFD_FEATURE_WP_ASYNC Muhammad Usama Anjum
2023-10-19 13:12 ` [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL Muhammad Usama Anjum
2023-10-19 13:27 ` [PATCH 1/2] ioctl_userfaultfd.2: add UFFD_FEATURE_WP_ASYNC Alejandro Colomar
@ 2023-10-19 13:29 ` Alejandro Colomar
2023-10-19 13:34 ` Muhammad Usama Anjum
2 siblings, 1 reply; 18+ messages in thread
From: Alejandro Colomar @ 2023-10-19 13:29 UTC (permalink / raw)
To: Muhammad Usama Anjum; +Cc: kernel, linux-man
[-- Attachment #1: Type: text/plain, Size: 954 bytes --]
On Thu, Oct 19, 2023 at 06:12:44PM +0500, Muhammad Usama Anjum wrote:
> Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
> ---
> Changes since v1:
> - Employ sementic new lines by breaking sentence before "by"
> ---
> man2/ioctl_userfaultfd.2 | 5 +++++
> 1 file changed, 5 insertions(+)
>
> diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2
> index e68085262..f6cafd9a2 100644
> --- a/man2/ioctl_userfaultfd.2
> +++ b/man2/ioctl_userfaultfd.2
> @@ -244,6 +244,11 @@ If this feature bit is set,
> the kernel supports resolving faults with the
> .B UFFDIO_POISON
> ioctl.
> +.TP
> +.BR UFFD_FEATURE_WP_ASYNC " (since Linux 6.7)"
Has this feature been merged?
Thanks,
Alex
> +If this feature bit is set,
> +the write protection faults would be asynchronously resolved
> +by the kernel.
> .PP
> The returned
> .I ioctls
> --
> 2.42.0
>
--
<https://www.alejandro-colomar.es/>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] ioctl_userfaultfd.2: add UFFD_FEATURE_WP_ASYNC
2023-10-19 13:29 ` Alejandro Colomar
@ 2023-10-19 13:34 ` Muhammad Usama Anjum
2023-10-19 13:42 ` Alejandro Colomar
0 siblings, 1 reply; 18+ messages in thread
From: Muhammad Usama Anjum @ 2023-10-19 13:34 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: Muhammad Usama Anjum, kernel, linux-man
On 10/19/23 6:29 PM, Alejandro Colomar wrote:
> On Thu, Oct 19, 2023 at 06:12:44PM +0500, Muhammad Usama Anjum wrote:
>> Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
>> ---
>> Changes since v1:
>> - Employ sementic new lines by breaking sentence before "by"
>> ---
>> man2/ioctl_userfaultfd.2 | 5 +++++
>> 1 file changed, 5 insertions(+)
>>
>> diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2
>> index e68085262..f6cafd9a2 100644
>> --- a/man2/ioctl_userfaultfd.2
>> +++ b/man2/ioctl_userfaultfd.2
>> @@ -244,6 +244,11 @@ If this feature bit is set,
>> the kernel supports resolving faults with the
>> .B UFFDIO_POISON
>> ioctl.
>> +.TP
>> +.BR UFFD_FEATURE_WP_ASYNC " (since Linux 6.7)"
>
> Has this feature been merged?
Yes, This patch is in maintainer's tree (in mm-stable these day).
https://lore.kernel.org/all/20231018213452.A78A8C433C8@smtp.kernel.org
It should be released with next kernel release.
I'm not sure if you can accept a patch which isn't in Linus's tree yet. But
these patches are already in maintainer's tree and in linux-next from
almost a month.
>
> Thanks,
> Alex
>
>> +If this feature bit is set,
>> +the write protection faults would be asynchronously resolved
>> +by the kernel.
>> .PP
>> The returned
>> .I ioctls
>> --
>> 2.42.0
>>
>
--
BR,
Muhammad Usama Anjum
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 1/2] ioctl_userfaultfd.2: add UFFD_FEATURE_WP_ASYNC
2023-10-19 13:34 ` Muhammad Usama Anjum
@ 2023-10-19 13:42 ` Alejandro Colomar
0 siblings, 0 replies; 18+ messages in thread
From: Alejandro Colomar @ 2023-10-19 13:42 UTC (permalink / raw)
To: Muhammad Usama Anjum; +Cc: kernel, linux-man
[-- Attachment #1: Type: text/plain, Size: 1839 bytes --]
Hi Muhammad,
On Thu, Oct 19, 2023 at 06:34:26PM +0500, Muhammad Usama Anjum wrote:
> On 10/19/23 6:29 PM, Alejandro Colomar wrote:
> > On Thu, Oct 19, 2023 at 06:12:44PM +0500, Muhammad Usama Anjum wrote:
> >> Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
> >> ---
> >> Changes since v1:
> >> - Employ sementic new lines by breaking sentence before "by"
> >> ---
> >> man2/ioctl_userfaultfd.2 | 5 +++++
> >> 1 file changed, 5 insertions(+)
> >>
> >> diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2
> >> index e68085262..f6cafd9a2 100644
> >> --- a/man2/ioctl_userfaultfd.2
> >> +++ b/man2/ioctl_userfaultfd.2
> >> @@ -244,6 +244,11 @@ If this feature bit is set,
> >> the kernel supports resolving faults with the
> >> .B UFFDIO_POISON
> >> ioctl.
> >> +.TP
> >> +.BR UFFD_FEATURE_WP_ASYNC " (since Linux 6.7)"
> >
> > Has this feature been merged?
> Yes, This patch is in maintainer's tree (in mm-stable these day).
> https://lore.kernel.org/all/20231018213452.A78A8C433C8@smtp.kernel.org
>
> It should be released with next kernel release.
>
> I'm not sure if you can accept a patch which isn't in Linus's tree yet. But
> these patches are already in maintainer's tree and in linux-next from
> almost a month.
Yep, if it's in a maintainer tree, I prefer merging it already, unless
you expect significant changes before Linus. If anything happens, we
can fix it later.
In linux-next, I'd prefer to wait.
Cheers,
Alex
> >
> > Thanks,
> > Alex
> >
> >> +If this feature bit is set,
> >> +the write protection faults would be asynchronously resolved
> >> +by the kernel.
> >> .PP
> >> The returned
> >> .I ioctls
> >> --
> >> 2.42.0
> >>
> >
>
> --
> BR,
> Muhammad Usama Anjum
--
<https://www.alejandro-colomar.es/>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL
2023-10-19 13:12 ` [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL Muhammad Usama Anjum
@ 2023-10-23 21:52 ` Alejandro Colomar
2023-10-24 2:48 ` G. Branden Robinson
2023-10-24 15:51 ` [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL Muhammad Usama Anjum
0 siblings, 2 replies; 18+ messages in thread
From: Alejandro Colomar @ 2023-10-23 21:52 UTC (permalink / raw)
To: Muhammad Usama Anjum; +Cc: kernel, linux-man, G. Branden Robinson
[-- Attachment #1: Type: text/plain, Size: 8478 bytes --]
Hi Muhammad,
[CC += Branden]
On Thu, Oct 19, 2023 at 06:12:45PM +0500, Muhammad Usama Anjum wrote:
> Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
> ---
> The feature has been added to mm-stable:
> https://lore.kernel.org/all/20231018213453.BF1ACC43395@smtp.kernel.org
>
> Changes since v1:
> - Several formatting updates
> - Added some additional sentences
Wow, the formatting is very well done. Great job! Patch applied.
See a few small comments below.
> ---
> man2/ioctl_pagemap_scan.2 | 203 ++++++++++++++++++++++++++++++++++++++
> 1 file changed, 203 insertions(+)
> create mode 100644 man2/ioctl_pagemap_scan.2
>
> diff --git a/man2/ioctl_pagemap_scan.2 b/man2/ioctl_pagemap_scan.2
> new file mode 100644
> index 000000000..c257072d7
> --- /dev/null
> +++ b/man2/ioctl_pagemap_scan.2
> @@ -0,0 +1,203 @@
> +.\" This manpage is Copyright (C) 2023 Collabora;
> +.\" Written by Muhammad Usama Anjum <usama.anjum@collabora.com>
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.TH ioctl_pagemap_scan 2 2023-10-17 "Linux man-pages (unreleased)"
> +.SH NAME
> +ioctl_pagemap_scan \- get and/or clear page flags
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ", " \-lc )
> +.SH SYNOPSIS
> +.nf
> +.BR "#include <linux/fs.h>" " /* Definition of " struct " " pm_scan_arg ", "
> +.BR " struct page_region "and " PAGE_IS_* "constants " */"
That space is not necessary after a closing '"' is something I don't
know why exists. I changed that slightly.
Also, we use the Oxford comma (a comma right before 'and' and 'or'.
-.BR "#include <linux/fs.h>" " /* Definition of " struct " " pm_scan_arg ", "
-.BR " struct page_region "and " PAGE_IS_* "constants " */"
+.BR "#include <linux/fs.h>" " /* Definition of " "struct pm_scan_arg" ,
+.BR " struct page_region" ", and " PAGE_IS_* " constants */"
> +.B #include <sys/ioctl.h>
> +.PP
> +.BI "int ioctl(int " pagemap_fd ", PAGEMAP_SCAN, struct pm_scan_arg *" arg );
> +.fi
> +.SH DESCRIPTION
> +This
> +.BR ioctl (2)
> +is used to get and optionally clear some specific flags from page table entries.
> +The information is returned with
> +.B PAGE_SIZE
> +granularity.
> +.PP
> +To start tracking the written state (flag) of a page or range of memory,
> +the
> +.B UFFD_FEATURE_WP_ASYNC
> +must be enabled by
> +.B UFFDIO_API
> +.BR ioctl (2)
> +on
> +.B userfaultfd
> +and memory range must be registered with
> +.B UFFDIO_REGISTER
> +.BR ioctl (2)
> +in
> +.B UFFDIO_REGISTER_MODE_WP
> +mode.
> +.SS Supported page flags
> +The following page table entry flags are supported:
> +.TP
> +.B PAGE_IS_WPALLOWED
> +The page has asynchronous write-protection enabled.
> +.TP
> +.B PAGE_IS_WRITTEN
> +The page has been written to from the time it was write protected.
> +.TP
> +.B PAGE_IS_FILE
> +The page is file backed.
> +.TP
> +.B PAGE_IS_PRESENT
> +The page is present in the memory.
> +.TP
> +.B PAGE_IS_SWAPPED
> +The page is swapped.
> +.TP
> +.B PAGE_IS_PFNZERO
> +The page has zero PFN.
> +.TP
> +.B PAGE_IS_HUGE
> +The page is THP or Hugetlb backed.
> +.SS Supported operations
> +The get operation is always performed
> +if the output buffer is specified.
> +The other operations are as following:
> +.TP
> +.B PM_SCAN_WP_MATCHING
> +Write protect the matched pages.
> +.TP
> +.B PM_SCAN_CHECK_WPASYNC
> +Abort the scan
> +when a page is found
> +which doesn't have the Userfaultfd Asynchronous Write protection enabled.
> +.SS The \f[I]struct pm_scan_arg\f[] argument
> +.EX
> +struct pm_scan_arg {
> + __u64 size;
> + __u64 flags;
> + __u64 start;
> + __u64 end;
> + __u64 walk_end;
> + __u64 vec;
> + __u64 vec_len;
> + __u64 max_pages
> + __u64 category_inverted;
> + __u64 category_mask;
> + __u64 category_anyof_mask
> + __u64 return_mask;
I prefer two spaces between the type and the name. I got that habit
from nginx.
<https://nginx.org/en/docs/dev/development_guide.html#code_style>
struct pm_scan_arg {
- __u64 size;
- __u64 flags;
- __u64 start;
- __u64 end;
- __u64 walk_end;
- __u64 vec;
- __u64 vec_len;
- __u64 max_pages
- __u64 category_inverted;
- __u64 category_mask;
- __u64 category_anyof_mask
- __u64 return_mask;
+ __u64 size;
+ __u64 flags;
+ __u64 start;
+ __u64 end;
+ __u64 walk_end;
+ __u64 vec;
+ __u64 vec_len;
+ __u64 max_pages
+ __u64 category_inverted;
+ __u64 category_mask;
+ __u64 category_anyof_mask
+ __u64 return_mask;
};
> +};
> +.EE
> +.TP
> +.B size
> +This field should be set to the size of the structure in bytes,
> +as in
> +.IR "sizeof(struct pm_scan_arg)" .
We try to use \~ for a fillable space; it has the nice effect of
removing the quotes.
-.IR "sizeof(struct pm_scan_arg)" .
+.IR sizeof(struct\~pm_scan_arg) .
> +.TP
> +.B flags
> +The operations to be performed are specified in it.
> +.TP
> +.B start
> +The starting address of the scan is specified in it.
> +.TP
> +.B end
> +The ending address of the scan is specified in it.
> +.TP
> +.B walk_end
> +The kernel returns the scan's ending address in it.
> +The
> +.I walk_end
> +equal to
> +.I end
> +means that scan has completed on the entire range.
> +.TP
> +.B vec
> +The address of
> +.I page_region
> +array for output.
> +.PP
> +.in +8n
Ahh, this is great, because I needed to explain to groff(1) maintainers
what is the problem with TP that I was complaining about in another
thread.
Branden, here's what I mean. If you're new to man(7), it is rather
unintuitive what to do here.
Muhammad, in this project, we usually use IP to continuate a TP. PP
would break the indentation back to before the TP, which is why you
needed so much in 'in'.
Another solution, which we're discussing is wrapping everything is RS/RE.
I applied this:
-.PP
-.in +8n
+.IP
+.in +4n
> +.EX
> +struct page_region {
> + __u64 start;
> + __u64 end;
> + __u64 categories;
> +};
> +.EE
> +.in
> +.TP
> +.B vec_len
> +The length of the
> +.I page_region
> +struct array.
> +.TP
> +.B max_pages
> +It is the optional limit for the number of output pages required.
> +.TP
> +.B category_inverted
> +.BI PAGE_IS_ *
> +categories which values match if 0 instead of 1.
> +.TP
> +.B category_mask
> +Skip pages for which any
> +.BI PAGE_IS_ *
> +category doesn't match.
> +.TP
> +.B category_anyof_mask
> +Skip pages for which no
> +.BI PAGE_IS_ *
> +category matches.
> +.TP
> +.B return_mask
> +.BI PAGE_IS_ *
> +categories that are to be reported in
> +.IR page_region .
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EINVAL
> +Invalid arguments i.e., invalid
> +.I size
> +of the argument, invalid
> +.IR flags ,
> +invalid
> +.IR categories ,
> +the
> +.I start
> +address isn't aligned with
> +.B PAGE_SIZE
> +or
> +.I vec_len
> +is specified when
> +.I vec
> +is
> +.BR NULL .
> +.TP
> +.B EFAULT
> +Invalid
> +.I arg
> +pointer, invalid
> +.I vec
> +pointer or invalid address range specified by
> +.I start
> +and
> +.IR end .
> +.TP
> +.B ENOMEM
> +No memory is available.
> +.TP
> +.B EINTR
> +Fetal signal is pending.
And a bit more of semantic newlines:
@@ -163,29 +163,32 @@ .SH ERRORS
Error codes can be one of, but are not limited to, the following:
.TP
.B EINVAL
-Invalid arguments i.e., invalid
+Invalid arguments i.e.,
+invalid
.I size
-of the argument, invalid
+of the argument,
+invalid
.IR flags ,
invalid
.IR categories ,
the
.I start
address isn't aligned with
-.B PAGE_SIZE
+.BR PAGE_SIZE ,
or
.I vec_len
is specified when
.I vec
-is
-.BR NULL .
+is NULL.
.TP
.B EFAULT
Invalid
.I arg
-pointer, invalid
+pointer,
+invalid
.I vec
-pointer or invalid address range specified by
+pointer,
+or invalid address range specified by
.I start
and
.IR end .
Cheers,
Alex
> +.SH STANDARDS
> +Linux.
> +.SH HISTORY
> +Linux 6.7.
> +.SH SEE ALSO
> +.BR ioctl (2)
> --
> 2.42.0
>
--
<https://www.alejandro-colomar.es/>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL
2023-10-23 21:52 ` Alejandro Colomar
@ 2023-10-24 2:48 ` G. Branden Robinson
2023-10-24 10:40 ` Alejandro Colomar
2023-10-24 15:51 ` [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL Muhammad Usama Anjum
1 sibling, 1 reply; 18+ messages in thread
From: G. Branden Robinson @ 2023-10-24 2:48 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: Muhammad Usama Anjum, kernel, linux-man
[-- Attachment #1: Type: text/plain, Size: 3907 bytes --]
Hi Alex,
At 2023-10-23T23:52:28+0200, Alejandro Colomar wrote:
> [CC += Branden]
> > +.SH SYNOPSIS
> > +.nf
> > +.BR "#include <linux/fs.h>" " /* Definition of " struct " " pm_scan_arg ", "
> > +.BR " struct page_region "and " PAGE_IS_* "constants " */"
>
> That space is not necessary after a closing '"' is something I don't
> know why exists.
Right; since filling is off, and the line will be broken after
"pm_scan_arg," (with typeface changes) anyway, this attempts to put a
space at the end of the line. But that would be invisible, and an
according-to-Hoyle *roff formatter would get rid of such spaces at the
end of the line before sending them to the output device anyway.
$ printf '.TH foo 1 date package\n.B "pm_scan_arg, "\n' \
| groff -Tutf8 -man -Z | sed -n '/pm_scan_arg/,/package/p'
tpm_scan_arg,
n40 0
f1
V200
H0
tpackage
If one has learned device-independent troff's output language (see
groff_out(5)), one can see that the space after the comma is simply
discarded.
> I changed that slightly.
[...]
> We try to use \~ for a fillable space; it has the nice effect of
> removing the quotes.
>
> -.IR "sizeof(struct pm_scan_arg)" .
> +.IR sizeof(struct\~pm_scan_arg) .
Yes. This is portable _almost_ everywhere (certainly anyplace where
_Linux_ man pages are available), and it can prevent a lot of ugliness.
groff_man_style(7):
\~ Adjustable non‐breaking space. Use this escape
sequence to prevent a break inside a short phrase or
between a numerical quantity and its corresponding
unit(s).
Before starting the motor,
set the output speed to\~1.
There are 1,024\~bytes in 1\~KiB.
CSTR\~#8 documents the B\~language.
\~ is a GNU extension also supported by Heirloom
Doctools troff 050915 (September 2005), mandoc 1.9.14
(2009‐11‐16), neatroff (commit 1c6ab0f6e, 2016‐09‐13),
and Plan 9 from User Space troff (commit 93f8143600,
2022‐08‐12), but not by Solaris or Documenter’s
Workbench troffs.
> > +.TP
> > +.B vec
> > +The address of
> > +.I page_region
> > +array for output.
> > +.PP
> > +.in +8n
>
> Ahh, this is great, because I needed to explain to groff(1)
> maintainers what is the problem with TP that I was complaining about
> in another thread.
>
> Branden, here's what I mean.
Good, yes. I see what you're talking about. We can now use
ioctl_pagemap_scan(2) as a site for our horrific medical experiments.
3:-)
I think this is an instance of the tricky little constraint problem
Michael Kerrisk and I discussed almost 3 years ago.
https://lore.kernel.org/linux-man/a79fc055-c7ab-1793-04eb-eb4f678e5035@gmail.com/
In all that time, no flash of brilliance has yet illuminated a solution
(that wouldn't involve extending the man(7) language, like recognizing
an additional argument to TP or other paragraphing macros).
> If you're new to man(7), it is rather unintuitive what to do here.
Yes. groff_man_style(7) attempts to offer advice here, in subsections
"Horizontal and vertical spacing" and as one of the FAQs in "Notes"
(".RS doesn't indent relative to my indented paragraph.").
That's more material than I care to quote to this list, so I will just
advise anyone who doesn't already have groff 1.23.0 installed to check
out pages 261 and 269 of
<https://www.gnu.org/software/groff/manual/groff-man-pages.pdf>.
> Muhammad, in this project, we usually use IP to continuate a TP.
More projects than this one use it for that purpose; when `IP` itself is
given no tag argument, it is idiomatic usage going back to 1979.
Regards,
Branden
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL
2023-10-24 2:48 ` G. Branden Robinson
@ 2023-10-24 10:40 ` Alejandro Colomar
2023-10-28 13:07 ` managing tagged paragraphs (was: [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL) G. Branden Robinson
0 siblings, 1 reply; 18+ messages in thread
From: Alejandro Colomar @ 2023-10-24 10:40 UTC (permalink / raw)
To: G. Branden Robinson; +Cc: Muhammad Usama Anjum, kernel, linux-man
[-- Attachment #1: Type: text/plain, Size: 3626 bytes --]
Hi Branden,
On Mon, Oct 23, 2023 at 09:48:02PM -0500, G. Branden Robinson wrote:
> Hi Alex,
>
> At 2023-10-23T23:52:28+0200, Alejandro Colomar wrote:
> > [CC += Branden]
> > > +.SH SYNOPSIS
> > > +.nf
> > > +.BR "#include <linux/fs.h>" " /* Definition of " struct " " pm_scan_arg ", "
> > > +.BR " struct page_region "and " PAGE_IS_* "constants " */"
> >
> > That space is not necessary after a closing '"' is something I don't
> > know why exists.
>
> Right; since filling is off, and the line will be broken after
> "pm_scan_arg," (with typeface changes) anyway, this attempts to put a
> space at the end of the line. But that would be invisible, and an
> according-to-Hoyle *roff formatter would get rid of such spaces at the
> end of the line before sending them to the output device anyway.
>
> $ printf '.TH foo 1 date package\n.B "pm_scan_arg, "\n' \
> | groff -Tutf8 -man -Z | sed -n '/pm_scan_arg/,/package/p'
> tpm_scan_arg,
> n40 0
> f1
> V200
> H0
> tpackage
>
> If one has learned device-independent troff's output language (see
> groff_out(5)), one can see that the space after the comma is simply
> discarded.
Hmm, I might use .grout for the similarity with that manual page name. ;)
[...]
>
> > > +.TP
> > > +.B vec
> > > +The address of
> > > +.I page_region
> > > +array for output.
> > > +.PP
> > > +.in +8n
> >
> > Ahh, this is great, because I needed to explain to groff(1)
> > maintainers what is the problem with TP that I was complaining about
> > in another thread.
> >
> > Branden, here's what I mean.
>
> Good, yes. I see what you're talking about. We can now use
> ioctl_pagemap_scan(2) as a site for our horrific medical experiments.
> 3:-)
>
> I think this is an instance of the tricky little constraint problem
> Michael Kerrisk and I discussed almost 3 years ago.
>
> https://lore.kernel.org/linux-man/a79fc055-c7ab-1793-04eb-eb4f678e5035@gmail.com/
Yep, and like Michael, I also dislike the line break. Is there any
chance that we could make it not break after TP so that it (RS) would be
usable there?
>
> In all that time, no flash of brilliance has yet illuminated a solution
> (that wouldn't involve extending the man(7) language, like recognizing
> an additional argument to TP or other paragraphing macros).
>
> > If you're new to man(7), it is rather unintuitive what to do here.
>
> Yes. groff_man_style(7) attempts to offer advice here, in subsections
> "Horizontal and vertical spacing" and as one of the FAQs in "Notes"
> (".RS doesn't indent relative to my indented paragraph.").
Yup, but anyone new to man(7) will likely be put off by that page.
$ man groff_man_style | wc -l
1439
If you're just contributing a few paragraphs, you may prefer to learn by
trial and error (which is a perfectly valid approach, and one that I
prefer). Only when I wanted to learn the more obscure details, or quote
to someone else, I've read that page (and I haven't read it entirely
yet!).
Cheers,
Alex
>
> That's more material than I care to quote to this list, so I will just
> advise anyone who doesn't already have groff 1.23.0 installed to check
> out pages 261 and 269 of
> <https://www.gnu.org/software/groff/manual/groff-man-pages.pdf>.
>
> > Muhammad, in this project, we usually use IP to continuate a TP.
>
> More projects than this one use it for that purpose; when `IP` itself is
> given no tag argument, it is idiomatic usage going back to 1979.
>
> Regards,
> Branden
--
<https://www.alejandro-colomar.es/>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL
2023-10-23 21:52 ` Alejandro Colomar
2023-10-24 2:48 ` G. Branden Robinson
@ 2023-10-24 15:51 ` Muhammad Usama Anjum
1 sibling, 0 replies; 18+ messages in thread
From: Muhammad Usama Anjum @ 2023-10-24 15:51 UTC (permalink / raw)
To: Alejandro Colomar
Cc: Muhammad Usama Anjum, kernel, linux-man, G. Branden Robinson
On 10/24/23 2:52 AM, Alejandro Colomar wrote:
> Hi Muhammad,
>
> [CC += Branden]
>
> On Thu, Oct 19, 2023 at 06:12:45PM +0500, Muhammad Usama Anjum wrote:
>> Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
>> ---
>> The feature has been added to mm-stable:
>> https://lore.kernel.org/all/20231018213453.BF1ACC43395@smtp.kernel.org
>>
>> Changes since v1:
>> - Several formatting updates
>> - Added some additional sentences
>
> Wow, the formatting is very well done. Great job! Patch applied.
Alex, thank you so much for explaining stuff in previous revision and in
this patch. I didn't know that comma before and and or is called Oxford comma.
> See a few small comments below.
>
>> ---
>> man2/ioctl_pagemap_scan.2 | 203 ++++++++++++++++++++++++++++++++++++++
>> 1 file changed, 203 insertions(+)
>> create mode 100644 man2/ioctl_pagemap_scan.2
>>
>> diff --git a/man2/ioctl_pagemap_scan.2 b/man2/ioctl_pagemap_scan.2
>> new file mode 100644
>> index 000000000..c257072d7
>> --- /dev/null
>> +++ b/man2/ioctl_pagemap_scan.2
>> @@ -0,0 +1,203 @@
>> +.\" This manpage is Copyright (C) 2023 Collabora;
>> +.\" Written by Muhammad Usama Anjum <usama.anjum@collabora.com>
>> +.\"
>> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
>> +.\"
>> +.TH ioctl_pagemap_scan 2 2023-10-17 "Linux man-pages (unreleased)"
>> +.SH NAME
>> +ioctl_pagemap_scan \- get and/or clear page flags
>> +.SH LIBRARY
>> +Standard C library
>> +.RI ( libc ", " \-lc )
>> +.SH SYNOPSIS
>> +.nf
>> +.BR "#include <linux/fs.h>" " /* Definition of " struct " " pm_scan_arg ", "
>> +.BR " struct page_region "and " PAGE_IS_* "constants " */"
>
> That space is not necessary after a closing '"' is something I don't
> know why exists. I changed that slightly.
>
> Also, we use the Oxford comma (a comma right before 'and' and 'or'.
>
> -.BR "#include <linux/fs.h>" " /* Definition of " struct " " pm_scan_arg ", "
> -.BR " struct page_region "and " PAGE_IS_* "constants " */"
> +.BR "#include <linux/fs.h>" " /* Definition of " "struct pm_scan_arg" ,
> +.BR " struct page_region" ", and " PAGE_IS_* " constants */"
>
>> +.B #include <sys/ioctl.h>
>> +.PP
>> +.BI "int ioctl(int " pagemap_fd ", PAGEMAP_SCAN, struct pm_scan_arg *" arg );
>> +.fi
>> +.SH DESCRIPTION
>> +This
>> +.BR ioctl (2)
>> +is used to get and optionally clear some specific flags from page table entries.
>> +The information is returned with
>> +.B PAGE_SIZE
>> +granularity.
>> +.PP
>> +To start tracking the written state (flag) of a page or range of memory,
>> +the
>> +.B UFFD_FEATURE_WP_ASYNC
>> +must be enabled by
>> +.B UFFDIO_API
>> +.BR ioctl (2)
>> +on
>> +.B userfaultfd
>> +and memory range must be registered with
>> +.B UFFDIO_REGISTER
>> +.BR ioctl (2)
>> +in
>> +.B UFFDIO_REGISTER_MODE_WP
>> +mode.
>> +.SS Supported page flags
>> +The following page table entry flags are supported:
>> +.TP
>> +.B PAGE_IS_WPALLOWED
>> +The page has asynchronous write-protection enabled.
>> +.TP
>> +.B PAGE_IS_WRITTEN
>> +The page has been written to from the time it was write protected.
>> +.TP
>> +.B PAGE_IS_FILE
>> +The page is file backed.
>> +.TP
>> +.B PAGE_IS_PRESENT
>> +The page is present in the memory.
>> +.TP
>> +.B PAGE_IS_SWAPPED
>> +The page is swapped.
>> +.TP
>> +.B PAGE_IS_PFNZERO
>> +The page has zero PFN.
>> +.TP
>> +.B PAGE_IS_HUGE
>> +The page is THP or Hugetlb backed.
>> +.SS Supported operations
>> +The get operation is always performed
>> +if the output buffer is specified.
>> +The other operations are as following:
>> +.TP
>> +.B PM_SCAN_WP_MATCHING
>> +Write protect the matched pages.
>> +.TP
>> +.B PM_SCAN_CHECK_WPASYNC
>> +Abort the scan
>> +when a page is found
>> +which doesn't have the Userfaultfd Asynchronous Write protection enabled.
>> +.SS The \f[I]struct pm_scan_arg\f[] argument
>> +.EX
>> +struct pm_scan_arg {
>> + __u64 size;
>> + __u64 flags;
>> + __u64 start;
>> + __u64 end;
>> + __u64 walk_end;
>> + __u64 vec;
>> + __u64 vec_len;
>> + __u64 max_pages
>> + __u64 category_inverted;
>> + __u64 category_mask;
>> + __u64 category_anyof_mask
>> + __u64 return_mask;
>
> I prefer two spaces between the type and the name. I got that habit
> from nginx.
> <https://nginx.org/en/docs/dev/development_guide.html#code_style>
>
> struct pm_scan_arg {
> - __u64 size;
> - __u64 flags;
> - __u64 start;
> - __u64 end;
> - __u64 walk_end;
> - __u64 vec;
> - __u64 vec_len;
> - __u64 max_pages
> - __u64 category_inverted;
> - __u64 category_mask;
> - __u64 category_anyof_mask
> - __u64 return_mask;
> + __u64 size;
> + __u64 flags;
> + __u64 start;
> + __u64 end;
> + __u64 walk_end;
> + __u64 vec;
> + __u64 vec_len;
> + __u64 max_pages
> + __u64 category_inverted;
> + __u64 category_mask;
> + __u64 category_anyof_mask
> + __u64 return_mask;
> };
>
>
>> +};
>> +.EE
>> +.TP
>> +.B size
>> +This field should be set to the size of the structure in bytes,
>> +as in
>> +.IR "sizeof(struct pm_scan_arg)" .
>
> We try to use \~ for a fillable space; it has the nice effect of
> removing the quotes.
>
> -.IR "sizeof(struct pm_scan_arg)" .
> +.IR sizeof(struct\~pm_scan_arg) .
>
>> +.TP
>> +.B flags
>> +The operations to be performed are specified in it.
>> +.TP
>> +.B start
>> +The starting address of the scan is specified in it.
>> +.TP
>> +.B end
>> +The ending address of the scan is specified in it.
>> +.TP
>> +.B walk_end
>> +The kernel returns the scan's ending address in it.
>> +The
>> +.I walk_end
>> +equal to
>> +.I end
>> +means that scan has completed on the entire range.
>> +.TP
>> +.B vec
>> +The address of
>> +.I page_region
>> +array for output.
>> +.PP
>> +.in +8n
>
> Ahh, this is great, because I needed to explain to groff(1) maintainers
> what is the problem with TP that I was complaining about in another
> thread.
>
> Branden, here's what I mean. If you're new to man(7), it is rather
> unintuitive what to do here.
>
> Muhammad, in this project, we usually use IP to continuate a TP. PP
> would break the indentation back to before the TP, which is why you
> needed so much in 'in'.
>
> Another solution, which we're discussing is wrapping everything is RS/RE.
>
> I applied this:
>
> -.PP
> -.in +8n
> +.IP
> +.in +4n
>
>
>> +.EX
>> +struct page_region {
>> + __u64 start;
>> + __u64 end;
>> + __u64 categories;
>> +};
>> +.EE
>> +.in
>> +.TP
>> +.B vec_len
>> +The length of the
>> +.I page_region
>> +struct array.
>> +.TP
>> +.B max_pages
>> +It is the optional limit for the number of output pages required.
>> +.TP
>> +.B category_inverted
>> +.BI PAGE_IS_ *
>> +categories which values match if 0 instead of 1.
>> +.TP
>> +.B category_mask
>> +Skip pages for which any
>> +.BI PAGE_IS_ *
>> +category doesn't match.
>> +.TP
>> +.B category_anyof_mask
>> +Skip pages for which no
>> +.BI PAGE_IS_ *
>> +category matches.
>> +.TP
>> +.B return_mask
>> +.BI PAGE_IS_ *
>> +categories that are to be reported in
>> +.IR page_region .
>> +.SH RETURN VALUE
>> +On error, \-1 is returned, and
>> +.I errno
>> +is set to indicate the error.
>> +.SH ERRORS
>> +Error codes can be one of, but are not limited to, the following:
>> +.TP
>> +.B EINVAL
>> +Invalid arguments i.e., invalid
>> +.I size
>> +of the argument, invalid
>> +.IR flags ,
>> +invalid
>> +.IR categories ,
>> +the
>> +.I start
>> +address isn't aligned with
>> +.B PAGE_SIZE
>> +or
>> +.I vec_len
>> +is specified when
>> +.I vec
>> +is
>> +.BR NULL .
>> +.TP
>> +.B EFAULT
>> +Invalid
>> +.I arg
>> +pointer, invalid
>> +.I vec
>> +pointer or invalid address range specified by
>> +.I start
>> +and
>> +.IR end .
>> +.TP
>> +.B ENOMEM
>> +No memory is available.
>> +.TP
>> +.B EINTR
>> +Fetal signal is pending.
>
> And a bit more of semantic newlines:
>
> @@ -163,29 +163,32 @@ .SH ERRORS
> Error codes can be one of, but are not limited to, the following:
> .TP
> .B EINVAL
> -Invalid arguments i.e., invalid
> +Invalid arguments i.e.,
> +invalid
> .I size
> -of the argument, invalid
> +of the argument,
> +invalid
> .IR flags ,
> invalid
> .IR categories ,
> the
> .I start
> address isn't aligned with
> -.B PAGE_SIZE
> +.BR PAGE_SIZE ,
> or
> .I vec_len
> is specified when
> .I vec
> -is
> -.BR NULL .
> +is NULL.
> .TP
> .B EFAULT
> Invalid
> .I arg
> -pointer, invalid
> +pointer,
> +invalid
> .I vec
> -pointer or invalid address range specified by
> +pointer,
> +or invalid address range specified by
> .I start
> and
> .IR end .
>
>
> Cheers,
> Alex
>
>> +.SH STANDARDS
>> +Linux.
>> +.SH HISTORY
>> +Linux 6.7.
>> +.SH SEE ALSO
>> +.BR ioctl (2)
>> --
>> 2.42.0
>>
>
--
BR,
Muhammad Usama Anjum
^ permalink raw reply [flat|nested] 18+ messages in thread
* managing tagged paragraphs (was: [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL)
2023-10-24 10:40 ` Alejandro Colomar
@ 2023-10-28 13:07 ` G. Branden Robinson
2023-10-28 16:22 ` Alejandro Colomar
0 siblings, 1 reply; 18+ messages in thread
From: G. Branden Robinson @ 2023-10-28 13:07 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: Muhammad Usama Anjum, kernel, linux-man
[-- Attachment #1: Type: text/plain, Size: 5944 bytes --]
Hi Alex,
At 2023-10-24T12:40:55+0200, Alejandro Colomar wrote:
> On Mon, Oct 23, 2023 at 09:48:02PM -0500, G. Branden Robinson wrote:
> > If one has learned device-independent troff's output language (see
> > groff_out(5)), one can see that the space after the comma is simply
> > discarded.
>
> Hmm, I might use .grout for the similarity with that manual page name.
> ;)
Yes, I like the terms "trout" and "grout" for the original Kernighan
device-independent troff format and GNU's extended version of it,
respectively. But I have met few other people who do. :)
> > Good, yes. I see what you're talking about. We can now use
> > ioctl_pagemap_scan(2) as a site for our horrific medical experiments.
> > 3:-)
> >
> > I think this is an instance of the tricky little constraint problem
> > Michael Kerrisk and I discussed almost 3 years ago.
> >
> > https://lore.kernel.org/linux-man/a79fc055-c7ab-1793-04eb-eb4f678e5035@gmail.com/
>
> Yep, and like Michael, I also dislike the line break. Is there any
> chance that we could make it not break after TP so that it (RS) would
> be usable there?
The exhibit was roughly this (based on ioctl_pageman_scan(2)):
.TH foo 2 2023-10-28 "groff test suite"
.TP
.B vec
The address of
.I page_region
array for output.
.IP
.in +4n
.EX
struct page_region {
__u64 start;
__u64 end;
__u64 categories;
};
.EE
.in
Other text.
This already formats without a line break after `TP`.
$ nroff -man -Tascii ATTIC/vec.man
foo(2) System Calls Manual foo(2)
vec The address of page_region array for output.
struct page_region {
__u64 start;
__u64 end;
__u64 categories;
};
Other text.
groff test suite 2023-10-28 foo(2)
If the paragraph tag is long, man(7) will break the line after it.
$ nroff -man -Tascii ATTIC/vec.man
foo(2) System Calls Manual foo(2)
vecvecvec
The address of page_region array for output.
struct page_region {
__u64 start;
__u64 end;
__u64 categories;
};
Other text.
groff test suite 2023-10-28 foo(2)
If you want to set the tag on the same line as the tag, you need to give
`TP` an argument indicating the desired width of the tag. E.g.,
".TP 11n".
$ nroff -man -Tascii ATTIC/vec.man
foo(2) System Calls Manual foo(2)
vecvecvec The address of page_region array for output.
struct page_region {
__u64 start;
__u64 end;
__u64 categories;
};
Other text.
groff test suite 2023-10-28 foo(2)
If you want to _force_ a break after tag no matter its width, there are
a few ways, but for practical purposes, an inset region is useful.
I'm considerably elaborating the example here to illustrate the
adaptability of the "nest-RS-and-RE-within-TP" approach.
$ cat ATTIC/vec.man
.TH foo 2 2023-10-28 "groff test suite"
.TP
.B vec
.RS
The address of
.I page_region
array for output.
.P
Further details about page regions.
.RS
.P
.EX
struct page_region {
__u64 start;
__u64 end;
__u64 categories;
};
.EE
.RE
.P
Further discussion of
.BR vec .
.RE
.P
We will talk about something else now.
$ nroff -man -Tascii ATTIC/vec.man
foo(2) System Calls Manual foo(2)
vec
The address of page_region array for output.
Further details about page regions.
struct page_region {
__u64 start;
__u64 end;
__u64 categories;
};
Further discussion of vec.
We will talk about something else now.
groff test suite 2023-10-28 foo(2)
Notice how I needed neither `in` requests nor the `IP` macro for that.
This approach is fairly flexible, and still works for simple cases (but
does _force_ a break after the tag).
$ cat ATTIC/vec.man
.TH foo 2 2023-10-28 "groff test suite"
.TP
.B vec
.RS
The address of
.I page_region
array for output.
.RE
.TP
.B vec_len
The length of the
.I page_region
struct array.
$ nroff -man -Tascii ATTIC/vec.man
foo(2) System Calls Manual foo(2)
vec
The address of page_region array for output.
vec_len
The length of the page_region struct array.
groff test suite 2023-10-28 foo(2)
> Yup, but anyone new to man(7) will likely be put off by that page.
>
> $ man groff_man_style | wc -l
> 1439
Because we don't know your terminal width, that number doesn't
communicate a lot. But it is just shy of 20k words in groff 1.23.0.
The "reference" version, groff_man(7), is half as long.
> If you're just contributing a few paragraphs, you may prefer to learn
> by trial and error (which is a perfectly valid approach, and one that
> I prefer).
Experimentation is certainly superior to guessing (or assuming).
> Only when I wanted to learn the more obscure details, or quote
> to someone else, I've read that page (and I haven't read it entirely
> yet!).
I look forward to your critique from a position of practical experience.
Regards,
Branden
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: managing tagged paragraphs (was: [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL)
2023-10-28 13:07 ` managing tagged paragraphs (was: [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL) G. Branden Robinson
@ 2023-10-28 16:22 ` Alejandro Colomar
2023-10-28 18:07 ` G. Branden Robinson
0 siblings, 1 reply; 18+ messages in thread
From: Alejandro Colomar @ 2023-10-28 16:22 UTC (permalink / raw)
To: G. Branden Robinson; +Cc: Muhammad Usama Anjum, kernel, linux-man
[-- Attachment #1: Type: text/plain, Size: 3293 bytes --]
Hi Branden,
On Sat, Oct 28, 2023 at 08:07:14AM -0500, G. Branden Robinson wrote:
> Hi Alex,
>
> At 2023-10-24T12:40:55+0200, Alejandro Colomar wrote:
> > On Mon, Oct 23, 2023 at 09:48:02PM -0500, G. Branden Robinson wrote:
> > > If one has learned device-independent troff's output language (see
> > > groff_out(5)), one can see that the space after the comma is simply
> > > discarded.
> >
> > Hmm, I might use .grout for the similarity with that manual page name.
> > ;)
>
> Yes, I like the terms "trout" and "grout" for the original Kernighan
> device-independent troff format and GNU's extended version of it,
> respectively. But I have met few other people who do. :)
>
> > > Good, yes. I see what you're talking about. We can now use
> > > ioctl_pagemap_scan(2) as a site for our horrific medical experiments.
> > > 3:-)
> > >
> > > I think this is an instance of the tricky little constraint problem
> > > Michael Kerrisk and I discussed almost 3 years ago.
> > >
> > > https://lore.kernel.org/linux-man/a79fc055-c7ab-1793-04eb-eb4f678e5035@gmail.com/
> >
> > Yep, and like Michael, I also dislike the line break. Is there any
> > chance that we could make it not break after TP so that it (RS) would
> > be usable there?
>
> The exhibit was roughly this (based on ioctl_pageman_scan(2)):
>
> .TH foo 2 2023-10-28 "groff test suite"
> .TP
> .B vec
> The address of
> .I page_region
> array for output.
> .IP
> .in +4n
> .EX
> struct page_region {
> __u64 start;
> __u64 end;
> __u64 categories;
> };
> .EE
> .in
> Other text.
>
> This already formats without a line break after `TP`.
I meant to ask if modifying RS's behavior to not break after TP was
something you'd consider viable.
[...]
> > Yup, but anyone new to man(7) will likely be put off by that page.
> >
> > $ man groff_man_style | wc -l
> > 1439
>
> Because we don't know your terminal width, that number doesn't
> communicate a lot.
Huh! I thought I had used the standard width, but it seems I didn't.
$ man groff_man_style | wc
1460 10154 81450
Even weirder is that it's not 89 either, which is the size of the
terminal when I use half screen. And to crash my brain, I can't even
reproduce it with any terminal size:
$ MANWIDTH=82 man groff_man_style | wc
1442 10152 81154
$ MANWIDTH=83 man groff_man_style | wc
1435 10156 80990
> But it is just shy of 20k words in groff 1.23.0.
> The "reference" version, groff_man(7), is half as long.
$ groff --version
GNU groff version 1.23.0.497-e982
>
> > If you're just contributing a few paragraphs, you may prefer to learn
> > by trial and error (which is a perfectly valid approach, and one that
> > I prefer).
>
> Experimentation is certainly superior to guessing (or assuming).
>
> > Only when I wanted to learn the more obscure details, or quote
> > to someone else, I've read that page (and I haven't read it entirely
> > yet!).
>
> I look forward to your critique from a position of practical experience.
Me too. I remember my promise to review it; I'm just very slow; even
slower than sloppy recuriters.
Cheers,
Alex
>
> Regards,
> Branden
--
<https://www.alejandro-colomar.es/>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: managing tagged paragraphs (was: [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL)
2023-10-28 16:22 ` Alejandro Colomar
@ 2023-10-28 18:07 ` G. Branden Robinson
2023-10-29 0:42 ` Alejandro Colomar
0 siblings, 1 reply; 18+ messages in thread
From: G. Branden Robinson @ 2023-10-28 18:07 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: linux-man
[-- Attachment #1: Type: text/plain, Size: 690 bytes --]
[dropping Muhammad and Collabora from Cc]
Hi Alex,
At 2023-10-28T18:22:52+0200, Alejandro Colomar wrote:
> I meant to ask if modifying RS's behavior to not break after TP was
> something you'd consider viable.
Ahh. Hmm. Can you show me an exhibit of desired output?
> $ MANWIDTH=82 man groff_man_style | wc
> 1442 10152 81154
> $ MANWIDTH=83 man groff_man_style | wc
> 1435 10156 80990
Only thing I can guess here is that man-db man(1) runs sandboxed and so
might not be running a groff from $HOME.
> Me too. I remember my promise to review it; I'm just very slow; even
> slower than sloppy recuriters.
I had no idea such a low speed was possible.
Regards,
Branden
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: managing tagged paragraphs (was: [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL)
2023-10-28 18:07 ` G. Branden Robinson
@ 2023-10-29 0:42 ` Alejandro Colomar
0 siblings, 0 replies; 18+ messages in thread
From: Alejandro Colomar @ 2023-10-29 0:42 UTC (permalink / raw)
To: G. Branden Robinson; +Cc: linux-man
[-- Attachment #1: Type: text/plain, Size: 2123 bytes --]
Hi Branden,
On Sat, Oct 28, 2023 at 01:07:03PM -0500, G. Branden Robinson wrote:
> At 2023-10-28T18:22:52+0200, Alejandro Colomar wrote:
> > I meant to ask if modifying RS's behavior to not break after TP was
> > something you'd consider viable.
>
> Ahh. Hmm. Can you show me an exhibit of desired output?
I'd like both sections to be identical in the following page (with the
behavior of the first one).
$ cat RS.man
.TH RS 7 to-morrow Alex
.SH Continuing TP with IP
.TP
tag
First paragraph.
.IP
Second paragraph.
.SH Continuing TP with RS
.TP
tag
.RS
First paragraph.
.PP
Second paragraph.
.RE
$ MANWIDTH=72 man ./RS.man | cat
RS(7) Miscellaneous Information Manual RS(7)
Continuing TP with IP
tag First paragraph.
Second paragraph.
Continuing TP with RS
tag
First paragraph.
Second paragraph.
Alex to‐morrow RS(7)
>
> > $ MANWIDTH=82 man groff_man_style | wc
> > 1442 10152 81154
> > $ MANWIDTH=83 man groff_man_style | wc
> > 1435 10156 80990
>
> Only thing I can guess here is that man-db man(1) runs sandboxed and so
> might not be running a groff from $HOME.
Heh, I've managed to reproduce it! It seems I run that thing just
before installing groff from git in this computer:
$ /usr/bin/groff --version | head -n1
GNU groff version 1.23.0
$ /usr/local/bin/groff --version | head -n1
GNU groff version 1.23.0.497-e982
$ MANROFFOPT=--version man man | head -n1
GNU nroff (groff) version 1.23.0.497-e982
$ PATH=/usr/bin
$ MANROFFOPT=--version man man | head -n1
GNU nroff (groff) version 1.23.0
$ MANWIDTH=80 man groff_man_style | wc
1439 9943 81331
>
> > Me too. I remember my promise to review it; I'm just very slow; even
> > slower than sloppy recuriters.
>
> I had no idea such a low speed was possible.
I've taken an entire year to read the Picture of Dorian Gray, if that
gives you an idea. :D
Cheers,
Alex
--
<https://www.alejandro-colomar.es/>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL
2023-10-19 12:31 ` Muhammad Usama Anjum
@ 2023-10-19 12:51 ` Alejandro Colomar
0 siblings, 0 replies; 18+ messages in thread
From: Alejandro Colomar @ 2023-10-19 12:51 UTC (permalink / raw)
To: Muhammad Usama Anjum; +Cc: kernel, linux-man
[-- Attachment #1: Type: text/plain, Size: 1155 bytes --]
Hi Muhammad,
On Thu, Oct 19, 2023 at 05:31:32PM +0500, Muhammad Usama Anjum wrote:
> Hi Alex,
>
> Thank you for taking time to review. I'll fix everything and run lint
> before sending next revision.
Thanks.
[...]
> >> +.SH DESCRIPTION
> >> +This
> >> +.BR ioctl (2)
> >> +is used to get and optionally clear some specific flags from page table entries.
> >> +
> >
> > Please use an empty roff(7) request instead of a empty input line. That
> > is, use a line with just a '.', that is, s/^$/./
Another thing you can use is a comment:
.\"
This is more commonly found in other pages in this repository.
Cheers,
Alex
> >
> > $ make lint build check --debug=print
> > TROFF .tmp/man/man2/ioctl_pagemap_scan.2.cat.set
> > ! (troff -wbreak -man -Tutf8 -rLL=78n -rCHECKSTYLE=3 -ww <.tmp/man/man2/ioctl_pagemap_scan.2.cat.troff 2>&1 >.tmp/man/man2/ioctl_pagemap_scan.2.cat.set \
> > | grep -v -f './share/lint/groff/man.ignore.grep' \
> > ||:; \
> > ) \
> > | grep ^ >&2
> > an.tmac:man2/ioctl_pagemap_scan.2:25: style: blank line in input
> > ...
--
<https://www.alejandro-colomar.es/>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL
2023-10-17 17:12 ` Alejandro Colomar
@ 2023-10-19 12:31 ` Muhammad Usama Anjum
2023-10-19 12:51 ` Alejandro Colomar
0 siblings, 1 reply; 18+ messages in thread
From: Muhammad Usama Anjum @ 2023-10-19 12:31 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: Muhammad Usama Anjum, kernel, linux-man
Hi Alex,
Thank you for taking time to review. I'll fix everything and run lint
before sending next revision.
On 10/17/23 10:12 PM, Alejandro Colomar wrote:
> Hi Muhammad,
>
> On Tue, Oct 17, 2023 at 08:01:32PM +0500, Muhammad Usama Anjum wrote:
>> Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
>
> Please link to the discussion where this feature is being discussed, in
> case someone needs to review it in the future.
>
>> ---
>> man2/ioctl_pagemap_scan.2 | 183 ++++++++++++++++++++++++++++++++++++++
>> 1 file changed, 183 insertions(+)
>> create mode 100644 man2/ioctl_pagemap_scan.2
>>
>> diff --git a/man2/ioctl_pagemap_scan.2 b/man2/ioctl_pagemap_scan.2
>> new file mode 100644
>> index 000000000..4e096028d
>> --- /dev/null
>> +++ b/man2/ioctl_pagemap_scan.2
>> @@ -0,0 +1,183 @@
>> +.\" This manpage is Copyright (C) 2023 Collabora;
>> +.\" Written by Muhammad Usama Anjum <usama.anjum@collabora.com>
>> +.\"
>> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
>> +.\"
>> +.\" Commit 84ceddb3c2b0c280936f28f450d65f46cb7411c6
>> +.\"
>> +.TH ioctl_pagemap_scan 2 2023-10-17 "Linux man-pages (unreleased)"
>> +.SH NAME
>> +ioctl_pagemap_scan \- get and/or clear page flags
>> +.SH LIBRARY
>> +Standard C library
>> +.RI ( libc ", " \-lc )
>> +.SH SYNOPSIS
>> +.nf
>> +.BR "#include <linux/fs.h>" " /* Definition of " struct " " pm_scan_arg ", " struct " " page_region " and " PAGE_IS_* " constants */"
>
> Please split the comment into several lines, so that the manual page can
> be read in an 80-column terminal without wrapping lines.
>
>> +.B #include <sys/ioctl.h>
>> +.PP
>> +.BI "int ioctl(int " pagemap_fd ", PAGEMAP_SCAN, struct pm_scan_arg *" arg );
>> +.fi
>> +.SH DESCRIPTION
>> +This
>> +.BR ioctl (2)
>> +is used to get and optionally clear some specific flags from page table entries.
>> +
>
> Please use an empty roff(7) request instead of a empty input line. That
> is, use a line with just a '.', that is, s/^$/./
>
> $ make lint build check --debug=print
> TROFF .tmp/man/man2/ioctl_pagemap_scan.2.cat.set
> ! (troff -wbreak -man -Tutf8 -rLL=78n -rCHECKSTYLE=3 -ww <.tmp/man/man2/ioctl_pagemap_scan.2.cat.troff 2>&1 >.tmp/man/man2/ioctl_pagemap_scan.2.cat.set \
> | grep -v -f './share/lint/groff/man.ignore.grep' \
> ||:; \
> ) \
> | grep ^ >&2
> an.tmac:man2/ioctl_pagemap_scan.2:25: style: blank line in input
> ...
>
>> +.SS Supported page flags
>> +The following page table entry flags are support:
>
> s/support/supported/
>
>> +.TP
>> +.BR PAGE_IS_WPALLOWED
>
> '.BR' is wrong here (it alternates bold and roman). It should be '.B',
> which is just bold. You can check groff_man(7) and groff_man_style(7).
> See these warnings:
>
> $ make lint build check --debug=print
> TROFF .tmp/man/man2/ioctl_pagemap_scan.2.cat.set
> ! (troff -wbreak -man -Tutf8 -rLL=78n -rCHECKSTYLE=3 -ww <.tmp/man/man2/ioctl_pagemap_scan.2.cat.troff 2>&1 >.tmp/man/man2/ioctl_pagemap_scan.2.cat.set \
> | grep -v -f './share/lint/groff/man.ignore.grep' \
> ||:; \
> ) \
> | grep ^ >&2
> an.tmac:man2/ioctl_pagemap_scan.2:25: style: blank line in input
> an.tmac:man2/ioctl_pagemap_scan.2:29: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:32: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:35: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:38: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:41: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:44: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:47: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:49: style: blank line in input
> an.tmac:man2/ioctl_pagemap_scan.2:53: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:56: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:58: style: blank line in input
> an.tmac:man2/ioctl_pagemap_scan.2:79: style: blank line in input
> an.tmac:man2/ioctl_pagemap_scan.2:81: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:88: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:91: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:94: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:97: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:99: style: .IR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:101: style: .IR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:104: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:106: style: .IR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:119: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:121: style: .IR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:124: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:127: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:130: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:133: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:136: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:138: style: .IR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:139: style: blank line in input
> an.tmac:man2/ioctl_pagemap_scan.2:157: style: .BR expects at least 2 arguments, got 1
> an.tmac:man2/ioctl_pagemap_scan.2:163: style: .BR expects at least 2 arguments, got 1
> make: *** [share/mk/build/catman.mk:54: .tmp/man/man2/ioctl_pagemap_scan.2.cat.set] Error 1
> make: *** Deleting file '.tmp/man/man2/ioctl_pagemap_scan.2.cat.set'
>
>> +Page has async-write-protection enabled
>
> Here and below:
> s/Page/The page/
>
>> +.TP
>> +.BR PAGE_IS_WRITTEN
>> +Page has been written to from the time it was write protected
>> +.TP
>> +.BR PAGE_IS_FILE
>> +Page is file backed
>> +.TP
>> +.BR PAGE_IS_PRESENT
>> +Page is present in the memory
>> +.TP
>> +.BR PAGE_IS_SWAPPED
>> +Page is in swapped
>> +.TP
>> +.BR PAGE_IS_PFNZERO
>> +Page has zero PFN
>> +.TP
>> +.BR PAGE_IS_HUGE
>> +Page is THP or Hugetlb backed
>> +
>
> s/^$/./
>
>> +.SS Supported Operations
>
> I think s/Operations/operations/
>
>> +The get operation is always performed if the output buffer is specified. The other operations are as following:
>
> Please use semantic newlines. Input lines should never go past column
> 80, except for very good reasons.
>
> $ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
> Use semantic newlines
> In the source of a manual page, new sentences should be started
> on new lines, long sentences should be split into lines at
> clause breaks (commas, semicolons, colons, and so on), and long
> clauses should be split at phrase boundaries. This convention,
> sometimes known as "semantic newlines", makes it easier to see
> the effect of patches, which often operate at the level of in‐
> dividual sentences, clauses, or phrases.
>
> Also, see this warning:
>
> $ make lint build check --debug=print
> LINT (mandoc) .tmp/man/man2/ioctl_pagemap_scan.2.lint-man.mandoc.touch
> ! (mandoc -man -Tlint man2/ioctl_pagemap_scan.2 2>&1 \
> | grep -v -f './share/lint/mandoc/man.ignore.grep' \
> ||:; \
> ) \
> | grep ^ >&2
> mandoc: man2/ioctl_pagemap_scan.2:51:111: STYLE: input text line longer than 80 bytes: The get operation is...
> mandoc: man2/ioctl_pagemap_scan.2:57:93: STYLE: input text line longer than 80 bytes: Abort the scan when ...
> mandoc: man2/ioctl_pagemap_scan.2:60:2: WARNING: skipping paragraph macro: PP after SS
> make: *** [share/mk/lint/man/man.mk:32: .tmp/man/man2/ioctl_pagemap_scan.2.lint-man.mandoc.touch] Error 1
>
>> +.TP
>> +.BR PM_SCAN_WP_MATCHING
>> +Write protect the matched pages
>> +.TP
>> +.BR PM_SCAN_CHECK_WPASYNC
>> +Abort the scan when a page which isn't registered with Userfaultfd Asynchronous Write protect
>
> Semantic newlines.
>
>> +
>
> s/^$/./
>
>> +.SS The struct pm_scan_arg Argument
>
> Types should go in italics. To do this inside SH or SS, do:
>
> .SS The \f[I]struct pm_scan_arg\f[] Argument.
>
> Also, why Argument and not argument?
>
>> +.PP
>
> This .PP is redundant.
>
> $ make lint build check --debug=print
> LINT (mandoc) .tmp/man/man2/ioctl_pagemap_scan.2.lint-man.mandoc.touch
> ! (mandoc -man -Tlint man2/ioctl_pagemap_scan.2 2>&1 \
> | grep -v -f './share/lint/mandoc/man.ignore.grep' \
> ||:; \
> ) \
> | grep ^ >&2
> mandoc: man2/ioctl_pagemap_scan.2:51:111: STYLE: input text line longer than 80 bytes: The get operation is...
> mandoc: man2/ioctl_pagemap_scan.2:57:93: STYLE: input text line longer than 80 bytes: Abort the scan when ...
> mandoc: man2/ioctl_pagemap_scan.2:60:2: WARNING: skipping paragraph macro: PP after SS
> make: *** [share/mk/lint/man/man.mk:32: .tmp/man/man2/ioctl_pagemap_scan.2.lint-man.mandoc.touch] Error 1
>
>> +.in
>> +.EX
>> +struct pm_scan_arg {
>> + __u64 size;
>> + __u64 flags;
>> + __u64 start;
>> + __u64 end;
>> + __u64 walk_end;
>> + __u64 vec;
>> + __u64 vec_len;
>> + __u64 max_pages
>> + __u64 category_inverted;
>> + __u64 category_mask;
>> + __u64 category_anyof_mask
>> + __u64 return_mask;
>> +};
>> +.EE
>> +.in
>> +
>
> This blank line makes no sense.
>
>> +.TP
>> +.BR size
>> +The size of
>> +.I arg
>> +is specified in it. It'll help in future if extension is make to
>
> Semantic newlines.
>
> Also, I have a hard time understanding the second sentence.
> You may want to check the wording used in other pages for structures
> where the size is kind of a version marker.
>
>> +.I struct pm_scan_arg
>> +in future.
>> +.TP
>> +.BR flags
>> +The operations to be performed are specified in it.
>> +.TP
>> +.BR start
>> +The starting address of the scan is specified in it.
>> +.TP
>> +.BR end
>> +The ending address of the scan is specified in it.
>> +.TP
>> +.BR walk_end
>> +The kernel returns the scan's ending address in it. The
>
> Semantic newlines.
>
>> +.IR walk_end
>> +equal to
>> +.IR end
>> +means that scan has completed on the entire range.
>> +.TP
>> +.BR vec
>> +The address of
>> +.IR page_region
>> +array for output
>> +.PP
>> +.in +8n
>> +.EX
>> +struct page_region {
>> + __u64 start;
>> + __u64 end;
>> + __u64 categories;
>> +};
>> +.EE
>> +.in
>> +.TP
>> +.BR vec_len
>> +The length of the
>> +.IR page_region
>
> Similarly, this should be I, not IR.
>
>> +struct array
>> +.TP
>> +.BR max_pages
>> +Optional limit for number of output pages
>> +.TP
>> +.BR category_inverted
>> +PAGE_IS_* categories which values match if 0 instead of 1
>
> PAGE_IS_* should probably be in mixed bold/italics:
>
> .BI PAGE_IS_ *
>
> See groff_man_stlye(7):
>
> Use bold for ...
> ..., and for literals
> that are major topics of the subject under discussion;
> for example, this page uses bold for macro, string, and
> register names. In an .EX/.EE example of interactive
> I/O (such as a shell session), set only user input in
> bold.
>
> Use italics for ...
> ..., and anywhere a parameter requiring replacement
> by the user is encountered. ...
>
>
>
>> +.TP
>> +.BR category_mask
>> +Skip pages for which any category doesn't match
>> +.TP
>> +.BR category_anyof_mask
>> +Skip pages for which no category matches
>> +.TP
>> +.BR return_mask
>> +Page categories that are to be reported in
>> +.IR page_region
>> +
>
> s/^$/./
>
>> +.SH RETURN VALUE
>> +On error, \-1 is returned, and
>> +.I errno
>> +is set to indicate the error.
>> +.SH ERRORS
>> +Error codes can be one of, but are not limited to, the following:
>> +.TP
>> +.B EINVAL
>> +Invalid arguments i.e., invalid
>> +.I size
>> +of the argument, invalid
>> +.I flags
>> +, invalid
>> +.I categories
>> +, the
>> +.I start
>> +address isn't aligned with
>> +.BR PAGE_SIZE
>> +or
>> +.I vec_len
>> +is specified when
>> +.I vec
>> +is
>> +.BR NULL.
>> +.TP
>> +.B EFAULT
>> +Invalid
>> +.I arg
>> +pointer, invalid
>> +.I vec
>> +pointer or invalid address range specified by
>> +.I start
>> +and
>> +.I end
>> +.TP
>> +.B ENOMEM
>> +No memory is available
>> +.TP
>> +.B EINTR
>> +Fetal signal pending
>> +.SH STANDARDS
>> +Linux.
>
> Please add a HISTORY section indicating at least the Linux version where
> it was (will be) introduced.
>
> Also, it would probably be useful to add an EXAMPLES section with a
> small example of use.
>
> Thanks,
> Alex
>
>> +.SH SEE ALSO
>> +.BR ioctl (2)
>> --
>> 2.40.1
>>
>
--
BR,
Muhammad Usama Anjum
^ permalink raw reply [flat|nested] 18+ messages in thread
* Re: [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL
2023-10-17 15:01 ` [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL Muhammad Usama Anjum
@ 2023-10-17 17:12 ` Alejandro Colomar
2023-10-19 12:31 ` Muhammad Usama Anjum
0 siblings, 1 reply; 18+ messages in thread
From: Alejandro Colomar @ 2023-10-17 17:12 UTC (permalink / raw)
To: Muhammad Usama Anjum; +Cc: kernel, linux-man
[-- Attachment #1: Type: text/plain, Size: 12824 bytes --]
Hi Muhammad,
On Tue, Oct 17, 2023 at 08:01:32PM +0500, Muhammad Usama Anjum wrote:
> Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
Please link to the discussion where this feature is being discussed, in
case someone needs to review it in the future.
> ---
> man2/ioctl_pagemap_scan.2 | 183 ++++++++++++++++++++++++++++++++++++++
> 1 file changed, 183 insertions(+)
> create mode 100644 man2/ioctl_pagemap_scan.2
>
> diff --git a/man2/ioctl_pagemap_scan.2 b/man2/ioctl_pagemap_scan.2
> new file mode 100644
> index 000000000..4e096028d
> --- /dev/null
> +++ b/man2/ioctl_pagemap_scan.2
> @@ -0,0 +1,183 @@
> +.\" This manpage is Copyright (C) 2023 Collabora;
> +.\" Written by Muhammad Usama Anjum <usama.anjum@collabora.com>
> +.\"
> +.\" SPDX-License-Identifier: Linux-man-pages-copyleft
> +.\"
> +.\" Commit 84ceddb3c2b0c280936f28f450d65f46cb7411c6
> +.\"
> +.TH ioctl_pagemap_scan 2 2023-10-17 "Linux man-pages (unreleased)"
> +.SH NAME
> +ioctl_pagemap_scan \- get and/or clear page flags
> +.SH LIBRARY
> +Standard C library
> +.RI ( libc ", " \-lc )
> +.SH SYNOPSIS
> +.nf
> +.BR "#include <linux/fs.h>" " /* Definition of " struct " " pm_scan_arg ", " struct " " page_region " and " PAGE_IS_* " constants */"
Please split the comment into several lines, so that the manual page can
be read in an 80-column terminal without wrapping lines.
> +.B #include <sys/ioctl.h>
> +.PP
> +.BI "int ioctl(int " pagemap_fd ", PAGEMAP_SCAN, struct pm_scan_arg *" arg );
> +.fi
> +.SH DESCRIPTION
> +This
> +.BR ioctl (2)
> +is used to get and optionally clear some specific flags from page table entries.
> +
Please use an empty roff(7) request instead of a empty input line. That
is, use a line with just a '.', that is, s/^$/./
$ make lint build check --debug=print
TROFF .tmp/man/man2/ioctl_pagemap_scan.2.cat.set
! (troff -wbreak -man -Tutf8 -rLL=78n -rCHECKSTYLE=3 -ww <.tmp/man/man2/ioctl_pagemap_scan.2.cat.troff 2>&1 >.tmp/man/man2/ioctl_pagemap_scan.2.cat.set \
| grep -v -f './share/lint/groff/man.ignore.grep' \
||:; \
) \
| grep ^ >&2
an.tmac:man2/ioctl_pagemap_scan.2:25: style: blank line in input
...
> +.SS Supported page flags
> +The following page table entry flags are support:
s/support/supported/
> +.TP
> +.BR PAGE_IS_WPALLOWED
'.BR' is wrong here (it alternates bold and roman). It should be '.B',
which is just bold. You can check groff_man(7) and groff_man_style(7).
See these warnings:
$ make lint build check --debug=print
TROFF .tmp/man/man2/ioctl_pagemap_scan.2.cat.set
! (troff -wbreak -man -Tutf8 -rLL=78n -rCHECKSTYLE=3 -ww <.tmp/man/man2/ioctl_pagemap_scan.2.cat.troff 2>&1 >.tmp/man/man2/ioctl_pagemap_scan.2.cat.set \
| grep -v -f './share/lint/groff/man.ignore.grep' \
||:; \
) \
| grep ^ >&2
an.tmac:man2/ioctl_pagemap_scan.2:25: style: blank line in input
an.tmac:man2/ioctl_pagemap_scan.2:29: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:32: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:35: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:38: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:41: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:44: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:47: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:49: style: blank line in input
an.tmac:man2/ioctl_pagemap_scan.2:53: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:56: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:58: style: blank line in input
an.tmac:man2/ioctl_pagemap_scan.2:79: style: blank line in input
an.tmac:man2/ioctl_pagemap_scan.2:81: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:88: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:91: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:94: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:97: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:99: style: .IR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:101: style: .IR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:104: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:106: style: .IR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:119: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:121: style: .IR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:124: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:127: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:130: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:133: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:136: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:138: style: .IR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:139: style: blank line in input
an.tmac:man2/ioctl_pagemap_scan.2:157: style: .BR expects at least 2 arguments, got 1
an.tmac:man2/ioctl_pagemap_scan.2:163: style: .BR expects at least 2 arguments, got 1
make: *** [share/mk/build/catman.mk:54: .tmp/man/man2/ioctl_pagemap_scan.2.cat.set] Error 1
make: *** Deleting file '.tmp/man/man2/ioctl_pagemap_scan.2.cat.set'
> +Page has async-write-protection enabled
Here and below:
s/Page/The page/
> +.TP
> +.BR PAGE_IS_WRITTEN
> +Page has been written to from the time it was write protected
> +.TP
> +.BR PAGE_IS_FILE
> +Page is file backed
> +.TP
> +.BR PAGE_IS_PRESENT
> +Page is present in the memory
> +.TP
> +.BR PAGE_IS_SWAPPED
> +Page is in swapped
> +.TP
> +.BR PAGE_IS_PFNZERO
> +Page has zero PFN
> +.TP
> +.BR PAGE_IS_HUGE
> +Page is THP or Hugetlb backed
> +
s/^$/./
> +.SS Supported Operations
I think s/Operations/operations/
> +The get operation is always performed if the output buffer is specified. The other operations are as following:
Please use semantic newlines. Input lines should never go past column
80, except for very good reasons.
$ MANWIDTH=72 man man-pages | sed -n '/Use semantic newlines/,/^$/p'
Use semantic newlines
In the source of a manual page, new sentences should be started
on new lines, long sentences should be split into lines at
clause breaks (commas, semicolons, colons, and so on), and long
clauses should be split at phrase boundaries. This convention,
sometimes known as "semantic newlines", makes it easier to see
the effect of patches, which often operate at the level of in‐
dividual sentences, clauses, or phrases.
Also, see this warning:
$ make lint build check --debug=print
LINT (mandoc) .tmp/man/man2/ioctl_pagemap_scan.2.lint-man.mandoc.touch
! (mandoc -man -Tlint man2/ioctl_pagemap_scan.2 2>&1 \
| grep -v -f './share/lint/mandoc/man.ignore.grep' \
||:; \
) \
| grep ^ >&2
mandoc: man2/ioctl_pagemap_scan.2:51:111: STYLE: input text line longer than 80 bytes: The get operation is...
mandoc: man2/ioctl_pagemap_scan.2:57:93: STYLE: input text line longer than 80 bytes: Abort the scan when ...
mandoc: man2/ioctl_pagemap_scan.2:60:2: WARNING: skipping paragraph macro: PP after SS
make: *** [share/mk/lint/man/man.mk:32: .tmp/man/man2/ioctl_pagemap_scan.2.lint-man.mandoc.touch] Error 1
> +.TP
> +.BR PM_SCAN_WP_MATCHING
> +Write protect the matched pages
> +.TP
> +.BR PM_SCAN_CHECK_WPASYNC
> +Abort the scan when a page which isn't registered with Userfaultfd Asynchronous Write protect
Semantic newlines.
> +
s/^$/./
> +.SS The struct pm_scan_arg Argument
Types should go in italics. To do this inside SH or SS, do:
.SS The \f[I]struct pm_scan_arg\f[] Argument.
Also, why Argument and not argument?
> +.PP
This .PP is redundant.
$ make lint build check --debug=print
LINT (mandoc) .tmp/man/man2/ioctl_pagemap_scan.2.lint-man.mandoc.touch
! (mandoc -man -Tlint man2/ioctl_pagemap_scan.2 2>&1 \
| grep -v -f './share/lint/mandoc/man.ignore.grep' \
||:; \
) \
| grep ^ >&2
mandoc: man2/ioctl_pagemap_scan.2:51:111: STYLE: input text line longer than 80 bytes: The get operation is...
mandoc: man2/ioctl_pagemap_scan.2:57:93: STYLE: input text line longer than 80 bytes: Abort the scan when ...
mandoc: man2/ioctl_pagemap_scan.2:60:2: WARNING: skipping paragraph macro: PP after SS
make: *** [share/mk/lint/man/man.mk:32: .tmp/man/man2/ioctl_pagemap_scan.2.lint-man.mandoc.touch] Error 1
> +.in
> +.EX
> +struct pm_scan_arg {
> + __u64 size;
> + __u64 flags;
> + __u64 start;
> + __u64 end;
> + __u64 walk_end;
> + __u64 vec;
> + __u64 vec_len;
> + __u64 max_pages
> + __u64 category_inverted;
> + __u64 category_mask;
> + __u64 category_anyof_mask
> + __u64 return_mask;
> +};
> +.EE
> +.in
> +
This blank line makes no sense.
> +.TP
> +.BR size
> +The size of
> +.I arg
> +is specified in it. It'll help in future if extension is make to
Semantic newlines.
Also, I have a hard time understanding the second sentence.
You may want to check the wording used in other pages for structures
where the size is kind of a version marker.
> +.I struct pm_scan_arg
> +in future.
> +.TP
> +.BR flags
> +The operations to be performed are specified in it.
> +.TP
> +.BR start
> +The starting address of the scan is specified in it.
> +.TP
> +.BR end
> +The ending address of the scan is specified in it.
> +.TP
> +.BR walk_end
> +The kernel returns the scan's ending address in it. The
Semantic newlines.
> +.IR walk_end
> +equal to
> +.IR end
> +means that scan has completed on the entire range.
> +.TP
> +.BR vec
> +The address of
> +.IR page_region
> +array for output
> +.PP
> +.in +8n
> +.EX
> +struct page_region {
> + __u64 start;
> + __u64 end;
> + __u64 categories;
> +};
> +.EE
> +.in
> +.TP
> +.BR vec_len
> +The length of the
> +.IR page_region
Similarly, this should be I, not IR.
> +struct array
> +.TP
> +.BR max_pages
> +Optional limit for number of output pages
> +.TP
> +.BR category_inverted
> +PAGE_IS_* categories which values match if 0 instead of 1
PAGE_IS_* should probably be in mixed bold/italics:
.BI PAGE_IS_ *
See groff_man_stlye(7):
Use bold for ...
..., and for literals
that are major topics of the subject under discussion;
for example, this page uses bold for macro, string, and
register names. In an .EX/.EE example of interactive
I/O (such as a shell session), set only user input in
bold.
Use italics for ...
..., and anywhere a parameter requiring replacement
by the user is encountered. ...
> +.TP
> +.BR category_mask
> +Skip pages for which any category doesn't match
> +.TP
> +.BR category_anyof_mask
> +Skip pages for which no category matches
> +.TP
> +.BR return_mask
> +Page categories that are to be reported in
> +.IR page_region
> +
s/^$/./
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EINVAL
> +Invalid arguments i.e., invalid
> +.I size
> +of the argument, invalid
> +.I flags
> +, invalid
> +.I categories
> +, the
> +.I start
> +address isn't aligned with
> +.BR PAGE_SIZE
> +or
> +.I vec_len
> +is specified when
> +.I vec
> +is
> +.BR NULL.
> +.TP
> +.B EFAULT
> +Invalid
> +.I arg
> +pointer, invalid
> +.I vec
> +pointer or invalid address range specified by
> +.I start
> +and
> +.I end
> +.TP
> +.B ENOMEM
> +No memory is available
> +.TP
> +.B EINTR
> +Fetal signal pending
> +.SH STANDARDS
> +Linux.
Please add a HISTORY section indicating at least the Linux version where
it was (will be) introduced.
Also, it would probably be useful to add an EXAMPLES section with a
small example of use.
Thanks,
Alex
> +.SH SEE ALSO
> +.BR ioctl (2)
> --
> 2.40.1
>
--
<https://www.alejandro-colomar.es/>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 18+ messages in thread
* [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL
2023-10-17 15:01 Muhammad Usama Anjum
@ 2023-10-17 15:01 ` Muhammad Usama Anjum
2023-10-17 17:12 ` Alejandro Colomar
0 siblings, 1 reply; 18+ messages in thread
From: Muhammad Usama Anjum @ 2023-10-17 15:01 UTC (permalink / raw)
To: alx; +Cc: Muhammad Usama Anjum, kernel, linux-man
Signed-off-by: Muhammad Usama Anjum <usama.anjum@collabora.com>
---
man2/ioctl_pagemap_scan.2 | 183 ++++++++++++++++++++++++++++++++++++++
1 file changed, 183 insertions(+)
create mode 100644 man2/ioctl_pagemap_scan.2
diff --git a/man2/ioctl_pagemap_scan.2 b/man2/ioctl_pagemap_scan.2
new file mode 100644
index 000000000..4e096028d
--- /dev/null
+++ b/man2/ioctl_pagemap_scan.2
@@ -0,0 +1,183 @@
+.\" This manpage is Copyright (C) 2023 Collabora;
+.\" Written by Muhammad Usama Anjum <usama.anjum@collabora.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" Commit 84ceddb3c2b0c280936f28f450d65f46cb7411c6
+.\"
+.TH ioctl_pagemap_scan 2 2023-10-17 "Linux man-pages (unreleased)"
+.SH NAME
+ioctl_pagemap_scan \- get and/or clear page flags
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/fs.h>" " /* Definition of " struct " " pm_scan_arg ", " struct " " page_region " and " PAGE_IS_* " constants */"
+.B #include <sys/ioctl.h>
+.PP
+.BI "int ioctl(int " pagemap_fd ", PAGEMAP_SCAN, struct pm_scan_arg *" arg );
+.fi
+.SH DESCRIPTION
+This
+.BR ioctl (2)
+is used to get and optionally clear some specific flags from page table entries.
+
+.SS Supported page flags
+The following page table entry flags are support:
+.TP
+.BR PAGE_IS_WPALLOWED
+Page has async-write-protection enabled
+.TP
+.BR PAGE_IS_WRITTEN
+Page has been written to from the time it was write protected
+.TP
+.BR PAGE_IS_FILE
+Page is file backed
+.TP
+.BR PAGE_IS_PRESENT
+Page is present in the memory
+.TP
+.BR PAGE_IS_SWAPPED
+Page is in swapped
+.TP
+.BR PAGE_IS_PFNZERO
+Page has zero PFN
+.TP
+.BR PAGE_IS_HUGE
+Page is THP or Hugetlb backed
+
+.SS Supported Operations
+The get operation is always performed if the output buffer is specified. The other operations are as following:
+.TP
+.BR PM_SCAN_WP_MATCHING
+Write protect the matched pages
+.TP
+.BR PM_SCAN_CHECK_WPASYNC
+Abort the scan when a page which isn't registered with Userfaultfd Asynchronous Write protect
+
+.SS The struct pm_scan_arg Argument
+.PP
+.in
+.EX
+struct pm_scan_arg {
+ __u64 size;
+ __u64 flags;
+ __u64 start;
+ __u64 end;
+ __u64 walk_end;
+ __u64 vec;
+ __u64 vec_len;
+ __u64 max_pages
+ __u64 category_inverted;
+ __u64 category_mask;
+ __u64 category_anyof_mask
+ __u64 return_mask;
+};
+.EE
+.in
+
+.TP
+.BR size
+The size of
+.I arg
+is specified in it. It'll help in future if extension is make to
+.I struct pm_scan_arg
+in future.
+.TP
+.BR flags
+The operations to be performed are specified in it.
+.TP
+.BR start
+The starting address of the scan is specified in it.
+.TP
+.BR end
+The ending address of the scan is specified in it.
+.TP
+.BR walk_end
+The kernel returns the scan's ending address in it. The
+.IR walk_end
+equal to
+.IR end
+means that scan has completed on the entire range.
+.TP
+.BR vec
+The address of
+.IR page_region
+array for output
+.PP
+.in +8n
+.EX
+struct page_region {
+ __u64 start;
+ __u64 end;
+ __u64 categories;
+};
+.EE
+.in
+.TP
+.BR vec_len
+The length of the
+.IR page_region
+struct array
+.TP
+.BR max_pages
+Optional limit for number of output pages
+.TP
+.BR category_inverted
+PAGE_IS_* categories which values match if 0 instead of 1
+.TP
+.BR category_mask
+Skip pages for which any category doesn't match
+.TP
+.BR category_anyof_mask
+Skip pages for which no category matches
+.TP
+.BR return_mask
+Page categories that are to be reported in
+.IR page_region
+
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EINVAL
+Invalid arguments i.e., invalid
+.I size
+of the argument, invalid
+.I flags
+, invalid
+.I categories
+, the
+.I start
+address isn't aligned with
+.BR PAGE_SIZE
+or
+.I vec_len
+is specified when
+.I vec
+is
+.BR NULL.
+.TP
+.B EFAULT
+Invalid
+.I arg
+pointer, invalid
+.I vec
+pointer or invalid address range specified by
+.I start
+and
+.I end
+.TP
+.B ENOMEM
+No memory is available
+.TP
+.B EINTR
+Fetal signal pending
+.SH STANDARDS
+Linux.
+.SH SEE ALSO
+.BR ioctl (2)
--
2.40.1
^ permalink raw reply related [flat|nested] 18+ messages in thread
end of thread, other threads:[~2023-10-29 0:42 UTC | newest]
Thread overview: 18+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-10-19 13:12 [PATCH 1/2] ioctl_userfaultfd.2: add UFFD_FEATURE_WP_ASYNC Muhammad Usama Anjum
2023-10-19 13:12 ` [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL Muhammad Usama Anjum
2023-10-23 21:52 ` Alejandro Colomar
2023-10-24 2:48 ` G. Branden Robinson
2023-10-24 10:40 ` Alejandro Colomar
2023-10-28 13:07 ` managing tagged paragraphs (was: [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL) G. Branden Robinson
2023-10-28 16:22 ` Alejandro Colomar
2023-10-28 18:07 ` G. Branden Robinson
2023-10-29 0:42 ` Alejandro Colomar
2023-10-24 15:51 ` [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL Muhammad Usama Anjum
2023-10-19 13:27 ` [PATCH 1/2] ioctl_userfaultfd.2: add UFFD_FEATURE_WP_ASYNC Alejandro Colomar
2023-10-19 13:29 ` Alejandro Colomar
2023-10-19 13:34 ` Muhammad Usama Anjum
2023-10-19 13:42 ` Alejandro Colomar
-- strict thread matches above, loose matches on Subject: below --
2023-10-17 15:01 Muhammad Usama Anjum
2023-10-17 15:01 ` [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL Muhammad Usama Anjum
2023-10-17 17:12 ` Alejandro Colomar
2023-10-19 12:31 ` Muhammad Usama Anjum
2023-10-19 12:51 ` Alejandro Colomar
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.