Buses: fail driver errors and report optional camera skips

Runner/suites/Kernel/Baseport/Buses/Buses.yaml

@@ -11,6 +11,7 @@ params:
   # Safe CI defaults: use the in-repository read-only EEPROM path and do not
   # invoke the optional legacy binary or any active bus operation.
   I2C_LEGACY_TEST_ENABLE: "0"
+  # Additional read-only modes: matrix and pm. Default auto remains unchanged.
   I2C_EEPROM_MODE: "auto"
   I2C_EEPROM_DEVICE: "auto"
   # Integrity mode must receive a target-approved range and explicit write

Runner/suites/Kernel/Baseport/Buses/README.md

@@ -1,7 +1,7 @@
 # I2C Buses Validation
 
 This suite performs capability-driven I2C runtime validation. It correlates
-enabled Qualcomm I2C device-tree controllers with runtime adapters and clients,
+enabled Qualcomm GENI, QUP and CCI device-tree controllers with runtime adapters and clients,
 reports driver binding, queries adapter functionality, and retains bounded
 inventory and kernel-health evidence.
 
@@ -16,10 +16,10 @@ from the running target. When discovery is ambiguous, select the sysfs data
 file explicitly. A destructive integrity check additionally requires the user
 to provide a documented safe offset and length.
 
-On Debian, Ubuntu, and CentOS, the suite uses the shared package provider to
-install the mapped `i2c-tools` package when it is missing. Yocto remains
-image-managed and never performs runtime package installation. Missing optional
-utilities or hardware produce SKIP with discovery evidence.
+Yocto, Debian, Ubuntu and CentOS all use image-provided components. The suite
+does not install packages or require systemd. Missing optional utilities or
+hardware produce SKIP with discovery evidence. An I/O error or short read after
+selecting an available EEPROM is FAIL, not an unavailable-environment SKIP.
 
 ## Default run
 
@@ -82,6 +82,72 @@ EEPROM_PATH=/sys/bus/i2c/devices/<bus>-<address>/eeprom
 The probe reads the dynamically reported device capacity and records its
 SHA-256 digest without modifying the device.
 
+When Python is absent, `i2c_eeprom_read.sh` provides the read-only path using
+image-provided `sh`, `dd`, `stat`, `sha256sum`, `cmp` and the base shell utilities.
+The helper probes `dd` for `iflag=fullblock` support before device access and
+skips if it is unavailable, partial kernel reads must not truncate a block.
+It preserves candidate deduplication, explicit selection, exact byte counts and
+failure reporting. This fallback reads at most 1 MiB per selected range. For a
+larger EEPROM, provide `--eeprom-offset` and `--eeprom-length`. Reads use aligned
+blocks where possible, not a fixed one-byte read for every EEPROM access.
+Python remains required for destructive integrity mode, there is no shell write
+fallback. A missing explicitly selected file fails rather than selecting a
+different device. Ordinary automatic mode still skips an absent or ambiguous
+EEPROM.
+
+Metadata-only EEPROM discovery for automatic adapter selection does not require
+the data-read tools or apply the 1 MiB read limit. It does not read EEPROM data.
+Missing read tools therefore do not prevent identification of an adapter for a
+separately requested operation whose own prerequisites are available.
+
+## Additional read-only coverage
+
+These explicit modes work with ramdisk tools and do not require Python:
+
+```sh
+./run.sh --eeprom-mode matrix
+./run.sh --eeprom-mode pm
+```
+
+`matrix` takes a baseline and compares repeated reads at the beginning, middle
+and end of the selected range. It exercises lengths 1, 2, 3, 16, 32, 64 and the
+selected range length where they fit, at most 21 comparisons. The default range
+is the first `min(capacity, 4096)` bytes. A mismatch or transfer error fails.
+This is sysfs read consistency coverage, not proof of a particular FIFO, DMA,
+GPI or repeated-start transfer mode. The kernel driver controls those details.
+
+`pm` takes a baseline, observes the selected client/controller ancestry for
+natural runtime suspend for at most ten seconds, then verifies an identical
+fresh read. It skips if no natural suspend is observed. It never writes
+`power/control`, changes autosuspend delays, unbinds drivers, or suspends the
+whole system. A post-idle read failure or mismatch fails. This is a read-after-
+idle check, not exhaustive power-management transition coverage.
+
+Select a device and read range explicitly when needed:
+
+```sh
+./run.sh --eeprom-mode matrix --eeprom-device "$EEPROM_PATH" \
+    --eeprom-offset 0 --eeprom-length 256 --eeprom-timeout 60
+I2C_EEPROM_MODE=pm I2C_EEPROM_DEVICE="$EEPROM_PATH" ./run.sh
+```
+
+The existing `I2C_EEPROM_MODE`, `I2C_EEPROM_DEVICE`, `I2C_EEPROM_OFFSET`,
+`I2C_EEPROM_LENGTH` and `I2C_EEPROM_TIMEOUT` parameters apply to these modes.
+CLI values override environment values. The suite bounds the complete EEPROM
+operation with `--eeprom-timeout`, each shell data read also has a ten-second
+watchdog with termination escalation. No multi-device operation is inferred
+from enumeration order. Use explicit invocations for multiple EEPROMs.
+
+Each shell-helper invocation retains a separate visible `eeprom-read.XXXXXX/`
+directory under the suite results. Evidence includes `i2c_eeprom_candidates.tsv`, the EEPROM report,
+read data and SHA-256 for probe mode, matrix expected/actual buffers and read
+logs, and `i2c_runtime_pm.tsv` plus before/after buffers for PM mode.
+
+Stuck-bus, NACK injection and recovery testing are not part of these modes.
+They require a separately selected controlled fixture and a documented
+injection/recovery interface. Never use automatic address scans or raw register
+writes as a substitute for a fault injector on production peripherals.
+
 ## EEPROM data-integrity validation
 
 Integrity mode reads the original bytes from a user-approved range, derives a
@@ -174,7 +240,7 @@ EEPROM validator provides the default functional coverage.
 ## Public options
 
 - `--legacy-test`
-- `--eeprom-mode auto|off|probe|integrity`
+- `--eeprom-mode auto|off|probe|integrity|matrix|pm`
 - `--eeprom-test`
 - `--eeprom-device auto|PATH`
 - `--eeprom-offset BYTES`
@@ -200,11 +266,91 @@ Every option has a corresponding uppercase environment variable shown by
 
 - `PASS`: applicable runtime topology is healthy and each available or
   explicitly requested validation completes with its required evidence.
-- `FAIL`: runtime state is inconsistent, user input is malformed, an operation
-  fails after its environment is available, or modified data cannot be
+- `FAIL`: controller or required-client runtime state is inconsistent, user
+  input is malformed, an operation fails after its environment is available,
+  a controller/client driver error is captured, or modified data cannot be
   restored and verified.
-- `SKIP`: I2C, a selected adapter or EEPROM, Python, or an optional diagnostic
-  utility is unavailable.
+- `SKIP`: I2C or its character interface is unavailable, automatic EEPROM
+  selection is absent or ambiguous, a required optional utility is missing,
+  an optional camera is unbound, or natural runtime suspend is not observed.
+  An explicitly selected missing EEPROM is `FAIL`.
 
 Artifacts are retained under `results/Buses/`, including controller, adapter,
 client, driver, dmesg, EEPROM discovery, digest, and restoration evidence.
+The result is initialized before argument validation so a malformed invocation
+cannot publish an earlier PASS. An unavailable selected operation does not
+override an existing failure or bypass the final kernel-health checks.
+
+### Topology completeness
+
+`i2c_topology.tsv` records controller-to-adapter ownership. One unrelated working
+adapter cannot satisfy another controller. Enabled CCI master buses require
+their own runtime adapters, while a CCI parent with no enabled buses does not
+create an adapter requirement. Enabled DT client nodes are reconciled against
+exact runtime `of_node` identities, including nodes that never became clients.
+Disabled ancestors are excluded. Mux channel links and enabled channel nodes are
+checked against runtime adapters. Framework-owned adapter objects do not need a
+client-style direct driver binding. Optional-camera readiness keeps its separate
+classification, driver errors still fail independently.
+
+### Client probe diagnostics
+
+The controller-only kernel scan does not establish client health. The suite
+also filters the retained `dmesg_snapshot.log` using client addresses, names,
+bound drivers, and module candidates from `i2c_clients.tsv`. Matching lines are
+saved verbatim in `i2c_client_dmesg.log`, including probe failures and their
+supporting messages. No additional kernel-log capture, module loading, bus scan,
+or hardware write is performed.
+
+When runtime validation fails or an optional camera sensor is skipped, up to
+120 client log lines are also printed to stdout. The complete filtered file
+remains available for larger logs. An empty
+file means no matching messages were retained, not that probing succeeded.
+Unavailable kernel logs are reported without hiding an existing runtime FAIL.
+Explicit errors from discovered I2C controller and client drivers are also
+retained in `i2c_driver_errors.log` and printed with `I2C-DRIVER-ERROR` labels.
+The full matching context is saved in `i2c_driver_dmesg.log`. Probe errors,
+firmware-load failures, chip-ID read failures and other explicit driver errors
+fail Buses even with `I2C_DMESG_STRICT=0`. The existing strict option still
+controls additional findings from the legacy controller scan, it cannot
+suppress this driver-error check. Errors remain failures even if the driver
+subsequently binds successfully.
+
+Normal initialization and dummy-regulator notices alone are not failures.
+Matching covers runtime-discovered controllers, adapter identities and clients, including optional
+cameras, not unrelated drivers elsewhere in the kernel. If the kernel snapshot
+is unavailable, the check cannot certify driver health. No second kernel-log
+capture or hardware operation is performed.
+
+### Optional camera sensors
+
+Buses validates controller and required-client readiness, not image capture.
+An unbound optional camera sensor is recorded as an individual capture-readiness
+SKIP while bus and kernel-health checks continue. Runtime DT identification
+requires a `camera@...` or
+`sensor@...` node with `compatible` and `reg` properties and a media endpoint
+under `port` or `ports` exposing both `remote-endpoint` and `data-lanes`.
+This conservative structural check uses no board, sensor-model, driver-name or
+I2C-address list. A name alone is insufficient. Unclassified unbound clients,
+including bridges and embedded controllers, remain FAIL, as do controller
+failures. Bound cameras are still included in the bound-client inventory.
+
+The skipped clients are listed in `i2c_optional_camera_clients.tsv` and their
+probe evidence remains in the client diagnostic log and stdout. SKIP means
+camera capture readiness is outside this bus check, not that disconnection was
+proven.
+A failed chip-ID read can also indicate a power, reset, wiring or driver issue.
+Camera functionality belongs to `Libcamera_cam` or `Camera_NHX`, using the
+appropriate stack and an attached sensor. Those suites may themselves SKIP
+when their required environment is unavailable, so a Buses PASS is not proof
+of camera coverage or health.
+
+For a setup without cameras, the default `./run.sh` may PASS its bus checks
+with a camera SKIP only when no other gating failure is observed. A captured
+camera probe error still makes the overall result FAIL, even if the camera
+is known to be disconnected. Disable the unused camera DT node or omit its
+optional overlay in that setup to avoid attempting an invalid probe. A camera
+SKIP cannot hide an embedded-controller or other driver failure. Explicitly
+requested
+I2C scans, register operations and EEPROM checks keep their existing result
+policy. No DT nodes, overlays, services or drivers are modified by the test.