定义
Mailbox（邮箱机制）是一种基于固定缓冲区或消息槽的IPC通信方式， 用于任务间小数据单元的高效传递。
概述
邮箱（Mailbox）是一种基于固定消息槽的通信机制，用于任务之间传递固定大小的数据单元。 每个邮箱可以存放一个或多个消息指针或数据块。
邮箱是实时操作系统中轻量级IPC通信的核心组件，专门为小数据高频通信场景设计。与消息队列相比，邮箱具有更低的内存开销、更快的访问速度和更确定的行为特性。邮箱内部通常维护固定数量的消息槽，每个槽存储固定大小的数据单元或指针。这种固定结构的设计使得邮箱在编译时即可确定内存需求，避免了动态内存分配的开销与风险。
邮箱的主要应用场景包括传感器数据上报、状态同步、驱动层事件通知、控制命令传递等。这些场景的共同特点是数据量小（通常为几个字节到几十字节）、通信频率高、对延迟敏感。邮箱通过环形缓冲区或消息槽数组实现，提供O(1)时间的发送与接收操作，满足实时系统的确定性要求。
邮箱支持阻塞与非阻塞两种通信模式。阻塞模式下，当邮箱已满时发送任务阻塞等待空槽，当邮箱为空时接收任务阻塞等待数据。非阻塞模式下，发送与接收操作立即返回成功或失败，适用于不能阻塞的任务或中断服务程序。HRTOS提供灵活的超时配置，允许开发者根据应用需求选择合适的阻塞策略。
设计目标
Mailbox 的设计目标是在保持极低系统开销的前提下， 提供确定性的小数据通信能力。 相比复杂消息系统，Mailbox更强调固定结构、快速访问与低延迟。
不适合：大数据块、复杂优先级消息调度。
典型使用场景
Mailbox常用于传感器数据上报、状态同步、驱动层事件通知等小数据高频通信场景。 相比消息队列，它更轻量，但不适合大数据传输。
工作原理
邮箱内部维护一个环形缓冲区，用于存储消息。 发送任务将数据放入邮箱，接收任务从邮箱取出数据进行处理。
邮箱的内部实现依赖于邮箱控制块（Mailbox Control Block）与环形缓冲区。每个邮箱包含缓冲区指针、消息槽数量、消息大小、读写索引、等待队列等字段。环形缓冲区通过head与tail索引实现，head指向下一个写入位置，tail指向下一个读取位置。当head追上tail时表示邮箱已满，当tail追上head时表示邮箱为空。这种设计避免了数据移动，提供O(1)时间的写入与读取操作。
发送操作时，内核检查邮箱是否已满（head+1 == tail，考虑环形回绕）。如果邮箱未满，将数据复制到head指向的消息槽，递增head索引（考虑环形回绕），检查是否有等待的接收任务，如果有则唤醒最高优先级的接收任务并触发调度。如果邮箱已满，根据配置策略决定行为：阻塞等待空槽、超时返回或覆盖旧数据（overwrite模式）。
接收操作时，内核检查邮箱是否为空（head == tail）。如果邮箱未空，从tail指向的消息槽读取数据，递增tail索引（考虑环形回绕），检查是否有等待的发送任务，如果有则唤醒最高优先级的发送任务并触发调度。如果邮箱为空，根据配置策略决定行为：阻塞等待数据、超时返回或立即返回空值。
邮箱的等待队列通常采用优先级排序，确保高优先级等待任务优先获得消息槽或数据。当邮箱有空槽或有数据时，内核从队列首部唤醒最高优先级的等待任务。这种设计保证了公平性，避免低优先级任务饥饿。在多核SMP系统中，邮箱操作需要考虑跨核心的同步，通常使用原子指令或自旋锁保护邮箱控制块。
关键接口 / 结构
os_mailbox_init()用于初始化邮箱，参数包括邮箱控制块指针、缓冲区指针、消息槽数量、消息大小。该接口设置邮箱的缓冲区、初始化读写索引为0、配置消息槽大小与数量。初始化操作必须在首次使用邮箱之前调用，未初始化的邮箱行为未定义。缓冲区通常由调用者分配，邮箱仅管理缓冲区的访问逻辑。
os_mailbox_send()用于发送消息到邮箱，参数包括邮箱指针、数据指针、超时时间。超时时间为0时为非阻塞调用，立即返回发送结果；超时时间为-1时为永久阻塞，任务会一直等待直到有空槽；超时时间为正数时为限时阻塞，任务等待指定时间后超时返回。发送成功返回0，超时返回-1，错误返回-2。该接口在临界区中执行，确保缓冲区操作的原子性。
os_mailbox_recv()用于从邮箱接收消息，参数包括邮箱指针、接收缓冲区指针、超时时间。超时时间配置与发送接口相同。接收成功返回0，超时返回-1，错误返回-2。接收操作将邮箱中的数据复制到接收缓冲区，调用者需确保接收缓冲区足够大。该接口同样在临界区中执行。
mailbox结构体定义了邮箱的核心属性。buffer字段指向消息槽缓冲区，可以是静态分配或动态分配的内存。size字段存储消息槽的总数量。head字段指向下一个写入位置，tail字段指向下一个读取位置。该结构体还可能包含消息大小字段、等待队列指针、统计信息等字段。结构体大小取决于配置，HRTOS通过优化字段布局减少内存占用。
运行流程
发送任务将数据写入邮箱缓冲区，当邮箱非满时写入成功； 接收任务在邮箱非空时读取数据并处理。
完整的邮箱发送流程包括：任务调用os_mailbox_send()接口，内核进入临界区；检查邮箱是否已满（head+1 == tail，考虑环形回绕），如果邮箱未满则将数据复制到head指向的消息槽，递增head索引（考虑环形回绕）；检查是否有等待的接收任务，如果有则唤醒最高优先级的接收任务并触发调度；退出临界区，发送操作完成。如果邮箱已满，根据超时配置决定行为：超时为0时立即返回错误，超时为正数时将当前任务插入发送等待队列并阻塞，超时为-1时永久阻塞等待。
完整的邮箱接收流程包括：任务调用os_mailbox_recv()接口，内核进入临界区；检查邮箱是否为空（head == tail），如果邮箱未空则从tail指向的消息槽读取数据，递增tail索引（考虑环形回绕）；检查是否有等待的发送任务，如果有则唤醒最高优先级的发送任务并触发调度；退出临界区，接收操作完成。如果邮箱为空，根据超时配置决定行为：超时为0时立即返回错误，超时为正数时将当前任务插入接收等待队列并阻塞，超时为-1时永久阻塞等待。
阻塞与唤醒机制
当邮箱为空时，接收任务可进入阻塞等待状态； 当邮箱已满时，发送任务可选择阻塞、超时返回或覆盖旧数据， 具体行为由系统配置策略决定。
Mailbox vs Message Queue
Mailbox适用于固定大小的小数据传输，结构简单、开销低； Message Queue支持变长数据与更复杂调度机制，适用于复杂任务通信场景。
机制选择建议
不同IPC机制适用于不同通信需求：
扩展说明
邮箱机制通常用于任务间事件数据传递，如传感器数据上报、状态信息同步等。 在高实时系统中可作为消息队列的轻量替代方案。
邮箱与消息队列的选择是工程实践中的重要决策。邮箱适用于固定大小的小数据高频通信，具有确定性的O(1)操作时间、固定的内存需求、简单的实现逻辑。消息队列支持变长数据、多优先级消息、复杂的调度策略，适用于复杂的任务通信场景。如果通信数据量小且固定、对延迟敏感，应选择邮箱；如果需要传输变长数据或复杂的消息调度，应选择消息队列。
在中断服务程序（ISR）中使用邮箱时，只能使用非阻塞模式（timeout=0）。ISR不能阻塞等待邮箱空槽，否则会导致系统死锁。如果ISR需要向任务发送数据，应使用邮箱的非阻塞发送模式：如果邮箱已满则丢弃数据或覆盖旧数据（overwrite模式）。这种设计确保了中断响应的实时性，同时实现了ISR与任务间的数据传递。
邮箱的覆盖模式（overwrite）是特殊的应用场景配置。启用覆盖模式后，当邮箱已满时，新数据会覆盖最旧的数据（tail位置），而不是阻塞等待。这种模式适用于最新数据最重要的场景，如传感器数据更新、状态值刷新等。HRTOS提供配置选项启用或禁用覆盖模式，开发者可根据应用需求选择合适的策略。
- 模块职责：邮箱管理负责基于固定缓冲区的小数据通信，实现高效、确定性的任务间数据传递
- 内部机制：基于邮箱控制块、环形缓冲区、读写索引、等待队列实现，支持阻塞与非阻塞模式
- 状态迁移：邮箱在EMPTY、PARTIAL、FULL状态间切换，由发送与接收操作驱动
- 调用流程：init → send → write/block → recv → read/block
- 资源管理：邮箱控制块为全局资源，缓冲区为共享资源需保护并发访问
- 工程案例：传感器数据上报、状态同步、驱动事件通知、控制命令传递
- 边界条件：消息槽数量、消息大小、环形回绕、超时时间
- 错误场景：邮箱溢出、数据丢失、缓冲区越界、ISR阻塞、死锁
- 异常处理：溢出检测、覆盖模式、超时处理、边界检查
- 模块关系：与调度器模块协作阻塞唤醒任务，与中断模块协调ISR-Task通信
邮箱的性能优化是实时系统工程的重要环节。HRTOS采用环形缓冲区设计，避免数据移动开销，提供O(1)时间的发送与接收操作。缓冲区大小根据应用需求配置，通常为2的幂次方，便于环形回绕计算（使用位掩码代替模运算）。对于多核SMP系统，邮箱操作使用原子指令或自旋锁保护，减少临界区持续时间。这些优化确保了邮箱操作的高效性，满足实时系统的性能要求。
对于功耗敏感的嵌入式系统，邮箱的使用会影响系统功耗管理。长时间阻塞等待邮箱空槽或数据的任务会阻止系统进入低功耗模式。HRTOS提供邮箱超时检测机制，当任务等待时间超过阈值时记录警告，指导开发者优化通信设计。系统还支持在发送或接收失败时主动让出CPU，允许系统进入低功耗模式，平衡实时性与功耗。