allocMem(3)

NAME
allocMem, freeMem, getMemByAddr, getMemByName, readMem, writeMem, accessMem, getMemName lockMem unlockMem -- allocate and access pieces of shared memory for RCI programs.

USAGE
#include <rci.h>

void *allocMem (name, size, pool)
   const char *name;
   int size, pool;

freeMem (mem)
   void *mem;

void *getMemByName (name)
   const char *name;

void *getMemByAddr (p)
   void *p;

readMem (mem, dest)
   void *mem;
   void *dest;

writeMem (mem, src)
   void *mem;
   void *src;

accessMem (mem, src, dest, size)
   void *mem, src, dest;
   int size;

char *getMemName (mem)
   void *mem;

lockMem (mem)
   void *mem;

unlockMem (mem)
   void *mem;

ARGUMENTS

name --
    Name of the memory object.

size --
    Desired size of the memory object, in bytes.

pool --
    Host memory pool from which memory object is allocated.

mem --
    Pointer to the memory object.

p --
    Pointer to the memory object as seen by the planning task.

src --
    Buffer to copy memory object from.

dest --
    Buffer to copy memory object to.

size --
    Size of copy operation, in bytes.

RESTRICTIONS
allocMem() and freeMem() must be called from the planning level.

lockMem() and unlockMem() cannot presently be called from the planning level, although this should change.

DESCRIPTION
The RCI memory object package is meant to provide the RCI environment with something akin to a shared variable mechanism. "Memory objects" are pieces of memory which are allocated and freed by the planning task, and can be accessed by any RCI task once it has obtained a pointer to it.

allocMem() creates a memory object with the given "name" consisting of "size" bytes, zeros it, and returns a pointer to it. The argument pool optionally identifies the memory pool from which it will be allocated; under the current implementation, this is simply a CPU number; i.e., a value of n will cause the object to be allocated from CPU n's memory. If pool is specified as UNDEF, then the system will select a memory pool automatically. It is possible to specifiy a NULL name, by setting name to be either NULL, or a pointer to a NULL string. This can be useful for hidden allocation. Retrieval of such pieces of memory can be done using the getMemByAddr() primitive (see below).

freeMem() frees the allocated memory.

getMemByName() locates a memory object, using its name as a key, and returns a pointer to it. This operation is necessary because, in general, the value of a pointer to a given piece of memory will differ from CPU to CPU (since different virtual addresses can point to the same physical address).

getMemByAddr() locates a memory object, using the value of the pointer returned to the planning task (i.e., returned by allocMem()) as a key. This is useful if one does not wish to name an object and risk name collisions. The routine is also faster than getMemByName().

readMem() copies the contents of the indicated memory object into a buffer. The read is atomic in that it will lock out other calls to readMem(), writeMem(), accessMem(), or lockMem() which reference the same piece of memory. The buffer is assumed to be at least as big as the memory object.

writeMem() copies a buffer into the a memory object. The write is atomic in the same sense as readMem(). The buffer is assumed to be at least as big as the memory object.

 NOTE: only the memory object itself, i.e., the leftmost argument, is accessed atomically by the read and write primitives. If the righthand argument is also an memory object, it will not be accessed atomically.

accessMem() is the most general copying routine, moving size bytes from src into dest. It is intended for cases where we do not wish to copy an entire memory object, but only part of it. The access is atomic in the same sense as readMem(). For that matter, it is not strictly necessary that either the source or destination address belongs to the memory object; the memory object can be used to simply provide a mutual exclusion flag for the operation.

getMemName() the name of a memory object, given its address.

lockMem() locks access to a memory object. After this is called, any attempt by another task to perform a readMem(), writeMem(), accessMem(), or lockMem() will block until the memory is unlocked with unlockMem().

unlockMem() unlocks a memory object.

 NOTE: At the time of this writing, lockMem() and unlockMem() will not work if called from the planning level.

DIAGNOSTICS
allocMem() returns NULL if the memory object cannot be allocated from the selected pool. If the requested memory object has a name, and this name is already in use, then allocMem() will return NULL and will place the error code EDuplicate, and an error message, on the errorStack (q.v.).

getMemByName() and getMemByAddr() return NULL if they cannot find the memory object.

allocMem() and freeMem() routine will abort the program if called from the control level.

SEE ALSO
rciGlobalMemory(3).