/* 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 code01j,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.h01d,02oct92,pme  added SPARC support. documentation cleanup.01c,29sep92,pme  changed semSm[BC]Create to sem[BC]SmCreate		 comments cleanup01b,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.*//*DESCRIPTIONThis library provides the interface to VxWorks shared memory binary andcounting semaphores.  Once a shared memory semaphore is created, thegeneric semaphore-handling routines provided in semLib are used tomanipulate it.  Shared memory binary semaphores are created usingsemBSmCreate().  Shared memory counting semaphores are created usingsemCSmCreate().Shared memory binary semaphores are used to:  (1) control mutuallyexclusive access to multiprocessor-shared data structures, or (2)synchronize multiple tasks running in a multiprocessor system.  Forgeneral information about binary semaphores, see the manual entrysemBLib.Shared memory counting semaphores are used for guarding multiple instancesof a resource used by multiple CPUs.  For general information about sharedcounting semaphores, see the manual entry for semCLib.For information about the generic semaphore-handling routines, see themanual entry for semLib.MEMORY REQUIREMENTSThe semaphore structure is allocated from a dedicated shared memory partition.The shared semaphore dedicated shared memory partition is initialized bythe shared memory objects master CPU.  The size of this partition isdefined by the maximum number of shared semaphores, set in the configurationparameter 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 countingsemaphores to be used in the system.RESTRICTIONSShared 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 associatedshared memory.  Attempts to delete a shared semaphore return ERROR andset `errno' to S_smObjLib_NO_OBJECT_DESTROY .\i `Queuing Style:'The shared semaphore queuing style specified when the semaphore is created must be FIFO.\ieINTERRUPT LATENCYInternally, interrupts are locked while manipulating shared semaphore data structures, thus increasing local CPU interrupt latency.CONFIGURATIONBefore routines in this library can be called, the shared memory objectfacility must be initialized by calling usrSmObjInit().  This is doneautomatically during VxWorks initialization when the component INCLUDE_SM_OBJis included.AVAILABILITYThis module is distributed as a component of the unbundled shared memorysupport option, VxMP.INTERNALTo 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 sharedmemory 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 taskblocks on a shared semaphore or after each restart signal or timeoutoccuring while taking a shared semaphore.In order to use the standard wind kernel routines we use a pseudo multi-wayqueue to manipulate the shared queues and nodes (actually shared TCBs). We have defined a new class of queue called qFifoG for which the queue headcontains :       - 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 FlushThe issue here is to keep a per CPU semaphore flush indivisibility whilekeeping a reasonable interrupt latency.  Note that a system wide flushindivisibility is impossible to achieve.This implies that only one notification is made to any CPU where there'sone or more tasks pending on the flushed semaphore.Since no modifications are made to the semaphore status, semaphore flushis the same for binary and counting semaphores and is called semSmFlush().- Optional Facility:Since this facility is optional, 'flush', 'give' and 'take' routines arecalled via function pointers in semFlush(), semGive(), and semTake(),respectively, to avoid this code being imported into VxWorks when the VxMPoption is not available.Functions pointers are initialized by semSmLibInit() which is calledin 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.hSEE 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