HP OpenVMS Systems Documentation

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

8.8 Issuing a $QIO Request to the Generic Class Driver

The format of the Queue I/O Request ($QIO) system service thatinitiates a request to the SCSI generic class driver is as follows.This explanation concentrates on the special elements of a $QIO requestto 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

High-Level Language Format

Arguments

chan

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

func

Longword value containing the IO$_DIAGNOSE function code. Only theIO$_DIAGNOSE function code is implemented in the generic SCSI classdriver.

iosb

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

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

[efn]
[astadr] [astprm]

p1

p2

Descriptor Fields

opcode

Currently, the only supported opcode is 1, indicating a pass-throughfunction. 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:

SCSI command address

SCSI command length

SCSI data address

If the dir bit is set in the flagsfield, data is written into this buffer during the execution of thecommand. Otherwise, data is read from this buffer and sent to thetarget device.

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

SCSI data length

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

SCSI pad length

For example, suppose an application program is using the generic classdriver to read the first 2 bytes of a disk block. The length field inthe SCSI READ command contains 1 (indicating one logical block, or 512bytes), 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 initializethe SCSI pad length field properly causes port drivertimeouts and SCSI bus resets.

phase change timeout

See Section 8.5.4 for additional information.

disconnect timeout

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 servicereturns the following information for any device serviced by thegeneric SCSI class driver. (Refer to the description of the $GETDVIsystem service in the OpenVMS System Services Reference Manual.)

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

DVI$DEVCLASS returns the device class, which is DC$_MISC; DVI$DEVTYPEreturns 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 driverto send a SCSI INQUIRY command to a device.

/*GKTEST.CThis program uses the SCSI generic class driver to send an inquiry commandto 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 0x30globalvalue        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");}

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 supportsanother 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.

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

9.2.1 OpenVMS VAX Lan Devices

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

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