Adaptive World Mode 60-SIPT/60-2230C Introduction This application note provides information on the Adaptive World Mode (AWM) feature for the 60 series 60-SIPT and 60-2230C products. When the radio’s regulatory domain is configured for World Mode, this feature uses an FCC-compliant geo-location algorithm and the 802.11d Country IE to determine the current location and set the regulatory country code of the client radio for optimal performance. Components AWM consists of 4 main components - the driver, radio firmware, adaptive world mode daemon and database, and the Linux CRDA database. These components must be properly deployed by the customer for this feature to work correctly and maintain regulatory compliance. The following sections describe these components, their requirements, and how they interact to optimize the radio’s performance. Driver The Ezurio Wi-Fi driver facilitates secure passage of information between the AWM daemon and radio firmware. In addition, it monitors the radio operation to ensure that the geo-location is updated in a timely manner without errors, and it coordinates the regulatory country settings used by the firmware and the Linux Wi-Fi radio stack. If any anomaly is detected the driver resets the radio stack back to its initial world mode boot settings. Radio Firmware The radio firmware receives messages from the AWM daemon, decrypts and validates that the message is not a replay or been tampered with, and adjusts the radio’s hardware registers and TX powers to maintain regulatory compliance. In addition, the firmware maintains a 60-minute timer which resets each time AWM “checks in”. If this timer should ever expire the firmware informs the driver and reverts to its boot time world mode settings. Linux CRDA Database The Linux CRDA component is a historical daemon used to look up the regulatory country code settings from an external database (CRDA database) and send them to the Linux Wi-Fi radio stack for use in determining the valid channel set and per channel characteristics (e.g. DFS, passive scan, allowed bandwidth, etc.) for a given regulatory country code/domain. Prior to kernel 4.15 the Summit backports package compiled this database directly into the Linux Wi-Fi stack, but since 4.15 both CRDA and the ability to statically compile in the database have been deprecated. Instead, the Linux community has chosen to update the database format and have it read in directly by the Linux Wi-Fi stack. The name and path of this database is /lib/firmware/regulatory.db. When this feature is enabled, upon boot the Linux Wi-Fi radio stack reads this database to obtain the list of valid countries/domains and associated data. In addition, the database is referenced each time the Linux Wi-Fi stack is provided a location hint via the associated AP’s 802.11d country IE, a driver notification, or a user notification. In order to meet regulatory compliance the CRDA feature, which is controlled by the CFG80211_CRDA_SUPPORT kernel configuration option, MUST be enabled in the host’s Linux kernel build and an appropriate regulatory.db MUST be deployed. Ezurio provides such a regulatory.db in each radio firmware package it releases. Note: Deployments using kernel 4.4 or newer do not need to configure CFG80211_CRDA_SUPPORT, however the regulatory.db still needs to be present. Adaptive World Mode Overview The adaptive world mode daemon (AWM) is a user mode application responsible for implementing the geo-location algorithm. Like CRDA, it makes use of a cryptographically signed database, /lib/firmware/lrdmwl/regpwr.db, containing the list of 802.11d country codes, per country hardware power limitations, and channel characteristics required by the radio firmware to stay in regulatory compliance for a given location/country. If this database is not present or has been tampered with, AWM will not perform geo-location detection and thus the radio stack will stay in its sub-optimal boot time world mode state. When AWM starts it verifies that the RegulatoryPwrDB exists, that it was signed with a certificate created by Ezurio and its content has not been tampered with. Afterwards it enumerates the interfaces on the system looking for wireless adapters which indicate they are Ezurio Radios, have a station/managed or AP interface, and whose OTP memory is set to the worldwide (WW) regulatory domain. For each adapter meeting this criteria AWM stores this information and then waits for one of these adapters to indicate its interface is up if it is not already up. Once AWM finds such an interface, it marks the interface the active interface and initiates a geo-location scan to determine the present location. Upon scan completion AWM sorts the 802.11d IEs broadcast by the surrounding APs according to RSSI value. If the location can be determined and the geo-location is found in the RegulatoryPwrDB, AWM sends the corresponding RegulatoryPwrDB entry to the driver/firmware for further processing and optimization. If at any point AWM receives an indication that the active interface is removed or marked down, AWM may re-enumerate the system adapters looking for another Ezurio Radio and when found restart a geo-location scan. Finally, in cases where AWM is stopped it informs the radio firmware to revert to its world mode domain settings before exiting. Interface Selection While AWM manages multiple Wi-Fi adapters, it uses a single interface for geo-location detection. The selection algorithm uses the first interface it finds that matches the preferred interface type, by default a managed/station interface, and is up and capable of issuing scans. When searching for a preferred interface to use, the selection algorithm starts with the lowest numbered Wi-Fi adapter (e.g. phy0) and lowest numbered interface index (e.g. wlan0) it can. If the preferred interface type can’t be found AWM uses a non-preferred interface. Once a usable interface is found AWM uses this interface for all geo-location scans until such time that the interface is no longer available (e.g. interface is set down or removed) unless the useable interface is not of the preferred type, in which case AWM will re-evaluate the available interfaces whenever a new interface arrives. Should AWM switch the active interface or adapter, it may initiate a geo-location scan depending on its operating mode. The preferred interface type may be changed by using the command line option -F with one of the following values: Value Behavior STA Prefer station/managed interfaces for geo-location scans (default) AP Prefer AP interfaces for geo-location scans NONE No preference, use the first interface found for geo-location scans Algorithm The AWM geo-location algorithm maintains up to 5 APs in its country code list, with the AP with the highest RSSI ranked first. The daemon then acts based on the following rules: APs Detected Total Count Country Code A Total Count Country Code B Action >=3 3 of top 5 APs 2 Set Regulatory Domain to Country Code A >=3 2 of top 5 APs 2 Remain in Worldwide Mode >=3 2 of top 5 APs 1 Set Regulatory Domain to Country Code A >=3 1 of top 5 APs 1 Remain in Worldwide Mode 2 2 of top 2 APs 0 Set Regulatory Domain to Country Code A 2 1 of top 2 APs 1 Remain in Worldwide Mode <=1 1 of top 1 APs 0 Remain in Worldwide Mode * *AWM lite mode will Set Regulatory Domain to Country Code A Note: The adaptive world mode daemon only works with Ezurio 60 series radios. Opportunistic Scans AWM may make use of scan results that were initiated by ‘3rd Party’ applications, e.g. wpa supplicant, to determine its geo-location. By doing so it results in fewer interruptions to the Wi-Fi stack and thus better overall network performance. Standard Mode Standard mode operation is the out-of-box operating mode and is compliant with FCC regulatory requirements. Under normal operation once AWM sends the geo-location to the radio firmware it starts a periodic 30-minute timer, unless it fails to negotiate a country code in which case the timer may be set to expire sooner, which upon expiration causes AWM to revalidate its current geo-location. When running in standard mode, every time an interface change occurs AWM will initiate a geo-location scan in order to comply with the FCC requirement that ‘Device must recheck the geo-location at least once every hour, when the device is switched on and connections are established or changed’. Lite Mode Lite mode is an operating mode that allows operating in a manner which is not FCC compliant but is less disruptive to the overall system, e.g. no geo-location check every hour, and still allows detection of current geo-location. When operating in lite mode AWM continues its current boot procedure where it enumerates the adapters and initiates a geo-location scan to determine the present location. However, once the geo-location is determined and AWM has sent this information to the radio firmware, it stops all future geo-location scans. Unlike standard mode, as interfaces come and go, AWM will transition across them without initiating a geo-location scan unless AWM is transitioning from having no useable interface in which case it will restart the full geo-location detection algorithm. When running in this mode, forcing AWM to transition from this no useable interface state (e.g. set all interfaces down via ip link set wlan0 down) is one way to force AWM to re-evaluate its geo-location. To enable lite mode use the command line option -M and the value lite. Note: Devices running with AWM in lite mode are not FCC compliant and must not be shipped to the USA. Strict Country Enforcement AWM’s lite mode is only intended to be used exclusively outside countries that require the geo-location be checked periodically, e.g. USA. Therefore, to stay compliant and help enforce the use of AWM’s standard operating mode where required, whenever AWM determines the geo-location is in one of these countries while running in lite mode, AWM will stay in world mode and immediately stop all further active geo-location scan attempts. Once AWM is in this state the only way to leave this state is to reboot the device, set all interfaces down/up, or AWM making use of an opportunistic scan to determine that the geo-location is no longer in an area where strict country enforcement is required. Wi-Fi MAC Address Overrides AWM uses the OUI assigned to the Wi-Fi MAC address to determine if AWM should manage the regulatory domain for a wireless radio. The OUI that AWM uses for this defaults to CCEE40. If the user overrides this MAC address with another address, then AWM will no longer manage the radio’s regulatory domain unless the new OUI is provided, which can be done using the -O [OUI] parameter when starting AWM. Note: Releases 11.39.0.19 and newer no longer use the OUI to determine if the radio is manageable. Installation This section lists the components and tools needed to deploy adaptive world mode feature on an end device. Software Components The AWM feature is made available as a binary executable and supporting files. These files are distributed as a tarball package having the name: adaptive_ww-<openssl_version>-<platform_ext>-<version>.tar.bz2 The list of supported platforms and platform naming conventions are: Platform Platform Extension Name arm soft-float arm-eabi arm hard-float arm-eabihf arm aarch64 arm-eabiaarch64 x86 32-bit x86 x86 64-bit x86-64 PowerPC 32-bit powerpc-e5500 The files in the tarball are listed below along with a description and location where they should be installed on the end device. They must be present and/or running on the end device for AWM to work properly. File Description Location regulatory.db The CRDA database /lib/firmware regpwr.db The AWM database /lib/firmware/lrdmwl adaptive_ww The AWM daemon /usr/bin adaptive_ww system V service file /etc/init.d/ adaptive_ww.services systemd service file /usr/lib/systemd/system/ Note: The first release of AWM named the system V service file S30adaptive-ww. It will be changed to adaptive_ww in subsequent releases. Shared Object Dependencies The adaptive_ww daemon depends on the following shared objects: libnl-genl-3.so.200 libnl-route-3.so.200 libnl-3.so.200 libcrypto.so.1.1 or libcrypto.so.1.0.0 libpthread.so.0 libc.so.6 Lightweight Manufacturing Utility The LMU vendor tool is used to set the radio’s OTP memory to the regulatory country code into which the device is shipping. If world mode is desired the vendor should use WW or WW440 where the 440 indicates that the radio has been certified for EN 300-440 compliance and as such may use U-NII-3 band (5725-5850) when determined to be in an ETSI country. More information about this tool may be found in the 60 series vendor tool app note document. Note: By default Ezurio radios are set to WW in the factory.
