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.

Profile Table

Trip points are in Celsius, ordered Fan (active) < Processor (passive) < powerclamp (passive).

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.

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 thermal profile (Fan °C / Processor °C / powerclamp °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-reloads, 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

Planned Changes

Effective State (pre → post)

(omit when the outcome is declined or dry_run_only)

Validation Results

Failures and Troubleshooting

Troubleshooting Notes

• thermald not found at /usr/sbin/thermald: install it (sudo apt-get install -y thermald) and re-trigger.
• The skill never prompts for sudo approval. If the script fails because sudo needs a password, configure passwordless sudo out of band first via sudo visudo -f /etc/sudoers.d/set-thermal-profile:

  <user> ALL=(root) NOPASSWD: /home/<user>/enib/tools/power-tuning/set_thermal_profile.sh
  

  Never use NOPASSWD: ALL. If a sudo -v timestamp exists but is not honored (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.
• "None of the expected cooling devices are present; refusing to write an empty zone": this platform exposes no Fan/Processor/intel_powerclamp cooling devices (check grep . /sys/class/thermal/cooling_device*/type). The profile cannot be applied as-is.
• "thermald did not accept the generated config": the script validates in test-mode before installing and aborts without changing the system; inspect the logged excerpt for the offending zone/trip.
• "powerclamp trip too close to Tjmax; use < 105": lower clamp_c below 105 °C.
• "Fan trip (…) must be < Processor trip (…)": trip points must satisfy fan < proc < clamp; reorder them.
• --charge requested but skipped: no CHRG cooling device on this platform; the top trip is written without it.
• If firmware adaptive tables seem to override the profile: confirm the effective ExecStart has --ignore-default-control and no --adaptive (the script's systemd override sets this); check ${OVERRIDE_FILE} if not.

Related Skills

• set-power-profile — cap the package/platform power (PkgWatt/SysWatt) so less heat is produced; the thermal profile then governs the escalation as temperature rises. Apply the power envelope first, then the thermal policy.
• monitor-power-thermal — watch PkgTmp against the trip points while a load runs, to confirm the escalation engages where intended.
• generate-platform-stress — drive the platform hot enough with synthetic load (stress-ng) to exercise the trip points and observe the fan / frequency-cap / idle-injection stages.
• generate-openvino-stress — drive the platform with real AI inference load (OpenVINO benchmark_app on CPU/GPU/NPU) to exercise trip points under realistic workload patterns.
• Typical loop: set a power profile → set this thermal profile → start monitor-power-thermal → run generate-platform-stress or generate-openvino-stress with a bounded duration → confirm temperature holds within the trips without unexpected throttling.