gpib - Generic GPIB Record

Contents

The GPIB record is designed to perform generic GPIB I/O. It is intended to
allow EPICS to communicate with a new GPIB instrument without even rebooting
the IOC, i.e. without writing any C code or changing the database. The GPIB
record is thus very useful for allowing Channel Access clients to communicate
with GPIB devices for which no EPICS device support exists. It is also useful
for GPIB diagnostics. The GPIB bus address is a field in the record which can
be modified, so the record can be used to communicate with multiple devices.

The GPIB record communicates with the GPIB controller hardware through the
standard EPICS GPIB driver. This means that any supported GPIB controller can
be used. These presently include the National Instruments VME board, and the
Greenspring Industry Pack module. The latter is supported under Hideos and
MPF.

There are two output fields, AOUT (ASCII Output) and BOUT (Binary Output). The
OFMT (Output Format) field is used to select one of these fields or the other
as the output source to the GPIB device.
Similarly, there are two input fields, AINP (ASCII Input)
and BINP (Binary Input). The
IFMT (Input Format) field is used to select one or the other as the
destination of data sent from the GPIB device.
The ASCII fields are type DBF_STRING,
and are very convenient for typical communication with many GPIB devices. They
permit, for example, medm
screens where the user can type a string and observe
the response from the instrument. The ASCII fields, however are limited
to 40 characters in length, and cannot be used to read or write binary data.
The binary input and output fields are DBF_CHAR arrays,
and can be used to transfer many
kilobytes of arbitrary data, either ASCII or binary.

A read
operation on input continues until 1 of the following 4 conditions is met:

The device asserts EOI

The input delimiter (EOS) is found. See note under
Restrictions below.

The desired number of input characters (NRRD) are received

The timeout (TMOT) expires

The GPIB record calls the GPIB driver directly, and does not go through a
separate device support layer.

This field is unused. The functions normally assigned to the VAL
field in many records are performed by the AOUT, BOUT, AINP, and BINP fields
in the GPIB record.

TMOD

R/W

"Transaction mode"

DBF_RECCHOICE

The type of GPIB transaction which is desired. The choices are:

"Write/Read" (default)

The output source (AOUT or BOUT as selected by OFMT) is sent
to the GPIB device. A response is then read back into AINP or BINP (as
selected by IFMT). The response must be received within the time specified by
TMOT.

"Write"

The output source (AOUT or BOUT as selected by OFMT) is sent
to the GPIB device. No response is read back.

"Read"

Data is read from the GPIB device into the input field (AINP or BINP as
selected by IFMT). The response must be received within the time specified by
TMOT. No output is sent to the device prior to the read operation.

AOUT

R/W*

"Output (command) string"

DBF_STRING

The output string which is sent to the device if OFMT="ASCII". The number
of bytes sent to the device will be strlen(AOUT).

BOUT

R/W*

"Output binary data"

DBF_CHAR (array)

The output data which is sent to the device if OFMT="Binary". The maximum
length of this field is controlled by OMAX.
The actual number of bytes to be sent to the device is controlled by NOWT.

OMAX

R

"Max. size of output array"

DBF_LONG

The allocated length of the BOUT array. This value cannot be changed after
IOC initialization. Default=512.

NOWT

R/W

"Number of bytes to write"

DBF_LONG

The actual number of bytes to send from the BOUT array to the GPIB device
if OFMT="Binary". This value must be less than or equal to OMAX.
Default=512.

OFMT

R/W

"Output format"

DBF_RECCHOICE

The output format. The choices are:

"ASCII"

The data sent to the device will be taken from the AOUT field.

"Binary"

The data sent to the device will be taken from the BOUT field.

AINP

R

"Input (response) string"

DBF_STRING

The input string which is read from the device if IFMT="ASCII". The string
will be NULL terminated. Note that due to the maximum size of a string in
EPICS, the response must be less than 40 characters. If longer responses are
required then set IFMT="Binary" and read into the BINP field.

BINP

R

"Input binary data"

DBF_CHAR (array)

The input data which is read from the device if IFMT="Binary". The maximum
length of this field is controlled by IMAX.
The actual number of bytes read from the device is given by NORD.

IMAX

R

"Max. size of input array"

DBF_LONG

The allocated length of the BINP array. This value cannot be changed after
IOC initialization. Default=512.

EOS

R/W

"Input delimiter"

DBF_LONG

A character which indicates the end of a message on input.
Set this field to -1 (the default) if no character should be used
as an input delimiter.
Commonly used values are 10 (Line Feed) or 13 (Carriage Return).
The input delimiter will be removed from the input buffer on both
ASCII and binary reads.
See note under
Restrictions below.

NRRD

R/W

"Number of bytes to read"

DBF_LONG

The requested number of bytes to read. This
field is valid for both "ASCII" and "Binary" input formats. If this field is
zero, then the requested number of bytes to read will be the EPICS defined
MAX_STRING_SIZE=40 (if IFMT="ASCII") or IMAX (if IFMT="Binary").
Default=0.

NORD

R

"Number of bytes read"

DBF_LONG

The actual number of bytes read in the last GPIB read operation. This
field is valid for both "ASCII" and "Binary" input formats.

IFMT

R/W

"Input format"

DBF_RECCHOICE

The input format. The choices are:

"ASCII" (default)

The data read from the device will be placed in the AINP field.

"Binary"

The data read from the device will be placed in the BINP field.

INP

R

"Input Specification"

DBF_INLINK

The input link specification. This field is used to select the GPIB device
type (National Instruments, HiDEOS, Bitbus), link number, and GPIB address.
The initial GPIB address can be specified either in the INP field or
the ADDR field, with the ADDR field taking precedence
if both are non-zero.

SPR

R

"Serial Poll Response"

DBF_UCHAR

The device status byte, which is read during a Serial Poll operation.

ADDR

R/W

"GPIB address"

DBF_LONG

The GPIB address of the device. This field is can be initialized to a value
when creating the database. If the initial value is zero and the GPIB
address specified in the INP (Input Link) field is non-zero, then the
input link value will be copied to ADDR. This field can be changed at any time.

TMOT

R/W

"Timeout (msec)"

DBF_LONG

The timeout value for GPIB read operations in milliseconds.
If a response is not received from the device within this time then the record
sets a major alarm.

UCMD

R/W*

"Universal command"

DBF_RECCHOICE

A GPIB Universal Command to be executed. GPIB Universal Commands are
commands which are directed to all devices on the GPIB bus, not just addressed
devices. The choices are:

"None"

"Device Clear (DCL)"

"Local Lockout (LL0)"

"Serial Poll Disable (SPD)"

"Serial Poll Enable (SPE)"

"Unlisten (UNL)"

"Untalk (UNT)"

If the UCMD field is set to any value except
"None" then the
following occurs: the record processes, the appropriate
Universal Command is
executed, and UCMD is set back to "None". The record processing
only performs the Universal Command, i.e. it does not also
perform the GPIB operation indicated by TMOD.

ACMD

R/W*

"Addressed command"

DBF_RECCHOICE

A GPIB Addressed Command to be executed. GPIB Addressed Commands are
commands which are directed to only the addressed devices on the GPIB bus.
The choices are:

"None"

"Group Execute Trig. (GET)"

"Go To Local (GTL)"

"Selected Dev. Clear (SDC)"

"Take Control (TCT)"

"Serial Poll"

If the ACMD field is set to any value except
"None" then the
following occurs: the record processes, the appropriate
Addressed Command is
executed, and ACMD is set back to "None". The record processing
only performs the Addressed Command, i.e. it does not also
perform the GPIB operation indicated by TMOD.

Private Fields

IPTR

N

"Input buffer pointer"

DBF_NOACCESS

The pointer to the buffer for the BINP field.

OPTR

N

"Output buffer pointer"

DBF_NOACCESS

The pointer to the buffer for the BOUT field.

OINP

R

"Previous input string"

DBF_STRING

The previous input string. Used for posting events when IFMT="ASCII".

Note: In the Access column above:

R

Read only

R/W

Read and write are allowed

R/W*

Read and write are allowed; write triggers record
processing if the record's SCAN field is set to "Passive".

The following table briefly describes all of the files required to implement
the GPIB record. The reader is assumed to be familiar with the
EPICS IOC Software Configuration Management document
which describes how to build an
EPICS application tree into which these files are to be placed, and how to run
"gnumake" to build the record support. These files can all be
obtained in a
compressed tar file. This file should be untarred in a
&lttop&gt/xxxApp/ directory.

Files to be placed in
&lttop&gt/xxxApp/src/

gpibRecord.c

The source file for the record

gpibRecord.dbd

The database definition file for the record

Makefile.Vx

This file is not included in the distribution. However, the user must edit
this file and add the following lines:

SRCS.c += ../gpibRecord.c
LIBOBJS += gpibRecord.o

Makefile.Host

This file is not included in the distribution. However, the user must edit
this file and the following line:

RECTYPES += gpibRecord.h

xxxAppInclude.dbd

This file is not included in the distribution. However, the user must edit
this file and add the following lines:

This file builds an medm screen to access the GPIB record.
The medm screen is most useful for communicating with GPIB devices
in ASCII.
To use it from the command line, type the following:

&gt medm -x -macro REC=my_gpib_record GPIB_IO.adl

where my_gpib_record is the name of a GPIB record in an IOC.

This file can also be used as a related display from other medm
screens by passing the argument REC=my_gpib_record.

Files to be placed in
&lttop&gt/xxxApp/Db/

gpib.db

This file loads an instance of a GPIB record. It is very simple, and it
will need to be edited if you are not using Hideos or MPF.

Files to be placed in
&lttop&gt/iocBoot/&ltiocName&gt/

st.cmd

This file is not included in the distribution. However, this file must be
edited to enable support for the particular GPIB driver being used. A line like
the following must be added to load a generic GPIB record:

The GPIB record presently has no support for SRQs, which are
Service Requests, the GPIB
equivalent of an interrupt. Support for SRQs may be added in the future.

The EOS (input delimiter) character is presently implmented only for HiDEOS
or MPF links. It is not yet implemented for National Instruments or
Bitbus links. EOS may be supported for these links in a future release of the
EPICS GPIB driver.