MediaTek MT7902 Linux Wi-Fi driver

This repository packages the upstream mt76 MT7902 implementation as a focused out-of-tree module build. It supports the PCI device 14c3:7902 through the mt7921e driver family.

The earlier standalone PCI experiment has been removed. MT7902 support belongs inside mt76 because it needs the existing MT792x firmware, DMA, MCU, mac80211, and power-management infrastructure.

Status

The source includes the MT7902 series merged by the mt76 maintainers in February 2026:

• MT7902 PCIe device matching;
• MT7902 firmware and ROM-patch selection;
• chip detection and Connac2 behavior;
• MT7902 MCU initialization;
• the MT7902 DMA queue layout and ring sizes;
• WFDMA prefetch configuration;
• interrupt-map handling; and
• required firmware-download and PSE synchronization fixes.

Runtime power management is intentionally disabled for MT7902 by upstream. Normal mac80211 operation is expected to work, but suspend/runtime-PM support should not be assumed.

The vendored source is pinned to upstream openwrt/mt76 commit 66067d203bd04b703b55341bbf986ead5db05653. See mt76/UPSTREAM.md for provenance and the included patch series.

Requirements

• Linux with PCI, cfg80211, and mac80211 enabled
• Headers for the running kernel
• A C compiler and kernel build tools

On Debian or Ubuntu, install the usual build prerequisites with:

sudo apt install build-essential linux-headers-$(uname -r)

Build

make

The build produces this dependency set:

mt76/mt76.ko
mt76/mt76-connac-lib.ko
mt76/mt792x-lib.ko
mt76/mt7921/mt7921-common.ko
mt76/mt7921/mt7921e.ko

The wrapper deliberately builds only the PCIe MT7921/MT7902 path, even when the host kernel configuration enables other mt76 chipsets.

To use a different prepared kernel tree:

make KERNELDIR=/path/to/kernel/build

Verify the bundled firmware checksums:

make firmware-verify

The two firmware files come from official linux-firmware commit edc18bd4dc29a3bfa07f30b9715a94b0926a2014 and retain MediaTek's redistributable firmware license. See firmware/README.md.

Install

Installing these modules replaces the running kernel's complete MT7921/MT7922 module dependency chain, not just the final mt7921e module. Rebuild and reinstall after every kernel update.

First check the hardware and currently bound driver:

lspci -nnk -d 14c3:7902

Install the modules under the kernel's updates/mt7902 directory:

sudo make install
sudo depmod -a

This also installs the two Wi-Fi firmware files under /lib/firmware/mediatek. It does not install Bluetooth firmware or modify the Bluetooth driver.

If Secure Boot is enabled, the modules must be signed with a trusted key before they can be loaded. Follow the module-signing procedure provided by your distribution.

Rebooting is the safest way to replace an already loaded wireless stack. After reboot, verify:

lspci -nnk -d 14c3:7902
sudo dmesg | grep -Ei 'mt7921|mt7902|firmware'
iw dev

Kernel driver in use should be mt7921e, and iw dev should show the created wireless interface.

Test without installing

Only do this when no mt76 wireless device is in use. Removing these modules disconnects every device using this dependency chain.

sudo modprobe -r mt7921e mt7921_common mt792x_lib mt76_connac_lib mt76
sudo insmod mt76/mt76.ko
sudo insmod mt76/mt76-connac-lib.ko
sudo insmod mt76/mt792x-lib.ko
sudo insmod mt76/mt7921/mt7921-common.ko
sudo insmod mt76/mt7921/mt7921e.ko

Unload the test modules in reverse order:

sudo rmmod mt7921e mt7921_common mt792x_lib mt76_connac_lib mt76

Troubleshooting

If probing reports missing firmware, confirm the exact filenames and run:

make firmware-check

If module loading reports invalid module format, rebuild against the running kernel:

make clean
make
modinfo mt76/mt7921/mt7921e.ko | grep vermagic
uname -r

If the in-tree module loads instead of this build, inspect the selected module:

modinfo -n mt7921e

The expected installed path contains updates/mt7902.

To remove the installed override, delete that directory for the affected kernel, regenerate module dependencies, and reboot:

sudo rm -r -- /lib/modules/$(uname -r)/updates/mt7902
sudo depmod -a
sudo reboot

Updating the driver

Do not copy individual MT7902 conditionals onto an arbitrary older mt7921 driver. The support depends on the full ordered series and its surrounding mt76 state. Updates should be made by importing a reviewed upstream mt76 revision, recording its commit in mt76/UPSTREAM.md, and rebuilding all five modules together.

References

• Canonical mt76 repository
• Linux PCI driver guide
• Linux Wireless MediaTek/mt76 documentation
• Linux firmware repository

Licenses

The wrapper documentation and repository-level material are GPL-2.0. Vendored mt76 sources retain their upstream SPDX identifiers and license; see mt76/LICENSE. The firmware remains governed by firmware/LICENCE.mediatek.