1. 项目概述

MicroTasks 是一个面向资源受限嵌入式系统的轻量级协作式任务调度与消息传递库。其设计目标并非替代完整RTOS（如FreeRTOS、Zephyr或ThreadX），而是为无OS环境（Bare-Metal）或极简运行时场景提供可预测、零动态内存分配、无中断抢占依赖的确定性并发模型。该库不引入任何内核态/用户态切换、不使用SysTick以外的硬件定时器、不依赖堆内存管理，所有任务控制块（TCB）、消息队列缓冲区、调度器状态均在编译期静态声明，完全规避运行时内存碎片与分配失败风险——这一特性使其特别适用于安全关键型应用（如工业传感器节点、电池供电的IoT终端、汽车ECU基础服务模块）以及对代码体积极度敏感的8/16位MCU平台（如STM8、MSP430、PIC18）。

项目名称“MicroTasks”直指其核心定位： 微任务 （Micro-Task），即每个任务单元仅承担单一职责、执行时间可控（通常<100μs）、无阻塞等待、通过显式让出（yield）交出CPU控制权。这种设计摒弃了传统抢占式多任务中复杂的上下文保存/恢复、优先级继承、死锁检测等开销，将调度复杂度降至最低，同时保证系统行为完全可静态分析——开发者可通过阅读源码与配置即可100%确定任意时刻哪个任务正在运行、消息何时被投递、最大响应延迟是多少。

1.1 协作式调度的本质与工程价值

协作式（Co-operative）调度与抢占式（Pre-emptive）调度的根本区别在于 控制权转移的触发机制 ：

• 抢占式 ：由硬件定时器中断强制打断当前任务，调度器根据优先级/时间片决定下一个运行任务。优点是实时响应性高；缺点是上下文切换开销大、中断嵌套深度不可控、调试困难、且需严格保护临界区（如禁用全局中断或使用信号量）。
• 协作式 ：任务必须 主动调用 microtask_yield() 或 microtask_delay() 显式放弃CPU。调度器仅在这些函数中执行任务切换。优点是零中断干扰、无栈溢出风险（因无中断嵌套）、无临界区竞争（除非显式共享数据）、执行路径完全线性可追踪。

在嵌入式底层开发中，协作式模型的价值常被低估。实际工程中，大量应用场景天然适合协作式：

• 传感器数据周期性采集（每100ms读取温湿度+ADC值）
• LED状态机驱动（呼吸灯、故障闪烁模式）
• UART命令解析与响应（接收一帧AT指令后处理并回传）
• 简单PID控制循环（每5ms执行一次计算与PWM更新）

这些任务本身无需毫秒级抢占响应，其逻辑天然具备“执行-等待-再执行”的协作特征。MicroTasks正是将这一模式抽象为标准化接口，避免开发者重复编写状态机轮询代码，同时杜绝因 while(1) 死循环导致的CPU独占问题。

2. 核心架构与数据结构

MicroTasks 的架构极简，仅包含三个核心组件： 任务控制块（TCB）数组、就绪队列、消息队列池 。所有结构体均采用C99标准定义，无编译器扩展依赖，确保跨平台兼容性。

2.1 任务控制块（TCB）

每个任务由 microtask_t 结构体唯一标识，其定义如下：

typedef struct {
    const char* name;                    // 任务名称（仅用于调试，可设为NULL）
    void (*func)(void*);                 // 任务主函数指针
    void* arg;                           // 传递给func的参数
    uint8_t state;                       // 当前状态：MICROTASK_STATE_READY/RUNNING/BLOCKED
    uint32_t delay_ticks;                // 延迟计数器（单位：调度tick）
    struct microtask_s* next;            // 就绪队列链表指针
} microtask_t;

关键字段说明：

• func 与 arg 构成任务入口： func(arg) 即为任务体。此设计允许同一函数通过不同 arg 实现参数化任务（如多个LED控制任务复用同一闪烁函数）。
• state 仅含三种状态，无 suspended 或 deleted 等复杂状态，极大简化状态机逻辑。
• delay_ticks 用于实现 microtask_delay() ：每次调度tick到来时，就绪队列中所有 delay_ticks > 0 的任务将其减1；减至0时置为 READY 状态。 注意：此延迟非绝对时间，而是相对调度tick次数 ，实际时间取决于 microtask_tick() 的调用频率。

2.2 就绪队列与调度器

就绪队列是一个单向链表，头结点为全局变量 g_ready_list 。调度器不维护优先级，采用 轮询（Round-Robin）策略 ：每次 microtask_schedule() 调用时，从 g_ready_list 头部取出第一个任务执行，执行完毕后将其移至链表尾部。此设计保证所有就绪任务获得均等CPU时间片，避免饥饿问题。

调度器主循环逻辑（典型Bare-Metal main() 中）：

int main(void) {
    HAL_Init();
    SystemClock_Config();
    
    // 初始化MicroTasks（注册任务、设置tick频率）
    microtask_init();
    
    // 启动调度器
    while (1) {
        microtask_schedule();  // 执行一次调度：运行当前就绪队列首任务
        HAL_Delay(1);          // 人为制造1ms tick间隔（实际应由SysTick中断驱动）
    }
}

2.3 消息队列池

消息传递通过 microtask_msg_t 结构体实现，其定义为：

typedef struct {
    void* data;           // 指向消息有效载荷的指针
    size_t len;           // 消息长度（字节）
    uint8_t priority;     // 优先级（0=最低，255=最高，当前未使用，预留）
} microtask_msg_t;

消息队列本身是固定大小的环形缓冲区，由 microtask_queue_t 管理：

typedef struct {
    microtask_msg_t* buffer;   // 指向预分配的消息缓冲区首地址
    uint16_t size;             // 缓冲区总容量（消息个数）
    uint16_t head;             // 写入位置索引
    uint16_t tail;             // 读取位置索引
    uint16_t count;            // 当前消息数量
} microtask_queue_t;

关键约束 ：消息内容（ data 指向的数据）必须由发送方 保证生命周期覆盖接收方处理完成 。MicroTasks不复制消息数据，仅传递指针。这意味着：

• 若发送栈变量地址，接收任务必须在发送任务返回前完成处理；
• 推荐做法：使用静态缓冲区或DMA传输完成后的内存池。

3. API详解与工程化使用

MicroTasks 提供7个核心API，全部为 static inline 或简单函数，无隐藏副作用。以下按使用频率与重要性排序解析。

3.1 任务注册与初始化

void microtask_init(void);
void microtask_create(microtask_t* task, 
                      const char* name, 
                      void (*func)(void*), 
                      void* arg);

• microtask_init() ：必须在 main() 中首次调用 microtask_schedule() 前执行。其内部完成：
  • 将所有已注册任务（通过 microtask_create 声明）加入 g_ready_list
  • 初始化全局调度计数器
• microtask_create() ： 非动态创建，仅为TCB赋值并链入就绪队列 。典型用法：

  // 静态声明TCB（推荐：避免栈分配不确定性）
  static microtask_t led_task;
  static microtask_t sensor_task;
  
  void led_handler(void* arg) { /* LED控制逻辑 */ }
  void sensor_handler(void* arg) { /* 传感器采集逻辑 */ }
  
  int main(void) {
      // ... 硬件初始化 ...
      
      // 注册任务
      microtask_create(&led_task, "LED", led_handler, (void*)GPIOA);
      microtask_create(&sensor_task, "SENSOR", sensor_handler, NULL);
      
      microtask_init(); // 此时两个任务均进入READY状态
      
      while(1) {
          microtask_schedule();
      }
  }
  

3.2 调度与让出控制

void microtask_schedule(void);
void microtask_yield(void);
void microtask_delay(uint32_t ticks);

• microtask_schedule() ： 调度器主入口 。执行流程：
  1. 若 g_ready_list 为空，直接返回（空闲循环）
  2. 取出队首任务，将其 state 置为 RUNNING
  3. 调用 task->func(task->arg)
  4. 任务函数返回后，若其 state 仍为 RUNNING （即未调用 yield 或 delay ），则置为 READY 并移至队尾；若为 BLOCKED ，则不移入队列
• microtask_yield() ： 立即让出CPU 。将当前运行任务 state 置为 READY ，并触发一次 microtask_schedule() （即立刻切换到下一任务）。适用于任务已完成部分工作，但需等待外部事件（如GPIO中断标志）时主动释放CPU。
• microtask_delay(ticks) ： 延迟ticks个调度周期后再运行 。将当前任务 delay_ticks 设为 ticks ， state 置为 BLOCKED 。注意：此函数 不阻塞当前任务 ，而是立即将控制权交还调度器，因此调用后任务函数必须立即返回，否则延迟无效。

3.3 消息队列操作

bool microtask_queue_create(microtask_queue_t* q, 
                            microtask_msg_t* buffer, 
                            uint16_t size);
bool microtask_queue_send(microtask_queue_t* q, 
                          void* data, 
                          size_t len, 
                          uint32_t timeout_ms);
bool microtask_queue_receive(microtask_queue_t* q, 
                             microtask_msg_t* msg, 
                             uint32_t timeout_ms);

• microtask_queue_create() ：初始化队列。 buffer 必须是 size 个 microtask_msg_t 结构体的连续数组。例如：

  #define MSG_QUEUE_SIZE 4
  static microtask_msg_t msg_buffer[MSG_QUEUE_SIZE];
  static microtask_queue_t uart_rx_queue;
  
  microtask_queue_create(&uart_rx_queue, msg_buffer, MSG_QUEUE_SIZE);
  

• microtask_queue_send() ：发送消息。 timeout_ms 参数在此版本中 恒为0 （无阻塞发送），若队列满则返回 false 。 工程实践中，应在发送前检查队列剩余空间 ：

  if (uart_rx_queue.count < uart_rx_queue.size) {
      microtask_queue_send(&uart_rx_queue, rx_buffer, rx_len, 0);
  } else {
      // 处理溢出：丢弃、告警或触发复位
      HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
  }
  

• microtask_queue_receive() ：接收消息。 timeout_ms 同样为0，队列空则立即返回 false 。典型接收任务结构：

  void uart_handler(void* arg) {
      microtask_msg_t msg;
      while (microtask_queue_receive(&uart_rx_queue, &msg, 0)) {
          // 解析msg.data中的UART数据
          parse_uart_command(msg.data, msg.len);
      }
      // 无消息时，任务自然退出，CPU交还调度器
  }
  

4. 典型工程应用示例

4.1 基于HAL的UART命令处理器

场景：STM32F4通过USART1接收ASCII命令（如"LED ON"、"TEMP?"），解析后控制外设并回传结果。

// 全局消息队列
#define CMD_QUEUE_SIZE 8
static microtask_msg_t cmd_buffer[CMD_QUEUE_SIZE];
static microtask_queue_t cmd_queue;

// UART接收完成回调（HAL_UART_RxCpltCallback）
void HAL_UART_RxCpltCallback(UART_HandleTypeDef *huart) {
    if (huart == &huart1) {
        // 将接收到的rx_buffer作为消息发送
        microtask_msg_t msg = { .data = rx_buffer, .len = RX_BUFFER_SIZE };
        microtask_queue_send(&cmd_queue, rx_buffer, RX_BUFFER_SIZE, 0);
        // 重新启动DMA接收
        HAL_UART_Receive_DMA(&huart1, rx_buffer, RX_BUFFER_SIZE);
    }
}

