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

デバイスのリソース要件リストを表すフレームワーク リソース要件リスト オブジェクトへのハンドル。

[in] HostRoleResources

ホスト モードで動作しているコントローラー デバイスのリソース リストへのハンドル。

[in] FunctionRoleResources

コントローラーが関数モードで動作している場合の、コントローラーのリソース リストへのハンドル。

戻り値

操作が成功した場合、コールバック関数は STATUS_SUCCESS、またはNT_SUCCESS(status) が TRUE と等しい別の状態値を返す必要があります。 それ以外の場合は、NT_SUCCESS(status) が 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
Header ursdevice.h (Urscx.h を含む)
IRQL PASSIVE_LEVEL

こちらもご覧ください

ハードウェア リソースの処理

UrsDeviceInitialize

UrsIoResourceListAppendDescriptor

WdfIoResourceListRemove