# Re: \[PATCHv3 1/1\] Documentation: describe how to add a system call

- From: David Drysdale \<hidden\>
- Date: 2015-08-10 07:43:45 
- List: linux-api
- Page: https://ratatoskr.run/linux-api/2015/08/4554467
- Thread: https://ratatoskr.run/linux-api/2015/07/4547734/t.md

```text
On Wed, Aug 5, 2015 at 5:21 PM, Pavel Machek [ref] wrote:
> Hi!
>
>> Add a document describing the process of adding a new system call,
>> including the need for a flags argument for future compatibility, and
>> covering 32-bit/64-bit concerns (albeit in an x86-centric way).
>>
>> Signed-off-by: David Drysdale <redacted>
>> Reviewed-by: Michael Kerrisk <redacted>
>> Reviewed-by: Eric B Munson <redacted>
>> Reviewed-by: Kees Cook <redacted>
>> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
>> ---
>>  Documentation/adding-syscalls.txt | 531 ++++++++++++++++++++++++++++++++++++++
>>  1 file changed, 531 insertions(+)
>>  create mode 100644 Documentation/adding-syscalls.txt
>
> We usually align documentation to less than 80 columns, afaict.

Ah, a few re-worded paragraphs crept over the limit.  Reflowed.

>> +call.  To make sure that userspace programs can safely use flags between kernel
>> +versions, check whether the flags value holds any unknown flags, and reject the
>> +sycall (with EINVAL) if it does:
>
> syscall?

Fixed, thanks.

>> +New system call proposals, like any change to the kernel's API, should always
>> +be cc'ed to linux-api@vger.kernel.org
>
> . at and of sentence?

Fixed.

>> +System Calls Returning Elsewhere
>> +--------------------------------
>> +
>> +For most system calls, once the system call is complete the user program
>> +continues exactly where it left off -- at the next instruction, with the same
>> +stack and registers as before the system call, and with the same virtual
>> +memory space.
>
> Umm. Normally we place return value in register. And I'm not sure.. do
> syscalls preserve registers that are normally caller-clobbered in the ABI?

Reworded to:

For most system calls, once the system call is complete the user program
continues exactly where it left off -- at the next instruction, with the
stack the same and most of the registers the same as before the system call,
and with the same virtual memory space.

> Thanks,
>                                                                         Pavel

Thanks for the updates,
David

> --
> (english) http://www.livejournal.com/~pavelmachek
> (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html
```