Zephyr最简工程配置指南

Zephyr最简工程配置指南x86平台QEMU运行引言在Zephyr RTOS开发中配置一个最简工程是学习和测试的最佳起点。本文将详细介绍如何配置一个最小化的Zephyr工程仅使用x86平台并在QEMU模拟器中运行。这种配置方式具有以下优势快速入门无需硬件设备即可体验Zephyr资源高效仅包含必要组件易于调试QEMU提供完整的调试支持跨平台可在Windows、Linux、macOS上运行一、环境准备1.1 安装必要依赖# Ubuntu/Debian系统sudoapt-getupdatesudoapt-getinstall-y\git\cmake\ninja-build\gperf\ccache\python3\python3-pip\python3-venv\device-tree-compiler\qemu-system-x86# QEMU x86模拟器# macOS系统使用Homebrewbrewinstallgitcmake ninja gperf ccache python dtc qemu# Windows系统# 建议使用WSL2或直接安装Zephyr SDK1.2 安装West工具# 安装Westpipinstallwest# 验证安装west--version1.3 获取Zephyr源码最小化# 创建工作目录mkdir-p~/zephyrprojectcd~/zephyrproject# 初始化West项目只获取核心仓库west init-mhttps://github.com/zephyrproject-rtos/zephyr--mrmain# 配置只下载必要组件west config manifest.project-filter -- -hal_* -lib_* -modules_*# 更新代码仅核心仓库west update--narrow# 安装Python依赖pipinstall-rzephyr/scripts/requirements.txt二、最简工程结构2.1 创建工程目录# 创建工程目录mkdir-p~/zephyr-appcd~/zephyr-app# 创建必要文件touchCMakeLists.txt prj.conf src/main.c2.2 工程文件结构zephyr-app/ ├── CMakeLists.txt # CMake配置文件 ├── prj.conf # Kconfig配置文件 └── src/ └── main.c # 主程序入口2.3 CMakeLists.txt配置# CMakeLists.txt # 最低CMake版本要求 cmake_minimum_required(VERSION 3.20.0) # 包含Zephyr构建系统 find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) # 项目名称 project(my_minimal_app) # 添加源文件 target_sources(app PRIVATE src/main.c)2.4 prj.conf配置最简配置# prj.conf - 最简配置 # 基础配置 CONFIG_SOC_POSIXy CONFIG_BOARD_QEMU_X86y # 内核配置 CONFIG_KERNELy CONFIG_INIT_STACKSy # 控制台输出 CONFIG_CONSOLEy CONFIG_SERIALy CONFIG_UART_CONSOLEy # 调试配置 CONFIG_DEBUGy CONFIG_DEBUG_OPTIMIZATIONSy # 系统时钟 CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC100000000 # 定时器 CONFIG_TIMERy CONFIG_SYS_CLOCK_TICKS_PER_SEC100三、编写最简应用代码3.1 main.c 最小实现/* src/main.c - 最简Zephyr应用 */#includezephyr/kernel.h#includezephyr/sys/printk.h/* 定义线程栈大小 */#defineSTACKSIZE1024/* 定义线程优先级 */#definePRIORITY7/* 线程函数 */voidmain_thread(void){intcount0;while(1){printk(Hello Zephyr! Count: %d\n,count);k_msleep(1000);}}/* 定义线程 */K_THREAD_DEFINE(main_tid,STACKSIZE,main_thread,NULL,NULL,NULL,PRIORITY,0,K_NO_WAIT);/* 主入口函数 */voidmain(void){printk(Zephyr minimal app started!\n);}3.2 代码解释部分说明#include zephyr/kernel.h内核API头文件#include zephyr/sys/printk.h打印函数头文件K_THREAD_DEFINE定义静态线程k_msleep()毫秒级延时函数printk()内核打印函数四、编译配置4.1 设置环境变量# 设置Zephyr基础路径exportZEPHYR_BASE~/zephyrproject/zephyr# 设置SDK路径如果需要# export ZEPHYR_SDK_INSTALL_DIR/opt/zephyr-sdk-0.17.2# 验证设置echo$ZEPHYR_BASE4.2 编译命令# 进入工程目录cd~/zephyr-app# 编译指定qemu_x86目标板west build-bqemu_x86.# 查看编译结果ls-labuild/zephyr/4.3 编译输出# 编译成功输出示例[100%]Linking C executable zephyr/zephyr.elf[100%]Built target zephyr五、在QEMU中运行5.1 运行命令# 方式1使用west run命令west build-trun# 方式2手动运行QEMUqemu-system-i386\-cpuqemu32\-nographic\-kernelbuild/zephyr/zephyr.elf\-machinepc# 方式3带调试端口运行qemu-system-i386\-cpuqemu32\-nographic\-kernelbuild/zephyr/zephyr.elf\-machinepc\-s-S5.2 运行输出# 预期输出SeaBIOS(version rel-1.16.0-0-gd239552ce722-prebuilt.qemu.org)Booting from ROM..*** Booting Zephyr OS build zephyr-v3.5.0-xxx *** Zephyr minimal app started!Hello Zephyr!Count:0Hello Zephyr!Count:1Hello Zephyr!Count:2...5.3 退出QEMU# 按 CtrlA 然后按 X 退出QEMU六、调试配置6.1 使用GDB调试# 启动QEMU并监听调试端口qemu-system-i386\-cpuqemu32\-nographic\-kernelbuild/zephyr/zephyr.elf\-machinepc\-s-S# 启动GDBgdb-multiarch build/zephyr/zephyr.elf# GDB命令(gdb)target remote localhost:1234(gdb)breakmain(gdb)continue(gdb)info threads(gdb)next(gdb)print count6.2 VS Code调试配置创建.vscode/launch.json{version:0.2.0,configurations:[{name:Zephyr QEMU Debug,type:cppvsdbg,request:launch,program:${workspaceFolder}/build/zephyr/zephyr.elf,args:[],stopAtEntry:false,cwd:${workspaceFolder},environment:[],externalConsole:false,preLaunchTask:build,MIMode:gdb,miDebuggerPath:gdb-multiarch,miDebuggerServerAddress:localhost:1234,setupCommands:[{description:Enable pretty-printing for gdb,text:-enable-pretty-printing,ignoreFailures:true}]}]}七、进阶配置7.1 添加shell支持修改prj.conf# 添加shell支持 CONFIG_SHELLy CONFIG_SHELL_BACKEND_SERIALy CONFIG_SHELL_PROMPTzephyr 运行效果*** Booting Zephyr OS build zephyr-v3.5.0-xxx *** Zephyr minimal app started!zephyrhelpAvailable commands:help:print thishelpkernel:kernel commands version:print kernel version zephyrkernel threads Threads: 0x200003e0 main_tidprio70x20000100 idleprio31zephyr7.2 添加定时器功能/* 在main.c中添加定时器 */#includezephyr/kernel.h#includezephyr/sys/printk.h#defineTIMER_STACKSIZE512#defineTIMER_PRIORITY5structk_timermy_timer;voidtimer_expiry_fn(structk_timer*timer_id){printk(Timer expired!\n);}voidtimer_stop_fn(structk_timer*timer_id){printk(Timer stopped!\n);}K_TIMER_DEFINE(my_timer,timer_expiry_fn,timer_stop_fn);voidmain(void){printk(Starting timer...\n);k_timer_start(my_timer,K_SECONDS(1),K_SECONDS(1));while(1){k_msleep(500);}}7.3 添加线程间通信/* 添加信号量示例 */#includezephyr/kernel.h#includezephyr/sys/printk.h#defineSTACKSIZE1024#definePRIORITY7K_SEM_DEFINE(my_sem,0,1);voidthread1(void){while(1){printk(Thread 1: Waiting for semaphore\n);k_sem_take(my_sem,K_FOREVER);printk(Thread 1: Got semaphore\n);k_msleep(1000);}}voidthread2(void){while(1){printk(Thread 2: Giving semaphore\n);k_sem_give(my_sem);k_msleep(2000);}}K_THREAD_DEFINE(thread1_tid,STACKSIZE,thread1,NULL,NULL,NULL,PRIORITY,0,K_NO_WAIT);K_THREAD_DEFINE(thread2_tid,STACKSIZE,thread2,NULL,NULL,NULL,PRIORITY1,0,K_NO_WAIT);voidmain(void){printk(Thread communication example\n);}八、常见问题与解决方案8.1 QEMU未找到问题qemu-system-i386: command not found解决# Ubuntu/Debiansudoapt-getinstallqemu-system-x86# macOSbrewinstallqemu# 验证安装qemu-system-i386--version8.2 编译错误 - 缺少工具链问题arm-zephyr-eabi-gcc: command not found解决# 对于x86平台通常不需要额外工具链# 如果需要SDK安装Zephyr SDKwgethttps://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.17.2/zephyr-sdk-0.17.2-setup.runchmodx zephyr-sdk-0.17.2-setup.run ./zephyr-sdk-0.17.2-setup.run --include-i686 --include-qemu8.3 链接错误 - undefined reference问题undefined reference to printk解决# 在prj.conf中添加 CONFIG_CONSOLEy CONFIG_SERIALy CONFIG_UART_CONSOLEy8.4 QEMU运行无输出问题运行QEMU后没有输出解决# 确保使用-nographic选项qemu-system-i386-nographic-kernelbuild/zephyr/zephyr.elf# 检查串口配置# 在prj.conf中添加CONFIG_UART_CONSOLE_ON_DEV_NAMEuart0九、最简工程模板9.1 完整工程打包# 创建模板目录结构mkdir-pzephyr-minimal-app/{src,config}cdzephyr-minimal-app# 创建CMakeLists.txtcatCMakeLists.txtEOF cmake_minimum_required(VERSION 3.20.0) find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE}) project(minimal_app) target_sources(app PRIVATE src/main.c) EOF# 创建prj.confcatprj.confEOF CONFIG_SOC_POSIXy CONFIG_BOARD_QEMU_X86y CONFIG_KERNELy CONFIG_INIT_STACKSy CONFIG_CONSOLEy CONFIG_SERIALy CONFIG_UART_CONSOLEy CONFIG_DEBUGy CONFIG_DEBUG_OPTIMIZATIONSy CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC100000000 CONFIG_TIMERy CONFIG_SYS_CLOCK_TICKS_PER_SEC100 EOF# 创建main.ccatsrc/main.cEOF #include zephyr/kernel.h #include zephyr/sys/printk.h #define STACKSIZE 1024 #define PRIORITY 7 void main_thread(void) { int count 0; while (1) { printk(Hello Zephyr! Count: %d\n, count); k_msleep(1000); } } K_THREAD_DEFINE(main_tid, STACKSIZE, main_thread, NULL, NULL, NULL, PRIORITY, 0, K_NO_WAIT); void main(void) { printk(Zephyr minimal app started!\n); } EOFechoMinimal Zephyr app created successfully!9.2 使用模板# 使用模板创建工程mkdir-p~/myappcd~/myappcp-r/path/to/zephyr-minimal-app/*.# 设置环境变量exportZEPHYR_BASE~/zephyrproject/zephyr# 编译运行west build-bqemu_x86.west build-trun十、性能优化建议10.1 优化编译配置# prj.conf - 优化配置 # 关闭调试信息发布版本 CONFIG_DEBUGn CONFIG_DEBUG_OPTIMIZATIONSn CONFIG_OPTIMIZE_FOR_SIZEy # 关闭不需要的功能 CONFIG_ASSERTn CONFIG_LOGn CONFIG_SHELLn # 优化内存 CONFIG_HEAP_MEM_POOL_SIZE2048 CONFIG_KERNEL_MEM_POOL_SIZE102410.2 优化代码// 优化后的main.c#includezephyr/kernel.h#includezephyr/sys/printk.h#defineSTACKSIZE512// 减小栈大小#definePRIORITY7voidmain_thread(void){staticintcount;// 使用静态变量节省栈空间for(;;){printk(Count: %d\n,count);k_sleep(K_MSEC(1000));// 使用k_sleep替代k_msleep}}K_THREAD_DEFINE(main_tid,STACKSIZE,main_thread,NULL,NULL,NULL,PRIORITY,0,K_NO_WAIT);voidmain(void){}// 简化主函数结束语通过本文的介绍您已经掌握了如何配置一个最简的Zephyr工程步骤内容环境准备安装QEMU、West工具工程结构CMakeLists.txt prj.conf src/main.c编译命令west build -b qemu_x86 .运行命令west build -t run调试方法GDB QEMU远程调试最简工程的优势快速上手无需硬件设备QEMU即可运行资源高效只包含必要组件编译速度快易于学习代码量少便于理解Zephyr核心概念可扩展性可以逐步添加功能建议在掌握最简工程后尝试添加更多功能Shell交互定时器线程间通信文件系统网络功能参考资料Zephyr官方文档Zephyr快速入门QEMU官方文档Zephyr GitHub仓库