From e6c1c3ed226858003900b4807786526294fbf335 Mon Sep 17 00:00:00 2001 From: Srikanth Muppandam Date: Thu, 2 Jul 2026 11:12:18 +0530 Subject: [PATCH] docs: add README coverage for WiFi connectivity tests Add README files for WiFi_Dynamic_IP, WiFi_Manual_IP, WiFi_Firmware_Driver and WiFi_OnOff. Document each test's purpose, dependencies, usage, LAVA parameters, generated logs, and PASS/SKIP/FAIL criteria. Align the documentation with the current run.sh behavior, including SSID/password handling, WiFi interface detection, firmware/probe checks, DHCP validation, and OnOff recovery configuration. Signed-off-by: Srikanth Muppandam --- .../README_WiFi_Connectivity.md | 143 +++++++++++------- .../WiFi/WiFi_Firmware_Driver/README.md | 114 ++++++++++++++ .../WiFi/WiFi_Manual_IP/README.md | 115 ++++++++++++++ .../Connectivity/WiFi/WiFi_OnOff/README.md | 134 ++++++++++++++++ 4 files changed, 454 insertions(+), 52 deletions(-) create mode 100644 Runner/suites/Connectivity/WiFi/WiFi_Firmware_Driver/README.md create mode 100644 Runner/suites/Connectivity/WiFi/WiFi_Manual_IP/README.md create mode 100644 Runner/suites/Connectivity/WiFi/WiFi_OnOff/README.md diff --git a/Runner/suites/Connectivity/WiFi/WiFi_Dynamic_IP/README_WiFi_Connectivity.md b/Runner/suites/Connectivity/WiFi/WiFi_Dynamic_IP/README_WiFi_Connectivity.md index 7b84cd897..fb3a65db3 100644 --- a/Runner/suites/Connectivity/WiFi/WiFi_Dynamic_IP/README_WiFi_Connectivity.md +++ b/Runner/suites/Connectivity/WiFi/WiFi_Dynamic_IP/README_WiFi_Connectivity.md @@ -1,74 +1,113 @@ -Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries. -SPDX-License-Identifier: BSD-3-Clause -# WiFi Connectivity Validation +# WiFi Dynamic IP -## ๐Ÿ“‹ Overview +## Overview -This test validates WiFi functionality by: +`WiFi_Dynamic_IP` validates WiFi connectivity using DHCP-based IP assignment. The test connects to an access point, verifies that the WiFi interface receives an IP address, and confirms external connectivity using `ping`. -- Connecting to an access point (AP) using either `nmcli` or `wpa_supplicant`. -- Verifying IP acquisition via DHCP. -- Checking internet connectivity with a `ping` test. -- Handling systemd network service status. -- Supporting flexible SSID/password input via arguments, environment, or file. +The test first attempts connection through `nmcli`. If that path does not complete successfully, it falls back to `wpa_supplicant` with `udhcpc`. -## โœ… SSID/PASSWORD Input Priority (Hybrid Approach) +## What the test validates -1. **Command-line arguments**: - ```sh - ./run.sh "MySSID" "MyPassword" - ``` +- WiFi credentials are available through CLI arguments, environment, or the repo WiFi credential helper. +- Required tools are present. +- `systemd-networkd.service` is available where applicable. +- A WiFi interface is detected. +- The device can connect to the configured SSID. +- DHCP assigns an IP address to the WiFi interface. +- Internet connectivity is verified by pinging `8.8.8.8`. -2. **Environment variables**: - ```sh - SSID_ENV=MySSID PASSWORD_ENV=MyPassword ./run.sh - ``` +## Dependencies -3. **Fallback to `ssid_list.txt` file** (if above not set): - ```txt - MySSID MyPassword - ``` +The target should provide: -## โš™๏ธ Supported Tools +- `iw` +- `ping` +- `nmcli` for the primary connection path +- `wpa_supplicant` and `udhcpc` for fallback connection +- `systemd-networkd.service` on systemd-based images -- Primary: `nmcli` -- Fallback: `wpa_supplicant`, `udhcpc`, `ifconfig` +The script sources the common test environment through `init_env` and uses common helpers from `functestlib.sh`. -Ensure these tools are available in the system before running the test. Missing tools are detected and logged as skipped/failure. +## Usage -## ๐Ÿงช Test Flow +Run from the test directory: -1. **Dependency check** โ€“ verifies necessary binaries are present. -2. **Systemd services check** โ€“ attempts to start network services if inactive. -3. **WiFi connect (nmcli or wpa_supplicant)** โ€“ based on tool availability. -4. **IP assignment check** โ€“ validates `ifconfig wlan0` output. -5. **Internet test** โ€“ pings `8.8.8.8` to confirm outbound reachability. -6. **Result logging** โ€“ writes `.res` file and logs all actions. +```sh +./run.sh --ssid "" --password "" +``` + +Show help: + +```sh +./run.sh --help +``` + +The script supports these arguments: + +| Argument | Description | +|---|---| +| `--ssid ` | WiFi access point SSID | +| `--password ` | WiFi access point password | +| `--help`, `-h` | Print usage and exit | -## ๐Ÿงพ Output +## LAVA usage -- `WiFi_Connectivity.res`: Contains `WiFi_Connectivity PASS` or `FAIL`. -- Logs are printed using `log_info`, `log_pass`, and `log_fail` from `functestlib.sh`. +The YAML exposes the WiFi credentials as parameters: -## ๐Ÿ“‚ Directory Structure +```yaml +params: + SSID: "" + PASSWORD: "" +``` + +The LAVA step runs: +```sh +./run.sh --ssid "${SSID}" --password "${PASSWORD}" || true ``` -WiFi/ -โ”œโ”€โ”€ run.sh -โ”œโ”€โ”€ ssid_list.txt (optional) -โ”œโ”€โ”€ README.md + +The final test result is emitted through: + +```sh +$REPO_PATH/Runner/utils/send-to-lava.sh WiFi_Dynamic_IP.res ``` -## ๐ŸŒ Integration (meta-qcom_PreMerge.yaml) +## Output files -Add this test with SSID parameters as follows: +The test writes a ping log in the test directory: -```yaml -- name: WiFi_Connectivity - path: Runner/suites/Connectivity/WiFi - timeout: - minutes: 5 - params: - SSID_ENV: "xxxx" - PASSWORD_ENV: "xxxx" +```text +wifi_ping_.log ``` + +This log contains the ping output from the connectivity check. It is useful when the test connects successfully but the external connectivity check fails. + +## PASS criteria + +The test passes when: + +1. A WiFi interface is found. +2. The target connects to the configured SSID using either `nmcli` or `wpa_supplicant`. +3. The WiFi interface receives an IP address. +4. Ping to `8.8.8.8` succeeds. + +## SKIP criteria + +The test skips when SSID or password is missing. + +## FAIL criteria + +The test fails when: + +- Required dependencies are missing. +- Network service validation fails. +- No WiFi interface is detected. +- Both connection methods fail. +- IP assignment fails after connection. +- Ping fails after IP assignment. + +## Notes + +- The password is hidden in logs. +- The test performs cleanup through WiFi helper functions before exit. +- The fallback path helps support minimal images where `nmcli` may not be sufficient or available. diff --git a/Runner/suites/Connectivity/WiFi/WiFi_Firmware_Driver/README.md b/Runner/suites/Connectivity/WiFi/WiFi_Firmware_Driver/README.md new file mode 100644 index 000000000..64f115a31 --- /dev/null +++ b/Runner/suites/Connectivity/WiFi/WiFi_Firmware_Driver/README.md @@ -0,0 +1,114 @@ +# WiFi Firmware Driver + +## Overview + +`WiFi_Firmware_Driver` validates that the target has WiFi firmware available, that the expected driver/module visibility is present, and that the kernel log does not show WiFi probe or runtime failures. + +This test is useful for verifying basic WiFi firmware and driver readiness before running connection tests. + +## What the test validates + +- Required command-line utilities are available. +- The SoC model is detected from device tree when available. +- WiFi firmware is found under `/lib/firmware`. +- The WiFi firmware family is detected. +- Family-specific runtime preparation succeeds. +- Family-specific modules are visible. +- Firmware load or use evidence exists in the kernel log. +- Kernel logs do not show WiFi probe/runtime failures. + +## Dependencies + +The target should provide: + +- `find` +- `grep` +- `modprobe` +- `lsmod` +- `cat` +- `stat` +- `awk` + +The script sources the common test environment through `init_env`, then uses helpers from: + +- `functestlib.sh` +- `lib_connectivity.sh` + +## Usage + +Run from the test directory: + +```sh +./run.sh +``` + +No mandatory CLI arguments are required. + +## Optional environment variables + +| Variable | Default | Description | +|---|---|---| +| `WIFI_FW_PROBE_LOG_DIR` | `./wifi_firmware_driver_dmesg` | Directory used for WiFi probe/runtime log evidence | +| `WIFI_FW_PROBE_LOG_TAG` | `WiFi_Firmware_Driver/probe` | Log tag used when reporting probe checks | +| `WIFI_FW_LOAD_LOG_TAG` | `WiFi_Firmware_Driver/firmware` | Log tag used when reporting firmware load checks | + +Example: + +```sh +WIFI_FW_PROBE_LOG_DIR=./fw_probe_logs ./run.sh +``` + +## LAVA usage + +The YAML runs the test directly: + +```sh +./run.sh || true +``` + +The final test result is emitted through: + +```sh +$REPO_PATH/Runner/utils/send-to-lava.sh WiFi_Firmware_Driver.res +``` + +## Output files + +The test writes the result file: + +```text +WiFi_Firmware_Driver.res +``` + +Depending on helper behavior and failure mode, WiFi probe/runtime log artifacts may be collected under the configured probe log directory. + +## PASS criteria + +The test passes when: + +1. Required tools are available. +2. WiFi firmware is detected. +3. Family-specific preparation and module checks pass. +4. Firmware load/use evidence is found. +5. No WiFi probe/runtime failures are detected. + +## SKIP criteria + +The test skips when: + +- Required tools are missing. +- No supported WiFi firmware is found under `/lib/firmware`. + +## FAIL criteria + +The test fails when: + +- Family-specific runtime preparation fails. +- Expected family modules are not visible. +- Firmware load/use evidence is not found. +- WiFi probe/runtime failures are detected in the kernel log. + +## Notes + +- The test currently detects ath12k, ath11k, and ath10k firmware families through common connectivity helpers. +- This test does not validate association to an access point or IP assignment. Use `WiFi_Dynamic_IP` or `WiFi_Manual_IP` for connection validation. diff --git a/Runner/suites/Connectivity/WiFi/WiFi_Manual_IP/README.md b/Runner/suites/Connectivity/WiFi/WiFi_Manual_IP/README.md new file mode 100644 index 000000000..3b14bab97 --- /dev/null +++ b/Runner/suites/Connectivity/WiFi/WiFi_Manual_IP/README.md @@ -0,0 +1,115 @@ +# WiFi Manual IP + +## Overview + +`WiFi_Manual_IP` validates WiFi connectivity using `wpa_supplicant` and manual DHCP invocation through `udhcpc`. + +The test connects to the configured SSID, requests an IP address using `udhcpc`, and verifies internet connectivity with `ping`. + +## What the test validates + +- WiFi credentials are available through CLI arguments, environment, or the repo WiFi credential helper. +- Required tools are present. +- A WiFi interface is detected. +- A valid `udhcpc` script is available or generated. +- `wpa_supplicant` can associate with the configured access point. +- `udhcpc` assigns an IP address. +- Internet connectivity is verified by pinging `8.8.8.8`. + +## Dependencies + +The target should provide: + +- `iw` +- `wpa_supplicant` +- `udhcpc` +- `ip` +- `ping` + +The script sources the common test environment through `init_env` and uses common helpers from `functestlib.sh`. + +## Usage + +Run from the test directory: + +```sh +./run.sh --ssid "" --password "" +``` + +Show help: + +```sh +./run.sh --help +``` + +The script supports these arguments: + +| Argument | Description | +|---|---| +| `--ssid ` | WiFi access point SSID | +| `--password ` | WiFi access point password | +| `--help`, `-h` | Print usage and exit | + +## LAVA usage + +The YAML exposes the WiFi credentials as parameters: + +```yaml +params: + SSID: "" + PASSWORD: "" +``` + +The LAVA step runs: + +```sh +./run.sh --ssid "${SSID}" --password "${PASSWORD}" || true +``` + +The final test result is emitted through: + +```sh +$REPO_PATH/Runner/utils/send-to-lava.sh WiFi_Manual_IP.res +``` + +## Output files + +The test may create these temporary or diagnostic files in the test directory or `/tmp`: + +```text +wpa.log +/tmp/wpa_supplicant.conf +``` + +The script installs an exit trap to restore the `udhcpc` script state through the common helper. + +## PASS criteria + +The test passes when: + +1. A WiFi interface is found. +2. A WPA configuration is generated successfully. +3. `wpa_supplicant` starts successfully for the interface. +4. `udhcpc` assigns an IP address. +5. Ping to `8.8.8.8` succeeds. + +## SKIP criteria + +The test skips when SSID or password is missing. + +## FAIL criteria + +The test fails when: + +- Required dependencies are missing. +- No WiFi interface is detected. +- `udhcpc` script setup fails. +- WPA configuration generation fails. +- IP assignment fails. +- Ping fails after IP assignment. + +## Notes + +- This test is focused on the `wpa_supplicant` + `udhcpc` path. +- For automatic connection fallback using both `nmcli` and `wpa_supplicant`, use `WiFi_Dynamic_IP`. +- The password is hidden in logs. diff --git a/Runner/suites/Connectivity/WiFi/WiFi_OnOff/README.md b/Runner/suites/Connectivity/WiFi/WiFi_OnOff/README.md new file mode 100644 index 000000000..c088f8917 --- /dev/null +++ b/Runner/suites/Connectivity/WiFi/WiFi_OnOff/README.md @@ -0,0 +1,134 @@ +# WiFi On/Off + +## Overview + +`WiFi_OnOff` validates WiFi runtime readiness and verifies that the detected WiFi interface can be toggled down and back up. + +The test performs kernel configuration checks, device tree visibility checks, module visibility logging, probe/runtime failure checks, interface detection, and interface up/down validation. + +## What the test validates + +- Required tools are present. +- Mandatory WiFi kernel configs are enabled. +- Optional WiFi configs are reported when visible. +- WiFi or combined WCN device tree entries are visible based on configured patterns. +- WiFi driver module visibility is logged. +- Target-specific WiFi driver kernel configs can be inferred and validated. +- Kernel logs do not show WiFi probe/runtime failures. +- A usable WiFi interface appears within the configured wait window. +- The WiFi interface can be brought down and back up. + +## Dependencies + +The target should provide: + +- `ip` +- `iw` + +The script sources the common test environment through `init_env`, then uses helpers from: + +- `functestlib.sh` +- `lib_connectivity.sh` + +## Usage + +Run from the test directory: + +```sh +./run.sh +``` + +Run with common overrides: + +```sh +WIFI_WAIT_SECS=90 WIFI_WAIT_STEP_SECS=3 WIFI_RECOVERY_RELOAD=1 ./run.sh +``` + +Run with a preferred interface override: + +```sh +WIFI_IFACE=wlan0 ./run.sh +``` + +## Configuration + +| Variable | Default | Description | +|---|---|---| +| `WIFI_WAIT_SECS` | `60` | Maximum time to wait for a WiFi interface | +| `WIFI_WAIT_STEP_SECS` | `2` | Poll interval while waiting for the interface | +| `WIFI_RECOVERY_RELOAD` | `1` | Enable best-effort recovery reload behavior | +| `WIFI_RECOVERY_RELOAD_AFTER_S` | empty / auto | Time before recovery reload is attempted | +| `WIFI_PROBE_LOG_DIR` | `./wifi_onoff_dmesg` | Directory used for WiFi probe/runtime log evidence | +| `WIFI_PROBE_LOG_TAG` | `WiFi_OnOff/probe` | Log tag used when reporting probe checks | +| `WIFI_IFACE` | empty | Optional interface override | +| `WIFI_DT_PATTERNS` | built-in list | Newline-separated DT compatible/name patterns | +| `WIFI_DRIVER_MODULES` | built-in list | Newline-separated driver module names to log/check | + +Default DT patterns include Qualcomm/WCN and common WiFi identifiers such as `qcom,wcn7850`, `qcom,wcn6855`, `ath12k`, `ath11k`, `ath10k`, `wifi`, `wlan`, and `qca`. + +Default module names include `ath12k_wifi7`, `ath12k`, `ath11k`, `ath11k_pci`, `ath10k_pci`, `ath10k_snoc`, `cfg80211`, `mac80211`, and `mhi`. + +## LAVA usage + +The YAML exposes these parameters: + +```yaml +params: + WIFI_WAIT_SECS: "60" + WIFI_WAIT_STEP_SECS: "2" + WIFI_RECOVERY_RELOAD: "1" + WIFI_RECOVERY_RELOAD_AFTER_S: "" +``` + +The LAVA step runs: + +```sh +WIFI_WAIT_SECS="${WIFI_WAIT_SECS}" WIFI_WAIT_STEP_SECS="${WIFI_WAIT_STEP_SECS}" WIFI_RECOVERY_RELOAD="${WIFI_RECOVERY_RELOAD}" WIFI_RECOVERY_RELOAD_AFTER_S="${WIFI_RECOVERY_RELOAD_AFTER_S}" ./run.sh || true +``` + +The final test result is emitted through: + +```sh +$REPO_PATH/Runner/utils/send-to-lava.sh WiFi_OnOff.res +``` + +## Output files + +The test writes standard test result output through the common result helper. Probe/runtime diagnostics may be collected under: + +```text +wifi_onoff_dmesg/ +``` + +The directory can be changed with `WIFI_PROBE_LOG_DIR`. + +## PASS criteria + +The test passes when: + +1. Mandatory WiFi kernel configs are enabled. +2. No WiFi probe/runtime failures are detected. +3. A WiFi interface is detected. +4. The interface can be brought down. +5. The interface can be brought back up. + +## SKIP criteria + +The test skips when no usable WiFi interface or runtime WiFi object is found and no probe/runtime failure is detected. + +## FAIL criteria + +The test fails when: + +- Mandatory WiFi kernel configs are missing. +- Target-specific WiFi driver kernel configs are missing. +- WiFi probe/runtime failures are detected. +- The WiFi runtime stack is present but no usable interface appears. +- The interface cannot be brought down. +- The interface cannot be brought back up. + +## Notes + +- This test does not connect to an access point. +- Use `WiFi_Dynamic_IP` or `WiFi_Manual_IP` to validate association, DHCP, and external connectivity. +- The test logs extra diagnostics when no interface appears or an interface toggle operation fails.