[PATCH] prctl.2: doc PR_SET/GET_IO_FLUSHER - V4

[PATCH] prctl.2: doc PR_SET/GET_IO_FLUSHER - V4

[Mike Christie]

This patch documents the PR_SET_IO_FLUSHER and PR_GET_IO_FLUSHER
prctl commands added to the linux kernel for 5.6 in commit:

commit 8d19f1c8e1937baf74e1962aae9f90fa3aeab463
Author: Mike Christie <mchristi@redhat.com>
Date:   Mon Nov 11 18:19:00 2019 -0600

    prctl: PR_{G,S}ET_IO_FLUSHER to support controlling memory reclaim

Signed-off-by: Mike Christie <mchristi@redhat.com>
---

V4:
- Remove internal details.
- Add CAP_SYS_RESOURCE requirement info.

V3:
- Replace emulation device example.

V2:
- My initial patch for this was very bad. This version is almost 100%
taken word for word from Dave Chinner's review comments.

Signed-off-by: Mike Christie <mchristi@redhat.com>

 man2/prctl.2 | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 720ec04e4..3c3355439 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -1381,6 +1381,31 @@ system call on Tru64).
 for information on versions and architectures.)
 Return unaligned access control bits, in the location pointed to by
 .IR "(unsigned int\ *) arg2" .
+.TP
+.B PR_SET_IO_FLUSHER (Since Linux 5.6)
+If a user process is involved in the block layer or file system IO path,
+and can allocate memory while processing IO requests it must set
+\fIarg2\fP to 1. This will put the process in the IO_FLUSHER state which
+allows it special treatment to make progress when allocating memory.
+If \fIarg2\fP is 0, the process will clear the IO_FLUSHER state, and
+the default behavior will be used.
+
+The calling process must have the
+.BR CAP_SYS_RESOURCE
+capability.
+
+Examples of IO_FLUSHER applications are FUSE daemons, SCSI device
+emulation daemons, and daemons that perform error handling like multipath
+path recovery applications.
+
+.TP
+.B PR_GET_IO_FLUSHER (Since Linux 5.6)
+Return as the function result 1 if the caller is in the IO_FLUSHER state and
+0 if not.
+
+The calling process must have the
+.BR CAP_SYS_RESOURCE
+capability.
 .SH RETURN VALUE
 On success,
 .BR PR_GET_DUMPABLE ,
@@ -1395,6 +1420,7 @@ On success,
 .BR PR_GET_SPECULATION_CTRL ,
 .BR PR_MCE_KILL_GET ,
 .BR PR_CAP_AMBIENT + PR_CAP_AMBIENT_IS_SET ,
+.BR PR_GET_IO_FLUSHER ,
 and (if it returns)
 .BR PR_GET_SECCOMP
 return the nonnegative values described above.
-- 
2.21.0

Re: [PATCH] prctl.2: doc PR_SET/GET_IO_FLUSHER - V4

[Bart Van Assche]

On 2020-04-01 19:08, Mike Christie wrote:
> +.TP
> +.B PR_GET_IO_FLUSHER (Since Linux 5.6)
> +Return as the function result 1 if the caller is in the IO_FLUSHER state and
> +0 if not.

Although I'm not at all a language expert, the word order at the start
of the above sentence seems a bit weird to me?

Thanks,

Bart.

Re: [PATCH] prctl.2: doc PR_SET/GET_IO_FLUSHER - V4

[Michal Hocko]

On Wed 01-04-20 21:08:50, Mike Christie wrote:
> This patch documents the PR_SET_IO_FLUSHER and PR_GET_IO_FLUSHER
> prctl commands added to the linux kernel for 5.6 in commit:
> 
> commit 8d19f1c8e1937baf74e1962aae9f90fa3aeab463
> Author: Mike Christie <mchristi@redhat.com>
> Date:   Mon Nov 11 18:19:00 2019 -0600
> 
>     prctl: PR_{G,S}ET_IO_FLUSHER to support controlling memory reclaim
> 
> Signed-off-by: Mike Christie <mchristi@redhat.com>

Yes this wording is much better than the previous version.

Acked-by: Michal Hocko <mhocko@suse.com>

