libsys.adoc

=== libsys

Contact: Brooks Davis <[email protected]>

The libsys project removes direct system calls from [.filename]#libc.so# and [.filename]#libpthread.so# (aka [.filename]#libthr.so#) to a separate [.filename]#libsys.so#.
This will:

 * Isolate language runtimes from the details of system call implementations.
 * Better support logging and replay frameworks for systems calls.
 * Support elimination of the ability to make system calls outside trusted code in the runtime linker and `libsys`.

This work was initially inspired by a compartmentalization prototype in CheriBSD in 2016.
Ali Mashtizadeh and Tal Garfinkel picked that work up and attempted to upstream it (link:https://reviews.freebsd.org/D14609[D14609]).
Unfortunately we could not figure out how to review and land the massive reorganization required through a phabricator review so it languished.
Last year the CHERI project once again found a need for system call separation in a new library-based compartmentalization framework in CheriBSD so I rebuilt the patch from scratch, committing dozens of `libc` cleanups along the way.
I landed the first batch of changes on February 5th.
Since then I have made a number of refinements to the way we link `libsys` as well as which symbols are provided in which library.

Thanks to mailto:[email protected][Konstantin Belousov] for many rounds of review and feedback as well as runtime linker fixes.
Thanks to mailto:[email protected][Mark Johnston] for runtime linker debugging and mailto:[email protected][Dimitry Andric] for sanitizer fixes.
Thanks also to everyone who reported bugs and helped debug issues.

==== Known issues (as of the end of the reporting period)

 * The `libsys` ABI is not yet considered stable (it is safe to assume `__sys_foo()` will be supported so language runtimes can use it now).
 * Programs using the address sanitizer must be linked with `-lsys` (resolved in base at publication time).

==== TODO

 * Add a [.filename]#libsys.h#.  (See link:https://reviews.freebsd.org/D44387[D44387] and other reviews in the stack.)
 * Update man:intro[2] for `libsys`.
 * Finalize the ABI.
   I am likely to reduce the set of `_` (underscore) prefixed symbols we expose.
 * MFC the existence of `libsys`?
   It is not clear this is practical, but it might be possible to MFC something useful for language runtimes.

==== Help wanted

 * Port language runtimes that do not use `libc` to use `libsys` for system calls rather than rolling their own interfaces.
 * Explore limitations on where system calls can be made similar to OpenBSD's link:https://man.openbsd.org/OpenBSD-7.3/msyscall[msyscall(2)] (now obsolete) and link:https://man.openbsd.org/pinsyscalls[pinsyscalls(2)] (not an obvious match to our `libsys`).

Sponsor: AFRL, DARPA