|
| 1 | +# WASI POSIX shim headers |
| 2 | + |
| 3 | +This directory contains a set of header wrappers that augment the WASI sysroot |
| 4 | +with POSIX declarations and inline stub implementations required by the |
| 5 | +CoreCLR PAL and adjacent components (minipal, debug, hosts). |
| 6 | + |
| 7 | +## Why this exists |
| 8 | + |
| 9 | +Unlike Linux, macOS, FreeBSD, OpenBSD, Android, or Haiku, the WASI sysroot |
| 10 | +is missing entire POSIX subsystems: |
| 11 | + |
| 12 | +| Subsystem | Status in WASI | |
| 13 | +|-----------|---------------| |
| 14 | +| Signals (`<signal.h>`, `sigaction`, `siginfo_t`, `sigaltstack`) | Most declarations hidden behind `__wasilibc_unmodified_upstream` | |
| 15 | +| `<ucontext.h>` | Not provided | |
| 16 | +| `<pthread.h>` | Partial — `pthread_setschedparam`, `pthread_getschedparam`, `pthread_exit` declarations missing | |
| 17 | +| `<sys/wait.h>` | Not provided | |
| 18 | +| `<sys/vfs.h>` (statfs) | Not provided | |
| 19 | +| `<sys/resource.h>` (rusage) | Partial | |
| 20 | +| `<dlfcn.h>` (dynamic loading) | Not provided | |
| 21 | +| `<link.h>` (link map) | Not provided | |
| 22 | +| `<pwd.h>` (user database) | Not provided | |
| 23 | + |
| 24 | +The PAL and adjacent code consume these headers from dozens of translation |
| 25 | +units. Two patterns were considered: |
| 26 | + |
| 27 | +### Alternative 1 — `HAVE_*` configure checks (the dominant PAL pattern) |
| 28 | + |
| 29 | +Existing platforms (Haiku, FreeBSD, OpenBSD, Apple) handle missing pieces by: |
| 30 | + |
| 31 | +1. Probing for the missing symbol in `pal/src/configure.cmake` with |
| 32 | + `check_include_files` / `check_function_exists`. |
| 33 | +2. Wrapping each call site in `#if HAVE_<NAME>`. |
| 34 | +3. Adding inline stubs to the shared `.cpp` file behind `#ifdef <PLATFORM>`. |
| 35 | + |
| 36 | +This works well when the gap is small (e.g., Haiku is missing a handful of |
| 37 | +symbols). It scales poorly for WASI because the gap spans *most of POSIX* |
| 38 | +across *many* PAL files. Applying it here would produce hundreds of |
| 39 | +`#if HAVE_*` blocks scattered across `pal/src/{thread,exception,signal, |
| 40 | +synchmgr,init,debug,loader,map,misc}/`. |
| 41 | + |
| 42 | +### Alternative 2 — Sysroot shim headers (the approach taken) |
| 43 | + |
| 44 | +A single directory of `#include_next` wrappers layers the missing |
| 45 | +declarations and link-time-stubbed inline functions on top of the WASI |
| 46 | +sysroot. Each shim is small (10–100 lines) and lives next to its peers, |
| 47 | +making the platform delta inspectable in one place. |
| 48 | + |
| 49 | +The shim approach is similar to how Apple's `sys/sysctl.h` or Linux's |
| 50 | +`linux/elf.h` are sometimes wrapped by build systems that need to add |
| 51 | +missing typedefs. |
| 52 | + |
| 53 | +## How the shims are wired into the build |
| 54 | + |
| 55 | +`src/coreclr/CMakeLists.txt` adds the shim directory via |
| 56 | + |
| 57 | + include_directories(BEFORE SYSTEM ...pal/src/include/pal/wasi) |
| 58 | + |
| 59 | +inside the `if(CLR_CMAKE_TARGET_WASI)` block. The `BEFORE SYSTEM` placement |
| 60 | +ensures the wrapper resolves before the WASI sysroot's own `<signal.h>`, |
| 61 | +allowing each wrapper to do `#include_next <signal.h>` to chain to the |
| 62 | +underlying header and then add missing declarations on top. |
| 63 | + |
| 64 | +The scope is intentionally the entire CoreCLR build, not just PAL. |
| 65 | +`minipal/Unix/doublemapping.cpp` and `debug/dbgutil/` also include |
| 66 | +`<link.h>`, `<dlfcn.h>`, and `<sys/resource.h>`. Limiting the scope to PAL |
| 67 | +would require either narrowing the consumer set (large refactor) or |
| 68 | +duplicating the include-directory glue in every subdirectory that needs it. |
| 69 | + |
| 70 | +## Link-time stubs |
| 71 | + |
| 72 | +Header declarations alone are not enough — when the PAL references |
| 73 | +`pthread_setschedparam` (declared in the shim) the linker still needs a |
| 74 | +definition. Trivial stubs (return -1, no-op, etc.) live in |
| 75 | +`pal/src/arch/wasm/stubs.cpp`. Heavier shims like the |
| 76 | +`posix_memalign`-backed arena allocator that replaces `mmap` for anonymous |
| 77 | +mappings live next to them in `mmap-wasi.c`. |
| 78 | + |
| 79 | +## When to remove a shim |
| 80 | + |
| 81 | +A shim should be removed (and the symbol absorbed back into the shared PAL) |
| 82 | +when one of the following becomes true: |
| 83 | + |
| 84 | +1. The upstream WASI sysroot starts providing the missing declaration. |
| 85 | + Track [WebAssembly/wasi-libc](https://github.com/WebAssembly/wasi-libc) |
| 86 | + for additions. |
| 87 | +2. The number of call sites in CoreCLR shrinks to a handful, at which point |
| 88 | + `HAVE_*` configure checks become cheaper than a wrapper header. |
| 89 | +3. The symbol becomes completely unused in the WASI build, in which case |
| 90 | + the shim can be deleted outright. |
0 commit comments