GPIB(4) COMMAND REFERENCE GPIB(4) NAME gpib - GPIB interface driver For 4301, 4320 and 4330 Series UTek products. SYNOPSIS #include <box/gpibb.h> #include <sys/ioctl.h> #include <box/gpbioctl.h> DESCRIPTION This section describes the special files /dev/gpibn and the overall GPIB system organization. System Organization Each GPIB interface is associated with one configuration special file ( device ), one interface special file ( device ), and up to 15 instrument controller special files ( devices ). Configuration devices are used by the GPIB utilities gpconf(1), gpinit(1), and gprm(1) to set up the instrument controller devices; they are described in gpid(4). Interface devices support all GPIB operations; they are fully described later. Instrument control devices provide device-independent access to a single GPIB instrument; they are created by the gpconf(1) utility, and can be given whatever names the user desires. Instrument control devices are described in gins(4). Applications that require the special features of the GPIB, such as initiating a transfer in which the controller does not particitate, should access the bus through the interface devices described here. Most applications do not need such features and should access individual instruments through the instrument control devices. The /dev/gpibn devices allow direct control of the GPIB interface; ioctl(2) calls configure the interface and send interface messages; read(2) and write(2) transfer device- dependent data without interpretation. The GPIB is a message-oriented system; each read or write transfers a single message. Note that this precludes the use of stdio(3s) which assumes a stream-oriented device, although the function sprintf(3s) can be used to format messages in a local buffer. Messages can be split across multiple read or write requests. Configuration Printed 4/6/89 1
GPIB(4) COMMAND REFERENCE GPIB(4) The GIOCSCONF ioctl(2) sets or modifies the configuration of the interface. GIOCGCONF returns the current settings. GIOCSCONF and GIOCGCONF take the following structure (defined in <box/gpibb.h>) as argument: struct gpibconf { short gc_addr; /* GPIB address */ struct timeval gc_htime; /* handshake timeout */ struct timeval gc_ptime; /* serial poll timeout */ short gc_eom; /* end-of-message byte */ long gc_flags; /* device-dependent control flags */ short gc_pgrp; /* process or group to signal */ short gc_mask; /* interrupt mask */ }; gcaddr specifies the interface's GPIB address. The primary address is stored in the high byte. The secondary address (low byte) is forced to G_NOADRS. Setting the primary address to G_NOADRS effectively removes the interface from the system. gchtime and gcptime specify the time limits for command/data transfers and serial poll response, respectively. These values are the time allowed per byte transferred. The actual timeout may be up to twice as long as specified in certain cases. Setting the time to zero disables the timeout, but runs the risk of locking up the system. See the CAVEATS section. gceom is the byte recognized as end-of-message during read(2). The driver recognizes end-of-message, but does not modify the data. In particular, the end-of-message byte is not removed or changed. gceom can be set to -1 to disable end-of-message recognition. The GPIB interface message END will always terminate input. gcflags encodes various options: GF_SCAS This interface is the GPIB system controller. If this bit is set, GIOSCONF causes the driver to REN TRUE, assert IFC for .5 seconds, and enter the GPIB Controller Active State (CACS). If this bit is cleared, GIOSCONF causes the driver to immediately release REN, IFC, and ATN and enter the GPIB Controller Idle State (CIDS). GF_STD1 Reduce the interface T1 delay from 2.2 us to 1.2 us. GF_VSTD1 Reduce the interface T1 delay to 600 ns for the second and following bytes of any device-dependent message. Printed 4/6/89 2
GPIB(4) COMMAND REFERENCE GPIB(4) GF_TCSYNC Take control synchronously. By default, this bit is turned on by the GPIB configuration utility. Asynchronous assertion of ATN (GF_TCSYNC cleared) may cause data to be lost, but is provided as an option for special cases. GF_PPST Instrument status for parallel poll. GF_TRDMA Device-dependent data should be sent using DMA hardware, if present. GF_POLLME (Not used by the interface device.) GF_EXCL Block further open(2) calls on this device. This bit may also be set by the TIOCEXCL and cleared by the TIOCNXCL ioctls. GF_ASYNC Request asynchronous notification when the device status changes. See the discussion of Status and Signals. GF_ASYNC may also be set/cleared by the fcntl(2) system call or the FIOASYNC ioctl. GF_NDELAY Set the driver into non-blocking mode. read(2), write(2), and ioctl(2) will return EWOULDBLOCK if the interface is busy or EINPROGRESS if the interface is idle, but the caller must wait for the data transfer. See the discussion of asynchronous I/O. This bit may also be set/cleared by the FIONBIO ioctl or the fcntl(2) system call. GF_WEOI By default, this bit is turned on by the GPIB configuration utility gpconf(1). If a program turns this bit off and then writes data, EOI won't be asserted with the last byte of the message. This allows a single message to be broken across multiple write(2) calls. gcpgrp is the process group to be signalled when the driver is ready for I/O (SIGIO) or flags an exception (SIGURG). Note that the GF_ASYNC flag must be set to enable signalling. gcpgrp defaults to the first process to open the device. It can also be set/tested with the TIOCSPGRP/TIOCGPGRP ioctls. gcmask may be used to disable signals from certain events. See the discussion of status and signals. Interface Messages Printed 4/6/89 3
GPIB(4) COMMAND REFERENCE GPIB(4) ioctl(fd, GIOCIFC, atv) struct timeval *atv; Send interface clear and take control. GIOCIFC will return an error if this is not the system controller. atv can be NULL, in which case IFC is asserted for some default interval (0.5 second). The microsecond parameter available for GPIB does not return a value less than 50 milliseconds in pulse width -- make the resulting time conversion as necessary. ioctl(fd, GIOCREN, aren) int *aren; Set the state of the interface REN line. GIOCREN will return an error if this is not the system controller. ioctl(fd, GIOCPPST, appst) int *appst; Set or clear the workstation's parallel poll response flag. This call can be used to change the state of the PPST flag without reconfiguring the interface. ioctl(fd, GIOCWEOI, aweoi) int *aweoi; Set or clear the WEOI flag. This call can be used to change the state of the WEOI flag without reconfiguring the interface. ioctl(fd, GIOCSTB, astat) int *astat Set the workstation's serial poll status byte. If the RSV bit (bit 6, numbering from 0) of the status byte is set, the workstation asserts SRQ on the bus until it is polled by the controller-in-charge. If the RSV bit is clear, the workstation immediately releases SRQ. Note that it is not possible for the workstation to poll its own status. ioctl(fd, GIOCRSV, arsv) int *arsv; Set or clear rsv local message. SRQ will be cleared when the workstation is polled. ioctl(fd, GIOCCMD, cmd) char *cmd; Assert ATN and send cmd on the GPIB. Addressed, universal, and secondary commands are defined in <box/gpibb.h>; cmd may Printed 4/6/89 4
GPIB(4) COMMAND REFERENCE GPIB(4) point to a null character ('\0') to take control (assert ATN) without sending any command. The null will not be sent. ioctl(fd, GIOCWEND, atv) struct timeval *atv; Drop ATN and wait for the data transfer to complete. There is no default time value. atv specifies the maximum time to be allowed for the transfer. ioctl(fd, GIOCSPOLL, status) char *status; Drop ATN and read one byte from the GPIB. This call is used to read the serial poll status from a previously addressed device. You must use GIOCSPOLL to read the serial poll status from a device; attempting to use read(2) may hang the GPIB. ioctl(fd, GIOCPPOLL, status) char *status; Assert ATN with EOI (GPIB IDY message) and return the GPIB data. Device-Dependent Messages The calls read(2) and write(2) transfer device-dependent messages. Each read transfers no more than one message. The term field of the gpibstat structure (described later) records the termination condition for the last transfer. If the message is longer than the buffer the remaining bytes are not discarded, but can be read with another read call. Each write call is normally treated as a single message. The driver asserts EOI by sending a GPIB END message concurrently with the last byte written. A single message can be split across multiple write calls if the user clears the WEOI flag before writing the first portion and setting WEOI before the last portion of the message. Status and Signals The GIOCGSTAT ioctl(2) returns the following structure (defined in <box/gpibb.h>): struct gpibstat { short gs_intr; /* pending interrupts */ char gs_status;/* device status byte */ Printed 4/6/89 5
GPIB(4) COMMAND REFERENCE GPIB(4) char gs_term; /* last I/O terminator */ long gs_state; /* interface state */ }; gsintr records the following events: GI_SRQ Service request. This bit will remain set as long as the GPIB SRQ message is true. GI_LOST (Not used by the interface device.) GI_RLC Remote/local status change. The current status is part of the interface gsstate. GI_TCT Control is passed to this interface. The driver interrupts any active I/O and sets this flag when the GPIB TCT (Take Control) message is received. GI_DCAS Device clear active state. The driver interrupts any active I/O and sets this flag when the GPIB DCL or SDC message is received. GI_SPAS Serial poll active state. The controller has polled this interface and the status can be changed. GI_GET Device trigger message received. GI_IFC Interface clear message received. GI_MTA My talk address. The interface has entered the talker active state. GI_MLA My listen address. The interface has entered the listener active state. GI_IWANT I want control. This bit is provided for the benefit of certain shared-control applications. It is set by a GIOCASGN from an instrument control device when the interface device has assigned the bus or by a read or write to an instrument control device if this interface is not the controller- in-charge. GI_SRQ, GI_TCT, and GI_IWANT stay active until the associated condition goes away. Other bits are cleared when read. If the GF_ASYNC flag and the corresponding bit in the gc_mask are set, the driver will send a signal to the associated gcpgrp. GI_MTA and GI_MLA send SIGIO; all other interrupts send SIGURG. An interrupt will also wake up a Printed 4/6/89 6
GPIB(4) COMMAND REFERENCE GPIB(4) process waiting in select(2). GI_MTA and GI_MLA will wake up a process waiting for write or read, respectively. Other interrupts will wake up processes waiting for exceptions. gsstatus is this interface's serial poll status, set by the GIOCSSTAT or GIOCRSV ioctls(2). It is not generally useful. gsterm records the termination status for the last I/O operation: GT_END EOI was asserted with the last byte placed in the buffer. GT_EOM The last byte placed in the buffer was the end- of-message byte. GT_ERR There were no active listeners on the bus. (The write(2) returns EIO.) GT_TIME The transfer timed out. (The read(2) or write(2) returns EIO.) GT_INTR The transfer was interrupted by an interface message which changed the addressed state of the interface. gsstate records the current addressed state of the interface along with some other values. See <box/gpibb.h> for a complete list. Asynchronous I/O If the NDELAY flag is set, the driver does not block waiting for any I/O operation. Instead it returns EWOULDBLOCK if the operation cannot be initiated (e.g., some other I/O operation is in progress) or EINPROGRESS if the operation can be initiated but not completed without waiting (e.g., read or write while controller-in-charge). The application may choose to wait in select(2) or perform other processing while awaiting a SIGIO indicating the interface is ready and the I/O operation may be repeated. Interaction with Instrument Control Devices The driver arbitrates access to the interface hardware between the interface device and any instrument control devices present. To prevent interference from other users, you must assign the GPIB during each sequence of operations. Printed 4/6/89 7
GPIB(4) COMMAND REFERENCE GPIB(4) ioctl(fd, GIOCASGN, was) int *was; If was is non-null, GIOCASGN returns the previous (assigned/not assigned) state. If the GF_NDELAY flag is set and the interface is busy, GIOCASGN will return EWOULDBLOCK. ioctl(fd, GIOCRELSE, NULL) Release the GPIB for other use. CAVEATS A timeout of zero causes the system to lock up if the expected response does not occur. The most common example is when a non-existent GPIB device is referenced. To avoid this problem, rather than disabling the timeout, specify a large value for gchtime or gcptime. If the device is non-existent the timeout eventually occurs, letting the system process the missing response. SEE ALSO gpconf(1), gpinit(1), gprm(1), gpstat(1), close(2), fcntl(2), ioctl(2), open(2), read(2), select(2), sigvec(2), write(2), sigset(3j), gpib(4), gpid(4), and gins(4). REFERENCES 4300 Series Option 3J (F3J) High Speed GPIB Interface Reference & Installation Printed 4/6/89 8
%%index%% na:240,132; sy:372,848; de:1220,2931;4463,3039;7814,2907;11033,4153;15498,3808;19618,2462;22392,3059;25763,875; ca:26638,655; se:27293,454; re:27747,354; %%index%%000000000187