Skip to content

SCHEDULER.md

Latest commit

 

History

History
106 lines (77 loc) · 3.2 KB

SCHEDULER.md

File metadata and controls

106 lines (77 loc) · 3.2 KB
Raw

Scheduler Design (Scope 5)

Clan OS Scope 5 uses a preemptive, round-robin context scheduler for kernel tasks.

Core Policy

  • Quantum: SCHED_QUANTUM_TICKS = 5
  • Runtime quantum override API: set_scheduler_quantum_ticks(ticks)
  • Runtime fairness-interval API: set_fairness_check_interval_ticks(ticks)
  • Atomic runtime config API: apply_runtime_config(config)
  • Trigger: timer tick sets reschedule flag each quantum boundary
  • Switch path: deferred preemption checkpoint in task loops (preempt_if_irq_pending)
  • Selection: round-robin over runnable context tasks

Context Switch Flow

  1. Timer IRQ increments scheduler ticks (on_timer_tick)
  2. Quantum expiry sets NEED_RESCHEDULE and IRQ preempt pending flag
  3. Running task reaches checkpoint (preempt_if_requested / preempt_if_irq_pending)
  4. Scheduler selects next runnable task pair
  5. switch_context saves current CPU context and restores next

Fairness & Telemetry

  • Per-task metrics (TaskMetrics): switches, cpu ticks, preemption attempts/successes
  • Kernel fairness counters: KERNEL_TASK_1..4_COUNT
  • Runtime fairness monitor: log_preemption_fairness
  • Fairness violation threshold: score > 1.10

Fairness score is computed as:

$$ \text{fairness_score} = \frac{\max(\text{task counters})}{\min(\text{task counters})} $$

A score close to 1.0 indicates balanced scheduling.

Observability

Scope 5 observability components:

  • Global counters:
    • process creations / terminations
    • total preemptions
    • fairness violations
    • scheduler lock contention
  • Event ring buffer (EVENT_LOG_CAPACITY = 256):
    • event type
    • tick timestamp
    • pid/task id
  • Performance snapshot (PerformanceCounters::read) includes:
    • timer ticks
    • total preemptions
    • scheduler lock contention
    • fairness violations

Public Scheduler API

Main public APIs in task::scheduler:

  • on_timer_tick()
  • try_context_reschedule()
  • preempt_if_requested()
  • preempt_if_irq_pending()
  • spawn_context_task(name, entry)
  • spawn_preemption_lab_tasks()
  • stats() and context_stats()
  • get_task_metrics(id) and get_all_task_metrics()
  • scheduler_lock_contention()
  • scheduler_quantum_ticks() / set_scheduler_quantum_ticks()
  • fairness_check_interval_ticks() / set_fairness_check_interval_ticks()
  • runtime_config() / apply_runtime_config()

Running

Preemptive mode:

cargo run -p kernel --features preemption

Integration validation:

cargo test -p kernel --features preemption --test preemption_integration

Budgeted matrix validation:

python scripts/validation_matrix.py --soak-duration 30 --latency-duration 30 --boot-wait 90 --smoke-timeout 180

Current enforced budgets in matrix mode:

  • fairness score <= 1.10
  • max estimated preemption latency <= 300ms (matrix default)
  • scope-6 runtime smoke line must report all true flags

Scheduler CR3 (Scope 31)

Preemptive context switch applies the next runnable process user CR3 via apply_scheduler_cr3_for_next. Process records store cr3_phys when hardware page tables are built.

SMP (Scope 49)

smp::init() records CPU and parked AP counts and provides TLB flush hooks. Scheduling still runs on the bootstrap processor only. See SMP.md.