EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS función de devolución de llamada (ursdevice.h)

Artículo
08/07/2023

La extensión de clase de doble rol USB invoca esta devolución de llamada para permitir que el controlador cliente inserte los recursos del objeto resource-requirements-list en las listas de recursos que se usarán durante el tiempo de vida de cada rol.

Sintaxis

EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS EvtUrsDeviceFilterResourceRequirements;

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

Parámetros

[in] Device

Identificador del objeto de dispositivo de marco que el controlador de cliente recuperó en la llamada anterior a WdfDeviceCreate.

[in] IoResourceRequirementsList

Identificador de un objeto resource-requirements-list del marco que representa la lista de requisitos de recursos de un dispositivo.

[in] HostRoleResources

Identificador de una lista de recursos para el dispositivo controlador cuando funciona en modo host.

[in] FunctionRoleResources

Identificador de una lista de recursos para el controlador cuando funciona en modo de función.

Valor devuelto

Si la operación se realiza correctamente, la función de devolución de llamada debe devolver STATUS_SUCCESS u otro valor de estado para el que NT_SUCCESS(status) es igual a TRUE. De lo contrario, debe devolver un valor de estado para el que NT_SUCCESS(status) es igual a FALSE.

Comentarios

El controlador cliente registra su implementación con la extensión de clase de doble rol USB llamando a UrsDeviceInitialize después de llamar a WdfDeviceCreate para crear el objeto de dispositivo de marco para el controlador. La extensión de clase invoca esta devolución de llamada antes de EvtDevicePrepareHardware. La devolución de llamada se invoca dentro del evtDeviceFilterRemoveResourceRequirements de la extensión de clase, que se registra en nombre del controlador de cliente. El cliente no debe implementar y registrar su EvtDeviceFilterRemoveResourceRequirements porque invalidará la implementación de la extensión de clase.

Cada rol tiene un número determinado de recursos de hardware asignados. Esos recursos pueden ser memoria, interrupciones, etc. El sistema mantiene los recursos en una lista de requisitos de recursos que contiene el intervalo de recursos en los que el dispositivo puede funcionar.

Para obtener más información sobre las listas de requisitos de recursos, consulte Control de recursos de hardware.

La extensión de clase asigna memoria para la lista de requisitos de recursos y las listas de recursos para los roles de host y función. Cuando la extensión de clase invoca la implementación del controlador de cliente de EVT_URS_DEVICE_FILTER_RESOURCE_REQUIREMENTS, pasa un identificador WDFIORESREQLIST a esa lista de requisitos junto con los identificadores URSIORESLIST para las listas de recursos de rol de host y función. En la implementación, se espera que el controlador de cliente se enumere a través de las configuraciones lógicas de la lista de requisitos y compruebe el descriptor de recursos para cada configuración mediante una llamada a WdfIoResourceListGetDescriptor.

Si el controlador quiere usar un recurso determinado, puede agregar el descriptor de recursos asociado a la lista de recursos correspondiente llamando a UrsIoResourceListAppendDescriptor.

Para eliminar un descriptor de recursos de la lista de requisitos, el controlador llama a WdfIoResourceListRemove.

Ejemplos


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

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 10
Servidor mínimo compatible	Windows Server 2016
Plataforma de destino	Windows
Versión mínima de KMDF	1.15
Encabezado	ursdevice.h (incluya Urscx.h)
IRQL	PASSIVE_LEVEL