rciCreate(3)

%

NAME
rciCreate, rciClose -- create and delete RCI tasks.

USAGE
#include <rci.h>

RCI_DESC *rciCreate(name, cpuSelect)
   const char *name;
   unsigned long cpuSelect;

rciClose();

ARGUMENTS

name --
    The name associated with the task. The number of characters is truncated to TASK_NAME_SIZE.

cpuSelect --
    A bitmask describing which CPUs the task is allowed to run on. Bit 0 indicates the arbiter CPU, while the succeeding bits indicate auxiliary CPUs 1, 2, ... , etc. From among the specified CPUs, RCI will give first priority to allocating an auxiliary CPU, and second priority to using the arbiter.

RESTRICTIONS
These routines must be called from the planning level.

DESCRIPTION
rciCreate() sets up an RCI task, and, if successful, returns a pointer to its task descriptor. A CPU is selected for the task and that CPU is initialized and loaded, if necessary. A task control block (see RCI_TCB(3)) is allocated and attached to the descriptor.

Upon the first call to rciCreate(), the associated task's CPU is designated as clock server for the system. If this happens to be the arbiter CPU, then the clock will be relocated to an auxiliary CPU as soon as a task is created on one, since this will provide the most reliable clock service.

rciClose() removes all tasks and associated shared memory areas. Once this has been done, it is then possible to "start over again", creating new RCI tasks and setting up new shared memory areas.

DIAGNOSTICS
rciCreate() returns NULL in the event of failure, while rciClose() returns -1. Error information is reported on the errorStack (q.v.). Returned error codes are accessible with getErrorCode().

The following error codes describe common errors:

EEnviron --
    Environment variable RCCL not defined.

EDuplicate --
    Task name is already in use.

EMemory --
    Out of memory, shared memory space, or locked memory space.

EAuxHalted --
    One of the auxiliary CPUs is in a halted state; probably in console mode.

ENotAvail --
    None of the requested CPUs, or no RCI devices, are available.

    The following error codes indicate a problem with the RCI system installation:

EBadAccess --
    A system support file (config file, lock file, or boot files) or device (ka device or generic RCI device) is inaccessible.

EBadObj --
    A system support support device is not properly configured.

EBadFxn --
    A system support function (or function package), which is obtained from a configuration table, is either missing or has a bogus address.

EInternal --
    Unexpected internal failure.

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

NOTES
It should be possible to delete a single task, although this involved more software complexity than was deemed necessary at the moment. At the user level this would involve introducing a function rciDelete() which removes a task.

SEE ALSO
rciStart(3), rciControlFxns(3), rciAllocDevice(3), rciScheduling(3), rciInterruptDev(3), rciRate(3), rciAttachRobot(3), errorStack(3).