HP 9000 Series 300 Operation instructions

Device I/O and User Interfacing
HP-UX Concepts and Tutorials
HP 9000 Series 300/800 Computers
HP Part Number 97089-90057
FliOW HEWLETT
a!e. PACKARD
Hewlett-Packard Company
3404 East Harmony Road, Fort Collins, Colorado 80525

Legal Notices
The information contained in this document is subject to change without notice.
Hewlett-Packard makes no warranty of any kind with regard to this manual,
including, but not limited to, the implied warranties of merchantability and
fitness for a particular purpose. Hewlett-Packard shall not be liable for errors
contained herein or direct, indirect, special, incidental or consequential damages
in connection with the furnishing, performance, or use of this material.
Warranty. A copy of the specific warranty terms applicable to your Hewlett-
Packard product and replacement parts can be obtained from your local Sales
and Service Office.
Copyright © Hewlett-Packard Company, 1989
This document contains information which is protected by copyright. All rights
are reserved. Reproduction, adaptation, or translation without prior written
permission is prohibited, except as allowed under the copyright laws.
Restricted Rights Legend. Use, duplication or disclosure by the U.S. Govern-
ment Department of Defense is subject to restrictions as set forth in para-
graph (b)(3) (ii) of the Rights in Technical Data and Software clause in
FAR 52.227-7013.
Use of this manual and flexible disc(s) or tape cartridge(s) supplied for this pack
is restricted to this product only. Additional copies of the programs can be made
for security and back-up purposes only. Resale of the programs in their present
form
or with alterations, is expressly prohibited.
Copyright © AT&T, Inc. 1980, 1984
Copyright © The Regents of the University of California 1979, 1980, 1983
This software and documentation is based in part on the Fourth Berkeley Software
Distribution under license from the Regents of the University of California.

Printing History
This manual printing date and part number indicate its current edition. The
printing date will change when a new edition is printed. Minor changes may be
made at reprint without changing the printing date. The manual part number
will change when extensive changes are made.
September 1989
... Edition 1. This edition supersedes manual part number
97089-90054. The current edition contains all information previously contained
in the Device I/O and the Curses and Terminfo tutorials. In addition, the
manual reflects the following changes:
• Examples in the Device I/O tutorial have been updated to reflect
changes for
the 7.0 release.
• The Curses and Terminfo tutorial now includes 16-bit character
support.
• The NLS t.utorial has been removed and placed in a separate manual,
HP-UX Native Language Support (97089-90058).
iii

Contents
1.
Interfacing Concepts
Variation Between
Computer Systems .
1-1
Manual Organization 1-2
DIL Interfacing Subroutines 1-3
Linking DIL Routines. 1-3
Calling DIL Routines from Pascal 1-3
Calling DIL Routines from FORTRAN
1-4
General Interface Concepts 1-5
Definition 1-5
Interface Functions 1-6
Handshake I/O . 1-7
Handshake Output 1-7
Handshake Input 1-7
HP-IB Protocol 1-8
The HP -IB Interface 1-9
General Structure 1-9
Handshake Lines 1-10
Bus Management Control Lines 1-13
ATN: The Attention Line 1-14
IFC: The Interface Clear Line 1-14
REN: The Remote Enable Line 1-14
EOI: The End or Identify Line. 1-14
SRQ: The Service Request Line 1-15
The GPIO Interface 1-15
2. General- Purpose Routines
Background Basics 2-2
Interface Special Files . 2-2
Entity Identifiers (eid) 2-2
Contents-1

Programming Model . . . . .
General-
Purpose Routines . . .
Additional Series 300 Routines
Opening Interface Special
Files. .
Closing Interface Special Files . .
Low-Level Read/Write Operations
Example
......... .
Designing Error Checking Routines
The errno Variable . . .
Using errno . . . . . .
The errno.h Header File
Displaying
err no
Error Handlers .
Resetting Interfaces .
Locking
an Interface
Controlling
I/O Parameters
Setting I/O Timeout . .
Setting Data Path Width
Setting Minimum Data Transfer Rate
Setting the Read Termination Pattern
Termination on Byte Count . . . .
Termination on Hardware Condition
Termination on Data Pattern
Disabling a Read Termination Pattern
Determining Why a Read Terminated.
Example ........... .
Interrupts . . . . . . . . . . . . .
Series 300 and 800 Interrupt Support
HP-IB Interrupts
GPIO Interrupts
io_on_interru pt
io_interrupt_ctl
3. Controlling the HP-IB Interface
Overview of HP-IB Commands
UNLISTEN .. .
UNTALK ... .
DEVICE CLEAR
Contents-2
2-2
2-3
2-4
2-4
2-6
2-7
2-9
2-10
2-10
2-10
2-10
2-11
2-12
2-13
2-14
2-15
2-16
2-17
2-19
2-19
2-20
2-20
2-20
2-23
2-24
2-25
2-27
2-27
2-27
2-28
2-28
2-31
3-2
3-4
3-4
3-5

LOCAL LOCKOUT ~5
SERIAL POLL ENABLE 3-5
SERIAL POLL DISABLE 3-5
TRIGGER (Group Execute Trigger) 3-5
SELECTED DEVICE CLEAR. . 3-6
GO TO LOCAL . . . . . . . . 3-6
PARALLEL POLL CONFIGURE 3-6
PARALLEL POLL ENABLE 3-6
PARALLEL
POLL DISABLE . 3-6
Overview of HP-IB DIL Routines. 3-7
Standard DIL Routines . . . 3-7
HP-IB:
The Computer's Role 3-9
Ground Rules . . . . . . 3-9
Available Subroutines versus Controller Role . 3-9
Bus Citizenship: Surviving Multi-Device/Multi-Process
HP-IB . . . . . 3-11
io_lock
and io_ unlock 3-12
io_burst . . . . . . 3-12
hpib_io . . . . . . 3-12
Opening the HP-IB Interface File. 3-13
Sending HP-IB Commands 3-13
Errors While Sending Commands . 3-16
Changing
Parity on Commands 3-17
Active Controller Role
..... 3-17
Determining Active Controller . 3-18
Setting Up Talkers
and Listeners 3-19
Auto-Addressing . . . . . . 3-19
Using hpib_send_cmnd . . . 3-22
Calculating Talk
and Listen Addresses 3-23
An Example Configuration 3-24
Remote Control of Devices 3-
25
Locking Out Local Control 3-25
Enabling Local Control 3-26
Triggering Devices
3- 26
Transferring Data 3-27
Data Output. . 3-27
Data Input 3-29
Clearing
HP -IB Devices 3-30
Contents-3

Responding to Service Requests
Monitoring
the SRQ Line . .
Processing the Service Request
Parallel Polling. . . . . . . .
Configuring Parallel Poll Responses
Disabling Parallel Poll Responses
Conducting a Parallel Poll . . . .
Errors During Parallel Polls . . .
Waiting For a Parallel Poll Response
Calculating
the mask
Calculating
the sense
Example .... .
Serial Polling ... .
Conducting a Serial Poll .
Errors During Serial Poll
Passing Control . . . . .
What If Control Is Not Accepted?
Errors While Passing Control
Controlling the ATN Line . . . . .
Changing the Interface Bus Address
System Controller Role . . . . .
Determining System Controller .
System Controller's Duties
hpib_abort ....... .
hpib_ren_ctl . . . . . . . .
Errors During hpib_abort and hpib_ren_ctl
The Computer As a Non-Active Controller
Checking Controller
Status
Requesting Service . . . . . . .
Errors While Requesting Service
Responding to Parallel Polls . . .
Calculating
the Response . . .
Limitations of hpib_card_ppolLresp
Error Conditions . . . . . .
hpib_ppolLresp_ctl. . . . .
Disabling Parallel-Poll Response
Accepting Active Control . . .
Errors While Waiting on
Status
Contents-4
3-31
3-31
3-33
3-34
3-35
3-39
3-39
3-41
3-42
3-42
3-43
3-44
3-46
3-46
3-48
3-49
3-49
3-50
3-51
3-51
3-52
3-52
3-54
3-54
3-55
3-55
3-57
3-57
3-58
3-60
3-61
3-62
3-62
3-63
3-63
3-64
3-65
3-66

Determining When You Are Addressed . . . . . . .
Combining
I/O Operations into a Single Subroutine Call
Iodetail: The I/O Operation Template
The Mode Component
The Terminator Component
The Count Component
The Buf Component
Allocating Space . . . .
Example ...... .
Locating Errors in Buffered I/O Operations
4. Controlling the GPIO Interface
Interface Configuration . . .
Creating the GPIO Interface File
Interface Control Limitations
Using DIL Subroutines . . .
Resetting
the Interface
Performing Data Transfers.
Using Status and Control Lines
Driving CTLO
and CTLI
Reading STIO and STll . .
Controlling Data Path Width
Controlling Transfer Speed
GPIO Timeouts
Burst Transfers
Read Terminations . . . .
Determining Why a Read Operation Terminated
Specifying a Read Termination
Pattern
Interrupts . . . . . . . . . . . . . . . . . .
A. Series 300 Dependencies
Location of
the DIL Subroutines
Linking DIL Subroutines
The GPIO Interface
Data Lines .. ...
Handshake Lines . . .
Special-
Purpose Lines .
Data Handshake Methods
3-67
3-72
3-73
3-73
3-75
3-75
3-76
3-76
3-77
3-79
4-1
4-1
4-2
4-2
4-3
4-4
4-5
4-5
4-6
4-7
4-8
4-8
4-9
4-9
4-9
4-9
4-9
A-I
A-2
A-2
A-2
A-2
A-3
A-3
Contents-5

Data- In Clock Source . . . . .
Creating
the Interface Special File
Creating
the Special File
pathname ..
major_number . . . .
minor_number . . . .
Creating
an HP-IB Interface File
Creating a
GPIO Interface File.
Effects of Resetting (via io_reset) . .
Entity Identifiers . . . . . . . . .
Restrictions Using
the DIL Subroutines
hpib_send_cmnd
hpib_status
io_reset . . .
io_speed_ctl .
io_timeout_ctl
Performance Tips
B. Series 800 Dependencies
Compiling Programs That Use DIL
Accessing
the Interface Special Files
Major Numbers . . . . . . . .
Minor Numbers
and Logical Unit Numbers
Listing Special Files
......... .
Naming Conventions for Interface Special Files
Creating Interface Special
Files. .
Hardware Effects on DIL Routines
hpib_rqst_srvce . . . . . . .
hpib_io
.......... .
hpib_atn_ctl, hpib-address_ctl, hpih_parity_ctl .
io_eoLctl .
io_reset . . .
io_speed_ctl .
io_timeout_ctl
io_width_ctl .
Return Values for Special Error Conditions
DIL
Support of HP-IB Auto-Addressed Files.
hpib_card_ppolLresp . . . . . . . . . .
Contents-6
A-3
A-4
A-4
A-4
A-4
A-5
A-5
A-6
A-7
A-7
A-7
A-7
A-8
A-8
A-8
A-8
A-9
B-1
B-2
B-2
B-2
B-3
B-4
B-5
B-6
B-6
B-6
B-6
B-6
B-7
B-7
B-7
B-7
B-8
B-8
B-10

hpib_io . . . .
hpib_ren_ctl . .
hpib_send_cmd
hpib_spoll . . .
hpib_wait_on_ppoll
io_on_interrupt
Performance
Tips
Process Locking
Setting Real-Time
Priority
Preallocating Disc Space
Reducing
System Call Overhead
Setting Up Faster Data Transfers .
C. ASCII Character Codes
D. DIL Programming Example
B-10
B-10
B-10
B-10
B-11
B-11
B-12
B-12
B-12
B-13
B-14
B-14
Contents-7

1
Interfacing Concepts
This tutorial explains how to access arbitrary I/O devices from HP-UX
through HP-IB (Hewlett-Packard Interface Bus) and GPIO (General-Purpose
I/O) interfaces by using subroutines contained in the HP-UX Device I/O
Library (DIL). Topics discussed include general I/O programming strategies, as
well as strategies related specifically to HP-IB and GPIO interfaces.
It is assumed that communication with I/O devices is handled through calls to
DIL subroutines from C, Pascal, or FORTRAN programs. Examples shown
in this tutorial are written in C, but the techniques illustrated are easily
converted for use with Pascal or FORTRAN by adding a little extra code.
Variation Between Computer Systems
In general, DIL subroutines function identically on all HP-UX computers,
regardless of series or model number within a series. However, because of
certain inherent differences between processors and other hardware, some
differences do exist.
If such differences arise during an explanation, they are
clearly identified.
Additional major differences related
to a specific model or series are identified
in a separate appendix for that series. Separate appendices are provided for
Series 300
and 800.
Interfacing Concepts 1-1

Manual Organization
Chapter 1: Interfacing Concepts presents basic I/O programming concepts and
a description of the HP-IB and GPIO interfaces.
Chapter 2: General-Purpose Routines discusses how to access interfaces from
HP-UX environment and how to implement I/O transfers.
Chapter 3: Controlling the HP-IB Interface describes I/O programming
techniques for
the HP-IB interface.
Chapter 4: Controlling the GPIO Interface discusses I/O programming
techniques for
the GPIO interface.
Appendix A: Series 300 Dependencies discusses hardware- and system-
dependent characteristics of DIL subroutines when used
with Series 300
computers. If you are using a Series 300 HP-UX system, check this appendix to
ensure correct use of DIL subroutines.
Appendix B: Series 800 Dependencies is similar to other appendices, but for
Series 800 computers. Use this appendix to ensure the correct use of DIL
subroutines on Series 800 systems.
Appendix C: Character Codes
Appendix D: DIL Programming Example shows a non-trivial example of an
Amigo-protocol HP-IB device driver suitable for driving HP-IB line printers
that support Amigo protocol (commonly used on certain HP-IB disc drives
and line printers). This example program shows good HP-UX programming
practice,
and illustrates a number of other techniques and features such as
parsing a
command with arguments.
1-2 Interfacing Concepts

OIL Interfacing Subroutines
As mentioned previously, Device I/O Library (DIL) subroutines provide
a means for directly accessing peripheral devices through HP-IB and/or
GPIO interfaces connected to your computer system. Some routines are
general-purpose and can be used with any interface supported by the library,
while others provide control of only certain specific HP-IB or GPIO interfaces.
Linking OIL Routines
DIL routines can be called from C, Pascal, or FORTRAN programs. However,
the -I f1.ag must be given when invoking the C, Pascal, or FORTRAN compiler,
cc (1), pc (1), or
fc (1). Otherwise, library subroutines are not automatically
linked with your program. To link DIL subroutines
to a compiled C program,
invoke
the C compiler as follows:
cc program.c -ldvio
Similarly, for a Pascal program, use:
pc program.p -ldvio
and for a FORTRAN program, use:
fc program.f -ldvio
In all three cases, the -I option is passed to the HP-UX linker, causing it to
link any DIL routines called by the program being compiled. To determine
the exact location of DIL library on your HP-UX system, refer to the
corresponding hardware-specific appendix in this tutorial.
Calling OIL Routines from Pascal
You must provide an external declaration for each DIL subroutine called from
a Pascal program.
An external declaration consists of the subroutine heading,
including a formal
parameter list and result type, followed by the Pascal
EXTERNAL directive. For example, the C description of open(2) is:
int open(path. oflag)
char *path;
int of lag;
Interfacing Concepts 1-3

The equivalent external declaration for the same subroutine in a Pascal
program is:
TYPE
PATHNAME = PACKED ARRAY [0 .. 50] OF CHAR;
FUNCTION open
(VAR path: PATHNAME;
of lag: INTEGER):
INTEGER;
EXTERNAL;
Note that the path parameter is a VAR parameter, indicating that the
parameter is passed by reference. This simulates the passing of a pointer,
which is
what open(2) expects. In general, declaring a C routine from Pascal is
straightforward.
Calling OIL Routines from FORTRAN
C and FORTRAN subroutine calls are not compatible because C passes
parameters by value while FORTRAN passes them by reference. This
incompatibility can be easily circumvented by directing the compiler to
generate a call by value through the use of FORTRAN's $ALIAS option. For
example:
$ALIAS close = 'close' (%val)
If the FORTRAN compiler on your system does not support this form of
$ALIAS, the parameter-passing differences can be resolved by writing an
onionskin routine which is a C-language function written for the purpose of
resolving parameter-passing irregularities between C
and other languages.
For example,
to access close(2) through an onionskin routine, use:
$ALIAS close = '_my_io_close'
then write the onionskin routine:
int my_io_close (eid)
1* the compiler will create the external symbol "_my_io_close"
based on the above declaration*/
int *eid;
{
return (close (*eid»;
}
1-4 Interfacing Concepts

General Interface Concepts
The remainder of this chapter discusses interfaces in general and the HP-IB
and GPIO interfaces in particular. This background information is helpful
for understanding system operation, but is not prerequisite to being able to
successfully use DIL routines.
Definition
An interface is a built-in or plug-in electronic subassembly that manages the
transfer of information between the computer and one or more peripheral
devices. It converts electrical signals from the computer to a form that is
compatible with the requirements of the peripheral device and converts signals
from
the peripheral device to a form that can be used by the computer. The
interface also controls information transfer paths and transfer timing such that
data flows in an orderly manner in correct sequence.
HP 9000 computers are equipped with both built-in as well as plug-in
interfaces that can be purchased as standard or optional items. Separate
interface cabling connects the peripheral device(s) to the interface unless the
peripheral device is built into the computer housing. The following functional
block diagram illustrates the functional architecture of a typical interface:
Computer
I/O
Backplane
Connector
Electrical I/O
Level Conversion Device
Circuitry Connector
Interface Logic
and Peripheral
Control
Circuitry Device
Figure 1-1. Interface Functional Diagram
Interfacing Concepts 1-5

Interface Functions
A usable interface must fill the following system requirements:
• Electrical Compatibility: The interface must convert electrical signal
voltages, currents, frequencies,
and timing from the computer to a
form
that is useful to the peripheral device, and vice-versa (unless no
conversions are necessary). It must also provide any special protection
that might be necessary to protect circuitry within the computer or
peripheral from damage due to external effects related to the interface
cable or power source.
• Mechanical Compatibility: The interface must be mechanically
structured so that it is readily connected to both the computer and the
peripheral device. This is usually accomplished by means of an interface
cable
that has appropriate connectors on each end.
• Data Compatibility. Just as two people must speak a common language
before they
can communicate well, the computer and peripheral must
use compatible forms of communication. While in most cases, the
computer operating system and the programmer are responsible for
general data format, communication protocols such as those used
in data communication networks and HP -IB interconnections are
usually managed by the interface card, based upon various signals and
commands from the computer and the peripheral device.
• Timing Compatibility. Peripheral devices within a given system rarely
have identical
data transfer rates and data transfer timing requirements.
They also rarely match the timing and transfer rates in the computer or
other devices in the system. For this reason, one of the most important
functions of the interface is to manage and coordinate the interaction
between the computer and the interface as well as timing between the
interface and peripheral devices by using special timing signals that
are inserted into the data being transferred (most common in data
communication interfaces) or carried on separate control signal lines
(typical for HP-IB and GPIO interfaces). These timing signals are used
to coordinate when a transfer begins and at what rate the information
is handled.
• Processor Overhead Reduction: Another important function of the
interface card is to relieve the computer of low-level tasks, such as
1-6 Interfacing Concepts

performing data transfer handshakes. This distribution of tasks eases
some of
the computer's burden and decreases the otherwise stringent
response-
time requirements of external devices. The actual tasks
performed by each
type of interface card vary widely. The remainder of
this chapter concentrates on the functions of two particular interfaces:
HP-IB and GPIO.
Handshake I/O
Most HP-IB and GPIO interfaces operate by means of handshake transfers
which
operate generally as follows:
Handshake Output
• Computer sets input/output control to output and places first word or
byte on I/O bus to interface.
• Computer asserts peripheral control line to interface to start transfer.
• Interface recognizes asserted control signal from computer and transfers
data to output drivers and interface cable.
• Interface asserts output timing signals to peripheral device and waits
for response.
• Peripheral accepts output timing signals, inputs data from interface
cable,
then returns flag signal indicating data has been accepted.
• Interface recognizes flag and sets flag to computer indicating the
transaction is complete. If the sender and receiver do not agree upon
start time and transfer rate, then the transfer is carried out via a
handshake process: the transfer proceeds one data item at a time with
the receiving device acknowledging that it received the data and that
the sender can transfer the next data item. Both types of transfers are
utilized with different interfaces.
Handshake Input
• Computer sets input/output control to input.
• Computer asserts peripheral control line to interface to start transfer.
Interfacing Concepts 1-7

• Interface recognizes asserted control signal from computer, sends data
input command sequence to peripheral device, and waits for response.
• Peripheral accepts input command sequence, places data on interface
cable,
then returns flag signal indicating data is available.
• Interface recognizes flag, moves data to computer I/O bus, and sets flag
to computer indicating the transaction is complete.
Different interfaces
support variations on this basic sequence. For example,
more sophisticated
data communication and HP-IB cards may be equipped
with a microprocessor and shared memory that is directly accessible to the
computer and the interface processor. The computer moves data to and from
shared memory according to program needs, while the interface processor
performs similar operations
to meet the demands of any data transfers in
progress. Shared pointers
and other flags prevent collisions between conflicting
demands from the two processors, and the increased efficiency of a "smart"
interface greatly reduces the complexity and overhead related to more mundane
approaches to interrupt-driven handshake I/O.
For example, instead of handling each character or word as a single transaction,
the computer can load a block of data into the shared memory then signal the
interface that data is ready for transfer. The interface then uses the shared
pointers or
other means to determine how much data to transfer, handles the
transfer, then signals the computer that the task is complete.
HP-IB Protocol
When a single interface is shared by multiple peripheral devices, additional
signalling
must be used to control which devices respond to each transaction
as in HP-IB interfacing. A selection of protocol signals and device commands
are used to activate or deactivate various devices on the HP-IB bus according
to the needs of the bus controller (controlling interface). This signals, their
functions, and the sequences in which they are used are discussed in greater
detail
throughout this tutorial.
1-8 Interfacing Concepts