MiniportSendPackets

MiniportSendPackets

VOID
MiniportSendPackets(
IN NDIS_HANDLE MiniportAdapterContext,
IN PPNDIS_PACKET PacketArray,
IN UINT NumberOfPackets
);

MiniportSendPackets is a required function if the driver has neither a MiniportSend nor MiniportWanSend function. MiniportSendPackets transfers some number of packets, specified as an array of packet pointers, over the network.

Parameters

MiniportAdapterContext

Specifies the handle to a miniport-allocated context area in which the driver maintains per-NIC state, set up by MiniportInitialize.

PacketArray

Points to the initial element in a packet array, with each element specifying the address of a packet descriptor for a packet to be transmitted, along with an associated out-of-band data block containing information such as the packet priority, an optional timestamp, and the per-packet status to be set by MiniportSendPackets.

NumberOfPackets

Specifies the number of pointers to packet descriptors at PacketArray.

Comments

If a driver registers both MiniportSendPackets and MiniportSend functions when it initializes, NDIS always calls its MiniportSendPackets function.

The input packet packet descriptor pointers have been ordered according to the order in which the packets should be sent over the network by the protocol driver that set up the packet array. The NDIS library preserves the protocol-determined ordering when it submits each packet array to MiniportSendPackets.

Consequently, MiniportSendPackets should transmit each packet in any given array sequentially. MiniportSendPackets can call NdisQueryPacket to extract information, such as the number of buffer descriptors chained to the packet and the total size in bytes of the requested transfer. It can call NdisGetFirstBufferFromPacket, NdisQueryBuffer, or NdisQueryBufferOffset to extract information about individual buffers containing the data to be transmitted.

MiniportSendPackets can retrieve any protocol-supplied out-of-band information associated with each packet by using the relevant NDIS_GET_PACKET_TIME_TO_SEND and NDIS_GET_MEDIA_SPECIFIC_INFO macros.

Each protocol driver must set up packet arrays with packet descriptors that are fully set up to be passed by the underlying driver's MiniportSendPackets function to its NIC. That is, the protocol is responsible for determining what is required, based on the medium type selected by the miniport to which the protocol bound itself. However, a protocol can supply packets shorter than the minimum for the selected medium, which MiniportSendPackets must pad if its medium imposes a minimum-length requirement on transmits.

Any NDIS intermediate driver that layers itself between a higher-level protocol and an underlying NIC driver has the same responsibility as any protocol driver to set up packets according to the requirements of the underlying miniport and its selected medium. Such an intermediate driver must repackage each incoming send packet in a fresh packet descriptor that was allocated by the intermediate driver.

MiniportSendPackets can use only the eight-byte area at MiniportReserved within the NDIS_PACKET structure for its own purposes. Consequently, an NDIS intermediate driver that forwards send requests to an underlying NIC driver must repackage the packets given to its MiniportSendPackets function in fresh packet descriptors, which the intermediate driver allocates from packet pool, so that the underlying miniport has a MiniportReserved area it can use.

MiniportSendPackets sets one of the following values in the Status member of the NDIS_PACKET_OOB_DATA block associated with an input packet descriptor:

NDIS_STATUS_SUCCESS

The driver (or its NIC) has accepted the packet data for transmission, so MiniportSendPackets is returning the packet and the associated out-of-band data, which NDIS will return to the protocol that made this request.

NDIS_STATUS_PENDING

The driver will complete the transmit operation asynchronously with NdisMSendComplete.

NDIS_STATUS_RESOURCES

The miniport currently cannot set up the transmit operation due to resource constraints, so NDIS should queue this packet and all remaining packets in the given array for resubmission to MiniportSendPackets when the driver next calls NdisMSendResourcesAvailable or NdisMSendComplete.

When MiniportSendPackets sets this value for a packet in the input array, the NDIS library assumes all remaining packets in the array have the same status set, so NDIS requeues the associated packets in the same order, which preserves the protocol-determined ordering of the packet array. NDIS reflects this status to the protocol as NDIS_STATUS_PENDING for this packet and for all remaining packets in the given array.

NDIS_STATUS_FAILURE

The given packet was invalid or unacceptable to the NIC. Setting this status or any other driver-determined NDIS_STATUS_XXX error value for a packet effectively completes the packet, which NDIS returns to the allocating protocol as a failed send request.

When MiniportSendPackets returns control, the driver can no longer access anything in the given packet array with the following exceptions:

·If MiniportSendPackets set the Status for a packet to NDIS_STATUS_PENDING, the miniport can access the packet descriptor and any media-specific information in the associated out-of-band data block. MiniportSendPackets can use the buffer descriptors chained to that packet descriptor, as well.

After the driver calls NdisMSendComplete with the final status of the transmit operation, ownership of the given packet, out-of-band data block, and associated buffers reverts to the allocating protocol. A miniport should never return NDIS_STATUS_RESOURCES for a packet it passes to NdisMSendComplete.

·If MiniportSendPackets set the Status for a packet to NDIS_STATUS_RESOURCES, the miniport can access the packet, its associated out-of-band data block, and the buffer descriptors chained to that packet when NDIS resubmits the send request, along with subsequent elements of the packet array, to MiniportSendPackets.

Setting NDIS_STATUS_RESOURCES for an incoming packet causes NDIS to requeue the associated packet and those specified by all remaining array elements for subsequent resubmission to MiniportSendPackets. NDIS assumes that a subsequent call to NdisMSendResourcesAvailable or NdisMSendComplete, whichever occurs first, indicates that MiniportSendPackets is ready to accept more packets for transmission. NDIS preserves the original ordering of returned array elements when it resubmits them as a packet array to MiniportSendPackets.

If the underlying driver's MiniportQueryInformation function set the NDIS_MAC_OPTION_NO_LOOPBACK flag when the NDIS library queried the OID_GEN_MAC_OPTIONS, the miniport must not attempt to loop back any packets. The NDIS library provides software loopback support for such a driver.

By default, MiniportSendPackets runs at IRQL DISPATCH_LEVEL.