简介《高通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 调度算法一起看才能拼出完整图景数据从协议栈下来经过主机驱动的队列管理交给固件的调度器调度器再根据 ATFAirtime Fairness策略和 MU 分组决定谁先发、发多少。你在主机侧看到的队列深度、聚合参数最终都要和固件侧的调度能力对齐否则就是两套逻辑各说各话。2.2 组件化为什么 11.0 的代码结构和你印象里不一样从修订记录能看出一个明显趋势从 2018 年 3 月的 J 版开始大量“componentization”条目涌现——Green AP 组件化、QDF CB 组件化、FTM 组件化、Target-to-host 初始化组件化、Spectral 组件化、Extender AP 组件化。这不是文档在凑字数而是驱动架构在往“可裁剪、可复用”方向走。对一线工程师的实际意义是你拿到的驱动源码不再是铁板一块很多功能可以通过编译开关和组件边界决定要不要编进去。移植到资源受限的板子时先看哪些组件是必需的比盲目全编再删要省事得多。一个常见的落地动作是在编译配置里确认 FTMFactory Test Mode组件是否启用。指南 22.12 节讲 FTM daemon22.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、FILS2019.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 21 | head -80iw phy的输出是判断“这个参数能不能配”的第一手依据如果能力集里没有某个加密套件hostapd.conf 里写了也会在启动时被拒。hostapd -dd的调试输出会打印驱动返回的错误码比看 syslog 更直接。参数层面重点盯supported bands里的频段范围和HT/VHT/HE capabilities这两块决定了你后面信道和带宽能开到什么程度。3.2 手动创建与删除 VAP5.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 到该接口启动配置中 interfacevap1 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.binspectral_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 配置中 acs1 hostapd -dd /etc/hostapd/hostapd.conf 21 | 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.pcapset 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 章各节的统计项观测维度对应章节判断依据每 PPDU MCS/NSS/BW22.19是否达到配置上限未达则查链掩码与协商MU-MIMO/OFDMA 参数22.19.2 / 22.19.3MU 标志是否为 0多客户端场景下是否成组每射频 Tx/Rx 统计22.2.8.1 / 22.2.8.2射频级吞吐与错误计数是否异常Beacon 计数与中断统计22.2.9Beacon 是否稳定发送有无中断客户端 RSSI 与 Tx/Rx 包24.24 / 24.28客户端侧信号与重传是否匹配验证方法上我一般做三步对照单客户端干净信道抓基线加入干扰或第二客户端复测调整一个参数比如聚合上限或 ATF 权重后再测。三步下来参数到底有没有生效、生效在哪个层面基本就清楚了。10.29 至 10.32 节的 ATF 相关配置尤其适合这个流程因为 ATF 的效果在单客户端下看不出来必须多客户端并发才能验证公平性是否按预期分配。还有一个容易被忽略的点是版本回退的后悔药每次改配置前把当前生效的 hostapd.conf 和关键 debugfs 节点值 dump 一份存档出问题时能快速回到上一个已知good状态。我吃过一次亏调 ATF 权重时没存基线结果公平性反而更差花了半天才靠记忆恢复。从那以后我每次动调度类参数前都强制走一遍“dump 配置 抓统计基线”的流程哪怕只改一个数字。希望帮到你。本文还有配套的精品资源点击获取
简介《高通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 调度算法一起看才能拼出完整图景数据从协议栈下来经过主机驱动的队列管理交给固件的调度器调度器再根据 ATFAirtime Fairness策略和 MU 分组决定谁先发、发多少。你在主机侧看到的队列深度、聚合参数最终都要和固件侧的调度能力对齐否则就是两套逻辑各说各话。2.2 组件化为什么 11.0 的代码结构和你印象里不一样从修订记录能看出一个明显趋势从 2018 年 3 月的 J 版开始大量“componentization”条目涌现——Green AP 组件化、QDF CB 组件化、FTM 组件化、Target-to-host 初始化组件化、Spectral 组件化、Extender AP 组件化。这不是文档在凑字数而是驱动架构在往“可裁剪、可复用”方向走。对一线工程师的实际意义是你拿到的驱动源码不再是铁板一块很多功能可以通过编译开关和组件边界决定要不要编进去。移植到资源受限的板子时先看哪些组件是必需的比盲目全编再删要省事得多。一个常见的落地动作是在编译配置里确认 FTMFactory Test Mode组件是否启用。指南 22.12 节讲 FTM daemon22.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、FILS2019.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 21 | head -80iw phy的输出是判断“这个参数能不能配”的第一手依据如果能力集里没有某个加密套件hostapd.conf 里写了也会在启动时被拒。hostapd -dd的调试输出会打印驱动返回的错误码比看 syslog 更直接。参数层面重点盯supported bands里的频段范围和HT/VHT/HE capabilities这两块决定了你后面信道和带宽能开到什么程度。3.2 手动创建与删除 VAP5.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 到该接口启动配置中 interfacevap1 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.binspectral_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 配置中 acs1 hostapd -dd /etc/hostapd/hostapd.conf 21 | 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.pcapset 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 章各节的统计项观测维度对应章节判断依据每 PPDU MCS/NSS/BW22.19是否达到配置上限未达则查链掩码与协商MU-MIMO/OFDMA 参数22.19.2 / 22.19.3MU 标志是否为 0多客户端场景下是否成组每射频 Tx/Rx 统计22.2.8.1 / 22.2.8.2射频级吞吐与错误计数是否异常Beacon 计数与中断统计22.2.9Beacon 是否稳定发送有无中断客户端 RSSI 与 Tx/Rx 包24.24 / 24.28客户端侧信号与重传是否匹配验证方法上我一般做三步对照单客户端干净信道抓基线加入干扰或第二客户端复测调整一个参数比如聚合上限或 ATF 权重后再测。三步下来参数到底有没有生效、生效在哪个层面基本就清楚了。10.29 至 10.32 节的 ATF 相关配置尤其适合这个流程因为 ATF 的效果在单客户端下看不出来必须多客户端并发才能验证公平性是否按预期分配。还有一个容易被忽略的点是版本回退的后悔药每次改配置前把当前生效的 hostapd.conf 和关键 debugfs 节点值 dump 一份存档出问题时能快速回到上一个已知good状态。我吃过一次亏调 ATF 权重时没存基线结果公平性反而更差花了半天才靠记忆恢复。从那以后我每次动调度类参数前都强制走一遍“dump 配置 抓统计基线”的流程哪怕只改一个数字。希望帮到你。本文还有配套的精品资源点击获取
