MODULES := core/fdt.rad core/platform.rad core/frames.rad core/abi.rad core/handles.rad

CHECK_MODULES := check/boot.rad check/fixture.rad check/frames.rad check/handles.rad

record the contracts established through step 4 of the 22-step plan.

## Handles and rights

- A handle packs kind [63:60], generation [59:28], zero reserved bits [27:24],

  and slot [23:0]. It is domain-relative authority, never a kernel pointer.

  This build has 512 handle slots per domain and up to 512 domains.

- Object identities include kind, index, and nonzero incarnation. Slot generation

  and object incarnation are distinct stale-name defenses. Exhausted generations

  and incarnations are retired rather than wrapped.

- Rights are Read=1, Write=2, Execute=4, Grant=8, Transfer=16, Create=32,

  Allocate=64, Wake=128, Destroy=256; higher bits are reserved. New Page rights

  are Read|Write|Grant|Transfer. New Domain rights are

  Destroy|Execute|Grant|Transfer|Wake; root additionally has Create|Allocate.

Exercise invented and stale names, reserved bits, wrong kinds, rights checks, and generation retirement.

mod handles;

    handles::run();

//! Capability lookup authority, rights, and stale-generation checks.

use core::abi;

use core::handles;

/// Require a handle lookup to fail with the specified error.

fn reject(table: *handles::Table, handle: abi::Handle, kind: abi::Kind, rights: u16, expected: abi::Error) {

    let _entry = try handles::require(table, handle, kind, rights) catch error {

        assert error == expected;

        return;

    };

    panic "reject: invalid authority accepted";

}

/// Exercise packed handles, rights checks, reuse, and generation exhaustion.

export fn run() {

    let mut table: handles::Table = undefined;

    let mut other: handles::Table = undefined;

    handles::init(&mut table);

    handles::init(&mut other);

    let page = abi::Object { kind: abi::Kind::Page, index: 9, epoch: 1 };

    let original = handles::install(&mut table, 0, page, abi::READ);

    let entry = try! handles::require(&table, original, abi::Kind::Page, abi::READ);

    assert entry.object.index == 9 and entry.object.epoch == 1;

    reject(&table, original, abi::Kind::Page, abi::WRITE, abi::Error::Denied);

    reject(&table, original, abi::Kind::Domain, 0, abi::Error::BadHandle);

    reject(&other, original, abi::Kind::Page, 0, abi::Error::BadHandle);

    reject(&table, abi::Handle { bits: 0 }, abi::Kind::Page, 0, abi::Error::BadHandle);

    reject(&table, abi::Handle { bits: original.bits | 0x1000000 }, abi::Kind::Page, 0, abi::Error::BadHandle);

    reject(&table, abi::Handle { bits: original.bits | 0xffffff }, abi::Kind::Page, 0, abi::Error::BadHandle);

    reject(&table, abi::Handle { bits: original.bits ^ (3 as u64 << 60) }, abi::Kind::Page, 0, abi::Error::BadHandle);

    let _removed = handles::remove(&mut table, 0);

    let replacement = handles::install(&mut table, 0, page, abi::READ | abi::WRITE);

    reject(&table, original, abi::Kind::Page, 0, abi::Error::BadHandle);

    let _valid = try! handles::require(&table, replacement, abi::Kind::Page, abi::WRITE);

    let _again = handles::remove(&mut table, 0);

    set table.entries[0].generation = 0xffffffff;

    let last = handles::install(&mut table, 0, page, abi::READ);

    let _last = handles::remove(&mut table, 0);

    reject(&table, last, abi::Kind::Page, 0, abi::Error::BadHandle);

    let next = try! handles::vacant(&table);

    assert next == 1;

    for i in 1..abi::MAX_HANDLES {

        let _handle = handles::install(&mut table, i, page, abi::READ);

    }

    let _slot = try handles::vacant(&table) catch error {

        assert error == abi::Error::Exhausted;

        return;

    };

    panic "run: full capability table accepted an entry";

}

export mod abi;

export mod handles;

//! Stable object kinds, rights, handles, and direct-call errors.

/// Per-domain capability slots in this build.

export constant MAX_HANDLES: u32 = 512;

/// Maximum live domains in this build.

export constant MAX_DOMAINS: u32 = 512;

/// A domain identifier that cannot name a live domain.

export constant INVALID_DOMAIN: u32 = 0xffff;

/// Kernel object kinds in packed-handle order.

export union Kind: Copy {

    /// An unoccupied capability slot.

    Empty,

    /// Contiguous physical memory.

    Page,

    /// One external interrupt source.

    Interrupt,

    /// One device register region.

    Device,

    /// A domain's notification queue.

    Events,

    /// A protection domain.

    Domain,

    /// Finite execution authority on one hart.

    Budget,

}

/// Direct-call error codes in ABI order.

export union Error: Copy {

    /// The operation succeeded.

    Ok,

    /// The handle is absent, stale, malformed, or of the wrong kind.

    BadHandle,

    /// Required capability rights are absent.

    Denied,

    /// No suitable physical memory remains.

    OutOfMemory,

    /// An argument is invalid for this operation.

    InvalidArg,

    /// The resource or a bounded request queue is busy.

    Busy,

    /// Image verification failed.

    VerifyFailed,

    /// The target is not pending activation.

    NotPending,

    /// A bounded kernel resource is fully committed.

    Exhausted,

}

/// Read or derive read-only resource access.

export constant READ: u16 = 1;

/// Write or derive writable resource access.

export constant WRITE: u16 = 2;

/// Activate an execution context.

export constant EXECUTE: u16 = 4;

