ariadne
/
libucontext
1
1
Fork 1
Code Issues 2 Pull Requests 1 Projects Releases Wiki Activity

libucontext: expand README

pull/21/head
Ariadne Conill 2020-12-07 14:39:07 -07:00
parent c10cde83da
commit 22bd490272
1 changed files with 39 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
README.md
View File

@ -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.