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.

[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?