@c
@c  COPYRIGHT (c) 1988-2002.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved.
@c
@c  This is the chapter from the RTEMS ITRON User's Guide that
@c  documents the services provided by the message buffer
@c  manager.
@c
@c  $Id$
@c

@chapter Message Buffer Manager

@section Introduction

The message buffer manager provides functions to create, delete, and
control of message buffers.  This manager is based on the ITRON 3.0
standard. 

The services provided by the message buffer manager are:

@itemize @bullet
@item @code{cre_mbf} - Create MessageBuffer
@item @code{del_mbf} - Delete MessageBuffer
@item @code{snd_mbf} - Send Message to MessageBuffer
@item @code{psnd_mbf} - Poll and Send Message to MessageBuffer
@item @code{tsnd_mbf} - Send Message to MessageBuffer with Timeout
@item @code{rcv_mbf} - Receive Message from MessageBuffer
@item @code{prcv_mbf} - Poll and Receive Message from MessageBuffer
@item @code{trcv_mbf} - Receive Message from MessageBuffer with Timeout
@item @code{ref_mbf} - Reference MessageBuffer Status
@end itemize

@section Background

@subsection T_CMBF Structure

The T_CMBF structure is used to define the characteristics of a message
buffer and passed as an argument to the @code{cre_mbf} routine. This
structure is defined as:

@example
@group

typedef struct t_cmbf @{
  VP      exinf;   /* extended information */
  ATR     mbfatr;  /* message buffer attributes */
  INT     bufsz;   /* buffer size (in bytes) */
  INT     maxmsz;  /* maximum message size (in bytes) */
  /* (CPU and/or implementation-dependent information may also be
  included) */
@} T_CMBF;

@end group
@end example

where the meaning of each field is:

@table @b
@item exinf
is for any extended information that the implementation may define. This
implementation does not use this field.

@item mbfatr
is the attributes for the message buffer. The only attributes which can
be specified is whether tasks wait in FIFO (@code{TA_TFIFO}) or priority
(@code{TA_TPRI}) order.

@item bufsz
is the size of the message buffer. Since some control data are needed to
manage each messages in the message buffer, @code{bufsz} is usually
larger than the total of all message sizes in this buffer.

@item maxmsz
is the maximum message size.

@end table

@subsection T_RMBF Structure

The T_RMBF structure is filled in by the @code{ref_mbf} routine with
status and state information of the message buffer. The structure is
defined as follows:

@example
@group

typedef struct t_rmbf @{
  VP      exinf;   /* extended information */
  BOOL_ID wtsk;    /* waiting task information */
  BOOL_ID stsk;    /* sending task information */
  INT     msgsz;   /* message size (in bytes) */
  INT     frbufsz; /* free buffer size (in bytes) */
  /* (CPU and/or implementation-dependent information is returned) */
@} T_RMBF;

@end group
@end example

@table @b

@item exinf
is for any extended information that the implementation may define.
This implementation does not use this field.

@item wtsk
is TRUE when there is one or more tasks waiting on this message buffer
to send message. It is FALSE when there is no waiting task. The meaning
of this field is allowed to vary between ITRON implementations.  It may
have the ID of a waiting task, the number of tasks waiting, or a boolean
indication that one or more tasks are waiting.

@item stsk
is TRUE when there is one or more tasks waiting on this message buffer
to receive message. It is FALSE when there is no waiting task. The meaning
of this field is allowed to vary between ITRON implementations.  It may
have the ID of a waiting task, the number of tasks waiting, or a boolean
indication that one or more tasks are waiting.

@item msgsz
is the size of the message that is at the head of the message buffer. If
there is no message on the message queue, @code{msgsz} will be returned
as FALSE = 0.

@item frbufsz
is the amount of free memory in the message buffer. 

@end table

@section Operations

@section System Calls

This section details the message buffer manager's services.
A subsection is dedicated to each of this manager's services
and describes the calling sequence, related constants, usage,
and status codes.

@c
@c  cre_mbf
@c

@page
@subsection cre_mbf - Create MessageBuffer

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER cre_mbf(
  ID mbfid,
  T_CMBF *pk_cmbf
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_NOMEM} - Insufficient memory (Memory for control block and/or
ring buffer cannot be allocted)

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_RSATR} - Reserved attribute (mbfatr was invalid or could not be
used)

@code{E_OBJ} - Invalid object state (a messagebuffer of the same ID
already exists)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{E_PAR} - Parameter error (pk_cmbf is invalid or bufsz and/or
maxmsz is negative or invalid) 

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.


@code{EN_CTXID} - Specified an object on another node when the system
call was issued from a task in dispatch disabled state or from a
task-independent portion

@code{EN_PAR} - A value outside the range supported by the target node
and/or transmission packet format was specified as a parameter (a value
outside supported range was specified for exinf, mbfatr, bufsz and/or
maxmsz) 

@subheading DESCRIPTION:

This routine creates a message buffer on the local node. The message
buffer is initialized based on the attributes specified in the
@code{pk_cmbf} structure. The buffer size and the maximum message size
are determined by the @code{bufsz} and @code{maxmsz} fields in this
structure. 

The @code{mbfatr} field represents attributes of the message
buffer. If @code{TA_TFIFO} is specified, tasks will be put on the queue
on a First In-First Out basis. If @code{TA_TPRI} is specified, tasks
will be placed on the queue according to their priority.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.

@c
@c  del_mbf
@c

@page
@subsection del_mbf - Delete MessageBuffer

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER del_mbf(
  ID mbfid
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_NOEXS} - Object does not exist (the messagebuffer specified by
mbfid does not exist)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.

@code{EN_CTXID} - Specified an object on another node when the system
call was issued from a task in dispatch disabled state or from a
task-independent portion 

@subheading DESCRIPTION:

This routine deletes the message buffer specified by @code{mbfid}. 
Issuing this system call releases memory area used for the control block of
the associated message buffer and the buffer area used for storing messages.

This routine will complete normally even if there are tasks waiting to
send or receive messages at the message buffer.  In that case, an
@code{E_DLT} error will be returned to each waiting task.  If there are
messages still in the message buffer, they will be deleted along with
the message buffer and no error will result.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.

@c
@c  snd_mbf
@c

@page
@subsection snd_mbf - Send Message to Message Buffer

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER snd_mbf(
  ID mbfid,
  VP msg,
  INT msgsz
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_NOEXS} - Object does not exist (the message buffer specified by
mbfid does not exist)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{E_PAR} - Parameter error (msgsz is 0 or less; msgsz is larger than
maxmsz; values unsuitable for msg; tmout is -2 or less) 

@code{E_DLT} - The object being waited for was deleted (the
message buffer of interest was deleted while waiting)

@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
while waiting)

@code{E_CTX} - Context error (issued from task-independent portions or a
task in dispatch disabled state; implementation dependent for psnd_mbf
and tsnd_mbf(tmout=TMO_POL)) 

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.

@code{EN_CTXID} - Specified an object on another node when the system
call was issued from a task in dispatch disabled state or from a
task-independent portion (implementation-dependent; applicable to
psnd_mbf and tsnd_mbf (tmout=TMO_POL) only) 

@code{EN_PAR} - A value outside the range supported by the target node
and/or transmission packet format was specified as a parameter (a value
outside supported range was specified for msgsz and/or tmout) 

@subheading DESCRIPTION:

This routine sends the message stored at the address given by @code{msg}
to the message buffer specified by @code{mbfid}.  The size of the
message is specified by @code{msgsz}; that is, @code{msgsz} number of
bytes beginning from @code{msg} are copied to the message buffer
specified by @code{mbfid}.  If the available space in the buffer is not
enough to include the message given by @code{msg}, the task issuing this
system call will wait on a send wait queue until more buffer space
becomes available.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.

@c
@c  psnd_mbf
@c

@page
@subsection psnd_mbf - Poll and Send Message to Message Buffer

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER ercd =psnd_mbf(
  ID mbfid,
  VP msg,
  INT msgsz
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_NOEXS} - Object does not exist (the message buffer specified by
mbfid does not exist)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{E_PAR} - Parameter error (msgsz is 0 or less; msgsz is larger than
maxmsz; values unsuitable for msg; tmout is -2 or less) 

@code{E_DLT} - The object being waited for was deleted (the
message buffer of interest was deleted while waiting)

@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
while waiting)

@code{E_TMOUT} - Polling failure or timeout

@code{E_CTX} - Context error (issued from task-independent portions or a
task in dispatch disabled state; implementation dependent for psnd_mbf
and tsnd_mbf(tmout=TMO_POL)) 

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.

@code{EN_CTXID} - Specified an object on another node when the system
call was issued from a task in dispatch disabled state or from a
task-independent portion (implementation-dependent; applicable to
psnd_mbf and tsnd_mbf (tmout=TMO_POL) only) 

@code{EN_PAR} - A value outside the range supported by the target node
and/or transmission packet format was specified as a parameter (a value
outside supported range was specified for msgsz and/or tmout) 

@subheading DESCRIPTION:

This routine has the same function as @code{snd_mbf} except for the
waiting feature.  @code{Psnd_mbf} polls whether or not the task should
wait if @code{snd_mbf} is executed.  The meaning of parameters to
@code{psnd_mbf} are the same as for @code{snd_mbf}.  The specific
operations by @code{psnd_mbf} are as follows.

  - If there is enough space in the buffer, processing is the same as
  @code{snd_mbf}: the message is sent and the system call completes
  normally.

  - If there is not enough space in the buffer, an @code{E_TMOUT} error
  is returned to indicate polling failed and the system call finishes.
  Unlike @code{snd_mbf}, the issuing task does not wait in this case.
  The status of the message buffer and the message queue remain unchanged.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.

@c
@c  tsnd_mbf
@c

@page
@subsection tsnd_mbf - Send Message to Message Buffer with Timeout

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER ercd =tsnd_mbf(
  ID mbfid,
  VP msg,
  INT msgsz,
  TMO tmout
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_NOEXS} - Object does not exist (the message buffer specified by
mbfid does not exist)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{E_PAR} - Parameter error (msgsz is 0 or less; msgsz is larger than
maxmsz; values unsuitable for msg; tmout is -2 or less) 

@code{E_DLT} - The object being waited for was deleted (the
message buffer of interest was deleted while waiting)

@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
while waiting)

@code{E_TMOUT} - Polling failure or timeout

@code{E_CTX} - Context error (issued from task-independent portions or a
task in dispatch disabled state; implementation dependent for psnd_mbf
and tsnd_mbf(tmout=TMO_POL)) 

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.

@code{EN_CTXID} - Specified an object on another node when the system
call was issued from a task in dispatch disabled state or from a
task-independent portion (implementation-dependent; applicable to
psnd_mbf and tsnd_mbf (tmout=TMO_POL) only) 

@code{EN_PAR} - A value outside the range supported by the target node
and/or transmission packet format was specified as a parameter (a value
outside supported range was specified for msgsz and/or tmout) 

@subheading DESCRIPTION:

The @code{tsnd_mbf} system call has the same function as @code{snd_mbf}
with an additional timeout feature.  A maximum wait time (timeout value)
can be specified using the parameter @code{tmout}.  When a timeout is
specified, a timeout error, @code{E_TMOUT}, will result and the system
call will finish if the period specified by @code{tmout} elapses without
conditions for releasing wait being satisfied (i.e. without sufficient
buffer space becoming available).

Only positive values can be specified for @code{tmout}.  Specifying
@code{TMO_POL} = 0 to @code{tsnd_mbf} for @code{tmout} indicates that a
timeout value of 0 be used, resulting in exactly the same processing as
@code{psnd_mbf}.  Specifying @code{TMO_FEVR} = -1 to @code{tsnd_mbf} for
@code{tmout} indicates that an infinite timeout value be used, resulting
in exactly the same processing as @code{snd_mbf}.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.


@c
@c  rcv_mbf
@c

@page
@subsection rcv_mbf - Receive Message from Message Buffer

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER rcv_mbf(
  VP msg,
  INT *p_msgsz,
  ID mbfid
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_NOEXS} - Object does not exist (the message buffer specified by
mbfid does not exist)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{E_PAR} - Parameter error (values unsuitable for msg; tmout is -2
or less) 

@code{E_DLT} - The object being waited for was deleted (the specified
message buffer was deleted while waiting)

@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
while waiting)

@code{E_CTX} - Context error (issued from task-independent portions or a
task in dispatch disabled state) 

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.

@code{EN_PAR} - A value outside the range supported by the target node
and/or transmission packet format was specified as a parameter (a value
outside supported range was specified for tmout)

@code{EN_RPAR} - A value outside the range supported by the issuing node
and/or transmission packet format was returned as a return parameter (msgsz is outside supported range for requesting node)

@subheading DESCRIPTION:

@code{Rcv_mbf} receives the message from the message buffer specified by
@code{mbfid}, and stores it at the memory location given by @code{msg}.
In other words, the content of the message at the head of the message
buffer specified by @code{mbfid} is copied into an area which begins
from @code{msg} and whose size is @code{msgsz}.

If the message buffer is empty, the task issuing this system call will wait
on a receive message wait queue until a message arrives.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.


@c
@c  prcv_mbf
@c

@page
@subsection prcv_mbf - Poll and Receive Message from Message Buffer

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER ercd =prcv_mbf(
  VP msg,
  INT *p_msgsz,
  ID mbfid
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_NOEXS} - Object does not exist (the message buffer specified by
mbfid does not exist)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{E_PAR} - Parameter error (values unsuitable for msg; tmout is -2
or less) 

@code{E_DLT} - The object being waited for was deleted (the specified
message buffer was deleted while waiting)

@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
while waiting)

@code{E_TMOUT} - Polling failure or timeout

@code{E_CTX} - Context error (issued from task-independent portions or a
task in dispatch disabled state) 

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.

@code{EN_PAR} - A value outside the range supported by the target node
and/or transmission packet format was specified as a parameter (a value
outside supported range was specified for tmout)

@code{EN_RPAR} - A value outside the range supported by the issuing node
and/or transmission packet format was returned as a return parameter (msgsz is outside supported range for requesting node)


@subheading DESCRIPTION:
The @code{prcv_mbf} system call has the same function as @code{rcv_mbf}
except for the waiting feature.  @code{Prcv_mbf} polls whether or not
the task should wait if @code{rcv_mbf} is executed.  The meaning of
parameters to @code{prcv_mbf} are the same as for @code{rcv_mbf}.  The
specific operations by @code{prcv_mbf} are as follows.

  - If there is a message in the specified message buffer, processing is
the same as @code{rcv_mbf}: the first message on the message buffer is
retrieved and the system call completes normally.

  - If there is no message in the specified message buffer, an
@code{E_TMOUT} error is returned to indicate polling failed and the
system call finishes.  Unlike @code{rcv_mbf}, the issuing task does not
wait in this case.  The status of the message buffer remain unchanged.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.


@c
@c  trcv_mbf
@c

@page
@subsection trcv_mbf - Receive Message from Message Buffer with Timeout

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER ercd =trcv_mbf(
  VP msg,
  INT *p_msgsz,
  ID mbfid,
  TMO tmout
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_NOEXS} - Object does not exist (the message buffer specified by
mbfid does not exist)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{E_PAR} - Parameter error (values unsuitable for msg; tmout is -2
or less) 

@code{E_DLT} - The object being waited for was deleted (the specified
message buffer was deleted while waiting)

@code{E_RLWAI} - WAIT state was forcibly released (rel_wai was received
while waiting)

@code{E_TMOUT} - Polling failure or timeout

@code{E_CTX} - Context error (issued from task-independent portions or a
task in dispatch disabled state) 

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.

@code{EN_PAR} - A value outside the range supported by the target node
and/or transmission packet format was specified as a parameter (a value
outside supported range was specified for tmout)

@code{EN_RPAR} - A value outside the range supported by the issuing node
and/or transmission packet format was returned as a return parameter (msgsz is outside supported range for requesting node)

@subheading DESCRIPTION:
The @code{trcv_mbf} system call has the same function as @code{rcv_mbf}
with an additional timeout feature.  A maximum wait time (timeout value)
can be specified using the parameter @code{tmout}.  When a timeout is
specified, a timeout error, @code{E_TMOUT}, will result and the system
call will finish if the period specified by @code{tmout} elapses without
conditions for releasing wait being satisfied (i.e. without a message
arriving).

Only positive values can be specified for @code{tmout}.  Specifying
@code{TMO_POL} = 0 to @code{trcv_mbf} for @code{tmout} indicates that a
timeout value of 0 be used, resulting in exactly the same processing as
@code{prcv_mbf}.  Specifying @code{TMO_FEVR} = -1 to @code{trcv_mbf} for
tmout indicates that an infinite timeout value be used, resulting in
exactly the same processing as @code{rcv_mbf}.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.

@c
@c  ref_mbf
@c

@page
@subsection ref_mbf - Reference Message Buffer Status

@subheading CALLING SEQUENCE:

@ifset is-C
@example
ER ref_mbf(
  T_RMBF *pk_rmbf,
  ID mbfid
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@code{E_OK} - Normal Completion

@code{E_ID} - Invalid ID number (mbfid was invalid or could not be used)

@code{E_NOEXS} - Object does not exist (the message buffer specified by
mbfid does not exist)

@code{E_OACV} - Object access violation (A mbfid less than -4 was
specified from a user task.  This is implementation dependent.)

@code{E_PAR} - Parameter error (the packet address for the return
parameters could not be used) 

@code{EN_OBJNO} - An object number which could not be accessed on the
target node is specified.

@code{EN_CTXID} - Specified an object on another node when the system
call was issued from a task in dispatch disabled state or from a
task-independent portion

@code{EN_RPAR} - A value outside the range supported by the issuing node
and/or transmission packet format was returned as a return parameter (a
value outside supported range for exinf, wtsk, stsk, msgsz and/or
frbufsz on a requesting node) 

@subheading DESCRIPTION:
This system call refers to the state of the message buffer specified by
@code{mbfid}, and returns information of a task waiting to send a
message (@code{stsk}), the size of the next message to be received
(@code{msgsz}), the free buffer size (@code{frbufsz}), information of a
task waiting to receive a message (@code{wtsk}), and its extended
information (@code{exinf}).

@code{Wtsk} and @code{stsk} indicate whether or not there is a task
waiting for the message buffer in question.  If there is no waiting
task, @code{wtsk} and @code{stsk} are returned as @code{FALSE} = 0.  If
there is a waiting task, @code{wtsk} and @code{stsk} are returned as
values other than 0.

An @code{E_NOEXS} error will result if the message buffer specified to
@code{ref_mbf} does not exist.

The size of the message at the head of the message buffer (the next
message to be received) is returned to @code{msgsz}.  If there are no
messages on the message buffer, @code{msgsz} will be returned as
@code{FALSE} = 0.  A message whose size is zero cannot be sent.

At least one of @code{msgsz} = @code{FALSE} and @code{wtsk} =
@code{FALSE} is always true in this system call.

@code{Frbufsz} indicates the amount of free memory in the message
buffer.  This value can be used to know the total approximate size of
the messages which can be sent to the message buffer.

@subheading NOTES:

Multiprocessing is not supported.  Thus none of the "EN_" status codes
will be returned.