RK3588 + Linux7.0.3 网络工程调试错误速查手册

目录

1. 内核模块编译类错误
2. 模块加载内核符号类错误
3. 网卡驱动&GMAC硬件类错误
4. Netfilter/防火墙/限流模块错误
5. 虚拟网卡类错误
6. NAPI收包性能类错误
7. WiFi/SDIO无线驱动错误
8. Bonding双网冗余组网错误
9. 性能调优&内核参数报错
10. 开发板环境依赖缺失报错

---

一、内核模块编译类错误

报错1：missing headers, build kernel first

错误原因 ：内核源码未编译、未生成.config与头文件
解决方案

cd kernel
make rockchip_rk3588_defconfig
make prepare
make scripts

重新执行模块make编译

报错2：error: 'struct net_device' has no member named xxx

错误原因 ：内核版本API变更，Linux7.0.3与旧内核结构体字段差异
解决方案

1. 对照当前内核include/linux/netdevice.h修正字段
2. 使用RK3588原厂配套内核源码编译，不要混用主线内核

报错3：CROSS_COMPILE is not set

错误原因 ：未指定ARM64交叉编译工具链
解决方案

在Makefile顶部固定路径：

CROSS_COMPILE := /你的路径/aarch64-linux-gnu-
ARCH := arm64

报错4：permission denied 编译失败

解决方案

sudo chmod 755 -R 内核目录 模块工程目录

---

二、模块加载内核符号类错误

报错1：Unknown symbol in module

现象 ：insmod xxx.ko 提示未定义内核函数

原因1：内核未开启对应配置项

例：使用netfilter报错 → 内核未开启CONFIG_NETFILTER

原因2：编译内核与开发板运行内核版本不一致

根治方案

1. 开发板执行 uname -r 记录真实内核版本
2. 使用完全同版本同配置内核源码编译模块
3. 开发板执行：

depmod -a
modprobe xxx

报错2：module format invalid

原因 ：x86编译出ARM64模块，架构不匹配
解决 ：全程指定ARCH=arm64交叉编译，禁止本机gcc直接编译

报错3：tainted kernel 内核被污染警告

原因 ：加载非GPL私有模块、驱动异常崩溃过
影响 ：不影响功能，仅内核调试日志受限
消除 ：模块添加 MODULE_LICENSE("GPL");

---

三、GMAC以太网硬件驱动常见错误

报错1：gmac0 no phy found 找不到PHY芯片

原因

1. 设备树phy-address地址错误
2. MDIO总线未启用
3. 硬件复位引脚配置错误
   解决
4. DTS确认reg=<0>与硬件PHY地址一致
5. 检查snps,reset-gpio引脚定义
6. 内核开启CONFIG_PHYLIB、CONFIG_REALTEK_PHY

报错2：link down 网卡始终无连接

排查顺序

1. 网线、交换机端口是否千兆
2. phy-mode配置错误：
   • RGMII硬件 → 配置rgmii-id
   • 配成rmii必然不通
3. 执行 ethtool eth0 查看协商状态

报错3：千兆网卡只能跑百兆

核心原因 ：RGMII时钟时序延迟参数不对
修复DTS

snps,reset-delays-us = <0 10000 100000>;

报错4：gmac dma alloc fail DMA内存分配失败

原因 ：内核CMA预留内存不足
解决 ：内核开启大页内存、调整dma_buf配置，增大预留DMA缓冲区

报错5：收包正常、发包卡死

原因 ：TX DMA描述符环溢出、中断未使能
解决 ：重启网卡 ip link set eth0 down && ip link set eth0 up

---

四、Netfilter 防火墙/流量限速模块错误

报错1：nf_register_net_hook failed 注册钩子失败

原因

1. 内核关闭CONFIG_NETFILTER
2. 重复加载同一钩子模块
   解决
3. 内核开启网络过滤框架
4. 先rmmod旧模块再重新加载

报错2：防火墙规则不生效、依旧能访问

原因

1. 钩子挂载点位错误（拦截转发包用NF_INET_FORWARD，本机入站用NF_INET_LOCAL_IN）
2. IP字节序未做htonl转换
   标准正确写法

__be32 banip = htonl(0xc0a8010a);
if(iph->saddr == banip)

报错3：流量限速模块直接丢包过多/不限速

原因

1. 计时周期jiffies换算错误
2. 统计字节未累加skb真实长度
   修正 ：严格使用skb->len做流量统计

报错4：加载模块后内核卡顿、CPU飙升

原因 ：钩子优先级过高、无休眠循环占用CPU
解决 ：调整priority为中间优先级，避免抢占系统核心进程

---

五、虚拟网卡模块调试错误

报错1：alloc_netdev failed 创建虚拟网卡失败

原因 ：内核虚拟网络设备数量达到上限
解决：卸载无用虚拟网卡，清理残留设备

ip link del vnic0

报错2：虚拟网卡创建成功，无法配置IP

原因 ：未绑定ether_setup以太网设备初始化函数
修复 ：创建时必须传入ether_setup

报错3：发包日志打印正常，无实际网络转发

