Message Mailboxes API Changes

Owned by Former user (Deleted)
Last updated: Mar 23, 2021 by WES Admin
2 min read

The table below shows the API for message mailbox management. Note that µC/OS-III does not directly provide services for managing message mailboxes. Given that a message mailbox is a message queue of size one, µC/OS-III can easily emulate message mailboxes.

Message Mailbox API
µC/OS-II (os_mbox.c)µC/OS-III (os_q.c)Note
void * 
OSMboxAccept( 
    OS_EVENT *pevent);

(1)

OS_EVENT * 
OSMboxCreate( 
    void *pmsg);
void 
OSQCreate( 
    OS_Q *p_q, 
    CPU_CHAR *p_name, 
    OS_MSG_QTY max_qty, 
    OS_ERR *p_err);

(2)

void * 
OSMboxDel( 
    OS_EVENT *pevent, 
    INT8U opt, 
    INT8U *perr);
OS_OBJ_QTY, 
OSQDel( 
    OS_Q *p_q, 
    OS_OPT opt, 
    OS_ERR *p_err);

void * 
OSMboxPend( 
    OS_EVENT *pevent, 
    INT32U timeout, 
    INT8U *perr);
void * 
OSQPend( 
    OS_Q *p_q, 
    OS_TICK timeout, 
    OS_OPT opt, 
    OS_MSG_SIZE *p_msg_size, 
    CPU_TS *p_ts, 
    OS_ERR *p_err);

(3)

INT8U 
OSMBoxPendAbort( 
    OS_EVENT *pevent, 
    INT8U opt, 
    INT8U *perr);
OS_OBJ_QTY 
OSQPendAbort( 
    OS_Q *p_q, 
    OS_OPT opt 
    OS_ERR *p_err);

INT8U 
OSMboxPost( 
    OS_EVENT *pevent, 
    void *pmsg);
void 
OSQPost( 
    OS_Q *p_q, 
    Void *p_void, 
    OS_MSG_SIZE msg_size, 
    OS_OPT opt, 
    OS_ERR *p_err);

(4)

INT8U 
OSMboxPostOpt( 
    OS_EVENT *pevent, 
    void *pmsg, 
    INT8U opt);

(4)

INT8U 
OSMboxQuery( 
    OS_EVENT *pevent, 
    OS_MBOX_DATA *p_mbox_data);

(5)

(1) In µC/OS-III, there is no “accept” API since this feature is built into the OSQPend() by specifying the OS_OPT_PEND_NON_BLOCKING option.

(2) In µC/OS-II, OSMboxCreate() returns the address of an OS_EVENT, which is used as the “handle” to the message mailbox. In µC/OS-III, the application must allocate storage for an OS_Q, which serves the same purpose as the OS_EVENT. The benefit in µC/OS-III is that it is not necessary to predetermine the number of message queues at compile time. Also, to create the equivalent of a message mailbox, you would specify 1 for the max_qty argument.

(3) µC/OS-III returns additional information about the message received. Specifically, the sender specifies the size of the message as a snapshot of the current timestamp is taken and stored as part of the message. The receiver of the message therefore knows when the message was sent.

(4) In µC/OS-III, OSQPost() offers a number of options that replaces the two post functions provided in µC/OS-II.

(5) µC/OS-III does not provide query services, as they were rarely used in µC/OS-II.