Enumeração dinâmica

de enumeração dinâmica é a capacidade de um driver de detetar e relatar alterações no número e tipo de dispositivos que estão conectados ao sistema enquanto o sistema está em execução.

Os controladores de barramento devem usar enumeração dinâmica se o número ou os tipos de dispositivos conectados ao dispositivo pai dependerem da configuração do sistema. Alguns desses dispositivos podem estar sempre conectados ao sistema, e alguns podem ser conectados e desconectados enquanto o sistema está em execução.

Por exemplo, o número e o tipo de dispositivos conectados ao barramento PCI de um sistema dependem do sistema, mas são permanentes, a menos que um usuário desligue a alimentação, abra o gabinete e adicione ou remova um dispositivo usando uma chave de fenda. Por outro lado, um usuário pode adicionar ou remover dispositivos USB conectando ou desconectando um cabo enquanto o sistema está funcionando.

Listas Dinâmicas de Crianças

A estrutura permite que os drivers ofereçam suporte à enumeração dinâmica fornecendo objetos de lista filho da estrutura. Cada objeto de lista de filhos representa uma lista de dispositivos filhos que estão conectados a um dispositivo pai. O controlador de barramento para o dispositivo pai deve identificar os dispositivos filhos do dispositivo pai, adicioná-los à lista de dispositivos filhos do dispositivo pai e criar um objeto de dispositivo físico (ODP) para cada filho.

Cada vez que um driver cria um objeto de dispositivo de framework que representa um FDO para um dispositivo, o framework cria uma lista de filhos vazia e padrão para o dispositivo. O seu driver pode obter um identificador para a lista padrão de filhos de um dispositivo chamando WdfFdoGetDefaultChildList. Normalmente, se você estiver escrevendo um driver de barramento que enumera os filhos de um dispositivo, o driver pode adicionar filhos à lista de filhos padrão. Se for necessário criar listas de filhos adicionais, o driver pode chamar WdfChildListCreate.

Antes que um driver possa usar uma lista de filhos, este deve configurar o objeto de lista de filhos inicializando uma estrutura WDF_CHILD_LIST_CONFIG e passando a estrutura para WdfFdoInitSetDefaultChildListConfigpara a lista filho padrão ou para WdfChildListCreatepara listas filho extras.

Descrições dinâmicas da criança

Cada vez que um controlador de barramento identifica um dispositivo filho, deve adicionar a descrição do dispositivo à lista de dispositivos filhos. Uma descrição da criança consiste em uma descrição de identificação obrigatória e uma descrição de endereço opcional.

Descrição de identificação Uma descrição de identificação é uma estrutura que contém informações que identificam exclusivamente cada dispositivo que o driver enumera. O driver define essa estrutura, mas seu primeiro membro deve ser uma estrutura WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER.

Normalmente, uma descrição de identificação contém as cadeias de caracteres de identificação do dispositivo, possivelmente um número de série, e informações sobre a localização do dispositivo no barramento, como um número de slot.

O driver pode fornecer o seguinte conjunto de funções de retorno de chamada, que permitem que o framework manipule as informações em uma descrição de identificação.

• EvtChildListIdentificationDescriptionCompare, que compara os conteúdos de duas estruturas de descrição de identificação.

• EvtChildListIdentificationDescriptionCopy, que copia o conteúdo de uma estrutura de descrição de identificação para outra.

• EvtChildListIdentificationDescriptionDuplicate, que cria uma nova descrição de identificação duplicando uma estrutura de descrição de identificação existente e, se necessário, alocando buffers extras.

• EvtChildListIdentificationDescriptionCleanup, que desaloca buffers que a função de callback EvtChildListIdentificationDescriptionDuplicate alocou.

Normalmente, você precisa fornecer essas funções de retorno de chamada se as estruturas de descrição de identificação do seu driver contiverem ponteiros para buffers alocados dinamicamente. Para obter mais informações sobre a finalidade dessas funções de retorno de chamada, consulte suas páginas de referência.

Descrição do endereço Uma descrição de endereço é uma estrutura que contém informações que o driver requer para aceder ao dispositivo no seu barramento, caso as informações possam mudar enquanto que o dispositivo está conectado. O driver define essa estrutura, mas seu primeiro membro deve ser uma estrutura WDF_CHILD_ADDRESS_DESCRIPTION_HEADER.

