Document revision date: 30 March 2001

## OpenVMS I/O User's Reference Manual

Previous | Contents | Index

## 8.7 Assigning a Channel to GKDRIVER

On VAX and Alpha systems, an application program assigns a channel to the generic SCSI class driver using the standard call to the $ASSIGN system service, as described in the OpenVMS System Services Reference Manual. The application program specifies a device name and a word to receive the channel number.

## 8.8 Issuing a $QIO Request to the Generic Class Driver

The format of the Queue I/O Request ($QIO) system service that initiates a request to the SCSI generic class driver is as follows. This explanation concentrates on the special elements of a $QIO request to the SCSI generic class driver. For a detailed description of the $QIO system service, refer to the OpenVMS System Services Reference Manual.

VAX MACRO Format

`$QIO [efn] ,chan ,func ,iosb ,[astadr] ,[astprm] ,p1 ,p2 [,p3] [,p4] [,p5] [,p6]`

High-Level Language Format

`SYS$QIO ([efn] ,chan ,func ,iosb ,[astadr] ,[astprm] ,p1 ,p2 [,p3] [,p4] [,p5] [,p6])`

### Arguments

> #### chan

> I/O channel assigned to the device to which the request is directed. The chan argument is a word value containing the number of the channel, as returned by the Assign I/O Channel ($ASSIGN) system service.

> #### func

> Longword value containing the IO$_DIAGNOSE function code. Only the IO$_DIAGNOSE function code is implemented in the generic SCSI class driver.

> #### iosb

> I/O status block. The iosb argument is required in a request to the generic SCSI class driver; it has the following format:

The status code provides the final status indicating the success or failure of the SCSI command. The SCSI status byte contains the status value returned from the target device, as defined in the ANSI SCSI specification. The transfer count field specifies the actual number of bytes transferred during the SCSI bus DATA IN or DATA OUT phase.

#### [efn]
[astadr] [astprm]

These arguments apply to $QIO system service completion. For an explanation of these arguments, refer to the OpenVMS System Services Reference Manual.

#### p1

Address of a generic SCSI descriptor of the following format:

#### p2

Length of the generic SCSI descriptor.

### Descriptor Fields

> #### opcode

> Currently, the only supported opcode is 1, indicating a pass-through function. Other opcode values are reserved for future expansion.

> #### flags

> Bit map having the following format:

Bits in the flags bit map are defined as follows:

Field | Definition
--- | ---
dir | Direction of transfer. If this bit is set, the target is expected at some time to enter the DATA IN phase to send data to the host. To facilitate this, the port driver maps the specified data buffer for write access. If this bit is clear, the target is expected at some time to enter the DATA OUT phase to receive data from the host. To facilitate this, the port driver maps the specified data buffer for read access. The generic SCSI class driver ignores the dir flag if either the SCSI data address or SCSI data length field of the generic SCSI descriptor is zero.
dis | Enable disconnection. If this bit is set, the target device is allowed to disconnect during the execution of the command. If this bit is clear, the target cannot disconnect during the execution of the command. Note that targets that hold on to the bus for long periods of time without disconnecting can adversely affect system performance. See Section 8.5.2 for additional information.
syn | Enable synchronous mode. If this bit is set, the port driver uses synchronous mode for data transfers, if both the host and target allow this mode of operation. If this bit is clear, or synchronous mode is not supported by either the host or target, the port driver uses asynchronous mode for data transfers. See Section 8.5.1 for additional information.
dpr | Disable port retry. If this bit is clear, the port driver retries, up to three times, any command that fails with a timeout, bus parity, or invalid phase transition error. If this bit is set, the port driver does not retry commands for which it detects failure. See Section 8.5.3 for additional information.

#### SCSI command address

Address of a buffer containing a SCSI command.

#### SCSI command length

Length of the SCSI command. The maximum length of the SCSI command is 128 bytes.

#### SCSI data address

Address of a data buffer associated with the SCSI command.

If the dir bit is set in the flags field, data is written into this buffer during the execution of the command. Otherwise, data is read from this buffer and sent to the target device.

If the SCSI command requires no data to be transferred, then the SCSI data address field should be clear.

#### SCSI data length

Length, in bytes, of the data buffer pointed to by the SCSI data address field. The maximum data buffer size is 65,535 bytes.

If the SCSI command requires no data to be transferred, then this field should be clear.

#### SCSI pad length

This field is used to accommodate SCSI device classes that require that the transfer length be specified in terms of a larger data unit than the count of bytes expressed in the SCSI data length field. If the total amount of data requested in the SCSI command does not match that specified in the SCSI data length field, this field must account for the difference.

For example, suppose an application program is using the generic class driver to read the first 2 bytes of a disk block. The length field in the SCSI READ command contains 1 (indicating one logical block, or 512 bytes), while the SCSI data length field contains a 2. The SCSI pad length field must contain the difference, 510 bytes.

For most transfers, this field should contain 0. Failure to initialize the SCSI pad length field properly causes port driver timeouts and SCSI bus resets.

#### phase change timeout

Maximum number of seconds for a target to change the SCSI bus phase or complete a data transfer. A value of 0 causes the SCSI port driver's default phase change timeout value of 4 seconds to be used.

See Section 8.5.4 for additional information.

#### disconnect timeout

Maximum number of seconds for a target to reselect the initiator to proceed with a disconnected I/O transfer. A value of 0 causes the SCSI port driver's default disconnect timeout value of 4 seconds to be used.

See Section 8.5.4 for additional information.

## 8.9 Generic SCSI Class Driver Device Information

A call to the Get Device/Volume Information ($GETDVI) system service returns the following information for any device serviced by the generic SCSI class driver. (Refer to the description of the $GETDVI system service in the OpenVMS System Services Reference Manual.)

$GETDVI returns the following device characteristics when you specify the item code DVI$_DEVCHAR:

DEV$M_AVL | Available device
DEV$M_IDV | Input device
DEV$M_ODV | Output device
DEV$M_SHR | Shareable device
DEV$M_RND | Random-access device

DVI$DEVCLASS returns the device class, which is DC$_MISC; DVI$DEVTYPE returns the device type, which is DT$_GENERIC_SCSI.

## 8.10 Call a Generic SCSI Class Driver

Example 8-1 is an application that uses the generic SCSI class driver to send a SCSI INQUIRY command to a device.

Example 8-1 Generic SCSI Class Driver Call Example

    /*
    GKTEST.C

    This program uses the SCSI generic class driver to send an inquiry command
    to a device on the SCSI bus.

    */

    #include ctype

    /* Define the descriptor used to pass the SCSI information to GKDRIVER */

    #define OPCODE 0
    #define FLAGS 1
    #define COMMAND_ADDRESS 2
    #define COMMAND_LENGTH 3
    #define DATA_ADDRESS 4
    #define DATA_LENGTH 5
    #define PAD_LENGTH 6
    #define PHASE_TIMEOUT 7
    #define DISCONNECT_TIMEOUT 8

    #define FLAGS_READ 1
    #define FLAGS_DISCONNECT 2

    #define GK_EFN 1

    #define SCSI_STATUS_MASK 0X3E

    #define INQUIRY_OPCODE 0x12
    #define INQUIRY_DATA_LENGTH 0x30

    globalvalue
            IO$_DIAGNOSE;

    short
            gk_chan,
            transfer_length;

    int
            i,
            status,
            gk_device_desc[2],
            gk_iosb[2],
            gk_desc[15];

    char
            scsi_status,
            inquiry_command[6] = {INQUIRY_OPCODE, 0, 0, 0, INQUIRY_DATA_LENGTH, 0},
            inquiry_data[INQUIRY_DATA_LENGTH],
            gk_device[] = {"GKA0"};

    main ()
    {

    /* Assign a channel to GKA0 */

            gk_device_desc[0] = 4;
            gk_device_desc[1] = &gk_device[0];
            status = sys$assign (&gk_device_desc[0], &gk_chan, 0, 0);
            if (!(status & 1)) sys$exit (status);

    /* Set up the descriptor with the SCSI information to be sent to the target */

            gk_desc[OPCODE] = 1;
            gk_desc[FLAGS] = FLAGS_READ + FLAGS_DISCONNECT;
            gk_desc[COMMAND_ADDRESS] = &inquiry_command[0];
            gk_desc[COMMAND_LENGTH] = 6;
            gk_desc[DATA_ADDRESS] = &inquiry_data[0];
            gk_desc[DATA_LENGTH] = INQUIRY_DATA_LENGTH;
            gk_desc[PAD_LENGTH] = 0;
            gk_desc[PHASE_TIMEOUT] = 0;
            gk_desc[DISCONNECT_TIMEOUT] = 0;
            for (i=9; i<15; i++) gk_desc[i] = 0;    /* Clear reserved fields */

    /* Issue the QIO to send the inquiry command and receive the inquiry data */

            status = sys$qiow (GK_EFN, gk_chan, IO$_DIAGNOSE, gk_iosb, 0, 0,
                               &gk_desc[0], 15*4, 0, 0, 0, 0);

    /* Check the various returned status values */

            if (!(status & 1)) sys$exit (status);
            if (!(gk_iosb[0] & 1)) sys$exit (gk_iosb[0] & 0xffff);
            scsi_status = (gk_iosb[1] >> 24) & SCSI_STATUS_MASK;
            if (scsi_status) {
                    printf ("Bad SCSI status returned: %02.2x\n", scsi_status);
                    sys$exit (1);
            }

    /* The command succeeded. Display the SCSI data returned from the target */

            transfer_length = gk_iosb[0] >> 16;
            printf ("SCSI inquiry data returned: ");
            for (i=0; i<transfer_length; i++) {
                    if (isprint (inquiry_data[i]))
                            printf ("%c", inquiry_data[i]);
                    else
                            printf (".");
            }
            printf ("\n");
    }

## Chapter 9
Local Area Network (LAN) Device Drivers

This chapter describes the QIO interface of local area network (LAN) drivers that control the LAN devices.

In addition to the QIO interface, the OpenVMS operating system supports another interface into LAN drivers. The VMS Communications Interface (VCI) provides a low overhead, privileged interface.

## 9.1 Local Area Network (LAN) Terminology

The following is a list of terms relevant to local area networks:

- CSMA/CD --- Stands for carrier sense multiple access with collision detection. A technique that mediates demands by nodes on a single shared network channel; carrier sense determines whether the communications medium is already in use, while collision detection detects when more than one node is attempting to transmit.
- Ethernet --- One of the earliest and the most common local area networks (LANs), Ethernet can refer to either a general LAN application (for example, Ethernet address) or to the specific CSMA/CD technology that implements the Intel, Xerox, and Compaq intercompany Ethernet specifications. The data transmission rate is 10Mbps.
- Fast Ethernet ---This protocol is an extension of Ethernet. The data transmission rate is 100Mbps and it uses the same CSMA/CD access method.
- Gigabit Ethernet --- This protocol is an extension of Ethernet and Fast Ethernet. The data transmission rate is 1000 Mbps (1 gigabit/sec). It supports Ethernet and IEEE/802.3 packet formats, and the CSMA/CD access method.
- FDDI --- Fiber Distributed Data Interface is a 100 Mbps token ring LAN technology standardized by the American National Standards Institute (ANSI).
- Token Ring --- This LAN is the IEEE 802.5 standard token passing ring. The data transmission rate is is 4 or 16 Mbps.
- ATM --- Asynchronous transfer mode (ATM) is supported for emulated local area networks (ELANs) and conforms to the standards defined by the ATM Forum's LANE V1.0 specifications. The Classical Internet Protocol (CLIP) over ATM is supported only on the DGLTA, DGLPA, and DGLPB devices and conforms to the standards defined in RFC 1577 specifications.

## 9.2 Supported Communication Devices

Section 9.2.1 and Section 9.2.2 show the communication devices supported on the OpenVMS operating system.

### 9.2.1 OpenVMS VAX Lan Devices

On VAX systems, Table 9-1 lists the supported devices.

