1. 一块只认 USB 转串口的 ARM 板:代码开发工具没对齐内核,驱动就只是一堆源码
板子上的 USB 口插上 CH340 模块,系统里就是不出 /dev/ttyUSB0。这个场景我在好几块不同的 ARM 板上都遇到过,问题多半不在硬件,而在代码开发工具这条链上:手上有一份 ch34x 驱动源码,但要把它变成板子能 insmod 的 .ko,中间隔着内核源码版本、交叉编译前缀、Makefile 里那个 KERNELDIR 三样东西,任一样对不上,编出来的产物就是废的。
下面按我实际跑过的顺序讲:从确认板端内核版本开始,改 Makefile、敲 make 命令、把 .ko 拷上板、insmod 后看到 ttyUSB0,参数写在哪、错了会表现成什么样,一并说清。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 代码开发工具选型:为什么 ch34x 必须在板端内核源码树里编译
写驱动模块和写一个普通的 ARM 应用完全是两码事。应用只要编译器支持 ARM 就能跑,模块还要过内核这一关。这一章先把“为什么非得用板端内核源码”讲透,再落到怎么确认手上的源码树是对的。
2.1 驱动模块不是普通程序,它的身份证由编译时的内核决定
.ko 文件加载时,内核会先读模块头里的 vermagic,里面带着内核版本号、是否 SMP、是否预empt 等一串标志;接着做符号解析,驱动代码里调用的 usb_register_driver、tty_register_driver 这类符号,必须在板端内核里有对应实现,而且符号 CRC 要对得上。这两道检查任何一道不过,insmod 就会直接拒绝。
这意味着编译 .ko 时用的“内核”,不能是随便一个 Linux 内核,必须是板子上正在跑的那个内核的源码树,而且这个源码树最好已经完整编译过一次,至少生成过 Module.symvers 和 include/generated/ 下的配置头。少了这些,kbuild 走到一半就会停下来告诉你找不到符号或者找不到头文件。
我第一次做这件事的时候,就是拿了主机上 /usr/src/linux-headers-$(uname -r) 去编,编译器一声不吭地产出了 .ko,拷到板上 insmod 直接失败。当时没看内核日志,以为是驱动源码有问题,来回折腾了半天,后来才发现产物根本就是给 x86_64 编的。
2.2 主机 Ubuntu 的内核路径为什么一定编不出能用的 .ko
ch34x 驱动源码目录里的 Makefile,默认写的是主机 Ubuntu 的内核路径。这行不改成板端路径,后面所有步骤都是白费。原因有两层,缺一层都不行。
第一层是架构。主机内核是 x86_64,用它编出来的模块 ELF 头里 e_machine 是 x86_64,ARM 板子的内核加载器看到这个头就直接拒了,连 vermagic 都轮不到检查。
第二层是版本和配置。哪怕你神奇地把架构问题绕过去了,vermagic 里记的还是主机内核的版本串和配置标志,跟板端内核完全对不上。
三种组合的差别,用一张表看得最清楚:
| 编译时用的内核树 | 实际调用的编译器 | 产物架构 | 上板结果 |
|---|---|---|---|
| 主机 Ubuntu 内核路径 | 主机 gcc | x86_64 | 加载被拒,架构不符 |
| 板端内核源码,但没传交叉编译参数 | 仍是主机 gcc | x86_64 | 同上,白编 |
板端内核源码 + ARCH=arm + 交叉前缀 |
arm-himix200-linux-gcc |
ARM | vermagic 对得上,可加载 |
所以“改 KERNELDIR”和“加交叉编译参数”这两件事必须同时做,只做一件的结果和一件都不做差不多,只是失败的地方不同:只改路径会在编译中途报找不到编译器或头文件,只加参数则能编出来但加载不了。
2.3 交叉编译前缀决定产物架构,末尾那根短横线不是装饰
交叉编译工具链的调用方式是“前缀 + 工具名”,arm-himix200-linux- 这个前缀拼上 gcc 就是 arm-himix200-linux-gcc,拼上 ld 就是 arm-himix200-linux-ld。前缀末尾那根短横线是拼接用的,写的时候不能丢,丢了 make 会去找一个叫 arm-himix200-linuxgcc 的东西,报“命令未找到”。
这套工具链要事先装好并且进了 PATH。验证办法很土但有效,直接在终端敲一次:
bash复制# 确认交叉编译器能被找到,且版本信息正常输出
arm-himix200-linux-gcc -v
能打印出 gcc 版本和目标架构,说明工具链就位;报 command not found,就先把工具链的 bin 目录加进 PATH,别急着往下走。
前缀还必须和 ARCH 匹配。ARCH=arm 会让 kbuild 去读板端内核源码里 arch/arm/ 下的 Makefile 和头文件,而 CROSS_COMPILE 指定的是实际干活的编译器。两个参数一个管“按哪个架构的规则编”,一个管“用哪套工具编”,配错了会出现“头文件找到了但编译不过”这种很别扭的现象。
2.4 先把板端内核版本和源码树位置确认下来
动手改 Makefile 之前,花两分钟把两件事确认掉:板子跑的内核版本,以及主机上板端内核源码树的确切路径。这两个信息后面要反复用到。
bash复制# 第一步:在开发板串口终端里执行,记下完整版本串
uname -r
# 输出形如 4.9.y-smp,这一段后面要和 vermagic 对照
# 第二步:回到 Ubuntu 主机,确认板端内核源码树存在
ls -d /home/dev/sdk/osdrv/opensource/kernel/linux-4.9.y-smp
# 第三步:确认这棵源码树是能用的,至少有顶层 Makefile 和 arch/arm
ls /home/dev/sdk/osdrv/opensource/kernel/linux-4.9.y-smp/Makefile
ls -d /home/dev/sdk/osdrv/opensource/kernel/linux-4.9.y-smp/arch/arm
三步都有正常输出,说明源码树这一侧没问题。第三步尤其别省,有些人拿到的是裁剪过的内核头文件包,只有 include/ 没有 arch/,编模块时会在很靠后的阶段才报错,排查起来很费时间。
uname -r 的输出和源码树目录名要能对上。目录名里带 4.9.y-smp,板子上跑的是 4.9.y-smp,这才叫一致。如果板子上是 4.9.y(不带 smp),源码树是 4.9.y-smp,编出来的模块 vermagic 会差一个 SMP 标志,加载照样失败。这种差异肉眼很容易忽略,建议把两个字符串抄在同一个地方逐字符比一遍。
3. Makefile 与交叉编译参数:把 KERNELDIR、ARCH、CROSS_COMPILE 落到一条命令里
确认完内核版本和源码树,接下来是把驱动源码目录里的 Makefile 改对,然后用一条命令把 .ko 编出来。这一章的重点不是“能编过”,而是“编出来的东西是对的”。
3.1 驱动源码里的 Makefile:obj-m、-C、M= 三件事
内核模块的 Makefile 和普通应用的 Makefile 长得不一样,它本质上是在调用内核自己的构建系统,只是把当前目录“挂”进去。标准的 kbuild 骨架大致是这样,ch34x 这类单文件驱动照着套即可:
makefile复制# ch34x 驱动的最小 kbuild 骨架
obj-m += ch34x.o
# 板端内核源码树,必须与板子上跑的内核一致
# 用 ?= 是为了允许命令行覆盖,方便一块主机编多块板子
KERNELDIR ?= /home/dev/sdk/osdrv/opensource/kernel/linux-4.9.y-smp
# 当前驱动源码目录,-C 切过去之后要靠它切回来
PWD := $(shell pwd)
all:
$(MAKE) -C $(KERNELDIR) M=$(PWD) modules
clean:
$(MAKE) -C $(KERNELDIR) M=$(PWD) clean
三个关键点逐一说。obj-m += ch34x.o 告诉 kbuild 把 ch34x.c 编成模块而不是编进内核,冒号后面那个名字决定了最终产物叫 ch34x.ko,后面 insmod 时用的模块名也是它。-C $(KERNELDIR) 是把 make 的工作目录切到内核源码树,让内核自己的顶层 Makefile 接管流程。M=$(PWD) 是告诉内核构建系统“真正的源码在另一个目录”,编完再切回来。少了 M=,kbuild 会以为你要编整个内核,直接卡住。
这里的 ch34x.o 和最终文件名必须和驱动源码文件名一致。源码叫 ch34x.c,这里就写 ch34x.o;写成别的名字,kbuild 找不到源文件,报错信息通常只说“no rule to make target”,不会直接告诉你是名字写错了。
3.2 KERNELDIR 用 := 还是 ?=:一个等号决定能不能在命令行覆盖
原始 Makefile 里 KERNELDIR 是用 := 赋值的,指向的是主机 Ubuntu 的内核路径。改成板端路径之后,赋值符号也建议一起换掉。
:= 是立即展开,make 一读进来就把值定死,命令行上传进来的同名变量在某些写法下会被它盖掉,表现是“我明明在 make 后面带了 KERNELDIR,怎么还是去编主机内核”。?= 是“只在变量没定义时才赋值”,命令行传了就用命令行的,没传才用默认值,一块主机上编多块不同内核的板子时特别省事。
改完这行,顺手把路径后面多余的空格清掉。Makefile 里变量赋值末尾的空格会被当成值的一部分,拼出来的路径变成 /path/to/kernel ,ls 能过,make 进去就找不到文件,报错还看不出问题在哪。
3.3 一条 make 命令里的 ARCH 与 CROSS_COMPILE 怎么传进子 make
Makefile 改好之后,编译命令是这样一条:
bash复制# ARCH 指定目标架构,CROSS_COMPILE 指定交叉工具链前缀
# 末尾的短横线是前缀的一部分,不能省略
make ARCH=arm CROSS_COMPILE=arm-himix200-linux-
这条命令看着简单,值得说清楚的是这两个变量怎么传到子 make 里去。顶层 Makefile 里执行的是 $(MAKE) -C $(KERNELDIR) M=$(PWD) modules,这是一次子 make 调用。命令行上传的变量默认会通过 MAKEFLAGS 传给子 make,所以不需要在 Makefile 里再写一遍 export,也不需要把 ARCH 手工塞进 $(MAKE) 后面。这一点很多人不放心,会在 Makefile 里重复写一次,反而容易写错。
ARCH=arm 的作用是让 kbuild 走板端内核源码里 arch/arm/ 那条分支,决定编译选项、头文件搜索路径和链接脚本。CROSS_COMPILE=arm-himix200-linux- 的作用是给 kbuild 一个前缀,它会自动拼出 arm-himix200-linux-gcc、arm-himix200-linux-ld、arm-himix200-linux-objcopy 一整串工具。
两个参数缺一个都会出问题。只写 ARCH=arm,kbuild 会去调主机 gcc,编出来的东西架构还是不对;只写 CROSS_COMPILE,kbuild 仍按主机架构的规则走,会去找 arch/x86 下的东西,在 ARM 内核源码树里当然找不到。
跑完这条命令,当前目录下应该出现 ch34x.ko。如果编译过程中刷了大量 warning 但最终产出了 .ko,先别高兴,继续做下一节的自检。
3.4 编完先自检:file 看架构、modinfo 看 vermagic
.ko 出来之后,拷上板之前,在主机上做两项检查,能省掉一大半来回烧板子的时间。
bash复制# 第一项:确认产物是 ARM 架构,而不是 x86_64
file ch34x.ko
# 期望输出里能看到 ARM,看到 x86-64 就说明交叉编译参数没生效
# 第二项:确认 vermagic 与板端内核版本一致
modinfo ch34x.ko | grep vermagic
# 期望输出形如 4.9.y-smp SMP mod_unload ARMv7 ...
file 看的是 ELF 头里的机器类型,这是最硬的一道证据。modinfo 读的是模块里的 vermagic 段,把它和板子上 uname -r 的输出对照,版本号、SMP 标志要能对上。两项都过,这个 .ko 才值得往板上拷。
| 自检项 | 命令 | 通过标准 | 不通过说明什么 |
|---|---|---|---|
| 架构 | file ch34x.ko |
显示 ARM | ARCH 或 CROSS_COMPILE 没生效 |
| 内核版本 | modinfo ch34x.ko | grep vermagic |
与 uname -r 一致 |
KERNELDIR 指向了别的内核树 |
| 模块名 | ls ch34x.ko |
文件名与 obj-m 一致 |
Makefile 里目标名写错 |
file 和 modinfo 这两个命令不在驱动源码里,是我一般会加进流程的自检手段。它们不改任何东西,只是把“上板之后才发现不对”提前到“拷之前就发现”。
4. 加载与验证的排查清单:insmod 之后看不到 ttyUSB0 的五种翻车
前面几步走顺了,剩下的就是拷上板、insmod、看设备节点。这一段看着最简单,翻车却最集中,因为失败现象往往只有一句“没有 ttyUSB0”,原因可能在上一步也可能在这一步。下面五条按我遇到的频率排。
4.1 现象:make 一上来就报找不到内核目录或顶层 Makefile
现象很直接,make 刚启动就停下,提示进不去某个目录,或者找不到目标 modules。
原因基本只有一个:KERNELDIR 还指着主机 Ubuntu 的内核路径,或者路径拼错了。原始 Makefile 里那一行本来就是主机路径,没改就编,必然是这样。另一种情况是路径写对了但末尾多了空格,拼出来的目录名带空格,ls 手动敲能过,make 里过不去。
解决分三步:先把 KERNELDIR 改成板端内核源码树的绝对路径;再手动 ls 一次这个路径下的 Makefile,确认文件真的在;最后用 make -n 空跑一遍,看它实际要进的目录是不是你期望的那个。make -n 只打印不执行,是这类路径问题最快的定位手段。
4.2 现象:编译顺利通过,上板 insmod 却失败
现象是主机上 .ko 生成得好好的,拷到板上执行 insmod ch34x.ko,返回非零,lsmod 里看不到模块,内核日志里能看到加载被拒的记录。
原因有两类。一类是编译时压根没带 ARCH 和 CROSS_COMPILE,产物是主机架构,板子不认;另一类是内核源码树版本和板端不一致,架构对了但 vermagic 对不上,比如源码树带 smp 而板子跑的是单核配置。
解决靠的是 3.4 那两项自检,把检查提前到拷之前。已经拷上板了也不要紧,回到主机重跑 file 和 modinfo,两项里哪项不对,就回去改对应的参数重编,不要在板上反复试。
4.3 现象:insmod 没报错,但 lsmod 里就是没有 ch34x
现象有点玄学:命令敲下去没看到明显的错误输出,紧接着 lsmod 却找不到这个模块。
原因通常是 insmod 其实失败了,只是错误信息滚得快没注意,返回码非零。另一种情况是加载的是目录里另一个同名的旧 .ko,你以为编的是新的,实际拷的是上一次的产物。
解决办法是把“有没有成功”这件事问清楚,别靠眼睛看:
bash复制# 加载并立刻检查返回码,0 才算成功
insmod ch34x.ko
echo $?
# 紧接着看内核日志末尾,加载失败的原因通常在这里
dmesg | tail -n 20
# 再确认模块是否真的在列表里
lsmod | grep ch34x
返回码非零就以 dmesg 的输出为准,那里会写明是版本不符、符号找不到还是参数问题。返回码是 0 但 lsmod 没有,多半是文件名和模块名对不上,lsmod 显示的是模块内部的名字,不是文件名。
4.4 现象:模块加载成功,/dev 下却没有 ttyUSB0
现象是 lsmod 能看到 ch34x,说明驱动已经在内核里了,但 ls /dev/ttyUSB* 什么都没有。
原因分两层。第一层是硬件还没插:驱动加载和 USB 设备枚举是两件事,模块在,不代表设备在。材料里的验证顺序是先 insmod 再插模块,插上之后 /dev 下才出现 ttyUSB0。第二层是设备不匹配:ch34x 只认 CH340、CH341 这一类 USB 转串口芯片,插一个别的芯片上去,驱动加载得再成功也不会生成节点。
解决按顺序来:先确认模块在(lsmod | grep ch34x),再插上 USB 转串口模块,然后看 /dev 下有没有新节点。插上之后可以用 dmesg | tail 看枚举日志,能看到 USB 设备的接入记录和设备节点创建记录。如果日志里连接入记录都没有,问题在硬件连接或 USB 供电,不在驱动。
4.5 现象:换一块板子或者换一版内核,整套流程全部作废
现象是同一份驱动源码,在 A 板上编好能用,换到 B 板上 insmod 就不行,必须从头再来一遍。
原因不是操作有问题,而是 .ko 和内核强绑定这件事本身决定的。板端内核版本一变,vermagic 就变;内核配置一变,符号 CRC 就变。一个 .ko 只对应一棵内核树,跨板子复用基本不成立。
解决思路是把内核路径变成参数,而不是写死在 Makefile 里。3.2 里把 := 换成 ?= 就是为这件事做准备,每块板子编之前传一次自己的 KERNELDIR,源码目录一个字节都不用改。再进一步,把编译命令和自检步骤收进一个脚本,下次换板子只改一个入参。
5. 把这条链固化成脚本:内核路径参数化与上板前的三项自检
这套流程我重复到第三遍的时候就开始烦了:每次都要改 Makefile 里的路径、敲 make、看 file、看 modinfo、拷文件、insmod、看 dmesg。烦到一定程度就容易偷懒,偷懒就会翻车。后来干脆写成一个脚本,把容易忘的步骤焊死在里面。
bash复制#!/bin/bash
# build_ch34x.sh —— 用法: ./build_ch34x.sh /path/to/board-kernel-source
set -e
KERNELDIR=${1:?请传入板端内核源码树的绝对路径}
CROSS=arm-himix200-linux-
# 编之前先确认源码树和工具链都在,避免编到一半才报错
test -f "${KERNELDIR}/Makefile" || { echo "内核源码树路径不对"; exit 1; }
command -v "${CROSS}gcc" >/dev/null || { echo "交叉编译器不在 PATH 里"; exit 1; }
make ARCH=arm CROSS_COMPILE="${CROSS}" KERNELDIR="${KERNELDIR}"
# 编完立刻自检,三项不过就不往下走
file ch34x.ko | grep -q ARM || { echo "产物不是 ARM 架构"; exit 1; }
modinfo ch34x.ko | grep vermagic
echo "自检通过,可以拷到板上 insmod 了"
set -e 让脚本任何一步失败就停,不会带着错误状态往下跑。第一行参数展开里那个 :? 是必填校验,不传路径直接退出并打印用法,避免 KERNELDIR 为空时 make 拿个空字符串去拼目录。两个 test 和 command -v 把前置条件提到最前面,这两项不过,后面的 make 一定会以更难懂的方式失败。最后那行 file | grep -q ARM 把架构检查变成硬门禁,架构不对直接退出,不给“先拷上去试试”的机会。
拷到板上之后,我固定走这三步,顺序不乱:
| 步骤 | 命令 | 看什么 |
|---|---|---|
| 加载并验返回码 | insmod ch34x.ko; echo $? |
返回 0 才算加载成功 |
| 确认模块在列表里 | lsmod | grep ch34x |
有输出说明模块已驻留内核 |
| 插模块后看节点 | ls /dev/ttyUSB* |
出现 ttyUSB0 说明枚举成功 |
如果第二步过了第三步没有,别急着重编,先 dmesg | tail 看枚举日志,八成是模块没插好或者芯片不是 CH340 系列。
血泪经验是:不要把“编出来了”当成“编对了”。file 和 modinfo 这两条命令加起来不到五秒,能省掉一次烧板子来回。从那以后我每次编完模块,不管多急,都强制把这两项跑一遍再拷文件,架构和 vermagic 有一个不对,坚决不上板。希望帮到你。