As descrições de endereços são opcionais. Se as informações de endereço de um dispositivo não puderem ser alteradas entre o momento em que o dispositivo está ligado e o momento em que é desligado, todas as informações de endereço do dispositivo podem ser armazenadas numa descrição de identificação. Por exemplo, os controladores USB atribuem endereços aos dispositivos quando os dispositivos estão conectados, e esses endereços não mudam.

Por outro lado, alguns ônibus usam informações de endereçamento que podem mudar. Por exemplo, o barramento IEEE 1394 usa uma "contagem de geração", que é o número de redefinições de barramento que ocorreram. Cada solicitação de E/S assíncrona para um dispositivo IEEE 1394 deve incluir a contagem de geração. Como essas informações de endereço podem ser alteradas, o driver deve armazená-las em uma descrição de endereço.

Para manipular as informações em uma descrição de endereço, o driver pode fornecer o seguinte conjunto de funções de retorno de chamada:

• EvtChildListAddressDescriptionCopy, que copia o conteúdo de uma estrutura de descrição de endereço para outra.

• EvtChildListAddressDescriptionDuplicate, que cria uma nova descrição de endereço duplicando uma estrutura de descrição de endereço existente e, se necessário, alocando buffers extras.

• EvtChildListAddressDescriptionCleanup, que desaloca buffers que a função de retorno de chamada EvtChildListAddressDescriptionDuplicate alocou.

Normalmente, é necessário fornecer essas funções de retorno de chamada se as estruturas de descrição de endereço do driver contiverem ponteiros para buffers alocados dinamicamente. Para obter mais informações sobre a finalidade dessas funções de retorno de chamada, consulte suas páginas de referência.

Adicionando dispositivos a uma lista dinâmica de filhos

Quando a estrutura chama a função de retorno de chamada de um driver de barramento EvtDriverDeviceAdd, essa função deve chamar WdfDeviceCreate para criar um FDO para o dispositivo pai, que normalmente é um adaptador de barramento. Para obter mais informações sobre como criar um FDO, consulte Criando objetos de dispositivo em um driver de função. O driver deve, em seguida, enumerar os filhos do dispositivo pai e adicionar os filhos a uma lista de filhos.

Opcionalmente, o driver pode chamar WdfDeviceSetBusInformationForChildren para fornecer ao framework informações sobre o barramento. Recomendamos que o faça porque torna mais fácil para os dispositivos e aplicações infantis identificarem o autocarro.

Para adicionar filhos a uma lista de filhos, o driver deve chamar WdfChildListAddOrUpdateChildDescriptionAsPresent para cada dispositivo filho encontrado. Esta chamada informa o framework que um driver descobriu um dispositivo secundário conectado a um dispositivo principal. Quando o driver chama WdfChildListAddOrUpdateChildDescriptionAsPresent, ele fornece uma descrição de identificação e, opcionalmente, uma descrição de endereço.

Depois de o driver chamar WdfChildListAddOrUpdateChildDescriptionAsPresent para relatar um novo dispositivo, o framework informa o gestor PnP de que o novo dispositivo existe. O gestor PnP constrói uma pilha de dispositivos e uma pilha de controladores para o novo dispositivo. Como parte deste processo, o framework chama a função de retorno de chamada EvtChildListCreateDevice do driver de barramento . Esta função de retorno de chamada deve chamar WdfDeviceCreate para criar um PDO para o novo dispositivo.

Normalmente, vários dispositivos filho são conectados a um pai, portanto, o driver de barramento precisa chamar WdfChildListAddOrUpdateChildDescriptionAsPresent várias vezes. A maneira mais eficiente de fazer esse processo é a seguinte:

1. Ligue WdfChildListBeginScan.

2. Invoque WdfChildListAddOrUpdateChildDescriptionAsPresent para cada dispositivo filho.

3. Chamar WdfChildListEndScan.

Se você cercar a enumeração dinâmica do driver com chamadas para WdfChildListBeginScan e WdfChildListEndScan, a estrutura armazenará todas as alterações na lista filho. Ele notifica o gestor PnP das alterações quando o driver chama WdfChildListEndScan. Em algum momento posterior, a estrutura chama o driver de barramento EvtChildListCreateDevice função de retorno de chamada para cada dispositivo na lista filho. Para cada novo dispositivo, esta função de retorno de chamada chama WdfDeviceCreate para criar um PDO.

Quando o driver chama WdfChildListBeginScan, o framework marca todos os dispositivos relatados anteriormente como não estando mais presentes. Portanto, o driver deve chamar WdfChildListAddOrUpdateChildDescriptionAsPresent para todas as crianças que o driver pode detetar, não apenas crianças recém-descobertas. Para adicionar um único filho a uma lista de filhos, o driver pode fazer uma única chamada para WdfChildListUpdateAllChildDescriptionsAsPresent sem primeiro chamar WdfChildListBeginScan.

Atualização de uma lista dinâmica de filhos

Para atualizar as informações em uma lista filho dinâmica, use um dos seguintes métodos:

1. Quando um dispositivo pai recebe uma interrupção que indica a chegada ou remoção de uma criança, a função de retorno de chamada EvtInterruptDpcdodriver chama WdfChildListAddOrUpdateChildDescriptionAsPresent se um dispositivo estiver conectado ou WdfChildListUpdateChildDescriptionAsMissing se um dispositivo estiver desconectado.

2. O driver pode fornecer uma função de retorno de chamada EvtChildListScanForChildren, que a estrutura do framework chama cada vez que o dispositivo pai entra em seu estado de funcionamento (D0). Essa função de retorno de chamada deve enumerar todos os dispositivos filho chamando WdfChildListBeginScan, WdfChildListAddOrUpdateChildDescriptionAsPresent (ou WdfChildListUpdateAllChildDescriptionsAsPresent) e WdfChildListEndScan.

Você pode usar uma ou ambas as técnicas em seu motorista.

Percorrendo uma lista dinâmica de filhos

Para examinar o conteúdo de uma lista de crianças, o motorista pode percorrer a lista usando uma das seguintes técnicas:

• Para obter o conteúdo da descrição de cada dispositivo filho, um de cada vez, o driver pode:

  1. Chamada WdfChildListBeginIteration.
  2. Ligue WdfChildListRetrieveNextDevice, quantas vezes forem necessárias.
  3. Chamada WdfChildListEndIteration.

  Ao chamar WdfChildListBeginIteration, o driver especifica um sinalizador do tipo WDF_RETRIEVE_CHILD_FLAGSque indica se a estrutura deve recuperar todas as descrições do dispositivo ou apenas um subconjunto. Quando WdfChildListRetrieveNextDevice encontra uma correspondência, ele recupera as descrições de identificação e endereço do dispositivo filho, além de um identificador para seu objeto de dispositivo.

• Para obter a descrição de endereço atualmente presente na descrição de um dispositivo filho, o driver pode chamar WdfChildListRetrieveAddressDescription, especificando uma descrição de identificação. A estrutura atravessa a lista de filhos até encontrar um dispositivo filho com uma descrição de identificação que corresponda. Em seguida, recupera a descrição do endereço.

• Se precisar obter um identificador para o objeto de dispositivo da framework que está associado a um dispositivo filho específico, o seu driver pode utilizar WdfChildListRetrievePdo. A estrutura de dados percorre a lista de dispositivos subordinados até encontrar um dispositivo subordinado com uma descrição de identificação correspondente e, em seguida, retorna um identificador de objeto de dispositivo. Para proteger o chamador da remoção repentina de PnP do PDO em outro thread, envolva a chamada com WdfChildListBeginIteration e WdfChildListEndIteration.

Aceder às descrições de identificação e morada de uma Denominação de Origem Protegida

O seu condutor pode recorrer aos seguintes métodos para aceder à descrição de identificação ou morada de um DOP:

• WdfPdoRetrieveIdentificationDescription, que recupera a descrição de identificação associada a uma DOP.

• WdfPdoRetrieveAddressDescription, que recupera a descrição do endereço associada a um PDO.

• WdfPdoUpdateAddressDescription, que atualiza a descrição do endereço associado a um PDO.

Gestão de pedidos de reenumeração

Os drivers de barramento baseados em estrutura que oferecem suporte à enumeração dinâmica podem receber uma solicitação para reenumerar um dispositivo filho específico por meio da interface REENUMERATE_SELF_INTERFACE_STANDARD. Para obter mais informações, consulte Tratamento de solicitações de enumeração.