Skip to content

Discover optional Lerwatt advice without manual integration setup #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Denny-Lin merged 2 commits into from
Nov 2, 2026
Merged

Discover optional Lerwatt advice without manual integration setup #8

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
537e066
Automatically discover optional Lerwatt advice in normal operation
Denny-Lin Nov 2, 2026
d658da0
Allow bounded deployment fixture transactions on slower musl runners
Denny-Lin Nov 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,11 @@

<p align="center">CPU scheduling that learns inside the Linux kernel.</p>

Lertick always owns its scheduling model. New installations automatically exchange
compatible, fresh advice with a running Lerwatt; no peer-specific install flag is
required. Missing or removed peers leave scheduling independent. Neither project
starts, replaces or retrains the other. [Automatic coordination](docs/INTEGRATION.md).

## Performance at a glance

**Lertick online mode recorded 50.34% lower short-burst completion p99 than Linux EEVDF in our VM benchmark.** Mixed-contention tests also expose clear regressions:
Expand Down
12 changes: 6 additions & 6 deletions deploy.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Usage: ./deploy.sh COMMAND [OPTIONS]
restart Restart this service; never stop another scheduler.
enable Start now and enable this service at boot.
disable Stop now and disable this service at boot.
integration [on|off|status] Persist optional Lerwatt coordination (default off).
integration [auto|on|off|status] Persist optional Lerwatt coordination (default auto).
update Build/verify a candidate before stopping/replacing this service.
rollback Restore the previous complete release, preserving service intent.
uninstall Disable/stop this service and remove its installed files.
Expand Down Expand Up @@ -106,16 +106,16 @@ validate_options()
case $command in
plan|run|trial) validate_options "$@" ;;
integration)
[ "$#" -le 1 ] || fail 'integration accepts on, off or status'
case ${1:-status} in on|off|status) ;; *) fail 'integration accepts on, off or status' ;; esac
[ "$#" -le 1 ] || fail 'integration accepts auto, on, off or status'
case ${1:-status} in auto|on|off|status) ;; *) fail 'integration accepts auto, on, off or status' ;; esac
;;
report) for arg in "$@"; do case $arg in --include-logs|--help) ;; *) fail "unsupported report option: $arg" ;; esac; done ;;
*) [ "$#" -eq 0 ] || fail "$command does not accept options" ;;
esac
if [ "$command" = plan ]; then
printf 'Run plan (not executed; requires a compatible idle sched_ext kernel):\n'
if [ "$duration" -eq 0 ]; then set -- --summary-only --sample-ms 60000 "$@"; fi
for word in sudo "$loader" --mode online --duration 0 --track-all --cpuperf auto "$@"; do
for word in sudo "$loader" --mode online --duration 0 --track-all --cpuperf auto --lerwatt-auto "$@"; do
escaped=$(printf '%s' "$word" | sed "s/'/'\\\\''/g"); printf " '%s'" "$escaped"
done
printf '\nNo scheduler was loaded or attached.\n'; exit 0
Expand Down Expand Up @@ -274,9 +274,9 @@ if [ "$duration" -eq 0 ]; then
else printf 'Lertick: starting finite foreground scheduler; Ctrl-C detaches it.\n' >&2; fi
[ -z "$pending_signal" ] || finish_run "$pending_status"
if [ "$stats_requested" = yes ]; then
"$loader" --mode online --duration "$base_duration" --track-all --cpuperf auto "$@" &
"$loader" --mode online --duration "$base_duration" --track-all --cpuperf auto --lerwatt-auto "$@" &
else
"$loader" --mode online --duration "$base_duration" --track-all --cpuperf auto "$@" >/dev/null &
"$loader" --mode online --duration "$base_duration" --track-all --cpuperf auto --lerwatt-auto "$@" >/dev/null &
fi
child=$!
[ -z "$pending_signal" ] || stop_run "$pending_status"
Expand Down
6 changes: 3 additions & 3 deletions docs/DEPLOYMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -385,8 +385,8 @@ overlay from the read-only base.

## CPU frequency targets and the Lerwatt plug-in

Native service setup is now available through `lertick integration on` and
Lerwatt's `./deploy.sh install --lertick`. Models and release versions remain
New managed services and foreground helper runs discover optional Lerwatt advice
automatically; ordinary installations need no peer-specific flag. Models and release versions remain
independent; compatible model-only updates do not change the contract ABI.
See [setup, ownership and ABI compatibility](INTEGRATION.md) before using the
raw-loader research commands below.
Expand All @@ -402,7 +402,7 @@ lowers idle CPUs' targets. `auto` selects `util` when any policy's
a VM without cpufreq, `auto` keeps the previous behavior. The registered event
records `cpuperf` and `cpuperf_reason`; snapshots then add a `cpus` array.

`--lerwatt` pins `lw_contract` and `lt_demand` under `/sys/fs/bpf/lertick/`
`--lerwatt-auto` enables best-effort discovery and keeps ordinary scheduling if publication is unavailable. It does not force `cpuperf util` merely because no peer is present. The advanced strict `--lerwatt` mode pins `lw_contract` and `lt_demand` under `/sys/fs/bpf/lertick/`
before attaching, publishes demand every 100 ms, and unpins them at exit; a
pin failure aborts before the default scheduler is replaced. Clusters are the
cpufreq policies sorted by first CPU. Without real policies, Lertick uses a
Expand Down
2 changes: 1 addition & 1 deletion docs/INSTALL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ lertick trial --mode shadow --duration 30 \

The default bounds are 0.5–5 ms after eight valid labels, with a 2 ms fallback. They bound newly assigned budgets, not exact execution time or the remaining budget of an already running task. Lower prediction error has not established a general throughput or latency advantage; consult the [recorded comparisons](PHASE2_RESULTS.md) and [long-window confirmation](../results/model-confirmation/README.md).

The helper forwards `--mode`, `--duration`, `--sample-ms` and `--stats-json`; tracking and CPU-performance defaults are fixed for this simple path. Optional persistent Lerwatt coordination uses `lertick integration on`; follow the [shared integration guide](INTEGRATION.md) to configure both projects. For targeted tracking, partial switching, full research snapshots or model experiments, use the advanced loader instructions in [deployment and reproduction](DEPLOYMENT.md). Model tracking and the set of scheduled tasks are distinct: selecting a TGID for learning alone does not isolate scheduling to that process.
The helper forwards `--mode`, `--duration`, `--sample-ms` and `--stats-json`; tracking and CPU-performance defaults are fixed for this simple path. New installations automatically discover compatible Lerwatt advice; no integration-enable command is needed. Existing saved opt-outs remain respected. Follow the [shared integration guide](INTEGRATION.md) to configure both projects. For targeted tracking, partial switching, full research snapshots or model experiments, use the advanced loader instructions in [deployment and reproduction](DEPLOYMENT.md). Model tracking and the set of scheduled tasks are distinct: selecting a TGID for learning alone does not isolate scheduling to that process.

## Telemetry and permissions

Expand Down
80 changes: 56 additions & 24 deletions docs/INTEGRATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

[← Project home](../README.md) · [Lertick](https://github.com/Denny-Lin/lertick) · [Lerwatt](https://github.com/Denny-Lin/lerwatt)

Use each controller on its own, or enable an optional local link. **Lertick owns scheduling; Lerwatt owns CPU power constraints.** They exchange demand and limits while keeping their models, training and service lifecycles separate.
Each controller works on its own and discovers an optional compatible local peer automatically. **Lertick owns scheduling; Lerwatt owns CPU power constraints.** They exchange demand and limits while keeping their models, training and service lifecycles separate.

```mermaid
flowchart LR
Expand All @@ -16,34 +16,60 @@ flowchart LR
linkStyle default stroke:#86868b,stroke-width:1.5px
```

## Enable the link
## Automatic discovery

First satisfy each project's native Linux requirements. Lerwatt needs usable CPUFreq controls and temperature inputs. Lertick additionally needs a compatible running sched_ext kernel, BTF and its BPF toolchain. Installing these services does not install or change the kernel. A compatible running kernel needs no reboot for activation; changing kernels can require one.
Install each project normally after satisfying its native Linux requirements.
Lerwatt needs CPUFreq controls, temperature inputs and Linux userspace BPF
headers. Lertick also needs a supported running sched_ext kernel, BTF and its
BPF toolchain. Neither installer changes the kernel or installs its peer.

From the **Lerwatt checkout**, as your normal user:
From the Lerwatt checkout, as your normal user:

```sh
./deploy.sh check
./deploy.sh install --lertick --period-ms 100
lerwatt status
./deploy.sh install
```

This builds the BPF-capable daemon locally, then installs, enables and starts Lerwatt. Usable Linux userspace BPF headers are required; Lerwatt's contract uses raw BPF syscalls without libbpf. Its service configuration stores `contract=auto`. Coordination accepts a **10–100 ms** control period; the default is 100 ms. A normal independent installation keeps `contract=off` and the BPF-free build.

From the **Lertick checkout**, as your normal user:
From the Lertick checkout, as your normal user:

```sh
./deploy.sh install
lertick integration on
lertick enable
lertick status
```

Lertick installation adds files without starting or enabling its service. `integration on` saves the optional link setting; `enable` starts now and at boot. Changing integration on an already running managed Lertick service restarts that service with verified settings, preserving its prior active/enabled intent. It does not restart Lerwatt.

**Either project may start first.** An absent or incompatible peer leaves the other operating independently. Neither unit requires the peer through `Requires=` or `BindsTo=`, and neither project starts, stops, upgrades or restarts the peer.

## Check or turn off coordination
New Lerwatt installations save `contract=auto` and build the BPF-capable daemon;
new Lertick installations save `lerwatt=auto`. No `--lertick` installation flag
or `integration on` command is needed. Lertick installation still does not start
or enable scheduling: `enable` is the user's normal service activation, not a
peer-specific step. A plain upgrade preserves saved settings, including explicit
`off` opt-outs from earlier versions. For such a saved opt-out, choose auto once
with `./deploy.sh install --lertick` or `lertick integration auto` respectively.

**Either project may start first.** A service may be installed without running;
installation files alone do not prove a usable peer. Connection requires the
real maps plus matching ABI, topology, attachment session and fresh records.
Missing, stopped, removed, expired or incompatible peers leave local operation
independent. Running peers reconnect automatically; uninstalling a peer does not
stop the remaining controller. Neither service has `Requires=` or `BindsTo=` on
the other, and neither starts, stops, upgrades or retrains its peer.

Discovery is separate from prediction. Lerwatt keeps its own learned thermal
model and MPC, Lertick keeps its own scheduler model. Peer appearance/disappearance
never changes the selected prediction algorithm or private weights. New Lerwatt
installs use nominal MPC; cooperative prediction can be selected separately
with `--prediction cooperative` and retains all reliability gates. Earlier
saved cooperative choices are preserved. Installing Lertick does not make
Lerwatt forecasts more accurate.

Lertick's automatic mode is best effort: inability to discover topology, obtain
an attachment identity or publish maps leaves ordinary scheduling available.
It never overwrites foreign pins. Transport unavailable at initial attachment
requires a later local Lertick restart after the environment is repaired; this
is distinct from an absent peer, which connects later without restart. Raw
loader `--lerwatt` retains strict failure behavior for diagnostics. Raw loader
users can select `--lerwatt-auto`; normal helper/service runs do so automatically.

## Inspect or override discovery

```sh
lerwatt status
Expand All @@ -53,21 +79,27 @@ lertick status
sudo systemctl show lerwatt.service lertick.service --property=StatusText
```

Configured `auto`/`on` means the link is requested. Inspect current worker status and logs for **connected**, **waiting** or **off**; an enabled service or saved setting alone does not prove a fresh compatible exchange. Waiting can mean the peer has not started, its records expired, or its ABI/topology/session is incompatible. Do not interpret a counter from an older run as proof of a current connection.
Configured `auto` means discovery is enabled; it does not mean connected.
Worker status/logs report **connected**, **waiting** or **off**. Waiting includes
an absent/inactive peer and rejected stale/incompatible records. Do not interpret
an older counter or an installed executable as current connectivity. Coordination
uses a 10–100 ms control period, with 100 ms the default.

To keep both controllers but remove their optional link, run this from the Lerwatt checkout:
Advanced explicit opt-outs remain available:

```sh
# From the Lerwatt checkout:
./deploy.sh install --no-lertick
```

Then:

```sh
# Only the Lertick managed service:
lertick integration off
```

Plain Lerwatt reinstallation and Lertick updates preserve their saved integration settings. Lerwatt stores its setting in `/etc/lerwatt/lerwatt.conf`; Lertick uses `/etc/lertick/integration.conf`. Both are private root-owned data files, parsed without sourcing shell code. Turning off coordination does not disable either controller's own learning.
These choices affect exchange, not either controller's learning. They do not
change Lerwatt's selected nominal/cooperative predictor. Lertick changes only
its own service when a managed integration setting is explicitly changed.
The strict legacy `lertick integration on` mode remains available. Configuration
is root-private strict data in `/etc/lerwatt/lerwatt.conf` and
`/etc/lertick/integration.conf`, never sourced as shell commands.

## Control ownership

Expand Down
Loading
Loading