高通11.0 AP驱动编程指南：Split MAC架构与调试实战

简介：《高通WiFi驱动编程指南》是一份面向无线网络开发者的技术参考文档，聚焦高通WLAN驱动在接入点（AP）设备上的编程与调试，适合具备一定嵌入式与网络基础、需要深入理解驱动结构的中高级开发者。资源包内为1个PDF文件，压缩包约87.21MB，内容涵盖驱动安装配置、Split MAC分层设计、射频与电源管理、MU-MIMO性能优化及版本更新说明等模块，并附有QCA_Networking系列版本的修订记录与命令输出示例。文档还涉及驱动与操作系统、网卡之间的协作机制，以及故障排查与诊断工具的使用思路，可帮助读者对照实际项目梳理驱动架构、定位性能瓶颈。目前已有2947人学习下载，适合作为高通WiFi驱动开发与维护的案头参考资料。

1. 拿到一份 80-YA728 编程指南，先别急着翻目录

做接入点固件的人大概都有过这种体验：板子跑起来了，hostapd 也拉起了 SSID，客户端能连上，但一到多用户并发、信道切换、频谱扫描这些场景就开始玄学——吞吐忽高忽低，日志里全是看不懂的固件事件。这时候你需要的不是再调一遍 hostapd.conf，而是一份能告诉你驱动内部怎么组织、哪些参数在哪个层面生效的编程指南。这份《Wireless LAN Driver Version 11.0 for Access Point Programming Guide》（文档号 80-YA728-6）就是干这个的：它面向高通 11.0 版 AP 驱动，覆盖从 Split MAC 架构、802.11ax 调度、ATF 公平调度，到频谱扫描、cfg80211 适配、诊断工具链的一整套内容。适合已经能把 AP 跑起来、想往下钻一层的中高级网络固件工程师，也适合刚接手 IPQ807x 平台、需要快速建立驱动全貌的新手。它不教你写第一行驱动，但能让你在遇到“为什么这个参数改了没反应”时，知道该去哪个子系统找答案。

2. 先立住架构：Split MAC 与 11.0 驱动的分层逻辑

2.1 Split MAC 到底把什么拆开了

很多人第一次看到 Split MAC 会以为是“MAC 层拆成两半跑在两个 CPU 上”，这个理解只对了一半。在这份指南的语境里，Split MAC 描述的是把 MAC 功能划分成主机侧（host）和固件/目标侧（target/firmware）两部分：时间敏感、需要紧耦合射频的操作下沉到固件，比如帧的聚合、块确认、速率自适应、MU-MIMO/OFDMA 的调度决策；而配置管理、VAP 生命周期、与上层网络栈的对接留在主机驱动。这样拆的直接收益是主机 CPU 不用为每个 PPDU 做决策，代价是你改一个参数时得先判断它落在哪一侧——落在固件侧的参数，主机侧改了配置但没走对下发通道，就是“改了没反应”的典型来源。

指南里 2.13 节专门讲 Split MAC，配合 2.15 节的 802.11ax Tx 数据路径和 2.16 节的 MU-MIMO/OFDMA Tx 调度算法一起看，才能拼出完整图景：数据从协议栈下来，经过主机驱动的队列管理，交给固件的调度器，调度器再根据 ATF（Airtime Fairness）策略和 MU 分组决定谁先发、发多少。你在主机侧看到的队列深度、聚合参数，最终都要和固件侧的调度能力对齐，否则就是两套逻辑各说各话。

2.2 组件化：为什么 11.0 的代码结构和你印象里不一样

从修订记录能看出一个明显趋势：从 2018 年 3 月的 J 版开始，大量“componentization”条目涌现——Green AP 组件化、QDF CB 组件化、FTM 组件化、Target-to-host 初始化组件化、Spectral 组件化、Extender AP 组件化。这不是文档在凑字数，而是驱动架构在往“可裁剪、可复用”方向走。对一线工程师的实际意义是：你拿到的驱动源码不再是铁板一块，很多功能可以通过编译开关和组件边界决定要不要编进去。移植到资源受限的板子时，先看哪些组件是必需的，比盲目全编再删要省事得多。

一个常见的落地动作是：在编译配置里确认 FTM（Factory Test Mode）组件是否启用。指南 22.12 节讲 FTM daemon，22.13 节讲 IPQ807x 上的 QDART，这两块是产测和射频校准的入口。如果你只做功能验证不做产测，可以先把 FTM 相关组件裁掉减小镜像；但一旦要做校准，就得把 daemon 和 QDART 链路一起拉起来，缺一个都跑不通。

2.3 用版本号反查特性可用性

这份文档的修订历史本身就是一张特性时间线。QCA_Networking_2017.SPF.7.0 引入了 Split MAC、8 链操作、第三代频谱扫描；SPF.8.0 加了 Direct DMA 框架、WPA3 相关（SAE、OWE、Suite B）、FILS；2019.SPF.9.0 又补了接收流导向（RFS）、每射频重初始化、5.9 GHz 频段支持。实操上，当你拿到一块板子和一版驱动，第一件事不是读全部章节，而是拿uname -r和驱动版本号去对修订记录，确认你手上的版本到底包含哪些特性。比如你要用 WPA3 的 OWE，就得确认驱动至少到 2018 年 7 月的 N 版；要做 5.9 GHz，得看 P 版之后。这个动作能省掉大量“照着文档配了但没生效”的排查时间。

# 查看当前内核与驱动版本，和文档修订记录对齐 uname -a # 驱动版本通常可从模块信息或启动日志中获取 dmesg | grep -i "wlan\|ath\|qca" | head -40 # 若驱动以模块形式加载，查看模块版本 modinfo qca_ol 2>/dev/null | grep -i version

上面几条命令的目的不是“查版本”这么简单，而是建立“板子实际跑的版本”和“文档描述的版本”之间的映射。dmesg里驱动初始化打印的版本串往往比modinfo更准，因为它是运行时真实加载的那一份。参数上没什么可调的，关键是养成先对齐版本再读章节的习惯——文档里很多章节标题带“Support for”，意思是“从这个版本起支持”，不是“所有版本都这么干”。

3. 把配置落到命令行：VAP、信道与频谱扫描的实操路径

3.1 从 cfg80211 生成 hostapd 配置

指南 4.4.13 节讲“Generate hostapd configuration with cfg80211”，这是把驱动能力和上层配置打通的关键一环。传统做法是手写 hostapd.conf，参数靠经验拍；cfg80211 路径下，驱动的能力集（支持的频段、加密套件、HT/VHT/HE 能力）会通过 nl80211 暴露出来，hostapd 可以据此生成更贴合硬件的配置。实操上我一般先用iw phy把能力集 dump 出来，再对照生成配置，避免写了驱动不支持的组合。

# 查看无线 phy 的能力集，确认频段、加密与 HE 支持 iw phy | grep -A 30 "Supported bands" iw phy | grep -i "Supported Ciphers" -A 10 # 查看当前 VAP 与接口状态 iw dev # 用 hostapd 的调试模式验证配置是否被驱动接受 hostapd -dd /etc/hostapd/hostapd.conf 2>&1 | head -80

iw phy的输出是判断“这个参数能不能配”的第一手依据：如果能力集里没有某个加密套件，hostapd.conf 里写了也会在启动时被拒。hostapd -dd的调试输出会打印驱动返回的错误码，比看 syslog 更直接。参数层面，重点盯supported bands里的频段范围和HT/VHT/HE capabilities，这两块决定了你后面信道和带宽能开到什么程度。

3.2 手动创建与删除 VAP

5.14 节讲 cfg80211 下的手动 VAP 创建与删除，这在多 SSID、多 BSSID 场景里很实用。默认 hostapd 会自己管理 VAP，但做隔离测试或动态加 SSID 时，手动控制更灵活。常见做法是用iw创建接口，再让 hostapd 绑定到指定接口。

# 在指定 phy 上创建一个 AP 类型的 VAP iw phy phy0 interface add vap1 type __ap # 确认接口已创建 ip link show vap1 # 绑定 hostapd 到该接口启动（配置中 interface=vap1） hostapd -B /etc/hostapd/vap1.conf # 删除 VAP 前先停 hostapd，再删接口 killall hostapd iw dev vap1 del

这里的关键顺序是“先停服务再删接口”，反过来删接口会让 hostapd 残留状态，下次启动可能报接口不存在。type __ap里的双下划线是 cfg80211 的接口类型标识，写错成ap在某些版本上会被拒。参数上，phy0要换成你实际的 phy 编号，多射频平台（比如带第三射频的型号）上 phy 编号和射频的对应关系要看启动日志确认，别想当然。

3.3 频谱扫描：从 spectraltool 到结果解读

15 章是频谱分析的集中地，从第二代到第三代 Spectral Scan，再到spectraltool命令行工具和athssd演示应用。第三代扫描相比第二代在配置参数和输出格式上都有变化，15.3.2 节列了具体配置参数。落地时最容易翻车的是“扫描开了但拿不到数据”，原因通常是扫描没在正确的射频上使能，或者用户态工具和驱动的事件通道没对上。

