adding-syscalls.rst 26 KB

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