Isolamento do pacote de driver

O isolamento do pacote de driver é um requisito para os drivers do Windows que torna os pacotes de driver mais resilientes a alterações externas, mais fáceis de atualizar e mais simples de instalar.

A tabela a seguir mostra alguns exemplos de práticas de pacotes de drivers herdados que não são mais permitidas para Drivers do Windows na coluna da esquerda, juntamente com o comportamento necessário para Drivers do Windows na coluna da direita.

Para obter ajuda para determinar se o pacote de drivers atende aos requisitos de isolamento de pacotes de drivers, consulte Validação de Drivers do Windows. Para obter exemplos de como atualizar um INF para atender aos requisitos de isolamento do pacote de driver, consulte Adaptar um INF para cumprir o isolamento do pacote de driver.

Executar a partir do repositório de drivers

Todos os pacotes de driver isolados deixam os seus arquivos de pacote de driver no repositório de drivers. Isso significa que eles especificam DIRID 13 em seu INF para especificar o local para arquivos de pacote de driver na instalação. Para obter mais informações sobre como usá-lo num pacote de drivers, consulte Executar do armazém de drivers.

Estado de leitura e escrita

O acesso a vários registros e estados de arquivo deve ser feito chamando funções que fornecem a um chamador a localização do estado e, em seguida, o estado é lido/gravado em relação a esse local. Não use caminhos de registro absolutos codificados e caminhos de arquivo.

Esta secção contém as seguintes subsecções:

• Estado do registo

• Estado do ficheiro

• Estado da propriedade

Estado do registo

Esta secção contém as seguintes subsecções:

• Estado do registo do dispositivo PnP

• Estado do registo da interface do dispositivo

• Estado do registo do serviço

Estado do registo do dispositivo PnP

Pacotes de driver isolados e componentes de modo de usuário normalmente usam um dos dois locais para armazenar o estado do dispositivo no registro. Estas são a chave de hardware (chave de dispositivo) para o dispositivo e a chave de software (chave de driver) para o dispositivo. A chave de hardware é normalmente para configurações relacionadas a como uma instância de dispositivo individual interage com o hardware. Por exemplo, para ativar um recurso de hardware ou colocar o hardware em um modo específico. A chave de software é normalmente para configurações relacionadas a como uma instância de dispositivo individual interage com o sistema e outro software. Por exemplo, para configurar o local de um arquivo de dados, para interoperar com uma estrutura ou para acessar as configurações do aplicativo para um dispositivo. Para recuperar um identificador para estes locais do registro, utilize uma das seguintes opções:

• IoOpenDeviceRegistryKey (WDM)

• WdfDeviceOpenRegistryKey, WdfFdoInitOpenRegistryKey (WDF)

• CM_Open_DevNode_Key (código de modo de usuário)

• Diretiva INF AddReg usando entradas HKR reg-root em uma seção de adicionar ao registo referenciada a partir de uma seção INF DDInstall ou seção DDInstall.HW, conforme mostrado abaixo:

[ExampleDDInstall.HW]
AddReg = Example_DDInstall.AddReg

[Example_DDInstall.AddReg] 
HKR,,ExampleValue,,%13%\ExampleFile.dll

Estado do registo da interface do dispositivo

Para ler e gravar o estado do Registro da interface do dispositivo, use uma das seguintes opções:

• IoOpenDeviceInterfaceRegistryKey (WDM)

• CM_Open_Device_Interface_Key (código de modo de utilizador)

• Diretiva INF AddReg usando entradas reg-root HKR numa secção add-registry referenciada a partir de uma secção add-interface

Estado do registro do serviço

O estado do serviço deve ser classificado em uma das 3 categorias

• Estado do registo do serviço imutável

• Estado do registo interno de serviços

• Estado do registo do serviço partilhado

Estado do registo do serviço imutável

Estado de serviço imutável é o estado fornecido pelo pacote de driver que instala o serviço. Esses valores do registo que são definidos pelo INF para o driver e serviços Win32 devem ser armazenados na subchave "Parâmetros" do serviço, fornecendo uma entrada HKR numa seção AddReg e, em seguida, fazendo referência a essa seção na seção de instalação do serviço no INF. Por exemplo:

[ExampleDDInstall.Services]
Addservice = ExampleService, 0x2, Example_Service_Inst

[Example_Service_Inst]
DisplayName    = %ExampleService.SvcDesc%
ServiceType    = 1
StartType      = 3
ErrorControl   = 1
ServiceBinary  = %13%\ExampleService.sys
AddReg=Example_Service_Inst.AddReg

[Example_Service_Inst.AddReg]
HKR, Parameters, ExampleValue, 0x00010001, 1

Para acessar o local desse estado a partir do serviço em tempo de execução, use uma destas funções:

• IoOpenDriverRegistryKey (WDM) com uma DRIVER_REGKEY_TYPE de DriverRegKeyParameters

• WdfDriverOpenParametersRegistryKey (WDF)

• GetServiceRegistryStateKey (Serviços Win32) com uma SERVICE_REGISTRY_STATE_TYPE de ServiceRegistryStateParameters

Esses valores do Registro fornecidos pelo INF na subchave "Parameters" para o serviço só devem ser lidos em tempo de execução e não modificados. Devem ser considerados como apenas de leitura.

Se os valores do Registro fornecidos pelo INF forem configurações padrão que podem ser substituídas no tempo de execução, os valores de substituição deverão ser gravados no estado do Registro do serviço interno ou no estado do Registro do serviço compartilhado para o serviço. Ao recuperar as configurações, a configuração pode ser procurada primeiro no estado mutável. Se ele não existir lá, então a configuração pode ser procurada no estado imutável. RtlQueryRegistryValueWithFallback pode ser usado para ajudar a consultar configurações como essas que têm uma substituição e um valor padrão.

Estado do registo do serviço interno

Estado de serviço interno é o estado que é escrito durante a execução, pertencente e gerido apenas pelo próprio serviço e é apenas acessível a esse serviço. Para aceder à localização do estado do serviço interno, use uma destas funções do serviço:

• IoOpenDriverRegistryKey (WDM) com uma DRIVER_REGKEY_TYPE de DriverRegKeyPersistentState

• WdfDriverOpenPersistentStateRegistryKey (WDF)

• GetServiceRegistryStateKey (Serviços Win32) com um tipo de estado de registro de serviço de ServiceRegistryStatePersistent

Se o serviço quiser permitir que outros componentes modifiquem essas configurações, o serviço deverá expor uma interface que outro componente possa chamar e que informe ao serviço como alterar essas configurações. Por exemplo, um serviço Win32 pode expor uma interface COM ou RPC e um serviço de driver pode expor uma interface IOCTL através de uma interface de dispositivo.

Estado do registo do serviço partilhado

Estado de serviço compartilhado é o estado que é escrito em tempo de execução e pode ser compartilhado com outros componentes de modo de usuário se eles forem suficientemente privilegiados. Para acessar o local desse estado de serviço compartilhado, use uma destas funções:

• IoOpenDriverRegistryKey (WDM) com um DRIVER_REGKEY_TYPE de DriverRegKeySharedPersistentState

• GetSharedServiceRegistryStateKey (Serviços Win32) com uma SERVICE_SHARED_REGISTRY_STATE_TYPE de ServiceSharedRegistryPersistentState

Estado do ficheiro

Esta secção contém as seguintes subsecções:

• Estado do arquivo do dispositivo

• Estado do arquivo de serviço

• DriverData e ProgramData

• Arquivos temporários

Estado do arquivo do dispositivo

Se os arquivos relacionados a um dispositivo precisarem ser gravados em tempo de execução, esses arquivos deverão ser armazenados em relação a um identificador ou caminho de arquivo fornecido por meio de APIs do sistema operacional. Os arquivos de configuração específicos para esse dispositivo são um exemplo de quais tipos de arquivos devem ser armazenados aqui. Para acessar o local desse estado, use uma destas funções do serviço:

• IoGetDeviceDirectory (WDM) com o parâmetro DirectoryType definido como DeviceDirectoryData

• WdfDeviceRetrieveDeviceDirectoryString (WDF)

Estado do ficheiro de serviço

O estado do arquivo de serviço pode ser classificado em uma das 3 categorias

• Estado do ficheiro de serviço imutável

• Estado do ficheiro de serviço interno

• Estado do arquivo de serviço compartilhado

Estado do arquivo de serviço imutável

Ficheiros imutáveis de estado de serviço são ficheiros que fazem parte do pacote de drivers. Para obter mais informações sobre como acessar esses arquivos, consulte Executar do repositório de drivers.