# 使能指定射频的频谱扫描（具体节点名随平台而异，先确认 debugfs 路径） ls /sys/kernel/debug/ieee80211/phy0/ # 常见做法是向 spectral 相关节点写入使能标志 echo 1 > /sys/kernel/debug/ieee80211/phy0/ath10k/spectral_scan_ctl 2>/dev/null # 用 spectraltool 抓取并落盘 spectraltool -i wifi0 -s 30 -o /tmp/spectral.bin # 检查是否有数据写入 ls -l /tmp/spectral.bin

spectral_scan_ctl这类 debugfs 节点的路径在不同驱动分支上不完全一致，先ls确认再写，别照抄。spectraltool的-s是采样时长（秒），-o是输出文件；采样太短拿不到有统计意义的样本，太长又占空间，一般 30 秒起步。如果文件大小为 0，先查扫描是否真的使能、射频是否处于工作信道，再看用户态工具版本是否和驱动匹配——这两处是血泪经验里最高频的两个坑。

3.4 信道选择与 ACS 的边界

14 章讲信道管理，包括 EACS PLUS、智能信道管理、UMAC 自动信道选择，以及 14.20 节的云端信道切换。ACS 不是“打开就完事”，它的决策依赖扫描到的干扰信息和 regulatory 约束。9 章讲监管合规，包括 offload 到固件的监管规则和 HLOS 替换后保留监管设置。实操上，如果 ACS 选出来的信道和预期不符，先确认监管域设置是否正确——监管域错了，可用信道集合就错了，ACS 再聪明也只能在错误集合里挑。

# 查看当前监管域 iw reg get # 设置监管域（示例，按实际区域代码替换） iw reg set US # 触发一次 ACS 并观察选择结果（hostapd 配置中 acs=1） hostapd -dd /etc/hostapd/hostapd.conf 2>&1 | grep -i "acs\|channel"

监管域设置要注意：有些平台把监管规则 offload 到固件，主机侧iw reg set之后还要确认固件是否同步，否则会出现“主机认为可用、固件拒绝”的分裂状态。9.3 节专门讲 HLOS 替换后保留监管设置，做系统升级或多系统切换时这块要重点验证。

4. 诊断与统计：把“玄学”变成可观测数据

4.1 txrx_stats 与每 PPDU 统计

22 章是整份文档里最“干活”的一章。22.2.7 讲 Tx/Rx 统计，22.2.8 给了txrx_stats命令的样例输出，22.19 进一步细化到每 PPDU 的统计，包括 MU-MIMO 和 OFDMA 参数。这些统计是排查吞吐问题的核心依据：客户端速率上不去，先看每 PPDU 的 MCS、带宽、空间流数是否符合预期，再看 MU 分组有没有真的生效。

# 查询驱动统计（命令名随平台工具链而异，常见为 txrx_stats） txrx_stats wifi0 # 关注输出中的 per-PPDU 字段：MCS、NSS、BW、MU 标志 txrx_stats wifi0 | grep -i "mcs\|nss\|bw\|mu" # 查看每射频的 Tx/Rx 统计 txrx_stats wifi0 radio0

读这些统计要有基线意识：先在单客户端、干净信道下抓一份“正常态”数据，再在问题场景下抓一份对比。参数上重点看 NSS（空间流数）和 BW（带宽）是否达到配置上限，如果 NSS 一直低于预期，可能是天线链掩码配置问题（8.9 节讲不重连客户端修改 Tx 链掩码），也可能是客户端能力协商结果如此。MU 标志为 0 不一定是故障，要看是否有多个支持 MU 的客户端同时在线。

4.2 固件 assert 与配置恢复

3.12 节讲 IPQ807x 上固件 assert 后恢复 WLAN 配置，3.15 节讲固件 assert 时位翻转的早期检测。固件 assert 是 AP 现场最头疼的问题之一：设备看起来还在，但 Wi-Fi 没了，日志里只有一行 assert。恢复机制的价值在于 assert 后能自动重建 VAP 和关键配置，减少人工介入。落地时要确认恢复流程覆盖了你实际用到的配置项——如果某个自定义参数不在恢复列表里，assert 之后它就会丢。

# 查看固件 assert 相关日志 dmesg | grep -i "assert\|firmware crash\|target" # 确认恢复流程是否触发（日志中通常有 recovery 相关打印） dmesg | grep -i "recover\|restore" # 检查 assert 后 VAP 是否重建 iw dev

如果 assert 后 VAP 没恢复，先看恢复流程是否被编译进去，再看恢复的配置来源是持久化存储还是运行时快照。3.15 节的位翻转检测属于更底层的防护，它能在 assert 早期发现内存损坏迹象，对定位“为什么老是 assert”有帮助，但需要相应的调试配置打开。

