[PATCH] mprotect.2: Add information regarding PROT_{SEM,SAO,GROWSUP,GROWSDOWN}

[PATCH] mprotect.2: Add information regarding PROT_{SEM,SAO,GROWSUP,GROWSDOWN}

[Eugene Syromyatnikov]

The note regarding PROT_SEM is done based on observation that it is not
actually used in mprotect code (as far as i understood it).

---
 man2/mprotect.2 | 58 +++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 50 insertions(+), 8 deletions(-)

diff --git a/man2/mprotect.2 b/man2/mprotect.2
index 440fa65..4c3a1e2 100644
--- a/man2/mprotect.2
+++ b/man2/mprotect.2
@@ -30,12 +30,6 @@
 .\" 2007-06-02, mtk: Fairly substantial rewrites and additions, and
 .\" a much improved example program.
 .\"
-.\" FIXME The following protection flags need documenting:
-.\"         PROT_SEM
-.\"         PROT_GROWSDOWN
-.\"         PROT_GROWSUP
-.\"         PROT_SAO (PowerPC)
-.\"
 .TH MPROTECT 2 2015-07-23 "Linux" "Linux Programmer's Manual"
 .SH NAME
 mprotect, pkey_mprotect \- set protection on a region of memory
@@ -60,7 +54,7 @@ that violates the protection, then the kernel generates a
 signal for the process.
 .PP
 .I prot
-is either
+is a combination of the following access flags:
 .B PROT_NONE
 or a bitwise-or of the other values in the following list:
 .TP 1.1i
@@ -75,6 +69,38 @@ The memory can be modified.
 .TP
 .B PROT_EXEC
 The memory can be executed.
+'\" 882ad449046cec136c484dd2b3659fb4c683e0a3
+.TP
+.BR PROT_SEM " (since Linux 2.5.7)"
+The memory can be used for atomic operations. It was introduced as part of
+.BR futex (2)
+implementation (in order), but not actually used in any currently supported
+architecture so far.
+'\" aba46c5027cb59d98052231b36efcbbde9c77a1d ef3d3246a0d06be622867d21af25f997aeeb105f
+.TP
+.BR PROT_SAO " (since Linux 2.6.26)"
+The memory should have strong access ordering. This feature is specific to
+PowerPC architecture (version 2.06 of architecture specification adds SAO CPU
+feature, and is available on POWER 7 and newer, for example).
+.PP
+'\" c1dd59582e5b518983b0f4db66f0f8a969139c1b
+Additionally (since Linux 2.6.0),
+.I prot
+can have one of the following flags set:
+.TP 1.1i
+.B PROT_GROWSUP
+Apply protection mode to the whole VMA, which grows up (it should be mapped with
+.B MAP_GROWSUP
+flag set, which itself is available on IA-64 only, or be stack segment on
+HP PARISC).
+.TP
+.B PROT_GROWSDOWN
+Apply protection mode to the whole VMA, which grows down (it should be mapped
+with
+.B MAP_GROWSDOWN
+flag set).
+.PP
+This is especially useful for stacks and other mappings which can grow.
 .PP
 Like
 .BR mprotect (),
@@ -122,7 +148,23 @@ or not a multiple of the system page size.
 .RB ( pkey_mprotect ())
 \fIpkey\fP has not been allocated with
 .BR pkey_alloc (2)
-.\" Or: both PROT_GROWSUP and PROT_GROWSDOWN were specified in 'prot'.
+.TP
+.BR EINVAL
+Both
+.BR PROT_GROWSUP " and " PROT_GROWSDOWN
+were specified in
+.IR prot .
+.TP
+.BR EINVAL
+Invalid flags specified in
+.IR prot .
+.TP
+.BR EINVAL
+(PowerPC architecture)
+.B PROT_SAO
+specified in
+.IR prot ,
+but SAO hardware feature is no available.
 .TP
 .B ENOMEM
 Internal kernel structures could not be allocated.
-- 
2.10.2

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH v2] mprotect.2: Added information regarding PROT_{SEM,SAO,GROWSUP,GROWSDOWN}

[Eugene Syromyatnikov]

Changes since v1:
 * Fixed description of PROT_GROWSUP/PROT_GROWSDOWN from "whole mapping"
   to "up to end/down to beginning".
 * Clarified situation regarding obtaining VMA with
   VM_GROWSUP/VM_GROWSDOWN bit set.
 * Clarified meaning of "invalid flag"
 * Some rewording, typo fixes.

---
 man2/mprotect.2 | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 57 insertions(+), 8 deletions(-)

diff --git a/man2/mprotect.2 b/man2/mprotect.2
index 440fa65..f3b2b1a 100644
--- a/man2/mprotect.2
+++ b/man2/mprotect.2
@@ -30,12 +30,6 @@
 .\" 2007-06-02, mtk: Fairly substantial rewrites and additions, and
 .\" a much improved example program.
 .\"
-.\" FIXME The following protection flags need documenting:
-.\"         PROT_SEM
-.\"         PROT_GROWSDOWN
-.\"         PROT_GROWSUP
-.\"         PROT_SAO (PowerPC)
-.\"
 .TH MPROTECT 2 2015-07-23 "Linux" "Linux Programmer's Manual"
 .SH NAME
 mprotect, pkey_mprotect \- set protection on a region of memory
@@ -60,7 +54,7 @@ that violates the protection, then the kernel generates a
 signal for the process.
 .PP
 .I prot
-is either
+is a combination of the following access flags:
 .B PROT_NONE
 or a bitwise-or of the other values in the following list:
 .TP 1.1i
@@ -75,6 +69,42 @@ The memory can be modified.
 .TP
 .B PROT_EXEC
 The memory can be executed.
+'\" 882ad449046cec136c484dd2b3659fb4c683e0a3
+.TP
+.BR PROT_SEM " (since Linux 2.5.7)"
+The memory can be used for atomic operations. It was introduced as part of
+.BR futex (2)
+implementation (in order), but not actually used in any currently supported
+architecture so far.
+'\" aba46c5027cb59d98052231b36efcbbde9c77a1d ef3d3246a0d06be622867d21af25f997aeeb105f
+.TP
+.BR PROT_SAO " (since Linux 2.6.26)"
+The memory should have strong access ordering. This feature is specific to
+PowerPC architecture (version 2.06 of architecture specification adds SAO CPU
+feature, and it is available on POWER 7 or PowerPC A2, for example).
+.PP
+'\" c1dd59582e5b518983b0f4db66f0f8a969139c1b
+Additionally (since Linux 2.6.0),
+.I prot
+can have one of the following flags set:
+.TP 1.1i
+'\" mm/mmap.c:
+'\"	vm_flags |= calc_vm_prot_bits(prot, pkey) | calc_vm_flag_bits(flags) |
+'\"			mm->def_flags | VM_MAYREAD | VM_MAYWRITE | VM_MAYEXEC;
+'\" And calc_vm_flag_bits converts only GROWSDOWN/DENYWRITE/LOCKED.
+.B PROT_GROWSUP
+Apply protection mode up to the end of the VMA which grows up (it should be a
+stack segment on HP PA-RISC, since there are no other ways to map a segment with
+.B VM_GROWSUP
+even if architecture has support for it.)
+.TP
+.B PROT_GROWSDOWN
+Apply protection mode down to the beginning of the VMA which grows down (it
+should be stack segment or mapped with
+.B MAP_GROWSDOWN
+flag set.)
+.PP
+This is especially useful for stacks and other mappings which can grow.
 .PP
 Like
 .BR mprotect (),
@@ -122,7 +152,26 @@ or not a multiple of the system page size.
 .RB ( pkey_mprotect ())
 \fIpkey\fP has not been allocated with
 .BR pkey_alloc (2)
-.\" Or: both PROT_GROWSUP and PROT_GROWSDOWN were specified in 'prot'.
+.TP
+.BR EINVAL
+Both
+.BR PROT_GROWSUP " and " PROT_GROWSDOWN
+were specified in
+.IR prot .
+.TP
+.BR EINVAL
+Invalid (other than
+.BR PROT_READ ", " PROT_WRITE ", " PROT_EXEC ", " PROT_SEM ", "
+.BR PROT_SAO " (on PowerPC only), " PROT_GROWSUP ", " PROT_GROWSDOWN )
+flags specified in
+.IR prot .
+.TP
+.BR EINVAL
+(PowerPC architecture)
+.B PROT_SAO
+specified in
+.IR prot ,
+but SAO hardware feature is not available.
 .TP
 .B ENOMEM
 Internal kernel structures could not be allocated.
