CIO_START (Start Device) mpioctl MPQP Device Handler Operation

Purpose

Note: This function is supported in AIX® 5.1 and earlier only.

Starts a session with the Multiprotocol Quad Port (MPQP) device handler.

Description

The CIO_START operation registers a network ID in the network ID table and establishes the physical connection with the MPQP device. Once this start operation completes successfully, the port is ready to transmit and receive data.

Note: The CIO_START operation defines the protocol- and configuration-specific attributes of the selected port. All bits that are not defined must be set to 0 (zero).

For the MPQP CIO_START operation, the extptr parameter points to a t_start_dev structure. This structure contains pointers to the session_blk structure.

The session_blk structure contains the netid and status fields. The t_start_dev device-dependent information for an MPQP device follows the session block. All of these structures can be found in the /usr/include/sys/mpqp.h file.

The CIO_START operation functions with a 4-Port Multiprotocol Interface adapter that has been correctly configured for use on a qualified network. Consult adapter specifications for more information on configuring the adapter and network qualifications.

t_start_dev Fields

The t_start_dev structure contains the following fields:

Field Description
phys_link Indicates the physical link protocol. Only one type of physical link is valid at a time. The six supported values are:
Physical Link
Type
PL_232D
EIA-232D
PL_422A
EIA-422A
PL_V35
V.35
PL_X21
X.21
PL_SMART_MODEM
Hayes EIA232-D autodial protocol
PL_V25
V.25bis EIA-422A autodial protocol
Note: When using the X.21 physical interface, X.21 centralized multiport (multidrop) operation on a leased-circuit public data network is not supported.

If the phys_link field is PL_SMART_MODEM or PL_V25, the dial_proto and dial_flags fields are applicable. Otherwise, these fields are ignored. If no dial protocol or flags are supplied when the PL_SMART_MODEM or PL_V25 link is selected, defaults are used. The defaults for the dial phase for a PL_SMART_MODEM link is an asynchronous protocol at 2400 baud with even parity, 7 bits per character, and 1 stop bit. A PL_V25 link has the same defaults.

dial_proto Identifies the autodial protocol, which communicates with the modem to send information such as dial sequence or register settings. Most modems use an asynchronous protocol during the connect phase of call establishment. If no value is set, the default mode is asynchronous.
Note: The dial_proto field is ignored if the physical link is not an autodial protocol.
data_proto Identifies the possible data protocol selections during the data transfer phase. The data_flags field has different meanings depending on what protocol is selected. The data_proto field accepts the following values:

 

DATA_PRO_BSC
Indicates a bisync protocol.
DATA_PRO_SDLC_FDX
Indicates receivers enabled during transmit.
DATA_PRO_SDLC_HDX
Indicates receivers disabled during transmit.
modem_flags Establishes modem characteristics. This field accepts the following values:
MF_AUTO
Indicates that the call is to be answered or dialed automatically.
MF_CALL
Indicates an outgoing call (switched only).
MF_CDSTL_OFF
Indicates that the data terminal ready (DTR) should be enabled without waiting for ring indicate (RI) to connect data set to line.
MF_CDSTL_ON
Enables DTR after RI occurs. If the data set ready (DSR) goes active prior to RI, DTR is enabled and RI is ignored.
MF_DRS_ON
Enables date rate selected (DRS).
MF_DRS_OFF
Disables DRS (full speed). This is the default.
MF_LEASED
Indicates a leased telephone circuit.
MF_LISTEN
Indicates an incoming call (switched only).
MF_MANUAL
Indicates that the operator answers or dials the call manually.
MF_SWITCHED
Indicates a switched telephone circuit.
Note: The MF_DRS_ON and MF_DRS_OFF modem characteristics are not currently supported. The default is full speed.
poll_addr Identifies the address-compare value for a Binary Synchronous Communication (BSC) polling frame or an Synchronous Data Link Control (SDLC) frame. If using BSC, a value for the selection address must also be provided or the address-compare is not enabled. If a frame is received that does not match the poll address (or select address for BSC), the frame is not passed to the system.
select_addr Specifies a valid select address for BSC only.
modem_int_mask Reserved. This value must be 0.
baud_rate Specifies the baud rate for transmit and receive clock. This field is used for date terminal equipment (DTE) clocking only (that is, when the modem does not supply the clock). Acceptable baud rates range from 150 baud to a maximum speed of 38400 baud. If this field contains a value that does not match one of the following choices, the next lowest baud rate is used:
  • 38400
  • 19200
  • 9600
  • 4800
  • 2400
  • 2000
  • 1200
  • 1050
  • 600
  • 300

