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 sing
le core is now the special case of a one-bit CpuSet.

Key changes:

• awkernel_lib: adds a const-friendly CpuSet type ([u64; NUM_MAX_CPU / 64], i.e. 512 CPUs) with const fn constructors (empty, from_bits, insert, contains, is_empty, masked_workers, all_workers) so it can be embedded in the const-evaluated PRIORITY_LIST.
• 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. 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.
• 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.
• Preemption: invoke_preemption now 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.
• Renames: PartitionedTask → ClusteredTask (now holding a CpuSet and updating the per-CPU counter for every core in the set), 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.
• Bug fix: fixes a pre-existing lost-wakeup bug in wake_workers — break → continue so higher-numbered CPUs with queued clustered tasks are no longer skipped when the global task count reaches zero.

Related links

• Crate: https://crates.io/crates/affinity_btree_queue
• Source: https://github.com/ytakano/affinity_btree_queue

How was this PR tested?

• cargo check_std, cargo check_x86 (no_std target), cargo clippy_std — all pass with no warnings.
• cargo test_awkernel_async_lib — 42 passed.
• make x86_64 RELEASE=1 — builds successfully.
• Booted in QEMU (-smp 4) with the test_clustered_edf feature:
  • core pinning: single-core CpuSet tasks ran only on their assigned core (cores 1–3) — all [OK].
  • cluster affinity: a task with CpuSet {1, 2} only ever ran on cores 1 or 2 — all [OK].
  • 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.

Notes for reviewers

• SchedulerType grows from 16 bytes to ~72 bytes (still Copy); it is only passed by value on the spawn path.
• The get_next_task(false) path (RR preemption tick, primary CPU only) can never dequeue a clustered task b
  ecause spawn always removes CPU 0 from every set — same invariant as before. This is noted in a comment in
  clustered_edf::get_next.
• The single queue Mutex is only ever acquired while GLOBAL_WAKE_GET_MUTEX is held (both in wake_task a
  nd via the get_next_task wrapper), so no new lock cycle is introduced. invoke_preemption still runs befor
  e the queue lock is taken.
• The queue is lazily initialized with num_cpu() on first use (AffinityBTreeQueue::new is not const), f
  ollowing the existing pattern in prioritized_rr.rs. set_num_cpu runs before the first spawn, so num_cp u() is final by then.
• The wake_workers break → continue fix addresses a latent lost-wakeup that becomes more reachable with
  clusters; it is included here rather than split out because the counter semantics changed in the same area.
• mdbook/src/internal/scheduler.md is updated to describe ClusteredEDF and the affinity-aware B-tree queue.

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

CpuSet::iter always evaluates the inner 0..64 filter for every word, so each traversal costs a fixed 512 branch evaluations regardless of how many bits are set or how many words are zero. This runs on the hot path (ClusteredTask::new/take/Drop and invoke_preemption), so even a single-core pinned task pays 512 evaluations to yield one CPU index. Consider skipping zero words and using word.trailing_zeros() with word &= word - 1 to make the cost O(popcount).

[atsushi421]

ClusteredTask::new/take/Drop each loop over the whole cpu_set doing one atomic RMW per member CPU on a distinct cache line. A wide-affinity task (e.g. CpuSet::any(), up to 511 workers) does up to 511 atomics per wake, per dequeue, and per drop, versus O(1) in the old partitioned design. Consider whether a single global clustered-task counter plus the queue's affinity-aware pop_for_cpu could replace the per-CPU array, or at least ensure the loop only touches set bits.

[atsushi421]

The new CpuSet bit logic (masked_workers per-word masking, CPU 0 exclusion, all_workers, cross-word iter) has no unit tests, even though awkernel_lib already unit-tests a comparable bitmap in net/port_bitmap.rs. Consider adding a #[cfg(test)] mod tests covering masked_workers at and around word boundaries (num_cpus of 64/65/128), CPU 0 always excluded, all_workers for several sizes including 1, and iter ordering across words.

[atsushi421]

The empty-set fallback here (mask to empty, warn, fall back to all worker cores) is a distinct code path that no test exercises; the test crate only spawns valid single-core and {1,2} sets. Consider adding a test that spawns a ClusteredEDF task with an invalid set (e.g. CpuSet::empty(), or a set whose only cores are >= num_cpu()) and verifies it still runs on a worker core.

[atsushi421]

This fallback makes an invalid or empty affinity set runnable on every worker core, a much larger blast radius than the previous PartitionedEDF fallback to a single core 1. The only trace of this policy is this runtime warning; it is not mentioned in the cpu_set() doc or the mdbook scheduler section. Consider documenting the fallback so callers know an out-of-range set is normalized to all workers rather than rejected.

[atsushi421]

get_scheduler (and get_priority) take SchedulerType by value, and this find_map copies the full ~72-byte value (now that CpuSet is embedded) out of the reference on every iteration, even though only the discriminant is matched. Consider changing these to take &SchedulerType and binding a reference in the closures to avoid the per-iteration payload copy.

[atsushi421]

from_bits only writes words[0], so it cannot express any CPU >= 64 even though CPU_SET_WORDS supports up to 512. It is also currently unused. Consider accepting [u64; CPU_SET_WORDS], or documenting explicitly that it is limited to the first 64 CPUs (and removing it / any() if they are not part of the intended public API).

[atsushi421]

This comment says the decrement is handled by ClusteredTask::Drop, but the decrement actually happens in the explicit take() call inside get_next (Drop is a no-op once take() has run). Consider rewording to attribute the decrement to take().