Linux MT7921/MT7925 WiFi Driver Fixes¶
The MediaTek MT7921 and MT7925 WiFi drivers in stock Linux 6.8–6.19 kernels have several bugs that can lead to kernel panics (NULL pointer dereferences), race conditions, mutex deadlocks, and other issues that can hang systems using these WiFi cards.
These issues are exacerbated in certain WiFi environments, especially when:
- using multi-AP setups with WiFi 6E/7 (or fast roaming enabled)
- using 6 GHz frequencies with APs that allow higher transmit power in certain regulatory domains
- using WiFi 7 environments with MLO enabled
About this Project¶
This project exists to provide fixes for the issues I can solve in the kernel, and to make those fixes as easy to install as possible while I continue working with MediaTek to get these patches upstream so future kernels no longer have these bugs.
I can fix issues in the Linux kernel driver, but not the firmware running on the WiFi chip. My original goal was to prevent kernel driver bugs from crashing my machine and causing me to lose work. I can’t fix bugs that exist on the device itself or in its firmware.
The MediaTek WiFi firmware is an encrypted black box. While some adventurous folks have managed to crack and extract keys from MediaTek firmware, that is not my goal. What I have done is fix kernel-side bugs and improve recovery handling so that when firmware crashes due to its own bugs, the driver can recover quickly—and to avoid patterns I’ve noticed can aggravate firmware issues from the kernel side.
My end goal is for this project to stop being necessary once these fixes land upstream. But because the upstreaming process can take time, I’m publishing these packages so people can work around the issues now and use their machines today—especially since these bugs can cripple brand-new laptops from vendors like Framework, Lenovo, Dell, ASUS, and Acer, sometimes crashing every few minutes.
In the process of creating these patches, I’ve also documented what I’ve learned about these drivers and the hardware, different debugging methods, crashes I’ve reproduced (and reports others have sent), and a stress-testing suite that can reproduce the bugs and demonstrate that these patches fix them.
Getting Started¶
-
Quick Install
Quickly install the patched driver via your package manager or install script.
-
Known Issues
Common issues, known crashes, and some of their workarounds (either implemented in this driver package or how to avoid otherwise like disabling band stearing, fast roaming, 6ghz, MLO, etc)
-
Patches
6 stability patches for kernel 6.17+
-
Architecture
Deep dive into driver internals
-
Contributing
How to report issues, test patches, and submit fixes
Status¶
| Component | Version | Status |
|---|---|---|
| Patches | Patchset v7 (7 patches) | Stable |
| DKMS Package | v1.5.0 | Released |
| Upstreaming work | Still in progress | Pending review |
Supported Hardware¶
- MT7925 - WiFi 7 (802.11be) PCIe card
- MT7921 - WiFi 6E (802.11ax) PCIe/USB/SDIO
Supported Kernels¶
| Kernel | Status | Notes |
|---|---|---|
| 6.17.x | Supported | Minimum version for DKMS |
| 6.18.x | Supported | Recommended |
| 6.19-rc | Supported | Release candidate |
| < 6.17 | Not supported | Use kernel patches instead. Some additional patches may be needed. |