sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget+/translations/zh_CN/process/adding-syscallsmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/zh_TW/process/adding-syscallsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/it_IT/process/adding-syscallsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/ja_JP/process/adding-syscallsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/ko_KR/process/adding-syscallsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/pt_BR/process/adding-syscallsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget+/translations/sp_SP/process/adding-syscallsmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhtarget)}(h.. _addsyscalls:h]h}(h]h ]h"]h$]h&]refid addsyscallsuh1hhKhhhhhE/var/lib/git/docbuild/linux/Documentation/process/adding-syscalls.rstubhsection)}(hhh](htitle)}(hAdding a New System Callh]hAdding a New System Call}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hThis document describes what's involved in adding a new system call to the Linux kernel, over and above the normal submission advice in :ref:`Documentation/process/submitting-patches.rst `.h](hThis document describes what’s involved in adding a new system call to the Linux kernel, over and above the normal submission advice in }(hhhhhNhNubh)}(hG:ref:`Documentation/process/submitting-patches.rst `h]hinline)}(hhh]h,Documentation/process/submitting-patches.rst}(hhhhhNhNubah}(h]h ](xrefstdstd-refeh"]h$]h&]uh1hhhubah}(h]h ]h"]h$]h&]refdocprocess/adding-syscalls refdomainhreftyperef refexplicitrefwarn reftargetsubmittingpatchesuh1hhhhKhhubh.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(hSystem Call Alternativesh]hSystem Call Alternatives}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK ubh)}(hX8The first thing to consider when adding a new system call is whether one of the alternatives might be suitable instead. Although system calls are the most traditional and most obvious interaction points between userspace and the kernel, there are other possibilities -- choose what fits best for your interface.h]hX8The first thing to consider when adding a new system call is whether one of the alternatives might be suitable instead. Although system calls are the most traditional and most obvious interaction points between userspace and the kernel, there are other possibilities -- choose what fits best for your interface.}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh block_quote)}(hX!- If the operations involved can be made to look like a filesystem-like object, it may make more sense to create a new filesystem or device. This also makes it easier to encapsulate the new functionality in a kernel module rather than requiring it to be built into the main kernel. - If the new functionality involves operations where the kernel notifies userspace that something has happened, then returning a new file descriptor for the relevant object allows userspace to use ``poll``/``select``/``epoll`` to receive that notification. - However, operations that don't map to :manpage:`read(2)`/:manpage:`write(2)`-like operations have to be implemented as :manpage:`ioctl(2)` requests, which can lead to a somewhat opaque API. - If you're just exposing runtime system information, a new node in sysfs (see ``Documentation/filesystems/sysfs.rst``) or the ``/proc`` filesystem may be more appropriate. However, access to these mechanisms requires that the relevant filesystem is mounted, which might not always be the case (e.g. in a namespaced/sandboxed/chrooted environment). Avoid adding any API to debugfs, as this is not considered a 'production' interface to userspace. - If the operation is specific to a particular file or file descriptor, then an additional :manpage:`fcntl(2)` command option may be more appropriate. However, :manpage:`fcntl(2)` is a multiplexing system call that hides a lot of complexity, so this option is best for when the new function is closely analogous to existing :manpage:`fcntl(2)` functionality, or the new functionality is very simple (for example, getting/setting a simple flag related to a file descriptor). - If the operation is specific to a particular task or process, then an additional :manpage:`prctl(2)` command option may be more appropriate. As with :manpage:`fcntl(2)`, this system call is a complicated multiplexor so is best reserved for near-analogs of existing ``prctl()`` commands or getting/setting a simple flag related to a process. h]h bullet_list)}(hhh](h list_item)}(hXIf the operations involved can be made to look like a filesystem-like object, it may make more sense to create a new filesystem or device. This also makes it easier to encapsulate the new functionality in a kernel module rather than requiring it to be built into the main kernel. - If the new functionality involves operations where the kernel notifies userspace that something has happened, then returning a new file descriptor for the relevant object allows userspace to use ``poll``/``select``/``epoll`` to receive that notification. - However, operations that don't map to :manpage:`read(2)`/:manpage:`write(2)`-like operations have to be implemented as :manpage:`ioctl(2)` requests, which can lead to a somewhat opaque API. h](h)}(hXIf the operations involved can be made to look like a filesystem-like object, it may make more sense to create a new filesystem or device. This also makes it easier to encapsulate the new functionality in a kernel module rather than requiring it to be built into the main kernel.h]hXIf the operations involved can be made to look like a filesystem-like object, it may make more sense to create a new filesystem or device. This also makes it easier to encapsulate the new functionality in a kernel module rather than requiring it to be built into the main kernel.}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj>ubj2)}(hX- If the new functionality involves operations where the kernel notifies userspace that something has happened, then returning a new file descriptor for the relevant object allows userspace to use ``poll``/``select``/``epoll`` to receive that notification. - However, operations that don't map to :manpage:`read(2)`/:manpage:`write(2)`-like operations have to be implemented as :manpage:`ioctl(2)` requests, which can lead to a somewhat opaque API. h]j8)}(hhh](j=)}(hIf the new functionality involves operations where the kernel notifies userspace that something has happened, then returning a new file descriptor for the relevant object allows userspace to use ``poll``/``select``/``epoll`` to receive that notification.h]h)}(hIf the new functionality involves operations where the kernel notifies userspace that something has happened, then returning a new file descriptor for the relevant object allows userspace to use ``poll``/``select``/``epoll`` to receive that notification.h](hIf the new functionality involves operations where the kernel notifies userspace that something has happened, then returning a new file descriptor for the relevant object allows userspace to use }(hj[hhhNhNubhliteral)}(h``poll``h]hpoll}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1jchj[ubh/}(hj[hhhNhNubjd)}(h ``select``h]hselect}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj[ubh/}hj[sbjd)}(h ``epoll``h]hepoll}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj[ubh to receive that notification.}(hj[hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjWubah}(h]h ]h"]h$]h&]uh1j<hjTubj=)}(hHowever, operations that don't map to :manpage:`read(2)`/:manpage:`write(2)`-like operations have to be implemented as :manpage:`ioctl(2)` requests, which can lead to a somewhat opaque API. h]h)}(hHowever, operations that don't map to :manpage:`read(2)`/:manpage:`write(2)`-like operations have to be implemented as :manpage:`ioctl(2)` requests, which can lead to a somewhat opaque API.h](h(However, operations that don’t map to }(hjhhhNhNubhmanpage)}(h:manpage:`read(2)`h]hread(2)}(hjhhhNhNubah}(h]h ]jah"]h$]h&] xml:spacepreservepathread(2)pagereadsection2uh1jhjubh/}(hjhhhNhNubj)}(h:manpage:`write(2)`h]hwrite(2)}(hjhhhNhNubah}(h]h ]jah"]h$]h&]jjjwrite(2)jwritejjuh1jhjubh+-like operations have to be implemented as }(hjhhhNhNubj)}(h:manpage:`ioctl(2)`h]hioctl(2)}(hjhhhNhNubah}(h]h ]jah"]h$]h&]jjjioctl(2)jioctljjuh1jhjubh3 requests, which can lead to a somewhat opaque API.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j<hjTubeh}(h]h ]h"]h$]h&]bullet-uh1j7hhhKhjPubah}(h]h ]h"]h$]h&]uh1j1hhhKhj>ubeh}(h]h ]h"]h$]h&]uh1j<hj9ubj=)}(hXIf you're just exposing runtime system information, a new node in sysfs (see ``Documentation/filesystems/sysfs.rst``) or the ``/proc`` filesystem may be more appropriate. However, access to these mechanisms requires that the relevant filesystem is mounted, which might not always be the case (e.g. in a namespaced/sandboxed/chrooted environment). Avoid adding any API to debugfs, as this is not considered a 'production' interface to userspace.h]h)}(hXIf you're just exposing runtime system information, a new node in sysfs (see ``Documentation/filesystems/sysfs.rst``) or the ``/proc`` filesystem may be more appropriate. However, access to these mechanisms requires that the relevant filesystem is mounted, which might not always be the case (e.g. in a namespaced/sandboxed/chrooted environment). Avoid adding any API to debugfs, as this is not considered a 'production' interface to userspace.h](hOIf you’re just exposing runtime system information, a new node in sysfs (see }(hjhhhNhNubjd)}(h'``Documentation/filesystems/sysfs.rst``h]h#Documentation/filesystems/sysfs.rst}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh ) or the }(hjhhhNhNubjd)}(h ``/proc``h]h/proc}(hj5hhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubhX< filesystem may be more appropriate. However, access to these mechanisms requires that the relevant filesystem is mounted, which might not always be the case (e.g. in a namespaced/sandboxed/chrooted environment). Avoid adding any API to debugfs, as this is not considered a ‘production’ interface to userspace.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK#hjubah}(h]h ]h"]h$]h&]uh1j<hj9ubj=)}(hXIf the operation is specific to a particular file or file descriptor, then an additional :manpage:`fcntl(2)` command option may be more appropriate. However, :manpage:`fcntl(2)` is a multiplexing system call that hides a lot of complexity, so this option is best for when the new function is closely analogous to existing :manpage:`fcntl(2)` functionality, or the new functionality is very simple (for example, getting/setting a simple flag related to a file descriptor).h]h)}(hXIf the operation is specific to a particular file or file descriptor, then an additional :manpage:`fcntl(2)` command option may be more appropriate. However, :manpage:`fcntl(2)` is a multiplexing system call that hides a lot of complexity, so this option is best for when the new function is closely analogous to existing :manpage:`fcntl(2)` functionality, or the new functionality is very simple (for example, getting/setting a simple flag related to a file descriptor).h](hYIf the operation is specific to a particular file or file descriptor, then an additional }(hjWhhhNhNubj)}(h:manpage:`fcntl(2)`h]hfcntl(2)}(hj_hhhNhNubah}(h]h ]jah"]h$]h&]jjjfcntl(2)jfcntljjuh1jhjWubh3 command option may be more appropriate. However, }(hjWhhhNhNubj)}(h:manpage:`fcntl(2)`h]hfcntl(2)}(hjshhhNhNubah}(h]h ]jah"]h$]h&]jjjfcntl(2)jfcntljjuh1jhjWubh is a multiplexing system call that hides a lot of complexity, so this option is best for when the new function is closely analogous to existing }(hjWhhhNhNubj)}(h:manpage:`fcntl(2)`h]hfcntl(2)}(hjhhhNhNubah}(h]h ]jah"]h$]h&]jjjfcntl(2)jfcntljjuh1jhjWubh functionality, or the new functionality is very simple (for example, getting/setting a simple flag related to a file descriptor).}(hjWhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK)hjSubah}(h]h ]h"]h$]h&]uh1j<hj9ubj=)}(hXWIf the operation is specific to a particular task or process, then an additional :manpage:`prctl(2)` command option may be more appropriate. As with :manpage:`fcntl(2)`, this system call is a complicated multiplexor so is best reserved for near-analogs of existing ``prctl()`` commands or getting/setting a simple flag related to a process. h]h)}(hXUIf the operation is specific to a particular task or process, then an additional :manpage:`prctl(2)` command option may be more appropriate. As with :manpage:`fcntl(2)`, this system call is a complicated multiplexor so is best reserved for near-analogs of existing ``prctl()`` commands or getting/setting a simple flag related to a process.h](hQIf the operation is specific to a particular task or process, then an additional }(hjhhhNhNubj)}(h:manpage:`prctl(2)`h]hprctl(2)}(hjhhhNhNubah}(h]h ]jah"]h$]h&]jjjprctl(2)jprctljjuh1jhjubh2 command option may be more appropriate. As with }(hjhhhNhNubj)}(h:manpage:`fcntl(2)`h]hfcntl(2)}(hjhhhNhNubah}(h]h ]jah"]h$]h&]jjjfcntl(2)jfcntljjuh1jhjubha, this system call is a complicated multiplexor so is best reserved for near-analogs of existing }(hjhhhNhNubjd)}(h ``prctl()``h]hprctl()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh@ commands or getting/setting a simple flag related to a process.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK/hjubah}(h]h ]h"]h$]h&]uh1j<hj9ubeh}(h]h ]h"]h$]h&]j j uh1j7hhhKhj3ubah}(h]h ]h"]h$]h&]uh1j1hhhKhjhhubeh}(h]system-call-alternativesah ]h"]system call alternativesah$]h&]uh1hhhhhhhhK ubh)}(hhh](h)}(h)Designing the API: Planning for Extensionh]h)Designing the API: Planning for Extension}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhK7ubh)}(hA new system call forms part of the API of the kernel, and has to be supported indefinitely. As such, it's a very good idea to explicitly discuss the interface on the kernel mailing list, and it's important to plan for future extensions of the interface.h]hXA new system call forms part of the API of the kernel, and has to be supported indefinitely. As such, it’s a very good idea to explicitly discuss the interface on the kernel mailing list, and it’s important to plan for future extensions of the interface.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK9hj hhubh)}(hX](The syscall table is littered with historical examples where this wasn't done, together with the corresponding follow-up system calls -- ``eventfd``/``eventfd2``, ``dup2``/``dup3``, ``inotify_init``/``inotify_init1``, ``pipe``/``pipe2``, ``renameat``/``renameat2`` -- so learn from the history of the kernel and plan for extensions from the start.)h](h(The syscall table is littered with historical examples where this wasn’t done, together with the corresponding follow-up system calls -- }(hj,hhhNhNubjd)}(h ``eventfd``h]heventfd}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj,ubh/}(hj,hhhNhNubjd)}(h ``eventfd2``h]heventfd2}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj,ubh, }(hj,hhhNhNubjd)}(h``dup2``h]hdup2}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj,ubh/}hj,sbjd)}(h``dup3``h]hdup3}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj,ubh, }hj,sbjd)}(h``inotify_init``h]h inotify_init}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj,ubh/}hj,sbjd)}(h``inotify_init1``h]h inotify_init1}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj,ubh, }(hj,hhhNhNubjd)}(h``pipe``h]hpipe}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj,ubh/}hj,sbjd)}(h ``pipe2``h]hpipe2}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj,ubh, }hj,sbjd)}(h ``renameat``h]hrenameat}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj,ubh/}hj,sbjd)}(h ``renameat2``h]h renameat2}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj,ubhT -- so learn from the history of the kernel and plan for extensions from the start.)}(hj,hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK>hj hhubh)}(hXjFor simpler system calls that only take a couple of arguments, the preferred way to allow for future extensibility is to include a flags argument to the system call. To make sure that userspace programs can safely use flags between kernel versions, check whether the flags value holds any unknown flags, and reject the system call (with ``EINVAL``) if it does::h](hXRFor simpler system calls that only take a couple of arguments, the preferred way to allow for future extensibility is to include a flags argument to the system call. To make sure that userspace programs can safely use flags between kernel versions, check whether the flags value holds any unknown flags, and reject the system call (with }(hjhhhNhNubjd)}(h ``EINVAL``h]hEINVAL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh ) if it does:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKDhj hhubh literal_block)}(hKif (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3)) return -EINVAL;h]hKif (flags & ~(THING_FLAG1 | THING_FLAG2 | THING_FLAG3)) return -EINVAL;}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKJhj hhubh)}(hI(If no flags values are used yet, check that the flags argument is zero.)h]hI(If no flags values are used yet, check that the flags argument is zero.)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKMhj hhubh)}(hXFor more sophisticated system calls that involve a larger number of arguments, it's preferred to encapsulate the majority of the arguments into a structure that is passed in by pointer. Such a structure can cope with future extension by including a size argument in the structure::h]hXFor more sophisticated system calls that involve a larger number of arguments, it’s preferred to encapsulate the majority of the arguments into a structure that is passed in by pointer. Such a structure can cope with future extension by including a size argument in the structure:}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKOhj hhubj)}(hstruct xyzzy_params { u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */ u32 param_1; u64 param_2; u64 param_3; };h]hstruct xyzzy_params { u32 size; /* userspace sets p->size = sizeof(struct xyzzy_params) */ u32 param_1; u64 param_2; u64 param_3; };}hj:sbah}(h]h ]h"]h$]h&]jjuh1jhhhKThj hhubh)}(hAs long as any subsequently added field, say ``param_4``, is designed so that a zero value gives the previous behaviour, then this allows both directions of version mismatch:h](h-As long as any subsequently added field, say }(hjHhhhNhNubjd)}(h ``param_4``h]hparam_4}(hjPhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjHubhv, is designed so that a zero value gives the previous behaviour, then this allows both directions of version mismatch:}(hjHhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK[hj hhubj2)}(hX- To cope with a later userspace program calling an older kernel, the kernel code should check that any memory beyond the size of the structure that it expects is zero (effectively checking that ``param_4 == 0``). - To cope with an older userspace program calling a newer kernel, the kernel code can zero-extend a smaller instance of the structure (effectively setting ``param_4 = 0``). h]j8)}(hhh](j=)}(hTo cope with a later userspace program calling an older kernel, the kernel code should check that any memory beyond the size of the structure that it expects is zero (effectively checking that ``param_4 == 0``).h]h)}(hTo cope with a later userspace program calling an older kernel, the kernel code should check that any memory beyond the size of the structure that it expects is zero (effectively checking that ``param_4 == 0``).h](hTo cope with a later userspace program calling an older kernel, the kernel code should check that any memory beyond the size of the structure that it expects is zero (effectively checking that }(hjshhhNhNubjd)}(h``param_4 == 0``h]h param_4 == 0}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1jchjsubh).}(hjshhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK_hjoubah}(h]h ]h"]h$]h&]uh1j<hjlubj=)}(hTo cope with an older userspace program calling a newer kernel, the kernel code can zero-extend a smaller instance of the structure (effectively setting ``param_4 = 0``). h]h)}(hTo cope with an older userspace program calling a newer kernel, the kernel code can zero-extend a smaller instance of the structure (effectively setting ``param_4 = 0``).h](hTo cope with an older userspace program calling a newer kernel, the kernel code can zero-extend a smaller instance of the structure (effectively setting }(hjhhhNhNubjd)}(h``param_4 = 0``h]h param_4 = 0}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh).}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKbhjubah}(h]h ]h"]h$]h&]uh1j<hjlubeh}(h]h ]h"]h$]h&]j j uh1j7hhhK_hjhubah}(h]h ]h"]h$]h&]uh1j1hhhK_hj hhubh)}(hSee :manpage:`perf_event_open(2)` and the ``perf_copy_attr()`` function (in ``kernel/events/core.c``) for an example of this approach.h](hSee }(hjhhhNhNubj)}(h:manpage:`perf_event_open(2)`h]hperf_event_open(2)}(hjhhhNhNubah}(h]h ]jah"]h$]h&]jjjperf_event_open(2)jperf_event_openjjuh1jhjubh and the }(hjhhhNhNubjd)}(h``perf_copy_attr()``h]hperf_copy_attr()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh function (in }(hjhhhNhNubjd)}(h``kernel/events/core.c``h]hkernel/events/core.c}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh") for an example of this approach.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKfhj hhubeh}(h](designing-the-api-planning-for-extensionah ]h"])designing the api: planning for extensionah$]h&]uh1hhhhhhhhK7ubh)}(hhh](h)}(h'Designing the API: Other Considerationsh]h'Designing the API: Other Considerations}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKkubh)}(hXIf your new system call allows userspace to refer to a kernel object, it should use a file descriptor as the handle for that object -- don't invent a new type of userspace object handle when the kernel already has mechanisms and well-defined semantics for using file descriptors.h]hXIf your new system call allows userspace to refer to a kernel object, it should use a file descriptor as the handle for that object -- don’t invent a new type of userspace object handle when the kernel already has mechanisms and well-defined semantics for using file descriptors.}(hj.hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKmhjhhubh)}(hXdIf your new xyzzy(2) system call does return a new file descriptor, then the flags argument should include a value that is equivalent to setting ``O_CLOEXEC`` on the new FD. This makes it possible for userspace to close the timing window between ``xyzzy()`` and calling ``fcntl(fd, F_SETFD, FD_CLOEXEC)``, where an unexpected ``fork()`` and ``execve()`` in another thread could leak a descriptor to the exec'ed program. (However, resist the temptation to reuse the actual value of the ``O_CLOEXEC`` constant, as it is architecture-specific and is part of a numbering space of ``O_*`` flags that is fairly full.)h](hIf your new xyzzy(2) system call does return a new file descriptor, then the flags argument should include a value that is equivalent to setting }(hj<hhhNhNubjd)}(h ``O_CLOEXEC``h]h O_CLOEXEC}(hjDhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj<ubhY on the new FD. This makes it possible for userspace to close the timing window between }(hj<hhhNhNubjd)}(h ``xyzzy()``h]hxyzzy()}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj<ubh and calling }(hj<hhhNhNubjd)}(h"``fcntl(fd, F_SETFD, FD_CLOEXEC)``h]hfcntl(fd, F_SETFD, FD_CLOEXEC)}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj<ubh, where an unexpected }(hj<hhhNhNubjd)}(h ``fork()``h]hfork()}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj<ubh and }(hj<hhhNhNubjd)}(h ``execve()``h]hexecve()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj<ubh in another thread could leak a descriptor to the exec’ed program. (However, resist the temptation to reuse the actual value of the }(hj<hhhNhNubjd)}(h ``O_CLOEXEC``h]h O_CLOEXEC}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj<ubhN constant, as it is architecture-specific and is part of a numbering space of }(hj<hhhNhNubjd)}(h``O_*``h]hO_*}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj<ubh flags that is fairly full.)}(hj<hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKrhjhhubh)}(hXVIf your system call returns a new file descriptor, you should also consider what it means to use the :manpage:`poll(2)` family of system calls on that file descriptor. Making a file descriptor ready for reading or writing is the normal way for the kernel to indicate to userspace that an event has occurred on the corresponding kernel object.h](heIf your system call returns a new file descriptor, you should also consider what it means to use the }(hjhhhNhNubj)}(h:manpage:`poll(2)`h]hpoll(2)}(hjhhhNhNubah}(h]h ]jah"]h$]h&]jjjpoll(2)jpolljjuh1jhjubh family of system calls on that file descriptor. Making a file descriptor ready for reading or writing is the normal way for the kernel to indicate to userspace that an event has occurred on the corresponding kernel object.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK|hjhhubh)}(h?If your new xyzzy(2) system call involves a filename argument::h]h>If your new xyzzy(2) system call involves a filename argument:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h@int sys_xyzzy(const char __user *path, ..., unsigned int flags);h]h@int sys_xyzzy(const char __user *path, ..., unsigned int flags);}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hLyou should also consider whether an xyzzyat(2) version is more appropriate::h]hKyou should also consider whether an xyzzyat(2) version is more appropriate:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hKint sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags);h]hKint sys_xyzzyat(int dfd, const char __user *path, ..., unsigned int flags);}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hX This allows more flexibility for how userspace specifies the file in question; in particular it allows userspace to request the functionality for an already-opened file descriptor using the ``AT_EMPTY_PATH`` flag, effectively giving an fxyzzy(3) operation for free::h](hThis allows more flexibility for how userspace specifies the file in question; in particular it allows userspace to request the functionality for an already-opened file descriptor using the }(hj"hhhNhNubjd)}(h``AT_EMPTY_PATH``h]h AT_EMPTY_PATH}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj"ubh: flag, effectively giving an fxyzzy(3) operation for free:}(hj"hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h- xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...) - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...)h]h- xyzzyat(AT_FDCWD, path, ..., 0) is equivalent to xyzzy(path,...) - xyzzyat(fd, "", ..., AT_EMPTY_PATH) is equivalent to fxyzzy(fd, ...)}hjBsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(h(For more details on the rationale of the \*at() calls, see the :manpage:`openat(2)` man page; for an example of AT_EMPTY_PATH, see the :manpage:`fstatat(2)` man page.)h](h@(For more details on the rationale of the *at() calls, see the }(hjPhhhNhNubj)}(h:manpage:`openat(2)`h]h openat(2)}(hjXhhhNhNubah}(h]h ]jah"]h$]h&]jjj openat(2)jopenatjjuh1jhjPubh4 man page; for an example of AT_EMPTY_PATH, see the }(hjPhhhNhNubj)}(h:manpage:`fstatat(2)`h]h fstatat(2)}(hjlhhhNhNubah}(h]h ]jah"]h$]h&]jjj fstatat(2)jfstatatjjuh1jhjPubh man page.)}(hjPhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hIf your new xyzzy(2) system call involves a parameter describing an offset within a file, make its type ``loff_t`` so that 64-bit offsets can be supported even on 32-bit architectures.h](hhIf your new xyzzy(2) system call involves a parameter describing an offset within a file, make its type }(hjhhhNhNubjd)}(h ``loff_t``h]hloff_t}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubhF so that 64-bit offsets can be supported even on 32-bit architectures.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX7If your new xyzzy(2) system call involves privileged functionality, it needs to be governed by the appropriate Linux capability bit (checked with a call to ``capable()``), as described in the :manpage:`capabilities(7)` man page. Choose an existing capability bit that governs related functionality, but try to avoid combining lots of only vaguely related functions together under the same bit, as this goes against capabilities' purpose of splitting the power of root. In particular, avoid adding new uses of the already overly-general ``CAP_SYS_ADMIN`` capability.h](hIf your new xyzzy(2) system call involves privileged functionality, it needs to be governed by the appropriate Linux capability bit (checked with a call to }(hjhhhNhNubjd)}(h ``capable()``h]h capable()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh), as described in the }(hjhhhNhNubj)}(h:manpage:`capabilities(7)`h]hcapabilities(7)}(hjhhhNhNubah}(h]h ]jah"]h$]h&]jjjcapabilities(7)j capabilitiesj7uh1jhjubhXB man page. Choose an existing capability bit that governs related functionality, but try to avoid combining lots of only vaguely related functions together under the same bit, as this goes against capabilities’ purpose of splitting the power of root. In particular, avoid adding new uses of the already overly-general }(hjhhhNhNubjd)}(h``CAP_SYS_ADMIN``h]h CAP_SYS_ADMIN}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh capability.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hX/If your new xyzzy(2) system call manipulates a process other than the calling process, it should be restricted (using a call to ``ptrace_may_access()``) so that only a calling process with the same permissions as the target process, or with the necessary capabilities, can manipulate the target process.h](hIf your new xyzzy(2) system call manipulates a process other than the calling process, it should be restricted (using a call to }(hjhhhNhNubjd)}(h``ptrace_may_access()``h]hptrace_may_access()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh) so that only a calling process with the same permissions as the target process, or with the necessary capabilities, can manipulate the target process.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXNFinally, be aware that some non-x86 architectures have an easier time if system call parameters that are explicitly 64-bit fall on odd-numbered arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit registers. (This concern does not apply if the arguments are part of a structure that's passed in by pointer.)h]hXPFinally, be aware that some non-x86 architectures have an easier time if system call parameters that are explicitly 64-bit fall on odd-numbered arguments (i.e. parameter 1, 3, 5), to allow use of contiguous pairs of 32-bit registers. (This concern does not apply if the arguments are part of a structure that’s passed in by pointer.)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]&designing-the-api-other-considerationsah ]h"]'designing the api: other considerationsah$]h&]uh1hhhhhhhhKkubh)}(hhh](h)}(hProposing the APIh]hProposing the API}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj#hhhhhKubh)}(hTo make new system calls easy to review, it's best to divide up the patchset into separate chunks. These should include at least the following items as distinct commits (each of which is described further below):h]hTo make new system calls easy to review, it’s best to divide up the patchset into separate chunks. These should include at least the following items as distinct commits (each of which is described further below):}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj#hhubj2)}(hX - The core implementation of the system call, together with prototypes, generic numbering, Kconfig changes and fallback stub implementation. - Wiring up of the new system call for one particular architecture, usually x86 (including all of x86_64, x86_32 and x32). - A demonstration of the use of the new system call in userspace via a selftest in ``tools/testing/selftests/``. - A draft man-page for the new system call, either as plain text in the cover letter, or as a patch to the (separate) man-pages repository. h]j8)}(hhh](j=)}(hThe core implementation of the system call, together with prototypes, generic numbering, Kconfig changes and fallback stub implementation.h]h)}(hThe core implementation of the system call, together with prototypes, generic numbering, Kconfig changes and fallback stub implementation.h]hThe core implementation of the system call, together with prototypes, generic numbering, Kconfig changes and fallback stub implementation.}(hjMhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjIubah}(h]h ]h"]h$]h&]uh1j<hjFubj=)}(hxWiring up of the new system call for one particular architecture, usually x86 (including all of x86_64, x86_32 and x32).h]h)}(hxWiring up of the new system call for one particular architecture, usually x86 (including all of x86_64, x86_32 and x32).h]hxWiring up of the new system call for one particular architecture, usually x86 (including all of x86_64, x86_32 and x32).}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjaubah}(h]h ]h"]h$]h&]uh1j<hjFubj=)}(hnA demonstration of the use of the new system call in userspace via a selftest in ``tools/testing/selftests/``.h]h)}(hnA demonstration of the use of the new system call in userspace via a selftest in ``tools/testing/selftests/``.h](hQA demonstration of the use of the new system call in userspace via a selftest in }(hj}hhhNhNubjd)}(h``tools/testing/selftests/``h]htools/testing/selftests/}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj}ubh.}(hj}hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjyubah}(h]h ]h"]h$]h&]uh1j<hjFubj=)}(hA draft man-page for the new system call, either as plain text in the cover letter, or as a patch to the (separate) man-pages repository. h]h)}(hA draft man-page for the new system call, either as plain text in the cover letter, or as a patch to the (separate) man-pages repository.h]hA draft man-page for the new system call, either as plain text in the cover letter, or as a patch to the (separate) man-pages repository.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j<hjFubeh}(h]h ]h"]h$]h&]j j uh1j7hhhKhjBubah}(h]h ]h"]h$]h&]uh1j1hhhKhj#hhubh)}(htNew system call proposals, like any change to the kernel's API, should always be cc'ed to linux-api@vger.kernel.org.h](h^New system call proposals, like any change to the kernel’s API, should always be cc’ed to }(hjhhhNhNubh reference)}(hlinux-api@vger.kernel.orgh]hlinux-api@vger.kernel.org}(hjhhhNhNubah}(h]h ]h"]h$]h&]refuri mailto:linux-api@vger.kernel.orguh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj#hhubeh}(h]proposing-the-apiah ]h"]proposing the apiah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h"Generic System Call Implementationh]h"Generic System Call Implementation}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hXThe main entry point for your new xyzzy(2) system call will be called ``sys_xyzzy()``, but you add this entry point with the appropriate ``SYSCALL_DEFINEn()`` macro rather than explicitly. The 'n' indicates the number of arguments to the system call, and the macro takes the system call name followed by the (type, name) pairs for the parameters as arguments. Using this macro allows metadata about the new system call to be made available for other tools.h](hFThe main entry point for your new xyzzy(2) system call will be called }(hjhhhNhNubjd)}(h``sys_xyzzy()``h]h sys_xyzzy()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh4, but you add this entry point with the appropriate }(hjhhhNhNubjd)}(h``SYSCALL_DEFINEn()``h]hSYSCALL_DEFINEn()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubhX0 macro rather than explicitly. The ‘n’ indicates the number of arguments to the system call, and the macro takes the system call name followed by the (type, name) pairs for the parameters as arguments. Using this macro allows metadata about the new system call to be made available for other tools.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThe new entry point also needs a corresponding function prototype, in ``include/linux/syscalls.h``, marked as asmlinkage to match the way that system calls are invoked::h](hFThe new entry point also needs a corresponding function prototype, in }(hj6hhhNhNubjd)}(h``include/linux/syscalls.h``h]hinclude/linux/syscalls.h}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj6ubhF, marked as asmlinkage to match the way that system calls are invoked:}(hj6hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hasmlinkage long sys_xyzzy(...);h]hasmlinkage long sys_xyzzy(...);}hjVsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hXSome architectures (e.g. x86) have their own architecture-specific syscall tables, but several other architectures share a generic syscall table. Add your new system call to the generic list by adding an entry to the list in ``include/uapi/asm-generic/unistd.h``::h](hSome architectures (e.g. x86) have their own architecture-specific syscall tables, but several other architectures share a generic syscall table. Add your new system call to the generic list by adding an entry to the list in }(hjdhhhNhNubjd)}(h%``include/uapi/asm-generic/unistd.h``h]h!include/uapi/asm-generic/unistd.h}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjdubh:}(hjdhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h7#define __NR_xyzzy 292 __SYSCALL(__NR_xyzzy, sys_xyzzy)h]h7#define __NR_xyzzy 292 __SYSCALL(__NR_xyzzy, sys_xyzzy)}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hAlso update the __NR_syscalls count to reflect the additional system call, and note that if multiple new system calls are added in the same merge window, your new syscall number may get adjusted to resolve conflicts.h]hAlso update the __NR_syscalls count to reflect the additional system call, and note that if multiple new system calls are added in the same merge window, your new syscall number may get adjusted to resolve conflicts.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThe file ``kernel/sys_ni.c`` provides a fallback stub implementation of each system call, returning ``-ENOSYS``. Add your new system call here too::h](h The file }(hjhhhNhNubjd)}(h``kernel/sys_ni.c``h]hkernel/sys_ni.c}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubhH provides a fallback stub implementation of each system call, returning }(hjhhhNhNubjd)}(h ``-ENOSYS``h]h-ENOSYS}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh%. Add your new system call here too:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hCOND_SYSCALL(xyzzy);h]hCOND_SYSCALL(xyzzy);}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hYour new kernel functionality, and the system call that controls it, should normally be optional, so add a ``CONFIG`` option (typically to ``init/Kconfig``) for it. As usual for new ``CONFIG`` options:h](hkYour new kernel functionality, and the system call that controls it, should normally be optional, so add a }(hjhhhNhNubjd)}(h ``CONFIG``h]hCONFIG}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh option (typically to }(hjhhhNhNubjd)}(h``init/Kconfig``h]h init/Kconfig}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh) for it. As usual for new }(hjhhhNhNubjd)}(h ``CONFIG``h]hCONFIG}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh options:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj2)}(hX- Include a description of the new functionality and system call controlled by the option. - Make the option depend on EXPERT if it should be hidden from normal users. - Make any new source files implementing the function dependent on the CONFIG option in the Makefile (e.g. ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.o``). - Double check that the kernel still builds with the new CONFIG option turned off. h]j8)}(hhh](j=)}(hXInclude a description of the new functionality and system call controlled by the option.h]h)}(hXInclude a description of the new functionality and system call controlled by the option.h]hXInclude a description of the new functionality and system call controlled by the option.}(hj/ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj+ ubah}(h]h ]h"]h$]h&]uh1j<hj( ubj=)}(hJMake the option depend on EXPERT if it should be hidden from normal users.h]h)}(hjE h]hJMake the option depend on EXPERT if it should be hidden from normal users.}(hjG hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjC ubah}(h]h ]h"]h$]h&]uh1j<hj( ubj=)}(hMake any new source files implementing the function dependent on the CONFIG option in the Makefile (e.g. ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.o``).h]h)}(hMake any new source files implementing the function dependent on the CONFIG option in the Makefile (e.g. ``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.o``).h](hiMake any new source files implementing the function dependent on the CONFIG option in the Makefile (e.g. }(hj^ hhhNhNubjd)}(h*``obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.o``h]h&obj-$(CONFIG_XYZZY_SYSCALL) += xyzzy.o}(hjf hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj^ ubh).}(hj^ hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjZ ubah}(h]h ]h"]h$]h&]uh1j<hj( ubj=)}(hQDouble check that the kernel still builds with the new CONFIG option turned off. h]h)}(hPDouble check that the kernel still builds with the new CONFIG option turned off.h]hPDouble check that the kernel still builds with the new CONFIG option turned off.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j<hj( ubeh}(h]h ]h"]h$]h&]j j uh1j7hhhKhj$ ubah}(h]h ]h"]h$]h&]uh1j1hhhKhjhhubh)}(h.To summarize, you need a commit that includes:h]h.To summarize, you need a commit that includes:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj2)}(hX- ``CONFIG`` option for the new function, normally in ``init/Kconfig`` - ``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry point - corresponding prototype in ``include/linux/syscalls.h`` - generic table entry in ``include/uapi/asm-generic/unistd.h`` - fallback stub in ``kernel/sys_ni.c`` h]j8)}(hhh](j=)}(hD``CONFIG`` option for the new function, normally in ``init/Kconfig``h]h)}(hj h](jd)}(h ``CONFIG``h]hCONFIG}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj ubh* option for the new function, normally in }(hj hhhNhNubjd)}(h``init/Kconfig``h]h init/Kconfig}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj ubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j<hj ubj=)}(h3``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry pointh]h)}(hj h](jd)}(h``SYSCALL_DEFINEn(xyzzy, ...)``h]hSYSCALL_DEFINEn(xyzzy, ...)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj ubh for the entry point}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j<hj ubj=)}(h7corresponding prototype in ``include/linux/syscalls.h``h]h)}(hj h](hcorresponding prototype in }(hj hhhNhNubjd)}(h``include/linux/syscalls.h``h]hinclude/linux/syscalls.h}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj ubeh}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j<hj ubj=)}(h hhhNhNubjd)}(h%``include/uapi/asm-generic/unistd.h``h]h!include/uapi/asm-generic/unistd.h}(hjE hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj> ubeh}(h]h ]h"]h$]h&]uh1hhhhKhj: ubah}(h]h ]h"]h$]h&]uh1j<hj ubj=)}(h&fallback stub in ``kernel/sys_ni.c`` h]h)}(h$fallback stub in ``kernel/sys_ni.c``h](hfallback stub in }(hjc hhhNhNubjd)}(h``kernel/sys_ni.c``h]hkernel/sys_ni.c}(hjk hhhNhNubah}(h]h ]h"]h$]h&]uh1jchjc ubeh}(h]h ]h"]h$]h&]uh1hhhhKhj_ ubah}(h]h ]h"]h$]h&]uh1j<hj ubeh}(h]h ]h"]h$]h&]j j uh1j7hhhKhj ubah}(h]h ]h"]h$]h&]uh1j1hhhKhjhhubh)}(h.. _syscall_generic_6_11:h]h}(h]h ]h"]h$]h&]hsyscall-generic-6-11uh1hhKhjhhhhubh)}(hhh](h)}(h Since 6.11h]h Since 6.11}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKubh)}(hStarting with kernel version 6.11, general system call implementation for the following architectures no longer requires modifications to ``include/uapi/asm-generic/unistd.h``:h](hStarting with kernel version 6.11, general system call implementation for the following architectures no longer requires modifications to }(hj hhhNhNubjd)}(h%``include/uapi/asm-generic/unistd.h``h]h!include/uapi/asm-generic/unistd.h}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj2)}(hF- arc - arm64 - csky - hexagon - loongarch - nios2 - openrisc - riscv h]j8)}(hhh](j=)}(harch]h)}(hj h]harc}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j<hj ubj=)}(harm64h]h)}(hj h]harm64}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j<hj ubj=)}(hcskyh]h)}(hj h]hcsky}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j<hj ubj=)}(hhexagonh]h)}(hj h]hhexagon}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j<hj ubj=)}(h loongarchh]h)}(hj2 h]h loongarch}(hj4 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj0 ubah}(h]h ]h"]h$]h&]uh1j<hj ubj=)}(hnios2h]h)}(hjI h]hnios2}(hjK hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hjG ubah}(h]h ]h"]h$]h&]uh1j<hj ubj=)}(hopenrisch]h)}(hj` h]hopenrisc}(hjb hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hj^ ubah}(h]h ]h"]h$]h&]uh1j<hj ubj=)}(hriscv h]h)}(hriscvh]hriscv}(hjy hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hju ubah}(h]h ]h"]h$]h&]uh1j<hj ubeh}(h]h ]h"]h$]h&]j j uh1j7hhhMhj ubah}(h]h ]h"]h$]h&]uh1j1hhhMhj hhubh)}(hsInstead, you need to update ``scripts/syscall.tbl`` and, if applicable, adjust ``arch/*/kernel/Makefile.syscalls``.h](hInstead, you need to update }(hj hhhNhNubjd)}(h``scripts/syscall.tbl``h]hscripts/syscall.tbl}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj ubh and, if applicable, adjust }(hj hhhNhNubjd)}(h#``arch/*/kernel/Makefile.syscalls``h]harch/*/kernel/Makefile.syscalls}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hj hhubh)}(hAs ``scripts/syscall.tbl`` serves as a common syscall table across multiple architectures, a new entry is required in this table::h](hAs }(hj hhhNhNubjd)}(h``scripts/syscall.tbl``h]hscripts/syscall.tbl}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj ubhg serves as a common syscall table across multiple architectures, a new entry is required in this table:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(h"468 common xyzzy sys_xyzzyh]h"468 common xyzzy sys_xyzzy}hj sbah}(h]h ]h"]h$]h&]jjuh1jhhhMhj hhubh)}(hNote that adding an entry to ``scripts/syscall.tbl`` with the "common" ABI also affects all architectures that share this table. For more limited or architecture-specific changes, consider using an architecture-specific ABI or defining a new one.h](hNote that adding an entry to }(hj hhhNhNubjd)}(h``scripts/syscall.tbl``h]hscripts/syscall.tbl}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj ubh with the “common” ABI also affects all architectures that share this table. For more limited or architecture-specific changes, consider using an architecture-specific ABI or defining a new one.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hIf a new ABI, say ``xyz``, is introduced, the corresponding updates should be made to ``arch/*/kernel/Makefile.syscalls`` as well::h](hIf a new ABI, say }(hj hhhNhNubjd)}(h``xyz``h]hxyz}(hj! hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj ubh=, is introduced, the corresponding updates should be made to }(hj hhhNhNubjd)}(h#``arch/*/kernel/Makefile.syscalls``h]harch/*/kernel/Makefile.syscalls}(hj3 hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj ubh as well:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(h!syscall_abis_{32,64} += xyz (...)h]h!syscall_abis_{32,64} += xyz (...)}hjK sbah}(h]h ]h"]h$]h&]jjuh1jhhhMhj hhubh)}(h.To summarize, you need a commit that includes:h]h.To summarize, you need a commit that includes:}(hjY hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj2)}(hXL- ``CONFIG`` option for the new function, normally in ``init/Kconfig`` - ``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry point - corresponding prototype in ``include/linux/syscalls.h`` - new entry in ``scripts/syscall.tbl`` - (if needed) Makefile updates in ``arch/*/kernel/Makefile.syscalls`` - fallback stub in ``kernel/sys_ni.c`` h]j8)}(hhh](j=)}(hD``CONFIG`` option for the new function, normally in ``init/Kconfig``h]h)}(hjp h](jd)}(h ``CONFIG``h]hCONFIG}(hju hhhNhNubah}(h]h ]h"]h$]h&]uh1jchjr ubh* option for the new function, normally in }(hjr hhhNhNubjd)}(h``init/Kconfig``h]h init/Kconfig}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchjr ubeh}(h]h ]h"]h$]h&]uh1hhhhM!hjn ubah}(h]h ]h"]h$]h&]uh1j<hjk ubj=)}(h3``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry pointh]h)}(hj h](jd)}(h``SYSCALL_DEFINEn(xyzzy, ...)``h]hSYSCALL_DEFINEn(xyzzy, ...)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj ubh for the entry point}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM"hj ubah}(h]h ]h"]h$]h&]uh1j<hjk ubj=)}(h7corresponding prototype in ``include/linux/syscalls.h``h]h)}(hj h](hcorresponding prototype in }(hj hhhNhNubjd)}(h``include/linux/syscalls.h``h]hinclude/linux/syscalls.h}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj ubeh}(h]h ]h"]h$]h&]uh1hhhhM#hj ubah}(h]h ]h"]h$]h&]uh1j<hjk ubj=)}(h$new entry in ``scripts/syscall.tbl``h]h)}(hj h](h new entry in }(hj hhhNhNubjd)}(h``scripts/syscall.tbl``h]hscripts/syscall.tbl}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj ubeh}(h]h ]h"]h$]h&]uh1hhhhM$hj ubah}(h]h ]h"]h$]h&]uh1j<hjk ubj=)}(hC(if needed) Makefile updates in ``arch/*/kernel/Makefile.syscalls``h]h)}(hj h](h (if needed) Makefile updates in }(hj hhhNhNubjd)}(h#``arch/*/kernel/Makefile.syscalls``h]harch/*/kernel/Makefile.syscalls}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj ubeh}(h]h ]h"]h$]h&]uh1hhhhM%hj ubah}(h]h ]h"]h$]h&]uh1j<hjk ubj=)}(h&fallback stub in ``kernel/sys_ni.c`` h]h)}(h$fallback stub in ``kernel/sys_ni.c``h](hfallback stub in }(hj9 hhhNhNubjd)}(h``kernel/sys_ni.c``h]hkernel/sys_ni.c}(hjA hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj9 ubeh}(h]h ]h"]h$]h&]uh1hhhhM&hj5 ubah}(h]h ]h"]h$]h&]uh1j<hjk ubeh}(h]h ]h"]h$]h&]j j uh1j7hhhM!hjg ubah}(h]h ]h"]h$]h&]uh1j1hhhM!hj hhubeh}(h]( since-6-11j eh ]h"]syscall_generic_6_11ah$] since 6.11ah&]uh1hhjhhhhhK referencedKexpect_referenced_by_name}jl j sexpect_referenced_by_id}j j subeh}(h]"generic-system-call-implementationah ]h"]"generic system call implementationah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hx86 System Call Implementationh]hx86 System Call Implementation}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj} hhhhhM*ubh)}(hXTo wire up your new system call for x86 platforms, you need to update the master syscall tables. Assuming your new system call isn't special in some way (see below), this involves a "common" entry (for x86_64 and x32) in arch/x86/entry/syscalls/syscall_64.tbl::h]hX To wire up your new system call for x86 platforms, you need to update the master syscall tables. Assuming your new system call isn’t special in some way (see below), this involves a “common” entry (for x86_64 and x32) in arch/x86/entry/syscalls/syscall_64.tbl:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM,hj} hhubj)}(h"333 common xyzzy sys_xyzzyh]h"333 common xyzzy sys_xyzzy}hj sbah}(h]h ]h"]h$]h&]jjuh1jhhhM1hj} hhubh)}(hCand an "i386" entry in ``arch/x86/entry/syscalls/syscall_32.tbl``::h](hand an “i386” entry in }(hj hhhNhNubjd)}(h*``arch/x86/entry/syscalls/syscall_32.tbl``h]h&arch/x86/entry/syscalls/syscall_32.tbl}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM3hj} hhubj)}(h"380 i386 xyzzy sys_xyzzyh]h"380 i386 xyzzy sys_xyzzy}hj sbah}(h]h ]h"]h$]h&]jjuh1jhhhM5hj} hhubh)}(hbAgain, these numbers are liable to be changed if there are conflicts in the relevant merge window.h]hbAgain, these numbers are liable to be changed if there are conflicts in the relevant merge window.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM7hj} hhubeh}(h]x86-system-call-implementationah ]h"]x86 system call implementationah$]h&]uh1hhhhhhhhM*ubh)}(hhh](h)}(h$Compatibility System Calls (Generic)h]h$Compatibility System Calls (Generic)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhM<ubh)}(hFor most system calls the same 64-bit implementation can be invoked even when the userspace program is itself 32-bit; even if the system call's parameters include an explicit pointer, this is handled transparently.h]hFor most system calls the same 64-bit implementation can be invoked even when the userspace program is itself 32-bit; even if the system call’s parameters include an explicit pointer, this is handled transparently.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM>hj hhubh)}(hHowever, there are a couple of situations where a compatibility layer is needed to cope with size differences between 32-bit and 64-bit.h]hHowever, there are a couple of situations where a compatibility layer is needed to cope with size differences between 32-bit and 64-bit.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMBhj hhubh)}(hThe first is if the 64-bit kernel also supports 32-bit userspace programs, and so needs to parse areas of (``__user``) memory that could hold either 32-bit or 64-bit values. In particular, this is needed whenever a system call argument is:h](hkThe first is if the 64-bit kernel also supports 32-bit userspace programs, and so needs to parse areas of (}(hjhhhNhNubjd)}(h ``__user``h]h__user}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh{) memory that could hold either 32-bit or 64-bit values. In particular, this is needed whenever a system call argument is:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMEhj hhubj2)}(h- a pointer to a pointer - a pointer to a struct containing a pointer (e.g. ``struct iovec __user *``) - a pointer to a varying sized integral type (``time_t``, ``off_t``, ``long``, ...) - a pointer to a struct containing a varying sized integral type. h]j8)}(hhh](j=)}(ha pointer to a pointerh]h)}(hjDh]ha pointer to a pointer}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMJhjBubah}(h]h ]h"]h$]h&]uh1j<hj?ubj=)}(hKa pointer to a struct containing a pointer (e.g. ``struct iovec __user *``)h]h)}(hj[h](h1a pointer to a struct containing a pointer (e.g. }(hj]hhhNhNubjd)}(h``struct iovec __user *``h]hstruct iovec __user *}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj]ubh)}(hj]hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMKhjYubah}(h]h ]h"]h$]h&]uh1j<hj?ubj=)}(hQa pointer to a varying sized integral type (``time_t``, ``off_t``, ``long``, ...)h]h)}(hQa pointer to a varying sized integral type (``time_t``, ``off_t``, ``long``, ...)h](h,a pointer to a varying sized integral type (}(hjhhhNhNubjd)}(h ``time_t``h]htime_t}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh, }(hjhhhNhNubjd)}(h ``off_t``h]hoff_t}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh, }(hjhhhNhNubjd)}(h``long``h]hlong}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh, ...)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMLhjubah}(h]h ]h"]h$]h&]uh1j<hj?ubj=)}(h@a pointer to a struct containing a varying sized integral type. h]h)}(h?a pointer to a struct containing a varying sized integral type.h]h?a pointer to a struct containing a varying sized integral type.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMNhjubah}(h]h ]h"]h$]h&]uh1j<hj?ubeh}(h]h ]h"]h$]h&]j j uh1j7hhhMJhj;ubah}(h]h ]h"]h$]h&]uh1j1hhhMJhj hhubh)}(hXThe second situation that requires a compatibility layer is if one of the system call's arguments has a type that is explicitly 64-bit even on a 32-bit architecture, for example ``loff_t`` or ``__u64``. In this case, a value that arrives at a 64-bit kernel from a 32-bit application will be split into two 32-bit values, which then need to be re-assembled in the compatibility layer.h](hThe second situation that requires a compatibility layer is if one of the system call’s arguments has a type that is explicitly 64-bit even on a 32-bit architecture, for example }(hjhhhNhNubjd)}(h ``loff_t``h]hloff_t}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh or }(hjhhhNhNubjd)}(h ``__u64``h]h__u64}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh. In this case, a value that arrives at a 64-bit kernel from a 32-bit application will be split into two 32-bit values, which then need to be re-assembled in the compatibility layer.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMPhj hhubh)}(h(Note that a system call argument that's a pointer to an explicit 64-bit type does **not** need a compatibility layer; for example, :manpage:`splice(2)`'s arguments of type ``loff_t __user *`` do not trigger the need for a ``compat_`` system call.)h](hU(Note that a system call argument that’s a pointer to an explicit 64-bit type does }(hj&hhhNhNubhstrong)}(h**not**h]hnot}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1j.hj&ubh* need a compatibility layer; for example, }(hj&hhhNhNubj)}(h:manpage:`splice(2)`h]h splice(2)}(hjBhhhNhNubah}(h]h ]jah"]h$]h&]jjj splice(2)jsplicejjuh1jhj&ubh’s arguments of type }(hj&hhhNhNubjd)}(h``loff_t __user *``h]hloff_t __user *}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj&ubh do not trigger the need for a }(hj&hhhNhNubjd)}(h ``compat_``h]hcompat_}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj&ubh system call.)}(hj&hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMVhj hhubh)}(hXThe compatibility version of the system call is called ``compat_sys_xyzzy()``, and is added with the ``COMPAT_SYSCALL_DEFINEn()`` macro, analogously to SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit kernel, but expects to receive 32-bit parameter values and does whatever is needed to deal with them. (Typically, the ``compat_sys_`` version converts the values to 64-bit versions and either calls on to the ``sys_`` version, or both of them call a common inner implementation function.)h](h7The compatibility version of the system call is called }(hjhhhNhNubjd)}(h``compat_sys_xyzzy()``h]hcompat_sys_xyzzy()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh, and is added with the }(hjhhhNhNubjd)}(h``COMPAT_SYSCALL_DEFINEn()``h]hCOMPAT_SYSCALL_DEFINEn()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh macro, analogously to SYSCALL_DEFINEn. This version of the implementation runs as part of a 64-bit kernel, but expects to receive 32-bit parameter values and does whatever is needed to deal with them. (Typically, the }(hjhhhNhNubjd)}(h``compat_sys_``h]h compat_sys_}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubhK version converts the values to 64-bit versions and either calls on to the }(hjhhhNhNubjd)}(h``sys_``h]hsys_}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubhG version, or both of them call a common inner implementation function.)}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMZhj hhubh)}(hThe compat entry point also needs a corresponding function prototype, in ``include/linux/compat.h``, marked as asmlinkage to match the way that system calls are invoked::h](hIThe compat entry point also needs a corresponding function prototype, in }(hjhhhNhNubjd)}(h``include/linux/compat.h``h]hinclude/linux/compat.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubhF, marked as asmlinkage to match the way that system calls are invoked:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMbhj hhubj)}(h&asmlinkage long compat_sys_xyzzy(...);h]h&asmlinkage long compat_sys_xyzzy(...);}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhMfhj hhubh)}(hXIf the system call involves a structure that is laid out differently on 32-bit and 64-bit systems, say ``struct xyzzy_args``, then the include/linux/compat.h header file should also include a compat version of the structure (``struct compat_xyzzy_args``) where each variable-size field has the appropriate ``compat_`` type that corresponds to the type in ``struct xyzzy_args``. The ``compat_sys_xyzzy()`` routine can then use this ``compat_`` structure to parse the arguments from a 32-bit invocation.h](hgIf the system call involves a structure that is laid out differently on 32-bit and 64-bit systems, say }(hjhhhNhNubjd)}(h``struct xyzzy_args``h]hstruct xyzzy_args}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubhe, then the include/linux/compat.h header file should also include a compat version of the structure (}(hjhhhNhNubjd)}(h``struct compat_xyzzy_args``h]hstruct compat_xyzzy_args}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh5) where each variable-size field has the appropriate }(hjhhhNhNubjd)}(h ``compat_``h]hcompat_}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh& type that corresponds to the type in }(hjhhhNhNubjd)}(h``struct xyzzy_args``h]hstruct xyzzy_args}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh. The }(hjhhhNhNubjd)}(h``compat_sys_xyzzy()``h]hcompat_sys_xyzzy()}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh routine can then use this }(hjhhhNhNubjd)}(h ``compat_``h]hcompat_}(hjfhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh; structure to parse the arguments from a 32-bit invocation.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhhj hhubh)}(h"For example, if there are fields::h]h!For example, if there are fields:}(hj~hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMphj hhubj)}(htstruct xyzzy_args { const char __user *ptr; __kernel_long_t varying_val; u64 fixed_val; /* ... */ };h]htstruct xyzzy_args { const char __user *ptr; __kernel_long_t varying_val; u64 fixed_val; /* ... */ };}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhMrhj hhubh)}(h@in struct xyzzy_args, then struct compat_xyzzy_args would have::h]h?in struct xyzzy_args, then struct compat_xyzzy_args would have:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMyhj hhubj)}(htstruct compat_xyzzy_args { compat_uptr_t ptr; compat_long_t varying_val; u64 fixed_val; /* ... */ };h]htstruct compat_xyzzy_args { compat_uptr_t ptr; compat_long_t varying_val; u64 fixed_val; /* ... */ };}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhM{hj hhubh)}(hThe generic system call list also needs adjusting to allow for the compat version; the entry in ``include/uapi/asm-generic/unistd.h`` should use ``__SC_COMP`` rather than ``__SYSCALL``::h](h`The generic system call list also needs adjusting to allow for the compat version; the entry in }(hjhhhNhNubjd)}(h%``include/uapi/asm-generic/unistd.h``h]h!include/uapi/asm-generic/unistd.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh should use }(hjhhhNhNubjd)}(h ``__SC_COMP``h]h __SC_COMP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh rather than }(hjhhhNhNubjd)}(h ``__SYSCALL``h]h __SYSCALL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(hI#define __NR_xyzzy 292 __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy)h]hI#define __NR_xyzzy 292 __SC_COMP(__NR_xyzzy, sys_xyzzy, compat_sys_xyzzy)}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhj hhubh)}(hTo summarize, you need:h]hTo summarize, you need:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj2)}(hX- a ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry point - corresponding prototype in ``include/linux/compat.h`` - (if needed) 32-bit mapping struct in ``include/linux/compat.h`` - instance of ``__SC_COMP`` not ``__SYSCALL`` in ``include/uapi/asm-generic/unistd.h`` h]j8)}(hhh](j=)}(hCa ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry pointh]h)}(hjh](ha }(hj!hhhNhNubjd)}(h&``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)``h]h"COMPAT_SYSCALL_DEFINEn(xyzzy, ...)}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1jchj!ubh for the compat entry point}(hj!hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(h5corresponding prototype in ``include/linux/compat.h``h]h)}(hjHh](hcorresponding prototype in }(hjJhhhNhNubjd)}(h``include/linux/compat.h``h]hinclude/linux/compat.h}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjJubeh}(h]h ]h"]h$]h&]uh1hhhhMhjFubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(h?(if needed) 32-bit mapping struct in ``include/linux/compat.h``h]h)}(hjmh](h%(if needed) 32-bit mapping struct in }(hjohhhNhNubjd)}(h``include/linux/compat.h``h]hinclude/linux/compat.h}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjoubeh}(h]h ]h"]h$]h&]uh1hhhhMhjkubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hVinstance of ``__SC_COMP`` not ``__SYSCALL`` in ``include/uapi/asm-generic/unistd.h`` h]h)}(hTinstance of ``__SC_COMP`` not ``__SYSCALL`` in ``include/uapi/asm-generic/unistd.h``h](h instance of }(hjhhhNhNubjd)}(h ``__SC_COMP``h]h __SC_COMP}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh not }(hjhhhNhNubjd)}(h ``__SYSCALL``h]h __SYSCALL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh in }(hjhhhNhNubjd)}(h%``include/uapi/asm-generic/unistd.h``h]h!include/uapi/asm-generic/unistd.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j<hjubeh}(h]h ]h"]h$]h&]j j uh1j7hhhMhjubah}(h]h ]h"]h$]h&]uh1j1hhhMhj hhubh)}(hhh](h)}(h Since 6.11h]h Since 6.11}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hThis applies to all the architectures listed in :ref:`Since 6.11` under "Generic System Call Implementation", except arm64. See :ref:`Compatibility System Calls (arm64)` for more information.h](h0This applies to all the architectures listed in }(hjhhhNhNubh)}(h':ref:`Since 6.11`h]h)}(hjh]h Since 6.11}(hjhhhNhNubah}(h]h ](hstdstd-refeh"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]refdocj refdomainj reftyperef refexplicitrefwarnjsyscall_generic_6_11uh1hhhhMhjubhC under “Generic System Call Implementation”, except arm64. See }(hjhhhNhNubh)}(h7:ref:`Compatibility System Calls (arm64)`h]h)}(hj%h]h"Compatibility System Calls (arm64)}(hj'hhhNhNubah}(h]h ](hstdstd-refeh"]h$]h&]uh1hhj#ubah}(h]h ]h"]h$]h&]refdocj refdomainj1reftyperef refexplicitrefwarnj compat_arm64uh1hhhhMhjubh for more information.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hYou need to extend the entry in ``scripts/syscall.tbl`` with an extra column to indicate that a 32-bit userspace program running on a 64-bit kernel should hit the compat entry point::h](h You need to extend the entry in }(hjMhhhNhNubjd)}(h``scripts/syscall.tbl``h]hscripts/syscall.tbl}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjMubh with an extra column to indicate that a 32-bit userspace program running on a 64-bit kernel should hit the compat entry point:}(hjMhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(h8468 common xyzzy sys_xyzzy compat_sys_xyzzyh]h8468 common xyzzy sys_xyzzy compat_sys_xyzzy}hjmsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjhhubh)}(hTo summarize, you need:h]hTo summarize, you need:}(hj{hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj2)}(hX- ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry point - corresponding prototype in ``include/linux/compat.h`` - modification of the entry in ``scripts/syscall.tbl`` to include an extra "compat" column - (if needed) 32-bit mapping struct in ``include/linux/compat.h`` h]j8)}(hhh](j=)}(hA``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry pointh]h)}(hjh](jd)}(h&``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)``h]h"COMPAT_SYSCALL_DEFINEn(xyzzy, ...)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh for the compat entry point}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(h5corresponding prototype in ``include/linux/compat.h``h]h)}(hjh](hcorresponding prototype in }(hjhhhNhNubjd)}(h``include/linux/compat.h``h]hinclude/linux/compat.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hXmodification of the entry in ``scripts/syscall.tbl`` to include an extra "compat" columnh]h)}(hXmodification of the entry in ``scripts/syscall.tbl`` to include an extra "compat" columnh](hmodification of the entry in }(hjhhhNhNubjd)}(h``scripts/syscall.tbl``h]hscripts/syscall.tbl}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh( to include an extra “compat” column}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hA(if needed) 32-bit mapping struct in ``include/linux/compat.h`` h]h)}(h?(if needed) 32-bit mapping struct in ``include/linux/compat.h``h](h%(if needed) 32-bit mapping struct in }(hjhhhNhNubjd)}(h``include/linux/compat.h``h]hinclude/linux/compat.h}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j<hjubeh}(h]h ]h"]h$]h&]j j uh1j7hhhMhjubah}(h]h ]h"]h$]h&]uh1j1hhhMhjhhubh)}(h.. _compat_arm64:h]h}(h]h ]h"]h$]h&]h compat-arm64uh1hhMhjhhhhubh)}(hhh](h)}(h"Compatibility System Calls (arm64)h]h"Compatibility System Calls (arm64)}(hjDhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjAhhhhhMubh)}(hOn arm64, there is a dedicated syscall table for compatibility system calls targeting 32-bit (AArch32) userspace: ``arch/arm64/tools/syscall_32.tbl``. You need to add an additional line to this table specifying the compat entry point::h](hrOn arm64, there is a dedicated syscall table for compatibility system calls targeting 32-bit (AArch32) userspace: }(hjRhhhNhNubjd)}(h#``arch/arm64/tools/syscall_32.tbl``h]harch/arm64/tools/syscall_32.tbl}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjRubhU. You need to add an additional line to this table specifying the compat entry point:}(hjRhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjAhhubj)}(h8468 common xyzzy sys_xyzzy compat_sys_xyzzyh]h8468 common xyzzy sys_xyzzy compat_sys_xyzzy}hjrsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjAhhubeh}(h]( compatibility-system-calls-arm64j@eh ]h"]("compatibility system calls (arm64) compat_arm64eh$]h&]uh1hhjhhhhhMjq }jj6sjs }j@j6subeh}(h]id1ah ]h"]h$]jn ah&]uh1hhj hhhhhMjp Kubeh}(h]"compatibility-system-calls-genericah ]h"]$compatibility system calls (generic)ah$]h&]uh1hhhhhhhhM<ubh)}(hhh](h)}(h Compatibility System Calls (x86)h]h Compatibility System Calls (x86)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hTo wire up the x86 architecture of a system call with a compatibility version, the entries in the syscall tables need to be adjusted.h]hTo wire up the x86 architecture of a system call with a compatibility version, the entries in the syscall tables need to be adjusted.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hFirst, the entry in ``arch/x86/entry/syscalls/syscall_32.tbl`` gets an extra column to indicate that a 32-bit userspace program running on a 64-bit kernel should hit the compat entry point::h](hFirst, the entry in }(hjhhhNhNubjd)}(h*``arch/x86/entry/syscalls/syscall_32.tbl``h]h&arch/x86/entry/syscalls/syscall_32.tbl}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh gets an extra column to indicate that a 32-bit userspace program running on a 64-bit kernel should hit the compat entry point:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(h=380 i386 xyzzy sys_xyzzy __ia32_compat_sys_xyzzyh]h=380 i386 xyzzy sys_xyzzy __ia32_compat_sys_xyzzy}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjhhubh)}(hSecond, you need to figure out what should happen for the x32 ABI version of the new system call. There's a choice here: the layout of the arguments should either match the 64-bit version or the 32-bit version.h]hSecond, you need to figure out what should happen for the x32 ABI version of the new system call. There’s a choice here: the layout of the arguments should either match the 64-bit version or the 32-bit version.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hIf there's a pointer-to-a-pointer involved, the decision is easy: x32 is ILP32, so the layout should match the 32-bit version, and the entry in ``arch/x86/entry/syscalls/syscall_64.tbl`` is split so that x32 programs hit the compatibility wrapper::h](hIf there’s a pointer-to-a-pointer involved, the decision is easy: x32 is ILP32, so the layout should match the 32-bit version, and the entry in }(hjhhhNhNubjd)}(h*``arch/x86/entry/syscalls/syscall_64.tbl``h]h&arch/x86/entry/syscalls/syscall_64.tbl}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh= is split so that x32 programs hit the compatibility wrapper:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubj)}(hV333 64 xyzzy sys_xyzzy ... 555 x32 xyzzy __x32_compat_sys_xyzzyh]hV333 64 xyzzy sys_xyzzy ... 555 x32 xyzzy __x32_compat_sys_xyzzy}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjhhubh)}(hIf no pointers are involved, then it is preferable to reuse the 64-bit system call for the x32 ABI (and consequently the entry in arch/x86/entry/syscalls/syscall_64.tbl is unchanged).h]hIf no pointers are involved, then it is preferable to reuse the 64-bit system call for the x32 ABI (and consequently the entry in arch/x86/entry/syscalls/syscall_64.tbl is unchanged).}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hIn either case, you should check that the types involved in your argument layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or 64-bit (-m64) equivalents.h]hIn either case, you should check that the types involved in your argument layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or 64-bit (-m64) equivalents.}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjhhubeh}(h]compatibility-system-calls-x86ah ]h"] compatibility system calls (x86)ah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(h System Calls Returning Elsewhereh]h System Calls Returning Elsewhere}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjGhhhhhMubh)}(hXFor most system calls, once the system call is complete the user program continues exactly where it left off -- at the next instruction, with the stack the same and most of the registers the same as before the system call, and with the same virtual memory space.h]hXFor most system calls, once the system call is complete the user program continues exactly where it left off -- at the next instruction, with the stack the same and most of the registers the same as before the system call, and with the same virtual memory space.}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjGhhubh)}(hHowever, a few system calls do things differently. They might return to a different location (``rt_sigreturn``) or change the memory space (``fork``/``vfork``/``clone``) or even architecture (``execve``/``execveat``) of the program.h](h_However, a few system calls do things differently. They might return to a different location (}(hjfhhhNhNubjd)}(h``rt_sigreturn``h]h rt_sigreturn}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjfubh) or change the memory space (}(hjfhhhNhNubjd)}(h``fork``h]hfork}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjfubh/}(hjfhhhNhNubjd)}(h ``vfork``h]hvfork}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjfubh/}hjfsbjd)}(h ``clone``h]hclone}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjfubh) or even architecture (}(hjfhhhNhNubjd)}(h ``execve``h]hexecve}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjfubh/}hjfsbjd)}(h ``execveat``h]hexecveat}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjfubh) of the program.}(hjfhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjGhhubh)}(hTo allow for this, the kernel implementation of the system call may need to save and restore additional registers to the kernel stack, allowing complete control of where and how execution continues after the system call.h]hTo allow for this, the kernel implementation of the system call may need to save and restore additional registers to the kernel stack, allowing complete control of where and how execution continues after the system call.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjGhhubh)}(hThis is arch-specific, but typically involves defining assembly entry points that save/restore additional registers and invoke the real system call entry point.h]hThis is arch-specific, but typically involves defining assembly entry points that save/restore additional registers and invoke the real system call entry point.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjGhhubh)}(hFor x86_64, this is implemented as a ``stub_xyzzy`` entry point in ``arch/x86/entry/entry_64.S``, and the entry in the syscall table (``arch/x86/entry/syscalls/syscall_64.tbl``) is adjusted to match::h](h%For x86_64, this is implemented as a }(hjhhhNhNubjd)}(h``stub_xyzzy``h]h stub_xyzzy}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh entry point in }(hjhhhNhNubjd)}(h``arch/x86/entry/entry_64.S``h]harch/x86/entry/entry_64.S}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh&, and the entry in the syscall table (}(hjhhhNhNubjd)}(h*``arch/x86/entry/syscalls/syscall_64.tbl``h]h&arch/x86/entry/syscalls/syscall_64.tbl}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh) is adjusted to match:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjGhhubj)}(h#333 common xyzzy stub_xyzzyh]h#333 common xyzzy stub_xyzzy}hj@sbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjGhhubh)}(hThe equivalent for 32-bit programs running on a 64-bit kernel is normally called ``stub32_xyzzy`` and implemented in ``arch/x86/entry/entry_64_compat.S``, with the corresponding syscall table adjustment in ``arch/x86/entry/syscalls/syscall_32.tbl``::h](hQThe equivalent for 32-bit programs running on a 64-bit kernel is normally called }(hjNhhhNhNubjd)}(h``stub32_xyzzy``h]h stub32_xyzzy}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjNubh and implemented in }(hjNhhhNhNubjd)}(h$``arch/x86/entry/entry_64_compat.S``h]h arch/x86/entry/entry_64_compat.S}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjNubh5, with the corresponding syscall table adjustment in }(hjNhhhNhNubjd)}(h*``arch/x86/entry/syscalls/syscall_32.tbl``h]h&arch/x86/entry/syscalls/syscall_32.tbl}(hjzhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjNubh:}(hjNhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjGhhubj)}(h2380 i386 xyzzy sys_xyzzy stub32_xyzzyh]h2380 i386 xyzzy sys_xyzzy stub32_xyzzy}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjGhhubh)}(hXIf the system call needs a compatibility layer (as in the previous section) then the ``stub32_`` version needs to call on to the ``compat_sys_`` version of the system call rather than the native 64-bit version. Also, if the x32 ABI implementation is not common with the x86_64 version, then its syscall table will also need to invoke a stub that calls on to the ``compat_sys_`` version.h](hUIf the system call needs a compatibility layer (as in the previous section) then the }(hjhhhNhNubjd)}(h ``stub32_``h]hstub32_}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh! version needs to call on to the }(hjhhhNhNubjd)}(h``compat_sys_``h]h compat_sys_}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh version of the system call rather than the native 64-bit version. Also, if the x32 ABI implementation is not common with the x86_64 version, then its syscall table will also need to invoke a stub that calls on to the }(hjhhhNhNubjd)}(h``compat_sys_``h]h compat_sys_}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh version.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjGhhubh)}(hXUFor completeness, it's also nice to set up a mapping so that user-mode Linux still works -- its syscall table will reference stub_xyzzy, but the UML build doesn't include ``arch/x86/entry/entry_64.S`` implementation (because UML simulates registers etc). Fixing this is as simple as adding a #define to ``arch/x86/um/sys_call_table_64.c``::h](hFor completeness, it’s also nice to set up a mapping so that user-mode Linux still works -- its syscall table will reference stub_xyzzy, but the UML build doesn’t include }(hjhhhNhNubjd)}(h``arch/x86/entry/entry_64.S``h]harch/x86/entry/entry_64.S}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubhh implementation (because UML simulates registers etc). Fixing this is as simple as adding a #define to }(hjhhhNhNubjd)}(h#``arch/x86/um/sys_call_table_64.c``h]harch/x86/um/sys_call_table_64.c}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjGhhubj)}(h#define stub_xyzzy sys_xyzzyh]h#define stub_xyzzy sys_xyzzy}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhjGhhubeh}(h] system-calls-returning-elsewhereah ]h"] system calls returning elsewhereah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(h Other Detailsh]h Other Details}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj,hhhhhM ubh)}(hMost of the kernel treats system calls in a generic way, but there is the occasional exception that may need updating for your particular system call.h]hMost of the kernel treats system calls in a generic way, but there is the occasional exception that may need updating for your particular system call.}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM hj,hhubh)}(hXqThe audit subsystem is one such special case; it includes (arch-specific) functions that classify some special types of system call -- specifically file open (``open``/``openat``), program execution (``execve``/``exeveat``) or socket multiplexor (``socketcall``) operations. If your new system call is analogous to one of these, then the audit system should be updated.h](hThe audit subsystem is one such special case; it includes (arch-specific) functions that classify some special types of system call -- specifically file open (}(hjKhhhNhNubjd)}(h``open``h]hopen}(hjShhhNhNubah}(h]h ]h"]h$]h&]uh1jchjKubh/}(hjKhhhNhNubjd)}(h ``openat``h]hopenat}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1jchjKubh), program execution (}(hjKhhhNhNubjd)}(h ``execve``h]hexecve}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjKubh/}hjKsbjd)}(h ``exeveat``h]hexeveat}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjKubh) or socket multiplexor (}(hjKhhhNhNubjd)}(h``socketcall``h]h socketcall}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjKubhl) operations. If your new system call is analogous to one of these, then the audit system should be updated.}(hjKhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj,hhubh)}(hMore generally, if there is an existing system call that is analogous to your new system call, it's worth doing a kernel-wide grep for the existing system call to check there are no other special cases.h]hMore generally, if there is an existing system call that is analogous to your new system call, it’s worth doing a kernel-wide grep for the existing system call to check there are no other special cases.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj,hhubeh}(h] other-detailsah ]h"] other detailsah$]h&]uh1hhhhhhhhM ubh)}(hhh](h)}(hTestingh]hTesting}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhMubh)}(hX A new system call should obviously be tested; it is also useful to provide reviewers with a demonstration of how user space programs will use the system call. A good way to combine these aims is to include a simple self-test program in a new directory under ``tools/testing/selftests/``.h](hXA new system call should obviously be tested; it is also useful to provide reviewers with a demonstration of how user space programs will use the system call. A good way to combine these aims is to include a simple self-test program in a new directory under }(hjhhhNhNubjd)}(h``tools/testing/selftests/``h]htools/testing/selftests/}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjhhubh)}(hXFor a new system call, there will obviously be no libc wrapper function and so the test will need to invoke it using ``syscall()``; also, if the system call involves a new userspace-visible structure, the corresponding header will need to be installed to compile the test.h](huFor a new system call, there will obviously be no libc wrapper function and so the test will need to invoke it using }(hjhhhNhNubjd)}(h ``syscall()``h]h syscall()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh; also, if the system call involves a new userspace-visible structure, the corresponding header will need to be installed to compile the test.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM"hjhhubh)}(hMake sure the selftest runs successfully on all supported architectures. For example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32) and x32 (-mx32) ABI program.h]hMake sure the selftest runs successfully on all supported architectures. For example, check that it works when compiled as an x86_64 (-m64), x86_32 (-m32) and x32 (-mx32) ABI program.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM'hjhhubh)}(hFor more extensive and thorough testing of new functionality, you should also consider adding tests to the Linux Test Project, or to the xfstests project for filesystem-related changes.h]hFor more extensive and thorough testing of new functionality, you should also consider adding tests to the Linux Test Project, or to the xfstests project for filesystem-related changes.}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM+hjhhubj2)}(h`- https://linux-test-project.github.io/ - git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git h]j8)}(hhh](j=)}(h%https://linux-test-project.github.io/h]h)}(hj?h]j)}(hj?h]h%https://linux-test-project.github.io/}(hjDhhhNhNubah}(h]h ]h"]h$]h&]refurij?uh1jhjAubah}(h]h ]h"]h$]h&]uh1hhhhM/hj=ubah}(h]h ]h"]h$]h&]uh1j<hj:ubj=)}(h6git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git h]h)}(h4git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.gith]h4git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git}(hjbhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM0hj^ubah}(h]h ]h"]h$]h&]uh1j<hj:ubeh}(h]h ]h"]h$]h&]j j uh1j7hhhM/hj6ubah}(h]h ]h"]h$]h&]uh1j1hhhM/hjhhubeh}(h]testingah ]h"]testingah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hMan Pageh]hMan Page}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM4ubh)}(hX All new system calls should come with a complete man page, ideally using groff markup, but plain text will do. If groff is used, it's helpful to include a pre-rendered ASCII version of the man page in the cover email for the patchset, for the convenience of reviewers.h]hXAll new system calls should come with a complete man page, ideally using groff markup, but plain text will do. If groff is used, it’s helpful to include a pre-rendered ASCII version of the man page in the cover email for the patchset, for the convenience of reviewers.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM6hjhhubh)}(hThe man page should be cc'ed to linux-man@vger.kernel.org For more details, see https://www.kernel.org/doc/man-pages/patches.htmlh](h"The man page should be cc’ed to }(hjhhhNhNubj)}(hlinux-man@vger.kernel.orgh]hlinux-man@vger.kernel.org}(hjhhhNhNubah}(h]h ]h"]h$]h&]refuri mailto:linux-man@vger.kernel.orguh1jhjubh For more details, see }(hjhhhNhNubj)}(h1https://www.kernel.org/doc/man-pages/patches.htmlh]h1https://www.kernel.org/doc/man-pages/patches.html}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhhM;hjhhubeh}(h]man-pageah ]h"]man pageah$]h&]uh1hhhhhhhhM4ubh)}(hhh](h)}(h&Do not call System Calls in the Kernelh]h&Do not call System Calls in the Kernel}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM@ubh)}(hXSystem calls are, as stated above, interaction points between userspace and the kernel. Therefore, system call functions such as ``sys_xyzzy()`` or ``compat_sys_xyzzy()`` should only be called from userspace via the syscall table, but not from elsewhere in the kernel. If the syscall functionality is useful to be used within the kernel, needs to be shared between an old and a new syscall, or needs to be shared between a syscall and its compatibility variant, it should be implemented by means of a "helper" function (such as ``ksys_xyzzy()``). This kernel function may then be called within the syscall stub (``sys_xyzzy()``), the compatibility syscall stub (``compat_sys_xyzzy()``), and/or other kernel code.h](hSystem calls are, as stated above, interaction points between userspace and the kernel. Therefore, system call functions such as }(hjhhhNhNubjd)}(h``sys_xyzzy()``h]h sys_xyzzy()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh or }(hjhhhNhNubjd)}(h``compat_sys_xyzzy()``h]hcompat_sys_xyzzy()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubhXk should only be called from userspace via the syscall table, but not from elsewhere in the kernel. If the syscall functionality is useful to be used within the kernel, needs to be shared between an old and a new syscall, or needs to be shared between a syscall and its compatibility variant, it should be implemented by means of a “helper” function (such as }(hjhhhNhNubjd)}(h``ksys_xyzzy()``h]h ksys_xyzzy()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubhE). This kernel function may then be called within the syscall stub (}(hjhhhNhNubjd)}(h``sys_xyzzy()``h]h sys_xyzzy()}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh#), the compatibility syscall stub (}(hjhhhNhNubjd)}(h``compat_sys_xyzzy()``h]hcompat_sys_xyzzy()}(hjChhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh), and/or other kernel code.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMBhjhhubh)}(hX=At least on 64-bit x86, it will be a hard requirement from v4.17 onwards to not call system call functions in the kernel. It uses a different calling convention for system calls where ``struct pt_regs`` is decoded on-the-fly in a syscall wrapper which then hands processing over to the actual syscall function. This means that only those parameters which are actually needed for a specific syscall are passed on during syscall entry, instead of filling in six CPU registers with random user space content all the time (which may cause serious trouble down the call chain).h](hAt least on 64-bit x86, it will be a hard requirement from v4.17 onwards to not call system call functions in the kernel. It uses a different calling convention for system calls where }(hj[hhhNhNubjd)}(h``struct pt_regs``h]hstruct pt_regs}(hjchhhNhNubah}(h]h ]h"]h$]h&]uh1jchj[ubhXr is decoded on-the-fly in a syscall wrapper which then hands processing over to the actual syscall function. This means that only those parameters which are actually needed for a specific syscall are passed on during syscall entry, instead of filling in six CPU registers with random user space content all the time (which may cause serious trouble down the call chain).}(hj[hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMMhjhhubh)}(hMoreover, rules on how data may be accessed may differ between kernel data and user data. This is another reason why calling ``sys_xyzzy()`` is generally a bad idea.h](h~Moreover, rules on how data may be accessed may differ between kernel data and user data. This is another reason why calling }(hj{hhhNhNubjd)}(h``sys_xyzzy()``h]h sys_xyzzy()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchj{ubh is generally a bad idea.}(hj{hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMVhjhhubh)}(hExceptions to this rule are only allowed in architecture-specific overrides, architecture-specific compatibility wrappers, or other code in arch/.h]hExceptions to this rule are only allowed in architecture-specific overrides, architecture-specific compatibility wrappers, or other code in arch/.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMZhjhhubeh}(h]&do-not-call-system-calls-in-the-kernelah ]h"]&do not call system calls in the kernelah$]h&]uh1hhhhhhhhM@ubh)}(hhh](h)}(hReferences and Sourcesh]hReferences and Sources}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM_ubj2)}(hX - LWN article from Michael Kerrisk on use of flags argument in system calls: https://lwn.net/Articles/585415/ - LWN article from Michael Kerrisk on how to handle unknown flags in a system call: https://lwn.net/Articles/588444/ - LWN article from Jake Edge describing constraints on 64-bit system call arguments: https://lwn.net/Articles/311630/ - Pair of LWN articles from David Drysdale that describe the system call implementation paths in detail for v3.14: - https://lwn.net/Articles/604287/ - https://lwn.net/Articles/604515/ - Architecture-specific requirements for system calls are discussed in the :manpage:`syscall(2)` man-page: http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES - Collated emails from Linus Torvalds discussing the problems with ``ioctl()``: https://yarchive.net/comp/linux/ioctl.html - "How to not invent kernel interfaces", Arnd Bergmann, https://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf - LWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN: https://lwn.net/Articles/486306/ - Recommendation from Andrew Morton that all related information for a new system call should come in the same email thread: https://lore.kernel.org/r/20140724144747.3041b208832bbdf9fbce5d96@linux-foundation.org - Recommendation from Michael Kerrisk that a new system call should come with a man page: https://lore.kernel.org/r/CAKgNAkgMA39AfoSoA5Pe1r9N+ZzfYQNvNPvcRN7tOvRb8+v06Q@mail.gmail.com - Suggestion from Thomas Gleixner that x86 wire-up should be in a separate commit: https://lore.kernel.org/r/alpine.DEB.2.11.1411191249560.3909@nanos - Suggestion from Greg Kroah-Hartman that it's good for new system calls to come with a man-page & selftest: https://lore.kernel.org/r/20140320025530.GA25469@kroah.com - Discussion from Michael Kerrisk of new system call vs. :manpage:`prctl(2)` extension: https://lore.kernel.org/r/CAHO5Pa3F2MjfTtfNxa8LbnkeeU8=YJ+9tDqxZpw7Gz59E-4AUg@mail.gmail.com - Suggestion from Ingo Molnar that system calls that involve multiple arguments should encapsulate those arguments in a struct, which includes a size field for future extensibility: https://lore.kernel.org/r/20150730083831.GA22182@gmail.com - Numbering oddities arising from (re-)use of O_* numbering space flags: - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness check") - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc conflict") - commit bb458c644a59 ("Safer ABI for O_TMPFILE") - Discussion from Matthew Wilcox about restrictions on 64-bit arguments: https://lore.kernel.org/r/20081212152929.GM26095@parisc-linux.org - Recommendation from Greg Kroah-Hartman that unknown flags should be policed: https://lore.kernel.org/r/20140717193330.GB4703@kroah.com - Recommendation from Linus Torvalds that x32 system calls should prefer compatibility with 64-bit versions rather than 32-bit versions: https://lore.kernel.org/r/CA+55aFxfmwfB7jbbrXxa=K7VBYPfAvmu3XOkGrLbB1UFjX1+Ew@mail.gmail.com - Patch series revising system call table infrastructure to use scripts/syscall.tbl across multiple architectures: https://lore.kernel.org/lkml/20240704143611.2979589-1-arnd@kernel.orgh]j8)}(hhh](j=)}(hkLWN article from Michael Kerrisk on use of flags argument in system calls: https://lwn.net/Articles/585415/h]h)}(hkLWN article from Michael Kerrisk on use of flags argument in system calls: https://lwn.net/Articles/585415/h](hKLWN article from Michael Kerrisk on use of flags argument in system calls: }(hjhhhNhNubj)}(h https://lwn.net/Articles/585415/h]h https://lwn.net/Articles/585415/}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhhMahjubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hrLWN article from Michael Kerrisk on how to handle unknown flags in a system call: https://lwn.net/Articles/588444/h]h)}(hrLWN article from Michael Kerrisk on how to handle unknown flags in a system call: https://lwn.net/Articles/588444/h](hRLWN article from Michael Kerrisk on how to handle unknown flags in a system call: }(hjhhhNhNubj)}(h https://lwn.net/Articles/588444/h]h https://lwn.net/Articles/588444/}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhhMchjubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hsLWN article from Jake Edge describing constraints on 64-bit system call arguments: https://lwn.net/Articles/311630/h]h)}(hsLWN article from Jake Edge describing constraints on 64-bit system call arguments: https://lwn.net/Articles/311630/h](hSLWN article from Jake Edge describing constraints on 64-bit system call arguments: }(hjhhhNhNubj)}(h https://lwn.net/Articles/311630/h]h https://lwn.net/Articles/311630/}(hj#hhhNhNubah}(h]h ]h"]h$]h&]refurij%uh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhhMehjubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hPair of LWN articles from David Drysdale that describe the system call implementation paths in detail for v3.14: - https://lwn.net/Articles/604287/ - https://lwn.net/Articles/604515/ h](h)}(hpPair of LWN articles from David Drysdale that describe the system call implementation paths in detail for v3.14:h]hpPair of LWN articles from David Drysdale that describe the system call implementation paths in detail for v3.14:}(hjBhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMghj>ubj2)}(hF- https://lwn.net/Articles/604287/ - https://lwn.net/Articles/604515/ h]j8)}(hhh](j=)}(h https://lwn.net/Articles/604287/h]h)}(hjYh]j)}(hjYh]h https://lwn.net/Articles/604287/}(hj^hhhNhNubah}(h]h ]h"]h$]h&]refurijYuh1jhj[ubah}(h]h ]h"]h$]h&]uh1hhhhMjhjWubah}(h]h ]h"]h$]h&]uh1j<hjTubj=)}(h!https://lwn.net/Articles/604515/ h]h)}(h https://lwn.net/Articles/604515/h]j)}(hj~h]h https://lwn.net/Articles/604515/}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurij~uh1jhj|ubah}(h]h ]h"]h$]h&]uh1hhhhMkhjxubah}(h]h ]h"]h$]h&]uh1j<hjTubeh}(h]h ]h"]h$]h&]j j uh1j7hhhMjhjPubah}(h]h ]h"]h$]h&]uh1j1hhhMjhj>ubeh}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hArchitecture-specific requirements for system calls are discussed in the :manpage:`syscall(2)` man-page: http://man7.org/linux/man-pages/man2/syscall.2.html#NOTESh]h)}(hArchitecture-specific requirements for system calls are discussed in the :manpage:`syscall(2)` man-page: http://man7.org/linux/man-pages/man2/syscall.2.html#NOTESh](hIArchitecture-specific requirements for system calls are discussed in the }(hjhhhNhNubj)}(h:manpage:`syscall(2)`h]h syscall(2)}(hjhhhNhNubah}(h]h ]jah"]h$]h&]jjj syscall(2)jsyscalljjuh1jhjubh man-page: }(hjhhhNhNubj)}(h9http://man7.org/linux/man-pages/man2/syscall.2.html#NOTESh]h9http://man7.org/linux/man-pages/man2/syscall.2.html#NOTES}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhhMmhjubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hxCollated emails from Linus Torvalds discussing the problems with ``ioctl()``: https://yarchive.net/comp/linux/ioctl.htmlh]h)}(hxCollated emails from Linus Torvalds discussing the problems with ``ioctl()``: https://yarchive.net/comp/linux/ioctl.htmlh](hACollated emails from Linus Torvalds discussing the problems with }(hjhhhNhNubjd)}(h ``ioctl()``h]hioctl()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jchjubh: }(hjhhhNhNubj)}(h*https://yarchive.net/comp/linux/ioctl.htmlh]h*https://yarchive.net/comp/linux/ioctl.html}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhhMphjubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hu"How to not invent kernel interfaces", Arnd Bergmann, https://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdfh]h)}(hu"How to not invent kernel interfaces", Arnd Bergmann, https://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdfh](h:“How to not invent kernel interfaces”, Arnd Bergmann, }(hj$hhhNhNubj)}(h?https://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdfh]h?https://www.ukuug.org/events/linux2007/2007/papers/Bergmann.pdf}(hj,hhhNhNubah}(h]h ]h"]h$]h&]refurij.uh1jhj$ubeh}(h]h ]h"]h$]h&]uh1hhhhMrhj ubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hhLWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN: https://lwn.net/Articles/486306/h]h)}(hhLWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN: https://lwn.net/Articles/486306/h](hHLWN article from Michael Kerrisk on avoiding new uses of CAP_SYS_ADMIN: }(hjKhhhNhNubj)}(h https://lwn.net/Articles/486306/h]h https://lwn.net/Articles/486306/}(hjShhhNhNubah}(h]h ]h"]h$]h&]refurijUuh1jhjKubeh}(h]h ]h"]h$]h&]uh1hhhhMthjGubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hRecommendation from Andrew Morton that all related information for a new system call should come in the same email thread: https://lore.kernel.org/r/20140724144747.3041b208832bbdf9fbce5d96@linux-foundation.orgh]h)}(hRecommendation from Andrew Morton that all related information for a new system call should come in the same email thread: https://lore.kernel.org/r/20140724144747.3041b208832bbdf9fbce5d96@linux-foundation.orgh](h{Recommendation from Andrew Morton that all related information for a new system call should come in the same email thread: }(hjrhhhNhNubj)}(hVhttps://lore.kernel.org/r/20140724144747.3041b208832bbdf9fbce5d96@linux-foundation.orgh]hVhttps://lore.kernel.org/r/20140724144747.3041b208832bbdf9fbce5d96@linux-foundation.org}(hjzhhhNhNubah}(h]h ]h"]h$]h&]refurij|uh1jhjrubeh}(h]h ]h"]h$]h&]uh1hhhhMvhjnubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hRecommendation from Michael Kerrisk that a new system call should come with a man page: https://lore.kernel.org/r/CAKgNAkgMA39AfoSoA5Pe1r9N+ZzfYQNvNPvcRN7tOvRb8+v06Q@mail.gmail.comh]h)}(hRecommendation from Michael Kerrisk that a new system call should come with a man page: https://lore.kernel.org/r/CAKgNAkgMA39AfoSoA5Pe1r9N+ZzfYQNvNPvcRN7tOvRb8+v06Q@mail.gmail.comh](hXRecommendation from Michael Kerrisk that a new system call should come with a man page: }(hjhhhNhNubj)}(h\https://lore.kernel.org/r/CAKgNAkgMA39AfoSoA5Pe1r9N+ZzfYQNvNPvcRN7tOvRb8+v06Q@mail.gmail.comh]h\https://lore.kernel.org/r/CAKgNAkgMA39AfoSoA5Pe1r9N+ZzfYQNvNPvcRN7tOvRb8+v06Q@mail.gmail.com}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhhMyhjubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hSuggestion from Thomas Gleixner that x86 wire-up should be in a separate commit: https://lore.kernel.org/r/alpine.DEB.2.11.1411191249560.3909@nanosh]h)}(hSuggestion from Thomas Gleixner that x86 wire-up should be in a separate commit: https://lore.kernel.org/r/alpine.DEB.2.11.1411191249560.3909@nanosh](hQSuggestion from Thomas Gleixner that x86 wire-up should be in a separate commit: }(hjhhhNhNubj)}(hBhttps://lore.kernel.org/r/alpine.DEB.2.11.1411191249560.3909@nanosh]hBhttps://lore.kernel.org/r/alpine.DEB.2.11.1411191249560.3909@nanos}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhhM{hjubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hSuggestion from Greg Kroah-Hartman that it's good for new system calls to come with a man-page & selftest: https://lore.kernel.org/r/20140320025530.GA25469@kroah.comh]h)}(hSuggestion from Greg Kroah-Hartman that it's good for new system calls to come with a man-page & selftest: https://lore.kernel.org/r/20140320025530.GA25469@kroah.comh](hmSuggestion from Greg Kroah-Hartman that it’s good for new system calls to come with a man-page & selftest: }(hjhhhNhNubj)}(h:https://lore.kernel.org/r/20140320025530.GA25469@kroah.comh]h:https://lore.kernel.org/r/20140320025530.GA25469@kroah.com}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhhM}hjubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hDiscussion from Michael Kerrisk of new system call vs. :manpage:`prctl(2)` extension: https://lore.kernel.org/r/CAHO5Pa3F2MjfTtfNxa8LbnkeeU8=YJ+9tDqxZpw7Gz59E-4AUg@mail.gmail.comh]h)}(hDiscussion from Michael Kerrisk of new system call vs. :manpage:`prctl(2)` extension: https://lore.kernel.org/r/CAHO5Pa3F2MjfTtfNxa8LbnkeeU8=YJ+9tDqxZpw7Gz59E-4AUg@mail.gmail.comh](h7Discussion from Michael Kerrisk of new system call vs. }(hjhhhNhNubj)}(h:manpage:`prctl(2)`h]hprctl(2)}(hjhhhNhNubah}(h]h ]jah"]h$]h&]jjjprctl(2)jprctljjuh1jhjubh extension: }(hjhhhNhNubj)}(h\https://lore.kernel.org/r/CAHO5Pa3F2MjfTtfNxa8LbnkeeU8=YJ+9tDqxZpw7Gz59E-4AUg@mail.gmail.comh]h\https://lore.kernel.org/r/CAHO5Pa3F2MjfTtfNxa8LbnkeeU8=YJ+9tDqxZpw7Gz59E-4AUg@mail.gmail.com}(hj*hhhNhNubah}(h]h ]h"]h$]h&]refurij,uh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hSuggestion from Ingo Molnar that system calls that involve multiple arguments should encapsulate those arguments in a struct, which includes a size field for future extensibility: https://lore.kernel.org/r/20150730083831.GA22182@gmail.comh]h)}(hSuggestion from Ingo Molnar that system calls that involve multiple arguments should encapsulate those arguments in a struct, which includes a size field for future extensibility: https://lore.kernel.org/r/20150730083831.GA22182@gmail.comh](hSuggestion from Ingo Molnar that system calls that involve multiple arguments should encapsulate those arguments in a struct, which includes a size field for future extensibility: }(hjIhhhNhNubj)}(h:https://lore.kernel.org/r/20150730083831.GA22182@gmail.comh]h:https://lore.kernel.org/r/20150730083831.GA22182@gmail.com}(hjQhhhNhNubah}(h]h ]h"]h$]h&]refurijSuh1jhjIubeh}(h]h ]h"]h$]h&]uh1hhhhMhjEubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hX(Numbering oddities arising from (re-)use of O_* numbering space flags: - commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness check") - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc conflict") - commit bb458c644a59 ("Safer ABI for O_TMPFILE") h](h)}(hFNumbering oddities arising from (re-)use of O_* numbering space flags:h]hFNumbering oddities arising from (re-)use of O_* numbering space flags:}(hjphhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjlubj2)}(h- commit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness check") - commit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc conflict") - commit bb458c644a59 ("Safer ABI for O_TMPFILE") h]j8)}(hhh](j=)}(hPcommit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness check")h]h)}(hPcommit 75069f2b5bfb ("vfs: renumber FMODE_NONOTIFY and add to uniqueness check")h]hTcommit 75069f2b5bfb (“vfs: renumber FMODE_NONOTIFY and add to uniqueness check”)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hOcommit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc conflict")h]h)}(hOcommit 12ed2e36c98a ("fanotify: FMODE_NONOTIFY and __O_SYNC in sparc conflict")h]hScommit 12ed2e36c98a (“fanotify: FMODE_NONOTIFY and __O_SYNC in sparc conflict”)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(h0commit bb458c644a59 ("Safer ABI for O_TMPFILE") h]h)}(h/commit bb458c644a59 ("Safer ABI for O_TMPFILE")h]h3commit bb458c644a59 (“Safer ABI for O_TMPFILE”)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j<hjubeh}(h]h ]h"]h$]h&]j j uh1j7hhhMhj~ubah}(h]h ]h"]h$]h&]uh1j1hhhMhjlubeh}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hDiscussion from Matthew Wilcox about restrictions on 64-bit arguments: https://lore.kernel.org/r/20081212152929.GM26095@parisc-linux.orgh]h)}(hDiscussion from Matthew Wilcox about restrictions on 64-bit arguments: https://lore.kernel.org/r/20081212152929.GM26095@parisc-linux.orgh](hGDiscussion from Matthew Wilcox about restrictions on 64-bit arguments: }(hjhhhNhNubj)}(hAhttps://lore.kernel.org/r/20081212152929.GM26095@parisc-linux.orgh]hAhttps://lore.kernel.org/r/20081212152929.GM26095@parisc-linux.org}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhjubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hRecommendation from Greg Kroah-Hartman that unknown flags should be policed: https://lore.kernel.org/r/20140717193330.GB4703@kroah.comh]h)}(hRecommendation from Greg Kroah-Hartman that unknown flags should be policed: https://lore.kernel.org/r/20140717193330.GB4703@kroah.comh](hMRecommendation from Greg Kroah-Hartman that unknown flags should be policed: }(hj hhhNhNubj)}(h9https://lore.kernel.org/r/20140717193330.GB4703@kroah.comh]h9https://lore.kernel.org/r/20140717193330.GB4703@kroah.com}(hjhhhNhNubah}(h]h ]h"]h$]h&]refurijuh1jhj ubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hRecommendation from Linus Torvalds that x32 system calls should prefer compatibility with 64-bit versions rather than 32-bit versions: https://lore.kernel.org/r/CA+55aFxfmwfB7jbbrXxa=K7VBYPfAvmu3XOkGrLbB1UFjX1+Ew@mail.gmail.comh]h)}(hRecommendation from Linus Torvalds that x32 system calls should prefer compatibility with 64-bit versions rather than 32-bit versions: https://lore.kernel.org/r/CA+55aFxfmwfB7jbbrXxa=K7VBYPfAvmu3XOkGrLbB1UFjX1+Ew@mail.gmail.comh](hRecommendation from Linus Torvalds that x32 system calls should prefer compatibility with 64-bit versions rather than 32-bit versions: }(hj1hhhNhNubj)}(h\https://lore.kernel.org/r/CA+55aFxfmwfB7jbbrXxa=K7VBYPfAvmu3XOkGrLbB1UFjX1+Ew@mail.gmail.comh]h\https://lore.kernel.org/r/CA+55aFxfmwfB7jbbrXxa=K7VBYPfAvmu3XOkGrLbB1UFjX1+Ew@mail.gmail.com}(hj9hhhNhNubah}(h]h ]h"]h$]h&]refurij;uh1jhj1ubeh}(h]h ]h"]h$]h&]uh1hhhhMhj-ubah}(h]h ]h"]h$]h&]uh1j<hjubj=)}(hPatch series revising system call table infrastructure to use scripts/syscall.tbl across multiple architectures: https://lore.kernel.org/lkml/20240704143611.2979589-1-arnd@kernel.orgh]h)}(hPatch series revising system call table infrastructure to use scripts/syscall.tbl across multiple architectures: https://lore.kernel.org/lkml/20240704143611.2979589-1-arnd@kernel.orgh](hqPatch series revising system call table infrastructure to use scripts/syscall.tbl across multiple architectures: }(hjXhhhNhNubj)}(hEhttps://lore.kernel.org/lkml/20240704143611.2979589-1-arnd@kernel.orgh]hEhttps://lore.kernel.org/lkml/20240704143611.2979589-1-arnd@kernel.org}(hj`hhhNhNubah}(h]h ]h"]h$]h&]refurijbuh1jhjXubeh}(h]h ]h"]h$]h&]uh1hhhhMhjTubah}(h]h ]h"]h$]h&]uh1j<hjubeh}(h]h ]h"]h$]h&]j j uh1j7hhhMahjubah}(h]h ]h"]h$]h&]uh1j1hhhMahjhhubeh}(h]references-and-sourcesah ]h"]references and sourcesah$]h&]uh1hhhhhhhhM_ubeh}(h](adding-a-new-system-callheh ]h"](adding a new system call addsyscallseh$]h&]uh1hhhhhhhhKjq }jhs js }hhsubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehÌ _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}(h]haj ]j aj@]j6aunameids}(jhjjj jjjj jjjjz jw jl j since 6.11Nj j jjjj@jjjDjAj)j&jjjjjjjjjju nametypes}(jjj jj jjz jl jj jjjjDj)jjjjjuh}(hhjhjjjj jjjj#jw jj j ji j j j} jj jjj@jAjjAjAjj&jGjj,jjjjjjjju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}jKsRparse_messages]hsystem_message)}(hhh]h)}(h-Duplicate implicit target name: "since 6.11".h]h1Duplicate implicit target name: “since 6.11”.}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj%ubah}(h]h ]h"]h$]h&]jalevelKtypeINFOsourcehÌlineMuh1j#hjhhhhhMubatransform_messages](j$)}(hhh]h)}(hhh]h1Hyperlink target "addsyscalls" is not referenced.}hjFsbah}(h]h ]h"]h$]h&]uh1hhjCubah}(h]h ]h"]h$]h&]levelKtypej>sourcehÌlineKuh1j#ubj$)}(hhh]h)}(hhh]h:Hyperlink target "syscall-generic-6-11" is not referenced.}hj`sbah}(h]h ]h"]h$]h&]uh1hhj]ubah}(h]h ]h"]h$]h&]levelKtypej>sourcehÌlineKuh1j#ubj$)}(hhh]h)}(hhh]h2Hyperlink target "compat-arm64" is not referenced.}hjzsbah}(h]h ]h"]h$]h&]uh1hhjwubah}(h]h ]h"]h$]h&]levelKtypej>sourcehÌlineMuh1j#ube transformerN include_log] decorationNhhub.