Multipacket Sends from Serialized Miniport Drivers (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.
Each packet descriptor has associated out-of-band (OOB) data, as described in Packet Out-of-Band Data. The OOB block lets a protocol driver specify a time-to-send ( TimeToSend) to a cooperating miniport driver that supports priority sends. The Statusmember of the OOB block is set by a serialized miniport driver before returning from MiniportSendPacketsto indicate the return value of the call. The other members of the NDIS_PACKET_OOB_DATA block are read-only to the miniport driver.
A serialized miniport driver that provides MiniportSendPacketsand returns NDIS_STATUS_PENDING for one or more packets must save the pointers to the individual packets for which it returns this pending status. When MiniportSendPacketsreturns, the array containing the pointers will be returned to the caller.
A serialized miniport driver that does not have the resources to send a packet can set the Statusmember to NDIS_STATUS_RESOURCES. In this case, NDIS queues the packets and then resubmits them to the miniport driver when it completes a send by calling NdisMSendCompleteor calls NdisMSendResourcesAvailable, whichever is called first.
NDIS assumes that, if NDIS_STATUS_RESOURCES is set for one element, it is set for all subsequent array elements. In effect, the miniport driver relinquishes ownership, temporarily or permanently, of any packet in an array of packets for which it sets a Statusother than NDIS_STATUS_PENDING before returning from MiniportSendPackets. Otherwise, the miniport driver owns those packet resources until it later relinquishes ownership by calling NdisMSendComplete, passing the final status of the send as a parameter to this call.
Instead of returning NDIS_STATUS_RESOURCES when it does not have the resources to send a packet, a serialized miniport driver can queue the send request internally. The miniport driver can use the miniport driver-reserved fields in the packet header to link queued packets, which may be linked to its adapter-specific context structure. If the miniport driver queues a packet, it must return NDIS_STATUS_PENDING as the status for the queued packet. To increase throughput, the miniport driver might implement packet queuing to avoid the latency incurred when the packet is returned to NDIS and later resubmitted to the miniport driver.
A serialized miniport driver sets the Statusfield of every packet before it returns from MiniportSendPackets, whether the packet is completed synchronously or asynchronously.
If a serialized miniport driver completes the send synchronously, it should set the Statusmember of the OOB data in the packet with the status of the send, which is NDIS_STATUS_SUCCESS, NDIS_STATUS_FAILURE, NDIS_STATUS_RESOURCES, or a miniport driver-determined status. The miniport driver sets the Statusmember to NDIS_STATUS_PENDING if it keeps the packet and therefore will complete the send later. If the miniport driver returns a status of NDIS_STATUS_RESOURCES for a packet in the array, NDIS requeues that packet and any following packets in the array and submits them later when the miniport driver indicates that it has available resources.
After MiniportSendPacketsreturns, the Statusfield of the OOB data is unavailable. Therefore, when a serialized miniport driver completes a packet for which it has previously returned NDIS_STATUS_PENDING, the miniport driver must return the status of the send in the Statusparameter of its call to NdisMSendComplete. The miniport driver must not write the Statusmember of the OOB data for any packets that are completed by calling NdisMSendComplete.