EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS回调函数 (ursdevice.h)

  • 项目

USB 双角色类扩展调用此回调，以允许客户端驱动程序将资源从 resource-requirements-list 对象插入到将在每个角色的生存期内使用的资源列表。

语法

EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS EvtUrsDeviceFilterResourceRequirements;

NTSTATUS EvtUrsDeviceFilterResourceRequirements(
  [in] WDFDEVICE Device,
  [in] WDFIORESREQLIST IoResourceRequirementsList,
  [in] URSIORESLIST HostRoleResources,
  [in] URSIORESLIST FunctionRoleResources
)
{...}

参数

[in] Device

客户端驱动程序在上一次调用 WdfDeviceCreate 时检索到的框架设备对象的句柄。

[in] IoResourceRequirementsList

表示设备资源要求列表的框架 resource-requirements-list 对象的句柄。

[in] HostRoleResources

控制器设备在主机模式下运行时的资源列表的句柄。

[in] FunctionRoleResources

控制器在函数模式下运行时的资源列表的句柄。

返回值

如果操作成功，回调函数必须返回STATUS_SUCCESS，或NT_SUCCESS (状态) 等于 TRUE 的另一个状态值。 否则，它必须返回一个状态值，NT_SUCCESS (状态) 等于 FALSE。

注解

客户端驱动程序通过在调用 WdfDeviceCreate 后调用 UrsDeviceInitialize 为控制器创建框架设备对象，向 USB 双角色类扩展注册其实现。 类扩展在 EvtDevicePrepareHardware 之前调用此回调。 回调在类扩展的 EvtDeviceFilterRemoveResourceRequirements 中调用，该调用代表客户端驱动程序注册。 客户端不得实现和注册其 EvtDeviceFilterRemoveResourceRequirements ，因为它将替代类扩展的实现。

每个角色都有一定数量的已分配硬件资源。 这些资源可以是内存、中断等。 资源由系统在 资源要求列表中 维护，其中包含设备可以运行的硬件资源范围。

有关资源要求列表的详细信息，请参阅 处理硬件资源。

类扩展为 资源要求列表 分配内存，并为主机角色和函数角色分配 资源列表 。 当类扩展调用客户端驱动程序的 EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS 实现时，它将 WDFIORESREQLIST 句柄以及主机和函数角色 资源列表的 URSIORESLIST 句柄传递到该要求列表。 在实现中，客户端驱动程序应枚举要求列表中的逻辑配置，并通过调用 WdfIoResourceListGetDescriptor 来检查每个配置的资源描述符。

如果驱动程序要使用特定资源，则可以通过调用 UrsIoResourceListAppendDescriptor 将关联的资源描述符添加到相应的资源列表中。

若要从要求列表中删除资源描述符，驱动程序会调用 WdfIoResourceListRemove。

示例


EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS EvtUrsFilterRemoveResourceRequirements;


_Function_class_(EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS)
_IRQL_requires_same_
_IRQL_requires_max_(PASSIVE_LEVEL)
NTSTATUS
EvtUrsFilterRemoveResourceRequirements (
    _In_ WDFDEVICE Device,
    _In_ WDFIORESREQLIST IoResourceRequirementsList,
    _In_ URSIORESLIST HostRoleResources,
    _In_ URSIORESLIST FunctionRoleResources
    )
{
    NTSTATUS status;
    WDFIORESLIST resList;
    ULONG resListCount;
    ULONG resCount;
    ULONG currentResourceIndex;
    PIO_RESOURCE_DESCRIPTOR descriptor;
    BOOLEAN assignToHost;
    BOOLEAN assignToFunction;
    BOOLEAN keepAssigned;

    TRY {

        status = STATUS_SUCCESS;

        //
        // Currently does not support multiple logical configurations. Only the first one
        // is considered.
        //

        resListCount = WdfIoResourceRequirementsListGetCount(IoResourceRequirementsList);
        if (resListCount == 0) {
            // No logical resource configurations found.
            LEAVE;
        }

        // Enumerate through logical resource configurations.

        resList = WdfIoResourceRequirementsListGetIoResList(IoResourceRequirementsList, 0);
        resCount = WdfIoResourceListGetCount(resList);


        for (currentResourceIndex = 0; currentResourceIndex < resCount; ++currentResourceIndex) {

            descriptor = WdfIoResourceListGetDescriptor(resList, currentResourceIndex);

            if (descriptor->Type == CmResourceTypeConfigData) {

                //
                // This indicates the priority of this logical configuration.
                // This descriptor can be ignored.
                //

                keepAssigned = TRUE;
                assignToFunction = FALSE;
                assignToHost = FALSE;

            } else if ((descriptor->Type == CmResourceTypeMemory) ||
                       (descriptor->Type == CmResourceTypeMemoryLarge)) {

                //
                // This example client driver keeps the memory resources here. 
                //

                keepAssigned = TRUE;
                assignToFunction = TRUE;
                assignToHost = TRUE;

            } else {

                //
                // For all other resources, pass it to the child device nodes for host and function.
                //

                keepAssigned = FALSE;
                assignToHost = TRUE;
                assignToFunction = TRUE;
            }

            if (assignToHost != FALSE) {
                status = UrsIoResourceListAppendDescriptor(HostRoleResources, descriptor);
                if (!NT_SUCCESS(status)) {
                    // UrsIoResourceListAppendDescriptor for HostRoleResources failed.
                    LEAVE;
                }
            }

            if (assignToFunction != FALSE) {
                status = UrsIoResourceListAppendDescriptor(FunctionRoleResources, descriptor);
                if (!NT_SUCCESS(status)) {
                    // UrsIoResourceListAppendDescriptor for FunctionRoleResources failed.
                    LEAVE;
                }
            }

            if (keepAssigned == FALSE) {
                WdfIoResourceListRemove(resList, currentResourceIndex);
                --currentResourceIndex;
                --resCount;
            }
        }

    } FINALLY {
    }

    return status;
}

要求

要求 值
最低受支持的客户端 Windows 10
最低受支持的服务器 Windows Server 2016
目标平台 Windows
最低 KMDF 版本 1.15
标头 ursdevice.h (包括 Urscx.h)
IRQL PASSIVE_LEVEL

另请参阅

处理硬件资源

UrsDeviceInitialize

UrsIoResourceListAppendDescriptor

WdfIoResourceListRemove