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

[Gabriel Krisman Bertazi <krisman@collabora.com>]

"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:

> Hello Gabriel,
>
> On 12/22/20 9:25 PM, Gabriel Krisman Bertazi wrote:
>> Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.com>
>> 
>> ---
>> Changes since v3:
>> (suggested by Michael Kerrisk)
>>   - Explain what dispatch to user space means.
>>   - Document the fact that the memory region is a single consecutive
>>   range.
>>   - Explain failure if *arg5 is set to a bad value.
>>   - fix english typo.
>>   - Define what 'invalid memory region' means.
>> 
>> Changes since v2:
>> (suggested by Alejandro Colomar)
>>   - selective -> selectively
>>   - Add missing oxford comma.
>> 
>> Changes since v1:
>> (suggested by Alejandro Colomar)
>>   - Use semantic lines
>>   - Fix usage of .{B|I}R and .{B|I}
>>   - Don't format literals
>>   - Fix preferred spelling of userspace
>>   - Fix case of word
>> ---
>>  man2/prctl.2 | 122 +++++++++++++++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 122 insertions(+)
>> 
>> diff --git a/man2/prctl.2 b/man2/prctl.2
>> index f25f05fdb593..71261a736964 100644
>> --- a/man2/prctl.2
>> +++ b/man2/prctl.2
>> @@ -1533,6 +1533,98 @@ For more information, see the kernel source file
>>  (or
>>  .I Documentation/arm64/sve.txt
>>  before Linux 5.3).
>> +.TP
>> +.\" prctl PR_SET_SYSCALL_USER_DISPATCH
>> +.\" commit 1446e1df9eb183fdf81c3f0715402f1d7595d4
>> +.BR PR_SET_SYSCALL_USER_DISPATCH " (since Linux 5.11, x86 only)"
>> +.IP
>> +Configure the Syscall User Dispatch mechanism
>> +for the calling thread,
>> +to selectively intercept system calls
>> +and dispatch them back to be instrumented by user space
>> +through
>> +.BR SIGSYS .
>
> I think that "dispatch them back to be instrumented by user space" 
> doesn't really explain anything to someone unfamiliar with SUD.
>
> How about something like this (if it is correct):
>
> [[
> The Syscall User Dispatch mechanism allows an application to
> selectively intercept system calls so that they can be emulated
> within the application itself. Interception takes the form a
> thread-directed SIGSYS signal that is delivered to the thread
> when it makes a system call. Upon rece(The system call is not executed
> by the kernel.)
> ]]
>
>> +This gives user space the opportunity to emulate the system call
>> +and modify its return value.
>
> How is the system call emulated? What I mean is: does one 
> emulate it from the SIGSYS handler? That needs to be more
> clearly stated.

I am rethinking the mention to emulation in the manpage, as that goes
beyond SUD.  In fact, it is one usecase that can be implemented using
SUD and signal handlers, but there are others.

I'm using your suggestion above slightly modified, to avoid the term emulation.

>
>> +.IP
>> +When a system call is dispatched back to user space
>> +by this mechanism,
>> +it is not executed by the kernel.
>> +When the signal handler returns,
>> +the system call completes immediately
>> +with the return value set
>> +by the signal handler.
>> +(See
>> +.BR sigaction (2)
>> +for information on setting the return value).
>
> I can's see anything in sigaction(2) that explains how to set the
> return value. Am I missing something or do you have a patch in
> progress for that page?

the way you modify the syscall return value is not part of SUD, instead
it is generic to how signals are handled.  so I'm dropping this bit.

-- 
Gabriel Krisman Bertazi