Espressif WiFi Driver (esp-wifi-drv)

The Espressif WiFi driver is an 802.11 wireless network driver for the Linux kernel, supporting Espressif WiFi chips.

Driver Architecture

Espressif WiFi Driver Architecture:

  +---------------------------------+
  |              Linux              |
  |                                 |
  |    iw / wpa / hostapd / tools   |
  |                |                |
  |          (user space)           |
  |                | nl80211        |
  |  --------------+--------------  |
  |          (kernel space)         |
  |                | cfg80211_ops   |
  |                v                |
  |             mac80211            |
  +----------------+----------------+
                   |
                   | ieee80211_ops
                   v
  +---------------------------------+
  |            espwl_core           |
  +---------------------------------+
  |           TRANS Layer           |
  +---------------------------------+
  |       HIF (Host Interface)      |
  +---------------------------------+
  |      usb   |   sdio   |   pci   |
  +----------------+----------------+
                   |
                   | (USB/SDIO/PCIe)
                   v
               WiFi Chip

Project Structure

Core Modules

• core: Core driver module implementing main driver logic
• fw: Firmware management
• hw: Hardware abstraction layer
• trans: Transport layer
• mac: MAC layer implementation
• phy: Physical layer implementation
• wow: Wake-on-Wireless support
• sip: SIP related functionality

Interface Modules

• pci: PCIe interface support
• sdio: SDIO interface support
• usb: USB interface support

Debug and Test

• debug: Debug functionality
• debugfs: Debug filesystem interface
• testmode: Test mode support

Development

Install pre-commit and enable the Git hook so commits run the same checks as CI (clang-format --dry-run --Werror on tracked *.c / *.h, excluding espwl_test/include/libnl3/, plus light hygiene on C/H sources):

python3 -m pip install --user pre-commit
export PATH="$HOME/.local/bin:$PATH"
pre-commit install

Run once on the whole tree: pre-commit run --all-files. Requires clang-format on PATH (Ubuntu: sudo apt install clang-format).

Build System

This project provides two build methods controlled by the BUILD variable:

1. Cross-compilation Build (Default)

Used for cross-compilation scenarios, requires specifying the kernel source path. This is the default build mode (BUILD=cross).

Prerequisites

• Compiled Linux kernel source (requires vmlinux or Module.symvers)
• Cross-compilation toolchain (default: aarch64-linux-gnu-)

Usage

# Basic build (PCI enabled by default, SDIO and USB disabled)
# BUILD=cross is the default, so it can be omitted
make KSRC=/path/to/kernel/source

# Specify architecture and cross-compilation toolchain
make KSRC=/path/to/kernel/source ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-

# Enable specific interfaces
make KSRC=/path/to/kernel/source PCI=y SDIO=n USB=n

# Explicitly specify cross build mode
make BUILD=cross KSRC=/path/to/kernel/source

# Clean build files
make clean

Configuration Options

• KSRC: Linux kernel source directory (required)
• ARCH: Target architecture (default: arm64)
• CROSS_COMPILE: Cross-compilation toolchain prefix (default: aarch64-linux-gnu-)
• PCI: Enable PCIe interface (default: y)
• SDIO: Enable SDIO interface (default: n)
• USB: Enable USB interface (default: n)
• E22_ECO0: Build the legacy E22 ECO0 PCIe driver path (default: n; ECO1 is default)

Build Features

• ESPWL_DEBUG: y (default) or n — only compile-time switch: whether to build in verbose logging (espwl_dbg, hex helpers, debugfs debug_level, module parameter debug=). The bitmask itself is not set at compile time.
• Debug filesystem: CONFIG_ESPWL_DEBUGFS (always enabled from Makefile; see debugfs directory under the driver’s debugfs root).
• Generic Netlink test mode: CONFIG_ESPWL_GENETLINK_TESTMODE
• Git version information: Automatically embeds Git commit hash

2. Native Build

Used for directly compiling and installing the driver on the target system.

Prerequisites

• Linux kernel headers (usually located at /lib/modules/$(uname -r)/build)
• Compiled kernel module symbol files

Usage

# Build driver modules
make BUILD=host

# Build and install driver
make BUILD=host install

# Uninstall driver
make BUILD=host uninstall

# Sign driver modules (for secure boot)
make BUILD=host sign

# Build, sign and install
make BUILD=host sign-install

# Clean build files
make BUILD=host clean

Installation Paths

• Module installation path: /lib/modules/$(uname -r)/kernel/drivers/net/wireless/espressif/
• Firmware path: /lib/firmware/espressif

Module Signing

If the system has secure boot enabled, you can use the sign target to sign driver modules:

1. First run will generate MOK (Machine Owner Key) key (MOK.priv and MOK.der)
2. Import the key using mokutil --import MOK.der
3. Reboot the system and complete MOK enrollment
4. Afterward, you can use the generated key to sign modules
5. If MOK.der already exists, key creation will be skipped

Quick Start

Manual Build Examples

# Cross-compilation example
make KSRC=/home/user/linux ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-

# Native build example
make BUILD=host
sudo make BUILD=host install

Loading and Unloading Driver

Loading Driver Modules

# Load mac80211 etc.
sudo modprobe mac80211

# Load core module
sudo insmod espwl_core

# Load interface module (choose based on interface used)
sudo modprobe espwl_pci    # PCIe interface

Unloading Driver Modules

# Unload interface modules
sudo modprobe -r espwl_pci
# Unload core module
sudo modprobe -r espwl_core

Debug Features

Debug Filesystem

The driver supports debugging through debugfs:

# Mount debugfs (if not mounted)
sudo mount -t debugfs none /sys/kernel/debug

# Access driver debug information
ls /sys/kernel/debug/espwl/

Debug Options

• Compile time: make ESPWL_DEBUG=n strips espwl_dbg and related debug code. Default build (ESPWL_DEBUG=y) includes log support; initial mask is 0 until you change it at runtime.
• Runtime (log level / mask): module parameter debug=0x<hex> on insmod/modprobe, or read/write debug_level under the driver’s debugfs directory (same bitmask; see that file for bit names). Do not use the Makefile for the mask.

Licensing

Kernel driver sources in this repository are distributed under GNU General Public License v2.0 or the 3-Clause BSD License, at your option (GPL-2.0 OR BSD-3-Clause; see SPDX tags in individual source files). Built modules use MODULE_LICENSE("Dual BSD/GPL"), consistent with common Linux dual-licensed drivers.

Full texts: LICENSE (overview), LICENSE.GPL-2.0, LICENSE.BSD-3-Clause.

Other directories (for example user-space test code or vendored headers) may carry different licenses; check the notices in those files.

Copyright

Copyright (C) 2026 Espressif Systems (Shanghai) CO LTD