c
Previous |
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.
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 |
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.
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:
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) |
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) |
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) |
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.
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 |
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.
1st word | 2nd word | 3rd word | 4th word |
---|---|---|---|
SS$_NORMAL | undefined | 0 | 0 |
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:
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:
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:
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:
The frame received for the upper VCM is discarded by the LAN driver.
The input registers for this event are:
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:
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:
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.
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 |