Lines Matching +full:2 +full:x32 +full:- +full:bit
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
32 have to be implemented as :manpage:`ioctl(2)` requests, which can lead
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
42 an additional :manpage:`fcntl(2)` command option may be more appropriate. However,
43 :manpage:`fcntl(2)` is a multiplexing system call that hides a lot of complexity, so
45 existing :manpage:`fcntl(2)` functionality, or the new functionality is very simple
47 - If the operation is specific to a particular task or process, then an
48 additional :manpage:`prctl(2)` command option may be more appropriate. As
49 with :manpage:`fcntl(2)`, this system call is a complicated multiplexor so
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
102 See :manpage:`perf_event_open(2)` and the ``perf_copy_attr()`` function (in
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.
114 If your new :manpage:`xyzzy(2)` system call does return a new file descriptor,
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
125 what it means to use the :manpage:`poll(2)` family of system calls on that file
130 If your new :manpage:`xyzzy(2)` system call involves a filename argument::
134 you should also consider whether an :manpage:`xyzzyat(2)` version is more appropriate::
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, ...)
147 :manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the
148 :manpage:`fstatat(2)` man page.)
150 If your new :manpage:`xyzzy(2)` system call involves a parameter describing an
151 offset within a file, make its type ``loff_t`` so that 64-bit offsets can be
152 supported even on 32-bit architectures.
154 If your new :manpage:`xyzzy(2)` system call involves privileged functionality,
155 it needs to be governed by the appropriate Linux capability bit (checked with
157 page. Choose an existing capability bit that governs related functionality,
159 under the same bit, as this goes against capabilities' purpose of splitting
161 overly-general ``CAP_SYS_ADMIN`` capability.
163 If your new :manpage:`xyzzy(2)` system call manipulates a process other than
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,
185 - Wiring up of the new system call for one particular architecture, usually
186 x86 (including all of x86_64, x86_32 and x32).
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 ----------------------------------
199 The main entry point for your new :manpage:`xyzzy(2)` system call will be called
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 ------------------------------
256 way (see below), this involves a "common" entry (for x86_64 and x32) in
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
297 does **not** need a compatibility layer; for example, :manpage:`splice(2)`'s arguments of
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
368 Second, you need to figure out what should happen for the x32 ABI version of
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
374 ``arch/x86/entry/syscalls/syscall_64.tbl`` is split so that x32 programs hit
379 555 x32 xyzzy __x32_compat_sys_xyzzy
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 entry in
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
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 -------
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
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: