mt7925

Imported from zbowling/mt7925 (AGENTS.md). Install upstream with npx skills add zbowling/mt7925. Copyright stays with the author.

Instructions for AI Agents

This document helps AI agents effectively work with this repository. It provides critical requirements, workflow guidelines, and a documentation index for finding relevant information.

Documentation Index (Progressive Disclosure)

The docs/ folder contains comprehensive documentation. Use this index to find the right file for your task.

Quick Reference: What Do You Need?

Documentation by Category

Architecture & Code Understanding

Debugging & Diagnostics

Protocols & Features

Chipset & Version Specifics

Known Issues & Workarounds

Critical Requirements

Git Workflow (IMPORTANT)

DO NOT push directly to main branch. The repository has branch protection rules that block direct pushes.

1. Always use feature branches

   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/your-bug-fix
   # or
   git checkout -b docs/your-documentation-change

2. Push to feature branch and create a PR

   git push -u origin feature/your-feature-name
   gh pr create --fill

3. Branch naming conventions

   • feature/ - New features or enhancements
   • fix/ - Bug fixes
   • docs/ - Documentation changes
   • chore/ - Maintenance tasks (version bumps, CI updates)

4. Never force push to main - This will be rejected by branch protection

Patch Quality

1. Patches MUST apply cleanly

   • No hunk errors, no fuzz, no offset warnings
   • Each patch should apply with git apply without any modifications
   • Always validate with ./scripts/validate-patches.sh before committing

2. Maintain individual patches, NOT squashed

   • NEVER squash patches into a single mega-patch
   • Each fix should be its own numbered patch file (0001-, 0002-, etc.)
   • This preserves the history of what was fixed and why

3. Patches come from git branches

   • Source of truth: zbowling/linux-wifi fork
   • Patches in kernels/ are exported using git format-patch
   • Never hand-edit patches - edit the source branch and re-export

4. Validate before committing in this repo

   • Run ./scripts/validate-patches.sh to verify patches apply
   • CI workflow tests patch application and builds

Multi-Kernel Support

When porting patches to a new kernel version, see PATCH_DIFFERENCES.md.

Repository Structure

mt7925/
├── kernels/
│   ├── 6.17/           # Patches for 6.17.x kernels
│   ├── 6.18/           # Patches for 6.18.x kernels (primary)
│   ├── 6.19-rc/        # Patches for 6.19-rcX kernels
│   └── nbd168/         # Upstream staging patches
├── dkms/               # DKMS package with patched source
│   └── src/            # Full mt76 driver source (patched)
├── scripts/
│   └── validate-patches.sh
├── docs/               # Documentation (see index above)
└── .github/
    └── workflows/      # CI validation and build testing

Workflow for Adding New Patches

1. Work in linux-wifi fork

   cd <path-to-linux-wifi-fork>
   git checkout mt7925-fixes-v6.18.5
   # Make changes
   git commit -m "wifi: mt76: mt7925: <description>"

2. Export patches

   git format-patch v6.18.5..mt7925-fixes-v6.18.5 -o <path-to-this-repo>/kernels/6.18

3. Validate (before committing in this repo)

   ./scripts/validate-patches.sh 6.18

4. Port to other versions (see PATCH_DIFFERENCES.md)

5. Commit and push in this repo

Context: Why These Patches Exist

The MT7925 is a WiFi 7 (802.11be) chip from MediaTek. The upstream driver has several issues:

1. NULL pointer dereferences - MLO code paths don't check for NULL links
2. Race conditions - Missing mutex protection around ieee80211_iterate_* calls
3. MCU timeouts - Commands can flood MCU during rapid state changes
4. Deadlocks - Incorrect mutex nesting, work queue interactions

For detailed analysis, see:

• MLO.md - NULL pointer issues
• LOCKING.md - Deadlock scenarios
• MCU_PROTOCOL.md - Timeout handling

DKMS Package

The dkms/ directory contains a complete patched mt76 driver that can be installed via DKMS:

cd dkms
sudo dkms install .

The source in dkms/src/ has all patches pre-applied and may contain experimental fixes not yet in the patch files.

DKMS Package Structure

dkms/
├── src/                        # Full mt76 driver source (patched)
├── dkms.conf                   # DKMS configuration (version, modules)
├── install.sh                  # Manual install script
├── uninstall.sh                # Manual uninstall script
├── README.md                   # User documentation
├── DIFFERENCES.md              # Patch documentation
├── PKGBUILD                    # Arch Linux AUR package
├── mt76-mt7925-dkms.install    # Arch Linux DKMS hooks
├── mt76-mt7925-dkms.spec       # RPM spec file (Fedora/RHEL)
└── debian/                     # Debian/Ubuntu packaging
    ├── control                 # Package metadata (includes debhelper-compat)
    ├── rules                   # Build rules (auto-extracts version from changelog)
    ├── changelog               # Version history
    ├── copyright               # License info
    └── source/format           # Source format (3.0 quilt)

Version Update Workflow

Use tbump to automatically update version numbers and changelogs:

# Simple version bump (interactive mode, recommended)
uvx tbump 1.5.0

# Non-interactive mode (for scripts)
uvx tbump 1.5.0 --non-interactive

# Only update files, no git operations
uvx tbump --only-patch 1.5.0

What tbump does automatically:

1. Updates version strings in 12+ files (see table below)
2. Runs scripts/update-changelogs.sh to update:
   • dkms/debian/changelog (Debian format with RFC 2822 date)
   • dkms/mt76-mt7925-dkms.spec %changelog section
   • CHANGELOG.md (adds new version section and comparison link)
3. Creates a git commit with message chore: bump version to X.Y.Z
4. Creates a git tag vX.Y.Z
5. Does NOT push (you create a PR manually)

After tbump, you should:

1. Review the auto-generated changelog entries
2. Edit them to include meaningful release notes
3. Amend the commit if needed: git add -A && git commit --amend

tbump Configuration (tbump.toml)

Hooks:

Files automatically updated:

Changelog Script (scripts/update-changelogs.sh)

The before_commit hook runs this script to update special changelog formats:

./scripts/update-changelogs.sh <new_version> <prev_version> [message]

What it updates:

Full Release Workflow

# 1. Create feature branch
git checkout -b chore/bump-version-1.5.0

# 2. Run tbump (updates files + changelogs, commits, creates tag)
uvx tbump 1.5.0

# 3. Review and edit changelog entries
#    - Edit dkms/debian/changelog with actual release notes
#    - Edit CHANGELOG.md with detailed changes
#    - Amend commit if needed:
git add -A && git commit --amend --no-edit

# 4. Delete local tag (tbump created it, but we tag after merge)
git tag -d v1.5.0

# 5. Push branch and create PR
git push -u origin chore/bump-version-1.5.0
gh pr create --title "chore: bump version to 1.5.0"

# 6. After PR is merged, tag from main
git checkout main && git pull
git tag -a v1.5.0 -m "Release v1.5.0"
git push origin v1.5.0

tbump Reference

See tbump documentation for more options:

• {new_version} - Placeholder for new version in hooks
• {current_version} - Placeholder for current version in search patterns
• {major}, {minor}, {patch} - Individual version components
• --non-interactive - Skip confirmation prompts
• --only-patch - Update files only, no git operations

CI/CD Release Workflow

The .github/workflows/release.yml workflow automatically builds and publishes packages:

Trigger: Push a tag matching v* (e.g., v1.4.0)

Build Steps:

1. Creates source tarball (mt76-mt7925-dkms-X.Y.Z.tar.gz)
2. Builds DEB package (Debian/Ubuntu)
3. Builds RPM package (Fedora/RHEL)
4. Builds Arch package (.pkg.tar.zst)

Release Steps:

1. Creates GitHub Release with all package assets
2. Publishes PKGBUILD to AUR

GitHub Secrets for AUR Publishing

The following secrets must be configured in the repository for AUR publishing:

Module List

The DKMS package builds 12 kernel modules:

MT7921 modules are included because mt792x-lib is shared - building only MT7925 would cause ABI mismatch for MT7921 users.

Contact

Maintained by Zac Bowling. Patches have been submitted to LKML but MediaTek's response time is slow.