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


  • rt0 defines a collection of functions that the basic Rust ABI expects to be defined by some part of the C runtime:


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




Type Aliases