1. 应用怎样留下事件入口#

Paipop 应用把生命周期回调和系统事件回调放入同一张操作表：

1
static const struct application_operation paipop_toy_ops = {
2
    .state_machine = paipop_toy_state_machine,
3
    .event_handler = paipop_toy_event_handler,
4
};
5

6
REGISTER_APPLICATION(paipop_toy) = {
7
    .name = "paipop_toy",
8
    .ops = &paipop_toy_ops,
9
    .state = APP_STA_DESTROY,
10
};

其中 .state_machine 接收 APP_STA_START、APP_STA_STOP 等应用生命周期状态，.event_handler 接收应用运行期间的系统事件。后者的实现很薄：

1
static int paipop_toy_event_handler(struct application *app,
2
                                    struct sys_event *event)
3
{
4
    if (!event) {
5
        return false;
6
    }
7

8
    return paipop_events_handle_sys_event(event);
9
}

源码位置：apps/Paipop_YP_Toy/app_main.c:95-161。

它不是由项目代码反复手动调用的“收集函数”。项目只是把函数地址注册到操作表；事件到达当前应用时，杰理框架再通过该函数指针调用它。它自身也不保存事件，只把这封“信”交给项目的分类层。

这两个参数也要分清：app 是 app_core 提供的当前 paipop_toy 应用对象，当前实现没有用到它；event 是事件框架交付的外层 struct sys_event，不是按键驱动里局部变量 e 的地址。后面要先检查 event->type 再决定 event->payload 的结构类型；如果生产者不完全可信，健壮代码还应检查 event->len 是否足以容纳目标结构。

2. 从局部 e/dev 到 event->payload：装包、投递与拆包#

杰理定义的系统事件结构是：

1
#define SYS_KEY_EVENT       0x0001
2
#define SYS_TOUCH_EVENT     0x0002
3
#define SYS_DEVICE_EVENT    0x0004
4
#define SYS_NET_EVENT       0x0008
5
#define SYS_BT_EVENT        0x0010
6

7
struct sys_event {
8
    u16 type;
9
    u8 from;
10
    u8 len;
11
    u8 payload[0];
12
};

源码位置：杰理 SDK include_lib/utils/event/event.h:9-25。

可以把它理解成统一信封：

• type 表示大类，例如按键、网络或设备事件；
• from 表示来源；
• len 表示内容长度；
• payload 是具体事件数据。

投递不是把局部指针原样留到以后。 系统事件接口的签名是：

1
int sys_event_notify(u16 type, u8 from, void *event, u8 len);

调用方给出“事件大类、来源、数据地址和数据长度”，事件框架据此把数据交付为带 payload 的统一事件。以按键为例，发送端的 e 是 key_driver_scan() 栈上的局部变量：

1
struct key_event e = {0};
2

3
e.type = scan_para->key_type;
4
e.action = key_event;
5
e.value = key_value;
6
key_event_notify(KEY_EVENT_FROM_KEY, &e);

摇一摇则由项目显式创建另一种局部数据并调用系统接口：

1
struct device_event dev = {0};
2

3
dev.event = PAIPOP_EVT_SHAKE;
4
dev.value = 0;
5
dev.arg = NULL;
6
sys_event_notify(SYS_DEVICE_EVENT,
7
                 PAIPOP_DEVICE_EVENT_FROM_APP,
8
                 &dev, sizeof(dev));

当前最终 sdk.elf 中，经过 LTO 特化的本项目按键路径可以确认等效调用为 sys_event_notify(SYS_KEY_EVENT, KEY_EVENT_FROM_KEY, event, 6)；这里的 6 是当前 ABI 下 struct key_event 的大小。这个证据只确认当前 K1/K2 路径，不泛化为所有构建、所有 from 参数都完全相同。后续应用回调看到的数据关系应理解为：

1
发送时                         接收时
2

3
&e → struct key_event          event → struct sys_event
4
      type/action/value                 type = SYS_KEY_EVENT
5
                                        from = KEY_EVENT_FROM_KEY
6
                                        payload → e 的字段内容

因此 paipop_toy_event_handler(app, event) 中的 event 不等于原来的 &e；类型也不同：前者是 struct sys_event *，后者是 struct key_event *。但将 event->payload 转回 struct key_event * 后，读到的 type/action/value 来自发送时的 e。当前 ELF 的反汇编还确认，事件框架把 4 字节信封头和 len 字节负载复制进内部环形缓冲区；这是字节级浅拷贝，结构体中的指针所指对象不会被继续深拷贝，本项目摇一摇消息里的 dev.arg 恰好为 NULL。精确 C 实现仍在杰理二进制库边界，本文不把反汇编结论虚构成某段可见的 malloc/memcpy 源码。公开接口也没有承诺 payload 在回调结束后仍然有效，因此处理函数不应把这个指针保存起来长期使用；确实需要跨回调保留时，应复制所需字段到自己管理的存储中。

项目先判断 type，再决定怎样解释 payload：

1
int paipop_events_handle_sys_event(struct sys_event *event)
2
{
3
    if (!event) {
4
        return false;
5
    }
6

7
    switch (event->type) {
8
    case SYS_KEY_EVENT:
9
        return paipop_events_handle_key(
10
            (struct key_event *)event->payload);
11
    case SYS_NET_EVENT:
12
        return paipop_events_handle_net(
13
            (struct net_event *)event->payload);
14
    case SYS_DEVICE_EVENT:
15
        return paipop_events_handle_device(event);
16
    default:
17
        break;
18
    }
19

20
    return false;
21
}

源码位置：src/app/paipop_events.c:282-299。

虽然杰理定义了五类顶层事件，当前项目只在这里分类 KEY、NET 和 DEVICE。TOUCH、BT 或不属于本模块的事件会返回 false。必须先判断类型再转换 payload，否则可能把网络数据误当成 struct key_event 读取。这里的强制转换不会重新创建或复制一份按键事件，只是告诉 C 编译器“从这个地址开始，按照 struct key_event 的字段布局读取”。

不过，检查 type 只能确定“期望按哪种结构解释”，不能证明负载长度一定足够。当前构建的正常生产者分别发送 6 字节 key_event 和 12 字节 device_event，而 paipop_events_handle_sys_event() / paipop_events_handle_device() 没有校验 event->len，是在信任杰理 SDK 和项目内部生产者。若以后允许外部模块构造事件，更稳妥的解包条件应类似：

1
event->type == SYS_KEY_EVENT &&
2
event->len >= sizeof(struct key_event)

if (!dev) 也不能替代长度检查：只要外层 event 非空，它尾部的 payload 地址通常就不是空指针，即使实际负载不足。

3. true、false 与默认事件处理器#

事件回调的返回值表达的是“这封信有没有被当前应用消费”：

1
true  → 当前应用已经处理，不需要默认处理器继续处理
2
false → 当前应用不处理，框架可以继续走后备路径

杰理的事件示例说明：当活动应用没有消费事件时，会调用弱定义的 app_default_event_handler()。Paipop 工程提供了自己的默认实现：已知的五类系统事件直接忽略，未知类型才触发断言。这里的 true/false 只用于说明应用消费与默认处理器的后备关系，并不能据此断言所有静态 post_handler 等后续钩子都会被跳过。

1
void app_default_event_handler(struct sys_event *event)
2
{
3
    switch (event->type) {
4
    case SYS_KEY_EVENT:
5
    case SYS_TOUCH_EVENT:
6
    case SYS_DEVICE_EVENT:
7
    case SYS_NET_EVENT:
8
    case SYS_BT_EVENT:
9
        break;
10
    default:
11
        ASSERT(0, "unknown event type: %s\n", __func__);
12
        break;
13
    }
14
}

因此，默认处理器不是另一个业务 FSM，也不在 paipop_toy_ops 中。它更像活动应用没有消费事件时的兜底入口。

杰理公开头文件、官方事件示例和 app_core 任务循环能够确认上述接口契约。事件核心实现位于 SDK 库边界，所以后文用 ⇢ 表示由事件框架、任务或硬件完成的跳转，不把它画成当前源码中可见的普通直接调用。

1. 同一个输入在不同状态下含义不同#

PAIPOP_EVT_TOUCH_CLICK 并不总是打断对话：

• 引擎仍在初始化时，记录“初始化完成后开始”；
• 初始化失败时，重新尝试初始化；
• 已在 ENGINE_EXIT 时，开始或排队下一轮；
• 只有正在 ENGINE_CHAT 时，才请求退出当前轮次。

聊天状态下，按键和摇一摇才会走到 SDK 退出请求：

1
case PAIPOP_EVT_TOUCH_CLICK:
2
    if (state == PAIPOP_TOY_STATE_ENGINE_CHAT &&
3
        paipop_fsm_mark_exit_requested()) {
4
        paipop_fsm_start_exit_request_timer();
5
        ret = paipop_engine_interrupt_chat("touch restart");
6
    }
7
    return 0;
8

9
case PAIPOP_EVT_SHAKE:
10
    if (state == PAIPOP_TOY_STATE_ENGINE_CHAT &&
11
        paipop_fsm_try_begin_shake_interrupt()) {
12
        paipop_fsm_mark_shake_restart_requested();
13
        ret = paipop_engine_interrupt_chat("shake interrupt");
14
    }
15
    return 0;

上面为了突出共同结构省略了失败恢复、提示音和日志，完整代码位于 src/app/paipop_fsm.c:874-936。从源码可以确认：按键用 exit_request_pending 避免重复请求；摇一摇先在 paipop_fsm_try_begin_shake_interrupt() 中持有 FSM mutex，把 fsm.shake_interrupt_pending 从 0 置 1，再调用 SDK。若 SDK 同步返回负值，代码会恢复相应标志；未被同步拒绝时，按键和摇一摇分别启用自己的超时保护。超时长度和恢复策略是当前项目规则，不能反推为杰理或灵芯框架的通用要求。

还有一个重要时序：调用 paipop_engine_interrupt_chat() 后，代码并没有立即执行玩具状态转换，所以 FSM 仍是 ENGINE_CHAT。与此同时，PaipopSDK 自己的阶段可以推进到 INTERRUPTING 或 EXITING。只有后续收到 SDK 的 EXIT 生命周期事件，玩具 FSM 才会进入 ENGINE_EXIT。

2. 请求退出和退出完成是两个时刻#

FSM 最终通过项目封装调用 Paipop_ExitChat()：

1
int paipop_engine_interrupt_chat(const char *reason)
2
{
3
    return paipop_engine_exit_chat_mode(reason, 1);
4
}
5

6
/* paipop_engine_exit_chat_mode() 内 */
7
Paipop_GetExitChatDefaultProps(&props);
8
props.disableCloseWebsocketImmediately = false;
9
ret = Paipop_ExitChat(&props);

源码位置：src/services/paipop_engine_service.c:529-557。

PaipopSDK/paipop_sdk.h:199-202 只承诺两件事：该接口用于请求退出，完成结果通过生命周期回调通知。项目调用点把 ret < 0 当作请求被同步拒绝并执行恢复，因此在这层代码里，非负返回值最多只能解释为“没有被同步拒绝”，不能解释成退出已经完成，也不能说明录音、播放器或网络资源已经释放。

初始化对话 SDK 时，项目注册了生命周期监听：

1
Paipop_GetVoiceChatInitDefaultProps(&props);
2
props.lifeCycleListener = paipop_engine_lifecycle_event;
3
ret = Paipop_VoiceChatInit(&props);

当 SDK 后续通过生命周期监听报告 EXIT 时，回调再发布业务事件：

1
case PAIPOP_CHAT_LIFE_CYCLE_EVENT_EXIT: {
2
    Paipop_ExitPayload *ep = (Paipop_ExitPayload *)payload;
3
    int exit_code = ep ? ep->code : -1;
4

5
    /* 省略异常退出附加事件 */
6
    paipop_events_post(PAIPOP_EVT_ENGINE_EXIT, exit_code);
7
    break;
8
}

源码位置：src/services/paipop_engine_service.c:411-448,482-504。

这个事件经过同一条 SYS_DEVICE_EVENT 路径回到 FSM：

1
case PAIPOP_EVT_ENGINE_EXIT:
2
    if (state == PAIPOP_TOY_STATE_ENGINE_CHAT) {
3
        paipop_fsm_prepare_managed_continue(value);
4
        return paipop_fsm_transition(
5
            PAIPOP_TOY_STATE_ENGINE_EXIT,
6
            PAIPOP_EVT_ENGINE_EXIT);
7
    }
8
    return 0;

3. ENGINE_EXIT 之后怎样开始下一轮#

PAIPOP_EVT_ENGINE_EXIT 不是立刻恢复录音。后续顺序由 paipop_fsm.c 明确规定：

1. FSM 从 ENGINE_CHAT 转入 ENGINE_EXIT。进入该状态时会取消退出请求定时器、清除互斥锁保护的 fsm.shake_interrupt_pending，把眼睛设为 IDLE，按键路径如有需要先播放打断提示音，然后启动 1.2 秒退出保护定时器。
2. 保护到期后，paipop_fsm_exit_guard_timeout() 设置 exit_restart_ready；只有 restart_after_exit 仍为真时，才发布 PAIPOP_EVT_ENGINE_RESTART。
3. FSM 仅在仍处于 ENGINE_EXIT 且 exit_restart_ready 为真时调用 paipop_fsm_restart_chat()；过期或不满足条件的重启事件会被忽略。
4. 若本地提示音仍在播放，重启函数不会抢占它，而是每 200 ms 再检查一次。若 OTA 已经开始，则清除重启标志并取消这次续聊；WebSocket 失败等路径也可以撤销待重启状态。
5. 按键和摇一摇的显式打断都会把 continue_same_conversation 置一，因此最终调用 paipop_engine_continue_chat_round()。该函数保留原 conversation_id、生成新的 turn_id、关闭欢迎音并启动一个新的单轮任务；它不是恢复旧音频，也不是创建一段全新 conversation。
6. 新一轮请求没有被同步拒绝后，FSM 才从 ENGINE_EXIT 转回 ENGINE_CHAT，眼睛回到 LISTENING。

重启函数中最能体现顺序的代码是：

1
if (paipop_tone_is_playing()) {
2
    sys_timeout_add_to_task("app_core", NULL,
3
                            paipop_fsm_exit_guard_timeout,
4
                            PAIPOP_ENGINE_TONE_RECHECK_MS); /* 200 ms */
5
    return 0;
6
}
7

8
if (paipop_ota_is_busy()) {
9
    paipop_fsm_clear_restart();
10
    return 0;
11
}
12

13
ret = continue_same_conversation ?
14
      paipop_engine_continue_chat_round() :
15
      paipop_engine_start_new_chat(0);
16
if (ret < 0) {
17
    return 0;
18
}
19
return paipop_fsm_transition(PAIPOP_TOY_STATE_ENGINE_CHAT,
20
                             PAIPOP_EVT_ENGINE_RESTART);

这是从 paipop_fsm_restart_chat() 摘出的控制骨架，省略了锁内取值、日志和定时器句柄保存；分支和调用顺序与 src/app/paipop_fsm.c:589-649 一致。

对应证据位于 src/app/paipop_fsm.c:13-17,216-266,399-410,523-650,673-734,937-970 与 src/services/paipop_engine_service.c:247-292,515-526。闭环可以压缩为：

1
点击/摇动
2
  → FSM 请求 Paipop_ExitChat
3
  → 玩具 FSM 暂时仍为 ENGINE_CHAT
4
  ⇢ PaipopSDK/灵芯异步处理退出请求，可处于 INTERRUPTING/EXITING
5
  ⇢ 生命周期回调 EXIT
6
  → PAIPOP_EVT_ENGINE_EXIT
7
  ⇢ 系统事件回到 app_core
8
  → FSM：ENGINE_CHAT → ENGINE_EXIT
9
  → 1.2s 保护；提示音未完则每 200ms 复查
10
  → PAIPOP_EVT_ENGINE_RESTART
11
  → continue_chat_round：同一 conversation 的新 turn
12
  → FSM：ENGINE_EXIT → ENGINE_CHAT

对灵芯库内部具体以何种线程、顺序释放资源，当前源码没有足够证据；本文只追踪到 PaipopSDK 公共接口与项目注册的生命周期回调边界。

1. FSM 自身可以直接更新状态#

初始化时直接设定初始状态：

1
memset(&fsm, 0, sizeof(fsm));
2
fsm.state = PAIPOP_TOY_STATE_VM_CONFIG;
3
fsm.pending_after_tone = PAIPOP_TOY_STATE_NONE;

合法转换也在互斥锁内直接修改：

1
paipop_fsm_lock();
2
current = fsm.state;
3
allowed = paipop_fsm_transition_allowed(current, target, reason);
4
if (allowed) {
5
    fsm.state = target;
6
}
7
paipop_fsm_unlock();

源码位置：src/app/paipop_fsm.c:117-153,741-758。

这里虽然会使用“事件”作为转换原因，但并不要求再构造一封杰理 struct sys_event。

2. 眼睛任务使用共享状态和版本号#

眼睛行为变化不会发布 sys_event：paipop_eye_set_behavior() 在 mutex 下更新 eye_hdl.behavior 并执行 generation++，动画任务再读取最新快照。它只关心最新表现，不必为每次表情变化排一条系统事件。源码位置：src/services/paipop_eye_service.c:800-815。

3. 设备数据和 PCM 不适合逐帧包装成系统事件#

I²C/SPI 的读写由 dev_ioctl()、dev_read()、dev_write() 直接返回；PCM 是连续、高频、数据量较大的音频流，通常通过缓冲区、生产者/消费者接口或专用回调传递。如果把每几个字节都包装成 sys_event，会增加复制、排队和调度开销，还可能堵塞低频控制消息。

可以用下面的选择原则：

因此更准确的结论不是“所有改变最终都由事件实现”，而是：

项目把重要的、低频的、跨模块控制变化统一成业务事件；模块内部状态、高频数据和同步设备操作仍使用更合适的通道。

Q1：回调和事件框架是独立的吗？#

概念上独立。回调解决“以后调用谁”，事件框架解决“消息怎样封装、排队、路由和分类”。回调不一定使用事件框架；事件框架最终通常又通过已注册的回调把事件交给接收者。当前摇一摇正是“硬件回调 → 定时回调 → 业务回调 → 系统事件 → 应用事件回调”的组合。

Q2：REGISTER_DEVICES 和 SYS_DEVICE_EVENT 是同一套机制吗？#

不是。前者建立设备名字到 device_operations 的静态查找表，供 dev_open/read/write/ioctl 使用；后者只是一种系统事件类型。名字里都有 device，但一个用于主动操作驱动，一个用于传递消息。

Q3：为什么不把 paipop_events_handle_key() 直接注册给 app_core？#

应用入口签名是 (application *, sys_event *)，按键处理函数却只接收 key_event *，并且是 paipop_events.c 内部的 static 函数。统一入口还要面对网络、设备等事件，必须先检查 event->type 决定 payload 类型；若事件生产者不完全可信，还应同时校验 event->len。

Q4：I²C、SPI 完成读写后会自动进入 paipop_toy_event_handler() 吗？#

不会。REGISTER_DEVICES 本身只建立设备查找表，不发布系统事件；当前可见的 STK8321/LCD dev_ioctl()、dev_write() 调用也没有自动发布事件。按键是另一条路径，key_event_notify() 会在杰理库内部继续进入事件机制，所以不能把“业务代码直接调用 sys_event_notify()”当作唯一入口。

Q5：app_default_event_handler() 与业务 FSM 有什么关系？#

没有直接的状态转换关系。它是活动应用没有消费某个系统事件时的后备处理器。当前 Paipop 实现对五种已知类型不做业务处理，只对未知类型断言。

Q6：app_core 串行后还需要互斥锁吗？#

要看数据是否只由 app_core 访问。眼睛任务、SDK 任务和硬件中断仍可与它并发；普通互斥锁也不能在 ISR 中阻塞使用。当前硬件 pending 是布尔标志，多个边沿可能合并；若要求逐个保留，应使用临界区、原子交换或 ISR 安全队列。