estructura IO_RESOURCE_REQUIREMENTS_LIST (wdm.h)

Artículo
03/08/2023

La estructura IO_RESOURCE_REQUIREMENTS_LIST describe conjuntos de configuraciones de recursos que un dispositivo puede usar. Cada configuración representa un intervalo de recursos sin procesar, de varios tipos, que un dispositivo puede usar.

Sintaxis

typedef struct _IO_RESOURCE_REQUIREMENTS_LIST {
  ULONG            ListSize;
  INTERFACE_TYPE   InterfaceType;
  ULONG            BusNumber;
  ULONG            SlotNumber;
  ULONG            Reserved[3];
  ULONG            AlternativeLists;
  IO_RESOURCE_LIST List[1];
} IO_RESOURCE_REQUIREMENTS_LIST, *PIO_RESOURCE_REQUIREMENTS_LIST;

Miembros

ListSize

Número total de bytes que constituyen la estructura IO_RESOURCE_REQUIREMENTS_LIST , su matriz de IO_RESOURCE_LIST y la matriz IO_RESOURCE_DESCRIPTOR de este último.

InterfaceType

Especifica un tipo de interfaz. Debe ser uno de los tipos definidos por INTERFACE_TYPE, en Wdm.h o Ntddk.h. (No lo usan los controladores WDM).

BusNumber

Número de bus asignado por el sistema y basado en cero. (No lo usan los controladores WDM).

SlotNumber

Número de ranura del sistema. (No lo usan los controladores WDM).

Reserved[3]

Reservado.

AlternativeLists

Número de listas alternativas (o configuraciones) de recursos de hardware que se describen en esta estructura de IO_RESOURCE_REQUIREMENTS_LIST . El miembro List es el encabezado de la primera lista alternativa.

List[1]

Estructura IO_RESOURCE_LIST que actúa como encabezado para la primera lista alternativa de recursos de hardware. Si la estructura de IO_RESOURCE_REQUIREMENTS_LIST describe más de una lista alternativa, la segunda lista alternativa sigue inmediatamente la primera lista alternativa en la memoria, etc. El tamaño de cada lista alternativa depende de la longitud de la matriz de IO_RESOURCE_DESCRIPTOR que contiene. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

Comentarios

El IRP_MN_FILTER_RESOURCE_REQUIREMENTS y los IRP de IRP_MN_QUERY_RESOURCE_REQUIREMENTS usan esta estructura para describir una o varias configuraciones alternativas de recursos de hardware.

La estructura IO_RESOURCE_REQUIREMENTS_LIST es un encabezado para una estructura de datos mayor, de tamaño variable, que especifica una o varias listas alternativas de recursos. Todos los datos de esta estructura mayor ocupan un bloque contiguo de memoria, cuyo tamaño especifica el miembro ListSize . Cada lista alternativa ocupa un subbloqueo dentro del bloque más grande.

Cada lista alternativa comienza con una estructura IO_RESOURCE_LIST , que actúa como encabezado para una matriz de estructuras de IO_RESOURCE_DESCRIPTOR . La longitud de esta matriz determina el tamaño de la lista, que puede variar de una lista alternativa a la siguiente. El código de controlador puede usar la aritmética de puntero para pasar de una lista alternativa a la siguiente. Por ejemplo, si un parámetro denominado list es un puntero a la estructura IO_RESOURCE_LIST al principio de una lista alternativa, la lista se puede actualizar para que apunte al inicio de la lista siguiente de la siguiente manera:

list = (PIO_RESOURCE_LIST)(list->Descriptors + list->Count);

En este ejemplo, list->Descriptors es un puntero al inicio de la matriz de IO_RESOURCE_DESCRIPTOR y list->Count es el número de elementos de la matriz. Para obtener más información sobre los miembros Descriptores y Count , vea IO_RESOURCE_LIST.

Ejemplos

Si un controlador contiene un controlador para un IRP de IRP_MN_FILTER_RESOURCE_REQUIREMENTS , el controlador suele recorrer la lista de recursos a la que apunta el campo IoStatus.Information del IRP. El ejemplo de código siguiente contiene una función denominada FilterResources, a la que se llama en el controlador para recorrer la lista. Esta función comprueba que se especifica un recurso determinado en la lista o cambia los requisitos de recursos de la lista sin cambiar el tamaño de la lista. (Una función que cambia el tamaño de la lista tendría que asignar un búfer para la lista actualizada, escribir la lista en este búfer, actualizar el campo IoStatus.Information del IRP para que apunte a la lista actualizada y liberar el búfer que contiene la lista original).

La función FilterResources devuelve TRUE (probablemente de la instrucción switch , aunque se omiten los detalles para simplificar el ejemplo de código) si encuentra el recurso que está buscando en la lista, o si realiza un cambio en la lista que no cambia el tamaño de la lista. De lo contrario, devuelve FALSE.

/* Modify the resource list in place (without changing its size). */

BOOLEAN FilterResources(PIO_RESOURCE_REQUIREMENTS_LIST reqlist)
{
    PIO_RESOURCE_LIST list;

    list = reqlist->List;

    for (int ix = 0; ix < reqlist->AlternativeLists; ++ix)
    {
        /* Process resources in IO_RESOURCE_LIST block number ix. */

        for (int jx = 0; jx < list->Count; ++jx)
        {
            PIO_RESOURCE_DESCRIPTOR desc; 

            desc = list->Descriptors + jx;

            switch (desc->Type)
            {
               /* Process element jx in Descriptors array. */

               ...

            }
        }

        /* Advance to next IO_RESOURCE_LIST block in memory. */

        list = (PIO_RESOURCE_LIST)(list->Descriptors + list->Count);
    }

    return FALSE;
}