Allocating a VM Queue

To allocate a queue with an initial set of configuration parameters, an overlying driver issues an OID_RECEIVE_FILTER_ALLOCATE_QUEUE method OID request. The InformationBuffer member of the NDIS_OID_REQUEST structure initially contains a pointer to an NDIS_RECEIVE_QUEUE_PARAMETERS structure. After a successful return from the OID method request, the InformationBuffer member of the NDIS_OID_REQUEST structure contains a pointer to an NDIS_RECEIVE_QUEUE_PARAMETERS structure that has a new queue identifier and an MSI-X table entry.

The NDIS_RECEIVE_QUEUE_PARAMETERS structure is used in the OID_RECEIVE_FILTER_ALLOCATE_QUEUE OID and the OID_RECEIVE_FILTER_QUEUE_PARAMETERS OID. For more information about VM queue parameters, see Obtaining and Updating VM Queue Parameters.

The overlying driver initializes the NDIS_RECEIVE_QUEUE_PARAMETERS structure with the following queue configuration parameters:

• The queue type (NdisReceiveQueueTypeVMQueue from the NDIS_RECEIVE_QUEUE_TYPE enumeration.)

• The processor affinity for the queue.

• The queue name and the virtual machine name.

• The lookahead-split parameters.

  Note  Starting with NDIS 6.30, splitting packet data into separate lookahead buffers is no longer supported.

Note  The overlying driver can set the NDIS_RECEIVE_QUEUE_PARAMETERS_PER_QUEUE_RECEIVE_INDICATION and NDIS_RECEIVE_QUEUE_PARAMETERS_LOOKAHEAD_SPLIT_REQUIRED flags in the Flags member of the NDIS_RECEIVE_QUEUE_PARAMETERS structure. The other flags are not used for queue allocation.

When NDIS receives an OID request to allocate a receive queue, it verifies the queue parameters. After NDIS allocates the necessary resources and the queue identifier, it submits the OID request to the underlying miniport driver. The queue identifier is unique to the associated network adapter.

If the miniport driver can successfully allocate the necessary software and hardware resources for the receive queue, it completes the OID request with a success status.

Before NDIS sends the OID request to the miniport driver, NDIS assigns a queue identifier in the QueueId member of the NDIS_RECEIVE_QUEUE_PARAMETERS structure and passes the method request to the miniport driver. The miniport driver provides the MSI-X table entry in the MSIXTableEntry member.

The miniport driver must retain the queue identifiers for the allocated receive queues. NDIS uses the queue identifier of a receive queue for subsequent calls to the miniport driver to set a receive filter on the receive queue, change the receive queue parameters, or free the receive queue.

Note  The default queue (queue identifier zero) is always allocated and cannot be freed.

The overlying driver must use the queue identifier that NDIS provides in subsequent OID requests, for example, to modify the queue parameters or free the queue. The queue identifier is also included in the OOB data on all NET_BUFFER_LIST structures that are associated with the queue. Drivers use the NET_BUFFER_LIST_RECEIVE_QUEUE_ID macro to retrieve the queue identifier in a NET_BUFFER_LIST structure.

Note  A protocol driver can set VMQ filters at any time after it successfully allocates a queue and before the queue is deleted.

The protocol driver issues an OID_RECEIVE_FILTER_QUEUE_ALLOCATION_COMPLETE method OID request to complete the queue allocation. The miniport driver can allocate shared memory and other resources when the allocation is complete. For more information about allocating shared memory resources, see Shared Memory Resource Allocation.

After a miniport driver receives an OID_RECEIVE_FILTER_QUEUE_ALLOCATION OID request and handles it successfully, the queue is in the Allocated state. For more information about queue states, see Queue States and Operations.

After an overlying driver allocates one or more receive queues (and optionally sets the initial filters), it must issue OID_RECEIVE_FILTER_QUEUE_ALLOCATION_COMPLETE set OID requests to notify the miniport driver that the allocation is complete for the current batch of receive queues.

The miniport driver must not retain any packets in a receive queue if there are no filters set on that queue. If a queue never had any filters set or all the filters were cleared, the queue should be empty and any packets should be discarded. That is, they are not indicated up the driver stack or retained in the queue.

Overlying drivers use the OID_RECEIVE_FILTER_FREE_QUEUE OID to free queues that they allocate. For more information about freeing queues, see Freeing a VM Queue.