手把手教你用PetaLinux开发内核模块：从零点亮FPGA上的LED
你有没有遇到过这样的场景？硬件团队在Vivado里设计好了一个自定义IP，比如一个简单的LED控制器或GPIO扩展模块，现在需要在Linux系统中把它驱动起来。标准内核没有现成支持，怎么办？
别急着改内核源码重新编译——那太重了。真正高效的做法是：写一个可动态加载的内核模块（LKM），配合设备树绑定，快速实现功能上线。
本文将以Xilinx Zynq平台为例，带你完整走一遍基于PetaLinux 的内核模块开发全流程。我们不讲空话，只上干货：从工程搭建、代码编写、交叉编译到板级验证，每一步都实打实可复现。
为什么选PetaLinux做内核模块开发？
在嵌入式Linux领域，尤其是Xilinx Zynq系列SoC（如Zynq-7000、Zynq UltraScale+ MPSoC）平台上，PetaLinux 已成为事实上的标准开发工具链。它不是简单的脚本集合，而是基于 Yocto Project 构建的一套完整自动化系统构建框架。
它的最大优势是什么？
——一切皆集成，环境免维护。
你想单独编译一个.ko模块，但又怕版本不对、头文件缺失、工具链错配？PetaLinux 帮你全搞定了。只要你用它的内核源和配置，就能保证模块与目标系统100%兼容。
更重要的是，它能自动处理HDF → 设备树 → 内核镜像的联动关系，让你专注逻辑实现，而不是折腾构建系统。
第一步：创建PetaLinux工程并导入硬件
我们的起点是一个已经由 Vivado 生成的硬件描述文件（HDF）。这个文件包含了PS端CPU、DDR、时钟以及PL侧所有AXI外设的信息。
# 创建新项目（以zynqMP模板为例） petalinux-create -t project --name my_zynqmp_project --template zynqMP cd my_zynqmp_project # 导入HDF（假设路径为 ~/vivado_prj/hw_project.sdk/system.hdf） petalinux-config --get-hw-description=~/vivado_prj/hw_project.sdk/执行完这三步后，PetaLinux 会：
- 自动生成
project-spec/meta-user/recipes-bsp/device-tree/files/system-top.dts - 提取 PL 端 IP 的地址映射、中断连接等信息生成
.dtsi片段 - 初始化 U-Boot 和 Linux 内核配置
⚠️ 小贴士：如果你后续修改了FPGA设计，只需重新导出HDF，并再次运行
petalinux-config --get-hw-description即可同步更新设备树。
接下来要确保一件事：启用可加载模块支持。否则你的.ko文件根本没法加载！
petalinux-config -c kernel进入图形化菜单后，找到：
Enable loadable module support [*]务必勾选！这是后续一切操作的前提。
保存退出后，PetaLinux 会在底层为你设置好CONFIG_MODULES=y，同时保留符号导出机制（如__ksymtab），让模块能正确引用内核函数。
第二步：编写内核模块代码 —— 让LED亮起来
我们现在要写一个最简化的平台驱动，用于控制一个位于 AXI 总线上的 LED 控制器。该IP在Vivado中被分配的基地址是0x43C00000，寄存器宽度为32位，写1点亮LED。
驱动核心逻辑
Linux现代驱动推荐使用platform_driver+device tree的模式，而不是直接访问物理地址。这样更安全、更灵活，也便于热插拔和资源管理。
下面是完整的驱动代码：
// simple_led_module.c #include <linux/init.h> #include <linux/module.h> #include <linux/kernel.h> #include <linux/platform_device.h> #include <linux/io.h> #include <linux/of_address.h> #include <linux/of_device.h> #define DRIVER_NAME "simple-led-driver" static void __iomem *led_base; static int simple_led_probe(struct platform_device *pdev) { struct resource *res; // 获取设备树中的内存资源 res = platform_get_resource(pdev, IORESOURCE_MEM, 0); if (!res) { dev_err(&pdev->dev, "No memory resource\n"); return -EINVAL; } // 映射物理地址到虚拟内存空间 led_base = devm_ioremap_resource(&pdev->dev, res); if (IS_ERR(led_base)) { dev_err(&pdev->dev, "Failed to map registers\n"); return PTR_ERR(led_base); } // 点亮LED iowrite32(0x01, led_base); dev_info(&pdev->dev, "LED turned ON at %pR\n", res); return 0; } static int simple_led_remove(struct platform_device *pdev) { // 关闭LED if (led_base) iowrite32(0x00, led_base); return 0; } // 匹配表：决定哪个设备节点能触发probe static const struct of_device_id simple_led_of_match[] = { { .compatible = "xlnx,simple-led-1.0" }, { /* end */ } }; MODULE_DEVICE_TABLE(of, simple_led_of_match); // 平台驱动结构体 static struct platform_driver simple_led_driver = { .probe = simple_led_probe, .remove = simple_led_remove, .driver = { .name = DRIVER_NAME, .of_match_table = simple_led_of_match, }, }; // 模块入口/出口 static int __init simple_led_init(void) { int ret = platform_driver_register(&simple_led_driver); if (ret) pr_err("%s: Failed to register driver\n", DRIVER_NAME); else pr_info("%s: Driver registered\n", DRIVER_NAME); return ret; } static void __exit simple_led_exit(void) { platform_driver_unregister(&simple_led_driver); pr_info("%s: Driver unregistered\n", DRIVER_NAME); } module_init(simple_led_init); module_exit(simple_led_exit); MODULE_AUTHOR("Engineer"); MODULE_DESCRIPTION("Simple LED Control Module for PetaLinux"); MODULE_LICENSE("GPL v2"); MODULE_VERSION("1.0");关键点解析
| 技术点 | 说明 |
|---|---|
devm_ioremap_resource() | 安全映射I/O内存，出错自动释放，且设备卸载时会自动清理 |
platform_get_resource() | 从设备树提取 reg 资源，避免硬编码地址 |
.compatible匹配 | 是驱动能否被调用的关键，必须与DTS完全一致 |
devm_*系列函数 | 实现资源自动管理，防止泄漏 |
特别是MODULE_LICENSE("GPL v2")这一行不能少！如果没声明许可证，内核会认为这是“专有代码”，可能导致模块加载失败并打印tainted警告。
第三步：Makefile怎么写？别自己猜，让PetaLinux告诉你
很多人卡在编译环节，就是因为Makefile写错了。你以为随便找个内核路径就行？错！必须使用当前PetaLinux工程所用的内核源码目录和交叉编译器。
聪明的方法是：通过petalinux-config命令动态获取关键参数。
# Makefile obj-m += simple_led_module.o # 自动获取内核源路径（指向build/tmp/work-shared/.../kernel-source） KERNEL_SRC := $(shell petalinux-config -c kernel --show-kernel-arch-dir) # 获取交叉编译前缀（如 aarch64-xilinx-linux-） CROSS_COMPILE ?= $(shell petalinux-config -c kernel --get-cross-compile) # 架构自动识别（通常是 arm 或 aarch64） ARCH ?= $(shell uname -m | sed -e s/i.86/arm/ -e s/x86_64/aarch64/) all: $(MAKE) -C $(KERNEL_SRC) M=$(CURDIR) ARCH=$(ARCH) CROSS_COMPILE=$(CROSS_COMPILE) modules clean: $(MAKE) -C $(KERNEL_SRC) M=$(CURDIR) clean install: scp simple_led_module.ko root@192.168.1.10:/lib/modules/$(shell uname -r)/✅ 成功秘诀：
--show-kernel-arch-dir返回的是实际构建用的内核源路径，包含.config和Module.symvers，这才是模块能成功链接的根本保障。
运行make后你会看到：
Building modules, stage 2. MODPOST 1 modules CC simple_led_module.mod.o LD [M] simple_led_module.ko恭喜！你的simple_led_module.ko已经诞生。
第四步：设备树添加节点，建立软硬件桥梁
现在代码有了，但内核还不知道哪里有个“simple-led”设备。我们需要在设备树中声明它。
编辑：
project-spec/meta-user/recipes-bsp/device-tree/files/system-user.dtsi加入以下内容：
/include/ "system-conf.dtsi" / { amba_pl: amba_pl@0 { #address-cells = <2>; #size-cells = <2>; compatible = "simple-bus"; ranges; simple_led: simple_led@43c00000 { compatible = "xlnx,simple-led-1.0"; reg = <0x0 0x43c00000 0x0 0x1000>; clock-names = "s_axi_aclk"; clocks = <&misc_clk_0>; }; }; };解释几个关键字段：
reg = <0x0 0x43c00000 ...>：第一个0表示高32位地址为空，第二个是低32位基址；后面是长度。compatible：必须与驱动中的.of_match_table完全一致，否则 probe 不会触发。ranges和#address-cells：表明这是一个可寻址的总线段，允许子节点拥有内存映射资源。
保存后重建设备树：
petalinux-build -c device-tree生成的.dtb文件将包含这个新节点。
第五步：部署与调试 —— 看见LED亮起那一刻
把东西烧到板子上之前，先确认三件事：
- 新的
image.ub是否包含了更新后的.dtb？ .ko文件是否传到了目标板？- 目标板内核是否启用了模块支持？
部署步骤
# 编译整个系统（包括新的dtb） petalinux-build # 启动板子，通过TFTP/NFS或SD卡加载系统 # 复制ko文件到板子（可通过scp、tftp等方式） scp simple_led_module.ko root@192.168.1.10:/tmp/ # 登录目标板 ssh root@192.168.1.10在开发板上执行：
# 加载模块 insmod /tmp/simple_led_module.ko # 查看日志 dmesg | tail -5你应该能看到类似输出：
[ 1234.567890] simple-led-driver: Driver registered [ 1234.567910] simple-led-driver: LED turned ON at [mem 0x43c00000-0x43c00fff]🎉 成功了！LED应该已经亮起。
再试试卸载：
rmmod simple_led_module dmesg | tail -1 # 输出：Driver unregistered如果一切正常，LED熄灭。
常见问题排查清单
| 问题现象 | 可能原因 | 解决方法 |
|---|---|---|
insmod: error inserting 'xxx.ko': Invalid module format | 内核版本或配置不匹配 | 使用petalinux-build -c kernel确保.config和Module.symvers正确 |
Unknown symbol in module | 引用了未导出的内核符号 | 检查是否用了EXPORT_SYMBOL，或换用公开API |
No matching node found | 设备树.compatible不一致 | 对比of_match_table和 DTS 中字符串是否完全相同（含厂商前缀） |
ioremap failed | reg地址范围错误或已被占用 | 检查Vivado中IP地址是否冲突，确认MMU映射可用 |
| 模块加载无反应 | probe函数未执行 | 打印of_node_name_eq()调试，或临时添加pr_info()到 match 表 |
💡 调试技巧：可以在驱动中加一句
pr_info("Matching against: %s\n", np->full_name);来查看到底有没有走到匹配流程。
更进一步的设计建议
虽然我们实现了基本功能，但在真实产品中还需考虑更多：
✅ 使用 devm_* 管理资源
所有申请的内存、中断、时钟都应使用devm_request_irq()、devm_clk_get()等形式，确保设备移除时自动释放。
✅ 添加 sysfs 接口供用户空间控制
例如暴露/sys/class/simple-led/brightness，让用户程序也能开关LED。
✅ 支持多实例设备
如果有多个同类IP，驱动应能通过platform_data或设备树属性区分不同实例。
✅ 生产环境关闭调试日志
将pr_debug()替换为条件宏，在发布版本中禁用，减少性能开销。
结语：掌握这套方法，你就能应对大多数定制驱动需求
通过这个实战案例，你应该已经掌握了基于 PetaLinux 开发内核模块的核心能力：
- 如何利用 PetaLinux 工具链保持构建一致性
- 如何编写符合现代Linux规范的 platform driver
- 如何通过设备树实现软硬件自动绑定
- 如何完成交叉编译与部署验证
- 如何系统性地排查常见错误
这些技能不仅适用于LED控制，同样可用于ADC采集、PWM输出、自定义通信协议等各种场景。
当你下次面对一个新的FPGA IP时，不再需要等待内核合并周期，也不必重新编译整个系统——只需写个模块，insmod一下，立刻见效。
这才是嵌入式开发应有的敏捷节奏。
如果你正在做工业控制、边缘计算或智能硬件项目，这种“快速原型 + 动态加载”的开发模式，将是提升迭代效率的关键利器。
📣 欢迎你在评论区分享你的模块开发经验，或者提出你在实践中遇到的具体问题，我们一起探讨解决！
