c LAN VCI Specification

LAN VCI Specification


Previous

3.2.2 VCI$xxx_PORTMGMT_COMPLETE

When the LAN driver has completed processing a request made through the VCI$LAN_PORTMGMT_INITIATE service, it calls the VCI$xxx_PORTMGMT_COMPLETE service in the upper VCM to return the VCRP.

The calling sequence is as follows:


        JSB     @VCIB$A_PORTMGMT_COMPLETE(R4) 

The status of the request is stored in the VCRP$Q_REQUEST_STATUS field of the VCRP. Table 3-3 shows some of the possible values for this quadword field. See Section 3.6 for a meaning of the status values in the first word. Only the first status code is a success status value; the others are failure status values. Other error status values may be returned.

Table 3-3 Port management request status values
1st word 2nd word 3rd word 4th word
SS$_NORMAL 0 0 0
SS$_ABORT 0 0 0
SS$_BADPARAM bad parameter 0 0
SS$_DEVACTIVE 0 0 0
SS$_DEVINACT 0 0 0
SS$_DEVOFFLINE 0 0 0
SS$_ILLIOFUNC 0 0 0
SS$_INSFMEM 0 0 0
SS$_IVADDR 0 0 0
SS$_OPINCOMPL 0 0 0
SS$_TIMEOUT 0 0 0

3.3 TRANSMIT SERVICE ROUTINES

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 one of the two service routines provided by the LAN driver. The transmit request is asynchronous. This means that the LAN driver completes the transmit request via the transmit completion service routine of the upper VCM.

If the LAN driver cannot accept the request (possibly it has not been enabled), then the transmit is completed immediately via the upper VCM's transmit completion service routine.

Implementor's note

The transmit error case can cause problems. The two VCMs could call recursively with the upper VCM requesting transmits and the LAN driver returning an error on every transmit request. This could cause a system hang at a high IPL possibly with an important spinlock. Or the recursive calls between the two VCMs could overflow the stack and crash the system. It is left to the upper VCM to handle this situation.

Transmit requests may be issued to the LAN driver after the upper VCM has received a PORT_USABLE event. The PORT_USABLE event is reported to the upper VCM after a successful completion of an ENABLE_PORT request and the device is operational. When the upper VCM receives a PORT_UNUSABLE event, the upper VCM is not allowed to make transmit requests until it receives another PORT_USABLE event.

Most LAN Drivers are able to handle chained and non-chained transmit requests. The rules for making chained and non-chained transmit requests are described in Section 6.4.2. If the LAN driver does not support chained transmit requests, then the VCIB$V_DLL_XMT_CHAIN flag is set in the field VCIB$W_DLL_FLAGS and the upper VCM should not make chained requests. On OpenVMS AXP, transmit chaining will always be supported, so the VCIB$V_DLL_XMT_CHAIN flag will never be set. The upper VCM does not need to check this flag on OpenVMS AXP.

The VCRP$L_BOFF field must be initialized to allow sufficient space for the LAN driver to back-build its header in the VCRP without going into the scratch field of the VCRP. Note that even though it's required that the LAN driver not back-build its header into the scratch space of the VCRP, the LAN driver doesn't check that this occurs. This is because the VCI is a privileged interface and we expect the upper VCM to initialize the VCRP properly. Therefore the upper VCM has to initialize VCRP$L_BOFF such that it allows enough space for the LAN header. The field VCIB$W_DLL_HDR_SIZE can be used by the upper VCM to ensure that it leaves enough space for the LAN header. The upper VCM can also use the constant value LAN$C_MAX_HDR_SIZE as the maximum LAN header size. If LAN$C_MAX_HDR_SIZE is not defined in $LANUDEF in LANUDEF.MLB, then the constant 58 (decimal) can be used.

There are two ways to make a transmit request to the LAN drivers:

  1. The upper VCM calls the transmit initiate routine to transmit data. The LAN driver builds its header in the VCRP and passes the packet to the device. When the device completes the request to the LAN driver, the LAN driver calls the transmit complete routine in the upper VCM. This style of transmit request is very similar to the QIO request (except that the overhead in CPU time is greatly reduced as compared to QIO). The upper VCM provides the standard information required by the LAN driver to build the header.
  2. A more efficient method to transmit packets is for the upper VCM to call the build header routine in the LAN driver. The upper VCM then places this header in all (or most) of the VCRPs it uses for transmit requests and calls the LAN driver's transmit frame routine. This style of transmit requests allows for the LAN header to be built once. The CPU time required to build the header for every packet is saved if the same header is used for multiple transmit requests.

