g
LAN VCI Specification
LAN VCI Specification
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
|
- LIL$L_LISTLEN
This field contains the size (in bytes) of the
items; not including the header (not including the fields up to and
including LIL$B_SUBTYPE).
- LIL$A_LISTADR
This field contains the address of the list of
items. This is usually the address of the LIL$T_DATA field.
- LIL$W_SIZE
This field contains the size (in bytes) of this
structure (from the LISTLEN field to the end of the DATA section). If
the item (DATA) section is part of the allocated memory, then this size
field should include that section also. This field is typically used
when deallocation occurs.
- LIL$B_TYPE
This field contains the type of structure. This
field should contain the value DYN$C_DECNET (defined in $DYNDEF in
LIB.MLB).
- LIL$B_SUBTYPE
This field contains the type of structure. This
field should contain the value DYN$C_NET_ITEM (defined in $DYNDEF in
LIB.MLB).
- LIL$T_DATA
This field marks the position in this structure
where the items in the list can be placed.
In general, the items in
the list can (and usually do) begin at the LIL$T_DATA field. However,
the item list header allows the items to be placed in a separate buffer.
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
|
- LIL$W_ITEMLEN
This field contains the number of bytes in the
item. This includes the ITEMLEN, ITEMTAG, and ITEMVAL fields; so the
smallest number this field can contain is 4 (in the case where the size
of the value field is zero bytes).
- LIL$W_ITEMTAG
This field contains the tag for the item. The tag
is used to identify the item.
- LIL$T_ITEMVAL
The value for the item is stored in this field.
The number of bytes required to store the value and the format of the
value depends on the 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).
- Use the Fast Transmit Complete feature by setting the
VCIB$V_LAN_FTC flag in the VCIB$W_LAN_CLIENT_FLAGS field of the VCIB.
This allows the LAN driver to use the most efficient method to complete
transmit requests to the upper VCM.
- The upper VCM should not check if a receive VCRP has a success
status in the VCRP$Q_REQUEST_STATUS field. The LAN driver only
completes receive VCRPs with success status values to the upper VCM.
- Use the build header routine to get a LAN header. In most cases,
this routine can be called once during the life of the VCI port. Once
the upper VCM gets the LAN header, the upper VCM should pre-pended it
to all packets it transmits and use the transmit frame service routine.
This saves CPU cycles because the LAN driver doesn't have to build a
LAN header for every packet transmitted; it only needs to initialize
the destination address field, possibly a length field, and (for FDDI
only) the FC field (if the P2 parameter XFC was set to zero on the
enable port request).
- The upper VCM can prevent copying transmit data by using the
transmit chaining feature. By not copying the data, fewer CPU cycles
are used.
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.
- VCRP$B_RMOD
- VCRP$L_PID
- VCRP$A_ASTADR
- VCRP$L_ASTPRM
- VCRP$L_KAST
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.
- 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.
- 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.
- 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.
- 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.
- Remember that the enable port request is completed asynchronously.
So when control is returned to the upper VCM, it should dismiss its
fork thread.
- 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.
- 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.
- 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.
- With the change port VCRP ready, the upper VCM calls the LAN
driver's port management routine to change the VCI port.
- The change port request is completed asynchronously. So when
control is returned to the upper VCM, it should dismiss its fork thread.
- 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.
- 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.
- 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.
- With the disable port VCRP ready, the upper VCM calls the LAN
driver's port management routine to disable the VCI port.
- Remember that the disable port request is completed asynchronously.
So when control is returned to the upper VCM, it should dismiss its
fork thread.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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:
- VCRP$L_BOFF is set to the offset from the beginning of the VCRP to
the upper VCM's data in the VCRP. Remember to leave enough space for
the LAN header.
- VCRP$L_BCNT is set to the number of bytes of data in the VCRP.
- VCRP$L_TOTAL_PDU_SIZE is set to VCRP$L_BCNT (plus DCBE$L_BCNT if
this is a chained request).
- VCRP$Q_LAN_DEST is set to the destination address.
- VCRP$L_LAN_802XMT and VCRP$B_LAN_T_RESP are initialized if the VCI
port has been started with the 802 format.
- VCRP$B_LAN_FC is set to the priority bits of the FC field if this
an FDDI device and the upper VCM set the XFC P2 parameter to zero.
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:
- VCRP$L_BOFF is set to the offset from the beginning of the VCRP to
the LAN header that has been placed in the VCRP.
- VCRP$L_BCNT is set to the number of bytes of data in the VCRP (for
this case, it includes the LAN header).
- VCRP$L_TOTAL_PDU_SIZE is set to VCRP$L_BCNT (plus DCBE$L_BCNT if
this is a chained request)
- VCRP$Q_LAN_DEST is set to the destination address.
- VCRP$B_LAN_FC is set to the priority bits of the FC field if this
an FDDI device and the upper VCM set the XFC parameter to zero.
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:
- UNCHAINED - In this format there is a VCRP with no attached buffer
or DCBE. All the data to be transmitted is in the VCRP.
- CHAINED - In this format there is a VCRP with embedded data and a
DCBE with attached data. In this case, the user data embedded in the
VCRP can consist of zero bytes; but the upper VCM still initializes the
VCRP$L_BCNT and VCRP$L_BOFF fields of the VCRP.
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.
- The packet is placed into the VCRP. There are usually three parts
to the packet; the LAN header, the upper VCM's header, and the data.
The upper VCM's header begins at VCRP$T_DATA + header size (where
header size is either LAN$C_MAX_HDR_SIZE or the contents of
VCIB$W_DLL_HDR_SIZE). The upper VCM copies its header and the data into
the VCRP. If it has the LAN header (from a previous call to BUILD_HDR),
then the upper VCM can copy the LAN header into the VCRP; placing it
just before upper VCM's header.
- Set VCRP$L_BOFF to be the number of bytes to either the LAN header
(if the LAN header has been copied into the VCRP) or to the upper VCM's
header.
- Set VCRP$L_BCNT to be equal to the number of bytes that have been
placed in the VCRP; including the LAN header if it has been copied into
the VCRP.
- Set VCRP$L_TOTAL_PDU_SIZE to the value in VCRP$L_BCNT.
- Set VCRP$A_DCB_LINK to zero.
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.
- The VCRP that the upper VCM allocates for a chained transmit
request cannot be smaller than VCRP$T_DATA plus the contents of
VCIB$W_DLL_CHAIN_SIZE. When the upper VCM calculates the size required
for the LAN header and any of its data, it makes sure that size is not
smaller than VCRP$T_DATA plus the contents of VCIB$W_DLL_CHAIN_SIZE.
- Some of the packet is placed into the VCRP. Usually just the
headers are placed in the VCRP; specifically the LAN header and the
upper VCM's header. The upper VCM's header begins at VCRP$T_DATA +
header size (where header size is either LAN$C_MAX_HDR_SIZE or the
contents of VCIB$W_DLL_HDR_SIZE). The upper VCM copies its header into
the VCRP. If it has the LAN header (from a previous call to BUILD_HDR),
then the upper VCM can copy the LAN header into the VCRP; placing it
just before upper VCM's header.
Note that if LAN$C_MAX_HDR_SIZE is
not defined, then the constant 58 (decimal) can be used.
- Set VCRP$L_BOFF to be the number of bytes to either the LAN header
(if the LAN header has been copied into the VCRP) or to the upper VCM's
header.
- Set VCRP$L_BCNT to be equal to the number of bytes that have been
placed in the VCRP; including the LAN header if it has been copied into
the VCRP.
- Set VCRP$A_DCB_LINK to point to the DCBE.
- Set either DCBE$L_BUFFER_ADDRESS or both DCBE$L_SVAPTE and
DCBE$L_BOFF to point to the data. If DCBE$L_SVAPTE and DCBE$L_BOFF
point to the data, then DCBE$L_BUFFER_ADDRESS is set to zero.
- Set DCBE$L_BCNT to be equal to the number of bytes pointed to by
the DCBE.
- Set VCRP$L_TOTAL_PDU_SIZE to the value in VCRP$L_BCNT plus the
value in DCBE$L_BCNT.
- Set DCBE$A_DCB_LINK to zero.
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
- UI - Initialized by the upper VCM
- UO - Optionally initialized by the upper VCM
- NU - Not used by the LAN driver
- NA - Not applicable to this buffer format
Key to Destroyed
- Y - Destroyed by the LAN driver
- N - Not destroyed by the LAN driver
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.