📄 smobjlib.html
字号:
<html><head><!-- /vobs/wpwr/docs/vxworks/ref/smObjLib.html - generated by refgen from smObjLib.c --> <title> smObjLib </title></head><body bgcolor="#FFFFFF"> <hr><a name="top"></a><p align=right><a href="libIndex.htm"><i>VxWorks API Reference : OS Libraries</i></a></p></blockquote><h1>smObjLib</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>smObjLib</strong> - shared memory objects library (VxMP Option) </p></blockquote><h4>ROUTINES</h4><blockquote><p><p><b><a href="./smObjLib.html#smObjLibInit">smObjLibInit</a>( )</b> - install the shared memory objects facility (VxMP Option)<br><b><a href="./smObjLib.html#smObjSetup">smObjSetup</a>( )</b> - initialize the shared memory objects facility (VxMP Option)<br><b><a href="./smObjLib.html#smObjInit">smObjInit</a>( )</b> - initialize a shared memory objects descriptor (VxMP Option)<br><b><a href="./smObjLib.html#smObjAttach">smObjAttach</a>( )</b> - attach the calling CPU to the shared memory objects facility (VxMP Option)<br><b><a href="./smObjLib.html#smObjLocalToGlobal">smObjLocalToGlobal</a>( )</b> - convert a local address to a global address (VxMP Option)<br><b><a href="./smObjLib.html#smObjGlobalToLocal">smObjGlobalToLocal</a>( )</b> - convert a global address to a local address (VxMP Option)<br><b><a href="./smObjLib.html#smObjTimeoutLogEnable">smObjTimeoutLogEnable</a>( )</b> - control logging of failed attempts to take a spin-lock (VxMP Option)<br><p></blockquote><h4>DESCRIPTION</h4><blockquote><p>This library contains miscellaneous functions used by the shared memoryobjects facility (VxMP). Shared memory objects provide high-speedsynchronization and communication among tasks running on separate CPUs thathave access to a common shared memory. Shared memory objects are systemobjects (e.g., semaphores and message queues) that can be used acrossprocessors.<p>The main uses of shared memory objects are interprocessor synchronization,mutual exclusion on multiprocessor shared data structures, and high-speeddata exchange.<p>Routines for displaying shared memory objects statistics are provided by the <b><a href="./smObjShow.html#top">smObjShow</a></b> module.<p></blockquote><h4>SHARED MEMORY MASTER CPU</h4><blockquote><p>One CPU node acts as the shared memory objects master. This CPUinitializes the shared memory area and sets up the shared memory anchor.These steps are performed by the master calling <b><a href="./smObjLib.html#smObjSetup">smObjSetup</a>( )</b>. Thisroutine should be called only once by the master CPU. Usually <b><a href="./smObjLib.html#smObjSetup">smObjSetup</a>( )</b>is called from <b>usrSmObjInit( )</b>. (See "Configuration" below.)<p>Once <b><a href="./smObjLib.html#smObjSetup">smObjSetup</a>( )</b> has completed successfully, there is little functionaldifference between the master CPU and other CPUs using shared memory objects,except that the master is responsible for maintaining the heartbeat inthe shared memory objects header.<p></blockquote><h4>ATTACHING TO SHARED MEMORY</h4><blockquote><p>Each CPU, master or non-master, that will use shared memory objectsmust attach itself to the shared memory objects facility, whichmust already be initialized.<p>Before it can attach to a shared memory region, each CPU must allocateand initialize a shared memory descriptor (<b>SM_DESC</b>), which describes theindividual CPU's attachment to the shared memory objects facility. Sincethe shared memory descriptor is used only by the local CPU, it is notnecessary for the descriptor itself to be located in shared memory. Infact, it is preferable for the descriptor to be allocated from the CPU'slocal memory, since local memory is usually more efficiently accessed.<p>The shared memory descriptor is initialized by calling <b><a href="./smObjLib.html#smObjInit">smObjInit</a>( )</b>. Thisroutine takes a number of parameters which specify the characteristics ofthe calling CPU and its access to shared memory.<p>Once the shared memory descriptor has been initialized, the CPU canattach itself to the shared memory region. This is done by calling<b><a href="./smObjLib.html#smObjAttach">smObjAttach</a>( )</b>.<p>When <b><a href="./smObjLib.html#smObjAttach">smObjAttach</a>( )</b> is called, it verifies that the shared memory anchorcontains the value <b>SM_READY</b> and that the heartbeat located in the sharedmemory objects header is incrementing. If either of these conditions isnot met, the routine will check periodically until either <b>SM_READY</b> or anincrementing heartbeat is recognized or a time limit is reached. Thelimit is expressed in seconds, and 600 seconds (10 minutes) is thedefault. If the time limit is reached before <b>SM_READY</b> or a heartbeat isfound, ERROR is returned and <b>errno</b> is set to <b>S_smLib_DOWN</b> .<p></blockquote><h4>ADDRESS CONVERSION</h4><blockquote><p>This library also provides routines for converting between local andglobal shared memory addresses, <b><a href="./smObjLib.html#smObjLocalToGlobal">smObjLocalToGlobal</a>( )</b> and<b><a href="./smObjLib.html#smObjGlobalToLocal">smObjGlobalToLocal</a>( )</b>. A local shared memory address is the addressrequired by the local CPU to reach a location in shared memory. A globalshared memory address is a value common to all CPUs in the system used toreference a shared memory location. A global shared memory address isalways an offset from the shared memory anchor.<p></blockquote><h4>SPIN-LOCK MECHANISM</h4><blockquote><p>The shared memory objects facilities use a spin-lock mechanism based on anindivisible read-modify-write (RMW) operation on a shared memory locationwhich acts as a low-level mutual exclusion device. The spin-lock mechanismis called with a system-wide configuration parameter,<b>SM_OBJ_MAX_TRIES</b>, which specifies the maximum number of RMW tries on aspin-lock location.<p>Care must be taken that the number of RMW tries on a spin-lock on aparticular CPU never reaches <b>SM_OBJ_MAX_TRIES</b>, otherwise systembehavior becomes unpredictable. The default value should be sufficientfor reliable operation.<p>The routine <b><a href="./smObjLib.html#smObjTimeoutLogEnable">smObjTimeoutLogEnable</a>( )</b> can be used to enable or disable theprinting of a message should a shared memory object call fail while tryingto take a spin-lock.<p></blockquote><h4>RELATION TO BACKPLANE DRIVER</h4><blockquote><p>Shared memory objects and the shared memory network (backplane) driver use common underlying shared memory utilities. They also use the same anchor, the same shared memory header, and the same interrupt when they are used atthe same time.<p></blockquote><h4>LIMITATIONS</h4><blockquote><p>A maximum of twenty CPUs can be used concurrently with shared memoryobjects. Each CPU in the system must have a hardware test-and-set (TAS)mechanism, which is called via the system-dependent routine <b><a href="./sysLib.html#sysBusTas">sysBusTas</a>( )</b>.<p>The use of shared memory objects raises interrupt latency, because internalmechanisms lock interrupts while manipulating critical shared datastructures. Interrupt latency does not depend on the number of objects orCPUs used.<p></blockquote><h4>GETTING STATUS INFORMATION</h4><blockquote><p>The routine <b><a href="./smObjShow.html#smObjShow">smObjShow</a>( )</b> displays useful information regarding the currentstatus of shared memory objects, including the number of tasks usingshared objects, shared semaphores, and shared message queues, the numberof names in the database, and also the maximum number of tries to getspin-lock access for the calling CPU.<p></blockquote><h4>CONFIGURATION</h4><blockquote><p>When the component <b>INCLUDE_SM_OBJ</b> is included, the init and setuproutines in this library are called automatically during VxWorksinitialization.<p></blockquote><h4>AVAILABILITY</h4><blockquote><p>This module is distributed as a component of the unbundled shared memoryobjects support option, VxMP.<p></blockquote><h4>INCLUDE FILES</h4><blockquote><p><b>smObjLib.h</b><p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./smObjShow.html#top">smObjShow</a></b>, <b><a href="./semSmLib.html#top">semSmLib</a></b>, <b><a href="./msgQSmLib.html#top">msgQSmLib</a></b>, <b><a href="./smMemLib.html#top">smMemLib</a></b>, <b><a href="./smNameLib.html#top">smNameLib</a></b>, <b>usrSmObjInit( )</b>,<i>VxWorks Programmer's Guide: Shared Memory Objects</i><hr><a name="smObjLibInit"></a><p align=right><a href="rtnIndex.htm"><i>OS Libraries : Routines</i></a></p></blockquote><h1>smObjLibInit( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>smObjLibInit( )</strong> - install the shared memory objects facility (VxMP Option)</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS smObjLibInit (void)</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine installs the shared memory objects facility. It is calledautomatically when the component <b>INCLUDE_SM_OBJ</b> is included.<p></blockquote><h4>AVAILABILITY</h4><blockquote><p>This routine is distributed as a component of the unbundled shared memoryobjects support option, VxMP.<p></blockquote><h4>RETURNS</h4><blockquote><p>OK, or ERROR if the shared memory objects facility has already beeninstalled.</blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./smObjLib.html#top">smObjLib</a></b><hr><a name="smObjSetup"></a><p align=right><a href="rtnIndex.htm"><i>OS Libraries : Routines</i></a></p></blockquote><h1>smObjSetup( )</h1> <blockquote></a></blockquote><h4>NAME</h4><blockquote> <p><strong>smObjSetup( )</strong> - initialize the shared memory objects facility (VxMP Option)</p></blockquote><h4>SYNOPSIS</h4><blockquote><p><pre>STATUS smObjSetup ( SM_OBJ_PARAMS * smObjParams /* setup parameters */ )</pre></blockquote><h4>DESCRIPTION</h4><blockquote><p>This routine initializes the shared memory objects facility by filling theshared memory header. It must be called only once by the shared memorymaster CPU. It is called automatically only by the master CPU, when thecomponent <b>INCLUDE_SM_OBJ</b> is included.<p>Any CPU on the system backplane can use the shared memory objects facility;however, the facility must first be initialized on the master CPU. Thenbefore other CPUs are attached to the shared memory area by <b><a href="./smObjLib.html#smObjAttach">smObjAttach</a>( )</b>, each must initialize its own shared memory objects descriptor using<b><a href="./smObjLib.html#smObjInit">smObjInit</a>( )</b>. This mechanism is similar to the one used by the shared memorynetwork driver.<p>The <i>smObjParams</i> parameter is a pointer to a structure containing thevalues used to describe the shared memory objects setup. This structure is defined as follows in <b>smObjLib.h</b>:<pre>typedef struct sm_obj_params /* setup parameters */ { BOOL allocatedPool; /* TRUE if shared memory pool is malloced */ SM_ANCHOR * pAnchor; /* shared memory anchor */ char * smObjFreeAdrs; /* start address of shared memory pool */ int smObjMemSize; /* memory size reserved for shared memory */ int maxCpus; /* max number of CPUs in the system */ int maxTasks; /* max number of tasks using smObj */ int maxSems; /* max number of shared semaphores */ int maxMsgQueues; /* max number of shared message queues */ int maxMemParts; /* max number of shared memory partitions */ int maxNames; /* max number of names of shared objects */ } SM_OBJ_PARAMS;</pre></blockquote><h4>AVAILABILITY</h4><blockquote><p>This routine is distributed as a component of the unbundled shared memoryobjects support option, VxMP.<p></blockquote><h4>RETURNS</h4><blockquote><p>OK, or ERROR if the shared memory pool cannot hold all the requestedobjects or the number of CPUs exceeds the maximum.<p></blockquote><h4>ERRNO</h4><blockquote><p><p> <b>S_smObjLib_TOO_MANY_CPU</b> <br> <b>S_smObjLib_SHARED_MEM_TOO_SMALL</b><p></blockquote><h4>SEE ALSO</h4><blockquote><p><b><a href="./smObjLib.html#top">smObjLib</a></b>, <b><a href="./smObjLib.html#smObjInit">smObjInit</a>( )</b>, <b><a href="./smObjLib.html#smObjAttach">smObjAttach</a>( )</b><hr><a name="smObjInit"></a><p align=right>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -