一、开发环境前置说明
AG32芯片官方SDK已预先完整移植FreeRTOS Kernel V10.4.6稳定版本，无需用户手动移植内核、适配底层驱动，极大降低RTOS开发门槛。
FreeRTOS内核源码默认存放路径：\AgRV_pio\packages\framework-agrv_freertos\
开发核心原则：用户无需修改、研读底层内核源码，仅需熟练掌握官方标准API的调用方法，即可快速完成多任务开发、定时器、信号量、队列等功能落地。
二、FreeRTOS工程快速验证(官方示例工程)
为快速确认AG32芯片FreeRTOS环境正常可用，可直接基于官方自带示例工程完成编译、烧录与功能验证，快速排查环境适配问题。
1. 工程打开方式
通过VS Code直接打开官方示例工程目录：\AgRV_pio\platforms\AgRV\examples\freeRTOS。该工程默认调用系统公共VE配置文件，无自定义VE工程文件，为方便后续二次开发、自定义引脚配置，建议手动创建专属VE配置文件。
2. 自定义VE配置文件搭建步骤
步骤1：拷贝基础配置文件，从示例工程路径中复制example_board.ve文件至当前工程根目录，作为自定义硬件配置模板。
步骤2：精简引脚配置，打开复制后的example_board.ve文件，仅保留系统时钟(clk)与LED指示灯引脚配置，删除其余冗余外设、引脚配置，保证工程简洁无冗余。
步骤3：绑定工程配置，打开工程根目录下platformio.ini文件，添加VE文件引用配置：board_logic.ve = example_board.ve，完成硬件配置绑定。
3. 工程编译与烧录验证
配置完成后，严格按照顺序执行烧录操作：先编译并烧录VE硬件配置文件，再编译并烧录工程代码。两次烧录均成功后，设备LED灯将周期性闪烁，代表AG32芯片FreeRTOS运行环境搭建成功、多任务调度正常。
三、官方示例工程精简适配(单Task最简工程)
官方默认示例工程集成了队列(xQueue)、信号量(xSemaphore)、任务(xTask)、软件定时器(xTimer)等全套FreeRTOS功能，适合功能学习。若仅需基础多任务运行，可精简为单任务闪烁LED最简工程，降低资源占用，适配基础开发场景。
重要注意事项：精简工程功能时，删除对应外设、内核对象的同时，必须同步删除Hook回调函数中对应的调用代码，否则会出现编译报错、程序运行异常等问题。
1. 精简后main函数标准代码
保留硬件初始化、任务创建、调度器启动核心逻辑，删除冗余功能，最简代码如下：
int main(void) {
prvSetupHardware(); // 底层硬件初始化(时钟、GPIO必备)
// 创建LED闪烁任务
xTaskCreate(led_task,
“led_task”,
configMINIMAL_STACK_SIZE,
NULL,
mainEVENT_SEMAPHORE_TASK_PRIORITY,
&xGPTimerTask);
vTaskStartScheduler(); // 启动FreeRTOS任务调度
for(;;);
}
其中 prvSetupHardware() 为系统必备硬件初始化函数，包含时钟、GPIO基础配置，不可删除，否则硬件无法正常工作。
2. 核心任务函数配置
在led_task任务函数中编写LED循环闪烁逻辑，实现基础任务调度效果。同时因精简后不再使用事件信号量(xEventSemaphore)，需清空 vApplicationTickHook 钩子函数中所有信号量相关操作代码，避免代码冗余与运行报错。
四、FreeRTOS静态内存分配开发适配
FreeRTOS默认采用动态内存分配方式，由系统自动申请、释放内存。若项目需要静态内存分配(固定内存地址、杜绝内存碎片、适配高可靠场景)，可通过开启对应宏定义实现。
1. 核心宏定义开启
在工程配置中开启静态分配宏：configSUPPORT_STATIC_ALLOCATION，开启后系统将关闭动态内存申请，所有任务、信号量、定时器需手动静态分配内存。
2. 必备钩子函数适配
开启静态分配模式后，必须新增两个适配钩子函数，否则工程无法编译通过，具体函数实现与配置细节可参考技术文档：https://blog.csdn.net/m0_46451722/article/details/113053257。
静态分配API用法与动态分配基本一致，核心区别为：静态模式需提前定义、分配好内存空间，再传入对应API参数中，完成任务与内核对象创建。
五、自建工程添加FreeRTOS完整步骤
用户新建空白工程后，可手动快速接入官方FreeRTOS组件，无需重新移植内核，具体适配步骤如下：
步骤1：工程配置文件引入FreeRTOS库
打开自建工程的platformio.ini配置文件，在库依赖配置项中添加FreeRTOS引用，多库依赖需采用「逗号+空格」格式分隔。
步骤2：校验硬件VE配置
确保工程VE配置文件中已完成系统时钟、LED引脚基础配置，保证硬件外设可正常初始化、工作。
步骤3：代码引入头文件与宏定义
在工程example.c或业务代码文件中，引入FreeRTOS核心头文件，同时根据开发需求引入对应功能宏定义，为任务创建、调度功能提供支撑。
步骤4：适配底层初始化与钩子函数
在工程代码中补充FreeRTOS运行所需的底层适配函数、基础钩子函数，完善工程运行环境。
步骤5：主函数启动RTOS调度
在main.c硬件初始化完成后，添加任务创建代码，调用 vTaskStartScheduler() 启动FreeRTOS任务调度。
步骤6：编译烧录验证
按照「编译烧录VE配置文件→编译烧录工程代码」的顺序操作，烧录完成后即可观察到LED闪烁，代表自建工程FreeRTOS适配成功。
六、开发注意事项总结
1. AG32官方SDK内置FreeRTOS V10.4.6版本，稳定性强，无需手动升级、移植，直接调用API即可开发;
2. 精简官方示例工程时，必须同步清理Hook函数冗余代码，避免编译报错、程序运行异常;
3. 静态内存分配模式需手动开启宏定义并补充适配钩子函数，适配高可靠、低碎片开发场景;
4. 所有FreeRTOS工程必须优先烧录VE硬件配置文件，再烧录业务代码，否则硬件配置不生效;
5. 自建工程引入FreeRTOS库时，严格遵循官方配置格式，多库依赖规范分隔，避免库加载失败。