// 命令处理任务
void cmd_processor_task(void* arg) {
    microtask_msg_t msg;
    char* cmd_str;
    
    // 非阻塞接收所有待处理命令
    while (microtask_queue_receive(&cmd_queue, &msg, 0)) {
        cmd_str = (char*)msg.data;
        
        if (strncmp(cmd_str, "LED ON", 6) == 0) {
            HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_SET);
        } else if (strncmp(cmd_str, "LED OFF", 7) == 0) {
            HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_RESET);
        } else if (strncmp(cmd_str, "TEMP?", 5) == 0) {
            float temp = read_temperature();
            char resp[32];
            snprintf(resp, sizeof(resp), "TEMP:%.2f\r\n", temp);
            HAL_UART_Transmit(&huart1, (uint8_t*)resp, strlen(resp), HAL_MAX_DELAY);
        }
    }
}

// 在main()中注册
microtask_create(&cmd_task, "CMD_PROC", cmd_processor_task, NULL);
microtask_queue_create(&cmd_queue, cmd_buffer, CMD_QUEUE_SIZE);

4.2 低功耗传感器采样任务

场景：每5秒唤醒一次，读取BME280传感器，通过LoRaWAN发送，随后进入STOP模式。

void sensor_task(void* arg) {
    static uint32_t last_wake_time = 0;
    uint32_t now = HAL_GetTick();
    
    // 使用delay实现精确周期（假设microtask_tick()每1ms调用一次）
    if (now - last_wake_time >= 5000) {
        last_wake_time = now;
        
        // 1. 唤醒传感器
        bme280_wake();
        HAL_Delay(10); // 等待稳定
        
        // 2. 读取数据
        float temp, hum, pres;
        bme280_read(&temp, &hum, &pres);
        
        // 3. 准备LoRa消息（静态缓冲区）
        static uint8_t lora_payload[64];
        encode_sensor_data(lora_payload, temp, hum, pres);
        
        // 4. 发送（非阻塞，假设有lora_send_async）
        lora_send_async(lora_payload, sizeof(lora_payload));
        
        // 5. 进入低功耗（关键：在delay前调用，确保调度器能休眠）
        HAL_PWR_EnterSTOPMode(PWR_LOWPOWERREGULATOR_ON, PWR_STOPENTRY_WFI);
    }
    
    // 任务末尾调用delay，使调度器在下次tick时再次检查时间
    microtask_delay(1); // 1ms后重试
}

// 注册任务（无需高优先级，因周期长）
microtask_create(&sensor_task_obj, "SENSOR", sensor_task, NULL);

5. 配置与移植指南

5.1 关键配置选项

MicroTasks 通过 microtasks_config.h 头文件提供编译期配置，主要选项包括：

宏定义	默认值	说明
MICROTASKS_TICK_MS	1	调度tick周期（毫秒），决定 microtask_delay() 的时间基准。需与 microtask_tick() 调用频率严格一致。
MICROTASKS_MAX_TASKS	8	最大支持任务数。影响 g_ready_list 大小及内存占用。
MICROTASKS_ENABLE_DEBUG	0	是否启用调试信息（如任务名打印）。生产环境建议关闭。

配置示例（针对超低功耗应用） ：

// microtasks_config.h
#define MICROTASKS_TICK_MS    10    // 改为10ms tick，降低调度开销
#define MICROTASKS_MAX_TASKS  4     // 减少TCB内存占用
#define MICROTASKS_ENABLE_DEBUG 0   // 关闭调试

5.2 移植到不同平台

MicroTasks 仅依赖两个底层接口，移植只需实现它们：

1. microtask_tick() ：必须由硬件定时器（如SysTick）以 MICROTASKS_TICK_MS 频率调用。在STM32 HAL中：

   void SysTick_Handler(void) {
       HAL_IncTick();
       microtask_tick(); // 此处插入MicroTasks tick
   }
   

2. microtask_get_tick_count() （可选）：若需在任务中获取绝对时间戳（如计算超时），需提供该函数。默认实现为 HAL_GetTick() ，但可替换为更高精度的定时器读数。

无SysTick平台移植 （如某些8051 MCU）：

