godspeed_sdk/

ipc.rs

// SPDX-License-Identifier: Apache-2.0
//! IPC syscall wrappers - §8.2.
//!
//! Typed wrappers so service code cannot accidentally call the wrong syscall
//! number or pass a malformed message size.

use crate::capability::CapHandle;
use crate::syscall::raw_syscall;

pub const MAX_PAYLOAD: usize = 4096;

/// An IPC message as seen by service code.
pub struct Message {
    pub payload: [u8; MAX_PAYLOAD],
    pub payload_len: usize,
    /// Capability handles embedded in this message (received side).
    pub caps: [Option<CapHandle>; 4],
    pub cap_count: usize,
}

impl Message {
    pub fn from_bytes(bytes: &[u8]) -> Self {
        let len = bytes.len().min(MAX_PAYLOAD);
        let mut payload = [0u8; MAX_PAYLOAD];
        payload[..len].copy_from_slice(&bytes[..len]);
        Self {
            payload,
            payload_len: len,
            caps: [None; 4],
            cap_count: 0,
        }
    }

    pub fn payload_bytes(&self) -> &[u8] {
        &self.payload[..self.payload_len]
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum IpcError {
    EndpointDead,
    QueueFull,
    MessageTooLarge,
    /// A synchronous `call` was woken because the peer (the would-be replier) died before replying
    /// (§8.6). The reply-side twin of `EndpointDead`: the caller waited on the peer's liveness, not a
    /// timer, and so never hangs (Commandment VIII). Reacquire the peer by name and retry, exactly as
    /// for a failed send.
    ReplyDead,
    CapError(crate::capability::CapError),
}

// ---------------------------------------------------------------------------
// IPC syscall wrappers.
// ---------------------------------------------------------------------------

/// Block until a message is available on `endpoint`. (§8.2 - `recv`)
///
/// Passes a stack-allocated receive buffer to the kernel; the kernel copies the
/// message payload there and returns the number of bytes written.
pub fn recv(endpoint: CapHandle) -> Result<Message, IpcError> {
    let mut payload = [0u8; MAX_PAYLOAD];
    // SAFETY: raw_syscall(2) = Recv; buf is a valid stack slice within user space.
    let ret = unsafe {
        raw_syscall(
            2,
            endpoint.0 as u64,
            payload.as_mut_ptr() as u64,
            MAX_PAYLOAD as u64,
        )
    };
    if ret < 0 {
        Err(i64_to_ipc_error(ret))
    } else {
        Ok(Message::from_bytes(&payload[..ret as usize]))
    }
}

/// Non-blocking `recv`: return `Ok(None)` immediately if the endpoint queue is empty,
/// `Ok(Some(msg))` if a message was waiting. (syscall 34 - `try_recv`) Lets a busy-polling
/// driver drain interrupt events (§12) without giving up its loop.
pub fn try_recv(endpoint: CapHandle) -> Result<Option<Message>, IpcError> {
    const TRY_RECV_EMPTY: i64 = -1000; // kernel sentinel for an empty queue
    let mut payload = [0u8; MAX_PAYLOAD];
    // SAFETY: raw_syscall(34) = TryRecv; buf is a valid stack slice within user space.
    let ret = unsafe {
        raw_syscall(
            34,
            endpoint.0 as u64,
            payload.as_mut_ptr() as u64,
            MAX_PAYLOAD as u64,
        )
    };
    if ret == TRY_RECV_EMPTY {
        Ok(None)
    } else if ret < 0 {
        Err(i64_to_ipc_error(ret))
    } else {
        Ok(Some(Message::from_bytes(&payload[..ret as usize])))
    }
}

/// Receive into a buffer the CALLER owns, returning the byte count.
///
/// A `Message` carries a 4096-byte payload BY VALUE, so `recv_timeout` below costs EIGHT kilobytes of
/// stack per call: one 4 KiB array to receive into, and another inside the `Message` it builds and
/// returns. Every wrapper that forwards that `Message` pays 4 KiB again.
///
/// On `fs` that arithmetic is fatal rather than untidy. Its request path is several such calls deep,
/// it runs on a 256 KiB stack, and adding one more level made it overflow at mount - a fault that took
/// five wrong attempts to place because each one removed a single 4 KiB item without measuring the
/// whole frame.
///
/// This is the shape the operation actually has, and the shape every real IPC API uses: the kernel
/// copies into memory the caller already owns, and hands back a length. Nothing large is created and
/// nothing large is moved. `Ok(None)` is the timeout, exactly as above.
///
/// Caps are NOT delivered here - the block and frame paths carry none, and a caller that needs one
/// takes it with `take_pending_cap` regardless. A buffer API that silently dropped a capability would
/// be a leak, so this one simply does not carry them.
pub fn recv_timeout_into(
    endpoint: CapHandle, buf: &mut [u8], timeout_cycles: u64,
) -> Result<Option<usize>, IpcError> {
    const RECV_TIMED_OUT: i64 = -1001;
    let packed = ((buf.len() as u64) << 16) | (endpoint.0 as u64 & 0xFFFF);
    let timeout_cycles = abi_timeout(timeout_cycles);
    // SAFETY: raw_syscall(35) = RecvTimeout; `buf` is a valid caller-owned slice in user space and its
    // true length is what is passed, so the kernel cannot write past it.
    let ret = unsafe { raw_syscall(35, packed, buf.as_mut_ptr() as u64, timeout_cycles) };
    if ret == RECV_TIMED_OUT {
        Ok(None)
    } else if ret < 0 {
        Err(i64_to_ipc_error(ret))
    } else {
        Ok(Some((ret as usize).min(buf.len())))
    }
}

/// Blocking `recv` with a timeout in counter ticks (the kernel waits at least one scheduler tick):
/// `Ok(Some(msg))` on a message, `Ok(None)` on timeout, `Err` on a real error. `timeout_cycles == 0`
/// blocks forever (like `recv`). (syscall 35 - `recv_timeout`) Lets a driver idle on its interrupt
/// yet still wake on a timer (e.g. for keyboard auto-repeat while a key is held - §12).
pub fn recv_timeout(endpoint: CapHandle, timeout_cycles: u64) -> Result<Option<Message>, IpcError> {
    const RECV_TIMED_OUT: i64 = -1001; // kernel sentinel for "timed out, no message"
    let mut payload = [0u8; MAX_PAYLOAD];
    // arg0 packs the buffer length (high) and the cap slot (low) to fit the 3-arg ABI.
    let packed = ((MAX_PAYLOAD as u64) << 16) | (endpoint.0 as u64 & 0xFFFF);
    let timeout_cycles = abi_timeout(timeout_cycles);
    // SAFETY: raw_syscall(35) = RecvTimeout; buf is a valid stack slice within user space.
    let ret = unsafe { raw_syscall(35, packed, payload.as_mut_ptr() as u64, timeout_cycles) };
    if ret == RECV_TIMED_OUT {
        Ok(None)
    } else if ret < 0 {
        Err(i64_to_ipc_error(ret))
    } else {
        Ok(Some(Message::from_bytes(&payload[..ret as usize])))
    }
}

/// Fit a timeout to what one syscall argument can actually carry.
///
/// A 32-bit ABI carries each argument in ONE register and `raw_syscall` truncates a `u64` arg to
/// `u32`. Every OTHER argument (pointer, handle, length) genuinely fits in 32 bits, but a timeout in
/// generic-timer ticks does NOT: at QEMU raspi2b's 62.5 MHz, `u32::MAX` ticks is only ~68 s (~71 min
/// at the real Pi 2's measured 1 MHz, `kernel/src/arch/arm/timer.rs`). A
/// longer finite timeout would truncate to a tiny value (premature wake) or - if it landed on a
/// multiple of 2^32 - to **0**, which the kernel reads as "block forever". A bounded Commandment VIII
/// deadline turning into an infinite hang is the worst possible way for this to fail, which is why it
/// saturates: a long finite request becomes the longest REPRESENTABLE timeout, never a tiny one and
/// never 0. A genuine 0 (block forever) stays 0. (userspace-audit Audit 4, A-U1.)
///
/// ASKED AS REGISTER WIDTH, NOT AS `target_arch = "arm"`, which is what both call sites said
/// separately. arm32 was never the reason - a 32-bit argument register was, and arm32 merely happens
/// to be the only 32-bit port that currently builds userspace. A future 32-bit port inherits the
/// clamp instead of inheriting the hang, and that is not hypothetical: the failure mode here is
/// SILENT on the port that lacks it. (`target_pointer_width` is a proxy for argument-register width;
/// they coincide on every target this SDK builds for, and `kernel/src/task/scheduler.rs` already uses
/// the same proxy for the same reason.)
#[inline]
fn abi_timeout(timeout_cycles: u64) -> u64 {
    if cfg!(target_pointer_width = "32") && timeout_cycles != 0 {
        timeout_cycles.min(u32::MAX as u64).max(1)
    } else {
        timeout_cycles
    }
}

/// Send a message to `endpoint`; block if the queue is full. (§8.2 - `send`)
pub fn send(endpoint: CapHandle, msg: &Message) -> Result<(), IpcError> {
    let payload = msg.payload_bytes();
    // SAFETY: raw_syscall(1) = Send; payload is a valid slice within user space.
    let ret = unsafe {
        raw_syscall(
            1,
            endpoint.0 as u64,
            payload.as_ptr() as u64,
            payload.len() as u64,
        )
    };
    if ret == 0 { Ok(()) } else { Err(i64_to_ipc_error(ret)) }
}

/// Send without blocking; return `QueueFull` immediately. (§8.2 - `try_send`)
pub fn try_send(endpoint: CapHandle, msg: &Message) -> Result<(), IpcError> {
    let payload = msg.payload_bytes();
    // SAFETY: raw_syscall(3) = TrySend; payload is a valid slice within user space.
    let ret = unsafe {
        raw_syscall(
            3,
            endpoint.0 as u64,
            payload.as_ptr() as u64,
            payload.len() as u64,
        )
    };
    if ret == 0 { Ok(()) } else { Err(i64_to_ipc_error(ret)) }
}

/// Synchronous CALL (syscall 41): send `request` to `target` carrying `reply_grant` as a one-shot
/// reply cap, then block on `recv` (the caller's own endpoint, where the reply lands) until the peer
/// replies OR the peer's endpoint dies. Returns the reply, `Err(ReplyDead)` if the peer died before
/// replying, `Err(EndpointDead)` if the peer was already dead when the request was sent, or another
/// `IpcError` on a failed send.
///
/// This **waits on truth, not on time** (Commandment VIII): a peer that dies mid-request wakes the
/// caller with `ReplyDead` (the reply-side twin of `EndpointDead`, §8.6) instead of hanging it - no
/// timer, no fixed yield count. The buffer is in/out: the request is read from it, and the kernel
/// writes the reply back into the same buffer.
pub fn call(
    target:      CapHandle,
    reply_grant: CapHandle,
    recv:        CapHandle,
    request:     &Message,
) -> Result<Message, IpcError> {
    let mut buf = [0u8; MAX_PAYLOAD];
    let req = request.payload_bytes();
    buf[..req.len()].copy_from_slice(req);
    // Pack three 16-bit cap slots + the length into THREE 32-bit-safe args (not two): arg0 = target |
    // reply, arg2 = recv | len. The old layout put `recv` in bits 32-47 of arg0, which the ARM 32-bit
    // syscall ABI truncates away (each arg is one register) - recv_slot became 0 and the Call routed to
    // the wrong endpoint (userspace-audit A-U1 class). A request length never exceeds one message (4 KiB
    // < 0xFFFF), so `recv` rides the high half of the length arg. `handle_call` mirrors this.
    let packed = ((reply_grant.0 as u64) << 16) | (target.0 as u64);
    let recv_len = ((recv.0 as u64) << 16) | (req.len() as u64 & 0xFFFF);
    // SAFETY: raw_syscall(41) = Call; `buf` is a valid in/out stack buffer in user space (request in,
    // reply written back), `req.len() <= MAX_PAYLOAD`. The kernel validates every cap slot and the
    // buffer pointer before use.
    let ret = unsafe { raw_syscall(41, packed, buf.as_mut_ptr() as u64, recv_len) };
    if ret < 0 {
        Err(i64_to_ipc_error(ret))
    } else {
        Ok(Message::from_bytes(&buf[..ret as usize]))
    }
}

/// `call`, bounded, receiving into a caller-owned buffer.
///
/// The reason this exists as a SYSCALL rather than the hand-rolled send + `recv_timeout_into` it
/// replaces: `recv_timeout_into` takes whatever is next on the endpoint. A service that serves clients
/// on the same endpoint it awaits replies on would receive an unrelated CLIENT REQUEST, fail to match
/// it, and drop it - losing the request and leaving the real reply to arrive later as an orphan that
/// desynced every following exchange. `Call` never had that flaw (it dequeues the reply specifically),
/// it just could not be bounded. Now it can.
///
/// Three cap slots pack into `a0` at 8 bits each - a task holds at most 64 caps, so six bits suffice -
/// because the ARM 32-bit ABI truncates each argument to one register and the plain `call` layout had
/// no room left. Length and deadline share `a2`.
///
/// `Ok(None)` = the deadline passed with no reply.
pub fn call_deadline_into(
    target:      CapHandle,
    reply_grant: CapHandle,
    recv:        CapHandle,
    request:     &[u8],
    buf:         &mut [u8],
    max_secs:    u64,
) -> Result<Option<usize>, IpcError> {
    const RECV_TIMED_OUT: i64 = -1001;
    // `buf` carries the request OUT and the reply BACK, exactly as plain `call` does with its own
    // 4 KiB frame. So it must hold the LARGER of the two, and a caller that sized it for replies
    // alone is a caller whose requests are about to be cut short.
    //
    // This said `.min(buf.len())` in its first version, which truncated in silence: `fs` sized its
    // buffer at 2 + BLOCK = 514 for replies while a block WRITE request is 1 + 9 + BLOCK = 522, so
    // every write went out eight bytes short and came back a failure with no reason attached. Reads
    // are ten bytes and fit, which is why reads worked and only writes broke. A silent truncation is
    // the one thing a message path must never do (§26.7).
    if request.len() > MAX_PAYLOAD { return Err(IpcError::MessageTooLarge); }
    if request.len() > buf.len() { return Err(IpcError::MessageTooLarge); }
    let n = request.len();
    buf[..n].copy_from_slice(&request[..n]);
    // TELL THE KERNEL HOW BIG THE REPLY BUFFER IS. It writes the reply back into `buf`, and until
    // now it was never told the size: `handle_call_deadline` validated MAX_MESSAGE_SIZE and its own
    // comment said "the SDK always passes a MAX_MESSAGE_SIZE buffer". That is true of `call` (41),
    // which allocates its own 4 KiB internally - and false here, where the buffer is the CALLER'S
    // slice, of whatever size it chose. `console_dims` passes EIGHT BYTES. Validating 4 KiB only
    // proves those bytes are mapped, which they are - it is the middle of a stack - so nothing stood
    // between a larger-than-expected reply and a smashed frame.
    //
    // Encoded as a 4-bit power-of-two CLASS rather than a length, because the request length and the
    // deadline already occupy the length argument, and arg0 has exactly one nibble spare below the
    // 32-bit line that arm32's one-register-per-arg ABI truncates at. Rounded DOWN, so a 514-byte
    // buffer declares 512 and the kernel refuses a 514-byte reply rather than writing two bytes past
    // it. Being wrong in the conservative direction turns a silent smash into a loud refusal (§26.7).
    // Callers should size this buffer as a POWER OF TWO. A 522-byte buffer declares 512 and its own
    // 522-byte replies are then refused - correct, conservative, and confusing. `fs` carries the note
    // and a compile-time assert on its side; this is the reason.
    let cap_class = (usize::BITS - 1 - buf.len().max(1).leading_zeros()).min(12) as u64;
    let slots = (target.0 as u64 & 0xFF)
        | ((reply_grant.0 as u64 & 0xFF) << 8)
        | ((recv.0 as u64 & 0xFF) << 16)
        | (cap_class << 24);
    let len_secs = (n as u64 & 0xFFFF) | ((max_secs.min(0xFFFF)) << 16);
    // SAFETY: raw_syscall(50) = CallDeadline; `buf` is a caller-owned slice in user space and the
    // kernel writes at most one message into it, which is why the request is staged there too.
    let ret = unsafe { crate::syscall::raw_syscall(50, slots, buf.as_mut_ptr() as u64, len_secs) };
    if ret == RECV_TIMED_OUT {
        Ok(None)
    } else if ret < 0 {
        Err(i64_to_ipc_error(ret))
    } else {
        Ok(Some(ret as usize))
    }
}

// ---------------------------------------------------------------------------
// Error conversion.
// ---------------------------------------------------------------------------

pub(crate) fn i64_to_ipc_error(code: i64) -> IpcError {
    match code {
        -2  => IpcError::CapError(crate::capability::CapError::CapNotHeld),
        -3  => IpcError::CapError(crate::capability::CapError::CapInsufficientRights),
        -4  => IpcError::CapError(crate::capability::CapError::CapNotGrantable),
        -7  => IpcError::EndpointDead,
        -8  => IpcError::QueueFull,
        -9  => IpcError::QueueFull, // QueueEmpty on caller side == retry
        -10 => IpcError::MessageTooLarge,
        -12 => IpcError::ReplyDead,
        _   => IpcError::EndpointDead,
    }
}