Qualcomm Atheros QCA9377无线网卡Linux驱动适配指南

问题诊断：确认您的无线网卡需求

在开始安装流程前，请先通过以下命令确认您的无线网卡型号是否适用本方案：

lspci | grep -i ath

预期输出（类似以下内容）：

03:00.0 Network controller: Qualcomm Atheros QCA9377 802.11ac Wireless Network Adapter (rev 30)

如果输出中包含"QCA9377"且版本号为rev 30，则本文方案适用。若显示不同型号或版本，请查找对应型号的专用驱动方案。

版本兼容性矩阵

系统/内核版本	支持状态	推荐安装方式	注意事项
Ubuntu 18.04+	✅ 完全支持	基础适配版	需内核4.15+
Arch Linux	✅ 完全支持	PKGBUILD	滚动更新需重新编译
Fedora 30+	✅ 基本支持	基础适配版	可能需要禁用安全启动
内核4.4-rc2	⚠️ 有限支持	内核专用脚本	需应用专用补丁
CentOS 7	❌ 不推荐	-	内核版本过低

安装方案选择

根据您的系统环境和技术需求，选择以下任一安装路径：

A. 基础适配版（适合大多数用户）

1. 获取项目源码

git clone https://gitcode.com/gh_mirrors/qu/Qualcomm-Atheros-QCA9377-Wifi-Linux
cd Qualcomm-Atheros-QCA9377-Wifi-Linux

[!NOTE] 确保系统已安装git工具，如未安装可通过系统包管理器获取：

• Debian/Ubuntu: sudo apt install git
• Fedora/RHEL: sudo dnf install git
• Arch: sudo pacman -S git

2. 执行自动安装脚本

# 添加执行权限
chmod +x install.sh
# 运行安装脚本
sudo ./install.sh

该脚本将自动完成以下操作：

• 配置ath10k内核模块参数
• 复制固件文件到/lib/firmware/ath10k/目录
• 处理模块依赖关系

3. 系统验证与重启

# 验证固件文件是否正确安装
ls -la /lib/firmware/ath10k/QCA9377/hw1.0/

预期输出应包含：

• board.bin
• firmware-5.bin

确认文件存在后重启系统：

sudo reboot

B. 定制优化版（适合高级用户）

1. Arch Linux专用方案

# 构建并安装软件包
makepkg -i

[!TIP] 使用PKGBUILD方式安装可获得更好的系统集成度，自动处理依赖关系和升级路径。

2. 内核4.4-rc2专用方案

# 为特殊内核版本应用补丁并安装
chmod +x install_for_kernel_4.4-rc2.sh
sudo ./install_for_kernel_4.4-rc2.sh

3. 手动配置高级选项

# 创建模块配置文件
sudo tee /etc/modprobe.d/ath10k_core.conf <<EOF
options ath10k_core skip_otp=y
options ath10k_core debug_mask=0x100
EOF

# 更新initramfs
sudo update-initramfs -u

功能验证测试

系统重启后，通过以下步骤确认驱动工作状态：

1. 内核模块检查

lsmod | grep ath10k

预期输出应包含：

ath10k_pci               49152  0
ath10k_core             311296  1 ath10k_pci
ath                    36864  1 ath10k_core

2. 无线接口状态

iw dev

预期输出应显示类似以下内容的无线接口（通常为wlan0或wlp3s0）：

phy#0
    Interface wlp3s0
        ifindex 3
        wdev 0x1
        addr aa:bb:cc:dd:ee:ff
        type managed
        channel 36 (5180 MHz), width: 80 MHz, center1: 5210 MHz
        txpower 20.00 dBm

3. 连接测试

# 扫描附近无线网络
sudo iw dev wlp3s0 scan | grep SSID
# 连接到指定网络（需安装iwconfig或nmcli）
nmcli device wifi connect "YOUR_SSID" password "YOUR_PASSWORD"

故障排查：常见问题解决

问题1：驱动安装后无线接口未出现

原因：固件文件未正确复制或内核模块未加载

解决方案：

# 检查固件文件权限
sudo chmod -R 644 /lib/firmware/ath10k/
# 手动加载模块
sudo modprobe ath10k_pci
# 查看模块加载日志
dmesg | grep ath10k

问题2：无线网络连接不稳定或速度慢

原因：电源管理设置或信道干扰

解决方案：

# 禁用无线网卡电源管理
sudo iwconfig wlp3s0 power off
# 或在 NetworkManager 中永久禁用
sudo tee /etc/NetworkManager/conf.d/wifi-powersave.conf <<EOF
[connection]
wifi.powersave = 2
EOF

问题3：系统启动后驱动无法自动加载

原因：模块黑名单或依赖问题

解决方案：

# 检查是否存在黑名单
grep ath10k /etc/modprobe.d/*
# 如存在，注释掉blacklist相关行
# 更新initramfs
sudo update-initramfs -u

[!WARNING] 该项目已标记为废弃状态，不再提供官方更新和维护。对于新内核版本，可能需要手动适配或考虑替代方案。

性能优化与调优

1. 高级模块参数配置

# 创建优化配置文件
sudo tee /etc/modprobe.d/ath10k_optimize.conf <<EOF
options ath10k_core rts_threshold=2347
options ath10k_core tx_amsdu_size=0
options ath10k_core enable_amsdu=1
EOF

2. 监控无线连接质量

# 安装无线监控工具
sudo apt install wavemon  # Debian/Ubuntu
# 或
sudo dnf install wavemon  # Fedora/RHEL

# 运行监控工具
wavemon

社区资源与替代方案

虽然项目官方不再维护，但以下社区资源可能对解决特定问题有帮助：

• Linux Wireless邮件列表：提供内核无线驱动相关讨论
• Ubuntu Launchpad Bug跟踪：可搜索QCA9377相关问题报告
• Arch Linux AUR：社区维护的更新版本和补丁
• 替代驱动方案：考虑linux-firmware包中的更新固件

项目文件结构说明

了解以下关键文件位置有助于手动排查和维护：

Qualcomm-Atheros-QCA9377-Wifi-Linux/
├── firmware-only/          # 固件文件目录
│   └── QCA9377/hw1.0/      # 硬件特定固件
│       ├── board.bin       # 板级配置文件
│       └── firmware-5.bin  # 主固件文件
├── install.sh              # 通用安装脚本
├── PKGBUILD                # Arch Linux包定义
└── ath10k.conf             # 模块配置示例

通过本文档提供的步骤，您应该能够在支持的Linux系统上成功安装和配置QCA9377无线网卡驱动。对于遇到的特定问题，建议结合社区资源和系统日志进行深入排查。