feat(sched): add CPU core affinity via ClusteredEDF scheduler

[ytakano]

Description

Generalizes the PartitionedEDF scheduler — which pinned each task to a single core — into a ClusteredEDF scheduler where each task carries a CpuSet describing the set of cores it may run on. Pinning to a single core is now the special case of a one-bit CpuSet.

Key changes:

• Affinity-aware run queue: replaces the per-core [Mutex<EDFData>; NUM_MAX_CPU] BinaryHeap array with a single affinity-aware priority queue from the affinity_btree_queue crate, vendored in-tree as a workspace member (like smoltcp). get_next pops the earliest-deadline task runnable on the calling CPU via pop_for_cpu. Priority is (absolute_deadline, wake_time), matching the previous EDF ordering, with FIFO tie-breaking on fully-equal keys.
• CpuSet: awkernel_lib's CpuSet is now a type alias of affinity_btree_queue::CpuMask<CPU_SET_WORDS> (512 CPUs), so schedulers pass it to the run queue with no conversion. All constructors are const fn (chainable builder CpuSet::empty().with(1).with(2)), and its iter() is O(popcount). The CPU-0-exclusion policy stays in awkernel_lib as the const free functions cpu::masked_workers / cpu::all_workers.
• API: SchedulerType::PartitionedEDF(u64, u16) → ClusteredEDF(u64, CpuSet); Task.partitioned_core: Option<u16> → Task.cpu_set: Option<CpuSet>. spawn masks out CPU 0 (primary core) and out-of-range bits, and falls back to all worker cores (1..num_cpu()) with a warning when the resulting set is empty. This normalization/fallback contract is documented on the SchedulerType::ClusteredEDF variant and in the mdbook.
• O(1) clustered-task bookkeeping: the per-CPU NUM_CLUSTERED_TASKS_IN_QUEUE counter array is replaced by a single global AtomicU32 plus the run queue's exact affinity mask. ClusteredTask::new/take/Drop now do one atomic RMW instead of one per member CPU (up to 511 for a wide-affinity task). wake_workers reads the precise set of CPUs with an eligible queued task via the new Scheduler::queued_cpu_mask() trait method (default empty; ClusteredEDF implements it with the queue's O(1) affinity_mask()).
• Extensibility: a new clustered scheduler only needs to (1) wrap queue entries in ClusteredTask, (2) implement queued_cpu_mask(), and (3) sit in the clustered prefix of PRIORITY_LIST. SchedulerType::is_clustered() is the single source of truth for the prefix, and a compile-time assertion rejects any reorder that would break it.
• Boot invariant: cpu::sanity_check() (run on the primary CPU) panics if num_cpu() < 2. Awkernel reserves CPU 0 as the primary core and runs tasks only on the worker cores 1..num_cpu(), so a single CPU has no worker core; enforcing this once at boot replaces a confusing downstream panic and keeps the clustered fallback's messaging valid.
• Preemption: invoke_preemption selects the core running the lowest-priority task among the set, and skips preemption entirely (enqueue only) when any core in the set is idle.
• Micro-opt: get_scheduler / get_priority take &SchedulerType so the find_map in get_next_task no longer copies the large (CpuSet-embedding) SchedulerType per iteration.
• Renames: PartitionedTask → ClusteredTask, NUM_PARTITIONED_TASKS_IN_QUEUE → NUM_CLUSTERED_TASKS_IN_QUEUE, get_num_partitioned_schedulers → get_num_clustered_schedulers, test crate test_partitioned_edf → test_clustered_edf.

Related links

• Crate (upstream / crates.io source): https://github.com/ytakano/affinity_btree_queue — the library is vendored under affinity_btree_queue/ in this repo.

How was this PR tested?

• cargo check_std, cargo check_riscv64 (no_std target), cargo clippy_std — all pass with no warnings.
• RUSTFLAGS="-D warnings" make test — all suites pass, including:
  • test_awkernel_async_lib (42),
  • new cpu.rs unit tests for the masked_workers / all_workers worker-mask policy (word boundaries 64/65/128, CPU 0 exclusion, cross-word iter ordering),
  • the vendored test_affinity_btree_queue crate tests (61 unit + 17 doc).
• make x86_64 RELEASE=1 — builds successfully.
• Booted in QEMU (-smp 4) with the test_clustered_edf feature — all [OK], no panic:
  • core pinning: single-core CpuSet tasks ran only on their assigned core (cores 1–3).
  • cluster affinity: a task with CpuSet {1, 2} only ran on cores 1 or 2.
  • EDF preemption: light (earlier deadline) correctly preempted heavy on the same core.
  • multi-core: tasks on cores 1 and 2 ran in parallel without interference.
  • empty-set fallback: tasks spawned with an empty set and with an out-of-range-only set both fell back to worker cores and ran (never on CPU 0).

Notes for reviewers

• SchedulerType grows from 16 bytes to ~72 bytes (still Copy) because it embeds a CpuSet. It is passed by reference on the hot get_next_task path (get_scheduler/get_priority take &SchedulerType) and only by value on the spawn path.
• The get_next_task(false) path (RR preemption tick, primary CPU only) can never dequeue a clustered task because spawn always removes CPU 0 from every set — same invariant as before, noted in clustered_edf::get_next.
• Locking: the single queue Mutex is the innermost lock everywhere (nothing else is acquired while holding it). It is taken under GLOBAL_WAKE_GET_MUTEX in wake_task/get_next_task, and wake_workers now also takes it directly (without GLOBAL_WAKE_GET_MUTEX) to read queued_cpu_mask(); since it is innermost, no lock cycle is introduced. invoke_preemption still runs before the queue lock is taken.
• The queue is lazily initialized with num_cpu() on first use (AffinityBTreeQueue::new is not const), following the existing pattern in prioritized_rr.rs. set_num_cpu runs before the first spawn.
• Known bounded latency (future work): when preemption succeeds, the task is pinned to the victim CPU's preemption-pending heap and is invisible to the other CPUs in its set until the IPI is handled; if another core in the set goes idle meanwhile it cannot pick the task up. This is bounded (IPI delivery + the victim's interrupt-disabled sections) and never a lost wakeup — documented in invoke_preemption. An enqueue-instead-of-pin strategy would close it but touches the pending-heap machinery shared by all schedulers, so it is deferred.
• mdbook/src/internal/scheduler.md is updated to describe ClusteredEDF, the affinity-aware B-tree queue, the global-counter + queued_cpu_mask bookkeeping, and the spawn-time normalization/fallback.

[Copilot]

Pull request overview

Introduces a new ClusteredEDF real-time scheduler that generalizes the prior PartitionedEDF model by allowing tasks to run on a set of worker cores (CpuSet affinity), and updates the surrounding API, tests, and documentation accordingly.

Changes:

• Add CpuSet (const-friendly CPU affinity bitmask) and migrate task/scheduler APIs from single-core pinning to affinity sets.
• Replace per-core EDF runqueues with a single affinity-aware AffinityBTreeQueue, and add a new clustered_edf scheduler implementation.
• Rename and update the userland/kernel test feature and test crate from test_partitioned_edf to test_clustered_edf, plus doc updates/regeneration.

Reviewed changes

