Lines Matching +full:numbering +full:- +full:space
9 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
13 ------------------------
18 kernel, there are other possibilities -- choose what fits best for your
21 - If the operations involved can be made to look like a filesystem-like
26 - If the new functionality involves operations where the kernel notifies
30 - However, operations that don't map to
31 :manpage:`read(2)`/:manpage:`write(2)`-like operations
35 - If you're just exposing runtime system information, a new node in sysfs
41 - If the operation is specific to a particular file or file descriptor, then
47 - If the operation is specific to a particular task or process, then an
50 is best reserved for near-analogs of existing ``prctl()`` commands or
55 -----------------------------------------
63 together with the corresponding follow-up system calls --
65 ``pipe``/``pipe2``, ``renameat``/``renameat2`` -- so
75 return -EINVAL;
85 u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */
95 - To cope with a later userspace program calling an older kernel, the kernel
98 - To cope with an older userspace program calling a newer kernel, the kernel
99 code can zero-extend a smaller instance of the structure (effectively
107 ---------------------------------------
110 should use a file descriptor as the handle for that object -- don't invent a
112 well-defined semantics for using file descriptors.
120 the exec'ed program. (However, resist the temptation to re-use the actual value
121 of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a
122 numbering space of ``O_*`` flags that is fairly full.)
140 already-opened file descriptor using the ``AT_EMPTY_PATH`` flag, effectively
143 - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...)
144 - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...)
151 offset within a file, make its type ``loff_t`` so that 64-bit offsets can be
152 supported even on 32-bit architectures.
161 overly-general ``CAP_SYS_ADMIN`` capability.
169 Finally, be aware that some non-x86 architectures have an easier time if
170 system call parameters that are explicitly 64-bit fall on odd-numbered
171 arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit
177 -----------------
183 - The core implementation of the system call, together with prototypes,
184 generic numbering, Kconfig changes and fallback stub implementation.
185 - Wiring up of the new system call for one particular architecture, usually
187 - A demonstration of the use of the new system call in userspace via a
189 - A draft man-page for the new system call, either as plain text in the
190 cover letter, or as a patch to the (separate) man-pages repository.
193 be cc'ed to linux-api@vger.kernel.org.
197 ----------------------------------
213 Some architectures (e.g. x86) have their own architecture-specific syscall
216 ``include/uapi/asm-generic/unistd.h``::
226 system call, returning ``-ENOSYS``. Add your new system call here too::
234 - Include a description of the new functionality and system call controlled
236 - Make the option depend on EXPERT if it should be hidden from normal users.
237 - Make any new source files implementing the function dependent on the CONFIG
238 option in the Makefile (e.g. ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.o``).
239 - Double check that the kernel still builds with the new CONFIG option turned
244 - ``CONFIG`` option for the new function, normally in ``init/Kconfig``
245 - ``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry point
246 - corresponding prototype in ``include/linux/syscalls.h``
247 - generic table entry in ``include/uapi/asm-generic/unistd.h``
248 - fallback stub in ``kernel/sys_ni.c``
252 ------------------------------
270 ------------------------------------
272 For most system calls the same 64-bit implementation can be invoked even when
273 the userspace program is itself 32-bit; even if the system call's parameters
277 needed to cope with size differences between 32-bit and 64-bit.
279 The first is if the 64-bit kernel also supports 32-bit userspace programs, and
280 so needs to parse areas of (``__user``) memory that could hold either 32-bit or
281 64-bit values. In particular, this is needed whenever a system call argument
284 - a pointer to a pointer
285 - a pointer to a struct containing a pointer (e.g. ``struct iovec __user *``)
286 - a pointer to a varying sized integral type (``time_t``, ``off_t``,
288 - a pointer to a struct containing a varying sized integral type.
291 system call's arguments has a type that is explicitly 64-bit even on a 32-bit
293 arrives at a 64-bit kernel from a 32-bit application will be split into two
294 32-bit values, which then need to be re-assembled in the compatibility layer.
296 (Note that a system call argument that's a pointer to an explicit 64-bit type
302 SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit
303 kernel, but expects to receive 32-bit parameter values and does whatever is
305 values to 64-bit versions and either calls on to the ``sys_`` version, or both of
314 If the system call involves a structure that is laid out differently on 32-bit
315 and 64-bit systems, say ``struct xyzzy_args``, then the include/linux/compat.h
317 compat_xyzzy_args``) where each variable-size field has the appropriate
320 parse the arguments from a 32-bit invocation.
341 version; the entry in ``include/uapi/asm-generic/unistd.h`` should use
349 - a ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry point
350 - corresponding prototype in ``include/linux/compat.h``
351 - (if needed) 32-bit mapping struct in ``include/linux/compat.h``
352 - instance of ``__SC_COMP`` not ``__SYSCALL`` in
353 ``include/uapi/asm-generic/unistd.h``
357 --------------------------------
363 column to indicate that a 32-bit userspace program running on a 64-bit kernel
370 should either match the 64-bit version or the 32-bit version.
372 If there's a pointer-to-a-pointer involved, the decision is easy: x32 is
373 ILP32, so the layout should match the 32-bit version, and the entry in
381 If no pointers are involved, then it is preferable to re-use the 64-bit system
386 layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or
387 64-bit (-m64) equivalents.
391 --------------------------------
394 continues exactly where it left off -- at the next instruction, with the
396 and with the same virtual memory space.
399 different location (``rt_sigreturn``) or change the memory space
407 This is arch-specific, but typically involves defining assembly entry points
417 The equivalent for 32-bit programs running on a 64-bit kernel is normally
426 of the system call rather than the native 64-bit version. Also, if the x32 ABI
431 For completeness, it's also nice to set up a mapping so that user-mode Linux
432 still works -- its syscall table will reference stub_xyzzy, but the UML build
441 -------------
446 The audit subsystem is one such special case; it includes (arch-specific)
447 functions that classify some special types of system call -- specifically
453 new system call, it's worth doing a kernel-wide grep for the existing system
458 -------
461 reviewers with a demonstration of how user space programs will use the system
462 call. A good way to combine these aims is to include a simple self-test
467 involves a new userspace-visible structure, the corresponding header will need
471 example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32)
472 and x32 (-mx32) ABI program.
476 for filesystem-related changes.
478 - https://linux-test-project.github.io/
479 - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git
483 --------
487 pre-rendered ASCII version of the man page in the cover email for the
490 The man page should be cc'ed to linux-man@vger.kernel.org
491 For more details, see https://www.kernel.org/doc/man-pages/patches.html
495 --------------------------------------
508 At least on 64-bit x86, it will be a hard requirement from v4.17 onwards to not
510 convention for system calls where ``struct pt_regs`` is decoded on-the-fly in a
514 registers with random user space content all the time (which may cause serious
521 Exceptions to this rule are only allowed in architecture-specific overrides,
522 architecture-specific compatibility wrappers, or other code in arch/.
526 ----------------------
528 - LWN article from Michael Kerrisk on use of flags argument in system calls:
530 - LWN article from Michael Kerrisk on how to handle unknown flags in a system
532 - LWN article from Jake Edge describing constraints on 64-bit system call
534 - Pair of LWN articles from David Drysdale that describe the system call
537 - https://lwn.net/Articles/604287/
538 - https://lwn.net/Articles/604515/
540 - Architecture-specific requirements for system calls are discussed in the
541 :manpage:`syscall(2)` man-page:
542 http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES
543 - Collated emails from Linus Torvalds discussing the problems with ``ioctl()``:
545 - "How to not invent kernel interfaces", Arnd Bergmann,
547 - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN:
549 - Recommendation from Andrew Morton that all related information for a new
551 https://lore.kernel.org/r/20140724144747.3041b208832bbdf9fbce5d96@linux-foundation.org
552 - Recommendation from Michael Kerrisk that a new system call should come with
554 - Suggestion from Thomas Gleixner that x86 wire-up should be in a separate
556 - Suggestion from Greg Kroah-Hartman that it's good for new system calls to
557 come with a man-page & selftest: https://lore.kernel.org/r/20140320025530.GA25469@kroah.com
558 - Discussion from Michael Kerrisk of new system call vs. :manpage:`prctl(2)` extension:
559 https://lore.kernel.org/r/CAHO5Pa3F2MjfTtfNxa8LbnkeeU8=YJ+9tDqxZpw7Gz59E-4AUg@mail.gmail.com
560 - Suggestion from Ingo Molnar that system calls that involve multiple
563 - Numbering oddities arising from (re-)use of O_* numbering space flags:
565 - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness
567 - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc
569 - commit bb458c644a59 ("Safer ABI for O_TMPFILE")
571 - Discussion from Matthew Wilcox about restrictions on 64-bit arguments:
572 https://lore.kernel.org/r/20081212152929.GM26095@parisc-linux.org
573 - Recommendation from Greg Kroah-Hartman that unknown flags should be
575 - Recommendation from Linus Torvalds that x32 system calls should prefer
576 compatibility with 64-bit versions rather than 32-bit versions: