1# Linux Syscall Support (LSS) 2 3Every so often, projects need to directly embed Linux system calls instead of 4calling the implementations in the system runtime library. 5 6This project provides a header file that can be included into your application 7whenever you need to make direct system calls. 8 9The goal is to provide an API that generally mirrors the standard C library 10while still making direct syscalls. We try to hide some of the differences 11between arches when reasonably feasible. e.g. Newer architectures no longer 12provide an `open` syscall, but do provide `openat`. We will still expose a 13`sys_open` helper by default that calls into `openat` instead. 14 15We explicitly do not expose the raw syscall ABI including all of its historical 16warts to the user. We want people to be able to easily make a syscall, not have 17to worry that on some arches size args are swapped or they are shifted. 18 19Please be sure to review the Caveats section below however. 20 21## How to include linux\_syscall\_support.h in your project 22 23You can either copy the file into your project, or preferably, you can set up 24Git submodules to automatically pull from our source repository. 25 26## Supported targets 27 28The following architectures/ABIs have been tested (at some point) and should 29generally work. If you don't see your combo listed here, please double check 30the header itself as this list might be out of date. 31 32* x86 32-bit (i.e. i386, i486, i586, i686, Intel, AMD, etc...) 33* [x86_64 64-bit](https://en.wikipedia.org/wiki/X86-64) (i.e. x86-64, amd64, etc...) 34* [x32 32-bit](https://sites.google.com/site/x32abi/) 35* [ARM 32-bit](https://en.wikipedia.org/wiki/ARM_architecture) OABI 36* [ARM 32-bit](https://en.wikipedia.org/wiki/ARM_architecture) EABI (i.e. armv6, armv7, etc...) 37* AARCH64 64-bit (i.e. arm64, armv8, etc...) 38* PowerPC 32-bit (i.e. ppc, ppc32, etc...) 39* MIPS 32-bit o32 ABI 40* MIPS 32-bit n32 ABI 41* MIPS 64-bit n64 ABI 42* LOONGARCH 64-bit ABI 43 44## API 45 46By default, you can just add a `sys_` prefix to any function you want to call. 47So if you want to call `open(...)`, use `sys_open(...)` instead. 48 49### Knobs 50 51The linux\_syscall\_support.h header provides many knobs for you to control 52the exported API. These are all documented in the top of the header in a big 53comment block, so refer to that instead. 54 55## Caveats 56 57### ABI differences 58 59Some functions that the standard C library exposes use a different ABI than 60what the Linux kernel uses. Care must be taken when making syscalls directly 61that you use the right structure and flags. e.g. Most C libraries define a 62`struct stat` (commonly in `sys/stat.h` or `bits/stat.h`) that is different 63from the `struct stat` the kernel uses (commonly in `asm/stat.h`). If you use 64the wrong structure layout, then you can see errors like memory corruption or 65weird/shifted values. If you plan on making syscalls directly, you should 66focus on headers that are available under the `linux/` and `asm/` namespaces. 67 68Note: LSS provides structs for most of these cases. For `sys_stat()`, it 69provides `struct kernel_stat` for you to use. 70 71### Transparent backwards compatibility with older kernels 72 73While some C libraries (notably, glibc) take care to fallback to older syscalls 74when running on older kernels, there is no such support in LSS. If you plan on 75trying to run on older kernels, you will need to handle errors yourself (e.g. 76`ENOSYS` when using a too new syscall). 77 78Remember that this can happen with new flag bits too. e.g. The `O_CLOEXEC` 79flag was added to many syscalls, but if you try to run use it on older kernels, 80it will fail with `EINVAL`. In that case, you must handle the fallback logic 81yourself. 82 83### Variable arguments (varargs) 84 85We do not support vararg type functions. e.g. While the standard `open()` 86function can accept 2 or 3 arguments (with the mode field being optional), 87the `sys_open()` function always requires 3 arguments. 88 89## Bug reports & feature requests 90 91If you wish to report a problem or request a feature, please file them in our 92[bug tracker](https://bugs.chromium.org/p/linux-syscall-support/issues/). 93 94Please do not post patches to the tracker. Instead, see below for how to send 95patches to us directly. 96 97While we welcome feature requests, please keep in mind that it is unlikely that 98anyone will find time to implement them for you. Sending patches is strongly 99preferred and will often move things much faster. 100 101## Projects that use LSS 102 103* [Chromium](https://www.chromium.org/) 104* [Breakpad](https://chromium.googlesource.com/breakpad/breakpad) 105* [Native Client](https://developer.chrome.com/native-client), in nacl\_bootstrap.c 106 107## How to get an LSS change committed 108 109### Review 110 111You get your change reviewed, you can upload it to 112[Gerrit](https://chromium-review.googlesource.com/q/project:linux-syscall-support+status:open) 113using `git cl upload` from 114[Chromium's depot-tools](https://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html). 115 116### Testing 117 118Tests are found in the [tests/](./tests/) subdirectory. It does not (yet) offer 119100% coverage, but should grow over time. 120 121New commits that update/change/add syscall wrappers should include tests for 122them too. Consult the [test documentation](./tests/README.md) for more details. 123 124To run, just run `make` inside the tests directory. It will compile & execute 125the tests locally. 126 127There is some limited cross-compile coverage available if you run `make cross`. 128It only compiles things (does not execute at all). 129 130### Rolling into Chromium 131 132If you commit a change to LSS, please also commit a Chromium change to update 133`lss_revision` in 134[Chromium's DEPS](https://chromium.googlesource.com/chromium/src/+/HEAD/DEPS) 135file. 136 137This ensures that the LSS change gets tested, so that people who commit later 138LSS changes don't run into problems with updating `lss_revision`. 139