threads(M2): thread_spawn/thread_exit + runtime.Thread.spawn

A thread is a task sharing the caller's address space. New private syscalls
thread_spawn(entry, stack_top, arg)=37 and thread_exit=38: thread_spawn goes
through scheduler.spawnThread (retains the shared aspace), thread_exit ends the
task like a process exit(0) (terminateCurrent -> releaseAspace, so the space
survives while siblings hold it). The closure pointer reaches the new thread in
rdi via a new jump_to_user_arg asm path and a per-task user_arg (0 for a normal
process, whose _start ignores it) - so the runtime trampoline is a plain C-ABI
Zig function, no naked asm.

runtime.Thread (library/runtime/thread.zig) mirrors std.Thread.spawn: mmap a
stack, heap-allocate the args closure, hand the kernel the trampoline + closure.
addThreadedUserBinary opts a binary into single_threaded=false; thread-test is
the first, and proves a worker runs in the shared address space via a shared
global the main thread polls.

Gate thread-spawn PASS; 16 guardrail cases green (incl. args/init/process on the
new jump_to_user_arg path) + aspace-refcount; build + host tests clean.

system/abi.zig

@@ -63,6 +63,8 @@ pub const SystemCall = enum(u64) {
     shm_create = 34, // shm_create(len) -> vaddr (rax), handle (rdx): a shareable, zeroed, cacheable RAM region mapped into this AS; the handle is a capability passed to another process as an ipc_call send_cap (docs/display-v2.md)
     shm_map = 35, // shm_map(cap) -> vaddr: map the shared region named by a received capability into this AS (the same physical pages the creator sees)
     shm_physical = 36, // shm_physical(cap) -> paddr: the guest-physical base of a shared region held by capability, so a driver can program it into a device (e.g. virtio-gpu attach_backing); the pages are contiguous (docs/display-v2.md)
+    thread_spawn = 37, // thread_spawn(entry, stack_top, arg) -> tid: start a task that shares the caller's address space at `entry` on `stack_top`, with `arg` in rdi (docs/threading.md)
+    thread_exit = 38, // thread_exit(): end the calling thread, dropping one reference to its address space (destroyed on the last)
     _,
 };
 

system/kernel/architecture/x86_64/cpu.zig

@@ -687,6 +687,15 @@ pub fn jumpToUser(entry: u64, stack_top: u64) noreturn {
     jump_to_user(entry, stack_top);
 }
 
+/// As `jumpToUser`, but delivers `arg0` in the user's `rdi` — how a fresh thread
+/// receives its closure pointer (docs/threading.md). A normal process is dropped
+/// with `arg0 = 0`, which its `_start` ignores (it reads argv off the stack).
+extern fn jump_to_user_arg(rip: u64, rsp: u64, arg0: u64) callconv(.c) noreturn;
+
+pub fn jumpToUserArg(entry: u64, stack_top: u64, arg0: u64) noreturn {
+    jump_to_user_arg(entry, stack_top, arg0);
+}
+
 /// Route CPU exceptions to `handler`, which receives the trap frame and does not
 /// return. Until set, faults just halt the core.
 pub fn setFaultHandler(handler: *const fn (*const CpuState) noreturn) void {

system/kernel/architecture/x86_64/isr.s

@@ -123,6 +123,22 @@ jump_to_user:
     swapgs                 # user GS base (isr_common/syscall swap back on entry)
     iretq
 
+# jump_to_user_arg(rdi = user rip, rsi = user rsp, rdx = user rdi/arg0): as
+# jump_to_user, but delivers arg0 in the user's rdi — how a fresh **thread**
+# receives its closure pointer (docs/threading.md). rdi carries the rip only until
+# it is pushed into the iretq frame, after which we overwrite it with the arg.
+.global jump_to_user_arg
+jump_to_user_arg:
+    cli
+    push $0x1B              # user SS  (0x18 | RPL 3)
+    push %rsi              # user RSP
+    push $0x202            # RFLAGS: IF | reserved-1
+    push $0x23             # user CS  (0x20 | RPL 3)
+    push %rdi             # user RIP  (consumes rdi)
+    mov %rdx, %rdi        # user rdi = arg0 (the thread's closure pointer)
+    swapgs                 # user GS base (isr_common/syscall swap back on entry)
+    iretq
+
 # --- ring 3 entry/exit ------------------------------------------------------
 
 # enter_user(rdi = user rip, rsi = user rsp, rdx = &TSS.rsp0)

system/kernel/process.zig

@@ -227,6 +227,16 @@ fn system_call(state: *architecture.CpuState) void {
         .shm_create => systemShmCreate(state),
         .shm_map => systemShmMap(state),
         .shm_physical => systemShmPhysical(state),
+        .thread_spawn => systemThreadSpawn(state),
+        .thread_exit => {
+            // A thread ends like a process exit(0), but only this task: its
+            // resources are released and its address-space reference dropped (the
+            // space survives while sibling threads hold it). docs/threading.md.
+            if (scheduler.currentIsUserProcess()) {
+                scheduler.current().exit_reason = .exited;
+                terminateCurrent();
+            } else architecture.userExit();
+        },
         _ => fail(state),
     }
 }
@@ -642,6 +652,23 @@ fn systemSpawn(state: *architecture.CpuState) void {
     fail(state); // no bundled binary by that name
 }
 
+/// thread_spawn(entry, stack_top, arg) -> tid: start a task that shares the **caller's**
+/// address space (docs/threading.md). The runtime supplies `entry` (its thread
+/// trampoline), a stack it mmap'd, and the closure pointer, which the kernel delivers in
+/// the new thread's rdi. The entry and stack must lie in the user half; the new thread is
+/// supervised by the caller and inherits its priority. Only a user process may spawn.
+fn systemThreadSpawn(state: *architecture.CpuState) void {
+    const entry = architecture.systemCallArg(state, 0);
+    const stack_top = architecture.systemCallArg(state, 1);
+    const arg = architecture.systemCallArg(state, 2);
+    const t = scheduler.current();
+    if (t.aspace == 0) return fail(state); // kernel tasks own no address space to share
+    if (entry == 0 or entry >= user_half_end) return fail(state);
+    if (stack_top == 0 or stack_top > user_half_end) return fail(state);
+    const tid = scheduler.spawnThread(t.aspace, entry, stack_top, arg, t.priority, t.id) orelse return fail(state);
+    architecture.setSystemCallResult(state, tid);
+}
+
 /// process_enumerate(buffer, maximum) -> total: snapshot the task table into the
 /// caller's buffer (up to `maximum` `abi.ProcessDescriptor` entries), returning
 /// the total live-task count — the exact shape of `device_enumerate`, so a `ps`
@@ -1433,7 +1460,7 @@ pub fn spawnProcessSupervised(image: []const u8, priority: u3, argv: []const []c
         architecture.mapUserPageInto(aspace, page_virtual, stack_frame, true, false); // RW + NX
     }
 
-    const child = scheduler.spawnUserLocked(aspace, parsed.entry, user_sp, priority, argv[0], supervisor, if (exit_endpoint) |endpoint| @ptrCast(endpoint) else null) orelse
+    const child = scheduler.spawnUserLocked(aspace, parsed.entry, user_sp, 0, priority, argv[0], supervisor, if (exit_endpoint) |endpoint| @ptrCast(endpoint) else null) orelse
         return error.OutOfMemory;
     // The child holds a reference to its exit endpoint from birth to death. Taken
     // only now, after nothing can fail; the lock is still held, so the child

system/kernel/scheduler.zig

@@ -78,6 +78,8 @@ pub const Task = struct {
     aspace: u64 = 0,
     user_ip: u64 = 0, // user-mode entry point (user task only)
     user_sp: u64 = 0, // user-mode stack pointer (user task only)
+    user_arg: u64 = 0, // value delivered in the user's rdi at first entry: 0 for a
+    // process (its _start ignores it), the closure pointer for a thread (docs/threading.md)
     // Next free virtual address in this task's mmap grant arena (0 = uninitialised;
     // process.zig lazily seeds it to the arena base on the first mmap). Bumped up
     // as the user heap grows; user task only.
@@ -388,7 +390,7 @@ pub fn spawnOn(entry: *const fn () void, priority: Priority, cpu: u32) bool {
 /// out of memory.
 /// **Caller must hold the kernel lock** (the loader that builds `aspace` holds it
 /// across the whole spawn, so the address space and the task appear atomically).
-pub fn spawnUserLocked(aspace: u64, entry: u64, user_sp: u64, priority: Priority, task_name: []const u8, supervisor: u32, exit_endpoint: ?*anyopaque) ?u32 {
+pub fn spawnUserLocked(aspace: u64, entry: u64, user_sp: u64, user_arg: u64, priority: Priority, task_name: []const u8, supervisor: u32, exit_endpoint: ?*anyopaque) ?u32 {
     const t = freeSlot() orelse return null;
     const stack = heap.allocator().alloc(u8, stack_size) catch return null;
     // Take this task's reference to the address space before we commit the slot, so a
@@ -405,6 +407,7 @@ pub fn spawnUserLocked(aspace: u64, entry: u64, user_sp: u64, priority: Priority
         .aspace = aspace,
         .user_ip = entry,
         .user_sp = user_sp,
+        .user_arg = user_arg,
         .supervisor = supervisor,
         .exit_endpoint = exit_endpoint,
     };
@@ -421,6 +424,17 @@ pub fn spawnUserLocked(aspace: u64, entry: u64, user_sp: u64, priority: Priority
     return t.id;
 }
 
+/// Spawn a **thread**: a user task that shares an *existing* address space `aspace`
+/// (docs/threading.md), starting at `entry` on `user_sp` with `arg` delivered in its
+/// rdi. Takes a reference to `aspace` (destroyed only when the last thread on it
+/// exits). Acquires the kernel lock itself. `supervisor` is the spawning process.
+/// Returns the new thread's id, or null if the task table is full / out of memory.
+pub fn spawnThread(aspace: u64, entry: u64, user_sp: u64, arg: u64, priority: Priority, supervisor: u32) ?u32 {
+    const flags = sync.enter();
+    defer sync.leave(flags);
+    return spawnUserLocked(aspace, entry, user_sp, arg, priority, "thread", supervisor, null);
+}
+
 /// The first thing a fresh user task runs (in ring 0, via task_trampoline). It
 /// drops to ring 3 at the task's recorded entry/stack. Reading them from the
 /// Task avoids smuggling values through callee-saved registers across the
@@ -430,7 +444,7 @@ fn startUserTask() void {
     // No serial chatter here: this runs on every spawn, unserialized against
     // user-space writes, and its output used to shear concurrent log lines in
     // half — the largest source of corrupted markers in the QEMU scenarios.
-    architecture.jumpToUser(t.user_ip, t.user_sp); // noreturn
+    architecture.jumpToUserArg(t.user_ip, t.user_sp, t.user_arg); // noreturn (arg0 = 0 for a process)
 }
 
 /// The unlocked task-creation primitive. Caller must hold the kernel lock (or be the

system/kernel/tests.zig

@@ -141,6 +141,8 @@ pub fn run(case: []const u8, boot_information: *const BootInformation) void {
         faultRecoveryTest(boot_information);
     } else if (eql(case, "aspace-refcount")) {
         aspaceRefcountTest(boot_information);
+    } else if (eql(case, "thread-spawn")) {
+        threadSpawnTest(boot_information);
     } else if (eql(case, "args")) {
         argsTest(boot_information);
     } else if (eql(case, "init")) {
@@ -1376,7 +1378,7 @@ fn spawnFaultingProcess() ?u32 {
     architecture.mapUserPageInto(aspace, process.stack_base_virtual, stack_frame, true, false); // RW + NX
 
     // Supervised by the calling test task, so exitReasonOf can read the verdict.
-    const id = scheduler.spawnUserLocked(aspace, process.code_virtual, process.stack_base_virtual + abi.page_size, 4, "fault-probe", scheduler.currentId(), null) orelse {
+    const id = scheduler.spawnUserLocked(aspace, process.code_virtual, process.stack_base_virtual + abi.page_size, 0, 4, "fault-probe", scheduler.currentId(), null) orelse {
         architecture.destroyAddressSpace(aspace);
         return null;
     };
@@ -1466,6 +1468,42 @@ fn aspaceRefcountTest(boot_information: *const BootInformation) void {
     result();
 }
 
+/// Thread spawn (docs/threading-plan.md M2): the `thread-test` service spawns a worker
+/// thread that writes a shared global; the main thread, polling that memory, observes the
+/// write — proving `runtime.Thread.spawn` started a task in the **same** address space
+/// (a separate process could not touch it). The service's own marker is the verdict.
+fn threadSpawnTest(boot_information: *const BootInformation) void {
+    log("DANOS-TEST-BEGIN: thread-spawn\n", .{});
+    if (boot_information.initial_ramdisk_len == 0) {
+        check("bootloader handed over an initial_ramdisk", false);
+        result();
+        return;
+    }
+    const image = @as([*]const u8, @ptrFromInt(boot_handoff.physicalToVirtual(boot_information.initial_ramdisk_base)))[0..boot_information.initial_ramdisk_len];
+    const rd = initial_ramdisk.Reader.init(image) orelse {
+        check("initial_ramdisk image is valid", false);
+        result();
+        return;
+    };
+
+    check("thread-test spawned", spawnNamed(rd, "thread-test"));
+
+    // Wait for the service's verdict marker (it polls shared memory the worker wrote).
+    const ok_marker = "thread-test: child ran in shared aspace ok";
+    const fail_marker = "thread-test: FAIL";
+    scheduler.setPriority(1);
+    const deadline = architecture.millis() + 12000;
+    while (architecture.millis() < deadline) {
+        if (bufferHas(ok_marker) or bufferHas(fail_marker)) break;
+        scheduler.yield();
+    }
+    scheduler.setPriority(4);
+
+    check("a worker thread ran in the shared address space (shared write observed)", bufferHas(ok_marker));
+    check("the thread path reported no failure", !bufferHas(fail_marker));
+    result();
+}
+
 /// The full PID-1 path: the bootloader read /system/services/init off the boot volume and
 /// handed it over; load it as a user ELF and spawn it as a real ring-3 process
 /// — the same call the normal boot path makes — then confirm it beats. init

system/services/thread-test/thread-test.zig

@@ -0,0 +1,47 @@
+//! thread-test — the first multi-threaded danos binary (docs/threading-plan.md M2).
+//!
+//! Proves `runtime.Thread.spawn` starts a task in the **same address space**: the main
+//! thread spawns a worker, the worker writes a shared global and signals `done`, and the
+//! main thread — polling that shared memory — observes the write. Seeing the write proves
+//! the two tasks share one address space (a separate process could not touch this memory).
+//! The `thread-test: child ran in shared aspace ok` line is the case's marker.
+//!
+//! Built multi-threaded (`addThreadedUserBinary`), so the poll below is a real atomic
+//! load the compiler must re-read — under a single-threaded build it could be hoisted.
+
+const std = @import("std");
+const runtime = @import("runtime");
+
+/// Written by the worker thread, read by main — the shared-address-space evidence.
+var shared_value: u32 = 0;
+/// Release/acquire handshake: publishes the `shared_value` write to the reader.
+var done = std.atomic.Value(u32).init(0);
+
+const sentinel: u32 = 0xA5A5;
+
+fn worker() void {
+    shared_value = sentinel; // a plain write to a global we share with main
+    done.store(1, .release); // ...published by this release store
+}
+
+pub fn main() void {
+    _ = runtime.system.write("thread-test: starting\n");
+
+    _ = runtime.Thread.spawn(.{}, worker, .{}) catch {
+        _ = runtime.system.write("thread-test: FAIL spawn refused\n");
+        return;
+    };
+
+    // Bounded wait for the worker to run and publish. yield() keeps the core useful;
+    // the acquire load pairs with the worker's release store.
+    var spins: usize = 0;
+    while (done.load(.acquire) == 0 and spins < 50_000_000) : (spins += 1) {
+        runtime.system.yield();
+    }
+
+    if (done.load(.acquire) == 1 and shared_value == sentinel) {
+        _ = runtime.system.write("thread-test: child ran in shared aspace ok\n");
+    } else {
+        _ = runtime.system.write("thread-test: FAIL worker did not update shared memory\n");
+    }
+}