oro+oro-std+sysabi+examples: add initial ID system boilerplate

.cargo/config.toml

@@ -21,4 +21,4 @@ oro-ra-x86_64 = "check --quiet --message-format=json --keep-going --target ./oro
 
 oro-ra-aarch64 = "check --quiet --message-format=json --keep-going --target ./oro-arch-aarch64/aarch64-unknown-oro.json --bin oro-kernel-aarch64 --bin oro-limine-aarch64 -Zunstable-options -Zbuild-std=core,compiler_builtins,alloc -Zbuild-std-features=compiler-builtins-mem"
 
-oro-examples = "build --target=x86_64-unknown-none --target=aarch64-unknown-none -p example-noop -p example-spin -p example-std-noop -p example-std-noop-nightly"
+oro-examples = "build --target=x86_64-unknown-none --target=aarch64-unknown-none -p example-noop -p example-spin -p example-std-noop -p example-std-noop-nightly -p example-std-spin"

Cargo.toml

@@ -37,6 +37,7 @@ members = [
 	"examples/no-std/spin",
 	"examples/std/noop",
 	"examples/std/noop-nightly",
+	"examples/std/spin",
 ]
 
 [workspace.dependencies]

examples/std/spin/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "example-std-spin"
+description = "Example module that yields its time slice forever."
+version = "0.0.0"
+publish = false
+edition = "2021"
+
+build = "build.rs"
+
+[dependencies]
+std = { version = "0.0.0", package = "oro-std", path = "../../../oro-std" }
+
+[dependencies.oro]
+path = "../../../oro"
+features = ["runtime"]
+
+[build-dependencies.oro]
+path = "../../../oro"
+features = ["build"]
+default-features = false

examples/std/spin/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+	::oro::build();
+}

examples/std/spin/src/main.rs

@@ -0,0 +1,8 @@
+#![no_main]
+
+#[no_mangle]
+fn main() {
+	loop {
+		std::thread::yield_now();
+	}
+}

oro-std/src/thread/current.rs

@@ -0,0 +1,36 @@
+#![expect(unused_imports)]
+use ::oro::{id::kernel::iface::THREAD_V0, key, uses};
+
+use crate::thread::Thread;
+
+/// Gets a handle to the thread that invokes it.
+///
+/// # Oro-specific
+/// This function **panics** in the rare case the thread handle cannot be retrieved.
+/// This is a temporary measure until the kernel implements TLS.
+#[must_use]
+pub fn current() -> Thread {
+	// NOTE(qix-): The real `std` stores a TLS handle to the current thread,
+	// NOTE(qix-): which is totally valid but the kernel hasn't implemented
+	// NOTE(qix-): TLS quite yet. So we do it (slowly) here each time.
+	uses!(THREAD_V0, key!("id"));
+}
+
+/// Cooperatively gives up a timeslice to the OS scheduler.
+///
+/// This calls the underlying OS scheduler's yield primitive, signaling
+/// that the calling thread is willing to give up its remaining timeslice
+/// so that the OS may schedule other threads on the CPU.
+///
+/// A drawback of yielding in a loop is that if the OS does not have any
+/// other ready threads to run on the current CPU, the thread will effectively
+/// busy-wait, which wastes CPU time and energy.
+///
+/// # Oro-specific
+/// This function **panics** in the rare case the interface is unavailable.
+pub fn yield_now() {
+	// NOTE(qix-): The real `std` stores a TLS handle to the current thread,
+	// NOTE(qix-): which is totally valid but the kernel hasn't implemented
+	// NOTE(qix-): TLS quite yet. So we do it (slowly) here each time.
+	uses!(THREAD_V0, key!("id"));
+}

oro-std/src/thread.rs → oro-std/src/thread/mod.rs

@@ -1,5 +1,8 @@
 //! Native threads.
 
+mod current;
+
+pub use self::current::{current, yield_now};
 use crate::{fmt, num::NonZero};
 
 /// A unique identifier for a running thread.

oro-sysabi/src/id.rs

