core/platform/src/syscalls.rs

//! Provides the Syscalls trait which directly represents Tock's system call
//! APIs. Syscalls is implemented by both `libtock_runtime` which makes system
//! calls into a real Tock kernel, and `libtock_fake` which is a fake Tock
//! kernel.

// TODO: Implement `libtock_runtime` and `libtock_fake`.

/// Syscalls represents Tock's system call APIs. It is designed to be
/// implemented as easily as possible -- its arguments and return values
/// correspond directly to registers in the ABI. For a higher-level abstraction,
/// see Platform.
///
/// By design, syscalls is designed to be zero-cost in a TBF binary and
/// functional (but not zero-cost) in unit tests. In a TBF binary, Syscalls is
/// implemented with the `'static` lifetime, and is a zero-sized type. Syscalls
/// requires `Copy` in order to support defining it usefully on zero-sized
/// types. When used in unit tests, the Syscalls implementation carries a
/// lifetime local to that unit test.
///
/// With the exception of `memop`, this trait aligns closely to Tock's
/// kernel::Driver trait.
pub trait Syscalls<'k>: Copy {
    /// Calls the `allow` system call.
    ///
    /// # Safety
    /// `allow` is unsafe because callers must guarantee that `pointer` and
    /// `length` refer to memory that the kernel can mutate safely. The buffer
    /// must last for the lifetime 'k.
    // `driver` and `minor` are `usize` because the kernel internally treats
    // them as `usize`s. `allow`'s return value is a kernel `ReturnCode`;
    // Platform translates the `isize` into a `ReturnCode`.
    unsafe fn allow(self, driver: usize, minor: usize, pointer: *mut u8, length: usize) -> isize;

    /// Calls the `command` system call.
    // `driver`, `minor`, `arg1`, and `arg2` are all `usize` (rather than `u32`)
    // because the kernel refers to them internally as `usize`s. command returns
    // a kernel ReturnCode; Platform is responsible for translating an isize
    // into the local ReturnCode.
    fn command(self, driver: usize, minor: usize, arg1: usize, arg2: usize) -> isize;

    /// Calls the `memop` system call with an argument. Note that memop() cannot
    /// cause memory unsafety, although it can cause the app to fault (e.g. Brk
    /// can move the app break below the stack, causing a fault). The isize
    /// returned is a kernel ReturnCode.
    // Platform performs the translation from isize into ReturnCode to keep
    // Syscalls implementations simple.
    fn memop_arg(self, op: MemopWithArg, arg: usize) -> isize;

    /// Calls the `memop` system call with no arguments. This version is
    /// slightly cheaper because it does not need to set the argument register.
    // We're okay with leaking the value in the argument register because
    // memop() is always handled by the core kernel, never by an untrusted
    // capsule.
    fn memop_noarg(self, op: MemopNoArg) -> isize;

    /// Calls the `subscribe` system call.
    ///
    /// # Safety
    /// `subscribe` is unsafe because the callback can potentially be unsafe,
    /// and callers of `subscribe` must assert that calling the callback with
    /// the provided `data` value is safe. The callback must last for the 'k
    /// lifetime.
    // Driver, minor, the callback args, and data are all represented as `usize`
    // because that is the type the kernel uses internally to store them (e.g.
    // as opposed to u32).
    unsafe fn subscribe(
        self,
        driver: usize,
        minor: usize,
        callback: Option<unsafe extern "C" fn(usize, usize, usize, usize)>,
        data: usize,
    );

    /// Puts the process to sleep until a callback becomes pending, then invokes
    /// the callback.
    fn yieldk(self);
}

#[non_exhaustive]
#[repr(usize)]
pub enum MemopWithArg {
    Brk = 0,
    Sbrk = 1,
    FlashRegionStart = 8,
    FlashRegionEnd = 9,
    SpecifyStackTop = 10,
    SpecifyHeapStart = 11,
}

#[non_exhaustive]
#[repr(usize)]
pub enum MemopNoArg {
    MemoryStart = 2,
    MemoryEnd = 3,
    FlashStart = 4,
    FlashEnd = 5,
    GrantStart = 6,
    FlashRegions = 7,
}