GINS(4) COMMAND REFERENCE GINS(4) NAME gins - GPIB instrument controller SYNOPSIS #include <box/gpibb.h> #include <sys/ioctl.h> #include <box/gpbioctl.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), and 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 later. Applications that require 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. Configuration Printed 5/19/88 1
GINS(4) COMMAND REFERENCE GINS(4) 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. 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/gpibb.h>. The driver adds 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 returns 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 later) records the termination condition for the last transfer. The driver sends the appropriate talk and listen addresses before each transfer and sends UNT UNL afterwards. Printed 5/19/88 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 is sent to the GPIB device and not to any of the instruments. When SRQ is asserted the workstation calls your SRQ interrupt handler for each SRQ that appears on the bus. No status bytes are 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/gpiba", 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) { do some stuff } Printed 5/19/88 3
GINS(4) COMMAND REFERENCE GINS(4) } 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 sends a signal (SIGURG) to the associated pgrp. A service request also wakes 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 enables polling until the device requests service. At this time, further polling is disabled, the select returns, and a GIOCGSTAT ioctl reports SRQ and the device status. Status is the instrument's last reported serial poll status. These two sample C programs 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/gpiba . * 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/gpiba 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. * * ------------------------------------------------------------ * * Usage: * This program prompts the user for newline-delimited input * from "stdin". The first character of each input line is Printed 5/19/88 4
GINS(4) COMMAND REFERENCE GINS(4) * 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/gpibb.h> #include <box/gpb_ioctl.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/gpiba", 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); bytes = read(scope, r, BUFLEN); } else { write(fg, &(s[1]), strlen(s) - 1); Printed 5/19/88 5
GINS(4) COMMAND REFERENCE GINS(4) 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/gpiba . * 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/gpiba 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: * 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 Printed 5/19/88 6
GINS(4) COMMAND REFERENCE GINS(4) * 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/gpibb.h> #include <box/gpb_ioctl.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("> "); 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); } Printed 5/19/88 7
GINS(4) COMMAND REFERENCE GINS(4) 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 there are no interruptions during an instrument control device operation (address-transfer-unaddress); in most cases, this is 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), and config(8). 4300 Series Option 3J (F3J) High Speed GPIB Interface Reference & Installation Printed 5/19/88 8
%%index%% na:240,85; sy:325,848; de:1173,3084;4569,3610;8491,2602;11405,2432;14149,2004;16465,2232;19009,1947;21268,1940; se:23208,708; %%index%%000000000159