GKaszewski/k-os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(kernel): SystemControl cap for halt, board device table + boot caps to init, RegionAddress syscall, idle loop services irqs

Browse Source
This commit is contained in:
Gabriel Kaszewski
2026-10-26 23:59:57 +01:00
parent 130a82f50d
commit bafc18a5f8
21 changed files with 626 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
crates/kernel/src/abi.rs
View File

@@ -40,7 +40,9 @@ fn message(a: &[usize; 6]) -> Option<Message> {
pub fn decode(nr: usize, a: &[usize; 6]) -> Option<Syscall> {
Some(match nr {
SYS_EXIT => Syscall::Exit,
SYS_HALT => Syscall::Halt,
SYS_HALT => Syscall::Halt {
control: slot(a[0])?,
},
SYS_EXIT_THREAD => Syscall::ExitThread,
SYS_YIELD => Syscall::Yield,
SYS_GET_TIME => Syscall::GetTime,
@@ -125,6 +127,9 @@ pub fn decode(nr: usize, a: &[usize; 6]) -> Option<Syscall> {
va: VirtualAddress::from_raw(a[1]),
perms: reg_perms(a[2])?,
},
SYS_REGION_ADDRESS => Syscall::RegionAddress {
region: slot(a[0])?,
},
SYS_DEBUG_PUTCHAR => Syscall::DebugPutchar { byte: a[0] as u8 },
SYS_MAP_PAGE => Syscall::MapPage {
process: slot(a[0])?,

79
crates/kernel/src/board.rs Normal file
View File

@@ -0,0 +1,79 @@
//! The authority init starts with. The board describes its devices; the
//! kernel turns each into capabilities (an MMIO region and an IRQ line)
//! and adds one SystemControl capability. Init then decides who gets what;
//! nothing else is privileged by its process id.
use domain::{error::KernelError, resource::Resource};
use platform::Platform;
use types::{
address::PhysicalAddress,
bounded::PageCount,
id::{IrqId, ProcessId, RegionId},
permission::{Permission, PermissionSet},
};
use crate::Kernel;
/// A device the board exposes to userspace: its MMIO window and, if it
/// raises interrupts, its IRQ line.
#[derive(Debug, Clone, Copy)]
pub struct BoardDevice {
pub base: PhysicalAddress,
pub pages: PageCount,
pub irq: Option<IrqId>,
}
impl<P: Platform> Kernel<P> {
/// Creates one device region per board device, owned by `init`. Fails
/// on the first device that is misaligned, overlaps the frame pool or
/// another device, or names an IRQ the kernel cannot route.
pub fn register_board(
&mut self,
init: ProcessId,
devices: &[BoardDevice],
) -> Result<(), KernelError> {
for device in devices {
if let Some(irq) = device.irq
&& !self.irqs.is_valid(irq)
{
return Err(KernelError::InvalidIrq(irq));
}
self.create_device_region(init, device.base, device.pages)?;
}
Ok(())
}
/// Gives `init` a capability to every registered device's region and
/// IRQ line, then one SystemControl capability. All carry Delegate so
/// init can hand them on. Done separately from `register_board` so
/// boot code can wire drivers to the regions first.
pub fn grant_boot_authority(
&mut self,
init: ProcessId,
devices: &[BoardDevice],
) -> Result<(), KernelError> {
let delegate = PermissionSet::empty().with(Permission::Delegate);
let control = delegate.with(Permission::Execute);
let mmio = delegate.with(Permission::Read).with(Permission::Write);
for device in devices {
let region = self
.device_region_at(device.base)
.filter(|id| self.regions.get(*id).is_some_and(|r| r.owner() == init))
.ok_or(KernelError::NoSuchObject)?;
self.grant_cap(init, Resource::Memory(region), mmio)?;
if let Some(irq) = device.irq {
self.grant_cap(init, Resource::Interrupt(irq), control)?;
}
}
self.grant_cap(init, Resource::SystemControl, control)?;
Ok(())
}
/// The device region that starts at `base`.
pub fn device_region_at(&self, base: PhysicalAddress) -> Option<RegionId> {
self.regions
.iter()
.find(|(_, r)| r.backing() == domain::memory::RegionBacking::Device && r.base() == base)
.map(|(id, _)| id)
}
}

6
crates/kernel/src/lib.rs
View File

@@ -15,6 +15,7 @@
)]
pub mod abi;
mod board;
mod captree;
pub mod interrupt;
mod memory;
@@ -22,6 +23,7 @@ mod memory;
pub mod proofs;
pub mod syscall;
pub use board::BoardDevice;
pub use syscall::{SyscallOutcome, SyscallResult};
#[cfg(test)]
@@ -388,7 +390,9 @@ impl<P: Platform> Kernel<P> {
Resource::Memory(id) => self.regions.generation(*id),
Resource::Notification(id) => self.notifications.generation(*id),
Resource::Process(pid) => self.processes.generation(*pid),
Resource::Interrupt(_) | Resource::ProcessCreate => Some(Generation::initial()),
Resource::Interrupt(_) | Resource::ProcessCreate | Resource::SystemControl => {
Some(Generation::initial())
}
}
}

18
crates/kernel/src/memory.rs
View File

@@ -325,11 +325,23 @@ impl<P: Platform> Kernel<P> {
}
// Device memory must never alias frames the kernel hands out.
let len = pages.value() as usize * PAGE_SIZE;
let start = base.raw();
let end = start.checked_add(len).ok_or(KernelError::InvalidAddress)?;
let pool_start = self.frames.base().raw();
let pool_end = pool_start + self.frames.capacity() * PAGE_SIZE;
if base.raw() < pool_end && base.raw() + len > pool_start {
if start < pool_end && end > pool_start {
return Err(KernelError::InvalidAddress);
}
// Nor another device's window: each device has one region, so
// revoking or delegating it means the same thing everywhere.
let overlaps = self.regions.iter().any(|(_, r)| {
let r_start = r.base().raw();
let r_end = r_start.saturating_add(r.pages().value() as usize * PAGE_SIZE);
r.backing() == RegionBacking::Device && start < r_end && end > r_start
});
if overlaps {
return Err(KernelError::AddressInUse);
}
self.regions
.insert(Region::new(owner, RegionBacking::Device, base, pages))
.ok_or(KernelError::NoFreeSlot)
@@ -339,6 +351,10 @@ impl<P: Platform> Kernel<P> {
self.regions.get(id).map(Region::base)
}
pub fn region_pages(&self, id: RegionId) -> Option<PageCount> {
self.regions.get(id).map(Region::pages)
}
/// Maps all of region `id` at `va` in `pid`, all or nothing.
/// Maps region `id` for boot code; the mapping is not tied to any
/// capability and lasts until the region or the process dies.

19
crates/kernel/src/syscall/memory.rs
View File

@@ -1,6 +1,9 @@
use platform::Platform;
use types::{
address::VirtualAddress, bounded::CapSlot, bounded::PageCount, id::ProcessId,
address::{PhysicalAddress, VirtualAddress},
bounded::CapSlot,
bounded::PageCount,
id::ProcessId,
mapping::PagePerms,
};
@@ -115,4 +118,18 @@ impl<P: Platform> Kernel<P> {
let via = self.cap_ref(pid, slot);
self.map_region_via(id, pid, va, perms, via)
}
/// The physical base of the region behind `slot`. Needs Read on the
/// capability; pool regions are physically contiguous, so the base is
/// enough to program a device.
pub(crate) fn region_address_cap(
&self,
pid: ProcessId,
slot: CapSlot,
) -> Result<PhysicalAddress, KernelError> {
let Resource::Memory(id) = *self.check_cap(pid, slot, Permission::Read)?.resource() else {
return Err(KernelError::WrongObject);
};
self.region_base(id).ok_or(KernelError::InvalidRegion)
}
}

6
crates/kernel/src/syscall/mod.rs
View File

@@ -92,6 +92,10 @@ impl<P: Platform> Kernel<P> {
self.map_region_cap(pid, region, va, perms)
.map(|()| SyscallResult::Ok),
),
Syscall::RegionAddress { region } => complete(
self.region_address_cap(pid, region)
.map(|pa| SyscallResult::Value(pa.raw())),
),
Syscall::Delegate {
slot,
to_endpoint,
@@ -136,7 +140,7 @@ impl<P: Platform> Kernel<P> {
Syscall::AcknowledgeInterrupt { irq } => {
complete(self.ack_interrupt(pid, irq).map(|()| SyscallResult::Ok))
}
Syscall::Halt => self.handle_halt(pid),
Syscall::Halt { control } => self.handle_halt(pid, control),
Syscall::CreateEndpoint => self.handle_create_endpoint(pid),
Syscall::DebugPutchar { byte } => self.handle_debug_putchar(byte),
Syscall::MapPage {

15
crates/kernel/src/syscall/simple.rs
View File

@@ -1,4 +1,6 @@
use domain::{error::KernelError, resource::Resource};
use platform::Platform;
use types::{bounded::CapSlot, id::ProcessId, permission::Permission};
use super::{SyscallOutcome, SyscallResult};
use crate::Kernel;
@@ -87,12 +89,13 @@ impl<P: Platform> Kernel<P> {
SyscallOutcome::Complete(SyscallResult::Ok)
}
pub(crate) fn handle_halt(&mut self, pid: types::id::ProcessId) -> SyscallOutcome {
if pid.raw() != 0 {
return SyscallOutcome::Complete(SyscallResult::Error(
domain::error::KernelError::ProcessCreateDenied,
));
/// Halts the machine for a holder of a SystemControl capability with
/// Execute; anyone else gets an error and nothing happens.
pub(crate) fn handle_halt(&mut self, pid: ProcessId, control: CapSlot) -> SyscallOutcome {
match self.check_cap(pid, control, Permission::Execute) {
Ok(cap) if *cap.resource() == Resource::SystemControl => self.platform.halt(),
Ok(_) => SyscallOutcome::Complete(SyscallResult::Error(KernelError::WrongObject)),
Err(e) => SyscallOutcome::Complete(SyscallResult::Error(e)),
}
self.platform.halt();
}
}

3
crates/kernel/src/tests/abi.rs
View File

@@ -41,6 +41,7 @@ fn every_defined_syscall_decodes() {
SYS_SET_IRQ_NOTIFICATION,
SYS_CREATE_REGION,
SYS_MAP_REGION,
SYS_REGION_ADDRESS,
];
// slot 1, slot 2, small values, no cap
let args = [1, 2, 1, 0, 0, NONE];
@@ -51,7 +52,7 @@ fn every_defined_syscall_decodes() {
#[test]
fn retired_and_unknown_numbers_do_not_decode() {
for nr in [3, 5, 35, 1000, usize::MAX] {
for nr in [3, 5, 36, 1000, usize::MAX] {
assert!(decode(nr, &[0; 6]).is_none(), "{nr} decoded");
}
}

323
crates/kernel/src/tests/board.rs Normal file
View File

@@ -0,0 +1,323 @@
use super::*;
use crate::{BoardDevice, SyscallOutcome, SyscallResult};
use domain::{error::KernelError, resource::Resource, syscall::Syscall};
use types::{
address::{PhysicalAddress, VirtualAddress},
badge::Badge,
bounded::{CapSlot, PageCount, Priority},
id::IrqId,
mapping::PagePerms,
permission::{Permission, PermissionSet},
time::TimeSlice,
};
const UART: usize = 0x1000_0000;
const VIRTIO: usize = 0x1000_1000;
fn device(base: usize, pages: u16, irq: Option<u16>) -> BoardDevice {
BoardDevice {
base: PhysicalAddress::from_raw(base),
pages: PageCount::new(pages).unwrap(),
irq: irq.map(IrqId::from_raw),
}
}
fn board() -> [BoardDevice; 2] {
[device(UART, 1, Some(10)), device(VIRTIO, 1, Some(1))]
}
/// Init after boot with the board registered and its authority granted.
fn booted() -> (Kernel<MockPlatform>, ProcessId) {
let (mut k, init) = kernel_with_process();
k.register_board(init, &board()).unwrap();
k.grant_boot_authority(init, &board()).unwrap();
(k, init)
}
fn slot_holding(k: &Kernel<MockPlatform>, pid: ProcessId, resource: Resource) -> CapSlot {
k.processes
.get(pid)
.unwrap()
.capabilities()
.iter()
.find(|(_, c)| *c.resource() == resource)
.map(|(s, _)| s)
.expect("capability present")
}
fn perms_of(k: &Kernel<MockPlatform>, pid: ProcessId, slot: CapSlot) -> PermissionSet {
*k.processes
.get(pid)
.unwrap()
.capabilities()
.get(slot)
.unwrap()
.permissions()
}
fn error_of(outcome: SyscallOutcome) -> KernelError {
match outcome {
SyscallOutcome::Complete(SyscallResult::Error(e)) => e,
_ => panic!("expected an error"),
}
}
// ---- halt ----
#[test]
fn init_cannot_halt_without_a_system_control_cap() {
let (mut k, _) = kernel_with_process();
let e = error_of(k.handle_syscall(Syscall::Halt {
control: CapSlot::new(0).unwrap(),
}));
assert!(
matches!(e, KernelError::WrongObject),
"slot 0 is ProcessCreate"
);
let e = error_of(k.handle_syscall(Syscall::Halt {
control: CapSlot::new(9).unwrap(),
}));
assert!(matches!(e, KernelError::InvalidSlot(_)));
}
#[test]
#[should_panic(expected = "halt")]
fn system_control_cap_halts() {
let (mut k, init) = booted();
let control = slot_holding(&k, init, Resource::SystemControl);
k.handle_syscall(Syscall::Halt { control });
}
#[test]
fn halt_needs_execute_on_the_cap() {
let (mut k, init) = booted();
let control = slot_holding(&k, init, Resource::SystemControl);
let weak = k
.mint(
init,
control,
Badge::new(0),
PermissionSet::empty().with(Permission::Delegate),
)
.unwrap();
let e = error_of(k.handle_syscall(Syscall::Halt { control: weak }));
assert!(matches!(e, KernelError::PermissionDenied { .. }));
}
#[test]
#[should_panic(expected = "halt")]
fn any_holder_of_the_cap_may_halt_not_just_init() {
let (mut k, init) = booted();
let other = k.create_process_internal().unwrap();
let tid = k.spawn_thread_for_test(other, Priority::DEFAULT, TimeSlice::DEFAULT);
k.grant_cap_for_test(
other,
Resource::SystemControl,
PermissionSet::empty().with(Permission::Execute),
);
let _ = init;
k.switch_to_thread_for_test(tid);
let control = slot_holding(&k, other, Resource::SystemControl);
k.handle_syscall(Syscall::Halt { control });
}
// ---- boot authority ----
#[test]
fn init_gets_mmio_irq_and_control_caps_it_can_delegate() {
let (k, init) = booted();
let delegate = Permission::Delegate;
for d in board() {
let region = k.device_region_at(d.base).unwrap();
let mem = slot_holding(&k, init, Resource::Memory(region));
let p = perms_of(&k, init, mem);
assert!(p.allows(Permission::Read) && p.allows(Permission::Write) && p.allows(delegate));
assert!(!p.allows(Permission::Execute), "MMIO is never executable");
let irq = slot_holding(&k, init, Resource::Interrupt(d.irq.unwrap()));
let p = perms_of(&k, init, irq);
assert!(p.allows(Permission::Execute) && p.allows(delegate));
}
let control = slot_holding(&k, init, Resource::SystemControl);
let p = perms_of(&k, init, control);
assert!(p.allows(Permission::Execute) && p.allows(delegate));
}
#[test]
fn boot_authority_keeps_existing_slots() {
let (mut k, init) = kernel_with_process();
let before = k.cap_slots_for_test(init);
k.register_board(init, &board()).unwrap();
k.grant_boot_authority(init, &board()).unwrap();
let after = k.cap_slots_for_test(init);
for (b, a) in before.iter().zip(after.iter()) {
assert!(!b || *a, "an existing slot was disturbed");
}
assert_eq!(after.iter().filter(|s| **s).count(), 1 + 2 + 2 + 1);
}
#[test]
fn init_can_map_a_device_through_its_cap() {
let (mut k, init) = booted();
let region = slot_holding(
&k,
init,
Resource::Memory(k.device_region_at(PhysicalAddress::from_raw(UART)).unwrap()),
);
let outcome = k.handle_syscall(Syscall::MapRegion {
region,
va: VirtualAddress::from_raw(0x10_0000),
perms: PagePerms::ReadWrite,
});
assert!(matches!(
outcome,
SyscallOutcome::Complete(SyscallResult::Ok)
));
let e = error_of(k.handle_syscall(Syscall::MapRegion {
region,
va: VirtualAddress::from_raw(0x20_0000),
perms: PagePerms::ReadExecute,
}));
assert!(matches!(e, KernelError::PermissionDenied { .. }));
}
#[test]
fn init_can_route_a_board_irq() {
let (mut k, init) = booted();
let irq = slot_holding(&k, init, Resource::Interrupt(IrqId::from_raw(1)));
let notification = k.create_notification_cap(init).unwrap();
let outcome = k.handle_syscall(Syscall::SetIrqNotification { irq, notification });
assert!(matches!(
outcome,
SyscallOutcome::Complete(SyscallResult::Ok)
));
}
#[test]
fn granting_needs_a_registered_board() {
let (mut k, init) = kernel_with_process();
assert!(matches!(
k.grant_boot_authority(init, &board()),
Err(KernelError::NoSuchObject)
));
}
#[test]
fn granting_needs_the_regions_to_be_inits() {
let (mut k, init) = kernel_with_process();
let other = k.create_process_internal().unwrap();
k.register_board(other, &board()).unwrap();
assert!(matches!(
k.grant_boot_authority(init, &board()),
Err(KernelError::NoSuchObject)
));
}
#[test]
fn board_devices_may_not_overlap() {
let (mut k, init) = kernel_with_process();
let overlapping = [device(UART, 2, None), device(UART + 0x1000, 1, None)];
assert!(matches!(
k.register_board(init, &overlapping),
Err(KernelError::AddressInUse)
));
}
#[test]
fn board_devices_may_not_alias_the_frame_pool() {
let (mut k, init) = kernel_with_process();
assert!(matches!(
k.register_board(init, &[device(0x8400_0000, 1, None)]),
Err(KernelError::InvalidAddress)
));
}
#[test]
fn board_devices_must_be_page_aligned_and_in_range() {
let (mut k, init) = kernel_with_process();
assert!(matches!(
k.register_board(init, &[device(UART + 8, 1, None)]),
Err(KernelError::InvalidAddress)
));
assert!(matches!(
k.register_board(init, &[device(usize::MAX & !0xfff, 2, None)]),
Err(KernelError::InvalidAddress)
));
}
#[test]
fn board_irqs_must_be_routable() {
let (mut k, init) = kernel_with_process();
let bad = IrqId::from_raw(u16::MAX);
assert!(matches!(
k.register_board(init, &[device(UART, 1, Some(u16::MAX))]),
Err(KernelError::InvalidIrq(i)) if i == bad
));
}
// ---- region address ----
#[test]
fn region_address_reports_the_physical_base() {
let (mut k, init) = booted();
let pool = k
.create_region_cap(init, PageCount::new(2).unwrap())
.unwrap();
let outcome = k.handle_syscall(Syscall::RegionAddress { region: pool });
let SyscallOutcome::Complete(SyscallResult::Value(pa)) = outcome else {
panic!("expected an address");
};
let Resource::Memory(id) = *k
.processes
.get(init)
.unwrap()
.capabilities()
.get(pool)
.unwrap()
.resource()
else {
panic!("not a region cap");
};
assert_eq!(Some(pa), k.region_base(id).map(|b| b.raw()));
let uart = slot_holding(
&k,
init,
Resource::Memory(k.device_region_at(PhysicalAddress::from_raw(UART)).unwrap()),
);
let outcome = k.handle_syscall(Syscall::RegionAddress { region: uart });
assert!(matches!(
outcome,
SyscallOutcome::Complete(SyscallResult::Value(UART))
));
}
#[test]
fn region_address_needs_read() {
let (mut k, init) = booted();
let pool = k
.create_region_cap(init, PageCount::new(1).unwrap())
.unwrap();
let blind = k
.mint(
init,
pool,
Badge::new(0),
PermissionSet::empty().with(Permission::Write),
)
.unwrap();
let e = error_of(k.handle_syscall(Syscall::RegionAddress { region: blind }));
assert!(matches!(e, KernelError::PermissionDenied { .. }));
}
#[test]
fn region_address_rejects_other_objects() {
let (mut k, _) = booted();
// An endpoint cap carries Read, so this fails on the object type.
let SyscallOutcome::Complete(SyscallResult::Slot(endpoint)) =
k.handle_syscall(Syscall::CreateEndpoint)
else {
panic!("expected an endpoint");
};
let e = error_of(k.handle_syscall(Syscall::RegionAddress { region: endpoint }));
assert!(matches!(e, KernelError::WrongObject));
}

1
crates/kernel/src/tests/mod.rs
View File

@@ -2,6 +2,7 @@ mod helpers;
mod mock_platform;
mod abi;
mod board;
mod capability;
mod captree_model;
mod exit;

13
crates/kernel/src/tests/storm.rs
View File

@@ -310,7 +310,7 @@ fn new_round(k: &mut Kernel<MockPlatform>, init: ProcessId, init_thread: ThreadI
#[test]
fn the_kernel_survives_a_syscall_storm() {
let mut total = [0usize; 36];
let mut total = [0usize; 36 + 1];
for seed in [17u64, 0xABCD_EF01, 4242, 0x1357_9BDF, 8] {
let (mut k, init) = kernel_with_process();
let init_thread = k.current_thread().unwrap();
@@ -318,7 +318,7 @@ fn the_kernel_survives_a_syscall_storm() {
let mut rng = Rng(seed);
let mut executed = 0;
let mut rounds = 0;
let mut succeeded = [0usize; 36];
let mut succeeded = [0usize; 36 + 1];
new_round(&mut k, init, init_thread);
let mut step = 0;
@@ -350,9 +350,11 @@ fn the_kernel_survives_a_syscall_storm() {
}
let tid = runnable[rng.below(runnable.len())];
let is_init = k.thread_process(tid) == Some(init);
let nr = rng.below(36);
// Halting stops the machine and init exiting ends the test.
if nr == SYS_HALT || (is_init && (nr == SYS_EXIT || nr == SYS_EXIT_THREAD)) {
let nr = rng.below(36 + 1);
// init exiting ends the test. Halt stays in: nobody here holds
// a SystemControl cap, so a halt that got through would panic
// the mock platform and fail the test.
if is_init && (nr == SYS_EXIT || nr == SYS_EXIT_THREAD) {
continue;
}
let args: [usize; 6] = core::array::from_fn(|_| rng.arg());
@@ -415,6 +417,7 @@ fn the_kernel_survives_a_syscall_storm() {
SYS_RELEASE_PAGES,
SYS_CREATE_REGION,
SYS_MAP_REGION,
SYS_REGION_ADDRESS,
SYS_KILL,
SYS_CREATE_PROCESS,
SYS_SPAWN_THREAD,