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