interface.idl

/// A notification message. If a task has unread notifications, the kernel
/// constructs and returns this message. `data` may include
/// multiple notifications (e.g. `NOTIFY_TIMER | NOTIFY_ASYNC`).
oneway notifications(data: notifications);

/// Requests a pending async message. Internally used by `async_recv` API.
oneway async();

/// Represents an invalid message.
oneway invalid();

enum abi_hook_type {
    INITIAL = 1,
    SYSCALL = 2,
};

/// The kernel sends this message to a pager task when an exception occurs.
oneway exception(task: task, exception: exception_type);

/// The kernel calls this RPC when a page fault occurs.
/// When the pager task replies, the kernel continues executing the page-faulted task.
rpc page_fault(task: task, vaddr: vaddr, ip: vaddr, fault: uint) -> ();

/// The kernel calls this RPC when a task with ABI hook enabled
/// initiated a system call.
rpc abi_hook(task: task, type: int, frame: trap_frame) -> (frame: trap_frame);

/// Hardware-assisted hypervisor like Linux's KVM.
namespace hv {
    /// The x64 guest calls this RPC before it starts to retrieve some initial
    /// guest states.
    rpc x64_start(task: task) -> (guest_rip: uint64, ept_pml4: paddr, initial_rbx: uint64);

    /// The guest calls this RPC when it enters an idle state or waits for interrupt.
    rpc halt(task: task) -> ();
    /// The guest calls this RPC when it tried to perform an invalid access to a
    /// guest physical memory address (EPT violation in Intel VT).
    rpc guest_page_fault(task: task, gpaddr: gpaddr, frame: hv_frame) -> (frame: hv_frame);
    /// IO port read access from the guest.
    rpc ioport_read(task: task, port: uint16, size: size) -> (value: uint32);
    /// IO port write access from the guest.
    rpc ioport_write(task: task, port: uint16, size: size, value: uint32) -> ();

    /// Receive a pending message from the server.
    oneway await(task: task);
    /// Injects an IRQ into the guest.
    oneway inject_irq(irq_bitmap: uint32);
}

/// IPC benchmarking.
namespace benchmark {
    /// No-op. Do nothing but returns the value as it is.
    rpc nop(value: int) -> (value: int);
    /// No-op. Do nothing but returns data (to be sent as ool) as it is.
    rpc nop_with_ool(data: bytes) -> (data: bytes);
}

/// The memory management server (vm) interface.
namespace vm {
    /// Allocates memory pages. `paddr` is zero, it allocates arbitrary physical
    /// memory pages. Otherwise, it maps the specified physical memory address to
    /// an unused virtual memory address.
    rpc alloc_pages(num_pages: size, paddr: paddr) -> (vaddr: vaddr, paddr: paddr);
}

/// Service discovery.
namespace discovery {
    /// Registers a service.
    rpc serve(name: str) -> ();
    /// Looks for a service. This blocks until a service with `name` appears.
    rpc lookup(name: str) -> (task: task);
}

/// High-level task managemnt.
namespace task {
    /// Allocates an unused TASK ID.
    rpc alloc(pager: task) -> (task: task);
    /// Deallocates an unused TASK ID.
    rpc free(task: task) -> ();
    /// Launches a task.
    rpc launch(name_and_cmdline: str) -> (task: task);
    /// Watches a task. If the task exits, the watcher task receives an async
    /// message `task.exited`.
    rpc watch(task: task) -> ();
    /// Unwatches a task.
    rpc unwatch(task: task) -> ();
    /// A message sent to watcher tasks when a task exits.
    async oneway exited(task: task);
}

/// Out-of-Line (OoL) payload internal interface.
namespace ool {
    /// Registers a receive buffer for an OoL payload.
    rpc recv(addr: vaddr, len: size)-> ();
    /// Sends an OoL payload to `dst`. Returns the OoL payload identifier.
    rpc send(dst: task, addr: vaddr, len: size)-> (id: vaddr);
    /// Checks if the caller task has received a OoL payload from `src` with the
    /// `id`. Returns the receive buffer address if it's valid.
    rpc verify(src: task, id: vaddr, len: size)-> (received_at: vaddr);
}


/// A file system driver.
namespace fs {
    /// Opens a file.
    rpc open(path: str) -> (handle: handle);
    /// Creates a file. If `exist_ok` is true, it return `OK` even if the file
    /// already exists.
    rpc create(path: str, exist_ok: bool) -> (handle: handle);
    /// Closes a file handle.
    rpc close(handle: handle) -> ();
    /// Reads file contents.
    rpc read(handle: handle, offset: offset, len: size) -> (data: bytes);
    /// Writes bytes into the file.
    rpc write(handle: handle, offset: offset, data: bytes) -> ();
    /// Returns file metadata.
    rpc stat(path: str) -> (size: size);
}

/// A block (disk) device interface.
namespace blk {
    /// Reads blocks at `offset` (in bytes) from the device. The size of a block
    /// depends on the device.
    rpc read(sector: offset, num_sectors: size) -> (data: bytes);
    /// Writes blocks at `offset` (in bytes) into the device. The size of a block
    /// depends on the device.
    rpc write(sector: offset, data: bytes) -> ();
}

/// A network device interface.
namespace net {
    /// A RX packet payload.
    oneway rx(payload: bytes);
    /// A TX packet payload to be sent from the device.
    oneway tx(payload: bytes);
}

namespace rtc {
    rpc read() -> (year: uint32, month: uint8, day: uint8, day_of_week: uint8, hour: uint8, minute: uint8, second: uint8);
}

namespace time {
    rpc gettimeofday() -> (unixtime: uint64);
}

namespace shm {
    rpc create(size: size) ->  (shm_id: int);
    rpc map(shm_id: int, writable: bool)   ->  (vaddr: vaddr);
    rpc close(shm_id: int) ->  ();
}

namespace shm_test {
    rpc read()  ->  (shm_id: int);
}

include "servers/*/interface.idl";