mpqn Special File

Purpose

Provides access to multiprotocol adapters by way of the Multiprotocol Quad Port (MPQP) device handler.

Description

The /dev/mpqn character special file provides access to the MPQP device handler for the purpose of providing access to a synchronous network. The MPQP device handler supports multiple adapters.

Usage Considerations

When accessing the MPQP device handler, the following should be taken into account:

Driver initialization and termination

The device handler may be loaded and unloaded. The handler supports the configuration calls to initialize and terminate itself.

Special file support

Calls other than the open and close subroutine calls are discussed in relation to the mode in which the device handler is operating.

Subroutine Support

The MPQP device handler supports the open, close, read, write, and ioctl subroutines in the following manner:

  • The open and close subroutines

    The device handler supports the /dev/mpqn special file as a character-multiplex special file. The special file must be opened for both reading and writing (O_RDWR). There are no particular considerations for closing the special file. Which special file name is used in an open call depends on how the device is to be opened. Types of special file names are:

    Item Description
    /dev/mpqn Starts the device handler for the selected port.
    /dev/mpqn/D Starts the device handler in Diagnostic mode for the selected port.
  • The read subroutine

    Can take the form of a read, readx, readv, or readvx subroutine call. For this call, the device handler copies the data into the buffer specified by the caller.

  • The write subroutine

    Can take the form of a write, writex, writev, or writevx subroutine call. For this call, the device handler copies the user data into a buffer and transmits the data on the LAN.

  • The ioctl subroutine
    Item Description
    CIO_START Starts a session and registers a network ID.
    CIO_HALT Halts a session and removes a network ID.
    CIO_QUERY Returns the current RAS counter values. These values are defined in the /usr/include/sys/comio.h file.
    CIO_GET_STAT Returns the current adapter and device handler status.
    MP_START_AR Puts the MPQP port into Autoresponse mode.
    MP_STOP_AR Permits the MPQP port to exit Autoresponse mode.
    MP_CHG_PARMS Permits the data link control (DLC) to change certain profile parameters after the MPQP device has been started.
    MP_SET_DELAY Sets the value of NDELAY.

Error Codes

The following error codes may be returned when accessing the device handler through the /dev/mpqn special file:

Item Description
ECHRNG Indicates that the channel number is out of range.
EAGAIN Indicates that the maximum number of direct memory accesses (DMAs) was reached, so that the handler cannot get memory for internal control structures.
EBUSY Indicates one of the following:
  • The port is not in correct state.
  • The port should be configured, but is not opened or started.
  • The port state is not opened for start of an ioctl operation.
  • The port is not started or is not in data-transfer state.
EIO Indicates that the handler could not queue the request to the adapter.
EFAULT Indicates that the cross-memory copy service failed.
EINTR Indicates that the sleep was interrupted by a signal.
EINVAL Indicates one of the following:
  • The port not set up properly.
  • The handler could not set up structures for write.
  • The port is not valid.
  • A select operation was called by a kernel process.
  • The specified physical-link parameter is not valid for that port.
  • The read was called by a kernel process.
ENOMEM Indicates one of the following:
  • No mbuf or mbuf clusters are available.
  • The total data length is more than a page.
  • There is no memory for internal structures.
ENOMSG Indicates that the status-queue pointer is null, and there are no entries.
ENOTREADY Indicates that the port state in define device structure (DDS) is not in Data Transfer mode or that the implicit halt of port failed.
ENXIO Indicates one of the following:
  • The port has not been started successfully.
  • An invalid adapter number was specified.
  • The channel number is illegal.
  • The adapter is already open in Diagnostic mode.
  • The adapter control block (ACB) pointer is null or does not exist.
  • The registration of the interrupt handler failed.
  • The port does not exist or is not in proper state.
  • The adapter number is out of range.

The communication device handler topic defines specific errors returned on each subroutine call.