1 files changed, 86 insertions, 0 deletions

diff --git a/rsapi/src/lib.rs b/rsapi/src/lib.rs
new file mode 100644
index 0000000..f71e69f
--- /dev/null
+++ b/rsapi/src/lib.rs
@@ -0,0 +1,86 @@
+//! rsapi — the kernel↔binary ABI (ADR 0006).
+//!
+//! One versioned `Exports` table is constructed per invocation and handed
+//! to the binary's entry point.  The header starts with a magic and a
+//! `version: u32` so a future kernel can keep old binaries working
+//! (dispatch on the version, never on struct layout).
+//!
+//! Everything here is `no_std`-clean: plain structs and function pointers,
+//! no allocation, no rsnix dependency — binaries link only this crate.
+
+#![no_std]
+
+/// Table magic: "RSEX".
+pub const EXPORTS_MAGIC: u32 = 0x5245_5853;
+
+/// ABI revision.  Bump on any signature change; the kernel refuses to run
+/// binaries whose required major exceeds its own.
+pub const ABI_VERSION: u32 = 1;
+
+/// Entry-point signature.  `extern "C"` on the x86_64-unknown-uefi
+/// target is the Win64 convention: the three arguments arrive in
+/// RCX/RDX/R8 on both sides of the table.
+pub type EntryPoint = extern "C" fn(exports: &'static Exports, argc: usize, argv: *const Arg) -> i32;
+
+/// One C-style argv element: pointer + length (rs-dos strings are not
+/// NUL-terminated in memory).
+#[derive(Clone, Copy)]
+pub struct Arg {
+    pub ptr: *const u8,
+    pub len: usize,
+}
+
+/// A line of text handed across the ABI (stream I/O).
+#[derive(Clone, Copy)]
+pub struct Line {
+    pub ptr: *const u8,
+    pub len: usize,
+}
+
+impl Line {
+    /// Borrow as a &str (lossy is impossible: lines are always UTF-8).
+    pub fn as_str(&self) -> &'static str {
+        unsafe { core::str::from_utf8_unchecked(core::slice::from_raw_parts(self.ptr, self.len)) }
+    }
+}
+
+/// Outcome of `get_line`.
+#[derive(Clone, Copy, PartialEq, Eq)]
+pub enum StreamResult {
+    /// A line is available (see `out`).
+    Line,
+    /// Input exhausted.
+    Eof,
+    /// Aborted (^C or upstream killed); stop immediately.
+    Abort,
+}
+
+// ---------------------------------------------------------------------------
+// Exports table — v1
+// ---------------------------------------------------------------------------
+
+/// The function table a binary receives.  Layout is fixed by `version`;
+/// new functions are appended, existing ones never move.
+#[repr(C)]
+pub struct Exports {
+    // ---- header ----
+    pub magic: u32,
+    pub version: u32,
+
+    // ---- console / streams (v1) ----
+    /// Print one line to the command's output stream.
+    /// Returns false when the consumer says stop (pager quit / head limit /
+    /// ^C) — the binary should wrap up promptly.
+    pub put_line: fn(line: Line) -> bool,
+    /// Read one line from the command's input stream (only meaningful for
+    /// input consumers like cat/hexdump; otherwise returns Eof).
+    /// `out` receives the line when the result is `StreamResult::Line`.
+    pub get_line: fn(out: &mut Line) -> StreamResult,
+
+    // ---- lifecycle (v1) ----
+    /// Log one line to the kernel log ring (/dev/klog).
+    pub log_line: fn(line: Line),
+    /// Exit code for the completion message to the spawner.
+    /// (Calling this is optional; returning from the entry point exits 0.)
+    pub exit: fn(code: i32) -> !,
+}