kSTEP: Kernel Scheduler Test and Evaluation Platform

kSTEP is a framework for reproducing and testing Linux kernel scheduler bugs.

Important

OSDI'26 AE reviewers: start with AE.md, not the general getting-started instructions below. docs/AE.md contains the reviewer-specific instructions for accessing our reserved machines and reproducing the paper figures.

🚀 Getting Started

If you are not an OSDI'26 AE reviewer, continue here.

📦 Clone the repository

git clone https://github.com/kstep-dev/kstep

💾 Install dependencies

./install_deps.sh

🐞 Reproduce known bugs

./reproduce.py <name|all> [--run <buggy|fixed|plot>]

• <name|all>: Name of the bug to reproduce (see reproduce.py), or all to reproduce all bugs.

• --run: Choose which version or action to run (buggy, fixed, or generate a plot), default to all.

• Example: ./reproduce.py sync_wakeup checks out both the buggy and fixed kernels, builds kSTEP, runs the sync_wakeup driver, and plots the results.

Note

Reproducing all bugs will require at least 64GB of available disk space.

📊 Results

kSTEP Driver, Fix, and Output	Figure
sync_wakeup.c Official Fix: linux@aa3ee4f Our Fix: sync_wakeup.patch buggy.jsonl, fixed.jsonl
vruntime_overflow.c Fix: linux@bbce3de buggy.jsonl, fixed.jsonl
freeze.c Fix: linux@cd9626e buggy.jsonl, fixed.jsonl
extra_balance.c Fix: linux@6d7e478 buggy.jsonl, fixed.jsonl
driver_util_avg.c Fix: linux@17e3e88 buggy.jsonl, fixed.jsonl
long_balance.c Fix: linux@2feab24 buggy.jsonl, fixed.jsonl
lag_vruntime.c Fix: linux@5068d84 buggy.jsonl, fixed.jsonl
even_idle_cpu.c Fix: even_idle_cpu.patch buggy.jsonl, fixed.jsonl
local_group_imbalance.c Fix: fix_local_group_imbalanced.patch buggy.jsonl, fixed.jsonl
util_avg_jump.c Fix: fix_util_avg_jump.patch buggy.jsonl, fixed.jsonl
rt_runtime_toggle.c Fix: linux@9b58e97 buggy.jsonl, fixed.jsonl
uclamp_inversion.c Fix: linux@0213b70 buggy.jsonl, fixed.jsonl
h_nr_runnable.c Fix: linux@3429dd5 buggy.jsonl, fixed.jsonl

💻 Running Your Own Drivers

For driver development, please refer to AGENTS.md for recommended workflow and tips.

🐧 Checkout Linux source code

./checkout_linux.py <version> [<name>] [--tarball]

• <version>: Linux tag (e.g., v6.14) or commit hash (e.g., 6d7e478, 5068d84~1).

• Example: ./checkout_linux.py v6.14 foo_buggy checks out Linux v6.14 under linux/foo_buggy, and symlinks linux/current to it.

🛠️ Build Linux and kSTEP

make linux [LINUX_NAME=<name>]  # Build kernel
make kstep [LINUX_NAME=<name>]  # Build kSTEP rootfs (default target)

• [LINUX_NAME=<name>]: Name of the Linux directory under linux/, default to what linux/current points to.

🏃‍♂️ Run kSTEP

./run.py <driver_name> [--smp <cpus>] [--mem_mb <mb>] [--log_file <path>]

• <driver_name>: Driver to run (see *.c files in the kmod/drivers/ and kmod/drivers_new_bugs/ directories).

• [--log_file <path>]: Log file to save the output, default to data/logs/latest.log.

• Example: ./run.py sync_wakeup runs the sync_wakeup driver with default parameters.

📁 Directory Structure

• kmod/: Kernel module (kstep.ko) loaded at boot

  • driver.c + driver_*.c: Bug-specific drivers that setup and run test cases
  • driver.h: Public API for drivers (task creation, ticking, sleeping, cgroups, etc.)
  • internal.h and other *.c files: Framework primitives and utilities

• user/: Minimal userspace (init.c) that mounts filesystems and loads kstep.ko

• linux/: Git worktrees of Linux source

  • linux/master: Main clone of Linux kernel
  • linux/current: Symlink to active kernel version
  • linux/*.patch: Fixes for specific bugs

• data/: Data directory

  • data/rootfs: Root filesystem images
  • data/logs: QEMU log files

• scripts/: Python utilities for parsing logs and plotting results