OID_RECEIVE_FILTER_FREE_QUEUE

NDIS protocol drivers issue object identifier (OID) set requests of OID_RECEIVE_FILTER_FREE_QUEUE to free a receive queue.

The InformationBuffer member of the NDIS_OID_REQUEST structure contains a pointer to an NDIS_RECEIVE_QUEUE_FREE_PARAMETERS structure with a queue identifier of type NDIS_RECEIVE_QUEUE_ID.

Remarks

The OID set request of OID_RECEIVE_FILTER_FREE_QUEUE is optional for NDIS 6.20 and later miniport drivers. It is mandatory for miniport drivers that support the virtual machine queue interface.

After an overlying driver issues the OID_RECEIVE_FILTER_ALLOCATE_QUEUE OID to allocate a receive queue, it issues the OID_RECEIVE_FILTER_FREE_QUEUE OID to free the receive queue.

When NDIS requests a miniport driver to free a VMQ receive queue, it follows these steps:

  1. The network adapter stops the DMA transfer of data to receive buffers that are associated with the receive queue, after which the queue must enter the DMA Stopped state. The network adapter probably stopped the DMA activity when it received the OID_RECEIVE_FILTER_CLEAR_FILTER OID request to clear the last set filter on the receive queue.

  2. The miniport driver generates an NDIS_STATUS_RECEIVE_QUEUE_STATE status indication with the QueueState member of the NDIS_RECEIVE_QUEUE_STATE structure set to NdisReceiveQueueOperationalStateDmaStopped to notify NDIS that the DMA transfer has been stopped.

  3. The miniport driver waits for all the indicated receive packets for that queue to be returned to the miniport driver.

  4. The miniport driver frees all the shared memory that it allocated for the network adapter's receive buffers that are associated with the queue by calling NdisFreeSharedMemory.

  5. The miniport driver completes the OID_RECEIVE_FILTER_FREE_QUEUE OID request to free the receive queue.

Miniport drivers call the NdisFreeSharedMemory function to free shared memory for a queue. If the miniport driver allocated the shared memory for a nondefault queue, the driver frees the shared memory in the context of the OID_RECEIVE_FILTER_FREE_QUEUE OID while it is freeing the queue. Miniport drivers free shared memory that they allocated for the default queue in the context of the MiniportHaltEx function.

An overlying driver must free all the filters that it set on a queue before it frees the queue. Also, an overlying driver must free all the receive queues that it allocated on a network adapter before it calls the NdisCloseAdapterEx function to close a binding to the network adapter. NDIS frees all the queues that are allocated on a network adapter before it calls the miniport driver's MiniportHaltEx function.

Return Status Codes

The miniport driver's MiniportOidRequest function returns one of the following values for this request:

TermDescription

NDIS_STATUS_SUCCESS

The miniport driver completed the request successfully.

NDIS_STATUS_PENDING

The miniport driver will complete the request asynchronously. After the miniport driver has completed all processing, it must succeed the request by calling the NdisMOidRequestComplete function, passing NDIS_STATUS_SUCCESS for the Status parameter.

NDIS_STATUS_NOT_ACCEPTED

The miniport driver is resetting.

NDIS_STATUS_REQUEST_ABORTED

The miniport driver stopped processing the request. For example, NDIS called the MiniportResetEx function.

 

NDIS returns one of the following status codes for this request:

Status codeDescription

NDIS_STATUS_SUCCESS

The requested queue was freed successfully.

NDIS_STATUS_PENDING

The request is pending completion. NDIS will pass the final status code and results to the OID request completion handler for the caller after the request has completed.

NDIS_STATUS_INVALID_PARAMETER

The queue identifier is invalid.

NDIS_STATUS_INVALID_LENGTH

The information buffer is too short. NDIS sets the DATA.METHOD_INFORMATION.BytesNeeded member in the NDIS_OID_REQUEST structure to the minimum buffer size that is required.

 

Requirements

Version

Supported in NDIS 6.20 and later.

Header

Ntddndis.h (include Ndis.h)

See also

MiniportHaltEx
NDIS_OID_REQUEST
NDIS_RECEIVE_QUEUE_FREE_PARAMETERS
NDIS_STATUS_RECEIVE_QUEUE_STATE
NdisCloseAdapterEx
NdisFreeSharedMemory
OID_RECEIVE_FILTER_ALLOCATE_QUEUE

 

 

Send comments about this topic to Microsoft

Show: