From 22bd490272df4b743297cd74ea6167955809bfba Mon Sep 17 00:00:00 2001 From: Ariadne Conill Date: Mon, 7 Dec 2020 14:39:07 -0700 Subject: [PATCH] libucontext: expand README --- README.md | 41 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 39 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 1512b03..0f865a2 100644 --- a/README.md +++ b/README.md @@ -10,10 +10,11 @@ Since version 0.13, for some architectures, you can deploy to bare metal using n `FREESTANDING=yes` make option. Systems which use a syscall cannot work this way. The table below shows which architecture ports have been adapted to build with `FREESTANDING=yes`. +Adding support for new architectures is easy, but you need to know assembly language for the +target to do it. -## supported architectures -Adding support for new architectures is easy, but you need to know assembly language to do it. +## supported features | Architecture | Works on musl | Syscall | Supports FREESTANDING | |--------------|---------------|---------|-----------------------| @@ -40,3 +41,39 @@ $ make ARCH=x86_64 $ make ARCH=x86_64 check $ make ARCH=x86_64 DESTDIR=out install ``` + +There are a few options: + +* `ARCH`: The architecture libucontext is being built for. Must be set to one of the architectures + listed in the feature support table. If unset, the build system will attempt to guess based on what + architecture the host is running. Setting this option explicitly is highly recommended. + +* `FREESTANDING`: If this is set to `yes`, the system ucontext.h headers will not be used. Instead, + the headers in `arch/${ARCH}/freestanding` will be used for definitions where appropriate. + Default is `no`. + +* `EXPORT_UNPREFIXED`: If this is set to `yes`, the POSIX 2004 names `getcontext`, `setcontext`, + `swapcontext` and `makecontext` will be provided as weak symbols aliased against their `libucontext_` + namespaced equivalents. This is necessary for libucontext to provide these functions on musl + systems, but you may wish to disable this when using `FREESTANDING` mode to avoid conflicts with + the target's libc. Default is `yes`. + + +## caveats + +`libucontext`, while largely functionally equivalent does have some differences over traditional POSIX +ucontext functions: + +* Saving and restoring the signal mask is not implemented. This is largely a non-issue because most + uses of these functions did not modify the signal mask anyway, but saving/restoring the signal mask + (even though it is unmodified in basically all cases in practice) induces a significant performance + penalty due to having to make kernel syscalls. + +* Only basic GPR registers are saved and restored when context swapping. The glibc implementation uses + hardware capability detection to save/restore other register groups, such as the FPU registers or + vector processing (AltiVec/AVX/NEON) registers. Adding this capability detection would significantly + increase the complexity of the project and thus is not implemented. Support for compiling in code to + save/restore FPU registers or vector registers may be added in a later release as a build-time + setting -- for now, we assume a soft-float ABI with no optional processor features. In practice, this + does not really matter, code using these functions are unlikely to be impacted by this design + assumption.