docs: add README coverage for WiFi connectivity tests

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 "<SSID>" --password "<PASSWORD>"
+```
+
+Show help:
+
+```sh
+./run.sh --help
+```
+
+The script supports these arguments:
+
+| Argument | Description |
+|---|---|
+| `--ssid <SSID>` | WiFi access point SSID |
+| `--password <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_<interface>.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.

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.

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 "<SSID>" --password "<PASSWORD>"
+```
+
+Show help:
+
+```sh
+./run.sh --help
+```
+
+The script supports these arguments:
+
+| Argument | Description |
+|---|---|
+| `--ssid <SSID>` | WiFi access point SSID |
+| `--password <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.