/// Copy authority to another domain.

export constant GRANT: u16 = 8;

/// Move authority to another domain.

export constant TRANSFER: u16 = 16;

/// Create protection domains.

export constant CREATE: u16 = 32;

/// Allocate from the physical resource pool.

export constant ALLOCATE: u16 = 64;

/// Append a wakeup event to a domain.

export constant WAKE: u16 = 128;

/// Destroy a protection domain.

export constant DESTROY: u16 = 256;

/// All defined rights; high bits are reserved.

export constant RIGHTS: u16 = 511;

/// Rights on a new Page allocation.

export constant PAGE_RIGHTS: u16 = READ | WRITE | GRANT | TRANSFER;

/// Rights on a newly created Domain handle.

export constant DOMAIN_RIGHTS: u16 = DESTROY | EXECUTE | GRANT | TRANSFER | WAKE;

/// Initial root authority on its own Domain.

export constant ROOT_RIGHTS: u16 = DOMAIN_RIGHTS | CREATE | ALLOCATE;

/// A domain-relative packed capability identifier, not a kernel pointer.

export record Handle: Copy {

    /// Kind [63:60], generation [59:28], reserved [27:24], slot [23:0].

    bits: u64,

}

/// Identity of a kernel object across slot reuse.

export record Object: Copy {

    /// Resource table selected by this identity.

    kind: Kind,

    /// Index in that resource table.

    index: u32,

    /// Incarnation of the object slot; zero is never live.

    epoch: u32,

}

//! Domain-local capability lookup and slot generation management.

use core::abi;

/// One authoritative capability-table entry.

export record Entry: Copy {

    /// Named object and its incarnation.

    object: abi::Object,

    /// Rights held through this entry.

    rights: u16,

    /// Slot generation; zero marks permanent retirement.

    generation: u32,

}

/// Fixed storage for a domain's capabilities.

export record Table: Copy {

    /// Live and empty slots; slot positions do not move.

    entries: [Entry; abi::MAX_HANDLES],

}

/// Initialize a table once, before its first domain incarnation.

export fn init(table: *mut Table) {

    for i in 0..abi::MAX_HANDLES {

        set table.entries[i] = Entry {

            object: abi::Object { kind: abi::Kind::Empty, index: 0, epoch: 0 },

            rights: 0, generation: 1,

        };

    }

}

/// Find an empty slot whose generation has not been retired.

export fn vacant(table: *Table) -> u32 throws (abi::Error) {

    for i in 0..abi::MAX_HANDLES {

        let entry = &table.entries[i];

        if entry.object.kind == abi::Kind::Empty and entry.generation <> 0 { return i; }

    }

    throw abi::Error::Exhausted;

}

/// Install authority into a known empty slot and return its packed handle.

export fn install(table: *mut Table, slot: u32, object: abi::Object, rights: u16) -> abi::Handle {

    assert slot < abi::MAX_HANDLES and object.kind <> abi::Kind::Empty and object.epoch <> 0;

    let entry = &mut table.entries[slot];

    assert entry.object.kind == abi::Kind::Empty and entry.generation <> 0;

    set entry.object = object;

    set entry.rights = rights & abi::RIGHTS;

    return abi::Handle {

        bits: (object.kind as u64 << 60) | (entry.generation as u64 << 28) | slot as u64,

    };

}

/// Validate the packed handle and return its authoritative table index.

export fn slot(table: *Table, handle: abi::Handle) -> u32 throws (abi::Error) {

    let bits = handle.bits;

    let index = (bits & 0xffffff) as u32;

    if bits == 0 or (bits & 0xf000000) <> 0 or index >= abi::MAX_HANDLES {

        throw abi::Error::BadHandle;

    }

    let entry = &table.entries[index];

    if entry.object.kind == abi::Kind::Empty or (bits >> 60) <> entry.object.kind as u64

        or ((bits >> 28) & 0xffffffff) <> entry.generation as u64 {

        throw abi::Error::BadHandle;

    }

    return index;

}

/// Require a live handle of the given kind with all requested rights.

/// The object owner must also check the object's epoch and lifecycle.

export fn require(table: *Table, handle: abi::Handle, kind: abi::Kind, rights: u16) -> Entry throws (abi::Error) {

    let index = try slot(table, handle);

    let entry = table.entries[index];

    if entry.object.kind <> kind { throw abi::Error::BadHandle; }

    if entry.rights & rights <> rights { throw abi::Error::Denied; }

    return entry;

}

/// Invalidate a slot before reuse and return its former authority.

/// Generation exhaustion permanently retires the slot.

export fn remove(table: *mut Table, index: u32) -> Entry {

    assert index < abi::MAX_HANDLES;

    let previous = table.entries[index];

    assert previous.object.kind <> abi::Kind::Empty;

    let entry = &mut table.entries[index];

    set entry.object = abi::Object { kind: abi::Kind::Empty, index: 0, epoch: 0 };

    set entry.rights = 0;

    if previous.generation == 0xffffffff {

        set entry.generation = 0;

    } else {

        set entry.generation = previous.generation + 1;

    }

    return previous;

}

/// Read a live slot by kind without constructing a handle from an index.

export fn get(table: *Table, index: u32, kind: abi::Kind) -> abi::Handle throws (abi::Error) {

    if index >= abi::MAX_HANDLES or kind == abi::Kind::Empty { throw abi::Error::BadHandle; }

    let entry = &table.entries[index];

    if entry.object.kind <> kind { throw abi::Error::BadHandle; }

    return abi::Handle {

        bits: (kind as u64 << 60) | (entry.generation as u64 << 28) | index as u64,

    };

}