Protocol Driver Packet Management (NDIS 5.1)
Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.
A protocol driver must manage packet pools and data buffer pools while sending and receiving data. The driver uses packet pools to manage packet descriptors and buffer pools to manage buffer descriptors.
Packet descriptors can be allocated as needed, when the driver initializes, or at binding time. You can allocate packet descriptors with chained buffer descriptors at initialization time to hold receive packets that occur immediately after the protocol binds itself to an underlying miniport driver. In this case, the ProtocolReceivefunction must return control to the underlying driver as quickly as possible. Otherwise, subsequently received data can be lost.
A connectionless protocol driver can receive incoming data from an underlying miniport driver from either its ProtocolReceivePacketfunction or ProtocolReceivefunction. Data received with ProtocolReceivePacketis a packet descriptor specifying a full network packet. Data indicated to ProtocolReceivemust be copied into a protocol-supplied buffer chained to a protocol-allocated packet descriptor. A connection-oriented protocol always receives incoming data at its ProtocolCoReceivePacketfunction.
Every connectionless protocol driver must provide a ProtocolReceivefunction. When NDIS calls this function, the protocol driver must copy the indicated lookahead data into a protocol-allocated buffer, chained to a preallocated packet descriptor. The protocol must pass the descriptor to NdisTransferData. This call passes the packet descriptor to the underlying miniport driver which adds any additional data that it received, beyond the indicated lookahead data.
If a protocol driver binds itself only to underlying NDIS drivers that indicate arrays of packets with NdisMCoIndicateReceivePacket, ProtocolCoReceivePacketneed not provide packet descriptors, buffers, and buffer descriptors for incoming data.
When NDIS indicates a full network packet to a protocol driver's Protocol(Co)ReceivePacket function, the driver can give clients direct read-only access to the buffered data. The protocol driver provides such access until the clients consume the data and release the packet descriptor and all its resources. When the protocol driver takes ownership of such packet resources, it is not required to copy data into a preallocated packet or call NdisTransferData.
If a protocol driver supplies a packet descriptor with more than one chained buffer to NdisTransferData, NdisSendPackets, or NdisCoSendPackets, and the length of actual data in the last buffer is less than the allocated length of its buffer, the protocol driver should call NdisAdjustBufferLengthto set the actual length of the data in the buffer descriptor. When NDIS returns the packet descriptor to the protocol driver, the driver should readjust the buffer descriptor's specified length to the full length of the buffer.
The following topics contain additional information about protocol driver packet management:
Allocating Packet Pools and Buffer Pools in a Protocol Driver
Packet Reuse in a Protocol Driver