gpio(7) — Series 800 Only

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.

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);

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 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.

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.

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 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.

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 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 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.

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.

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.

[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
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*

Museum

Related Articles