GPIB(4) COMMAND REFERENCE GPIB(4)
NAME
gpib - GPIB interface driver
SYNOPSIS
#include <box/gpib.h>
#include <sys/ioctl.h>
DESCRIPTION
This section describes both 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 below. Instrument control devices
provide device-independent access to a single GPIB
instrument. They are created by the gpconf(1) utility, and
may be given whatever names the user desires. Instrument
control devices are described in gins(4).
Applications which require the special features of the GPIB,
such as the ability to initiate 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.
Configuration.
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/gpib.h>) as argument:
Printed 10/17/86 1
GPIB(4) COMMAND REFERENCE GPIB(4)
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 CAVEATS section below.
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. EOI will always terminate
input.
Gcflags encodes various options:
GF_SCAS This interface is the GPIB system controller.
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.
GF_TCSYNC Take control synchronously. Asynchronous
assertion of ATN (GF_TCSYNC cleared) may cause
data to be lost.
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.)
Printed 10/17/86 2
GPIB(4) COMMAND REFERENCE GPIB(4)
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 below. 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. 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.
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 may 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 below.
Interface messages.
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 may be
NULL, in which case IFC is asserted for some default
interval (0.5 second). (The microsecond parameter available
for gpib will 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, GIOCCMD, cmd)
char *cmd;
Printed 10/17/86 3
GPIB(4) COMMAND REFERENCE GPIB(4)
Assert ATN and send cmd on the GPIB . Addressed, universal,
and secondary commands are defined in <box/gpib.h>. Cmd may
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.
Read(2) and write(2) transfer device-dependent messages.
Each read transfers exactly one message. If the message is
longer than the buffer, the remaining bytes will be
discarded. The term field of the gpibstat structure
(described below) records the termination condition for the
last transfer.
Status and signals.
The GIOCGSTAT ioctl(2) returns the following structure
(defined in <box/gpib.h>):
struct gpibstat {
short gs_intr; /* pending interrupts */
char gs_status;/* device status byte */
char gs_term; /* last I/O terminator */
long gs_state; /* interface state */
};
Gsintr records the following events:
Printed 10/17/86 4
GPIB(4) COMMAND REFERENCE GPIB(4)
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 Take control message received. Control is being
passed to this interface. You must accept control
(GIOCACPT ioctl) before attempting any I/O.
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 may 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 read or write to an instrument
control device if this interface is not the
controller-in-charge.
When one of these events occurs, the status bit is set.
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
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.
Printed 10/17/86 5
GPIB(4) COMMAND REFERENCE GPIB(4)
Term 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/gpib.h>
for a complete list.
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.
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. Thus, if the device
is non-existent, the timeout will eventually occur, letting
the system process the missing response.
Printed 10/17/86 6
GPIB(4) COMMAND REFERENCE GPIB(4)
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), gins(4), config(8).
Printed 10/17/86 7
%%index%%
na:72,64;
sy:136,359;
de:495,2924;3563,2607;6314,3028;9486,2904;12534,2498;15176,2045;
ca:17221,575;
se:17940,494;
%%index%%000000000148