smlib.c

VxWorks操作系统内核源代码

/* 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 upgrade
02q,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 25804
02n,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 shuffle
02c,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.
*/

/*
DESCRIPTION

This library contains the shared memory routines which are common
to 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 CPU

One CPU node acts as the shared memory master.  This CPU initializes
the shared memory header and sets up the shared memory anchor.  These
steps 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 separate
shared memory regions.)

Once smSetup() has completed successfully, there is little functional
difference between the master CPU and other CPU's using shared memory,
except that the master is responsible for maintaining the shared memory
packet and shared memory object heartbeats in
the shared memory header regions.


SHARED MEMORY ANCHOR

The shared memory anchor is a small data structure which is at
a predetermined location, to allow all CPU's using shared memory to
find it.  The shared memory anchor contains the base offset to the
actual 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 the
shared 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 MEMORY

Each CPU, master or non-master, which will use the shared memory region
must attach itself to the shared memory.  The shared memory region must
have already been initialized by the master CPU calling smSetup().

The first step in attaching to shared memory is for each CPU to allocate and
initialize a shared memory descriptor (SM_DESC).  This structure describes
the individual CPU's attachment to the shared memory region and is used
in all subsequent shared memory calls to identify which shared memory
region is being used.  Since the shared memory descriptor is used only
by the local CPU, it is not necessary for the descriptor itself to be
located in shared memory.  In fact, it is preferable for the descriptor
to be allocated from the CPU's local memory, since local memory is usually
more efficient to access.

The shared memory descriptor is initialized by calling the smInit()
routine.  This routine takes a number of parameters which specify the
characteristics of this CPU and its access to shared memory.

After the shared memory descriptor has been initialized, the CPU may
attach itself to the shared memory region.  This is done by calling the
smAttach() routine. 


DETACHING FROM SHARED MEMORY

The attachment of a CPU to shared memory may be ended by calling
smDetach().  This routine will mark the calling CPU as no longer
attached.  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().)


INTERRUPTS

There 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, vme
bus interrupts, and user defined interrupts.  Mailbox interrupts are the
first 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 BSP
writer to specify a routine to be used
to generate an interrupt in another CPU.  The three interrupt arguments
are passed to the
user's routine.  When using this method, the user is responsible for calling
the smUtilIntRoutine(), when an incoming signal (interrupt) is detected.
The routine smUtilIntRoutine() will process any data packets in the list
for the local cpu.  The global variable <smUtilUser1Rtn> is a pointer to the
user routine for SM_INT_USER_1 .  The variable <smUtilUser2Rtn> is the pointer
for 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 was
successfully notified, or ERROR if it was not.

If it is not possible to use interrupts to notify receiving CPU's, a
polling method may be used.  


INTERNAL

This 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       /
			____________v
common shared memory	| smLib	    |
library			_____________
			     |
			     v
shared 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 common
to 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
\ie

SHARED MEMORY LOCK

The routines smLockTake() and smLockGive() are used to achieve the necessary
inter-processor locks.  The routine that is called to perform a Test and
Set (TAS) primitive is one of the calling arguments.  The delay algorithm
between TAS attempts is an exponential one.  The delay between retries is
twice as great as the previous delay, until the delay reaches a maximum
value and is then reset to its starting value.  The following variables
can be tuned to give best performance for any specific CPU and clock
combination.

\cs
   int smLockTakeDelayMin = 256;
   int smLockTakeDelayMax = 1*1024*1024;
\ce

The minimum number of retries (>= 1) to be attempted is specified as an
argument to smLockTake().  (One retry is always made if the first attempt
fails, even if the minimum number of retries is specified as zero.)

INTERNAL
There needs to be better documentation discussing the interfaces
and 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
    (