%g
LAN VCI Specification
LAN VCI Specification
Chapter 4
DATA STRUCTURES
This section describes the data structures used by the VCI.
For efficiency, the LAN drivers require that the VCIB, VCRP, and DCBE
be quadword aligned. The upper VCM must ensure that these data
structures are quadword aligned.
All these data structures must exist in system space.
4.1 LAN BLOCK
The LAN block is a LAN driver data structure that is used by the upper
VCM for calling the access routines. The fields in this data structure
begin with LAN$.
The LAN block fields are defined by $LANUDEF in LANUDEF.MLB.
Table 4-1 describes the fields of the LAN block.
Table 4-1 LAN Block
|
ACCESS BY |
|
FIELD NAME |
UPPER |
LAN |
DESCRIPTION |
|
VCM |
DRIVER |
|
L_VERSION
|
R
|
W
|
LAN VCI version
|
A_GET_DEVICE
|
R
|
W
|
Address of Get Device routine
|
A_CREATE_PORT
|
R
|
W
|
Address of Create Port routine
|
A_DELETE_PORT
|
R
|
W
|
Address of Delete Port routine
|
Key to Access
- W: The module has read and write access to the field.
- R: The module has read access to the field.
Note that although the LAN block may exist, these fields may not be
initialized. These fields are initialized when the LAN$L_VERSION field
is non-zero. A detailed description of each of these LAN block fields
follows:
- LAN$L_VERSION
This field is used by the upper VCM to check that
the rest of the LAN block fields have been initialized and that the
version of the LAN block is compatible with their software. The upper
VCM must check that this field contains the value 1 before using the
other fields of the LAN block.
- LAN$A_GET_DEVICE
The LAN driver stores the address of the get
device routine in this field.
- LAN$A_CREATE_PORT
The LAN driver stores the address of the
create port routine in this field.
- LAN$A_DELETE_PORT
The LAN driver stores the address of the
delete port routine in this field.
4.2 LDC
The LDC is a LAN driver data structure that is used by the upper VCM to
acquire information about a LAN device. The fields in this data
structure begin with LDC$. The LDC data structure is quadword aligned
in memory.
The LDC fields are defined by $LDCDEF in LANUDEF.MLB.
Table 4-2 describes the fields of the LDC.
Table 4-2 LDC
|
ACCESS BY |
|
FIELD NAME |
UPPER |
LAN |
DESCRIPTION |
|
VCM |
DRIVER |
|
A_NAME
|
R
|
W
|
Address of device name string
|
(W)L_TYPE
|
R
|
W
|
Type of medium
|
(W)L_RCVSIZE
|
R
|
W
|
Minimum number receive ring entries
|
(B)L_DEVTYPE
|
R
|
W
|
VMS device type
|
Field name
If the field name begins with a letter in parentheses, then the letter
in the parentheses is used in the OpenVMS VAX name.
Key to Access
- W: The module has read and write access to the field.
- R: The module has read access to the field.
Remember that the address of the LDC is returned on calls to the
LAN$GET_DEVICE routine. The address of the LDC is also stored (by the
LAN driver on a call to VCI$LAN_CREATE_PORT) in the VCIB if the upper
VCM decides to use the device; so the upper VCM does not need to save
the LDC address in its own data structure. A detailed description of
each of these LDC fields follows:
- LDC$A_NAME
This field contains the address of a counted string
containing the device name. Note that this counted string is exactly
what is required to be passed to the CREATE_PORT routine in the
DLL$K_LAN_DEVICE item of the item list pointed to by
VCIB$A_DLL_INPUT_LIST. DLL$K_LAN_DEVICE is defined in $LANUDEF in
LANUDEF.MLB.
- LDC$W_TYPE
This field is used by the upper VCM to detect the
type of medium for this LAN device. The value stored in this field is
the same as the value stored in the field VCIB$W_DLL_TYPE. See
Section 4.3 for the list of values for that field.
- LDC$W_RCVSIZE
This field contains the minimum number of receive
buffers that are given to this device when there is sufficient
non-paged pool and CPU time to fill the device's receive buffer pool.
If there is insufficient non-paged pool or if there isn't enough CPU
time to keep the device's receive buffer pool full, then the actual
number of receive buffers owned by the device may be less than the
value stored in this field. The LAN driver is usually able to keep the
number of receive buffers given to the device at or above the number
stored in this field. The upper VCM can use this number to inform the
other nodes on the network how many packets to send to this node. Note
that no upper VCM should assume that it can have all these receive
buffers available at all times. The LAN is a shared medium. It is
suggested that no more than 75% of the receive buffers be used as a
pipeline.
- LDC$B_DEVTYPE
This field contains the VMS device type for this
device. This is the same as the value stored in the UCB$B_DEVTYPE field
for this device. The device types are listed in the LAN chapter of the
VMS I/O User's Manual and are defined in $DCDEF in STARLET.MLB.
4.3 VCIB
The VCI block is allocated, owned, and deallocated by the upper VCM.
Neither VCM is allowed to deallocate a VCI block while the VCI Port for
that VCIB is created. The LAN driver never deallocates the VCIB of an
upper VCM.
Note that there are fields in the VCIB that are initialized, used, and
referenced only by the LAN driver. The size of the VCIB as defined by
this specification is the size required by the LAN drivers. The upper
VCM is allowed to make the VCIB larger and define its own VCIB fields
in the portion of the VCIB following the size needed by the LAN
drivers. It is expected that most upper VCMs will do this to allow for
context required by the upper VCM.
The registered name for this data structure is VCIB$.
The VCIB fields are defined by $VCIBDEF in LIB.MLB and $VCIBDLLDEF in
LANUDEF.MLB.
Table 4-3 describes the fields of the VCIB structure.
Table 4-3 VCIB structure
|
ACCESS BY |
|
FIELD NAME |
UPPER |
LAN |
DESCRIPTION |
|
VCM |
DRIVER |
|
L_FLINK
|
W
|
N
|
Forward queue link
|
L_BLINK
|
W
|
N
|
Back queue link
|
W_SIZE
|
RI
|
N
|
Size of structure
|
B_TYPE
|
RI
|
R
|
Type of structure DYN$C_DECNET
|
B_SUB_TYPE
|
RI
|
R
|
Subtype of structure DYN$C_NET_VCI_VCIB
|
L_VCI_ID
|
RI
|
R
|
VCI ID of the upper VCM
|
W_VERSION_UPPER
|
RI
|
R
|
VCI version of the upper VCM
|
W_VERSION_LOWER
|
R
|
RI
|
VCI version of the LAN driver
|
A_PORTMGMT_INITIATE
|
R
|
I
|
Address of Port Management Initiate routine
|
A_PORTMGMT_COMPLETE
|
I
|
R
|
Address of Port Management Complete routine
|
A_TRANSMIT_INITIATE
|
R
|
I
|
Address of Transmit Initiate routine
|
A_TRANSMIT_COMPLETE
|
I
|
R
|
Address of Transmit Complete routine
|
A_RECEIVE_COMPLETE
|
I
|
R
|
Address of Receive Complete routine
|
A_REPORT_EVENT
|
I
|
R
|
Address of Report Event routine
|
A_DLL_INPUT_LIST
|
I
|
R
|
Address of input item list
|
(W)L_DLL_CLIENT_FLAGS
|
I
|
R
|
Flags specified by upper VCM
|
(W)L_DLL_FLAGS
|
R
|
I
|
Flags specified by LAN driver
|
(W)L_DLL_TYPE
|
R
|
I
|
Type of medium
|
(W)L_DLL_HDR_SIZE
|
R
|
I
|
Maximum header size in bytes
|
(W)L_DLL_XMT_SIZE
|
R
|
I
|
Maximum transmit size in bytes
|
(W)L_DLL_CHAIN_SIZE
|
R
|
I
|
Minimum size of 1st entry in chain in bytes
|
A_LAN_BUILD_HDR
|
R
|
I
|
Address of Build Header routine
|
A_LAN_TRANSMIT_FRAME
|
R
|
I
|
Address of Transmit Frame routine
|
A_LAN_TRANSMIT_AVAIL
|
R
|
I
|
Address of longword containing the number of transmit entries available
on the device
|
(W)L_LAN_MAX_RCV
|
I
|
R
|
Maximum number of outstanding receives allowed
|
(W)L_LAN_OUT_RCV
|
N
|
IW
|
Number of outstanding receives
|
(W)L_LAN_CLIENT_FLAGS
|
I
|
R
|
Flags specified by upper VCM
|
(W)L_LAN_FLAGS
|
R
|
I
|
Flags specified by LAN driver
|
A_LAN_LDC
|
R
|
I
|
Address of LDC structure
|
K_LAN_FIXED_LENGTH
|
C
|
C
|
Length of the required portion of the VCIB
|
Field name
If the field name begins with a letter in parentheses, then the letter
in the parentheses is used in the OpenVMS VAX name.
Key to Access
- C: Constant value.
- N: This module has no access to this field.
- W: The module has read and write access to the field.
- R: The module has read access to the field.
- I: This field is initialized by this module, this does not
imply that the module has access to the field after initialization.
A detailed description of each of these VCIB fields follows:
- VCIB$L_FLINK
This field is used only by the upper VCM. It may
be used to put the VCIB into a queue or for private storage.
- VCIB$L_BLINK
This field is used only by the upper VCM. It may
be used to put the VCIB into a queue or for private storage.
- VCIB$W_SIZE
This field is used only by the upper VCM. It should
be used to hold the size of the VCIB so it can be used during
deallocation of the VCIB.
- VCIB$B_TYPE
The upper VCM sets this field to the value
DYN$C_DECNET (defined in $DYNDEF in LIB.MLB).
- VCIB$B_SUB_TYPE
The upper VCM sets this field to the value
DYN$C_NET_VCI_VCIB (defined in $DYNDEF in LIB.MLB).
- VCIB$L_VCI_ID
The upper VCM sets this field to its VCI ID. The
VCI IDs are defined in $VCIBDEF in LIB.MLB. Note that there are some
VCI IDs for customer use. Table A-1 lists the registered VCI IDs.
- VCIB$W_VERSION_UPPER
For this version of the VCI, the upper VCM
sets this field to the value 1.
- VCIB$W_VERSION_LOWER
For this version of the VCI, the LAN
driver sets this field to the value 1.
- VCIB$A_PORTMGMT_INITIATE
The LAN driver stores the address of
the port management initiate routine in this field.
- VCIB$A_PORTMGMT_COMPLETE
The upper VCM stores the address of
the port management complete routine in this field.
- VCIB$A_TRANSMIT_INITIATE
The LAN driver stores the address of
the transmit initiate routine in this field.
- VCIB$A_TRANSMIT_COMPLETE
The upper VCM stores the address of
the transmit complete routine in this field.
- VCIB$A_RECEIVE_COMPLETE
The upper VCM stores the address of the
receive complete routine in this field.
- VCIB$A_REPORT_EVENT
The upper VCM stores the address of the
report event routine in this field.
- VCIB$A_DLL_INPUT_LIST
This field is initialized by the upper
VCM to contain the address of an input item list header (or the value
zero). The item list is used by the LAN driver to determine which LAN
device the upper VCM is trying to create a VCI port to. If this field
is zero, if the item list is empty, or if the LAN driver cannot find
the device name item in the list, then the LAN driver uses the first
LAN device. If the upper VCM wishes to specify a particular LAN device
for the LAN driver to use, then this field must point to an item list
header that contains one item; the DLL$K_LAN_DEVICE item.
The value
of the DLL$K_LAN_DEVICE item is the address of a counted string which
contains the device name of the device the upper VCM would like to use.
This item is used when the upper VCM knows the device name. The
DLL$K_LAN_DEVICE item is passed as a longword parameter where the
longword contains the address of a counted string which contains the
name of the device. Currently, all CSMACD and FDDI devices require a
three character device name. Note that the LAN$GET_DEVICE routine
returns the address of a counted string name of a device. This address
can be used as the DLL$K_LAN_DEVICE item list value.
DLL$K_LAN_DEVICE is defined in $LANUDEF in LANUDEF.MLB.
Note
that the item list structures are define in Section 4.6.
- VCIB$W_DLL_CLIENT_FLAGS
This field contains flags that are
initialized by the upper VCM. In this version, there are no flags
defined in this field. The upper VCM sets this field to zero.
- VCIB$W_DLL_FLAGS
This field contains flags that are initialized
by the LAN driver. The flags for this field include the following.
- VCIB$V_DLL_XMT_CHAIN - Initialized before PORT_USABLE. Set if the
LAN driver supports transmit chaining on this device, else cleared. If
set, the upper VCM is not allowed to issue a transmit chain request to
the LAN driver. Since OpenVMS AXP will support transmit chaining on all
devices, this flag will never be set on OpenVMS AXP. On OpenVMS VAX, if
this flag is set, the upper VCM is not allowed to issue transmit chain
requests to the LAN driver.
- VCIB$W_DLL_TYPE
This field is used by the upper VCM to know
which type of medium it is using. Possible values for this field
include:
- VCIB$K_DLL_CSMACD
- VCIB$K_DLL_FDDI
- VCIB$W_DLL_HDR_SIZE
This field is used by the upper VCM on
transmit requests. Before the PORT_USABLE event, the LAN driver
initializes this field to be the maximum number of bytes the LAN driver
may need for its transmit header. The upper VCM must leave at least
this much space before the data in its transmit VCRPs for the LAN
header. Note that the LAN header cannot be backfilled into the scratch
area of the VCRP. The LAN driver is not required to ensure that it does
not backfill its header into the scratch area of the VCRP. The upper
VCM must ensure that it leaves enough space for the LAN driver to
backfill its header without going into the scratch area of the VCRP.
Note that the constant LAN$C_MAX_HDR_SIZE can also be used by the
upper VCM. This constant represents the maximum header size for all LAN
drivers.
- VCIB$W_DLL_XMT_SIZE
This field is used by the upper VCM on
transmit requests. The LAN driver initializes this field before it
reports the PORT_USABLE event. The LAN driver initializes this field to
be the maximum number of bytes the upper VCM is allowed to transmit per
transmit request. The LAN driver is not required to ensure that the
upper VCM does not transmit more than the allowable number of bytes.
Note that this size does not include the LAN header. The contents of
this field are invalid after the upper VCM has disabled the port and
after the LAN driver has disabled the port. The field is again valid
after the port is re-enabled and the upper VCM receives the PORT_USABLE
event.
- VCIB$W_DLL_CHAIN_SIZE
This field is used by the upper VCM on
chained transmit requests. Before the PORT_USABLE event, the LAN driver
initializes this field to be the minimum number of bytes required in
the first buffer of a chained transmit. That is, this field is set to
the minimum number of bytes that must exist in the VCRP portion of a
chained request. This number includes the LAN header. The upper VCM is
required to ensure that at least this number of bytes are available in
the VCRP of a chained request.
The upper VCM may provide further
optimization by ensuring that the first buffer contains at least this
much data; instead of forcing the LAN driver to copy data from the
second buffer into this buffer. The performance improvement is realized
when the upper VCM copies the appropriate number of bytes from the
second buffer into the VCRP. It may cost the LAN driver more CPU time
to do the copy if the LAN driver has to initialize system PTEs to
perform the copy. The upper VCM may be able to do the copy when the
process is still current and the buffer is still available through
process space.
- VCIB$A_LAN_BUILD_HDR
The LAN driver stores the address of the
build header routine in this field.
- VCIB$A_LAN_TRANSMIT_FRAME
The LAN driver stores the address of
the transmit frame routine in this field.
- VCIB$A_LAN_TRANSMIT_AVAIL
This field is a pointer to a longword
containing the number of transmit entries available on the device. If
an upper VCM is using multiple devices, this can be used to determine
which device is less/more busy.
- VCIB$W_LAN_MAX_RCV
The upper VCM initializes this word to
contain the maximum number of outstanding receives the upper VCM wishes
to have. This field is only used if the VCIB$V_LAN_RCV_LIM flag is set
to 1.
- VCIB$W_LAN_OUT_RCV
This field is used solely by the LAN driver
to keep track of the number of outstanding receives. This field is only
used if the VCIB$V_LAN_RCV_LIM flag is set to 1.
- VCIB$W_LAN_CLIENT_FLAGS
This field contains flags that are
initialized by the upper VCM. All remaining bits of this flag field
must be set to zero.
- VCIB$V_LAN_RCV_LIM - If set to 1, the upper VCM wants the LAN
driver to limit the number of outstanding receive VCRPs being held by
the upper VCM. The VCIB$W_LAN_MAX_RCV and VCIB$W_LAN_OUT_RCV fields are
used to implement this feature. If set to 0, the upper VCM can have an
infinite number of outstanding receives.
- VCIB$V_LAN_RCV_ICS - Initialized to 0.
- VCIB$V_LAN_SFR - Skip field restore - This flag is ignored if the
VCIB$V_LAN_FTC flag is set to 1. If FTC=0 and SFR=0, the LAN driver
will save the BOFF, BCNT, and TOTAL_PDU_SIZE fields in the VCRP of
transmit requests. That is, these fields are not destroyed by the LAN
driver. This flag is initialized before the upper VCM creates the VCI
port. If FTC=1 or SFR=1, then these fields may be destroyed by the LAN
driver before the VCRP is returned to the upper VCM.
- VCIB$V_LAN_SCC - Skip completion check - The upper VCM sets this
flag to 1 if the VCIB$V_LAN_FTC flag is set to 0. This flag is ignored
if the VCIB$V_LAN_FTC flag is set to 1.
- VCIB$V_LAN_FTC - Fast transmit complete - If set to 1, the upper
VCM wishes to have fast transmit completion. If set to 1, the LAN
driver will not restore the BOFF, BCNT, and TOTAL_PDU_SIZE fields of
transmit requests.
- VCIB$W_LAN_FLAGS
This field contains flags that are initialized
by the LAN driver. In this version, there are no flags defined for this
field.
- VCIB$A_LAN_LDC
The address of the LDC structure. The upper VCM
can examine the fields in the LDC structure; but cannot write the LDC
fields. The LDC structure is defined in Section 4.2.
- VCIB$K_LAN_FIXED_LENGTH
This is a constant representing the
minimum size of the VCIB required for the LAN drivers.