NDIS_PD_QUERY_QUEUE_DEPTH callback function (ndis.h)

Article
10/21/2021

The PacketDirect (PD) platform calls a PD-capable miniport driver's PDQueryQueueDepth function to return the number of unprocessed PD_BUFFER structures that are posted to the Queue.

Note You must declare the function by using the NDIS_PD_QUERY_QUEUE_DEPTH type. For more information, see the following Examples section.

Syntax

NDIS_PD_QUERY_QUEUE_DEPTH NdisPdQueryQueueDepth;

VOID() NdisPdQueryQueueDepth(
  [in]  const NDIS_PD_QUEUE *Queue,
  [out] ULONG64 *Depth
)
{...}

Parameters

[in] Queue

A pointer to a transmit or receive queue.

[out] Depth

On a receive queue, this is the number of PD_BUFFER structures that are available for placing incoming packets into. For example, if 10 buffers were posted, and 3 of the 10 have already been fetched by the provider for placing incoming packets into, this value should be 7. On a transmit queue, this is the number of PD_BUFFER structures that the provider has not yet fetched from the queue for transmitting.

Return value

This callback function does not return a value.

Remarks

Note For IHV partners: The ability to monitor the queue depth is very important for clients to access congestion build-up and take precautionary action. An increasing queue depth for a transmit queue is a sign of increasing congestion on the outbound link. A decreasing queue depth for an RX queue is a sign of the client not being able to process incoming packets fast enough on the inbound link. Clients may need to monitor the queue depth status with frequently (For example, getting the queue depth for each post and operation, therefore the cost (in CPU cycles) of querying the queue depth must not be noticeable in comparison to the cost of a single PDPostAndDrainBufferList call.

Examples

To define a PDQueryQueueDepth function, you must first provide a function declaration that identifies the type of function you're defining. Windows provides a set of function types for drivers. Declaring a function using the function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it's a requirement for writing drivers for the Windows operating system.

For example, to define a PDQueryQueueDepth function that is named "MyPDQueryQueueDepth", use the NDIS_PD_QUERY_QUEUE_DEPTH type as shown in this code example:

NDIS_PD_QUERY_QUEUE_DEPTH MyPDQueryQueueDepth;

Then, implement your function as follows:

_Use_decl_annotations_
VOID
 MyPDQueryQueueDepth(
    CONST NDIS_PD_QUEUE*  Queue,
    ULONG64*  Depth
    )
  {...}

The NDIS_PD_QUERY_QUEUE_DEPTH function type is defined in the Ntddndis.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the Use_decl_annotations annotation to your function definition. The Use_decl_annotations annotation ensures that the annotations that are applied to the NDIS_PD_QUERY_QUEUE_DEPTH function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for NDIS Drivers.

For information about Use_decl_annotations, see Annotating Function Behavior.

Requirements

Requirement	Value
Minimum supported client	Windows 10
Minimum supported server	Windows Server 2016
Target Platform	Windows
Header	ndis.h
IRQL	<= DISPATCH_LEVEL

Share via