NDIS_SET_PACKET_STATUS(
IN PNDIS_PACKET Packet,
IN NDIS_STATUS Status
);
NDIS_SET_PACKET_STATUS sets the Status value in the out-of-band data block associated with a given packet descriptor just before a driver calls NdisMIndicateReceivePacket or before a driver’s MiniportSendPackets function returns control.
For packet descriptors used in receive indications, the value can be either of the following:
Protocols that receive the indication can use the packet descriptor, along
with all buffers mapped by buffer descriptors chained to the packet descriptor
and any out-of-band information supplied with the packet, to copy the
indicated net packet data, possibly forwarding the processed copy to
interested clients.
Setting this status forces bound protocols to return ownership of each such packet descriptor, of any medium-specific buffer in the out-of-band data block for each packet descriptor, and of the memory mapped by each packet descriptor’s respective chained buffer descriptors to the indicating driver more quickly. The protocols must wait for a call to their ProtocolReceiveComplete functions to begin postprocessing the data they copied from the indication and forwarding the processed data to their clients.
An indicating driver can set this status if it is running low on packet pool or buffer pool. An indicating NIC driver usually sets this status if it is running low on NIC receive buffers due to high network traffic. A busmaster DMA NIC driver might call NdisMAllocateSharedMemoryAsync in these circumstances to get additional NIC receive buffer space.
NDIS assumes that, if this status is set for a packet in an indicated array, it is set for all subsequent packets in that array. Consequently, an indicating driver need not set the status for subsequent packet descriptors in an array after it sets this status in the out-of-band data block for one packet descriptor.
For packet descriptors used in sends, MiniportSendPackets can set one of the following values:
After MiniportSendPackets returns control, the driver will call NdisMSendComplete
with a final completion status for the given packet descriptor, which NDIS
propagates to the ProtocolSendComplete function of the driver that allocated
the resources specified by the packet descriptor and initiated the send.
NDIS assumes that the Status member for all subsequent packet
descriptors in the array given to MiniportSendPackets is set to the same
value. NDIS queues these packet descriptors internally in the same order for
resubmission to MiniportSendPackets when the driver calls NdisMSendResourcesAvailable
or NdisMSendComplete, whichever call occurs first. NDIS reflects this
miniport-set status value to protocols as NDIS_STATUS_PENDING.
Whether such a send packet is completed with NDIS_STATUS_SUCCESS or a driver-determined error status, MiniportSendPackets must set the Status member for the given packet descriptor so that NDIS can reflect this status back to the protocol that initiated the send when NDIS calls ProtocolSendComplete with the returned packet descriptor.
Only drivers that indicate receives with NdisMIndicateReceivePacket to bound protocols and/or drivers that have MiniportSendPackets functions use the NDIS_SET_PACKET_STATUS macro.
After such an underlying driver has set the Status for some number of packet descriptors in an array and called NdisMIndicateReceivePacket with the array of pointers to those packet descriptors, it must use the NDIS_GET_PACKET_STATUS macro when NdisMIndicateReceivePacket returns control. The returned Status in the NDIS_PACKET_OOB_DATA block associated with each packet descriptor that the driver indicated with NDIS_STATUS_SUCCESS determines what the indicating driver does next, as follows:
The driver can prepare these descriptors, the out-of-band block, and
media-specific information buffer, if any, for reuse in subsequent receive
indications immediately.
When the MiniportSendPackets function sets the Status for an incoming send packet to anything other than NDIS_STATUS_PENDING or NDIS_STATUS_RESOURCES, it completes the packet and relinquishes ownership to all resources specified by the associated packet descriptor. NDIS returns the packet descriptor to the ProtocolSendComplete function of the allocating driver and propagates the miniport-set status value as an input parameter to ProtocolSendComplete. Otherwise, the underlying driver will call NdisMSendComplete with the packet descriptor and final status when the asynchronous send operation is done.
Protocol drivers should never test the Status value in an associated out-of-band data block on return from NdisSendPackets or NdisSend. NDIS or the underlying driver retains ownership of the packet descriptor, of the associated out-of-band block and any buffers specified in this block, and of all buffers mapped by buffer descriptors chained to the packet descriptor until the ProtocolSendComplete function is called with the packet descriptor.
Callers of NDIS_SET_PACKET_STATUS run at IRQL <= DISPATCH_LEVEL.
MiniportHandleInterrupt, MiniportReturnPacket, MiniportSendPackets, MiniportTimer, NdisAllocatePacket, NDIS_GET_PACKET_STATUS, NdisMAllocateSharedMemoryAsync, NdisMIndicateReceivePacket, NdisMSendComplete, NDIS_OOB_DATA_FROM_PACKET, NDIS_PACKET_OOB_DATA, NdisSend, NdisSendPackets, NDIS_SET_PACKET_HEADER_SIZE, NDIS_SET_PACKET_MEDIA_SPECIFIC_INFO, NDIS_SET_PACKET_TIME_RECEIVED, NDIS_SET_PACKET_TIME_SENT, ProtocolSendComplete