semsmlib.c

VXWORKS源代码

/* semSmLib.c - shared memory semaphore library (VxMP Option) */

/* Copyright 1984-2002 Wind River Systems, Inc. */

/*
modification history
--------------------
01n,06may02,mas  cache flush and volatile fix (SPR 68334); bridge flush fix
		 (SPR 68844)
01m,24oct01,mas  doc update (SPR 71149)
01l,14mar99,jdi  doc: removed refs to config.h and/or configAll.h (SPR 25663).
01k,22feb99,wsl  doc: fixed typo in errno code
01j,22mar94,pme  added WindView level event logging.
01i,24feb93,jdi  doc tweaks.
01h,08feb93,jdi  documentation cleanup.
01g,29jan93,pme  added little endian support.
01f,23nov92,jdi  documentation cleanup.
01e,13nov92,dnw  added include of smObjLib.h
01d,02oct92,pme  added SPARC support. documentation cleanup.
01c,29sep92,pme  changed semSm[BC]Create to sem[BC]SmCreate
		 comments cleanup
01b,30jul92,pme  changed semSm[BC]Init to call qFifoGInit.
		 added signal restarting.
		 semSm{Create,Init} call semSmLibInit for robustness.
		 documentation cleanup.
01a,19jul92,pme  added semSmLibInit() to reduce coupling.
                 reduced interrupt latency in semSmGive and semSmTake.
                 merged shared counting and binary semaphores.
                 code review clean up.
                 written.
*/

/*
DESCRIPTION
This library provides the interface to VxWorks shared memory binary and
counting semaphores.  Once a shared memory semaphore is created, the
generic semaphore-handling routines provided in semLib are used to
manipulate it.  Shared memory binary semaphores are created using
semBSmCreate().  Shared memory counting semaphores are created using
semCSmCreate().

Shared memory binary semaphores are used to:  (1) control mutually
exclusive access to multiprocessor-shared data structures, or (2)
synchronize multiple tasks running in a multiprocessor system.  For
general information about binary semaphores, see the manual entry
semBLib.

Shared memory counting semaphores are used for guarding multiple instances
of a resource used by multiple CPUs.  For general information about shared
counting semaphores, see the manual entry for semCLib.

For information about the generic semaphore-handling routines, see the
manual entry for semLib.

MEMORY REQUIREMENTS
The semaphore structure is allocated from a dedicated shared memory partition.

The shared semaphore dedicated shared memory partition is initialized by
the shared memory objects master CPU.  The size of this partition is
defined by the maximum number of shared semaphores, set in the configuration
parameter SM_OBJ_MAX_SEM .

This memory partition is common to shared binary and counting semaphores,
thus SM_OBJ_MAX_SEM must be set to the sum total of binary and counting
semaphores to be used in the system.

RESTRICTIONS
Shared memory semaphores differ from local semaphores in the following ways:

\is
\i `Interrupt Use:'
Shared semaphores may not be given, taken, or flushed at interrupt level.

\i `Deletion:'
There is no way to delete a shared semaphore and free its associated
shared memory.  Attempts to delete a shared semaphore return ERROR and
set `errno' to S_smObjLib_NO_OBJECT_DESTROY .

\i `Queuing Style:'
The shared semaphore queuing style specified when the semaphore is created 
must be FIFO.
\ie

INTERRUPT LATENCY
Internally, interrupts are locked while manipulating shared semaphore 
data structures, thus increasing local CPU interrupt latency.

CONFIGURATION
Before routines in this library can be called, the shared memory object
facility must be initialized by calling usrSmObjInit().  This is done
automatically during VxWorks initialization when the component INCLUDE_SM_OBJ
is included.

AVAILABILITY
This module is distributed as a component of the unbundled shared memory
support option, VxMP.

INTERNAL
To achieve full transparency, semBSmCreate() and semCSmCreate() returns 
a semaphore of type SEM_ID but the effective structure pointed to by 
this ID is a SM_SEMAPHORE.

When a task blocks on a shared semaphore a data structure called shared
memory object task control block (smObjTcb) is added to the shared 
semaphore pend queue.  This smObjTcb is allocated from a dedicated 
fixed block size shared memory partition the first time the task
blocks on a shared semaphore or after each restart signal or timeout
occuring while taking a shared semaphore.

In order to use the standard wind kernel routines we use a pseudo multi-way
queue to manipulate the shared queues and nodes (actually shared TCBs). 
We have defined a new class of queue called qFifoG for which the queue head
contains :

       - a pointer to qFifoGClass.
       - a pointer to the Fifo pending queue associated with the
         shared object where task is pending on.
       - a pointer to the shared memory object pend queue lock.  This
         pointer is initialized to NULL if we already have the lock.
         This pointer is necessary because when a timeout expires,
         when a signal is sent to the task, or when a task is deleted 
	 Q_REMOVE is called to remove the shared TCB from the semaphore 
	 pending list without having previously acquired semaphore 
	 lock access.  Thus only qFifoGRemove(), which is called by Q_REMOVE ,
         need to check if this pointer is NULL before manipulating the queue.

- Shared Semaphore Flush

The issue here is to keep a per CPU semaphore flush indivisibility while
keeping a reasonable interrupt latency.  Note that a system wide flush
indivisibility is impossible to achieve.
This implies that only one notification is made to any CPU where there's
one or more tasks pending on the flushed semaphore.

Since no modifications are made to the semaphore status, semaphore flush
is the same for binary and counting semaphores and is called semSmFlush().

- Optional Facility:

Since this facility is optional, 'flush', 'give' and 'take' routines are
called via function pointers in semFlush(), semGive(), and semTake(),
respectively, to avoid this code being imported into VxWorks when the VxMP
option is not available.
Functions pointers are initialized by semSmLibInit() which is called
in smObjInit().

routine structure:

 semBSmCreate       semCSmCreate
 |     |            |      |
(o) semSmBInit     (o) semSmCInit
         |                 |
         \                 /
          ------   --------
                \ /
             qFifoGInit
                 |
             smDllInit     



         semGive           semFlush                 semTake
            |                 |        Interrupt       | 
        semSmGive         semSmFlush   /            semSmTake
        /  |  |           /  | |      /              | |   \
       /   *  |   --------   * |     /               | *    \
      /       |  /             |    /                |       \
      |\ smObjEventSend  smObjEventProcess       smObjTcbInit/|
      | \    /   \             |       |   \         |      / |
      |  \  *     -----  windReadyQPut |    *       (i)    /  |
      |   -----------  \               |                  /   |
 windReadyQPut       \  -------------- |    windReadyQRemove  |
                      |               \|                      |
                 qFifoGRemove          |                  qFifoGPut
                      |      \         |                      |
                  smDllRemove *    smDllConcat             smDllPut



        *                      *               (o)           (i)
	|                      |                |             |
   SM_OBJ_LOCK_TAKE    SM_OBJ_LOCK_GIVE   smMemPartAlloc smFixBlkPartAlloc	

INCLUDE FILES: semSmLib.h

SEE ALSO: semLib, semBLib, semCLib, smObjLib, semShow, usrSmObjInit(),
\tb VxWorks Programmer's Guide: Shared Memory Objects, 
\tb VxWorks Programmer's Guide: Basic OS
*/

/* LINTLIBRARY */

#include "vxWorks.h"
#include "errnoLib.h"
#include "objLib.h"
#include "classLib.h"
#include "qFifoGLib.h"
#include "semLib.h"
#include "stdlib.h"
#include "stdio.h"
#include "string.h"
#include "taskLib.h"
#include "cacheLib.h"
#include "intLib.h"
#include "smObjLib.h"
#include "netinet/in.h"
#include "private/semSmLibP.h"
#include "private/windLibP.h"
#include "private/smObjLibP.h"
#include "private/smMemLibP.h"
#include "private/sigLibP.h"
#include "private/eventP.h"

/* locals */

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

/*****************************************************************************
*
* semSmLibInit - initialize the shared semaphore management package
*
* This routine initializes the shared memory semaphore library by installing
* the addresses of its give, take, and flush routines for both binary and
* counting semaphores in the kernel's semaphore function dispatch table.
*
* SEE ALSO: smObjLibInit().
*
* RETURNS: N/A
*
* NOMANUAL
*/

void semSmLibInit (void)
    {
    if ((!semSmLibInstalled) & (semLibInit () == OK))
	{
    	/* fill the semaphore function tables */

    	semGiveTbl  [SEM_TYPE_SM_BINARY]	= (FUNCPTR) semSmGive;
    	semTakeTbl  [SEM_TYPE_SM_BINARY]	= (FUNCPTR) semSmTake;
    	semFlushTbl [SEM_TYPE_SM_BINARY]	= (FUNCPTR) semSmFlush;
    	semGiveTbl  [SEM_TYPE_SM_COUNTING]	= (FUNCPTR) semSmGive;
    	semTakeTbl  [SEM_TYPE_SM_COUNTING]	= (FUNCPTR) semSmTake;
    	semFlushTbl [SEM_TYPE_SM_COUNTING]	= (FUNCPTR) semSmFlush;

	semSmLibInstalled = TRUE;
	}
    }

/*****************************************************************************
*
* semBSmCreate - create and initialize a shared memory binary semaphore (VxMP Option)
*
* This routine allocates and initializes a shared memory binary semaphore.
* The semaphore is initialized to an <initialState> of either
* SEM_FULL (available) or SEM_EMPTY (not available).  The shared semaphore
* structure is allocated from the shared semaphore dedicated memory
* partition.
*
* The semaphore ID returned by this routine can be used directly by the
* generic semaphore-handling routines in semLib -- semGive(), semTake(), and
* semFlush() -- and the show routines, such as show() and semShow().
*
* The queuing style for blocked tasks is set by <options>; the only
* supported queuing style for shared memory semaphores is first-in-first-out,
* selected by SEM_Q_FIFO .
*
* Before this routine can be called, the shared memory objects facility must
* be initialized (see semSmLib).
*
* The maximum number of shared memory semaphores (binary plus counting) that
* can be created is SM_OBJ_MAX_SEM , a configurable parameter.
*
* AVAILABILITY
* This routine is distributed as a component of the unbundled shared memory
* support option, VxMP.
* 
* RETURNS: The semaphore ID, or NULL if memory cannot be allocated 
* from the shared semaphore dedicated memory partition.
* 
* ERRNO: S_memLib_NOT_ENOUGH_MEMORY, S_semLib_INVALID_QUEUE_TYPE,
* S_semLib_INVALID_STATE, S_smObjLib_LOCK_TIMEOUT
*
* SEE ALSO: semLib, semBLib, smObjLib, semShow,
* \tb VxWorks Programmer's Guide: Basic OS
*
* INTERNAL
* The least significant bit of the semaphore id is set to 1 in order to
* differentiate shared and local semaphores.
*/

SEM_ID semBSmCreate
    (
    int		options,	/* semaphore options */
    SEM_B_STATE	initialState	/* initial semaphore state */
    )
    {
    SM_SEM_ID   smSemId;
    int         temp;           /* temp storage */

    /* 
     * Allocate semaphore structure from shared semaphores
     * dedicated shared memory partition. 
     */
  
    smSemId = (SM_SEM_ID) smMemPartAlloc ((SM_PART_ID) smSemPartId,
                                          sizeof (SM_SEMAPHORE));

    if (smSemId == NULL)
        {
	return (NULL);
        }

    /* clear shared semaphore structure */

    bzero ((char *) smSemId, sizeof (SM_SEMAPHORE));

    /* initialize allocated semaphore */

    if (semSmBInit ((SM_SEMAPHORE *) (smSemId), options, initialState) != OK)
    	{
    	smMemPartFree ((SM_PART_ID) smSemPartId, (char *) smSemId);
    	return (NULL);
    	}

    /* update shared memory objects statistics */

    CACHE_PIPE_FLUSH ();                        /* CACHE FLUSH   [SPR 68334] */
    temp = pSmObjHdr->curNumSemB;               /* PCI bridge bug [SPR 68844]*/

    pSmObjHdr->curNumSemB = htonl (ntohl (pSmObjHdr->curNumSemB) + 1);

    CACHE_PIPE_FLUSH ();                        /* CACHE FLUSH   [SPR 68334] */
    temp = pSmObjHdr->curNumSemB;               /* BRIDGE FLUSH  [SPR 68334] */

    return ((SEM_ID) (SM_OBJ_ADRS_TO_ID (smSemId)));
    }

/*****************************************************************************
*
* semSmBInit - initialize a declared shared binary semaphore
*
* The initialization of a static shared binary semaphore, or a shared binary
* semaphore embedded in some larger shared object need not deal with
* allocation.  This routine may be called to initialize such a semaphore.  The
* semaphore is initialized to the specified initial state of either SEM_FULL
* or SEM_EMPTY .
*
* Binary semaphore options include the queuing style for blocked tasks.
* For now, the only available shared semaphore queueing style is
* first-in-first-out, type SEM_Q_FIFO defined as 0 in semLib.h.
*
* The semaphore address parameter is the local address of a shared semaphore
* structure. 
*
* RETURNS: OK, or ERROR if queue type or initial state is invalid.
* 
* SEE ALSO: semBSmCreate
*
* ERRNO: S_semLib_INVALID_QUEUE_TYPE, S_semLib_INVALID_STATE