IdleScope

English | 한국어

English

Evidence-based Linux deep-idle blocker diagnosis.

IdleScope observes package C-states and PCIe state, classifies the symptom, produces evidence-scored suspects, and applies a fail-closed safety policy. It is not a PowerTOP replacement, automatic BIOS tuner, generic power optimizer, or dashboard.

Read-only diagnosis covers CPU/package idle, PCIe link power, generic runtime PM, NVMe/APST visibility, SATA ALPM, NIC/EEE, USB autosuspend, GPU runtime PM, wakeup sources, and background activity. A mechanism finding is not a confirmed blocker and never creates causal evidence by itself.

The evidence score is a transparent heuristic, not a probability. Every score contribution has a human-readable reason, and unavailable counters remain unavailable rather than becoming zero.

Status and active-operation warning

Diagnosis remains read-only by default. v1.0.0 retains one explicitly requested active operation: experiment run TARGET --method DRIVER_DETACH --execute. It is available only for a current SAFE, leaf PCIe mechanism target with MEDIUM/HIGH evidence, complete dependencies, observable unbind/bind controls, and verifiable restoration. probe still always refuses with exit code 2. No other power policy or device operation is active.

User installation (Ubuntu/Debian)

Install the release .deb; it keeps its Python dependencies under /usr/lib/idlescope and does not run sudo pip or modify the host Python environment. Python 3.11 through 3.13 is required.

Fast install from the GitHub release on x86-64 Ubuntu 24.04 (system Python 3.12):

curl -LO https://github.com/Putpocket/IdleScope/releases/download/v1.0.0/idlescope_1.0.0_amd64.deb
curl -LO https://github.com/Putpocket/IdleScope/releases/download/v1.0.0/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS
sudo apt install ./idlescope_1.0.0_amd64.deb
idlescope --help

For Debian, Proxmox, other Ubuntu versions, and other Linux distributions, install the wheel in an isolated environment:

python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install https://github.com/Putpocket/IdleScope/releases/download/v1.0.0/idlescope-1.0.0-py3-none-any.whl
idlescope --help

sudo apt install ./idlescope_1.0.0_amd64.deb
command -v idlescope
idlescope --help
sudo idlescope doctor
sudo idlescope inventory
sudo idlescope quiet
sudo idlescope diagnose
sudo apt remove idlescope

turbostat is optional but required for package C-state measurements. Collection permissions depend on the host configuration.

Developer installation and packaging

python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
.venv/bin/ruff check .
.venv/bin/mypy idlescope
.venv/bin/python -m build
tests/integration/wheel_smoke.sh dist/idlescope-1.0.0-py3-none-any.whl
sudo apt install python3-venv
scripts/build-deb.sh

Snapshots default to ~/.local/share/idlescope/snapshots and contain the raw inventory and measurement statistics (median, min, max, sample count).

Repeated baselines are stored separately under ~/.local/share/idlescope/sessions:

sudo idlescope measure --name baseline --repeat 5
sudo idlescope measure --name metered --repeat 5 --wall-power-command /path/to/read-watts
idlescope trends baseline
idlescope compare baseline metered --intervention "manual observation"

The wall-power command is executed directly without a shell and must print one numeric watt value (an optional W/watts suffix is accepted). IdleScope does not claim that an arbitrary user command is read-only; only trusted meter-reader commands should be configured. PkgWatt and wall watts remain separate metrics. Repeated identical observations increase reproducibility, not correlation. Correlation requires path-state variation, and intervention text alone never creates causal evidence.

Manual A/B/A experiments link existing sessions without changing the host:

idlescope experiment create --name hba-test --target 0000:01:00.0
idlescope experiment add hba-test --phase before hba-before
idlescope experiment intervention hba-test \
  --type manual_hardware_change --description "manual removal"
idlescope experiment add hba-test --phase after hba-after
idlescope experiment add hba-test --phase restore hba-restored
idlescope experiment analyze hba-test

The user performs and is responsible for every intervention outside IdleScope. An A/B/A return can provide strong counterfactual evidence, but manual experiments are capped at MEDIUM causal evidence and never automatically identify a specific blocker. Wall-power samples record their provider type and trust provenance; command providers are marked user_asserted.

CLI workflow

Start with the compact system summary, drill into the ranked validation targets, and request a narrative only when it is useful:

