HPUX gpio[7]
gpio(7) Series 800 Only gpio(7)
NAME
gpio - general-purpose I/O interface
SYNOPSIS
#include <sys/gpio.h>
DESCRIPTION
gpio is a general-purpose I/O interface supporting high-speed parallel
communication with an arbitrary peripheral. It includes sixteen data
lines, two handshake lines for transfer protocol, a peripheral-
controlled interrupt line, and several lines for application-dependent
control and status. This section describes the use of the gpio driver
in the HP-UX system.
Device Attributes
GPIO attributes are classified into two groups: per-open, and per-
interface. File descriptors obtained from separate open(2) requests
have separate per-open attributes; 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-interface.
tab(#), center; l l . Attribute#Driver Request _
timeout#GPIO_TIMEOUT signal mask#GPIO_SIGNAL_MASK lock count#GPIO_LOCK
Transfer Requests
Standard read(2) and write(2) requests are used for data transfer over
gpio.
Control Requests
A user can configure the gpio driver by using ioctl(2) calls:
struct io_ctl_status {
int type;
int arg[3];
} gpio_control;
ioctl(fildes, IO_CONTROL, &gpio_control);
Hewlett-Packard Company - 1 - HP-UX Release 9.0: August 1992
gpio(7) Series 800 Only gpio(7)
In the io_ctl_status structure, the type member specifies the type of
control function required. The arg[] array holds any associated
arguments. The defined values for type and their use are as follows:
GPIO_TIMEOUT Set timeout. If any DMA transaction for this file
takes longer than arg[0] microseconds, it aborts with a
status of ETIMEDOUT returned to the user. This is used
mainly for detecting device failure. A timeout of 0 is
equivalent to an hour for HP 27114A/B interface cards,
and infinity (that is, no transaction times out) for
the HP 28651A interface.
GPIO_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. Widths of 8 and 16 bits are supported.
If the 16-bit data width is selected, the number of
bytes to transfer must be even; otherwise, an error
code of EFAULT is returned to the user.
GPIO_SIGNAL_MASK
Define events that cause a signal to be sent to the
calling process. Each request overwrites the previous
mask for the fildes; thus events can be disabled by
using a zero.
The value of arg[0] defines which events allow the
calling process to receive a signal should an
asynchronous event occur on the gpio. The value of
arg[0] is expected to be an event mask of flags,
constructed by computing the bit-wise OR of the desired
flag values. Currently, only the following flag is
supported:
ST_ARQ2 Signal on assertion of Attention Request
(ARQ) triggered by ATTN line.
When the interrupt mask is enabled and ATTN line is
asserted, the process is sent SIGEMT; therefore, the
user should set up a handler to trap this signal (see
signal(2)). The reason for interrupt can be obtained
via the IO_STATUS request GPIO_SIGNAL_MASK.
To receive multiple interrupts, the interrupt mask must
be re-enabled after each SIGEMT signal.
Refer to GPIO_STS_LINES for an explanation of how
GPIO_SIGNAL_MASK affects the number of status lines on
Hewlett-Packard Company - 2 - HP-UX Release 9.0: August 1992
gpio(7) Series 800 Only gpio(7)
the HP 27114B interface.
Note that for the HP 28651A interface, the user can
enable or disable abortion of the current transaction
by asserting the interrupt line (see the
ABORT_ON_EXT_INT flag of the GPIO_SET_CONFIG command).
GPIO_LOCK Lock or unlock the gpio interface. Setting arg[0] to
LOCK_INTERFACE gives the calling process exclusive
access to the card. The lock is incremental, meaning
that 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 also can 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
attempting to access the interface are blocked until
either the interface becomes unlocked or until the
existing timeout expires (timer is started by the
driver based on the existing timeout value). However,
if the O_NDELAY file status flag is set (see fcntl(5)),
the user request returns immediately with an error.
GPIO_RESET Reset the gpio interface. This request restores the
interface to a known state; arg[0] has the following
value:
HW_CLR For the HP 27114A and HP 27114B, set the
gpio card to its default configuration.
This command alters the control lines,
the transfer counter, EDGE_LOGIC_SENSE,
the handshake mode, the data path, and
the PEND option (refer to section titled
Default Configuration later in this
entry).
For the HP 28651A, the gpio card is set
to its default configuration then
reconfigured to match what the
configuration of the card was prior to
the GPIO_RESET.
Hewlett-Packard Company - 3 - HP-UX Release 9.0: August 1992
gpio(7) Series 800 Only gpio(7)
GPIO_SET_CONFIG
Set up additional parameters for the gpio interface as
specified in arg[0] and arg[1].
The configuration mask in arg[0] is constructed by
computing the bit-wise OR of the flags from the list
below. Since each request overwrites the previous
parameter setting, it is advisable to get the current
settings through an IO_STATUS ioctl GPIO_GET_CONFIG
request.
LOGIC_SENSE_SIZE
For the HP 28651A interface only. This
flag is used to mask out the "logic
sense" flags described below. This is
useful for determining which logic sense
is enabled.
PFLG_LOGIC_SENSE
For the HP 28651A only. Define the
logic sense for PFLG handshake line as
"Ready when PFLG High." Default: "Ready
when PFLG Low."
PCTL_LOGIC_SENSE
For the HP 28651A only. Define the
logic sense for PCTL handshake line as
"Control Set when PCTL High." Default:
"Control Set when PCTL Low."
PDDR_LOGIC_SENSE
For the HP 28651A interface only.
Define the logic sense for PDDR
handshake line as "Out direction when
PDDR High." Default: "Out direction when
PDDR Low."
EDGE_LOGIC_SENSE
Defines which edge of the PFLG input is
used by the HP 27114A and HP 27114B
cards to handshake data.
For the HP 27114A: if EDGE_LOGIC_SENSE
is asserted, the busy-to-ready (falling)
edge of PFLG will trigger data movement.
Otherwise, the ready-to-busy edge of
PFLG will trigger data movement.
Default: the ready-to-busy edge of PFLG
triggers data movement.
Hewlett-Packard Company - 4 - HP-UX Release 9.0: August 1992
gpio(7) Series 800 Only gpio(7)
For the HP 27114B: if EDGE_LOGIC_SENSE
is asserted the busy-to-ready edge of
PFLG will trigger data movement while in
the FIFO handshake mode; the low level
of PFLG will trigger data movement if in
either of the FULL handshake modes. If
EDGE_LOGIC_SENSE is not asserted in the
configuration mask, the ready-to-busy
edge of PFLG trigers data movement if in
the FIFO handshake mode; the high level
of PFLG will trigger data movement if in
either of the FULL handshake modes.
Default: the ready-to-busy edge of PFLG
triggers data movement.
The HP 28651A does not support this
option.
The following handshake modes are available for the
driver and the peripheral:
HANDSHAKE_MODE_SIZE
For the HP 28651A only. This flag masks
out the handshake mode bits. This is
useful for determining which handshake
mode is enabled.
FULL_HANDSHAKE_MODE
For the HP 28651A only. This
configuration mask selects the Full
handshake mode, which allows peripherals
to indicate a state of readiness. This
is the default mode.
PULSE_HANDSHAKE_MODE
For the HP 28651A only. This
configuration mask selects the Pulse
handshake mode.
STROBE_HANDSHAKE_MODE
For the HP 28651A only. This
configuration mask selects the Strobe
handshake mode.
SLAVE_HANDSHAKE_MODE
For the HP 28651A only. This
configuration mask selects the Slave
handshake mode.
FIFO_MASTER For the HP 27114B only. This flag
selects the FIFO_MASTER' handshake, also
Hewlett-Packard Company - 5 - HP-UX Release 9.0: August 1992
gpio(7) Series 800 Only gpio(7)
known as a "pulsed" handshake. This is
the same handshake used by the HP
27114A. Default: FIFO_MASTER is
asserted.
FULL_MASTER For the HP 27114B only. This flag
selects the FULL_MASTER handshake. This
handshake is useful when using gpio-to-
gpio links.
FULL_SLAVE For the HP 27114B. This flag selects
the FULL_SLAVE handshake. This
handshake is useful when using gpio-to-
gpio links.
The HP 27114A has only one handshake, the FIFO_MASTER
handshake.
The following flags define the settings available for
the clock source bits:
DIN_CLK_SIZE For the HP 28651A only. This flag is
used to mask out the clock source bits
used for latching the input data.
DIN_CLK_PFLG_BUSY_TO_READY
For the HP 28651A only. This
configuration mask selects the PFLG
busy-to-ready transition for latching
the input data. This is the default
mode.
DIN_CLK_PFLG_READY_TO_BUSY
For the HP 28651A only. This
configuration mask selects the PFLG
ready-to-busy transition for latching
the input data.
DIN_CLK_PCTL_SET_TO_CLEAR
For the HP 28651A only. This
configuration mask selects the PCTL
set-to-clear transition for latching the
input data.
DIN_CLK_PCTL_CLEAR_TO_SET
For the HP 28651A only. This
configuration mask selects the PCTL
clear-to-set transition for latching the
input data.
Hewlett-Packard Company - 6 - HP-UX Release 9.0: August 1992
gpio(7) Series 800 Only gpio(7)
DIN_CLK_READ_OF_LO_BYTE
For the HP 28651A only. This
configuration mask latches the input
data whenever the low byte of the input
register is read.
DIN_CLK_READ_OF_HI_BYTE
For the HP 28651A only. This
configuration mask latches the input
data whenever the high byte of the input
register is read.
TRNSFR_CTR_EN For the HP 27114B only. If the
configuration mask asserts the
TRNSFR_CTR_EN flag, the HP 27114B will
stop handshaking when the transfer
counter becomes zero. This is unlike
the HP 27114A which, during input
transfers, continues to handshake data
onto the card (up to another 66 words of
data) if the peripheral supplies the
data. Note: if the transfer counter is
not enabled during writes where PEND is
asserted, the number of bytes transfered
is unknown. Default: the transfer
counter is disabled.
PDIR_OPT_EN For the HP 27114B only. Whenever the
PDIR_OPT_EN flag is asserted, the CTL5
line reflects the DIR output and the
CTL4 line reflects the HEND output. If
the PDIR_OPT_EN flag is not asserted the
CTL5 line reflects the sixth control
bit, CTL5, and the CTL4 line reflects
the fifth control bit, CTL4. The
default is PDIR_OPT_EN asserted.
Refer to GPIO_CTL_LINES for an
explanation of how PDIR_OPT_EN affects
the number of control lines of the HP
27114B.
PEND_OPT_EN For the HP 27114B only. When the
PEND_OPT flag is asserted, the assertion
of the PEND input at the frontplane will
terminate the data transfer on the
backplane. Default: PEND_OPT_EN is not
asserted.
Refer to GPIO_STS_LINES for an
explanation of how PEND_OPT_EN affects
Hewlett-Packard Company - 7 - HP-UX Release 9.0: August 1992
gpio(7) Series 800 Only gpio(7)
the number of status lines on the HP
27114B.
ABORT_ON_EXT_INT
For the HP 28651A only. This
configuration mask causes the driver to
abort the current request on external
interrupts. Default: request not
aborted.
The value of arg[1] is valid for the HP 28651A only.
The parameter in arg[1] sets a delay to allow data to
settle. The delay set in this parameter postpones
assertion of PCTL or reception of PFLG by the specified
nano-seconds(nsec). The range for the delay is 125-
2000 nsec and the default value is 2000 nsec.
The HP 27114B allows a PCTL/PFLG delay to be set via
hardware jumpers (refer to the HP 27114B Hardware
Reference Manual).
GPIO_CTL_LINES
This control function allows the user to set or
clear the gpio control lines. The arg[0] is an
integer mask mapped onto the control lines, with
the least significant bit corresponding to control
line 0 (CTL0); every set bit asserts its
associated control line.
Three control lines are available to the user on
the HP 27114A: CTL0-CTL2.
Up to six control lines are available on the HP
27114B. Four of these control lines, CTL0-CTL3,
are always available. The fifth and sixth control
lines, CTL4 and CTL5, are multiplexed at the
frontplane to reflect either the outputs from the
HEND and DIR bits, or the outputs from the CTL4
and CTL5 bits. The multiplexing is defined by the
assertion/deassertion of the PDIR_OPT_EN flag in
arg[0] of GPIO_SET_CONFIG.
The default state of the CTL5 line reflects the
DIR output. The default state of the CTL4 line
reflects the HEND output. Whenever the
PDIR_OPT_EN flag is asserted this is the
frontplane configuration for the CTL5 and CTL4
line outputs.
To enable the sixth control line to reflect the
sixth control bit, CTL5, and the fifth control
Hewlett-Packard Company - 8 - HP-UX Release 9.0: August 1992
gpio(7) Series 800 Only gpio(7)
line, CTL4, to reflect the fifth control bit, the
PDIR_OPT_EN flag must be deasserted. See
GPIO_SET_CONFIG.
There are five control lines on the HP 28651A.
Status Requests
These requests are used to obtain information about the state of a
device or the gpio in general. They use a calling sequence similar to
that of control requests:
struct io_ctl_status {
int type;
int arg[3];
} gpio_status;
ioctl (fildes, IO_STATUS, &gpio_status);
The type member specifies the type of information to return in the
arg[] array. The following values for type are supported by gpio:
GPIO_TIMEOUT Return the interface's timeout in microseconds in
arg[0]. Zero is returned when the timeout is infinite.
GPIO_WIDTH Return the interface's path width in bits in arg[0].
GPIO_SIGNAL_MASK
Return the reason for the last interrupt in arg[0].
The mask returned has bits set to indicate the
reason(s) for the last SIGEMT. Bit definitions are the
same as the corresponding IO_CONTROL request bits.
GPIO_LOCK 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] contains
-1.
GPIO_GET_CONFIG
Return to the user the configuration parameters
specified in the GPIO_SET_CONFIG for IO_CONTROL. The
value of arg[0] is the configuration mask described
above and arg[1] is the handshake delay value in nano-
seconds.
GPIO_STS_LINES This status function gives the user access to the gpio
status lines. The value of arg[0] is an integer mask
similar to that of GPIO_CTL_LINES, with the state of
status line 0 (STS0) being returned in the least-
significant bit. GPIO_STS_LINES returns only the state
of those lines; they cannot be set programmatically.
Hewlett-Packard Company - 9 - HP-UX Release 9.0: August 1992
gpio(7) Series 800 Only gpio(7)
Two status lines are available to the user on the HP
27114A.
Up to six status lines are available on the HP 27114B.
Four of these status lines, STS0-STS3, are always
available. The fifth status line, STS4, is multiplexed
between the PEND circuit and the STS4 bit. The default
state for the fifth status line sends input to the PEND
circuit, eventhough the PEND option is disabled. To
enable the fifth status line for input to the STS4 bit,
the PEND option must be disabled (see control request
GPIO_SIGNAL_MASK). The sixth status line, STS5, is
multiplexed between the attention interrupt circuit,
ATTN, and the STS5 bit. The default state for the
sixth status line sends input to the ATTN circuit,
eventhough the card is not enabled to generate
interrupts. To enable the sixth status line for input
to the STS5 bit, interrupts (ARQs) must be disabled
(see control request GPIO_SIGNAL_MASK).
Five status lines are available to the user on the HP
28651A.
GPIO_INTERFACE_TYPE
Return the type of interface in arg[0]. This is a 32-
bit value as follows:
For the HP 27114A card: (left to right)
bits 0-15 0
bits 16-19 0
bit 20 parity
bits 21-23 card revision number
bits 24-31 card ID
For the HP 27114B card: (left to right)
bits 0-15 0
bits 16-23 card revision number
bits 24-31 card ID
For the HP 28651A card: (left to right)
bits 0-15 GPIO1_INTERFACE
bits 16-19 card revision number
bits 20-31 card ID
The HP 27114A card will have a revision number of 0 or
1.
The HP 27114B card will have a revision number of 2 or
greater.
Hewlett-Packard Company - 10 - HP-UX Release 9.0: August 1992
gpio(7) Series 800 Only gpio(7)
Extended Status Request
To obtain several status variables in one request, the following
request can be made:
struct io_environment gpio_env;
ioctl(fildes, IO_ENVIRONMENT, &gpio_env);
where the io_environment structure includes the following members:
int interface_type;
int timeout;
int status;
int signal_mask;
int width;
int locking_pid;
unsigned int config_mask;
unsigned short delay;
Default Configuration
The default configuration of any gpio interface is:
Timeout one hour (infinite on the HP 28651A)
Path Width 16 bits (8 bits on the HP 28651A)
Interrupts disabled
Locking unlocked
User control lines all zero (set on the HP 28651A)
Additional defaults to the HP 27114B interface are:
PEND Disabled
Transfer Counter Disabled
Edge_logic_sense not asserted; the ready-to-busy edge of PFLG
triggers data movement. This is the same for
the HP 27114A.
Handshake mode FIFO_MASTER
Data path empty; the value of the data lines is unknown
ERRORS
A -1 return value for a driver request indicates that an error
occurred; errno is set to indicate 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 is true:
[EACCES] The access to the specific device file cannot be
granted without the proper minor number.
[EACCES] The interface is currently locked via GPIO_LOCK.
[EFAULT] I/O request specified odd byte count or odd address on
16-bits GPIO data-width mode.
Hewlett-Packard Company - 11 - HP-UX Release 9.0: August 1992
gpio(7) Series 800 Only gpio(7)
[EINTR] An interface power failure occurred during the
processing of this request; the device might have lost
state.
[EINVAL] An attempt was made to unlock an interface that was not
locked.
[EINVAL] Invalid command or parameter.
[EIO] Some unclassified error occurred.
[EMFILE] The maximum number of simultaneous opens on this
interface exceeded.
[ENXIO] There is no bus interface associated with the device
file.
[EPERM] An attempt is made to unlock when lock is not owned by
this user.
[ERANGE] The interface lock count limit exceeded.
[ETIMEDOUT] The transaction did not complete within the timeout
specified.
WARNINGS
Processes that use GPIO_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(2) or dup(2)) that
refer to the same device file. Ensuring that all open file descriptors
on that interface are closed remedies the situation.
DEPENDENCIES
Series 800
Note that this interface applies to both the HP 27114A/B (CIO
AFIs) and HP 28651A (HP-PB) cards which have very dissimilar
hardware features. gpio provides as consistent an interface as
possible across all these cards, but there are still significant
differences. Because of this, users of this interface should
consult the appropriate hardware documentation and read carefully
the hardware-specific information given in this manual entry in
the following ioctl command definitions:
GPIO_RESET
GPIO_SIGNAL_MASK
GPIO_SET_CONFIG
GPIO_CTL_LINES
GPIO_STS_LINES
GPIO_GET_CONFIG
Hewlett-Packard Company - 12 - HP-UX Release 9.0: August 1992
gpio(7) Series 800 Only gpio(7)
GPIO_INTERFACE_TYPE
Path Width under Default Configuration
Links from HP 27114A to HP 27114A are not supported. Links from HP
27114A to HP 28651A are supported only when the HP 28651A is
configured as slave. Links from the HP 27114A to the HP 27114B are
supported only when the HP 27114B is configured as slave.
AUTHOR
gpio was developed by HP.
FILES
/dev/gpio*
SEE ALSO
ioctl(2), signal(2), particular device documentation.
Hewlett-Packard Company - 13 - HP-UX Release 9.0: August 1992