Re: [PATCH] prctl.2: Document Syscall User Dispatch

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

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/