qfifoglib.c

vxworks源码源码解读是学习vxworks的最佳途径

/* qFifoGLib.c - global FIFO queue library */

/* Copyright 1984-1992 Wind River Systems, Inc. */
#include "copyright_wrs.h"

/*
modification history
--------------------
01e,29jan93,pme  added little endian support
01d,02oct92,pme  added SPARC support.
01c,29sep92 pme  added comments to qFifoGRemove.
01b,30jul92,pme	 removed qFifoGLibInit, added qFifoGInit.
                 cleanup.
01a,19jul92,pme	 fixed shared semaphore race, made qFifoGRemove return STATUS.
               	 written.
*/

/*
DESCRIPTION
This library contains routines to manage a first-in-first-out global queue 
stored in shared memory.
The routine qFifoGPut takes a key in addition to a node to queue.  This key
determines whether the node is placed at the head or tail of the queue.

This queue complies with the multi-way queue data structures and thus may be
utilized by any multi-way queue.  The FIFO multi-way queue class is accessed
by the global id qFifoGClassId.

The pointer to a global fifo queue points on a structure which
contains the effective queue and a integer used as a spin-lock for the queue.
This mecanism allows use of standard kernel functions such as windPendPut
and windPendQGet to operate on multi-processor shared queue.

INCLUDE FILE: qFifoGLib.h

SEE ALSO: qLib.
*/

#include "vxWorks.h"
#include "intLib.h"
#include "smLib.h"
#include "qClass.h"
#include "qFifoGLib.h"
#include "stdlib.h"
#include "taskLib.h"
#include "netinet/in.h"
#include "private/smObjLibP.h"

/* forward static functions */

static STATUS qFifoGNullRtn (void);

/* locals */

LOCAL Q_CLASS qFifoGClass =
    {
    (FUNCPTR)qFifoGNullRtn,
    (FUNCPTR)qFifoGInit,
    (FUNCPTR)qFifoGNullRtn,
    (FUNCPTR)qFifoGNullRtn,
    (FUNCPTR)qFifoGPut,
    (FUNCPTR)qFifoGGet,
    (FUNCPTR)qFifoGRemove,
    (FUNCPTR)qFifoGNullRtn,
    (FUNCPTR)qFifoGNullRtn,
    (FUNCPTR)qFifoGNullRtn,
    (FUNCPTR)qFifoGNullRtn,
    (FUNCPTR)qFifoGNullRtn,
    (FUNCPTR)qFifoGInfo,
    (FUNCPTR)qFifoGEach,
    &qFifoGClass
    };

/* globals */

Q_CLASS_ID qFifoGClassId = &qFifoGClass;


/******************************************************************************
*
* qFifoGInit - initialize global FIFO queue 
*
* This routine initializes the specified global FIFO queue.
*
* RETURNS: OK, or ERROR if FIFO queue could not be initialized.
*
* NOMANUAL
*/

STATUS qFifoGInit 
    (
    Q_FIFO_G_HEAD * pQFifoGHead		/* global FIFO queue to initialize */
    )
    {
    smDllInit (pQFifoGHead->pFifoQ);	/* initialize the real queue */

    return (OK);
    }

/*******************************************************************************
*
* qFifoGPut - add a node to a global FIFO queue
*
* This routine adds the specifed node to the global FIFO queue.  
* The insertion is either at the tail or head based on the specified key 
* FIFO_KEY_TAIL or FIFO_KEY_HEAD respectively.
*
* This routine is only use through Q_PUT in windPendQPut to add a shared 
* task control block into a semaphore pend Queue. Thus what we always 
* have to do when this function is called is to insert the shared tcb 
* of the task that calls us in the semaphore queue specified by <pQFifoGHead>.
*
* RETURNS: N/A
*
* NOMANUAL
*/

void qFifoGPut 
    (
    Q_FIFO_G_HEAD * pQFifoGHead,	/* Q to where to put node */	
    SM_DL_NODE *    pQFifoGNode,	/* not used */
    ULONG           key 
    )
    {
    /* do the shared TCB queueing */

    if (key == FIFO_KEY_HEAD)
	smDllInsert (pQFifoGHead->pFifoQ, (SM_DL_NODE *)NULL, 
		     (SM_DL_NODE *)taskIdCurrent->pSmObjTcb);
    else
	smDllAdd (pQFifoGHead->pFifoQ, (SM_DL_NODE *)taskIdCurrent->pSmObjTcb);
    }

/*******************************************************************************
*
* qFifoGGet - get the first node out of a global FIFO queue
*
* This routines dequeues and returns the first node of a global FIFO queue.  
* If the queue is empty, NULL will be returned.
*
* RETURNS: pointer the first node, or NULL if queue is empty.
*
* NOMANUAL
*/

SM_DL_NODE * qFifoGGet 
    (
    Q_FIFO_G_HEAD * pQFifoGHead 	/* Q to get node from */
    )
    {
    SM_DL_NODE * node;

    if (SM_DL_EMPTY (pQFifoGHead->pFifoQ))
	return (NULL);

    node =  smDllGet (pQFifoGHead->pFifoQ);

    return ((SM_DL_NODE *) ntohl ((int) (((SM_OBJ_TCB *) (node))->localTcb)));
    }

/*******************************************************************************
*
* qFifoGRemove - remove the specified node from a global FIFO queue
*
* This routine removes the specified node from a global FIFO queue.
*
* RETURNS: OK, ALREADY_REMOVED if node was removed by a timeout, a task
*          deletion or a siganl, or ERROR if lock cannot be taken.
*
* ERRNO:  S_smObjLib_LOCK_TIMEOUT
*
* NOMANUAL
*/

STATUS qFifoGRemove 
    (
    Q_FIFO_G_HEAD * pQFifoGHead,	/* Q head to remove from */
    SM_DL_NODE *    pQFifoGNode 	/* pointer to node to remove */
    )
    {
    BOOL         status;	/* return status */
    int          level;		/* inlock return value */

    if (pQFifoGHead->pLock != NULL)
	{
        /* 
         * qFifoGRemove can be called by windPendQRemove to remove a task from
         * a semaphore pend queue when a task is deleted or when a delay 
	 * expires. It can also be called by windRestart when a signal is
	 * sent to the task. In all cases this function is called with 
	 * pQFifoGHead->pLock not NULL indicating that lock access must 
	 * be obtained before manipulating the queue and a pointer to 
	 * the task control block is passed as node to remove, but 
	 * actually what we need to remove from the pendQ is the shared tcb 
	 * not the tcb itself.
         */

	if (SM_OBJ_LOCK_TAKE(pQFifoGHead->pLock, &level) == ERROR)
	    return (ERROR); 			/* ENTER LOCKED SECTION */

	/* 
	 * What can happen here is that because the notification time
	 * is not null, the shared TCB may have been removed by a semGive
	 * on another CPU but this removal has not shown up on the take
	 * side.
	 */
	  
        if (! ntohl (((WIND_TCB *) (pQFifoGNode))->pSmObjTcb->removedByGive)) 
	    {
	    /*
	     * This is the normal case, a task deletion, a timeout or 
	     * a signal when the shared TCB has not been already removed 
	     * by semGive on an other CPU, so we remove it.
	     */

	     /*
	      * If this shared TCB has been previously removed from a shared 
	      * semaphore pendQ, removedByGive has been reset to FALSE
	      * by smObjEventProcess. 
	      */

	    smDllRemove (pQFifoGHead->pFifoQ, 
		     (SM_DL_NODE *) (((WIND_TCB *) (pQFifoGNode))->pSmObjTcb));

	    status = OK;
	    }
        else
	    {
	    /*
	     * This is the bad case, the removedByGive field of the shared 
	     * TCB has been set to TRUE. In that case we set the local TCB 
	     * pointer in the shared TCB to NULL indicating that the task 
	     * has been deleted, got a timeout or has received a signal. 
	     * This will be use by smObjEventProcess when the shared TCB 
	     * will show up.
	     * We also set the pointer to the shared TCB stored in the local
	     * TCB to NULL to oblige the task to re-allocate a shared TCB if
	     * it is not deleted and goes back to a semTake on the same or
	     * on another shared semaphore.
	     * Then we return a special status to the upper layers of 
	     * the kernel.
	     */

	     /* 
	      * This cannot be done outside the LOCKED SECTION because
	      * we want to be sure that the notification interrupt
	      * does not occur between the test on removedByGive and here.
	      */

	     /*
	      * Note that we don't need to reset removedByGive to FALSE
	      * because this shared TCB will be dropped by smObjEventProcess.
	      */

	    ((WIND_TCB *) (pQFifoGNode))->pSmObjTcb->localTcb = NULL;
	    ((WIND_TCB *) (pQFifoGNode))->pSmObjTcb = NULL;

	    status = ALREADY_REMOVED;
	    }

        SM_OBJ_LOCK_GIVE (pQFifoGHead->pLock, level); /* EXIT LOCKED SECTION */
	}

    else
	{
	/* 
	 * We are called by semGive with lock already obtained, 
	 * simply remove the node from the queue. Actually,
	 * pQFifoGNode is a pointer to a shared TCB and pQFifoGHead->pFifoQ
	 * is a shared semaphore pendQ.
	 */

    	smDllRemove (pQFifoGHead->pFifoQ, pQFifoGNode);

	/* tell everybody that we are no more on the semaphore pend Q */ 
	((SM_OBJ_TCB *) (pQFifoGNode))->removedByGive = htonl (TRUE);
				
	status = OK;
	}

    return (status);
    }
/*******************************************************************************
*
* qFifoGInfo - get information of a FIFO queue
*
* This routine returns information of a FIFO queue.  If the parameter nodeArray
* is NULL, the number of queued nodes is returned.  Otherwise, the specified
* nodeArray is filled with a node pointers of the FIFO queue starting from the
* head.  Node pointers are copied until the TAIL of the queue is reached or
* until maxNodes has been entered in the nodeArray.
*
* RETURNS: Number of nodes entered in nodeArray, or nodes in FIFO queue.
*
* NOMANUAL
*/

int qFifoGInfo 
    (
    Q_FIFO_G_HEAD * pQFifoGHead,/* FIFO queue to gather list for */
    int             nodeArray[],/* array of node pointers to be filled in */
    int             maxNodes    /* max node pointers nodeArray can accomodate */
    )
    {
    SM_DL_NODE * pNode = (SM_DL_NODE *) SM_DL_FIRST (pQFifoGHead->pFifoQ);
    int *        pElement  = nodeArray;

    if (nodeArray == NULL)		/* NULL node array means return count */
	return (smDllCount (pQFifoGHead->pFifoQ));

    while ((pNode != LOC_NULL) && (--maxNodes >= 0))
	{
	*(pElement++) = (int) pNode;	                /* fill in table */
	pNode = (SM_DL_NODE *) SM_DL_NEXT (pNode);	/* next node */
	}

    return (pElement - nodeArray);	/* return count of active tasks */
    }

/*******************************************************************************
*
* qFifoGEach - call a routine for each node in a queue
*
* This routine calls a user-supplied routine once for each node in the
* queue.  The routine should be declared as follows:
* .CS
*  BOOL routine (pQNode, arg)
*      SM_DL_NODE *pQNode;	/@ pointer to a queue node          @/
*      int	   arg;		/@ arbitrary user-supplied argument @/
* .CE
* The user-supplied routine should return TRUE if qFifoGEach() is to continue
* calling it for each entry, or FALSE if it is done and qFifoGEach() can exit.
*
* RETURNS: NULL if traversed whole queue, or pointer to SM_DL_NODE that
*          qFifoGEach stopped on.
*
* NOMANUAL
*/

SM_DL_NODE * qFifoGEach 
    (
    Q_FIFO_G_HEAD * pQHead,     /* queue head of queue to call routine for */
    FUNCPTR         routine,    /* the routine to call for each table entry */
    int             routineArg  /* arbitrary user-supplied argument */
    )
    {
    SM_DL_NODE * pQNode = (SM_DL_NODE *) SM_DL_FIRST (pQHead->pFifoQ);

    while ((pQNode != NULL) && ((* routine) (pQNode, routineArg)))
	pQNode = (SM_DL_NODE *) SM_DL_NEXT (pQNode);

    return (pQNode);			/* return node we ended with */
    }

/*******************************************************************************
*
* qFifoGNullRtn - null routine for global queue class structure
*
* This routine does nothing and returns OK.
*
* RETURNS: OK
*
* NOMANUAL
*/

LOCAL STATUS qFifoGNullRtn (void)
    {
    return (OK);
    }