# galpt/scx_timely architecture

> Architecture diagram of the GitHub repository galpt/scx_timely, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/galpt/scx_timely
- Repository: https://github.com/galpt/scx_timely

## Overview

`scx_timely` is a two-part `sched_ext` scheduler: a Rust userspace controller/loader and an eBPF kernel scheduling core. The repo also includes build-time code generation plus shell tooling for installation, enablement, and benchmarking.

#### High-level architecture

The system is organized around one main boundary:

- **Userspace Rust crate**: parses mode/CLI options, loads and configures the scheduler, and gathers status/metrics.
- **Kernel eBPF program**: implements the actual CPU scheduling behavior inside the Linux `sched_ext` framework.

Everything else in the repo either supports that boundary or exercises it.

#### Main runtime components

##### 1) Rust userspace entrypoint
- `src/main.rs` is the executable entrypoint.
- It is the orchestration layer for:
  - command-line parsing / mode selection
  - choosing one of the built-in presets: `desktop`, `powersave`, or `server`
  - applying controller knobs to the scheduler
  - starting or attaching to the `sched_ext` program
  - reporting scheduler state and health

This layer is the part the install and benchmark scripts invoke.

##### 2) Scheduler statistics / observability
- `src/stats.rs` is the userspace-side metrics/reporting module.
- It is likely responsible for collecting and formatting scheduler state that is surfaced to the CLI, status script, and benchmark logs.

This is not the policy itself; it is the visibility layer around it.

##### 3) Kernel scheduling logic
- `src/bpf/main.bpf.c` is the kernel-side BPF program.
- `src/bpf/intf.h` defines the C-side interface shared with userspace.
- This is where the actual `sched_ext` hooks and TIMELY-inspired policy live.

Architecturally, this is the core control loop:
- tasks are enqueued/dequeued by the kernel scheduler hooks
- queue delay is measured
- the TIMELY-style controller interprets delay and delay-gradient feedback
- slice gain / placement decisions are adjusted using additive increase, multiplicative decrease, and faster recovery behavior

The README makes clear that the policy is a TIMELY adaptation:
- RTT maps to task queue delay
- send-rate control maps to per-task slice gain
- `Tlow` / `Thigh` map to low/high queue-delay thresholds

##### 4) Generated Rust-BPF interface
- `src/bpf_intf.rs` and `src/bpf_skel.rs` are generated or build-assisted bindings that connect the Rust loader to the BPF program.
- They form the typed boundary between Rust userspace and the kernel BPF object.

This is an important architectural seam: the Rust side configures and monitors the BPF scheduler, but the policy execution happens in kernel space.

#### Build-time architecture

##### 5) Build script and BPF compilation
- `build.rs` is part of the build pipeline that prepares the BPF artifact and generated bindings.
- `Cargo.toml` / `Cargo.lock` define the Rust crate and its dependency graph.

The build process likely:
- compiles the BPF C source
- generates the skeleton/interface bindings
- packages the Rust binary with the BPF object so the userspace loader can deploy it at runtime

This is a standard `sched_ext`/libbpf-style split: the Rust binary is the controller/loader, while the BPF object is the in-kernel implementation.

#### Operational and deployment tooling

These files are not core scheduler logic, but they matter to how the system is used:

- `install.sh`, `uninstall.sh`
  - integrate the scheduler with the local machine
  - manage `/etc/default/scx`
  - enable/disable `scx.service`
- `enable_scx_timely.sh`, `status_scx_timely.sh`
  - reassert or inspect the active scheduler configuration
- `install_benchmark_deps.sh`, `benchmark.sh`, `mini_benchmarker.sh`, `kill_benchmark.sh`, `mini_benchmarker_plot.py`
  - benchmark orchestration and result plotting
  - compare baseline Linux, `scx_cake`, `scx_bpfland`, and `scx_timely`

These scripts sit outside the runtime data path, but they are important for understanding the repo as a scheduler project rather than a library.

#### Data flow

A simplified runtime flow looks like this:

