MiniportSendPackets (Windows Embedded CE 6.0)

Article
01/05/2012

1/6/2010

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

Syntax

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

Parameters

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

PacketArray
[in]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
[in]Specifies the number of pointers to packet descriptors at PacketArray.

Return Value

None.

Remarks

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

The protocol driver that sets up the packet array established the order of the input packet descriptor pointers using the order in which the packets should be sent over the network. 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.

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.

Whether the driver is serialized or deserialized determines how its MiniportSendPackets function handles the completion of input packet descriptor(s) when this driver function is called.

Serialized Miniports

The MiniportSendPackets function of a serialized driver sets the value of the Status member of the NDIS_PACKET_OOB_DATA block associated with an input packet descriptor. The following table shows the possible status values.

Value	Description
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 serialized 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. 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 re-queues 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, a serialized driver can no longer access anything in the given packet array with the following exceptions:

Status set to NDIS_STATUS_PENDING
In this case, 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 descriptor, 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.
Status set to NDIS_STATUS_RESOURCES
In this case, the miniport can access the packet descriptor, the 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 re-queue the associated packet and all remaining array elements for subsequent resubmission to the MiniportSendPackets function of a serialized driver. NDIS assumes that a subsequent call to NdisMSendResourcesAvailable or NdisMSendComplete, whichever occurs first, indicates that such a driver's MiniportSendPackets function 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.

Deserialized Miniports

The NDIS library ignores the OOB block in all packet descriptors it submits to the MiniportSendPackets functions of deserialized drivers. It also assumes that all deserialized miniports will complete each packet descriptor input to their MiniportSendPackets functions asynchronously with NdisMSendComplete. Consequently, such a deserialized driver's MiniportSendPackets function usually ignores the Status member of the NDIS_PACKET_OOB_DATA block, but it can set this member to the same status as it subsequently passes to NdisMSendComplete.

Rather than relying on NDIS to queue and resubmit packets whenever MiniportSendPackets has insufficient resources, a deserialized miniport manages its own internal packet queuing. The following list shows the responsibilities of a deserialized miniport.

Hold incoming send packets in its internal queue until they can be transmitted over the network
Preserve the protocol-determined ordering of packet descriptors incoming to its MiniportSendPackets function.
Complete each incoming send packet with NdisMSendComplete.
Never call NdisMSendResourcesAvailable.
Never pass STATUS_INSUFFICIENT_RESOURCES to NdisMSendComplete with a protocol-allocated packet descriptor that was originally submitted to its MiniportSendPackets function. Such a returned status effectively fails the send operation requested by the protocol, and NDIS would return the packet descriptor and all associated resources to the protocol that originally allocated it.
Synchronize access to its internal queue(s) of packet descriptors with the driver's other MiniportXxx functions that also access the same queue(s).

Requirements

Header	externs.h
Windows Embedded CE	Windows CE .NET 4.0 and later