Table 9-1 Supported OpenVMS VAX Systems LAN Devices
Medium | Bus | Device | Device Name | DECnet Name | Device Type | Version
--- | --- | --- | --- | --- | --- | ---
CSMA/CD | XMI | DEMNA | EXc0 | MNA | DT$_EX_DEMNA | V5.3
CSMA/CD | Local | SGEC | EZc0 | ISA | DT$_EZ_SGEC | V5.3
CSMA/CD | Local | LANCE | ESc0 | SVA | DT$_ES_LANCE | V4.4
CSMA/CD | TurboChannel | PMAD | ECc0 | MXE | DT$_EC_PMAD | V5.5-2HW
CSMA/CD | TurboChannel | DELTA | ECc0 | MXE | DT$_EC_PMAD | V5.5-2HW
CSMA/CD | QBUS | DESQA | ESc0 | SVA | DT$_ES_LANCE | V5.0
CSMA/CD | QBUS | DELQA | XQc0 | QNA | DT$_XQ_DELOA | V5.0
CSMA/CD | QBUS | DEQTA | XQc0 | QNA | DT$_XQ_DEQTA | V5.3
CSMA/CD | QBUS | DEQNA | XQc0 | QNA | DT$_DEQNA | V4.0
CSMA/CD | QBUS | KFE52 | EFc0 | KFE | DT$_FT_NI | V5.4
CSMA/CD | UNIBUS | DEUNA | XEc0 | UNA | DT$_DEUNA | V4.0
CSMA/CD | UNIBUS | DELUA | XEc0 | UNA | DT$_DELUA | V4.0
CSMA/CD | BI | DEBNA | ETc0 | BNA | DT$_ET_DEBNA | V4.4
CSMA/CD | BI | DEBNK | ETc0 | BNA | DT$_ET_DEBNA | V4.4
CSMA/CD | BI | DEBNT | ETc0 | BNA | DT$_ET_DEBNA | V4.4
CSMA/CD | BI | DEBNI | ETc0 | BNA | DT$_ET_DEBNI | V5.2
FDDI | XMI | DEMFA | FXc0 | MFA | DT$_FX_DEMFA | V5.4-3
FDDI | TurboChannel | DEFZA | FCc0 | FZA | DT$_FC_DEFZA | V5.5-2HW
FDDI | TurboChannel | DEFTA | FCc0 | FZA | DT$_FC_DEFTA | V6.0
FDDI | QBUS | DEFQA | FQc0 | FQA | DT$_FQ_DEFQA | V6.1

Note The DEQTA device is also known as the DELQA-YM. Also note that the device name is the name of the template device which is used by applications to identify the LAN device. The "c" in the device name indicates the controller letter, for example, A, B, and so on.

### 9.2.2 OpenVMS Alpha Lan Devices

On Alpha systems, Table 9-2 lists the supported devices.

Table 9-2 Supported OpenVMS Alpha LAN Devices
Medium | Bus | Device | Device Name | DECnet Name | Device Type | Version
--- | --- | --- | --- | --- | --- | ---
CSMA/CD | XMI | DEMNA | EXc0 | MNA | DT$_EX_DEMNA | V1.0
CSMA/CD | Local | TGEC | EZc0 | ISA | DT$_EZ_TGEC | V1.0
CSMA/CD | TurboChannel | COREIO | ESc0 | SVA | DT$_ES_LANCE | V1.0
CSMA/CD | TurboChannel | PMAD | ECc0 | MXE | DT$_EC_PMAD | V1.0
CSMA/CD | TurboChannel | DELTA | ECc0 | MXE | DT$_EY_NITC2 | V6.1
CSMA/CD | EISA | DE422 | ERc0 | ERA | DT$_ER_DE422 | V1.5
CSMA/CD | EISA | DE425 | ERc0 | ETA | DT$_ER_TULILP | V6.1
CSMA/CD | ISA | DE200 | ERc0 | ERA | DT$_ER_LANCE | V6.1
CSMA/CD | ISA | DE201 | ERc0 | ERA | DT$_ER_LANCE | V6.1
CSMA/CD | ISA | DE202 | ERc0 | ERA | DT$_ER_LANCE | V6.1
CSMA/CD | ISA | DE203 | ERc0 | ERA | DT$_ER_LEMAC | V6.2
CSMA/CD | ISA | DE204 | ERc0 | ERA | DT$_ER_LEMAC | V6.2
CSMA/CD | ISA | DE205 | ERc0 | ERA | DT$_ER_LEMAC | V6.2
CSMA/CD | PCI | Tulip | EWc0 | EWA | DT$_EW_TULIP | V6.1
CSMA/CD | PCI | DE434 | EWc0 | EWA | DT$_EW_DE435 | V6.1
CSMA/CD | PCI | DE435 | EWc0 | EWA | DT$_EW_DE435 | V6.1
CSMA/CD | PCI | DE436 | EWc0 | EWA | DT$_EW_DE435 | V6.1
CSMA/CD | PCI | DE450 | EWc0 | EWA | DT$_EW_DE450 | V6.2
CSMA/CD | PCI | DE500-XA | EWc0 | EWA | DT$_EW_DE500 | V6.2
CSMA/CD | PCI | DE500-AA | EWC0 | EWA | DT$_EW_DE500 | V6.2
CSMA/CD | PCI | DE500-BA | EWc0 | EWA | DT$_EW_DE500 | V6.2
CSMA/CD | PCI | DE504-BA | EWc0 | EWA | DT$_EW_DE504 | V7.1-1H1
CSMA/CD | PCI | DE500-FA | EWc0 | EWA | DT$_EW_DE500 | V7.1
CSMA/CD | PCMCIA | 3COM 3C589B | EOc0 | CEC | DT$_EO_3C589 | V6.2-1H2
CSMA/CD | PCI | DEGPA-SA | EWc0 | EWA | DT$_EW_DEGPA | V7.1-2
CSMA/CD | PCI | DEGPA-TA | EWc0 | EWA | DT$_EW_DEGPA | V7.1-2
CSMA/CD | PCI | DE600 | EIc0 | EIA | DT$_EI_82558 or DT$_EI_82559 | V7.1-2
CSMA/CD | PCI | DE602 | EIc0 | EIA | DT$_EI_82558 or DT$_EI_82559 | V7.1-2
CSMA/CD | PCI | Shared Memory | EBc0 | EBA | DT$_EB_SMLAN | V7.1-2
FDDI | XMI | DEMFA | FXc0 | MFA | DT$_FX_DEMFA | V1.0
FDDI | FutureBus+ | DEFAA | FAc0 | FAA | DT$_FA_DEFAA | V1.5
FDDI | TurboChannel | DEFZA | FCc0 | FZA | DT$_FC_DEFZA | V1.0
FDDI | TurboChannel | DEFTA | FCc0 | FZA | DT$_FC_DEFTA | V1.5
FDDI | EISA | DEFEA | FRc0 | FEA | DT$_FR_DEFEA | V1.5-1H1
FDDI | PCI | DEFPA | FWc0 | FPA | DT$_FW_DEFPA | V6.2
TokenRing | TurboChannel | DETRA | ICc0 | TRA | DT$_IC_DETRA | V6.1
TokenRing | EISA | DW300 | IRc0 | TRE | DT$_IR_DW300 | V6.1
TokenRing | ISA | DW110 | IRc0 | TRE | DT$_IR_DW300 | V6.2
TokenRing | PCI | PBXNP-AA | IWc0 | TRE | DT$_IW_TI380PCI | V6.2-1H1
TokenRing | PCI | PBXNP-DA | IWc0 | TRE | DT$_IW_RACORE | V7.1-1H1
ATM | TurboChannel | DGLTA | HCc0 /ELc0 | ELA | DT$_HC_OTTO | V6.2
ATM | PCI | DGLPB | HWc0 /ELc0 | ELA | DT$_HW_OTTO | V7.1-1H1
ATM | PCI | DGLPA | HWc0 /ELc0 | ELA | DT$_HW_METEOR | V7.1-2
ATM | PCI | DAPBA | HWc0 /ELc0 | ELA | DT$_HW_HE155 | V7.2-1
ATM | PCI | DAPCA | HWc0 /ELc0 | ELA | DT$_HW_HE622 | V7.2-1

Previous | Next | Contents | Index

| privacy and legal statement |
6136PRO_028.HTML