idlescope status
idlescope plan
idlescope show 01:00.0
idlescope explain 01:00.0
idlescope optimize

The commands intentionally have separate roles:

• status summarizes the latest deep-idle evidence.
• plan ranks meaningful validation candidates.
• show presents structured state for one target.
• explain describes why that target received its assessment.
• optimize separates verified improvements from unverified investigation targets.

Multi-domain findings and transaction foundation

IdleScope calibrates multi-domain findings before ranking them. MECHANISM findings can be validation candidates, CONTEXT explains the diagnosis, CONFOUNDER limits measurement quality, and OPPORTUNITY describes device/link power policy without claiming a package-idle blocker. A control interface being present does not by itself make a finding auto-testable. Virtual network interfaces remain dependency topology rather than hardware power targets, and DRM connectors are subordinate state of their gpu:cardN target.

The transaction model supports the active experiment and recovery workflow:

idlescope transaction status
idlescope transaction status --json
idlescope transaction preflight 01:00.0 --method DRIVER_DETACH
idlescope transaction preflight 01:00.0 --method DRIVER_DETACH --json

The durable journal model records an original driver state, host fingerprint, boot ID, explicit apply/restore intent phases, revisions, and transition history using fsync plus atomic rename. Recovery compares the journal with fresh live state and fails closed on a missing device, a different driver, corrupt/newer-schema journals, or unresolved transactions.

Transaction schema compatibility

The internal journal schema is 0.9; journals from internal schema 0.8 remain readable. These are persistence schema identifiers, not public IdleScope release versions. Missing optional identity fields receive their documented empty defaults and do not make a completed, restore-verified journal corrupt. An incomplete 0.8 journal that reached APPLY_INTENT still blocks active work. If it lacks enough captured PCI identity evidence for an unambiguous bind, recovery is classified as manual rather than guessing from the BDF. IdleScope does not rewrite or discard old journals during load. Unknown newer schemas and structurally inconsistent journals remain fail-closed blockers.

Transaction JSON changes are additive within a supported schema where possible. Consumers must tolerate new optional fields. Removed presentation aliases are not emitted as duplicate JSON keys; method_restore_verified is the machine-readable method-scoped restore result.

SAFE-only DRIVER_DETACH experiments

Dry planning is read-only:

idlescope experiment run 05:00.0 --method DRIVER_DETACH

An active A/B/A run requires the explicit flag and root privileges:

sudo idlescope experiment run 05:00.0 --method DRIVER_DETACH --execute

IdleScope measures A_before, reruns live discovery and SafetyEngine, durably records APPLY_INTENT, detaches the driver, verifies the unbound state, measures B, durably records RESTORE_INTENT, restores and verifies the captured original driver, measures A_restore, then uses the existing experiment analysis. The global transaction lock remains held through restore. Normal exceptions, Ctrl+C, and controlled SIGTERM enter the restore path; SIGKILL and power loss are handled by the durable recovery journal on the next invocation.

Inspect and explicitly recover unfinished transactions with:

idlescope transaction status
idlescope transaction show TXID
sudo idlescope transaction recover TXID

Driver detach changes driver ownership only. It does not remove the PCI function or its electrical presence, so a negative result does not exclude a physical device or link-level cause. No force, safety override, skip-restore, bulk-target, or automatic-target option exists.

Safety SAFE alone is never enough. An active target must also be a discrete leaf PCI endpoint with a current MEDIUM/HIGH MECHANISM finding, unchanged identity and topology, complete dependency discovery, no storage, management-network, SSH, bridge/bond, VFIO, or running-guest dependency, a bound original driver, trusted unbind/bind controls, observable restoration, and no unresolved or corrupt journal. Do not use a management NIC, VFIO device, storage controller, integrated/chipset function, or a random SAFE PCI function for hardware acceptance. If no genuinely unused endpoint meets every condition, skipping a real active happy path is correct.

Experiment outcome and host recovery are separate. A preflight rejection reports host mutation NONE and recovery NOT_REQUIRED; an experiment can fail scientifically while the original driver is RESTORED_VERIFIED. Ordinary status, plan, show, and optimize commands never perform recovery. Normal in-process failures attempt restore first; after SIGKILL or power loss, inspect the durable journal and run the explicit transaction recover TXID command. Recovery is idempotent when the exact captured original state is already present.

Active operation architecture

The v1.0.0 active call path is deliberately narrow:

Diagnosis -> Preflight -> Transaction -> ApplyAuthorization
          -> MutationGateway -> DriverDetachExecutor -> sysfs unbind

Journal -> Reconciliation -> RestoreAuthorization
        -> MutationGateway -> DriverDetachExecutor -> sysfs bind
        -> DRIVER_DETACH restore-postcondition verification

RESTORE_VERIFIED is method-scoped: for DRIVER_DETACH it proves that the same captured PCI function identity is present and owned by the captured original driver. It does not claim that network configuration, storage state, runtime PM, or every driver-specific operational property was restored.

Apply and restore authorizations are separate immutable types tied to the current durable journal revision and phase. Raw BDF strings cannot call executor mutation methods. The executor validates the authorization again before its internal sysfs backend writes. Direct executor mutation use is unsupported; active operations must go through experiment transaction orchestration. Read-only inventory, domain, status, planner, and presentation modules do not depend on the mutation layer. Apply authorization additionally requires a valid A_before artifact and a durable final execution gate containing the fresh READY preflight. Real PCI bus entries are validated as symlinks into the trusted /sys/devices topology; the synthetic E2E fixture uses the same layout.

This is an architectural enforcement boundary against accidental misuse, not OS-level privilege separation, sandboxing, or a security isolation mechanism. Active DRIVER_DETACH remains experimental and should be used only on explicitly SAFE, non-critical devices.

Validation path	Status
Protected-target zero-write rejection on physical Proxmox hardware	Verified
Production transaction/gateway/executor detach and restore on synthetic sysfs	Verified
Real host /sys mutation during automated tests	Never performed
Positive A/B/A on a genuinely SAFE physical PCI endpoint	Not yet HIL validated

Active command exit codes are: 0 completed, 2 usage/unsupported probe, 3 blocked or not relevant, 4 failed with the DRIVER_DETACH restore postcondition verified, 5 recovery required, and 6 manual recovery required.

Historical measurement evidence and current host state have separate lifetimes. PC6/PC8, PkgWatt, reproducibility, and experiment evidence come from stored sessions. Driver binding, runtime PM, current topology, dependencies, VM assignment, validation capability, and Safety are collected again from the live host. A plan-time Safety decision is still not authorization for a future mutation.

Generic domain targets use stable prefixes, for example:

idlescope show net:enp3s0
idlescope show nvme:nvme0
idlescope show sata:host2
idlescope show usb:1-2
idlescope show gpu:card0

Use the technical and machine-readable views when needed:

idlescope show 01:00.0 --verbose
idlescope show 01:00.0 --json
idlescope plan --all
idlescope plan --json
idlescope status --json

CLI presentation is English-only. Compact tables use canonical values such as HIGH, PROTECTED, and BLOCKED. JSON continues to use the same stable English machine values. The older idlescope plan --target 01:00.0 form remains an alias for the human show view.

The read-only optimization planner aggregates local session and experiment history:

idlescope optimize
idlescope optimize --all
idlescope optimize --json
idlescope optimize --target 0000:01:00.0
idlescope optimize --summary

Investigation ranking contains unmeasured mechanism candidates; optimization ranking contains only candidates with observed positive wall-power savings. Impact and action priority are kept separate, so a protected high-impact device is not presented as safe to change. Savings use the median across experiments and retain signed raw deltas. Multiple candidate savings are never summed in the system summary because PCIe paths and system-level effects may overlap.

The validation planner describes possible counterfactual tests without executing them:

idlescope plan
idlescope show 01:00.0
idlescope explain 01:00.0
idlescope plan --all
idlescope show 01:00.0 --verbose
idlescope show 01:00.0 --json

Plans keep investigation value, Safety, intervention testability, and future automation eligibility separate. A plan-time SafetyDecision is never an authorization token: any future executor must rerun fail-closed safety checks immediately before an intervention. Driver detach tests cover driver ownership, not physical absence, and a negative detach result does not exclude an electrically present endpoint. Missing wall power does not disable investigation or validation ranking; PkgWatt remains CPU package power and is never labeled as system or device saving. Human output is the default. --verbose keeps a table-based human layout with additional technical evidence. --json emits only machine-readable data and is intended for scripts.

PCIe mechanism scoring is scope-aware. External endpoints with an actual upstream PCIe port use PCIE_PATH; integrated root-bus functions use INTEGRATED_PLATFORM and report link states as NOT_APPLICABLE, not UNSUPPORTED. D0 or runtime-active state alone cannot produce HIGH mechanism evidence. Measurement snapshots persist fail-closed SafetyEngine decisions, and older sessions without one remain UNASSESSED in the planner.

Stability requires at least three valid windows. Smaller runs report INSUFFICIENT_DATA and a small-sample warning. Workload, package C-state, package power, and wall-power stability are reported separately, so noisy network activity does not erase reproducible PC6/PC8 limitation evidence.

deep_package_cstate_stability uses only available PC6, PC8, and PC10 metrics; an unavailable PC10 is ignored rather than treated as unstable. Every stability result includes metrics_used and human-readable reasons under stability_details. Session and planner JSON distinguish session_investigation_priority from planner_investigation_priority; both rank measurement value, never permission to mutate. Safety, operational risk, and action priority remain separate.

Block discovery follows sysfs partitions and holders/ through device-mapper, LVM, and mdraid, then maps consumers through /proc/self/mountinfo and /proc/swaps. Network discovery follows sysfs lower_* links through bridges, bonds, and VLANs, protecting default IPv4/IPv6 and SSH-peer routes. Missing collectors or unresolved topology produce CAUTION, never SAFE.

quiet measures deltas from /proc/stat, /proc/diskstats, /proc/interrupts, and sysfs network counters. Its defaults (10% CPU busy, 1 MB/s network, 1 MB/s disk, 5000 interrupts/s) are initial heuristics, configurable with the QuietConfig model and subject to calibration on real hosts.

A device is SAFE only when it is a leaf with a bound driver, is not a critical PCI class, every requested dependency collector completed, and no storage, mount, root, swap, route, SSH, bridge/bond/VLAN, or unknown dependency remains.

Safety warning

Unbinding PCI drivers can disconnect storage, networking, displays, or the running system. PROTECTED devices must never be probed, even with force. Unknown dependency state is CAUTION, never SAFE. The only hardware-state mutation path in this release is the explicit, transaction- protected, SAFE-only DRIVER_DETACH experiment described above.

Contributors

• Putpocket — project owner and maintainer
• Codex (OpenAI) — implementation and review collaborator

---

한국어

Linux deep-idle 진입을 방해하는 원인을 evidence 기반으로 찾는 진단 도구입니다.

IdleScope는 CPU package C-state와 PCIe 저전력 상태를 측정하고, 현재 증상을 분류한 뒤 조사할 가치가 있는 장치와 subsystem을 evidence 수준에 따라 정렬합니다. 단순히 power/control=on 같은 설정 하나를 보고 blocker라고 단정하지 않으며, 관찰된 mechanism과 실제 causal proof를 구분합니다.

기본 동작은 read-only입니다. CPU/package idle, PCIe, runtime PM, NVMe/APST, SATA ALPM, NIC/EEE, USB autosuspend, GPU runtime PM, interrupt/wakeup, background activity를 관찰합니다. v1.0.0에서 실제 host state를 변경할 수 있는 기능은 사용자가 명시적으로 실행하는 SAFE-only DRIVER_DETACH A/B/A experiment 하나뿐입니다. runtime PM, APST, ALPM, EEE, USB/GPU policy, PCI remove/rescan, VM/service 상태는 변경하지 않습니다.

Evidence score는 확률이 아니라 근거가 공개되는 heuristic입니다. 각 점수의 근거를 사람이 읽을 수 있고, 수집할 수 없는 counter는 0으로 바꾸지 않고 unavailable로 유지합니다.

상태 및 active operation 경고

진단은 기본적으로 read-only입니다. Active experiment는 현재 SAFE인 leaf PCIe mechanism target이면서 evidence가 MEDIUM/HIGH이고, dependency discovery가 완전하며, unbind/bind control과 method-specific restore 확인이 모두 가능할 때만 실행됩니다. probe는 항상 exit code 2로 거부되며, 그 밖의 power policy나 device operation은 active하지 않습니다.

사용자 설치(Ubuntu/Debian)

Ubuntu 24.04 x86-64(system Python 3.12)에서는 GitHub Release의 .deb를 설치하는 방법이 가장 간단합니다. Python dependency는 /usr/lib/idlescope의 전용 virtual environment에 들어가며 system Python package를 변경하지 않습니다.

