Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Globals | Related Pages | Search for 

Mailbox functions


Files

file  mbx.c
 Mailbox functions.

Defines

#define MOD_SIZE(indx)   ((indx) < mbx->size ? (indx) : (indx) - mbx->size)
#define CHK_MBX_MAGIC   { if (mbx->magic != RT_MBX_MAGIC) { return -EINVAL; } }

Functions

 MODULE_LICENSE ("GPL")
void mbx_delete_signal (MBX *mbx)
void mbx_signal (MBX *mbx)
int mbx_wait (MBX *mbx, int *fravbs, RT_TASK *rt_current)
int mbx_wait_until (MBX *mbx, int *fravbs, RTIME time, RT_TASK *rt_current)
int mbxput (MBX *mbx, char **msg, int msg_size, int space)
int mbxovrwrput (MBX *mbx, char **msg, int msg_size, int space)
int mbxget (MBX *mbx, char **msg, int msg_size, int space)
int mbxevdrp (MBX *mbx, char **msg, int msg_size, int space)
int _rt_mbx_evdrp (MBX *mbx, void *msg, int msg_size, int space)
 Receives bytes as many as possible leaving the message available for another receive.
int rt_typed_mbx_init (MBX *mbx, int size, int type)
 Initializes a fully typed mailbox queueing tasks according to the specified type.
int rt_mbx_init (MBX *mbx, int size)
 Initializes a mailbox.
int rt_mbx_delete (MBX *mbx)
 Deletes a mailbox.
int _rt_mbx_send (MBX *mbx, void *msg, int msg_size, int space)
 Sends a message unconditionally.
int _rt_mbx_send_wp (MBX *mbx, void *msg, int msg_size, int space)
 Sends as many bytes as possible without blocking the calling task.
int _rt_mbx_send_if (MBX *mbx, void *msg, int msg_size, int space)
 Sends a message, only if the whole message can be passed without blocking the calling task.
int _rt_mbx_send_until (MBX *mbx, void *msg, int msg_size, RTIME time, int space)
 Sends a message with absolute timeout.
int _rt_mbx_send_timed (MBX *mbx, void *msg, int msg_size, RTIME delay, int space)
 Sends a message with relative timeout.
int _rt_mbx_receive (MBX *mbx, void *msg, int msg_size, int space)
 Receives a message unconditionally.
int _rt_mbx_receive_wp (MBX *mbx, void *msg, int msg_size, int space)
 Receives bytes as many as possible, without blocking the calling task.
int _rt_mbx_receive_if (MBX *mbx, void *msg, int msg_size, int space)
 Receives a message only if the whole message can be passed without blocking the calling task.
int _rt_mbx_receive_until (MBX *mbx, void *msg, int msg_size, RTIME time, int space)
 Receives a message with absolute timeout.
int _rt_mbx_receive_timed (MBX *mbx, void *msg, int msg_size, RTIME delay, int space)
 Receives a message with relative timeout.
int _rt_mbx_ovrwr_send (MBX *mbx, void *msg, int msg_size, int space)
 Sends a message overwriting what already in the buffer if there is no place for the message.
MBX * _rt_typed_named_mbx_init (unsigned long mbx_name, int size, int qtype)
 Initializes a specifically typed (fifo queued, priority queued or resource queued) mailbox identified by a name.
int rt_named_mbx_delete (MBX *mbx)
 Deletes a named mailbox.
int set_rt_fun_entries (struct rt_native_fun_entry *entry)
void reset_rt_fun_entries (struct rt_native_fun_entry *entry)
int __rtai_mbx_init (void)
void __rtai_mbx_exit (void)

Variables

rt_native_fun_entry rt_mbx_entries []

Define Documentation

#define CHK_MBX_MAGIC   { if (mbx->magic != RT_MBX_MAGIC) { return -EINVAL; } }
 

Definition at line 346 of file mbx.c.

Referenced by _rt_mbx_ovrwr_send(), _rt_mbx_receive(), _rt_mbx_receive_if(), _rt_mbx_receive_until(), _rt_mbx_receive_wp(), _rt_mbx_send(), _rt_mbx_send_if(), _rt_mbx_send_until(), _rt_mbx_send_wp(), and rt_mbx_delete().

#define MOD_SIZE (  indx   )     ((indx) < mbx->size ? (indx) : (indx) - mbx->size)
 

Definition at line 188 of file mbx.c.

Function Documentation

void __rtai_mbx_exit (  void   ) 
 

Definition at line 988 of file mbx.c.

References reset_rt_fun_entries(), and rt_mbx_entries.

Here is the call graph for this function:

int __rtai_mbx_init (  void   ) 
 

Definition at line 983 of file mbx.c.

References rt_mbx_entries, and set_rt_fun_entries().

Here is the call graph for this function:

int _rt_mbx_evdrp (  MBX *  mbx,
void *  msg,
int  msg_size,
int  space
) 
 

Receives bytes as many as possible leaving the message available for another receive.

rt_mbx_evdrp receives at most msg_size of bytes of message from the mailbox mbx and then returns immediately. Does what rt_mbx_receive_wp does while keeping the message in the mailbox buffer. Useful if one needs to just preview the mailbox content, without actually receiving it.

Parameters:
mbx is a pointer to a user allocated mailbox structure.
msg points to a buffer provided by the caller.
msg_size corresponds to the size of the message to be received.
Returns:
The number of bytes not received is returned.
Definition at line 340 of file mbx.c.

References MBX, and mbxevdrp().

Here is the call graph for this function:

int _rt_mbx_ovrwr_send (  MBX *  mbx,
void *  msg,
int  msg_size,
int  space
) 
 

Sends a message overwriting what already in the buffer if there is no place for the message.

rt_mbx_ovrwr_send sends the message msg of msg_size bytes to the mailbox mbx overwriting what already in the mailbox buffer if there is no place for the message. Useful for logging purposes. It returns immediately and the caller is never blocked.

Returns:
On success, 0 is returned. On failure a negative value is returned as described below:
  • EINVAL: mbx points to an invalid mailbox.
Definition at line 854 of file mbx.c.

References CHK_MBX_MAGIC, flags, MBX, mbx_signal(), mbxovrwrput(), rt_sem_signal(), and RT_TASK.

Here is the call graph for this function:

int _rt_mbx_receive (  MBX *  mbx,
void *  msg,
int  msg_size,
int  space
) 
 

Receives a message unconditionally.

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.

Parameters:
mbx is a pointer to a user allocated mailbox structure.
msg points to a buffer provided by the caller.
msg_size corresponds to the size of the message to be received.
Returns:
On success, 0 is returned. On failure a value is returned as described below:
  • the number of bytes not received: an error is occured in the queueing of all receiving tasks.
  • EINVAL: mbx points to an invalid mailbox.
Definition at line 665 of file mbx.c.

References CHK_MBX_MAGIC, MBX, mbx_signal(), mbx_wait(), mbxget(), rt_sem_signal(), rt_sem_wait(), and RT_TASK.

Referenced by rt_get_net_rpc_ret().

Here is the call graph for this function:

int _rt_mbx_receive_if (  MBX *  mbx,
void *  msg,
int  msg_size,
int  space
) 
 

Receives a message only if the whole message can be passed without blocking the calling task.

rt_mbx_receive_if receives a message from the mailbox mbx if the whole message of msg_size bytes is available immediately.

Parameters:
mbx is a pointer to a user allocated mailbox structure.
msg points to a buffer provided by the caller.
msg_size corresponds to the size of the message to be received.
Returns:
On success, the number of bytes not received (0 or msg_size) is returned. On failure a negative value is returned as described below:
  • EINVAL: mbx points to an invalid mailbox.
Definition at line 743 of file mbx.c.

References CHK_MBX_MAGIC, flags, MBX, mbx_signal(), mbxget(), rt_sem_signal(), and RT_TASK.

Here is the call graph for this function:

int _rt_mbx_receive_timed (  MBX *  mbx,
void *  msg,
int  msg_size,
RTIME  delay,
int  space
) 
 

Receives a message with relative timeout.

rt_mbx_receive_timed receives 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.

Parameters:
mbx is a pointer to a user allocated mailbox structure.
msg points to a buffer provided by the caller.
msg_size corresponds to the size of the message received.
delay is the timeout value relative to the current time.
Returns:
On success, 0 is returned. On failure a value is returned as described below:
  • the number of bytes not received: an error is occured in the queueing of all receiving tasks or the timeout has expired.
  • EINVAL: mbx points to an invalid mailbox.
See also: notes under rt_mbx_received_until(). Definition at line 835 of file mbx.c.

References _rt_mbx_receive_until(), MBX, and RTIME.

Here is the call graph for this function:

int _rt_mbx_receive_until (  MBX *  mbx,
void *  msg,
int  msg_size,
RTIME  time,
int  space
) 
 

Receives a message with absolute timeout.

rt_mbx_receive_until receives 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.

Parameters:
mbx is a pointer to a user allocated mailbox structure.
msg points to a buffer provided by the caller.
msg_size corresponds to the size of the message received.
time is an absolute value of the timeout.
Returns:
On success, 0 is returned. On failure a value is returned as described below:
  • the number of bytes not received: an error is occured in the queueing of all receiving tasks or the timeout has expired.
  • EINVAL: mbx points to an invalid mailbox.
See also: notes under rt_mbx_received_timed(). Definition at line 789 of file mbx.c.

References CHK_MBX_MAGIC, MBX, mbx_signal(), mbx_wait_until(), mbxget(), rt_sem_signal(), rt_sem_wait_until(), RT_TASK, RTIME, and SEM_ERR.

Referenced by _rt_mbx_receive_timed().

Here is the call graph for this function:

int _rt_mbx_receive_wp (  MBX *  mbx,
void *  msg,
int  msg_size,
int  space
) 
 

Receives bytes as many as possible, without blocking the calling task.

rt_mbx_receive_wp receives at most msg_size of bytes of message from the mailbox mbx then returns immediately.

Parameters:
mbx is a pointer to a user allocated mailbox structure.
msg points to a buffer provided by the caller.
msg_size corresponds to the size of the message to be received.
Returns:
On success, the number of bytes not received is returned. On failure a negative value is returned as described below:
  • EINVAL: mbx points to not a valid mailbox.
Definition at line 702 of file mbx.c.

References CHK_MBX_MAGIC, flags, MBX, mbx_signal(), mbxget(), rt_sem_signal(), and RT_TASK.

Here is the call graph for this function:

int _rt_mbx_send (  MBX *  mbx,
void *  msg,
int  msg_size,
int  space
) 
 

Sends a message unconditionally.

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 copied into the mailbox or an error occurs. Even if the message can be sent in a single shot, the sending task can be blocked if there is a task of higher priority waiting to receive from the mailbox.

Parameters:
mbx is a pointer to a user allocated mailbox structure.
msg corresponds to the message to be sent.
msg_size is the size of the message.
Returns:
On success, 0 is returned. On failure a value is returned as described below:
  • the number of bytes not received: an error is occured in the queueing of all sending tasks.
  • EINVAL: mbx points to an invalid mailbox.
Definition at line 475 of file mbx.c.

References CHK_MBX_MAGIC, MBX, mbx_signal(), mbx_wait(), mbxput(), rt_sem_signal(), rt_sem_wait(), and RT_TASK.

Here is the call graph for this function:

int _rt_mbx_send_if (  MBX *  mbx,
void *  msg,
int  msg_size,
int  space
) 
 

Sends a message, only if the whole message can be passed without blocking the calling task.

rt_mbx_send_if tries to atomically send the message msg of msg_size bytes to the mailbox mbx. It returns immediately and the caller is never blocked.

Returns:
On success, the number of unsent bytes (0 or msg_size) is returned. On failure a negative value is returned as described below:
  • EINVAL: mbx points to an invalid mailbox.
Definition at line 548 of file mbx.c.

References CHK_MBX_MAGIC, flags, MBX, mbx_signal(), mbxput(), rt_sem_signal(), and RT_TASK.

Here is the call graph for this function:

int _rt_mbx_send_timed (  MBX *  mbx,
void *  msg,
int  msg_size,
RTIME  delay,
int  space
) 
 

Sends a message with relative timeout.

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.

Parameters:
mbx is a pointer to a user allocated mailbox structure.
msg is the message to be sent.
msg_size corresponds to the size of the message.
delay is the timeout value relative to the current time.
Returns:
On success, 0 is returned. On failure a value is returned as described below:
  • the number of bytes not received: an error is occured in the queueing of all sending tasks or the timeout has expired.
  • EINVAL: mbx points to an invalid mailbox.
See also: notes under _rt_mbx_send_until(). Definition at line 640 of file mbx.c.

References _rt_mbx_send_until(), MBX, and RTIME.

Here is the call graph for this function:

int _rt_mbx_send_until (  MBX *  mbx,
void *  msg,
int  msg_size,
RTIME  time,
int  space
) 
 

Sends a message with absolute timeout.

rt_mbx_send_until sends 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.

Parameters:
mbx is a pointer to a user allocated mailbox structure.
msg is the message to be sent.
msg_size corresponds to the size of the message.
time is an absolute value for the timeout.
Returns:
On success, 0 is returned. On failure a value is returned as described below:
  • the number of bytes not received: an error is occured in the queueing of all sending tasks or the timeout has expired.
  • EINVAL: mbx points to an invalid mailbox.
See also: notes under _rt_mbx_send_timed(). Definition at line 594 of file mbx.c.

References CHK_MBX_MAGIC, MBX, mbx_signal(), mbx_wait_until(), mbxput(), rt_sem_signal(), rt_sem_wait_until(), RT_TASK, RTIME, and SEM_ERR.

Referenced by _rt_mbx_send_timed().

Here is the call graph for this function:

int _rt_mbx_send_wp (  MBX *  mbx,
void *  msg,
int  msg_size,
int  space
) 
 

Sends as many bytes as possible without blocking the calling task.

rt_mbx_send_wp atomically sends as many bytes of message msg as possible to the mailbox mbx then returns immediately.

Parameters:
mbx is a pointer to a user allocated mailbox structure.
msg corresponds to the message to be sent.
msg_size is the size of the message.
Returns:
On success, the number of unsent bytes is returned. On failure a negative value is returned as described below:
  • EINVAL: mbx points to an invalid mailbox.
Definition at line 512 of file mbx.c.

References CHK_MBX_MAGIC, flags, MBX, mbx_signal(), mbxput(), rt_sem_signal(), and RT_TASK.

Here is the call graph for this function:

MBX* _rt_typed_named_mbx_init (  unsigned long  mbx_name,
int  size,
int  qtype
) 
 

Initializes a specifically typed (fifo queued, priority queued or resource queued) mailbox identified by a name.

_rt_typed_named_mbx_init initializes a mailbox of type qtype and size size identified by name. Named mailboxed are useful for use among different processes, kernel/user space and in distributed applications, see netrpc.

Parameters:
mbx_name is the mailbox name; since it can be a clumsy identifier, services are provided to convert 6 characters identifiers to unsigned long (see nam2num()).
size corresponds to the size of the mailbox.
qtype corresponds to the queueing policy: FIFO_Q, PRIO_Q or RES_Q.
Returns:
On success the pointer to the allocated mbx is returned. On failure, NULL is returned.
See also: notes under rt_mbx_init() and rt_typed_mbx_init(). Definition at line 904 of file mbx.c.

References IS_MBX, MBX, rt_free(), rt_get_adr_cnt(), rt_malloc(), rt_mbx_delete(), rt_register(), and rt_typed_mbx_init().

Here is the call graph for this function:

void mbx_delete_signal (  MBX *  mbx  )  [static]
 

Definition at line 39 of file mbx.c.

References flags, MBX, RT_SCHED_DELAYED, RT_SCHED_MBXSUSP, RT_SCHED_READY, RT_TASK, and task.

Referenced by rt_mbx_delete().

void mbx_signal (  MBX *  mbx  )  [static]
 

Definition at line 59 of file mbx.c.

References cpuid, flags, MBX, RT_SCHED_DELAYED, RT_SCHED_MBXSUSP, RT_SCHED_READY, RT_SCHED_SUSPENDED, rt_schedule(), RT_TASK, rt_task_delete(), and task.

Here is the call graph for this function:

int mbx_wait (  MBX *  mbx,
int *  fravbs,
RT_TASK *  rt_current
)  [static]
 

Definition at line 120 of file mbx.c.

References flags, MBX, RT_SCHED_MBXSUSP, RT_TASK, and SEM_ERR.

Referenced by _rt_mbx_receive(), _rt_mbx_send(), mbx_receive(), mbx_receive_wjo(), and mbx_send().

int mbx_wait_until (  MBX *  mbx,
int *  fravbs,
RTIME  time,
RT_TASK *  rt_current
)  [static]
 

Definition at line 150 of file mbx.c.

References flags, MBX, RT_SCHED_DELAYED, RT_SCHED_MBXSUSP, rt_smp_time_h, RT_TASK, RTIME, SEM_ERR, and SEM_TIMOUT.

Referenced by _rt_mbx_receive_until(), and _rt_mbx_send_until().

int mbxevdrp (  MBX *  mbx,
char **  msg,
int  msg_size,
int  space
)  [static]
 

Definition at line 295 of file mbx.c.

References MBX, and MOD_SIZE.

Referenced by _rt_mbx_evdrp().

int mbxget (  MBX *  mbx,
char **  msg,
int  msg_size,
int  space
)  [static]
 

Definition at line 267 of file mbx.c.

References flags, MBX, MOD_SIZE, rt_spin_lock_irqsave(), and rt_spin_unlock_irqrestore.

Referenced by _rt_mbx_receive(), _rt_mbx_receive_if(), _rt_mbx_receive_until(), and _rt_mbx_receive_wp().

Here is the call graph for this function:

int mbxovrwrput (  MBX *  mbx,
char **  msg,
int  msg_size,
int  space
)  [static]
 

Definition at line 218 of file mbx.c.

References flags, MBX, MOD_SIZE, rt_spin_lock_irqsave(), and rt_spin_unlock_irqrestore.

Referenced by _rt_mbx_ovrwr_send().

Here is the call graph for this function:

int mbxput (  MBX *  mbx,
char **  msg,
int  msg_size,
int  space
)  [static]
 

Definition at line 190 of file mbx.c.

References flags, MBX, MOD_SIZE, rt_spin_lock_irqsave(), and rt_spin_unlock_irqrestore.

Here is the call graph for this function:

MODULE_LICENSE (  "GPL"   ) 
 

void reset_rt_fun_entries (  struct rt_native_fun_entry *  entry  ) 
 

Definition at line 1543 of file sched.c.

int rt_mbx_delete (  MBX *  mbx  ) 
 

Deletes a mailbox.

rt_mbx_delete removes a mailbox previously created with rt_mbx_init().

Parameters:
mbx is the pointer to the structure used in the corresponding call to rt_mbx_init.
Returns:
0 is returned on success. On failure, a negative value is returned as described below:
  • EINVAL: mbx points to an invalid mailbox.
  • EFAULT: mailbox data were found in an invalid state.
Definition at line 438 of file mbx.c.

References CHK_MBX_MAGIC, MBX, mbx_delete_signal(), rt_sem_delete(), and sched_free.

Referenced by _rt_typed_named_mbx_init(), and rt_named_mbx_delete().

Here is the call graph for this function:

int rt_mbx_init (  MBX *  mbx,
int  size
) 
 

Initializes a mailbox.

rt_mbx_init initializes a mailbox of size size. mbx must point to a user allocated MBX structure. Using mailboxes is a flexible method for inter task communications. Tasks are allowed to send arbitrarily sized messages by using any mailbox buffer size. There is even no need to use a buffer sized at least as the largest message you envisage, even if efficiency is likely to suffer from such a decision. 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 sized messages with a buffer that is an integer multiple of such a size guarantees maximum efficiency by having each message 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. Thus mailboxes provide a flexible mechanism to allow you to freely implement your own policy.

rt_mbx_init is equivalent to rt_typed_mbx_init(mbx, size, PRIO_Q).

Parameters:
mbx is a pointer to a user allocated mailbox structure.
size corresponds to the size of the mailbox.
Returns:
On success 0 is returned. On failure, a special value is returned as indicated below:
  • ENOMEM: Space could not be allocated for the mailbox buffer.
See also: notes under rt_typed_mbx_init(). Definition at line 418 of file mbx.c.

References MBX, PRIO_Q, and rt_typed_mbx_init().

Here is the call graph for this function:

int rt_named_mbx_delete (  MBX *  mbx  ) 
 

Deletes a named mailbox.

rt_named_mbx_delete removes a mailbox previously created with _rt_typed_named_mbx_init().

Parameters:
mbx is the pointer to the structure returned by a corresponding call to _rt_typed_named_mbx_init.
As it is done by all the named allocation functions delete calls have just the effect of decrementing a usage count till the last is done, as that is the one that really frees the object.

Returns:
On success, an integer >=0 is returned. On failure, a negative value is returned as described below:
  • EFAULT: deletion of mailbox failed.
See also: notes under rt_mbx_delete(). Definition at line 943 of file mbx.c.

References MBX, rt_drg_on_adr_cnt(), rt_free(), and rt_mbx_delete().

Referenced by RT_named_mbx_delete().

Here is the call graph for this function:

int rt_typed_mbx_init (  MBX *  mbx,
int  size,
int  type
) 
 

Initializes a fully typed mailbox queueing tasks according to the specified type.

rt_typed_mbx_init initializes a mailbox of size size. mbx must point to a user allocated MBX structure. Tasks are queued in FIFO order (FIFO_Q), priority order (PRIO_Q) or resource order (RES_Q).

Parameters:
mbx is a pointer to a user allocated mailbox structure.
size corresponds to the size of the mailbox.
type corresponds to the queueing policy: FIFO_Q, PRIO_Q or RES_Q.
Returns:
On success 0 is returned. On failure, a special value is returned as indicated below:
  • ENOMEM: Space could not be allocated for the mailbox buffer.
See also: notes under rt_mbx_init(). Definition at line 369 of file mbx.c.

References BIN_SEM, MBX, RT_MBX_MAGIC, rt_typed_sem_init(), and sched_malloc.

Referenced by _rt_typed_named_mbx_init(), and rt_mbx_init().

Here is the call graph for this function:

int set_rt_fun_entries (  struct rt_native_fun_entry *  entry  ) 
 

Definition at line 1555 of file sched.c.

Variable Documentation

struct rt_native_fun_entry rt_mbx_entries[]
 

Initial value:

Definition at line 959 of file mbx.c.

Referenced by __rtai_mbx_exit(), and __rtai_mbx_init().

Generated on Thu Nov 20 11:58:27 2008 for RTAI API by doxygen 1.3.8