HPUX hpib[7]
hpib(7) Series 800 Only hpib(7)
NAME
hpib - Hewlett-Packard Interface Bus driver
SYNOPSIS
#include <sys/hpibio.h>
DESCRIPTION
HP-IB is Hewlett-Packard's implementation of the Institute of
Electrical and Electronic Engineers Standard Digital Interface for
Programmable Instrumentation (IEEE Std 488-1978). This section
describes the use of the HP-IB driver in the HP-UX system.
Auto-addressed Files vs. Raw Bus Files
A major distinction is made in the HP-UX driver between "auto-
addressed" files and "raw bus" files. An auto-addressed file is
associated with a specified address on the HP-IB. The user need not
be concerned with any HP-IB addressing or commands; the driver handles
device addressing and unaddressing during data transfers. However,
the user is limited to transactions to and from a single device. A
raw bus file, on the other hand, gives the user access to the entire
HP-IB; responsibility for all commands and addressing lies with the
user. The raw bus file is typically used to access multiple devices
on the same bus, as well as provide universal device commands such as
interface clear and parallel poll.
Although differences exist between auto-addressed and raw bus files,
the user/driver interface is consistent across both types. Therefore,
each category of requests is presented with separate subsections for
auto-addressed and raw bus files.
Naming Convention
HP-IB device files are named according to the following format:
/dev/hpib/#[a#]
where the first # specifies the bus number (assigned by the
administrator) and the second # specifies the address on that bus.
Device files without an address suffix denote the raw bus. Files with
the address suffix are auto-addressed.
Device Attributes
HP-IB attributes are classified into two groups, per-open and per-
interface. File descriptors obtained from separate open() requests
have separate per-open attributes (see open(2)); changing an attribute
from the per-open group affects requests on that file descriptor only.
Attributes in the per-interface group are shared by all file
descriptors on that interface; changing an attribute from one file
descriptor affects all users of the interface.
The per-open set of attributes and the driver requests to change them
are listed in the following table. All other attributes are per-
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
hpib(7) Series 800 Only hpib(7)
interface.
center tab(;); lB lB l lf4. Attribute;Driver Request _
timeout;HPIB_TIMEOUT write termination mode;HPIB_EOI read termination
pattern;HPIB_READ_PATTERN read termination reason;HPIB_TERM_REASON
signal mask;HPIB_SIGNAL_MASK lock count;HPIB_LOCK wait
events;HPIB_WAIT_ON_STATUS
Transfer Requests
The standard read() and write() requests are used for data transfer
over HP-IB (see read(2) and write(2)). However, their actions are
slightly different for each type of file. Raw bus files place data
directly onto the bus. No addressing or unaddressing of devices is
done by the driver; this is the user's responsibility.
On the other hand, the driver does all addressing for transactions
with auto-addressed files. The actual sequence of events is:
UNL, <device addressing>, <data>, <terminator>
All write requests end when the specified number of bytes has been
transferred over the bus. Optionally, the HP-IB END message can be
sent with the last byte written; this is controlled via the HPIB_EOI
request. All read requests end when the specified number of bytes has
been read over the bus or when the device asserts EOI. In addition, a
single character can be designated to end the read operation via the
HPIB_READ_PATTERN request.
Control Requests
Control requests cause some action on the bus. All such requests have
the same format:
struct io_ctl_status {
int type;
int arg[3];
} hpib_control;
ioctl(fildes, IO_CONTROL, &hpib_control);
In the io_ctl_status structure, the type field specifies the type of
control function required, while the arg array holds any associated
arguments. The defined values for type and their use are described as
follows:
HPIB_TIMEOUT Set the timeout. If any transaction for this file
takes longer than arg[0] microseconds, it is
aborted with a status of ETIMEDOUT returned to the
user. This is used mainly for detecting device
failure. A timeout of 0 is equivalent to
infinity; that is, no transaction will time out.
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
hpib(7) Series 800 Only hpib(7)
HPIB_WIDTH Set the width of the interface. This request
specifies the number of valid data lines on
transfers; arg[0] holds the desired interface
width in bits. All future read requests inspect
only the least significant arg[0] data lines, and
all future writes present data on only those
lines. The state of all other data lines is
indeterminate.
HPIB_SPEED Set the transfer speed of the interface. The
desired data transfer speed in kilobytes per
second is specified in arg[0]. Note that this
value is advisory only, and is typically used by
the driver to determine the method of data
transfer.
HPIB_EOI Enable/disable EOI assertion on writes. If arg[0]
is nonzero, all subsequent writes end with EOI
asserted on the last byte transferred. A zero
arg[0] disables EOI assertion.
HPIB_SYSTEM_CTLR Make the interface system controller or non-system
controller. If arg[0] is nonzero, the interface
becomes the system controller. A zero in arg[0]
sets the interface to non-system controller. This
request is applicable to raw bus files only.
HPIB_READ_PATTERN Enable or disable pattern matching on reads. If
arg[0] is nonzero, all subsequent reads terminate
when the pattern specified in arg[1] is
encountered in the input stream. This termination
condition is subject to all other termination
conditions in effect for the file. Only the n
least significant bits of the pattern are used in
the match, where n is the interface's current
width, set via HPIB_WIDTH. A zero arg[0] disables
read pattern matching.
HPIB_SIGNAL_MASK Define signaling events. This request allows the
calling process to receive a signal when some
event occurs on the HP-IB. The event or events
are specified by computing the bitwise inclusive
OR of the values from the list below, and placing
the mask in arg[0]. All of these events can be
enabled on raw bus files, but only ST_SRQ and
ST_PPOLL apply to auto-addressed files.
ST_SRQ Signal on assertion of Service
Request (SRQ).
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
hpib(7) Series 800 Only hpib(7)
ST_PPOLL Signal when device responds to
Parallel Poll.
ST_REN Signal when interface enters
remote state.
ST_ACTIVE_CTLR Signal when interface becomes
active controller.
ST_TALK Signal when interface is
addressed to talk.
ST_LISTEN Signal when interface is
addressed to listen.
ST_IFC Signal on assertion of
Interface Clear (IFC).
ST_DCL Signal on receipt of Device
Clear (DCL).
ST_GET Signal on receipt of Group
Execute Trigger (GET).
When any subsequent flagged event occurs, the
process is sent SIGEMT. The user should set up a
handler to trap this signal via signal() or
sigvector() (see signal(2) or sigvector(2)). The
reason for interrupt can be obtained via the
IO_STATUS request HPIB_SIGNAL_MASK. Each request
overwrites the previous mask for the file;
therefore events can be disabled by using a zero
arg[0].
If ST_PPOLL is flagged, the user supplies
additional information in the arg array. For raw
bus files, the low-order bytes of arg[1] and
arg[2] contain eight-bit masks with each bit
corresponding to a Data I/O (DIO) line and the
least significant bit mapped to DIO1. When a
device responds to parallel poll, it asserts the
appropriate line; arg[1]'s bits indicate the
parallel poll sense of this assertion. Bits set
in arg[2] indicate that the corresponding address
is capable of responding to polling. For auto-
addressed files, arg[1] specifies the parallel
poll sense of the assigned device's response to
parallel poll. Parallel poll interrupts can be
enabled only if the interface is the active
controller.
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992
hpib(7) Series 800 Only hpib(7)
HPIB_LOCK Lock or unlock the HP-IB interface. Setting
arg[0] to LOCK_INTERFACE locks the HP-IB
interface, giving the calling process exclusive
access to the card and bus. The lock is
incremental; that is, if the interface is already
locked by the current process, additional lock
requests increment a per-open lock count
maintained in the driver.
An arg[0] of UNLOCK_INTERFACE decrements the per-
open lock count; when the total interface lock
count drops to zero, the lock is cleared. The
lock can also be cleared by setting arg[0] to
CLEAR_ALL_LOCKS, which removes all locks held by
the current process.
After a successful lock or unlock, arg[1] contains
the current lock count for this open, and arg[2]
contains the total lock count on this interface.
While the interface is locked, other processes
that attempt to access the bus or interface are
blocked until either the interface becomes
unlocked or the process's per-open timeout (set
via HPIB_TIMEOUT) expires. However, if the
O_NDELAY file status flag is set (see fcntl(5)),
the user request fails and returns immediately
with the EACCES error. See the Summary of
Privilege Requirements section for a list of user
requests that might block.
HPIB_ADDRESS Set the HP-IB address to which the interface
responds when it is not the active controller.
The bus address is set via arg[0], and must be
between 0 and 30 decimal. Two additional flags,
HPIB_TALK_ALWAYS and HPIB_LISTEN_ALWAYS, can be
set by computing the bitwise inclusive OR of their
values with the address. These flags enable the
interface to talk, and/or listen always,
respectively. This request is applicable to raw
bus files only.
HPIB_RESET Reset the device or bus, depending on which of the
following values is in arg[0]:
DEVICE_CLR Address the device and send a
selective device clear (SDC)
command. This applies only to
auto-addressed files.
Hewlett-Packard Company - 5 - HP-UX Release 9.0: August 1992
hpib(7) Series 800 Only hpib(7)
BUS_CLR Assert Interface Clear (IFC)
and Remote Enable (REN), and
clear Attention (ATN).
HW_CLR Reset bus interface card. The
card is self-tested and if the
card is system controller, IFC
is pulsed. All other card
state information is
preserved. This applies to
raw bus files only.
HPIB_PPOLL_RESP Control the interface's response to parallel poll.
When the interface is not acting as active
controller, it can be enabled to respond to
parallel polling by the current active controller.
If arg[0] is nonzero, the interface responds to
parallel poll. arg[1] specifies the DIO line on
which the card responds; arg[1] has a value
between 0 and 7, with a value of 0 mapping to
DIO1, 1 mapping to DIO2, and so forth. The
parallel poll sense of the response is determined
by arg[2]. An arg[0] of zero disables the
interface's response to parallel poll.
For auto-addressed files, the file's associated
device address is configured, rather than the
interface.
HPIB_PPOLL_IST Enable or disable response to parallel poll. If
arg[0] is nonzero, the interface responds to
parallel poll. An arg[0] of zero disables the
interface's response. This differs from the
previous request, because the parallel poll sense
and address of the interface's response are
unchanged. This request applies to raw bus files
only.
HPIB_REN Place a device into or out of the remote state.
For a raw bus file, this request merely sets or
clears the Remote Enable line, depending on
whether arg[0] is nonzero or zero respectively.
For auto-addressed files, a nonzero arg[0] asserts
the Remote Enable line and addresses the device.
If arg[0] is zero, the device is removed from the
remote state by sending it a Go-to-Local command
(GTL).
HPIB_SRQ Request service. This request causes the
interface to assert the Service Request line (SRQ)
until it is serially polled. At that time it
Hewlett-Packard Company - 6 - HP-UX Release 9.0: August 1992
hpib(7) Series 800 Only hpib(7)
responds with the status byte given in arg[1].
This request applies to raw bus files only.
This request is normally used only when the
interface is not the active controller.
Nonetheless, the active controller can assert SRQ,
and the HPIB_BUS_STATUS request will reflect the
assertion; however, the SRQ line does not change
state until the interface passes control.
HPIB_PASS_CONTROL Pass active control of the bus. If the interface
is currently active controller, this request
relinquishes control of the bus, passing it
instead to the device at the bus address in
arg[0]. Passing control should be done with care,
since it is not possible to detect whether the
named device can indeed assume bus control. This
request applies only to raw bus files.
HPIB_GET_CONTROL Become active controller. This request causes the
interface to assert Interface Clear (IFC) and
Remote Enable (REN) as a means of regaining
control of the HP-IB. It applies only to raw bus
files.
Transparent Bus Request
This request allows a user to send direct commands over the HP-IB; it
should be used with care, since improper use might place the bus in an
unusable state.
The transparent bus request takes the following form:
struct hpib_command {
int length;
char buffer[MAX_HPIB_COMMANDS];
} hpib_cmd;
ioctl(fildes, HPIB_COMMAND, &hpib_cmd);
This call transmits length bytes of data in buffer over the HP-IB with
Attention (ATN) asserted. On completion of the request, ATN remains
asserted.
For commands sent through an auto-addressed file, buffer is surrounded
with the appropriate device addressing. What appears on the bus is:
UNL, TALK CIC, LISTEN device, buffer
This differs from the approach toward a raw bus file. For such files,
the buffer is merely placed on the bus with ATN asserted, with no
addressing or unaddressing.
Hewlett-Packard Company - 7 - HP-UX Release 9.0: August 1992
hpib(7) Series 800 Only hpib(7)
Status Requests
These requests are used to obtain information about the general state
of a device or the HP-IB. Their calling sequence is similar to that
of control requests:
struct io_ctl_status hpib_status;
ioctl(fildes, IO_STATUS, &hpib_status);
As with the data structure to control requests, the type field
specifies the type of information requested, while the arg array holds
clarification data. The defined status requests for HP-IB and their
use are described as follows:
HPIB_ADDRESS Return the bus address associated with the file in
arg[0].
HPIB_TIMEOUT Return the interface's timeout in microseconds in
arg[0].
HPIB_WIDTH Return the interface's path width in bits in
arg[0].
HPIB_SPEED Return the interface's data transfer rate in K-
bytes per second in arg[0].
HPIB_READ_PATTERN Return the interface's read termination pattern in
arg[0]; if pattern matching is not enabled, arg[0]
holds a -1.
HPIB_SIGNAL_MASK Return the reason for the last signal. This
request returns a mask in arg[0], with bits set
indicating the reason(s) for the last SIGEMT sent
to the user process. Bit definitions are
identical to those of the corresponding IO_CONTROL
request.
HPIB_LOCK Return lock status. If the device is locked to a
process, return that process ID in arg[0] and the
interface lock count in arg[1]. If the device is
not locked, arg[0] holds a -1.
HPIB_TERM_REASON Return end conditions for the last read from this
device or bus. This request returns a byte in
arg[0], with a mask of reason(s) for the
completion of the last read from the device or raw
bus. Applicable bits are:
TR_COUNT Read requested number of
bytes.
Hewlett-Packard Company - 8 - HP-UX Release 9.0: August 1992
hpib(7) Series 800 Only hpib(7)
TR_MATCH Detected specified match
pattern.
TR_TIMEOUT Timed out.
TR_END Device asserted EOI.
TR_ERROR Detected bus error.
TR_NOTERM No read done since open.
HPIB_PPOLL Conduct a parallel poll. This request returns the
bus response to parallel poll in the least
significant byte of arg[0], with DIO1
corresponding to the least significant bit. The
driver delays at least 100 microseconds before
reading the poll response, thus allowing the use
of HPIB_PPOLL on systems with extended buses.
This request applies to both auto-addressed and
raw bus files.
HPIB_SPOLL Conduct a serial poll. For raw bus files, this
request conducts a serial poll of the device
address in arg[1]; the status byte returned by the
device is available in arg[0]. Auto-addressed
files ignore any address in arg[1], polling
instead the device's predefined address.
HPIB_BUS_STATUS Return the status of the HP-IB. This request,
applicable to both types of files, returns
information related to the current bus state. On
return, arg[0] holds a value with bits set
indicating:
ST_NDAC NDAC is being asserted.
ST_SRQ SRQ is being asserted.
ST_REN Interface is in the
remote state.
ST_ACTIVE_CTLR Interface is active
controller.
ST_SYSTEM_CTLR Interface is system
controller.
ST_TALK Interface is addressed to
talk.
Hewlett-Packard Company - 9 - HP-UX Release 9.0: August 1992
hpib(7) Series 800 Only hpib(7)
ST_LISTEN Interface is addressed to
listen.
ST_TALK_ALWAYS Interface is configured
to talk always.
ST_LISTEN_ALWAYS Interface is configured
to listen always.
HPIB_WAIT_ON_PPOLL Wait (sleep) until a given device responds to
parallel poll. This request blocks the user until
either the user's device responds to parallel poll
(for auto-addressed files) or until any enabled
devices respond (for raw bus files).
For a raw bus file, arg[1] and arg[2] contain
eight-bit masks as defined in the HPIB_SIGNAL_MASK
request. The return value of the request in
arg[0] shows which devices responded to parallel
poll.
For an auto-addressed file, arg[1] specifies the
sense of the particular device's assertion.
Successful completion of the request implies that
the device responded.
HPIB_WAIT_ON_STATUS Wait (sleep) until any of a set of given states is
entered. The event(s) to await are specified by
computing the bitwise inclusive OR of the values
from the list below, and placing the mask in
arg[0]. Applicable bits are:
ST_SRQ Wait until SRQ is
asserted.
ST_ACTIVE_CTLR Wait until user is active
controller.
ST_TALK Wait until user is
addressed to talk.
ST_LISTEN Wait until user is
addressed to listen.
Note that more than one bit can be set, thereby
waiting for any of the events to occur. The
return value in arg[0] is modified to show the
actual event(s) that ended the wait. This is
applicable to raw bus files only.
Hewlett-Packard Company - 10 - HP-UX Release 9.0: August 1992
hpib(7) Series 800 Only hpib(7)
HPIB_INTERFACE_TYPE Return the interface type. This returns one of
two values in arg[0]:
HPIB_INTERFACE The open file is a HP-IB
raw bus file.
HPIB_DEVICE The open file is a HP-IB
auto-addressed file.
Extended Status Request
If the user wants to obtain several status variables in one request,
the following request can be used:
struct io_environment hpib_env;
ioctl(fildes, IO_ENVIRONMENT, &hpib_env);
where the io_environment structure includes the following fields:
int interface_type;
int timeout;
int status;
int term_reason;
int read_pattern;
int signal_mask;
int width;
int speed;
int locking_pid;
Summary of Privilege Requirements
The following table summarizes which ioctl() requests can be performed
under what circumstances (see ioctl(2)). The first three columns
indicate whether the interface must be in the controlling state given
to perform the request. An entry of Y means that the interface must
be in that state, N means that the interface must not be in that
state, and - means that the state is irrelevant. The next two columns
indicate whether the request works for auto-addressed or raw bus
files. The final column indicates whether the request is subject to
blocking while the interface is locked (see HPIB_LOCK).
If an entry is marked with an asterisk (*), check the particular
request for more information.
center, box tab(;); l | c | c | c | c | c | c l | c
| c | c | c | c | c lf4 | cp-1 | cp-1 | cp-1 | cp-1 | cp-1
| cp-1 . ;Non-;Active;System;Auto;Raw;Lock
Request;Ctlr;Ctlr;Ctlr;Addr;Bus;Enforced _ IO_CONTROL
HPIB_TIMEOUT;-;-;-;Y;Y;N HPIB_WIDTH;-;-;-;Y;Y;Y
HPIB_SPEED;-;-;-;N;Y;Y HPIB_EOI;-;-;-;Y;Y;N
HPIB_SYSTEM_CTLR;-;-;-;N;Y;Y
Hewlett-Packard Company - 11 - HP-UX Release 9.0: August 1992
hpib(7) Series 800 Only hpib(7)
HPIB_READ_PATTERN;-;-;-;Y;Y;N HPIB_SIGNAL_MASK;*;*;-;Y;Y;Y
HPIB_LOCK;-;-;-;Y;Y;Y HPIB_ADDRESS;-;-;-;N;Y;Y HPIB_RESET
DEVICE_CLR;N;Y;-;Y;N;Y BUS_CLR;-;-;Y;Y;Y;Y
HW_CLR;-;-;-;N;Y;Y
HPIB_PPOLL_RESP;N;Y;-;Y;Y;Y HPIB_PPOLL_IST;-;-;-;N;Y;Y
HPIB_REN;-;-;Y;Y;Y;Y HPIB_SRQ;-;*;-;N;Y;Y
HPIB_PASS_CONTROL;N;Y;-;N;Y;Y HPIB_GET_CONTROL;-;-;Y;N;Y;Y
HPIB_COMMAND;N;Y;-;Y;Y;Y
IO_STATUS HPIB_ADDRESS;-;-;-;Y;Y;Y HPIB_TIMEOUT;-;-;-;Y;Y;N
HPIB_WIDTH;-;-;-;Y;Y;N HPIB_SPEED;-;-;-;Y;Y;N
HPIB_READ_PATTERN;-;-;-;Y;Y;N
HPIB_SIGNAL_MASK;-;-;-;Y;Y;N HPIB_LOCK;-;-;-;Y;Y;N
HPIB_TERM_REASON;-;-;-;Y;Y;N HPIB_PPOLL;N;Y;-;Y;Y;Y
HPIB_SPOLL;N;Y;-;Y;Y;Y
HPIB_BUS_STATUS;-;-;-;Y;Y;Y HPIB_WAIT_ON_PPOLL;N;Y;-;Y;Y;Y
HPIB_WAIT_ON_STATUS;-;-;-;N;Y;Y HPIB_INTERFACE_TYPE;-;-;-;Y;Y;N
IO_ENVIRONMENT;-;-;-;Y;Y;Y
Default Configuration
The default configuration of any HP-IB file is:
Timeout Infinite
Path Width 8 bits
Transfer Speed 0
EOI Assertion Enabled
Pattern Match Disabled
Enabled Signals None
Locking Unlocked
Termination Reason TR_NOTERM
ERRORS
A -1 return value for a driver request indicates that an error
occurred; errno is set to specify the reason. In addition to errors
defined in open(2), close(2), read(2), write(2), and ioctl(2), a
driver request can fail if any of the following conditions are
encountered:
[EACCES] The interface is not in the active-controller or
system-controller state.
[EACCES] The interface is currently locked by another
process via HPIB_LOCK.
[EACCES] A request to access the file would block and the
O_NDELAY file status flag is set for the file
Hewlett-Packard Company - 12 - HP-UX Release 9.0: August 1992
hpib(7) Series 800 Only hpib(7)
descriptor.
[EINVAL] The request is not applicable to this type of
file. Alternatively, type or arg has an invalid
value.
[EINTR] An interface power failure occurred during the
processing of this request; the device might have
lost state.
[EINTR] A signal was received either while waiting for the
interface to become unlocked, or while waiting for
a HPIB_WAIT_ON_PPOLL or HPIB_WAIT_ON_STATUS
request.
[EIO] An unclassified error occurred.
[EMFILE] The number of simultaneous open() requests on this
interface exceeds the maximum allowed.
[ENXIO] No bus interface is associated with the device
file.
[EPERM] An attempt was made to unlock an interface that
was not locked.
[ERANGE] The interface lock count was exceeded.
[ETIMEDOUT] The transaction did not complete within the
timeout specified.
In addition, the following messages can appear on the system console
as a result of errors:
instr0 unit %d: device adapter failure.
The bus hardware is no longer functioning.
instr0 unit %d: unexpected message (message type = %d, from port %d).
The driver received an unclassifiable
message.
WARNINGS
It is possible to circumvent the bus protection mechanisms afforded by
the auto-addressed and raw bus dichotomy. Specifically, a user of an
auto-addressed file can send commands to any or all devices on the bus
with the HPIB_COMMAND request, if the proper device addressing is done
within the data buffer.
The HPIB_LOCK request should be used with care. Since it provides an
exclusive lock, invoking the HPIB_LOCK blocks access to any system
disk or swap device on the associated bus.
Hewlett-Packard Company - 13 - HP-UX Release 9.0: August 1992
hpib(7) Series 800 Only hpib(7)
Processes that use HPIB_LOCK should clear all locks before exiting.
The driver attempts to clear them if the process terminates
unexpectedly; however, a lock might be left outstanding if the locker
dies after creating new file descriptors (via fork() or dup() that
refer to the same device file (see fork(2) or dup(2)). Ensuring that
all open file descriptors on a given interface are closed remedies the
situation.
By default, some HP-IB peripherals respond to parallel poll on DIOn,
where n has the value of 8 minus the device's bus address. That is, a
device at address 6 can respond on DIO2. Therefore, the results of an
HPIB_PPOLL request can be misleading if some devices are not remotely
configured.
It is impossible to transfer data using a secondary address in a
single driver request.
DEPENDENCIES
HP27110B
The HPIB_SPEED and HPIB_SYSTEM_CTLR requests are not supported; they
are configured by switches on the device adapter.
The HPIB_SRQ request can affect only the RQS bit of the serial poll
response byte; all other bits are masked to zero by the hardware.
AUTHOR
hpib was developed by HP.
FILES
/dev/hpib/*
SEE ALSO
fcntl(5), ioctl(2), signal(2), sigvector(2), specific device
documentation in section (7).
Hewlett-Packard Company - 14 - HP-UX Release 9.0: August 1992