MiniportFilterResourceRequirements routine

The MiniportFilterResourceRequirements function enables a miniport driver to modify the resource requirements for a device.

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

Syntax


MINIPORT_FILTER_RESOURCE_REQUIREMENTS MiniportFilterResourceRequirements;

NDIS_STATUS MiniportFilterResourceRequirements(
  _In_  NDIS_HANDLE MiniportAddDeviceContext,
  _In_  PIRP Irp
)
{ ... }

Parameters

MiniportAddDeviceContext [in]

A handle for a driver-allocated context area that the miniport driver registered with NDIS in the MiniportAddDevice function.

Irp [in]

The IRP_MN_FILTER_RESOURCE_REQUIREMENTS request for the miniport driver to handle.

Return value

MiniportFilterResourceRequirements returns one of the following values:

Return codeDescription
NDIS_STATUS_SUCCESS

The miniport driver handled the I/O request packet (IRP) request successfully.

NDIS_STATUS_RESOURCES

The miniport driver could not handle the IRP because of low resources.

NDIS_STATUS_FAILURE

MiniportFilterResourceRequirements failed for reasons other than insufficient resources.

 

Remarks

The MiniportFilterResourceRequirements function is an optional function. Miniport drivers should register this function if they support MSI-X and at least one of the following is true:

  • The driver requires the ability to change the interrupt affinity for each MSI-X message.

  • The driver will register for line-based interrupts in the MiniportInitializeEx function.

To register MiniportFilterResourceRequirements, specify the entry point in the NDIS_MINIPORT_PNP_CHARACTERISTICS structure.

NDIS calls the MiniportFilterResourceRequirements function after NDIS receives an IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRP for a network interface card (NIC). NDIS calls MiniportFilterResourceRequirements after the underlying function drivers in the device stack have completed the processing of the IRP.

The miniport driver must be prepared to handle IRP_MN_FILTER_RESOURCE_REQUIREMENTS from MiniportFilterResourceRequirements immediately after the MiniportAddDevice function returns NDIS_STATUS_SUCCESS.

A miniport driver can set an affinity policy for each resource of type CmResourceTypeInterrupt that describes an MSI-X message. If an affinity policy requests targeting for a specific set of processors, the miniport driver also sets a KAFFINITY mask at the Interrupt.TargetedProcessors member in the IO_RESOURCE_DESCRIPTOR structure.

If an NDIS 6.1 or later miniport driver requires more message interrupt resources, it can add more message interrupt resources to the resources list. If the operating system can provide more message interrupt resources, the miniport adapter receives the added message interrupt resources when it is started.

Each message interrupt resource in the list is assigned a message number that corresponds to the order it has in the resource list. The messages are numbered from 0 through the total number of message interrupt resources minus one.

To assign an MSI-X table entry to a CPU at run time, the miniport driver can call the NdisMConfigMSIXTableEntry function.

A miniport driver can remove all of the resources of type CmResourceTypeInterrupt that are message interrupt resources. The driver can then register for line-based interrupts in the MiniportInitializeEx function. If the miniport driver does not remove these message interrupt resources, the operating system will fail if the driver tries to register line-based interrupt in MiniportInitializeEx.

To allocate memory for a new resource-requirements list, use the NdisAllocateMemoryWithTagPriority function. The miniport driver can free the memory for the old resources-requirement list with the NdisFreeMemory function. The PnP manager frees any driver-allocated memory after the associated IRP is complete.

Miniport drivers should not modify other resources, such as CmResourceTypeMemory and CmResourceTypePort resources. Miniport drivers should avoid adding a new resource to the resource list. However, miniport drivers can add more message interrupt resources. If the miniport driver adds more message interrupt resources, the driver must not remove them from the MiniportStartDevice function.

If a miniport driver returns NDIS_STATUS_RESOURCES or NDIS_STATUS_FAILURE from MiniportFilterResourceRequirements, NDIS will use the resource requirements as specified by the parent bus driver.

NDIS can call MiniportFilterResourceRequirements several times before NDIS calls the MiniportRemoveDevice function. But NDIS calls MiniportFilterResourceRequirements only when a device is in the halted state.

NDIS calls MiniportFilterResourceRequirements at IRQL = PASSIVE_LEVEL.

Examples

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


MINIPORT_FILTER_RESOURCE_REQUIREMENTS MyFilterResourceRequirements;

Then, implement your function as follows:


_Use_decl_annotations_
NDIS_STATUS
 MyFilterResourceRequirements(
    NDIS_HANDLE  MiniportAddDeviceContext,
    PIRP  Irp
    )
  {...}

The MINIPORT_FILTER_RESOURCE_REQUIREMENTS 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_FILTER_RESOURCE_REQUIREMENTS 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

Version

Supported in NDIS 6.0 and later.

Header

Ndis.h (include Ndis.h)

IRQL

PASSIVE_LEVEL

See also

IO_RESOURCE_DESCRIPTOR
IRP_MN_FILTER_RESOURCE_REQUIREMENTS
KAFFINITY
MiniportAddDevice
MiniportInitializeEx
MiniportRemoveDevice
MiniportStartDevice
NDIS_MINIPORT_PNP_CHARACTERISTICS
NdisAllocateMemoryWithTagPriority
NdisFreeMemory
NdisMConfigMSIXTableEntry

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft