Documentation/process/adding-syscalls.rst

4 Adding a New System Call
7 This document describes what's involved in adding a new system call to the
9 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
12 System Call Alternatives
13 ------------------------
15 The first thing to consider when adding a new system call is whether one of
16 the alternatives might be suitable instead.  Although system calls are the
18 kernel, there are other possibilities -- choose what fits best for your
21  - If the operations involved can be made to look like a filesystem-like
26      - If the new functionality involves operations where the kernel notifies
30      - However, operations that don't map to
31        :manpage:`read(2)`/:manpage:`write(2)`-like operations
35  - If you're just exposing runtime system information, a new node in sysfs
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
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
55 -----------------------------------------
57 A new system call forms part of the API of the kernel, and has to be supported
63 together with the corresponding follow-up system calls --
65 ``pipe``/``pipe2``, ``renameat``/``renameat2`` -- so
68 For simpler system calls that only take a couple of arguments, the preferred
70 system call.  To make sure that userspace programs can safely use flags
71 between kernel versions, check whether the flags value holds any unknown
72 flags, and reject the system call (with ``EINVAL``) if it does::
75         return -EINVAL;
77 (If no flags values are used yet, check that the flags argument is zero.)
79 For more sophisticated system calls that involve a larger number of arguments,
85         u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */
95  - To cope with a later userspace program calling an older kernel, the kernel
96    code should check that any memory beyond the size of the structure that it
98  - To cope with an older userspace program calling a newer kernel, the kernel
99    code can zero-extend a smaller instance of the structure (effectively
107 ---------------------------------------
109 If your new system call allows userspace to refer to a kernel object, it
110 should use a file descriptor as the handle for that object -- don't invent a
112 well-defined semantics for using file descriptors.
114 If your new :manpage:`xyzzy(2)` system call does return a new file descriptor,
120 the exec'ed program. (However, resist the temptation to re-use the actual value
121 of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a
124 If your system call returns a new file descriptor, you should also consider
125 what it means to use the :manpage:`poll(2)` family of system calls on that file
130 If your new :manpage:`xyzzy(2)` system call involves a filename argument::
140 already-opened file descriptor using the ``AT_EMPTY_PATH`` flag, effectively
143  - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...)
144  - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...)
150 If your new :manpage:`xyzzy(2)` system call involves a parameter describing an
151 offset within a file, make its type ``loff_t`` so that 64-bit offsets can be
152 supported even on 32-bit architectures.
154 If your new :manpage:`xyzzy(2)` system call involves privileged functionality,
161 overly-general ``CAP_SYS_ADMIN`` capability.
163 If your new :manpage:`xyzzy(2)` system call manipulates a process other than
169 Finally, be aware that some non-x86 architectures have an easier time if
170 system call parameters that are explicitly 64-bit fall on odd-numbered
171 arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit
177 -----------------
179 To make new system calls easy to review, it's best to divide up the patchset
183  - The core implementation of the system call, together with prototypes,
185  - Wiring up of the new system call for one particular architecture, usually
187  - A demonstration of the use of the new system call in userspace via a
189  - A draft man-page for the new system call, either as plain text in the
190    cover letter, or as a patch to the (separate) man-pages repository.
192 New system call proposals, like any change to the kernel's API, should always
193 be cc'ed to linux-api@vger.kernel.org.
196 Generic System Call Implementation
197 ----------------------------------
199 The main entry point for your new :manpage:`xyzzy(2)` system call will be called
202 number of arguments to the system call, and the macro takes the system call name
204 this macro allows metadata about the new system call to be made available for
208 ``include/linux/syscalls.h``, marked as asmlinkage to match the way that system
213 Some architectures (e.g. x86) have their own architecture-specific syscall
215 new system call to the generic list by adding an entry to the list in
216 ``include/uapi/asm-generic/unistd.h``::
221 Also update the __NR_syscalls count to reflect the additional system call, and
222 note that if multiple new system calls are added in the same merge window,
226 system call, returning ``-ENOSYS``.  Add your new system call here too::
230 Your new kernel functionality, and the system call that controls it, should
234  - Include a description of the new functionality and system call controlled
236  - Make the option depend on EXPERT if it should be hidden from normal users.
237  - Make any new source files implementing the function dependent on the CONFIG
238    option in the Makefile (e.g. ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.o``).
239  - Double check that the kernel still builds with the new CONFIG option turned
244  - ``CONFIG`` option for the new function, normally in ``init/Kconfig``
245  - ``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry point
246  - corresponding prototype in ``include/linux/syscalls.h``
247  - generic table entry in ``include/uapi/asm-generic/unistd.h``
248  - fallback stub in ``kernel/sys_ni.c``
251 x86 System Call Implementation
252 ------------------------------
254 To wire up your new system call for x86 platforms, you need to update the
255 master syscall tables.  Assuming your new system call isn't special in some
269 Compatibility System Calls (Generic)
270 ------------------------------------
272 For most system calls the same 64-bit implementation can be invoked even when
273 the userspace program is itself 32-bit; even if the system call's parameters
277 needed to cope with size differences between 32-bit and 64-bit.
279 The first is if the 64-bit kernel also supports 32-bit userspace programs, and
280 so needs to parse areas of (``__user``) memory that could hold either 32-bit or
281 64-bit values.  In particular, this is needed whenever a system call argument
284  - a pointer to a pointer
285  - a pointer to a struct containing a pointer (e.g. ``struct iovec __user *``)
286  - a pointer to a varying sized integral type (``time_t``, ``off_t``,
288  - a pointer to a struct containing a varying sized integral type.
291 system call's arguments has a type that is explicitly 64-bit even on a 32-bit
293 arrives at a 64-bit kernel from a 32-bit application will be split into two
294 32-bit values, which then need to be re-assembled in the compatibility layer.
296 (Note that a system call argument that's a pointer to an explicit 64-bit type
298 type ``loff_t __user *`` do not trigger the need for a ``compat_`` system call.)
300 The compatibility version of the system call is called ``compat_sys_xyzzy()``,
302 SYSCALL_DEFINEn.  This version of the implementation runs as part of a 64-bit
303 kernel, but expects to receive 32-bit parameter values and does whatever is
305 values to 64-bit versions and either calls on to the ``sys_`` version, or both of
309 ``include/linux/compat.h``, marked as asmlinkage to match the way that system
314 If the system call involves a structure that is laid out differently on 32-bit
315 and 64-bit systems, say ``struct xyzzy_args``, then the include/linux/compat.h
317 compat_xyzzy_args``) where each variable-size field has the appropriate
320 parse the arguments from a 32-bit invocation.
340 The generic system call list also needs adjusting to allow for the compat
341 version; the entry in ``include/uapi/asm-generic/unistd.h`` should use
349  - a ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry point
350  - corresponding prototype in ``include/linux/compat.h``
351  - (if needed) 32-bit mapping struct in ``include/linux/compat.h``
352  - instance of ``__SC_COMP`` not ``__SYSCALL`` in
353    ``include/uapi/asm-generic/unistd.h``
356 Compatibility System Calls (x86)
357 --------------------------------
359 To wire up the x86 architecture of a system call with a compatibility version,
363 column to indicate that a 32-bit userspace program running on a 64-bit kernel
369 the new system call.  There's a choice here: the layout of the arguments
370 should either match the 64-bit version or the 32-bit version.
372 If there's a pointer-to-a-pointer involved, the decision is easy: x32 is
373 ILP32, so the layout should match the 32-bit version, and the entry in
381 If no pointers are involved, then it is preferable to re-use the 64-bit system
385 In either case, you should check that the types involved in your argument
386 layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or
387 64-bit (-m64) equivalents.
390 System Calls Returning Elsewhere
391 --------------------------------
393 For most system calls, once the system call is complete the user program
394 continues exactly where it left off -- at the next instruction, with the
395 stack the same and most of the registers the same as before the system call,
398 However, a few system calls do things differently.  They might return to a
403 To allow for this, the kernel implementation of the system call may need to
405 control of where and how execution continues after the system call.
407 This is arch-specific, but typically involves defining assembly entry points
408 that save/restore additional registers and invoke the real system call entry
417 The equivalent for 32-bit programs running on a 64-bit kernel is normally
424 If the system call needs a compatibility layer (as in the previous section)
426 of the system call rather than the native 64-bit version.  Also, if the x32 ABI
431 For completeness, it's also nice to set up a mapping so that user-mode Linux
432 still works -- its syscall table will reference stub_xyzzy, but the UML build
441 -------------
443 Most of the kernel treats system calls in a generic way, but there is the
444 occasional exception that may need updating for your particular system call.
446 The audit subsystem is one such special case; it includes (arch-specific)
447 functions that classify some special types of system call -- specifically
449 socket multiplexor (``socketcall``) operations. If your new system call is
450 analogous to one of these, then the audit system should be updated.
452 More generally, if there is an existing system call that is analogous to your
453 new system call, it's worth doing a kernel-wide grep for the existing system
454 call to check there are no other special cases.
458 -------
460 A new system call should obviously be tested; it is also useful to provide
461 reviewers with a demonstration of how user space programs will use the system
462 call.  A good way to combine these aims is to include a simple self-test
465 For a new system call, there will obviously be no libc wrapper function and so
466 the test will need to invoke it using ``syscall()``; also, if the system call
467 involves a new userspace-visible structure, the corresponding header will need
471 example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32)
472 and x32 (-mx32) ABI program.
476 for filesystem-related changes.
478  - https://linux-test-project.github.io/
479  - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git
483 --------
485 All new system calls should come with a complete man page, ideally using groff
487 pre-rendered ASCII version of the man page in the cover email for the
490 The man page should be cc'ed to linux-man@vger.kernel.org
491 For more details, see https://www.kernel.org/doc/man-pages/patches.html
494 Do not call System Calls in the Kernel
495 --------------------------------------
497 System calls are, as stated above, interaction points between userspace and
498 the kernel.  Therefore, system call functions such as ``sys_xyzzy()`` or
508 At least on 64-bit x86, it will be a hard requirement from v4.17 onwards to not
509 call system call functions in the kernel.  It uses a different calling
510 convention for system calls where ``struct pt_regs`` is decoded on-the-fly in a
521 Exceptions to this rule are only allowed in architecture-specific overrides,
522 architecture-specific compatibility wrappers, or other code in arch/.
526 ----------------------
528  - LWN article from Michael Kerrisk on use of flags argument in system calls:
530  - LWN article from Michael Kerrisk on how to handle unknown flags in a system
532  - LWN article from Jake Edge describing constraints on 64-bit system call
534  - Pair of LWN articles from David Drysdale that describe the system call
537     - https://lwn.net/Articles/604287/
538     - https://lwn.net/Articles/604515/
540  - Architecture-specific requirements for system calls are discussed in the
541    :manpage:`syscall(2)` man-page:
542    http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES
543  - Collated emails from Linus Torvalds discussing the problems with ``ioctl()``:
545  - "How to not invent kernel interfaces", Arnd Bergmann,
547  - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN:
549  - Recommendation from Andrew Morton that all related information for a new
550    system call should come in the same email thread:
551    https://lore.kernel.org/r/20140724144747.3041b208832bbdf9fbce5d96@linux-foundation.org
552  - Recommendation from Michael Kerrisk that a new system call should come with
554  - Suggestion from Thomas Gleixner that x86 wire-up should be in a separate
555    commit: https://lore.kernel.org/r/alpine.DEB.2.11.1411191249560.3909@nanos
556  - Suggestion from Greg Kroah-Hartman that it's good for new system calls to
557    come with a man-page & selftest: https://lore.kernel.org/r/20140320025530.GA25469@kroah.com
558  - Discussion from Michael Kerrisk of new system call vs. :manpage:`prctl(2)` extension:
559    https://lore.kernel.org/r/CAHO5Pa3F2MjfTtfNxa8LbnkeeU8=YJ+9tDqxZpw7Gz59E-4AUg@mail.gmail.com
560  - Suggestion from Ingo Molnar that system calls that involve multiple
563  - Numbering oddities arising from (re-)use of O_* numbering space flags:
565     - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness
566       check")
567     - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc
569     - commit bb458c644a59 ("Safer ABI for O_TMPFILE")
571  - Discussion from Matthew Wilcox about restrictions on 64-bit arguments:
572    https://lore.kernel.org/r/20081212152929.GM26095@parisc-linux.org
573  - Recommendation from Greg Kroah-Hartman that unknown flags should be
575  - Recommendation from Linus Torvalds that x32 system calls should prefer
576    compatibility with 64-bit versions rather than 32-bit versions: