# rdkcentral/rdkb-halif-wifi architecture

> Architecture diagram of the GitHub repository rdkcentral/rdkb-halif-wifi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rdkcentral/rdkb-halif-wifi
- Repository: https://github.com/rdkcentral/rdkb-halif-wifi

## Overview

#### Purpose and delivery model
This repository defines the RDK-B Wi-Fi Hardware Abstraction Layer (HAL) contract: a platform-independent C API implemented by OEM/SoC vendors and consumed by upper RDK components. It is primarily an interface/documentation repository, not a HAL implementation. The deliverable is a single, statically loadable, process-lifetime library with one initialized HAL instance.

Core interface: `include/wifi_hal.h`  
Build/package metadata: `configure.ac`, `build_ut.sh`

#### Entry point and lifecycle
Consumers must call `wifi_init()` before every other API. The HAL remains available for the process lifetime, is expected to be thread-safe, and APIs must not block. HAL-created memory remains HAL-owned; caller-created memory remains caller-owned unless an API specifies otherwise.

The upper layer owns persistent Wi-Fi configuration; the HAL applies requested state to the platform and reports standardized return codes.

Primary API root: `include/wifi_hal.h`  
Contract reference: `docs/pages/halSpec.md`

#### API partitioning
The public contract is divided by Wi-Fi domain rather than implementation layers:
- Common/generic types, initialization, capability discovery, and shared operations.
- Radio configuration and PHY-level control.
- AP/VAP creation, configuration, and connected-device management.
- Station/client operation and scan/connection status.
- Telemetry, extender, emulation, and deprecated compatibility surfaces.

Paths: `include/wifi_hal_generic.h`, `include/wifi_hal_radio.h`, `include/wifi_hal_ap.h`  
Additional domains: `include/wifi_hal_sta.h`, `include/wifi_hal_telemetry.h`, `include/wifi_hal_extender.h`

#### Primary control flow
An upper RDK process initializes the HAL, queries capabilities, then configures radios and creates/configures VAPs. Vendor HAL code translates these abstract operations to the Linux Wi-Fi stack and vendor driver. Capability APIs are the feature boundary: upper layers use them to avoid invoking unavailable platform features.

Expected sequence: initialization → capability discovery → radio operating parameters → VAP lifecycle.  
API surfaces: `include/wifi_hal.h`, `include/wifi_hal_radio.h`, `include/wifi_hal_ap.h`

#### Asynchronous event boundary
The HAL exposes callback-registration APIs for operations whose outcomes arrive asynchronously, including management-frame transmission, AP association/deauthentication/disassociation events, STA connection changes, and scan results. Callers must copy callback data unless API documentation says otherwise. This separates non-blocking request APIs from driver/kernel-originated events.

Relevant contracts: `include/wifi_hal_ap.h`, `include/wifi_hal_sta.h`, `include/wifi_hal_client_mgt.h`

#### Platform and infrastructure boundary
The vendor implementation sits between RDK consumers and Linux kernel Wi-Fi facilities/drivers. `cfg80211`/`nl80211` and `hostapd` are optional vendor-selected integration components. Kernel boot is expected to start HAL dependencies before `wifi_init()`.

The repository uses Autotools metadata and a unit-test build script; documentation is generated from Doxygen-oriented interface comments.

Paths: `configure.ac`, `docs/generate_docs.sh`, `docs/pages/halSpec.md`

#### Operational constraints
Vendor implementations must map internal/system failures to fixed API return codes, log errors and critical events consistently (specified log filename: `wifi_vendor_hal.log`), and minimize idle CPU/memory use. Compile-time feature flags may vary implementations, while runtime capability reporting preserves a stable upper-layer contract.

Compatibility and optional interfaces: `include/wifi_hal_deprecated.h`, `include/wifi_hal_emu.h`

Main entry points: [`include/wifi_hal.h`](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal.h) (HAL API Root), [`include/wifi_hal_radio.h`](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_radio.h) (Radio & PHY Control), [`include/wifi_hal_ap.h`](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_ap.h) (AP & VAP Management), [`include/wifi_hal_generic.h`](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_generic.h) (Capability Discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_contract["Public HAL Contract"]
  node_hal_root["HAL API Root<br/>C API<br/>[wifi_hal.h]"]
  node_lifecycle["Initialization &amp; Ownership<br/>contract<br/>[wifi_hal.h]"]
  node_capabilities["Capability Discovery<br/>feature boundary<br/>[wifi_hal_generic.h]"]
  node_generic["Common Types &amp; Operations<br/>API domain<br/>[wifi_hal_generic.h]"]
  node_compatibility["Emulation &amp; Deprecated APIs<br/>compatibility API"]
end

subgraph group_domains["Wi-Fi Domains"]
  node_radio_api["Radio &amp; PHY Control<br/>API domain<br/>[wifi_hal_radio.h]"]
  node_ap_api["AP &amp; VAP Management<br/>API domain<br/>[wifi_hal_ap.h]"]
  node_sta_api["Station &amp; Scan<br/>API domain<br/>[wifi_hal_sta.h]"]
  node_client_events["Client Event Callbacks<br/>callback API"]
  node_telemetry["Telemetry &amp; Extender<br/>optional API domains"]
end

subgraph group_platform["Vendor Platform Boundary"]
  node_vendor_hal{{"Vendor HAL Implementation<br/>OEM shared library"}}
  node_async_events["Driver-Originated Events<br/>asynchronous flow"]
  node_linux_wifi["Linux Wi-Fi Stack &amp; Driver<br/>platform integration"]
end

subgraph group_delivery["Delivery &amp; Documentation"]
  node_build["Autotools Build Metadata<br/>build system<br/>[configure.ac]"]
  node_docs["HAL Specification<br/>documentation<br/>[halSpec.md]"]
  node_doc_generator["Documentation Generator<br/>build script<br/>[generate_docs.sh]"]
end

node_rdk_consumer["Upper RDK Process<br/>consumer"]

node_rdk_consumer -->|"links and calls"| node_hal_root
node_hal_root -->|"requires wifi_init"| node_lifecycle
node_hal_root -->|"exposes"| node_capabilities
node_hal_root -->|"includes"| node_generic
node_hal_root -->|"includes"| node_radio_api
node_hal_root -->|"includes"| node_ap_api
node_hal_root -->|"includes"| node_sta_api
node_capabilities -.->|"gates feature use"| node_radio_api
node_capabilities -.->|"gates feature use"| node_ap_api
node_rdk_consumer -->|"configures radios"| node_radio_api
node_radio_api -->|"then creates VAPs"| node_ap_api
node_ap_api -->|"registers AP events"| node_client_events
node_sta_api -->|"receives scan and connection events"| node_async_events
node_client_events -->|"receives client events"| node_async_events
node_hal_root -->|"implemented by"| node_vendor_hal
node_vendor_hal -->|"translates operations to"| node_linux_wifi
node_linux_wifi -->|"originates"| node_async_events
node_hal_root -.->|"retains optional surfaces"| node_compatibility
node_build -->|"packages contract library"| node_hal_root
node_doc_generator -->|"generates reference"| node_docs
node_docs -.->|"specifies behavior"| node_hal_root

click node_hal_root "https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal.h"
click node_lifecycle "https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal.h"
click node_capabilities "https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_generic.h"
click node_generic "https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_generic.h"
click node_radio_api "https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_radio.h"
click node_ap_api "https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_ap.h"
click node_sta_api "https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_sta.h"
click node_client_events "https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_client_mgt.h"
click node_telemetry "https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_telemetry.h"
click node_compatibility "https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_deprecated.h"
click node_build "https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/configure.ac"
click node_docs "https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/docs/pages/halSpec.md"
click node_doc_generator "https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/docs/generate_docs.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hal_root,node_lifecycle,node_capabilities,node_generic,node_compatibility toneBlue
class node_radio_api,node_ap_api,node_sta_api,node_client_events,node_telemetry toneAmber
class node_vendor_hal,node_async_events,node_linux_wifi toneMint
class node_build,node_docs,node_doc_generator toneRose
class node_rdk_consumer toneNeutral
```

## Components

### Public HAL Contract

Platform-independent API headers and lifecycle rules.

- [HAL API Root](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal.h): C API · Statically loaded process-lifetime HAL entry point. · `include/wifi_hal.h`
- [Initialization & Ownership](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal.h): contract · wifi_init precedes all APIs; calls are non-blocking and thread-safe. · `include/wifi_hal.h`
- [Capability Discovery](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_generic.h): feature boundary · Prevents consumers from calling unavailable platform features. · `include/wifi_hal_generic.h`
- [Common Types & Operations](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_generic.h): API domain · `include/wifi_hal_generic.h`
- [Emulation & Deprecated APIs](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_deprecated.h): compatibility API · `include/wifi_hal_deprecated.h`

### Wi-Fi Domains

Domain-specific API surfaces.

- [Radio & PHY Control](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_radio.h): API domain · `include/wifi_hal_radio.h`
- [AP & VAP Management](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_ap.h): API domain · Creates and configures VAPs and manages connected devices. · `include/wifi_hal_ap.h`
- [Station & Scan](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_sta.h): API domain · `include/wifi_hal_sta.h`
- [Client Event Callbacks](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_client_mgt.h): callback API · Association, deauthentication, and disassociation event registration. · `include/wifi_hal_client_mgt.h`
- [Telemetry & Extender](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/include/wifi_hal_telemetry.h): optional API domains · `include/wifi_hal_telemetry.h`

### Vendor Platform Boundary

OEM implementation and Linux Wi-Fi integration.

- **Vendor HAL Implementation**: OEM shared library · Maps the stable contract to platform behavior and standardized return codes.
- **Driver-Originated Events**: asynchronous flow · Callback data is transient unless the contract says otherwise.
- **Linux Wi-Fi Stack & Driver**: platform integration · May use cfg80211/nl80211 and hostapd.

### Delivery & Documentation

Build metadata and generated contract documentation.

- [Autotools Build Metadata](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/configure.ac): build system · `configure.ac`
- [HAL Specification](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/docs/pages/halSpec.md): documentation · Doxygen-oriented contract reference. · `docs/pages/halSpec.md`
- [Documentation Generator](https://github.com/rdkcentral/rdkb-halif-wifi/blob/develop/docs/generate_docs.sh): build script · `docs/generate_docs.sh`

### Other components

- **Upper RDK Process**: consumer · Owns persistent Wi-Fi configuration and consumes the HAL.

## Connections

- Upper RDK Process → HAL API Root: links and calls
- HAL API Root → Initialization & Ownership: requires wifi_init
- HAL API Root → Capability Discovery: exposes
- HAL API Root → Common Types & Operations: includes
- HAL API Root → Radio & PHY Control: includes
- HAL API Root → AP & VAP Management: includes
- HAL API Root → Station & Scan: includes
- Capability Discovery → Radio & PHY Control: gates feature use
- Capability Discovery → AP & VAP Management: gates feature use
- Upper RDK Process → Radio & PHY Control: configures radios
- Radio & PHY Control → AP & VAP Management: then creates VAPs
- AP & VAP Management → Client Event Callbacks: registers AP events
- Station & Scan → Driver-Originated Events: receives scan and connection events
- Client Event Callbacks → Driver-Originated Events: receives client events
- HAL API Root → Vendor HAL Implementation: implemented by
- Vendor HAL Implementation → Linux Wi-Fi Stack & Driver: translates operations to
- Linux Wi-Fi Stack & Driver → Driver-Originated Events: originates
- HAL API Root → Emulation & Deprecated APIs: retains optional surfaces
- Autotools Build Metadata → HAL API Root: packages contract library
- Documentation Generator → HAL Specification: generates reference
- HAL Specification → HAL API Root: specifies behavior