Skip to content

scx_cake: align README with shipped behavior#3643

Open
kurtislin wants to merge 1 commit into
sched-ext:mainfrom
kurtislin:cake/readme-accuracy
Open

scx_cake: align README with shipped behavior#3643
kurtislin wants to merge 1 commit into
sched-ext:mainfrom
kurtislin:cake/readme-accuracy

Conversation

@kurtislin

Copy link
Copy Markdown
Contributor

The scx_cake README documents several mechanisms that don't exist in the code, and in most cases the code comments already say so. This aligns the README with what actually ships (the in-tree scx_cake is unchanged since v1.1.1).

The bigger items:

  • The "VPROT: Preemption Protection" section (O(1) victim finding, per-class protection thresholds, SCX_KICK_PREEMPT kicks) is not implemented anywhere in executable BPF code. cake_select_cpu's own comment says "DSQ ordering handles all priority — no preemption or kicks needed", so the section now describes the DSQ-ordering-only design that actually exists. The nr_vprot_suppressed counter has no BPF writer, so it's gone from the TUI docs too.
  • "Kfunc Tunneling" describes caching scx_bpf_now() in cached_now. That staging was removed; the comment at the removal site says it "had ZERO READERS".
  • The class table contradicts tier_base[] = {8192, 0, 49152, 32768}: the real dispatch order is GAME < NORMAL < BG < HOG, while the README listed HOG before BG with different values.
  • The DRR++ deficit section claims per-bout drain, bonus removal on exhaustion and a GAME exemption. In the shipped code the new-flow flag is set once in init_task and never cleared, and deficit_u16 is initialized but never drained or consulted, so the section now says that.
  • Sleep-lag credit and the waker-boost chain were documented in five places, but the code says "sleep_lag REMOVED" and CAKE_FLOW_WAKER_BOOST has no setter.
  • "TUI still works" in release mode is wrong: the loader force-disables --verbose and --testing in release builds (and warns about it). --starvation is parsed but discarded at its only call site, so it's now marked as unused.
  • The data-structure overview listed five struct fields that don't exist (nice_shift, sleep_lag, cached_cpumask, waker_boost, cached_perf), and the schbench link pointed at a repo that doesn't exist (it's masoncl/schbench).

For what it's worth, the author's out-of-tree nightly branch has independently deleted the remnants of most of these mechanisms, describing them as dead code — so this documents shipped behavior, it isn't a divergence from where the scheduler is headed. Whether the half-wired deficit/new-flow logic should be completed or removed instead is a behavioral question, intentionally not answered here; I'll file that separately. Doc-only change.

The README describes several mechanisms that do not exist in the code,
and the code itself often says so. Bring the documentation in line with
what actually ships:

  - The "VPROT: Preemption Protection" section describes victim
    finding, per-class protection thresholds and SCX_KICK_PREEMPT
    kicks. None of this is implemented: no preemption kick exists in
    executable BPF code, and the comment in cake_select_cpu states
    "DSQ ordering handles all priority - no preemption or kicks
    needed". Replace the section with a description of the actual
    DSQ-ordering-only design. The nr_vprot_suppressed counter has no
    BPF writer, so drop it from the TUI documentation too.

  - The "Kfunc Tunneling" section documents caching scx_bpf_now() in
    cpu_bss[cpu].cached_now. The in-code comment says the staging was
    removed because cached_now "had ZERO READERS". Drop the section
    and the vocabulary entry.

  - The class table contradicts tier_base[] = {8192, 0, 49152, 32768}:
    the real dispatch order is GAME < NORMAL < BG < HOG, while the
    README lists HOG before BG with different values. Fix the table
    and both ordering notes.

  - The DRR++ deficit description claims per-bout deficit drain, bonus
    removal on exhaustion and a GAME exemption. In the shipped code
    the new-flow flag is set once in init_task and never cleared, and
    deficit_u16 is initialized but never drained or consulted.
    Describe the current state instead.

  - Sleep-lag credit and the waker-boost chain are documented in five
    places, but the code says "sleep_lag REMOVED" and
    CAKE_FLOW_WAKER_BOOST has no setter. Replace with the implicit
    sleeper credit that vtime non-advance actually provides.

  - "TUI still works" in release mode is wrong: the loader force-
    disables --verbose and --testing in release builds and warns about
    it. Same for --starvation, which is parsed but discarded at the
    only call site.

  - The data-structure overview lists five fields that do not exist in
    the structs (nice_shift, sleep_lag, cached_cpumask, waker_boost,
    cached_perf). List the real fields.

  - The schbench link points to a nonexistent repository; the project
    lives at masoncl/schbench.

The author's out-of-tree development branch has independently removed
most of these mechanisms' remnants, describing them as dead code, so
this should be uncontroversial as documentation of the shipped v1.1.1
behavior. Behavioral questions (whether to implement or remove the
half-wired deficit/new-flow logic) are intentionally left out and will
be raised separately.

Signed-off-by: Kurtis Lin <klaus.lin.sc@gmail.com>
@hodgesds hodgesds requested a review from RitzDaCat June 10, 2026 17:59
@RitzDaCat

Copy link
Copy Markdown
Collaborator

Valid! I will state that scx_cake is going through quite a lot of code mutations on my nightly branch so I will need to do a pretty heavy review and fix up the readme to match the current scope and design.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants