* [PATCH] prctl.2: Document Syscall User Dispatch
@ 2020-12-19 4:10 Gabriel Krisman Bertazi
2020-12-19 15:01 ` Alejandro Colomar (man-pages)
0 siblings, 1 reply; 3+ messages in thread
From: Gabriel Krisman Bertazi @ 2020-12-19 4:10 UTC (permalink / raw)
To: mtk.manpages; +Cc: linux-man, Gabriel Krisman Bertazi
Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.com>
---
man2/prctl.2 | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 93 insertions(+)
diff --git a/man2/prctl.2 b/man2/prctl.2
index f25f05fdb593..2e82c73c10c2 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -1533,6 +1533,70 @@ For more information, see the kernel source file
(or
.I Documentation/arm64/sve.txt
before Linux 5.3).
+.TP
+.\"commit 1446e1df9eb183fdf81c3f0715402f1d7595d4cb
+.BR PR_SET_SYSCALL_USER_DISPATCH " (Since Linux 5.11, x86 only)"
+.IP
+Configure the Syscall User Dispatch mechanism for the calling thread, to
+selective intercept system calls and dispatch them back to userspace
+through
+.IR SIGSYS .
+.IP
+The current Syscall User Dispatch mode is selected via
+.IR "arg2",
+which can either be set to
+.B PR_SYS_DISPATCH_ON
+to enable the feature, or to
+.B PR_SYS_DISPATCH_OFF
+to turn it off.
+.IP
+With
+.IR "arg2"
+set to
+.BR PR_SYS_DISPATCH_ON ,
+.IR "arg3"
+and
+.I "arg4"
+respectively identify the
+.I offset
+and
+.I length
+of a memory region in the process map from where system calls are always
+allowed to be executed, regardless of the switch variable.
+.I "arg5"
+points to a char-sized variable that is a fast switch to enable/disable
+the mechanism without invoking the kernel.
+.I "arg5"
+can be set to either
+.BR PR_SYS_DISPATCH_ON
+to enable the mechanism or to
+.BR PR_SYS_DISPATCH_OFF
+to temporarily disable it. Any other value will fail the application
+with a
+.IR SIGSYS .
+.IP
+When a system call is intercepted, a
+.I SIGSYS
+is raised with
+.I si_code
+set to
+.B SYS_USER_DISPATCH.
+.IP
+When
+.I "arg2"
+is set to
+.BR PR_SYS_DISPATCH_OFF ,
+the remaining arguments must be set to
+.BR 0 .
+.IP
+The setting is not preserved across
+.BR fork (2),
+.BR clone (2)
+or
+.BR execve (2) .
+.IP
+For more information, see the kernel source file
+.IR Documentation/admin-guide/syscall-user-dispatch.rst
.\" prctl PR_SET_TAGGED_ADDR_CTRL
.\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
.TP
@@ -2000,6 +2064,14 @@ and
.I arg3
is an invalid address.
.TP
+.B EFAULT
+.I option
+is
+.BR PR_SET_SYSCALL_USER_DISPATCH
+and
+.I arg5
+has an invalid address.
+.TP
.B EINVAL
The value of
.I option
@@ -2229,6 +2301,27 @@ is
and SVE is not available on this platform.
.TP
.B EINVAL
+.I option is
+.B PR_SET_SYSCALL_USER_DISPATCH
+and one of the following is true:
+.RS
+.IP * 3
+.I arg2
+is
+.B PR_SYS_DISPATCH_OFF
+and remaining arguments are not
+.BR 0.
+.IP * 3
+.I arg2
+is
+.B PR_SYS_DISPATCH_ON
+and the memory region provided is invalid.
+.IP * 3
+.I arg2
+is invalid.
+.RE
+.TP
+.B EINVAL
.I option
is
.BR PR_SET_TAGGED_ADDR_CTRL
--
2.29.2
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PATCH] prctl.2: Document Syscall User Dispatch
2020-12-19 4:10 [PATCH] prctl.2: Document Syscall User Dispatch Gabriel Krisman Bertazi
@ 2020-12-19 15:01 ` Alejandro Colomar (man-pages)
2020-12-21 16:38 ` Gabriel Krisman Bertazi
0 siblings, 1 reply; 3+ messages in thread
From: Alejandro Colomar (man-pages) @ 2020-12-19 15:01 UTC (permalink / raw)
To: Gabriel Krisman Bertazi, mtk.manpages; +Cc: linux-man
Hi Gabriel,
Thanks for the page!
Please see some comments below.
Thanks,
Alex
On 12/19/20 5:10 AM, Gabriel Krisman Bertazi wrote:
> Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.com>
> ---
> man2/prctl.2 | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 93 insertions(+)
>
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index f25f05fdb593..2e82c73c10c2 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -1533,6 +1533,70 @@ For more information, see the kernel source file
> (or
> .I Documentation/arm64/sve.txt
> before Linux 5.3).
> +.TP
> +.\"commit 1446e1df9eb183fdf81c3f0715402f1d7595d4cb
> +.BR PR_SET_SYSCALL_USER_DISPATCH " (Since Linux 5.11, x86 only)"
s/Since/since
rationale:
$ grep -r '(Since Linux' man? |wc -l
48
$ grep -r '(since Linux' man? |wc -l
1286
> +.IP
> +Configure the Syscall User Dispatch mechanism for the calling thread, to
See:
$ man 7 man-pages |sed -n '/Use semantic newlines/,/^$/p'
Use semantic newlines
In the source of a manual page, new sentences should be started
on new lines, and long sentences should split into lines at
clause breaks (commas, semicolons, colons, and so on). This
convention, sometimes known as "semantic newlines", makes it
easier to see the effect of patches, which often operate at the
level of individual sentences or sentence clauses.
> +selective intercept system calls and dispatch them back to userspace
s/userspace/user space/
Rationale:
$ man 7 man-pages |sed -n '/Preferred/,/user space/p'
Preferred terms
The following table lists some preferred terms to use in man
pages, mainly to ensure consistency across pages.
Term Avoid using Notes
────────────────────────────────────────────────────────────────────────────────────────────────────
bit mask bitmask
built-in builtin
Epoch epoch For the UNIX
Epoch (00:00:00, 1 Jan 1970 UTC)
filename file name
filesystem file system
hostname host name
inode i-node
lowercase lower case, lower-case
nonzero non-zero
pathname path name
pseudoterminal pseudo-terminal
privileged port reserved port, system port
real-time realtime, real time
run time runtime
saved set-group-ID saved group ID, saved set-GID
saved set-user-ID saved user ID, saved set-UID
set-group-ID set-GID, setgid
set-user-ID set-UID, setuid
superuser super user, super-user
superblock super block, super-block
timestamp time stamp
timezone time zone
uppercase upper case, upper-case
usable useable
user space userspace
> +through
> +.IR SIGSYS .
> +.IP
> +The current Syscall User Dispatch mode is selected via
> +.IR "arg2",
.IR arg2 ,
> +which can either be set to
> +.B PR_SYS_DISPATCH_ON
> +to enable the feature, or to
> +.B PR_SYS_DISPATCH_OFF
> +to turn it off.
> +.IP
> +With
> +.IR "arg2"
.I arg2
> +set to
> +.BR PR_SYS_DISPATCH_ON ,
> +.IR "arg3"
.I arg3
> +and
> +.I "arg4"
tr -d '"'
> +respectively identify the
> +.I offset
> +and
> +.I length
> +of a memory region in the process map from where system calls are always
See semantic newlines above.
> +allowed to be executed, regardless of the switch variable.
> +.I "arg5"
tr -d '"'
> +points to a char-sized variable that is a fast switch to enable/disable> +the mechanism without invoking the kernel.
> +.I "arg5"
tr -d '"'
> +can be set to either
> +.BR PR_SYS_DISPATCH_ON
s/.BR/.B/
> +to enable the mechanism or to
> +.BR PR_SYS_DISPATCH_OFF
s/.BR/.B
> +to temporarily disable it. Any other value will fail the application> +with a
See semantic newlines above.
> +.IR SIGSYS .
> +.IP
> +When a system call is intercepted, a
> +.I SIGSYS
> +is raised with
> +.I si_code
> +set to
> +.B SYS_USER_DISPATCH.
.BR SYS_USER_DISPATCH .
> +.IP
> +When
> +.I "arg2"
tr -d '"'
> +is set to
> +.BR PR_SYS_DISPATCH_OFF ,
> +the remaining arguments must be set to
> +.BR 0 .
Literals are not (usually) formatted.
[
the remaining arguments must be set to 0.
]
> +.IP
> +The setting is not preserved across
> +.BR fork (2),
> +.BR clone (2)
> +or
> +.BR execve (2) .
s/(2) ./(2)./
> +.IP
> +For more information, see the kernel source file
> +.IR Documentation/admin-guide/syscall-user-dispatch.rst
s/.IR/.I/
Could you add
> .\" prctl PR_SET_TAGGED_ADDR_CTRL
> .\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
> .TP
> @@ -2000,6 +2064,14 @@ and
> .I arg3
> is an invalid address.
> .TP
> +.B EFAULT
> +.I option
> +is
> +.BR PR_SET_SYSCALL_USER_DISPATCH
s/.BR/.B/
> +and
> +.I arg5
> +has an invalid address.
> +.TP
> .B EINVAL
> The value of
> .I option
> @@ -2229,6 +2301,27 @@ is
> and SVE is not available on this platform.
> .TP
> .B EINVAL
> +.I option is
> +.B PR_SET_SYSCALL_USER_DISPATCH
> +and one of the following is true:
> +.RS
> +.IP * 3
> +.I arg2
> +is
> +.B PR_SYS_DISPATCH_OFF
> +and remaining arguments are not
> +.BR 0.
and remaining arguments are not 0.
> +.IP * 3
> +.I arg2
> +is
> +.B PR_SYS_DISPATCH_ON
> +and the memory region provided is invalid.> +.IP * 3
> +.I arg2
> +is invalid.
> +.RE
> +.TP
> +.B EINVAL
> .I option
> is
> .BR PR_SET_TAGGED_ADDR_CTRL
>
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] prctl.2: Document Syscall User Dispatch
2020-12-19 15:01 ` Alejandro Colomar (man-pages)
@ 2020-12-21 16:38 ` Gabriel Krisman Bertazi
0 siblings, 0 replies; 3+ messages in thread
From: Gabriel Krisman Bertazi @ 2020-12-21 16:38 UTC (permalink / raw)
To: Alejandro Colomar (man-pages); +Cc: mtk.manpages, linux-man
"Alejandro Colomar (man-pages)" <alx.manpages@gmail.com> writes:
> Hi Gabriel,
>
> Thanks for the page!
> Please see some comments below.
Thanks for the very detailed review. In particular, I wasn't familiar
with semantic lines, which seems like a very interesting concept.
Will follow up with v2 shortly.
--
Gabriel Krisman Bertazi
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2020-12-21 16:39 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-12-19 4:10 [PATCH] prctl.2: Document Syscall User Dispatch Gabriel Krisman Bertazi
2020-12-19 15:01 ` Alejandro Colomar (man-pages)
2020-12-21 16:38 ` Gabriel Krisman Bertazi
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox