MiniportReturnPacket

The MiniportReturnPacket function is required in drivers that indicate receives with NdisMIndicateReceivePacket or NdisMCoIndicateReceivePacket.

VOID
  MiniportReturnPacket(
    IN NDIS_HANDLE  MiniportAdapterContext,
    IN PNDIS_PACKET  Packet
    );

Parameters

MiniportAdapterContext: Specifies the handle to a miniport driver-allocated context area in which the driver maintains per-NIC state, set up by MiniportInitialize.
Packet: Pointer to a packet descriptor being returned to the miniport driver, which previously indicated a packet array that contained this pointer.

Headers

Declared in Ndis.h. Include Ndis.h.

Comments

The following types of drivers must supply a MiniportReturnPacket function:

A miniport driver of a bus-master DMA NIC that supports multipacket receives. Such drivers include serialized miniports that export a MiniportSendPackets function, deserialized miniports, and connection-oriented miniports.
A miniport driver that supplies media-specific information, such as packet priorities, with its receive indications
An NDIS intermediate driver that binds itself to a miniport driver that supplies a MiniportReturnPacket function

For Serialized Drivers

Any receive packet with associated NDIS_PACKET_OOB_DATA structure in which the Status is set to NDIS_STATUS_PENDING on return from NdisMIndicateReceivePacket will be returned to MiniportReturnPacket. When all bound protocols have called NdisReturnPackets as many times as necessary to release their references to the originally indicated packet array, NDIS returns pended packets from the array to the MiniportReturnPacket function of the driver that originally allocated the packet array.

If the driver, before indicating up a receive packet descriptor with NdisMIndicateReceivePacket, set the Status member in the NDIS_PACKET_OOB_DATA associated with the descriptor to NDIS_STATUS_SUCCESS, the driver must check the packet's Status on return of NdisMIndicateReceivePacket:

If the Status is set to NDIS_STATUS_SUCCESS, the packet descriptor and associated buffer descriptors have been returned to the driver.
If the Status is set to NDIS_STATUS_PENDING, NDIS will return the packet descriptor to the driver's MiniportReturnPacket function.

For Deserialized and Connection-Oriented Drivers

If the driver, before indicating up a receive packet descriptor with NdisMIndicateReceivePacket or NdisMCoIndicateReceivePacket, sets the Status member in the NDIS_PACKET_OOB_DATA structure associated with the packet descriptor to NDIS_STATUS_SUCCESS, NDIS returns that packet descriptor to the driver's MiniportReturnPacket function. However, if the miniport driver sets the Status member to NDIS_STATUS_RESOURCES, thereby indicating that it needs to retain ownership of the packet descriptor and associated buffer descriptors, NDIS implicitly returns the packet descriptor to the driver on return of NdisM(Co)IndicateReceivePacket.

A deserialized or connection-oriented miniport driver must not examine the Status of indicated packets on return of NdisMIndicateReceivePacket. Instead, a deserialized miniport driver must save a packet’s Status in a local variable before indicating up the packet descriptor. When NdisMIndicateReceivePacket returns, the miniport driver should check the saved packet Status. If the miniport driver set the packet's Status to NDIS_STATUS_RESOURCES before indicating up the packet descriptor, it should reclaim the packet descriptor immediately after NdisMIndicateReceivePacket returns, preferably by calling its own MiniportReturnPacket function. In this case, NDIS does not call the miniport driver’s MiniportReturnPacket function to return the packet descriptor. If the miniport driver set the packet's Status to NDIS_STATUS_SUCCESS before indicating up the packet descriptor, the miniport driver must not reclaim the packet descriptor until NDIS subsequently returns the packet descriptor to the miniport driver's MiniportReturnPacket function.

For All Drivers

Usually, MiniportReturnPacket prepares such a returned packet to be used in a subsequent receive indication. Although MiniportReturnPacket could return the buffer descriptors chained to the packet to buffer pool and the packet descriptor itself to packet pool, it is far more efficient to reuse returned descriptors.

MiniportReturnPacket must call NdisUnchainBufferAtXxx as many times as necessary to save the pointers to all chained buffer descriptors before it calls NdisReinitializePacket. Otherwise, MiniportReturnPacket cannot recover the buffer descriptors the driver originally chained to the packet for the indication.

MiniportReturnPacket also can call NdisZeroMemory with the pointer returned by NDIS_OOB_DATA_FROM_PACKET to prepare the packet’s associated out-of-band block for reuse.

If a particular buffer descriptor was shortened to match the size of an indicated range of data, MiniportReturnPacket should call NdisAdjustBufferLength with that buffer descriptor to restore its mapping of the NIC’s receive buffer range.

MiniportReturnPacket runs at IRQL = DISPATCH_LEVEL.