4.3 数据包日志与 monitor 模式

22.20 节讲 Tx 数据包日志捕获，22.14 节讲 IPQ807x 上设置 monitor 模式，13.37 节讲 OL 模式下的 Tx 数据包捕获。这几块组合起来，能在不接外部抓包设备的情况下拿到空口侧的数据。monitor 模式的坑在于信道和带宽要跟目标 VAP 对齐，否则抓到的帧不完整；Tx 日志捕获的坑在于缓冲区大小，高吞吐场景下缓冲区太小会丢日志。

# 创建 monitor 接口 iw phy phy0 interface add mon0 type monitor ip link set mon0 up # 设置到目标信道（以 5180 MHz / 80 MHz 为例） iw dev mon0 set channel 36 80MHz # 用 tcpdump 抓空口帧 tcpdump -i mon0 -w /tmp/air.pcap

set channel的带宽参数要和被观测 VAP 一致，80 MHz 的 VAP 你用 20 MHz 去抓，只能看到部分子信道。抓完记得删 monitor 接口，长期挂着会占资源，某些平台上还影响正常射频调度。

5. 避坑与排查：五条来自现场的记录

5.1 改了聚合参数但吞吐没变

现象：按 11.9、11.10 节配置了每 VAP 的 AMPDU/AMSDU，吞吐纹丝不动。原因：聚合的实际生效点在固件侧调度，主机侧参数只是上限，固件会根据速率、重传和 MU 调度动态调整，单客户端低速率场景下聚合本来就不会拉满。解决：先用txrx_stats确认每 PPDU 的实际聚合度，再判断是参数没下发还是固件主动收敛；必要时用 11.7 节的自定义聚合与速率回退配置做对照实验。

5.2 频谱扫描文件为空

现象：spectraltool跑完输出文件 0 字节。原因：扫描未在目标射频使能，或用户态工具与驱动的扫描代际不匹配（第二代工具对第三代扫描）。解决：先确认 debugfs 下扫描控制节点已置位，再核对工具版本与 15.3 节描述的第三代参数是否一致；换用athssd演示应用做交叉验证。

5.3 WPA3 客户端连不上

现象：配置了 SAE 但客户端反复认证失败。原因：驱动版本早于 2018 年 7 月的 N 版，SAE/OWE/Suite B 尚未引入；或 hostapd 配置里加密套件与驱动能力集不匹配。解决：对齐驱动版本，用iw phy确认支持的加密套件，再按 5.15 至 5.17 节的配置要求逐项核对。

5.4 固件 assert 后 SSID 消失

现象：设备在线但 Wi-Fi 不可见，日志有 assert。原因：恢复流程未覆盖自定义 VAP 配置，或恢复组件未编译进镜像。解决：核对 3.12 节的恢复机制覆盖范围，把关键配置纳入持久化；用dmesg确认恢复流程是否触发，未触发则查编译配置。

5.5 ACS 选到拥挤信道

现象：自动信道选择结果长期落在干扰大的信道。原因：监管域设置与固件 offload 规则不一致，扫描数据不完整。解决：先iw reg get确认监管域，再核对 9.2、9.3 节的 offload 与保留逻辑；必要时用 14.21 节的信道排名信息查看 ACS 的决策依据，而不是只看最终结果。

6. 进阶验证：用统计闭环替代反复试参数

把这份指南用出价值的关键，不是把每章配置都抄一遍，而是建立“配置—统计—判断”的闭环。我的习惯是：任何一次参数调整，都先在txrx_stats里留一份基线，改完再抓一份，对比每 PPDU 的 MCS、NSS、BW 和 MU 标志，而不是凭体感说“好像快了”。下面这张表是我常用的对照维度，来自 22 章各节的统计项：

验证方法上，我一般做三步对照：单客户端干净信道抓基线；加入干扰或第二客户端复测；调整一个参数（比如聚合上限或 ATF 权重）后再测。三步下来，参数到底有没有生效、生效在哪个层面，基本就清楚了。10.29 至 10.32 节的 ATF 相关配置尤其适合这个流程，因为 ATF 的效果在单客户端下看不出来，必须多客户端并发才能验证公平性是否按预期分配。

还有一个容易被忽略的点是版本回退的后悔药：每次改配置前把当前生效的 hostapd.conf 和关键 debugfs 节点值 dump 一份存档，出问题时能快速回到上一个已知good状态。我吃过一次亏，调 ATF 权重时没存基线，结果公平性反而更差，花了半天才靠记忆恢复。从那以后我每次动调度类参数前都强制走一遍“dump 配置 + 抓统计基线”的流程，哪怕只改一个数字。希望帮到你。

本文还有配套的精品资源，点击获取