\input manualMacros.tex
\manBegin
\manPageInfo{RCI Reference Manual}{}{}
\manTitle{rciAllocDevice}{3}
\manSection{NAME}
{\tt \manName{rciDeallocDevice}},
{\tt \manName{rciAllocDevice}}
-- attaches an RCI task to an I/O driver.
\manSection{USAGE}
\cverbatim
#include <rci.h>

rciAllocDevice (td, devaddr, mode)
   RCI_DESC *td;
   struct devAddr *devaddr;
   int mode;

rciDeallocDevice (td)
   RCI_DESC *td; @endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt td} --}
Pointer to task descriptor.
\manItem{{\tt devaddr} --}
Address specification for the device, containing a device name, an
address number (usually a bus address), an optional string giving additional
address information, and optional arguments
for the driver.
\manItem{{mode} --}
{\tolerance=10000
Access mode for the device. The access modes are defined in 
{\tt h/IOdevice.h}. There are two mode flags: 
{\tt DEV_INTERNAL} allows the device to be attached multiple times within the
same program. {\tt DEV_EXTERNAL} allows the device to be accessed multiple
times from different programs. {\tt DEV_ALL} is the combination of {\tt
DEV_EXTERNAL} and {\tt DEV_INTERNAL}, and {\tt DEV_NONE} defines both
flags set to 0.

}
\manSection{RESTRICTIONS}
These routines must be called from the planning level.
\manSection{DESCRIPTION}
{\tt rciAllocDevice()} attaches a control task to an RCI I/O device. 
This routine must be called when the task is not active.
If the routine is called and the task has a device already allocated,
the first device is deallocated automatically.

{\tt rciDeallocDevice()} detaches the device from the RCI task.
It returns {\tt 1} if a device was actually present and was detached, 
and {\tt 0} if no device was present.

Each RCI I/O device is defined by an {\it address} and a {\it driver name}.
These are specified using the structure {\tt devAddr}:
\cverbatim
      struct devAddr {
         char *name;            /* device type (driver name) */
         int address;           /* physical address */
         char *addrStr;         /* supplemental address info */
         int args[MAX_DEVARGS]; /* special arguments */
      } @endcverbatim
The driver
is a collection of I/O routines grouped together with a name given by
the {\tt name} field. 
The {\tt address} field is an identifying address (usually a bus address). 
The {\tt addrStr} field is used to provide additional addressing information;
at present this is supported for tasks running on the arbiter CPU
only (specifically, the {\tt addrStr} field is used by the simulator device
{\tt sim}).
The {\tt args}
field defines optional parameters that may by used by the driver routines
(for instance, additional addressing information for the {\tt probe()}
routine).

Usually, the I/O routines transfer data directly to and from
the physical device using the memory mapping I/O buses
provided by RCI, and there is no interaction 
with the host operating system (such as UNIX).
An exception to this is the simulator driver {\tt sim}, which
makes use of networking services.

RCI I/O drivers can be written for different types of devices and
introduced into the system libraries (see 
{\tt IOdevice(7)} for a description of how this is done).
\manSection{DIAGNOSTICS}
The function {\tt rciAllocDevice()} returns {\tt -1} in the event
of an error. Error information is reported on the {\it errorStack} (q.v.).

Returned error codes, accessible with {\tt getErrorCode()}, are:

\manItem{{\tt EDescriptor} --}
Invalid task descriptor.
\manItem{{\tt EActive} --}
Task is currently active.
\manItem{{\tt ENotDefined} --}
No driver is defined with the given name.
\manItem{{\tt EBusy} --}
The device at the specified location is currently being used and access is not
permitted according to the specified access mask.
\manItem{{\tt EMemory} --}
System is out of memory.
\manItem{{\tt ENoFile} --}
Can't access the lock file for the device.

These routines will abort the program if called from the control level.
\manSection{SEE ALSO}
\raggedright
{\tt IOdevice(7)}, {\tt rciCreate(3)}, {\tt rciInterruptDev(3)},
{\tt errorStack(3)}.
\manEnd
\end
