Module scheduler 

Scheduler implementation

Implements a per-CPU round-robin scheduler for Strat9-OS with support for cooperative and preemptive multitasking.

Preemption design

The timer interrupt (100Hz) calls maybe_preempt() which picks the next task and performs a context switch. Interrupts are disabled while the scheduler lock is held to prevent deadlock on single-core systems:

• yield_task(): CLI → lock → pick next → TSS/CR3 → unlock → switch_context → restore IF
• Timer handler: CPU already cleared IF → lock → pick next → TSS/CR3 → unlock → switch_context

Each task has its own 16KB kernel stack. Callee-saved registers are pushed/popped by switch_context(). CpuContext only stores saved_rsp.

TODO(v3 scheduler):

• API stabilization before adding more features:
  • freeze scheduler command syntax.
  • add a small machine-friendly output format (key=value) for scripts/debug.
• observability v2:
  • per-class latency/wait histograms.
  • one structured dump format (instead of free-form text logs) for top/debug.
• targeted scheduler tests (high priority):
  • config validation/reject paths (class/policy map).
  • ready-task migration on class-table updates.
  • SMP steal/preempt non-regression.
• only then: CPU affinity (first truly useful advanced scheduler feature).

Legacy backlog:

• class registry v2:
  • dynamic add/remove/reorder with validation and safe reject path.
  • policy->class mapping as runtime registry (not only static enum mapping).
• atomic class-table migration:
  • RCU/STW swap + migration of queued tasks across classes.
  • preserve per-task accounting (vruntime, rt budget, wake deadlines).
• balancing v2:
  • dedicated balancer module, per-class steal policy, CPU affinity masks.
  • NUMA-aware placement (future) and stronger anti-thrashing controls.
• SMP hardening:
  • explicit lock hierarchy doc + assertions.
  • improved resched IPI batching/coalescing policy tuning.
• observability v2:
  • latency/wait-time histograms per class + structured trace dump.
  • shell/top integration over stable snapshot API.
• tests:
  • deterministic migration/policy-remap/SMP-steal suites.
  • fairness/starvation long-run regression in test ISO.

Optimization roadmap (stability-first, incremental):

1. Lock contention reduction (highest ROI, low risk)
   • keep scheduler critical sections minimal: compute decisions under lock, execute expensive side effects (IPI, signal delivery, cleanup) after unlock.
   • split hot paths into tiny helpers with explicit “lock held / lock free” contract.
   • add/track contention counters in every try_lock fallback path.
2. Wakeup path scalability (only after strong guards)
   • re-introduce deadline index behind a runtime feature flag (default OFF).
   • enforce single writer API for wake deadlines (no direct field stores in syscalls).
   • add strict invariants:
     • if task has deadline != 0, index contains task exactly once.
     • on wake/kill/exit/resume, deadline is removed from index and field cleared.
   • keep safe fallback scan path available and switchable at runtime.
3. Scheduler observability for regressions
   • keep stable key=value output for scripts (scheduler metrics kv, scheduler dump kv).
   • expose blocked-task ids and per-cpu preempt causes to diagnose stalls quickly.
   • include boot-phase and lock-miss counters in all dump modes.
4. Balancing/pick optimizations
   • tune steal hysteresis/cooldown with metrics, avoid ping-pong migration.
   • avoid counting idle task as runnable load for CPU selection.
   • add bounded per-tick work budgets to prevent long interrupt latency tails.
5. Safety rails before each optimization lands
   • ship each optimization in one isolated patchset with rollback switch.
   • validate with targeted scenarios:
     • boot + shell responsiveness,
     • timeout-heavy workload (poll/futex/nanosleep),
     • SMP preempt/steal stress.
   • if any regression appears, disable feature first, debug second.

Modules

core_impl 🔒

perf_counters

Lightweight TSC-based performance counters for critical kernel paths.

runtime_ops 🔒

task_ops 🔒

timer_ops 🔒

Structs

CpuUsageSnapshot

GlobalSchedState

Global task registry : cold path: fork, exit, all_tasks scan.

PerCpuClassRqSet 🔒

SchedIdentity

Identity maps for the scheduler: PID/TID routing, process groups, session membership, and parent/child relationships.

SchedulerCpu 🔒

Per-CPU scheduler state

SchedulerMetricsSnapshot

SchedulerStateSnapshot

SwitchTarget 🔒

Information needed to perform a context switch after releasing the lock.

Enums

WaitChildResult

Result of a non-blocking wait on child exit.

Constants

STEAL_COOLDOWN_TICKS 🔒

STEAL_IMBALANCE_MIN 🔒

Statics

BLOCKED_TASKS 🔒

Blocked tasks registry : hot path: block/wake.

CPU_FAIR_RUNTIME_TICKS 🔒

CPU_IDLE_TICKS 🔒

CPU_PREEMPT_COUNT 🔒

CPU_RT_RUNTIME_TICKS 🔒

CPU_STEAL_IN_COUNT 🔒

CPU_STEAL_OUT_COUNT 🔒

CPU_SWITCH_COUNT 🔒

CPU_TOTAL_TICKS 🔒

Per-CPU scheduler tick counters used for CPU usage estimation.

CPU_TRY_LOCK_FAIL_COUNT 🔒

FIRST_PREEMPT_LOGGED 🔒

One-shot flag per CPU: set to true after the first preemption is logged. Prevents flooding the serial port with a preempt trace on every tick.

FORCE_RESCHED_HINT 🔒

Lock-free per-CPU hint: request a local preemption as soon as maybe_preempt can observe scheduler state. Written from IRQ paths without touching GLOBAL_SCHED_STATE, consumed under scheduler lock in maybe_preempt.

GLOBAL_SCHED_STATE 🔒

Global scheduler state : cold path: fork, exit, wake, block.

IPI_SEND_TRACE_BUDGET 🔒

LAST_STEAL_TICK 🔒

LOCAL_SCHEDULERS 🔒

Per-CPU local scheduler locks : hot path: timer tick, preemption, yield.

RESCHED_IPI_PENDING 🔒

SCHED_IDENTITY 🔒

Identity maps : cold path: PID/TID lookups, process groups, sessions, parent/child.

SCHED_VERBOSE 🔒

Verbose scheduler trace switch.

TICK_COUNT 🔒

Global tick counter (safe to increment from interrupt context)

Functions

active_cpu_count 🔒

Performs the active cpu count operation.

add_task

Add a task to the scheduler

add_task_with_parent

Add a task and register a parent/child relation.

block_current_task

Block the current task and yield to the scheduler.

class_table

Return the scheduler class-table currently in use.

clear_task_wake_deadline

Performs the clear task wake deadline operation.

configure_class_table

Configure scheduler class pick/steal order at runtime.

cpu_is_valid 🔒

Performs the cpu is valid operation.

cpu_usage_snapshot

Performs the cpu usage snapshot operation.

create_session

Create a new session for the calling task.

current_cpu_index 🔒

Performs the current cpu index operation.

current_pgid

Get the current process group id.

current_pid

Get the current process ID (POSIX pid).

current_sid

Get the current session id.

current_task_clone

Get the current task (cloned Arc), if any.

current_task_clone_spin_debug

Debug-only blocking variant used to diagnose early ring3 entry stalls.

current_task_clone_try

Best-effort, non-blocking variant of current_task_clone.

current_task_id

Get the current task’s ID (if any task is running).

current_task_id_try

Get the current task’s ID without blocking (safe for exceptions).

current_tid

Get the current thread ID (POSIX tid).

debug_scheduler_lock_addr

Returns the scheduler lock address for deadlock tracing.

exit_current_task

Mark the current task as Dead and yield to the scheduler.

finish_interrupt_switch

Finalize a preemption-driven switch once the raw timer stub has already moved onto the next task’s kernel stack.

finish_switch

Called immediately after a context switch completes (in the new task’s context). This safely re-queues the previously running task now that its state is fully saved.

flush_deferred_silo_cleanups

get_all_tasks

Get a list of all tasks in the system (for timer checking). Returns None if scheduler is not initialized or currently locked.

get_child_task_id_by_pid

Resolve a direct child of parent by POSIX pid.

get_child_task_id_by_tid

Resolve a direct child of parent by POSIX tid.

get_parent_id

Get parent task ID for a child task.

get_parent_pid

Get parent process ID for a child task.

get_pgid_by_pid

Resolve a PID to the current process group id.

get_sid_by_pid

Resolve a PID to the current session id.

get_task_by_id

Get a task by its TaskId (if still registered).

get_task_by_pid

Resolve a POSIX pid to the corresponding task.

get_task_id_by_pid

Resolve a POSIX pid to internal TaskId.

get_task_id_by_tid

Resolve a POSIX tid to the corresponding internal task id.

get_task_ids_in_pgid

Collect task IDs that currently belong to process group pgid.

get_task_ids_in_tgid

Collect task IDs that currently belong to thread group tgid.

init_scheduler

Initialize the scheduler

kill_task

Kill a task by ID (best-effort).

log_state

Dump per-cpu scheduler queues for tracing/debug.

maybe_preempt

Called from the timer interrupt handler (or a resched IPI) to potentially preempt the current task.

maybe_preempt_from_interrupt

Interrupt-aware preemption path.

note_try_lock_fail

Performs the note try lock fail operation.

note_try_lock_fail_on_cpu 🔒

Performs the note try lock fail on cpu operation.

request_force_resched_hint 🔒

Request a local force-reschedule hint for cpu.

reset_scheduler_metrics

Performs the reset scheduler metrics operation.

resume_task

Resume a previously suspended task by ID.

sched_trace 🔒

Performs the sched trace operation.

schedule

Start the scheduler (called from kernel_main)

schedule_on_cpu

Performs the schedule on cpu operation.

scheduler_metrics_snapshot

Performs the scheduler metrics snapshot operation.

send_resched_ipi_to_cpu 🔒

Send a reschedule IPI to cpu_index. No-op if APIC is not initialized, or if cpu_index is the current CPU (the caller already handles the local-CPU case via yield_cpu).

set_process_group

Set process group id for target_pid (or current if None).

set_task_sched_policy

Update a task scheduling policy and requeue if needed.

set_task_wake_deadline

Sets task wake deadline.

set_verbose

Enable or disable verbose scheduler tracing.

state_snapshot

Structured scheduler state snapshot for shell/top/debug tooling.

suspend_task

Suspend a task by ID (best-effort).

take_force_resched_hint 🔒

Consume and clear the local force-reschedule hint for cpu.

ticks

Get the current tick count

timer_tick

Timer interrupt handler - called from interrupt context.

try_wait_child

Try to reap a zombie child.

validate_task_context 🔒

Performs the validate task context operation.

verbose_enabled

Return current verbose tracing state.

wake_task

Wake a blocked task by its ID.

yield_dead_task

Force a context switch away from the current task, unconditionally.

yield_task

Yield the current task to allow other tasks to run (cooperative).