Mailbox

---

Detailed Description

Mailboxes are a mechanism for inter-task communication and interrupt-task communication. Each mailbox has its own mailbox control structure. Different tasks and interrupts can post a mailbox, but only one task can pend on a certain mailbox. Tasks can pend or post a mailbox with a timeout value.

Defines
#define	MBX_CREATE(name, n, msg_size)
	Create a mailbox.
Functions
void	MBX_Init (HANDLE *ph)
	Mailbox initialisation function.
STATUS	MBX_Post (HANDLE *ph, void *pmsg, uint16 tout)
	Mailbox post function.
STATUS	MBX_Pend (HANDLE *ph, void *pmsg, uint16 tout)
	Mailbox pend function.
void	MBX_Flush (HANDLE *ph)
	Mailbox flush function.

---

Define Documentation

#define MBX_CREATE (  name, n, msg_size   )

Create a mailbox. This macro creates and partialy initilises the mailbox control structure. It also allocates the needed message buffers. Parameters: name  name of the mailbox n  number of messages a mailbox can hold msg_size  size of a mailbox message Examples: timers.c.

---

Function Documentation

void MBX_Flush (  HANDLE *  ph  )

Mailbox flush function. Flush a mailbox and unblock all pending tasks that were waiting for free message containers. SYS_ERROR is passed to the task. Parameters: ph  handle to mailbox

void MBX_Init (  HANDLE *  ph  )

Mailbox initialisation function. A mailbox must be initialised before its usage. Calling this function initialises the mailbox. Parameters: ph  handle to mailbox Attention: The initialisation function must be called before running the scheduler. Examples: timers.c.

STATUS MBX_Pend (  HANDLE *  ph, void *  pmsg, uint16  tout )

Mailbox pend function. Only tasks can pend on mailboxes. If a mailbox is not empty the message is returned to the caller and the system call returns with SYS_OK. When there is no message the task is pending and SYS_ERROR is returned. If the caller specifed a timeout value a timer is started and the task is delayed from execution. After the timeout expires (no task or interrupt posted a message) the task is unblocked and SYS_MBX_TOUT is passed to the task's entry parameter. If somebody posted a message the timer is removed and the SYS_MBX values is passed to the task. Parameters: ph  handle to mailbox pmsg  pointer caller where the message will be copied tout  timeout value Return values: SYS_OK  if there was a message in mailbox SYS_ERR  if there was no messages in mailbox Attention: MBX_pend can not be called from an ISR. Examples: timers.c.

STATUS MBX_Post (  HANDLE *  ph, void *  pmsg, uint16  tout )

Mailbox post function. A mailbox can be post from an interrupt ISR or from a task. When posted from a task a timeout value can be specified. If a mailbox has a empty message container the message is stored in the mailbox and the system call returns with SYS_OK. When there is no empty message containers the task is pending and SYS_ERROR is returned. If the caller specifed a timeout value a timer is started and the task is delayed from execution. After the timeout expires (no task freed a message container) the task is unblocked and SYS_MBX_TOUT is passed to the task's entry parameter. If a task freed a message container the SYS_MBX value is passed to the task. Parameters: ph  handle to mailbox pmsg  pointer caller to message tout  timeout value Return values: SYS_OK  if there was a free message container SYS_ERR  if all message containers are full Examples: timers.c.

---