Loading...
1
2.. _addsyscalls:
3
4Adding a New System Call
5========================
6
7This document describes what's involved in adding a new system call to the
8Linux kernel, over and above the normal submission advice in
9:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
10
11
12System Call Alternatives
13------------------------
14
15The first thing to consider when adding a new system call is whether one of
16the alternatives might be suitable instead. Although system calls are the
17most traditional and most obvious interaction points between userspace and the
18kernel, there are other possibilities -- choose what fits best for your
19interface.
20
21 - If the operations involved can be made to look like a filesystem-like
22 object, it may make more sense to create a new filesystem or device. This
23 also makes it easier to encapsulate the new functionality in a kernel module
24 rather than requiring it to be built into the main kernel.
25
26 - If the new functionality involves operations where the kernel notifies
27 userspace that something has happened, then returning a new file
28 descriptor for the relevant object allows userspace to use
29 ``poll``/``select``/``epoll`` to receive that notification.
30 - However, operations that don't map to
31 :manpage:`read(2)`/:manpage:`write(2)`-like operations
32 have to be implemented as :manpage:`ioctl(2)` requests, which can lead
33 to a somewhat opaque API.
34
35 - If you're just exposing runtime system information, a new node in sysfs
36 (see ``Documentation/filesystems/sysfs.rst``) or the ``/proc`` filesystem may
37 be more appropriate. However, access to these mechanisms requires that the
38 relevant filesystem is mounted, which might not always be the case (e.g.
39 in a namespaced/sandboxed/chrooted environment). Avoid adding any API to
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
42 an additional :manpage:`fcntl(2)` command option may be more appropriate. However,
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
46 (for example, getting/setting a simple flag related to a file descriptor).
47 - If the operation is specific to a particular task or process, then an
48 additional :manpage:`prctl(2)` command option may be more appropriate. As
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
51 getting/setting a simple flag related to a process.
52
53
54Designing the API: Planning for Extension
55-----------------------------------------
56
57A new system call forms part of the API of the kernel, and has to be supported
58indefinitely. As such, it's a very good idea to explicitly discuss the
59interface on the kernel mailing list, and it's important to plan for future
60extensions of the interface.
61
62(The syscall table is littered with historical examples where this wasn't done,
63together with the corresponding follow-up system calls --
64``eventfd``/``eventfd2``, ``dup2``/``dup3``, ``inotify_init``/``inotify_init1``,
65``pipe``/``pipe2``, ``renameat``/``renameat2`` -- so
66learn from the history of the kernel and plan for extensions from the start.)
67
68For simpler system calls that only take a couple of arguments, the preferred
69way to allow for future extensibility is to include a flags argument to the
70system call. To make sure that userspace programs can safely use flags
71between kernel versions, check whether the flags value holds any unknown
72flags, and reject the system call (with ``EINVAL``) if it does::
73
74 if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3))
75 return -EINVAL;
76
77(If no flags values are used yet, check that the flags argument is zero.)
78
79For more sophisticated system calls that involve a larger number of arguments,
80it's preferred to encapsulate the majority of the arguments into a structure
81that is passed in by pointer. Such a structure can cope with future extension
82by including a size argument in the structure::
83
84 struct xyzzy_params {
85 u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */
86 u32 param_1;
87 u64 param_2;
88 u64 param_3;
89 };
90
91As long as any subsequently added field, say ``param_4``, is designed so that a
92zero value gives the previous behaviour, then this allows both directions of
93version mismatch:
94
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
97 expects is zero (effectively checking that ``param_4 == 0``).
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
100 setting ``param_4 = 0``).
101
102See :manpage:`perf_event_open(2)` and the ``perf_copy_attr()`` function (in
103``kernel/events/core.c``) for an example of this approach.
104
105
106Designing the API: Other Considerations
107---------------------------------------
108
109If your new system call allows userspace to refer to a kernel object, it
110should use a file descriptor as the handle for that object -- don't invent a
111new type of userspace object handle when the kernel already has mechanisms and
112well-defined semantics for using file descriptors.
113
114If your new :manpage:`xyzzy(2)` system call does return a new file descriptor,
115then the flags argument should include a value that is equivalent to setting
116``O_CLOEXEC`` on the new FD. This makes it possible for userspace to close
117the timing window between ``xyzzy()`` and calling
118``fcntl(fd, F_SETFD, FD_CLOEXEC)``, where an unexpected ``fork()`` and
119``execve()`` in another thread could leak a descriptor to
120the exec'ed program. (However, resist the temptation to re-use the actual value
121of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a
122numbering space of ``O_*`` flags that is fairly full.)
123
124If your system call returns a new file descriptor, you should also consider
125what it means to use the :manpage:`poll(2)` family of system calls on that file
126descriptor. Making a file descriptor ready for reading or writing is the
127normal way for the kernel to indicate to userspace that an event has
128occurred on the corresponding kernel object.
129
130If your new :manpage:`xyzzy(2)` system call involves a filename argument::
131
132 int sys_xyzzy(const char __user *path, ..., unsigned int flags);
133
134you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate::
135
136 int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags);
137
138This allows more flexibility for how userspace specifies the file in question;
139in particular it allows userspace to request the functionality for an
140already-opened file descriptor using the ``AT_EMPTY_PATH`` flag, effectively
141giving an :manpage:`fxyzzy(3)` operation for free::
142
143 - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...)
144 - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...)
145
146(For more details on the rationale of the \*at() calls, see the
147:manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the
148:manpage:`fstatat(2)` man page.)
149
150If your new :manpage:`xyzzy(2)` system call involves a parameter describing an
151offset within a file, make its type ``loff_t`` so that 64-bit offsets can be
152supported even on 32-bit architectures.
153
154If your new :manpage:`xyzzy(2)` system call involves privileged functionality,
155it needs to be governed by the appropriate Linux capability bit (checked with
156a call to ``capable()``), as described in the :manpage:`capabilities(7)` man
157page. Choose an existing capability bit that governs related functionality,
158but try to avoid combining lots of only vaguely related functions together
159under the same bit, as this goes against capabilities' purpose of splitting
160the power of root. In particular, avoid adding new uses of the already
161overly-general ``CAP_SYS_ADMIN`` capability.
162
163If your new :manpage:`xyzzy(2)` system call manipulates a process other than
164the calling process, it should be restricted (using a call to
165``ptrace_may_access()``) so that only a calling process with the same
166permissions as the target process, or with the necessary capabilities, can
167manipulate the target process.
168
169Finally, be aware that some non-x86 architectures have an easier time if
170system call parameters that are explicitly 64-bit fall on odd-numbered
171arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit
172registers. (This concern does not apply if the arguments are part of a
173structure that's passed in by pointer.)
174
175
176Proposing the API
177-----------------
178
179To make new system calls easy to review, it's best to divide up the patchset
180into separate chunks. These should include at least the following items as
181distinct commits (each of which is described further below):
182
183 - The core implementation of the system call, together with prototypes,
184 generic numbering, Kconfig changes and fallback stub implementation.
185 - Wiring up of the new system call for one particular architecture, usually
186 x86 (including all of x86_64, x86_32 and x32).
187 - A demonstration of the use of the new system call in userspace via a
188 selftest in ``tools/testing/selftests/``.
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.
191
192New system call proposals, like any change to the kernel's API, should always
193be cc'ed to linux-api@vger.kernel.org.
194
195
196Generic System Call Implementation
197----------------------------------
198
199The main entry point for your new :manpage:`xyzzy(2)` system call will be called
200``sys_xyzzy()``, but you add this entry point with the appropriate
201``SYSCALL_DEFINEn()`` macro rather than explicitly. The 'n' indicates the
202number of arguments to the system call, and the macro takes the system call name
203followed by the (type, name) pairs for the parameters as arguments. Using
204this macro allows metadata about the new system call to be made available for
205other tools.
206
207The new entry point also needs a corresponding function prototype, in
208``include/linux/syscalls.h``, marked as asmlinkage to match the way that system
209calls are invoked::
210
211 asmlinkage long sys_xyzzy(...);
212
213Some architectures (e.g. x86) have their own architecture-specific syscall
214tables, but several other architectures share a generic syscall table. Add your
215new system call to the generic list by adding an entry to the list in
216``include/uapi/asm-generic/unistd.h``::
217
218 #define __NR_xyzzy 292
219 __SYSCALL(__NR_xyzzy, sys_xyzzy)
220
221Also update the __NR_syscalls count to reflect the additional system call, and
222note that if multiple new system calls are added in the same merge window,
223your new syscall number may get adjusted to resolve conflicts.
224
225The file ``kernel/sys_ni.c`` provides a fallback stub implementation of each
226system call, returning ``-ENOSYS``. Add your new system call here too::
227
228 COND_SYSCALL(xyzzy);
229
230Your new kernel functionality, and the system call that controls it, should
231normally be optional, so add a ``CONFIG`` option (typically to
232``init/Kconfig``) for it. As usual for new ``CONFIG`` options:
233
234 - Include a description of the new functionality and system call controlled
235 by the option.
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
240 off.
241
242To summarize, you need a commit that includes:
243
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``
249
250
251x86 System Call Implementation
252------------------------------
253
254To wire up your new system call for x86 platforms, you need to update the
255master syscall tables. Assuming your new system call isn't special in some
256way (see below), this involves a "common" entry (for x86_64 and x32) in
257arch/x86/entry/syscalls/syscall_64.tbl::
258
259 333 common xyzzy sys_xyzzy
260
261and an "i386" entry in ``arch/x86/entry/syscalls/syscall_32.tbl``::
262
263 380 i386 xyzzy sys_xyzzy
264
265Again, these numbers are liable to be changed if there are conflicts in the
266relevant merge window.
267
268
269Compatibility System Calls (Generic)
270------------------------------------
271
272For most system calls the same 64-bit implementation can be invoked even when
273the userspace program is itself 32-bit; even if the system call's parameters
274include an explicit pointer, this is handled transparently.
275
276However, there are a couple of situations where a compatibility layer is
277needed to cope with size differences between 32-bit and 64-bit.
278
279The first is if the 64-bit kernel also supports 32-bit userspace programs, and
280so needs to parse areas of (``__user``) memory that could hold either 32-bit or
28164-bit values. In particular, this is needed whenever a system call argument
282is:
283
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``,
287 ``long``, ...)
288 - a pointer to a struct containing a varying sized integral type.
289
290The second situation that requires a compatibility layer is if one of the
291system call's arguments has a type that is explicitly 64-bit even on a 32-bit
292architecture, for example ``loff_t`` or ``__u64``. In this case, a value that
293arrives at a 64-bit kernel from a 32-bit application will be split into two
29432-bit values, which then need to be re-assembled in the compatibility layer.
295
296(Note that a system call argument that's a pointer to an explicit 64-bit type
297does **not** need a compatibility layer; for example, :manpage:`splice(2)`'s arguments of
298type ``loff_t __user *`` do not trigger the need for a ``compat_`` system call.)
299
300The compatibility version of the system call is called ``compat_sys_xyzzy()``,
301and is added with the ``COMPAT_SYSCALL_DEFINEn()`` macro, analogously to
302SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit
303kernel, but expects to receive 32-bit parameter values and does whatever is
304needed to deal with them. (Typically, the ``compat_sys_`` version converts the
305values to 64-bit versions and either calls on to the ``sys_`` version, or both of
306them call a common inner implementation function.)
307
308The compat entry point also needs a corresponding function prototype, in
309``include/linux/compat.h``, marked as asmlinkage to match the way that system
310calls are invoked::
311
312 asmlinkage long compat_sys_xyzzy(...);
313
314If the system call involves a structure that is laid out differently on 32-bit
315and 64-bit systems, say ``struct xyzzy_args``, then the include/linux/compat.h
316header file should also include a compat version of the structure (``struct
317compat_xyzzy_args``) where each variable-size field has the appropriate
318``compat_`` type that corresponds to the type in ``struct xyzzy_args``. The
319``compat_sys_xyzzy()`` routine can then use this ``compat_`` structure to
320parse the arguments from a 32-bit invocation.
321
322For example, if there are fields::
323
324 struct xyzzy_args {
325 const char __user *ptr;
326 __kernel_long_t varying_val;
327 u64 fixed_val;
328 /* ... */
329 };
330
331in struct xyzzy_args, then struct compat_xyzzy_args would have::
332
333 struct compat_xyzzy_args {
334 compat_uptr_t ptr;
335 compat_long_t varying_val;
336 u64 fixed_val;
337 /* ... */
338 };
339
340The generic system call list also needs adjusting to allow for the compat
341version; the entry in ``include/uapi/asm-generic/unistd.h`` should use
342``__SC_COMP`` rather than ``__SYSCALL``::
343
344 #define __NR_xyzzy 292
345 __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy)
346
347To summarize, you need:
348
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``
354
355
356Compatibility System Calls (x86)
357--------------------------------
358
359To wire up the x86 architecture of a system call with a compatibility version,
360the entries in the syscall tables need to be adjusted.
361
362First, the entry in ``arch/x86/entry/syscalls/syscall_32.tbl`` gets an extra
363column to indicate that a 32-bit userspace program running on a 64-bit kernel
364should hit the compat entry point::
365
366 380 i386 xyzzy sys_xyzzy __ia32_compat_sys_xyzzy
367
368Second, you need to figure out what should happen for the x32 ABI version of
369the new system call. There's a choice here: the layout of the arguments
370should either match the 64-bit version or the 32-bit version.
371
372If there's a pointer-to-a-pointer involved, the decision is easy: x32 is
373ILP32, so the layout should match the 32-bit version, and the entry in
374``arch/x86/entry/syscalls/syscall_64.tbl`` is split so that x32 programs hit
375the compatibility wrapper::
376
377 333 64 xyzzy sys_xyzzy
378 ...
379 555 x32 xyzzy __x32_compat_sys_xyzzy
380
381If no pointers are involved, then it is preferable to re-use the 64-bit system
382call for the x32 ABI (and consequently the entry in
383arch/x86/entry/syscalls/syscall_64.tbl is unchanged).
384
385In either case, you should check that the types involved in your argument
386layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or
38764-bit (-m64) equivalents.
388
389
390System Calls Returning Elsewhere
391--------------------------------
392
393For most system calls, once the system call is complete the user program
394continues exactly where it left off -- at the next instruction, with the
395stack the same and most of the registers the same as before the system call,
396and with the same virtual memory space.
397
398However, a few system calls do things differently. They might return to a
399different location (``rt_sigreturn``) or change the memory space
400(``fork``/``vfork``/``clone``) or even architecture (``execve``/``execveat``)
401of the program.
402
403To allow for this, the kernel implementation of the system call may need to
404save and restore additional registers to the kernel stack, allowing complete
405control of where and how execution continues after the system call.
406
407This is arch-specific, but typically involves defining assembly entry points
408that save/restore additional registers and invoke the real system call entry
409point.
410
411For x86_64, this is implemented as a ``stub_xyzzy`` entry point in
412``arch/x86/entry/entry_64.S``, and the entry in the syscall table
413(``arch/x86/entry/syscalls/syscall_64.tbl``) is adjusted to match::
414
415 333 common xyzzy stub_xyzzy
416
417The equivalent for 32-bit programs running on a 64-bit kernel is normally
418called ``stub32_xyzzy`` and implemented in ``arch/x86/entry/entry_64_compat.S``,
419with the corresponding syscall table adjustment in
420``arch/x86/entry/syscalls/syscall_32.tbl``::
421
422 380 i386 xyzzy sys_xyzzy stub32_xyzzy
423
424If the system call needs a compatibility layer (as in the previous section)
425then the ``stub32_`` version needs to call on to the ``compat_sys_`` version
426of the system call rather than the native 64-bit version. Also, if the x32 ABI
427implementation is not common with the x86_64 version, then its syscall
428table will also need to invoke a stub that calls on to the ``compat_sys_``
429version.
430
431For completeness, it's also nice to set up a mapping so that user-mode Linux
432still works -- its syscall table will reference stub_xyzzy, but the UML build
433doesn't include ``arch/x86/entry/entry_64.S`` implementation (because UML
434simulates registers etc). Fixing this is as simple as adding a #define to
435``arch/x86/um/sys_call_table_64.c``::
436
437 #define stub_xyzzy sys_xyzzy
438
439
440Other Details
441-------------
442
443Most of the kernel treats system calls in a generic way, but there is the
444occasional exception that may need updating for your particular system call.
445
446The audit subsystem is one such special case; it includes (arch-specific)
447functions that classify some special types of system call -- specifically
448file open (``open``/``openat``), program execution (``execve``/``exeveat``) or
449socket multiplexor (``socketcall``) operations. If your new system call is
450analogous to one of these, then the audit system should be updated.
451
452More generally, if there is an existing system call that is analogous to your
453new system call, it's worth doing a kernel-wide grep for the existing system
454call to check there are no other special cases.
455
456
457Testing
458-------
459
460A new system call should obviously be tested; it is also useful to provide
461reviewers with a demonstration of how user space programs will use the system
462call. A good way to combine these aims is to include a simple self-test
463program in a new directory under ``tools/testing/selftests/``.
464
465For a new system call, there will obviously be no libc wrapper function and so
466the test will need to invoke it using ``syscall()``; also, if the system call
467involves a new userspace-visible structure, the corresponding header will need
468to be installed to compile the test.
469
470Make sure the selftest runs successfully on all supported architectures. For
471example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32)
472and x32 (-mx32) ABI program.
473
474For more extensive and thorough testing of new functionality, you should also
475consider adding tests to the Linux Test Project, or to the xfstests project
476for filesystem-related changes.
477
478 - https://linux-test-project.github.io/
479 - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git
480
481
482Man Page
483--------
484
485All new system calls should come with a complete man page, ideally using groff
486markup, but plain text will do. If groff is used, it's helpful to include a
487pre-rendered ASCII version of the man page in the cover email for the
488patchset, for the convenience of reviewers.
489
490The man page should be cc'ed to linux-man@vger.kernel.org
491For more details, see https://www.kernel.org/doc/man-pages/patches.html
492
493
494Do not call System Calls in the Kernel
495--------------------------------------
496
497System calls are, as stated above, interaction points between userspace and
498the kernel. Therefore, system call functions such as ``sys_xyzzy()`` or
499``compat_sys_xyzzy()`` should only be called from userspace via the syscall
500table, but not from elsewhere in the kernel. If the syscall functionality is
501useful to be used within the kernel, needs to be shared between an old and a
502new syscall, or needs to be shared between a syscall and its compatibility
503variant, it should be implemented by means of a "helper" function (such as
504``ksys_xyzzy()``). This kernel function may then be called within the
505syscall stub (``sys_xyzzy()``), the compatibility syscall stub
506(``compat_sys_xyzzy()``), and/or other kernel code.
507
508At least on 64-bit x86, it will be a hard requirement from v4.17 onwards to not
509call system call functions in the kernel. It uses a different calling
510convention for system calls where ``struct pt_regs`` is decoded on-the-fly in a
511syscall wrapper which then hands processing over to the actual syscall function.
512This means that only those parameters which are actually needed for a specific
513syscall are passed on during syscall entry, instead of filling in six CPU
514registers with random user space content all the time (which may cause serious
515trouble down the call chain).
516
517Moreover, rules on how data may be accessed may differ between kernel data and
518user data. This is another reason why calling ``sys_xyzzy()`` is generally a
519bad idea.
520
521Exceptions to this rule are only allowed in architecture-specific overrides,
522architecture-specific compatibility wrappers, or other code in arch/.
523
524
525References and Sources
526----------------------
527
528 - LWN article from Michael Kerrisk on use of flags argument in system calls:
529 https://lwn.net/Articles/585415/
530 - LWN article from Michael Kerrisk on how to handle unknown flags in a system
531 call: https://lwn.net/Articles/588444/
532 - LWN article from Jake Edge describing constraints on 64-bit system call
533 arguments: https://lwn.net/Articles/311630/
534 - Pair of LWN articles from David Drysdale that describe the system call
535 implementation paths in detail for v3.14:
536
537 - https://lwn.net/Articles/604287/
538 - https://lwn.net/Articles/604515/
539
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()``:
544 https://yarchive.net/comp/linux/ioctl.html
545 - "How to not invent kernel interfaces", Arnd Bergmann,
546 https://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf
547 - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN:
548 https://lwn.net/Articles/486306/
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
553 a man page: https://lore.kernel.org/r/CAKgNAkgMA39AfoSoA5Pe1r9N+ZzfYQNvNPvcRN7tOvRb8+v06Q@mail.gmail.com
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
561 arguments should encapsulate those arguments in a struct, which includes a
562 size field for future extensibility: https://lore.kernel.org/r/20150730083831.GA22182@gmail.com
563 - Numbering oddities arising from (re-)use of O_* numbering space flags:
564
565 - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness
566 check")
567 - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc
568 conflict")
569 - commit bb458c644a59 ("Safer ABI for O_TMPFILE")
570
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
574 policed: https://lore.kernel.org/r/20140717193330.GB4703@kroah.com
575 - Recommendation from Linus Torvalds that x32 system calls should prefer
576 compatibility with 64-bit versions rather than 32-bit versions:
577 https://lore.kernel.org/r/CA+55aFxfmwfB7jbbrXxa=K7VBYPfAvmu3XOkGrLbB1UFjX1+Ew@mail.gmail.com
1Adding a New System Call
2========================
3
4This document describes what's involved in adding a new system call to the
5Linux kernel, over and above the normal submission advice in
6:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
7
8
9System Call Alternatives
10------------------------
11
12The first thing to consider when adding a new system call is whether one of
13the alternatives might be suitable instead. Although system calls are the
14most traditional and most obvious interaction points between userspace and the
15kernel, there are other possibilities -- choose what fits best for your
16interface.
17
18 - If the operations involved can be made to look like a filesystem-like
19 object, it may make more sense to create a new filesystem or device. This
20 also makes it easier to encapsulate the new functionality in a kernel module
21 rather than requiring it to be built into the main kernel.
22
23 - If the new functionality involves operations where the kernel notifies
24 userspace that something has happened, then returning a new file
25 descriptor for the relevant object allows userspace to use
26 ``poll``/``select``/``epoll`` to receive that notification.
27 - However, operations that don't map to
28 :manpage:`read(2)`/:manpage:`write(2)`-like operations
29 have to be implemented as :manpage:`ioctl(2)` requests, which can lead
30 to a somewhat opaque API.
31
32 - If you're just exposing runtime system information, a new node in sysfs
33 (see ``Documentation/filesystems/sysfs.txt``) or the ``/proc`` filesystem may
34 be more appropriate. However, access to these mechanisms requires that the
35 relevant filesystem is mounted, which might not always be the case (e.g.
36 in a namespaced/sandboxed/chrooted environment). Avoid adding any API to
37 debugfs, as this is not considered a 'production' interface to userspace.
38 - If the operation is specific to a particular file or file descriptor, then
39 an additional :manpage:`fcntl(2)` command option may be more appropriate. However,
40 :manpage:`fcntl(2)` is a multiplexing system call that hides a lot of complexity, so
41 this option is best for when the new function is closely analogous to
42 existing :manpage:`fcntl(2)` functionality, or the new functionality is very simple
43 (for example, getting/setting a simple flag related to a file descriptor).
44 - If the operation is specific to a particular task or process, then an
45 additional :manpage:`prctl(2)` command option may be more appropriate. As
46 with :manpage:`fcntl(2)`, this system call is a complicated multiplexor so
47 is best reserved for near-analogs of existing ``prctl()`` commands or
48 getting/setting a simple flag related to a process.
49
50
51Designing the API: Planning for Extension
52-----------------------------------------
53
54A new system call forms part of the API of the kernel, and has to be supported
55indefinitely. As such, it's a very good idea to explicitly discuss the
56interface on the kernel mailing list, and it's important to plan for future
57extensions of the interface.
58
59(The syscall table is littered with historical examples where this wasn't done,
60together with the corresponding follow-up system calls --
61``eventfd``/``eventfd2``, ``dup2``/``dup3``, ``inotify_init``/``inotify_init1``,
62``pipe``/``pipe2``, ``renameat``/``renameat2`` -- so
63learn from the history of the kernel and plan for extensions from the start.)
64
65For simpler system calls that only take a couple of arguments, the preferred
66way to allow for future extensibility is to include a flags argument to the
67system call. To make sure that userspace programs can safely use flags
68between kernel versions, check whether the flags value holds any unknown
69flags, and reject the system call (with ``EINVAL``) if it does::
70
71 if (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3))
72 return -EINVAL;
73
74(If no flags values are used yet, check that the flags argument is zero.)
75
76For more sophisticated system calls that involve a larger number of arguments,
77it's preferred to encapsulate the majority of the arguments into a structure
78that is passed in by pointer. Such a structure can cope with future extension
79by including a size argument in the structure::
80
81 struct xyzzy_params {
82 u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */
83 u32 param_1;
84 u64 param_2;
85 u64 param_3;
86 };
87
88As long as any subsequently added field, say ``param_4``, is designed so that a
89zero value gives the previous behaviour, then this allows both directions of
90version mismatch:
91
92 - To cope with a later userspace program calling an older kernel, the kernel
93 code should check that any memory beyond the size of the structure that it
94 expects is zero (effectively checking that ``param_4 == 0``).
95 - To cope with an older userspace program calling a newer kernel, the kernel
96 code can zero-extend a smaller instance of the structure (effectively
97 setting ``param_4 = 0``).
98
99See :manpage:`perf_event_open(2)` and the ``perf_copy_attr()`` function (in
100``kernel/events/core.c``) for an example of this approach.
101
102
103Designing the API: Other Considerations
104---------------------------------------
105
106If your new system call allows userspace to refer to a kernel object, it
107should use a file descriptor as the handle for that object -- don't invent a
108new type of userspace object handle when the kernel already has mechanisms and
109well-defined semantics for using file descriptors.
110
111If your new :manpage:`xyzzy(2)` system call does return a new file descriptor,
112then the flags argument should include a value that is equivalent to setting
113``O_CLOEXEC`` on the new FD. This makes it possible for userspace to close
114the timing window between ``xyzzy()`` and calling
115``fcntl(fd, F_SETFD, FD_CLOEXEC)``, where an unexpected ``fork()`` and
116``execve()`` in another thread could leak a descriptor to
117the exec'ed program. (However, resist the temptation to re-use the actual value
118of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a
119numbering space of ``O_*`` flags that is fairly full.)
120
121If your system call returns a new file descriptor, you should also consider
122what it means to use the :manpage:`poll(2)` family of system calls on that file
123descriptor. Making a file descriptor ready for reading or writing is the
124normal way for the kernel to indicate to userspace that an event has
125occurred on the corresponding kernel object.
126
127If your new :manpage:`xyzzy(2)` system call involves a filename argument::
128
129 int sys_xyzzy(const char __user *path, ..., unsigned int flags);
130
131you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate::
132
133 int sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags);
134
135This allows more flexibility for how userspace specifies the file in question;
136in particular it allows userspace to request the functionality for an
137already-opened file descriptor using the ``AT_EMPTY_PATH`` flag, effectively
138giving an :manpage:`fxyzzy(3)` operation for free::
139
140 - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...)
141 - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...)
142
143(For more details on the rationale of the \*at() calls, see the
144:manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the
145:manpage:`fstatat(2)` man page.)
146
147If your new :manpage:`xyzzy(2)` system call involves a parameter describing an
148offset within a file, make its type ``loff_t`` so that 64-bit offsets can be
149supported even on 32-bit architectures.
150
151If your new :manpage:`xyzzy(2)` system call involves privileged functionality,
152it needs to be governed by the appropriate Linux capability bit (checked with
153a call to ``capable()``), as described in the :manpage:`capabilities(7)` man
154page. Choose an existing capability bit that governs related functionality,
155but try to avoid combining lots of only vaguely related functions together
156under the same bit, as this goes against capabilities' purpose of splitting
157the power of root. In particular, avoid adding new uses of the already
158overly-general ``CAP_SYS_ADMIN`` capability.
159
160If your new :manpage:`xyzzy(2)` system call manipulates a process other than
161the calling process, it should be restricted (using a call to
162``ptrace_may_access()``) so that only a calling process with the same
163permissions as the target process, or with the necessary capabilities, can
164manipulate the target process.
165
166Finally, be aware that some non-x86 architectures have an easier time if
167system call parameters that are explicitly 64-bit fall on odd-numbered
168arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit
169registers. (This concern does not apply if the arguments are part of a
170structure that's passed in by pointer.)
171
172
173Proposing the API
174-----------------
175
176To make new system calls easy to review, it's best to divide up the patchset
177into separate chunks. These should include at least the following items as
178distinct commits (each of which is described further below):
179
180 - The core implementation of the system call, together with prototypes,
181 generic numbering, Kconfig changes and fallback stub implementation.
182 - Wiring up of the new system call for one particular architecture, usually
183 x86 (including all of x86_64, x86_32 and x32).
184 - A demonstration of the use of the new system call in userspace via a
185 selftest in ``tools/testing/selftests/``.
186 - A draft man-page for the new system call, either as plain text in the
187 cover letter, or as a patch to the (separate) man-pages repository.
188
189New system call proposals, like any change to the kernel's API, should always
190be cc'ed to linux-api@vger.kernel.org.
191
192
193Generic System Call Implementation
194----------------------------------
195
196The main entry point for your new :manpage:`xyzzy(2)` system call will be called
197``sys_xyzzy()``, but you add this entry point with the appropriate
198``SYSCALL_DEFINEn()`` macro rather than explicitly. The 'n' indicates the
199number of arguments to the system call, and the macro takes the system call name
200followed by the (type, name) pairs for the parameters as arguments. Using
201this macro allows metadata about the new system call to be made available for
202other tools.
203
204The new entry point also needs a corresponding function prototype, in
205``include/linux/syscalls.h``, marked as asmlinkage to match the way that system
206calls are invoked::
207
208 asmlinkage long sys_xyzzy(...);
209
210Some architectures (e.g. x86) have their own architecture-specific syscall
211tables, but several other architectures share a generic syscall table. Add your
212new system call to the generic list by adding an entry to the list in
213``include/uapi/asm-generic/unistd.h``::
214
215 #define __NR_xyzzy 292
216 __SYSCALL(__NR_xyzzy, sys_xyzzy)
217
218Also update the __NR_syscalls count to reflect the additional system call, and
219note that if multiple new system calls are added in the same merge window,
220your new syscall number may get adjusted to resolve conflicts.
221
222The file ``kernel/sys_ni.c`` provides a fallback stub implementation of each
223system call, returning ``-ENOSYS``. Add your new system call here too::
224
225 COND_SYSCALL(xyzzy);
226
227Your new kernel functionality, and the system call that controls it, should
228normally be optional, so add a ``CONFIG`` option (typically to
229``init/Kconfig``) for it. As usual for new ``CONFIG`` options:
230
231 - Include a description of the new functionality and system call controlled
232 by the option.
233 - Make the option depend on EXPERT if it should be hidden from normal users.
234 - Make any new source files implementing the function dependent on the CONFIG
235 option in the Makefile (e.g. ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.c``).
236 - Double check that the kernel still builds with the new CONFIG option turned
237 off.
238
239To summarize, you need a commit that includes:
240
241 - ``CONFIG`` option for the new function, normally in ``init/Kconfig``
242 - ``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry point
243 - corresponding prototype in ``include/linux/syscalls.h``
244 - generic table entry in ``include/uapi/asm-generic/unistd.h``
245 - fallback stub in ``kernel/sys_ni.c``
246
247
248x86 System Call Implementation
249------------------------------
250
251To wire up your new system call for x86 platforms, you need to update the
252master syscall tables. Assuming your new system call isn't special in some
253way (see below), this involves a "common" entry (for x86_64 and x32) in
254arch/x86/entry/syscalls/syscall_64.tbl::
255
256 333 common xyzzy sys_xyzzy
257
258and an "i386" entry in ``arch/x86/entry/syscalls/syscall_32.tbl``::
259
260 380 i386 xyzzy sys_xyzzy
261
262Again, these numbers are liable to be changed if there are conflicts in the
263relevant merge window.
264
265
266Compatibility System Calls (Generic)
267------------------------------------
268
269For most system calls the same 64-bit implementation can be invoked even when
270the userspace program is itself 32-bit; even if the system call's parameters
271include an explicit pointer, this is handled transparently.
272
273However, there are a couple of situations where a compatibility layer is
274needed to cope with size differences between 32-bit and 64-bit.
275
276The first is if the 64-bit kernel also supports 32-bit userspace programs, and
277so needs to parse areas of (``__user``) memory that could hold either 32-bit or
27864-bit values. In particular, this is needed whenever a system call argument
279is:
280
281 - a pointer to a pointer
282 - a pointer to a struct containing a pointer (e.g. ``struct iovec __user *``)
283 - a pointer to a varying sized integral type (``time_t``, ``off_t``,
284 ``long``, ...)
285 - a pointer to a struct containing a varying sized integral type.
286
287The second situation that requires a compatibility layer is if one of the
288system call's arguments has a type that is explicitly 64-bit even on a 32-bit
289architecture, for example ``loff_t`` or ``__u64``. In this case, a value that
290arrives at a 64-bit kernel from a 32-bit application will be split into two
29132-bit values, which then need to be re-assembled in the compatibility layer.
292
293(Note that a system call argument that's a pointer to an explicit 64-bit type
294does **not** need a compatibility layer; for example, :manpage:`splice(2)`'s arguments of
295type ``loff_t __user *`` do not trigger the need for a ``compat_`` system call.)
296
297The compatibility version of the system call is called ``compat_sys_xyzzy()``,
298and is added with the ``COMPAT_SYSCALL_DEFINEn()`` macro, analogously to
299SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit
300kernel, but expects to receive 32-bit parameter values and does whatever is
301needed to deal with them. (Typically, the ``compat_sys_`` version converts the
302values to 64-bit versions and either calls on to the ``sys_`` version, or both of
303them call a common inner implementation function.)
304
305The compat entry point also needs a corresponding function prototype, in
306``include/linux/compat.h``, marked as asmlinkage to match the way that system
307calls are invoked::
308
309 asmlinkage long compat_sys_xyzzy(...);
310
311If the system call involves a structure that is laid out differently on 32-bit
312and 64-bit systems, say ``struct xyzzy_args``, then the include/linux/compat.h
313header file should also include a compat version of the structure (``struct
314compat_xyzzy_args``) where each variable-size field has the appropriate
315``compat_`` type that corresponds to the type in ``struct xyzzy_args``. The
316``compat_sys_xyzzy()`` routine can then use this ``compat_`` structure to
317parse the arguments from a 32-bit invocation.
318
319For example, if there are fields::
320
321 struct xyzzy_args {
322 const char __user *ptr;
323 __kernel_long_t varying_val;
324 u64 fixed_val;
325 /* ... */
326 };
327
328in struct xyzzy_args, then struct compat_xyzzy_args would have::
329
330 struct compat_xyzzy_args {
331 compat_uptr_t ptr;
332 compat_long_t varying_val;
333 u64 fixed_val;
334 /* ... */
335 };
336
337The generic system call list also needs adjusting to allow for the compat
338version; the entry in ``include/uapi/asm-generic/unistd.h`` should use
339``__SC_COMP`` rather than ``__SYSCALL``::
340
341 #define __NR_xyzzy 292
342 __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy)
343
344To summarize, you need:
345
346 - a ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry point
347 - corresponding prototype in ``include/linux/compat.h``
348 - (if needed) 32-bit mapping struct in ``include/linux/compat.h``
349 - instance of ``__SC_COMP`` not ``__SYSCALL`` in
350 ``include/uapi/asm-generic/unistd.h``
351
352
353Compatibility System Calls (x86)
354--------------------------------
355
356To wire up the x86 architecture of a system call with a compatibility version,
357the entries in the syscall tables need to be adjusted.
358
359First, the entry in ``arch/x86/entry/syscalls/syscall_32.tbl`` gets an extra
360column to indicate that a 32-bit userspace program running on a 64-bit kernel
361should hit the compat entry point::
362
363 380 i386 xyzzy sys_xyzzy __ia32_compat_sys_xyzzy
364
365Second, you need to figure out what should happen for the x32 ABI version of
366the new system call. There's a choice here: the layout of the arguments
367should either match the 64-bit version or the 32-bit version.
368
369If there's a pointer-to-a-pointer involved, the decision is easy: x32 is
370ILP32, so the layout should match the 32-bit version, and the entry in
371``arch/x86/entry/syscalls/syscall_64.tbl`` is split so that x32 programs hit
372the compatibility wrapper::
373
374 333 64 xyzzy sys_xyzzy
375 ...
376 555 x32 xyzzy __x32_compat_sys_xyzzy
377
378If no pointers are involved, then it is preferable to re-use the 64-bit system
379call for the x32 ABI (and consequently the entry in
380arch/x86/entry/syscalls/syscall_64.tbl is unchanged).
381
382In either case, you should check that the types involved in your argument
383layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or
38464-bit (-m64) equivalents.
385
386
387System Calls Returning Elsewhere
388--------------------------------
389
390For most system calls, once the system call is complete the user program
391continues exactly where it left off -- at the next instruction, with the
392stack the same and most of the registers the same as before the system call,
393and with the same virtual memory space.
394
395However, a few system calls do things differently. They might return to a
396different location (``rt_sigreturn``) or change the memory space
397(``fork``/``vfork``/``clone``) or even architecture (``execve``/``execveat``)
398of the program.
399
400To allow for this, the kernel implementation of the system call may need to
401save and restore additional registers to the kernel stack, allowing complete
402control of where and how execution continues after the system call.
403
404This is arch-specific, but typically involves defining assembly entry points
405that save/restore additional registers and invoke the real system call entry
406point.
407
408For x86_64, this is implemented as a ``stub_xyzzy`` entry point in
409``arch/x86/entry/entry_64.S``, and the entry in the syscall table
410(``arch/x86/entry/syscalls/syscall_64.tbl``) is adjusted to match::
411
412 333 common xyzzy stub_xyzzy
413
414The equivalent for 32-bit programs running on a 64-bit kernel is normally
415called ``stub32_xyzzy`` and implemented in ``arch/x86/entry/entry_64_compat.S``,
416with the corresponding syscall table adjustment in
417``arch/x86/entry/syscalls/syscall_32.tbl``::
418
419 380 i386 xyzzy sys_xyzzy stub32_xyzzy
420
421If the system call needs a compatibility layer (as in the previous section)
422then the ``stub32_`` version needs to call on to the ``compat_sys_`` version
423of the system call rather than the native 64-bit version. Also, if the x32 ABI
424implementation is not common with the x86_64 version, then its syscall
425table will also need to invoke a stub that calls on to the ``compat_sys_``
426version.
427
428For completeness, it's also nice to set up a mapping so that user-mode Linux
429still works -- its syscall table will reference stub_xyzzy, but the UML build
430doesn't include ``arch/x86/entry/entry_64.S`` implementation (because UML
431simulates registers etc). Fixing this is as simple as adding a #define to
432``arch/x86/um/sys_call_table_64.c``::
433
434 #define stub_xyzzy sys_xyzzy
435
436
437Other Details
438-------------
439
440Most of the kernel treats system calls in a generic way, but there is the
441occasional exception that may need updating for your particular system call.
442
443The audit subsystem is one such special case; it includes (arch-specific)
444functions that classify some special types of system call -- specifically
445file open (``open``/``openat``), program execution (``execve``/``exeveat``) or
446socket multiplexor (``socketcall``) operations. If your new system call is
447analogous to one of these, then the audit system should be updated.
448
449More generally, if there is an existing system call that is analogous to your
450new system call, it's worth doing a kernel-wide grep for the existing system
451call to check there are no other special cases.
452
453
454Testing
455-------
456
457A new system call should obviously be tested; it is also useful to provide
458reviewers with a demonstration of how user space programs will use the system
459call. A good way to combine these aims is to include a simple self-test
460program in a new directory under ``tools/testing/selftests/``.
461
462For a new system call, there will obviously be no libc wrapper function and so
463the test will need to invoke it using ``syscall()``; also, if the system call
464involves a new userspace-visible structure, the corresponding header will need
465to be installed to compile the test.
466
467Make sure the selftest runs successfully on all supported architectures. For
468example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32)
469and x32 (-mx32) ABI program.
470
471For more extensive and thorough testing of new functionality, you should also
472consider adding tests to the Linux Test Project, or to the xfstests project
473for filesystem-related changes.
474
475 - https://linux-test-project.github.io/
476 - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git
477
478
479Man Page
480--------
481
482All new system calls should come with a complete man page, ideally using groff
483markup, but plain text will do. If groff is used, it's helpful to include a
484pre-rendered ASCII version of the man page in the cover email for the
485patchset, for the convenience of reviewers.
486
487The man page should be cc'ed to linux-man@vger.kernel.org
488For more details, see https://www.kernel.org/doc/man-pages/patches.html
489
490
491Do not call System Calls in the Kernel
492--------------------------------------
493
494System calls are, as stated above, interaction points between userspace and
495the kernel. Therefore, system call functions such as ``sys_xyzzy()`` or
496``compat_sys_xyzzy()`` should only be called from userspace via the syscall
497table, but not from elsewhere in the kernel. If the syscall functionality is
498useful to be used within the kernel, needs to be shared between an old and a
499new syscall, or needs to be shared between a syscall and its compatibility
500variant, it should be implemented by means of a "helper" function (such as
501``kern_xyzzy()``). This kernel function may then be called within the
502syscall stub (``sys_xyzzy()``), the compatibility syscall stub
503(``compat_sys_xyzzy()``), and/or other kernel code.
504
505At least on 64-bit x86, it will be a hard requirement from v4.17 onwards to not
506call system call functions in the kernel. It uses a different calling
507convention for system calls where ``struct pt_regs`` is decoded on-the-fly in a
508syscall wrapper which then hands processing over to the actual syscall function.
509This means that only those parameters which are actually needed for a specific
510syscall are passed on during syscall entry, instead of filling in six CPU
511registers with random user space content all the time (which may cause serious
512trouble down the call chain).
513
514Moreover, rules on how data may be accessed may differ between kernel data and
515user data. This is another reason why calling ``sys_xyzzy()`` is generally a
516bad idea.
517
518Exceptions to this rule are only allowed in architecture-specific overrides,
519architecture-specific compatibility wrappers, or other code in arch/.
520
521
522References and Sources
523----------------------
524
525 - LWN article from Michael Kerrisk on use of flags argument in system calls:
526 https://lwn.net/Articles/585415/
527 - LWN article from Michael Kerrisk on how to handle unknown flags in a system
528 call: https://lwn.net/Articles/588444/
529 - LWN article from Jake Edge describing constraints on 64-bit system call
530 arguments: https://lwn.net/Articles/311630/
531 - Pair of LWN articles from David Drysdale that describe the system call
532 implementation paths in detail for v3.14:
533
534 - https://lwn.net/Articles/604287/
535 - https://lwn.net/Articles/604515/
536
537 - Architecture-specific requirements for system calls are discussed in the
538 :manpage:`syscall(2)` man-page:
539 http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES
540 - Collated emails from Linus Torvalds discussing the problems with ``ioctl()``:
541 http://yarchive.net/comp/linux/ioctl.html
542 - "How to not invent kernel interfaces", Arnd Bergmann,
543 http://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf
544 - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN:
545 https://lwn.net/Articles/486306/
546 - Recommendation from Andrew Morton that all related information for a new
547 system call should come in the same email thread:
548 https://lkml.org/lkml/2014/7/24/641
549 - Recommendation from Michael Kerrisk that a new system call should come with
550 a man page: https://lkml.org/lkml/2014/6/13/309
551 - Suggestion from Thomas Gleixner that x86 wire-up should be in a separate
552 commit: https://lkml.org/lkml/2014/11/19/254
553 - Suggestion from Greg Kroah-Hartman that it's good for new system calls to
554 come with a man-page & selftest: https://lkml.org/lkml/2014/3/19/710
555 - Discussion from Michael Kerrisk of new system call vs. :manpage:`prctl(2)` extension:
556 https://lkml.org/lkml/2014/6/3/411
557 - Suggestion from Ingo Molnar that system calls that involve multiple
558 arguments should encapsulate those arguments in a struct, which includes a
559 size field for future extensibility: https://lkml.org/lkml/2015/7/30/117
560 - Numbering oddities arising from (re-)use of O_* numbering space flags:
561
562 - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness
563 check")
564 - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc
565 conflict")
566 - commit bb458c644a59 ("Safer ABI for O_TMPFILE")
567
568 - Discussion from Matthew Wilcox about restrictions on 64-bit arguments:
569 https://lkml.org/lkml/2008/12/12/187
570 - Recommendation from Greg Kroah-Hartman that unknown flags should be
571 policed: https://lkml.org/lkml/2014/7/17/577
572 - Recommendation from Linus Torvalds that x32 system calls should prefer
573 compatibility with 64-bit versions rather than 32-bit versions:
574 https://lkml.org/lkml/2011/8/31/244