Oro System ABI Low Level Bindings

This crate houses the Oro kernel sysabi data structures, which are used to interact with the Oro kernel from user space.

This crate is intended to be consumed only as a low-level interface to interacting with the Oro system ABI ("sysabi"), which provides pointers to in-memory Ring and Port information provided to Module Instances.

Usage

For updated usage information, please refer to the crate documentation.

License

This crate is Copyright © 2024 by Joshua Lee Junon and is released under either the MIT or the Apache 2.0 license, at the user's discretion.

Part of the Oro Operating System project.

lib.rs:

Oro Kernel System ABI Structures

This crate houses the Oro kernel sysabi data structures, which are used to interact with the Oro kernel from user space.

This crate is intended to be consumed only as a low-level interface to interacting with the Oro system ABI ("sysabi"), which provides pointers to in-memory Ring and Port information provided to Module Instances.

Usage

Entry points are handed a pointer to the Root sysabi structure via a stable but architecture-specific register or well-known memory location. This structure holds pointers to the Ring and Port metadata that is shared between all module instances on the same ring (though the data will differ between rings).

x86_64

On x86_64, the Root structure is passed to the entry point at first execution via the rdi register. It is guaranteed to be valid and aligned in a way that adheres both to the structure's prescribed layout as well as any alignment requirements of the architecture.

AArch64

On AArch64, the Root structure is passed to the entry point at first execution via the x0 register. It is guaranteed to be valid and aligned in a way that adheres both to the structure's prescribed layout as well as any alignment requirements of the architecture.

Stability

Important: The following stability guarantees are only applicable after version 1.0.0 of this crate.

The Oro sysabi is considered stable, using versioning to ensure compatibility across versions of this crate. Further, the C header file generated by this crate is considered stable in the same way.

Note that there is currently no stable specification for the sysabi, as the project is still in its infancy and the sysabi and kernel are subject to rapid, volatile changes for the time being.

Thus, the only supported, stable way to interact with the Ring and sibling instance Ports is via this crate (or the generated C header file).

Reminders about Oro's Design

A few reminders for those who are new to Oro:

• There are no system calls in Oro. All interactions with the kernel are done via the sysabi, which is a shared memory ring buffer message passing system, called Ports.

• Rings are the primary security boundary in Oro. Module instances on a ring can see all other instances on the ring, as well as child rings. However, they cannot see sibling or parent rings, or anything on them, under any circumstance. This is enforced by the kernel. The resources they have access to are limited to those explicitly granted to them by the parent ring via remounted Instances and their exported / consuming Ports.

• There is no argc or argv in Oro. All parameterization of execution is performed via Ports.

• While main is a valid entry point for legacy ELF binaries, it is not the only means by which an entry point can be defined. This is because Oro Modules can have multiple entry points, all of which have threads that are spawned and run concurrently upon ring / module instance initialization.

  At the time of writing, the only supported entry point is main.

• Ports are thread-bound, and are thus only accessible by the thread that currently owns them. In the future, a thread will be able to "steal" a Port from another thread, but this is not yet implemented and will almost definitely be expensive if done often, and can cause program instability if done incorrectly.

• Ports have two modes - synchronous and asynchronous.

  • Synchronous ports are blocking, and will cause a preemption (page fault on most architectures) upon the first write (send) or read (receive) to a port's slot. These reads and writes are enforced as sequentially accessed, and in the event a port is saturated (send) or drained (receive), the thread will be preempted until the port has had activity by the peer.
  • Asynchronous ports are non-blocking, and under most circumstances are automatically upgraded as such if both sides of the port exhibit behavior that indicate they are properly checking and manually managing the port's cursors (which are read/write). Even under these circumstances, an upgrade is not guaranteed. User configuration (via automation or otherwise) may mark the port as force-synchronous, namely in cases where the user has determined that a bug exists in the port's handling by one or both sides, or as an added layer of security or safety. Aynchronous ports are inherently dangerous as they remove many safety rails that synchronous ports provide. However, they are significantly more performant and can be used to great effect in high-performance, low-latency applications.

The current status of a port's mode can be queried via the sysabi and, like all other sysabi data, is updated in real-time.