-- 
2.10.2

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] mprotect.2: Added information regarding PROT_{SEM,SAO,GROWSUP,GROWSDOWN}

[Michael Kerrisk (man-pages)]

Hello Eugene,

Thanks. Overall, this looks helpful, but I have some questions, below.

On 11/14/2016 02:23 AM, Eugene Syromyatnikov wrote:
> Changes since v1:
>  * Fixed description of PROT_GROWSUP/PROT_GROWSDOWN from "whole mapping"
>    to "up to end/down to beginning".
>  * Clarified situation regarding obtaining VMA with
>    VM_GROWSUP/VM_GROWSDOWN bit set.
>  * Clarified meaning of "invalid flag"
>  * Some rewording, typo fixes.
> 
> ---
>  man2/mprotect.2 | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++-------
>  1 file changed, 57 insertions(+), 8 deletions(-)
> 
> diff --git a/man2/mprotect.2 b/man2/mprotect.2
> index 440fa65..f3b2b1a 100644
> --- a/man2/mprotect.2
> +++ b/man2/mprotect.2
> @@ -30,12 +30,6 @@
>  .\" 2007-06-02, mtk: Fairly substantial rewrites and additions, and
>  .\" a much improved example program.
>  .\"
> -.\" FIXME The following protection flags need documenting:
> -.\"         PROT_SEM
> -.\"         PROT_GROWSDOWN
> -.\"         PROT_GROWSUP
> -.\"         PROT_SAO (PowerPC)
> -.\"
>  .TH MPROTECT 2 2015-07-23 "Linux" "Linux Programmer's Manual"
>  .SH NAME
>  mprotect, pkey_mprotect \- set protection on a region of memory
> @@ -60,7 +54,7 @@ that violates the protection, then the kernel generates a
>  signal for the process.
>  .PP
>  .I prot
> -is either
> +is a combination of the following access flags:
>  .B PROT_NONE
>  or a bitwise-or of the other values in the following list:
>  .TP 1.1i
> @@ -75,6 +69,42 @@ The memory can be modified.
>  .TP
>  .B PROT_EXEC
>  The memory can be executed.
> +'\" 882ad449046cec136c484dd2b3659fb4c683e0a3

Presumably, this is a commit ID from a historical tree?
I'd leave such IDs out, since most people probably don't
have the histrorical git tree set up locally.

By the way, the usual convention use for comment lines is

    .\"

rather than

    '\"

> +.TP
> +.BR PROT_SEM " (since Linux 2.5.7)"
> +The memory can be used for atomic operations. It was introduced as part of
> +.BR futex (2)
> +implementation (in order), but not actually used in any currently supported

What do the words "in order" here mean?

> +architecture so far.
> +'\" aba46c5027cb59d98052231b36efcbbde9c77a1d ef3d3246a0d06be622867d21af25f997aeeb105f
> +.TP
> +.BR PROT_SAO " (since Linux 2.6.26)"
> +The memory should have strong access ordering. This feature is specific to
> +PowerPC architecture (version 2.06 of architecture specification adds SAO CPU
> +feature, and it is available on POWER 7 or PowerPC A2, for example).
> +.PP
> +'\" c1dd59582e5b518983b0f4db66f0f8a969139c1b

Drop previous line (historical git commit ID)

> +Additionally (since Linux 2.6.0),
> +.I prot
> +can have one of the following flags set:
> +.TP 1.1i
> +'\" mm/mmap.c:
> +'\"	vm_flags |= calc_vm_prot_bits(prot, pkey) | calc_vm_flag_bits(flags) |
> +'\"			mm->def_flags | VM_MAYREAD | VM_MAYWRITE | VM_MAYEXEC;
> +'\" And calc_vm_flag_bits converts only GROWSDOWN/DENYWRITE/LOCKED.
> +.B PROT_GROWSUP
> +Apply protection mode up to the end of the VMA which grows up (it should be a

We need to explain VMA in user-space terms. Do you have an idea here?

> +stack segment on HP PA-RISC, since there are no other ways to map a segment with
> +.B VM_GROWSUP
> +even if architecture has support for it.)
> +.TP
> +.B PROT_GROWSDOWN
> +Apply protection mode down to the beginning of the VMA which grows down (it
> +should be stack segment or mapped with
> +.B MAP_GROWSDOWN
> +flag set.)
> +.PP
> +This is especially useful for stacks and other mappings which can grow.

