estrutura IO_RESOURCE_REQUIREMENTS_LIST (wdm.h)

Artigo
03/08/2023

A estrutura IO_RESOURCE_REQUIREMENTS_LIST descreve conjuntos de configurações de recursos que podem ser usadas por um dispositivo. Cada configuração representa um intervalo de recursos brutos, de vários tipos, que podem ser usados por um dispositivo.

Sintaxe

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;

Membros

ListSize

O número total de bytes que constituem a estrutura IO_RESOURCE_REQUIREMENTS_LIST , sua matriz IO_RESOURCE_LIST e a matriz IO_RESOURCE_DESCRIPTOR deste último.

InterfaceType

Especifica um tipo de interface. Esse deve ser um dos tipos definidos por INTERFACE_TYPE, em Wdm.h ou Ntddk.h. (Não usado por drivers WDM.)

BusNumber

Um número de barramento baseado em zero atribuído pelo sistema. (Não usado por drivers WDM.)

SlotNumber

Um número de slot do sistema. (Não usado por drivers WDM.)

Reserved[3]

Reservado.

AlternativeLists

O número de listas alternativas (ou configurações) de recursos de hardware descritos por essa estrutura IO_RESOURCE_REQUIREMENTS_LIST . O membro List é o cabeçalho da primeira lista alternativa.

List[1]

A estrutura IO_RESOURCE_LIST que serve como cabeçalho para a primeira lista alternativa de recursos de hardware. Se a estrutura IO_RESOURCE_REQUIREMENTS_LIST descreve mais de uma lista alternativa, a segunda lista alternativa segue imediatamente a primeira lista alternativa na memória e assim por diante. O tamanho de cada lista alternativa depende do comprimento da matriz IO_RESOURCE_DESCRIPTOR que ela contém. Para obter mais informações, consulte a seção Comentários a seguir.

Comentários

Essa estrutura é usada pelo IRP_MN_FILTER_RESOURCE_REQUIREMENTS e IRP_MN_QUERY_RESOURCE_REQUIREMENTS IRPs para descrever uma ou mais configurações alternativas de recursos de hardware.

A estrutura IO_RESOURCE_REQUIREMENTS_LIST é um cabeçalho para uma estrutura de dados maior, de tamanho variável, que especifica uma ou mais listas alternativas de recursos. Todos os dados nessa estrutura maior ocupam um bloco contíguo de memória, cujo tamanho é especificado pelo membro ListSize . Cada lista alternativa ocupa um subbloco dentro do bloco maior.

Cada lista alternativa começa com uma estrutura IO_RESOURCE_LIST , que serve como um cabeçalho para uma matriz de estruturas de IO_RESOURCE_DESCRIPTOR . O comprimento dessa matriz determina o tamanho da lista, que pode variar de uma lista alternativa para a próxima. O código do driver pode usar a aritmética de ponteiro para passar de uma lista alternativa para a próxima. Por exemplo, se um parâmetro chamado list for um ponteiro para a estrutura IO_RESOURCE_LIST no início de uma lista alternativa, a lista poderá ser atualizada para apontar para o início da próxima lista da seguinte maneira:

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

Neste exemplo, list->Descriptors é um ponteiro para o início da matriz IO_RESOURCE_DESCRIPTOR e list->Count é o número de elementos na matriz. Para obter mais informações sobre os descritores e membrosde Contagem , consulte IO_RESOURCE_LIST.

Exemplos

Se um driver contiver um manipulador para um IRP IRP_MN_FILTER_RESOURCE_REQUIREMENTS , o manipulador normalmente orientará a lista de recursos apontada pelo campo IoStatus.Information no IRP. O exemplo de código a seguir contém uma função, chamada FilterResources, que é chamada no manipulador para percorrer a lista. Essa função verifica se um recurso específico está especificado na lista ou altera os requisitos de recursos na lista sem alterar o tamanho da lista. (Uma função que altera o tamanho da lista precisaria alocar um buffer para a lista atualizada, gravar a lista nesse buffer, atualizar o campo IoStatus.Information no IRP para apontar para a lista atualizada e liberar o buffer que contém a lista original.)

A função FilterResources retorna TRUE (provavelmente da instrução switch , embora os detalhes sejam omitidos para simplificar o exemplo de código) se encontrar o recurso que ele está procurando na lista ou se ele fizer uma alteração na lista que não altere o tamanho da lista. Caso contrário, retornará 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;
}