g LAN VCI Specification

LAN VCI Specification


Previous

4.6 LIL

The LAN Item List (LIL) is the data structure used to pass the device name to the LAN driver in the call to VCI$LAN_CREATE_PORT. A LAN Item List contains a header pointing to a series of items; so there are really two structures. One structure defines the item list header, and the other structure defines an item in the item list. Note that the items in the item list may actually follow the header in virtually contiguous memory or may be placed in a separate memory buffer. The items in the list, however, are virtually contiguous with each other. The fields in these structures begin with LIL$.

The LIL fields are defined by $LILDEF in LANUDEF.MLB.

Table 4-6 describes the fields of the LIL header structure.

Table 4-7 describes the fields of the LIL item structure.

Table 4-6 LIL header structure
FIELD NAME DESCRIPTION
L_LISTLEN Number of bytes in the list of items
A_LISTADR Address of the first byte in the list of items
W_SIZE Size of memory to be deallocated
B_TYPE Type of structure DYN$C_DECNET
B_SUBTYPE Subtype of structure DYN$C_NET_ITEM
T_DATA Place where the items can begin

Table 4-7 LIL item structure
FIELD NAME DESCRIPTION
W_ITEMLEN Number of bytes in this item
W_ITEMTAG Tag (identifier) for this item
T_ITEMVAL Value for this item


Chapter 5
FEATURES

This chapter describes some of the features available to the users of the LAN VCI. Many of these features are available through the use of particular fields in the data structures.

5.1 PERFORMANCE

This section highlights the features that provide the highest performance (lowest number of CPU cycles per I/O request).

5.2 CONVERTING A VCRP INTO A DCBE

The DCBE is smaller than the VCRP. And the fields that exist in the DCBE are exactly the same as the fields of the VCRP. That is, the DCBE fields have the same name and position as the corresponding field in the VCRP. This allows multiple VCRPs that are received at different times to be easily connected to form a single VCRP and many DCBEs. Even though the DCBEs in this case are larger than normal, they may still be called DCBEs.

5.3 CONVERTING A VCRP INTO AN ACB

The VCRP contains some fields that can be used to make the beginning of the VCRP look like an ACB (AST Control Block). These fields are generally used by upper VCMs that pass the VCRP to the I/O executive to be completed to a process. If the VCRP is not going to be passed to the I/O executive, then the ACB fields can be used by the upper VCM as permanent or temporary storage which are not destroyed by the LAN driver. The ACB fields in the VCRP include the following fields.


Chapter 6
PROCESSING

This chapter describes the steps that the upper VCM should use in making VCI requests to the LAN driver.

6.1 STARTING A VCI PORT

There are multiple steps required to getting a VCI port ready for data transfer. In general, a VCI port is created, the VCI port is enabled, and the upper VCM waits for the PORT_USABLE event.

Once the upper VCM has received a PORT_USABLE event for the port, the port can be used for data transfer.

