Quality/TestSuite/WIFI Driver Test Specification

Revision as of 14:48, 8 December 2010

Introduction

nl80211 is the 802.11 netlink interface and cfg80211 is the linux wireless configuration API.

nl80211 is used to configure a cfg80211 device and together they are intended to replace Wireless-Extensions in the future.

Test Coverage

Software Coverage

blts-wlan-core package (0.1.3) is testing nl80211 commands and also some Wireless-Extensions ioctls and events but only when corresponding nl80211 implementations are not available.

Current BLTS WLAN test coverage matrix:

• [WLAN-core-coverage.ods]

Hardware Coverage

Linux wireless cards/drivers that support nl80211/cfg80211 (and Wireless Extensions).

Limitations

Future Improvements

Future test cases may include further tests for nl80211 commands which are not covered yet.

Running the tests

Hardware setup and test environment

Required hardware for testing over the air:

• test device, running the test asset
• WLAN Access Point, for AP-using tests
• a second test device or other supported device for "ad-hoc" (IBSS) tests.

Multiple access points with different static configurations can be used instead of changing the AP configuration directly. The access point used must support DHCP discovery, either by itself or via a suitable network arrangement. SSIDs, keys and passphrases used must be entered in the test configuration file.

The adhoc tests "Establish new adhoc network" and "Join established adhoc network" are counterparts and require two adhoc mode capable test devices, both running the test case.

The test environment must have following packages installed:

• libbltscommon1

Setting up software simulator - mac80211_hwsim

If there is no suitable HW available for test execution or there is a need for verifying test case functionality, it is also possible to run some test cases with mac80211_hwsim.

mac80211_hwsim is a software simulator of 802.11 radios for mac80211. It is a Linux kernel module that can be used to simulate arbitrary number of IEEE 802.11 radios for mac80211.

The following steps are needed to use mac80211_hwsim to simulate radios and run test cases

1) build mac80211_hwsim as part of kernel configuration

2) load the kernel module (parameter 'radios' can be used to select how many radios are simulated - default 2)

$ modprobe mac80211_hwsim

Read further instruction about mac80211_hwsim usage from mac80211_hwsim web page (http://wireless.kernel.org/en/users/Drivers/mac80211_hwsim)

To simulate AP where the other station can associate to, the hostapd daemon (http://w1.fi/hostapd/) with a proper configuration file can be used

$ hostapd hostapd.conf

Building packages

The wlan-core test package comes with a packaging script that can be used to build tarball out of the sources, RPM package or Debian package. To build RPM package, in the root directory execute command:

./pack.sh -r

To get packaging script help, execute command:

./pack.sh -h

The building environment requires the following RPM packages installed:

• libbltscommon-devel
• libnl-devel

Configuration package

The wlan-core-tests package is dependent on blts-wlan-core-tests-config configuration file package. The packaging script pach.sh creates RPM package blts-wlan-core-tests-config-example_{version}.rpm and it must be installed first. The configuration file /etc/blts/blts-wlan-core-tests.cnf is copied in the test device during RPM installation.

The configuration file package can be installed in the device with a command: blts-wlan-core-tests-config-example_{version}.rpm

Test asset specific instructions

The test package can be installed in the device with a command:

rpm -ivh blts-wlan-core-tests_{version}.rpm 

Test case execution instructions:

The Enumerate hardware and Enumerate supported features tests run on a single device and do not require any existing access points. Enumerate hardware case can be configured to search expected phys (e.g. phy0) from the test device.

The configuration file used must be modified to match the test environment. SSIDs, keys and passphrases used must be entered in the test configuration file before testing.

Disconnect with AP loss test case waits about 60 seconds after connection is established that tester will turn off the AP where connection is made. The test case shows tester a text "Turn off AP to pass this test" and will only continue if AP is turned off, otherwise timeout occurs and test case fails.

Test cases using established adhoc network are counter parts and these test cases must be executed at the same time with two devices, so that the establishing side must be executed first and the joining side soon after that. The name and used channel for established adhoc network can be configured in the configuration file. The SSID used here must be unique (no networks with a same name in the test environment) otherwise these tests fail.

Test case arguments

Arguments:

Running test cases

Test cases execution must be done with root privileges.

Test case execution notices:

Test case descriptions and execution commands:

• Core-WLAN-Enumerate hardware

* Check that expected PHYs are found, then dump all PHYs, interfaces, and available configuration data

* $ blts-wlan-core-tests -en "Core-WLAN-Enumerate hardware"

• Core-WLAN-Enumerate supported features

* Dump commands and parameters that are supported by device/driver

* $ blts-wlan-core-tests -en "<code>$ blts-wlan-core-tests -en "Core-WLAN-Enumerate hardware""</code>

• Core-WLAN-Scan for specific AP

* Trigger a new scan with a given ssid and verify that AP is actually found

* $ blts-wlan-core-tests -en "Core-WLAN-Scan for specific AP"

• Core-WLAN-Associate with open AP

* Scan for open AP with a given ssid, after that do authentication and association requests, finally disconnect

* $ blts-wlan-core-tests -en "Core-WLAN-Associate with open AP"

• Core-WLAN-Associate with WEP encryption

* Scan for AP with a given ssid, after that set WEP encryption keys and do connection request, send DHCP discover and finally disconnect

* $ blts-wlan-core-tests -en "Core-WLAN-Associate with WEP encryption"

• Core-WLAN-Scan and associate on max power save

* Set max power save on and scan for open AP with a given ssid, after that connect and finally disconnect.

* NOTE: overrides command line parameter -S (power save)

* $ blts-wlan-core-tests -en "Core-WLAN-Scan and associate on max power save"

• Core-WLAN-Associate with WPA2-PSK AP

* Scan for AP with a given SSID, and associate. Perform WPA2 key exchange using pre-shared key.

* Verify connection using DHCP discover and finally disconnect.

* $ blts-wlan-core-tests -en "Core-WLAN-Associate with WPA2-PSK AP"

• Core-WLAN-Disconnect with deauthenticate

* Scan for open AP with a given ssid, after that do connection request, send DHCP discover and finally disconnect using

* deauthenticate command while waiting until disconnect event is received.

* $ blts-wlan-core-tests -en "Core-WLAN-Disconnect with deauthenticate"

• Core-WLAN-Disconnect with disassociate

* Scan for open AP with a given ssid, after that do connection request, send DHCP discover and finally disconnect using

* disassociate command while waiting until disconnect event is received.

* $ blts-wlan-core-tests -en "Core-WLAN-Disconnect with disassociate"

• Core-WLAN-Disconnect with AP loss

* Scan for open AP with a given ssid, after that do connection request, send DHCP discover and start waiting until disconnect event is received.

* NOTE: Manual test where AP must be turned off in about 60 seconds before test case can be continued.

* $ blts-wlan-core-tests -en "Core-WLAN-Disconnect with AP loss"

• Core-WLAN-Disconnect from adhoc network

* Scan for open adhoc network with a given ssid, after that join a IBSS and verify connection by sending test data and using scan

* request, after that leave IBSS and verify that device is properly disconnected from adhoc network. NOTE: The requirement for this test

* case is existing adhoc network where DUT can be joined or optionally wlan station that supports adhoc connections. NOTE2: if there is no

* existing adhoc network in the test environment "Core-WLAN-Establish new adhoc network" can be also used as a counterpart for this test case.

* $ blts-wlan-core-tests -en "Core-WLAN-Disconnect from adhoc network"

• Core-WLAN-Establish new adhoc network

* Estabish new IBSS with no encryption, after that start receiving test data packets and compare payload with expected data. This test case

* fails if adhoc network with same SSID already exists. NOTE: This test case requires either "Core-WLAN-Join established adhoc network" or

* optionally "Core-WLAN-Disconnect from adhoc network" as a counterpart and must be run first.

* $ blts-wlan-core-tests -en "Core-WLAN-Establish new adhoc network"

• Core-WLAN-Join established adhoc network

* Scan for open adhoc network with a given ssid, after that join a IBSS and verify connection by sending test data that is verified in

* the other DUT. NOTE: This test case requires "Core-WLAN-Establish new adhoc network" as a counterpart and must be run after it.

* $ blts-wlan-core-tests -en "Core-WLAN-Join established adhoc network"

Configuration file examples

To run test cases with variable data you need to specify where configuration file is located or if no configuration file is given, test driver tries to use default /etc/blts/blts-wlan-core-tests.cnf

The configuration file must be edited to match your test environment.

Access point SSID parameters in blts-wlan-core.cnf configuration file:

• open_ssid - SSID for an existing open AP
• wep_ssid - SSID for an existing WEP-encrypted AP
• wpa_ssid - SSID for an existing WPA-encrypted AP
• adhoc_ssid - SSID for an existing open adhoc network
• adhoc_ssid2 - SSID for established open adhoc network (adhoc network created during test runs)

To run "Core-WLAN-Associate with WEP encryption" case for example, execute the command:

blts-wlan-core-tests -l /var/log/tests/Core-WLAN-Associate_with_WEP_encryption.log -en "Core-WLAN-Associate with WEP encryption" -C /etc/blts/blts-wlan-core-tests.cnf

Example of WEP encryption case variation:

# Parameter configuration for blts-wlan-core

# Valid wlan devices for HW.
[parameter]
	name wlan_device
	const "wlan0" "wlan1"
[end_parameter]

# SSID for an existing AP (change this to match your environment)
[parameter]
	name ssid
	const "test-1"
[end_parameter]

# WEP keys - wep key format "i:t:key", space separated 
# i = index (0 - 3)
# t = type (a: = ASCII wep key / h: HEX wep key)
# e.g.
# first 0 index ascii wep key abcdef ->  0:a:abcdef
[parameter]
	name wep_keys
	const "0:a:abcde"
[end_parameter]

# WEP key index (0 - 3) - default key to transmit
[parameter]
        name wep_tx_keyidx
        const 0
[end_parameter]

# Tests

[test]       
	name "Core-WLAN-Associate with WEP encryption"
	params wlan_device ssid wep_keys wep_tx_keyidx
[end_test]

Module Design and Architecture

The test module can be compiled to self-sufficient command line program. Both Debian and RPM packaging is also provided.

Architecture diagram

References

Change History