Add test script to validate USB UAC #266
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| ``` | ||
| Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries. | ||
| SPDX-License-Identifier: BSD-3-Clause | ||
| ``` | ||
|
|
||
| # USB Audio Class Validation | ||
|
|
||
| ## Overview | ||
|
|
||
| This shell script executes on the DUT (Device-Under-Test) and validates USB Audio Class (UAC) devices. | ||
| The test validation scope includes: | ||
| - Successful enumeration of UAC devices and display following details for each device: | ||
| - DEVICE (USB device address), VID:PID, and PRODUCT string. | ||
| - Validation of ALSA integration: | ||
| - Confirm /proc/asound/cards exists. | ||
| - Identify ALSA cards corresponding to the UAC device. | ||
| - At least one PCM playback or capture node exists for each such card. | ||
| - Print a table of enumerated devices: | ||
|
|
||
| ``` | ||
| DEVICE VID:PID DRIVER PRODUCT | ||
| ------------------------------------------------------------------------------- | ||
| <dev> <vid:pid> <snd-usb-audio> <product> | ||
| ``` | ||
| The test PASS requires all detected UAC devices to have associated ALSA nodes. | ||
|
|
||
| --- | ||
|
|
||
| ## Setup | ||
|
|
||
| - Connect USB Audio peripheral(s) to USB port(s) on DUT. | ||
| - Only applicable for USB ports that support Host Mode functionality. | ||
| - USB Audio peripherals examples: USB headset, microphone, sound card, etc. | ||
|
Contributor
There was a problem hiding this comment. Improve README to clarify exact validation scope |
||
|
|
||
| --- | ||
|
|
||
| ## Usage | ||
| ### Instructions: | ||
| 1. **Copy the test suite to the target device** using `scp` or any preferred method. | ||
| 2. **Navigate to the test directory** on the target device. | ||
| 3. **Run the test script** using the test runner or directly. | ||
|
|
||
| --- | ||
|
|
||
| ### Quick Example | ||
| ``` | ||
| cd Runner | ||
| ./run-test.sh usb_uac | ||
| ``` | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,240 @@ | ||
| #!/bin/sh | ||
|
|
||
| # Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries. | ||
| # SPDX-License-Identifier: BSD-3-Clause | ||
| # Validate USB Audio Class (UAC) device detection | ||
| # Requires at least one USB Audio peripheral (e.g., USB headset, microphone, sound card) connected to a USB Host port. | ||
|
|
||
| TESTNAME="usb_uac" | ||
|
|
||
| # Robustly find and source init_env | ||
| SCRIPT_DIR="$( | ||
| cd "$(dirname "$0")" || exit 1 | ||
| pwd | ||
| )" | ||
|
|
||
| # Default result file (works even before functestlib is available) | ||
| # shellcheck disable=SC2034 | ||
| RES_FILE="$SCRIPT_DIR/${TESTNAME}.res" | ||
|
Contributor
There was a problem hiding this comment. current default is ./${TESTNAME}.res, so early SKIP paths before cd "$test_path" can write the result file into an unexpected working directory.
Contributor
Author
There was a problem hiding this comment. Skip paths before cd "$test_path" could reliably write result file in "$SCRIPT_DIR", please correct me if my understanding is wrong. Does default result file need to be changed to "./${TESTNAME}.res" instead of "$SCRIPT_DIR/${TESTNAME}.res"?
Contributor
There was a problem hiding this comment.
Yes, your understanding is correct. Using: RES_FILE="$SCRIPT_DIR/${TESTNAME}.res" is better for the early SKIP paths before RES_FILE="./${TESTNAME}.res" then early failures such as missing
Contributor
Author
There was a problem hiding this comment. Using RES_FILE="$SCRIPT_DIR/${TESTNAME}.res" for early skip paths in the script |
||
|
|
||
| INIT_ENV="" | ||
| SEARCH="$SCRIPT_DIR" | ||
| while [ "$SEARCH" != "/" ]; do | ||
| if [ -f "$SEARCH/init_env" ]; then | ||
| INIT_ENV="$SEARCH/init_env" | ||
| break | ||
| fi | ||
| SEARCH=$(dirname "$SEARCH") | ||
| done | ||
|
|
||
| if [ -z "$INIT_ENV" ]; then | ||
| echo "[ERROR] Could not find init_env (starting at $SCRIPT_DIR)" >&2 | ||
| echo "$TESTNAME SKIP" >"$RES_FILE" 2>/dev/null || true | ||
| exit 0 | ||
| fi | ||
|
|
||
| # Only source if not already loaded (idempotent) | ||
| if [ -z "${__INIT_ENV_LOADED:-}" ]; then | ||
| # shellcheck disable=SC1090 | ||
| . "$INIT_ENV" | ||
| __INIT_ENV_LOADED=1 | ||
| fi | ||
| # Always source functestlib.sh, using $TOOLS exported by init_env | ||
| # shellcheck disable=SC1090,SC1091 | ||
| . "$TOOLS/functestlib.sh" | ||
|
|
||
| # Resolve test path and cd (single SKIP/exit path) | ||
| SKIP_REASON="" | ||
| test_path=$(find_test_case_by_name "$TESTNAME") | ||
| if [ -z "$test_path" ] || [ ! -d "$test_path" ]; then | ||
| SKIP_REASON="$TESTNAME SKIP - test path not found" | ||
| elif ! cd "$test_path"; then | ||
| SKIP_REASON="$TESTNAME SKIP - cannot cd into $test_path" | ||
| else | ||
| RES_FILE="$test_path/${TESTNAME}.res" | ||
| fi | ||
|
|
||
| if [ -n "$SKIP_REASON" ]; then | ||
| log_skip "$SKIP_REASON" | ||
| echo "$TESTNAME SKIP" >"$RES_FILE" 2>/dev/null || true | ||
| exit 0 | ||
| fi | ||
|
|
||
| log_info "-----------------------------------------------------------------------------------------" | ||
| log_info "-------------------Starting $TESTNAME Testcase----------------------------" | ||
| log_info "=== Test Initialization ===" | ||
|
|
||
| # Check if dependencies are installed, else skip test | ||
| deps_list="grep sed sort wc tr readlink" | ||
| if ! check_dependencies "$deps_list"; then | ||
| log_skip "$TESTNAME SKIP - missing dependencies: $deps_list" | ||
|
Contributor
There was a problem hiding this comment. deps_list does not include every external command used by the script. For example, head is used later when extracting vidpid, driver_info, and product_info, but it is not part of the dependency check. |
||
| echo "$TESTNAME SKIP" >"$RES_FILE" | ||
|
Contributor
There was a problem hiding this comment. check_dependencies from functestlib.sh exits by default when dependencies are missing, so the if ! check_dependencies "$deps_list"; then ... block will normally not run. Recommended fix: either call check_dependencies "$deps_list" directly, or set CHECK_DEPS_NO_EXIT=1 before the call if this script wants to handle the failure itself. |
||
| exit 0 | ||
| fi | ||
|
|
||
| # Detect unique devices with bInterfaceClass = 01 (UAC) under /sys/bus/usb/devices | ||
| log_info "=== USB Audio device Detection ===" | ||
| audio_device_list="$( | ||
| for f in /sys/bus/usb/devices/*/bInterfaceClass; do | ||
| [ -r "$f" ] || continue | ||
| if grep -qx '01' "$f"; then | ||
|
Contributor
There was a problem hiding this comment. Validate more than bInterfaceClass == 01 |
||
| d=${f%/bInterfaceClass} | ||
| d=${d%:*} | ||
| printf '%s\n' "${d##*/}" | ||
| fi | ||
| done 2>/dev/null | sort -u | ||
| )" | ||
|
|
||
| audio_device_count="$(printf "%s\n" "$audio_device_list" | sed '/^$/d' | wc -l | tr -d '[:space:]')" | ||
| log_info "Number of USB audio devices found: $audio_device_count" | ||
|
Contributor
There was a problem hiding this comment. Distinguish playback-only vs capture-only devices and also log bound driver info from sysfs |
||
|
|
||
| if [ "$audio_device_count" -gt 0 ] 2>/dev/null; then | ||
| log_info "=== Enumerated USB Audio Devices ===" | ||
| printf '\n%-9s %-9s %-18s %-s\n' "DEVICE" "VID:PID" "DRIVER" "PRODUCT" | ||
| printf '%s\n' "--------------------------------------------------------" | ||
| dev_info_db="" | ||
| for dev in $(printf "%s\n" "$audio_device_list" | sed '/^$/d'); do | ||
| sys="/sys/bus/usb/devices/$dev" | ||
| vid=$([ -r "$sys/idVendor" ] && tr -d '[:space:]' < "$sys/idVendor" || echo -) | ||
| pid=$([ -r "$sys/idProduct" ] && tr -d '[:space:]' < "$sys/idProduct" || echo -) | ||
| if [ -r "$sys/product" ]; then | ||
|
Contributor
There was a problem hiding this comment. when a UAC interface enumerates but ALSA integration is incomplete, we still lose useful debug context in CI logs. Add a DRIVER column and populate it from the relevant interface driver symlink in sysfs.
Contributor
Author
There was a problem hiding this comment. Added driver info as well for each UAC device. |
||
| product=$(tr -d '\000' < "$sys/product") | ||
| else | ||
| product="-" | ||
| fi | ||
| # Determine driver from the UAC interface driver symlink | ||
| driver="-" | ||
|
|
||
| for intf in "$sys":*; do | ||
| # Only consider UAC interfaces (bInterfaceClass == 01) | ||
| if [ -r "$intf/bInterfaceClass" ] && grep -qx '01' "$intf/bInterfaceClass"; then | ||
| # Resolve driver symlink and extract driver name | ||
| if [ -L "$intf/driver" ]; then | ||
| link="$(readlink "$intf/driver" 2>/dev/null)" | ||
| driver="$(printf "%s\n" "$link" | grep -o 'snd-usb-audio' || echo -)" | ||
| fi | ||
| break | ||
| fi | ||
| done | ||
| dev_info_db="${dev_info_db}\n${dev}|${vid}:${pid}|${driver}|${product}" | ||
| printf '%-9s %-9s %-18s %-s\n' "$dev" "$vid:$pid" "$driver" "$product" | ||
| done | ||
| printf '\n' | ||
| fi | ||
|
|
||
| if [ "$audio_device_count" -le 0 ] 2>/dev/null; then | ||
| log_fail "$TESTNAME : Test Failed - No 'USB Audio Device' found" | ||
|
Contributor
There was a problem hiding this comment. Consider whether “no UAC device attached” should be FAIL or SKIP |
||
| echo "$TESTNAME FAIL" > "$RES_FILE" | ||
| exit 0 | ||
| fi | ||
|
|
||
| # Verify ALSA is available | ||
| if [ ! -r /proc/asound/cards ]; then | ||
| log_fail "$TESTNAME : Test Failed - ALSA not available (/proc/asound/cards missing)" | ||
| echo "$TESTNAME FAIL" > "$RES_FILE" | ||
| exit 0 | ||
| fi | ||
|
|
||
| if [ -r /proc/asound/cards ]; then | ||
| log_info "ALSA cards (/proc/asound/cards):" | ||
| while IFS= read -r line; do | ||
| log_info " $line" | ||
| done < /proc/asound/cards | ||
| fi | ||
|
|
||
| # Identify ALSA cards that correspond to USB | ||
| usb_alsa_card_nums="$(sed -n 's/^[[:space:]]*\([0-9][0-9]*\)[[:space:]]\{1,\}\[[^]]*\]:[[:space:]]\{1,\}USB.*/\1/p' /proc/asound/cards | sort -u)" | ||
| usb_alsa_card_count="$(printf "%s\n" "$usb_alsa_card_nums" | sed '/^$/d' | wc -l | tr -d '[:space:]')" | ||
| log_info "Number of ALSA USB sound cards: $usb_alsa_card_count" | ||
|
Contributor
There was a problem hiding this comment. USB ALSA card discovery depends on parsing /proc/asound/cards with a regex that only accepts card descriptions beginning with USB. Recommended fix: discover candidate cards from /sys/class/sound/card*/device first, resolve each card’s parent USB interface/device, and match that against the detected UAC device list; use /proc/asound/cards only for logging. |
||
|
|
||
| if [ "$usb_alsa_card_count" -le 0 ] 2>/dev/null; then | ||
| log_fail "$TESTNAME : Test Failed - No ALSA 'USB' cards found for detected USB Audio device(s)" | ||
| echo "$TESTNAME FAIL" > "$RES_FILE" | ||
| exit 0 | ||
| fi | ||
|
|
||
| # Map ALSA USB cards to their parent USB device id (e.g., 1-2.3 from 1-2.3:1.0) | ||
| card_map="" | ||
| while IFS= read -r c; do | ||
| [ -n "$c" ] || continue | ||
| link="$(readlink "/sys/class/sound/card${c}/device" 2>/dev/null || true)" | ||
|
Contributor
There was a problem hiding this comment. The card-to-USB mapping uses readlink without -f, then extracts only the basename. if the symlink target shape differs across kernels or ends in an intermediate sound object rather than the USB interface name, parent="${base%%:*}" can produce the wrong USB device id and mark a valid card as unmapped. Recommended fix: use readlink -f "/sys/class/sound/card${c}/device" and walk upward until a directory with idVendor/idProduct or a USB interface pattern is found, then map that stable parent. |
||
| [ -n "$link" ] || continue | ||
| base="${link##*/}" | ||
| parent="${base%%:*}" | ||
| [ -n "$parent" ] || continue | ||
| card_map="${card_map}${parent}|${c}\n" | ||
| done <<EOF | ||
| $usb_alsa_card_nums | ||
| EOF | ||
|
|
||
| # For each detected UAC device, verify mapped ALSA card(s) and device nodes | ||
| has_devnodes_count=0 | ||
| for dev in $(printf "%s\n" "$audio_device_list" | sed '/^$/d'); do | ||
| # Look up device details for debug messages | ||
| vidpid="$(printf "%b" "$dev_info_db" | sed -n "s/^${dev}|\\([^|]*\\)|.*/\\1/p" | head -n1)" | ||
| driver_info="$(printf "%b" "$dev_info_db" | sed -n "s/^${dev}|[^|]*|\\([^|]*\\)|.*/\\1/p" | head -n1)" | ||
| product_info="$(printf "%b" "$dev_info_db" | sed -n "s/^${dev}|[^|]*|[^|]*|\\(.*\\)$/\\1/p" | head -n1)" | ||
|
Contributor
There was a problem hiding this comment. The script interpolates raw USB device ids into sed regexes when looking up dev_info_db. USB device ids can contain dots, which are regex metacharacters. A device such as 1-2.3 can match unintended rows if similarly named devices exist, producing wrong VID/PID/product logs and potentially confusing failure triage. Recommended fix: avoid regex interpolation for structured data; use awk -F'|' -v dev="$dev" '$1 == dev {print $2; exit}' or another literal-field comparison. |
||
|
|
||
| missing_nodes=0 | ||
|
|
||
| # Cards mapped to this USB device | ||
| cards_for_dev="$(printf "%b" "$card_map" | sed -n "s/^${dev}|\\([0-9][0-9]*\\)$/\\1/p" | tr '\n' ' ' | sed 's/[[:space:]]*$//')" | ||
|
|
||
| if [ -z "$cards_for_dev" ]; then | ||
|
Contributor
There was a problem hiding this comment. The same raw-device-id regex issue is used to derive cards_for_dev from card_map. This is more than a logging issue; a wrong match here can map the wrong ALSA card to a UAC device or fail to map a valid one. Recommended fix: replace the sed lookup with literal field matching, for example awk -F'|' -v dev="$dev" '$1 == dev {print $2}', then join results. |
||
| log_info "UAC device $dev ($vidpid '$product_info', driver: $driver_info): No ALSA card mapped" | ||
| missing_nodes=1 | ||
| continue | ||
| fi | ||
|
|
||
| for c in $cards_for_dev; do | ||
| card_path="/sys/class/sound/card$c" | ||
| ctrl_dev="/dev/snd/controlC$c" | ||
|
|
||
| # Check if control device exists | ||
| if [ ! -e "$ctrl_dev" ]; then | ||
| log_info "UAC device $dev (card$c): Missing control device $ctrl_dev" | ||
| missing_nodes=1 | ||
| else | ||
| log_info "UAC device $dev ($vidpid '$product_info') -> card$c: $ctrl_dev exists" | ||
| fi | ||
|
|
||
| # Check for PCM devices (playback/capture) | ||
| pcm_found=0 | ||
|
|
||
| for pcm in "$card_path"/pcmC"${c}"D*p "$card_path"/pcmC"${c}"D*c; do | ||
|
Contributor
There was a problem hiding this comment. PCM node validation manually scans "$card_path"/pcmC"${c}"D*p and *c. This assumes sysfs PCM naming/layout and duplicates ALSA PCM enumeration logic that could be checked more directly through /proc/asound/pcm or aplay -l/arecord -l. Recommended fix: for the card being validated, confirm playback/capture PCMs from /proc/asound/pcm or ALSA tooling, then check matching /dev/snd/pcmC* nodes only as the final device-node check. |
||
| [ -e "$pcm" ] || continue | ||
| pcm_found=1 | ||
| pcm_name="${pcm##*/}" | ||
| dev_node="/dev/snd/${pcm_name}" | ||
| case "$pcm_name" in | ||
| *p) pcm_dir="playback" ;; | ||
| *c) pcm_dir="capture" ;; | ||
| *) pcm_dir="unknown" ;; | ||
| esac | ||
| if [ -e "$dev_node" ]; then | ||
| log_info " PCM device ($pcm_dir): $dev_node exists" | ||
| else | ||
| log_info " PCM device ($pcm_dir): $dev_node missing" | ||
| missing_nodes=1 | ||
| fi | ||
| done | ||
|
|
||
| if [ "$pcm_found" -eq 0 ]; then | ||
| log_info " No PCM devices found for card$c" | ||
| missing_nodes=1 | ||
| fi | ||
| done | ||
| if [ "$missing_nodes" -eq 0 ]; then | ||
| has_devnodes_count=$((has_devnodes_count + 1)) | ||
| fi | ||
| done | ||
|
|
||
| if [ "${has_devnodes_count:-0}" -eq "$audio_device_count" ] 2>/dev/null; then | ||
| log_pass "$TESTNAME : Test Passed - All ($audio_device_count/$audio_device_count) USB Audio device(s) detected have associated ALSA device nodes present" | ||
| echo "$TESTNAME PASS" > "$RES_FILE" | ||
| exit 0 | ||
| else | ||
| log_fail "$TESTNAME : Test Failed - $((audio_device_count - has_devnodes_count))/$audio_device_count USB Audio device(s) missing associated ALSA device nodes" | ||
| echo "$TESTNAME FAIL" > "$RES_FILE" | ||
| exit 0 | ||
| fi | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| metadata: | ||
| name: usb_uac | ||
| format: "Lava-Test Test Definition 1.0" | ||
| description: "This shell script executes on the DUT (Device-Under-Test) and verifies enumeration of connected USB Audio Class (UAC) Devices." | ||
| os: | ||
| - linux | ||
| scope: | ||
| - functional | ||
|
|
||
| run: | ||
| steps: | ||
| - REPO_PATH=$PWD | ||
| - cd Runner/suites/Kernel/Baseport/USB/usb_uac | ||
| - ./run.sh || true | ||
| - $REPO_PATH/Runner/utils/send-to-lava.sh usb_uac.res | ||
|
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The README says PASS requires all detected UAC devices to have associated ALSA nodes, but it does not describe the expected behavior when no USB audio peripheral is connected. The script currently reports FAIL in that case. lab users may schedule this test on boards without an attached UAC peripheral and interpret the result incorrectly.
Recommended fix: document “no UAC device connected” as an expected FAIL, or add a YAML/script parameter such as USB_UAC_REQUIRED=1 so labs can choose FAIL vs SKIP.