EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS Rückruffunktion (ursdevice.h)

Die USB-Dual-Role-Klassenerweiterung ruft diesen Rückruf auf, damit der Clienttreiber die Ressourcen aus dem resource-requirements-list-Objekt in Ressourcenlisten einfügen kann, die während der Lebensdauer jeder Rolle verwendet werden.

Syntax

EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS EvtUrsDeviceFilterResourceRequirements;

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

Parameter

[in] Device

Ein Handle für das Framework-Geräteobjekt, das der Clienttreiber im vorherigen Aufruf von WdfDeviceCreate abgerufen hat.

[in] IoResourceRequirementsList

Ein Handle für ein Framework resource-requirements-list-Objekt, das die Ressourcenanforderungsliste eines Geräts darstellt.

[in] HostRoleResources

Ein Handle für eine Ressourcenliste für das Controllergerät, wenn es im Hostmodus ausgeführt wird.

[in] FunctionRoleResources

Ein Handle für eine Ressourcenliste für den Controller, wenn er im Funktionsmodus ausgeführt wird.

Rückgabewert

Wenn der Vorgang erfolgreich ist, muss die Rückruffunktion STATUS_SUCCESS oder einen anderen status Wert zurückgeben, für den NT_SUCCESS(status) gleich TRUE ist. Andernfalls muss ein status Wert zurückgegeben werden, für den NT_SUCCESS(status) gleich FALSE ist.

Hinweise

Der Clienttreiber registriert seine Implementierung bei der USB-Dual-Role-Klassenerweiterung, indem er UrsDeviceInitialize aufruft , nachdem WdfDeviceCreate aufgerufen wurde, um das Framework-Geräteobjekt für den Controller zu erstellen. Die Klassenerweiterung ruft diesen Rückruf vor EvtDevicePrepareHardware auf. Der Rückruf wird innerhalb der EvtDeviceFilterRemoveResourceRequirequirements der Klassenerweiterung aufgerufen, die im Auftrag des Clienttreibers registriert wird. Der Client darf seine EvtDeviceFilterRemoveResourceRequirequirements nicht implementieren und registrieren, da er die Implementierung der Klassenerweiterung überschreibt.

Jede Rolle verfügt über eine bestimmte Anzahl von zugewiesenen Hardwareressourcen. Diese Ressourcen können Arbeitsspeicher, Unterbrechungen usw. sein. Die Ressourcen werden vom System in einer Ressourcenanforderungsliste verwaltet, die den Bereich der Hardwareressourcen enthält, in denen das Gerät betrieben werden kann.

Weitere Informationen zu Ressourcenanforderungenslisten finden Sie unter Behandeln von Hardwareressourcen.

Die Klassenerweiterung ordnet Arbeitsspeicher für die Ressourcenanforderungsliste und Ressourcenlisten für Host- und Funktionsrollen zu. Wenn die Klassenerweiterung die Implementierung von EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS des Clienttreibers aufruft, übergibt sie ein WDFIORESREQLIST-Handle zusammen mit URSIORESLIST-Handles für Host- und Funktionsrollenressourcenlisten an diese Anforderungsliste. In der Implementierung wird erwartet, dass der Clienttreiber die logischen Konfigurationen in der Anforderungsliste aufzählt und den Ressourcendeskriptor für jede Konfiguration überprüft, indem WdfIoResourceListGetDescriptor aufgerufen wird.

Wenn der Treiber eine bestimmte Ressource verwenden möchte, kann er den zugeordneten Ressourcendeskriptor der entsprechenden Ressourcenliste hinzufügen, indem er UrsIoResourceListAppendDescriptor aufruft.

Um einen Ressourcendeskriptor aus der Anforderungsliste zu löschen, ruft der Treiber WdfIoResourceListRemove auf.

Beispiele

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;
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 10
Unterstützte Mindestversion (Server)	Windows Server 2016
Zielplattform	Windows
KMDF-Mindestversion	1.15
Kopfzeile	ursdevice.h (include Urscx.h)
IRQL	PASSIVE_LEVEL

Weitere Informationen

Behandeln von Hardwareressourcen

UrsDeviceInitialize

UrsIoResourceListAppendDescriptor

WdfIoResourceListRemove