Revision/Update Information: Version 1.0
March 19, 2003
The VMS LAN drivers have an unprivileged interface (QIO) that has been available since the introduction of the LAN drivers. This specification describes a privileged interface to the same VMS LAN drivers. In some sections, the QIO interface is referenced. The QIO interface to the LAN drivers is documented in the LAN chapter of the VMS I/O User's Manual.
The privileged interface to the VMS LAN drivers is the VMS Communications Interface (VCI). It is an interface that is available at IPL 8 that has been designed to be very efficient. For these reasons, the VCI is the preferred interface for those applications that require minimal CPU overhead and/or maximum LAN utilization without the protection that the QIO interface provides.
This document assumes that the reader is familiar with the internals of VMS. The following is a list of documents which are relevant to this document:
This document contains a description of VCI terms, data structures, and
routines that form the LAN VCI.
1.2 PERFORMANCE
Compared to QIO, this interface uses less CPU and less memory for the
transmission and reception of data on the LAN. Within the LAN drivers,
the VCI code path is optimized over the QIO code path.
1.3 SUPPORT OBJECTIVES
The requirements and recommendations of the LAN VCI are subject to change between releases (major or minor) of VMS. As optimizations to this interface are developed they will be incorporated into the interface. Implementations using this interface must be updated to reflect any such changes.
The LAN VCI is not supported on the DEQNA device. Attempts to use the LAN VCI on a DEQNA result in the error SS$_UNSUPPORTED being returned.
This specification assumes that MACRO-32 will be the programming language used. However, the use of a high level language is not precluded.
The LAN VCI on OpenVMS VAX and OpenVMS AXP are mostly the same. This document describes the LAN VCI available in OpenVMS VAX version 6.0 and OpenVMS AXP version 1.5. There are a few data structure fields in OpenVMS AXP version 1.5 that have been extended to a longword (4 bytes). In a future release of OpenVMS VAX, the same fields will be extended to match the data structures in OpenVMS AXP version 1.5.
Differences in the LAN VCI of OpenVMS VAX version 6.0 and OpenVMS AXP version 1.5 are described in this specification.
The LAN VCI is an interface that allows the creation of ports to a LAN driver, allows the port to be enabled with specific attributes, allows the port to be used for data transmission and reception, allows the port to be disabled, and allows for the deletion of the port. The functions available from the LAN VCI are very similar to the functions available from the LAN QIO interface.
The LAN VCI has the following characteristics:
The rest of this chapter provides a definition of terms, an overview of
the primary data structures, and an overview of the VCI routines. The
details are provided in following chapters.
2.1 TERMS
This section describes the basic terms used within this specification.
2.1.1 VMS COMMUNICATION MODULE
A VMS Communication Module (VCM) is a single piece of VMS kernel mode code which implements a protocol and provides a VCI and/or uses a VCI. The LAN drivers are VCMs and each user of the VCI to the LAN drivers is a VCM. It is not required that a single VCM map directly to a single image or that a single image represent only one VCM. However, it is typical for a VCM to be implemented as a single image. Another example of a VCM is LTDRIVER (the VMS pseudo driver that implements the LAT protocol).
In keeping with architecture layering, an individual VCM has a
hierarchical relationship to its adjacent VCM. Therefore, from a given
VCM there may be an upper VCM and/or a lower VCM. The upper VCM
implements the protocol of the adjacent higher layer of the
architecture. The lower VCM implements the adjacent lower layer of the
architecture. With the LAN VCI, the LAN driver is always the lower VCM
and the user of the LAN VCI is the upper VCM.
2.1.2 SERVICE ROUTINE
The VCI routines are divided into several services. Each service provides a different type of request. For example, there is a port management service and there is a transmit service. These two services provide different functions. Each service may have one or more service routines. The service routines form the interface between the two adjacent VCMs. Each service routine exists in either the upper VCM or the LAN driver. A service with multiple service routines can have some of its service routines exist in the upper VCM and the rest in the LAN driver.
In general, the LAN driver provides INITIATE service routines and the upper VCM provides COMPLETION service routines. In some situations, the completion or initiation routine is not needed because the completion of the request or the initiation of the request is implied.
An example of a service that has both initiate and completion service routines is the TRANSMIT service. This service has an INITIATE routine which resides in the LAN driver and a COMPLETION routine which resides in the upper VCM.
An example of a service that has only a completion service routine is the REPORT EVENT service where there is a report event routine in the upper VCM only.
An overview of the service routines is available in Section 2.3 and a
detailed description of each service routine is available in
Chapter 3.
2.1.3 VCI PORT
The VCI port can be considered a "channel" that's established between two VCMs using the VCI. It comprises the handle for the communication between the two VCMs. The VCI port is represented by a VCIB data structure (described in Section 2.2.3). Once a VCIB has been initialized by both the upper VCM and the LAN driver, a VCI port has been created. Note that two VCMs may have more than one VCI port between them; and for each VCI port, there is a unique VCIB.
Although the VCI port is somewhat equivalent to a QIO channel, it cannot be accessed through QIO nor through the $ASSIGN system service. For each VCI port, the LAN driver creates a UCB; just as the I/O subsystem creates a UCB for each QIO channel. The UCB that's associated with the VCI port is visible using SDA; but is NOT available for access by the upper VCM.
Note that the VCI port is a VCI concept and is not associated with an
architectural port or any other entity called a port.
2.2 OVERVIEW OF DATA STRUCTURES
There are five major data structures used in the LAN VCI. The data
structures are described in full detail in Chapter 4.
2.2.1 LAN BLOCK
The LAN block is a data structure that's allocated and owned by the LAN
drivers. The address of the LAN block is stored in the system data cell
NET$AR_LAN_VECTOR. The LAN block contains some information that can be
used by the upper VCM and it contains addresses of some routines that
the upper VCM calls.
2.2.2 LAN DEVICE CHARACTERISTICS
The LAN Device Characteristics (LDC) data structure is owned by the LAN
drivers. There is one LDC for each available LAN device. The upper VCM
can acquire the address of each LDC by calling an access routine
repeatedly. The LDC can be used by the upper VCM to determine which
available LAN devices to use.
2.2.3 VCI BLOCK
The VCI Block (VCIB) is the data structure used to represent a VCI
Port. It contains the information required for the two VCMs to keep
context on the VCI port and for the two VCMs to call each other. The
upper VCM is responsible for allocating the VCIB, initializing its
fields in the VCIB, and calling the LAN driver to initialize its fields
in the VCIB. The VCIB contains pointers to the services provided by the
upper VCM and the LAN driver.
2.2.4 VMS COMMUNICATIONS REQUEST PACKET
The VMS Communications Request Packet (VCRP) is used to exchange
information and completion status of requests between VCMs. It
describes the type of function to be performed and provides the
parameter information needed for the request. The VCRP is allocated and
initialized by a VCM. It is then passed to the upper VCM or the LAN
driver at the appropriate service address.
2.2.5 DATA CHAIN BLOCK
The Data Chain Block (DCBE) is used to connect a buffer containing all
or part of a packet to a VCRP. This allows a packet to exist in
multiple non-contiguous buffers of memory. When a packet is broken up
into multiple buffers, it is called chaining. Chaining can occur on
transmit requests only.
2.3 OVERVIEW OF ROUTINES
This section contains an overview of the services that make up the LAN VCI. The section is divided into five parts.
Each classification of services is made up of a set of service routines
that support the classification. Each of the following sections
describe the service routines of a specific service classification. All
the service routines are described in full detail in Chapter 3.
2.3.1 ACCESS ROUTINES
The access routines are provided to allow the upper VCM to learn which LAN devices are available and to create and delete VCI ports to those LAN devices.
The Access routines include:
Ports represent the connection or channel between two VCMs. The Port Management services are provided to allow the upper VCM to enable (start), change, and disable (shut down) VCI ports to the LAN drivers.
The Port Management services include:
The transmit service is used to support the transmission of packets. In this service, the upper VCM constructs a transmit VCRP and initiates the request using the address of the service routine provided by the LAN driver.
The Transmit services include:
The receive service is used to support the reception of packets. In this service, the upper VCM does not need to post read requests. Instead, the LAN driver calls the upper VCM's receive completion routine with packets received for that VCM.
The Receive services include:
When an asynchronous event is detected by the LAN driver, it may wish to signal the event to the upper VCM. The Report Event service is used to perform this notification.
The Report Event services include:
This chapter describes the rules for calling the routines of the VCI.
Each update to the VCI is assigned a new version number. A new release of VMS may contain a new (higher) version of the VCI or it may contain the same version as the previous release of VMS.
All routines are called according to the following synchronization rules. All routines are called at IPL 8 with IOLOCK8 as the highest lock acquired. On a system where SMP is not enabled, no locks need be acquired. All routines are called on a CPU where access to I/O space is allowed - typically this means that the fork thread must be running on the primary CPU. The LAN drivers call the upper VCM according to these rules. The upper VCMs must adhere to these rules also.
See Chapter 6 for detailed steps in using these routines.
3.1 ACCESS ROUTINES
This section describes the Access Routines. These routines are accessed
through the LAN block.
3.1.1 LAN$GET_DEVICE
For each LAN device, some amount of information about the LAN device is made available to the upper VCM.
This routine is typically called repeatedly so that information about all devices can be acquired by the upper VCM. Each call to this routine provides the upper VCM with information about the next available LAN device.
Each call to this routine returns a pointer to the LDC structure of an existing LAN device or zero if there are no more existing LAN devices.
The call to LAN$GET_DEVICE is made through the LAN block. The calling sequence is as follows:
MOVL G^NET$AR_LAN_VECTOR,R0
BEQL NO_LAN_BLOCK
CMPL #1,LAN$L_VERSION(R0)
BNEQ WRONG_VERSION
JSB @LAN$A_GET_DEVICE(R0)
|
This call is completed synchronously.
The upper VCM can use this routine to get the name of the first LAN device by calling the routine once. The upper VCM could also use this routine to determine the name of the first FDDI device by calling this routine repeatedly until an FDDI device is returned or until a 0 is returned. The upper VCM would look in each LDC to see if that LDC was for an FDDI device. The upper VCM could also use this routine to determine the name of all the LAN devices.
Once using this routine to acquire the name of the desired LAN device, the upper VCM would typically pass the name of the device to the VCI$LAN_CREATE_PORT routine to create a VCI port to that LAN device.
If the upper VCM already knows the name of the desired device, then the
LAN$GET_DEVICE routine need not be called.
3.1.2 VCI$LAN_CREATE_PORT
The create port service is provided by the LAN driver. The address of the service is stored in the LAN block. The service is used to create a VCI Port.
Upon successful return from the create port routine, the VCI Port is in a state where it can be used to issue VCRPs between the VCMs. A successful call to the create port routine implies the creation of a VCI port; it does not imply that the port is now able to be used for packet transmission or reception. The upper VCM has to enable the port and wait for the port usable event before packet transmission or reception can begin.
Note that the LAN drivers cannot deallocate the VCIB; since that data structure is owned by the upper VCM. And the upper VCM cannot deallocate the VCIB until the VCI port has been deleted by a successful call to the delete port routine.
The steps to using the Create Port service are:
The call to create the VCI Port is made through the LAN block. The calling sequence is as follows:
MOVL G^NET$AR_LAN_VECTOR,R0
BEQL NO_LAN_BLOCK
CMPL #1,LAN$L_VERSION(R0)
BNEQ WRONG_VERSION
JSB @LAN$A_CREATE_PORT(R0)
|
This call is completed synchronously.
The status of the call is stored in R0 before returning to the caller. Table 3-1 shows some of the possible values. See Section 3.6 for a meaning of the status values. Only the first status code is a success status value; the others are failure status values. Other error status values may be returned.
| R0 | |
|---|---|
| SS$_NORMAL | |
| SS$_DEVACTIVE | |
| SS$_INSFMEM | |
| SS$_NOSUCHDEV | |
| SS$_SYSVERDIF | |
| SS$_UNSUPPORTED |
The delete port service is provided by the LAN driver. The address of the service is stored in the LAN block. The service is used to delete a VCI Port.
Upon successful return from the delete port routine, the VCI Port no longer exists. At this point, the upper VCM can deallocate the VCIB and any other context it has for the VCI port. The LAN drivers do NOT deallocate the VCIB.
The steps to using the Delete Port service are:
The call to delete the VCI Port is made through the LAN block. The calling sequence is as follows:
MOVL G^NET$AR_LAN_VECTOR,R0
JSB @LAN$A_DELETE_PORT(R0)
|
This call is completed synchronously.
The status of the call is stored in R0 before returning to the caller. Table 3-2 shows some of the possible values. See Section 3.6 for a meaning of the status values. Only the first status code is a success status value; the others are failure status values. Other error status values may be returned.
| R0 | |
|---|---|
| SS$_NORMAL | |
| SS$_DEVACTIVE | |
| SS$_NOSUCHDEV |
This section describes the Port Management Service Routines. These
routines are accessed through the VCIB.
3.2.1 VCI$LAN_PORTMGMT_INITIATE
The PORTMGMT_INITIATE service is provided by the LAN drivers.
PORTMGMT_INITIATE requests allow the upper VCM to perform functions on the VCI port. Note that once the VCI port has been created, it is still not totally functional. For example, it may not be used to transmit and receive packets. Using PORTMGMT_INITIATE requests, the VCI port can be enabled (started) with specific attributes, changed, or disabled (shut down).
Since the PORTMGMT_INITIATE service allows different operations, a function code in the VCRP is used to distinguish from the different types of PORTMGMT_INITIATE requests. The function codes that may be used with the PORTMGMT_INITIATE service routine are listed below. Some of these function codes are defined in $VCRPDEF in LIB.MLB and some are defined in $VCRPLANDEF in LANUDEF.MLB.
This service completes its requests asynchronously. That is, requests are completed through another service routine (the PORTMGMT_COMPLETE service routine).
Since requests are completed through the VCI$xxx_PORTMGMT_COMPLETE service routine, there is no return status on the call to the VCI$LAN_PORTMGMT_INITIATE routine. The status of the request is stored in the VCRP$Q_REQUEST_STATUS field of the VCRP when the VCRP is returned to the upper VCM.
The calling sequence is as follows:
JSB @VCIB$A_PORTMGMT_INITIATE(R4)
|
This call is completed asynchronously through the upper VCM's Port Management Complete service.
| Next |