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

On Wed, Aug 5, 2015 at 5:21 PM, Pavel Machek [off-list ref] wrote:

Hi!

quoted

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.

quoted

+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.

quoted

+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.

quoted

+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