General

Intended to unify all WiFi operations under one manager called OneWiFi manager (OWM). The following existing managers BM and WM will be replaced by OWM and we will remove WiFi statistics from SM. Challenges to drive this feature request are:

...

Core principles

• Re-usability

  • OW is designed to be highly modular and embeddable in other applications. It’s built as libow.so and libosw.so that can be linked to other processes if vendor requires special integration.

• Reliability

  • It’s robust in face of failure. It can be easily re-started (eg. if it crashes) with little, to no side-effects on the system. This is achieved by making it infer actions by comparing intentions (resulting from business logic code) against system state. If it crashes and system state is within intended parameters ranges, it will not take any actions that would re-configure, or otherwise impact, the system.

• Idempotency

  • Running the same thing over and over again should yield no side-effect or operations.

• Work deference

  • Main loop handles multiple data flows: When a task depends on multiple sources of data, a local copy of parameters is accumulated, and the task worker always performs the same set of verification on all of the parameters versus operational state of the specific task. This allows higher level of confidence of out-of-order events, or unexpected order of events to be handled correctly and gracefully.

• Observable and subscribe-able:

  • Certain tasks (business logic or not) can be isolated as a “service” that listens for stream of data, does work, and then reports the results of its work to other entities that might use it further.

Components

• OneWiFi Manager (OWM) - OpenSync program that wraps OW as a standalone library

• OneWiFi library (OW) - business logic, that interfaces configuration and state reports and uses OSW to execute actions and police the system

• OpenSync Wireless library (OSW) - low level API which includes all core libraries, helpers, abstractions with no direct impact on behavior and carrying no business logic on their own

Interactions

Many components expose APIs to interact with them: either instantiate actual objects that do the work, or to subscribe to their work results. Components form a cascade of dependencies between each other.

Steering

Steering has been redesigned to revolve around per-ue (user equipment, ie. Laptop, Smartphone, PC, etc) AP candidate lists that can be filtered and ordered by their preference. The client is always intended to be connect to the top-most available candidate. Based on the candidate list state, and the current link of the client, actions are executed: ACL changes, BTM, deauth.

...

Ordering logic is also replaceable. Initially BM’s logic will be repliaced (Wifi_VIF_Neighbor priorities, RRM RCPI).

Example interaction

Pre-assoc policy can mark AP candidate corresponding to the local 2.4G AP interface as blocked. This causes the execution of the ACL executor, which notifies osw_conf about a mutation. Eventually osw_conf re-builds the intended configuration parameters, including asking the ACL executor's mutator instance, to make given Client MAC address to be denied from connecting (this means using accept or deny list)

Statistics

Statistics can be requested by any component and will be streamed as buckets of deltas for the requested data. Components don’t need to worry about timers, overruns, underruns or details whether the underlying osw_drv implementation(s) data extraction procedures (absolute counters, or streamed deltas).

Northbound API

OW is adopting all of the tables that were originally operated by SM, BM and WM. There are no intentional changes to OVSDB.

The component that is responsible for these interactions is ow_ovsdb. OW is prepared to support other buses. There is a ow_webconfig that re-uses Wifi HAL API structures. It is not a independent bus adapter though - it requires to have its exposed API called, and is currently done with 3rd party integration which embeds OW.

OneWiFi library - OW

• ow_conf: Is a osw_conf mutator. Exposes a set of simple setter APIs against VIF and PHY entries (identified by phy_name or vif_name). Intended to be used by bus adapters, eg. ow_ovsdb.

• ow_ovsdb: BUS adapter that interfaces with OVSDB and calls ow_conf to apply intended confiugrations, and uses osw_state to observe system state to report back over Wifi_*_State tables.

• ow_steer_*: A set of steering related modules that have different responsibilities.

  • Used by ow_steer_bm to replicate BM's behavior using ow_steer building blocks.

    • Configured by ow_ovsdb_steer (part of ow_ovsdb)

Southbound API

Target APIs (including BSAL) are obsoleted. They are replaced by the osw_drv unified driver model. Any party interested in providing their specific WLAN driver support need to implement their own osw_drv provider. However, it is highly advisable to re-use existing drivers when possible, eg. osw_drv_nl80211 by providing specializer(s) like osw_plat_qsdk11_4.

It is possible to run osw_drv_target to use the obsoleted APIs. However there are no plans on continuing development of new features on top of the old target and BSAL APIs. osw_drv_target is intended to be a stop-gap solution for pre-existing platforms.

OpenSync Wireless library - OSW

• osw_drv / osw_state / osw_mux: A set of modules and interfaces that abstract driver or platform specifics that allow talking to, and interrogating, with WLAN driver(s). All other OSW and OW components make use of this to interact with WLAN driver(s). This follows a driver model where other components can register themselves as drivers (providers). There can be multiple providers at the same time providing supports for different WLAN drivers, eg. Quantenna + Broadcom. Here are some existing driver implementations:

  • osw_drv_target: stop-gap driver that translates to/from the old (SM, BM, WM) target APIs

  • osw_drv_wifihal_3_0: driver targeting RDK's WifiHAL API 3.0

  • osw_drv_nl80211: driver targeting Linux's nl80211 drivers, including hostAPd

    • Allows specializers to hook into and override certain aspects and behaviours to plug in implementations gaps. Some vendors started providing nl80211 support in their closed-source drivers but still require vendor-specific actions to set some things up.

      • osw_plat_qsdk11_4: Specializer for QSDK 11.4 platform (qcawifi). It overrides some of the osw_drv_vif_state reports and applies additional configurations for request_config_fn.

    • Uses osw_hostap module to isolate non-nl80211 specific logic

      • Allows specializers, similarly to osw_drv_nl80211 itself.

        • osw_plat_qsdk11_4: Makes use of it too, eg. to set send_probe_response=0

• osw_stats: Provides a convenient API for any other module interested in various statistics that would normally be collected by SM. The API uses a subscriber pattern with parameters describing what kinds of statistics are requested, and how and how often they should be collected. The internal scheduler takes care of the details on how to call osw_drv and how to process raw statistics reports.

• osw_confsync: This is mostly providing the mechanic to repliace what WM2 did: compares the actual system state against the desired state, and if out-of-sync, attempts to (re-)configure the system though osw_drv. It relies on osw_conf. If osw_conf has no mutators (osw_conf_mutator), osw_confsync will do nothing.

• osw_conf: Module that as a mediator between osw_confsync, osw_state and other modules that register as mutators. Configuration is always based off of the actual system state inferred from osw_state observation. Then, registered mutators are handed over the resulting initial configuration object with the intention of modifying it accordingly to their own business logic needs. Mutation is observable and use by osw_confsync to know when and what to compare.

  • For example steering module(s) can mutate the ACL alongside other entities that mutate the ACL.

  • For example STA interface’s parent channel can be used to override any possible channel re-configurations on AP interfaces to maintain connectivity and continuity.

Usage

Enabling

OWM is currently built by default, but is not enabled at runtime by default. Check the kconfig MANAGER_OWM_STARTUP option which requires persistent storage and feature flag feature.

Debugging

OWM process is merely instantiating OW, so all logs are attributed to OW module. When trying to debug, one needs to, eg.:

ovsh U AW_Debug -w name==OW name:=OW log_severity:=TRACE
# other severities: NOTICE, INFO, DEBUG, TRACE
# by default its: INFO

Environment

Some components use getenv() to infer if/what they should do. As such one needs to be careful when trying to re-start manually via SSH session, eg. when developing. Currently $INSTALL_PREFIX/scripts/functions.d/ (typically /usr/opensync/scripts/functions.d/) contains a few extra scripts that provide exports to:

• fix wpa_supplicant global socket path (historically many platforms are missing one / in their path)

• disable osw_drv_target (to avoid it conflicting with osw_drv_nl80211)

Currently missing features

• DPP

• Zero-wait DFS

• Some statistics are missing (eg. uplink_type)

Requirements

• QSDK 11.4

  • For osw_drv_nl80211 to provide all functionalities the WLAN driver requires:

    • Fix remain-on-channel to collect chan-stat events: to get surveys

    • Fix WPS IE parsing when starting AP: to allow disabling WPS

    • Fix ACL filtering not working with WPS: to allow blocking clients (pre-assoc steering)

    • Fix reporting RSSI in cfg80211_rx_mgmt: for probe request reporting (pre-assoc steering)

    • Extend RX-PROBE-REQUEST: for probe request reporting (pre-assoc steering)

• Build and runtime dependencies

  • libnl3 is required on the target platform to build osw_drv_nl80211

• Storage requirements:

  • Roughly extra 1.5M is required on rootfs to store libosw.so and libow.so

• RAM requirements:

  • Currently the resulting delta of memory usage, when replacing SM, BM and WM, is roughly 0.