Copilot reviewed 18 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
userland/src/lib.rs	Switch test entrypoint feature from test_partitioned_edf to test_clustered_edf.
userland/Cargo.toml	Rename optional dependency + feature flag to test_clustered_edf.
kernel/Cargo.toml	Rename kernel feature passthrough to test_clustered_edf.
awkernel_lib/src/cpu.rs	Add CpuSet type and related helpers/constants.
awkernel_async_lib/src/task.rs	Replace partitioned_core with cpu_set, update counters and wake logic.
awkernel_async_lib/src/scheduler.rs	Register ClusteredEDF, update scheduler type API, add clustered counter RAII wrapper.
awkernel_async_lib/src/scheduler/partitioned_edf.rs	Remove the old PartitionedEDF scheduler implementation.
awkernel_async_lib/src/scheduler/clustered_edf.rs	Add new ClusteredEDF scheduler implementation using AffinityBTreeQueue.
awkernel_async_lib/Cargo.toml	Add affinity_btree_queue dependency.
applications/tests/test_clustered_edf/src/lib.rs	Update tests to exercise core pinning and multi-core affinity via CpuSet.
applications/tests/test_clustered_edf/Cargo.toml	Rename test crate to test_clustered_edf.
mdbook/src/internal/scheduler.md	Update scheduler docs from PartitionedEDF to ClusteredEDF.
docs/print.html	Regenerated docs including new ClusteredEDF content (and additional RISC-V sections).
docs/internal/scheduler.html	Regenerated scheduler page reflecting ClusteredEDF.
docs/internal/page_table.html	Regenerated docs content (adds RISC-V sections).
docs/internal/memory_allocator.html	Regenerated docs content (adds RISC-V sections).
docs/internal/interrupt_controller.html	Regenerated docs content (adds RISC-V sections).
docs/internal/arch/mapper.html	Regenerated docs content (adds RISC-V sections).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[atsushi421]

The branch bundles the Rust nightly-2026-07-20 toolchain bump (#702) and its fixups (ixgbe.rs, smoltcp tcp.rs, fatfs dir_entry.rs, pvclock.rs, delay.rs, if_net.rs, Dockerfile, CI workflow), which are unrelated to CPU affinity and inflate the review surface. Consider landing #702 on main first and rebasing this PR so those changes drop out of the diff, or stating in the description that the newer nightly is a prerequisite.

---

The docs/ regeneration carries pages unrelated to this PR (RV32/64 mapper, page_table, interrupt_controller, memory_allocator, plus the book.toml and mdbook/src/LICENSE.md changes). Consider regenerating docs from an up-to-date main or limiting the generated-HTML changes to the scheduler pages, and moving the book.toml/LICENSE.md fix to a separate docs PR.

[atsushi421]

When the clustered prefix above returns None, this fallback re-runs the clustered schedulers' get_next. The queue state is frozen under GLOBAL_WAKE_GET_MUTEX, so the second call deterministically returns None, at the cost of an extra queue-mutex acquisition and an O(log N) affinity probe on every get_next_task. Iterating PRIORITY_LIST[get_num_clustered_schedulers()..] here would skip the already-tried prefix and also structurally rule out a clustered task ever reaching the NUM_TASK_IN_QUEUE decrement below.

[atsushi421]

This PR changes the signature to fn get_scheduler(sched_type: &SchedulerType), but this line (and the function table near the top of the page) still shows the old by-value signature. Please update both mentions.

[atsushi421]

This links to coverage.txt, but the file is not committed anywhere in the PR, so the link 404s on GitHub. Consider committing the file, noting it must be generated locally, or dropping the link.

[ytakano]

@atsushi421

The branch bundles the Rust nightly-2026-07-20 toolchain bump (#702) and its fixups (ixgbe.rs, smoltcp tcp.rs, fatfs dir_entry.rs, pvclock.rs, delay.rs, if_net.rs, Dockerfile, CI workflow), which are unrelated to CPU affinity and inflate the review surface. Consider landing #702 on main first and rebasing this PR so those changes drop out of the diff, or stating in the description that the newer nightly is a prerequisite.

Thank you. Merged main.

The docs/ regeneration carries pages unrelated to this PR (RV32/64 mapper, page_table, interrupt_controller, memory_allocator, plus the book.toml and mdbook/src/LICENSE.md changes). Consider regenerating docs from an up-to-date main or limiting the generated-HTML changes to the scheduler pages, and moving the book.toml/LICENSE.md fix to a separate docs PR.

I regenerated the docs.
mdbook automatically generates mdbook/src/LICENSE.md and RV32/64's pages.
So, can you ignore generated contents for review?