1
2 .. _addsyscalls:
3
4 Adding a New System Call
5 ========================
6
7 This document describes what's involved in add
8 Linux kernel, over and above the normal submis
9 :ref:`Documentation/process/submitting-patches
10
11
12 System Call Alternatives
13 ------------------------
14
15 The first thing to consider when adding a new
16 the alternatives might be suitable instead. A
17 most traditional and most obvious interaction
18 kernel, there are other possibilities -- choos
19 interface.
20
21 - If the operations involved can be made to l
22 object, it may make more sense to create a
23 also makes it easier to encapsulate the new
24 rather than requiring it to be built into t
25
26 - If the new functionality involves opera
27 userspace that something has happened,
28 descriptor for the relevant object allo
29 ``poll``/``select``/``epoll`` to receiv
30 - However, operations that don't map to
31 :manpage:`read(2)`/:manpage:`write(2)`-
32 have to be implemented as :manpage:`ioc
33 to a somewhat opaque API.
34
35 - If you're just exposing runtime system info
36 (see ``Documentation/filesystems/sysfs.rst`
37 be more appropriate. However, access to th
38 relevant filesystem is mounted, which might
39 in a namespaced/sandboxed/chrooted environm
40 debugfs, as this is not considered a 'produ
41 - If the operation is specific to a particula
42 an additional :manpage:`fcntl(2)` command o
43 :manpage:`fcntl(2)` is a multiplexing syste
44 this option is best for when the new functi
45 existing :manpage:`fcntl(2)` functionality,
46 (for example, getting/setting a simple flag
47 - If the operation is specific to a particula
48 additional :manpage:`prctl(2)` command opti
49 with :manpage:`fcntl(2)`, this system call
50 is best reserved for near-analogs of existi
51 getting/setting a simple flag related to a
52
53
54 Designing the API: Planning for Extension
55 -----------------------------------------
56
57 A new system call forms part of the API of the
58 indefinitely. As such, it's a very good idea
59 interface on the kernel mailing list, and it's
60 extensions of the interface.
61
62 (The syscall table is littered with historical
63 together with the corresponding follow-up syst
64 ``eventfd``/``eventfd2``, ``dup2``/``dup3``, `
65 ``pipe``/``pipe2``, ``renameat``/``renameat2``
66 learn from the history of the kernel and plan
67
68 For simpler system calls that only take a coup
69 way to allow for future extensibility is to in
70 system call. To make sure that userspace prog
71 between kernel versions, check whether the fla
72 flags, and reject the system call (with ``EINV
73
74 if (flags & ~(THING_FLAG1 | THING_FLAG2 |
75 return -EINVAL;
76
77 (If no flags values are used yet, check that t
78
79 For more sophisticated system calls that invol
80 it's preferred to encapsulate the majority of
81 that is passed in by pointer. Such a structur
82 by including a size argument in the structure:
83
84 struct xyzzy_params {
85 u32 size; /* userspace sets p->size =
86 u32 param_1;
87 u64 param_2;
88 u64 param_3;
89 };
90
91 As long as any subsequently added field, say `
92 zero value gives the previous behaviour, then
93 version mismatch:
94
95 - To cope with a later userspace program call
96 code should check that any memory beyond th
97 expects is zero (effectively checking that
98 - To cope with an older userspace program cal
99 code can zero-extend a smaller instance of
100 setting ``param_4 = 0``).
101
102 See :manpage:`perf_event_open(2)` and the ``pe
103 ``kernel/events/core.c``) for an example of th
104
105
106 Designing the API: Other Considerations
107 ---------------------------------------
108
109 If your new system call allows userspace to re
110 should use a file descriptor as the handle for
111 new type of userspace object handle when the k
112 well-defined semantics for using file descript
113
114 If your new :manpage:`xyzzy(2)` system call do
115 then the flags argument should include a value
116 ``O_CLOEXEC`` on the new FD. This makes it po
117 the timing window between ``xyzzy()`` and call
118 ``fcntl(fd, F_SETFD, FD_CLOEXEC)``, where an u
119 ``execve()`` in another thread could leak a de
120 the exec'ed program. (However, resist the temp
121 of the ``O_CLOEXEC`` constant, as it is archit
122 numbering space of ``O_*`` flags that is fairl
123
124 If your system call returns a new file descrip
125 what it means to use the :manpage:`poll(2)` fa
126 descriptor. Making a file descriptor ready for
127 normal way for the kernel to indicate to users
128 occurred on the corresponding kernel object.
129
130 If your new :manpage:`xyzzy(2)` system call in
131
132 int sys_xyzzy(const char __user *path, ...
133
134 you should also consider whether an :manpage:`
135
136 int sys_xyzzyat(int dfd, const char __user
137
138 This allows more flexibility for how userspace
139 in particular it allows userspace to request t
140 already-opened file descriptor using the ``AT_
141 giving an :manpage:`fxyzzy(3)` operation for f
142
143 - xyzzyat(AT_FDCWD, path, ..., 0) is equivale
144 - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equi
145
146 (For more details on the rationale of the \*at
147 :manpage:`openat(2)` man page; for an example
148 :manpage:`fstatat(2)` man page.)
149
150 If your new :manpage:`xyzzy(2)` system call in
151 offset within a file, make its type ``loff_t``
152 supported even on 32-bit architectures.
153
154 If your new :manpage:`xyzzy(2)` system call in
155 it needs to be governed by the appropriate Lin
156 a call to ``capable()``), as described in the
157 page. Choose an existing capability bit that
158 but try to avoid combining lots of only vaguel
159 under the same bit, as this goes against capab
160 the power of root. In particular, avoid addin
161 overly-general ``CAP_SYS_ADMIN`` capability.
162
163 If your new :manpage:`xyzzy(2)` system call ma
164 the calling process, it should be restricted (
165 ``ptrace_may_access()``) so that only a callin
166 permissions as the target process, or with the
167 manipulate the target process.
168
169 Finally, be aware that some non-x86 architectu
170 system call parameters that are explicitly 64-
171 arguments (i.e. parameter 1, 3, 5), to allow u
172 registers. (This concern does not apply if th
173 structure that's passed in by pointer.)
174
175
176 Proposing the API
177 -----------------
178
179 To make new system calls easy to review, it's
180 into separate chunks. These should include at
181 distinct commits (each of which is described f
182
183 - The core implementation of the system call,
184 generic numbering, Kconfig changes and fall
185 - Wiring up of the new system call for one pa
186 x86 (including all of x86_64, x86_32 and x3
187 - A demonstration of the use of the new syste
188 selftest in ``tools/testing/selftests/``.
189 - A draft man-page for the new system call, e
190 cover letter, or as a patch to the (separat
191
192 New system call proposals, like any change to
193 be cc'ed to linux-api@vger.kernel.org.
194
195
196 Generic System Call Implementation
197 ----------------------------------
198
199 The main entry point for your new :manpage:`xy
200 ``sys_xyzzy()``, but you add this entry point
201 ``SYSCALL_DEFINEn()`` macro rather than explic
202 number of arguments to the system call, and th
203 followed by the (type, name) pairs for the par
204 this macro allows metadata about the new syste
205 other tools.
206
207 The new entry point also needs a corresponding
208 ``include/linux/syscalls.h``, marked as asmlin
209 calls are invoked::
210
211 asmlinkage long sys_xyzzy(...);
212
213 Some architectures (e.g. x86) have their own a
214 tables, but several other architectures share
215 new system call to the generic list by adding
216 ``include/uapi/asm-generic/unistd.h``::
217
218 #define __NR_xyzzy 292
219 __SYSCALL(__NR_xyzzy, sys_xyzzy)
220
221 Also update the __NR_syscalls count to reflect
222 note that if multiple new system calls are add
223 your new syscall number may get adjusted to re
224
225 The file ``kernel/sys_ni.c`` provides a fallba
226 system call, returning ``-ENOSYS``. Add your
227
228 COND_SYSCALL(xyzzy);
229
230 Your new kernel functionality, and the system
231 normally be optional, so add a ``CONFIG`` opti
232 ``init/Kconfig``) for it. As usual for new ``C
233
234 - Include a description of the new functional
235 by the option.
236 - Make the option depend on EXPERT if it shou
237 - Make any new source files implementing the
238 option in the Makefile (e.g. ``obj-$(CONFIG
239 - Double check that the kernel still builds w
240 off.
241
242 To summarize, you need a commit that includes:
243
244 - ``CONFIG`` option for the new function, nor
245 - ``SYSCALL_DEFINEn(xyzzy, ...)`` for the ent
246 - corresponding prototype in ``include/linux/
247 - generic table entry in ``include/uapi/asm-g
248 - fallback stub in ``kernel/sys_ni.c``
249
250
251 x86 System Call Implementation
252 ------------------------------
253
254 To wire up your new system call for x86 platfo
255 master syscall tables. Assuming your new syst
256 way (see below), this involves a "common" entr
257 arch/x86/entry/syscalls/syscall_64.tbl::
258
259 333 common xyzzy sys_xyzzy
260
261 and an "i386" entry in ``arch/x86/entry/syscal
262
263 380 i386 xyzzy sys_xyzzy
264
265 Again, these numbers are liable to be changed
266 relevant merge window.
267
268
269 Compatibility System Calls (Generic)
270 ------------------------------------
271
272 For most system calls the same 64-bit implemen
273 the userspace program is itself 32-bit; even i
274 include an explicit pointer, this is handled t
275
276 However, there are a couple of situations wher
277 needed to cope with size differences between 3
278
279 The first is if the 64-bit kernel also support
280 so needs to parse areas of (``__user``) memory
281 64-bit values. In particular, this is needed
282 is:
283
284 - a pointer to a pointer
285 - a pointer to a struct containing a pointer
286 - a pointer to a varying sized integral type
287 ``long``, ...)
288 - a pointer to a struct containing a varying
289
290 The second situation that requires a compatibi
291 system call's arguments has a type that is exp
292 architecture, for example ``loff_t`` or ``__u6
293 arrives at a 64-bit kernel from a 32-bit appli
294 32-bit values, which then need to be re-assemb
295
296 (Note that a system call argument that's a poi
297 does **not** need a compatibility layer; for e
298 type ``loff_t __user *`` do not trigger the ne
299
300 The compatibility version of the system call i
301 and is added with the ``COMPAT_SYSCALL_DEFINEn
302 SYSCALL_DEFINEn. This version of the implemen
303 kernel, but expects to receive 32-bit paramete
304 needed to deal with them. (Typically, the ``c
305 values to 64-bit versions and either calls on
306 them call a common inner implementation functi
307
308 The compat entry point also needs a correspond
309 ``include/linux/compat.h``, marked as asmlinka
310 calls are invoked::
311
312 asmlinkage long compat_sys_xyzzy(...);
313
314 If the system call involves a structure that i
315 and 64-bit systems, say ``struct xyzzy_args``,
316 header file should also include a compat versi
317 compat_xyzzy_args``) where each variable-size
318 ``compat_`` type that corresponds to the type
319 ``compat_sys_xyzzy()`` routine can then use th
320 parse the arguments from a 32-bit invocation.
321
322 For 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
331 in struct xyzzy_args, then struct compat_xyzzy
332
333 struct compat_xyzzy_args {
334 compat_uptr_t ptr;
335 compat_long_t varying_val;
336 u64 fixed_val;
337 /* ... */
338 };
339
340 The generic system call list also needs adjust
341 version; the entry in ``include/uapi/asm-gener
342 ``__SC_COMP`` rather than ``__SYSCALL``::
343
344 #define __NR_xyzzy 292
345 __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sy
346
347 To summarize, you need:
348
349 - a ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` fo
350 - corresponding prototype in ``include/linux/
351 - (if needed) 32-bit mapping struct in ``incl
352 - instance of ``__SC_COMP`` not ``__SYSCALL``
353 ``include/uapi/asm-generic/unistd.h``
354
355
356 Compatibility System Calls (x86)
357 --------------------------------
358
359 To wire up the x86 architecture of a system ca
360 the entries in the syscall tables need to be a
361
362 First, the entry in ``arch/x86/entry/syscalls/
363 column to indicate that a 32-bit userspace pro
364 should hit the compat entry point::
365
366 380 i386 xyzzy sys_xyzzy __ia
367
368 Second, you need to figure out what should hap
369 the new system call. There's a choice here: t
370 should either match the 64-bit version or the
371
372 If there's a pointer-to-a-pointer involved, th
373 ILP32, so the layout should match the 32-bit v
374 ``arch/x86/entry/syscalls/syscall_64.tbl`` is
375 the compatibility wrapper::
376
377 333 64 xyzzy sys_xyzzy
378 ...
379 555 x32 xyzzy __x32_compat_sys_
380
381 If no pointers are involved, then it is prefer
382 call for the x32 ABI (and consequently the ent
383 arch/x86/entry/syscalls/syscall_64.tbl is unch
384
385 In either case, you should check that the type
386 layout do indeed map exactly from x32 (-mx32)
387 64-bit (-m64) equivalents.
388
389
390 System Calls Returning Elsewhere
391 --------------------------------
392
393 For most system calls, once the system call is
394 continues exactly where it left off -- at the
395 stack the same and most of the registers the s
396 and with the same virtual memory space.
397
398 However, a few system calls do things differen
399 different location (``rt_sigreturn``) or chang
400 (``fork``/``vfork``/``clone``) or even archite
401 of the program.
402
403 To allow for this, the kernel implementation o
404 save and restore additional registers to the k
405 control of where and how execution continues a
406
407 This is arch-specific, but typically involves
408 that save/restore additional registers and inv
409 point.
410
411 For x86_64, this is implemented as a ``stub_xy
412 ``arch/x86/entry/entry_64.S``, and the entry i
413 (``arch/x86/entry/syscalls/syscall_64.tbl``) i
414
415 333 common xyzzy stub_xyzzy
416
417 The equivalent for 32-bit programs running on
418 called ``stub32_xyzzy`` and implemented in ``a
419 with the corresponding syscall table adjustmen
420 ``arch/x86/entry/syscalls/syscall_32.tbl``::
421
422 380 i386 xyzzy sys_xyzzy stub
423
424 If the system call needs a compatibility layer
425 then the ``stub32_`` version needs to call on
426 of the system call rather than the native 64-b
427 implementation is not common with the x86_64 v
428 table will also need to invoke a stub that cal
429 version.
430
431 For completeness, it's also nice to set up a m
432 still works -- its syscall table will referenc
433 doesn't include ``arch/x86/entry/entry_64.S``
434 simulates registers etc). Fixing this is as s
435 ``arch/x86/um/sys_call_table_64.c``::
436
437 #define stub_xyzzy sys_xyzzy
438
439
440 Other Details
441 -------------
442
443 Most of the kernel treats system calls in a ge
444 occasional exception that may need updating fo
445
446 The audit subsystem is one such special case;
447 functions that classify some special types of
448 file open (``open``/``openat``), program execu
449 socket multiplexor (``socketcall``) operations
450 analogous to one of these, then the audit syst
451
452 More generally, if there is an existing system
453 new system call, it's worth doing a kernel-wid
454 call to check there are no other special cases
455
456
457 Testing
458 -------
459
460 A new system call should obviously be tested;
461 reviewers with a demonstration of how user spa
462 call. A good way to combine these aims is to
463 program in a new directory under ``tools/testi
464
465 For a new system call, there will obviously be
466 the test will need to invoke it using ``syscal
467 involves a new userspace-visible structure, th
468 to be installed to compile the test.
469
470 Make sure the selftest runs successfully on al
471 example, check that it works when compiled as
472 and x32 (-mx32) ABI program.
473
474 For more extensive and thorough testing of new
475 consider adding tests to the Linux Test Projec
476 for filesystem-related changes.
477
478 - https://linux-test-project.github.io/
479 - git://git.kernel.org/pub/scm/fs/xfs/xfstest
480
481
482 Man Page
483 --------
484
485 All new system calls should come with a comple
486 markup, but plain text will do. If groff is u
487 pre-rendered ASCII version of the man page in
488 patchset, for the convenience of reviewers.
489
490 The man page should be cc'ed to linux-man@vger
491 For more details, see https://www.kernel.org/d
492
493
494 Do not call System Calls in the Kernel
495 --------------------------------------
496
497 System calls are, as stated above, interaction
498 the kernel. Therefore, system call functions
499 ``compat_sys_xyzzy()`` should only be called f
500 table, but not from elsewhere in the kernel.
501 useful to be used within the kernel, needs to
502 new syscall, or needs to be shared between a s
503 variant, it should be implemented by means of
504 ``ksys_xyzzy()``). This kernel function may t
505 syscall stub (``sys_xyzzy()``), the compatibil
506 (``compat_sys_xyzzy()``), and/or other kernel
507
508 At least on 64-bit x86, it will be a hard requ
509 call system call functions in the kernel. It
510 convention for system calls where ``struct pt_
511 syscall wrapper which then hands processing ov
512 This means that only those parameters which ar
513 syscall are passed on during syscall entry, in
514 registers with random user space content all t
515 trouble down the call chain).
516
517 Moreover, rules on how data may be accessed ma
518 user data. This is another reason why calling
519 bad idea.
520
521 Exceptions to this rule are only allowed in ar
522 architecture-specific compatibility wrappers,
523
524
525 References and Sources
526 ----------------------
527
528 - LWN article from Michael Kerrisk on use of
529 https://lwn.net/Articles/585415/
530 - LWN article from Michael Kerrisk on how to
531 call: https://lwn.net/Articles/588444/
532 - LWN article from Jake Edge describing const
533 arguments: https://lwn.net/Articles/311630/
534 - Pair of LWN articles from David Drysdale th
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 syst
541 :manpage:`syscall(2)` man-page:
542 http://man7.org/linux/man-pages/man2/syscal
543 - Collated emails from Linus Torvalds discuss
544 https://yarchive.net/comp/linux/ioctl.html
545 - "How to not invent kernel interfaces", Arnd
546 https://www.ukuug.org/events/linux2007/2007
547 - LWN article from Michael Kerrisk on avoidin
548 https://lwn.net/Articles/486306/
549 - Recommendation from Andrew Morton that all
550 system call should come in the same email t
551 https://lore.kernel.org/r/20140724144747.30
552 - Recommendation from Michael Kerrisk that a
553 a man page: https://lore.kernel.org/r/CAKgN
554 - Suggestion from Thomas Gleixner that x86 wi
555 commit: https://lore.kernel.org/r/alpine.DE
556 - Suggestion from Greg Kroah-Hartman that it'
557 come with a man-page & selftest: https://lo
558 - Discussion from Michael Kerrisk of new syst
559 https://lore.kernel.org/r/CAHO5Pa3F2MjfTtfN
560 - Suggestion from Ingo Molnar that system cal
561 arguments should encapsulate those argument
562 size field for future extensibility: https:
563 - Numbering oddities arising from (re-)use of
564
565 - commit 75069f2b5bfb ("vfs: renumber FMOD
566 check")
567 - commit 12ed2e36c98a ("fanotify: FMODE_NO
568 conflict")
569 - commit bb458c644a59 ("Safer ABI for O_TM
570
571 - Discussion from Matthew Wilcox about restri
572 https://lore.kernel.org/r/20081212152929.GM
573 - Recommendation from Greg Kroah-Hartman that
574 policed: https://lore.kernel.org/r/20140717
575 - Recommendation from Linus Torvalds that x32
576 compatibility with 64-bit versions rather t
577 https://lore.kernel.org/r/CA+55aFxfmwfB7jbb
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.