Does "This" mean to PROT_GROWSUP, PROT_GROWSDOWN, or both?
(This needs to be made clearer.)

Cheers,

Michael

>  .PP
>  Like
>  .BR mprotect (),
> @@ -122,7 +152,26 @@ or not a multiple of the system page size.
>  .RB ( pkey_mprotect ())
>  \fIpkey\fP has not been allocated with
>  .BR pkey_alloc (2)
> -.\" Or: both PROT_GROWSUP and PROT_GROWSDOWN were specified in 'prot'.
> +.TP
> +.BR EINVAL
> +Both
> +.BR PROT_GROWSUP " and " PROT_GROWSDOWN
> +were specified in
> +.IR prot .
> +.TP
> +.BR EINVAL
> +Invalid (other than
> +.BR PROT_READ ", " PROT_WRITE ", " PROT_EXEC ", " PROT_SEM ", "
> +.BR PROT_SAO " (on PowerPC only), " PROT_GROWSUP ", " PROT_GROWSDOWN )
> +flags specified in
> +.IR prot .
> +.TP
> +.BR EINVAL
> +(PowerPC architecture)
> +.B PROT_SAO
> +specified in
> +.IR prot ,
> +but SAO hardware feature is not available.
>  .TP
>  .B ENOMEM
>  Internal kernel structures could not be allocated.
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH v2] mprotect.2: Added information regarding PROT_{SEM,SAO,GROWSUP,GROWSDOWN}

[Eugene Syromyatnikov]

On Tue, Nov 15, 2016 at 8:34 PM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> Hello Eugene,
>
> Thanks. Overall, this looks helpful, but I have some questions, below.
>
> On 11/14/2016 02:23 AM, Eugene Syromyatnikov wrote:
>> Changes since v1:
>>  * Fixed description of PROT_GROWSUP/PROT_GROWSDOWN from "whole mapping"
>>    to "up to end/down to beginning".
>>  * Clarified situation regarding obtaining VMA with
>>    VM_GROWSUP/VM_GROWSDOWN bit set.
>>  * Clarified meaning of "invalid flag"
>>  * Some rewording, typo fixes.
>>
>> ---
>>  man2/mprotect.2 | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++-------
>>  1 file changed, 57 insertions(+), 8 deletions(-)
>>
>> diff --git a/man2/mprotect.2 b/man2/mprotect.2
>> index 440fa65..f3b2b1a 100644
>> --- a/man2/mprotect.2
>> +++ b/man2/mprotect.2
>> @@ -30,12 +30,6 @@
>>  .\" 2007-06-02, mtk: Fairly substantial rewrites and additions, and
>>  .\" a much improved example program.
>>  .\"
>> -.\" FIXME The following protection flags need documenting:
>> -.\"         PROT_SEM
>> -.\"         PROT_GROWSDOWN
>> -.\"         PROT_GROWSUP
>> -.\"         PROT_SAO (PowerPC)
>> -.\"
>>  .TH MPROTECT 2 2015-07-23 "Linux" "Linux Programmer's Manual"
>>  .SH NAME
>>  mprotect, pkey_mprotect \- set protection on a region of memory
>> @@ -60,7 +54,7 @@ that violates the protection, then the kernel generates a
>>  signal for the process.
>>  .PP
>>  .I prot
>> -is either
>> +is a combination of the following access flags:
>>  .B PROT_NONE
>>  or a bitwise-or of the other values in the following list:
>>  .TP 1.1i
>> @@ -75,6 +69,42 @@ The memory can be modified.
>>  .TP
>>  .B PROT_EXEC
>>  The memory can be executed.
>> +'\" 882ad449046cec136c484dd2b3659fb4c683e0a3
>
> Presumably, this is a commit ID from a historical tree?
> I'd leave such IDs out, since most people probably don't
> have the histrorical git tree set up locally.
Yes. Ok, I'll remove it.

