i
LAN VCI Specification
LAN VCI Specification
4.4 VCRP
The VCRP is the data structure used to pass requests between two VCMs.
The VCRP contains request information and the completion status of that
request. There are basically two types of VCRPs; management VCRPs and
data VCRPs. Port Management requests use management VCRPs. Management
VCRPs contain a section that allows parameter buffers to be passed to
the LAN driver. Transmit and Receive requests use data VCRPs. Data
VCRPs contain a section that allow them to pass a packet between the
VCMs. For transmit VCRPs, the packet may be contained within the VCRP
or attached to the VCRP as a buffered or a direct I/O request.
The registered name for this data structure is VCRP$.
The VCRP fields are defined by $VCRPDEF in LIB.MLB and $VCRPLANDEF in
LANUDEF.MLB.
Table 4-4 describes the fields of the VCRP structure.
Table 4-4 VCRP structure
|
ACCESS ON |
|
FIELD NAME |
MGMT |
XMIT |
RECV |
DESCRIPTION |
L_FLINK
|
D
|
D
|
D
|
Forward queue link
|
L_BLINK
|
D
|
D
|
D
|
Back queue link
|
W_SIZE
|
UO
|
UO
|
LO
|
Size of structure
|
B_TYPE
|
UI
|
UI
|
LI
|
Type of structure DYN$C_VCRP
|
B_RMOD
|
UO
|
UO
|
UO
|
ACB - Request modifier
|
L_PID
|
UO
|
UO
|
UO
|
ACB - Process Identifier
|
A_ASTADR
|
UO
|
UO
|
UO
|
ACB - Address of user AST routine
|
L_ASTPRM
|
UO
|
UO
|
UO
|
ACB - Parameter for user AST routine
|
A_KAST
|
UO
|
UO
|
UO
|
ACB - Address of special kernel AST routine
|
W_COMMON_FLAGS
|
UI
|
UI
|
LI
|
Common flags for the request
|
B_FLAGS
|
UO
|
UO
|
UO
|
Request-specific flags
|
B_MODE
|
UO
|
UO
|
UO
|
Access mode - currently unused
|
A_DEALLOC_RTN
|
UO
|
UO
|
LI
|
Deallocation routine address
|
L_FUNCTION
|
UI
|
UI
|
LI
|
Function code
|
L_ASSOCIATION_ID
|
UO
|
UO
|
UO
|
Context for the creator of the VCRP
|
L_CONNECTION_ID
|
UO
|
UO
|
UO
|
Context for the creator of the VCRP
|
Q_REQUEST_STATUS
|
LI
|
LI
|
LI
|
Completion status of request
|
A_CREATOR
|
UO
|
UO
|
UO
|
Usually the VCIB address of the VCRP
|
Q_CREATOR_DATA
|
UO
|
UO
|
LO
|
Context for the creator of the VCRP
|
A_STACK
|
UO
|
UO
|
UO
|
Pointer to the context stack area
|
T_INTERNAL_STACK
|
UO
|
UO
|
UO
|
Internal context area
|
A_LAN_P2BUFF
|
UI
|
E
|
E
|
Address of address of P2 buffer
|
L_LAN_P2BUFF_SIZE
|
UI
|
E
|
E
|
Number of bytes in P2 buffer
|
A_DCB_LINK
|
E
|
UI
|
UO
|
Address of first DCBE
|
L_BOFF
|
E
|
UI
|
LI
|
Offset to data
|
L_BCNT
|
E
|
UI
|
LI
|
Number of bytes of packet in the VCRP
|
L_TOTAL_PDU_SIZE
|
E
|
UI
|
E
|
Number of bytes in all segments
|
(B)L_LAN_FC
|
E
|
UI
|
LI
|
FC field value
|
Q_LAN_T_DEST
|
E
|
UI
|
E
|
Destination address
|
L_LAN_802XMT
|
E
|
UD
|
E
|
802 only - overlay of next 3 fields
|
W_LAN_T_CTL
|
E
|
UD
|
E
|
802 only - control field value
|
B_LAN_T_CTL_SIZE
|
E
|
UD
|
E
|
802 only - control field value size
|
B_LAN_T_DSAP
|
E
|
UD
|
E
|
802 only - DSAP field value
|
(B)L_LAN_T_RESP
|
E
|
UD
|
E
|
802 only - response flag
|
A_LAN_R_HEADER
|
E
|
E
|
LI
|
Pointer to destination address of LAN header
|
T_SCRATCH
|
D
|
D
|
D
|
Scratch area
|
K_FIXED_LENGTH
|
C
|
C
|
C
|
Length of the required portion of the VCRP
|
T_DATA
|
A
|
A
|
A
|
Data area for data requests
|
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.
- A: Field is accessible to the current owner of the VCRP, but
its semantics are well defined and must be followed.
- D: Field is owned and can be destroyed by the current owner
of the VCRP.
- E: This field doesn't exist for this type of request.
- LI: The LAN driver initializes this field and the upper
VCM can read it.
- UI: The upper VCM initializes this field and the LAN
driver can read it.
- UD: The upper VCM initializes this field and the LAN
driver can set it to a default value.
- LO: Only the LAN driver has access to this field.
- UO: Only the upper VCM has access to this field.
All VCRP fields not defined in this specification should not be used by
the upper VCM for any purpose.
The fields marked with access UO are not described in the following
list. These fields are for the sole use of the upper VCM and the LAN
driver never accesses them. Most upper VCMs will use these fields for
private storage.
A detailed description of the remaining VCRP fields follows:
- VCRP$L_FLINK
This field is used by the VCM that currently owns
the VCRP. It is typically used to put the VCRP into a queue.
- VCRP$L_BLINK
This field is used by the VCM that currently owns
the VCRP. It is typically used to put the VCRP into a queue.
- VCRP$W_SIZE
This field is initialized by the VCM that allocated
the VCRP. It should be set to the size of the VCRP so it can be used
during deallocation of the VCRP.
- VCRP$B_TYPE
This field is initialized by the VCM that allocated
the VCRP. It should be set to the value DYN$C_VCRP (defined in $DYNDEF
in LIB.MLB).
- VCRP$W_COMMON_FLAGS
This flag field contains flags that are
common to all VCRPs. The flags used in this field follow. All remaining
bits of this flag field must be set to zero.
- VCRP$V_CMN_LOCKED - This flag is for transmit only. When set, this
flag indicates that user data has been locked down for a direct I/O.
This flag can be used by the upper VCM to keep track of direct I/O
transmit requests. The LAN drivers do not examine this flag on transmit
requests.
- VCRP$V_CMN_CACHE - When set indicates that this data structure is
from the owner's cache.
This flag is initialized and used only by
the owner of the structure. The owner of the structure can use the flag
to know if the structure was allocated from the owner's cache of data
structures. This provides a simple method for the owner to keep track
of the data structures being used.
The upper VCM can use this flag
in the VCRPs and DCBEs it allocates if it's useful to keep this context.
- VCRP$V_CMN_MGMT - When set indicates that this VCRP is for a
management request. When clear indicates that this VCRP is for a data
request. For port management requests, this flag is set to 1. For
transmit and receive requests, this flag must be clear.
- VCRP$A_DEALLOC_RTN
This field contains the address of a
deallocation routine to be used by the upper VCM when it is finished
with a receive VCRP. This field is only used in receive VCRPs. For
receive VCRPs, the LAN driver stores the address of a completion
routine in this field.
The deallocate routine is called at IPL8
with the IOLOCK8 spinlock as the highest spinlock taken out. The
address of the VCRP is in R3 and the deallocate routine can only
destroy R3.
This is the only way for an upper VCM to discard a
receive VCRP - it must call the DEALLOC_RTN routine. It cannot
deallocate the receive VCRP and it cannot pass it to the LAN driver any
other way.
- VCRP$L_FUNCTION
Function code for this request.
- For port management requests, the upper VCM sets this field to
either VCRP$K_FC_ENABLE_PORT, VCRP$K_FC_DISABLE_PORT, or
VCRP$K_FC_LAN_CHANGE_PORT.
- For transmit requests, the upper VCM sets this field to
VCRP$K_FC_TRANSMIT.
- For receive requests, the LAN driver sets this field to
VCRP$K_FC_RECEIVE.
- VCRP$Q_REQUEST_STATUS
This field contains the completion status
for the request. See Section 3.6 for more information.
- VCRP$Q_CREATOR_DATA
This field is used as private storage for
the VCM that allocated the VCRP.
- VCRP$T_INTERNAL_STACK
This field can be used by the upper VCM
as storage. Its size is VCRP$S_INTERNAL_STACK.
- VCRP$A_LAN_P2BUFF
This field contains the address of a longword
containing the address of the P2 buffer. The P2 buffer must be in
system space. The P2 buffer has the same format as the QIO
SETMODE!STARTUP P2 buffer. The P2 buffer is not to be modified or
deallocated by the upper VCM until the LAN driver returns the VCRP to
the upper VCM through the PORTMGMT_COMPLETE service routine.
For
more information about which parameters can be placed in the P2 buffer,
what values these parameters can have, and what the parameters mean,
see the LAN chapter of the VMS I/O User's Manual.
For VCI, there
are some restrictions on some of the P2 parameters. The following list
describes these restrictions. In future releases, some of these
restrictions may be lifted.
- NMA$C_PCLI_CRC - This parameter is passed with or defaulted to the
value NMA$C_STATE_ON. The CRC for the transmit packets cannot be
supplied by the upper VCM.
- NMA$C_PCLI_PRM - This parameter is passed with or defaulted to the
value NMA$C_STATE_OFF. Promiscuous mode is not supported through the
VCI.
- NMA$C_PCLI_ACC - For VCI ports using Ethernet format, this
parameter is passed with or defaulted to the value NMA$C_ACC_EXC.
Protocol sharing is not supported through the VCI.
- VCRP$L_LAN_P2BUFF_SIZE
This field contains the number of bytes
in the P2 buffer.
- VCRP$A_DCB_LINK
This field contains the address of a DCBE which
describes the next portion of a packet in a chained request. If there
are no more segments, then this field is set to zero.
- VCRP$L_BOFF
For the VCRP, this field contains the offset (in
bytes) from the beginning of the VCRP to the first byte of the data
embedded in this VCRP.
For the DCBE, this field may contain the
offset from the page pointed to by the SVAPTE field to the beginning of
the data.
- VCRP$L_BCNT
This field contains the number of bytes in the data
segment embedded in the VCRP.
- VCRP$L_TOTAL_PDU_SIZE
This field contains the number of bytes
in the entire packet including the embedded data and the data in all
the DCBEs chained to this VCRP.
- VCRP$B_LAN_FC
For receive requests, this field contains the FC
field value from the FDDI packet and contains the value zero for CSMACD
packets.
For FDDI transmit requests, this field is used if the XFC
parameter of the P2 buffer was set to the value zero. In this case,
this field should contain the priority bits (the low order three bits)
to be used in the FC field of the packet to be transmitted.
- VCRP$Q_LAN_T_DEST
The first six bytes of this field contain the
destination address. The last two bytes are unused by the LAN driver.
- VCRP$L_LAN_802XMT
This field is an overlay of the fields
VCRP$W_LAN_T_CTL, VCRP$B_LAN_T_CTL_SIZE, and VCRP$B_LAN_T_DSAP. The use
of these fields and this overlay is described in the following
paragraph.
The following four fields are initialized by the upper
VCM on transmit requests only if the port is an 802 port. If the CTL,
CTL_SIZE, and DSAP fields are all zero, then all four fields are
defaulted. If they are defaulted, then the default values are placed in
those fields by the LAN driver. This implies that these fields are only
destroyed by the LAN driver if they are defaulted. If they are
destroyed, they will contain the default values when the VCRP is
returned to the upper VCM through the TRANSMIT_COMPLETE service
routine. Note that the VCRP$W_LAN_T_CTL, VCRP$B_LAN_T_CTL_SIZE, and
VCRP$B_LAN_T_DSAP fields are contiguous (in that order) in the VCRP and
that they can be referenced as a longword using the field named
VCRP$L_LAN_802XMT.
- VCRP$W_LAN_T_CTL
If specified, this field contains the 802
control field value to be used by the LAN driver. The value is either
one byte or two bytes. The next field (VCRP$B_LAN_T_CTL_SIZE) contains
the number of bytes in this field. If this field is one byte, it's
passed in the low order byte. If this field is defaulted, it is
defaulted to the value 3 (Unnumbered Information).
- VCRP$B_LAN_T_CTL_SIZE
If specified, this field is used by the
LAN driver to detect the size of the control field value in the
VCRP$W_LAN_T_CTL field. If the low bit is clear, the CTL field is 2
bytes. If the low bit is set, the CTL field is 1 byte. If this field is
defaulted, it's defaulted to the value 1.
- VCRP$B_LAN_T_DSAP
If specified, this field contains the value
to be used in the DSAP field of the frame to be transmitted. If this
field is defaulted, it's defaulted to the SAP of the upper VCM's 802
port.
- VCRP$B_LAN_T_RESP
This field tells the LAN driver whether it
should transmit a response frame or a command frame. If the low order
bit is 1, then a response frame is transmitted. If the low order bit is
0, then a command frame is transmitted.
- VCRP$A_LAN_R_HEADER
This field contains the address of the
destination address field of the LAN header of the frame received. The
upper VCM can examine the header for the destination address and the
source address. The destination address is always the first 6 bytes of
the header and the source address is always the next 6 bytes of the
header.
- VCRP$T_SCRATCH
This field is scratch area and may be completely
destroyed by the current owner of the VCRP. The size of the scratch
area is VCRP$K_SCRATCH_AREA_LENGTH.
- VCRP$K_FIXED_LENGTH
This is a constant which represents the
minimum size VCRP excluding the space required for the data embedded in
transmit and receive VCRPs.
- VCRP$T_DATA This field represents the beginning of where packets
may be placed. Remember that for transmit requests, the upper VCM has
to leave enough space after this offset for the LAN header of the
packet. The value stored in the field VCIB$W_DLL_HDR_SIZE represents
the minimum size of the LAN header for this VCI port.
4.5 DCBE
The DCBE is used to connect a buffer containing part of a packet to a
VCRP. In the past, the data portion of a packet had to be copied into
the system data structure being used by the LAN driver. To prevent this
copying from occurring (to save CPU cycles), the DCBE was created. This
means that with the VCRP and the DCBE, one packet can span multiple
buffers. This is called chaining. The term chaining is used to
represent connecting a DCBE to a VCRP where the DCBE points to part of
a packet. Note that the LAN header is always contained in the VCRP, and
never in a DCBE.
Chaining is only possible in transmit VCRPs. Receive VCRPs always
contain all of the packet within the VCRP and Management VCRPs do not
have any fields that are allowed to point to a DCBE. Transmit VCRPs use
the field VCRP$A_DCB_LINK to point to a DCBE.
The registered name for this data structure is DCBE$.
The DCBE fields are defined by $DCBEDEF in LIB.MLB.
Table 4-5 describes the fields of the DCBE structure.
Table 4-5 DCBE structure
FIELD NAME |
ACCESS |
DESCRIPTION |
L_FLINK
|
D
|
Forward queue link
|
L_BLINK
|
D
|
Back queue link
|
W_SIZE
|
UO
|
Size of structure
|
B_TYPE
|
UI
|
Type of structure DYN$C_DECNET
|
B_SUB_TYPE
|
UI
|
Subtype of structure DYN$C_VCI_DCB
|
W_COMMON_FLAGS
|
UI
|
Common flags for the request
|
B_FLAGS
|
UO
|
Request-specific flags
|
B_MODE
|
UO
|
Access mode - currently unused
|
A_DEALLOC_RTN
|
UO
|
Deallocation routine address
|
A_DCB_LINK
|
UI
|
Address of next DCBE
|
L_SVAPTE
|
UI
|
System virtual address of PTE of data
|
L_BUFFER_ADDRESS
|
UI
|
System virtual address of data
|
L_BOFF
|
UI
|
Offset to data
|
L_BCNT
|
UI
|
Number of bytes of data in this buffer
|
K_DCB_HEADER
|
C
|
Length of the required portion of the DCBE
|
Key to Access
- C: Constant value.
- D: Field is owned and can be destroyed by the current owner
of the DCBE.
- UI: The upper VCM initializes this field and the LAN
driver can read it.
- UO: Only the upper VCM has access to this field.
The fields marked with access UO are not described in the following
list. These fields are for the sole use of the upper VCM and the LAN
driver never accesses them. A detailed description of the remaining
DCBE fields follows:
- DCBE$L_FLINK
This field is used by the VCM that currently owns
the DCBE. It is typically used to put the DCBE into a queue.
- DCBE$L_BLINK
This field is used by the VCM that currently owns
the DCBE. It is typically used to put the DCBE into a queue.
- DCBE$W_SIZE
This field is initialized by the VCM that allocated
the DCBE. It should be set to the size of the DCBE so it can be used
during deallocation of the DCBE.
- DCBE$B_TYPE
This field is initialized by the VCM that allocated
the DCBE. It should be set to the value DYN$C_DECNET (defined in
$DYNDEF in LIB.MLB).
- DCBE$B_SUB_TYPE
This field is initialized by the VCM that
allocated the DCBE. It should be set to the value DYN$C_VCI_DCB
(defined in $DYNDEF in LIB.MLB).
- DCBE$W_COMMON_FLAGS
See the description of VCRP$W_COMMON_FLAGS
in Section 4.4.
- DCBE$A_DCB_LINK
The field DCBE$A_DCB_LINK is always set to zero.
- DCBE$L_SVAPTE
This field may contain the system virtual address
of the page table entry that points to the first page of the segment.
- DCBE$L_BUFFER_ADDRESS
This field may contain the system virtual
address of the first byte of the data.
- DCBE$L_BOFF
See the description of VCRP$L_BOFF in Section 4.4.
- DCBE$L_BCNT
This field contains the number of bytes in the data
segment pointed to by the DCBE.
- DCBE$S_DCBEDEF
This is a constant representing the minimum size
of the DCBE.