衡山派Luban-Lite SDK代码结构深度解析：从BSP到应用的多RTOS支持框架

衡山派Luban-Lite SDK代码结构深度解析从BSP到应用的多RTOS支持框架最近在玩衡山派开发板发现它配套的Luban-Lite SDK设计得挺有意思。很多刚接触的朋友打开SDK看到一堆目录可能会有点懵bsp、kernel、packages、target……这些都是干嘛的我应该从哪里开始看今天我就带大家把这套SDK的目录结构彻底理清楚。这套SDK最厉害的地方在于它同时支持裸机、FreeRTOS和RT-Thread三种运行方式而且代码组织得非常清晰。理解了它的结构你就能快速找到需要的代码无论是移植到新板子还是开发新驱动都会顺手很多。咱们就从最顶层的目录开始一层层往下看。1. 顶层目录一览SDK的“全家福”当你解压Luban-Lite SDK后用tree -L 2命令或者直接在资源管理器里看会看到下面这样的结构。别慌我一个个给你解释。luban-lite ├── application // 应用入口和示例 ├── bsp // 板级支持包最核心的硬件驱动 ├── doc // 开发文档 ├── kernel // 三种内核裸机/FreeRTOS/RT-Thread ├── output // 编译输出目录 ├── packages // 组件包LVGL、LWIP等 ├── target // 具体开发板的配置 ├── toolchain // 工具链存放处 └── tools // 各种实用工具这个结构是不是有点像RT-Thread没错Luban-Lite确实借鉴了RT-Thread的一些优秀设计但又有自己的特色。最大的特色就是多内核支持——一套代码三种玩法。提示tree -L 2命令只显示前两级目录避免信息过载。想看更详细的结构可以把数字2改成3或4。2. 核心目录详解各司其职的模块2.1 application你的应用从这里开始application目录是写应用程序的地方。有意思的是它按内核分成了三个子目录application ├── baremetal // 裸机应用 │ ├── bootloader // 系统引导程序 │ └── helloworld // 裸机示例 ├── freertos // FreeRTOS应用目录结构类似 └── rt-thread // RT-Thread应用 └── helloworld // RT-Thread示例怎么用如果你写裸机程序就把main函数放在application/baremetal/下的某个工程里。如果用FreeRTOS就放在application/freertos/下。如果用RT-Thread就放在application/rt-thread/下。每个helloworld都是对应内核的入门示例编译运行一下就能验证开发环境是否搭好了。2.2 bsp硬件驱动的“大本营”bspBoard Support Package板级支持包是整个SDK最核心的部分所有跟硬件打交道的代码都在这里。它又细分为几个关键部分bsp ├── artinchip // ArtInChip SoC专属驱动 │ ├── drv // RTOS环境下的驱动 │ ├── drv_bare // 裸机专用驱动 │ ├── hal // 硬件抽象层 │ ├── include // 头文件 │ └── sys // 最小系统代码时钟、内存等 ├── common // 公共模块CRC32、分区表等 ├── peripheral // 外设模块驱动 │ ├── camera // 摄像头 │ ├── codec // 编解码器 │ ├── touch // 触摸屏 │ └── wireless // 无线模块 ├── examples_bare // 裸机示例代码 └── examples // RTOS示例代码 ├── test-uart // 串口测试 ├── test-adc // ADC测试 ├── test-can // CAN总线测试 └── ... // 其他外设测试重点理解artinchip目录这是针对衡山派使用的ArtInChip SoC的“专属司机”。drv和drv_bare的区别在于前者是为RTOS设计的可能有互斥锁、信号量等后者是给裸机用的更简单直接。hal层是对寄存器操作的封装让上层应用不用直接面对复杂的寄存器。peripheral目录这里放的是挂在SoC外部的外设驱动比如摄像头模块、Wi-Fi模块等。这些驱动通常通过I2C、SPI等总线与SoC通信。examples目录这是最好的学习资料每个外设都有对应的测试示例。比如你想知道串口怎么用直接看test-uart里的代码比看文档快多了。2.3 kernel三种内核自由选择这是Luban-Lite的特色所在——一套SDK支持三种运行时环境kernel ├── baremetal // 裸机内核接口封装 ├── freertos // FreeRTOS内核 ├── rt-thread // RT-Thread内核 └── common // 公共接口三种内核都能用的这意味着什么假设你公司有个产品最开始用裸机开发成本低后来功能复杂了要上RTOS。如果是传统方案你得重写大部分代码。但在Luban-Lite里你的硬件驱动bsp部分基本不用动只需要把应用从application/baremetal移到application/rt-thread然后重新编译就行了。common目录提供了统一的API接口让上层应用在不同内核下都能调用相同的函数当然底层实现不同。2.4 packages功能组件即插即用packages目录就像手机的“应用商店”里面有很多现成的功能组件packages ├── artinchip // ArtInChip官方组件 │ ├── aic-dm-apps // 设备管理应用 │ ├── lvgl-ui // LVGL图形界面 │ ├── ota // 空中升级 │ └── mpp // 媒体处理框架 └── third-party // 第三方组件 ├── lvgl // 轻量级图形库 ├── lwip // 轻量级TCP/IP协议栈 ├── littlefs // 掉电安全的文件系统 ├── cherryusb // USB协议栈 └── ... // 其他组件使用场景要做图形界面启用lvgl或lvgl-ui组件。要联网启用lwip组件。要做USB设备启用cherryusb。这些组件大多通过Kconfig配置系统来启用或禁用非常方便。而且很多组件来自RT-Thread的软件包生态经过充分测试稳定性有保障。2.5 target开发板的具体配置target目录是针对具体开发板的配置信息。衡山派有多个系列的开发板每个都有自己的配置target ├── configs // 方案配置文件 ├── d12x // D12x系列开发板 │ ├── common │ ├── demo68-nand // 使用NAND Flash的Demo板 │ ├── demo68-nor // 使用NOR Flash的Demo板 │ └── hmi-nor // HMI人机界面板 ├── d13x // D13x系列开发板 ├── d21x // D21x系列开发板 └── g73x // G73x系列开发板以d21x_demo128-nandD21x芯片128MB内存NAND Flash为例看看里面有什么d21x/demo128-nand ├── board.c // 板级初始化代码 ├── pinmux.c // 引脚复用配置这个很重要 ├── sys_clk.c // 系统时钟配置 ├── Kconfig.board // 板级Kconfig选项 ├── SConscript // 编译脚本 └── include // 板级头文件关键文件说明pinmux.c这个文件决定了每个引脚是作为GPIO、UART、I2C还是其他功能。如果你要改引脚功能就在这里改。我刚开始时就因为没配置这个调了半天串口没输出。board.c板子上电后最早执行的代码之一初始化DRAM、时钟等关键硬件。configs目录下的defconfig文件这是编译前的预设配置。比如d21x_demo128-nand_rt-thread_helloworld_defconfig就是为RT-Thread的helloworld示例预配好的选项。3. 其他重要目录3.1 doc开发文档文档不多但都很实用luban-lite_driver_development_guid.md驱动开发指南写驱动前必看。luban-lite_sdk_design.mdSDK设计说明了解整体架构。luban-lite_user_guid_linux.md和luban-lite_user_guid_windows.md不同系统的环境搭建指南。3.2 tools实用工具集tools ├── onestep.sh // Linux下的OneStep一键工具 ├── env // 环境工具类似RT-Thread env ├── script // 编译和打包脚本 └── toolchain // 工具链压缩包 ├── Xuantie-900-gcc-elf-newlib-x86_64-V2.6.1-20220906.tar.gz // Linux版 └── Xuantie-900-gcc-elf-newlib-mingw-V2.6.1-20220906.tar.gz // Windows版重点工具onestep.sh这是ArtInChip提供的命令行增强工具在Linux下用起来特别方便可以一键配置、编译、打包。工具链基于玄铁C906核心的GCC工具链编译时要用到。记得根据你的系统选择Linux版或Windows版。3.3 toolchain和outputtoolchain初始是空目录你需要把tools/toolchain/下的压缩包解压到这里编译时系统会从这里找编译器。output编译产生的所有文件.o、.a、.elf、.bin等都会放在这里。清空这个目录就相当于“make clean”。4. 实战从代码到固件的流程理解了目录结构咱们看看实际开发时这些目录是怎么协作的。假设我们要在衡山派D21x开发板上运行一个RT-Thread程序选择目标板进入target/configs/找到d21x_demo128-nand_rt-thread_helloworld_defconfig把它复制为.config。配置组件执行menuconfig命令如果有的话在packages里选择需要的组件比如LVGL、LWIP。编写应用在application/rt-thread/下创建你的应用目录或者直接修改helloworld。硬件适配如果要用到特殊引脚修改target/d21x/demo128-nand/pinmux.c。编译执行编译命令工具会读取.config确定配置从kernel/rt-thread/获取RT-Thread内核从bsp/获取硬件驱动从packages/获取启用的组件从target/d21x/demo128-nand/获取板级配置把所有东西编译链接输出到output/烧录把output/下的固件烧到开发板。5. 几个容易踩的坑根据我的使用经验有几个地方要特别注意1. 引脚配置问题这是新手最容易栽跟头的地方。比如你写了个程序控制GPIO结果没反应。先别怀疑人生去target/你的板子/pinmux.c里看看这个引脚是不是被配置成了其他功能比如UART。我在一个项目里就遇到过PA5引脚默认是SPI的时钟线我想当普通GPIO用结果忘了改pinmux调了一下午。2. 内核选择与驱动匹配bsp/artinchip/下有drv和drv_bare两个驱动目录。如果你用RT-Thread或FreeRTOS要用drv里的驱动如果用裸机要用drv_bare里的。混用可能会导致编译错误或运行时异常。3. 组件依赖有些组件有依赖关系。比如LVGL可能依赖特定的显示驱动LWIP依赖网络PHY驱动。启用组件时如果编译报错说缺少某些函数很可能是依赖的组件没启用。4. 配置文件管理SDK里有几种配置文件Kconfig图形化配置的选项定义defconfig预设的完整配置.config当前项目的实际配置由defconfig复制而来SConscript编译脚本改配置时建议先改menuconfig它会自动更新.config。不要直接手动改.config除非你知道自己在做什么。这套目录结构初看有点复杂但用习惯了就会发现它的巧妙之处。硬件相关的归bsp内核相关的归kernel组件归packages板级配置归target——各司其职条理清晰。特别是多内核支持的设计让项目在不同阶段可以灵活选择运行时环境不用重写底层代码。如果你刚开始接触建议按这个顺序熟悉先跑通application下的helloworld示例看看bsp/examples里的外设测试代码尝试启用packages里的某个组件比如littlefs最后再深入研究bsp/artinchip里的驱动实现有了对目录结构的整体认识无论是查找代码、调试问题还是移植到新板子你都知道该去哪里找什么了。