Skip to content

Commit 963196b

Browse files
kritibehlkritibehl
committed
DetTrace: add I/O transport validation and Core I/O QA artifacts
1 parent b287ce1 commit 963196b

15 files changed

Lines changed: 503 additions & 0 deletions

‎README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2015,3 +2015,28 @@ The workflow supports:
20152015
- failure-family grouping
20162016
20172017
Safe scope: structured diagnostic telemetry simulation, not production firmware telemetry ownership or Splunk deployment.
2018+
2019+
---
2020+
2021+
## I/O Transport Validation and Core I/O-Style QA Artifacts
2022+
2023+
DetTrace includes I/O transport replay workflows under `io_transport_validation/`.
2024+
2025+
The workflow validates:
2026+
2027+
- USB reconnect recovery
2028+
- PCIe-style enumeration failure isolation
2029+
- DisplayPort-style link training recovery
2030+
- accessory disconnect/reconnect behavior
2031+
- timeout/retry chains
2032+
- first-divergence reporting
2033+
- PASS/FAIL diagnostic status with reason
2034+
2035+
Quality artifacts under `quality_artifacts/` include:
2036+
2037+
- Core I/O-style test plan
2038+
- regression matrix
2039+
- bug reproduction template
2040+
- failure taxonomy
2041+
2042+
Safe scope: replay-based diagnostics and QA workflows. This does not claim USB/PCIe/DisplayPort driver development, kernel engineering, or firmware ownership.

‎io_transport_validation/README.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# I/O Transport Validation
2+
3+
This folder contains replay-based I/O transport validation artifacts for Apple Core I/O-style QA positioning.
4+
5+
## Scope
6+
7+
These are trace replay and diagnostics workflows. They do not claim USB/PCIe/DisplayPort driver development, kernel engineering, or firmware ownership.
8+
9+
## Scenarios
10+
11+
- USB reconnect recovery
12+
- PCIe-style enumeration failure isolation
13+
- DisplayPort-style link training recovery
14+
- accessory disconnect/reconnect validation
15+
- timeout/retry chain validation
16+
17+
## Run
18+
19+
python3 io_transport_validation/run_transport_replay.py
20+
21+
## Expected proof
22+
23+
The workflow reports:
24+
25+
- first divergence index
26+
- expected event
27+
- actual event
28+
- recovery observed
29+
- final state
30+
- PASS/FAIL diagnostic status with reason

‎io_transport_validation/accessory_disconnect_recovery.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"scenario": "accessory-disconnect-recovery",
3+
"safe_claim": "accessory lifecycle replay; not accessory firmware or driver development",
4+
"expected_flow": ["accessory_connected", "capability_read", "session_ready"],
5+
"actual_flow": ["accessory_connected", "capability_read", "disconnect", "reconnect", "capability_read", "session_ready"],
6+
"expected_recovery": true,
7+
"diagnosis": {
8+
"first_divergence_index": 2,
9+
"expected_event": "session_ready",
10+
"actual_event": "disconnect",
11+
"recovery_observed": true,
12+
"final_state": "session_ready",
13+
"diagnostic_status": "PASS",
14+
"reason": "accessory disconnect recovered through reconnect and capability re-read"
15+
}
16+
}

‎io_transport_validation/displayport_link_training_trace.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"scenario": "displayport-style-link-training-recovery",
3+
"safe_claim": "DisplayPort-style link training replay; not display driver or firmware development",
4+
"expected_flow": ["hotplug_detect", "link_training_start", "lane_align", "link_ready", "display_active"],
5+
"actual_flow": ["hotplug_detect", "link_training_start", "lane_align_timeout", "retry_link_training", "lane_align", "link_ready", "display_active"],
6+
"expected_recovery": true,
7+
"diagnosis": {
8+
"first_divergence_index": 2,
9+
"expected_event": "lane_align",
10+
"actual_event": "lane_align_timeout",
11+
"recovery_observed": true,
12+
"final_state": "display_active",
13+
"diagnostic_status": "PASS",
14+
"reason": "link-training timeout recovered after retry and reached display_active"
15+
}
16+
}

‎io_transport_validation/pcie_enumeration_trace.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"scenario": "pcie-style-enumeration-failure",
3+
"safe_claim": "PCIe-style enumeration replay; not PCIe driver or kernel development",
4+
"expected_flow": ["bus_scan", "config_read", "bar_assign", "interrupt_route", "device_ready"],
5+
"actual_flow": ["bus_scan", "config_read_timeout", "retry_config_read", "stale_device_state"],
6+
"expected_recovery": false,
7+
"diagnosis": {
8+
"first_divergence_index": 1,
9+
"expected_event": "config_read",
10+
"actual_event": "config_read_timeout",
11+
"recovery_observed": false,
12+
"final_state": "stale_device_state",
13+
"diagnostic_status": "FAIL",
14+
"reason": "enumeration did not reach BAR assignment or ready state after config-read timeout"
15+
}
16+
}

‎io_transport_validation/run_transport_replay.py‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
#!/usr/bin/env python3
2+
import json
3+
from pathlib import Path
4+
5+
ROOT = Path("io_transport_validation")
6+
REPORT_JSON = ROOT / "transport_validation_report.json"
7+
REPORT_MD = ROOT / "transport_validation_report.md"
8+
9+
TRACE_FILES = [
10+
"usb_reconnect_trace.json",
11+
"pcie_enumeration_trace.json",
12+
"displayport_link_training_trace.json",
13+
"accessory_disconnect_recovery.json",
14+
"timeout_retry_chain.json",
15+
]
16+
17+
18+
def load_trace(filename):
19+
path = ROOT / filename
20+
data = json.loads(path.read_text())
21+
data["_file"] = str(path)
22+
return data
23+
24+
25+
def validate_trace(trace):
26+
diag = trace["diagnosis"]
27+
actual_flow = trace["actual_flow"]
28+
expected_recovery = trace["expected_recovery"]
29+
30+
first_divergence_valid = (
31+
diag["first_divergence_index"] < len(actual_flow)
32+
and actual_flow[diag["first_divergence_index"]] == diag["actual_event"]
33+
)
34+
35+
recovery_valid = diag["recovery_observed"] == expected_recovery
36+
37+
final_state_valid = actual_flow[-1] == diag["final_state"]
38+
39+
expected_status = "PASS" if (
40+
first_divergence_valid and recovery_valid and final_state_valid
41+
) else "FAIL"
42+
43+
return {
44+
"scenario": trace["scenario"],
45+
"file": trace["_file"],
46+
"safe_claim": trace["safe_claim"],
47+
"first_divergence_index": diag["first_divergence_index"],
48+
"expected_event": diag["expected_event"],
49+
"actual_event": diag["actual_event"],
50+
"recovery_observed": diag["recovery_observed"],
51+
"final_state": diag["final_state"],
52+
"declared_status": diag["diagnostic_status"],
53+
"computed_status": expected_status,
54+
"reason": diag["reason"],
55+
"validation_passed": expected_status == diag["diagnostic_status"]
56+
}
57+
58+
59+
def main():
60+
traces = [load_trace(f) for f in TRACE_FILES]
61+
results = [validate_trace(t) for t in traces]
62+
63+
pass_count = sum(1 for r in results if r["validation_passed"])
64+
fail_count = len(results) - pass_count
65+
66+
report = {
67+
"workflow": "io-transport-replay-validation",
68+
"safe_claim": "I/O transport trace replay and diagnostics; not driver, firmware, or kernel development",
69+
"trace_count": len(results),
70+
"validation_pass_count": pass_count,
71+
"validation_fail_count": fail_count,
72+
"results": results
73+
}
74+
75+
REPORT_JSON.write_text(json.dumps(report, indent=2))
76+
77+
lines = [
78+
"# I/O Transport Validation Report",
79+
"",
80+
"## Safe claim",
81+
"",
82+
report["safe_claim"],
83+
"",
84+
"## Summary",
85+
"",
86+
f"- trace count: `{report['trace_count']}`",
87+
f"- validation pass count: `{report['validation_pass_count']}`",
88+
f"- validation fail count: `{report['validation_fail_count']}`",
89+
"",
90+
"## Results",
91+
""
92+
]
93+
94+
for r in results:
95+
lines.extend([
96+
f"### {r['scenario']}",
97+
"",
98+
f"- first divergence index: `{r['first_divergence_index']}`",
99+
f"- expected event: `{r['expected_event']}`",
100+
f"- actual event: `{r['actual_event']}`",
101+
f"- recovery observed: `{r['recovery_observed']}`",
102+
f"- final state: `{r['final_state']}`",
103+
f"- declared status: `{r['declared_status']}`",
104+
f"- computed status: `{r['computed_status']}`",
105+
f"- validation passed: `{r['validation_passed']}`",
106+
f"- reason: {r['reason']}",
107+
""
108+
])
109+
110+
REPORT_MD.write_text("\n".join(lines))
111+
print(json.dumps(report, indent=2))
112+
113+
if fail_count:
114+
raise SystemExit(1)
115+
116+
117+
if __name__ == "__main__":
118+
main()

‎io_transport_validation/timeout_retry_chain.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"scenario": "transport-timeout-retry-chain",
3+
"safe_claim": "transport timeout/retry replay; not production transport stack ownership",
4+
"expected_flow": ["request_send", "ack_received", "transaction_complete"],
5+
"actual_flow": ["request_send", "timeout", "retry_send", "timeout", "retry_send", "ack_received", "transaction_complete"],
6+
"expected_recovery": true,
7+
"diagnosis": {
8+
"first_divergence_index": 1,
9+
"expected_event": "ack_received",
10+
"actual_event": "timeout",
11+
"recovery_observed": true,
12+
"final_state": "transaction_complete",
13+
"diagnostic_status": "PASS",
14+
"reason": "timeout chain recovered after retry_send and final ack_received"
15+
}
16+
}

‎io_transport_validation/transport_validation_report.json‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
{
2+
"workflow": "io-transport-replay-validation",
3+
"safe_claim": "I/O transport trace replay and diagnostics; not driver, firmware, or kernel development",
4+
"trace_count": 5,
5+
"validation_pass_count": 4,
6+
"validation_fail_count": 1,
7+
"results": [
8+
{
9+
"scenario": "usb-reconnect-recovery",
10+
"file": "io_transport_validation/usb_reconnect_trace.json",
11+
"safe_claim": "USB-style transport replay; not USB driver development",
12+
"first_divergence_index": 2,
13+
"expected_event": "configuration_set",
14+
"actual_event": "disconnect",
15+
"recovery_observed": true,
16+
"final_state": "device_ready",
17+
"declared_status": "PASS",
18+
"computed_status": "PASS",
19+
"reason": "disconnect was recovered through reconnect, descriptor re-read, configuration_set, and device_ready",
20+
"validation_passed": true
21+
},
22+
{
23+
"scenario": "pcie-style-enumeration-failure",
24+
"file": "io_transport_validation/pcie_enumeration_trace.json",
25+
"safe_claim": "PCIe-style enumeration replay; not PCIe driver or kernel development",
26+
"first_divergence_index": 1,
27+
"expected_event": "config_read",
28+
"actual_event": "config_read_timeout",
29+
"recovery_observed": false,
30+
"final_state": "stale_device_state",
31+
"declared_status": "FAIL",
32+
"computed_status": "PASS",
33+
"reason": "enumeration did not reach BAR assignment or ready state after config-read timeout",
34+
"validation_passed": false
35+
},
36+
{
37+
"scenario": "displayport-style-link-training-recovery",
38+
"file": "io_transport_validation/displayport_link_training_trace.json",
39+
"safe_claim": "DisplayPort-style link training replay; not display driver or firmware development",
40+
"first_divergence_index": 2,
41+
"expected_event": "lane_align",
42+
"actual_event": "lane_align_timeout",
43+
"recovery_observed": true,
44+
"final_state": "display_active",
45+
"declared_status": "PASS",
46+
"computed_status": "PASS",
47+
"reason": "link-training timeout recovered after retry and reached display_active",
48+
"validation_passed": true
49+
},
50+
{
51+
"scenario": "accessory-disconnect-recovery",
52+
"file": "io_transport_validation/accessory_disconnect_recovery.json",
53+
"safe_claim": "accessory lifecycle replay; not accessory firmware or driver development",
54+
"first_divergence_index": 2,
55+
"expected_event": "session_ready",
56+
"actual_event": "disconnect",
57+
"recovery_observed": true,
58+
"final_state": "session_ready",
59+
"declared_status": "PASS",
60+
"computed_status": "PASS",
61+
"reason": "accessory disconnect recovered through reconnect and capability re-read",
62+
"validation_passed": true
63+
},
64+
{
65+
"scenario": "transport-timeout-retry-chain",
66+
"file": "io_transport_validation/timeout_retry_chain.json",
67+
"safe_claim": "transport timeout/retry replay; not production transport stack ownership",
68+
"first_divergence_index": 1,
69+
"expected_event": "ack_received",
70+
"actual_event": "timeout",
71+
"recovery_observed": true,
72+
"final_state": "transaction_complete",
73+
"declared_status": "PASS",
74+
"computed_status": "PASS",
75+
"reason": "timeout chain recovered after retry_send and final ack_received",
76+
"validation_passed": true
77+
}
78+
]
79+
}

0 commit comments

Comments
 (0)