\input manualMacros.tex
\manBegin
%\manIndexOpen
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{rciCreate}{3}
\manSection{NAME}
{\tt \manName{rciCreate}}, 
{\tt \manName{rciClose}}
-- create and delete RCI tasks.
\manSection{USAGE}
\cverbatim
#include <rci.h>

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

rciClose();
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt name} --}
The name associated with the task. The number of characters is truncated to 
{\tt TASK_NAME_SIZE}.
\manItem{{\tt cpuSelect} --}
A bitmask describing which CPUs the task is allowed to run on. Bit 0
indicates the {\it arbiter} CPU, while the succeeding bits indicate {\it
auxiliary} CPUs 1, 2, \dots, etc.
From among the specified CPUs, RCI will give first priority to allocating
an auxiliary CPU, and second priority to using the arbiter.
\manSection{RESTRICTIONS}
These routines must be called from the planning level.
\manSection{DESCRIPTION}
{\tt rciCreate()} sets up an RCI task, and, if successful, returns
a pointer to its {\it task descriptor}.
A CPU is selected for the task
and that CPU is
initialized and loaded, if necessary. A task control block 
(see {\tt RCI_TCB(3)}) is allocated and attached to the descriptor.

Upon the first call to {\tt 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.

{\tt 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.
\manSection{DIAGNOSTICS}
{\tt rciCreate()} returns {\tt NULL} in the event of failure, while
{\tt rciClose()} returns {\tt -1}. Error information is reported on the
{\it errorStack} (q.v.). Returned error codes are accessible with 
{\tt getErrorCode()}.
\medskip

The following error codes describe common errors:

\manItem{{\tt EEnviron} --}
Environment variable RCCL not defined.
\manItem{{\tt EDuplicate} --}
Task name is already in use.
\manItem{{\tt EMemory} --}
Out of memory, shared memory space, or locked memory space.
\manItem{{\tt EAuxHalted} --}
One of the auxiliary CPUs is in a halted state; probably in console mode.
\manItem{{\tt ENotAvail} --}
None of the requested CPUs, or no RCI devices, are available.
\medskip

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

\manItem{{\tt EBadAccess} --}
A system support file (config file, lock file, or boot files) or
device ({\tt ka} device or generic RCI device)
is inaccessible.
\manItem{{\tt EBadObj} --}
A system support
support device is not properly configured.
\manItem{{\tt EBadFxn} --}
A system support function (or function package), which is obtained from
a configuration table, is either missing or has a bogus address.
\manItem{{\tt EInternal} --}
Unexpected internal failure. 

These routines will abort the program if called from the control level.
\manSection{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 {\tt rciDelete()} which removes a task.
\manSection{SEE ALSO}
\raggedright
\tolerance = 400
{\tt rciStart(3)}, {\tt rciControlFxns(3)},
{\tt rciAllocDevice(3)}, {\tt rciScheduling(3)}, {\tt rciInterruptDev(3)},
{\tt rciRate(3)}, {\tt rciAttachRobot(3)},
{\tt errorStack(3)}.
\manEnd
\end
