Files
llvm-tms34010/libc/docs/dev/syscall_wrapper_refactor.rst
T
Pavel Labath aa1081f2c4 [libc] Introduce a typed syscall wrapper and use it in mmap (#197459)
Linux reserves a range of values (everything above -4096u, aka
MAX_ERRNO) as an error value, so the check can be performed without
knowing the details of the specific syscall. libc functions where these
values would be a valid result (e.g. PTRACE_PEEKDATA) are implemented
differently at the kernel level (e.g. returning the result through a
pointer argument). The only exception are a handful of syscalls (getpid,
getuid, ...) which can never fail, and where this could be an actual
user/group ID (particularly on 32-bit systems).

Specifically, for mmap, this lets us remove the is_valid_mmap helper and
SYS_mmap2 ifdefs in various places.

More generally, this can simplify many syscall wrappers as often the
only thing they are doing is converting the return value into an
ErrorOr.
2026-05-18 08:09:25 +02:00

72 lines
2.6 KiB
ReStructuredText

.. _syscall_wrapper_refactor:
==============================
Syscall Wrapper Refactoring
==============================
Purpose
=======
LLVM-libc is transitioning to a centralized system for Linux syscalls. The goal
is to move all direct ``syscall_impl`` calls into a dedicated directory:
``src/__support/OSUtil/linux/syscall_wrappers/``.
This refactor provides several benefits:
* **Reusability**: Allows multiple entrypoints to share a single syscall
implementation without public APIs depending on other public APIs.
* **Type Safety**: Using ``ErrorOr<T>`` ensures that error conditions are
handled explicitly.
* **Consistency**: Standardizes the conversion of syscall return values into
errno-compatible objects.
* **Maintainability**: Centralizes platform-specific syscall logic, making it
easier to audit and update.
The Pattern
===========
Each syscall should have its own header-only library in the ``syscall_wrappers``
directory. The wrapper function should return an ``ErrorOr<T>``. Wrappers live
in the ``linux_syscalls`` namespace to make call sites self-documenting and to
clearly identify any leakage into OS-generic code.
Example Wrapper (``src/__support/OSUtil/linux/syscall_wrappers/read.h``):
--------------------------------------------------------------------------
.. code-block:: c++
#include "hdr/types/ssize_t.h"
#include "src/__support/OSUtil/linux/syscall.h" // For syscall_checked
#include "src/__support/common.h"
#include "src/__support/error_or.h"
#include "src/__support/macros/config.h"
#include <sys/syscall.h> // For syscall numbers
namespace LIBC_NAMESPACE_DECL {
namespace linux_syscalls {
LIBC_INLINE ErrorOr<ssize_t> read(int fd, void *buf, size_t count) {
return syscall_checked<ssize_t>(SYS_read, fd, buf, count);
}
} // namespace linux_syscalls
} // namespace LIBC_NAMESPACE_DECL
How to Migrate
==============
1. **Cleanup Existing Implementation**: If the syscall was previously
implemented in ``OSUtil/linux/fcntl.cpp`` (or similar), remove the old
implementation to replace it with the new wrapper.
2. **Create the Wrapper**: Add a new header file in
``src/__support/OSUtil/linux/syscall_wrappers/``.
3. **Update CMake**: Add a ``add_header_library`` target for the new wrapper in
``src/__support/OSUtil/linux/syscall_wrappers/CMakeLists.txt``.
4. **Refactor Entrypoints**:
* Include the new wrapper header (e.g., ``read.h``).
* Replace direct ``syscall_impl`` calls with
``linux_syscalls::<function_name>``.
* Update the entrypoint's ``DEPENDS`` in ``CMakeLists.txt`` to include the
new wrapper target.