scx-adapt

README

scx-adapt

What is it?

scx-adapt is basically a profiling tool for sched_ext schedulers. Main goal is to choose and attach the appropiate scheduler for the current workload type since there is not a one-size-fits-all solution for CPU scheduling.

In YAML configuration files, sched_ext schedulers with their paths, priorities (scx-adapt iterates over schedulers and their criteria in order of their priorities) and their selection criteria are set. Schedulers get attached to kernel depending on the value of system performance metrics (e.g. load average).

Example configuration file

interval: 1000
schedulers:
  - path: "rr.o"
    loader: external
    structName: "sched_ops"
    priority: 1
    criterias:
      - value_name: load_avg_1
        less_than: 2
  - path: "/home/dogukan/schedulers/cfs.o"
    loader: external
    structName: "sched_ops"
    priority: 2
    criterias:
      - value_name: io_psi_some_10
        more_than: 50
  - path: "scx_central"
    loader: builtin
    log: true
    parameters:
      - "-s=50"
    priority: 3
    criterias:
      - value_name: load_avg_5
        more_than: 4

• interval: System metrics reading period of scx-adapt (in milliseconds)
• path: Filepath of sched_ext scheduler (BPF bytecode or executable). Relative filepaths are also supported but it is recommended to write absolute paths.
  • Schedulers added via add-scheduler command, can be called by their filenames in profile configuration file (stored in /var/lib/scx-adapt/schedulers by default).
• loader: Scheduler loader type:
  • external: BPF bytecode without the linker/loader logic. Linked using scx-adapt's linker.
  • builtin: Executable, links BPF program itself and has userspace counter-part.
• structName (REQUIRED to link builtin-loader schedulers): BPF map key of the struct which holds pointers of scheduling methods.
• parameters (optional) (ONLY for builtin-loader schedulers): Arguments to execute builtin-loader scheduler with.
• priority: Priority of scheduler (1-139). scx-adapt starts checking the schedulers' criteria in order of their priorities (smaller value, higher priority). Attaches the first matching scheduler to the kernel.
• log (optional) (ONLY for builtin-loader schedulers): Logging on or off (true|false) for builtin-loader scheduler. Stdout and stderr of scheduler process are piped into a log file which is located at /var/log/scx-adapt/ (by default).
• criterias: Criterias depending on the current value of system performance metrics. For now, it supports more_than and less_than
• value_name: System metric name
  • Currently supported metrics:
    • (cpu|io|mem)_psi_(some|full)_(10|60|300)
    • load_avg_(1|5|15)
    • procs_running
    • procs_blocked
    • procs_disk_io

Using scx-adapt

• scx-adapt [command]

Command	Explanation
add-profile <profile_path>	Add scx-adapt profile configuration to profiles folder
check-dependencies	Check dependencies of scx-adapt
check-profile <profile_path>	Check if profile file in YAML format is valid
install-service	Add Systemd service file 'scx-adapt@.service' to '/etc/systemd/system'
list-profiles	List profile configurations in profiles folder
log-csv <csv_file_path> [interval]	Print system variables to file in csv format
log-sched	Print sched_ext event tracing to stdout
remove-profile <profile_filename>	Remove profile configuration from profiles folder
remove-service	Remove Systemd service file 'scx-adapt@.service' in '/etc/systemd/system'
start-profile <profile_path>	Run scx-adapt with the profile configuration
status	Print currently running sched_ext scheduler.
add-scheduler --loader external|builtin <scheduler_path(s)...>	Add sched_ext scheduler to schedulers folder
remove-scheduler --loader external|builtin <scheduler_filename>	Remove scheduler from schedulers folder
list-schedulers	List schedulers in schedulers folder

Systemd service

[Unit]
Description=scx-adapt daemon for profile at %I
StartLimitIntervalSec=30
StartLimitBurst=2 

[Service]
Type=exec
ExecStart=/usr/bin/scx-adapt start-profile  %i
Restart=on-failure

[Install]
WantedBy=multi-user.target

scx-adapt service self-heals unless schedulers, which are defined inside the YAML configuration file, fail more than twice within 30 seconds (by default).

To install the service file and enable/start the service:

• $ scx-adapt install-service
• $ systemctl enable scx-adapt@<profile_path>
• $ systemctl start scx-adapt@<profile_path>

To disable/stop and delete service file:

• $ systemctl disable scx-adapt@<profile_path>
• $ systemctl stop scx-adapt@<profile_path>
• $ scx-adapt remove-service

Logs

For userspace schedulers (with log: true), standart output and standart error streams are written into log files which are located in /var/log/scx-adapt by default.

captain@fedora:/var/log/scx-adapt 🚢🐳 $ ls -1
2026-05-10_16-51-23_scx_central.log
2026-05-10_17-27-38_scx_beerland.log
2026-05-10_17-32-55_scx_rustland.log
2026-05-10_17-35-35_scx_simple.log
2026-05-10_17-47-34_scx_chaos.log

Installation

go install

go install github.com/dogukanmeral/scx-adapt@latest

Pre-compiled executables and distribution packages are not available but I plan to add automated releases as soon as possible.

Dependencies

The kernel has to be built with the following configuration:

• CONFIG_BPF=y
• CONFIG_BPF_SYSCALL=y
• CONFIG_BPF_JIT=y
• CONFIG_DEBUG_INFO_BTF=y
• CONFIG_BPF_JIT_ALWAYS_ON=y
• CONFIG_BPF_JIT_DEFAULT_ON=y
• CONFIG_SCHED_CLASS_EXT=y

https://github.com/sched-ext/scx#build--install

Further development

I (Doğukan Meral) have been the sole developer for scx-adapt while my friend Onur Karagür is currently working on performance analysis of schedulers and ways to optimize scx-adapt configurations using machine learning techniques on the scx-adapt-experiments repository.

Your feedbacks, suggestions, criticisms and most importantly your contributions are highly appriciated. Feel free to contact me at my e-mail address dogukan.meral@yahoo.com

Helpful resources for bpf and sched_ext / Inspirations for this project

• Johannes Bechberger's minimal scheduler repository and blog article
• Andrea Righi's neural network scheduler video
• scx repository which contains many Sched_ext schedulers and tools
• Perfetto: Browser based and locally running scheduler trace visualisation and analysis tool
• Changwoo Min's 'sched_ext: a BPF-extensible scheduler class' and 'sched_ext: scheduler architecture and interfaces' blog articles

License

scx-adapt is licensed under GPLv2. See LICENSE.

Documentation

Overview

Copyright © 2026 Doğukan Meral <dogukan.meral@yahoo.com>