> ---
> 
> V4:
> - Remove internal details.
> - Add CAP_SYS_RESOURCE requirement info.
> 
> V3:
> - Replace emulation device example.
> 
> V2:
> - My initial patch for this was very bad. This version is almost 100%
> taken word for word from Dave Chinner's review comments.
> 
> Signed-off-by: Mike Christie <mchristi@redhat.com>
> 
>  man2/prctl.2 | 26 ++++++++++++++++++++++++++
>  1 file changed, 26 insertions(+)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 720ec04e4..3c3355439 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -1381,6 +1381,31 @@ system call on Tru64).
>  for information on versions and architectures.)
>  Return unaligned access control bits, in the location pointed to by
>  .IR "(unsigned int\ *) arg2" .
> +.TP
> +.B PR_SET_IO_FLUSHER (Since Linux 5.6)
> +If a user process is involved in the block layer or file system IO path,
> +and can allocate memory while processing IO requests it must set
> +\fIarg2\fP to 1. This will put the process in the IO_FLUSHER state which
> +allows it special treatment to make progress when allocating memory.
> +If \fIarg2\fP is 0, the process will clear the IO_FLUSHER state, and
> +the default behavior will be used.
> +
> +The calling process must have the
> +.BR CAP_SYS_RESOURCE
> +capability.
> +
> +Examples of IO_FLUSHER applications are FUSE daemons, SCSI device
> +emulation daemons, and daemons that perform error handling like multipath
> +path recovery applications.
> +
> +.TP
> +.B PR_GET_IO_FLUSHER (Since Linux 5.6)
> +Return as the function result 1 if the caller is in the IO_FLUSHER state and
> +0 if not.
> +
> +The calling process must have the
> +.BR CAP_SYS_RESOURCE
> +capability.
>  .SH RETURN VALUE
>  On success,
>  .BR PR_GET_DUMPABLE ,
> @@ -1395,6 +1420,7 @@ On success,
>  .BR PR_GET_SPECULATION_CTRL ,
>  .BR PR_MCE_KILL_GET ,
>  .BR PR_CAP_AMBIENT + PR_CAP_AMBIENT_IS_SET ,
> +.BR PR_GET_IO_FLUSHER ,
>  and (if it returns)
>  .BR PR_GET_SECCOMP
>  return the nonnegative values described above.
> -- 
> 2.21.0

-- 
Michal Hocko
SUSE Labs

Re: [PATCH] prctl.2: doc PR_SET/GET_IO_FLUSHER - V4

[Michael Kerrisk (man-pages)]

Hello Mike,

On 4/2/20 4:08 AM, Mike Christie wrote:
> This patch documents the PR_SET_IO_FLUSHER and PR_GET_IO_FLUSHER
> prctl commands added to the linux kernel for 5.6 in commit:
> 
> commit 8d19f1c8e1937baf74e1962aae9f90fa3aeab463
> Author: Mike Christie <mchristi@redhat.com>
> Date:   Mon Nov 11 18:19:00 2019 -0600> 
>     prctl: PR_{G,S}ET_IO_FLUSHER to support controlling memory reclaim
> 
> Signed-off-by: Mike Christie <mchristi@redhat.com>

I've applied this patch, but I have some questions:

(a) What happens to the IO_FLUSHER setting in the child of fork(2)?
(b) What happens to the IO_FLUSHER setting during an execve(2)?
    (Is it preserved, reset, something else?)

Thanks,

Michael

> ---
> 
> V4:
> - Remove internal details.
> - Add CAP_SYS_RESOURCE requirement info.
> 
> V3:
> - Replace emulation device example.
> 
> V2:
> - My initial patch for this was very bad. This version is almost 100%
> taken word for word from Dave Chinner's review comments.
> 
> Signed-off-by: Mike Christie <mchristi@redhat.com>
> 
>  man2/prctl.2 | 26 ++++++++++++++++++++++++++
>  1 file changed, 26 insertions(+)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 720ec04e4..3c3355439 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -1381,6 +1381,31 @@ system call on Tru64).
>  for information on versions and architectures.)
>  Return unaligned access control bits, in the location pointed to by
>  .IR "(unsigned int\ *) arg2" .
> +.TP
> +.B PR_SET_IO_FLUSHER (Since Linux 5.6)
> +If a user process is involved in the block layer or file system IO path,
> +and can allocate memory while processing IO requests it must set
> +\fIarg2\fP to 1. This will put the process in the IO_FLUSHER state which
> +allows it special treatment to make progress when allocating memory.
> +If \fIarg2\fP is 0, the process will clear the IO_FLUSHER state, and
> +the default behavior will be used.
> +
> +The calling process must have the
> +.BR CAP_SYS_RESOURCE
> +capability.
> +
> +Examples of IO_FLUSHER applications are FUSE daemons, SCSI device
> +emulation daemons, and daemons that perform error handling like multipath
> +path recovery applications.
> +
> +.TP
> +.B PR_GET_IO_FLUSHER (Since Linux 5.6)
> +Return as the function result 1 if the caller is in the IO_FLUSHER state and
> +0 if not.
> +
> +The calling process must have the
> +.BR CAP_SYS_RESOURCE
> +capability.
>  .SH RETURN VALUE
>  On success,
>  .BR PR_GET_DUMPABLE ,
> @@ -1395,6 +1420,7 @@ On success,
>  .BR PR_GET_SPECULATION_CTRL ,
>  .BR PR_MCE_KILL_GET ,
>  .BR PR_CAP_AMBIENT + PR_CAP_AMBIENT_IS_SET ,
> +.BR PR_GET_IO_FLUSHER ,
>  and (if it returns)
>  .BR PR_GET_SECCOMP
>  return the nonnegative values described above.
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH] prctl.2: doc PR_SET/GET_IO_FLUSHER - V4

[Michael Kerrisk (man-pages)]

On 4/2/20 5:46 AM, Bart Van Assche wrote:
> On 2020-04-01 19:08, Mike Christie wrote:
>> +.TP
>> +.B PR_GET_IO_FLUSHER (Since Linux 5.6)
>> +Return as the function result 1 if the caller is in the IO_FLUSHER state and
>> +0 if not.
> 
> Although I'm not at all a language expert, the word order at the start
> of the above sentence seems a bit weird to me?

Thanks for spotting that Bart. I changed the text to:

              If a user  process  is  involved  in  the  block  layer  or
              filesystem I/O path, and can allocate memory while process‐
              ing I/O requests it must set arg2 to 1.  This will put  the
              process  in  the  IO_FLUSHER state, which allows it special
              treatment to make progress when allocating memory.  If arg2
              is  0, the process will clear the IO_FLUSHER state, and the
              default behavior will be used.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH] prctl.2: doc PR_SET/GET_IO_FLUSHER - V4

[Michael Kerrisk (man-pages)]

On 4/2/20 8:47 AM, Michal Hocko wrote:
> On Wed 01-04-20 21:08:50, Mike Christie wrote:
>> This patch documents the PR_SET_IO_FLUSHER and PR_GET_IO_FLUSHER
>> prctl commands added to the linux kernel for 5.6 in commit:
>>
>> commit 8d19f1c8e1937baf74e1962aae9f90fa3aeab463
>> Author: Mike Christie <mchristi@redhat.com>
>> Date:   Mon Nov 11 18:19:00 2019 -0600
>>
>>     prctl: PR_{G,S}ET_IO_FLUSHER to support controlling memory reclaim
>>
>> Signed-off-by: Mike Christie <mchristi@redhat.com>
> 
> Yes this wording is much better than the previous version.
> 
> Acked-by: Michal Hocko <mhocko@suse.com>

Thanks for the review, Michal!

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH] prctl.2: doc PR_SET/GET_IO_FLUSHER - V4

[Michael Christie]

On 04/01/2020 10:46 PM, Bart Van Assche wrote:
> On 2020-04-01 19:08, Mike Christie wrote:
>> +.TP
>> +.B PR_GET_IO_FLUSHER (Since Linux 5.6)
>> +Return as the function result 1 if the caller is in the IO_FLUSHER state and
>> +0 if not.
> 
> Although I'm not at all a language expert, the word order at the start
> of the above sentence seems a bit weird to me?
> 

