Documentation/process/adding-syscalls.rst

15 The first thing to consider when adding a new system call is whether one of
38    relevant filesystem is mounted, which might not always be the case (e.g.
40    debugfs, as this is not considered a 'production' interface to userspace.
41  - If the operation is specific to a particular file or file descriptor, then
43    :manpage:`fcntl(2)` is a multiplexing system call that hides a lot of complexity, so
44    this option is best for when the new function is closely analogous to
45    existing :manpage:`fcntl(2)` functionality, or the new functionality is very simple
47  - If the operation is specific to a particular task or process, then an
49    with :manpage:`fcntl(2)`, this system call is a complicated multiplexor so
50    is best reserved for near-analogs of existing ``prctl()`` commands or
62 (The syscall table is littered with historical examples where this wasn't done,
69 way to allow for future extensibility is to include a flags argument to the
77 (If no flags values are used yet, check that the flags argument is zero.)
81 that is passed in by pointer.  Such a structure can cope with future extension
91 As long as any subsequently added field, say ``param_4``, is designed so that a
97    expects is zero (effectively checking that ``param_4 == 0``).
115 then the flags argument should include a value that is equivalent to setting
121 of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a
122 numbering space of ``O_*`` flags that is fairly full.)
126 descriptor. Making a file descriptor ready for reading or writing is the
134 you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate::
143  - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...)
144  - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...)
181 distinct commits (each of which is described further below):
222 note that if multiple new system calls are added in the same merge window,
266 relevant merge window.
273 the userspace program is itself 32-bit; even if the system call's parameters
274 include an explicit pointer, this is handled transparently.
276 However, there are a couple of situations where a compatibility layer is
279 The first is if the 64-bit kernel also supports 32-bit userspace programs, and
281 64-bit values.  In particular, this is needed whenever a system call argument
282 is:
290 The second situation that requires a compatibility layer is if one of the
291 system call's arguments has a type that is explicitly 64-bit even on a 32-bit
300 The compatibility version of the system call is called ``compat_sys_xyzzy()``,
301 and is added with the ``COMPAT_SYSCALL_DEFINEn()`` macro, analogously to
303 kernel, but expects to receive 32-bit parameter values and does whatever is
314 If the system call involves a structure that is laid out differently on 32-bit
372 If there's a pointer-to-a-pointer involved, the decision is easy: x32 is
374 ``arch/x86/entry/syscalls/syscall_64.tbl`` is split so that x32 programs hit
381 If no pointers are involved, then it is preferable to re-use the 64-bit system
383 arch/x86/entry/syscalls/syscall_64.tbl is unchanged).
393 For most system calls, once the system call is complete the user program
407 This is arch-specific, but typically involves defining assembly entry points
411 For x86_64, this is implemented as a ``stub_xyzzy`` entry point in
413 (``arch/x86/entry/syscalls/syscall_64.tbl``) is adjusted to match::
417 The equivalent for 32-bit programs running on a 64-bit kernel is normally
427 implementation is not common with the x86_64 version, then its syscall
434 simulates registers etc).  Fixing this is as simple as adding a #define to
443 Most of the kernel treats system calls in a generic way, but there is the
446 The audit subsystem is one such special case; it includes (arch-specific)
449 socket multiplexor (``socketcall``) operations. If your new system call is
452 More generally, if there is an existing system call that is analogous to your
460 A new system call should obviously be tested; it is also useful to provide
462 call.  A good way to combine these aims is to include a simple self-test
486 markup, but plain text will do.  If groff is used, it's helpful to include a
487 pre-rendered ASCII version of the man page in the cover email for the
500 table, but not from elsewhere in the kernel.  If the syscall functionality is
510 convention for system calls where ``struct pt_regs`` is decoded on-the-fly in a
518 user data.  This is another reason why calling ``sys_xyzzy()`` is generally a