set-thermal-profile

## Purpose `set_thermal_profile.sh` generates, applies and verifies a **thermald** thermal profile. It builds a `/etc/thermald/thermal-conf.xml` with a staged escalation on the CPU package sensor (`x86_pkg_temp`): ``` Fan (active) < Processor (passive) < intel_powerclamp (passive) fans on early cap CPU frequency inject idle cycles (hard limit) ``` then makes thermald the sole thermal authority (systemd drop-in with `--ignore-default-control` and **without** `--adaptive`, so firmware DPTF/GDDV adaptive tables do not override the trip points) and verifies the result. This skill only automates the reference script. The thermal profile pairs with the power envelope from `set-power-profile`: the power cap bounds how much heat is produced, while this thermal profile governs how the platform reacts as package temperature rises. ## Terminology Acronyms and terms used throughout this skill. | Term | Meaning | |---|---| | thermald | The Linux thermal daemon that consumes the generated `thermal-conf.xml` and drives the cooling devices. | | trip point | A temperature threshold at which a cooling action is engaged. | | active trip | A cooling response that does **not** cost performance — here, turning fans on. | | passive trip | A cooling response that **reduces performance** to shed heat — frequency capping or idle injection. | | x86_pkg_temp | The CPU package temperature sensor the profile escalates on. | | Fan | The active cooling device (fans) engaged at the first (lowest) trip. | | Processor | The passive cooling device that caps CPU frequency at the middle trip. | | intel_powerclamp | The passive cooling device that injects idle cycles (hard limit) at the top trip. | | CHRG | The battery-charge cooling device; optionally added to the top trip when present (`--charge`). | | Tjmax | The silicon's maximum junction temperature (~110 °C); the top trip must stay below it. | | DPTF / GDDV | Firmware adaptive thermal framework/tables that would override the config unless thermald runs without `--adaptive`. | | cooling device | A `/sys/class/thermal/cooling_device*` the kernel exposes (Fan, Processor, intel_powerclamp, CHRG, …). | | systemd drop-in | An `override.conf` that re-declares thermald's `ExecStart` so our config is authoritative. | | dry_run | Preview mode: print the plan and generated XML without writing anything or touching the daemon. | ## Profile Table Trip points are in Celsius, ordered Fan (active) < Processor (passive) < powerclamp (passive). | Profile | Fan | Processor | powerclamp | Notes | |---|---|---|---|---| | cool | 55 | 70 | 80 | Aggressive cooling; fans on early, runs coolest/quietest-at-cost-of-perf | | warm *(default)* | 60 | 75 | 85 | Balanced | | hot | 70 | 90 | 95 | Lets the platform run warmer before intervening | | thermal-max | 95 | 100 | 104 | Pushes to Tjmax headroom; **runs hot** | | custom | `--fan` | `--proc` | `--clamp` | Supply your own trip points | ## Trigger Phrases - set thermal profile - apply thermal profile - set thermal profile to cool / warm / hot / thermal-max - configure thermald / set thermald trip points - set cpu thermal trip points - generate thermal-conf.xml - make thermald the sole thermal authority - set custom thermal trips (fan/proc/clamp) - add CHRG cooling device to thermal profile - disable thermald / revert to kernel default thermal control - run hot / run cool thermally ## Required Inputs - enib_home: absolute path to this repository root (default: current workspace root). On a host provisioned with Infrastructure Blueprint, the developer source tree lives at `/opt/edge/developer`, so `enib_home` is `/opt/edge/developer` on the target system. - profile: one of `cool`, `warm`, `hot`, `thermal-max`, or `custom`. Optional; defaults to `warm` when not supplied — the skill does not prompt for it. Passed via `--profile/-p` (a bare positional word is rejected by the script). - fan_c: Fan (active) trip in Celsius. **Only for `custom`** (required there); ignored for named profiles unless explicitly overriding. - proc_c: Processor (passive) trip in Celsius. **Only for `custom`** (required there). - clamp_c: powerclamp (passive) trip in Celsius. **Only for `custom`** (required there). - charge: `true` | `false` (default: `false`). When `true`, add the CHRG (battery charge) cooling device to the top trip **if present** on the platform (`--charge`). - output_file: optional path. When set, write the generated XML there and make **no** daemon changes (`-o FILE`). Implies no install. - disable: `true` | `false` (default: `false`). When `true`, stop thermald and disable it at boot (`--disable`), reverting to kernel default thermal control. Ignores profile options; leaves config/override files untouched. - dry_run: `true` | `false` (default: `false`). When `true`, only the plan and generated XML are shown; nothing is written and no service is touched (`--dry-run`). - auto_confirm: `true` | `false` (default: `false`). When `true`, skip the confirmation gate. ## Preconditions Run silently without user prompts: - [ ] Skill file exists and is readable: - `test -f <enib_home>/skills/set-thermal-profile/SKILL.md` - [ ] The thermal script exists and is executable: - `test -x <enib_home>/tools/power-tuning/set_thermal_profile.sh` - [ ] `thermald` is installed (needed to validate and run the config; not needed for `dry_run` or `output_file` mode): - `test -x /usr/sbin/thermald` - if missing, stop and instruct: install it (Ubuntu: `sudo apt-get install -y thermald`), then re-trigger. - [ ] Host is x86_64 with an Intel CPU (sanity check; non-fatal warning if not): - `uname -m` and `grep -m1 -o 'GenuineIntel' /proc/cpuinfo` - [ ] Detect the cooling devices present (informational; the script omits steps for absent devices and refuses to write an empty zone): - `grep -s . /sys/class/thermal/cooling_device*/type` — note whether `Fan`, `Processor`, `intel_powerclamp` (and `CHRG` when `charge=true`) are present. - [ ] **Sudo probe (MANDATORY before any apply / `--disable`)** — the script mutates `/etc/thermald/` and restarts the service and does **not** self-elevate: run `sudo -n true`. If exit is non-zero, do NOT apply; stop and instruct the user to run `sudo -v` in their terminal (or add a scoped `NOPASSWD` entry for the absolute path to `set_thermal_profile.sh` in `/etc/sudoers.d/`), then re-trigger. If `sudo -v` was already run but `sudo -n true` still fails (tty_tickets), make timestamps global: `echo 'Defaults timestamp_type=global' | sudo tee /etc/sudoers.d/agent-timestamp && sudo chmod 0440 /etc/sudoers.d/agent-timestamp && sudo visudo -c`. Never collect a password via prompts, env vars, scripts, or logs. `dry_run=true` and `output_file` mode need no sudo (read-only / no daemon changes). See [AGENTS.md](../../AGENTS.md#sudo-handling-must-follow-for-all-skills-that-invoke-sudo). Prompt only for missing required inputs: - [ ] Do not prompt when `profile` is omitted — default to `warm`. - [ ] Only for `profile=custom`: if any of `fan_c`, `proc_c`, `clamp_c` is missing, ask for the three trip points (the script requires all three for `custom`). Input validation (fail closed before running the script): - [ ] `profile` matches one of `cool|warm|hot|thermal-max|custom`. Otherwise stop and list the valid profiles. - [ ] For `custom` (or when overriding a named profile): `fan_c`, `proc_c`, `clamp_c` are positive integers satisfying `fan_c < proc_c < clamp_c` and `clamp_c < 105` (must stay below Tjmax). Warn if `fan_c < 30` (near idle; CPU may stay throttled). - [ ] `output_file`'s parent directory exists and is writable (when supplied). - [ ] `disable`, `charge`, `dry_run`, `auto_confirm` are booleans. `disable=true` is mutually exclusive with profile/custom trip options (the script ignores them under `--disable`). ## Steps **Terminal command rules (MUST follow for every command in this skill):** - Always invoke scripts by **absolute path** — never prefix with `cd`. - Never combine `cd` with any output redirection (`>`, `>>`, `2>`, `2>&1`, `| tee`) in the same compound command — this triggers the VS Code approval dialog. Run them as separate commands if both are needed. - Never use `$(...)` command substitution in terminal commands — VS Code blocks them with an approval dialog. The script handles all internal computation itself. 1. Resolve the plan (no writes yet). Build the argument list: - Base: `<enib_home>/tools/power-tuning/set_thermal_profile.sh --profile <profile>` - For `custom`, append `--fan <fan_c> --proc <proc_c> --clamp <clamp_c>`. - Append `--charge` only when `charge=true`. - For `output_file` mode, append `-o <output_file>` (no daemon changes). - For `disable=true`, use `--disable` instead of the profile/trip options. 2. **Always execute a dry run first** (read-only, no sudo, no writes) unless the invocation is `output_file`-only: - Run the resolved command with `--dry-run` (add `--disable` when disabling) and capture the summary and the generated XML verbatim. - This runs unconditionally on every apply invocation, including when `auto_confirm=true`. 3. **Render the Planned Changes as a table** built from the dry-run output: profile, resolved Fan/Processor/powerclamp trips, CHRG yes/no, which cooling devices are present vs will be wired in, config target (`/etc/thermald/thermal-conf.xml` or `output_file`), and the effective `ExecStart`. Show it before any write. 4. **Confirmation gate** — pause before any write: - If `dry_run=true`: stop here and record `CONFIRMATION=dry_run_only`. Do not apply. - Else if `output_file` is set: this only writes the XML (no daemon changes) — treat as low-risk; still show the plan, then proceed (respect `auto_confirm`; otherwise confirm). - Else if `auto_confirm=true`: log `AUTO_CONFIRM=true` and continue. - Else: present the tabulated Planned Changes and ask "Apply the <profile> thermal profile (Fan <F>°C / Processor <P>°C / powerclamp <C>°C) and make thermald the sole thermal authority on this host? (yes/no)" (or, for disable: "Stop and disable thermald, reverting to kernel default thermal control? (yes/no)"). On anything other than `yes`/`y` (case-insensitive), stop and record `CONFIRMATION=declined`. 5. Apply (only after confirmation). The script does **not** self-elevate, so prefix with `sudo` for apply / `--disable` (not for `--dry-run` or `-o`): - `sudo <enib_home>/tools/power-tuning/set_thermal_profile.sh --profile <profile> [custom/charge flags]` - The script validates the generated XML in thermald test-mode, backs up any existing config/override, installs, `daemon-reload`s, restarts thermald, and verifies the running daemon. Capture stdout/stderr verbatim and record the exit code. 6. Capture the effective state for the report (read-only): - `systemctl is-active thermald` - the effective `ExecStart` and the confirmation line the script prints (sole thermal authority ✔ / warning). - current package temperature (the script prints it at the end). ## Validation Validation section is criteria-only. Do not render the pass/fail results table here. - Preconditions passed (script executable; `thermald` present for apply; sudo probe = 0 when an apply/disable is intended). - `profile` validated; for `custom`, trip points validated for ordering (`fan < proc < clamp`), `clamp < 105`, and positive integers. - A dry run was executed first on every apply invocation, and the Planned Changes table was rendered from its output before the confirmation gate. - Confirmation gate outcome recorded as one of: `confirmed`, `auto_confirm`, `declined`, `dry_run_only`. - Apply phase only executed when the outcome is `confirmed` or `auto_confirm`. - When applied, the script exited with code `0`, thermald is `active`, and the effective `ExecStart` contains `--ignore-default-control` and **not** `--adaptive` (sole thermal authority). - When `output_file` mode, the XML was written to the given path and no daemon changes were made. - When `disable=true`, thermald is stopped and disabled and the script reported kernel default thermal control now applies. ## Rollback - Re-run with a different `profile` to change the trip points (the script backs up the previous config to `${CONF_FILE}.bak` and the override to `${OVERRIDE_FILE}.bak`). - Restore the previous config manually: `sudo cp /etc/thermald/thermal-conf.xml.bak /etc/thermald/thermal-conf.xml && sudo systemctl restart thermald`. - To fully revert to kernel default thermal control, run the skill with `disable=true` (`--disable`): it stops thermald and disables it at boot, leaving config/override files untouched. Re-enable later with `sudo systemctl enable --now thermald`. - The config and systemd override persist across reboot (unlike the runtime-only RAPL power cap from `set-power-profile`). ## Safety Rules - Never collect a sudo password and never prompt for sudo approval during skill execution; passwordless sudo is expected to be pre-configured (scoped `NOPASSWD` for the absolute path to `set_thermal_profile.sh`). Never collect a password via prompts, env vars, scripts, or logs. - **Never combine `cd` with output redirection** in the same compound terminal command — VS Code blocks such commands. Use absolute paths; split commands if redirection is needed. - **Never use `$(...)` command substitution in terminal commands** — VS Code blocks them. Delegate all computation to the script. - Warn before applying `thermal-max` (runs near Tjmax) or a high `custom` `clamp_c` on thermally constrained (e.g. fanless) enclosures — the platform will run hot and may thermally throttle only very late. - On a fanless enclosure the `Fan` active step is omitted (no such device); note that the platform then relies solely on the passive steps (frequency cap + idle injection). - The script restarts `thermald` to load the new profile; note the brief management gap. If the script aborts mid-run it restores the previously running daemon. - Do not modify anything outside `tools/power-tuning/`, `/etc/thermald/`, and the thermald systemd drop-in the script manages. ## Expected Result Summary Render the report as the following tables. ### Run Metadata | Field | Value | |---|---| | Preconditions | PASS/FAIL | | Host | `<uname -m>` + CPU model name | | Mode | `apply` / `output-file` / `disable` | | Profile | `<profile>` (n/a when disabling) | | Fan trip | `<F>°C (active)` | | Processor trip | `<P>°C (passive)` | | powerclamp trip | `<C>°C (passive)` | | CHRG device | `yes` / `no` | | Config target | `/etc/thermald/thermal-conf.xml` or `<output_file>` | | Dry run only | `true` / `false` | | Confirmation | `confirmed` / `auto_confirm` / `declined` / `dry_run_only` | ### Planned Changes | Item | Value | Notes | |---|---|---| | STEP 1 (active) | Fan @ `<F>`°C | omitted if no Fan device | | STEP 2 (passive) | Processor @ `<P>`°C | frequency cap; omitted if no Processor device | | STEP 3 (passive) | intel_powerclamp @ `<C>`°C | idle injection; omitted if absent | | Thermal authority | `--ignore-default-control`, no `--adaptive` | thermald is sole authority | ### Effective State (pre → post) (omit when the outcome is `declined` or `dry_run_only`) | Field | Before | After | |---|---|---|