core/events.rad core/domains.rad core/resources.rad core/capabilities.rad

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

	check/domains.rad check/capabilities.rad

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

## Capability transactions

- Grant intersects requested rights with source rights. A grant to another

  domain requires Grant; a self-grant may attenuate without that right.

- Transfer requires Transfer and a different target domain. Check the source,

  live target, and destination capacity before moving authority. Failure leaves

  the source usable. Object liveness is checked independently of the handle.

- Events cannot cross domains; the installed Events handle cannot be dropped.

  Interrupt authority cannot be granted and moves exclusively by transfer.

- Dropping a handle removes authority to invoke operations through that name

  and releases its object reference.

Exercise attenuation, self-grants, failed transfers with an intact source, Events locality, Interrupt exclusivity, and stale aliases.

mod capabilities;

    capabilities::run();

//! Capability mutation contracts across independent domain tables.

use core::abi;

use core::capabilities;

use core::domains;

use core::fdt;

use core::handles;

use core::resources;

/// Domain storage for capability transactions.

static DOMAINS: [domains::Domain; 3] = undefined;

/// Physical resources used by the transactions.

static OBJECTS: [resources::Slot; 4] = undefined;

/// Return a grant error as a test value.

fn grantError(source: abi::Handle, target: abi::Handle) -> abi::Error {

    let _handle = try capabilities::grant(&mut DOMAINS[..], &mut OBJECTS[..], 0, source, target, abi::RIGHTS as u64) catch error {

        return error;

    };

    return abi::Error::Ok;

}

/// Check attenuation, non-delegable queues, unique IRQs, and failed moves.

export fn run() {

    domains::init(&mut DOMAINS[..]);

    resources::init(&mut OBJECTS[..]);

    let rootHandle = domains::root(&mut DOMAINS[..], 0);

    let root = try! domains::resolve(&DOMAINS[..], 0, rootHandle, abi::CREATE);

    let child = try! domains::create(&mut DOMAINS[..], root, 1);

    let childHandle = handles::install(&mut DOMAINS[0].handles, 2, child, abi::DOMAIN_RIGHTS);

    let device = try! resources::create(&mut OBJECTS[..], resources::Value::Device(fdt::Range { base: 0x10000000, size: 256 }));

    let source = handles::install(&mut DOMAINS[0].handles, 3, device, abi::READ | abi::GRANT | abi::TRANSFER);

    resources::retain(&mut OBJECTS[..], device);

    let shared = try! capabilities::grant(&mut DOMAINS[..], &mut OBJECTS[..], 0, source, childHandle, (abi::READ | abi::WRITE) as u64);

    let authority = try! capabilities::lookup(&DOMAINS[..], &OBJECTS[..], child.index, shared);

    assert authority.rights == abi::READ;

    let _source = try! capabilities::lookup(&DOMAINS[..], &OBJECTS[..], 0, source);

    let narrowed = try! capabilities::grant(&mut DOMAINS[..], &mut OBJECTS[..], child.index, shared, abi::Handle { bits: 0 }, abi::READ as u64);

    let _local = try! capabilities::lookup(&DOMAINS[..], &OBJECTS[..], child.index, narrowed);

    let queue = try! handles::get(&DOMAINS[0].handles, 1, abi::Kind::Events);

    assert grantError(queue, childHandle) == abi::Error::Denied;

    let readQueue = try! capabilities::grant(&mut DOMAINS[..], &mut OBJECTS[..], 0, queue, abi::Handle { bits: 0 }, abi::READ as u64);

    try! capabilities::drop(&mut DOMAINS[..], &mut OBJECTS[..], 0, readQueue);

    try capabilities::drop(&mut DOMAINS[..], &mut OBJECTS[..], 0, queue) catch error {

        assert error == abi::Error::Denied;

    };

    let _queue = try! capabilities::lookup(&DOMAINS[..], &OBJECTS[..], 0, queue);

    let irq = try! resources::create(&mut OBJECTS[..], resources::Value::Interrupt(resources::Interrupt { number: 10, target: root }));

    let irqSlot = try! handles::vacant(&DOMAINS[0].handles);

    let interrupt = handles::install(&mut DOMAINS[0].handles, irqSlot, irq, abi::TRANSFER);

    resources::retain(&mut OBJECTS[..], irq);

    assert grantError(interrupt, childHandle) == abi::Error::Denied;

    assert grantError(interrupt, abi::Handle { bits: 0 }) == abi::Error::Denied;

    let moved = try! capabilities::transfer(&mut DOMAINS[..], &mut OBJECTS[..], 0, interrupt, childHandle, abi::TRANSFER as u64);

    let _receiver = try! capabilities::lookup(&DOMAINS[..], &OBJECTS[..], child.index, moved);

    let _old = try capabilities::lookup(&DOMAINS[..], &OBJECTS[..], 0, interrupt) catch error {

        assert error == abi::Error::BadHandle;

        for i in 0..abi::MAX_HANDLES - 4 {

            let _copy = try! capabilities::grant(&mut DOMAINS[..], &mut OBJECTS[..], 0, source, childHandle, abi::READ as u64);

        }

        let _failed = try capabilities::transfer(&mut DOMAINS[..], &mut OBJECTS[..], 0, source, childHandle, abi::READ as u64) catch full {

            assert full == abi::Error::InvalidArg;

            let _stillLive = try! capabilities::lookup(&DOMAINS[..], &OBJECTS[..], 0, source);

            try! capabilities::drop(&mut DOMAINS[..], &mut OBJECTS[..], 0, childHandle);

            assert domains::live(&DOMAINS[..], child);

            return;

        };

        panic "run: transfer into a full table succeeded";

    };

    panic "run: transferred source remained live";

}

export mod resources;

export mod capabilities;

//! Validated capability grants, transfers, and drops under the kernel lock.

use core::abi;

use core::domains;

use core::handles;

use core::resources;

/// Resolve source authority and check the named object's incarnation.

export fn lookup(store: *[domains::Domain], objects: *[resources::Slot], caller: u32, handle: abi::Handle) -> handles::Entry throws (abi::Error) {

    let slot = try handles::slot(&store[caller].handles, handle);

    let entry = store[caller].handles.entries[slot];

    if not resources::live(objects, store, entry.object) { throw abi::Error::BadHandle; }

    return entry;

}

/// Copy authority with attenuation after all failure checks complete.

export fn grant(store: *mut [domains::Domain], objects: *mut [resources::Slot], caller: u32, source: abi::Handle, target: abi::Handle, rights: u64) -> abi::Handle throws (abi::Error) {

    let entry = try lookup(store, objects, caller, source);

    let mut recipient = abi::Object { kind: abi::Kind::Domain, index: caller, epoch: store[caller].epoch };

    if target.bits <> 0 { set recipient = try domains::resolve(store, caller, target, 0); }

    if entry.object.kind == abi::Kind::Interrupt { throw abi::Error::Denied; }

    if recipient.index <> caller {

        if entry.object.kind == abi::Kind::Events or entry.rights & abi::GRANT == 0 {

            throw abi::Error::Denied;

        }

    }

    let slot = try handles::vacant(&store[recipient.index].handles) catch { throw abi::Error::InvalidArg; };

    resources::retain(objects, entry.object);

    return handles::install(&mut store[recipient.index].handles, slot, entry.object, entry.rights & rights as u16);

}

/// Move authority as one transaction; failure leaves the source live.

export fn transfer(store: *mut [domains::Domain], objects: *mut [resources::Slot], caller: u32, source: abi::Handle, target: abi::Handle, rights: u64) -> abi::Handle throws (abi::Error) {

    let entry = try lookup(store, objects, caller, source);

    let recipient = try domains::resolve(store, caller, target, 0);

    if recipient.index == caller { throw abi::Error::InvalidArg; }

    if entry.object.kind == abi::Kind::Events or entry.rights & abi::TRANSFER == 0 {

        throw abi::Error::Denied;

    }

    let slot = try handles::vacant(&store[recipient.index].handles) catch { throw abi::Error::InvalidArg; };

    let sourceSlot = try handles::slot(&store[caller].handles, source);

    resources::retarget(objects, entry.object, recipient);

    let result = handles::install(&mut store[recipient.index].handles, slot, entry.object, entry.rights & rights as u16);

    let _previous = handles::remove(&mut store[caller].handles, sourceSlot);

    return result;

}

/// Drop a live local capability without revoking persistent pointer access.

export fn drop(store: *mut [domains::Domain], objects: *mut [resources::Slot], caller: u32, handle: abi::Handle) throws (abi::Error) {

    let entry = try lookup(store, objects, caller, handle);

    let slot = try handles::slot(&store[caller].handles, handle);

    if entry.object.kind == abi::Kind::Events and slot == 1 { throw abi::Error::Denied; }

    let _previous = handles::remove(&mut store[caller].handles, slot);

    resources::release(objects, entry.object);

}

//! Physical object identities shared by capability entries.

use core::abi;

use core::domains;

use core::fdt;

/// An exclusive external interrupt source.

export record Interrupt: Copy {

    /// PLIC source number.

    number: u32,

    /// Current receiving domain, or the empty identity.

    target: abi::Object,

}

/// Resource data that determines the authoritative object kind.

export union Value: Copy {

    /// Unoccupied object slot.

    Free,

    /// User-visible MMIO register range.

    Device(fdt::Range),

    /// Exclusively held external interrupt source.

    Interrupt(Interrupt),

}

/// One resource slot and its live handle count.

export record Slot: Copy {

    /// Type-specific physical resource state.

    value: Value,

    /// Incarnation of the slot; exhausted epochs are never reused.

    epoch: u32,

    /// Number of live capability entries that name this resource.

    references: u32,

}

/// Get the kind associated with a resource value.

export fn kind(value: Value) -> abi::Kind {

    match value {

        case Value::Free => return abi::Kind::Empty,

        case Value::Device(_) => return abi::Kind::Device,

        case Value::Interrupt(_) => return abi::Kind::Interrupt,

    }

}

/// Initialize caller-owned physical resource storage once at boot.

export fn init(slots: *mut [Slot]) {

    for i in 0..slots.len {

        set slots[i] = Slot { value: Value::Free, epoch: 0, references: 0 };

    }

}

/// Install a physical resource before its first capability is published.

export fn create(slots: *mut [Slot], value: Value) -> abi::Object throws (abi::Error) {

    assert kind(value) <> abi::Kind::Empty;

    for i in 0..slots.len {

        let slot = &mut slots[i];

        if kind(slot.value) == abi::Kind::Empty and slot.epoch < 0xffffffff {

            set slot.epoch += 1;

            set slot.value = value;

            set slot.references = 0;

            return abi::Object { kind: kind(value), index: i, epoch: slot.epoch };

        }

    }

    throw abi::Error::Exhausted;

}

/// Check a physical-resource incarnation or a live domain-owned object.

export fn live(slots: *[Slot], domainStore: *[domains::Domain], object: abi::Object) -> bool {

    if object.kind == abi::Kind::Domain { return domains::live(domainStore, object); }

    if object.kind == abi::Kind::Events {

        return domains::live(domainStore, abi::Object {

            kind: abi::Kind::Domain, index: object.index, epoch: object.epoch,

        });

    }

    if object.kind == abi::Kind::Empty or object.index >= slots.len { return false; }

    let slot = &slots[object.index];

    return slot.epoch == object.epoch and object.epoch <> 0 and kind(slot.value) == object.kind;

}

/// Account for one newly installed physical-resource handle.

export fn retain(slots: *mut [Slot], object: abi::Object) {

    if object.kind == abi::Kind::Domain or object.kind == abi::Kind::Events { return; }

    let slot = &mut slots[object.index];

    assert slot.epoch == object.epoch and kind(slot.value) == object.kind;

    assert slot.references < abi::MAX_DOMAINS * abi::MAX_HANDLES;

    set slot.references += 1;

}

/// Account for one removed physical-resource handle.

export fn release(slots: *mut [Slot], object: abi::Object) {

    if object.kind == abi::Kind::Domain or object.kind == abi::Kind::Events { return; }

    let slot = &mut slots[object.index];

    assert slot.epoch == object.epoch and kind(slot.value) == object.kind and slot.references > 0;

    set slot.references -= 1;

    if let case Value::Interrupt(irq) = &mut slot.value {

        assert slot.references == 0;

        set irq.target = domains::none();

    }

}

/// Change the exclusive receiver before an Interrupt transfer becomes visible.

export fn retarget(slots: *mut [Slot], object: abi::Object, target: abi::Object) {

    if object.kind <> abi::Kind::Interrupt { return; }

    let slot = &mut slots[object.index];

    match &mut slot.value {

        case Value::Interrupt(irq) => set irq.target = target,

        else => panic "retarget: object kind mismatch",

    }

}