The status for a transmit request is stored in the VCRP$Q_REQUEST_STATUS field of the VCRP when the VCRP is returned to the upper VCM.

The transmit service routines are called through the VCIB. They are described in the following sections.

3.3.1 VCI$LAN_TRANSMIT_INITIATE

Transmit requests with no LAN header are made to the LAN driver via a call to the VCI$LAN_TRANSMIT_INITIATE routine. Completion of the VCRP is done via the transmit complete service.

The calling sequence is as follows:


        JSB     @VCIB$A_TRANSMIT_INITIATE(R4) 

3.3.2 VCI$LAN_BUILD_HDR

To request to have a LAN header built, the upper VCM calls the LAN driver's VCI$LAN_BUILD_HDR routine. The upper VCM passes some header information to this routine. Completion of this request is made synchronously.

The calling sequence is as follows:


        JSB     @VCIB$A_LAN_BUILD_HDR(R4) 

3.3.3 VCI$LAN_TRANSMIT_FRAME

Transmit requests with a LAN header are made to the LAN driver via a call to the VCI$LAN_TRANSMIT_FRAME routine. Completion of the VCRP is done via the transmit complete service.

The calling sequence is as follows:


        JSB     @VCIB$A_LAN_TRANSMIT_FRAME(R4) 

3.3.4 VCI$xxx_TRANSMIT_COMPLETE

When the LAN driver has completed processing a transmit request, it calls this service in the upper VCM to return the transmit VCRP.

The calling sequence is as follows:


        JSB     @VCIB$A_TRANSMIT_COMPLETE(R4) 

The status of the request is stored in the VCRP$Q_REQUEST_STATUS field of the VCRP. Table 3-4 shows some of the possible values for this quadword field. See Section 3.6 for a meaning of the status values in the first word. Only the first status code is a success status value; the others are failure status values. Other error status values may be returned.

Table 3-4 Transmit request status values
1st word 2nd word 3rd word 4th word
SS$_NORMAL undefined undefined 0
SS$_ABORT 0 0 0
SS$_DEVINACT 0 0 0
SS$_IVBUFLEN 0 0 0
SS$_OPINCOMPL 0 0 0
SS$_THIRDPARTY 0 0 0
SS$_TIMEOUT 0 0 0

3.4 RECEIVE SERVICE ROUTINES

The receive service is used to support the reception of packets. The receive service routines are called through the VCIB.

The LAN drivers use an "allocate receive" method for handling receive packets. This involves the LAN driver allocating receive buffers on behalf of the upper VCM. The upper VCM never needs to allocate a receive buffer and never needs to post read requests.

In the allocate receive method the LAN driver allocates the receive buffers. The LAN driver supplies no service for initiating receives. The initiation of receives is implicit when the VCI port becomes usable. The upper VCM supplies the receive complete service routine. Receive buffers are passed to the upper VCM through the receive complete service routine.

An important point about the allocate receive method is that since there is no initiation of the request, the receive VCRP does not traverse the VCMs from top to bottom and then bottom to top. The receive VCRP begins in the LAN driver and traverses the VCMs once from the bottom to the top.

There are different ways for the upper VCM to process the receive VCRPs. The upper VCM can either hold onto the VCRP or it can return the VCRP before it returns control back to the LAN driver. When the upper VCM decides it's done with the VCRP, it returns the VCRP to the LAN driver by calling the routine pointed to by the VCRP$A_DEALLOC_RTN field in the receive VCRP. This is the only way an upper VCM can get rid of a receive VCRP.

3.4.1 VCI$xxx_RECEIVE_COMPLETE

When the LAN driver has received a packet for a usable port of an upper VCM, it calls this service in the upper VCM to pass the VCRP and the packet.

The calling sequence is as follows:


        JSB     @VCIB$A_RECEIVE_COMPLETE(R4) 

The status of the request is stored in the VCRP$Q_REQUEST_STATUS field of the VCRP. Table 3-5 shows the possible values for this quadword field. See Section 3.6 for a meaning of the status values in the first word.

Table 3-5 Receive request status values
1st word 2nd word 3rd word 4th word
SS$_NORMAL undefined 0 0

3.5 REPORT EVENT SERVICE ROUTINES

The LAN driver reports the following events to the upper VCM through the report event service routine supplied by the upper VCM. The report event service routines are called through the VCIB.

The calling sequence is as follows:


        JSB     @VCIB$A_REPORT_EVENT(R4) 