• 使用通用定时器中断，在中断服务程序中调用 microtask_tick()
• 确保中断服务程序执行时间远小于 MICROTASKS_TICK_MS ，避免tick丢失

6. 与主流嵌入式生态的集成

6.1 与FreeRTOS共存

MicroTasks 可作为FreeRTOS的一个任务运行，处理对实时性要求不高的后台任务，从而减轻RTOS调度负担：

// FreeRTOS任务中运行MicroTasks调度器
void microtasks_wrapper_task(void* arg) {
    microtask_init();
    
    for(;;) {
        // 在FreeRTOS任务中，以固定频率调用MicroTasks调度
        microtask_schedule();
        vTaskDelay(pdMS_TO_TICKS(1)); // 1ms间隔
    }
}

// 创建FreeRTOS任务
xTaskCreate(microtasks_wrapper_task, "MICROTASKS", 256, NULL, 1, NULL);

6.2 与CMSIS-RTOS v2 API对齐

为便于迁移，MicroTasks 的API命名与CMSIS-RTOS v2保持风格一致：

• microtask_create() ≈ osThreadNew()
• microtask_delay() ≈ osDelay()
• microtask_queue_send/receive() ≈ osMessageQueuePut/Get()

这使得熟悉CMSIS标准的开发者能快速上手，且未来可平滑迁移到完整RTOS。

7. 性能与资源占用分析

在STM32F030F4P6（Cortex-M0, 48MHz, 4KB SRAM）上实测：

• 代码体积 ：纯C实现，启用O2优化后约1.2KB Flash
• RAM占用 ：每个TCB占用24字节，4个任务+1个消息队列（8消息×12字节）共约200字节
• 最大调度延迟 ：单次 microtask_schedule() 执行时间<2.5μs（含函数调用开销），远低于1ms tick周期，确保调度确定性

对比FreeRTOS最小配置 （仅 vTaskStartScheduler +1个空闲任务）：

• Flash：~4.5KB
• RAM：~300字节（仅TCB）
• 调度延迟：~5μs（含上下文切换）

MicroTasks在资源节省上优势显著，尤其适合Flash<16KB、RAM<2KB的超低成本MCU。

8. 实践陷阱与最佳实践

8.1 常见陷阱

• 任务永不返回 ：若任务函数中存在 while(1) 且未调用 yield 或 delay ，将导致调度器冻结。 必须确保每个任务函数最终返回 。
• 消息指针悬空 ：发送栈变量地址后任务返回，接收任务读取时数据已失效。 始终使用静态/全局缓冲区或堆内存（若可用） 。
• tick频率不匹配 ： MICROTASKS_TICK_MS 设为1，但 microtask_tick() 每10ms才调用一次，导致 delay(10) 实际耗时100ms。 必须严格校准硬件定时器与配置宏 。

8.2 工程最佳实践

• 任务粒度控制 ：单个任务执行时间建议<50μs。若逻辑复杂，拆分为多个小任务并通过消息通信。
• 中断处理原则 ：中断服务程序（ISR）中 只做最简操作 （如置标志、发消息），繁重处理放入任务中。例如：

  // ISR中
  BaseType_t xHigherPriorityTaskWoken = pdFALSE;
  microtask_msg_t msg = {.data = &event_id, .len = sizeof(event_id)};
  microtask_queue_send_from_isr(&event_queue, &msg, &xHigherPriorityTaskWoken);
  portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
  

• 调试技巧 ：启用 MICROTASKS_ENABLE_DEBUG 后，在 microtask_schedule() 中添加 printf("Running %s\r\n", current_task->name) ，配合串口调试助手观察任务切换序列。

MicroTasks的价值不在于功能丰富，而在于以极致的简洁性解决嵌入式开发中最普遍的并发需求。当项目需求明确为“几个周期性任务+简单消息传递”，且资源预算紧张时，它比引入完整RTOS更符合KISS（Keep It Simple, Stupid）原则。真正的工程智慧，往往体现在对工具适用边界的清醒认知，而非盲目追求技术先进性。