MINIPORT_MESSAGE_INTERRUPT_DPC

MINIPORT_MESSAGE_INTERRUPT_DPC callback function

A miniport driver must provide a MiniportMessageInterruptDPC handler if the driver calls the NdisMRegisterInterruptEx function to register an interrupt.

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

Syntax


MINIPORT_MESSAGE_INTERRUPT_DPC MiniportMessageInterruptDPC;

VOID MiniportMessageInterruptDPC(
  _In_ NDIS_HANDLE MiniportInterruptContext,
  _In_ ULONG       MessageId,
  _In_ PVOID       MiniportDpcContext,
  _In_ PVOID       ReceiveThrottleParameters,
  _In_ PVOID       NdisReserved2
)
{ ... }

Parameters

MiniportInterruptContext [in]

A handle to a block of interrupt context information. The miniport driver supplied this handle in the MiniportInterruptContext parameter that the miniport driver passed to the NdisMRegisterInterruptEx function.

MessageId [in]

A message-signaled interrupt (MSI) message identifier. MessageId is an index to an IO_INTERRUPT_MESSAGE_INFO_ENTRY structure inside a IO_INTERRUPT_MESSAGE_INFO structure. NDIS passes a pointer to the associated IO_INTERRUPT_MESSAGE_INFO structure in the MessageInfoTable member when the driver successfully registers for MSI with the NdisMRegisterInterruptEx function.

MiniportDpcContext [in]

A pointer to a context area that the miniport driver supplied when it called the NdisMQueueDpcEx or NdisMQueueDpc function. If NDIS called MiniportMessageInterruptDPC because the miniport driver returned a bitmask in the TargetProcessors parameter of the MiniportMessageInterrupt function, then MiniportDpcContext is NULL.

ReceiveThrottleParameters [in]

A pointer to an NDIS_RECEIVE_THROTTLE_PARAMETERS structure specifies the maximum number of NET_BUFFER_LIST structures that a miniport driver should indicate in a DPC.

Note  In NDIS 6.1 and earlier, this parameter is named NdisReserved1, its datatype is PULONG, and it is reserved for NDIS.
 
NdisReserved2 [in]

Reserved for NDIS.

Note  In NDIS 6.1 and earlier, this parameter's datatype is PULONG.
 

Return value

None

Remarks

Miniport drivers that register a message-signaled interrupt with the NdisMRegisterInterruptEx function must provide a MiniportMessageInterruptDPC function.

NDIS calls MiniportMessageInterruptDPC to complete the deferred processing of an interrupt. The miniport driver can call the NdisMQueueDpcEx or NdisMQueueDpc function to request additional deferred procedure calls (DPCs) for other processors.

Miniport drivers determine the source of each interrupt and take appropriate action. For example, if an interrupt indicates the completion of a transmit operation, the miniport driver completes a pending send request. If the cause of the interrupt is a change in link state, the miniport driver indicates the new link status to NDIS. If there are outstanding receive packets, the miniport driver indicates the packets to NDIS.

A miniport driver that supports receive side scaling (RSS), and has the feature enabled, examines its receive queues in MiniportMessageInterruptDPC. The NIC could have already queued received packets on separate queues based on hash values, if the NIC provides such capabilities. Otherwise, the miniport driver can sort the packets into separate queues in MiniportMessageInterruptDPC.

MiniportMessageInterruptDPC calls the NdisMIndicateReceiveNetBufferLists function to indicate the packets on the current processor. MiniportMessageInterruptDPC can determine processing that is required for other CPUs and request NDIS to schedule DPCs on CPUs where a DPC is not outstanding.

If the current DPC is running on the same CPU as the MiniportMessageInterrupt function, the miniport driver should indicate all of the packets that could not be mapped to a CPU. If this DPC is the last scheduled DPC and it will not request additional DPCs, MiniportMessageInterruptDPC should reenable the interrupts on the NIC, for the specified message, before it returns.

Before NDIS calls MiniportMessageInterruptDPC, interrupts for the specified message on the NIC, have typically been disabled in the MiniportMessageInterrupt function. Before it returns control, MiniportMessageInterruptDPC can reenable interrupts. If the miniport driver queued additional DPCs while interrupts were disabled, the driver should enable the interrupts after the last DPC executes.

Note  For better performance, miniport drivers should only disable interrupts for specific messages. They should not disable all message-signaled interrupts.
 

Miniport drivers should limit the number of the receive buffers that they indicate while they are processing an interrupt DPC batch to complete within the required time limit. An interrupt DPC batch is the collection of all the DPCs that run after the ISR and before the interrupts are reenabled.

A miniport driver can call NdisMDeregisterInterruptEx from its MiniportInitializeEx or MiniportHaltEx function to release resources that it allocated with NdisMRegisterInterruptEx. After NdisMDeregisterInterruptEx returns, NDIS does not call a miniport driver's MiniportMessageInterrupt or MiniportMessageInterruptDPC function.

NDIS calls MiniportMessageInterruptDPC at IRQL = DISPATCH_LEVEL.

Examples

To define a MiniportMessageInterruptDPC 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 MiniportMessageInterruptDPC function that is named "MyMessageInterruptDPC", use the MINIPORT_MESSAGE_INTERRUPT_DPC type as shown in this code example:


MINIPORT_MESSAGE_INTERRUPT_DPC MyMessageInterruptDPC;

Then, implement your function as follows:


_Use_decl_annotations_
VOID
 MyMessageInterruptDPC(
    NDIS_HANDLE  MiniportInterruptContext,
    ULONG  MessageId,
    PVOID  MiniportDpcContext,
    PVOID  ReceiveThrottleParameters,
    PVOID  NdisReserved2
    )
  {...}

The MINIPORT_MESSAGE_INTERRUPT_DPC function type is defined in the Ndis.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 MINIPORT_MESSAGE_INTERRUPT_DPC 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

Target platform

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

DISPATCH_LEVEL

See also

IO_INTERRUPT_MESSAGE_INFO
IO_INTERRUPT_MESSAGE_INFO_ENTRY
MiniportHaltEx
MiniportInitializeEx
MiniportMessageInterrupt
NDIS_MINIPORT_INTERRUPT_CHARACTERISTICS
NDIS_RECEIVE_THROTTLE_PARAMETERS
NdisMDeregisterInterruptEx
NdisMQueueDpc
NdisMQueueDpcEx
NdisMIndicateReceiveNetBufferLists
NdisMRegisterInterruptEx
NET_BUFFER_LIST
Receive Side Scaling (RSS)

 

 

Send comments about this topic to Microsoft

Show:
© 2016 Microsoft