Crate twizzler_runtime_api
source ·Expand description
The Twizzler Runtime API is the core interface definition for Twizzler programs, including startup, execution, and libstd support. It defines a set of traits that, when all implemented, form the full interface that Rust’s libstd expects from a Twizzler runtime.
From a high level, a Twizzler program links against Rust’s libstd and a particular runtime that will support libstd. That runtime must implement the minimum set of interfaces required by the Runtime trait. Libstd then invokes the runtime functions when needed (e.g. allocating memory, exiting a thread, etc.). Other libraries may invoke runtime functions directly as well (bypassing libstd), but note that doing so may not play nicely with libstd’s view of the world.
What does it look like to use the runtime?
When a program (including libstd) wishes to use the runtime, it invokes this library’s get_runtime function, which will return a reference (a &’static dyn reference) to a type that implements the Runtime trait. From there, runtime functions can be called: ``` let runtime = get_runtime(); runtime.get_monotonic()
Note that this function is only exposed if the runtime feature is enabled.
Another library! Right now, Twizzler defines two runtimes: a "minimal" runtime, and a
"reference" runtime. Those are not implemented in this crate. The minimal runtime is implemented
as part of the twizzler-abi crate, as it's the most "baremetal" runtime. The reference runtime
is implemented as a standalone set of crates. Of course, other runtimes can be implemented, as
long as they implement the required interface in this crate, libstd will work.
# Okay but how does get_runtime work?
Well, [get_runtime] is just a wrapper around calling an extern "C" function,
[__twz_get_runtime]. This symbol is external, so not defined in this crate. A crate that
implements [Runtime] then defines [__twz_get_runtime], allowing link-time swapping of runtimes. The twizzler-abi crate defines this symbol with (weak linkage)[https://en.wikipedia.org/wiki/Weak_symbol], causing it to be linked
only if another (strong) definition is not present. Thus, a program can link to a specific
runtime, but it can also be loaded by a dynamic linker and have its runtime selected at load
time.
Modules
- rt0 defines a collection of functions that the basic Rust ABI expects to be defined by some part of the C runtime:
Structs
- An address range.
- Arguments passed by the runtime to libstd.
- Return value returned by std from LibStdEntry
- An abstract representation of a library, useful for debugging and backtracing.
- Internal library ID type.
- Mapping protections for mapping objects into the address space.
- An object ID, represented as a transparent wrapper type. Any value where the upper 64 bits are zero is invalid.
- A handle to an internal object. This has similar semantics to Arc, but since this crate must be #[no_std], we need to implement refcounting ourselves.
- Arguments that std expects to pass to spawn.
- An ABI-defined argument passed to __tls_get_addr.
Enums
- Auxillary information provided to a new program on runtime entry.
- Possible errors returned by the FsRuntime
- Possible errors of join.
- Possible errors of mapping an object.
- Possible types of monotonicity.
- Possible errors from read.
- Enum of the possible ways to seek within a object
- Possible errors on spawn.
Traits
- Definitions of core runtime features.
- Functions for the debug support part of libstd (e.g. unwinding, backtracing).
- Trait for stdin
- Trait for stdout/stderr
- All the object related runtime functions.
- Full runtime trait, composed of smaller traits
- Runtime that implements STD’s FS support. Currently being implemented.
- Runtime that implements std’s process and command support. Currently unimplemented.
- Runtime that implements stdio.
- Runtime trait for libstd’s time support
- All the thread-related runtime functions.
Functions
- Wrapper around call to __twz_get_runtime.
Type Aliases
- The type of a callback to an IO Read call (see: RustStdioRuntime).
- The type of a callback to an IO Write call (see: RustStdioRuntime).
- The type of a callback to an IO Write call (see: RustStdioRuntime).
- A identifier for a Twizzler object that allows File-like IO The data backing RawFd holds the position of the file cursor and a reference to the object that stores the file’s data.