A value of 0 indicates the port is to be externally clocked (that is, use modem clocking). The on-board baud rate generator is limited to a speed of 38400. All higher baud rates up to the maximum of 64000 bits must be accomplished with modem clocking. For RS232, the adapter drives a clock signal on the DTE clock. Most modems provide their own clocking.

If the physical link is set to the PL_SMART_MODEM or PL_V25 link, the baud rate is the speed of the dial sequence and modem clocking is used for data transfer.

rcv_timeout Indicates the period of time, expressed in 100-msec units (0.10 sec), used for setting the receive timer. The MPQP device driver starts the receive timer whenever the CIO_START operation completes and a final transmit occurs.

If a receive occurs that is not a receive final frame, the timer is restarted. The timer is stopped when the receive final occurs. If the timer expires before a receive occurs, an error is reported to the logical link control (LLC) protocol. After the CIO_START operation completes, the receive time out value can be changed by the MP_CHANGE_PARAMS operation. A value of zero indicates that a receive timer should not be activated.

Final frames in SDLC are all frames with the poll or final bit set. In BSC, all frames are final frames except intermediate text block (ITB) frames.

rcv_data_offset Reserved
dial_data_length Specifies the length of the dial data. Dial data for Hayes-style dial data can be up to 256 bytes.

Flag Fields for Autodial Protocols

Flag fields in the t_start_dev structure take different values depending on the type of autodial protocol selected.

Data Flags for the BSC Autodial Protocol

If BSC is selected in the data_proto field, either ASCII or EBCDIC character sets can be used. Control characters are stripped automatically on reception. Data link escape (DLE) characters are automatically inserted and deleted in transparent mode. If BSC Address Check mode is selected, values for both poll and select addresses must be supplied. Odd parity is used if ASCII is selected.

The following are the default values:

The data flags for the BSC autodial protocol are:

Data Flag Description
DATA_FLG_RST_TMR Reset receive timer.
DATA_FLG_ADDR_CHK Address-compare select. This causes frames to be filtered by the hardware based on address. Only frames with matching addresses are sent to the system.
DATA_FLG_BSC_ASC ASCII BSC select.
DATA_FLG_C_CARR_ON Continuous carrier (RTS always on).
DATA_FLG_C_CARR_OFF RTS-disabled between transmits (default).

Dial Flags for ASC Protocols

If ASC and the parity enable bit is set, the value for parity select is honored. A value of 0 equals even parity. A value of 1 equals odd parity. If parity enable is set to 0, no parity type is enforced. The following are acceptable ASC dial flags:

ASC Dial Flag Description
DIAL_FLG_PAR_EN Enable parity.
DIAL_FLG_PAR_ODD Odd parity.
DIAL_FLG_STOP_0 0 stop bits.
DIAL_FLG_STOP_1 1 stop bit.
DIAL_FLG_STOP_15 1.5 stop bits.
DIAL_FLG_STOP_2 2 stop bits.
DIAL_FLG_CHAR_5 5 bits per character.
DIAL_FLG_CHAR_6 6 bits per character.
DIAL_FLG_CHAR_7 7 bits per character.
DIAL_FLG_CHAR_8 8 bits per character.
DIAL_FLG_C_CARR_ON Continuous carrier (RTS always on).
DIAL_FLG_C_CARR_OFF RTS disabled between transmits (default).
DIAL_FLG_TX_NO_CTS Transmit without waiting for clear to send (CTS).
DIAL_FLG_TX_CTS Wait for CTS to transmit (default).

Data Flags for the SDLC Protocol

For the Synchronous Data Link Control (SDLC) protocol, the flag for NRZ or NRZI must match the data-encoding method that is used by the remote DTE. If SDLC Address Check mode is selected, the poll address byte must also be specified. The receive timer (RT) is started whenever a final block is transmitted. If RT is set to 1, the receive timer is restarted after expiration. If RT is set to 0, the receive timer is not restarted after expiration. The receive timer value is specified by the 16-bit rcv_time out field. The following are the acceptable SDLC data flags:

SLDC Data Flag Description
DATA_FLG_NRZI NRZI select (default is NRZ).
DATA_FLG_ADDR_CHK Address-compare select.
DATA_FLG_RST_TMR Restart receive timer.
DIAL_FLG_C_CARR_ON Continuous carrier (RTS always on).
DIAL_FLG_C_CARR_OFF RTS disabled between transmits (default).

t_auto_data Fields

The t_auto_data structure contains the following fields that specify aspects of the X.21 call progress signal retry and logging data format:

Field Description
len Length of autodial to be sent to the modem.
sig[] Signals to be sent to the modem data in the form of an array of characters.
connect_timer Time-out value. This value is specified in 0.1 seconds. The adapter should wait for call to complete before reporting a connection failure to the DLC. The default is 30 seconds if no value is set.
v25b_tx_timer Time-out value. This value is specified in 0.1 seconds of delay after driving DTR and before sending dial data in V.25bis modem protocol. If no value is set, a default value of 0.1 seconds is used.

t_x21_data Fields

The t_x21_data structure contains the following fields that specify aspects of the X.21 call progress signal retry and logging data format:

Field Description
selection signal length Contains the length of the data held in the selection-signals portion of the buffer in bytes. Values from 0 to 256 are valid.
selection signals The selection signals are allocated 256 bytes each. Items are stored in the International Alphabet 5 (IA5) format.
retry_cnt Indicates how many attempts at outgoing call establishment must fail before the adapter software returns an error to the driver for the CIO_START operation. Values between 0 and 255 are allowed. This is a 1-byte field.
retry_delay Contains the number of 100-msec (0.1 sec) intervals to wait between successive call retries. This is a 2-byte field.
cps_group There are nine characters-per-second (cps) groups. Each cps group can generate a driver interrupt after a configurable number of errors are detected. Optionally, this interrupt can cause an X.21 network transaction to notify network error-logging monitors of excessive error rates. The netlog bit definitions determine which signals in each group are considered countable.

Retry and Netlog Groups

Specify the retry and netlog fields for a cps-particular group. The bits definitions are as follows:

Call progress signals are divided into groups of 10; for example, cps 43 is group 4, signal 3. To indicate retries for cps 43, the value for signal 3 should be ORed into the retry unsigned short for group 4. Possible values for retry groups are the following:

t_err_threshold Fields

The t_err_threshold structure describes the format for defining thresholds for transmit and receive errors. Counters track the total number of transmit and receive errors. Individual counters track certain types of errors. Thresholds can be set for individual errors, total errors, or a percentage of transmit and receive errors from all frames received.

When a counter reaches its threshold value, a status block is returned by the driver. The status block indicates the type of error counter that reached its threshold. If multiple thresholds are reached at the same time, the first expired threshold in the list is reported as having expired and its counter is reset to 0. The user can issue a CIO_QUERY operation call to retrieve the values of all counters.

If no thresholding is desired, the threshold should be set to 0. A value of 0 indicates that LLC should not be notified of an error at any time. To indicate that the LLC should be notified of every occurrence of an error, the threshold should be set to 1.

The t_err_threshold structure contains the following fields:

Field Description
tx_err_thresh Specifies the threshold for all transmit errors. Transmit errors include transmit underrun, CTS dropped, CTS time out, and transmit failsafe time out.
rx_err_thresh Specifies the threshold for all receive errors. Receive errors include overrun errors, break/abort errors, framing/cyclic redundancy check (CRC)/frame check sequence (FCS) errors, parity errors, bad frame synchronization, and receive-DMA-buffer-not-allocated errors.
tx_err_percent Specifies the percentage of transmit errors that must occur before a status block is sent to the LLC.
rx_err_percent Specifies the percentage of receive errors that must occur before a status block is sent to the LLC.

Execution Environment

The CIO_START operation can be called from the process environment only.

Return Values

Item Description
EBUSY Indicates the port state is not opened for a CIO_START operation.
EFAULT Indicates the cross-memory copy service was unsuccessful.
EINVAL Indicates the physical link parameter is not valid for the port.
EIO Indicates the device handler could not queue command to the adapter.
ENOMEM Indicates no mbuf clusters are available.
ENXIO Indicates the adapter number is out of range.