EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS fonction de rappel (ursdevice.h)

Article
08/07/2023

L’extension de classe double rôle USB appelle ce rappel pour permettre au pilote client d’insérer les ressources de l’objet resource-requirements-list dans les listes de ressources qui seront utilisées pendant la durée de vie de chaque rôle.

Syntaxe

EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS EvtUrsDeviceFilterResourceRequirements;

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

Paramètres

[in] Device

Handle de l’objet d’appareil framework que le pilote client a récupéré lors de l’appel précédent à WdfDeviceCreate.

[in] IoResourceRequirementsList

Handle d’un objet resource-requirements-list d’infrastructure qui représente la liste des besoins en ressources d’un appareil.

[in] HostRoleResources

Handle d’une liste de ressources pour l’appareil contrôleur lorsqu’il fonctionne en mode hôte.

[in] FunctionRoleResources

Handle d’une liste de ressources pour le contrôleur lorsqu’il fonctionne en mode fonction.

Valeur retournée

Si l’opération réussit, la fonction de rappel doit retourner STATUS_SUCCESS ou une autre valeur status pour laquelle NT_SUCCESS(status) est égal à TRUE. Sinon, il doit retourner une valeur status pour laquelle NT_SUCCESS(status) est false.

Remarques

Le pilote client inscrit son implémentation avec l’extension de classe double rôle USB en appelant UrsDeviceInitialize après avoir appelé WdfDeviceCreate pour créer l’objet d’appareil framework pour le contrôleur. L’extension de classe appelle ce rappel avant EvtDevicePrepareHardware. Le rappel est appelé dans l’extension EvtDeviceFilterRemoveResourceRequirequirements de l’extension de classe, qui est inscrit pour le compte du pilote client. Le client ne doit pas implémenter et inscrire ses evtDeviceFilterRemoveResourceRequirequirements , car il remplacera l’implémentation de l’extension de classe.

Chaque rôle a un certain nombre de ressources matérielles affectées. Ces ressources peuvent être de la mémoire, des interruptions, etc. Les ressources sont gérées par le système dans une liste de ressources requises qui contient la plage de ressources matérielles dans laquelle l’appareil peut fonctionner.

Pour plus d’informations sur les listes de ressources requises, consultez Gestion des ressources matérielles.

L’extension de classe alloue de la mémoire pour la liste des besoins en ressources et les listes de ressources pour les rôles d’hôte et de fonction. Lorsque l’extension de classe appelle l’implémentation du pilote client de EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS, elle transmet un handle WDFIORESREQLIST à cette liste d’exigences ainsi que des handles URSIORESLIST pour les listes de ressources de rôle d’hôte et de fonction. Dans l’implémentation, le pilote client est censé énumérer les configurations logiques dans la liste des exigences et case activée le descripteur de ressources pour chaque configuration en appelant WdfIoResourceListGetDescriptor.

Si le pilote souhaite utiliser une ressource particulière, il peut ajouter le descripteur de ressources associé à la liste de ressources correspondante en appelant UrsIoResourceListAppendDescriptor.

Pour supprimer un descripteur de ressource de la liste des exigences, le pilote appelle WdfIoResourceListRemove.

Exemples


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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 10
Serveur minimal pris en charge	Windows Server 2016
Plateforme cible	Windows
Version KMDF minimale	1.15
En-tête	ursdevice.h (inclure Urscx.h)
IRQL	PASSIVE_LEVEL