export mod abi;

export mod limits;

export mod slots;

//! Kernel handle representation, rights, errors, and operation numbers.

/// Domain-relative capability value. Zero is the self sentinel where allowed.

export record Handle: Copy(u64);

/// Rights granted by a live capability-table entry.

export record Rights: Copy(u16);

/// Read object contents or metadata.

export constant READ: u16 = 1;

/// Modify object contents.

export constant WRITE: u16 = 2;

/// Execute an image or entry.

export constant EXECUTE: u16 = 4;

/// Grant an attenuated capability.

export constant GRANT: u16 = 8;

/// Transfer a capability or CPU authority.

export constant TRANSFER: u16 = 16;

/// Create a domain.

export constant CREATE: u16 = 32;

/// Allocate physical memory.

export constant ALLOCATE: u16 = 64;

/// Wake or manage the parent relationship of a domain.

export constant WAKE: u16 = 128;

/// Destroy a domain.

export constant DESTROY: u16 = 256;

/// All defined right bits.

export constant RIGHTS_MASK: u16 = 511;

/// Cascade destruction through creation ancestry.

export constant CASCADE: u64 = 1;

/// Object kind stored in the high four handle bits.

export union Kind: Copy {

    /// Unoccupied table entry.

    Empty = 0,

    /// Contiguous physical memory.

    Page = 1,

    /// Interrupt source ownership.

    Interrupt = 2,

    /// Device memory region.

    Device = 3,

    /// Domain notification queue.

    Events = 4,

    /// Domain management authority.

    Domain = 5,

    /// Exclusive CPU time window.

    Budget = 6,

    /// Resident executable package graph entry.

    Image = 7,

}

/// Scalar error codes; the syscall ABI returns their negatives.

export union Error: Copy {

    /// Successful operation.

    Ok = 0,

    /// Missing, stale, or incorrectly typed handle.

    BadHandle = 1,

    /// Required rights are absent.

    Denied = 2,

    /// Physical memory is exhausted.

    OutOfMemory = 3,

    /// Invalid argument, alignment, or reserved bits.

    InvalidArg = 4,

    /// The operation cannot proceed in the current state.

    Busy = 5,

    /// The supplied executable image is invalid.

    VerifyFailed = 6,

    /// The domain is not pending activation.

    NotPending = 7,

    /// Fixed kernel storage is exhausted.

    Exhausted = 8,

}

/// Operation identifier passed in a7.

export union Operation: Copy {

    /// Grant capability rights.

    CapabilityGrant = 10,

    /// Transfer a capability.

    CapabilityTransfer = 11,

    /// Drop a capability.

    CapabilityDrop = 12,

    /// Create a pending domain from an image.

    DomainCreate = 20,

    /// Activate a pending domain.

    DomainActivate = 21,

    /// Destroy a domain.

    DomainDestroy = 22,

    /// Select a new lifecycle-event parent.

    DomainReparent = 23,

    /// Allocate physical frames.

    PageAllocate = 30,

    /// Split an exclusive page object.

    PageSplit = 31,

    /// Transfer the remaining active window to a target domain.

    Yield = 40,

    /// Request a timeout event.

    Timeout = 41,

    /// Wait for an event.

    Wait = 42,

    /// Terminate with an abort report.

    Abort = 43,

    /// Query page metadata.

    QueryPage = 44,

    /// Query device metadata.

    QueryDevice = 45,

    /// Query interrupt metadata.

    QueryInterrupt = 46,

    /// Query domain metadata.

    QueryDomain = 47,

    /// Query event queue metadata.

    QueryEvents = 48,

    /// Terminate normally.

    Exit = 49,

    /// Deliver a wake token.

    Wakeup = 50,

    /// Load a trusted binary RIL package.

    ImageLoad = 51,

    /// Query a resident image.

    QueryImage = 52,

    /// Create an additional execution context.

    ContextCreate = 60,

    /// Destroy an additional execution context.

    ContextDestroy = 61,

    /// Query an execution context.

    QueryContext = 62,

    /// Query the current context and execution window.

    CurrentContext = 63,

    /// Partition a CPU time window.

    BudgetSplit = 70,

    /// Combine adjacent CPU time windows.

    BudgetMerge = 71,

    /// Query a CPU time window.

    QueryBudget = 72,

    /// Bind and transfer a CPU time window to a context.

    BudgetBind = 73,

}

/// Generation-bearing reference within one object table.

export record Ref: Copy {

    /// Table index.

    index: u32,

    /// Generation of the indexed slot.

    generation: u32,

}

/// Structurally valid handle fields. Lookup must also check the live table entry.

export record Decoded: Copy {

    /// Encoded object kind.

    kind: Kind,

    /// Table slot and generation.

    object: Ref,

}

/// Pack kind, 32-bit generation, and 24-bit index with zero reserved bits.

export fn handle(kind: Kind, object: Ref) -> Handle throws (Error) {

    if kind == Kind::Empty or object.index > 0xffffff {

        throw Error::InvalidArg;

    }

    return Handle((kind as u64 << 60) | (object.generation as u64 << 28) | object.index as u64);

}

/// Decode a nonzero handle and reject reserved bits or unsupported kinds.

export fn decode(value: Handle) -> Decoded throws (Error) {

    let bits = *value;

    if bits == 0 or (bits & 0x0f000000) <> 0 {

        throw Error::BadHandle;

    }

    let mut kind = Kind::Empty;

    match bits >> 60 {

        case 1 => set kind = Kind::Page,

        case 2 => set kind = Kind::Interrupt,

        case 3 => set kind = Kind::Device,

        case 4 => set kind = Kind::Events,

        case 5 => set kind = Kind::Domain,

        case 6 => set kind = Kind::Budget,

        case 7 => set kind = Kind::Image,

        else => throw Error::BadHandle,

    }

    return Decoded { kind, object: Ref { index: (bits & 0xffffff) as u32, generation: (bits >> 28) as u32 } };

}

/// Validate a caller-supplied rights mask.

export fn rights(bits: u64) -> Rights throws (Error) {

    if (bits & ~(RIGHTS_MASK as u64)) <> 0 {

        throw Error::InvalidArg;

    }

    return Rights(bits as u16);

}

/// Check that all requested rights are present.

export fn permits(granted: Rights, requested: Rights) -> bool {

    return (*granted & *requested) == *requested;

}

/// Encode a generation-bearing internal ID without reserved bits.

export fn id(object: Ref) -> u64 {

    return (object.generation as u64 << 32) | object.index as u64;

}

/// Decode an internal ID. Object lookup validates its scope and liveness.

export fn reference(value: u64) -> Ref {

    return Ref { index: value as u32, generation: (value >> 32) as u32 };

}

//! Fixed kernel storage profile.

/// Maximum resident domains, including retained tombstones.

export constant DOMAINS: u32 = 512;

/// Per-domain capability table capacity.

export constant HANDLES: u32 = 512;

/// Maximum physical frames tracked by this build.

export constant FRAMES: u32 = 65536;

/// Physical frame size in bytes.

export constant FRAME_SIZE: u64 = 4096;

/// Maximum page objects, including split allocation segments.

export constant PAGES: u32 = 65536;

/// Maximum backing allocation records.

export constant ALLOCATIONS: u32 = 65536;

/// Maximum interrupt objects.

export constant INTERRUPTS: u32 = 128;

/// Maximum device memory regions.

export constant DEVICES: u32 = 128;

/// Maximum budget objects.

export constant BUDGETS: u32 = 512;

/// Maximum execution contexts across all domains.

export constant CONTEXTS: u32 = 2048;

/// Maximum hardware threads.

export constant HARTS: u32 = 8;

/// Maximum resident package records and gp table entries.

export constant PACKAGES: u32 = 256;

/// Generation values never wrap.

export constant LAST_GENERATION: u32 = 0xffffffff;

//! Bounded slot lifetimes and linear reservations.

use super::abi;

use super::limits;

/// Slot lifetime state.

export union State: Copy {

    /// Available for reservation.

    Free,

    /// Owned by an uncommitted reservation.

    Reserved,

    /// Published object.

    Live,

    /// Generation space is exhausted; the slot cannot be reused.

    Retired,

}

/// Metadata stored beside an object table's payload array.

export record Slot: Copy {

    /// Current nonzero generation.

    generation: u32,

    /// Current lifetime state.

    state: State,

}

/// A reserved slot that must be committed or cancelled in the same table.

export union Reservation: Once {

    /// Unpublished object slot.

    Held(abi::Ref),

}

/// Initialize fresh metadata. No live references may name this table.

export fn initialize(slots: &mut [Slot]) {

    for i in 0..slots.len {

        set slots[i] = Slot { generation: 1, state: State::Free };

    }

}

/// Reserve the first available slot with a bounded scan.

export fn reserve(slots: &mut [Slot]) -> Reservation throws (abi::Error) {

    for i in 0..slots.len {

        if slots[i].state == State::Free {

            set slots[i].state = State::Reserved;

            return Reservation::Held(abi::Ref { index: i, generation: slots[i].generation });

        }

    }

    throw abi::Error::Exhausted;

}

/// Check an internal reference against its table and required lifetime state.

export fn matches(slots: &[Slot], object: abi::Ref, state: State) -> bool {

    return object.index < slots.len and slots[object.index].generation == object.generation

        and slots[object.index].state == state;

}

/// Inspect a reservation's unpublished reference without consuming it.

export fn reference(reservation: &Reservation) -> abi::Ref {

    match reservation { case Reservation::Held(object) => return *object, }

}

/// Publish a reserved slot. The caller must initialize its payload first.

export fn commit(slots: &mut [Slot], reservation: Reservation) -> abi::Ref throws (abi::Error) {

    match reservation {

        case Reservation::Held(object) => {

            if not matches(slots, object, State::Reserved) {

                throw abi::Error::BadHandle;

            }

            set slots[object.index].state = State::Live;

            return object;

        },

    }

}

/// Advance the slot generation or retire it permanently.

fn advance(slot: &mut Slot) {

    if slot.generation == limits::LAST_GENERATION {

        set slot.state = State::Retired;

    }

    else {

        set slot.generation += 1;

        set slot.state = State::Free;

    }

}

/// Cancel a reservation and invalidate its generation.

export fn cancel(slots: &mut [Slot], reservation: Reservation) throws (abi::Error) {

    match reservation {

        case Reservation::Held(object) => {

            if not matches(slots, object, State::Reserved) {

                throw abi::Error::BadHandle;

            }

            advance(&mut slots[object.index]);

        },

    }

}

/// Invalidate a live object after all payload-specific teardown is complete.

export fn release(slots: &mut [Slot], object: abi::Ref) throws (abi::Error) {

    if not matches(slots, object, State::Live) {

        throw abi::Error::BadHandle;

    }

    advance(&mut slots[object.index]);

}

export mod abi;

export mod slots;

//! Handle bit boundaries and stable ABI values.

use std::testing;

use kernel::abi;

/// Check every kind at the index and generation boundaries.

@test fn handles() throws (testing::TestError) {

    for kind in &[abi::Kind::Page, abi::Kind::Interrupt, abi::Kind::Device,

        abi::Kind::Events, abi::Kind::Domain, abi::Kind::Budget, abi::Kind::Image]

    {

        for index in &[0 as u32, 0xffffff as u32] {

            for generation in &[0 as u32, 1 as u32, 0xffffffff as u32] {

                let object = abi::Ref { index, generation };

                let value = try! abi::handle(kind, object);

                let decoded = try! abi::decode(value);

                try testing::expect(decoded.kind == kind and decoded.object == object);

                try testing::expect((*value & 0x0f000000) == 0);

                try testing::expect(abi::reference(abi::id(object)) == object);

            }

        }

    }

    let maximum = try! abi::handle(abi::Kind::Image, abi::Ref { index: 0xffffff, generation: 0xffffffff });

    try testing::expect(*maximum == 0x7ffffffff0ffffff);

}

/// Reject self, empty/unsupported kinds, reserved bits, and oversized indices.

@test fn invalidHandles() throws (testing::TestError) {

    let mut failed: u32 = 0;

    for bits in &[0 as u64, 1 as u64, 0x8000000000000000, 0xf000000000000000,

        0x1000000001000000, 0x1000000002000000, 0x1000000004000000, 0x1000000008000000]

    {

        try abi::decode(abi::Handle(bits)) catch err {

            try testing::expect(err == abi::Error::BadHandle); set failed += 1;

        };

    }

    try testing::expect(failed == 8);

    try abi::handle(abi::Kind::Page, abi::Ref { index: 0x1000000, generation: 1 }) catch err {

        try testing::expect(err == abi::Error::InvalidArg); set failed += 1;

    };

    try testing::expect(failed == 9);

}

/// Check rights validation and the specified error/operation numbers.

@test fn numbersAndRights() throws (testing::TestError) {

    let all = try! abi::rights(511);

    let read = try! abi::rights(abi::READ as u64);

    try testing::expect(abi::permits(all, read) and not abi::permits(read, all));

    let mut failed = false;

    try abi::rights(512) catch err {

        try testing::expect(err == abi::Error::InvalidArg);

        set failed = true;

    };

    try testing::expect(failed);

    try testing::expect(abi::Operation::CapabilityGrant as u32 == 10);

    try testing::expect(abi::Operation::DomainReparent as u32 == 23);

    try testing::expect(abi::Operation::PageAllocate as u32 == 30);

    try testing::expect(abi::Operation::Yield as u32 == 40);

    try testing::expect(abi::Operation::Wakeup as u32 == 50);

    try testing::expect(abi::Error::BadHandle as u32 == 1 and abi::Error::Exhausted as u32 == 8);

}

//! Slot reservation, publication, cancellation, and generation retirement.

use std::testing;

use kernel::abi;

use kernel::slots;

/// Reservations occupy capacity before publication and must be consumed once.

@test unsafe fn lifetime() throws (testing::TestError) {

    let mut table: [slots::Slot; 2] = undefined;

    slots::initialize(&mut table[..]);

    let first = try! slots::reserve(&mut table[..]);

    let pending = slots::reference(&first);

    let reserved = slots::matches(&table[..], pending, slots::State::Reserved);

    let second = try! slots::reserve(&mut table[..]);

    let left = try! slots::commit(&mut table[..], first);

    let right = try! slots::commit(&mut table[..], second);

    try testing::expect(reserved and left.index == 0 and right.index == 1);

    let mut exhausted = false;

    try reserveAndCancel(&mut table[..]) catch err {

        try testing::expect(err == abi::Error::Exhausted); set exhausted = true;

    };

    try testing::expect(exhausted);

    try! slots::release(&mut table[..], left);

    try testing::expect(not slots::matches(&table[..], left, slots::State::Live));

    let replacement = try! slots::reserve(&mut table[..]);

    let next = try! slots::commit(&mut table[..], replacement);

    try testing::expect(next.index == left.index and next.generation == left.generation + 1);

    let mut stale = false;

    try slots::release(&mut table[..], left) catch err {

        try testing::expect(err == abi::Error::BadHandle); set stale = true;

    };

    try testing::expect(stale and slots::matches(&table[..], next, slots::State::Live));

}

/// Cancellation invalidates references and exhausted generations never wrap.

@test unsafe fn cancellationAndRetirement() throws (testing::TestError) {

    let mut table: [slots::Slot; 1] = undefined;

    slots::initialize(&mut table[..]);

    let token = try! slots::reserve(&mut table[..]);

    let old = slots::reference(&token);

    try! slots::cancel(&mut table[..], token);

    try testing::expect(table[0].state == slots::State::Free and table[0].generation == old.generation + 1);

    set table[0].generation = 0xffffffff;

    let last = try! slots::reserve(&mut table[..]);

    let object = try! slots::commit(&mut table[..], last);

    try! slots::release(&mut table[..], object);

    try testing::expect(table[0].state == slots::State::Retired and table[0].generation == 0xffffffff);

    let mut failed = false;

    try reserveAndCancel(&mut table[..]) catch err {

        try testing::expect(err == abi::Error::Exhausted); set failed = true;

    };

    try testing::expect(failed);

    set table[0].state = slots::State::Free;

    let cancelled = try! slots::reserve(&mut table[..]);

    try! slots::cancel(&mut table[..], cancelled);

    try testing::expect(table[0].state == slots::State::Retired);

}

/// Consume a reservation when a capacity check unexpectedly succeeds.

fn reserveAndCancel(table: &mut [slots::Slot]) throws (abi::Error) {

    let token = try slots::reserve(table);

    try slots::cancel(table, token);

}

//! Compile-failure fixture for an unconsumed reservation.

use std::testing;

use kernel::slots;

/// A reservation must be consumed before its scope ends.

@test unsafe fn abandon() throws (testing::TestError) {

    let mut table: [slots::Slot; 1] = undefined;

    slots::initialize(&mut table[..]);

    let token = try! slots::reserve(&mut table[..]);

}

//! Compile-failure fixture for repeated reservation consumption.

use std::testing;

use kernel::slots;

/// A reservation cannot be cancelled twice.

@test unsafe fn duplicate() throws (testing::TestError) {

    let mut table: [slots::Slot; 1] = undefined;

    slots::initialize(&mut table[..]);

    let token = try! slots::reserve(&mut table[..]);

    try! slots::cancel(&mut table[..], token);

    try! slots::cancel(&mut table[..], token);

}

#!/bin/sh

# Check that reservation misuse fails during compilation.

set -eu

emulator=$1

shift

work=$(mktemp -d)

trap 'rm -rf "$work"' EXIT HUP INT TERM

for name in duplicate abandon; do

    case "$name" in

        duplicate) diagnostic='linear value used after consumption' ;;

        abandon) diagnostic='linear value is not consumed' ;;

    esac

    if "$emulator" -memory-size=385024 -data-size=348160 -stack-size=512 \

        -run bin/radiance.rv64.dev "$@" -test \

        -pkg "$name" -mod "test/slots/$name.rad" -entry "$name" \

        -o "$work/test.rv64" > "$work/log" 2>&1; then

        printf 'reservation misuse compiled: %s\n' "$name" >&2

        exit 1

    fi

    if ! grep -q "$diagnostic" "$work/log"; then

        cat "$work/log" >&2

        exit 1

    fi

    printf 'reservation rejection: %s passed\n' "$name"

done