@@ -0,0 +1,49 @@
+//! Oro module metadata and ABI constants.
+
+/// ID masks for kernel interfaces.
+pub mod mask {
+	/// `(id & KERNEL_ID) == 0` indicates a kernel ID.
+	///
+	/// Any other ID is a non-standard, user-defined ID.
+	pub const KERNEL_ID: u64 = 0xFFFF_FFFF_0000_0000;
+
+	/// `(id & KERNEL_ID_TYPE)` extracts the kernel ID type.
+	///
+	/// Note that this _does_ include the high 32-bits
+	/// so that any erroneously operated upon user-defined
+	/// ID will not somehow pass the check.
+	pub const KERNEL_ID_TYPE: u64 = 0xFFFF_FFFF_FF00_0000;
+
+	/// `(iface & KERNEL_ID_TYPE) == KERNEL_ID_TYPE_PRIMITIVE` indicates a primitive type.
+	pub const KERNEL_ID_TYPE_PRIMITIVE: u64 = 0x0100_0000;
+
+	/// `(iface & KERNEL_ID_TYPE) == KERNEL_ID_TYPE_IFACE` indicates a kernel interface.
+	pub const KERNEL_ID_TYPE_IFACE: u64 = 0x0200_0000;
+
+	/// `(iface & KERNEL_ID_TYPE) == KERNEL_ID_TYPE_META` indicates a module metadata structure.
+	pub const KERNEL_ID_TYPE_META: u64 = 0x0300_0000;
+}
+
+/// Kernel interface IDs.
+pub mod iface {
+	use crate::id::mask::KERNEL_ID_TYPE_IFACE;
+
+	/// The ID of the kernel threading interface (version 0).
+	pub const THREAD_V0: u64 = KERNEL_ID_TYPE_IFACE | 0x00_001;
+}
+
+/// Kernel primitive type IDs.
+pub mod primitive {
+	use crate::id::mask::KERNEL_ID_TYPE_PRIMITIVE;
+
+	/// The ID of the kernel `usize` primitive type.
+	pub const U64: u64 = KERNEL_ID_TYPE_PRIMITIVE | 0x00_001;
+}
+
+/// Kernel metadata IDs.
+pub mod meta {
+	use crate::id::mask::KERNEL_ID_TYPE_META;
+
+	/// ID indicating that the following metadata indicates an interface/key usage.
+	pub const USES: u64 = KERNEL_ID_TYPE_META | 0x00_001;
+}

oro-sysabi/src/lib.rs

@@ -2,6 +2,9 @@
 #![cfg_attr(not(test), no_std)]
 #![cfg_attr(doc, feature(doc_cfg, doc_auto_cfg))]
 
+mod macros;
+
 pub(crate) mod arch;
 
+pub mod id;
 pub mod syscall;

oro-sysabi/src/macros.rs

@@ -0,0 +1,15 @@
+//! Macros for working with the system ABI.
+
+/// Auxiliary types used by macros exported by this crate.
+///
+/// **Using this module directly is highly discouraged. It is not stable.**
+pub mod private {}
+
+/// Declares that an `(interface_id, key)` is to be used
+/// by the current function.
+#[macro_export]
+macro_rules! uses {
+	($iface:expr, $key:expr) => {
+		todo!();
+	};
+}

oro/src/runtime.rs

@@ -1,6 +1,7 @@
 //! High-level runtime support for Oro modules.
 
 pub use ::oro_sysabi as sysabi;
+pub use sysabi::{key, uses};
 
 #[cfg(feature = "panic_handler")]
 #[panic_handler]
@@ -107,3 +108,18 @@ pub unsafe fn force_crash() -> ! {
 		core::hint::spin_loop();
 	}
 }
+
+/// IDs used throughout the Oro kernel.
+pub mod id {
+	/// Kernel IDs; re-exported from [`oro_sysabi::id`].
+	pub use ::oro_sysabi::id as kernel;
+
+	/// Common non-kernel IDs.
+	///
+	/// > **NOTE:** This is not a comprehensive list of all IDs in the Oro ecosystem,
+	/// > but - notably - the IDs used by the standard library (`oro-std` or, in the future,
+	/// > `std`). They can be used directly or by using non-`core` types provided by the `[oro-]std` module.
+	pub mod common {
+		// TODO(qix-): Intentionally empty for now.
+	}
+}