The event codes are defined in $VCRPLANDEF in LANUDEF.MLB.

3.5.1 PORT USABLE EVENT

When this event is reported it signals the upper VCM that its port can be used for data transfer.

The LAN driver reports this event whenever the VCI port becomes ready for data transfer. This can happen due to an ENABLE_PORT request from the upper VCM or due to the completion of an automatic restart following an error that made the port unusable.

The input registers for this event are:

3.5.2 PORT UNUSABLE EVENT

When this event is reported it signals the upper VCM that the VCI port can no longer be used for data transfer. The port can become unusable for many reasons. For example, it can be disabled by a DISABLE_PORT request and whenever the LAN driver has a fatal error. The reasons that the port became unusable are described below as part of the reason codes for this event.

The port can be re-enabled by the upper VCM (using an ENABLE_PORT request) or automatically by the LAN driver if the upper VCM has enabled this feature.

This event and the PORT_USABLE event are reported alternately. That is, the upper VCM never receives back to back PORT_USABLE events and never receives back to back PORT_UNUSABLE events.

The reason codes passed to the upper VCM for this event are:

The input registers for this event are:

3.5.3 RECEIVE CONGESTION EVENT

The LAN driver reports this event whenever receive packets are lost (whenever the Station Buffer Unavailable counter is incremented). This event will not be reported any more than once per five minutes. This is to prevent excessive overhead when we should be trying to handle the incoming packets.

The input registers for this event are:

3.5.4 NEW ADDRESS EVENT

The LAN driver reports this event when the physical address of the station has been changed.

The input registers for this event are:

Note that when the LAN driver reports the new address event, all headers supplied to the upper VCM through the BUILD_HDR service routine are invalid. The upper VCM has to re-issue all BUILD_HDR requests and replace all the old headers with new headers. The size of the headers remain the same; just the contents of the header will have changed.

3.5.5 RECEIVE PDU LOST EVENT

The LAN driver reports this event when:

  1. the upper VCM has put a 1 in the field VCIB$V_LAN_RCV_LIM and
  2. the field VCIB$W_LAN_MAX_RCV is equal to the field VCIB$W_LAN_OUT_RCV and
  3. another frame has been received by the LAN driver for this upper VCM.

The frame received for the upper VCM is discarded by the LAN driver.

The input registers for this event are:

3.5.6 RESTART FAILED EVENT

The LAN driver reports this event when it has exhausted its attempts to automatically restart the port. When this event is reported, the upper VCM should delete the port or attempt to enable the port.

The input registers for this event are:

3.5.7 STATION RENAMED EVENT

The LAN driver reports this event when it cannot restart the upper VCM because the DECnet Phase V customer assigned name of the station has been changed. This can happen if network management disables and deletes the station and then creates and enables the same station; but with a different name. When this event is reported, the upper VCM must delete the port.

The input registers for this event are:

3.6 STATUS VALUES

This section describes some of the different values that can be returned to the upper VCM in the VCRP request status field and in R0.

Table 3-6 Status value meanings
Status value Definition
SS$_NORMAL The request has completed successfully.
SS$_ABORT All VCI ports are being disabled due to an error detected by the LAN driver.
SS$_BADPARAM One of the parameters in the request was not specified correctly. For ENABLE_PORT, the NMA$C_PCLI_xxx code of the P2 parameter in error is in the second word of VCRP$Q_REQUEST_STATUS.
SS$_DEVACTIVE The VCI Port is active.
SS$_DEVINACT The VCI Port is not active.
SS$_DEVOFFLINE The LAN device is OFFLINE and is not usable.
SS$_ILLIOFUNC The function code field of the VCRP had a value that did not represent a function known by the LAN driver.
SS$_INSFMEM There was not enough non-paged pool to complete the request.
SS$_IVADDR The upper VCM's PHA parameter is the same as another node on the extended LAN.
SS$_IVBUFLEN The number of bytes to transmit was too large.
SS$_NOSUCHDEV The device name passed does match an existing device.
SS$_OPINCOMPL The request could not be completed because the VCI port is being restarted.
SS$_SYSVERDIF The LAN driver's VCI version was higher than the upper VCM's version and they are not compatible versions.
SS$_THIRDPARTY A data link entity was disabled by management action.
SS$_TIMEOUT The VCI port is being disabled due to a timeout.
SS$_UNSUPPORTED The LAN driver does not support the VCI and/or the VCM (by VCI ID) on this device.


Previous Next