This document records code structure, hardware-specific behavior, and implementation constraints that are useful when changing cctl. Unless noted otherwise, hardware observations refer to the tested Colorful Evol P15.
cctl.cincludes subsystem fragments fromsrc/in this order: core, controls, platform, keyboard, fan curves, telemetry, runtime, NVIDIA, snapshots, commands, and driver management. They form one translation unit so private hardware helpers can be shared without exporting symbols. Keep subsystem changes in their owning fragment.- The Makefile builds
cctlfromcctl.c,src/cctl_cpumon.c, andsrc/cctl_gpumon.c. The separate monitor programs share code throughsrc/cctl_monitor_common.handsrc/cctl_shared.h. Theexperimentaltarget enables the optional NVIDIA management commands withCCTL_NVIDIA. Building requirespkg-configand thedbus-1development library for fan-curve suspend notifications; this does not require systemd as PID 1. src/cctl_fancurve.incis included before snapshot and command handlers; its private worker and state helpers are available to those subsystems.
cctl editconf edits a private temporary copy as the invoking user. It saves
through the editconf __install helper, which validates temporary-file owner
and permissions before atomically replacing /var/lib/cctl/profiles.conf.
This uses cctl's installed passwordless sudo rule instead of nested
sudoedit/install commands that would prompt separately for a password.
cctl_live_ec_state() reads the recognized TCC offset from processor thermal
sysfs and falls back to the temperature-target MSR when needed. On the tested
machine, the offsets map as follows:
| TCC offset | EC code | Profile | PROCHOT temperature |
|---|---|---|---|
| 2°C | 2 | High performance | 98°C |
| 13°C | 3 | Standard | 87°C |
| 15°C | 1 | Powersave | 85°C |
| 10°C | 0 | Silent | 90°C |
cctl status prefers a recognized live TCC offset. It falls back to the
tuxedo_io profile cache only when the offset cannot identify a profile. The
cache records profile writes made through tuxedo_io since module load; it
does not observe Fn-key, firmware, or other driver changes. A cache value of
-1 means unknown and is omitted from the status detail. Cache reads are
version-gated because older drivers silently accept unknown ioctls.
The mode label in cctl status is inferred from the EC code and current CPU
governor/EPP; it is not a separately stored EC mode. The runtime state file
does not contain an EC profile code.
The profile names, TCC offsets, and trip temperatures above are specific to
the tested EC and CPU. The load-test README uses the live
tcc_offset_degree_celsius value; P-core and E-core frequencies there are in
MHz.
The PROCHOT value in JSON is inferred from the live EC/TCC state. The
terminal STATE label does not classify temperature against those profile
thresholds. It uses live hardware throttle flags when available and treats
power readings near RAPL limits as estimates. Current classification order in
src/cctl_cpumon.c is:
THERMAL THROTTLEwhen a live thermal-throttle flag is set.RECENT THERMAL EVENTwhen the package throttle counter increased within the last two seconds.POWER LIMIT ACTIVEwhen the hardware power-limit flag is set.NEAR PL2 (est.)at 98% of the reported PL2 value or higher.ABOVE PL1 (est.)above 102% of PL1.NEAR PL1 (est.)at 90% of PL1 or higher while total CPU utilization exceeds 60%.IDLEbelow 10% utilization. Otherwise,NORMALappears only when the hardware status read succeeded; if it failed, the display saysSTATUS N/A.
The monitor reads the RAPL TAU from
/sys/class/powercap/intel-rapl:0/constraint_0_time_window_us; it does not
assume a fixed time window. Hardware throttle flags come from
IA32_PACKAGE_THERM_STATUS, with per-core IA32_THERM_STATUS as fallback.
The package power-limit status is bit 10; the current thermal status is bit 0.
Threshold estimates compare sampled package power with the configured RAPL
limits and do not prove that a limit caused throttling.
- With the tested Intel
intel_pstatesetup, theperformancegovernor locks EPP toperformance. Thepowersavegovernor allows the configured EPP to guide clock scaling. Built-in profiles therefore usepowersaveand vary EPP. - During snapshot restore, a saved EPP that cannot be applied under the live
performancegovernor causes cctl to switch topowersavewhen the governor was not itself saved or masked. Masking EPP avoids that adjustment. - EC profile codes 2 and 3 require fan-auto safety when applied through
cctl set; Turbo ON requires it when the current EC code is 2 or 3.--nosafebypasses this. If a fan curve is active, profile and Turbo safety steps are skipped so the curve retains fan control. - Snapshot restore sets fans to EC AUTO at the start before applying settings,
even when a curve is active;
--nosafebypasses this initial AUTO step. The snapshot's saved curve configuration is applied last. Code is incctl_snapshot_restore()andcctl_snapshot_apply_fan_safety().
- Writes are restricted to package 0 (
/sys/class/powercap/intel-rapl:0), after verifying that constraint 0 islong_term; PL1 goes to constraint 0 and PL2 to constraint 1. Do not write sub-zones orpsys. On the tested laptop, writing those zones caused an EC conflict and a 0.4 GHz CPU throttle; treat this as a hardware-specific observation. - PL1 is limited to 45 W normally and 90 W while EC code 2 is active. The EC
may enforce lower defaults in codes 0, 1, and 3. PL2 is capped at 115 W and
must remain greater than PL1. The invariant is enforced by the command,
custom profile loading, snapshot restore, and
set_rapl_limits(). - If a snapshot requests PL1 above 45 W without applying EC code 2, restore skips PL1 and can still apply PL2.
cctl set maxprints a model-specific advisory that sustained CPU power can reach 60–90 W and temperatures can approach 98°C under heavy load. It recommendscpuperforbalancedfor lighter use.
gpumonrunsnvidia-smitelemetry queries only while the dGPU is in PCI power state D0. Thepkey pauses or resumes NVIDIA polling; cctl fan readings continue while polling is paused or the GPU is in D3cold.- The effective GPU power limit uses
enforced.power.limit, thenpower.limit, thenpower.max_limitas fallbacks.power.max_limitis retained separately for the gauge scale and JSON output. Avoid hardcoding example wattages; limits vary by profile and hardware. - On the tested EC, the GPU fan duty in
FANINFO1is stuck near 15%. Read GPU duty from the low byte ofFANINFO2instead.
Fan control uses two paths:
tuxedo_iohandles both-fan duty writes (W_CL_FANSPEED) and automatic control (W_CL_FANAUTO). The all-fan automatic-control mask is0x0f.W_CL_FANSPEEDsets both channels to manual duty together.cctl fan maxuses this ioctl with raw duty255(100%); if it fails, cctl falls back to the EC MAX mode sequence.- Direct EC port I/O handles individual fan duty, SILENT mode, and the MAX
fallback. The
protocol uses command port
0x66, data port0x62, and waits for the input buffer to clear before each write. Individual fan duty uses command0x99with{ fan_index, raw_duty }, where CPU is 1, GPU is 2, andraw_duty = percent * 255 / 100. - MAX fallback and SILENT send mode command
0x98(0x40and0x20respectively), followed by0x99for each fan. In this sequence the arguments are{ fan_index, value }. Standalone automatic restore has a firmware quirk: command0x99must instead receive{ 0xff, fan_index }. cctl fan autofirst usesW_CL_FANAUTO; if that fails, it restores each fan through the direct EC standalone-auto sequence described above.
Implementation lives in src/cctl_fancurve.inc; profiles are stored as JSON
under /var/lib/cctl/fancurves/.
- Profiles require 2–16 points, strictly increasing temperatures from 0–95°C,
fan speeds from 25–100%, hysteresis from 0–20°C, and a polling interval
from 250–60000 ms. Only the final point may use
"a"or"auto". - Numeric points are interpolated linearly. Below the first point the first
speed is used; above the final numeric point the final speed is held. A
final AUTO point switches to EC control at its temperature and resumes the
curve below
auto_temp - hysteresis. interval_mssets the worker polling delay. A new duty is written only when the target changes and the temperature has moved by at leasthysteresissince the previous duty write.- The worker controls both fans using the hotter valid CPU/GPU fan-sensor
temperature. It reads the third byte of
R_CL_FANINFO1/2; CPUhwmonand NVIDIAnvidia-smitemperatures are fallbacks. - Above 95°C, after three consecutive temperature-read failures, or after
three consecutive fan-duty write failures, the worker attempts to restore EC
auto. It retries ioctls, can reload
clevo_acpiandtuxedo_io, and finally falls back to direct EC auto. Following a successful safety handoff, the curve resumes below 90°C. The thermal condition is strictly above 95°C. - On this EC, duties 13–24% clamp to 25%, and duties below 13% turn the fans off. The profile minimum is therefore 25%.
- Starting a curve requires
tuxedo_io0.3.10 or newer, both driver modules, and/dev/tuxedo_io. The worker arms the driver's per-file close recovery before writing manual duty. Closing the worker's descriptor restores EC automatic control, including afterSIGKILL; unrelated cctl commands use their own descriptors and do not trigger it. - The open descriptor holds a module reference, so unloading
tuxedo_iofails while the worker is active. Stop the worker before replacing drivers. The currentdriverinstall.shretries module unload, warns if a module is still in use, then continues with DKMS cleanup/install; it does not stop the fan-curve worker itself. - The worker is detached and takes an exclusive
flockon/run/cctl_curve.lock./run/cctl_curve.staterecords PID, process start time, profile name, and start time. Matching the process start time prevents a reused PID from being mistaken for the worker.stopwaits for that worker to exit before returning.saliasesstart, andstaliasesstop; legacysetandoffare also accepted. createandeditopen the configured editor as the invoking user. When the profile directory is not writable, a restrictedfancurve __installhelper validates the temporary file and profile before installing it. Replacing an existing profile requires confirmation. Editing or deleting the currently active profile is refused.- While active, the curve owns both fans.
cctl fan autostops it before restoring EC auto; other fan overrides are refused.cctl setand Turbo skip changes that would take control away from the curve. - Snapshot format 5 embeds the active curve's hysteresis, interval, and all
temperature/fan points in the snapshot file; it does not depend on the saved
profile file at restore time. The worker publishes its active configuration
in
/run/cctl_curve.state, allowing a snapshot to capture the values the worker actually runs even if its profile file was removed or changed. Bothcctl fancurve startand snapshot restore use the samefc_start_profile()validation and restart path. Restore applies curve state last and starts an embedded configuration with the internal labelsnapshot-<snapshot_name>; the start message identifies the source snapshot. Format 4 remains readable with fan-curve config and no battery mode; format 3 uses the referenced profile file when available and format 2 skips curve state. Earlier formats have no saved battery mode.--mask fancurveskips saved curve state. At restore start, cctl always sets both fans to EC AUTO, even when a curve is active. The target curve state is applied last.--nosafebypasses the initial AUTO step; the older--mask nosafeform remains accepted but is deprecated. Thebatmask skips charge mode and thresholds. Manual fan duties are not captured, and snapshots do not start automatically at boot. - The worker listens for login1
PrepareForSleepsignals over the system D-Bus and holds a delay inhibitor while active. On suspend it closes its armedtuxedo_iodescriptor, triggering the driver's EC-auto close recovery; on resume it reacquires the inhibitor, reopens the driver, arms close recovery again, and forces a fresh curve write. This works with systemd-logind or elogind regardless of init system. If no login1-compatible manager is available, the curve runs without suspend auto-restore and cctl notes that when starting it. - After a suspend request, the worker stays in EC auto and polls temperatures
without writing fan duty. While the machine is actually suspended, user space
cannot run; polling continues once execution resumes. If the login1 wake
signal was missed, the worker resumes the curve when a valid CPU/GPU reading
exceeds
FANCURVE_SLEEP_RESUME_TEMP(85 C). If the worker exits entirely, the driver's close recovery leaves fans in EC auto; no detached worker can resume after process exit. - On the tested EC, the CPU fan-info temperature may read
1 Cimmediately after resume. Treat that reading as invalid and use the CPU hwmon fallback before selecting the hottest temperature for the curve.
R_CL_PERF_PROFILE reports the last performance profile written through
tuxedo_io since module load, or -1 when unknown. Fn-key, firmware, and
other driver writes are outside this cache. cctl status uses a recognized
live TCC-derived code first and the cache as a fallback; it omits cache data
when the value is -1.
The installer sets force_backlight_type=6 for tuxedo_keyboard. On the
tested Colorful Evol P15 the EC reports keyboard type 0x26, which the driver
does not recognize. Its low nibble matches the driver's 1-zone RGB type 0x06;
the idea that the high bits indicate a newer revision is a hypothesis. The
override bypasses detection and makes the supported 1-zone controls available.
The driver can also expose fixed-white (1), 3-zone RGB (2), and per-key
RGB (243) types, but cctl's keyboard commands currently support only 1-zone
RGB. LEDs are exposed under /sys/class/leds; the 1-zone device is
rgb:kbd_backlight.
- The tested Insyde H2O firmware uses UEFI NVRAM for MUX mode.
cctl mux switchchangesSetup-a04a27f4-df00-4d42-b552-39511302113dat file offset 430 (0x03= MSHybrid,0x02= dGPU only). The variable is 1204 bytes and the code rejects an unexpected size or mode. It stages the change for the next boot; it cannot switch the physical display MUX during the current session. Other firmware-synchronized bytes are left untouched. When on battery below 10%, switching is refused to reduce the risk of power loss during the NVRAM write. - In dGPU mode on this laptop, X11 starts the internal panel at 40 Hz on each
boot. The panel EDID lists 40 Hz as its preferred timing and 165 Hz in the
DisplayID extension. The NVIDIA X driver starts at 40 Hz;
xrandrstill lists 165 Hz, andcctl rr 165selects it. This is a model/driver observation, not a general dGPU behavior.
- The expected archive SHA-256 is
DRIVERS_SHA256insrc/cctl_drivers_cli.inc. Keep it synchronized with the verified archive stored under the matching SHA-256 directory intuxedo-drivers-cctl-mirror. - The release workflow reads that constant, downloads
<sha256>/drivers.tar.gzfrom the mirror without rebuilding it, verifies the checksum, and attaches the verified archive to the release. drivers-managesearches for a valid archive in this order: verified/var/lib/cctl/drivers.tar.gzcache, a matching archive beside the cctl binary, a fresh mirror download, then a user-provided full path. Every candidate is checked against the embedded hash before extraction. A verified candidate is cached before extraction so later reinstall or uninstall can work offline.