1. A user or system service launches `scx_timely` through the install/enable scripts or directly via CLI.
2. `src/main.rs` selects a preset or applies overrides.
3. The Rust loader uses the generated skeleton/interface bindings to load and configure the BPF scheduler.
4. The kernel-side BPF program in `src/bpf/main.bpf.c` receives `sched_ext` events and makes per-task scheduling decisions.
5. The BPF program feeds back queue-delay information and controller state.
6. `src/stats.rs` and the CLI surface status/metrics to userspace.
7. Benchmark scripts can repeatedly start runs, collect metrics, and compare modes or schedulers.

#### Important boundaries

##### Userspace vs kernel space
This is the primary architectural boundary:
- **Rust userspace** = configuration, lifecycle, telemetry, deployment
- **BPF kernel code** = latency-sensitive scheduling policy

##### Policy vs presets
The scheduler uses one controller structure with different default parameter sets:
- `desktop` favors interactive responsiveness
- `powersave` is more conservative
- `server` widens placement/policy behavior for heavier throughput-oriented loads

So the repo has a single policy engine with multiple tuning profiles, not separate scheduler implementations.

##### Base scheduler inheritance
The project is explicitly built on upstream `scx_bpfland`.
That means:
- it inherits the `bpfland` scheduler structure
- it narrows and reinterprets the control layer around TIMELY-like feedback
- the repo is an adaptation layer, not a full rewrite

#### External/runtime dependencies that matter architecturally

- **Linux `sched_ext`**: the kernel framework that makes this a pluggable scheduler
- **Upstream `scx`/`scx_bpfland`**: the base scheduler behavior and workspace alignment
- **systemd `scx.service` / `/etc/default/scx`**: deployment and persistence mechanism on the host
- **Benchmark utilities and plotting tools**: used to validate and tune the scheduler across profiles

#### What to draw in an architecture diagram

A clear diagram would have these boxes:

- User / benchmark scripts
- Rust userspace scheduler binary
- Generated Rust-BPF interface
- Kernel eBPF scheduler
- Linux `sched_ext` / task scheduling hooks
- Metrics/status output path

And these flows:
- CLI/presets from scripts into the Rust binary
- configuration from Rust into BPF
- scheduling events and queue-delay feedback inside the kernel BPF loop
- status/metrics from scheduler back to userspace and benchmark logs
- install/enable scripts into systemd and `/etc/default/scx`

In short: `scx_timely` is a `sched_ext` scheduler with a Rust control plane and a BPF data-plane, where the kernel-side policy is a TIMELY-inspired adaptation layered on top of `scx_bpfland`.

