NAME

mvme332xt − MVME332XT communication controller STREAMS driver

DESCRIPTION

mvme332xt is a STREAMS-based driver that provides a general interface to the MVME332XT VMEbus communication controller module.  The MVME332XT controller supports up to eight asynchronous serial communication ports and one Centronics-compatible printer port.  The mvme332xt driver supports up to eight MVME332XT controllers per system when the mvme332xt package has been installed. 

Each peripheral device connected to the MVME332XT has the same major device number.  The MVME332XT firmware presents a generic serial and printer device interface to the driver, which distinguishes a serial device from the printer device by its device unit number.  Device numbers 0-7 are allocated for the eight serial devices, and the printer is designated unit 8.  The least significant 4 bits in the minor device field are interpreted as the device unit number.  Therefore, 16 minor device numbers are required per MVME332XT controller.  The next four bits of the minor device number are interpreted as the controller number. 

When the mvme332xt driver is used with the STREAMS line discipline module ­ldterm(7), behavior on all communications ports is as described in UNIX System V/68 or V/88 Release 4 ­termio(7).  This is the default condition for sessions begun by ttymon(1M). 

If BSD/XENIX/V7 compatibility is required for a port, then the user must push the ­ttcompat(7) module onto the stream containing the MVME332XT driver.  This can be done either interactively by using the command strchg(1), or by modifying the autopush(1M) files for the MVME332XT controllers.  Each controller has an autopush file called /etc/m332.x.ap, where x is the controller number.  The autopush file(s) by default apply to all ports on a controller.  This can be changed by editing the autopush file(s). 

MVME332XT IOCTLS

In addition to supporting the standard ioctl(2) commands as specified by termio(7), mvme332xt supports hardware flow control and the downloading of object code and data to the MVME332XT via MVME332XT-specific ioctl system calls.  The optional ioctl system calls specified by termiox(7) are not supported. 

The following MVME332XT-specific ioctl system calls have the form:

ioctl(fildes, command, arg)
int fildes, command;
struct dl_info ∗arg;

The dl_info structure is defined in /usr/include/sys/mvme332xt.h and has the following format:

TCGETDL
Get download information from the MVME332XT. arg is a pointer to a user buffer large enough to contain a dl_info structure.  The base address of the downloadable area is returned in the ipcaddr field of this structure, and the size in bytes of the downloadable area is returned in the count field. 

TCDLOAD
Download object code or data to the MVME332XT. arg is a pointer to a user buffer containing a dl_info structure.  The hostaddr field points to a user buffer containing the object code or data to be downloaded.  The ipcaddr field points to the base address of the downloadable area in MVME332XT local RAM.  The count field specifies the number of bytes to be downloaded. 

TCGETSYM
Get symbol table from the MVME332XT. arg is a pointer to a user buffer containing a dl_info structure.  The hostaddr field points to a user buffer into which the symbol information will be copied.  The size of this buffer in bytes is specified by the count field.  The ipcaddr field should be set to 0 for the first call to TCGETSYM to indicate the beginning of the symbol table.  It is updated by the MVME332XT for subsequent TCGETSYM commands.  At the end of the symbol table, the MVME332XT returns EOF in the ipcaddr field.  On completion, the count field specifies the number of bytes returned by the MVME332XT. 

TCWHAT
This command performs exactly the same function as the TCGETSYM command, except that it returns a list of the firmware files with SCCS version numbers.  arg is a pointer to a user buffer containing a dl_info structure.  The hostaddr field points to a user buffer into which the SCCS information will be copied.  The size of this buffer in bytes is specified by the count field.  The ipcaddr field should be set to 0 for the first call to indicate the start of the TCWHAT command.  It is updated by the MVME332XT for subsequent TCWHAT commands.  At the end of the SCCS information, the MVME332XT returns EOF in the ipcaddr field.  On completion, the count field specifies the number of bytes returned by the MVME332XT. 

TCLINE
Load line discipline table, previously downloaded by TCDLOAD, into the MVME332XT’s internal table.  arg points to a user buffer containing a dl_info structure.  The ipcaddr field points to a user buffer containing the linesw table.  The count field specifies the number of lines in the linesw table.  The MVME332XT linesw table is defined as follows:

TCEXEC
Execute a user function that has been downloaded by a previous TCDLOAD command.  arg points to a user buffer containing a dl_info structure.  The ipcaddr field specifies the execution function address. 

The following MVME332XT-specific ioctl system call has the form:

ioctl(fildes, command, arg)
int fildes, command;
int arg;

TCSETHW
Set hardware flow control option. If arg is 1, enable hardware flow control using the RTS/CTS signal pairs; if arg is 0, disable hardware flow control. 

The following MVME332XT-specific ioctl system calls have the form:

ioctl(fildes, command, arg)
int fildes, command;
int ∗arg;

TCGETHW
Return hardware flow control status. If the specified serial port has hardware flow control enabled, 1 is returned to the arg integer location; otherwise, 0 is returned. 

TCGETVR
Return MVME332XT firmware and driver version and revision numbers in the integer pointed to by arg.  The driver version number is returned in the most significant byte, the driver revision number is in the second most significant byte, the firmware revision number is in the third byte, and the firmware revision number is in the least significant byte. 

TCGETDS
Return the current status of a device’s hardware signals, such as DCD, CTS, DSR, PR_FAULT, PR_POUT and PR_SELECT, in the integer pointed to by arg.  The following status values are defined in /usr/include/sys/mvme332xt.h:

E_DCD, E_LOST_DCD
E_DSR, E_LOST_DSR
E_CTS, E_LOST_CTS
E_PR_FAULT, E_PR_POUT, E_PR_SELECT

The following MVME332XT-specific ioctl system calls have the form:

ioctl(fildes, command, arg)
int fildes, command;
struct termios ∗arg;

TCSETDF
Set the default termios parameters.  arg is a pointer to a user-supplied termios structure. 

TCGETDF
Get the default termios parameters.  arg is a pointer to a user buffer large enough to contain a termios structure. 

CONFIGURATION ISSUES

Currently, the MVME332XT operates in a canonical state which handles only the most basic of features (breaks and interrupts).  Remaining functionality is left to the ldterm(7) module.  The ldterm(7) module may be pushed on the stream via autopush(1M) or when beginning a ttymon(1M) directly from the /etc/inittab file.  [See init(1M)]. 

The master.d file, /etc/master.d/mvme332xt, contains tunable parameters for the default board line discipline and vmin/vtime values.  The only way to change the default board line discipline is to edit this file, then run mkboot(1M) and then reboot the system. 

PRINTER ISSUES

Some printers use the DCD (Data Carrier Detect) signal to indicate off-line/on-line transitions.  When the printer is put off-line, the DCD signal is dropped.  If the port is not set up as a local line (CLOCAL not set in the termio c_cflags field), this will cause a hang-up on the stream, causing all further I/O attempts to fail.  When this happens, the only recourse is to close and re-open the port. 

If the port is set up as a local line, the DCD signal is ignored, and the printer can be put off-line without disrupting the stream.  However, the printer must be on-line when the new termio(7) settings (turning on the CLOCAL flag) are sent to the driver (CLOCAL is not set by default).  The on-line condition corresponds to the E_PR_SELECT hardware signal that can be queried via the TCGETDS ioctl. 

If the printer is off-line when CLOCAL is first set, the device driver will never see the on-line event, and will never send any data to the board. 

Note that if neither O_NDELAY nor O_NONBLOCK is used when the port is first opened, the open will block until the printer is on-line. 

BOOT TIME DIAGNOSTICS

The Software Discernible Field Replaceable Unit (SDFRU) is one MVME332xt board. 

Normal, Quick and Comprehensive diagnostic boot modes are the same. 

Diagnostic output verbosity mode of DV_OFF produces no output. 

Diagnostic output verbosity mode of DV_LEVEL1 produces the following phase messages for each SDFRU:

1. memory test of controller
2. checking results of confidence tests
3. test of bpp initialization
4. copy of port information to controller
5. initialization of firmware
6. copying download to board
7. testing execution of download

Each of these phases will pass or fail depending on the results of the tests ran within the phase.  A failed status means replacement of the SDFRU may be necessary. 

Diagnostic output verbosity mode of DV_LEVEL2 produces printing of information of individual tests within the above phases. 

Diagnostic output verbosity mode of DV_LEVEL3 produces no additional information. 

D_FRU_STATUS

A D_FRU_STATUS call to driverinfo(D2DK) will return information about the SDFRU. Along with the standard information, see driverinfo(D2DK), additional information about the SDFRU board firmware revision and fatal/non-fatal test results from the confidence tests is returned.  A non-zero non-fatal result is not serious and can be ignored. 

FILES

/usr/include/sys/mvme332xt.h
/dev/term/??, /dev/printer/lp?, /dev/port/m332_c?d?
/dev/edt/mvme332xt_c?
/etc/m332.?.ap
/etc/master.d/mvme332xt

ERRORS

Error numbers returned in errno are standard except for the ENOSPC error which may be returned on an open if no free Buffered Pipe Protocol envelopes can be gotten to send an OPEN command to the MVME332XT controller. 

The mvme332xt driver generates error messages which are displayed on the console in order to help the operator to diagnose problems.  The error messages displayed on the console have the following format:

MVME332xt: controller X, unit Y - MESSAGE

where X is the controller number, Y is the unit number, and MESSAGE is one of the following:

Create channel error - disabled
The driver must establish a communication channel with the MVME332XT before any commands can be dispatched. This error indicates that the channel between the driver and the MVME332XT was not successfully created, and typically indicates a configuration problem or malfunction. The controller is marked as bad by the driver and further access attempts are disallowed.

Initialization error, disabled
An error was reported by the MVME332XT controller when the driver sent an initialization command to it. This condition will result if the driver attempts to size one of the MVME332XT read/write rings to a non-base-2 value.

Unknown interrupt
An interrupt occurred from a MVME332XT controller that was marked nonexistent or bad.

Corrupt envelopes - disabled
This indicates channel corruption in the MVME332XT shared RAM.

PRINTER is de-selected
This message indicates that the printer is de-selected. Check the printer select switch.

PRINTER is out of paper
This indicates that the printer is out of paper. Check the printer paper supply.

PRINTER fault for unknown reason
This indicates a printer error other than the paper out or the de-selected error conditions. Check the printer connections or refer to the printer manufacturer’s user manual.

SEE ALSO

autopush(1M), m332ctl(1M), mvme332xt(1M), ttymon(1M), termio(7), ldterm(7), ttcompat(7), driverinfo(D2DK).