Wi-Fi low-latency mode

Android 10 extends the Wi-Fi lock API to allow latency-sensitive apps to configure Wi-Fi to a low-latency mode. The low-latency mode starts when all of the following conditions are met:

• Wi-Fi is enabled and the device has internet access.
• The app has created and acquired a Wi-Fi lock, and is running in the foreground.
• The screen is on.

To support low-latency mode on devices, device manufacturers must update the WLAN driver and vendor HAL. In low-latency mode, power save (also known as doze state in the IEEE 802.11 standard) is explicitly disabled by the framework. The scanning and roaming parameters in the driver and firmware layers can be optimized to further reduce Wi-Fi latency. The exact optimizations are implementation specific.

Android has a high-performance Wi-Fi lock mode (introduced in API level 12) that is separate from the low-latency mode.

Implementation

To support the Wi-Fi low-latency mode feature, provide implementations for the following IWifiChip functions.

In the AIDL HAL:

• int getFeatureSet()
• void setLatencyMode(in LatencyMode mode)

In the HIDL HAL (1.3 or newer):

• getCapabilities_1_3() generates (WifiStatus status, bitfield<ChipCapabilityMask> capabilities)
• setLatencyMode(LatencyMode mode) generates (WifiStatus status)

A reference implementation can be found in wifi_legacy_hal.cpp with the following functions:

• wifi_error wifi_get_supported_feature_set(wifi_interface_handle iface, feature_set *set)
• wifi_error wifi_set_latency_mode(wifi_interface_handle handle, wifi_latency_mode mode)

In low-latency mode, power save is explicitly disabled by WifiLockManager in the Android framework. To support this, the WLAN driver must support the NL80211 command, NL80211_CMD_SET_POWER_SAVE, to enable and disable power save. When Wi-Fi power save is disabled, the Wi-Fi system must stay in the awake state and be ready to send or receive packets with minimum delay.

Disable the feature

To turn off the low-latency mode feature, update the underlying code of getFeatureSet() for the AIDL HAL or getCapabilities_1_3() for the HIDL HAL, such that capabilities & SET_LATENCY_MODE = 0, where SET_LATENCY_MODE is defined in the IWifiChip AIDL or HIDL definition. When this feature is disabled, the framework disables power save only when the low-latency mode is active.

Validation

To test that low-latency mode works when enabled, run the following automated tests and manual ping latency tests.

Automated testing

Run the following VTS and CTS tests:

• VTS (AIDL): hardware/interfaces/wifi/aidl/vts/functional/wifi_chip_aidl_test.cpp
• VTS (HIDL): hardware/interfaces/wifi/1.3/vts/functional/wifi_chip_hidl_test.cpp
• CTS: cts/tests/tests/net/src/android/net/wifi/cts/WifiLockTest.java

Manual testing

Required test equipment and environment

For manual testing, the following setup is required:

• Wi-Fi access point (AP)

• Device-under-test (DUT) phone and test computer

  • The DUT must be connected to the access point over Wi-Fi.
  • The test computer must be connected to the access point over Wi-Fi or Ethernet.
  • The test computer must be connected to the DUT over USB.

Uplink ping test

1. Enable low latency mode.

   adb root
   adb shell cmd wifi force-low-latency-mode enabled

2. Make sure your computer is connected with the phone through ADB. From the ADB shell, ping the gateway continuously for 3 hours at 1 second intervals.

3. Save the test output in a text file and use a spreadsheet or a Python script to generate a histogram of the ping latency test results.

4. Repeat steps 1 through 3 with latency mode disabled.

   adb root
   adb shell cmd wifi force-low-latency-mode disabled

5. Compare the test results to ensure that the average ping latency value is reduced when the low-latency mode is enabled.

Downlink ping test

1. Enable low-latency mode.

   adb root
   adb shell cmd wifi force-low-latency-mode enabled

2. From the command line of the test computer, ping the phone's IP address continuously for 3 hours at 1 second intervals.

3. Save the test output in a text file and use a spreadsheet or a Python script to generate a histogram of the ping latency test results.

4. Repeat steps 1 through 3 with latency mode disabled.

   adb root
   adb shell cmd wifi force-low-latency-mode disabled

5. Compare the test results to ensure that the average ping latency value is reduced when the low-latency mode is enabled.

Other tests

Repeat the above tests in different environments. For example, at home or in the office.