Main entry points: [`src/bpf/main.bpf.c`](https://github.com/galpt/scx_timely/blob/HEAD/src/bpf/main.bpf.c) (BPF core), [`src/main.rs`](https://github.com/galpt/scx_timely/blob/HEAD/src/main.rs) (Main), [`build.rs`](https://github.com/galpt/scx_timely/blob/HEAD/build.rs) (Build script), [`install.sh`](https://github.com/galpt/scx_timely/blob/HEAD/install.sh) (Install)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Runtime"
  loader["Main<br/>userspace loader<br/>[main.rs]"]
  stats["Stats<br/>telemetry<br/>[stats.rs]"]
  bpf_core{{"BPF core<br/>sched_ext policy<br/>[main.bpf.c]"}}
  bpf_intf_h["C interface<br/>shared header<br/>[intf.h]"]
  sched_ext(("sched_ext<br/>kernel framework"))
end

subgraph "Build"
  bpf_iface_rs["BPF iface<br/>generated bindings<br/>[bpf_intf.rs]"]
  bpf_skel["Skeleton<br/>generated loader<br/>[bpf_skel.rs]"]
  build_rs["Build script<br/>build pipeline<br/>[build.rs]"]
end

subgraph "Ops"
  scripts["Scripts<br/>entry/tools"]
  systemd["systemd<br/>host integration"]
  default_cfg["Default cfg<br/>host config"]
  install_sh["Install<br/>deployment script<br/>[install.sh]"]
  uninstall_sh["Uninstall<br/>deployment script<br/>[uninstall.sh]"]
  enable_sh["Enable<br/>ops script"]
  status_sh["Status<br/>ops script"]
  bench["Benchmark<br/>[benchmark.sh]"]
  mini_bench["Mini bench<br/>benchmark runner"]
  plot["Plot<br/>results viz"]
end

scripts -->|"launch/configure"| loader
scripts -->|"install"| install_sh
scripts -->|"enable"| enable_sh
scripts -->|"inspect"| status_sh
scripts -->|"benchmark"| bench
scripts -->|"orchestrate"| mini_bench
bench -->|"visualize"| plot
mini_bench -->|"visualize"| plot
install_sh -->|"manage"| systemd
install_sh -->|"write"| default_cfg
uninstall_sh -->|"remove"| systemd
uninstall_sh -->|"cleanup"| default_cfg
loader -->|"report"| stats
loader -->|"load"| bpf_skel
loader -->|"configure"| bpf_iface_rs
build_rs -->|"generate"| bpf_skel
build_rs -->|"generate"| bpf_iface_rs
build_rs -->|"compile"| bpf_core
bpf_skel -->|"load artifact"| bpf_core
bpf_iface_rs -->|"mirror"| bpf_intf_h
bpf_core -->|"shared ABI"| bpf_intf_h
bpf_core -->|"runs on"| sched_ext
bpf_core -.->|"emit state"| stats
loader -.->|"control loop"| bpf_core

click loader "https://github.com/galpt/scx_timely/blob/main/src/main.rs"
click stats "https://github.com/galpt/scx_timely/blob/main/src/stats.rs"
click bpf_iface_rs "https://github.com/galpt/scx_timely/blob/main/src/bpf_intf.rs"
click bpf_skel "https://github.com/galpt/scx_timely/blob/main/src/bpf_skel.rs"
click build_rs "https://github.com/galpt/scx_timely/blob/main/build.rs"
click bpf_core "https://github.com/galpt/scx_timely/blob/main/src/bpf/main.bpf.c"
click bpf_intf_h "https://github.com/galpt/scx_timely/blob/main/src/bpf/intf.h"
click install_sh "https://github.com/galpt/scx_timely/blob/main/install.sh"
click uninstall_sh "https://github.com/galpt/scx_timely/blob/main/uninstall.sh"
click enable_sh "https://github.com/galpt/scx_timely/blob/main/enable_scx_timely.sh"
click status_sh "https://github.com/galpt/scx_timely/blob/main/status_scx_timely.sh"
click bench "https://github.com/galpt/scx_timely/blob/main/benchmark.sh"
click mini_bench "https://github.com/galpt/scx_timely/blob/main/mini_benchmarker.sh"
click plot "https://github.com/galpt/scx_timely/blob/main/mini_benchmarker_plot.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class loader,stats,bpf_core,bpf_intf_h,sched_ext toneBlue
class bpf_iface_rs,bpf_skel,build_rs toneAmber
class scripts,systemd,default_cfg,install_sh,uninstall_sh,enable_sh,status_sh,bench,mini_bench,plot toneMint
```

## Components

### Runtime

Active scheduler control and kernel policy path

- [Main](https://github.com/galpt/scx_timely/blob/HEAD/src/main.rs): userspace loader · CLI entrypoint and scheduler orchestrator · `src/main.rs`
- [Stats](https://github.com/galpt/scx_timely/blob/HEAD/src/stats.rs): telemetry · Userspace reporting and metrics formatting · `src/stats.rs`
- [BPF core](https://github.com/galpt/scx_timely/blob/HEAD/src/bpf/main.bpf.c): sched_ext policy · Kernel scheduler logic and TIMELY-style control loop · `src/bpf/main.bpf.c`
- [C interface](https://github.com/galpt/scx_timely/blob/HEAD/src/bpf/intf.h): shared header · Shared userspace-kernel interface definitions · `src/bpf/intf.h`
- **sched_ext**: kernel framework · Linux pluggable scheduler hooks and execution model

### Build

Code generation and compilation support

- [BPF iface](https://github.com/galpt/scx_timely/blob/HEAD/src/bpf_intf.rs): generated bindings · Typed Rust boundary to the kernel scheduler · `src/bpf_intf.rs`
- [Skeleton](https://github.com/galpt/scx_timely/blob/HEAD/src/bpf_skel.rs): generated loader · Generated BPF skeleton used by the Rust loader · `src/bpf_skel.rs`
- [Build script](https://github.com/galpt/scx_timely/blob/HEAD/build.rs): build pipeline · Prepares BPF artifacts and generated bindings · `build.rs`

### Ops

Installation, enablement, and benchmarking tooling

- **Scripts**: entry/tools · Install, enable, status, and benchmark entrypoints
- **systemd**: host integration · Service management and persistent enablement
- **Default cfg**: host config · /etc/default/scx configuration managed by scripts
- [Install](https://github.com/galpt/scx_timely/blob/HEAD/install.sh): deployment script · Installs and configures the scheduler · `install.sh`
- [Uninstall](https://github.com/galpt/scx_timely/blob/HEAD/uninstall.sh): deployment script · Removes scheduler integration · `uninstall.sh`
- [Enable](https://github.com/galpt/scx_timely/blob/HEAD/enable_scx_timely.sh): ops script · Reasserts active scx_timely configuration · `enable_scx_timely.sh`
- [Status](https://github.com/galpt/scx_timely/blob/HEAD/status_scx_timely.sh): ops script · Inspects active scheduler state · `status_scx_timely.sh`
- [Benchmark](https://github.com/galpt/scx_timely/blob/HEAD/benchmark.sh): benchmark script · Runs comparative scheduler benchmarks · `benchmark.sh`
- [Mini bench](https://github.com/galpt/scx_timely/blob/HEAD/mini_benchmarker.sh): benchmark runner · Small benchmark orchestration helper · `mini_benchmarker.sh`
- [Plot](https://github.com/galpt/scx_timely/blob/HEAD/mini_benchmarker_plot.py): results viz · Plots benchmark results · `mini_benchmarker_plot.py`

## Connections

- Scripts → Main: launch/configure · Scripts invoke the Rust scheduler binary with presets or overrides
- Scripts → Install: install · Installation path for host integration
- Scripts → Enable: enable · Enables the active scheduler configuration
- Scripts → Status: inspect · Reads back scheduler state and health
- Scripts → Benchmark: benchmark · Benchmark entrypoint for comparative runs
- Scripts → Mini bench: orchestrate · Mini benchmark workflow helper
- Benchmark → Plot: visualize · Benchmark results are plotted for analysis
- Mini bench → Plot: visualize · Mini benchmark output is plotted
- Install → systemd: manage · Installs or enables the scheduler service
- Install → Default cfg: write · Populates host default configuration
- Uninstall → systemd: remove · Disables or removes the service integration
- Uninstall → Default cfg: cleanup · Removes host configuration
- Main → Stats: report · Surfaces scheduler health and metrics
- Main → Skeleton: load · Uses the generated skeleton to load the scheduler
- Main → BPF iface: configure · Uses typed bindings to set controller state
- Build script → Skeleton: generate · Produces the BPF skeleton during build
- Build script → BPF iface: generate · Produces Rust-side interface bindings during build
- Build script → BPF core: compile · Builds the BPF scheduler artifact
- Skeleton → BPF core: load artifact · Skeleton wraps the compiled kernel program
- BPF iface → C interface: mirror · Rust bindings mirror the shared C interface
- BPF core → C interface: shared ABI · Kernel code uses the shared interface definitions
- BPF core → sched_ext: runs on · Kernel policy executes through sched_ext hooks
- BPF core → Stats: emit state · Scheduler state is surfaced back to userspace reporting
- Main → BPF core: control loop · Userspace configures and monitors the kernel policy
