task.c

/*
 * task.c — Object RISC libc: task management.
 *
 * Wraps Vol VI §4 task primitives plus the matching ObjFree-of-task
 * reaping path. Multi-child API: each call takes a `task_t` handle
 * that names a slot in a libc-managed OREF storage table holding
 * up to TASK_MAX_CONCURRENT child task refs at once.
 *
 *     task_t kid_a = task_spawn(child_a, 7);
 *     task_t kid_b = task_spawn(child_b, 11);
 *     int exit_a = task_wait(kid_a);
 *     int exit_b = task_wait(kid_b);
 *     task_free(kid_a);
 *     task_free(kid_b);
 *
 * The table itself is an OR-typed storage object (ObjAllocStore'd
 * by task_init), parked in O12 with R+W caps. Slot index → byte
 * offset is `slot * 8` (each OR ref is 64 bits). Slot occupancy is
 * read directly from the table — a null ref means a free slot (see
 * task_slot_used) — rather than a shadow bitmap. The table is
 * genuinely per-task (each task_init ObjAllocStores its own), so
 * this stays correct even when a task_spawn'd child shares the
 * parent's data segment; a data-section bitmap did NOT (the child's
 * task_init zeroed the parent's copy — see task_slot_used's note).
 *
 * Boot-ABI required of callers
 * ----------------------------
 * task_init() must be called once at program start, before main
 * clobbers O1 (the boot code ref). It parks the boot O1/O2/O3 in
 * O13/O11/O15 so subsequent task_spawn calls can hand the code ref
 * to TaskCreate and restore O2/O3 after the call (console_write,
 * print_str, etc. read string data through O2/O3).
 *
 *     O11 = boot stack ref               (parked by task_init)
 *     O12 = task table (objstore ref)    (allocated by task_init)
 *     O13 = parent's boot code ref       (parked by task_init)
 *     O15 = boot data ref                (parked by task_init)
 *
 * Slot choices match the term.c boot-save convention (O11 = stack,
 * O15 = data) so a program using both task.c and term.c gets one
 * coherent set of boot saves regardless of init order. O13 is
 * task-specific (term.c doesn't use it). O14 (term's self-svc save)
 * is left untouched.
 *
 * Children inherit the parent's OPRs verbatim (TaskCreate copies
 * O1..O15, with O0 forced null) — so they see the same O5..O10
 * service refs the parent had at task_spawn time, etc. That's how a
 * child can call print_str / hf_open / term_print without redoing the
 * init dances.
 *
 * The DATA SEGMENT, however, is NOT shared: task_spawn forks the child
 * a private byte-copy of the parent's data (see task_fork_data), so a
 * child's writes to C globals — and its task_init re-initialising the
 * per-task libc state — stay private. The child boots from a snapshot
 * of the parent's globals; cross-task data sharing is via explicit OR
 * objects (see multitask/concurrent.c), not globals.
 */

#include "liborisc.h"

#define CODE_VA            0x00010000
#define TAG_DATA           0x4102
#define TAG_STACK          0x4101
#define CAP_R              0x01
#define CAP_W              0x02
#define CAP_V              0x10   /* verify/own — required to ObjFree an object */
#define CAP_C              0x40
#define DEFAULT_STACK_SIZE 0x1000   /* 4 KiB — fine for leaf children */

/* TASK_MAX_CONCURRENT is defined in liborisc.h so callers can size
 * arrays of task_t against it. Keep them in sync. */
#define TABLE_BYTES (TASK_MAX_CONCURRENT * 8)

/* The task-table objstore doubles as orx.c's persistent state and
 * (Phase 45a) sup.c's + supervisor.c's + dir.c's. orx picks up at
 * byte offset TABLE_BYTES; the rest follow. We oversize the
 * allocation here so none of them have to re-allocate (and don't
 * have to claim their own OPR slot).
 *
 * 464 = 24 (orx scratch: code/data/stack)
 *     + 384 (16 × 24-byte orx manifest entries)
 *     + 8 (ORX_SLOT_ARGV: long-lived ref to the shared argv buffer)
 *     + 8 (BOOT_PARENT_SLOT: ref harvested from boot O8 at
 *          task_init time. Different programs see different things
 *          here:
 *            - Shells / supervisor-spawned children: their
 *              supervisor's mailbox sub-cap (set by orx_task_create's
 *              ORX_SLOT_CHILD_O8 swap). sup.c reads this slot when
 *              SENDing spawn requests.
 *            - Supervisors themselves (top-level, launched by
 *              oriscrun): the directory daemon's mailbox sub-cap,
 *              wired via boot.sh's `--service "DIR_PID=1@9"` on
 *              the O8 slot. supervisor.c copies this into DIR_SLOT
 *              at boot.
 *            - Programs launched directly without any parent: null.
 *          The slot is generic by design — "the thing my parent /
 *          oriscrun arranged for me to talk to" — and each program
 *          interprets it according to its own role.)
 *     + 8 (REPLY_MB_SLOT: long-lived ref to a per-program reply
 *          mailbox, allocated lazily by sup.c's sup_reply_mailbox_init
 *          and shared with dir.c. Both clients are synchronous
 *          SEND-and-poll, so they never have a reply outstanding
 *          simultaneously and can share the slot.)
 *     + 8 (ORX_SLOT_CHILD_O8: supervisor-only — the sub-cap to
 *          inject into the child's O8 around TaskCreate. orx.c's
 *          orx_task_create reads this and swaps O8 in/out
 *          transparently. Null in non-supervisor callers; their
 *          children inherit the parent's O8 as before.)
 *     + 8 (ORX_SLOT_O8_SAVE: transient — orx_task_create stashes
 *          the parent's O8 here while the override is active in
 *          O8, restores after TaskCreate.)
 *     + 8 (SUP_SCRATCH_SLOT: supervisor-only scratch for stashing
 *          OR refs across orx_spawn (which clobbers O1..O3 via the
 *          manifest restore path). Phase 45b uses this to hold the
 *          incoming reply_cap so handle_spawn_request can call
 *          orx_spawn and still SEND back to the requester.)
 *     + 8 (DIR_SLOT: the directory mailbox sub-cap. Populated at
 *          boot by supervisor.c (which copies BOOT_PARENT_SLOT →
 *          DIR_SLOT) and lazily on first dir_*() call by other
 *          programs (which SEND op=4 SUP_OP_GET_DIR to their
 *          BOOT_PARENT_SLOT and cache the reply here). Phase 45f
 *          replaces 45e's PEER_SUP_SLOT — the same offset 584,
 *          repurposed: peer discovery is now via dir_lookup
 *          rather than a static slot.)
 *     + 16 (RELAY_SCRATCH: two 8-byte slots the supervisor uses
 *          to stash O2 (the spawn-request bytes ref) and O3
 *          (the original reply_cap) across dir_walk's
 *          ReceiveQueuePoll, which clobbers O1..O4 with the
 *          response payload. Only used in supervisor.c's
 *          relay_spawn_request path; idle elsewhere. Phase 45f.)
 *     + 8 (DIR_REPLY_SCRATCH: dir.c stashes its derived reply
 *          sub-cap here (rather than parking it in O15, which
 *          would clobber task.c's boot-data save and break any
 *          subsequent print_str of a data-section string) and
 *          OREFLDs it directly into O3 at SEND time. Phase 45f.)
 *     + 8 (DIR_RESULT_SLOT: dir_walk publishes its resolved ref
 *          here on return (LEAF target / MOUNT service ref / null
 *          for DIR). Callers OREFLD from this slot rather than
 *          relying on a particular OPR being preserved across the
 *          dir_walk function-call boundary — pcc's calling
 *          convention treats OPRs as scratch, so passing OR refs
 *          via OPR returns is unreliable. Phase 45f.)
 *     + 8 (DIR_INPUT_REF_SLOT: dir_register / dir_mount stash the
 *          caller-supplied O1 (ref-to-register / service ref) here
 *          at function entry, BEFORE dir_init / dir_reply_mailbox_init
 *          run — both of those internally clobber O1 (via oisn checks
 *          and ObjAlloc on first call), and the entry-saved value
 *          would otherwise be lost. The SEND that emits the wire op
 *          OREFLDs from this slot directly into O4. Phase 45f bugfix.)
 *     + 8 (ORX_SLOT_CHILD_O5: terminal-pass-through console sub-cap
 *          to inject into the child's O5 around TaskCreate. Set by
 *          the supervisor when servicing a relayed spawn whose source
 *          CPU's terminal differs from ours. Null = no override; child
 *          inherits parent's O5 as before. Phase 49.)
 *     + 8 (ORX_SLOT_O5_SAVE: transient stash for parent's O5 across
 *          the override swap, mirror of ORX_SLOT_O8_SAVE.)
 *     + 8 (ORX_SLOT_CHILD_O6: terminal-pass-through keyboard sub-cap.)
 *     + 8 (ORX_SLOT_O6_SAVE: transient parent-O6 stash.)
 *     + 8 (ORX_SLOT_CHILD_O7: terminal-pass-through grid sub-cap.)
 *     + 8 (ORX_SLOT_O7_SAVE: transient parent-O7 stash.)
 *     + 8 (WM_SLOT: reserved/legacy.  wm.c used to park the window-
 *          manager service sub-cap here (from dir_walk("/sys/wm/0"));
 *          Phase 4 migrated wm.c onto the obj.h handle table, so the WM
 *          service is now an obj_t handle and this slot is dead.  Kept
 *          (not renumbered) so the hardcoded O12 offsets after it stay
 *          put.)
 *     + 8 (WM_INPUT_REF_SLOT: reserved/legacy.  Was the owner-task ref
 *          stashed at wm_new_window entry for O2 of the wire SEND; the
 *          owner-ref auto-destroy path was never wired (all callers pass
 *          null) and Phase 4's wm.c migration dropped it.  Dead.)
 *     + 8 (WM_LEADER_CONSOLE_SLOT: supervisor-only — when a leader
 *          succeeds at wm_init + wm_new_window + wm_bind_surface
 *          (CONSOLE), it stashes the WM-mediated CONSOLE sub-cap
 *          here.  populate_child_term_slots reads it back for
 *          spawns whose terminal idx matches the supervisor's own,
 *          so children inherit the WM-mediated console (output gets
 *          glyph-rendered) instead of bypassing the WM via the
 *          direct /sys/term/<idx>/console walk.  Null on workers
 *          and on leaders without WM mediation.  Phase 59 / WM γ.3.)
 *     + 8 (WM_LEADER_GRID_SLOT: same shape as WM_LEADER_CONSOLE_SLOT
 *          but for the GRID surface.  Filled when the leader runs
 *          wm_bind_surface(WSURF_GRID) successfully; read back by
 *          populate_child_term_slots to wire ORX_SLOT_CHILD_O7 so
 *          spawned children write positioned text through the WM's
 *          GRID rasteriser instead of /sys/term/<idx>/grid.
 *          Phase 59 / WM γ.9.)
 *     + 8 (WM_VECTOR_CAP_SLOT: reserved/legacy.  vector.c used to OREFLD
 *          the WM-mediated VECTOR sub-cap from here into O1 on each
 *          vec_*() SEND; Phase 4 migrated it onto the obj.h handle
 *          table, so vector.c now adopts the dir-result cap into a
 *          handle and this slot is dead.  Kept (not renumbered) so the
 *          dozens of hardcoded O12 offsets after it — and oriscwm's
 *          WM_VECTOR_BASE switch tables — stay put.  Phase 59 /
 *          WM γ.11; migrated Phase 4.)
 *     + 128 (WM_GRID_BASE: WM-only — per-window GRID service refs
 *          (16 windows × 8 bytes).  Mirrors WM_CONSOLE_BASE but for
 *          positioned-text SENDs.  Other programs leave this dead;
 *          the libc allocates the space so the WM doesn't have to
 *          claim its own OPR slot for a separate objstore.)
 *     + 128 (WM_VECTOR_BASE: WM-only — per-window VECTOR service
 *          refs (16 windows × 8 bytes).  Same shape as WM_GRID_BASE.
 *          Phase 59 / WM γ.11.)
 *     + 8 (WM_RASTER_CAP_SLOT: persistent — holds the WM-mediated
 *          RASTER sub-cap that raster.c OREFLDs into O1 on each
 *          raster_*() SEND.  Same role as WM_VECTOR_CAP_SLOT.  Lives
 *          past WM_VECTOR_BASE rather than alongside WM_VECTOR_CAP_SLOT
 *          to avoid renumbering 32 hardcoded offsets in oriscwm's
 *          stash_grid_o1 / load_grid_to_o1 / stash_vector_o1 /
 *          load_vector_to_o1 switch tables (pcc-orisc rejects
 *          computed-offset OREFLDs so each wid has its own case).
 *          Phase 59 / WM γ.12.)
 *     + 128 (WM_RASTER_BASE: WM-only — per-window RASTER service
 *          refs (16 windows × 8 bytes).  Same shape as WM_GRID_BASE
 *          / WM_VECTOR_BASE.  Phase 59 / WM γ.12.)
 *     + 8 (WM_POINTER_CAP_SLOT: persistent — holds the WM-mediated
 *          POINTER service sub-cap that pointer.c SENDs to in order
 *          to subscribe for pointer events.  Unlike vector / raster
 *          which are per-window, the v1 pointer service is one
 *          WM-wide instance (multi-window focus is post-multi-window
 *          WM work).  Phase 59 / WM γ.13.)
 *     + 32 (WM_POINTER_INTERNAL: WM-only — four 8-byte slots used by
 *          the WM's pointer-mediation logic: pointer service ref,
 *          single subscriber ref, internal events-mailbox ref, and
 *          the ref to /sys/term/0/pointer the WM walks at boot.
 *          Other programs leave these dead.  Phase 59 / WM γ.13.)
 *     + 24 (WM_KEYBOARD_INTERNAL: WM-only — three 8-byte slots for
 *          the keyboard-mediation broker: TAG_SERVICE clients SEND to,
 *          current subscriber's reply ref, and TAG_INPUT_SINK kind=0
 *          (Tk-fed by the host display worker).  Phase 60 step 3
 *          replaced the legacy oriscterm-walked keyboard ref with
 *          this in-process sink.)
 *     + 128 (WM_WINDOW_FB_BASE: WM-only — per-wid offscreen
 *          TAG_FRAMEBUFFER backing the matching CONSOLE window.
 *          Renders + scrolls + title-bar paints land in the wid's
 *          FB; the WM ObjBlitCopy-composites the touched region in
 *          z-order onto the screen FB (WM_SURF_FRAMEBUFFER).  16
 *          entries × 8 bytes.  Phase 60 step 7 introduced a single
 *          slot here; step 11 lifted it to a per-wid array when the
 *          N=1 CONSOLE restriction came down.)
 *     + 8 (WM_ACTIVE_FB_SLOT: WM-only — copy of the currently-
 *          active wid's window FB ref.  The painting helpers
 *          (flush_strip, fb_blit_row, fill_rect_window, etc.)
 *          target this slot so they don't have to thread a wid
 *          argument through every asm block; the caller calls
 *          set_active_window(wid) to install the right per-wid FB
 *          before any paint.  Phase 60 step 11.)
 *
 * Total: 720 standard + 128 WM_GRID_BASE + 128 WM_VECTOR_BASE +
 * 8 WM_RASTER_CAP_SLOT + 128 WM_RASTER_BASE + 8 WM_POINTER_CAP_SLOT
 * + 32 WM_POINTER_INTERNAL + 24 WM_KEYBOARD_INTERNAL + 128
 * WM_WINDOW_FB_BASE + 8 WM_ACTIVE_FB_SLOT + 128 WM_KBD_SUB_BASE +
 * 128 WM_PTR_SUB_BASE = 1568.  Adds room for per-wid keyboard /
 * pointer subscriber refs introduced by the focus model (Phase 60
 * step 18) — the WM stores one sub per window so it can route
 * events to the currently-focused window without a single-slot
 * race.  Non-WM programs leave the tail dead, same as before.
 *
 * + 8 (OR_SPILL_ANCHOR: reserved for the C compiler, NOT touched by
 *   libc.  The pcc backend homes `__or` autos/params that must survive
 *   a call in a per-frame OR-typed OBJSTORE and anchors that object's
 *   ref here (chained through the object's slot 0 for recursion).  The
 *   prologue/epilogue it emits OREFLD/OREFST this slot directly; the
 *   offset is hard-coded in tools/cc/arch/orisc/macdefs.h as
 *   ORSPILL_ANCHOR and MUST equal OR_SPILL_ANCHOR_OFFSET below.  It
 *   sits at the old end of the allocation (TABLE_BYTES + 1568 = 1696),
 *   guaranteed clear of every libc slot above.  Starts null from
 *   task_init's zero-init objstore = "no enclosing spill frame".) */
/* 1568 libc + 8 compiler OR-spill anchor + 128 obj.c handle table (16
 * 8-byte capability slots at byte offset 1704 = OBJ_TABLE_OFFSET in
 * obj.h, just past the anchor at 1696; obj.c stores capabilities there
 * so handle-based code needn't hold an `__or` value across a call) +
 * 256 for the two per-child resource-ref arrays (TASK_RES_STACK/DATA
 * below): task_spawn's stack ref and private data-copy ref, 16 slots
 * each, which task_free reclaims on reap instead of leaking them to CPU
 * teardown. The handle table WAS the last region; the resource arrays
 * now follow it (1832..2087), so IF OBJ_NHANDLE ever grows past 16 those
 * offsets must move past the enlarged handle table. Keep the handle slot
 * count in sync with OBJ_NHANDLE in obj.h. */
#define ORX_STATE_BYTES   1960
#define ALLOC_BYTES       (TABLE_BYTES + ORX_STATE_BYTES)

/* Per-child resource-ref arrays (16 x 8 bytes each), just past obj.c's
 * handle table (1704..1831). task_spawn stores the child's stack ref at
 * TASK_RES_STACK_OFFSET + slot*8 and its private data-copy ref at
 * TASK_RES_DATA_OFFSET + slot*8; task_free ObjFrees both on reap
 * (task_store_res / task_free_res). */
#define TASK_RES_STACK_OFFSET   1832
#define TASK_RES_DATA_OFFSET    1960

/* Compiler-owned OR-spill anchor slot (see macdefs.h ORSPILL_ANCHOR). */
#define OR_SPILL_ANCHOR_OFFSET   1696

/* Byte offset within O12 of the boot-parent ref parked from O8
 * by task_init. See the multi-line comment above for the per-
 * program-role interpretations of this slot.
 *
 * = TABLE_BYTES + 24 (orx scratch) + 384 (manifest) + 8 (argv) = 544.
 *
 * The legacy name `SUP_SLOT_OFFSET` is kept as an alias because
 * sup.c references it directly; the slot's role generalizes in
 * Phase 45f without changing the offset or harvest logic. */
#define BOOT_PARENT_SLOT_OFFSET   544
#define SUP_SLOT_OFFSET           BOOT_PARENT_SLOT_OFFSET

/* Task-table occupancy is derived on demand from the per-task O12
 * objstore (see task_slot_used), NOT a shadow bitmap. A data-section
 * bitmap is wrong here: task_spawn'd children share the parent's data
 * segment (TaskCreate leaves O3 = the parent's data object unless the
 * caller overrides it — Vol VI #0x000 makes O3 a caller-supplied data
 * object), so a child's task_init zeroing the bitmap wiped the
 * parent's record of its own children and broke the parent's
 * task_wait/free/query. The O12 objstore is genuinely per-task (each
 * task_init ObjAllocStores its own), so reading occupancy from it is
 * correct under any data-sharing policy. */

/* Phase 51: terminal_idx propagation. crt0.s parks the initial R4
 * (TaskCreate's init_r4 = parent's R5) into _orisc_init_r4 right
 * before main runs. The encoding is `terminal_idx + 1`, with 0
 * meaning "no terminal info" — top-level boots (the supervisor
 * itself) and legacy callers that didn't fill R5 land on 0.
 *
 * task_init reads _orisc_init_r4 once and decodes it into
 * `my_terminal_idx` (-1 for "no terminal," or a non-negative
 * terminal index). sup.c's sup_spawn re-encodes this into the
 * spawn-request's R7 so the chain of supervisors can route a
 * relayed spawn back to the requester's terminal regardless of
 * which CPU is hosting the running program.
 *
 * Programs that need to OVERRIDE this (the supervisor sets it to
 * its procid at boot, since its R4 from oriscrun is uninitialised)
 * use task_set_my_terminal_idx. */
extern int _orisc_init_r4;
static int my_terminal_idx;

/* --- task_init: park boot ORs + ObjAllocStore the table --------- */

void
task_init(void)
{
	asm volatile(
		"omov o13, o1\n"     /* boot code ref */
		"omov o11, o2\n"     /* boot stack ref */
		"omov o15, o3\n"     /* boot data ref */

		/* ObjAllocStore(R4=size, R5=tag, R6=caps) → O1 = table ref. */
		"addiu r4, r0, %0\n"
		"addiu r5, r0, %1\n"
		"addiu r6, r0, %2\n"
		"call  #0x106\n"
		"nop\n"
		"omov  o12, o1\n"

		/* Phase 45a/f: harvest boot O8 into BOOT_PARENT_SLOT, so
		 * sup.c (and dir.c, in the supervisor-self case) can find
		 * the relevant parent service after later libc inits
		 * (term_init, hf_init) reuse O8 for their own mailboxes.
		 * Programs without a parent see O8 = null; the slot ends
		 * up null and downstream callers gate appropriately. */
		"orefst o8, %3(o12)"
		:
		: "i"(ALLOC_BYTES), "i"(TAG_DATA), "i"(CAP_R | CAP_W),
		  "i"(BOOT_PARENT_SLOT_OFFSET)
		: "r2", "r3", "r4", "r5", "r6"
	);
	/* Task-table occupancy now lives in the freshly-zeroed O12
	 * objstore (task_slot_used), so there is no bitmap to clear. */
	/* Phase 51: decode terminal_idx from crt0's R4 stash. R4 == 0
	 * means "no info" (-1 internally); R4 == N+1 maps to terminal
	 * index N. The supervisor overrides this in main() with its
	 * own procid, since its R4 came from oriscrun, not a Phase-51-
	 * aware parent. */
	if (_orisc_init_r4 > 0) {
		my_terminal_idx = _orisc_init_r4 - 1;
	} else {
		my_terminal_idx = -1;
	}

	/* Preemption as a system default. Every task that runs libc
	 * startup self-installs the cause-0x01 timer handler, so a
	 * CPU-bound co-resident task can't starve the others whether or
	 * not it cooperates — the complement to direct-handoff (#143),
	 * which gives a just-woken I/O-bound task the CPU next. The
	 * install must be per-task (the trap vector points at this
	 * program's OWN preempt_timer_handler VA, so the supervisor
	 * can't arm it for a child) — hence task_init, the universal
	 * libc entry, not supervisor.c.
	 *
	 * Cheap and safe: COMPARE fires on COUNT (retired cycles), and a
	 * BLOCKED task doesn't advance COUNT — so the event-driven
	 * daemons (WM on its solo CPU, dir, hostfsd, the supervisor's
	 * infinite spawn-wait) effectively never hit it; it only fires
	 * for genuinely CPU-bound tasks, exactly the fairness target.
	 * Preemption is between-instructions and the context switch
	 * saves the full GPR/OREG file, so OREF spill anchors stay
	 * consistent (no mid-op hazard). */
	task_install_preempt_timer(DEFAULT_PREEMPT_QUANTUM);
}

/* Phase 51: getter / setter for the libc-managed terminal_idx slot.
 * sup_spawn reads this to populate R7 (so the supervisor can route
 * a relayed spawn back to the requester's terminal). The supervisor
 * sets it explicitly because crt0's R4-stash mechanism doesn't
 * apply to top-level boots. Other programs leave it alone — the
 * value task_init computed from the spawn handshake is the right
 * one for them. */
int
task_my_terminal_idx(void)
{
	return my_terminal_idx;
}

void
task_set_my_terminal_idx(int idx)
{
	my_terminal_idx = idx;
}

/* --- internal: OREFLD slot → O1 / OREFST O1 → slot ---------------
 *
 * OREFLD/OREFST take a constant 16-bit signed offset; we can't
 * compute the slot offset at runtime in a single instruction. The
 * switches below are mechanical — pcc lowers them to a chain of
 * compare-branches, which is fine at TASK_MAX_CONCURRENT = 16. */

static void
task_load_to_o1(int slot)
{
	switch (slot) {
	case  0: asm volatile("orefld o1, 0(o12)");   break;
	case  1: asm volatile("orefld o1, 8(o12)");   break;
	case  2: asm volatile("orefld o1, 16(o12)");  break;
	case  3: asm volatile("orefld o1, 24(o12)");  break;
	case  4: asm volatile("orefld o1, 32(o12)");  break;
	case  5: asm volatile("orefld o1, 40(o12)");  break;
	case  6: asm volatile("orefld o1, 48(o12)");  break;
	case  7: asm volatile("orefld o1, 56(o12)");  break;
	case  8: asm volatile("orefld o1, 64(o12)");  break;
	case  9: asm volatile("orefld o1, 72(o12)");  break;
	case 10: asm volatile("orefld o1, 80(o12)");  break;
	case 11: asm volatile("orefld o1, 88(o12)");  break;
	case 12: asm volatile("orefld o1, 96(o12)");  break;
	case 13: asm volatile("orefld o1, 104(o12)"); break;
	case 14: asm volatile("orefld o1, 112(o12)"); break;
	case 15: asm volatile("orefld o1, 120(o12)"); break;
	}
}

static void
task_store_from_o1(int slot)
{
	switch (slot) {
	case  0: asm volatile("orefst o1, 0(o12)");   break;
	case  1: asm volatile("orefst o1, 8(o12)");   break;
	case  2: asm volatile("orefst o1, 16(o12)");  break;
	case  3: asm volatile("orefst o1, 24(o12)");  break;
	case  4: asm volatile("orefst o1, 32(o12)");  break;
	case  5: asm volatile("orefst o1, 40(o12)");  break;
	case  6: asm volatile("orefst o1, 48(o12)");  break;
	case  7: asm volatile("orefst o1, 56(o12)");  break;
	case  8: asm volatile("orefst o1, 64(o12)");  break;
	case  9: asm volatile("orefst o1, 72(o12)");  break;
	case 10: asm volatile("orefst o1, 80(o12)");  break;
	case 11: asm volatile("orefst o1, 88(o12)");  break;
	case 12: asm volatile("orefst o1, 96(o12)");  break;
	case 13: asm volatile("orefst o1, 104(o12)"); break;
	case 14: asm volatile("orefst o1, 112(o12)"); break;
	case 15: asm volatile("orefst o1, 120(o12)"); break;
	}
}

/* --- task_store_res / task_free_res: per-child stack+data reclaim ----
 *
 * task_spawn allocates a stack and (post-fork) a private data copy per
 * child. task_store_res records both refs in per-child O12 slots at
 * spawn — reading O2 (the stack ref) and O3 (the data copy), which both
 * survive from TaskCreate to the call — so task_free_res can ObjFree
 * them on reap instead of leaking them to CPU teardown. Both switch on
 * `slot` because OREFLD/OREFST take a static immediate offset.
 *
 * task_free_res ignores ObjFree status by design: an unused slot reads
 * the null ref (EFAULT) and a stale ref — a task_register_o1 task that
 * never stored resources, or a reused slot — reads generation-mismatched
 * (ESTALE); both are harmless no-ops, so the slots need no nulling. */
static void
task_store_res(int slot)
{
	switch (slot) {
	case  0: asm volatile("orefst o2, %0(o12)\n orefst o3, %1(o12)" :: "i"(TASK_RES_STACK_OFFSET+0),   "i"(TASK_RES_DATA_OFFSET+0));   break;
	case  1: asm volatile("orefst o2, %0(o12)\n orefst o3, %1(o12)" :: "i"(TASK_RES_STACK_OFFSET+8),   "i"(TASK_RES_DATA_OFFSET+8));   break;
	case  2: asm volatile("orefst o2, %0(o12)\n orefst o3, %1(o12)" :: "i"(TASK_RES_STACK_OFFSET+16),  "i"(TASK_RES_DATA_OFFSET+16));  break;
	case  3: asm volatile("orefst o2, %0(o12)\n orefst o3, %1(o12)" :: "i"(TASK_RES_STACK_OFFSET+24),  "i"(TASK_RES_DATA_OFFSET+24));  break;
	case  4: asm volatile("orefst o2, %0(o12)\n orefst o3, %1(o12)" :: "i"(TASK_RES_STACK_OFFSET+32),  "i"(TASK_RES_DATA_OFFSET+32));  break;
	case  5: asm volatile("orefst o2, %0(o12)\n orefst o3, %1(o12)" :: "i"(TASK_RES_STACK_OFFSET+40),  "i"(TASK_RES_DATA_OFFSET+40));  break;
	case  6: asm volatile("orefst o2, %0(o12)\n orefst o3, %1(o12)" :: "i"(TASK_RES_STACK_OFFSET+48),  "i"(TASK_RES_DATA_OFFSET+48));  break;
	case  7: asm volatile("orefst o2, %0(o12)\n orefst o3, %1(o12)" :: "i"(TASK_RES_STACK_OFFSET+56),  "i"(TASK_RES_DATA_OFFSET+56));  break;
	case  8: asm volatile("orefst o2, %0(o12)\n orefst o3, %1(o12)" :: "i"(TASK_RES_STACK_OFFSET+64),  "i"(TASK_RES_DATA_OFFSET+64));  break;
	case  9: asm volatile("orefst o2, %0(o12)\n orefst o3, %1(o12)" :: "i"(TASK_RES_STACK_OFFSET+72),  "i"(TASK_RES_DATA_OFFSET+72));  break;
	case 10: asm volatile("orefst o2, %0(o12)\n orefst o3, %1(o12)" :: "i"(TASK_RES_STACK_OFFSET+80),  "i"(TASK_RES_DATA_OFFSET+80));  break;
	case 11: asm volatile("orefst o2, %0(o12)\n orefst o3, %1(o12)" :: "i"(TASK_RES_STACK_OFFSET+88),  "i"(TASK_RES_DATA_OFFSET+88));  break;
	case 12: asm volatile("orefst o2, %0(o12)\n orefst o3, %1(o12)" :: "i"(TASK_RES_STACK_OFFSET+96),  "i"(TASK_RES_DATA_OFFSET+96));  break;
	case 13: asm volatile("orefst o2, %0(o12)\n orefst o3, %1(o12)" :: "i"(TASK_RES_STACK_OFFSET+104), "i"(TASK_RES_DATA_OFFSET+104)); break;
	case 14: asm volatile("orefst o2, %0(o12)\n orefst o3, %1(o12)" :: "i"(TASK_RES_STACK_OFFSET+112), "i"(TASK_RES_DATA_OFFSET+112)); break;
	case 15: asm volatile("orefst o2, %0(o12)\n orefst o3, %1(o12)" :: "i"(TASK_RES_STACK_OFFSET+120), "i"(TASK_RES_DATA_OFFSET+120)); break;
	}
}

static void
task_free_res(int slot)
{
	switch (slot) {
	case  0: asm volatile("orefld o1, %0(o12)\n call #0x101\n nop\n orefld o1, %1(o12)\n call #0x101\n nop" :: "i"(TASK_RES_STACK_OFFSET+0),   "i"(TASK_RES_DATA_OFFSET+0)   : "r2","r3"); break;
	case  1: asm volatile("orefld o1, %0(o12)\n call #0x101\n nop\n orefld o1, %1(o12)\n call #0x101\n nop" :: "i"(TASK_RES_STACK_OFFSET+8),   "i"(TASK_RES_DATA_OFFSET+8)   : "r2","r3"); break;
	case  2: asm volatile("orefld o1, %0(o12)\n call #0x101\n nop\n orefld o1, %1(o12)\n call #0x101\n nop" :: "i"(TASK_RES_STACK_OFFSET+16),  "i"(TASK_RES_DATA_OFFSET+16)  : "r2","r3"); break;
	case  3: asm volatile("orefld o1, %0(o12)\n call #0x101\n nop\n orefld o1, %1(o12)\n call #0x101\n nop" :: "i"(TASK_RES_STACK_OFFSET+24),  "i"(TASK_RES_DATA_OFFSET+24)  : "r2","r3"); break;
	case  4: asm volatile("orefld o1, %0(o12)\n call #0x101\n nop\n orefld o1, %1(o12)\n call #0x101\n nop" :: "i"(TASK_RES_STACK_OFFSET+32),  "i"(TASK_RES_DATA_OFFSET+32)  : "r2","r3"); break;
	case  5: asm volatile("orefld o1, %0(o12)\n call #0x101\n nop\n orefld o1, %1(o12)\n call #0x101\n nop" :: "i"(TASK_RES_STACK_OFFSET+40),  "i"(TASK_RES_DATA_OFFSET+40)  : "r2","r3"); break;
	case  6: asm volatile("orefld o1, %0(o12)\n call #0x101\n nop\n orefld o1, %1(o12)\n call #0x101\n nop" :: "i"(TASK_RES_STACK_OFFSET+48),  "i"(TASK_RES_DATA_OFFSET+48)  : "r2","r3"); break;
	case  7: asm volatile("orefld o1, %0(o12)\n call #0x101\n nop\n orefld o1, %1(o12)\n call #0x101\n nop" :: "i"(TASK_RES_STACK_OFFSET+56),  "i"(TASK_RES_DATA_OFFSET+56)  : "r2","r3"); break;
	case  8: asm volatile("orefld o1, %0(o12)\n call #0x101\n nop\n orefld o1, %1(o12)\n call #0x101\n nop" :: "i"(TASK_RES_STACK_OFFSET+64),  "i"(TASK_RES_DATA_OFFSET+64)  : "r2","r3"); break;
	case  9: asm volatile("orefld o1, %0(o12)\n call #0x101\n nop\n orefld o1, %1(o12)\n call #0x101\n nop" :: "i"(TASK_RES_STACK_OFFSET+72),  "i"(TASK_RES_DATA_OFFSET+72)  : "r2","r3"); break;
	case 10: asm volatile("orefld o1, %0(o12)\n call #0x101\n nop\n orefld o1, %1(o12)\n call #0x101\n nop" :: "i"(TASK_RES_STACK_OFFSET+80),  "i"(TASK_RES_DATA_OFFSET+80)  : "r2","r3"); break;
	case 11: asm volatile("orefld o1, %0(o12)\n call #0x101\n nop\n orefld o1, %1(o12)\n call #0x101\n nop" :: "i"(TASK_RES_STACK_OFFSET+88),  "i"(TASK_RES_DATA_OFFSET+88)  : "r2","r3"); break;
	case 12: asm volatile("orefld o1, %0(o12)\n call #0x101\n nop\n orefld o1, %1(o12)\n call #0x101\n nop" :: "i"(TASK_RES_STACK_OFFSET+96),  "i"(TASK_RES_DATA_OFFSET+96)  : "r2","r3"); break;
	case 13: asm volatile("orefld o1, %0(o12)\n call #0x101\n nop\n orefld o1, %1(o12)\n call #0x101\n nop" :: "i"(TASK_RES_STACK_OFFSET+104), "i"(TASK_RES_DATA_OFFSET+104) : "r2","r3"); break;
	case 14: asm volatile("orefld o1, %0(o12)\n call #0x101\n nop\n orefld o1, %1(o12)\n call #0x101\n nop" :: "i"(TASK_RES_STACK_OFFSET+112), "i"(TASK_RES_DATA_OFFSET+112) : "r2","r3"); break;
	case 15: asm volatile("orefld o1, %0(o12)\n call #0x101\n nop\n orefld o1, %1(o12)\n call #0x101\n nop" :: "i"(TASK_RES_STACK_OFFSET+120), "i"(TASK_RES_DATA_OFFSET+120) : "r2","r3"); break;
	}
}

/* --- task_slot_used: is O12 table slot `slot` occupied? ---------
 *
 * Load the slot's stored ref into O1 (the null ref if the slot is
 * free) and OISN it. O1 survives from task_load_to_o1 to the next
 * asm exactly as it does for task_wait's CALL #0x007, so this uses
 * the same established idiom. Replaces the old shared
 * task_slots_in_use bitmap, which a task_spawn'd child's task_init
 * would clobber in the shared data segment. */
static int
task_slot_used(int slot)
{
	int isn;
	task_load_to_o1(slot);
	asm volatile("oisn %0, o1" : "=r"(isn) : : "r1");
	return !isn;
}

/* --- task_yield: surrender the rest of the quantum -------------- */

void
task_yield(void)
{
	asm volatile(
		"call #0x004\n"
		"nop"
		:
		:
		: "r2"
	);
}

/* --- task_exit: terminate the calling task (does not return) ---- */

void
task_exit(int code)
{
	asm volatile(
		"addu r4, %0, r0\n"
		"call #0x001\n"
		"nop"
		:
		: "r"(code)
		: "r4"
	);
}

/* --- task_fork_data: give the child a PRIVATE data segment --------
 *
 * TaskCreate (Vol VI #0x000) maps whatever ref is in O3 as the child's
 * data at DATA_VA. task_spawn used to leave O3 = the parent's own data
 * ref (O15, parked by task_init), so parent and child SHARED all C
 * globals — a child's task_init then clobbered the parent's per-task
 * libc state (task_slots_in_use, my_terminal_idx, obj.c's obj_inuse,
 * crt0's _orisc_init_r4, ...). Since the spec makes O3 a caller-
 * supplied data object, task_spawn instead FORKS: alloc a fresh
 * TAG_DATA object the size of the parent's data, ObjFetchBytes (#0x108)
 * a byte-copy of the parent's live data into it, and leave it in O3 for
 * the imminent TaskCreate. The child boots from a SNAPSHOT of the
 * parent's globals but its writes are its own — true fork semantics,
 * no shared globals. (Reads still see what the parent had at spawn, so
 * this is the least-surprising change over the old shared behaviour.)
 *
 * The copy's lifecycle matches the per-child stack task_spawn already
 * allocates: neither is explicitly freed (ObjFree of the task descriptor
 * doesn't cascade to its mappings — see primitive_ObjFree), both are
 * reclaimed at CPU teardown. task_spawn is used only by short-lived
 * example programs, so this is bounded in practice; a free-on-reap path
 * (for both stack and data) is a future refinement if a long-lived
 * task_spawn spawner ever appears.
 *
 * Leaves O3 = the private copy (or null if the parent has no data
 * segment); returns 0, or -errno on ObjAlloc/ObjFetchBytes failure.
 * Uses O1/O2 as scratch; must not touch O13 (code) / O15 (parent data).
 */
static int
task_fork_data(void)
{
	int size, status, isn;

	/* No parent data segment (rare) → the child gets none either. */
	asm volatile("oisn %0, o15" : "=r"(isn));
	if (isn) {
		asm volatile("omov o3, o0");        /* O3 = null */
		return 0;
	}
	asm volatile("olen %0, o15" : "=r"(size));

	/* Alloc the copy: R (TaskCreate requires R on O3) | W (ObjFetchBytes
	 * destination + the child mutating its own globals) | V (so task_free
	 * can reclaim it on reap — see task_free_res). Park it in O3. */
	asm volatile(
		"addu  r4, %1, r0\n"
		"addiu r5, r0, %2\n"
		"addiu r6, r0, %3\n"
		"call  #0x100\n"
		"nop\n"
		"omov  o3, o1\n"                    /* O3 = private data copy */
		"addu  %0, r2, r0"
		: "=r"(status)
		: "r"(size), "i"(TAG_DATA), "i"(CAP_R | CAP_W | CAP_V)
		: "r2", "r3", "r4", "r5", "r6"
	);
	if (status != 0)
		return -status;

	/* Byte-copy parent data (O15) → copy (O3). ObjFetchBytes #0x108:
	 * O1=src, O2=dst, R4=src offset, R5=dst offset, R6=count. */
	asm volatile(
		"omov  o1, o15\n"
		"omov  o2, o3\n"
		"addu  r6, %1, r0\n"
		"addu  r4, r0, r0\n"
		"addu  r5, r0, r0\n"
		"call  #0x108\n"
		"nop\n"
		"addu  %0, r2, r0"
		: "=r"(status)
		: "r"(size)
		: "r2", "r3", "r4", "r5", "r6"
	);
	if (status != 0)
		return -status;
	return 0;
}

/* --- task_spawn: create + resume a child --------------------------
 *
 * Allocates a fresh stack via ObjAlloc, calls TaskCreate with the
 * parent's code ref (parked in O13 by task_init) and the supplied
 * entry offset, OREFSTs the new ref into the next free table slot,
 * then TaskResumes. Restores O2/O3 from O11/O15 on the way out so
 * the caller's subsequent print_str / print_int keep working.
 *
 * Returns the slot index (>= 0) on success; -firmware_errno on a
 * primitive failure; -1 if the table is full.
 */
task_t
task_spawn(void (*entry)(int), int arg)
{
	unsigned int entry_off = (unsigned int)entry - CODE_VA;
	int slot;
	int status;

	/* Find a free slot. */
	for (slot = 0; slot < TASK_MAX_CONCURRENT; slot++) {
		if (!task_slot_used(slot))
			break;
	}
	if (slot >= TASK_MAX_CONCURRENT)
		return -1;

	/* Fork the child a PRIVATE data segment; leaves it in O3 for the
	 * TaskCreate below. Must precede the stack ObjAlloc — task_fork_data
	 * uses O1/O2 as scratch, and O3 then survives (unspilled) across the
	 * stack alloc to TaskCreate the same way O13/O15 already do. */
	status = task_fork_data();
	if (status != 0) {
		asm volatile("omov o3, o15");   /* restore caller's O3 */
		return status;
	}

	/* ObjAlloc(R4=size, R5=TAG_STACK, R6=R|W|C|V) → O1 = stack ref.
	 * V so task_free can reclaim the stack on reap (task_free_res). */
	asm volatile(
		"addiu r4, r0, %1\n"
		"addiu r5, r0, %2\n"
		"addiu r6, r0, %3\n"
		"call  #0x100\n"
		"nop\n"
		"addu  %0, r2, r0"
		: "=r"(status)
		: "i"(DEFAULT_STACK_SIZE), "i"(TAG_STACK), "i"(CAP_R | CAP_W | CAP_C | CAP_V)
		: "r2", "r3", "r4", "r5", "r6"
	);
	if (status != 0) {
		asm volatile("omov o3, o15");   /* restore caller's O3 (fork set it) */
		return -status;
	}

	/* TaskCreate(O1=code, O2=stack, R4=entry_off, R5=arg) → O1 = task. */
	asm volatile(
		"omov  o2, o1\n"           /* O2 = stack ref (just from ObjAlloc) */
		"omov  o1, o13\n"          /* O1 = parent's code ref */
		"addu  r4, %1, r0\n"
		"addu  r5, %2, r0\n"
		"call  #0x000\n"
		"nop\n"
		"addu  %0, r2, r0"
		: "=r"(status)
		: "r"(entry_off), "r"(arg)
		: "r2", "r3", "r4", "r5"
	);
	if (status != 0) {
		/* Restore O2/O3 before bailing — caller's prints depend on them. */
		asm volatile("omov o2, o11");
		asm volatile("omov o3, o15");
		return -status;
	}

	/* O1 now holds the new task ref. Park it in the table at `slot`;
	 * that OREFST IS the occupancy record now (no shadow bitmap). */
	task_store_from_o1(slot);

	/* Record the child's stack (O2) + data-copy (O3) refs so task_free
	 * reclaims them on reap. O2 = stack (TaskCreate's omov o2,o1) and
	 * O3 = the fork copy still hold here — task_store_from_o1 only
	 * touched O1. */
	task_store_res(slot);

	/* TaskResume(O1=task) — O1 still holds the ref from TaskCreate. */
	asm volatile(
		"call  #0x002\n"
		"nop\n"
		"addu  %0, r2, r0"
		: "=r"(status)
		:
		: "r2"
	);

	/* Restore O2/O3 for the caller. */
	asm volatile("omov o2, o11");
	asm volatile("omov o3, o15");

	if (status != 0)
		return -status;
	return slot;
}

/* --- task_register_o1 / task_resume — handles for tasks the libc
 * didn't create itself.
 *
 * orx.c's loader calls TaskCreate directly (it has its own
 * code/data/stack-allocation flow), then needs to enroll the
 * resulting task into the libc table so the user can task_wait /
 * task_free it via the normal handle API. task_register_o1 finds
 * a free slot, OREFSTs O1 (assumed to hold the task ref) into it,
 * and returns the handle. task_resume then drives the named task
 * to RUNNABLE — the equivalent of task_spawn's TaskResume step,
 * but separated out so loaders can interleave their own work
 * between TaskCreate and TaskResume.
 *
 * Returns -1 if the table is full (task_register_o1) or the
 * handle is invalid (task_resume); otherwise the firmware status
 * is propagated negated. */

task_t
task_register_o1(void)
{
	int slot;
	/* The task ref arrives in O1 — a side-channel the caller set
	 * unspilled (see obj_register_task / orx_spawn), so pcc doesn't
	 * know to preserve it. Scanning the O12 table for a free slot
	 * clobbers O1 (task_slot_used OREFLDs each slot into it), so stash
	 * the ref in O2 across the scan and restore it before the store.
	 * Both callers treat O2 as dead after this call. (task_spawn's
	 * identical scan needs no such dance — its O1 isn't live yet.) */
	asm volatile("omov o2, o1");
	for (slot = 0; slot < TASK_MAX_CONCURRENT; slot++) {
		if (!task_slot_used(slot))
			break;
	}
	if (slot >= TASK_MAX_CONCURRENT)
		return -1;
	asm volatile("omov o1, o2");
	task_store_from_o1(slot);
	return slot;
}

int
task_resume(task_t t)
{
	int status;
	if (t < 0 || t >= TASK_MAX_CONCURRENT
			|| !task_slot_used(t))
		return -1;
	task_load_to_o1(t);
	asm volatile(
		"call  #0x002\n"
		"nop\n"
		"addu  %0, r2, r0"
		: "=r"(status)
		:
		: "r2"
	);
	if (status != 0)
		return -status;
	return 0;
}

/* --- task_kill: externally terminate a task ----------------------
 *
 * Loads the child's ref from the table into O1, sets R4 = exit
 * code, calls TaskKill (#0x00A). The descriptor stays parked in
 * its slot — the caller still needs task_wait + task_free (or
 * orx_unload) to actually reclaim it. Idempotent: killing a task
 * that has already exited returns 0.
 */
int
task_kill(task_t t, int code)
{
	int status;

	if (t < 0 || t >= TASK_MAX_CONCURRENT
			|| !task_slot_used(t))
		return -1;

	task_load_to_o1(t);
	asm volatile(
		"addu  r4, %1, r0\n"
		"call  #0x00A\n"
		"nop\n"
		"addu  %0, r2, r0"
		: "=r"(status)
		: "r"(code)
		: "r2", "r4"
	);
	if (status != 0)
		return -status;
	return 0;
}

/* --- task_wait: block until the named child exits, return its code
 *
 * Loads the child's ref from the table into O1, calls TaskWait. On
 * wakeup the firmware places R3 = exit code; we surface that as the
 * return value. Errors return negative (firmware error code negated
 * to keep the happy-path 0..255 range usable).
 */
int
task_wait(task_t t)
{
	int status, code;

	if (t < 0 || t >= TASK_MAX_CONCURRENT
			|| !task_slot_used(t))
		return -1;

	task_load_to_o1(t);
	asm volatile(
		"call  #0x007\n"
		"nop\n"
		"addu  %0, r2, r0\n"
		"addu  %1, r3, r0"
		: "=r"(status), "=r"(code)
		:
		: "r2", "r3"
	);
	if (status != 0)
		return -status;
	return code;
}

/* --- task_free: reap the child's descriptor and free its slot --- */

int
task_free(task_t t)
{
	int status;

	if (t < 0 || t >= TASK_MAX_CONCURRENT
			|| !task_slot_used(t))
		return -1;

	task_load_to_o1(t);
	asm volatile(
		"call  #0x101\n"
		"nop\n"
		"addu  %0, r2, r0"
		: "=r"(status)
		:
		: "r2"
	);
	/* Clear the local libc slot on success, OR on EREMOTE (11) —
	 * Phase 45g bugfix. ObjFree refuses to free a remote-home ref
	 * (the simorisc primitive returns ERR_EREMOTE); the actual task
	 * descriptor lives on the remote CPU and is its supervisor's
	 * responsibility to reap. From the caller's perspective the
	 * libc slot IS the local handle, so dropping the bookkeeping
	 * bit here is the right "release my handle" semantic.
	 *
	 * Without this, relayed background spawns (`run @1 cmd &`)
	 * trigger a reap loop in the shell: the task exits on the peer,
	 * task_query keeps returning EXITED, orx_unload calls
	 * task_free → ObjFree returns EREMOTE → slot bit untouched →
	 * reap_exited_tasks fires `[task N done CODE]` again on every
	 * subsequent prompt iteration forever. */
	if (status == 0 || status == 11 /* ERR_EREMOTE */) {
		/* Reclaim the child's stack + private data copy (task_spawn
		 * recorded their refs). Harmless for tasks that stored none —
		 * a task_register_o1 / remote task's slots read null or a
		 * generation-stale ref, both ignored (see task_free_res). */
		task_free_res(t);
		/* Free the slot: overwrite the O12 entry with the null ref.
		 * That OREFST IS the deallocation now — task_slot_used reads
		 * it back as null (free) for the next task_spawn. */
		asm volatile("omov o1, o0");
		task_store_from_o1(t);
	}
	return status;
}

/* --- task_query / task_active_mask — non-blocking inspection ----
 *
 * Vol VI #0x008 returns a packed state word: state in low 8 bits,
 * processor id in next 8, exit code in upper 16 (only meaningful
 * when state == TASK_STATE_EXITED). We unpack into the
 * caller-supplied task_info_t for ergonomics.
 *
 * task_active_mask returns the libc's internal bitmap of in-use
 * task table slots so the shell can iterate `jobs` and the
 * auto-reaper can poll without taking locks. */

int
task_query(task_t t, struct task_info *out)
{
	int status, packed;

	if (t < 0 || t >= TASK_MAX_CONCURRENT
			|| !task_slot_used(t))
		return -1;
	task_load_to_o1(t);
	asm volatile(
		"call  #0x008\n"
		"nop\n"
		"addu  %0, r2, r0\n"
		"addu  %1, r3, r0"
		: "=r"(status), "=r"(packed)
		:
		: "r2", "r3"
	);
	if (status != 0)
		return -status;
	out->state     = packed & 0xff;
	out->processor = (packed >> 8) & 0xff;
	out->exit_code = (packed >> 16) & 0xff;
	return 0;
}

unsigned int
task_active_mask(void)
{
	unsigned int mask = 0;
	int slot;
	for (slot = 0; slot < TASK_MAX_CONCURRENT; slot++)
		if (task_slot_used(slot))
			mask |= (1u << slot);
	return mask;
}

/* --- task_install_preempt_timer — wire the timer handler --------
 *
 * Installs preempt_handler.s::preempt_timer_handler as the
 * supervisor handler for cause 0x01 (external-interrupt) via Vol VI
 * #0x520 InstallTrapHandler, then arms COMPARE = COUNT + quantum
 * and sets STATUS.IE so the timer starts firing. From this point
 * on, runaway CPU-bound tasks on the same CPU don't starve the
 * caller: every `quantum` cycles the handler fires, calls
 * TaskYield (deferred), and ERET picks the next runnable task.
 *
 * `quantum` is in cycles; the handler hardcodes 5000 internally
 * for the re-arm so this argument only sets the FIRST interval.
 * (Future libc could expose the quantum as a tunable in shared
 * state read by the handler.) */

extern void preempt_timer_handler(void);

void
task_install_preempt_timer(unsigned int quantum)
{
	/* InstallTrapHandler(R4=cause=1, R5=va=preempt_timer_handler) */
	asm volatile(
		"addiu r4, r0, 1\n"
		"la    r5, preempt_timer_handler\n"
		"call  #0x520\n"
		"nop"
		:
		:
		: "r2", "r3", "r4", "r5"
	);
	/* Arm: COMPARE = COUNT + quantum. */
	asm volatile(
		"lctrl r4, $5\n"
		"addu  r4, r4, %0\n"
		"sctrl $6, r4"
		:
		: "r"(quantum)
		: "r4"
	);
	/* Set STATUS.IE (bit 4), preserving mode bits. */
	asm volatile(
		"lctrl r4, $0\n"
		"ori   r4, r4, 0x10\n"
		"sctrl $0, r4"
		:
		:
		: "r4"
	);
}