\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{rciAllocCpus}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{rciAllocCpus}}
-- allocate CPUs for RCI system.
}
\manSection{USAGE}
\cverbatim
unsigned long rciAllocCpus (cpuMask)
  unsigned long cpuMask; @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt cpuMask} --}
Mask describing the CPUs which should be allocated.
\manSection{RESTRICTIONS}
This routine must be called from the planning level.
\manSection{DESCRIPTION}
This routine 
allows an RCI program to allocate system CPUs for later use by
the program (i.e., for use in subsequent calls to
{\tt rciCreate()}). The routine returns a
bitmask describing which CPUs were actually allocated. 

This routine has a few uses. It gives the programmer the ability to test for
the 
availability of system CPUs without actually creating tasks on them. In
addition, it may be useful to allocate an auxiliary CPU to make sure that one
is available to serve as the system clock; the system clock is set up during
the first call to {\tt rciCreate()}, and the CPU chosen to act as clock server
is selected from among the CPUs allocated at that time.
\manSection{DIAGNOSTICS}
The routine returns {\tt -1} in the event of an error. Error information is reported on the
{\it errorStack} (q.v.). Returned error codes are accessible with 
{\tt getErrorCode()}.
\medskip
Possible error codes include:

\manItem{{\tt EInternal} --}
Unexpected internal software failure.
\manItem{{\tt EBadAccess} --}
Unexpected error trying to open CPU device driver.

The routine will abort the program if called from the control level.
\manSection{SEE ALSO}
\raggedright
{\tt rciCreate()}, {\tt rciStart()}.
\manEnd
\end
