\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{robots}{5}
\manSection{NAME}
{\tt \manName{robots}}
-- RCI robot information file.
\manSection{DESCRIPTION}
The {\it robots} file, which lives in {\filefont \$RCCL/conf}, describes the 
I/O interface device and polling interrupt used by each robot configured into
an RCI system. This file is referenced when a robot is
attached to an RCI task with the {\tt rciAttachRobot()} call.

The entry for each robot in the file has the form
\cverbatim
  robot=<name> device=<dev> address=<addr> [interrupt=<polldev>]
               [arg<n>=<argvalue>]
@endcverbatim
White space is ignored except as a word delimiter. The character {\tt \#}
introduces a comment until the end of the line.

The keywords associated with each entry are:

\manItem{{\tt robot} --}
Is followed by the name of the robot being described. 

\manItem{{\tt device} --} 
Is followed by the name of the RCI I/O device which the robot interface functions
should use when communicating with the robot. This device name must correspond
to the name of an RCI device driver which exists
in the table {\tt IOdrivers} (located in the
file {\filefont drivers/IOdriverTable.c}).

\manItem{{\tt address} --}
Is followed by an integer giving the address of the specified I/O device.
Normally, this is an address on an I/O space bus. The integer may be specified
in either decimal, hex, or octal, using the normal C syntax for those bases.
The exact interpretation of the address is up to the device's probe routine.

\manItem{{\tt arg<n>} --}
Optional arguments to the device driver. Device drivers can be passed
up to {\tt MAX_DEVARGS} integer arguments when they are allocated. The
need for, and purpose of, these arguments is driver-specific. One typical use
is to provide additional addressing information. For instance, a
shared memory driver may need a csr address in addition to separate address
for the shared memory. The allowed argument keywords are {\tt arg0},
{\tt arg1}, etc., up to {\tt arg}N, 
where $\hbox{N} = \hbox{\tt MAX_DEVARGS}-1$.
Unspecified arguments are given the value {\tt UNDEF}.

\manItem{{\tt interrupt} --}
This entry is only necessary if the robot's control task is being
run on the arbiter CPU. In this case, it gives the special file
of an RCI UNIX device which can provide a polling interrupt
for the {\tt ON_FUNCTION} and {\tt ON_TRIGGER} scheduling disciplines.

{\tolerance=10000
\manItem{}
When an RCI task is run on the arbiter CPU, and either {\tt ON_FUNCTION} or
{\tt ON_TRIGGER} scheduling is specified, then it is necesary to specify
a polling interrupt that can be used to ``wake up'' the RCI
monitor to check to see if the task is runnable. The polling interrupt device
specified in the {\tt robots} file is opened by the {\tt rciAttachRobot()}
routine for the robot in question, and a file descriptor is placed in the
{\tt RCI_RBT} structure for that robot. This descriptor can then be
used, at the programmer's discretion, as a third argument to {\tt
rciScheduling()}.

}

\manSection{SEE ALSO}
\raggedright
{\tt rciAttachRobot(3)}, {\tt IOdevice(7)}, {\tt rciScheduling(3)}.

\manEnd
\end
