/* smLib.c - VxWorks common shared memory library *//* Copyright 1984-2002 Wind River Systems, Inc. *//*modification history--------------------02s,03may02,mas  cache flush and volatile fix (SPR 68334); bridge flush fix		 (SPR 68844)02r,14nov01,mas  added smLibInit() for future common code base upgrade02q,24oct01,mas  doc update (SPR 71149)02p,20sep01,jws  eliminate min 5000 tries in smLockTake() (SPR68418)02o,17mar99,dat  added docs about SM_INT_USER_1/2, SPR 2580402n,21feb99,jdi  doc: listed errnos.02m,18mar98,dat  added exponential backoff with limits, (more SPR 9312)02l,05dec97,dat  rework SPR 9312, add global variable smLockTakeDelayCnt.02k,29sep97,dat  SPR 9312, fixed smLockTake retry loop.02j,14jul93,wmd  Removed ntohl for anchorLocalAddr in smSetup() (SPR #2282).02i,10feb93,pme  Changed smLockTake retry time calculation.02h,29sep92,pme  Suppressed warning message in smLockTake.		 Added write pipe flush calls where needed.02g,02aug92,kdl  Uncommented include of "copyright_wrs.h".02f,24jul92,elh  Moved heartbeat from anchor to header.02e,13jul92,elh  Added tasClear functionality. Added pme's changes to		 smLockTake.02d,02jun92,elh  the tree shuffle02c,27may92,elh	 Further split up the library.  Changed to use offsets,		 Made completely independent.  General cleanup.02b,20may92,pme+ Removed pkt specific data structures (and routines	    elh	 that use them to their corrosponding files.02a,14may92,pme  Splitted to keep only routines common to backplane driver		 and shared memory objects.01e,20feb92,elh  Added in ntohl, and htonl for 960, Added USE_OFFSET.		 Extracted and renamed OS specific calls & moved to		 smUtilLib.  Also removed function pointers		 shMemIntGenFunc and shMemHwTasFunc.		 made TAS_CHECKS 10 TAS_TRIES 5000.		 modified parameters passed to intGen function.01d,10feb92,kdl+ Changed shMemDetach to flush input queue.	    elh  Removed references to OK_WAS{EMPTY, NT_EMPTY}.		 Made shMemSend return an ERROR if packet too large.		 Changed shMemSend to return silently (no		 interrupts generated) if sending to self.		 Misc code review changes.01c,05feb92,elh  ansified.01b,27jan92,elh	 added masterCpu to shared memory anchor.		 changed shMemBeat to take pAnchor as argument.		 changed arguments to shMemIsAlive.		 changed shMemSetup to probe memory.		 changed copyright.01a,15aug90,kdl	 written.*//*DESCRIPTIONThis library contains the shared memory routines which are commonto the shared memory libraries: smPktLib and smObjLib.  It provides basic shared memory functionality such as shared memory attachment, detachment and lock synchronization.SHARED MEMORY MASTER CPUOne CPU node acts as the shared memory master.  This CPU initializesthe shared memory header and sets up the shared memory anchor.  Thesesteps are performed by the master calling the smSetup() routine.This routine should be called only by the shared memory master CPU,and it should only be called once for a given shared memory region.(It is, however, possible to maintain and use multiple separateshared memory regions.)Once smSetup() has completed successfully, there is little functionaldifference between the master CPU and other CPU's using shared memory,except that the master is responsible for maintaining the shared memorypacket and shared memory object heartbeats inthe shared memory header regions.SHARED MEMORY ANCHORThe shared memory anchor is a small data structure which is ata predetermined location, to allow all CPU's using shared memory tofind it.  The shared memory anchor contains the base offset to theactual shared memory header.  (This allows the master CPU to dynamically allocate the shared memory region.)  Another field in the anchor contains a "ready value" which is set to a specific value when the master CPU has completed initializing the shared memory region.The shared memory anchor does not have to be defined as part of theshared memory region.  However, it must be located in a similar address space; the address translation constants which CPU boards use to convert local addresses to bus addresses must apply equally to the anchor and the regular shared memory region.ATTACHING TO SHARED MEMORYEach CPU, master or non-master, which will use the shared memory regionmust attach itself to the shared memory.  The shared memory region musthave already been initialized by the master CPU calling smSetup().The first step in attaching to shared memory is for each CPU to allocate andinitialize a shared memory descriptor (SM_DESC).  This structure describesthe individual CPU's attachment to the shared memory region and is usedin all subsequent shared memory calls to identify which shared memoryregion is being used.  Since the shared memory descriptor is used onlyby the local CPU, it is not necessary for the descriptor itself to belocated in shared memory.  In fact, it is preferable for the descriptorto be allocated from the CPU's local memory, since local memory is usuallymore efficient to access.The shared memory descriptor is initialized by calling the smInit()routine.  This routine takes a number of parameters which specify thecharacteristics of this CPU and its access to shared memory.After the shared memory descriptor has been initialized, the CPU mayattach itself to the shared memory region.  This is done by calling thesmAttach() routine. DETACHING FROM SHARED MEMORYThe attachment of a CPU to shared memory may be ended by callingsmDetach().  This routine will mark the calling CPU as no longerattached.  The CPU may re-attach itself to the shared memory region by later calling smAttach().  (When re-attaching, the original shared memory descriptor may be re-used if the CPU's configuration remains the same, or new values may be specified via smInit().)INTERRUPTSThere must be some method for a CPU to be notified of an occuring event.The preferred method is for the CPU initiating the event to interrupt the affected CPU.  This will be highly dependent on the specific hardware being used.  If interrupts cannot be used, a polling scheme may be employed, but this is much less efficient.Three types of interrupts are supported, mailbox interrupts, vmebus interrupts, and user defined interrupts.  Mailbox interrupts are thefirst preferred method (SM_INT_MAILBOX), followed by bus (backplane) interrupts(SM_INT_BUS).  If interrupts cannot be used, a polling scheme may be employed (SM_INT_NONE), but this is much less efficient. The user interrupt types (SM_INT_USER_1 and SM_INT_USER_2) allow the BSPwriter to specify a routine to be usedto generate an interrupt in another CPU.  The three interrupt argumentsare passed to theuser's routine.  When using this method, the user is responsible for callingthe smUtilIntRoutine(), when an incoming signal (interrupt) is detected.The routine smUtilIntRoutine() will process any data packets in the listfor the local cpu.  The global variable <smUtilUser1Rtn> is a pointer to theuser routine for SM_INT_USER_1 .  The variable <smUtilUser2Rtn> is the pointerfor the SM_INT_USER_2 routine.When a CPU initailizes its shared memory descriptor via the smInit() call, it passes in an interrupt type as well as three interrupt arguments.  This describes how the cpu wishes to be notified of events.  The interrupt types recognized by this library are listed in smLib.h. These values may be obtained for any attached CPU by calling smCpuInfoGet().  The default interrupt method for a particular target is defined by the configuration parameters: SM_INT_TYPE, SM_INT_ARG1, SM_INT_ARG2, and SM_INT_ARG3 .When a CPU wishs to notify a destination CPU of an event, the sending CPU will call smUtilIntGen(), to interrupt the destination CPU.smUtilIntGen() should return OK if the destination CPU wassuccessfully notified, or ERROR if it was not.If it is not possible to use interrupts to notify receiving CPU's, apolling method may be used.  INTERNALThis file runs under only vxWorks.  SunOS is no longer supported.The shared memory libaries are split into mulitple files.Below is the internal layout of the shared memory libraries:		              		    ___________shared memory object         		    | smObjLib|library		             	    	   / __________ 		              		  /	shared memory		____________     /packet library		| smPktLib |    / 			____________   /			     |	      /						     v       /			____________vcommon shared memory	| smLib	    |library			_____________			     |			     vshared memory           _____________   support routines	| smUtilLib |			_____________\is\i `smObjLib'Contains the share memory object routines.\i `smPktLib'Contains the shared memory packet routines.  It provides packet passing functionality to send and retreive data packets over the backplane using shared memory.  It is used by the backplane driver.\i `smLib'Contains routines the shared memory routines that are commonto backplane driver and the shared memory objects:  		\i `smUtilLib'Contains the OS specific routines needed by the shared memory libraries.  This module should be provided for each OS for which shared memory is ported and must contain at a minimum the following routines:\cs	smUtilMemProbe	- probe memory to see if it exists 	smUtilSofTas	- software test-and-set routine 	smUtilTas	- hardware test-and-set routine	smUtilTasClear	- clear hardware test-and-set routine	smUtilProcNumGet- get processor number	smUtilDelay	- delay for specified number of time 	smUtilRateGet	- get number of ticks per second 	intLock		- lock out interrupts	intUnlock	- unlock interrupts	smUtilIntGen	- interrupt generation routine	smUtilIntConnect- connect one or more routine to shared memory 		          interrupt.	smUtilIntRoutine- shared memory interrupt routine	smUtilPollTask  - shared memory polling task\ce\ieSHARED MEMORY LOCKThe routines smLockTake() and smLockGive() are used to achieve the necessaryinter-processor locks.  The routine that is called to perform a Test andSet (TAS) primitive is one of the calling arguments.  The delay algorithmbetween TAS attempts is an exponential one.  The delay between retries istwice as great as the previous delay, until the delay reaches a maximumvalue and is then reset to its starting value.  The following variablescan be tuned to give best performance for any specific CPU and clockcombination.\cs   int smLockTakeDelayMin = 256;   int smLockTakeDelayMax = 1*1024*1024;\ceThe minimum number of retries (>= 1) to be attempted is specified as anargument to smLockTake().  (One retry is always made if the first attemptfails, even if the minimum number of retries is specified as zero.)INTERNALThere needs to be better documentation discussing the interfacesand functionality of the OS specific library, smUtilLib.SEE ALSO: \tb VxWorks Programmer's Guide: Shared-Memory Objects,  \tb VxWorks Network Programmer's Guide: Data Link Layer Network Components.*//* Includes */#include "vxWorks.h"#include "cacheLib.h"#include "smLib.h"#include "smUtilLib.h"/* Defines */#define	SM_VERSION		1	/* protocol version for sh mem anchor *//* Globals */int		smAliveTimeout   = DEFAULT_ALIVE_TIMEOUT;/* current maximum # of tries to get lock used for statistics */int 		smCurMaxTries = 0;int		smLockTakeDelayMin = 256;int		smLockTakeDelayMax = 1*1024*1024;/* Locals */LOCAL BOOL	smLibInitialized = FALSE;LOCAL int	smRegionsMax 	 = SM_REGIONS_MAX;LOCAL SM_REGION smRegions [SM_REGIONS_MAX];/* Forward declarations */LOCAL int smRegionGet (SM_ANCHOR * anchorLocalAdrs);LOCAL int smRegionFind (SM_ANCHOR * anchorLocalAdrs);/******************************************************************************** smLibInit - initialize the shared memory library and shared memory region** This routine is normally called only by the system startup code during* kernel initialization.  It prepares the library and locates the shared* memory region via either static lookup or dynamic allocation.  A static* lookup is first attempted if <pRgnCfgTbl> is not NULL.  If the shared* memory region is not found or <pRgnCfgTbl> is NULL, an uncached shared* memory region of size <objSize> + <netSize> is allocated from the kernel* heap.** INTERNAL* This routine is a place holder until a common code base version of smLib is* created.  The input arguments are identical with those used in AE.** RETURNS: N/A** NOMANUAL*/void smLibInit    (    void * pRgnCfgTbl,		/* address of memory configuration table */    UINT   objSize,		/* shared object region size */    UINT   netSize		/* shared memory network region size */    )    {    /* NOT YET IMPLEMENTED */    if (pRgnCfgTbl == NULL)        ;    if (objSize == netSize)        ;    }/******************************************************************************** smSetup - set up shared memory (master CPU only)** This routine should be called only by the master CPU using shared* memory.  It initializes the specified memory area for use by the* shared memory protocol.  This includes initializing the shared memory* anchor and the shared memory header.** After the shared memory has been initialized, this and other CPU's* may initialize a shared memory descriptor to it, using smInit(),* and then attach to the shared memory area, using smAttach().** The <anchorLocalAdrs> parameter is the memory address by which the master* CPU accesses the actual shared memory anchor region to be initialized.** The <smLocalAdrs> parameter is the memory address by which the master* CPU accesses the actual shared memory region to be initialized.** The shared memory routines must be able to obtain exclusive access to* shared data structures.  To allow this, a test-and-set operation is* used.  It is preferable to use a genuine test-and-set instruction, if* the hardware being used permits this.  If this is not possible, smLib* provides a software emulation of test-and-set.  The <tasType> parameter* specifies what method of test-and-set is to be used.** The <maxCpus> parameter specifies the maximum number of CPU's which may* use the shared memory region.** The amount of shared memory taken as a result of the call, gets returned* in <pMemUsed>** INTERNAL* The first item in the shared memory area is the shared memory header (SM_HDR).* Following this is an array of CPU descriptors (SM_CPU_DESC); this table* contains one CPU descriptor for each possible CPU, as specified by <maxCpus>.** RETURNS: OK, or ERROR.** ERRNO: S_smLib_MEMORY_ERROR*/STATUS smSetup    (