Zephyr RTOS 中k_work_init_delayable 函数功能

k_work_init_delayable 函数的核心功能是：初始化一个“可延迟的工作项”（delayable work），将其设置为一个待执行的函数，但这个函数可以指定在未来的某个时间点执行，而不是立即提交到工作队列。它是 Zephyr 工作队列（Work Queue）机制中用于延迟/定时任务的关键组件。

1 工作队列概念

1.1 基本概念介绍

1）工作队列 (Work Queue)

Zephyr 的工作队列是一种将任务（一个函数）的执行上下文从中断服务例程（ISR）或高优先级线程卸载到低优先级线程的机制。

它由一个先入先出（FIFO）的队列和一个专门处理该队列的线程组成。

你提交一个“工作项”（work item），工作队列线程会在其上下文中执行你指定的函数。

2）可延迟工作项 (Delayable Work) vs 普通工作项 (Work)

普通工作项 (struct k_work)：使用 k_work_init 初始化。提交后，会尽快被工作队列线程执行（无延迟）。

可延迟工作项 (struct k_work_delayable)：使用 k_work_init_delayable 初始化。提交时，可以指定一个延迟时间。工作队列线程会等待这个延迟时间过后，才会执行该工作项。

1.2 工作队列特性

特性	描述
功能	初始化一个可以延迟指定时间后执行的任务。
本质	将一个函数（任务）与一个内置定时器绑定，并交由工作队列线程管理。
优势	实现延迟和周期性任务，节省系统资源，安全地从ISR卸载工作。
典型应用	按键防抖、轮询传感器、延迟初始化、非精确定时任务。

2 k_work_init_delayable函数介绍

1.1 函数原型

1）函数原型代码

#include <zephyr/kernel.h>

void k_work_init_delayable(struct k_work_delayable *dwork,
                           k_work_handler_t handler);

2）主要参数

参数 dwork：指向一个用户定义的 struct k_work_delayable 变量的指针。这个结构体包含了工作项信息和一个内置的定时器。
参数 handler：你的任务函数。其函数签名必须是：void handler(struct k_work *work)
- 注意：即使在可延迟工作项中，传入处理函数的参数类型仍然是 struct k_work *。你通常需要使用 CONTAINER_OF 宏来获取外层结构体的地址，从而访问你的自定义数据。

2.2 工作流程

初始化：使用 k_work_init_delayable 设置工作项和处理函数。此时工作项处于空闲状态。
提交（ scheduling ）：使用专门的提交函数（如 k_work_reschedule_for_queue，k_work_schedule_for_queue 等）将初始化好的可延迟工作项提交到某个工作队列。在提交时，必须指定延迟时间（例如 K_MSEC(100) 表示 100 毫秒后执行）。
等待与执行：工作队列系统内部管理一个定时器。定时器到期后，工作项会被自动加入到指定工作队列的末尾，等待线程调度执行。
取消（可选）：在延迟期间或工作项尚未被执行前，可以调用 k_work_cancel_delayable 来取消它的执行。

2.3 主要特点与用途

实现非精确定时任务：它不像硬件定时器那样精确，但非常适合执行那些不需要非常精确计时、且比较耗时的任务（例如，每隔几秒读取一次传感器数据）。
延迟执行/超时处理：例如，在按键检测中实现软件防抖（debounce）。当按键中断到来时，提交一个延迟 50ms 的工作项。如果 50ms 内再次收到中断，就取消上次的工作项并重新提交。只有在 50ms 内没有新中断，工作项才会执行，从而确认是一次有效的按键。
将任务从 ISR 中卸载：这是工作队列的核心目的。在 ISR 中，你不能执行冗长的操作。ISR 可以快速提交一个可延迟的工作项，让工作队列线程在之后去处理繁重的工作。
节省资源：相比于为每个需要定时执行的任务都创建一个内核线程（k_thread）和一个定时器（k_timer），使用可延迟工作项更加节省内核资源（内存、线程控制块等）。多个延迟任务可以共享同一个工作队列线程。

3 代码示例

以下是一个简单的示例，演示如何初始化并提交一个在 1 秒后打印消息的可延迟工作项。

#include <zephyr/kernel.h>
#include <zephyr/sys/printk.h>

/* 定义系统的工作队列 */
#define MY_WORK_Q sys_work_q

/* 定义并声明一个可延迟工作项 */
static struct k_work_delayable my_dwork;

/* 工作项的处理函数 */
void my_work_handler(struct k_work *work)
{
    /* 注意：参数是 k_work， 我们需要取得其外层的 k_work_delayable */
    struct k_work_delayable *dwork = k_work_delayable_from_work(work);

    printk("Hello from delayed work! Executed after 1 second.\n");

    // 可以在这里再次提交它，以实现周期性执行
    // k_work_reschedule_for_queue(&MY_WORK_Q, dwork, K_SECONDS(1));
}

void main(void)
{
    printk("Work Delayable Example Started.\n");

    /* 1. 初始化可延迟工作项，并将其与处理函数绑定 */
    k_work_init_delayable(&my_dwork, my_work_handler);

    /* 2. 提交工作项到系统工作队列，并设置延迟时间为1秒 */
    int ret = k_work_reschedule_for_queue(&MY_WORK_Q, &my_dwork, K_SECONDS(1));

    /* 检查提交是否成功 (0 表示成功) */
    if (ret != 0) {
        printk("Failed to schedule work!\n");
        return;
    }

    /* 主线程可以去做其他事情... */
    while (1) {
        k_sleep(K_FOREVER);
    }
}

4 重要注意事项

执行上下文：处理函数 handler 是在工作队列线程的上下文中执行的，其优先级由工作队列线程的优先级决定（例如，系统工作队列 sys_work_q 的优先级通常是负的，即协作式优先级）。
内存生命周期：你传递给处理函数的数据（通常通过 CONTAINER_OF 访问）必须在工作项执行期间一直有效。通常使用全局变量或动态分配的内存（k_malloc）。
取消与竞争：取消一个已经到期但尚未开始执行的工作项是可能的，但取消一个正在执行的工作项是不可能的。k_work_cancel_delayable 会等待正在执行的工作项完成。
提交函数：除了 k_work_reschedule_for_queue，还有 k_work_schedule_for_queue 等函数，它们在不同情况下使用（例如是相对当前时间延迟还是绝对时间点）。