msgqlib.c

VXWORKS源代码

/* msgQLib.c - message queue library */

/* Copyright 1990-2001 Wind River Systems, Inc. */
#include "copyright_wrs.h"

/*
modification history
--------------------
02n,10dec01,bwa  Added comment about MSG_Q_EVENTSEND_ERR_NOTIFY msgQCreate
                 option (SPR 72058).
02m,26oct01,bwa  Added msgQEvLib and eventLib to the list of 'SEE ALSO'
                 modules.
02l,12oct01,cjj  Added documentation regarding S_eventLib_EVENTSEND_FAILED
                 error
02k,09oct01,gls  merged in 02j, 02i, 02h, 02g below from AE.
02j,22feb01,ahm  ensured errno does'nt change if msgQDelete() is successful
                 (SPR#34643)
02i,19sep00,bwa  passed extra argument (msgQid) to calls to qJobGet()
                 added errnoSet after calls to qJobGet()(SPR #34057) 
02h,06sep00,aeg  doc: mentioned INCLUDE_MSG_Q component name.
02g,11aug00,aeg  fixed updating of timeout stats in msgQSend/Receive (SPR 33683)
02f,07sep01,bwa  Added VxWorks events support. Fixed SPR #31241 (corrected
		 msgQReceive comment for NO_WAIT).
02e,18dec00,pes  Correct compiler warnings
02d,19may98,drm  merged code from 3rd party to add distributed message queue 
                 support.
                 - merged code was originally based on version 02a 
02c,11may98,cjtc fix problem with problem fix!! Multiple calls to object
                 instrumentation in msgQDestroy
02b,11may98,nps  fixed msgQDestroy instrumentation anomaly.
02c,17apr98,rlp  canceled msgQInit and msgQSend modifications for backward
                 compatibility.
02b,04nov97,rlp  modified msgQInit and msgQSend for tracking messages sent.
02a,24jun96,sbs  made windview instrumentation conditionally compiled
01z,22oct95,jdi  doc: added bit values for options (SPR 4276).
02d,14apr94,smb  fixed class dereferencing for instrumentation macros
02c,15mar94,smb  modified instrumentation macros
02b,24jan94,smb  added instrumentation macros
02a,18jan94,smb  added instrumentation corrections for msgQDelete
01z,10dec93,smb  added instrumentation
01y,30jun93,jmm  changed msgQDestroy to look at msgQ as well as freeQ (spr 2070)
01x,02feb93,jdi  documentation cleanup for 5.1.
01w,13nov92,jcf  package init called with object creation.
01v,19oct92,pme  added reference to shared message queue documentation.
01u,23aug92,jcf  balanced taskSafe with taskUnsafe.
01t,11aug92,jcf  fixed msgQDestroy safety problem.
01s,30jul92,rrr  added restart and msgQ fix
01r,29jul92,pme  added NULL function pointer check for smObj routines.
01q,29jul92,jcf  package init called with object initialization.
01p,22jul92,pme  made msgQDestroy return S_smObjLib_NO_OBJECT_DESTROY when
		 trying to destroy a shared message queue.
01o,19jul92,pme  added shared message queue support.
01n,18jul92,smb  Changed errno.h to errnoLib.h.
01m,04jul92,jcf	 show routine removed.
01l,26may92,rrr  the tree shuffle
01k,13dec91,gae  ANSI fixes.  
01j,19nov91,rrr  shut up some ansi warnings.
01i,04oct91,rrr  passed through the ansification filter
                  -changed functions to ansi style
		  -changed includes to have absolute path from h/
		  -changed VOID to void
		  -changed copyright notice
01h,10aug91,del  changed interface to qInit to pass all "optional" args.
01g,05apr91,jdi	 documentation -- removed header parens and x-ref numbers;
		 doc review by dnw.
01f,22jan91,jaa	 documentation.
01e,08oct90,dnw  lint
01d,01oct90,dnw  fixed bug of msgQSend() not returning ERROR on timeout.
		 removed msgQSendArgs()/ReceiveArgs().
		 reordered parameters of msgQ{Send,Receive}().
		 simplified msgQInfoGet() interface.
		 added msgQNumMsgs().
		 made msgQDestroy() LOCAL.
		 made msgQ{LibInit,Init,Terminate}() be NOMANUAL.
		 finished documentation.
01c,19jul90,dnw  added VARARGS to msgQ{Send,Receive}Args()
01b,19jul90,dnw  changed call to objAlloc() to objAllocExtra()
		 made msgQShow() prettier
		 lint
01a,10may90,dnw  written
*/

/*
DESCRIPTION
This library contains routines  for creating and using message queues, the 
primary intertask communication mechanism within a single CPU.  Message
queues allow a variable number of messages (varying in length) to be
queued in first-in-first-out (FIFO) order.  Any task or interrupt service
routine can send messages to a message queue.  Any task can receive
messages from a message queue.  Multiple tasks can send to and receive
from the same message queue.  Full-duplex communication between two tasks
generally requires two message queues, one for each direction.

To provide message queue support for a system, VxWorks must be configured
with the INCLUDE_MSG_Q component.

CREATING AND USING MESSAGE QUEUES
A message queue is created with msgQCreate().  Its parameters specify the
maximum number of messages that can be queued to that message queue and 
the maximum length in bytes of each message.  Enough buffer space will 
be pre-allocated to accommodate the specified number of messages of 
specified length.

A task or interrupt service routine sends a message to a message queue
with msgQSend().  If no tasks are waiting for messages on the message queue,
the message is simply added to the buffer of messages for that queue.
If any tasks are already waiting to receive a message from the message
queue, the message is immediately delivered to the first waiting task.

A task receives a message from a message queue with msgQReceive().
If any messages are already available in the message queue's buffer,
the first message is immediately dequeued and returned to the caller.
If no messages are available, the calling task will block and be added to
a queue of tasks waiting for messages.  This queue of waiting tasks can
be ordered either by task priority or FIFO, as specified in an option
parameter when the queue is created.

TIMEOUTS
Both msgQSend() and msgQReceive() take timeout parameters.  When sending a
message, if no buffer space is available to queue the message, the timeout
specifies how many ticks to wait for space to become available.  When
receiving a message, the timeout specifies how many ticks to wait if no
message is immediately available.  The <timeout> parameter can
have the special values NO_WAIT (0) or WAIT_FOREVER (-1).  NO_WAIT 
means the routine should return immediately; WAIT_FOREVER means the routine
should never time out.

URGENT MESSAGES
The msgQSend() routine allows the priority of a message to be specified
as either normal or urgent, MSG_PRI_NORMAL (0) and MSG_PRI_URGENT (1),
respectively.  Normal priority messages are added to the tail of the list
of queued messages, while urgent priority messages are added to the head
of the list.

VXWORKS EVENTS
If a task has registered with a message queue via msgQEvStart(), events will
be sent to that task when a message arrives on that message queue, on the
condition that no other task is pending on the queue.

INTERNAL:
	WINDVIEW INSTRUMENTATION
Level 1:
	msgQCreate() causes EVENT_MSGQCREATE
	msgQDestroy() causes EVENT_MSGQDELETE
	msgQSend() causes EVENT_MSGQSEND
	msgQReceive() causes EVENT_MSGQRECEIVE

Level 2:
	N/A

Level 3:
	N/A

INCLUDE FILES: msgQLib.h

SEE ALSO: pipeDrv, msgQSmLib, msgQEvLib, eventLib,
.pG "Basic OS"
*/

#include "vxWorks.h"
#include "stdlib.h"
#include "string.h"
#include "taskLib.h"
#include "intLib.h"
#include "smObjLib.h"
#include "errnoLib.h"
#include "private/eventLibP.h"
#include "private/classLibP.h"
#include "private/objLibP.h"
#include "private/msgQLibP.h"
#include "private/msgQSmLibP.h"
#include "private/distObjTypeP.h"
#include "private/sigLibP.h"
#include "private/eventP.h"
#include "private/windLibP.h"
#include "private/kernelLibP.h"


/* locals */

LOCAL OBJ_CLASS msgQClass;

/* globals */

CLASS_ID msgQClassId = &msgQClass;

/* Instrumentation locals and globals */

#ifdef WV_INSTRUMENTATION
LOCAL OBJ_CLASS msgQInstClass;
CLASS_ID msgQInstClassId = &msgQInstClass;
#endif

/* shared memory objects function pointers */

FUNCPTR  msgQSmSendRtn;
FUNCPTR  msgQSmReceiveRtn;
FUNCPTR  msgQSmNumMsgsRtn;

/* distributed objects function pointers */

FUNCPTR  msgQDistSendRtn;
FUNCPTR  msgQDistReceiveRtn;
FUNCPTR  msgQDistNumMsgsRtn;

/* forward declarations */

LOCAL STATUS msgQDestroy (MSG_Q_ID msgQId, BOOL dealloc);

/* locals */

LOCAL BOOL msgQLibInstalled;	/* protect from muliple inits */


/*******************************************************************************
*
* msgQLibInit - initialize message queue library
*
* This routine initializes message queue facility.
* It is called once in kernelInit().
*
* RETURNS: OK or ERROR
*
* NOMANUAL
*/

STATUS msgQLibInit (void)
    {
    /* initialize shared memory objects function pointers */

    if (!msgQLibInstalled)
	{
	if (classInit (msgQClassId, sizeof (MSG_Q), OFFSET (MSG_Q, objCore),
		       (FUNCPTR)msgQCreate, (FUNCPTR)msgQInit,
		       (FUNCPTR)msgQDestroy) == OK)
	    {

#ifdef WV_INSTRUMENTATION
	    /* Instrumented class for windview */
	    msgQClassId->initRtn = msgQInstClassId;
            classInstrument (msgQClassId,msgQInstClassId);
#endif

	    msgQEvLibInit (); /* pull msgQLib in kernel */

	    msgQLibInstalled = TRUE;
	    }
	}

    return ((msgQLibInstalled) ? OK : ERROR);
    }

/*******************************************************************************
*
* msgQCreate - create and initialize a message queue
*
* This routine creates a message queue capable of holding up to <maxMsgs>
* messages, each up to <maxMsgLength> bytes long.  The routine returns 
* a message queue ID used to identify the created message queue in all 
* subsequent calls to routines in this library.  The queue can be created 
* with the following options:
* .iP "MSG_Q_FIFO  (0x00)" 8
* queue pended tasks in FIFO order.
* .iP "MSG_Q_PRIORITY  (0x01)"
* queue pended tasks in priority order.
* .iP "MSG_Q_EVENTSEND_ERR_NOTIFY (0x02)"
* When a message is sent, if a task is registered for events and the
* actual sending of events fails, a value of ERROR is returned and the errno
* is set accordingly. This option is off by default.
* .LP
*
* RETURNS:
* MSG_Q_ID, or NULL if error.
*
* ERRNO: S_memLib_NOT_ENOUGH_MEMORY, S_intLib_NOT_ISR_CALLABLE
*
* SEE ALSO: msgQSmLib
*/

MSG_Q_ID msgQCreate
    (
    int         maxMsgs,        /* max messages that can be queued */
    int         maxMsgLength,   /* max bytes in a message */
    int         options         /* message queue options */
    )
    {
    MSG_Q_ID	msgQId;
    void *	pPool;		/* pointer to memory for messages */
    UINT	size = (UINT) maxMsgs * MSG_NODE_SIZE (maxMsgLength);

    if (INT_RESTRICT () != OK)		/* restrict ISR from calling */
	return (NULL);

    if ((!msgQLibInstalled) && (msgQLibInit () != OK))
	return (NULL);			/* package init problem */

    if ((msgQId = (MSG_Q_ID)objAllocExtra (msgQClassId, size, &pPool)) == NULL)
	return (NULL);

    if (msgQInit (msgQId, maxMsgs, maxMsgLength, options, pPool) != OK)
	{
	objFree (msgQClassId, (char *) msgQId);
	return (NULL);
	}

#ifdef WV_INSTRUMENTATION
    /* windview - level 1 event logging routine */
    EVT_OBJ_4 (OBJ, msgQId, msgQClassId, EVENT_MSGQCREATE, 
		msgQId, maxMsgs, maxMsgLength, options);
#endif

    return ((MSG_Q_ID) msgQId);
    }

/*******************************************************************************
*
* msgQInit - initialize a message queue
*
* This routine initializes a message queue data structure.  Like msgQCreate()
* the resulting message queue is capable of holding up to <maxMsgs> messages,
* each of up to <maxMsgLength> bytes long.
* However, instead of dynamically allocating the MSG_Q data structure,
* this routine takes a pointer <pMsgQ> to the MSG_Q data structure to be
* initialized, and a pointer <pMsgPool> to the buffer to be use to hold
* queued messages.  <pMsgPool> must point to a 4 byte aligned buffer
* that is (<maxMsgs> * MSG_NODE_SIZE (<maxMsgLength>)).
*
* The queue can be created with the following options:
*
*	MSG_Q_FIFO	queue pended tasks in FIFO order
*	MSG_Q_PRIORITY	queue pended tasks in priority order
*
* RETURNS: OK or ERROR.
*
* ERRNO: S_msgQLib_INVALID_QUEUE_TYPE
*
* SEE ALSO: msgQCreate()
*
* NOMANUAL
*/

STATUS msgQInit
    (
    FAST MSG_Q *pMsgQ,          /* pointer to msg queue to initialize */
    int         maxMsgs,        /* max messages that can be queued */
    int         maxMsgLength,   /* max bytes in a message */
    int         options,        /* message queue options */
    void *      pMsgPool        /* pointer to memory for messages */
    )
    {
    FAST int		nodeSize = MSG_NODE_SIZE (maxMsgLength);
    FAST int		ix;
    FAST Q_CLASS_ID	msgQType;

    if ((!msgQLibInstalled) && (msgQLibInit () != OK))
	return (ERROR);				/* package init problem */

    bzero ((char *) pMsgQ, sizeof (*pMsgQ));	/* clear out msg q structure */

    /* initialize internal job queues */

    switch (options & MSG_Q_TYPE_MASK)
        {
        case MSG_Q_FIFO:	msgQType = Q_FIFO;	break;
        case MSG_Q_PRIORITY:	msgQType = Q_PRI_LIST;	break;

        default:
            errnoSet (S_msgQLib_INVALID_QUEUE_TYPE);
	    return (ERROR);
        }

    if ((qInit ((Q_HEAD *) &pMsgQ->msgQ, qJobClassId, msgQType,
	 0, 0, 0, 0, 0, 0, 0, 0, 0) != OK) ||
	(qInit ((Q_HEAD *) &pMsgQ->freeQ, qJobClassId, msgQType,
	 0, 0, 0, 0, 0, 0, 0, 0, 0) != OK))
	return (ERROR);


    /* put msg nodes on free list */

    for (ix = 0; ix < maxMsgs; ix++)
	{
	qJobPut (pMsgQ, &pMsgQ->freeQ, (Q_JOB_NODE *) pMsgPool,
		 Q_JOB_PRI_DONT_CARE);
	pMsgPool = (void *) (((char *) pMsgPool) + nodeSize);
	}


    /* initialize rest of msg q */

    pMsgQ->options	= options;
    pMsgQ->maxMsgs	= maxMsgs;
    pMsgQ->maxMsgLength	= maxMsgLength;

    eventInit (&pMsgQ->events);

#ifdef WV_INSTRUMENTATION
    if (wvObjIsEnabled)
    {
    /* windview - connect level 1 event logging routine */
    objCoreInit (&pMsgQ->objCore, msgQInstClassId);
    }
    else
#endif
    objCoreInit (&pMsgQ->objCore, msgQClassId);

    return (OK);
    }

/******************************************************************************
*
* msgQTerminate - terminate message queue
*
* This routine terminates a static message queue that was initialized with
* msgQInit.
*
* RETURNS: OK or ERROR.
*
* NOMANUAL
*/

STATUS msgQTerminate
    (
    MSG_Q_ID msgQId     /* message queue id to terminate */
    )
    {
    return (msgQDestroy (msgQId, FALSE));
    }

/*******************************************************************************
*
* msgQDelete - delete a message queue
*
* This routine deletes a message queue.  All tasks pending on either
* msgQSend(), msgQReceive() or pending for the reception of events
* meant to be sent from the message queue will unblock and return
* ERROR.  When this function returns, <msgQId> is no longer a valid 
* message queue ID.
*
* RETURNS: OK on success or ERROR otherwise.
*
* ERRNO:
* .iP "S_objLib_OBJ_ID_ERROR"
* Message queue ID is invalid
* .iP "S_intLib_NOT_ISR_CALLABLE"
* Routine cannot be called from ISR
* .iP "S_distLib_NO_OBJECT_DESTROY"
* Deleting a distributed message queue is not permitted
* .iP "S_smObjLib_NO_OBJECT_DESTROY"
* Deleting a shared message queue is not permitted
* SEE ALSO: msgQSmLib
*/

STATUS msgQDelete
    (
    MSG_Q_ID msgQId     /* message queue to delete */
    )
    {
    return (msgQDestroy (msgQId, TRUE));
    }

/*******************************************************************************
*
* msgQDestroy - destroy message queue
*
* RETURNS: OK or ERROR.
*
* ERRNO: S_distLib_NO_OBJECT_DESTROY
*
*/

LOCAL STATUS msgQDestroy
    (
    MSG_Q_ID msgQId,    /* message queue to destroy */
    BOOL     dealloc    /* deallocate memory associated with message queue */
    )
    {
    Q_JOB_NODE *pNode;
    FAST int	timeout;
    FAST int	nMsgs;

    int errnoCopy;