Skip to content

README.md

Latest commit

 

History

History
214 lines (169 loc) · 8.64 KB

README.md

File metadata and controls

214 lines (169 loc) · 8.64 KB
Raw

mt76 Out-of-Tree WiFi Driver Build Infrastructure

Build, install, and manage MediaTek mt76 WiFi drivers as out-of-tree kernel modules. Supports DKMS, non-DKMS, Secure Boot, and kernels 6.12 through 7.2.

Based on openwrt/mt76, adapted for standalone out-of-tree building by the morrownr community.

For companies, organizations or individuals seeking an engineer to do professional contract work:

Contract work: Linux wireless drivers. Lab testing, patches, and ongoing support.
lucid_duck@justthetip.ca
https://github.com/Lucid-Duck

Quick Start

# Install
git clone https://github.com/morrownr/mt76.git
cd mt76
sudo sh install-driver.sh

# Check status (no root needed)
./check-driver.sh

# Edit module parameters (optional)
sudo ./edit-parameters.sh

# Update
git pull
sudo sh install-driver.sh

# Uninstall
sudo sh uninstall-driver.sh

Supported Chipset Families

Family Chips Bus Modules WiFi Generation
MT76x0 MT7610, MT7630, MT7650 USB, PCIe mt76x0u, mt76x0e WiFi 5 (AC)
MT76x2 MT7612, MT7662 USB, PCIe mt76x2u, mt76x2e WiFi 5 (AC)
MT7615 MT7615, MT7663 USB, PCIe, SDIO mt7615e, mt7663u, mt7663s WiFi 5 (AC)
MT7921 MT7920, MT7921, MT7922, MT7902 USB, PCIe, SDIO mt7921e, mt7921u, mt7921s WiFi 6E (AXE)
MT7925 MT7925, MT7927 USB, PCIe mt7925e, mt7925u WiFi 7 (BE)

Inactive Families

Family Status
MT7603 Source retained but not built by default. Old WiFi 4 chip, no user reports on this repo. Users with MT7603 hardware should rely on the in-kernel mt7603e driver. Reactivation is a one-line Makefile change if someone needs it.
MT7915 Source retained but not built by default. PCIe-only AP/router silicon (MT7915, MT7906, MT7916). Users running this hardware are typically on routers with vendor BSPs; the in-kernel mt7915e driver covers desktop/laptop use.
MT7996 Source retained but not built by default. PCIe-only WiFi 7 AP/router silicon (MT7990, MT7991, MT7992, MT7996). Same router/BSP audience as MT7915; the in-kernel mt7996e driver covers desktop/laptop use.

Supported USB Adapters

For specific adapter recommendations, the Plug and Play List, and vendor selection guidance, see morrownr/USB-WiFi.

The drivers auto-bind to many vendor VID:PIDs per family; run lsusb after plugging in to see what was detected. Reference VID:PIDs by chip family:

Family Reference VID:PID WiFi Generation
MT76x0 148f:7610 WiFi 5 (AC)
MT76x2 0e8d:7612 WiFi 5 (AC)
MT7615 / MT7663 0e8d:7663 WiFi 5 (AC)
MT7921 0e8d:7961 WiFi 6E (AXE)
MT7925 0e8d:7925 WiFi 7 (BE)

Supported PCIe Devices

The drivers auto-bind to many vendor PCI IDs per family; run lspci -nn and look for MediaTek devices to see what was detected. Reference PCI IDs by chip family (vendor 14c3 unless noted):

Family PCI IDs
MT76x0 7610, 7630, 7650
MT76x2 7662, 7612, 7602
MT7615 7615, 7663, 7611
MT7921 7961, 7922, 0608, 0616, 7920, 7902 (also 0b48:7922)
MT7925 7925, 0717

Files

File Purpose
Makefile Kbuild out-of-tree Makefile for all 28 active modules across 7 chipset families
install-driver.sh Full install with progress display, prerequisite checks, build, verify
uninstall-driver.sh Clean removal of installed modules, DKMS entries, and config
check-driver.sh No-root diagnostic: loaded modules, hardware, link status, firmware, dmesg
edit-parameters.sh Open /etc/modprobe.d/mt76_git.conf in $EDITOR to tweak module parameters
default-editor.txt Editor used by edit-parameters.sh if $VISUAL and $EDITOR are unset (default: nano)
dkms.conf DKMS auto-rebuild on kernel updates, conditional PCI/SDIO support
mt76_git.conf modprobe options and blacklist for the in-kernel mt76 modules this repo replaces
compat-patches/ Source compatibility patches for older kernel API changes
mt7615/Makefile MT7615 family: common + PCIe + USB + SDIO (WiFi 5)
mt7915/Makefile MT7915 PCIe with coredump support (WiFi 6)
mt7921/Makefile MT7921 family: common + PCIe + USB + SDIO (WiFi 6E)
mt7925/Makefile MT7925 family: common + PCIe + USB (WiFi 7)
mt7996/Makefile MT7996 PCIe with NPU and coredump support (WiFi 7)
mt76x0/Makefile MT76x0 family: common + USB + PCIe (WiFi 5)
mt76x2/Makefile MT76x2 family: common + USB + PCIe (WiFi 5)

Module Map (28 active modules)

Core and transport:
  mt76_git              Core driver
  mt76_usb_git          USB transport
  mt76_sdio_git         SDIO transport (requires CONFIG_MMC)

Shared libraries:
  mt76x02_lib_git       Legacy shared (MT76x0/x2)
  mt76x02_usb_git       Legacy USB shared
  mt76_connac_lib_git   CONNAC shared
  mt792x_lib_git        MT792x shared
  mt792x_usb_git        MT792x USB shared

Chipset families:
  mt7615_common_git     MT7615 shared
  mt7615e_git           MT7615 PCIe
  mt7663_usb_sdio_common_git  MT7663 USB/SDIO shared
  mt7663u_git           MT7663 USB
  mt7663s_git           MT7663 SDIO (requires CONFIG_MMC)
  mt7915e_git           MT7915 PCIe
  mt7921_common_git     MT7921 shared
  mt7921e_git           MT7921 PCIe
  mt7921s_git           MT7921 SDIO
  mt7921u_git           MT7921 USB
  mt7925_common_git     MT7925 shared
  mt7925e_git           MT7925 PCIe
  mt7925u_git           MT7925 USB
  mt7996e_git           MT7996 PCIe
  mt76x0_common_git     MT76x0 shared
  mt76x0u_git           MT76x0 USB
  mt76x0e_git           MT76x0 PCIe
  mt76x2_common_git     MT76x2 shared
  mt76x2u_git           MT76x2 USB
  mt76x2e_git           MT76x2 PCIe

How It Works

All out-of-tree modules are built with a _git suffix (e.g., mt76_git.ko instead of mt76.ko). This allows them to coexist with the in-kernel mt76 modules. The blacklist in mt76_git.conf prevents the in-kernel versions from loading, so the out-of-tree versions handle all hardware.

This means:

  • Safe to install -- your in-kernel modules are untouched
  • Safe to uninstall -- blacklist removal restores in-kernel behavior
  • Safe to update -- just git pull && sudo sh install-driver.sh

Prerequisites

The installer checks for all of these automatically:

  • gcc -- C compiler
  • make -- build tool
  • bc -- used by kernel build system
  • iw -- wireless configuration tool
  • Kernel header files for your running kernel
  • Optional: dkms for automatic rebuilds on kernel updates

Kernels built with clang (CachyOS, Chimera) need their modules built with clang too. The Makefile detects this from the kernel's config and switches to LLVM=1 on its own, for make, install-driver.sh and dkms alike. Install clang, lld and llvm first; the package names are the same on Arch, Debian and Fedora. The tell that you are on such a kernel and the tools are missing is gcc failing with unrecognized command-line option '-mstack-alignment=8'.

Reporting Issues

Run check-driver.sh and include the full output in your bug report:

./check-driver.sh 2>&1 | tee mt76-diag.txt

This captures loaded modules (in-kernel vs out-of-tree), hardware detection, link status with signal strength, firmware presence, blacklist health, Secure Boot status, and recent kernel messages. Everything a maintainer needs in one command.

Kernel Compatibility

Supported range: 6.12 through 7.x (enforced by BUILD_EXCLUSIVE_KERNEL in dkms.conf).

Compatibility patches in compat-patches/:

  • linux/unaligned.h vs asm/unaligned.h header rename (kernel 6.12)
  • hrtimer_setup() replacing hrtimer_init() (kernel 6.12/6.19)
  • OpenWrt-specific EMLSR API isolation

Design Decisions

  • _git suffix: Follows the morrownr/rtw89 convention. Modules install to extra/ or updates/ directories which take priority over kernel/ in depmod search order.
  • PCI conditional: PCIe-only modules gated on CONFIG_PCI
  • SDIO conditional: SDIO modules gated on CONFIG_MMC
  • USB unconditional: USB modules always built
  • Git commit in modules: -DGIT_COMMIT baked in at build time for traceability
  • Module compression: Install target auto-matches distro compression (zstd/xz/gzip)
  • No SoC code: MT7622_WMAC, MT798X_WMAC, NPU configs left as no-ops (never defined on desktop/laptop kernels, code compiles out)

License

This program is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation.