NdisCoSendPackets

NdisCoSendPackets forwards a multipacket send on a particular VC to the underlying NIC driver for transmission over the network.

VOID 
  NdisCoSendPackets(
    IN NDIS_HANDLE  NdisVcHandle,
    IN PPNDIS_PACKET  PacketArray,
    IN UINT  NumberOfPackets
    );

Parameters

NdisVcHandle

Specifies the handle to the VC, thereby identifying the target of the send.

PacketArray

Pointer to an array of pointers to caller-allocated packet descriptors. Each packet descriptor in the array has chained buffer descriptors mapping buffers containing the data that the underlying NIC driver should transmit over the wire.

Each packet descriptor also has an associated NDIS_PACKET_OOB_DATA block, which the caller can set up with any timestamp and/or medium-specific out-of-band information relevant to the underlying driver and network medium.

NumberOfPackets

Specifies the number of pointers at PacketArray.

Headers

Declared in Ndis.h. Include Ndis.h.

Comments

A call to NdisCoSendPackets causes NDIS to call the NIC driver's MiniportCoSendPackets function. NDIS submits packet arrays to the underlying driver's MiniportCoSendPackets function in the same order as they are passed to NdisCoSendPackets. Before a protocol calls NdisCoSendPackets, it should set up the array of packet pointers in the same order as the packets should be sent over the wire.

The caller of NdisCoSendPackets should test the returned status for each packet descriptor in such an array individually when its ProtocolCoSendComplete function is called. While NDIS always submits packets for transmission in the FIFO order determined by the sending protocol, the underlying NIC driver might complete such sends in random order.

As soon as a protocol calls NdisCoSendPackets, it relinquishes ownership of the following:

• All packet descriptors accessible at PacketArray
• All buffers mapped by the buffer descriptors chained to those packet descriptors
• All out-of-band data blocks associated with the packet descriptors, including any medium-specific buffers specified in the OOB blocks

The allocating protocol regains ownership of these resources, one packet descriptor at a time, as its ProtocolCoSendComplete function is called with each packet descriptor in the array that it passed to NdisCoSendPackets.

Then, ProtocolCoSendComplete can either release the resources the protocol allocated or prepare these resources for reuse. During periods of average-to-high network I/O traffic, reusing the packet descriptors and buffers that a protocol allocates yields better performance than releasing buffers and the packet descriptor, only to reallocate them almost immediately for a subsequent send. However, any protocol that manages its usage of system resources carefully would not retain a large set of reusable packet descriptors with mapped buffers indefinitely after a period of high traffic falls into a sustained period of very low I/O demand. When ProtocolCoSendComplete reuses packet descriptors, it must save the buffer descriptors chained to each input packet descriptor with calls to an NdisUnchainBufferAtXxx function before it calls NdisReinitializePacket with the input packet descriptor.

Callers of NdisCoSendPackets can be running at IRQL <= DISPATCH_LEVEL.

See Also

MiniportCoSendPackets, NDIS_PACKET, NDIS_PACKET_OOB_DATA, NdisReinitializePacket, NDIS_SET_PACKET_MEDIA_SPECIFIC_INFO, NDIS_SET_PACKET_TIME_TO_SEND, NdisUnchainBufferAtBack, NdisUnchainBufferAtFront, ProtocolCoSendComplete