Lines Matching +full:2 +full:x32 +full:- +full:bit
6 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
10 ------------------------
15 kernel, there are other possibilities -- choose what fits best for your
18 - If the operations involved can be made to look like a filesystem-like
23 - If the new functionality involves operations where the kernel notifies
27 - However, operations that don't map to
28 :manpage:`read(2)`/:manpage:`write(2)`-like operations
29 have to be implemented as :manpage:`ioctl(2)` requests, which can lead
32 - If you're just exposing runtime system information, a new node in sysfs
38 - If the operation is specific to a particular file or file descriptor, then
39 an additional :manpage:`fcntl(2)` command option may be more appropriate. However,
40 :manpage:`fcntl(2)` is a multiplexing system call that hides a lot of complexity, so
42 existing :manpage:`fcntl(2)` functionality, or the new functionality is very simple
44 - If the operation is specific to a particular task or process, then an
45 additional :manpage:`prctl(2)` command option may be more appropriate. As
46 with :manpage:`fcntl(2)`, this system call is a complicated multiplexor so
47 is best reserved for near-analogs of existing ``prctl()`` commands or
52 -----------------------------------------
60 together with the corresponding follow-up system calls --
62 ``pipe``/``pipe2``, ``renameat``/``renameat2`` -- so
72 return -EINVAL;
82 u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */
92 - To cope with a later userspace program calling an older kernel, the kernel
95 - To cope with an older userspace program calling a newer kernel, the kernel
96 code can zero-extend a smaller instance of the structure (effectively
99 See :manpage:`perf_event_open(2)` and the ``perf_copy_attr()`` function (in
104 ---------------------------------------
107 should use a file descriptor as the handle for that object -- don't invent a
109 well-defined semantics for using file descriptors.
111 If your new :manpage:`xyzzy(2)` system call does return a new file descriptor,
117 the exec'ed program. (However, resist the temptation to re-use the actual value
118 of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a
122 what it means to use the :manpage:`poll(2)` family of system calls on that file
127 If your new :manpage:`xyzzy(2)` system call involves a filename argument::
131 you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate::
137 already-opened file descriptor using the ``AT_EMPTY_PATH`` flag, effectively
140 - xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...)
141 - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...)
144 :manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the
145 :manpage:`fstatat(2)` man page.)
147 If your new :manpage:`xyzzy(2)` system call involves a parameter describing an
148 offset within a file, make its type ``loff_t`` so that 64-bit offsets can be
149 supported even on 32-bit architectures.
151 If your new :manpage:`xyzzy(2)` system call involves privileged functionality,
152 it needs to be governed by the appropriate Linux capability bit (checked with
154 page. Choose an existing capability bit that governs related functionality,
156 under the same bit, as this goes against capabilities' purpose of splitting
158 overly-general ``CAP_SYS_ADMIN`` capability.
160 If your new :manpage:`xyzzy(2)` system call manipulates a process other than
166 Finally, be aware that some non-x86 architectures have an easier time if
167 system call parameters that are explicitly 64-bit fall on odd-numbered
168 arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit
174 -----------------
180 - The core implementation of the system call, together with prototypes,
182 - Wiring up of the new system call for one particular architecture, usually
183 x86 (including all of x86_64, x86_32 and x32).
184 - A demonstration of the use of the new system call in userspace via a
186 - A draft man-page for the new system call, either as plain text in the
187 cover letter, or as a patch to the (separate) man-pages repository.
190 be cc'ed to linux-api@vger.kernel.org.
194 ----------------------------------
196 The main entry point for your new :manpage:`xyzzy(2)` system call will be called
210 Some architectures (e.g. x86) have their own architecture-specific syscall
213 ``include/uapi/asm-generic/unistd.h``::
223 system call, returning ``-ENOSYS``. Add your new system call here too::
231 - Include a description of the new functionality and system call controlled
233 - Make the option depend on EXPERT if it should be hidden from normal users.
234 - Make any new source files implementing the function dependent on the CONFIG
235 option in the Makefile (e.g. ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.c``).
236 - Double check that the kernel still builds with the new CONFIG option turned
241 - ``CONFIG`` option for the new function, normally in ``init/Kconfig``
242 - ``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry point
243 - corresponding prototype in ``include/linux/syscalls.h``
244 - generic table entry in ``include/uapi/asm-generic/unistd.h``
245 - fallback stub in ``kernel/sys_ni.c``
249 ------------------------------
253 way (see below), this involves a "common" entry (for x86_64 and x32) in
267 ------------------------------------
269 For most system calls the same 64-bit implementation can be invoked even when
270 the userspace program is itself 32-bit; even if the system call's parameters
274 needed to cope with size differences between 32-bit and 64-bit.
276 The first is if the 64-bit kernel also supports 32-bit userspace programs, and
277 so needs to parse areas of (``__user``) memory that could hold either 32-bit or
278 64-bit values. In particular, this is needed whenever a system call argument
281 - a pointer to a pointer
282 - a pointer to a struct containing a pointer (e.g. ``struct iovec __user *``)
283 - a pointer to a varying sized integral type (``time_t``, ``off_t``,
285 - a pointer to a struct containing a varying sized integral type.
288 system call's arguments has a type that is explicitly 64-bit even on a 32-bit
290 arrives at a 64-bit kernel from a 32-bit application will be split into two
291 32-bit values, which then need to be re-assembled in the compatibility layer.
293 (Note that a system call argument that's a pointer to an explicit 64-bit type
294 does **not** need a compatibility layer; for example, :manpage:`splice(2)`'s arguments of
299 SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit
300 kernel, but expects to receive 32-bit parameter values and does whatever is
302 values to 64-bit versions and either calls on to the ``sys_`` version, or both of
311 If the system call involves a structure that is laid out differently on 32-bit
312 and 64-bit systems, say ``struct xyzzy_args``, then the include/linux/compat.h
314 compat_xyzzy_args``) where each variable-size field has the appropriate
317 parse the arguments from a 32-bit invocation.
338 version; the entry in ``include/uapi/asm-generic/unistd.h`` should use
346 - a ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry point
347 - corresponding prototype in ``include/linux/compat.h``
348 - (if needed) 32-bit mapping struct in ``include/linux/compat.h``
349 - instance of ``__SC_COMP`` not ``__SYSCALL`` in
350 ``include/uapi/asm-generic/unistd.h``
354 --------------------------------
360 column to indicate that a 32-bit userspace program running on a 64-bit kernel
365 Second, you need to figure out what should happen for the x32 ABI version of
367 should either match the 64-bit version or the 32-bit version.
369 If there's a pointer-to-a-pointer involved, the decision is easy: x32 is
370 ILP32, so the layout should match the 32-bit version, and the entry in
371 ``arch/x86/entry/syscalls/syscall_64.tbl`` is split so that x32 programs hit
376 555 x32 xyzzy __x32_compat_sys_xyzzy
378 If no pointers are involved, then it is preferable to re-use the 64-bit system
379 call for the x32 ABI (and consequently the entry in
383 layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or
384 64-bit (-m64) equivalents.
388 --------------------------------
391 continues exactly where it left off -- at the next instruction, with the
404 This is arch-specific, but typically involves defining assembly entry points
414 The equivalent for 32-bit programs running on a 64-bit kernel is normally
423 of the system call rather than the native 64-bit version. Also, if the x32 ABI
428 For completeness, it's also nice to set up a mapping so that user-mode Linux
429 still works -- its syscall table will reference stub_xyzzy, but the UML build
438 -------------
443 The audit subsystem is one such special case; it includes (arch-specific)
444 functions that classify some special types of system call -- specifically
450 new system call, it's worth doing a kernel-wide grep for the existing system
455 -------
459 call. A good way to combine these aims is to include a simple self-test
464 involves a new userspace-visible structure, the corresponding header will need
468 example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32)
469 and x32 (-mx32) ABI program.
473 for filesystem-related changes.
475 - https://linux-test-project.github.io/
476 - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git
480 --------
484 pre-rendered ASCII version of the man page in the cover email for the
487 The man page should be cc'ed to linux-man@vger.kernel.org
488 For more details, see https://www.kernel.org/doc/man-pages/patches.html
492 --------------------------------------
505 At least on 64-bit x86, it will be a hard requirement from v4.17 onwards to not
507 convention for system calls where ``struct pt_regs`` is decoded on-the-fly in a
518 Exceptions to this rule are only allowed in architecture-specific overrides,
519 architecture-specific compatibility wrappers, or other code in arch/.
523 ----------------------
525 - LWN article from Michael Kerrisk on use of flags argument in system calls:
527 - LWN article from Michael Kerrisk on how to handle unknown flags in a system
529 - LWN article from Jake Edge describing constraints on 64-bit system call
531 - Pair of LWN articles from David Drysdale that describe the system call
534 - https://lwn.net/Articles/604287/
535 - https://lwn.net/Articles/604515/
537 - Architecture-specific requirements for system calls are discussed in the
538 :manpage:`syscall(2)` man-page:
539 http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES
540 - Collated emails from Linus Torvalds discussing the problems with ``ioctl()``:
542 - "How to not invent kernel interfaces", Arnd Bergmann,
544 - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN:
546 - Recommendation from Andrew Morton that all related information for a new
549 - Recommendation from Michael Kerrisk that a new system call should come with
551 - Suggestion from Thomas Gleixner that x86 wire-up should be in a separate
553 - Suggestion from Greg Kroah-Hartman that it's good for new system calls to
554 come with a man-page & selftest: https://lkml.org/lkml/2014/3/19/710
555 - Discussion from Michael Kerrisk of new system call vs. :manpage:`prctl(2)` extension:
557 - Suggestion from Ingo Molnar that system calls that involve multiple
560 - Numbering oddities arising from (re-)use of O_* numbering space flags:
562 - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness
564 - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc
566 - commit bb458c644a59 ("Safer ABI for O_TMPFILE")
568 - Discussion from Matthew Wilcox about restrictions on 64-bit arguments:
570 - Recommendation from Greg Kroah-Hartman that unknown flags should be
572 - Recommendation from Linus Torvalds that x32 system calls should prefer
573 compatibility with 64-bit versions rather than 32-bit versions: