[PATCH v3 0/2] prctl.2 man page updates for Linux 5.6

[PATCH v3 0/2] prctl.2 man page updates for Linux 5.6

[Dave Martin]

A bunch of updates to the prctl(2) man page to fill in missing
prctls (mostly) up to Linux 5.6 (along with a few other tweaks and
fixes).

Patches from the v2 series [1] that have been applied or rejected
already have been dropped.

All that remain here now are the SVE and tagged address ABI controls
for arm64.



[1] https://lore.kernel.org/linux-man/1590614258-24728-1-git-send-email-Dave.Martin@arm.com/


Dave Martin (2):
  prctl.2: Add SVE prctls (arm64)
  prctl.2: Add tagged address ABI control prctls (arm64)

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

-- 
2.1.4

[PATCH v3 0/2] prctl.2 man page updates for Linux 5.6

[Dave Martin]

A bunch of updates to the prctl(2) man page to fill in missing
prctls (mostly) up to Linux 5.6 (along with a few other tweaks and
fixes).

Patches from the v2 series [1] that have been applied or rejected
already have been dropped.

All that remain here now are the SVE and tagged address ABI controls
for arm64.



[1] https://lore.kernel.org/linux-man/1590614258-24728-1-git-send-email-Dave.Martin@arm.com/


Dave Martin (2):
  prctl.2: Add SVE prctls (arm64)
  prctl.2: Add tagged address ABI control prctls (arm64)

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

-- 
2.1.4


_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

[PATCH v3 0/2] prctl.2 man page updates for Linux 5.6

[Dave Martin]

A bunch of updates to the prctl(2) man page to fill in missing
prctls (mostly) up to Linux 5.6 (along with a few other tweaks and
fixes).

Patches from the v2 series [1] that have been applied or rejected
already have been dropped.

All that remain here now are the SVE and tagged address ABI controls
for arm64.



[1] https://lore.kernel.org/linux-man/1590614258-24728-1-git-send-email-Dave.Martin-5wv7dgnIgG8@public.gmane.org/


Dave Martin (2):
  prctl.2: Add SVE prctls (arm64)
  prctl.2: Add tagged address ABI control prctls (arm64)

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

-- 
2.1.4

[PATCH v3 1/2] prctl.2: Add SVE prctls (arm64)

[Dave Martin]

Add documentation for the the PR_SVE_SET_VL and PR_SVE_GET_VL
prctls added in Linux 4.15 for arm64.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
Cc: Catalin Marinas <catalin.marinas@arm.com>
Cc: Will Deacon <will@kernel.org>

---

Since v2:

 * Clarify that the arg2 enumeration for PR_SVE_SET_VL applies to the
   bith _other than_ the PR_SVE_VL_LEN_MASK bits, rather than to all the
   bits.

 * Clarify return value semantics for PR_SVE_SET_VL, to highlight that
   there is no PR_SVE_SET_VL_ONEXEC in the return value and refer to
   PR_SVE_GET_VL for the rest of the definition.  Also clarify when the
   vector length given in the return value actually takes effect.

 * Reorder some documentation cross-references to avoid ambiguity about
   what they apply to.
---
 man2/prctl.2 | 170 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 170 insertions(+)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 88b791b..46ea9d2 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -1370,6 +1370,158 @@ call failing with the error
 .BR ENXIO .
 For further details, see the kernel source file
 .IR Documentation/admin\-guide/kernel\-parameters.txt .
+.\" prctl PR_SVE_SET_VL
+.\" commit 2d2123bc7c7f843aa9db87720de159a049839862
+.\" linux-5.6/Documentation/arm64/sve.rst
+.TP
+.BR PR_SVE_SET_VL " (since Linux 4.15, only on arm64)"
+Configure the thread's SVE vector length,
+as specified by
+.IR "(int) arg2" .
+Arguments
+.IR arg3 ", " arg4 " and " arg5
+are ignored.
+.IP
+The bits of
+.I arg2
+corresponding to
+.B PR_SVE_VL_LEN_MASK
+must be set to the desired vector length in bytes.
+This is interpreted as an upper bound:
+the kernel will select the greatest available vector length
+that does not exceed the value specified.
+In particular, specifying
+.B SVE_VL_MAX
+(defined in
+.I <asm/sigcontext.h>)
+for the
+.B PR_SVE_VL_LEN_MASK
+bits requests the maximum supported vector length.
+.IP
+In addition, the other bits of
+.I arg2
+must be set to one of the following combinations of flags:
+.RS
+.TP
+.B 0
+Perform the change immediately.
+At the next
+.BR execve (2)
+in the thread,
+the vector length will be reset to the value configured in
+.IR /proc/sys/abi/sve_default_vector_length .
+.TP
+.B PR_SVE_VL_INHERIT
+Perform the change immediately.
+Subsequent
+.BR execve (2)
+calls will preserve the new vector length.
+.TP
+.B PR_SVE_SET_VL_ONEXEC
+Defer the change, so that it is performed at the next
+.BR execve (2)
+in the thread.
+Further
+.BR execve (2)
+calls will reset the vector length to the value configured in
+.IR /proc/sys/abi/sve_default_vector_length .
+.TP
+.B "PR_SVE_SET_VL_ONEXEC | PR_SVE_VL_INHERIT"
+Defer the change, so that it is performed at the next
+.BR execve (2)
+in the thread.
+Further
+.BR execve (2)
+calls will preserve the new vector length.
+.RE
+.IP
+In all cases,
+any previously pending deferred change is canceled.
+.IP
+The call fails with error
+.B EINVAL
+if SVE is not supported on the platform, if
+.I arg2
+is unrecognized or invalid, or the value in the bits of
+.I arg2
+corresponding to
+.B PR_SVE_VL_LEN_MASK
+is outside the range
+.BR SVE_VL_MIN .. SVE_VL_MAX
+or is not a multiple of 16.
+.IP
+On success,
+a nonnegative value is returned that describes the
+.I selected
+configuration.
+If
+.B PR_SVE_SET_VL_ONEXEC
+was included in
+.IR arg2 ,
+then the configuration described by the return value
+will take effect at the next
+.BR execve ().
+Otherwise, the configuration is already in effect when the
+.B PR_SVE_SET_VL
+call returns.
+In either case, the value is encoded in the same way as the return value of
+.BR PR_SVE_GET_VL .
+Note that there is no explicit flag in the return value
+corresponding to
+.BR PR_SVE_SET_VL_ONEXEC .
+.IP
+The configuration (including any pending deferred change)
+is inherited across
+.BR fork (2)
+and
+.BR clone (2).
+.IP
+For more information, see the kernel source file
+.I Documentation/arm64/sve.rst
+.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed
+(or
+.I Documentation/arm64/sve.txt
+before Linux 5.3).
+.IP
+.B Warning:
+Because the compiler or run-time environment
+may be using SVE, using this call without the
+.B PR_SVE_SET_VL_ONEXEC
+flag may crash the calling process.
+The conditions for using it safely are complex and system-dependent.
+Don't use it unless you really know what you are doing.
+.\" prctl PR_SVE_GET_VL
+.TP
+.BR PR_SVE_GET_VL " (since Linux 4.15, only on arm64)"
+Get the thread's current SVE vector length configuration.
+.IP
+Arguments
+.IR arg2 ", " arg3 ", " arg4 " and " arg5
+are ignored.
+.IP
+Providing that the kernel and platform support SVE
+this operation always succeeds,
+returning a nonnegative value that describes the
+.I current
+configuration.
+The bits corresponding to
+.B PR_SVE_VL_LEN_MASK
+contain the currently configured vector length in bytes.
+The bit corresponding to
+.B PR_SVE_VL_INHERIT
+indicates whether the vector length will be inherited
+across
+.BR execve (2).
+.IP
+Note that there is no way to determine whether there is
+a pending vector length change that has not yet taken effect.
+.IP
+For more information, see the kernel source file
+.I Documentation/arm64/sve.rst
+.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed
+(or
+.I Documentation/arm64/sve.txt
+before Linux 5.3).
 .\"
 .\" prctl PR_TASK_PERF_EVENTS_DISABLE
 .TP
@@ -1613,6 +1765,8 @@ On success,
 .BR PR_GET_NO_NEW_PRIVS ,
 .BR PR_GET_SECUREBITS ,
 .BR PR_GET_SPECULATION_CTRL ,
+.BR PR_SVE_GET_VL ,
+.BR PR_SVE_SET_VL ,
 .BR PR_GET_THP_DISABLE ,
 .BR PR_GET_TIMING ,
 .BR PR_GET_TIMERSLACK ,
@@ -1904,6 +2058,22 @@ See the description of
 .B PR_PAC_RESET_KEYS
 above for details.
 .TP
+.B EINVAL
+.I option
+is
+.B PR_SVE_SET_VL
+and the arguments are invalid or unsupported,
+or SVE is not available on this platform.
+See the description of
+.B PR_SVE_SET_VL
+above for details.
+.TP
+.B EINVAL
+.I option
+is
+.B PR_SVE_GET_VL
+and SVE is not available on this platform.
+.TP
 .B ENODEV
 .I option
 was
-- 
2.1.4

[PATCH v3 1/2] prctl.2: Add SVE prctls (arm64)

[Dave Martin]

Add documentation for the the PR_SVE_SET_VL and PR_SVE_GET_VL
prctls added in Linux 4.15 for arm64.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
Cc: Catalin Marinas <catalin.marinas@arm.com>
Cc: Will Deacon <will@kernel.org>

---

Since v2:

 * Clarify that the arg2 enumeration for PR_SVE_SET_VL applies to the
   bith _other than_ the PR_SVE_VL_LEN_MASK bits, rather than to all the
   bits.

 * Clarify return value semantics for PR_SVE_SET_VL, to highlight that
   there is no PR_SVE_SET_VL_ONEXEC in the return value and refer to
   PR_SVE_GET_VL for the rest of the definition.  Also clarify when the
   vector length given in the return value actually takes effect.

 * Reorder some documentation cross-references to avoid ambiguity about
   what they apply to.
---
 man2/prctl.2 | 170 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 170 insertions(+)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 88b791b..46ea9d2 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -1370,6 +1370,158 @@ call failing with the error
 .BR ENXIO .
 For further details, see the kernel source file
 .IR Documentation/admin\-guide/kernel\-parameters.txt .
+.\" prctl PR_SVE_SET_VL
+.\" commit 2d2123bc7c7f843aa9db87720de159a049839862
+.\" linux-5.6/Documentation/arm64/sve.rst
+.TP
+.BR PR_SVE_SET_VL " (since Linux 4.15, only on arm64)"
+Configure the thread's SVE vector length,
+as specified by
+.IR "(int) arg2" .
+Arguments
+.IR arg3 ", " arg4 " and " arg5
+are ignored.
+.IP
+The bits of
+.I arg2
+corresponding to
+.B PR_SVE_VL_LEN_MASK
+must be set to the desired vector length in bytes.
+This is interpreted as an upper bound:
+the kernel will select the greatest available vector length
+that does not exceed the value specified.
+In particular, specifying
+.B SVE_VL_MAX
+(defined in
+.I <asm/sigcontext.h>)
+for the
+.B PR_SVE_VL_LEN_MASK
+bits requests the maximum supported vector length.
+.IP
+In addition, the other bits of
+.I arg2
+must be set to one of the following combinations of flags:
+.RS
+.TP
+.B 0
+Perform the change immediately.
+At the next
+.BR execve (2)
+in the thread,
+the vector length will be reset to the value configured in
+.IR /proc/sys/abi/sve_default_vector_length .
+.TP
+.B PR_SVE_VL_INHERIT
+Perform the change immediately.
+Subsequent
+.BR execve (2)
+calls will preserve the new vector length.
+.TP
+.B PR_SVE_SET_VL_ONEXEC
+Defer the change, so that it is performed at the next
+.BR execve (2)
+in the thread.
+Further
+.BR execve (2)
+calls will reset the vector length to the value configured in
+.IR /proc/sys/abi/sve_default_vector_length .
+.TP
+.B "PR_SVE_SET_VL_ONEXEC | PR_SVE_VL_INHERIT"
+Defer the change, so that it is performed at the next
+.BR execve (2)
+in the thread.
+Further
+.BR execve (2)
+calls will preserve the new vector length.
+.RE
+.IP
+In all cases,
+any previously pending deferred change is canceled.
+.IP
+The call fails with error
+.B EINVAL
+if SVE is not supported on the platform, if
+.I arg2
+is unrecognized or invalid, or the value in the bits of
+.I arg2
+corresponding to
+.B PR_SVE_VL_LEN_MASK
+is outside the range
+.BR SVE_VL_MIN .. SVE_VL_MAX
+or is not a multiple of 16.
+.IP
+On success,
+a nonnegative value is returned that describes the
+.I selected
+configuration.
+If
+.B PR_SVE_SET_VL_ONEXEC
+was included in
+.IR arg2 ,
+then the configuration described by the return value
+will take effect at the next
+.BR execve ().
+Otherwise, the configuration is already in effect when the
+.B PR_SVE_SET_VL
+call returns.
+In either case, the value is encoded in the same way as the return value of
+.BR PR_SVE_GET_VL .
+Note that there is no explicit flag in the return value
+corresponding to
+.BR PR_SVE_SET_VL_ONEXEC .
+.IP
+The configuration (including any pending deferred change)
+is inherited across
+.BR fork (2)
+and
+.BR clone (2).
+.IP
+For more information, see the kernel source file
+.I Documentation/arm64/sve.rst
+.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed
+(or
+.I Documentation/arm64/sve.txt
+before Linux 5.3).
+.IP
+.B Warning:
+Because the compiler or run-time environment
+may be using SVE, using this call without the
+.B PR_SVE_SET_VL_ONEXEC
+flag may crash the calling process.
+The conditions for using it safely are complex and system-dependent.
+Don't use it unless you really know what you are doing.
+.\" prctl PR_SVE_GET_VL
+.TP
+.BR PR_SVE_GET_VL " (since Linux 4.15, only on arm64)"
+Get the thread's current SVE vector length configuration.
+.IP
+Arguments
+.IR arg2 ", " arg3 ", " arg4 " and " arg5
+are ignored.
+.IP
+Providing that the kernel and platform support SVE
+this operation always succeeds,
+returning a nonnegative value that describes the
+.I current
+configuration.
+The bits corresponding to
+.B PR_SVE_VL_LEN_MASK
+contain the currently configured vector length in bytes.
+The bit corresponding to
+.B PR_SVE_VL_INHERIT
+indicates whether the vector length will be inherited
+across
+.BR execve (2).
+.IP
+Note that there is no way to determine whether there is
+a pending vector length change that has not yet taken effect.
+.IP
+For more information, see the kernel source file
+.I Documentation/arm64/sve.rst
+.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed
+(or
+.I Documentation/arm64/sve.txt
+before Linux 5.3).
 .\"
 .\" prctl PR_TASK_PERF_EVENTS_DISABLE
 .TP
@@ -1613,6 +1765,8 @@ On success,
 .BR PR_GET_NO_NEW_PRIVS ,
 .BR PR_GET_SECUREBITS ,
 .BR PR_GET_SPECULATION_CTRL ,
+.BR PR_SVE_GET_VL ,
+.BR PR_SVE_SET_VL ,
 .BR PR_GET_THP_DISABLE ,
 .BR PR_GET_TIMING ,
 .BR PR_GET_TIMERSLACK ,
@@ -1904,6 +2058,22 @@ See the description of
 .B PR_PAC_RESET_KEYS
 above for details.
 .TP
+.B EINVAL
+.I option
+is
+.B PR_SVE_SET_VL
+and the arguments are invalid or unsupported,
+or SVE is not available on this platform.
+See the description of
+.B PR_SVE_SET_VL
+above for details.
+.TP
+.B EINVAL
+.I option
+is
+.B PR_SVE_GET_VL
+and SVE is not available on this platform.
+.TP
 .B ENODEV
 .I option
 was
-- 
2.1.4


_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

[PATCH v3 1/2] prctl.2: Add SVE prctls (arm64)

[Dave Martin]

Add documentation for the the PR_SVE_SET_VL and PR_SVE_GET_VL
prctls added in Linux 4.15 for arm64.

Signed-off-by: Dave Martin <Dave.Martin-5wv7dgnIgG8@public.gmane.org>
Cc: Catalin Marinas <catalin.marinas-5wv7dgnIgG8@public.gmane.org>
Cc: Will Deacon <will-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org>

---

Since v2:

 * Clarify that the arg2 enumeration for PR_SVE_SET_VL applies to the
   bith _other than_ the PR_SVE_VL_LEN_MASK bits, rather than to all the
   bits.

 * Clarify return value semantics for PR_SVE_SET_VL, to highlight that
   there is no PR_SVE_SET_VL_ONEXEC in the return value and refer to
   PR_SVE_GET_VL for the rest of the definition.  Also clarify when the
   vector length given in the return value actually takes effect.

 * Reorder some documentation cross-references to avoid ambiguity about
   what they apply to.
---
 man2/prctl.2 | 170 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 170 insertions(+)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 88b791b..46ea9d2 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -1370,6 +1370,158 @@ call failing with the error
 .BR ENXIO .
 For further details, see the kernel source file
 .IR Documentation/admin\-guide/kernel\-parameters.txt .
+.\" prctl PR_SVE_SET_VL
+.\" commit 2d2123bc7c7f843aa9db87720de159a049839862
+.\" linux-5.6/Documentation/arm64/sve.rst
+.TP
+.BR PR_SVE_SET_VL " (since Linux 4.15, only on arm64)"
+Configure the thread's SVE vector length,
+as specified by
+.IR "(int) arg2" .
+Arguments
+.IR arg3 ", " arg4 " and " arg5
+are ignored.
+.IP
+The bits of
+.I arg2
+corresponding to
+.B PR_SVE_VL_LEN_MASK
+must be set to the desired vector length in bytes.
+This is interpreted as an upper bound:
+the kernel will select the greatest available vector length
+that does not exceed the value specified.
+In particular, specifying
+.B SVE_VL_MAX
+(defined in
+.I <asm/sigcontext.h>)
+for the
+.B PR_SVE_VL_LEN_MASK
+bits requests the maximum supported vector length.
+.IP
+In addition, the other bits of
+.I arg2
+must be set to one of the following combinations of flags:
+.RS
+.TP
+.B 0
+Perform the change immediately.
+At the next
+.BR execve (2)
+in the thread,
+the vector length will be reset to the value configured in
+.IR /proc/sys/abi/sve_default_vector_length .
+.TP
+.B PR_SVE_VL_INHERIT
+Perform the change immediately.
+Subsequent
+.BR execve (2)
+calls will preserve the new vector length.
+.TP
+.B PR_SVE_SET_VL_ONEXEC
+Defer the change, so that it is performed at the next
+.BR execve (2)
+in the thread.
+Further
+.BR execve (2)
+calls will reset the vector length to the value configured in
+.IR /proc/sys/abi/sve_default_vector_length .
+.TP
+.B "PR_SVE_SET_VL_ONEXEC | PR_SVE_VL_INHERIT"
+Defer the change, so that it is performed at the next
+.BR execve (2)
+in the thread.
+Further
+.BR execve (2)
+calls will preserve the new vector length.
+.RE
+.IP
+In all cases,
+any previously pending deferred change is canceled.
+.IP
+The call fails with error
+.B EINVAL
+if SVE is not supported on the platform, if
+.I arg2
+is unrecognized or invalid, or the value in the bits of
+.I arg2
+corresponding to
+.B PR_SVE_VL_LEN_MASK
+is outside the range
+.BR SVE_VL_MIN .. SVE_VL_MAX
+or is not a multiple of 16.
+.IP
+On success,
+a nonnegative value is returned that describes the
+.I selected
+configuration.
+If
+.B PR_SVE_SET_VL_ONEXEC
+was included in
+.IR arg2 ,
+then the configuration described by the return value
+will take effect at the next
+.BR execve ().
+Otherwise, the configuration is already in effect when the
+.B PR_SVE_SET_VL
+call returns.
+In either case, the value is encoded in the same way as the return value of
+.BR PR_SVE_GET_VL .
+Note that there is no explicit flag in the return value
+corresponding to
+.BR PR_SVE_SET_VL_ONEXEC .
+.IP
+The configuration (including any pending deferred change)
+is inherited across
+.BR fork (2)
+and
+.BR clone (2).
+.IP
+For more information, see the kernel source file
+.I Documentation/arm64/sve.rst
+.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed
+(or
+.I Documentation/arm64/sve.txt
+before Linux 5.3).
+.IP
+.B Warning:
+Because the compiler or run-time environment
+may be using SVE, using this call without the
+.B PR_SVE_SET_VL_ONEXEC
+flag may crash the calling process.
+The conditions for using it safely are complex and system-dependent.
+Don't use it unless you really know what you are doing.
+.\" prctl PR_SVE_GET_VL
+.TP
+.BR PR_SVE_GET_VL " (since Linux 4.15, only on arm64)"
+Get the thread's current SVE vector length configuration.
+.IP
+Arguments
+.IR arg2 ", " arg3 ", " arg4 " and " arg5
+are ignored.
+.IP
+Providing that the kernel and platform support SVE
+this operation always succeeds,
+returning a nonnegative value that describes the
+.I current
+configuration.
+The bits corresponding to
+.B PR_SVE_VL_LEN_MASK
+contain the currently configured vector length in bytes.
+The bit corresponding to
+.B PR_SVE_VL_INHERIT
+indicates whether the vector length will be inherited
+across
+.BR execve (2).
+.IP
+Note that there is no way to determine whether there is
+a pending vector length change that has not yet taken effect.
+.IP
+For more information, see the kernel source file
+.I Documentation/arm64/sve.rst
+.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed
+(or
+.I Documentation/arm64/sve.txt
+before Linux 5.3).
 .\"
 .\" prctl PR_TASK_PERF_EVENTS_DISABLE
 .TP
@@ -1613,6 +1765,8 @@ On success,
 .BR PR_GET_NO_NEW_PRIVS ,
 .BR PR_GET_SECUREBITS ,
 .BR PR_GET_SPECULATION_CTRL ,
+.BR PR_SVE_GET_VL ,
+.BR PR_SVE_SET_VL ,
 .BR PR_GET_THP_DISABLE ,
 .BR PR_GET_TIMING ,
 .BR PR_GET_TIMERSLACK ,
@@ -1904,6 +2058,22 @@ See the description of
 .B PR_PAC_RESET_KEYS
 above for details.
 .TP
+.B EINVAL
+.I option
+is
+.B PR_SVE_SET_VL
+and the arguments are invalid or unsupported,
+or SVE is not available on this platform.
+See the description of
+.B PR_SVE_SET_VL
+above for details.
+.TP
+.B EINVAL
+.I option
+is
+.B PR_SVE_GET_VL
+and SVE is not available on this platform.
+.TP
 .B ENODEV
 .I option
 was
-- 
2.1.4

Re: [PATCH v3 1/2] prctl.2: Add SVE prctls (arm64)

[Michael Kerrisk (man-pages)]

Hi Dave,

On 6/24/20 7:36 PM, Dave Martin wrote:
> Add documentation for the the PR_SVE_SET_VL and PR_SVE_GET_VL
> prctls added in Linux 4.15 for arm64.
> 
> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> Cc: Catalin Marinas <catalin.marinas@arm.com>
> Cc: Will Deacon <will@kernel.org>
> 
> ---
> 
> Since v2:
> 
>  * Clarify that the arg2 enumeration for PR_SVE_SET_VL applies to the
>    bith _other than_ the PR_SVE_VL_LEN_MASK bits, rather than to all the
>    bits.
> 
>  * Clarify return value semantics for PR_SVE_SET_VL, to highlight that
>    there is no PR_SVE_SET_VL_ONEXEC in the return value and refer to
>    PR_SVE_GET_VL for the rest of the definition.  Also clarify when the
>    vector length given in the return value actually takes effect.
> 
>  * Reorder some documentation cross-references to avoid ambiguity about
>    what they apply to.

Nicely written patch! I've applied locally, but won't push just yet, to
allow for some reviews/acks to come in.

Thanks,

Michael


> ---
>  man2/prctl.2 | 170 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 170 insertions(+)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 88b791b..46ea9d2 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -1370,6 +1370,158 @@ call failing with the error
>  .BR ENXIO .
>  For further details, see the kernel source file
>  .IR Documentation/admin\-guide/kernel\-parameters.txt .
> +.\" prctl PR_SVE_SET_VL
> +.\" commit 2d2123bc7c7f843aa9db87720de159a049839862
> +.\" linux-5.6/Documentation/arm64/sve.rst
> +.TP
> +.BR PR_SVE_SET_VL " (since Linux 4.15, only on arm64)"
> +Configure the thread's SVE vector length,
> +as specified by
> +.IR "(int) arg2" .
> +Arguments
> +.IR arg3 ", " arg4 " and " arg5
> +are ignored.
> +.IP
> +The bits of
> +.I arg2
> +corresponding to
> +.B PR_SVE_VL_LEN_MASK
> +must be set to the desired vector length in bytes.
> +This is interpreted as an upper bound:
> +the kernel will select the greatest available vector length
> +that does not exceed the value specified.
> +In particular, specifying
> +.B SVE_VL_MAX
> +(defined in
> +.I <asm/sigcontext.h>)
> +for the
> +.B PR_SVE_VL_LEN_MASK
> +bits requests the maximum supported vector length.
> +.IP
> +In addition, the other bits of
> +.I arg2
> +must be set to one of the following combinations of flags:
> +.RS
> +.TP
> +.B 0
> +Perform the change immediately.
> +At the next
> +.BR execve (2)
> +in the thread,
> +the vector length will be reset to the value configured in
> +.IR /proc/sys/abi/sve_default_vector_length .
> +.TP
> +.B PR_SVE_VL_INHERIT
> +Perform the change immediately.
> +Subsequent
> +.BR execve (2)
> +calls will preserve the new vector length.
> +.TP
> +.B PR_SVE_SET_VL_ONEXEC
> +Defer the change, so that it is performed at the next
> +.BR execve (2)
> +in the thread.
> +Further
> +.BR execve (2)
> +calls will reset the vector length to the value configured in
> +.IR /proc/sys/abi/sve_default_vector_length .
> +.TP
> +.B "PR_SVE_SET_VL_ONEXEC | PR_SVE_VL_INHERIT"
> +Defer the change, so that it is performed at the next
> +.BR execve (2)
> +in the thread.
> +Further
> +.BR execve (2)
> +calls will preserve the new vector length.
> +.RE
> +.IP
> +In all cases,
> +any previously pending deferred change is canceled.
> +.IP
> +The call fails with error
> +.B EINVAL
> +if SVE is not supported on the platform, if
> +.I arg2
> +is unrecognized or invalid, or the value in the bits of
> +.I arg2
> +corresponding to
> +.B PR_SVE_VL_LEN_MASK
> +is outside the range
> +.BR SVE_VL_MIN .. SVE_VL_MAX
> +or is not a multiple of 16.
> +.IP
> +On success,
> +a nonnegative value is returned that describes the
> +.I selected
> +configuration.
> +If
> +.B PR_SVE_SET_VL_ONEXEC
> +was included in
> +.IR arg2 ,
> +then the configuration described by the return value
> +will take effect at the next
> +.BR execve ().
> +Otherwise, the configuration is already in effect when the
> +.B PR_SVE_SET_VL
> +call returns.
> +In either case, the value is encoded in the same way as the return value of
> +.BR PR_SVE_GET_VL .
> +Note that there is no explicit flag in the return value
> +corresponding to
> +.BR PR_SVE_SET_VL_ONEXEC .
> +.IP
> +The configuration (including any pending deferred change)
> +is inherited across
> +.BR fork (2)
> +and
> +.BR clone (2).
> +.IP
> +For more information, see the kernel source file
> +.I Documentation/arm64/sve.rst
> +.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed
> +(or
> +.I Documentation/arm64/sve.txt
> +before Linux 5.3).
> +.IP
> +.B Warning:
> +Because the compiler or run-time environment
> +may be using SVE, using this call without the
> +.B PR_SVE_SET_VL_ONEXEC
> +flag may crash the calling process.
> +The conditions for using it safely are complex and system-dependent.
> +Don't use it unless you really know what you are doing.
> +.\" prctl PR_SVE_GET_VL
> +.TP
> +.BR PR_SVE_GET_VL " (since Linux 4.15, only on arm64)"
> +Get the thread's current SVE vector length configuration.
> +.IP
> +Arguments
> +.IR arg2 ", " arg3 ", " arg4 " and " arg5
> +are ignored.
> +.IP
> +Providing that the kernel and platform support SVE
> +this operation always succeeds,
> +returning a nonnegative value that describes the
> +.I current
> +configuration.
> +The bits corresponding to
> +.B PR_SVE_VL_LEN_MASK
> +contain the currently configured vector length in bytes.
> +The bit corresponding to
> +.B PR_SVE_VL_INHERIT
> +indicates whether the vector length will be inherited
> +across
> +.BR execve (2).
> +.IP
> +Note that there is no way to determine whether there is
> +a pending vector length change that has not yet taken effect.
> +.IP
> +For more information, see the kernel source file
> +.I Documentation/arm64/sve.rst
> +.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed
> +(or
> +.I Documentation/arm64/sve.txt
> +before Linux 5.3).
>  .\"
>  .\" prctl PR_TASK_PERF_EVENTS_DISABLE
>  .TP
> @@ -1613,6 +1765,8 @@ On success,
>  .BR PR_GET_NO_NEW_PRIVS ,
>  .BR PR_GET_SECUREBITS ,
>  .BR PR_GET_SPECULATION_CTRL ,
> +.BR PR_SVE_GET_VL ,
> +.BR PR_SVE_SET_VL ,
>  .BR PR_GET_THP_DISABLE ,
>  .BR PR_GET_TIMING ,
>  .BR PR_GET_TIMERSLACK ,
> @@ -1904,6 +2058,22 @@ See the description of
>  .B PR_PAC_RESET_KEYS
>  above for details.
>  .TP
> +.B EINVAL
> +.I option
> +is
> +.B PR_SVE_SET_VL
> +and the arguments are invalid or unsupported,
> +or SVE is not available on this platform.
> +See the description of
> +.B PR_SVE_SET_VL
> +above for details.
> +.TP
> +.B EINVAL
> +.I option
> +is
> +.B PR_SVE_GET_VL
> +and SVE is not available on this platform.
> +.TP
>  .B ENODEV
>  .I option
>  was
> 


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

Re: [PATCH v3 1/2] prctl.2: Add SVE prctls (arm64)

[Michael Kerrisk (man-pages)]

Hi Dave,

On 6/24/20 7:36 PM, Dave Martin wrote:
> Add documentation for the the PR_SVE_SET_VL and PR_SVE_GET_VL
> prctls added in Linux 4.15 for arm64.
> 
> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> Cc: Catalin Marinas <catalin.marinas@arm.com>
> Cc: Will Deacon <will@kernel.org>
> 
> ---
> 
> Since v2:
> 
>  * Clarify that the arg2 enumeration for PR_SVE_SET_VL applies to the
>    bith _other than_ the PR_SVE_VL_LEN_MASK bits, rather than to all the
>    bits.
> 
>  * Clarify return value semantics for PR_SVE_SET_VL, to highlight that
>    there is no PR_SVE_SET_VL_ONEXEC in the return value and refer to
>    PR_SVE_GET_VL for the rest of the definition.  Also clarify when the
>    vector length given in the return value actually takes effect.
> 
>  * Reorder some documentation cross-references to avoid ambiguity about
>    what they apply to.

Nicely written patch! I've applied locally, but won't push just yet, to
allow for some reviews/acks to come in.

Thanks,

Michael


> ---
>  man2/prctl.2 | 170 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 170 insertions(+)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 88b791b..46ea9d2 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -1370,6 +1370,158 @@ call failing with the error
>  .BR ENXIO .
>  For further details, see the kernel source file
>  .IR Documentation/admin\-guide/kernel\-parameters.txt .
> +.\" prctl PR_SVE_SET_VL
> +.\" commit 2d2123bc7c7f843aa9db87720de159a049839862
> +.\" linux-5.6/Documentation/arm64/sve.rst
> +.TP
> +.BR PR_SVE_SET_VL " (since Linux 4.15, only on arm64)"
> +Configure the thread's SVE vector length,
> +as specified by
> +.IR "(int) arg2" .
> +Arguments
> +.IR arg3 ", " arg4 " and " arg5
> +are ignored.
> +.IP
> +The bits of
> +.I arg2
> +corresponding to
> +.B PR_SVE_VL_LEN_MASK
> +must be set to the desired vector length in bytes.
> +This is interpreted as an upper bound:
> +the kernel will select the greatest available vector length
> +that does not exceed the value specified.
> +In particular, specifying
> +.B SVE_VL_MAX
> +(defined in
> +.I <asm/sigcontext.h>)
> +for the
> +.B PR_SVE_VL_LEN_MASK
> +bits requests the maximum supported vector length.
> +.IP
> +In addition, the other bits of
> +.I arg2
> +must be set to one of the following combinations of flags:
> +.RS
> +.TP
> +.B 0
> +Perform the change immediately.
> +At the next
> +.BR execve (2)
> +in the thread,
> +the vector length will be reset to the value configured in
> +.IR /proc/sys/abi/sve_default_vector_length .
> +.TP
> +.B PR_SVE_VL_INHERIT
> +Perform the change immediately.
> +Subsequent
> +.BR execve (2)
> +calls will preserve the new vector length.
> +.TP
> +.B PR_SVE_SET_VL_ONEXEC
> +Defer the change, so that it is performed at the next
> +.BR execve (2)
> +in the thread.
> +Further
> +.BR execve (2)
> +calls will reset the vector length to the value configured in
> +.IR /proc/sys/abi/sve_default_vector_length .
> +.TP
> +.B "PR_SVE_SET_VL_ONEXEC | PR_SVE_VL_INHERIT"
> +Defer the change, so that it is performed at the next
> +.BR execve (2)
> +in the thread.
> +Further
> +.BR execve (2)
> +calls will preserve the new vector length.
> +.RE
> +.IP
> +In all cases,
> +any previously pending deferred change is canceled.
> +.IP
> +The call fails with error
> +.B EINVAL
> +if SVE is not supported on the platform, if
> +.I arg2
> +is unrecognized or invalid, or the value in the bits of
> +.I arg2
> +corresponding to
> +.B PR_SVE_VL_LEN_MASK
> +is outside the range
> +.BR SVE_VL_MIN .. SVE_VL_MAX
> +or is not a multiple of 16.
> +.IP
> +On success,
> +a nonnegative value is returned that describes the
> +.I selected
> +configuration.
> +If
> +.B PR_SVE_SET_VL_ONEXEC
> +was included in
> +.IR arg2 ,
> +then the configuration described by the return value
> +will take effect at the next
> +.BR execve ().
> +Otherwise, the configuration is already in effect when the
> +.B PR_SVE_SET_VL
> +call returns.
> +In either case, the value is encoded in the same way as the return value of
> +.BR PR_SVE_GET_VL .
> +Note that there is no explicit flag in the return value
> +corresponding to
> +.BR PR_SVE_SET_VL_ONEXEC .
> +.IP
> +The configuration (including any pending deferred change)
> +is inherited across
> +.BR fork (2)
> +and
> +.BR clone (2).
> +.IP
> +For more information, see the kernel source file
> +.I Documentation/arm64/sve.rst
> +.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed
> +(or
> +.I Documentation/arm64/sve.txt
> +before Linux 5.3).
> +.IP
> +.B Warning:
> +Because the compiler or run-time environment
> +may be using SVE, using this call without the
> +.B PR_SVE_SET_VL_ONEXEC
> +flag may crash the calling process.
> +The conditions for using it safely are complex and system-dependent.
> +Don't use it unless you really know what you are doing.
> +.\" prctl PR_SVE_GET_VL
> +.TP
> +.BR PR_SVE_GET_VL " (since Linux 4.15, only on arm64)"
> +Get the thread's current SVE vector length configuration.
> +.IP
> +Arguments
> +.IR arg2 ", " arg3 ", " arg4 " and " arg5
> +are ignored.
> +.IP
> +Providing that the kernel and platform support SVE
> +this operation always succeeds,
> +returning a nonnegative value that describes the
> +.I current
> +configuration.
> +The bits corresponding to
> +.B PR_SVE_VL_LEN_MASK
> +contain the currently configured vector length in bytes.
> +The bit corresponding to
> +.B PR_SVE_VL_INHERIT
> +indicates whether the vector length will be inherited
> +across
> +.BR execve (2).
> +.IP
> +Note that there is no way to determine whether there is
> +a pending vector length change that has not yet taken effect.
> +.IP
> +For more information, see the kernel source file
> +.I Documentation/arm64/sve.rst
> +.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed
> +(or
> +.I Documentation/arm64/sve.txt
> +before Linux 5.3).
>  .\"
>  .\" prctl PR_TASK_PERF_EVENTS_DISABLE
>  .TP
> @@ -1613,6 +1765,8 @@ On success,
>  .BR PR_GET_NO_NEW_PRIVS ,
>  .BR PR_GET_SECUREBITS ,
>  .BR PR_GET_SPECULATION_CTRL ,
> +.BR PR_SVE_GET_VL ,
> +.BR PR_SVE_SET_VL ,
>  .BR PR_GET_THP_DISABLE ,
>  .BR PR_GET_TIMING ,
>  .BR PR_GET_TIMERSLACK ,
> @@ -1904,6 +2058,22 @@ See the description of
>  .B PR_PAC_RESET_KEYS
>  above for details.
>  .TP
> +.B EINVAL
> +.I option
> +is
> +.B PR_SVE_SET_VL
> +and the arguments are invalid or unsupported,
> +or SVE is not available on this platform.
> +See the description of
> +.B PR_SVE_SET_VL
> +above for details.
> +.TP
> +.B EINVAL
> +.I option
> +is
> +.B PR_SVE_GET_VL
> +and SVE is not available on this platform.
> +.TP
>  .B ENODEV
>  .I option
>  was
> 


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

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

[PATCH v3 2/2] prctl.2: Add tagged address ABI control prctls (arm64)

[Dave Martin]

Add documentation for the the PR_SET_TAGGED_ADDR_CTRL and
PR_GET_TAGGED_ADDR_CTRL prctls added in Linux 5.4 for arm64.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
Reviewed-by: Catalin Marinas <catalin.marinas@arm.com>
Cc: Vincenzo Frascino <vincenzo.frascino@arm.com>

---

Kept Catalin's Reviewed-by, since the changes are pretty minor.

Changes since v2:

 * Clarified type of PR_SET_TAGGED_ADDR_CTRL arg2.

 * Added Linux commit where enforecement of zeroing reserved args was
   added for PR_SET_TAGGED_ADDR_CTRL.

 * Added explicit text regarding how to disable the tagged-address ABI
   globally through sysctl.

 * Rearrange the tagged argument syscall exclusion list so that shmdt()
   isn't called out specially.  The reader probably doesn't care about
   this history here.

 * Minor rewordings.
---
 man2/prctl.2 | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 161 insertions(+)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 46ea9d2..cf92f3b 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -1522,6 +1522,148 @@ For more information, see the kernel source file
 (or
 .I Documentation/arm64/sve.txt
 before Linux 5.3).
+.\" prctl PR_SET_TAGGED_ADDR_CTRL
+.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
+.TP
+.BR PR_SET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)"
+Controls support for passing tagged userspace addresses to the kernel
+(i.e., addresses where bits 56\(em63 are not all zero).
+.IP
+The level of support is selected by
+.IR "arg2" ,
+which can be one of the following:
+.RS
+.TP
+.B 0
+Addresses that are passed
+for the purpose of being dereferenced by the kernel
+must be untagged.
+.TP
+.B PR_TAGGED_ADDR_ENABLE
+Addresses that are passed
+for the purpose of being dereferenced by the kernel
+may be tagged, with the exceptions summarized below.
+.RE
+.IP
+The remaining arguments
+.IR arg3 ", " arg4 " and " arg5
+must all be zero.
+.\" Enforcement added in
+.\" commit 3e91ec89f527b9870fe42dcbdb74fd389d123a95
+.IP
+On success, the mode specified in
+.I arg2
+is set for the calling thread and the the return value is 0.
+If the arguments are invalid,
+the mode specified in
+.I arg2
+is unrecognized,
+or if this feature is unsupported by the kernel
+or disabled via
+.IR /proc/sys/abi/tagged_addr_disabled ,
+the call fails with
+.BR EINVAL .
+.IP
+In particular, if
+.BR prctl ( PR_SET_TAGGED_ADDR_CTRL ,
+0, 0, 0, 0)
+fails with
+.B EINVAL
+then all addresses passed to the kernel must be untagged.
+.IP
+Irrespective of which mode is set,
+addresses passed to certain interfaces
+must always be untagged:
+.RS
+.IP \(em
+.BR brk (2),
+.BR mmap (2),
+.BR shmat (2),
+.BR shmdt (2),
+and the
+.I new_address
+argument of
+.BR mremap (2).
+.IP
+(Prior to Linux 5.6 these accepted tagged addresses,
+but the behaviour may not be what you expect.
+Don't rely on it.)
+.IP \(em
+\(oqpolymorphic\(cq interfaces
+that accept pointers to arbitrary types cast to a
+.I void *
+or other generic type, specifically
+.BR prctl (2),
+.BR ioctl (2),
+and in general
+.BR setsockopt (2)
+(only certain specific
+.BR setsockopt (2)
+options allow tagged addresses).
+.RE
+.IP
+This list of exclusions may shrink
+when moving from one kernel version to a later kernel version.
+While the kernel may make some guarantees
+for backwards compatibility reasons,
+for the purposes of new software
+the effect of passing tagged addresses to these interfaces
+is unspecified.
+.IP
+The mode set by this call is inherited across
+.BR fork (2)
+and
+.BR clone (2).
+The mode is reset by
+.BR execve (2)
+to 0
+(i.e., tagged addresses not permitted in the user/kernel ABI).
+.IP
+For more information, see the kernel source file
+.IR Documentation/arm64/tagged\-address\-abi.rst .
+.IP
+.B Warning:
+This call is primarily intended for use by the run-time environment.
+A successful
+.B PR_SET_TAGGED_ADDR_CTRL
+call elsewhere may crash the calling process.
+The conditions for using it safely are complex and system-dependent;
+Don't use it unless you know what you are doing.
+.\" prctl PR_GET_TAGGED_ADDR_CTRL
+.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
+.TP
+.BR PR_GET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)"
+Returns the current tagged address mode
+for the calling thread.
+.IP
+Arguments
+.IR arg2 ", " arg3 ", " arg4 " and " arg5
+must all be zero.
+.IP
+If the arguments are invalid
+or this feature is disabled or unsupported by the kernel,
+the call fails with
+.BR EINVAL .
+In particular, if
+.BR prctl ( PR_GET_TAGGED_ADDR_CTRL ,
+0, 0, 0, 0)
+fails with
+.BR EINVAL ,
+then this feature is definitely either unsupported,
+or disabled via
+.IR /proc/sys/abi/tagged_addr_disabled .
+In this case,
+all addresses passed to the kernel must be untagged.
+.IP
+Otherwise, the call returns a nonnegative value
+describing the current tagged address mode,
+encoded in the same way as the
+.I arg2
+argument of
+.BR PR_SET_TAGGED_ADDR_CTRL .
+.IP
+For more information, see the kernel source file
+.IR Documentation/arm64/tagged\-address\-abi.rst .
 .\"
 .\" prctl PR_TASK_PERF_EVENTS_DISABLE
 .TP
@@ -1767,6 +1909,7 @@ On success,
 .BR PR_GET_SPECULATION_CTRL ,
 .BR PR_SVE_GET_VL ,
 .BR PR_SVE_SET_VL ,
+.BR PR_GET_TAGGED_ADDR_CTRL ,
 .BR PR_GET_THP_DISABLE ,
 .BR PR_GET_TIMING ,
 .BR PR_GET_TIMERSLACK ,
@@ -2074,6 +2217,24 @@ is
 .B PR_SVE_GET_VL
 and SVE is not available on this platform.
 .TP
+.B EINVAL
+.I option
+is
+.BR PR_SET_TAGGED_ADDR_CTRL
+and the arguments are invalid or unsupported.
+See the description of
+.B PR_SET_TAGGED_ADDR_CTRL
+above for details.
+.TP
+.B EINVAL
+.I option
+is
+.BR PR_GET_TAGGED_ADDR_CTRL
+and the arguments are invalid or unsupported.
+See the description of
+.B PR_GET_TAGGED_ADDR_CTRL
+above for details.
+.TP
 .B ENODEV
 .I option
 was
-- 
2.1.4

[PATCH v3 2/2] prctl.2: Add tagged address ABI control prctls (arm64)

[Dave Martin]

Add documentation for the the PR_SET_TAGGED_ADDR_CTRL and
PR_GET_TAGGED_ADDR_CTRL prctls added in Linux 5.4 for arm64.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
Reviewed-by: Catalin Marinas <catalin.marinas@arm.com>
Cc: Vincenzo Frascino <vincenzo.frascino@arm.com>

---

Kept Catalin's Reviewed-by, since the changes are pretty minor.

Changes since v2:

 * Clarified type of PR_SET_TAGGED_ADDR_CTRL arg2.

 * Added Linux commit where enforecement of zeroing reserved args was
   added for PR_SET_TAGGED_ADDR_CTRL.

 * Added explicit text regarding how to disable the tagged-address ABI
   globally through sysctl.

 * Rearrange the tagged argument syscall exclusion list so that shmdt()
   isn't called out specially.  The reader probably doesn't care about
   this history here.

 * Minor rewordings.
---
 man2/prctl.2 | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 161 insertions(+)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 46ea9d2..cf92f3b 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -1522,6 +1522,148 @@ For more information, see the kernel source file
 (or
 .I Documentation/arm64/sve.txt
 before Linux 5.3).
+.\" prctl PR_SET_TAGGED_ADDR_CTRL
+.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
+.TP
+.BR PR_SET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)"
+Controls support for passing tagged userspace addresses to the kernel
+(i.e., addresses where bits 56\(em63 are not all zero).
+.IP
+The level of support is selected by
+.IR "arg2" ,
+which can be one of the following:
+.RS
+.TP
+.B 0
+Addresses that are passed
+for the purpose of being dereferenced by the kernel
+must be untagged.
+.TP
+.B PR_TAGGED_ADDR_ENABLE
+Addresses that are passed
+for the purpose of being dereferenced by the kernel
+may be tagged, with the exceptions summarized below.
+.RE
+.IP
+The remaining arguments
+.IR arg3 ", " arg4 " and " arg5
+must all be zero.
+.\" Enforcement added in
+.\" commit 3e91ec89f527b9870fe42dcbdb74fd389d123a95
+.IP
+On success, the mode specified in
+.I arg2
+is set for the calling thread and the the return value is 0.
+If the arguments are invalid,
+the mode specified in
+.I arg2
+is unrecognized,
+or if this feature is unsupported by the kernel
+or disabled via
+.IR /proc/sys/abi/tagged_addr_disabled ,
+the call fails with
+.BR EINVAL .
+.IP
+In particular, if
+.BR prctl ( PR_SET_TAGGED_ADDR_CTRL ,
+0, 0, 0, 0)
+fails with
+.B EINVAL
+then all addresses passed to the kernel must be untagged.
+.IP
+Irrespective of which mode is set,
+addresses passed to certain interfaces
+must always be untagged:
+.RS
+.IP \(em
+.BR brk (2),
+.BR mmap (2),
+.BR shmat (2),
+.BR shmdt (2),
+and the
+.I new_address
+argument of
+.BR mremap (2).
+.IP
+(Prior to Linux 5.6 these accepted tagged addresses,
+but the behaviour may not be what you expect.
+Don't rely on it.)
+.IP \(em
+\(oqpolymorphic\(cq interfaces
+that accept pointers to arbitrary types cast to a
+.I void *
+or other generic type, specifically
+.BR prctl (2),
+.BR ioctl (2),
+and in general
+.BR setsockopt (2)
+(only certain specific
+.BR setsockopt (2)
+options allow tagged addresses).
+.RE
+.IP
+This list of exclusions may shrink
+when moving from one kernel version to a later kernel version.
+While the kernel may make some guarantees
+for backwards compatibility reasons,
+for the purposes of new software
+the effect of passing tagged addresses to these interfaces
+is unspecified.
+.IP
+The mode set by this call is inherited across
+.BR fork (2)
+and
+.BR clone (2).
+The mode is reset by
+.BR execve (2)
+to 0
+(i.e., tagged addresses not permitted in the user/kernel ABI).
+.IP
+For more information, see the kernel source file
+.IR Documentation/arm64/tagged\-address\-abi.rst .
+.IP
+.B Warning:
+This call is primarily intended for use by the run-time environment.
+A successful
+.B PR_SET_TAGGED_ADDR_CTRL
+call elsewhere may crash the calling process.
+The conditions for using it safely are complex and system-dependent;
+Don't use it unless you know what you are doing.
+.\" prctl PR_GET_TAGGED_ADDR_CTRL
+.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
+.TP
+.BR PR_GET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)"
+Returns the current tagged address mode
+for the calling thread.
+.IP
+Arguments
+.IR arg2 ", " arg3 ", " arg4 " and " arg5
+must all be zero.
+.IP
+If the arguments are invalid
+or this feature is disabled or unsupported by the kernel,
+the call fails with
+.BR EINVAL .
+In particular, if
+.BR prctl ( PR_GET_TAGGED_ADDR_CTRL ,
+0, 0, 0, 0)
+fails with
+.BR EINVAL ,
+then this feature is definitely either unsupported,
+or disabled via
+.IR /proc/sys/abi/tagged_addr_disabled .
+In this case,
+all addresses passed to the kernel must be untagged.
+.IP
+Otherwise, the call returns a nonnegative value
+describing the current tagged address mode,
+encoded in the same way as the
+.I arg2
+argument of
+.BR PR_SET_TAGGED_ADDR_CTRL .
+.IP
+For more information, see the kernel source file
+.IR Documentation/arm64/tagged\-address\-abi.rst .
 .\"
 .\" prctl PR_TASK_PERF_EVENTS_DISABLE
 .TP
@@ -1767,6 +1909,7 @@ On success,
 .BR PR_GET_SPECULATION_CTRL ,
 .BR PR_SVE_GET_VL ,
 .BR PR_SVE_SET_VL ,
+.BR PR_GET_TAGGED_ADDR_CTRL ,
 .BR PR_GET_THP_DISABLE ,
 .BR PR_GET_TIMING ,
 .BR PR_GET_TIMERSLACK ,
@@ -2074,6 +2217,24 @@ is
 .B PR_SVE_GET_VL
 and SVE is not available on this platform.
 .TP
+.B EINVAL
+.I option
+is
+.BR PR_SET_TAGGED_ADDR_CTRL
+and the arguments are invalid or unsupported.
+See the description of
+.B PR_SET_TAGGED_ADDR_CTRL
+above for details.
+.TP
+.B EINVAL
+.I option
+is
+.BR PR_GET_TAGGED_ADDR_CTRL
+and the arguments are invalid or unsupported.
+See the description of
+.B PR_GET_TAGGED_ADDR_CTRL
+above for details.
+.TP
 .B ENODEV
 .I option
 was
-- 
2.1.4


_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

[PATCH v3 2/2] prctl.2: Add tagged address ABI control prctls (arm64)

[Dave Martin]

Add documentation for the the PR_SET_TAGGED_ADDR_CTRL and
PR_GET_TAGGED_ADDR_CTRL prctls added in Linux 5.4 for arm64.

Signed-off-by: Dave Martin <Dave.Martin-5wv7dgnIgG8@public.gmane.org>
Reviewed-by: Catalin Marinas <catalin.marinas-5wv7dgnIgG8@public.gmane.org>
Cc: Vincenzo Frascino <vincenzo.frascino-5wv7dgnIgG8@public.gmane.org>

---

Kept Catalin's Reviewed-by, since the changes are pretty minor.

Changes since v2:

 * Clarified type of PR_SET_TAGGED_ADDR_CTRL arg2.

 * Added Linux commit where enforecement of zeroing reserved args was
   added for PR_SET_TAGGED_ADDR_CTRL.

 * Added explicit text regarding how to disable the tagged-address ABI
   globally through sysctl.

 * Rearrange the tagged argument syscall exclusion list so that shmdt()
   isn't called out specially.  The reader probably doesn't care about
   this history here.

 * Minor rewordings.
---
 man2/prctl.2 | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 161 insertions(+)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 46ea9d2..cf92f3b 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -1522,6 +1522,148 @@ For more information, see the kernel source file
 (or
 .I Documentation/arm64/sve.txt
 before Linux 5.3).
+.\" prctl PR_SET_TAGGED_ADDR_CTRL
+.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
+.TP
+.BR PR_SET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)"
+Controls support for passing tagged userspace addresses to the kernel
+(i.e., addresses where bits 56\(em63 are not all zero).
+.IP
+The level of support is selected by
+.IR "arg2" ,
+which can be one of the following:
+.RS
+.TP
+.B 0
+Addresses that are passed
+for the purpose of being dereferenced by the kernel
+must be untagged.
+.TP
+.B PR_TAGGED_ADDR_ENABLE
+Addresses that are passed
+for the purpose of being dereferenced by the kernel
+may be tagged, with the exceptions summarized below.
+.RE
+.IP
+The remaining arguments
+.IR arg3 ", " arg4 " and " arg5
+must all be zero.
+.\" Enforcement added in
+.\" commit 3e91ec89f527b9870fe42dcbdb74fd389d123a95
+.IP
+On success, the mode specified in
+.I arg2
+is set for the calling thread and the the return value is 0.
+If the arguments are invalid,
+the mode specified in
+.I arg2
+is unrecognized,
+or if this feature is unsupported by the kernel
+or disabled via
+.IR /proc/sys/abi/tagged_addr_disabled ,
+the call fails with
+.BR EINVAL .
+.IP
+In particular, if
+.BR prctl ( PR_SET_TAGGED_ADDR_CTRL ,
+0, 0, 0, 0)
+fails with
+.B EINVAL
+then all addresses passed to the kernel must be untagged.
+.IP
+Irrespective of which mode is set,
+addresses passed to certain interfaces
+must always be untagged:
+.RS
+.IP \(em
+.BR brk (2),
+.BR mmap (2),
+.BR shmat (2),
+.BR shmdt (2),
+and the
+.I new_address
+argument of
+.BR mremap (2).
+.IP
+(Prior to Linux 5.6 these accepted tagged addresses,
+but the behaviour may not be what you expect.
+Don't rely on it.)
+.IP \(em
+\(oqpolymorphic\(cq interfaces
+that accept pointers to arbitrary types cast to a
+.I void *
+or other generic type, specifically
+.BR prctl (2),
+.BR ioctl (2),
+and in general
+.BR setsockopt (2)
+(only certain specific
+.BR setsockopt (2)
+options allow tagged addresses).
+.RE
+.IP
+This list of exclusions may shrink
+when moving from one kernel version to a later kernel version.
+While the kernel may make some guarantees
+for backwards compatibility reasons,
+for the purposes of new software
+the effect of passing tagged addresses to these interfaces
+is unspecified.
+.IP
+The mode set by this call is inherited across
+.BR fork (2)
+and
+.BR clone (2).
+The mode is reset by
+.BR execve (2)
+to 0
+(i.e., tagged addresses not permitted in the user/kernel ABI).
+.IP
+For more information, see the kernel source file
+.IR Documentation/arm64/tagged\-address\-abi.rst .
+.IP
+.B Warning:
+This call is primarily intended for use by the run-time environment.
+A successful
+.B PR_SET_TAGGED_ADDR_CTRL
+call elsewhere may crash the calling process.
+The conditions for using it safely are complex and system-dependent;
+Don't use it unless you know what you are doing.
+.\" prctl PR_GET_TAGGED_ADDR_CTRL
+.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
+.TP
+.BR PR_GET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)"
+Returns the current tagged address mode
+for the calling thread.
+.IP
+Arguments
+.IR arg2 ", " arg3 ", " arg4 " and " arg5
+must all be zero.
+.IP
+If the arguments are invalid
+or this feature is disabled or unsupported by the kernel,
+the call fails with
+.BR EINVAL .
+In particular, if
+.BR prctl ( PR_GET_TAGGED_ADDR_CTRL ,
+0, 0, 0, 0)
+fails with
+.BR EINVAL ,
+then this feature is definitely either unsupported,
+or disabled via
+.IR /proc/sys/abi/tagged_addr_disabled .
+In this case,
+all addresses passed to the kernel must be untagged.
+.IP
+Otherwise, the call returns a nonnegative value
+describing the current tagged address mode,
+encoded in the same way as the
+.I arg2
+argument of
+.BR PR_SET_TAGGED_ADDR_CTRL .
+.IP
+For more information, see the kernel source file
+.IR Documentation/arm64/tagged\-address\-abi.rst .
 .\"
 .\" prctl PR_TASK_PERF_EVENTS_DISABLE
 .TP
@@ -1767,6 +1909,7 @@ On success,
 .BR PR_GET_SPECULATION_CTRL ,
 .BR PR_SVE_GET_VL ,
 .BR PR_SVE_SET_VL ,
+.BR PR_GET_TAGGED_ADDR_CTRL ,
 .BR PR_GET_THP_DISABLE ,
 .BR PR_GET_TIMING ,
 .BR PR_GET_TIMERSLACK ,
@@ -2074,6 +2217,24 @@ is
 .B PR_SVE_GET_VL
 and SVE is not available on this platform.
 .TP
+.B EINVAL
+.I option
+is
+.BR PR_SET_TAGGED_ADDR_CTRL
+and the arguments are invalid or unsupported.
+See the description of
+.B PR_SET_TAGGED_ADDR_CTRL
+above for details.
+.TP
+.B EINVAL
+.I option
+is
+.BR PR_GET_TAGGED_ADDR_CTRL
+and the arguments are invalid or unsupported.
+See the description of
+.B PR_GET_TAGGED_ADDR_CTRL
+above for details.
+.TP
 .B ENODEV
 .I option
 was
-- 
2.1.4

Re: [PATCH v3 2/2] prctl.2: Add tagged address ABI control prctls (arm64)

[Michael Kerrisk (man-pages)]

Hi Dave,

On 6/24/20 7:36 PM, Dave Martin wrote:
> Add documentation for the the PR_SET_TAGGED_ADDR_CTRL and
> PR_GET_TAGGED_ADDR_CTRL prctls added in Linux 5.4 for arm64.
> 
> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> Reviewed-by: Catalin Marinas <catalin.marinas@arm.com>
> Cc: Vincenzo Frascino <vincenzo.frascino@arm.com>

Thanks for another nicely written patch! I've applied locally, 
but won't push just yet, to allow for some (more) reviews/acks
to come in.

Thanks,

Michael

> ---
> 
> Kept Catalin's Reviewed-by, since the changes are pretty minor.
> 
> Changes since v2:
> 
>  * Clarified type of PR_SET_TAGGED_ADDR_CTRL arg2.
> 
>  * Added Linux commit where enforecement of zeroing reserved args was
>    added for PR_SET_TAGGED_ADDR_CTRL.
> 
>  * Added explicit text regarding how to disable the tagged-address ABI
>    globally through sysctl.
> 
>  * Rearrange the tagged argument syscall exclusion list so that shmdt()
>    isn't called out specially.  The reader probably doesn't care about
>    this history here.
> 
>  * Minor rewordings.
> ---
>  man2/prctl.2 | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 161 insertions(+)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 46ea9d2..cf92f3b 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -1522,6 +1522,148 @@ For more information, see the kernel source file
>  (or
>  .I Documentation/arm64/sve.txt
>  before Linux 5.3).
> +.\" prctl PR_SET_TAGGED_ADDR_CTRL
> +.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
> +.TP
> +.BR PR_SET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)"
> +Controls support for passing tagged userspace addresses to the kernel
> +(i.e., addresses where bits 56\(em63 are not all zero).
> +.IP
> +The level of support is selected by
> +.IR "arg2" ,
> +which can be one of the following:
> +.RS
> +.TP
> +.B 0
> +Addresses that are passed
> +for the purpose of being dereferenced by the kernel
> +must be untagged.
> +.TP
> +.B PR_TAGGED_ADDR_ENABLE
> +Addresses that are passed
> +for the purpose of being dereferenced by the kernel
> +may be tagged, with the exceptions summarized below.
> +.RE
> +.IP
> +The remaining arguments
> +.IR arg3 ", " arg4 " and " arg5
> +must all be zero.
> +.\" Enforcement added in
> +.\" commit 3e91ec89f527b9870fe42dcbdb74fd389d123a95
> +.IP
> +On success, the mode specified in
> +.I arg2
> +is set for the calling thread and the the return value is 0.
> +If the arguments are invalid,
> +the mode specified in
> +.I arg2
> +is unrecognized,
> +or if this feature is unsupported by the kernel
> +or disabled via
> +.IR /proc/sys/abi/tagged_addr_disabled ,
> +the call fails with
> +.BR EINVAL .
> +.IP
> +In particular, if
> +.BR prctl ( PR_SET_TAGGED_ADDR_CTRL ,
> +0, 0, 0, 0)
> +fails with
> +.B EINVAL
> +then all addresses passed to the kernel must be untagged.
> +.IP
> +Irrespective of which mode is set,
> +addresses passed to certain interfaces
> +must always be untagged:
> +.RS
> +.IP \(em
> +.BR brk (2),
> +.BR mmap (2),
> +.BR shmat (2),
> +.BR shmdt (2),
> +and the
> +.I new_address
> +argument of
> +.BR mremap (2).
> +.IP
> +(Prior to Linux 5.6 these accepted tagged addresses,
> +but the behaviour may not be what you expect.
> +Don't rely on it.)
> +.IP \(em
> +\(oqpolymorphic\(cq interfaces
> +that accept pointers to arbitrary types cast to a
> +.I void *
> +or other generic type, specifically
> +.BR prctl (2),
> +.BR ioctl (2),
> +and in general
> +.BR setsockopt (2)
> +(only certain specific
> +.BR setsockopt (2)
> +options allow tagged addresses).
> +.RE
> +.IP
> +This list of exclusions may shrink
> +when moving from one kernel version to a later kernel version.
> +While the kernel may make some guarantees
> +for backwards compatibility reasons,
> +for the purposes of new software
> +the effect of passing tagged addresses to these interfaces
> +is unspecified.
> +.IP
> +The mode set by this call is inherited across
> +.BR fork (2)
> +and
> +.BR clone (2).
> +The mode is reset by
> +.BR execve (2)
> +to 0
> +(i.e., tagged addresses not permitted in the user/kernel ABI).
> +.IP
> +For more information, see the kernel source file
> +.IR Documentation/arm64/tagged\-address\-abi.rst .
> +.IP
> +.B Warning:
> +This call is primarily intended for use by the run-time environment.
> +A successful
> +.B PR_SET_TAGGED_ADDR_CTRL
> +call elsewhere may crash the calling process.
> +The conditions for using it safely are complex and system-dependent;
> +Don't use it unless you know what you are doing.
> +.\" prctl PR_GET_TAGGED_ADDR_CTRL
> +.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
> +.TP
> +.BR PR_GET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)"
> +Returns the current tagged address mode
> +for the calling thread.
> +.IP
> +Arguments
> +.IR arg2 ", " arg3 ", " arg4 " and " arg5
> +must all be zero.
> +.IP
> +If the arguments are invalid
> +or this feature is disabled or unsupported by the kernel,
> +the call fails with
> +.BR EINVAL .
> +In particular, if
> +.BR prctl ( PR_GET_TAGGED_ADDR_CTRL ,
> +0, 0, 0, 0)
> +fails with
> +.BR EINVAL ,
> +then this feature is definitely either unsupported,
> +or disabled via
> +.IR /proc/sys/abi/tagged_addr_disabled .
> +In this case,
> +all addresses passed to the kernel must be untagged.
> +.IP
> +Otherwise, the call returns a nonnegative value
> +describing the current tagged address mode,
> +encoded in the same way as the
> +.I arg2
> +argument of
> +.BR PR_SET_TAGGED_ADDR_CTRL .
> +.IP
> +For more information, see the kernel source file
> +.IR Documentation/arm64/tagged\-address\-abi.rst .
>  .\"
>  .\" prctl PR_TASK_PERF_EVENTS_DISABLE
>  .TP
> @@ -1767,6 +1909,7 @@ On success,
>  .BR PR_GET_SPECULATION_CTRL ,
>  .BR PR_SVE_GET_VL ,
>  .BR PR_SVE_SET_VL ,
> +.BR PR_GET_TAGGED_ADDR_CTRL ,
>  .BR PR_GET_THP_DISABLE ,
>  .BR PR_GET_TIMING ,
>  .BR PR_GET_TIMERSLACK ,
> @@ -2074,6 +2217,24 @@ is
>  .B PR_SVE_GET_VL
>  and SVE is not available on this platform.
>  .TP
> +.B EINVAL
> +.I option
> +is
> +.BR PR_SET_TAGGED_ADDR_CTRL
> +and the arguments are invalid or unsupported.
> +See the description of
> +.B PR_SET_TAGGED_ADDR_CTRL
> +above for details.
> +.TP
> +.B EINVAL
> +.I option
> +is
> +.BR PR_GET_TAGGED_ADDR_CTRL
> +and the arguments are invalid or unsupported.
> +See the description of
> +.B PR_GET_TAGGED_ADDR_CTRL
> +above for details.
> +.TP
>  .B ENODEV
>  .I option
>  was
> 


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

Re: [PATCH v3 2/2] prctl.2: Add tagged address ABI control prctls (arm64)

[Michael Kerrisk (man-pages)]

Hi Dave,

On 6/24/20 7:36 PM, Dave Martin wrote:
> Add documentation for the the PR_SET_TAGGED_ADDR_CTRL and
> PR_GET_TAGGED_ADDR_CTRL prctls added in Linux 5.4 for arm64.
> 
> Signed-off-by: Dave Martin <Dave.Martin@arm.com>
> Reviewed-by: Catalin Marinas <catalin.marinas@arm.com>
> Cc: Vincenzo Frascino <vincenzo.frascino@arm.com>

Thanks for another nicely written patch! I've applied locally, 
but won't push just yet, to allow for some (more) reviews/acks
to come in.

Thanks,

Michael

> ---
> 
> Kept Catalin's Reviewed-by, since the changes are pretty minor.
> 
> Changes since v2:
> 
>  * Clarified type of PR_SET_TAGGED_ADDR_CTRL arg2.
> 
>  * Added Linux commit where enforecement of zeroing reserved args was
>    added for PR_SET_TAGGED_ADDR_CTRL.
> 
>  * Added explicit text regarding how to disable the tagged-address ABI
>    globally through sysctl.
> 
>  * Rearrange the tagged argument syscall exclusion list so that shmdt()
>    isn't called out specially.  The reader probably doesn't care about
>    this history here.
> 
>  * Minor rewordings.
> ---
>  man2/prctl.2 | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 161 insertions(+)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 46ea9d2..cf92f3b 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -1522,6 +1522,148 @@ For more information, see the kernel source file
>  (or
>  .I Documentation/arm64/sve.txt
>  before Linux 5.3).
> +.\" prctl PR_SET_TAGGED_ADDR_CTRL
> +.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
> +.TP
> +.BR PR_SET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)"
> +Controls support for passing tagged userspace addresses to the kernel
> +(i.e., addresses where bits 56\(em63 are not all zero).
> +.IP
> +The level of support is selected by
> +.IR "arg2" ,
> +which can be one of the following:
> +.RS
> +.TP
> +.B 0
> +Addresses that are passed
> +for the purpose of being dereferenced by the kernel
> +must be untagged.
> +.TP
> +.B PR_TAGGED_ADDR_ENABLE
> +Addresses that are passed
> +for the purpose of being dereferenced by the kernel
> +may be tagged, with the exceptions summarized below.
> +.RE
> +.IP
> +The remaining arguments
> +.IR arg3 ", " arg4 " and " arg5
> +must all be zero.
> +.\" Enforcement added in
> +.\" commit 3e91ec89f527b9870fe42dcbdb74fd389d123a95
> +.IP
> +On success, the mode specified in
> +.I arg2
> +is set for the calling thread and the the return value is 0.
> +If the arguments are invalid,
> +the mode specified in
> +.I arg2
> +is unrecognized,
> +or if this feature is unsupported by the kernel
> +or disabled via
> +.IR /proc/sys/abi/tagged_addr_disabled ,
> +the call fails with
> +.BR EINVAL .
> +.IP
> +In particular, if
> +.BR prctl ( PR_SET_TAGGED_ADDR_CTRL ,
> +0, 0, 0, 0)
> +fails with
> +.B EINVAL
> +then all addresses passed to the kernel must be untagged.
> +.IP
> +Irrespective of which mode is set,
> +addresses passed to certain interfaces
> +must always be untagged:
> +.RS
> +.IP \(em
> +.BR brk (2),
> +.BR mmap (2),
> +.BR shmat (2),
> +.BR shmdt (2),
> +and the
> +.I new_address
> +argument of
> +.BR mremap (2).
> +.IP
> +(Prior to Linux 5.6 these accepted tagged addresses,
> +but the behaviour may not be what you expect.
> +Don't rely on it.)
> +.IP \(em
> +\(oqpolymorphic\(cq interfaces
> +that accept pointers to arbitrary types cast to a
> +.I void *
> +or other generic type, specifically
> +.BR prctl (2),
> +.BR ioctl (2),
> +and in general
> +.BR setsockopt (2)
> +(only certain specific
> +.BR setsockopt (2)
> +options allow tagged addresses).
> +.RE
> +.IP
> +This list of exclusions may shrink
> +when moving from one kernel version to a later kernel version.
> +While the kernel may make some guarantees
> +for backwards compatibility reasons,
> +for the purposes of new software
> +the effect of passing tagged addresses to these interfaces
> +is unspecified.
> +.IP
> +The mode set by this call is inherited across
> +.BR fork (2)
> +and
> +.BR clone (2).
> +The mode is reset by
> +.BR execve (2)
> +to 0
> +(i.e., tagged addresses not permitted in the user/kernel ABI).
> +.IP
> +For more information, see the kernel source file
> +.IR Documentation/arm64/tagged\-address\-abi.rst .
> +.IP
> +.B Warning:
> +This call is primarily intended for use by the run-time environment.
> +A successful
> +.B PR_SET_TAGGED_ADDR_CTRL
> +call elsewhere may crash the calling process.
> +The conditions for using it safely are complex and system-dependent;
> +Don't use it unless you know what you are doing.
> +.\" prctl PR_GET_TAGGED_ADDR_CTRL
> +.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
> +.TP
> +.BR PR_GET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)"
> +Returns the current tagged address mode
> +for the calling thread.
> +.IP
> +Arguments
> +.IR arg2 ", " arg3 ", " arg4 " and " arg5
> +must all be zero.
> +.IP
> +If the arguments are invalid
> +or this feature is disabled or unsupported by the kernel,
> +the call fails with
> +.BR EINVAL .
> +In particular, if
> +.BR prctl ( PR_GET_TAGGED_ADDR_CTRL ,
> +0, 0, 0, 0)
> +fails with
> +.BR EINVAL ,
> +then this feature is definitely either unsupported,
> +or disabled via
> +.IR /proc/sys/abi/tagged_addr_disabled .
> +In this case,
> +all addresses passed to the kernel must be untagged.
> +.IP
> +Otherwise, the call returns a nonnegative value
> +describing the current tagged address mode,
> +encoded in the same way as the
> +.I arg2
> +argument of
> +.BR PR_SET_TAGGED_ADDR_CTRL .
> +.IP
> +For more information, see the kernel source file
> +.IR Documentation/arm64/tagged\-address\-abi.rst .
>  .\"
>  .\" prctl PR_TASK_PERF_EVENTS_DISABLE
>  .TP
> @@ -1767,6 +1909,7 @@ On success,
>  .BR PR_GET_SPECULATION_CTRL ,
>  .BR PR_SVE_GET_VL ,
>  .BR PR_SVE_SET_VL ,
> +.BR PR_GET_TAGGED_ADDR_CTRL ,
>  .BR PR_GET_THP_DISABLE ,
>  .BR PR_GET_TIMING ,
>  .BR PR_GET_TIMERSLACK ,
> @@ -2074,6 +2217,24 @@ is
>  .B PR_SVE_GET_VL
>  and SVE is not available on this platform.
>  .TP
> +.B EINVAL
> +.I option
> +is
> +.BR PR_SET_TAGGED_ADDR_CTRL
> +and the arguments are invalid or unsupported.
> +See the description of
> +.B PR_SET_TAGGED_ADDR_CTRL
> +above for details.
> +.TP
> +.B EINVAL
> +.I option
> +is
> +.BR PR_GET_TAGGED_ADDR_CTRL
> +and the arguments are invalid or unsupported.
> +See the description of
> +.B PR_GET_TAGGED_ADDR_CTRL
> +above for details.
> +.TP
>  .B ENODEV
>  .I option
>  was
> 


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

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

Re: [PATCH v3 2/2] prctl.2: Add tagged address ABI control prctls (arm64)

[Michael Kerrisk (man-pages)]

Hi Dave,

On 6/24/20 7:36 PM, Dave Martin wrote:
> Add documentation for the the PR_SET_TAGGED_ADDR_CTRL and
> PR_GET_TAGGED_ADDR_CTRL prctls added in Linux 5.4 for arm64.
> 
> Signed-off-by: Dave Martin <Dave.Martin-5wv7dgnIgG8@public.gmane.org>
> Reviewed-by: Catalin Marinas <catalin.marinas-5wv7dgnIgG8@public.gmane.org>
> Cc: Vincenzo Frascino <vincenzo.frascino-5wv7dgnIgG8@public.gmane.org>

Thanks for another nicely written patch! I've applied locally, 
but won't push just yet, to allow for some (more) reviews/acks
to come in.

Thanks,

Michael

> ---
> 
> Kept Catalin's Reviewed-by, since the changes are pretty minor.
> 
> Changes since v2:
> 
>  * Clarified type of PR_SET_TAGGED_ADDR_CTRL arg2.
> 
>  * Added Linux commit where enforecement of zeroing reserved args was
>    added for PR_SET_TAGGED_ADDR_CTRL.
> 
>  * Added explicit text regarding how to disable the tagged-address ABI
>    globally through sysctl.
> 
>  * Rearrange the tagged argument syscall exclusion list so that shmdt()
>    isn't called out specially.  The reader probably doesn't care about
>    this history here.
> 
>  * Minor rewordings.
> ---
>  man2/prctl.2 | 161 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 161 insertions(+)
> 
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index 46ea9d2..cf92f3b 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -1522,6 +1522,148 @@ For more information, see the kernel source file
>  (or
>  .I Documentation/arm64/sve.txt
>  before Linux 5.3).
> +.\" prctl PR_SET_TAGGED_ADDR_CTRL
> +.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
> +.TP
> +.BR PR_SET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)"
> +Controls support for passing tagged userspace addresses to the kernel
> +(i.e., addresses where bits 56\(em63 are not all zero).
> +.IP
> +The level of support is selected by
> +.IR "arg2" ,
> +which can be one of the following:
> +.RS
> +.TP
> +.B 0
> +Addresses that are passed
> +for the purpose of being dereferenced by the kernel
> +must be untagged.
> +.TP
> +.B PR_TAGGED_ADDR_ENABLE
> +Addresses that are passed
> +for the purpose of being dereferenced by the kernel
> +may be tagged, with the exceptions summarized below.
> +.RE
> +.IP
> +The remaining arguments
> +.IR arg3 ", " arg4 " and " arg5
> +must all be zero.
> +.\" Enforcement added in
> +.\" commit 3e91ec89f527b9870fe42dcbdb74fd389d123a95
> +.IP
> +On success, the mode specified in
> +.I arg2
> +is set for the calling thread and the the return value is 0.
> +If the arguments are invalid,
> +the mode specified in
> +.I arg2
> +is unrecognized,
> +or if this feature is unsupported by the kernel
> +or disabled via
> +.IR /proc/sys/abi/tagged_addr_disabled ,
> +the call fails with
> +.BR EINVAL .
> +.IP
> +In particular, if
> +.BR prctl ( PR_SET_TAGGED_ADDR_CTRL ,
> +0, 0, 0, 0)
> +fails with
> +.B EINVAL
> +then all addresses passed to the kernel must be untagged.
> +.IP
> +Irrespective of which mode is set,
> +addresses passed to certain interfaces
> +must always be untagged:
> +.RS
> +.IP \(em
> +.BR brk (2),
> +.BR mmap (2),
> +.BR shmat (2),
> +.BR shmdt (2),
> +and the
> +.I new_address
> +argument of
> +.BR mremap (2).
> +.IP
> +(Prior to Linux 5.6 these accepted tagged addresses,
> +but the behaviour may not be what you expect.
> +Don't rely on it.)
> +.IP \(em
> +\(oqpolymorphic\(cq interfaces
> +that accept pointers to arbitrary types cast to a
> +.I void *
> +or other generic type, specifically
> +.BR prctl (2),
> +.BR ioctl (2),
> +and in general
> +.BR setsockopt (2)
> +(only certain specific
> +.BR setsockopt (2)
> +options allow tagged addresses).
> +.RE
> +.IP
> +This list of exclusions may shrink
> +when moving from one kernel version to a later kernel version.
> +While the kernel may make some guarantees
> +for backwards compatibility reasons,
> +for the purposes of new software
> +the effect of passing tagged addresses to these interfaces
> +is unspecified.
> +.IP
> +The mode set by this call is inherited across
> +.BR fork (2)
> +and
> +.BR clone (2).
> +The mode is reset by
> +.BR execve (2)
> +to 0
> +(i.e., tagged addresses not permitted in the user/kernel ABI).
> +.IP
> +For more information, see the kernel source file
> +.IR Documentation/arm64/tagged\-address\-abi.rst .
> +.IP
> +.B Warning:
> +This call is primarily intended for use by the run-time environment.
> +A successful
> +.B PR_SET_TAGGED_ADDR_CTRL
> +call elsewhere may crash the calling process.
> +The conditions for using it safely are complex and system-dependent;
> +Don't use it unless you know what you are doing.
> +.\" prctl PR_GET_TAGGED_ADDR_CTRL
> +.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
> +.TP
> +.BR PR_GET_TAGGED_ADDR_CTRL " (since Linux 5.4, only on arm64)"
> +Returns the current tagged address mode
> +for the calling thread.
> +.IP
> +Arguments
> +.IR arg2 ", " arg3 ", " arg4 " and " arg5
> +must all be zero.
> +.IP
> +If the arguments are invalid
> +or this feature is disabled or unsupported by the kernel,
> +the call fails with
> +.BR EINVAL .
> +In particular, if
> +.BR prctl ( PR_GET_TAGGED_ADDR_CTRL ,
> +0, 0, 0, 0)
> +fails with
> +.BR EINVAL ,
> +then this feature is definitely either unsupported,
> +or disabled via
> +.IR /proc/sys/abi/tagged_addr_disabled .
> +In this case,
> +all addresses passed to the kernel must be untagged.
> +.IP
> +Otherwise, the call returns a nonnegative value
> +describing the current tagged address mode,
> +encoded in the same way as the
> +.I arg2
> +argument of
> +.BR PR_SET_TAGGED_ADDR_CTRL .
> +.IP
> +For more information, see the kernel source file
> +.IR Documentation/arm64/tagged\-address\-abi.rst .
>  .\"
>  .\" prctl PR_TASK_PERF_EVENTS_DISABLE
>  .TP
> @@ -1767,6 +1909,7 @@ On success,
>  .BR PR_GET_SPECULATION_CTRL ,
>  .BR PR_SVE_GET_VL ,
>  .BR PR_SVE_SET_VL ,
> +.BR PR_GET_TAGGED_ADDR_CTRL ,
>  .BR PR_GET_THP_DISABLE ,
>  .BR PR_GET_TIMING ,
>  .BR PR_GET_TIMERSLACK ,
> @@ -2074,6 +2217,24 @@ is
>  .B PR_SVE_GET_VL
>  and SVE is not available on this platform.
>  .TP
> +.B EINVAL
> +.I option
> +is
> +.BR PR_SET_TAGGED_ADDR_CTRL
> +and the arguments are invalid or unsupported.
> +See the description of
> +.B PR_SET_TAGGED_ADDR_CTRL
> +above for details.
> +.TP
> +.B EINVAL
> +.I option
> +is
> +.BR PR_GET_TAGGED_ADDR_CTRL
> +and the arguments are invalid or unsupported.
> +See the description of
> +.B PR_GET_TAGGED_ADDR_CTRL
> +above for details.
> +.TP
>  .B ENODEV
>  .I option
>  was
> 


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

Re: [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6

[Michael Kerrisk (man-pages)]

Hi Dave,

On 6/24/20 7:36 PM, Dave Martin wrote:
> A bunch of updates to the prctl(2) man page to fill in missing
> prctls (mostly) up to Linux 5.6 (along with a few other tweaks and
> fixes).
> 
> Patches from the v2 series [1] that have been applied or rejected
> already have been dropped.
> 
> All that remain here now are the SVE and tagged address ABI controls
> for arm64.
> 
> 
> 
> [1] https://lore.kernel.org/linux-man/1590614258-24728-1-git-send-email-Dave.Martin@arm.com/
> 
> 
> Dave Martin (2):
>   prctl.2: Add SVE prctls (arm64)
>   prctl.2: Add tagged address ABI control prctls (arm64)
> 
>  man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 331 insertions(+)
Thanks. I've pushed these changes to master now.

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 v3 0/2] prctl.2 man page updates for Linux 5.6

[Michael Kerrisk (man-pages)]

Hi Dave,

On 6/24/20 7:36 PM, Dave Martin wrote:
> A bunch of updates to the prctl(2) man page to fill in missing
> prctls (mostly) up to Linux 5.6 (along with a few other tweaks and
> fixes).
> 
> Patches from the v2 series [1] that have been applied or rejected
> already have been dropped.
> 
> All that remain here now are the SVE and tagged address ABI controls
> for arm64.
> 
> 
> 
> [1] https://lore.kernel.org/linux-man/1590614258-24728-1-git-send-email-Dave.Martin@arm.com/
> 
> 
> Dave Martin (2):
>   prctl.2: Add SVE prctls (arm64)
>   prctl.2: Add tagged address ABI control prctls (arm64)
> 
>  man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 331 insertions(+)
Thanks. I've pushed these changes to master now.

Cheers,

Michael



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

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

Re: [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6

[Michael Kerrisk (man-pages)]

Hi Dave,

On 6/24/20 7:36 PM, Dave Martin wrote:
> A bunch of updates to the prctl(2) man page to fill in missing
> prctls (mostly) up to Linux 5.6 (along with a few other tweaks and
> fixes).
> 
> Patches from the v2 series [1] that have been applied or rejected
> already have been dropped.
> 
> All that remain here now are the SVE and tagged address ABI controls
> for arm64.
> 
> 
> 
> [1] https://lore.kernel.org/linux-man/1590614258-24728-1-git-send-email-Dave.Martin-5wv7dgnIgG8@public.gmane.org/
> 
> 
> Dave Martin (2):
>   prctl.2: Add SVE prctls (arm64)
>   prctl.2: Add tagged address ABI control prctls (arm64)
> 
>  man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 331 insertions(+)
Thanks. I've pushed these changes to master now.

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 v3 0/2] prctl.2 man page updates for Linux 5.6

[Dave Martin]

On Mon, Jun 29, 2020 at 01:52:24PM +0200, Michael Kerrisk (man-pages) wrote:
> Hi Dave,
> 
> On 6/24/20 7:36 PM, Dave Martin wrote:
> > A bunch of updates to the prctl(2) man page to fill in missing
> > prctls (mostly) up to Linux 5.6 (along with a few other tweaks and
> > fixes).
> > 
> > Patches from the v2 series [1] that have been applied or rejected
> > already have been dropped.
> > 
> > All that remain here now are the SVE and tagged address ABI controls
> > for arm64.
> > 
> > 
> > 
> > [1] https://lore.kernel.org/linux-man/1590614258-24728-1-git-send-email-Dave.Martin@arm.com/
> > 
> > 
> > Dave Martin (2):
> >   prctl.2: Add SVE prctls (arm64)
> >   prctl.2: Add tagged address ABI control prctls (arm64)
> > 
> >  man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 331 insertions(+)
> Thanks. I've pushed these changes to master now.

Thanks -- btw I finally got around to reviewing master, and noted a few
editorial changes that man-pages(7) does not make any statement about:

"arg1, arg2, and arg3"

	Do you strictly prefer the command before "and" here?

	Conventionally, the final comma would typically be omitted in
	prose, except where the list members are complex enough that the
	command is required to assist parsing.  However, lists of formal
	arguments are not quite vanilla prose.

"Providing that" -> "Provided that"

	Any particular rationale here?

"error EFOO" -> "the error EFOO"

	Is this a rule, in general?

.IP \(bu 2

	I assumed that specifying an explicit indentation amount would
	be fragile.  Going with the default behaviour also tends to
	result in a more consistent appearance.  Do you have any
	recommandations in this area?

	Do you have rules about the order to use bullet symbols?  I tend
	to avoid \(bu if possible, since while it's "correct", nroff can
	render it nastily as an unadorned letter "o" (e.g., with -Tascii
	or LC_CTYPE=C).  This is particlarly annoying if the indent is
	<= 2, since then the "o" tends to be visually swallowed by the
	following text (i.e., to a casual glance it looks like a word,
	particlarly if the following text is not capitalised).  Perhaps
	this is a bad glyph substitution decision in nroff rather than
	something that should be fixed in the man-pages source, but the
	man-pages source may be easier to fix...
	
	There is already inconsistency here: there are may top-level
	lists using ".IP *" in prctl.2, and plenty of places where the
	default indentation is used.


Should any of these be written up in man-pages(7), or is there a checker
than can detect them?

I wan't to minimise the amount of tweaking you have to do when merging
patches.

Cheers
---Dave

Re: [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6

[Dave Martin]

On Mon, Jun 29, 2020 at 01:52:24PM +0200, Michael Kerrisk (man-pages) wrote:
> Hi Dave,
> 
> On 6/24/20 7:36 PM, Dave Martin wrote:
> > A bunch of updates to the prctl(2) man page to fill in missing
> > prctls (mostly) up to Linux 5.6 (along with a few other tweaks and
> > fixes).
> > 
> > Patches from the v2 series [1] that have been applied or rejected
> > already have been dropped.
> > 
> > All that remain here now are the SVE and tagged address ABI controls
> > for arm64.
> > 
> > 
> > 
> > [1] https://lore.kernel.org/linux-man/1590614258-24728-1-git-send-email-Dave.Martin@arm.com/
> > 
> > 
> > Dave Martin (2):
> >   prctl.2: Add SVE prctls (arm64)
> >   prctl.2: Add tagged address ABI control prctls (arm64)
> > 
> >  man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 331 insertions(+)
> Thanks. I've pushed these changes to master now.

Thanks -- btw I finally got around to reviewing master, and noted a few
editorial changes that man-pages(7) does not make any statement about:

"arg1, arg2, and arg3"

	Do you strictly prefer the command before "and" here?

	Conventionally, the final comma would typically be omitted in
	prose, except where the list members are complex enough that the
	command is required to assist parsing.  However, lists of formal
	arguments are not quite vanilla prose.

"Providing that" -> "Provided that"

	Any particular rationale here?

"error EFOO" -> "the error EFOO"

	Is this a rule, in general?

.IP \(bu 2

	I assumed that specifying an explicit indentation amount would
	be fragile.  Going with the default behaviour also tends to
	result in a more consistent appearance.  Do you have any
	recommandations in this area?

	Do you have rules about the order to use bullet symbols?  I tend
	to avoid \(bu if possible, since while it's "correct", nroff can
	render it nastily as an unadorned letter "o" (e.g., with -Tascii
	or LC_CTYPE=C).  This is particlarly annoying if the indent is
	<= 2, since then the "o" tends to be visually swallowed by the
	following text (i.e., to a casual glance it looks like a word,
	particlarly if the following text is not capitalised).  Perhaps
	this is a bad glyph substitution decision in nroff rather than
	something that should be fixed in the man-pages source, but the
	man-pages source may be easier to fix...
	
	There is already inconsistency here: there are may top-level
	lists using ".IP *" in prctl.2, and plenty of places where the
	default indentation is used.


Should any of these be written up in man-pages(7), or is there a checker
than can detect them?

I wan't to minimise the amount of tweaking you have to do when merging
patches.

Cheers
---Dave

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

Re: [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6

[Michael Kerrisk (man-pages)]

Hello Dave,

TL;DR: don't worry about the small stuff; I'm happy to do the minor
edits given the high quality of your patches.

On Mon, 20 Jul 2020 at 18:52, Dave Martin <Dave.Martin@arm.com> wrote:
>
> On Mon, Jun 29, 2020 at 01:52:24PM +0200, Michael Kerrisk (man-pages) wrote:
> > Hi Dave,
> >
> > On 6/24/20 7:36 PM, Dave Martin wrote:
> > > A bunch of updates to the prctl(2) man page to fill in missing
> > > prctls (mostly) up to Linux 5.6 (along with a few other tweaks and
> > > fixes).
> > >
> > > Patches from the v2 series [1] that have been applied or rejected
> > > already have been dropped.
> > >
> > > All that remain here now are the SVE and tagged address ABI controls
> > > for arm64.
> > >
> > >
> > >
> > > [1] https://lore.kernel.org/linux-man/1590614258-24728-1-git-send-email-Dave.Martin@arm.com/
> > >
> > >
> > > Dave Martin (2):
> > >   prctl.2: Add SVE prctls (arm64)
> > >   prctl.2: Add tagged address ABI control prctls (arm64)
> > >
> > >  man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> > >  1 file changed, 331 insertions(+)
> > Thanks. I've pushed these changes to master now.
>
> Thanks -- btw I finally got around to reviewing master, and noted a few
> editorial changes that man-pages(7) does not make any statement about:
>
> "arg1, arg2, and arg3"
>
>         Do you strictly prefer the command before "and" here?
>
>         Conventionally, the final comma would typically be omitted in
>         prose, except where the list members are complex enough that the
>         command is required to assist parsing.  However, lists of formal
>         arguments are not quite vanilla prose.

There are two camps wrt that comma. I prefer the so-called Oxford
comma convention, as shown above. man-pages uses it generally.

> "Providing that" -> "Provided that"
>
>         Any particular rationale here?

Either would be fine; the past tense is just slightly better, to my ear.

> "error EFOO" -> "the error EFOO"
>
>         Is this a rule, in general?

I think the change that you refer to was actually: "with EFOO" to
"with the error EFOO". The former is just a little too brief, to my
ear.

> .IP \(bu 2
>
>         I assumed that specifying an explicit indentation amount would
>         be fragile.  Going with the default behaviour also tends to
>         result in a more consistent appearance.  Do you have any
>         recommandations in this area?
>
>         Do you have rules about the order to use bullet symbols?  I tend
>         to avoid \(bu if possible, since while it's "correct", nroff can
>         render it nastily as an unadorned letter "o" (e.g., with -Tascii
>         or LC_CTYPE=C).  This is particlarly annoying if the indent is
>         <= 2, since then the "o" tends to be visually swallowed by the
>         following text (i.e., to a casual glance it looks like a word,
>         particlarly if the following text is not capitalised).  Perhaps
>         this is a bad glyph substitution decision in nroff rather than
>         something that should be fixed in the man-pages source, but the
>         man-pages source may be easier to fix...
>
>         There is already inconsistency here: there are may top-level
>         lists using ".IP *" in prctl.2, and plenty of places where the
>         default indentation is used.

I must admit that I'm in the process of rethinking bulleted lists, and
I have not come to a conclusion (and that's why nothing is said in
man-pages(7), and also why there is currently inconsistency).

Using .IP with the default indent (8n) results in a very deep indent
between the glyph and the text, so it's not my preference.

Your note about the poor rendering with "-Tascii" is interesting.
Perhaps ".IP \(bu 3" may be better. But, I really do not know: do
people really render with "-Tascii" these days?

> Should any of these be written up in man-pages(7), or is there a checker
> than can detect them?

Perhaps man-pages should say something about the Oxford comma.

> I wan't to minimise the amount of tweaking you have to do when merging
> patches.

If every patch that I received was of the same quality as yours are,
my life would be much easier. The tweaks are minimal work on my part.
Don't worry. Just send me more patches :-).

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 v3 0/2] prctl.2 man page updates for Linux 5.6

[Michael Kerrisk (man-pages)]

Hello Dave,

TL;DR: don't worry about the small stuff; I'm happy to do the minor
edits given the high quality of your patches.

On Mon, 20 Jul 2020 at 18:52, Dave Martin <Dave.Martin@arm.com> wrote:
>
> On Mon, Jun 29, 2020 at 01:52:24PM +0200, Michael Kerrisk (man-pages) wrote:
> > Hi Dave,
> >
> > On 6/24/20 7:36 PM, Dave Martin wrote:
> > > A bunch of updates to the prctl(2) man page to fill in missing
> > > prctls (mostly) up to Linux 5.6 (along with a few other tweaks and
> > > fixes).
> > >
> > > Patches from the v2 series [1] that have been applied or rejected
> > > already have been dropped.
> > >
> > > All that remain here now are the SVE and tagged address ABI controls
> > > for arm64.
> > >
> > >
> > >
> > > [1] https://lore.kernel.org/linux-man/1590614258-24728-1-git-send-email-Dave.Martin@arm.com/
> > >
> > >
> > > Dave Martin (2):
> > >   prctl.2: Add SVE prctls (arm64)
> > >   prctl.2: Add tagged address ABI control prctls (arm64)
> > >
> > >  man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> > >  1 file changed, 331 insertions(+)
> > Thanks. I've pushed these changes to master now.
>
> Thanks -- btw I finally got around to reviewing master, and noted a few
> editorial changes that man-pages(7) does not make any statement about:
>
> "arg1, arg2, and arg3"
>
>         Do you strictly prefer the command before "and" here?
>
>         Conventionally, the final comma would typically be omitted in
>         prose, except where the list members are complex enough that the
>         command is required to assist parsing.  However, lists of formal
>         arguments are not quite vanilla prose.

There are two camps wrt that comma. I prefer the so-called Oxford
comma convention, as shown above. man-pages uses it generally.

> "Providing that" -> "Provided that"
>
>         Any particular rationale here?

Either would be fine; the past tense is just slightly better, to my ear.

> "error EFOO" -> "the error EFOO"
>
>         Is this a rule, in general?

I think the change that you refer to was actually: "with EFOO" to
"with the error EFOO". The former is just a little too brief, to my
ear.

> .IP \(bu 2
>
>         I assumed that specifying an explicit indentation amount would
>         be fragile.  Going with the default behaviour also tends to
>         result in a more consistent appearance.  Do you have any
>         recommandations in this area?
>
>         Do you have rules about the order to use bullet symbols?  I tend
>         to avoid \(bu if possible, since while it's "correct", nroff can
>         render it nastily as an unadorned letter "o" (e.g., with -Tascii
>         or LC_CTYPE=C).  This is particlarly annoying if the indent is
>         <= 2, since then the "o" tends to be visually swallowed by the
>         following text (i.e., to a casual glance it looks like a word,
>         particlarly if the following text is not capitalised).  Perhaps
>         this is a bad glyph substitution decision in nroff rather than
>         something that should be fixed in the man-pages source, but the
>         man-pages source may be easier to fix...
>
>         There is already inconsistency here: there are may top-level
>         lists using ".IP *" in prctl.2, and plenty of places where the
>         default indentation is used.

I must admit that I'm in the process of rethinking bulleted lists, and
I have not come to a conclusion (and that's why nothing is said in
man-pages(7), and also why there is currently inconsistency).

Using .IP with the default indent (8n) results in a very deep indent
between the glyph and the text, so it's not my preference.

Your note about the poor rendering with "-Tascii" is interesting.
Perhaps ".IP \(bu 3" may be better. But, I really do not know: do
people really render with "-Tascii" these days?

> Should any of these be written up in man-pages(7), or is there a checker
> than can detect them?

Perhaps man-pages should say something about the Oxford comma.

> I wan't to minimise the amount of tweaking you have to do when merging
> patches.

If every patch that I received was of the same quality as yours are,
my life would be much easier. The tweaks are minimal work on my part.
Don't worry. Just send me more patches :-).

Cheers,

Michael

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

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

Re: [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6

[Michael Kerrisk (man-pages)]

Hello Dave,

TL;DR: don't worry about the small stuff; I'm happy to do the minor
edits given the high quality of your patches.

On Mon, 20 Jul 2020 at 18:52, Dave Martin <Dave.Martin-5wv7dgnIgG8@public.gmane.org> wrote:
>
> On Mon, Jun 29, 2020 at 01:52:24PM +0200, Michael Kerrisk (man-pages) wrote:
> > Hi Dave,
> >
> > On 6/24/20 7:36 PM, Dave Martin wrote:
> > > A bunch of updates to the prctl(2) man page to fill in missing
> > > prctls (mostly) up to Linux 5.6 (along with a few other tweaks and
> > > fixes).
> > >
> > > Patches from the v2 series [1] that have been applied or rejected
> > > already have been dropped.
> > >
> > > All that remain here now are the SVE and tagged address ABI controls
> > > for arm64.
> > >
> > >
> > >
> > > [1] https://lore.kernel.org/linux-man/1590614258-24728-1-git-send-email-Dave.Martin-5wv7dgnIgG8@public.gmane.org/
> > >
> > >
> > > Dave Martin (2):
> > >   prctl.2: Add SVE prctls (arm64)
> > >   prctl.2: Add tagged address ABI control prctls (arm64)
> > >
> > >  man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> > >  1 file changed, 331 insertions(+)
> > Thanks. I've pushed these changes to master now.
>
> Thanks -- btw I finally got around to reviewing master, and noted a few
> editorial changes that man-pages(7) does not make any statement about:
>
> "arg1, arg2, and arg3"
>
>         Do you strictly prefer the command before "and" here?
>
>         Conventionally, the final comma would typically be omitted in
>         prose, except where the list members are complex enough that the
>         command is required to assist parsing.  However, lists of formal
>         arguments are not quite vanilla prose.

There are two camps wrt that comma. I prefer the so-called Oxford
comma convention, as shown above. man-pages uses it generally.

> "Providing that" -> "Provided that"
>
>         Any particular rationale here?

Either would be fine; the past tense is just slightly better, to my ear.

> "error EFOO" -> "the error EFOO"
>
>         Is this a rule, in general?

I think the change that you refer to was actually: "with EFOO" to
"with the error EFOO". The former is just a little too brief, to my
ear.

> .IP \(bu 2
>
>         I assumed that specifying an explicit indentation amount would
>         be fragile.  Going with the default behaviour also tends to
>         result in a more consistent appearance.  Do you have any
>         recommandations in this area?
>
>         Do you have rules about the order to use bullet symbols?  I tend
>         to avoid \(bu if possible, since while it's "correct", nroff can
>         render it nastily as an unadorned letter "o" (e.g., with -Tascii
>         or LC_CTYPE=C).  This is particlarly annoying if the indent is
>         <= 2, since then the "o" tends to be visually swallowed by the
>         following text (i.e., to a casual glance it looks like a word,
>         particlarly if the following text is not capitalised).  Perhaps
>         this is a bad glyph substitution decision in nroff rather than
>         something that should be fixed in the man-pages source, but the
>         man-pages source may be easier to fix...
>
>         There is already inconsistency here: there are may top-level
>         lists using ".IP *" in prctl.2, and plenty of places where the
>         default indentation is used.

I must admit that I'm in the process of rethinking bulleted lists, and
I have not come to a conclusion (and that's why nothing is said in
man-pages(7), and also why there is currently inconsistency).

Using .IP with the default indent (8n) results in a very deep indent
between the glyph and the text, so it's not my preference.

Your note about the poor rendering with "-Tascii" is interesting.
Perhaps ".IP \(bu 3" may be better. But, I really do not know: do
people really render with "-Tascii" these days?

> Should any of these be written up in man-pages(7), or is there a checker
> than can detect them?

Perhaps man-pages should say something about the Oxford comma.

> I wan't to minimise the amount of tweaking you have to do when merging
> patches.

If every patch that I received was of the same quality as yours are,
my life would be much easier. The tweaks are minimal work on my part.
Don't worry. Just send me more patches :-).

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 v3 0/2] prctl.2 man page updates for Linux 5.6

[Dave Martin]

On Mon, Jul 20, 2020 at 11:31:16PM +0200, Michael Kerrisk (man-pages) wrote:
> Hello Dave,
> 
> TL;DR: don't worry about the small stuff; I'm happy to do the minor
> edits given the high quality of your patches.
> 
> On Mon, 20 Jul 2020 at 18:52, Dave Martin <Dave.Martin@arm.com> wrote:
> >
> > On Mon, Jun 29, 2020 at 01:52:24PM +0200, Michael Kerrisk (man-pages) wrote:
> > > Hi Dave,
> > >
> > > On 6/24/20 7:36 PM, Dave Martin wrote:
> > > > A bunch of updates to the prctl(2) man page to fill in missing
> > > > prctls (mostly) up to Linux 5.6 (along with a few other tweaks and
> > > > fixes).
> > > >
> > > > Patches from the v2 series [1] that have been applied or rejected
> > > > already have been dropped.
> > > >
> > > > All that remain here now are the SVE and tagged address ABI controls
> > > > for arm64.
> > > >
> > > >
> > > >
> > > > [1] https://lore.kernel.org/linux-man/1590614258-24728-1-git-send-email-Dave.Martin@arm.com/
> > > >
> > > >
> > > > Dave Martin (2):
> > > >   prctl.2: Add SVE prctls (arm64)
> > > >   prctl.2: Add tagged address ABI control prctls (arm64)
> > > >
> > > >  man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> > > >  1 file changed, 331 insertions(+)
> > > Thanks. I've pushed these changes to master now.
> >
> > Thanks -- btw I finally got around to reviewing master, and noted a few
> > editorial changes that man-pages(7) does not make any statement about:
> >
> > "arg1, arg2, and arg3"
> >
> >         Do you strictly prefer the command before "and" here?
> >
> >         Conventionally, the final comma would typically be omitted in
> >         prose, except where the list members are complex enough that the
> >         command is required to assist parsing.  However, lists of formal
> >         arguments are not quite vanilla prose.
> 
> There are two camps wrt that comma. I prefer the so-called Oxford
> comma convention, as shown above. man-pages uses it generally.
> 
> > "Providing that" -> "Provided that"
> >
> >         Any particular rationale here?
> 
> Either would be fine; the past tense is just slightly better, to my ear.
> 
> > "error EFOO" -> "the error EFOO"
> >
> >         Is this a rule, in general?
> 
> I think the change that you refer to was actually: "with EFOO" to
> "with the error EFOO". The former is just a little too brief, to my
> ear.
> 
> > .IP \(bu 2
> >
> >         I assumed that specifying an explicit indentation amount would
> >         be fragile.  Going with the default behaviour also tends to
> >         result in a more consistent appearance.  Do you have any
> >         recommandations in this area?
> >
> >         Do you have rules about the order to use bullet symbols?  I tend
> >         to avoid \(bu if possible, since while it's "correct", nroff can
> >         render it nastily as an unadorned letter "o" (e.g., with -Tascii
> >         or LC_CTYPE=C).  This is particlarly annoying if the indent is
> >         <= 2, since then the "o" tends to be visually swallowed by the
> >         following text (i.e., to a casual glance it looks like a word,
> >         particlarly if the following text is not capitalised).  Perhaps
> >         this is a bad glyph substitution decision in nroff rather than
> >         something that should be fixed in the man-pages source, but the
> >         man-pages source may be easier to fix...
> >
> >         There is already inconsistency here: there are may top-level
> >         lists using ".IP *" in prctl.2, and plenty of places where the
> >         default indentation is used.
> 
> I must admit that I'm in the process of rethinking bulleted lists, and
> I have not come to a conclusion (and that's why nothing is said in
> man-pages(7), and also why there is currently inconsistency).
> 
> Using .IP with the default indent (8n) results in a very deep indent
> between the glyph and the text, so it's not my preference.

Is it worth trying to change the default indent in the macro package, or
will that just upset other people?


> Your note about the poor rendering with "-Tascii" is interesting.
> Perhaps ".IP \(bu 3" may be better. But, I really do not know: do
> people really render with "-Tascii" these days?

Probably not, though it may happen depending on the locale and/or
terminal type settings in minimal distro installs.

It's a minor annoyance at worst, and probably not worth fixing...


> > Should any of these be written up in man-pages(7), or is there a checker
> > than can detect them?
> 
> Perhaps man-pages should say something about the Oxford comma.

Fair enough.

> > I wan't to minimise the amount of tweaking you have to do when merging
> > patches.
> 
> If every patch that I received was of the same quality as yours are,
> my life would be much easier. The tweaks are minimal work on my part.
> Don't worry. Just send me more patches :-).

OK, I won't agonise too much over this, then.

Cheers
---Dave

Re: [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6

[Dave Martin]

On Mon, Jul 20, 2020 at 11:31:16PM +0200, Michael Kerrisk (man-pages) wrote:
> Hello Dave,
> 
> TL;DR: don't worry about the small stuff; I'm happy to do the minor
> edits given the high quality of your patches.
> 
> On Mon, 20 Jul 2020 at 18:52, Dave Martin <Dave.Martin@arm.com> wrote:
> >
> > On Mon, Jun 29, 2020 at 01:52:24PM +0200, Michael Kerrisk (man-pages) wrote:
> > > Hi Dave,
> > >
> > > On 6/24/20 7:36 PM, Dave Martin wrote:
> > > > A bunch of updates to the prctl(2) man page to fill in missing
> > > > prctls (mostly) up to Linux 5.6 (along with a few other tweaks and
> > > > fixes).
> > > >
> > > > Patches from the v2 series [1] that have been applied or rejected
> > > > already have been dropped.
> > > >
> > > > All that remain here now are the SVE and tagged address ABI controls
> > > > for arm64.
> > > >
> > > >
> > > >
> > > > [1] https://lore.kernel.org/linux-man/1590614258-24728-1-git-send-email-Dave.Martin@arm.com/
> > > >
> > > >
> > > > Dave Martin (2):
> > > >   prctl.2: Add SVE prctls (arm64)
> > > >   prctl.2: Add tagged address ABI control prctls (arm64)
> > > >
> > > >  man2/prctl.2 | 331 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
> > > >  1 file changed, 331 insertions(+)
> > > Thanks. I've pushed these changes to master now.
> >
> > Thanks -- btw I finally got around to reviewing master, and noted a few
> > editorial changes that man-pages(7) does not make any statement about:
> >
> > "arg1, arg2, and arg3"
> >
> >         Do you strictly prefer the command before "and" here?
> >
> >         Conventionally, the final comma would typically be omitted in
> >         prose, except where the list members are complex enough that the
> >         command is required to assist parsing.  However, lists of formal
> >         arguments are not quite vanilla prose.
> 
> There are two camps wrt that comma. I prefer the so-called Oxford
> comma convention, as shown above. man-pages uses it generally.
> 
> > "Providing that" -> "Provided that"
> >
> >         Any particular rationale here?
> 
> Either would be fine; the past tense is just slightly better, to my ear.
> 
> > "error EFOO" -> "the error EFOO"
> >
> >         Is this a rule, in general?
> 
> I think the change that you refer to was actually: "with EFOO" to
> "with the error EFOO". The former is just a little too brief, to my
> ear.
> 
> > .IP \(bu 2
> >
> >         I assumed that specifying an explicit indentation amount would
> >         be fragile.  Going with the default behaviour also tends to
> >         result in a more consistent appearance.  Do you have any
> >         recommandations in this area?
> >
> >         Do you have rules about the order to use bullet symbols?  I tend
> >         to avoid \(bu if possible, since while it's "correct", nroff can
> >         render it nastily as an unadorned letter "o" (e.g., with -Tascii
> >         or LC_CTYPE=C).  This is particlarly annoying if the indent is
> >         <= 2, since then the "o" tends to be visually swallowed by the
> >         following text (i.e., to a casual glance it looks like a word,
> >         particlarly if the following text is not capitalised).  Perhaps
> >         this is a bad glyph substitution decision in nroff rather than
> >         something that should be fixed in the man-pages source, but the
> >         man-pages source may be easier to fix...
> >
> >         There is already inconsistency here: there are may top-level
> >         lists using ".IP *" in prctl.2, and plenty of places where the
> >         default indentation is used.
> 
> I must admit that I'm in the process of rethinking bulleted lists, and
> I have not come to a conclusion (and that's why nothing is said in
> man-pages(7), and also why there is currently inconsistency).
> 
> Using .IP with the default indent (8n) results in a very deep indent
> between the glyph and the text, so it's not my preference.

Is it worth trying to change the default indent in the macro package, or
will that just upset other people?


> Your note about the poor rendering with "-Tascii" is interesting.
> Perhaps ".IP \(bu 3" may be better. But, I really do not know: do
> people really render with "-Tascii" these days?

Probably not, though it may happen depending on the locale and/or
terminal type settings in minimal distro installs.

It's a minor annoyance at worst, and probably not worth fixing...


> > Should any of these be written up in man-pages(7), or is there a checker
> > than can detect them?
> 
> Perhaps man-pages should say something about the Oxford comma.

Fair enough.

> > I wan't to minimise the amount of tweaking you have to do when merging
> > patches.
> 
> If every patch that I received was of the same quality as yours are,
> my life would be much easier. The tweaks are minimal work on my part.
> Don't worry. Just send me more patches :-).

OK, I won't agonise too much over this, then.

Cheers
---Dave

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

Re: [PATCH v3 0/2] prctl.2 man page updates for Linux 5.6

[Michael Kerrisk (man-pages)]

> > >         There is already inconsistency here: there are may top-level
> > >         lists using ".IP *" in prctl.2, and plenty of places where the
> > >         default indentation is used.
> >
> > I must admit that I'm in the process of rethinking bulleted lists, and
> > I have not come to a conclusion (and that's why nothing is said in
> > man-pages(7), and also why there is currently inconsistency).
> >
> > Using .IP with the default indent (8n) results in a very deep indent
> > between the glyph and the text, so it's not my preference.
>
> Is it worth trying to change the default indent in the macro package, or
> will that just upset other people?

I imagine it would break other stuff.

Thanks,

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 v3 0/2] prctl.2 man page updates for Linux 5.6

[Michael Kerrisk (man-pages)]

> > >         There is already inconsistency here: there are may top-level
> > >         lists using ".IP *" in prctl.2, and plenty of places where the
> > >         default indentation is used.
> >
> > I must admit that I'm in the process of rethinking bulleted lists, and
> > I have not come to a conclusion (and that's why nothing is said in
> > man-pages(7), and also why there is currently inconsistency).
> >
> > Using .IP with the default indent (8n) results in a very deep indent
> > between the glyph and the text, so it's not my preference.
>
> Is it worth trying to change the default indent in the macro package, or
> will that just upset other people?

I imagine it would break other stuff.

Thanks,

Michael

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

_______________________________________________
linux-arm-kernel mailing list
linux-arm-kernel@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

bulleted lists and indentation (was: prctl.2 man page updates for Linux 5.6)

[G. Branden Robinson]

[-- Attachment #1.1: Type: text/plain, Size: 4438 bytes --]

[CC list trimmed]

At 2020-08-04T14:52:05+0200, Michael Kerrisk (man-pages) wrote:
> > > >         There is already inconsistency here: there are may
> > > >         top-level lists using ".IP *" in prctl.2, and plenty of
> > > >         places where the default indentation is used.
> > >
> > > I must admit that I'm in the process of rethinking bulleted lists,
> > > and I have not come to a conclusion (and that's why nothing is
> > > said in man-pages(7), and also why there is currently
> > > inconsistency).
> > >
> > > Using .IP with the default indent (8n) results in a very deep
> > > indent between the glyph and the text, so it's not my preference.

Technically the indentation _amount_ is 7n in groff for nroff output
(7.2n for troff).  So with repeated indents you get text on columns 8,
15, 22, and so on (where the leftmost character cell is numbered 1).

> >
> > Is it worth trying to change the default indent in the macro
> > package, or will that just upset other people?
> 
> I imagine it would break other stuff.

In well-written man pages, I don't think it would, but it's still not
worth doing within man pages themselves.  However, a solution does exist
that people can apply to their own environments, if their man pager uses
groff as the typesetter (this is likely true of anybody reading this
unless they know they use the mandoc program).

The same indentation value is used for multiple purposes in the groff
implementation of the man macros, the language in which classical man
pages are written.  These purposes are:

	1. The amount a standard paragraph (.PP, .LP, or .P) is indented
	from the left edge of the screen (where the section headings
	defined by .SH are aligned).

	2. The amount a "relative indent" section is inset from the
	existing left margin.  In other words, how much an .RS/.RE
	region lies "inboard" of the surrounding material if you don't
	give .RS an explicit argument.

	3. The amount of space allocated to the tag in a tagged
	paragraph (the macros .TP and .TQ).  (If the tag overruns this
	amount, it gets the output line to itself and the entire
	subsequent paragraph is set indented by this same amount.)

	4. The amount of space by which an indented paragraph (.IP) is
	indented.  (.IP takes an optional tag argument, and is ideal for
	itemized or enumerated lists.)

A nice feature of the above extensive re-use of the same parameter is
that it pushes the man(7) language in the direction of being more
semantic and less presentational.  On the other hand, some people just
don't like the resulting esthetics.

This parameter is a register called "IN".  (There's one exception to
this generality; the indent of a subsection is controlled by the
register SN, and defaults to 3n.)

But rather than customizing each man page to the writer's preference,
which will (and does) lead to an explosion of different conventions
leading to an inconsistent user experience for readers of man pages from
diverse sources, we can give tell the man macro package what we want
this indentation amount to be.

You can edit your man.local file (on my Debian system, it is in
/etc/groff/man.local), and add a line like this (without the leading
tab):

	.nr IN 4n

If you're practiced with the *roff language you can write conditionals
to tune the application of this setting.  Say I only want to change the
IN register only if groff is my typesetter and if I'm rendering the page
to "an nroff device" (a terminal, basically).  I can do this:

	.if \n(.g .if n .nr IN 4n

The first condition is probably slightly contrived because I'd be
surprised if any non-groff typesetter opened /etc/groff/man.local to
read it, but I don't want to come across as unecumenical; there are
users out there of Heirloom Doctools troff, Plan 9 troff, and neatroff.

I'm attaching an example man page to demonstrate the above.  If you use
Colin Watson's man-db you can view it directly with "man -l".  I put the
register tweaking directly at the top of the page to make it easy for
people to experiment but *PLEASE* don't do this in actual man pages.  To
reiterate my earlier point: we want to empower the _reader_ to configure
the indentation in a way that pleases them, not encourage a hundred
different man page writers to subject the rest of the world to their
varied and conflicting preferences.

Regards,
Branden

[-- Attachment #1.2: indentation.man --]
[-- Type: application/x-troff-man, Size: 1741 bytes --]

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]