curl -LO https://github.com/Putpocket/IdleScope/releases/download/v1.0.0/idlescope_1.0.0_amd64.deb
curl -LO https://github.com/Putpocket/IdleScope/releases/download/v1.0.0/SHA256SUMS
sha256sum -c --ignore-missing SHA256SUMS
sudo apt install ./idlescope_1.0.0_amd64.deb
idlescope --help

Debian, Proxmox, 다른 Ubuntu 버전과 그 밖의 Linux 배포판에서는 wheel을 pipx로 격리 설치할 수 있습니다.

python3 -m pip install --user pipx
python3 -m pipx ensurepath
pipx install https://github.com/Putpocket/IdleScope/releases/download/v1.0.0/idlescope-1.0.0-py3-none-any.whl
idlescope --help

Python 3.11~3.13이 필요합니다. turbostat은 선택 dependency이지만 package C-state를 실제로 측정하려면 필요합니다.

설치 확인과 제거는 다음과 같이 할 수 있습니다.

command -v idlescope
idlescope --help
sudo idlescope doctor
sudo idlescope inventory
sudo idlescope quiet
sudo idlescope diagnose
sudo apt remove idlescope

개발자 설치 및 패키징

python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
.venv/bin/ruff check .
.venv/bin/mypy idlescope
.venv/bin/python -m build
tests/integration/wheel_smoke.sh dist/idlescope-1.0.0-py3-none-any.whl
sudo apt install python3-venv
scripts/build-deb.sh

Snapshot은 기본적으로 ~/.local/share/idlescope/snapshots에 저장되며 raw inventory와 measurement 통계(median, min, max, sample count)를 포함합니다. 반복 baseline은 ~/.local/share/idlescope/sessions에 별도로 저장됩니다.

sudo idlescope measure --name baseline --repeat 5
sudo idlescope measure --name metered --repeat 5 --wall-power-command /path/to/read-watts
idlescope trends baseline
idlescope compare baseline metered --intervention "manual observation"

Wall-power command는 shell 없이 직접 실행되며 숫자 watt 값 하나만 출력해야 합니다(W 또는 watts suffix 허용). 임의의 사용자 command가 read-only라고 IdleScope가 보증하지 않으므로 신뢰할 수 있는 meter reader만 지정해야 합니다. PkgWatt와 wall watts는 별도 metric입니다. 동일한 관찰의 반복은 reproducibility를 높일 뿐 correlation이 아니며, intervention 설명 문자열만으로 causal evidence가 생기지 않습니다.

기존 session을 연결하는 수동 A/B/A experiment는 host를 변경하지 않습니다.

idlescope experiment create --name hba-test --target 0000:01:00.0
idlescope experiment add hba-test --phase before hba-before
idlescope experiment intervention hba-test \
  --type manual_hardware_change --description "manual removal"
idlescope experiment add hba-test --phase after hba-after
idlescope experiment add hba-test --phase restore hba-restored
idlescope experiment analyze hba-test

IdleScope 밖에서 수행하는 intervention은 사용자의 책임입니다. A/B/A 복귀 관찰은 강한 counterfactual evidence가 될 수 있지만, manual experiment의 causal evidence는 MEDIUM이 상한이며 specific blocker를 자동 확정하지 않습니다. Wall-power sample에는 provider type과 trust provenance가 기록되고 command provider는 user_asserted로 표시됩니다.

CLI workflow

먼저 host와 collector 상태를 확인합니다.

sudo idlescope doctor
sudo idlescope inventory

반복 baseline을 측정한 뒤 전체 상태와 조사 후보를 확인합니다.

sudo idlescope measure --name baseline --repeat 5
idlescope status
idlescope plan

특정 PCI 장치나 generic domain target을 자세히 볼 수 있습니다.

idlescope show 03:00.0
idlescope explain 03:00.0
idlescope show net:enp3s0
idlescope show nvme:nvme0
idlescope show sata:host2
idlescope show usb:1-2
idlescope show gpu:card0

주요 command 역할은 다음과 같습니다.

• status: 대표 measurement session의 deep-idle 상태를 간결하게 표시합니다.
• plan: HIGH/MEDIUM mechanism 또는 measurement confounder를 우선순위로 표시합니다.
• show TARGET: 현재 live state, dependency, Safety, validation 방법을 표시합니다.
• explain TARGET: 무엇을 설명할 수 있고 무엇을 증명하지 못하는지 설명합니다.
• optimize: 검증된 절감과 아직 조사 중인 mechanism finding을 분리합니다.
• transaction status: unfinished/recovery/corrupt journal 상태를 확인합니다.