原因 ：仅实现发送回调，未实现路由与接收逻辑
解决：虚拟网卡仅做测试打印，如需真实转发需对接内核协议栈转发逻辑

---

六、NAPI 高吞吐收包机制错误

报错1：NAPI无法唤醒、收包中断不触发

原因

1. napi_enable未调用
2. 中断函数未调用napi_schedule调度轮询
   标准流程
   硬件中断 → 关中断 → napi_schedule → 进入poll轮询

报错2：高并发下丢包严重

原因

1. NAPI budget值设置过小
2. 未开启网卡多队列RSS
   优化：调整budget=64~256，内核开启RSS多队列

报错3：napi_complete_done调用异常崩溃

原因 ：收包数量判断逻辑颠倒
规范写法

if(recv_cnt < budget)
    napi_complete_done(napi, recv_cnt);

---

七、WiFi AP6275/SDIO无线驱动错误

报错1：sdio wifi firmware load failed 固件加载失败

解决

1. 将nvram.bin、fw.bin放入开发板/lib/firmware
2. Buildroot固件目录配置正确

报错2：wlan0网卡不生成

排查

1. DTS SDIO总线状态status=okay
2. 内核开启CONFIG_WLAN、CONFIG_SDIO_WIFI
3. 查看dmesg | grep wifi确认驱动加载

报错3：热点hostapd启动失败

常见原因

1. 信道区域码未配置country_code=CN
2. 5G信道在当前地区禁用
   解决：改用1-14 2.4G信道测试

报错4：WiFi连接成功但无法上网

原因：未配置DNS、未开启内核IP转发

echo 1 > /proc/sys/net/ipv4/ip_forward

---

八、Bonding双网口冗余组网错误

报错1：modprobe bonding 找不到模块

解决 ：内核开启CONFIG_BONDING

报错2：bond0创建成功，无法绑定eth0

原因 ：物理网卡已被IP占用
先清空

ip link set eth0 down
ip link set eth1 down

再执行绑定脚本

报错3：主备切换失效，断网业务中断

原因 ：bond模式选错，热备必须使用active-backup模式

报错4：绑定后网速叠加无效

说明 ：主备模式不能叠加带宽，聚合模式才可带宽叠加

---

九、网络性能调优参数报错

报错1：sysctl: cannot set xxx, permission denied

解决

sysctl -w net.ipv4.tcp_tw_reuse=1
# 永久写入
echo "net.ipv4.tcp_tw_reuse=1" >> /etc/sysctl.conf
sysctl -p

报错2：设置bbr拥塞控制提示不存在

原因 ：内核未编译CONFIG_TCP_CONG_BBR
解决：内核开启BBR重新编译内核

报错3：中断绑定写入失败

原因 ：内核开启了irqbalance自动均衡服务
关闭

systemctl stop irqbalance
systemctl disable irqbalance

再手动绑定CPU亲和性

---

十、skb数据包操作模块常见错误

报错1：dev_alloc_skb return NULL 分配skb失败

原因 ：内核内存紧张、碎片过多
解决：释放多余进程内存，增大系统空闲内存

报错2：skb_put越界访问内核崩溃

原因 ：写入数据长度超出预留缓冲区大小
规范 ：先计算长度再调用skb_put

报错3：skb克隆后修改数据互相影响

原因 ：skb_clone浅拷贝共享数据区
需要独立数据使用 ：skb_copy深拷贝

---

十一、开发板通用环境缺失报错汇总

缺失工具	现象	安装方式(Buildroot)
ethtool	无法查看网卡速率	开启BR2_PACKAGE_ETHTOOL
tcpdump	抓包命令不存在	开启BR2_PACKAGE_TCPDUMP
iperf3	无法网络压测	开启BR2_PACKAGE_IPERF3
wpa_supplicant	WiFi拨号失败	开启无线组件

---

十二、内核崩溃紧急处理方案

1. 出现Oops/panic网络相关崩溃
   • 立刻卸载最新加载的网络内核模块
   • dmesg查看崩溃调用栈，定位skb/NAPI/Netfilter代码行
2. 网络子系统卡死无响应

# 重启网络栈
/etc/init.d/network restart
# 强制重置网卡
echo 1 > /sys/class/net/eth0/reset

3. 无法开机进入系统
   • U-Boot启动阶段跳过自定义网络驱动加载，恢复默认内核启动

---

十三、调试万能排查顺序（优先执行）

1. dmesg -c 清空旧日志
2. 加载模块 insmod xxx.ko
3. dmesg -Hw 实时抓取报错
4. 核对：内核配置 → 设备树 → 硬件接线 → 模块API版本
5. 功能测试 → 抓包验证 → 性能压测

---

附加附赠：快速调试命令合集

# 查看所有网络相关内核打印
dmesg | grep -E "eth|gmac|wifi|skb|napi|netfilter"

# 查看网卡收发统计
cat /proc/net/dev

# 查看PHY链路状态
mii-tool eth0

# 查看内核已注册网络钩子
cat /proc/net/netfilter/nf_hooks

---

需要我再把这份手册导出为纯TXT离线版 ，或者整理成排查思维导图结构吗？