To start a VCI port, the upper VCM performs the following steps.

  1. The upper VCM allocates and initializes the VCIB that will represent this VCI port. Remember that the VCIB allocated can be larger than required by the LAN driver. The upper VCM can extend the VCIB for its own purpose.
    If the upper VCM does not know which LAN device to use, it can call the LAN$GET_DEVICE routine to determine which LAN devices are available.
  2. The upper VCM now creates the VCI port by calling the LAN driver's CREATE_PORT routine. This is a synchronous call. So the upper VCM gets status on this request when it gets control back from the call to the CREATE_PORT routine. If an error is returned, then the upper VCM should either not attempt to use that device or it could wait and try the device again once per minute (or so). The decision should be based on the error returned from the LAN driver. Some errors indicate that the device will never be usable.
    If successful, the VCIB must be kept intact by the upper VCM. It cannot be deallocated until the VCI port has been deleted.
  3. As soon as control is returned to the upper VCM (from its call to the LAN driver's create port routine) and the upper VCM has checked that the status of the call was successful, the upper VCM should allocate and initialize a VCRP for the enable port request.
    The ENABLE_PORT VCRP requires a P2 buffer. The upper VCM needs to allocate and initialize a P2 buffer. The field VCRP$A_LAN_P2BUFF points to the P2 buffer.
  4. With the enable port VCRP ready, the upper VCM calls the LAN driver's port management routine to enable the VCI port. The purpose of this step is to have the upper VCM request that the VCI port be enabled for use and to have the upper VCM specify the appropriate characteristics for the VCI port.
  5. Remember that the enable port request is completed asynchronously. So when control is returned to the upper VCM, it should dismiss its fork thread.
  6. When the upper VCM is called at its port management complete routine with its enable port request, it should examine the status of the request in the VCRP$Q_REQUEST_STATUS field of the VCRP. If there was an error, the upper VCM should handle it as appropriate for the upper VCM.
    This is where the upper VCM would typically deallocate the VCRP and the P2 buffer used for the ENABLE_PORT request.
  7. If the status of the enable port request was successful, then the upper VCM waits for a call to its report event routine with the port usable event. Once receiving this event, the upper VCM can now transmit packets and can now receive packets.

6.2 CHANGING A VCI PORT

There are only a few P2 parameters that may be changed on a VCI port that is usable. The parameters that may be changed are listed in the LAN chapter of the VMS I/O User's Manual.

To change any of these parameters on a VCI port that's usable, the upper VCM performs the following steps.

  1. The upper VCM should allocate and initialize a VCRP for the change port request. The VCRP should be initialized the same as an enable port request except for putting the new parameter values in the P2 buffer and setting the function code to VCRP$K_FC_LAN_CHANGE_PORT.
  2. With the change port VCRP ready, the upper VCM calls the LAN driver's port management routine to change the VCI port.
  3. The change port request is completed asynchronously. So when control is returned to the upper VCM, it should dismiss its fork thread.
  4. When the upper VCM is called at its port management complete routine with its change port request, it should examine the status of the request in the VCRP$Q_REQUEST_STATUS field of the VCRP. If there was an error, the upper VCM should handle it as appropriate for the upper VCM.
  5. There is no event associated with the change port request. Once the change port VCRP has been returned to the upper VCM, the request has been completed.

6.3 SHUTTING DOWN A VCI PORT

There are multiple steps required to shutting down a VCI port. In general, the VCI port is disabled, the upper VCM waits for the PORT_UNUSABLE event, and the VCI port is deleted.

To shut down a VCI port, the upper VCM performs the following steps.

  1. The upper VCM should allocate and initialize a VCRP for the disable port request. The VCRP should be initialized the same as an enable port request except that the P2 buffer fields are set to zero and the function code is set to VCRP$K_FC_DISABLE_PORT.
  2. With the disable port VCRP ready, the upper VCM calls the LAN driver's port management routine to disable the VCI port.
  3. Remember that the disable port request is completed asynchronously. So when control is returned to the upper VCM, it should dismiss its fork thread.
  4. Before the disable port request is completed, the LAN driver completes all outstanding VCI requests to the upper VCM with the status SS$_ABORT or another status. The status returned depends on the state of the outstanding request.
  5. When the upper VCM is called at its port management complete routine with its disable port request, it should examine the status of the request in the VCRP$Q_REQUEST_STATUS field of the VCRP. If there was an error, the upper VCM should handle it as appropriate for the upper VCM.
  6. If the status of the disable port request was successful, then the upper VCM waits for a call to its report event routine with the port unusable event.
  7. Before deleting the VCI port, the upper VCM ensures that all outstanding receive VCRPs have been returned to the LAN driver. Failure to do so may cause the system to crash.
  8. The upper VCM may now delete the VCI port by calling the LAN driver's DELETE_PORT routine. This is a synchronous call. So the upper VCM gets status on this request when it gets control back from the call to the DELETE_PORT routine.
  9. The upper VCM may now deallocate the VCIB.

6.4 TRANSMITTING A PACKET

There are multiple options available to the upper VCM to transmit packets. The packets can be transmitted from the upper VCM with or without the LAN header as part of the request. The packets can be transmitted chained or unchained. In a chained request, the second segment in the chain can be pointed by a system virtual address or by a SVAPTE/BOFF set. This section describes how to use and specify these options.

6.4.1 TRANSMIT FRAME

For the upper VCM to include the LAN header as part of the transmit request, the upper VCM first gets the LAN header. Note that the LAN header returned to the upper VCM does NOT have all the fields initialized. In particular, the destination address field is not initialized in the header. The remaining fields are initialized on the actual transmit request. This allows most upper VCMs to request one header from the LAN driver, to save that header, and to use that header on every transmit request - even though the destination address on each transmit request may be different. The build header routine is called to have the LAN driver return a LAN header to the upper VCM.

If the upper VCM does not wish to include the LAN header as part of its transmit request, then it calls the transmit initiate routine. Some of the VCRP fields to be initialized by the upper VCM when making a transmit request with no LAN header include:

If the upper VCM includes the LAN header as part of its transmit request, then it calls the transmit frame routine. The LAN header is always placed in the VCRP. Some of the VCRP fields to be initialized by the upper VCM when making a transmit request with a LAN header include:

When issuing a transmit request with the LAN header already included, the LAN driver requires that the LAN header be placed in the VCRP following the VCRP$T_DATA field. The number of bytes required for the LAN header varies across the different LAN mediums and the different packet formats. The LAN driver stores the minimum space required for each VCI port's LAN header in the field VCIB$W_DLL_HDR_SIZE. The upper VCM can also use the constant value LAN$C_MAX_HDR_SIZE. Using this constant makes it possible for the upper VCM to use all transmit VCRPs across all LAN devices. The best way for the upper VCM to accommodate this requirement is for the upper VCM to use the value VCRP$T_DATA plus LAN$C_MAX_HDR_SIZE when allocating its transmit VCRPs. If more space is required for the LAN header plus any data from the upper VCM, then a larger allocation size can be used.

Note that the size required by the LAN driver (VCIB$W_DLL_HDR_SIZE) may be larger than the size of the header returned from the build header routine. The value returned by the build header routine should NOT be used as the amount of space needed by the LAN driver after the VCRP$T_DATA field. The size returned from the build header routine should ONLY be used to copy the LAN header into the transmit VCRP.

6.4.2 TRANSMIT CHAINING

The transmit chaining feature of the VCI can provide large CPU cycle gains. This feature allows the upper VCM to leave the user data in its own memory instead of copying the user data into the VCRP.

The basic rule for transmit is that the upper VCM must allow enough space after the VCRP$T_DATA field for the LAN header. The number of bytes required by the LAN driver is supplied to the upper VCM in the field VCIB$W_DLL_HDR_SIZE. Or the upper VCM can use the constant LAN$C_MAX_HDR_SIZE.

The two supported transmit request formats are:

To set up an unchained request, the upper VCM uses one VCRP and no DCBEs.

The following list describes the steps required to set up the fields for an unchained request. Other fields are also required; but these are the fields that are different for chained and unchained transmit requests.

To chain a DCBE to a VCRP, the upper VCM uses one VCRP and one DCBE.

When issuing a transmit chain request, the LAN driver requires that a certain number of bytes of the transmit frame be able to fit in the VCRP following the VCRP$T_DATA field. The upper VCM does not need to place this number of bytes in the VCRP, but the upper VCM must make sure that there is space for these bytes. The minimum number of bytes required to be able to fit in the VCRP varies across the different LAN devices. The LAN driver stores the minimum space required in the field VCIB$W_DLL_CHAIN_SIZE.

The following list describes the steps required to set up the fields for a chained request. Other fields are also required; but these are the fields that are different for chained and unchained transmit requests.

Table 6-1 describes the fields that are used for each of these transmit buffer formats.

Table 6-1 Transmit request fields
Field Name Unchain Chain Destroyed
VCRP$L_BOFF UI UI Y
VCRP$L_BCNT UI UI Y
DCBE$L_BOFF NA UO N
DCBE$L_BCNT NA UI N
DCBE$L_BUFFER_ADDRESS NA UO N
DCBE$L_SVAPTE NA UO N


Key to Unchain and Chain Key to Destroyed

For the chained format, the upper VCM either initializes the BOFF and SVAPTE fields in the DCBE or initializes the BUFFER_ADDRESS field in the DCBE. If the SVAPTE and BOFF fields are used, then the BUFFER_ADDRESS field is set to zero. If the BUFFER_ADDRESS field is used, then the SVAPTE and BOFF fields are set to zero.


Previous Next