JSON이 필요한 자동화에서는 --json을 사용합니다. stdout에는 JSON만 출력되며 진행 메시지는 stderr로 분리됩니다.

idlescope status --json
idlescope plan --json
idlescope show 03:00.0 --json
idlescope optimize --json
idlescope transaction status --json

Multi-domain finding 및 transaction 기반

Finding role은 서로 다른 의미를 분리합니다. MECHANISM은 validation candidate가 될 수 있고, CONTEXT는 진단 해석을 돕고, CONFOUNDER는 measurement quality를 제한하며, OPPORTUNITY는 package-idle blocker라고 주장하지 않는 device/link 절감 가능성을 뜻합니다. Control interface의 존재만으로 finding이 auto-testable해지지 않습니다. Virtual network interface는 hardware power target이 아니라 dependency topology로 보존되고, DRM connector는 gpu:cardN의 subordinate state입니다.

Transaction 상태는 다음 read-only command로 확인할 수 있습니다.

idlescope transaction status
idlescope transaction status --json
idlescope transaction preflight 01:00.0 --method DRIVER_DETACH
idlescope transaction preflight 01:00.0 --method DRIVER_DETACH --json

Durable journal에는 original driver state, host fingerprint, boot ID, apply/restore intent phase, revision, transition history가 기록되며 fsync와 atomic rename을 사용합니다. Recovery는 journal과 fresh live state를 비교하고 device missing, different driver, corrupt/newer-schema journal, unresolved transaction에서 fail closed합니다.

Transaction schema 호환성

내부 journal schema는 0.9이며 내부 schema 0.8 journal도 읽을 수 있습니다. 이 숫자는 공개 IdleScope release version이 아니라 persistence schema identifier입니다. 과거 schema에 없던 optional identity field는 빈 default를 사용하므로 completed/restore-verified journal을 corrupt로 만들지 않습니다. 반면 APPLY_INTENT에 도달한 incomplete 0.8 journal은 계속 active operation을 차단합니다. 안전한 bind에 필요한 identity evidence가 부족하면 BDF만으로 추측하지 않고 manual recovery로 분류합니다. 구형 journal은 load 중 rewrite하거나 evidence를 버리지 않으며, 알 수 없는 newer schema와 구조적으로 모순된 journal은 fail-closed blocker입니다.

지원되는 schema 안에서 transaction JSON 변경은 가능한 한 additive입니다. Consumer는 새로운 optional field를 허용해야 합니다. 제거된 presentation alias를 중복 JSON key로 내보내지 않으며, method_restore_verified가 method-scoped restore 결과입니다.

Evidence를 읽는 법

IdleScope는 evidence를 다음과 같이 구분합니다.

1. limitation evidence: package PC6/PC8/PC10이 제한되는 증상
2. mechanism evidence: 장치/link/policy가 저전력 진입을 제한할 수 있는 구조
3. correlation evidence: 설명 변수가 실제로 변할 때 package idle도 함께 변한 관찰
4. causal/counterfactual evidence: 통제된 A/B/A 개입 결과

같은 상태에서 runtime_status=active, PC6=0이 반복되는 것은 persistence이지 correlation이 아닙니다. PkgWatt는 CPU package power이며 시스템 전체 소비전력이나 장치 watt가 아닙니다. 외부 wall meter가 없으면 whole-system saving은 unknown으로 유지합니다.

Active DRIVER_DETACH experiment

먼저 read-only dry run으로 readiness를 확인합니다.

idlescope experiment run 05:00.0 --method DRIVER_DETACH

실제 실행은 명시적인 --execute가 필요합니다.

sudo idlescope experiment run 05:00.0 --method DRIVER_DETACH --execute

실행 가능한 target은 현재 Safety=SAFE, MEDIUM/HIGH MECHANISM, discrete leaf endpoint, 완전한 dependency discovery, 정확한 original driver, unbind/bind interface, observable restore를 모두 만족해야 합니다. root/boot/swap/storage, management/default-route/SSH NIC, VFIO/running VM, bridge/bond dependency, integrated chipset function은 실행 대상이 아닙니다. --force, safety override, bulk detach 옵션은 없습니다.

실험 순서는 다음과 같습니다.

A_before measurement
→ fresh live discovery and Safety
→ durable APPLY_INTENT
→ driver unbind and verification
→ B measurement
→ durable RESTORE_INTENT
→ original driver bind and method-specific verification
→ A_restore measurement
→ analysis

DRIVER_DETACH는 driver ownership만 제거하며 PCI function의 전기적 존재는 유지합니다. 따라서 negative result는 물리 장치나 PCIe link-level 원인을 배제하지 않습니다.

Safety SAFE만으로는 충분하지 않습니다. Current MEDIUM/HIGH MECHANISM, unchanged identity와 topology, complete dependency discovery, storage/management network/SSH/bridge/bond/VFIO/running guest dependency 없음, bound original driver, trusted control, observable restoration, unresolved 또는 corrupt journal 없음이 모두 필요합니다. Management NIC, VFIO device, storage controller, integrated/chipset function 또는 임의의 SAFE function을 hardware acceptance에 사용하면 안 됩니다. 모든 조건을 충족하는 genuinely unused endpoint가 없다면 active happy path를 생략하는 것이 올바릅니다.

Transaction과 recovery

모든 active operation은 ~/.local/share/idlescope/transactions에 durable journal을 남깁니다. 일반적인 Python exception, Ctrl+C, controlled SIGTERM에서는 원래 driver 복원을 우선 시도합니다. SIGKILL이나 전원 장애 뒤에는 일반 status/plan 명령이 자동으로 장치를 bind하지 않습니다.

idlescope transaction status
idlescope transaction show TXID
sudo idlescope transaction recover TXID

RESTORE_VERIFIED는 DRIVER_DETACH가 정의한 postcondition, 즉 캡처한 PCI identity가 존재하고 원래 driver ownership이 관찰되었다는 뜻입니다. 네트워크 설정, storage 상태, runtime PM 또는 모든 driver-specific operational state가 복원됐다는 의미는 아닙니다.

Transaction schema 0.8과 0.9 journal을 읽을 수 있습니다. 구형 incomplete journal에 안전한 자동 recovery를 위한 identity evidence가 부족하면 BDF만으로 추측하지 않고 manual recovery로 분류합니다. 알 수 없는 newer schema와 corrupt journal은 active experiment를 fail-closed로 차단합니다.

Experiment outcome과 host recovery는 별도 축입니다. Preflight rejection은 host mutation NONE, recovery NOT_REQUIRED로 표시됩니다. 과학적으로 experiment가 실패해도 original driver postcondition은 RESTORED_VERIFIED일 수 있습니다. 일반 status, plan, show, optimize는 recovery mutation을 수행하지 않습니다. In-process failure는 restore를 먼저 시도하고, SIGKILL/power loss 이후에는 journal을 확인한 뒤 명시적으로 transaction recover TXID를 실행합니다. Exact original state가 이미 존재하면 recovery는 idempotent합니다.

Active operation architecture

Diagnosis -> Preflight -> Transaction -> ApplyAuthorization
          -> MutationGateway -> DriverDetachExecutor -> sysfs unbind

Journal -> Reconciliation -> RestoreAuthorization
        -> MutationGateway -> DriverDetachExecutor -> sysfs bind
        -> DRIVER_DETACH restore-postcondition verification

Apply/restore authorization은 서로 다른 immutable type이며 현재 durable journal revision과 phase에 결합됩니다. Raw BDF로 executor mutation을 호출할 수 없고, executor는 internal sysfs backend write 직전에 authorization을 다시 확인합니다. Direct executor mutation은 지원하지 않으며 active operation은 experiment transaction orchestration을 통과해야 합니다. Read-only inventory/domain/status/planner/presentation module은 mutation layer에 의존하지 않습니다. Apply authorization에는 valid A_before artifact와 fresh READY preflight를 담은 durable final execution gate가 추가로 필요합니다. 실제 PCI bus entry는 trusted /sys/devices topology로 이어지는 symlink로 검증하며 synthetic E2E도 같은 layout을 사용합니다.

이 경계는 accidental misuse를 줄이는 single-process architectural enforcement이며 OS privilege separation, sandbox 또는 security isolation이 아닙니다. Active DRIVER_DETACH는 experimental이고 명시적으로 SAFE인 non-critical device에서만 사용해야 합니다.

실제 하드웨어 검증 상태

