Packet Reuse in a Protocol Driver (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.
If a connectionless protocol driver uses NdisSend, ownership of protocol-allocated packet resources for sends reverts to the protocol driver when the call to NdisSendcompletes. The call is complete when NdisSendreturns anything other than NDIS_STATUS_PENDING or when NDIS calls the driver's ProtocolSendCompletefunction. After the call is complete, the protocol driver can reclaim the returned packet resources for subsequent sends or for copying received data in ProtocolReceive.
Ownership of protocol-allocated packet resources for sends also reverts to the protocol driver when a call to NdisSendPacketsor NdisCoSendPacketscompletes. The call is complete when the driver's ProtocolSendCompleteor ProtocolCoSendCompletefunction is called once for each packet descriptor in the array that it passed to NdisSendPacketsor NdisCoSendPackets.
It is more efficient for a protocol driver to reinitialize and reuse the packet descriptor and buffers than to deallocate these resources and then later reallocate them again for a subsequent send or data-transfer operation. A protocol usually exhibits better performance if it saves unchained buffer descriptors and buffers for reuse rather than deallocating and reallocating such resources.
A protocol driver calls NdisReinitializePacketto reinitialize a packet descriptor. First, the protocol driver should take care to remove any chained buffers and their buffer descriptors by calling NdisUnchainBufferAtXxx to release the buffer descriptors and the buffers mapped by these descriptors. Otherwise, NdisReinitializePacketsets the member that points to the chained buffer descriptors to NULL. Therefore, reinitializing the packet descriptor without first releasing and saving the chained buffer descriptors will cause a memory leak. Similarly, if the protocol and underlying driver use out-of-band (OOB) information, the resources specified in the OOB data block associated with each packet descriptor must be reclaimed before a call to NdisReinitializePacket.