Do you mean the "Return as the function result" part or something else?

That is how the other commands worded it. It looks like I messed up and
dropped the (). This is how they did it:

"Return (as the function result)"

I will resend with that fix.

If I misunderstood you I will fix that too.

Re: [PATCH] prctl.2: doc PR_SET/GET_IO_FLUSHER - V4

[Michael Kerrisk (man-pages)]

On Thu, 2 Apr 2020 at 16:01, Michael Christie <mchristi@redhat.com> wrote:
>
> On 04/01/2020 10:46 PM, Bart Van Assche wrote:
> > On 2020-04-01 19:08, Mike Christie wrote:
> >> +.TP
> >> +.B PR_GET_IO_FLUSHER (Since Linux 5.6)
> >> +Return as the function result 1 if the caller is in the IO_FLUSHER state and
> >> +0 if not.
> >
> > Although I'm not at all a language expert, the word order at the start
> > of the above sentence seems a bit weird to me?
> >
>
> Do you mean the "Return as the function result" part or something else?
>
> That is how the other commands worded it. It looks like I messed up and
> dropped the (). This is how they did it:
>
> "Return (as the function result)"
>
> I will resend with that fix.
>
> If I misunderstood you I will fix that too.

I already fixed this piece. There are still the open questions in my
other mail though.


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH] prctl.2: doc PR_SET/GET_IO_FLUSHER - V4

[Mike Christie]

On 04/02/2020 07:16 AM, Michael Kerrisk (man-pages) wrote:
> Hello Mike,
> 
> On 4/2/20 4:08 AM, Mike Christie wrote:
>> This patch documents the PR_SET_IO_FLUSHER and PR_GET_IO_FLUSHER
>> prctl commands added to the linux kernel for 5.6 in commit:
>>
>> commit 8d19f1c8e1937baf74e1962aae9f90fa3aeab463
>> Author: Mike Christie <mchristi@redhat.com>
>> Date:   Mon Nov 11 18:19:00 2019 -0600> 
>>     prctl: PR_{G,S}ET_IO_FLUSHER to support controlling memory reclaim
>>
>> Signed-off-by: Mike Christie <mchristi@redhat.com>
> 
> I've applied this patch, but I have some questions:

Hey,

Thanks for fixing up the patch for me.

> 
> (a) What happens to the IO_FLUSHER setting in the child of fork(2)?

The child will inherit the setting.

> (b) What happens to the IO_FLUSHER setting during an execve(2)?
>     (Is it preserved, reset, something else?)

It's preserved.

Re: [PATCH] prctl.2: doc PR_SET/GET_IO_FLUSHER - V4

[Michael Kerrisk (man-pages)]

Hi Mike,

On Sat, 4 Apr 2020 at 23:07, Mike Christie <mchristi@redhat.com> wrote:
>
> On 04/02/2020 07:16 AM, Michael Kerrisk (man-pages) wrote:
> > Hello Mike,
> >
> > On 4/2/20 4:08 AM, Mike Christie wrote:
> >> This patch documents the PR_SET_IO_FLUSHER and PR_GET_IO_FLUSHER
> >> prctl commands added to the linux kernel for 5.6 in commit:
> >>
> >> commit 8d19f1c8e1937baf74e1962aae9f90fa3aeab463
> >> Author: Mike Christie <mchristi@redhat.com>
> >> Date:   Mon Nov 11 18:19:00 2019 -0600>
> >>     prctl: PR_{G,S}ET_IO_FLUSHER to support controlling memory reclaim
> >>
> >> Signed-off-by: Mike Christie <mchristi@redhat.com>
> >
> > I've applied this patch, but I have some questions:
>
> Hey,
>
> Thanks for fixing up the patch for me.

you're welcome.

> > (a) What happens to the IO_FLUSHER setting in the child of fork(2)?
>
> The child will inherit the setting.
>
> > (b) What happens to the IO_FLUSHER setting during an execve(2)?
> >     (Is it preserved, reset, something else?)
>
> It's preserved.

Thanks. I added this text:

              The  IO_FLUSHER  state is inherited by a child process cre‐
              ated via fork(2) and is preserved across execve(2).

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/