검증 경로	상태
Proxmox physical host에서 PROTECTED target zero-write 거부	검증 완료
Production transaction/gateway/executor의 synthetic sysfs detach/restore	검증 완료
자동 테스트에서 실제 host /sys 변경	수행하지 않음
genuinely SAFE physical PCI endpoint positive A/B/A	아직 HIL 미검증

종료 코드

• 0: command 또는 experiment 완료
• 2: CLI usage error 또는 지원하지 않는 active probe
• 3: preflight blocked/not relevant
• 4: experiment 실패, DRIVER_DETACH restore postcondition 확인 완료
• 5: recovery 필요
• 6: manual recovery 필요

상세 진단 및 planner semantics

Historical evidence와 current live state는 수명이 다릅니다. PC6/PC8, PkgWatt, reproducibility, experiment evidence는 stored session에서 오고, driver binding, runtime PM, topology, dependency, VM assignment, validation capability와 Safety는 live host에서 다시 수집합니다. Plan-time Safety는 future mutation authorization이 아닙니다.

idlescope show 01:00.0 --verbose
idlescope show 01:00.0 --json
idlescope plan --all
idlescope plan --json
idlescope status --json
idlescope optimize
idlescope optimize --all
idlescope optimize --json
idlescope optimize --target 0000:01:00.0
idlescope optimize --summary

CLI presentation과 JSON machine value는 HIGH, PROTECTED, BLOCKED 같은 canonical English value를 사용합니다. idlescope plan --target 01:00.0은 human show view의 호환 alias입니다. Investigation ranking에는 아직 측정하지 않은 mechanism candidate가 포함되고, optimization ranking에는 positive wall-power saving을 관찰한 candidate만 포함됩니다. Impact와 action priority는 분리되며 overlapping PCIe/system effect를 이중 계산할 수 있으므로 여러 candidate의 watt saving을 system summary에서 합산하지 않습니다.

PCIe mechanism scoring은 scope-aware입니다. 실제 upstream PCIe port가 있는 external endpoint는 PCIE_PATH, integrated root-bus function은 INTEGRATED_PLATFORM이며 link state를 NOT_APPLICABLE로 표시합니다. D0 또는 runtime-active 하나만으로 HIGH mechanism evidence가 생기지 않습니다. Older session에 fail-closed SafetyDecision이 없으면 planner에서 UNASSESSED입니다.

Stability에는 valid window가 최소 3개 필요합니다. 더 작은 run은 INSUFFICIENT_DATA와 small-sample warning을 표시합니다. Workload, package C-state, package power, wall-power stability는 별도로 계산합니다. deep_package_cstate_stability는 available PC6/PC8/PC10만 사용하며 unavailable PC10을 unstable로 처리하지 않습니다.

Block discovery는 sysfs partition과 holders/를 따라 device-mapper, LVM, mdraid를 추적하고 /proc/self/mountinfo와 /proc/swaps로 consumer를 연결합니다. Network discovery는 bridge, bond, VLAN의 sysfs lower_* link를 추적하여 default IPv4/IPv6 및 SSH-peer route를 보호합니다. Collector 누락이나 unresolved topology는 SAFE가 아니라 CAUTION입니다.

quiet는 /proc/stat, /proc/diskstats, /proc/interrupts, sysfs network counter의 delta를 측정합니다. 기본 heuristic은 CPU busy 10%, network 1 MB/s, disk 1 MB/s, interrupt 5000/s이며 QuietConfig에서 조정할 수 있고 실제 host에 맞춘 calibration이 필요합니다.

Device는 bound driver가 있는 leaf이고 critical PCI class가 아니며, 요청한 dependency collector가 모두 완료되고 storage/mount/root/swap/route/SSH/bridge/bond/VLAN/unknown dependency가 없을 때만 SAFE입니다.

기여자

• Putpocket — 프로젝트 소유자 및 maintainer
• Codex (OpenAI) — 구현 및 코드 리뷰 협업

안전 경고

PCI driver unbind는 storage, network, display 또는 실행 중인 시스템 연결을 끊을 수 있습니다. PROTECTED/CAUTION/UNKNOWN target을 실행하지 마십시오. 실제 active experiment는 명확하게 SAFE하며 비중요한 unused discrete endpoint에서만 사용하십시오. 안전한 physical endpoint가 없다면 active happy path를 실행하지 않는 것이 정상입니다.