Indicating a Receive Packet with an NdisMXxxIndicateReceive Function (NDIS 5.1)
Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.
Legacy connectionless miniport drivers that do not support NdisMIndicateReceivePacketcall a medium-specific NdisMXxxIndicateReceive function to indicate a single packet to higher drivers.
During initialization, a connectionless miniport driver's MiniportQueryInformationfunction is called to determine the miniport driver's or network interface card's (NIC) operational characteristics. These characteristics include the minimum size of the lookahead buffer that the miniport driver indicates up. The miniport driver must indicate up at least this minimum amount of data, but it can indicate up more if more data is available on the NIC. For example, because a DMA adapter transfers all the data directly into memory, it usually indicates the complete received buffer up. This makes it possible for a protocol driver to copy the buffer on the indication without having to call NdisTransferDatato get the rest of the data.
On the other hand, connectionless miniport drivers that manage programmed I/O (PIO) NICs pass a minimum lookahead buffer up to protocol drivers; the rest of the data is not read until the miniport driver is called at its MiniportTransferDatafunction. Because transferring data in this manner is slow, the miniport driver optimizes for the case that no protocol accepts the packet and that the minimum number of protocols request calls to MiniportTransferData.
A connectionless miniport driver that calls NdisMXxxIndicateReceive must have a MiniportTransferDatafunction and must be prepared to be called to copy incoming data into a packet with chained buffers passed down by a protocol driver. MiniportTransferDatais called in the context of the miniport driver's NdisMXxxIndicateReceive call. After NdisMXxxIndicateReceive returns control, the miniport driver can receive new data; that is, it can reenable receive interrupts.
MiniportTransferDatais passed a packet descriptor that can specify a single buffer or a chain of buffers. The miniport driver must divide up the incoming data into these buffers. If the buffers supplied by the protocol driver are insufficient, the miniport driver should fail the transfer call with an appropriate status. However, the protocol driver should not make this mistake because the miniport driver indicates the total size of the incoming network packet in its NdisMXxxIndicateReceive call. Data transfer can complete synchronously if all the data is transferred inside MiniportTransferData(see the following figure).
.png)
Otherwise, MiniportTransferDatacan return NDIS_STATUS_PENDING. If the miniport driver returns a pending status, it must call NdisMTransferDataCompleteafter all the data has been transferred (see the following figure). Again, the miniport driver must not reenable interrupts until the transfer of data has been completed so that the data already received is not overwritten by an incoming receive.
.png)
A miniport driver must periodically call NdisMXxxIndicateReceive, thereby causing NDIS to call each bound protocol drivers' ProtocolReceiveCompletefunction. The call to ProtocolReceiveCompletenotifies a protocol driver that it can process the data that it has already received but not yet fully processed. For example, the miniport driver could indicate the received data to its clients. A miniport driver should call NdisMXxxIndicateReceive in its MiniportHandleInterruptfunction after every ten receives or before exiting MiniportHandleInterruptif fewer than ten receives are processed.