AddDevice Routines in Function or Filter Drivers

Uma rotina AddDevice em um driver de função ou filtro deve seguir as seguintes etapas:

1. Chame IoCreateDevice para criar um objeto de dispositivo funcional ou de filtro (um FDO ou filtro DO) para o dispositivo que está sendo adicionado.

   Não especifique um DeviceName para o objeto do dispositivo, pois isso ignora a segurança do gerenciador PnP. Se um componente do modo de usuário precisar de um link simbólico para o dispositivo, registre uma interface do dispositivo (consulte a próxima etapa abaixo). Se um componente do modo kernel precisar de um nome de dispositivo herdado, o driver deverá nomear o objeto do dispositivo, mas a nomenclatura não é recomendada.

   Inclua FILE_DEVICE_SECURE_OPEN no parâmetro DeviceCharacteristics . Essa característica orienta o gerente de E/S a executar verificações de segurança no objeto do dispositivo para todas as solicitações abertas, incluindo aberturas relativas e o nome do arquivo à direita é aberto.

2. [opcional] Crie um ou mais links simbólicos para o dispositivo.

   Chame IoRegisterDeviceInterface para registrar a funcionalidade do dispositivo e criar um link simbólico que os aplicativos ou componentes do sistema podem usar para abrir o dispositivo. O driver deve habilitar a interface chamando IoSetDeviceInterfaceState quando ele manipula a solicitação de IRP_MN_START_DEVICE . Para obter mais informações, consulte Classes de interface do dispositivo.

3. Armazene o ponteiro para o PDO do dispositivo na extensão do dispositivo.

   O gerenciador PnP fornece um ponteiro para o PDO como o parâmetro PhysicalDeviceObject para AddDevice. Os drivers usam o ponteiro PDO em chamadas para rotinas como IoGetDeviceProperty.

4. Defina sinalizadores na extensão do dispositivo para rastrear determinados estados PnP do dispositivo, como dispositivo pausado, removido e removido surpresa.

   Por exemplo, defina um sinalizador para indicar que os IRPs de entrada devem ser mantidos enquanto o dispositivo está em estado de pausa. Crie uma fila para manter IRPs, se o driver ainda não tiver um mecanismo para enfileirar IRPs. Confira Enfileiramento e Remoção de IRPs para obter mais informações.

   Aloque também uma estrutura IO_REMOVE_LOCK na extensão do dispositivo e chame IoInitializeRemoveLock para inicializar essa estrutura. Para obter mais informações, consulte Usando Remover Bloqueios.

5. Defina o bit de sinalizador DO_BUFFERED_IO ou DO_DIRECT_IO no objeto do dispositivo para especificar o tipo de buffer que o gerenciador de E/S deve usar para solicitações de E/S enviadas para a pilha do dispositivo. Drivers de nível superior OU esse membro com o mesmo valor que o driver mais baixo na pilha, exceto possivelmente para drivers de nível mais alto. Para obter mais informações, consulte Inicializando um objeto device.

6. Defina o sinalizador DO_POWER_INRUSH ou DO_POWER_PAGABLE para o gerenciamento de energia, se necessário. Os drivers que podem ser pagináveis devem definir o sinalizador DO_POWER_PAGABLE. Os sinalizadores de objeto do dispositivo normalmente são definidos pelo driver de barramento quando ele cria o PDO para o dispositivo. No entanto, os drivers de nível superior podem ocasionalmente precisar alterar os valores desses sinalizadores em suas rotinas AddDevice ao criar o FDO ou filtrar DO. Consulte Configurando sinalizadores de objeto do dispositivo para o Gerenciamento de Energia para obter detalhes.

7. Crie e/ou inicialize outros recursos de software que o driver usa para gerenciar esse dispositivo, como eventos, bloqueios de rotação ou outros objetos. (Os recursos de hardware, como portas de E/S, são configurados posteriormente, em resposta a uma solicitação de IRP_MN_START_DEVICE .)

   Como uma rotina AddDevice é executada em um contexto de thread do sistema em IRQL = PASSIVE_LEVEL, qualquer memória alocada com ExAllocatePoolWithTag para uso exclusivamente durante a inicialização pode ser do pool de páginas, desde que o driver não controle o dispositivo que contém o arquivo de página do sistema. Essa alocação de memória deve ser lançada com ExFreePool antes que AddDevice retorne o controle.

8. Anexe o objeto de dispositivo à pilha do dispositivo (IoAttachDeviceToDeviceStack).

   Especifique um ponteiro para o PDO do dispositivo no parâmetro TargetDevice .

   Armazene o ponteiro retornado por IoAttachDeviceToDeviceStack. Esse ponteiro, que aponta para o objeto de dispositivo do driver mais baixo para o dispositivo, é um parâmetro necessário para IoCallDriver e PoCallDriver ao passar IRPs para baixo na pilha do dispositivo.

9. Desmarque o sinalizador DO_DEVICE_INITIALIZING no FDO ou filtre DO com uma instrução semelhante à seguinte:

   FunctionalDeviceObject->Flags &= ~DO_DEVICE_INITIALIZING;
   

10. Esteja preparado para lidar com IRPs PnP para o dispositivo (como IRP_MN_QUERY_RESOURCE_REQUIREMENTS e IRP_MN_START_DEVICE).

Um driver não deve começar a controlar o dispositivo até receber uma IRP_MN_START_DEVICE que contém a lista de recursos de hardware atribuídos ao dispositivo pelo gerenciador PnP.