RTAI API---Mailbox functions

rt_mbx_init
rt_mbx_delete
rt_mbx_send
rt_mbx_receive
rt_mbx_send_wp
rt_mbx_receive_wp
rt_mbx_send_if
rt_mbx_receive_if
rt_mbx_send_until
rt_mbx_receive_until
rt_mbx_send_timed

rt_mbx_receive_timed

please refer to: https://www.rtai.org/userfiles/documentation/magma/html/api

***************************************************************************************************************************************************************************************

NAME
rt_mbx_init - initialize mailbox

SYNOPSIS
#include "rtai_sched.h"
int rt_mbx_init (MBX* mbx, int size);

DESCRIPTION
rt_mbx_init initializes a mailbox of size size. mbx have to point to a statically allocated structure.
Using mailboxes is a flexible method of task-to-task communication. Tasks are allowed to send arbitrary size messages by using any mailbox buffer size. Clearly you should use a buffer sized at least as the largest message you envisage. However if you expect a message larger than the average message size very rarely you can use a smaller buffer without much loss of efficiency. In such a way you can set up your own mailbox usage protocol, e.g. using fix size messages with a buffer that is an integer multiple of such a size guarantees that each message is sent/received atomically to/from the mailbox. Multiple senders and receivers are allowed and each will get the service it requires in turn, according to its priority.

RETURN VALUE
On success 0 is returned. On failure a negative value is returned as described below.
ERRORS
-EINVAL
Space could not be allocated for the mailbox buffer.
*********************************************************************************************************************************************************************************

NAME
rt_mbx_delete - delete mailbox

SYNOPSIS
#include "rtai_sched.h"
int rt_mbx_delete (MBX* mbx);

DESCRIPTION
rt_mbx_delete removes a mailbox previously created with rt_mbox_init. mbx points to the structure used in the corresponding call to rt_mbox_init.
RETURN VALUE
On success 0 is returned. On failure a negative value is returned as described below.
ERRORS
-EINVAL
mbx points to not a valid mailbox.
-EFAULT
??? Paolo, fill this line please.
****************************************************************************************************************************************************************************
NAME
rt_mbx_send - send message unconditionally

SYNOPSIS
#include "rtai_sched.h"
int rt_mbx_send (MBX* mbx, void* msg, int msg_size);

DESCRIPTION
rt_mbx_send sends a message msg of msg_size bytes to the mailbox mbx. The caller will be blocked until the whole message is enqueued or an error occurs.
RETURN VALUE
On success, the number of unsent bytes is returned. On failure a negative value is returned as described below.
ERRORS
-EINVAL
mbx points to not a valid mailbox.
***********************************************************************************************************************************************************************************
NAME
rt_mbx_send_wp - send bytes as many as possible

SYNOPSIS
#include "rtai_sched.h"
int rt_mbx_send_wp (MBX* mbx, void* msg, int msg_size);

DESCRIPTION
rt_mbx_send_wp sends as many as possible of bytes of message msg to mailbox mbx then returns immediately. The message length is msg_size.
RETURN VALUE
On success, the number of unsent bytes is returned. On failure a negative value is returned as described below.
ERRORS

-EINVAL
mbx points to not a valid mailbox.
********************************************************************************************************************************************************************************
NAME
rt_mbx_send_if - send a message if possible

SYNOPSIS
#include "rtai_sched.h"
int rt_mbx_send_if (MBX* mbx, void* msg, int msg_size);

DESCRIPTION
rt_mbx_send_if tries to enqueue a message msg of msg_size bytes to the mailbox mbx. It returns immediately, the caller is never blocked.
RETURN VALUE

On success, the number of unsent bytes (0 or msg_size) is returned. On failure a negative value is returned as described below.
ERRORS
-EINVAL
mbx points to not a valid mailbox.
*********************************************************************************************************************************************************************************
NAME
rt_mbx_send_until, rt_mbx_send_timed - send a message with timeout

SYNOPSIS
#include "rtai_sched.h"
int rt_mbx_send_until (MBX* mbx, void* msg, int msg_size, RTIME time);
int rt_mbx_send_timed (MBX* mbx, void* msg, int msg_size, RTIME delay);

DESCRIPTION
rt_mbx_send_until and rt_mbx_send_timed send a message msg of msg_size bytes to the mailbox mbx. The caller will be blocked until all bytes of message is enqueued, timeout expires or an error occurs. 
time is an absolute value. delay is relative to the current time.

RETURN VALUE
On success, the number of unsent bytes is returned. On failure a negative value is returned as described below.
ERRORS

-EINVAL
mbx points to not a valid mailbox.
**********************************************************************************************************************************************************************************
NAME
rt_mbx_receive - receive message unconditionally

SYNOPSIS
#include "rtai_sched.h"
int rt_mbx_receive (MBX* mbx, void* msg, int msg_size);

DESCRIPTION
rt_mbx_receive receives a message of msg_size bytes from the mailbox mbx. The caller will be blocked until all bytes of the message arrive or an error occurs. 
msg points to a buffer provided by the caller.
RETURN VALUE

On success, the number of received bytes is returned. On failure a negative value is returned as described below.
ERRORS
-EINVAL
mbx points to not a valid mailbox.
********************************************************************************************************************************************************************************
NAME

rt_mbx_receive_wp - receive bytes as many as possible

SYNOPSIS
#include "rtai_sched.h"
int rt_mbx_receive_wp (MBX* mbx, void* msg, int msg_size);

DESCRIPTION
rt_mbx_receive_wp receives at most msg_size of bytes of message from mailbox mbx then returns immediately. 
msg points to a buffer provided by the caller.

RETURN VALUE
On success, the number of received bytes is returned. On failure a negative value is returned as described below.
ERRORS
-EINVAL
mbx points to not a valid mailbox.
***************************************************************************************************************************************************************************

NAME
rt_mbx_receive_if - receive a message if available

SYNOPSIS
#include "rtai_sched.h"
int rt_mbx_receive_if (MBX* mbx, void* msg, int msg_size);

DESCRIPTION
rt_mbx_receive_if receives a message from the mailbox mbx if the whole message of msg_size bytes is available immediately. 
msg points to a buffer provided by the caller.

RETURN VALUE
On success, the number of received bytes (0 or msg_size) is returned. On failure a negative value is returned as described below.
ERRORS

-EINVAL
mbx points to not a valid mailbox.

**************************************************************************************************************************************************************************************
NAME
rt_mbx_receive_until, rt_mbx_receive_timed - receive a message with timeout

SYNOPSIS
#include "rtai_sched.h"
int rt_mbx_receive_until (MBX* mbx, void* msg, int msg_size, RTIME time);
int rt_mbx_receive_timed (MBX* mbx, void* msg, int msg_size, RTIME delay);

DESCRIPTION
rt_mbx_receive_until and rt_mbx_receive_timed receive a message of msg_size bytes from the mailbox mbx. The caller will be blocked until all bytes of the message arrive, timeout expires or an error occurs. 
time is an absolute value. delay is relative to the current time. 
msg points to a buffer provided by the caller.

RETURN VALUE
On success, the number of received bytes is returned. On failure a negative value is returned as described below.
ERRORS

-EINVAL
mbx points to not a valid mailbox.