Estado do ficheiro de serviço interno

O estado do ficheiro de serviço interno é aquele que é escrito em tempo de execução, sendo propriedade e gerido apenas pelo próprio serviço, e só acessível a esse serviço. Para aceder à localização do estado do serviço interno, use uma destas funções do serviço:

• IoGetDriverDirectory (WDM, KMDF) com o parâmetro DirectoryType definido como DriverDirectoryData

• WdfDriverRetrieveDriverDataDirectoryString (UMDF)

• GetServiceDirectory (Win32 Services) com o parâmetro eDirectoryType definido como ServiceDirectoryPersistentState

Se o serviço quiser permitir que outros componentes modifiquem essas configurações, o serviço deverá expor uma interface que outro componente possa chamar e que informe ao serviço como alterar essas configurações. Por exemplo, um serviço Win32 pode expor uma interface COM ou RPC e um serviço de driver pode expor uma interface IOCTL através de uma interface de dispositivo.

Estado do arquivo de serviço compartilhado

O estado do arquivo de serviço compartilhado é o estado que é gravado em tempo de execução e pode ser compartilhado com outros componentes do modo de usuário se eles forem suficientemente privilegiados. Para acessar o local desse estado de serviço compartilhado, use uma destas funções:

• IoGetDriverDirectory (WDM, KMDF) com o parâmetro DirectoryType definido como DriverDirectorySharedData

• GetSharedServiceDirectory (Win32 Services) com o parâmetro DirectoryType definido como ServiceSharedDirectoryPersistentState

DriverData e ProgramData

Os arquivos que podem ser compartilhados com outros componentes, mas que não se encaixam na categoria de estado do arquivo de serviço compartilhado, podem ser gravados em DriverData ou ProgramData locais.

Estes locais fornecem aos componentes um espaço para gravar estado temporário ou estado destinado a ser utilizado por outros componentes e que pode ser coletado e copiado de um sistema para ser processado por outro sistema. Por exemplo, arquivos de log personalizados ou relatórios de falhas se encaixam nesta descrição.

Evite escrever arquivos na raiz dos DriverData diretórios ou ProgramData . Em vez disso, crie um subdiretório com o nome da sua empresa e, em seguida, escreva arquivos e outros subdiretórios dentro desse diretório.

Por exemplo, para um nome de empresa como Contoso, um driver de modo kernel pode gravar um log personalizado em \DriverData\Contoso\Logs e um aplicativo de modo de usuário pode coletar ou analisar os arquivos de log do %DriverData%\Contoso\Logs.

Dados do motorista

O DriverData diretório está disponível no Windows 10, versão 1803 e posterior, e é acessível para administradores e drivers UMDF.

Os drivers de modo kernel acessam o DriverData diretório usando um link simbólico fornecido pelo sistema chamado \DriverData.

Programas de modo de usuário acessam o DriverData diretório usando a variável %DriverData%de ambiente .

ProgramData

A %ProgramData% variável de ambiente de modo de usuário está disponível para componentes de modo de usuário usarem ao armazenar dados.

Ficheiros temporários

Os arquivos temporários são normalmente usados em operações intermediárias. Podem ser gravados num subcaminho sob as variáveis de ambiente %TEMP% ou %TMP%. Como esses locais são acessados por meio de variáveis de ambiente, essa capacidade é limitada aos componentes do modo de usuário. Não há garantias sobre o tempo de vida ou a persistência desses arquivos temporários depois que os identificadores para eles são fechados. O sistema operacional ou o usuário pode removê-los a qualquer momento e eles podem não persistir durante uma reinicialização.

Evite escrever arquivos na raiz dos %TEMP% diretórios ou %TMP% . Em vez disso, crie um subdiretório com o nome da sua empresa e, em seguida, escreva arquivos e outros subdiretórios dentro desse diretório.

Estado da propriedade

Ambos os dispositivos e as interfaces de dispositivo suportam armazenar estado através do modelo de propriedade PnP. O modelo de propriedade permite que os dados de propriedade estruturada sejam armazenados em um dispositivo ou interface de dispositivo. Isso se destina a dados menores que se encaixam razoavelmente nos tipos de propriedade suportados pelo modelo de propriedade.

Para acessar as propriedades do dispositivo, estas APIs podem ser usadas:

• Drivers WDM

  • IoGetDevicePropertyData

  • IoSetDevicePropertyData

• Controladores WDF

  • WdfDeviceQueryProperty

  • WdfDeviceAllocAndQueryProperty

  • WdfDeviceQueryPropertyEx

  • WdfDeviceAllocAndQueryPropertyEx

  • WdfDeviceAssignProperty

  • WdfFdoInitQueryProperty

  • WdfFdoInitAllocAndQueryProperty

  • WdfFdoInitQueryPropertyEx

  • WdfFdoInitAllocAndQueryPropertyEx

• Código do modo de utilizador

  • CM_Get_DevNode_Property

  • CM_Set_DevNode_Property

Para acessar as propriedades da interface do dispositivo, estas APIs podem ser usadas:

• Controladores WDM

  • IoGetDeviceInterfacePropertyData

  • IoSetDeviceInterfacePropertyData

• Drivers WDF

  • WdfDeviceQueryInterfaceProperty

  • WdfDeviceAllocAndQueryInterfaceProperty

  • WdfDeviceAssignInterfaceProperty

• Código do modo de utilizador

  • CM_Get_Device_Interface_Property

  • CM_Set_Device_Interface_Property

Usando interfaces de dispositivo

Se um driver quiser permitir que outros componentes leiam ou modifiquem o estado interno do driver, o driver deve expor uma interface que outro componente pode chamar e que informa ao driver quais configurações retornar ou como modificar configurações específicas. Por exemplo, o serviço de controlador pode expor uma interface IOCTL através de uma interface de dispositivo.

Normalmente, o driver que possui o estado expõe uma interface de dispositivo em uma classe de interface de dispositivo personalizada. Quando o driver está pronto para que outros componentes tenham acesso ao estado, ele habilita a interface. Para ser notificado quando uma interface de dispositivo está ativada, os componentes do modo de usuário podem se registrar para notificações de chegada da interface do dispositivo e os componentes do modo kernel podem usar IoRegisterPlugPlayNotification. Para que esses componentes acessem o estado, o driver que habilita a interface deve definir um contrato para sua classe de interface de dispositivo personalizada. Este contrato é normalmente de dois tipos:

• Um contrato de E/S pode ser associado a essa classe de interface de dispositivo que fornece um mecanismo para acessar o estado. Outros componentes usam a interface do dispositivo habilitado para enviar solicitações de E/S em conformidade com o contrato.

• Uma interface de chamada direta que é retornada por meio de uma interface de consulta. Outros drivers podem enviar IRP_MN_QUERY_INTERFACE para recuperar ponteiros de função do driver a serem chamados.

Como alternativa, se o driver proprietário do estado permitir acesso direto ao estado, outros drivers poderão acessar o estado usando funções fornecidas pelo sistema para acesso programático ao estado da interface do dispositivo. Consulte Estado do Registro da Interface do Dispositivo para obter mais informações.

Essas interfaces ou estado (dependendo do método de compartilhamento usado) precisam ser versionados corretamente para que o driver proprietário do estado possa ser atendido independentemente de outros componentes que acessam esse estado. Os fornecedores de drivers não podem confiar que outros componentes estejam disponíveis ao mesmo tempo que o driver e permaneçam na mesma versão.

Como os dispositivos e drivers que controlam as interfaces vêm e vão, os drivers e aplicativos devem evitar chamar IoGetDeviceInterfaces na inicialização do componente para obter uma lista de interfaces habilitadas. Em vez disso, a prática recomendada é registrar-se para receber notificações de chegada ou remoção da interface do dispositivo e, em seguida, chamar a função apropriada para obter a lista de interfaces habilitadas existentes na máquina.

Para obter mais informações sobre interfaces de dispositivo, consulte:

• Usando interfaces de dispositivo

• Registo para Notificação de Chegada da Interface de Dispositivo e Remoção do Dispositivo

• Registrando-se para notificação de alteração da interface do dispositivo

Referência rápida do suporte do sistema operacional para APIs de gerenciamento de estado

A maioria dos pacotes de driver precisa suportar uma variedade de versões do sistema operacional. Consulte Suporte a várias versões do sistema operacional para obter mais informações sobre como fazer isso em um pacote de driver. As tabelas a seguir fornecem uma referência rápida de quando o suporte ao sistema operacional foi adicionado para várias APIs de gerenciamento de estado.

Controladores WDM

KMDF Drivers

Drivers UMDF

Código do modo de utilizador