> By the way, the usual convention use for comment lines is
>
>     .\"
>
> rather than
>
>     '\"
Got it.

>> +.TP
>> +.BR PROT_SEM " (since Linux 2.5.7)"
>> +The memory can be used for atomic operations. It was introduced as part of
>> +.BR futex (2)
>> +implementation (in order), but not actually used in any currently supported
>
> What do the words "in order" here mean?
Oh, it should be "(in order to guarantee ability to perform atomic
operations required by its commands such as FUTEX_WAIT)".

>> +architecture so far.
>> +'\" aba46c5027cb59d98052231b36efcbbde9c77a1d ef3d3246a0d06be622867d21af25f997aeeb105f
>> +.TP
>> +.BR PROT_SAO " (since Linux 2.6.26)"
>> +The memory should have strong access ordering. This feature is specific to
>> +PowerPC architecture (version 2.06 of architecture specification adds SAO CPU
>> +feature, and it is available on POWER 7 or PowerPC A2, for example).
>> +.PP
>> +'\" c1dd59582e5b518983b0f4db66f0f8a969139c1b
>
> Drop previous line (historical git commit ID)
>
>> +Additionally (since Linux 2.6.0),
>> +.I prot
>> +can have one of the following flags set:
>> +.TP 1.1i
>> +'\" mm/mmap.c:
>> +'\"  vm_flags |= calc_vm_prot_bits(prot, pkey) | calc_vm_flag_bits(flags) |
>> +'\"                  mm->def_flags | VM_MAYREAD | VM_MAYWRITE | VM_MAYEXEC;
>> +'\" And calc_vm_flag_bits converts only GROWSDOWN/DENYWRITE/LOCKED.
>> +.B PROT_GROWSUP
>> +Apply protection mode up to the end of the VMA which grows up (it should be a
>
> We need to explain VMA in user-space terms. Do you have an idea here?
"Mapping", maybe?

>> +stack segment on HP PA-RISC, since there are no other ways to map a segment with
>> +.B VM_GROWSUP
>> +even if architecture has support for it.)
>> +.TP
>> +.B PROT_GROWSDOWN
>> +Apply protection mode down to the beginning of the VMA which grows down (it
>> +should be stack segment or mapped with
>> +.B MAP_GROWSDOWN
>> +flag set.)
>> +.PP
>> +This is especially useful for stacks and other mappings which can grow.
>
> Does "This" mean to PROT_GROWSUP, PROT_GROWSDOWN, or both?
> (This needs to be made clearer.)
I think, after all the additional notes in the flag descriptions
themselves regarding their applicability, this note can be removed
altogether.

> Cheers,
>
> Michael
>
>>  .PP
>>  Like
>>  .BR mprotect (),
>> @@ -122,7 +152,26 @@ or not a multiple of the system page size.
>>  .RB ( pkey_mprotect ())
>>  \fIpkey\fP has not been allocated with
>>  .BR pkey_alloc (2)
>> -.\" Or: both PROT_GROWSUP and PROT_GROWSDOWN were specified in 'prot'.
>> +.TP
>> +.BR EINVAL
>> +Both
>> +.BR PROT_GROWSUP " and " PROT_GROWSDOWN
>> +were specified in
>> +.IR prot .
>> +.TP
>> +.BR EINVAL
>> +Invalid (other than
>> +.BR PROT_READ ", " PROT_WRITE ", " PROT_EXEC ", " PROT_SEM ", "
>> +.BR PROT_SAO " (on PowerPC only), " PROT_GROWSUP ", " PROT_GROWSDOWN )
>> +flags specified in
>> +.IR prot .
>> +.TP
>> +.BR EINVAL
>> +(PowerPC architecture)
>> +.B PROT_SAO
>> +specified in
>> +.IR prot ,
>> +but SAO hardware feature is not available.
>>  .TP
>>  .B ENOMEM
>>  Internal kernel structures could not be allocated.
>>
>
>
> --
> Michael Kerrisk
> Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
> Linux/UNIX System Programming Training: http://man7.org/training/



-- 
Eugene "eSyr" Syromyatnikov
mailto:evgSyr-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
xmpp:eSyr@jabber.{ru|org}
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html