rciSharedMemory(3)

NAME
rciSharedMemory, rciGlobalMemory, rciLocalMemory, rciSharedData
 -- RCI routines for setting up shared memory.

USAGE
#include <rci.h>

void *rciSharedMemory (label, size, hostTd)
   const char *label;
   int size;
   RCI_DESC *hostTd;

void *rciGlobalMemory (label, size, unused, pool)
   const char *label;
   int size;
   unsigned long unused;
   int pool;

void *rciLocalMemory (label, size, hostTd)
   const char *label;
   int size;
   RCI_DESC *hostTd;

rciSharedData (addr, size, hostTd, accessMask)
   void *addr;
   int size;
   RCI_DESC *hostTd;
   unsigned long accessMask;

ARGUMENTS

label --
    Name of the memory section; can be given as NULL.

size --
    Size of the shared memory area, in bytes.

hostTd --
    Descriptor pointer for the task which will host the shared memory; (i.e., the shared memory will be allocated from a pool that is quickly accessible to that task).

pool --
    Integer specifying where the memory should be allocated from. In the present system, all shared memory sections are allocated from one of the system's CPUs, hence pool should be a CPU number.

addr --
    Address of an existing area of memory to be mapped.

unused --
    Argument is not currently used.

accessMask --
    Bitmask describingn the tasks on which CPUs the memory will be mapped to. The bitmask for any given task may be obtained from its task descriptor using TASKMASK(td).

RESTRICTIONS
These routines must be called from the planning level.

DESCRIPTION
rciSharedMemory() allocates a shared memory section of size bytes, zeros it, and returns a pointer to it. (size is rounded up to the nearest page boundary.) The section is private to the planning task and the indicated control task. If label is not NULL, the control task can later obtain a pointer to the section by calling getSharedMemory() with the label name. Alternatively, a pointer to the section can be obtained by calling findSharedMemory() with the value returned by rciSharedMemory() as a key.

rciGlobalMemory() allocates a shared memory section of size bytes from the indicated pool (which is nominally a CPU number), zeros it, and returns a pointer to it. (Again, size is rounded up to the nearest page boundary.) The section is accessible to all tasks. If label is not NULL, tasks can later obtain a pointer to the section by calling getGlobalMemory() with the label name. Alternatively, a pointer to the section can be obtained by calling findGlobalMemory() with the value returned by rciGlobalMemory() as a key.

rciLocalMemory() allocates a memory section of size bytes of data private to the task specified by td, and returns a pointer to it whose value is valid for the control task. If label is not NULL, the task can later obtain a pointer to the section by calling getLocalMemory() with the label name.

NOTE: Unlike the other routines, rciLocalMemory() does not (at the time of this writing) zero its allocated memory.

rciSharedData() sets up a shared section from within the compile-time data region. This can be used to create shared compiled variables. The memory section described by addr and size must be part of the program data segment, and specifically that part of the data segment which has been marked for access by the control level (see rcc(1)). Both addr and size must be page-aligned. Mapping will be set up among all tasks which are indicated by the accessMask.

IMPORTANT: Because the sharing of the data segment is done on a per CPU basis, all tasks which are resident on the CPUs covered by accessMask will be mapped, whether they are explicitly described by accessMask or not.

Shared memory sections cannot presently be deleted individually. They are removed en masse, along with all the control tasks, by the function rciClose().

DIAGNOSTICS

In the event of error, rciSharedMemory(), rciGlobalMemory(), and rciLocalMemory() return NULL, while rciSharedData() returns -1. Error information is reported on the errorStack(q.v.).

Returned error codes, accessible with getErrorCode(), are:

EDescriptor --
    Invalid task descriptor.

ENoPageAlign --
    Argument to rciSharedData() is not page aligned.

ERange --
    Section specified to rciSharedData() does not lie in the control data area, or overlaps an existing section.

EMemory --

    Out of memory.

EInternal --
    Unexpected internal failure.

These routines will abort the program if called from the control level.

CAVEATS
Remember that rciSharedData() will set up a shared region among all tasks resident on the CPUs which host the tasks specified by accessMask.

There is no way to delete a shared memory area once it has been created, except through rciClose().

SEE ALSO
getSharedMemory(3), rciCreate(3), rciStart(3), errorStack(3).