Commit a556bd88 authored by Jesung Yang's avatar Jesung Yang Committed by Jonathan Corbet
Browse files

docs: align with scripts/syscall.tbl migration 



Update the documentation to reflect the migration of the following
architectures to the centralized syscall table format:

  arc, arm64, csky, hexagon, loongarch, nios2, openrisc, riscv

As of commit 3db80c99 ("riscv: convert to generic syscall table"),
these architectures no longer rely on include/uapi/asm-generic/unistd.h.
Instead, syscall table headers (syscall_table_{32,64}.h) are generated by
scripts/syscalltbl.sh based on entries in scripts/syscall.tbl, with ABIs
specified in arch/*/kernel/Makefile.syscalls.

For the convenience of developers working with older kernel versions, the
original documentation is fully retained, with new sections added to
cover the scripts/syscall.tbl approach.

Verified with `make htmldocs`.

Signed-off-by: default avatarJesung Yang <y.j3ms.n@gmail.com>
Link: https://lore.kernel.org/lkml/20240704143611.2979589-1-arnd@kernel.org


Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
Message-ID: <20250506194841.1567737-1-y.j3ms.n@gmail.com>
parent 54538c24

Documentation/process/adding-syscalls.rst

+84 −0
Original line number Diff line number Diff line
@@ -248,6 +248,52 @@ To summarize, you need a commit that includes: 
 - fallback stub in ``kernel/sys_ni.c``





.. _syscall_generic_6_11:



Since 6.11

~~~~~~~~~~



Starting with kernel version 6.11, general system call implementation for the

following architectures no longer requires modifications to

``include/uapi/asm-generic/unistd.h``:



 - arc

 - arm64

 - csky

 - hexagon

 - loongarch

 - nios2

 - openrisc

 - riscv



Instead, you need to update ``scripts/syscall.tbl`` and, if applicable, adjust

``arch/*/kernel/Makefile.syscalls``.



As ``scripts/syscall.tbl`` serves as a common syscall table across multiple

architectures, a new entry is required in this table::



    468   common   xyzzy     sys_xyzzy



Note 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.



If a new ABI, say ``xyz``, is introduced, the corresponding updates should be

made to ``arch/*/kernel/Makefile.syscalls`` as well::



    syscall_abis_{32,64} += xyz (...)



To summarize, you need a commit that includes:



 - ``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``





x86 System Call Implementation

------------------------------
@@ -353,6 +399,41 @@ To summarize, you need: 
   ``include/uapi/asm-generic/unistd.h``





Since 6.11

~~~~~~~~~~



This applies to all the architectures listed in :ref:`Since 6.11<syscall_generic_6_11>`

under "Generic System Call Implementation", except arm64. See

:ref:`Compatibility System Calls (arm64)<compat_arm64>` for more information.



You 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::



    468   common     xyzzy     sys_xyzzy    compat_sys_xyzzy



To summarize, you need:



 - ``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``





.. _compat_arm64:



Compatibility System Calls (arm64)

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



On 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::



    468   common     xyzzy     sys_xyzzy    compat_sys_xyzzy





Compatibility System Calls (x86)

--------------------------------
@@ -575,3 +656,6 @@ References and Sources 
 - 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.org