DRP(7)

NAME
drp - Digi Realport driver

SYNOPSIS

/dev/drpD
    - Daemon control devices

/dev/ttyXN
    - general tty and dialin devices

/dev/prXN
    - transparent print devices

/dev/cuXN
    - modem dialout devices

where:
    D is a number in the range 0-999,
    X is one or two alphanumeric characters, and
    N is a two digit number in the range 01 to 64.

DESCRIPTION
The Digi Realport driver makes the ports on a Digi RealPort-enabled product (such as a Digi Portserver) appear as though they are local tty devices directly attached to the computer. One instance of the Realport daemon drpd(1m) is required for communication with each unit.

The tty devices associated with a given product become enabled when the daemon first establishes communication with it. They remain enabled until the daemon exits.

In the current implementation, up to 1000 units are supported. There are no kernel parameter changes required after initial driver installation; the driver automatically allocates system resources as they are needed.

DEVICES

Each remote unit is represented by one /dev/drpD control device and multiple tty-style devices named /dev/ttyXN, /dev/prXN and /dev/cuXN. The control device suffix is an integer RealPort ID number from 0 to 999. The tty devices are all suffixed with a common one or two character alphanumeric string followed by a two-digit port number from 01 to 64. The alphanumeric substring is assigned by the System Administrator with the drpadmin(1m) command.

The /dev/drpD device is accessed only by the drpd(1m) daemon to send and receive asynchronous serial commands and data to and from its assigned network device. All communications are done on a single TCP connection between the daemon and the unit. This is an exclusive access device and it requires super-user permission to open.

For each physical asynchronous port, there are 3 tty-style devices. These devices all have termio(7) behavior and behave as directly connected tty devices.

The /dev/ttyXN devices are classic modem-controlled tty ports, suitable for user logins from terminals or modems. They block on the open when the port is busy or otherwise unavailable, and when carrier is not present.

The /dev/prXN devices are transparent print devices, designed to send data through a terminal to an attached printer. Data sent to these devices goes out bracketed by printer-on and printer-off sequences. In this mode data directed to the terminal has priority over the printer, and printer data flow is throttled by several ditty(1) settable parameters to improve terminal response.

When both the terminal and printer devices are open, shared port settings, such as baud rate and character format are taken from the terminal device, and automatically duplicated in the printer settings.

When only the printer device is accessed its characteristics are identical to the terminal device. However the printer device may never be used to read input data.

Since both the /dev/ttyXN and /dev/prXN devices have modem behavior appropriate for incoming modem connections, they are both referred to as dialin devices.

The /dev/cuXN devices are classic Berkeley style modem callout devices, also known as dialout devices. They may be opened and operated without carrier, however once carrier is established, a drop in carrier causes a hangup.

These ports open without delay, as though a non-blocking open was requested. If they cannot be opened promptly, the open fails.

Its not possible for a dialin and dialout device to both be open at the same time.

Its recommended that the /dev/ttyXN devices be referenced in /etc/inittab and /etc/ttytab for login operation. If its not convenient to wire DCD to the device, the command ditty forcedcd can be used to artificially force carrier on. The /dev/cuXN devices should be referenced in /usr/lib/uucp/Devices for dialout operation.

TTY HANGUP BEHAVIOR
When tty carrier drops, or when a tty device becomes unavailable due to a hardware or configuration change, all associated open tty devices exhibit hangup behavior.

In this driver, that means a HANGUP signal is sent to all processes attached to the device, and all subsequent open, read, write and ioctl operations fail until the device is closed.

This differs from some CLIST drivers who fail read/write/ioctl operations while carrier is low, but allow them when carrier is restored. However the behavior is fully compatible with all STREAMS based drivers where a HANGUP persists until the final close.

PORT SHARING BEHAVIOR
Unlike conventional local tty devices, Realport devices are shared between the local host, the remote unit, and possibly other hosts on the network. When a port is in other use, its said to be busy. Of course a device can also be busy when its opposite dialin/dialout device is open.

A blocking open to a busy device waits until the device becomes available, as though waiting for carrier. A non-blocking open fails.

DAEMON OPERATION
If an attempt is made to open a tty device before the daemon establishes communication with the RealPort-enabled product, or when communication is interrupted, the open waits as though waiting for carrier.

Once communication is established, a brief wait is still required before any tty device can complete an open. During this time the daemon sends an open request and waits for a response.

If the unit is temporarily unreachable, even a non-blocking open may block for several minutes until either communication is successful or the TCP/IP connection is dropped. During this time an interrupt such as an alarm is effective in terminating the wait.

The System Administrator may choose to configure more ports with drpadmin(1m) than physically exist on the assigned device, possibly with a thought to future expansion. A blocking open to the extra ports waits for the ports to appear (maybe years later) while a non-blocking open fails with a no-such-device error.

Its possible that the TCP/IP connection to a device may drop and be recovered some time later. An open port is unresponsive during the period, and while some in-flight and buffered data may be lost, port settings are always recovered. In most cases active sessions can continue without serious disruption. There is one exception; the remote unit may reassign a port to another use during the disruption so it is busy when communication is restored; the tty then exhibits hangup behavior.

If a unit is power cycled or swapped while a port is open, most applications won't notice the disruption. For example its possible replace a Portserver I with a Portserver II while active sessions are in progress. A hard-wired terminal user in the middle of an edit session would notice his terminal unresponsive for a time; but he would be able to continue editing when the swap was complete.

Modems and other devices that monitor modem signals may not be so tolerant as the user in the example above. Properly configured modems disconnect when DTR drops.

If the number of ports changes during operation, any additional ports which appear become immediately operative, while any ports which vanish become inoperative. Hence its possible to configure getty(1m) logins on nonexistent ports or even nonexistent remote units. The getty processes then wait quietly for the purchasing department. When hardware appears they spawn logins. When hardware vanishes they respawn and go back to their silent vigil.

Some applications change termio(7) settings very frequently. Rather than confirm each such change with the unit in real time, the daemon sends the change to the device and then returns immediately. This practice seldom has any effect on standard applications, but can cause problems with some applications (particularly test programs) which make assumptions about how quickly changes in terminal settings take effect.

When a RealPort daemon is killed, all ports on that unit exhibit hangup behavior, and are unavailable until the daemon is respawned and RealPort communication is restored.

TRANSPARENT PRINT
The transparent print devices are designed so that a terminal user may continue working while data is sent to the printer port of his terminal. To do this the driver:

(1) Gives priority to terminal data. In practice this means that terminal data must be sent ahead of printer data whenever possible.

(2) Sends only small amounts of printer data at a time. Note that a few keystrokes of terminal data arriving after a large block of printer data must wait until the large block has been completely transmitted.

(3) Slows down printer data transmission so the printer need never exercise flow control. Such flow control would also block data to the terminal.

(4) Models the printer's internal input buffer so the print buffer can be filled while the terminal is inactive and drained when it is busy.

Getting this to work in practice requires a few adjustable ditty(1) parameters:

maxcps
    The character-per-second data rate that the printer can sustain in typical use. If this number is set too low, printer speed is decreased. If its set too high, the printer will activate flow control. A value that is 50% to 80% of the printers rated CPS speed generally works well. Printers typically run full speed only on long lines of text; in practice there are carriage controls, spacing, overprinting, font metrics and print quality modes that limit the effective speed.

maxchar
    The maximum number of printer data characters that may be placed in any local or remote buffer ahead of terminal data. To limit the delay to a maximum of 50 milliseconds, a value should be chosen that is no more than 1/200 of the baud rate. For example 9600/200 is 48 characters, and it takes 50 milliseconds to send 48 characters at 9600 baud.

bufsize
    The size of the printer serial buffer used by the printer speed model. If this value is set to 800 characters, the driver will send up to 800 characters to the printer at high speed before throttling back to the maxcps rate above. Setting this parameter too low limits throughput slightly. Setting it too high causes the printer to activate flow control at the start of a printout.

Generally if the printer activates flow control at the start of a printout, bufsize is too large. Otherwise if it activates flow control during a printout, maxcps is too large. If the printer is not activating flow control, but terminal delays are experienced, maxchar is too large.

TERMIO COMPATIBILITY
In most cases, Realport devices appear identical to local tty devices. However there are some exceptions.

The HUPCL flag is ignored. The behavior of DTR after a close is defined by the remote unit's tty device type. See the Portserver (or similar) manual for details.

For reasons of efficiency, the transmission of commands and data to the RealPort-enabled device is asynchronous and the time to (for example) communicate a baud rate change is not tightly bound. Such delays can introduce race conditions in applications (primarily Posix test suites) which rapidly change tty settings.

All terminal delays except for TAB3 are ignored. These delays are not supported directly by the RealPort-enabled devices, and across a network with unpredictable delays its not practical to support them directly in the host computer. Many modern UNIX systems, such as HP-UX, appear to ignore them even with vendor provided hardware. As a practical matter, the mechanical terminals for which these delays were designed have not been manufactured in many years, and appear to survive primarily in dusty basements.

SEE ALSO
ditty(1), drpadmin(1m), drpd(1m)