rciAllocDevice(3)

NAME
rciDeallocDevice, rciAllocDevice -- attaches an RCI task to an I/O driver.

USAGE
#include <rci.h>

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

rciDeallocDevice (td)
   RCI_DESC *td;

ARGUMENTS

td --
    Pointer to task descriptor.

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.

mode --
    Access mode for the device. The access modes are defined in h/IOdevice.h. There are two mode flags: DEV_INTERNAL allows the device to be attached multiple times within the same program. DEV_EXTERNAL allows the device to be accessed multiple times from different programs. DEV_ALL is the combination of DEV_EXTERNAL and DEV_INTERNAL, and DEV_NONE defines both flags set to 0.

RESTRICTIONS
These routines must be called from the planning level.

DESCRIPTION
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.

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

Each RCI I/O device is defined by an address and a driver name. These are specified using the structure devAddr:
      struct devAddr {
         char *name;            /* device type (driver name) */
         int address;           /* physical address */
         char *addrStr;         /* supplemental address info */
         int args[MAX_DEVARGS]; /* special arguments */
      }

The driver is a collection of I/O routines grouped together with a name given by the name field. The address field is an identifying address (usually a bus address). The addrStr field is used to provide additional addressing information; at present this is supported for tasks running on the arbiter CPU only (specifically, the addrStr field is used by the simulator device sim). The args field defines optional parameters that may by used by the driver routines (for instance, additional addressing information for the 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 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 IOdevice(7) for a description of how this is done).

DIAGNOSTICS
The function rciAllocDevice() returns -1 in the event of an error. Error information is reported on the errorStack (q.v.).

Returned error codes, accessible with getErrorCode(), are:

EDescriptor --
    Invalid task descriptor.

EActive --
    Task is currently active.

ENotDefined --
    No driver is defined with the given name.

EBusy --
    The device at the specified location is currently being used and access is not permitted according to the specified access mask.

EMemory --
    System is out of memory.

ENoFile --
    Can't access the lock file for the device.

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

SEE ALSO
IOdevice(7), rciCreate(3), rciInterruptDev(3), errorStack(3).