\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{allocMem}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{allocMem}},
{\tt \manName{freeMem}},
{\tt \manName{getMemByAddr}},
{\tt \manName{getMemByName}},
{\tt \manName{readMem}},
{\tt \manName{writeMem}},
{\tt \manName{accessMem}},
{\tt \manName{getMemName}}
{\tt \manName{lockMem}}
{\tt \manName{unlockMem}}
-- allocate and access pieces of shared memory for RCI programs.

}
\manSection{USAGE}
\cverbatim
#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; @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt name} --}
Name of the memory object.
\manItem{{\tt size} --}
Desired size of the memory object, in bytes.
\manItem{{\tt pool} --}
Host memory pool from which memory object is allocated.
\manItem{{\tt mem} --}
Pointer to the memory object.
\manItem{{\tt p} --}
Pointer to the memory object as seen by the planning task.
\manItem{{\tt src} --}
Buffer to copy memory object from.
\manItem{{\tt dest} --}
Buffer to copy memory object to.
\manItem{{\tt size} --}
Size of copy operation, in bytes.
\manSection{RESTRICTIONS}
{\tt allocMem()} and {\tt freeMem()} must be called from the planning level.

{\tt lockMem()} and {\tt unlockMem()} cannot presently be called from the
planning level, although this should change.
\manSection{DESCRIPTION}
The RCI {\it 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.

{\tt allocMem()} creates a memory object with the given {\TT name} consisting
of {\TT size} bytes, zeros it, and returns a pointer to it. 
The argument {\tt 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 {\tt pool} is specified as {\tt UNDEF},
then the system will select a memory pool automatically.
It is possible to specifiy a {\tt NULL} name, by setting
{\tt name} to be either {\tt NULL}, or a pointer to a {\tt NULL} string. This
can be useful for hidden allocation. Retrieval of such pieces of memory
can be done using the {\tt getMemByAddr()} primitive (see below).

{\tt freeMem()} frees the allocated memory.

{\tt 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). 

{\tt getMemByAddr()} locates a memory object, using the value of the pointer
returned to the planning task (i.e., returned by {\tt 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
{\tt getMemByName()}.

{\tt 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 {\tt readMem()},
{\tt writeMem()}, {\tt accessMem()}, or {\tt lockMem()} which reference
the same piece of memory.
The buffer is assumed to be at least as big as the memory object.

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

\manInset{
{\bf 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.}

{\tt accessMem()} is the most general copying routine, moving
{\tt size} bytes from {\tt src} into {\tt 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 {\tt 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. 

{\tt getMemName()} the name of a memory object, given
its address.

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

{\tt unlockMem()} unlocks a memory object.

\manInset{
\bf NOTE: At the time of this writing, {\tt lockMem()} and {\tt unlockMem()}
will not work 
if called from the planning level.}

\manSection{DIAGNOSTICS}
{\tt allocMem()} returns {\tt 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
{\tt allocMem()} will return {\tt NULL} and will place the
error code {\tt EDuplicate}, and an error message, on the 
{\it errorStack} (q.v.).

{\tt getMemByName()} and {\tt getMemByAddr()} return {\tt NULL}
if they cannot find the memory object.

{\tt allocMem()} and {\tt freeMem()}
routine will abort the program if called from the control level.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt rciGlobalMemory(3)}.

\manEnd
\end
