GINS(4) COMMAND REFERENCE GINS(4)
NAME
gins - GPIB instrument controller
SYNOPSIS
#include <box/gpib.h>
#include <sys/ioctl.h>
DESCRIPTION
This section describes both the instrument control special
files 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), (Reg.).I gprm(1) to set up the instrument
controller devices. They are described in gpid(4).
Interface devices support all GPIB operations. They are
also described in gpib(4). 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 below.
Applications which require the special features of the GPIB,
such as the ability to initiate a transfer in which the
controller does not participate, should access the bus
through the interface special files described in gpib(4).
Most applications do not need such features and should
access individual instruments through the instrument control
devices.
The instrument control devices provide a device-independent
means of communicating with GPIB instruments. In many
cases, standard commands such as tee(1) and echo(1) can be
used to perform simple control tasks without further
programming. The system calls ioctl(2) configure the device
and send interface messages. The system calls 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.
Printed 10/17/86 1
GINS(4) COMMAND REFERENCE GINS(4)
Configuration.
Instrument control devices are initially configured by the
gpconf(1) utility. Applications which need to change the
device configuration ``on the fly'' may use the GIOCGCONF
and GIOCSCONF ioctl(2) described in gpib(4). Specific
differences in these calls are listed here:
Addr specifies the instrument's GPIB address. The primary
address is stored in the high byte. The secondary address
is stored in the low byte. Setting the primary address to
G_NOADRS effectively removes the device from the system.
The GF_SCAS, GF_STD1, GF_VSTD1, GF_TCSYNC, and GF_PPST flags
are ignored. GF_TRDMA, GF_EXCL, GF_ASYNC, and GF_NDELAY
behave as described in gpib(4). One new flag is added:
GF_POLLME Enable polling of this instrument on service
request. See the description of the SRQ
interrupt, below.
Interface messages.
ioctl(fd, GIOCCMD, cmd)
char *cmd;
Assert ATN and send cmd on the GPIB. Cmd must be one of the
addressed commands defined in <box/gpib.h>. The driver will
add the appropriate device addresses just as it does for
read(2) and write(2).
ioctl(fd, GIOCSPOLL, status)
char *status;
Serial poll the instrument. If the GF_POLLME flag is set
and the instrument has requested service since the last
GIOCSPOLL or GIOCGSTAT, the driver will return the saved
status rather than polling the instrument again.
Device-dependent messages.
The system calls 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 gsterm field of the
gpibstat structure (described below) records the termination
condition for the last transfer.
The driver sends the appropriate talk and listen addresses
before each transfer and UNT UNL afterwards.
Printed 10/17/86 2
GINS(4) COMMAND REFERENCE GINS(4)
Status and signals.
The GIOCGSTAT ioctl(2) returns the gpibstat structure
described in gpib(4) . Specific differences in this
structure are listed here:
GSintr records only the following events:
GI_SRQ Service request. If the GF_POLLME flag is set,
the driver will poll this instrument whenever it
receives a bus SRQ message. If this instrument is
requesting service, the driver will set the SRQ
bit and update status.
GI_LOST The instrument has requested service more than
once. Only the most recent status byte is saved.
The GF_POLLME flag can lose status bytes if a particular
device on the bus sends out a lot of SRQs. If the GPIB
program can't keep up with the device asserting SRQs, the
workstation device drivers still continue to autopoll every
SRQ that appears on the bus. However, the device drivers do
not queue status bytes (see above). The result is lost
status bytes.
There is a way around that. When you begin your GPIB
program, open the bus's GPIB device and all
of the instruments attached to it. Set up your SRQ handler
so that a SIGURG signal will be sent to the GPIB device and
not
to any of the instruments. When SRQ is asserted, the
workstation will call your SRQ interrupt handler for each
SRQ that appears on the bus. No status bytes will be lost.
Some sample pseudo-code is:
main()
{
void poll();
int device_fd, inst_1_fd, inst_2_fd;
struct gpibconf cfg;
device_fd = open("/dev/gpibo", O_RDWR, 0);
inst_1_fd = open("/dev/dvm", O_RDWR, 0);
inst_2_fd = open("/dev/scope", O_RDWR, 0);
signal(SIGURG, poll);
ioctl(device_fd, GIOCGCONF, &cfg);
cfg.gc_flags |= GF_ASYNC;
cfg.gc_mask |= GI_SRQ;
cfg.gc_pgrp = getprgp(0);
ioctl(device_fd, GIOCSCONF, &cfg);
while(1) {
Printed 10/17/86 3
GINS(4) COMMAND REFERENCE GINS(4)
do some stuff
}
}
void
poll()
{
unsigned char status;
ioctl(inst_1_fd, GIOCSPOLL, &status);
if (status has bit 7 set)
service inst_1_fd;
ioctl(inst_2_fd, GIOCSPOLL, &status);
if (status has bit 7 set)
service inst_2_fd;
}
If the GF_ASYNC flag and the corresponding bit in the mask
are set, the driver will send a signal (SIGURG) to the
associated pgrp. A service request will also wake up
processes waiting for an exception in select(2). As a
special case, if the GF_POLLME flag is cleared, a select on
an exception will enable polling until the device first
requests service. At this time, further polling will be
disabled, the select will return, and a GIOCGSTAT ioctl will
report SRQ and the device status.
Status is the instrument's last reported serial poll status.
The two sample C programs below show ways of setting up an
asynchronous SRQ handler, one with auto-poll disabled, and
one with auto-poll enabled.
/*
* This simple program permits a user to send "set" and "query"
* commands to one of two instruments connected to /dev/gpib0 .
* The primary benefit of this program is that it shows how to
* correctly poll one or more instruments when the auto-poll
* feature is disabled.
*
* It is assumed that the following GPIB instruments are attached
* to /dev/gpib0 via gpconf(1) :
*
* /dev/scope - a Tek Codes and Formats oscilloscope
* /dev/fg - a Tek Codes and Formats function generator
*
* It is also assumed that gpconf(1) has been used to disable
* auto-polling of these instruments.
*
Printed 10/17/86 4
GINS(4) COMMAND REFERENCE GINS(4)
* ------------------------------------------------------------
*
* Usage:
* This program prompts the user for newline-delimited input
* from "stdin". The first character of each input line is
* examined and if it is "s" or "S", the input line (sans
* first character) is sent to /dev/scope as a device-dependent
* command. Immediately thereafter, this program reads a
* query response (if any) from /dev/scope.
*
* If the first character is not "s" or "S", the same steps
* as above are taken, but the input/output device is
* /dev/fg instead.
*
* Caveats:
* This program performs no I/O error checks.
*/
#include <stdio.h>
#include <signal.h>
#include <sys/file.h>
#include <sys/ioctl.h>
#include <box/gpib.h>
#define BUFLEN 10000
int scope, fg, dev;
main()
{
int bytes;
char s[BUFLEN], r[BUFLEN];
struct gpibconf cfg;
void poll();
scope = open("/dev/scope", O_RDWR, 0);
fg = open("/dev/fg", O_RDWR, 0);
dev = open("/dev/gpib0", O_RDWR, 0);
ioctl(dev, GIOCGCONF,&cfg); /* get GPIB configure structure*/
cfg.gc_flags |= GF_ASYNC; /* enable the signal flag*/
cfg.gc_mask |= GI_SRQ;
cfg.gc_pgrp = getpgrp(0); /* enable the signal process group */
ioctl(dev ,GIOCSCONF, &cfg); /* set GPIB configure structure*/
signal(SIGURG, poll); /* Enable SRQ interrupts for "dev" only */
for (;;) {
printf("> ");
gets(s); /* Read a GPIB command from stdin */
if (s[0] == 's' || s[0] == 'S') {
write(scope, &(s[1]), strlen(s) - 1);
Printed 10/17/86 5
GINS(4) COMMAND REFERENCE GINS(4)
bytes = read(scope, r, BUFLEN);
}
else {
write(fg, &(s[1]), strlen(s) - 1);
bytes = read(fg, r, BUFLEN);
}
r[bytes] = ' ';
printf("%s0,r); /* Print response on stdout */
}
}
void
poll()
{
unsigned char status;
/*
* Poll each instrument on the bus. If bit 7 of an
* instrument's status byte is set, that instrument
* asserted SRQ.
*/
ioctl(scope, GIOCSPOLL, &status); /* Serial poll */
if (status & 0x40) /* Test bit 7 */
printf("* scope status: %d0, status);
ioctl(fg, GIOCSPOLL, &status); /* Serial poll */
if (status & 0x40) /* Test bit 7 */
printf("* fg status: %d0, status);
}
------------------------------------------------------------------
/*
* This simple program permits a user to send "set" and "query"
* commands to one of two instruments connected to /dev/gpib0 .
* The primary benefit of this program is that it shows how to
* correctly poll one or more instruments when the auto-poll
* feature is enabled.
*
* It is assumed that the following GPIB instruments are attached
* to /dev/gpib0 via gpconf(1) :
*
* /dev/scope - a Tek Codes and Formats oscilloscope
* /dev/fg - a Tek Codes and Formats function generator
*
* It is also assumed that gpconf(1) has been used to enable
* auto-polling of these instruments.
*
* ------------------------------------------------------------
*
* Usage:
Printed 10/17/86 6
GINS(4) COMMAND REFERENCE GINS(4)
* This program prompts the user for newline-delimited input
* from "stdin". The first character of each input line is
* examined and if it is "s" or "S", the input line (sans
* first character) is sent to /dev/scope as a device-dependent
* command. Immediately thereafter, this program reads a
* query response (if any) from /dev/scope.
*
* If the first character is not "s" or "S", the same steps
* as above are taken, but the input/output device is
* /dev/fg instead.
*
* Caveats:
* This program performs no I/O error checks.
*/
#include <stdio.h>
#include <signal.h>
#include <sys/file.h>
#include <sys/ioctl.h>
#include <box/gpib.h>
#define BUFLEN 10000
int scope, fg;
main()
{
int bytes;
char s[BUFLEN], r[BUFLEN];
struct gpibconf cfg;
void poll();
scope = open("/dev/scope", O_RDWR, 0);
fg = open("/dev/fg", O_RDWR, 0);
ioctl(scope, GIOCGCONF,&cfg); /* get GPIB configure structure*/
cfg.gc_flags |= GF_ASYNC; /* enable the signal flag*/
cfg.gc_mask |= GI_SRQ;
cfg.gc_pgrp = getpgrp(0); /* enable the signal process group */
ioctl(scope ,GIOCSCONF, &cfg); /* set GPIB configure structure*/
ioctl(fg, GIOCGCONF,&cfg);
cfg.gc_flags |= GF_ASYNC;
cfg.gc_mask |= GI_SRQ;
cfg.gc_pgrp = getpgrp(0);
ioctl(fg ,GIOCSCONF, &cfg);
signal(SIGURG, poll); /* Enable "fg" and "scope"
* interrupts.
*/
for (;;) {
printf("> ");
Printed 10/17/86 7
GINS(4) COMMAND REFERENCE GINS(4)
gets(s); /* Read a GPIB command from stdin */
if (s[0] == 's' || s[0] == 'S') {
write(scope, &(s[1]), strlen(s) - 1);
bytes = read(scope, r, BUFLEN);
}
else {
write(fg, &(s[1]), strlen(s) - 1);
bytes = read(fg, r, BUFLEN);
}
r[bytes] = ' ';
printf("%s0,r); /* Print response on stdout */
}
}
void
poll()
{
unsigned char status;
/*
* Poll each instrument on the bus. If bit 7 of an
* instrument's status byte is set, that instrument
* asserted SRQ.
*/
ioctl(scope, GIOCSPOLL, &status); /* Serial poll */
if (status & 0x40) /* Test bit 7 */
printf("* scope status: %d0, status);
ioctl(fg, GIOCSPOLL, &status); /* Serial poll */
if (status & 0x40) /* Test bit 7 */
printf("* fg status: %d0, status);
}
Interaction with interface devices.
The driver arbitrates access to the interface hardware
between the interface device and any instrument control
devices present. The driver guarantees that there will be
no interruptions during an instrument control device
operation (address-transfer-unaddress); in most cases, this
will be sufficient to prevent problems. You can use the
GIOCASGN and GIOCRELSE ioctls to prevent other devices from
interrupting sequences of operations.
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), signal(3c), gpib(4), gpid(4), gins(4), config(8).
Printed 10/17/86 8
%%index%%
na:72,69;
sy:141,359;
de:500,2937;3581,2924;6649,2329;9122,2163;11429,2062;13635,2022;15801,2011;17956,1940;
se:19896,449;
%%index%%000000000156