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 3db80c999debbad ("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: Jesung Yang <y.j3ms.n@gmail.com>
Link: https://lore.kernel.org/lkml/20240704143611.2979589-1-arnd@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250506194841.1567737-1-y.j3ms.n@gmail.com>

authored by

Jesung Yang and committed by

Jonathan Corbet 11 months ago a556bd88 54538c24

+84

1 changed file

expand all

Documentation

process

adding-syscalls.rst

+84

Documentation/process/adding-syscalls.rst

··· 248 248 - fallback stub in ``kernel/sys_ni.c`` 249 249 250 250 251 + .. _syscall_generic_6_11: 252 + 253 + Since 6.11 254 + ~~~~~~~~~~ 255 + 256 + Starting with kernel version 6.11, general system call implementation for the 257 + following architectures no longer requires modifications to 258 + ``include/uapi/asm-generic/unistd.h``: 259 + 260 + - arc 261 + - arm64 262 + - csky 263 + - hexagon 264 + - loongarch 265 + - nios2 266 + - openrisc 267 + - riscv 268 + 269 + Instead, you need to update ``scripts/syscall.tbl`` and, if applicable, adjust 270 + ``arch/*/kernel/Makefile.syscalls``. 271 + 272 + As ``scripts/syscall.tbl`` serves as a common syscall table across multiple 273 + architectures, a new entry is required in this table:: 274 + 275 + 468 common xyzzy sys_xyzzy 276 + 277 + Note that adding an entry to ``scripts/syscall.tbl`` with the "common" ABI 278 + also affects all architectures that share this table. For more limited or 279 + architecture-specific changes, consider using an architecture-specific ABI or 280 + defining a new one. 281 + 282 + If a new ABI, say ``xyz``, is introduced, the corresponding updates should be 283 + made to ``arch/*/kernel/Makefile.syscalls`` as well:: 284 + 285 + syscall_abis_{32,64} += xyz (...) 286 + 287 + To summarize, you need a commit that includes: 288 + 289 + - ``CONFIG`` option for the new function, normally in ``init/Kconfig`` 290 + - ``SYSCALL_DEFINEn(xyzzy, ...)`` for the entry point 291 + - corresponding prototype in ``include/linux/syscalls.h`` 292 + - new entry in ``scripts/syscall.tbl`` 293 + - (if needed) Makefile updates in ``arch/*/kernel/Makefile.syscalls`` 294 + - fallback stub in ``kernel/sys_ni.c`` 295 + 296 + 251 297 x86 System Call Implementation 252 298 ------------------------------ 253 299 ··· 397 351 - (if needed) 32-bit mapping struct in ``include/linux/compat.h`` 398 352 - instance of ``__SC_COMP`` not ``__SYSCALL`` in 399 353 ``include/uapi/asm-generic/unistd.h`` 354 + 355 + 356 + Since 6.11 357 + ~~~~~~~~~~ 358 + 359 + This applies to all the architectures listed in :ref:`Since 6.11<syscall_generic_6_11>` 360 + under "Generic System Call Implementation", except arm64. See 361 + :ref:`Compatibility System Calls (arm64)<compat_arm64>` for more information. 362 + 363 + You need to extend the entry in ``scripts/syscall.tbl`` with an extra column 364 + to indicate that a 32-bit userspace program running on a 64-bit kernel should 365 + hit the compat entry point:: 366 + 367 + 468 common xyzzy sys_xyzzy compat_sys_xyzzy 368 + 369 + To summarize, you need: 370 + 371 + - ``COMPAT_SYSCALL_DEFINEn(xyzzy, ...)`` for the compat entry point 372 + - corresponding prototype in ``include/linux/compat.h`` 373 + - modification of the entry in ``scripts/syscall.tbl`` to include an extra 374 + "compat" column 375 + - (if needed) 32-bit mapping struct in ``include/linux/compat.h`` 376 + 377 + 378 + .. _compat_arm64: 379 + 380 + Compatibility System Calls (arm64) 381 + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 382 + 383 + On arm64, there is a dedicated syscall table for compatibility system calls 384 + targeting 32-bit (AArch32) userspace: ``arch/arm64/tools/syscall_32.tbl``. 385 + You need to add an additional line to this table specifying the compat 386 + entry point:: 387 + 388 + 468 common xyzzy sys_xyzzy compat_sys_xyzzy 400 389 401 390 402 391 Compatibility System Calls (x86) ··· 656 575 - Recommendation from Linus Torvalds that x32 system calls should prefer 657 576 compatibility with 64-bit versions rather than 32-bit versions: 658 577 https://lore.kernel.org/r/CA+55aFxfmwfB7jbbrXxa=K7VBYPfAvmu3XOkGrLbB1UFjX1+Ew@mail.gmail.com 578 + - Patch series revising system call table infrastructure to use 579 + scripts/syscall.tbl across multiple architectures: 580 + https://lore.kernel.org/lkml/20240704143611.2979589-1-arnd@kernel.org

Configure Feed

Configure Feed