Especificando diretivas WDF em arquivos INF

Um arquivo INF que instala um driver WDF deve conter duas seções específicas do WDF:

• Seção [DDInstall.wdf] para cada seção [DDInstall]
• Seção [wdf-service-install], com o nome da seção especificado em uma diretiva KmdfService ou UmdfService em [DDInstall.wdf]

Essas seções contêm diretivas específicas do WDF. As diretivas específicas do UMDF começam com o prefixo UMDF e as diretivas específicas do KMDF começam com o prefixo KMDF.

O exemplo de código a seguir mostra diretivas específicas do UMDF:

[ECHO_Device.NT.Wdf]
UmdfService = Echo, Echo_service_wdfsect
UmdfServiceOrder = Echo

[Echo_service_wdfsect]
UmdfLibraryVersion = $UMDFVERSION$
ServiceBinary = %13%\echo.dll

O exemplo de código a seguir mostra diretivas específicas do KMDF:

[ECHO_Device.NT.Wdf]
KmdfService = Echo, Echo_service_wdfsect

[Echo_service_wdfsect]
KmdfLibraryVersion = $KMDFVERSION$

[Diretivas UMDF para seções DDInstall.WDF]

Veja a seguir um exemplo de código. Cada diretiva específica do UMDF na seção DDInstall.WDF é descrita abaixo.

[ECHO_Device.NT.Wdf]
UmdfService = Echo, Echo_service_wdfsect
UmdfServiceOrder = Echo

UmdfService

`UmdfService = <serviceName>, <sectionName>

Associa um driver UMDF a uma seção [wdf-service-install] que contém informações necessárias para instalar o driver UMDF. O parâmetro serviceName especifica o driver UMDF e é limitado a um máximo de 31 caracteres de comprimento. O parâmetro sectionName faz referência à seção [wdf-service-install]. Um arquivo INF válido normalmente requer pelo menos uma diretiva UmdfService . No entanto, se um driver UMDF fizer parte do sistema operacional, uma diretiva UmdfService para o driver UMDF não será necessária. Portanto, um arquivo INF válido pode não ter nenhuma diretiva UmdfService , embora a maioria dos arquivos INF tenha uma diretiva UmdfService para cada driver UMDF.

UmdfHostProcessSharing

Essa diretiva tem suporte nas versões 1.11 e posteriores do UMDF.

UmdfHostProcessSharing = <ProcessSharingDisabled | ProcessSharingEnabled>

Determina se uma pilha de dispositivos é colocada em um pool de processos compartilhado (ProcessSharingEnabled) ou em seu próprio processo individual (ProcessSharingDisabled). O padrão é ProcessSharingEnabled. Essa diretiva é específica do dispositivo em vez de específica do driver.

Para obter mais informações sobre o pool de dispositivos, consulte Usando o pool de dispositivos em drivers UMDF.

UmdfDirectHardwareAccess

Essa diretiva tem suporte nas versões 1.11 e posteriores do UMDF.

UmdfDirectHardwareAccess = <AllowDirectHardwareAccess | RejectDirectHardwareAccess>

Indica se a estrutura deve permitir que o driver use qualquer um dos recursos diretos de acesso de hardware, como acessar portas e registros de dispositivo, verificar recursos de hardware atribuídos ao dispositivo, lidar com interrupções de hardware ou adquirir recursos de conexão.

Se UmdfDirectHardwareAccess estiver definido como AllowDirectHardwareAccess, a estrutura permitirá que o driver use interfaces UMDF que executam acesso direto ao hardware.

Você deve especificar AllowDirectHardwareAccess se o driver UMDF acessar recursos de hardware, como registros ou portas, interrupções, pinos de GPIO ( E/S de uso geral ) ou conexões de barramento serial, como I2C, SPI e porta serial. Seu driver recebe todos esses recursos por meio dos parâmetros ResourcesRaw e ResourcesTranslated de sua função de retorno de chamada EvtDevicePrepareHardware .

Observação

A partir do UMDF versão 2.15, um driver UMDF não precisa especificar AllowDirectHardwareAccess para receber listas de recursos de hardware em sua rotina de retorno de chamada EvtDevicePrepareHardware . Se você não especificá-lo, o driver não terá os direitos de acesso para usar esses recursos, com uma exceção: se o dispositivo receber um ou mais recursos de conexão (CmResourceTypeConnection) e um ou mais recursos de interrupção (CmResourceTypeInterrupt), o driver poderá chamar WdfInterruptCreate de sua rotina de retorno de chamada EvtDevicePrepareHardware (mas não de EvtDriverDeviceAdd).

Para obter informações sobre como conectar um driver UMDF a determinados tipos de recursos, consulte:

• Recursos de hardware para drivers periféricos do User-Mode SPB
• IDs de conexão para dispositivos periféricos SPB-Connected
• Conectando um driver periférico UMDF a uma porta serial

Se UmdfDirectHardwareAccess estiver definido como RejectDirectHardwareAccess, a estrutura não permitirá que os drivers usem nenhum recurso de acesso direto ao hardware. O valor padrão é RejectDirectHardwareAccess.

Para obter informações sobre como um driver UMDF acessa recursos de hardware, consulte Localizando e mapeando recursos de hardware.

UmdfHostPriority

Essa diretiva tem suporte nas versões 2.15 e posteriores do UMDF.

UmdfHostPriority = <PriorityHigh>

Um driver de cliente UMDF HID pode definir UmdfHostPriority como PriorityHigh para aumentar sua prioridade de thread. Essa diretiva só deve ser usada para drivers de toque ou de entrada que sejam sensíveis ao tempo de resposta do usuário. Quando um driver especifica PriorityHigh, o sistema o coloca em um pool de dispositivos separado, juntamente com outros drivers de prioridade semelhante. Como o pool de dispositivos adicional usa mais memória, você deve usar essa configuração com cuidado. Para obter mais informações sobre o pool de dispositivos, consulte Usando o pool de dispositivos em drivers UMDF.

UmdfRegisterAccessMode

Essa diretiva tem suporte nas versões 1.11 e posteriores do UMDF.

UmdfRegisterAccessMode = <RegisterAccessUsingSystemCall | RegisterAccessUsingUserModeMapping>

Indica se a estrutura deve mapear os registros para o espaço de endereço no modo de usuário (para que uma chamada do sistema não esteja envolvida no acesso a registros) ou usar uma chamada do sistema para acessar registros.

Se UmdfRegisterAccessMode estiver definido como RegisterAccessUsingSystemCall, a estrutura usará uma chamada do sistema para acessar registros.

Se UmdfRegisterAccessMode estiver definido como RegisterAccessUsingUserModeMapping, a estrutura mapeará os registros no espaço de endereço no modo de usuário para que uma chamada do sistema não seja necessária para acessar registros. O valor padrão é RegisterAccessUsingSystemCall.

UmdfServiceOrder

UmdfServiceOrder = <serviceName1> [, <serviceName2> ...]

Lista a ordem em que o co-instalador instala os drivers UMDF na pilha do dispositivo. Mesmo que o co-instalador instale apenas um driver UMDF na pilha do dispositivo, o arquivo INF deve conter essa diretiva. Os parâmetros serviceNameXx correspondem aos parâmetros serviceName para cada diretiva UmdfService . Como os drivers UMDF são adicionados à pilha de dispositivos na ordem em que estão listados, o primeiro parâmetro especifica o driver UMDF mais baixo na pilha do dispositivo.

Para garantir que um co-instalador UMDF instale o dispositivo, apenas uma diretiva UmdfServiceOrder deve estar presente em qualquer determinada seção DDInstall específica do WDF . Ou seja, a diretiva UmdfServiceOrder não pode ser importada usando as diretivas Include e Needs .

UmdfImpersonationLevel

UmdfImpersonationLevel = <level>

Informa a estrutura sobre o nível máximo de representação que o driver UMDF pode ter. Uma diretiva UmdfImpersonationLevel é opcional; se um nível de representação não for especificado, o padrão será Identificação. Quando um aplicativo abre um identificador de arquivo, o aplicativo pode conceder um nível de representação maior ao driver. No entanto, o driver não pode chamar o método IWDFIoRequest::Impersonate para solicitar um nível de representação maior que o nível especificado por UmdfImpersonationLevel . Os valores possíveis para essa diretiva são:

• Anônimo

• Identificação

• Representação

• Delegação

Esses valores correspondem aos valores especificados na enumeração SECURITY_IMPERSONATION_LEVEL .

UmdfMethodNeitherAction

UmdfMethodNeitherAction = <Copiar | Rejeitar>

Indica se a estrutura aceitará (Copiar) ou rejeitará (Rejeitar) as solicitações de E/S de um dispositivo, se os objetos de solicitação contiverem códigos de controle de E/S que especificam o método de acesso ao buffer METHOD_NEITHER . Uma diretiva UmdfMethodNeitherAction é opcional. Se a diretiva não for especificada, o valor padrão será Rejeitar.

Para obter mais informações sobre como dar suporte ao método de acesso ao buffer METHOD_NEITHER em drivers baseados em UMDF, consulte Using Neither Buffered I/O nem Direct I/O in UMDF Drivers.

UmdfDispatcher

UmdfDispatcher = <FileHandle | WinUsb | NativeUSB>

Informa a estrutura para onde enviar E/S depois que a E/S passa pela parte do modo de usuário da pilha do dispositivo. Por padrão, a E/S é enviada para o refletor (WUDFRd.sys). Ao definir UmdfDispatcher como WinUsb, o driver instrui o UMDF a enviar E/S para a arquitetura do WinUsb. A partir do UMDF 2.15, especificar NativeUSB faz com que o refletor manipule a E/S USB.

• Se algum driver na pilha usar um destino baseado em identificador de arquivo, defina essa diretiva como FileHandle.
• Se o driver usa UMDF 2.15 ou posterior e usa destinos de E/S USB, defina essa diretiva como NativeUSB.
• Se o driver for pré-UMDF 2.15 e usar destinos de E/S USB, defina essa diretiva como WinUsb.

Uma diretiva UmdfDispatcher é opcional.

O exemplo de código a seguir mostra a diretiva UmdfDispatcher em uma seção DDInstall específica do WDF .

[Xxx_Install.Wdf]
UmdfDispatcher=NativeUSB

UmdfKernelModeClientPolicy

Essa diretiva tem suporte nas versões 1.9 e posteriores do UMDF.

UmdfKernelModeClientPolicy = <AllowKernelModeClients | RejectKernelModeClients>

Para permitir que drivers no modo kernel carreguem acima de um driver de modo de usuário em versões anteriores do UMDF, consulte Suporte ao cliente no modo Kernel em versões anteriores do UMDF.

Indica se a estrutura deve permitir que o driver receba solicitações de E/S de drivers no modo kernel.

Se UmdfKernelModeClientPolicy estiver definido como AllowKernelModeClients, a estrutura permitirá que os drivers no modo kernel sejam carregados acima de um driver de modo de usuário e fornecerá solicitações de E/S de drivers no modo kernel para o driver de modo de usuário.

Se UmdfKernelModeClientPolicy estiver definido como RejectKernelModeClients, a estrutura não permitirá que drivers no modo kernel sejam carregados acima de um driver de modo de usuário e não fornecerá solicitações de E/S de nenhum drivers no modo kernel para o driver de modo de usuário. Se o arquivo INF de um driver não contiver essa diretiva, o valor padrão será RejectKernelModeClients. Para obter mais informações, consulte Suporte a clientes no modo Kernel.

UmdfFileObjectPolicy

Essa diretiva tem suporte nas versões 1.11 e posteriores do UMDF.

UmdfFileObjectPolicy = <RejectNullAndUnknownFileObjects | AllowNullAndUnknownFileObjects>

Indica se a estrutura deve permitir o processamento de solicitações de E/S (IWDFIoRequest) que não estão associadas a um objeto de arquivo (IWDFFile) ou estão associadas a um objeto de arquivo desconhecido (um objeto de arquivo para o qual um driver não viu anteriormente uma solicitação de criação).

Se UmdfFileObjectPolicy estiver definido como RejectNullAndUnknownFileObjects, a estrutura não permitirá o processamento de solicitações associadas a um objeto de arquivo NULL ou desconhecido.

Se UmdfFileObjectPolicy estiver definido como AllowNullAndUnknownFileObjects, a estrutura permitirá o processamento de solicitações associadas a um objeto de arquivo NULL ou desconhecido.

O valor padrão é RejectNullAndUnknownFileObjects.

UmdfFsContextUsePolicy

Essa diretiva tem suporte nas versões 1.11 e posteriores do UMDF.

UmdfFsContextUsePolicy = <CanUseFsContext | CanUseFsContext2 | CannotUseFsContexts>

Indica se a estrutura pode armazenar informações internas em membros de contexto específicos de um objeto de arquivo WDM. Se um driver de modo kernel na mesma pilha usar um membro específico do objeto de arquivo, você poderá usar essa diretiva para solicitar que a estrutura não use o mesmo local.

Se UmdfFsContextUsePolicy estiver definido como CanUseFsContext, a estrutura armazenará informações no membro FsContext do objeto de arquivo WDM.

Se UmdfFsContextUsePolicy estiver definido como CanUseFsContext2, a estrutura armazenará informações no membro FsContext2 do objeto de arquivo WDM.

Se UmdfFsContextUsePolicy estiver definido como CannotUseFsContexts, a estrutura não usará FsContext ou FsContext2.

O valor padrão é CanUseFsContext.

[Seção Diretivas UMDF para wdf-service-install]

Veja a seguir um exemplo de código. Cada diretiva específica do UMDF na seção [wdf-service-install] é descrita abaixo. O nome da seção é especificado em uma diretiva UmdfService na seção [DDInstall.wdf].

[Echo_service_wdfsect]
UmdfLibraryVersion = $UMDFVERSION$
ServiceBinary = %13%\echo.dll

UmdfLibraryVersion

UmdfLibraryVersion = <versão>

Informa o co-instalador sobre o número de versão da estrutura que o driver UMDF usará. O formato da cadeia de caracteres de versão é <principal>.<menor>.<serviço>. Quando os drivers na pilha de dispositivos usam mais de uma versão da estrutura, o arquivo INF copia vários co-instaladores, um para cada versão da estrutura, para o mesmo local na unidade de disco rígido. No entanto, o arquivo INF adiciona apenas o co-instalador de versão mais alta ao valor do Registro CoInstallers32 . Para obter mais informações sobre como copiar co-instaladores, consulte Usando o co-instalador UMDF.

O co-instalador verifica a cadeia de caracteres de versão e a usa para localizar o co-instalador específico da versão para o driver UMDF. Em seguida, o co-instalador extrai a estrutura do co-instalador específico da versão.

ServiceBinary

ServiceBinary = <binarypath>

Informa o UMDF sobre onde colocar o binário do driver UMDF na unidade de disco rígido.

Os drivers UMDF devem ser copiados e executados no Windows\System32\Drivers\UMDF diretório .

DriverCLSID

Nota Essa diretiva só tem suporte no UMDF 1.x, que foi preterido. Para obter mais informações, consulte Guia de design do UMDF 1.x.

DriverCLSID = <{CLSID}>

Informa o UMDF sobre o CLSID (identificador de classe) do driver UMDF. Quando UMDF carrega o driver UMDF, o host UMDF usa o CLSID do driver UMDF para criar uma instância da interface IDriverEntry do driver UMDF.

UmdfExtensions

UmdfExtensions = <cxServiceName>

Necessário para drivers que se comunicam com drivers de extensão de classe fornecidos pela Microsoft. O parâmetro cxServiceName corresponde ao serviço associado ao binário do driver de extensão de classe.

Os nomes de serviço para os drivers de extensão de classe podem estar localizados como uma subchave na seguinte chave do Registro: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services

[Diretivas KMDF para seções DDInstall.WDF]

Veja a seguir um exemplo de código. Cada diretiva específica do KMDF na seção DDInstall.WDF é descrita abaixo.

[ECHO_Device.NT.Wdf]
KmdfService = Echo, Echo_service_wdfsect

KmdfService

KmdfService = <serviceName>, <sectionName>

Associa um driver KMDF a uma seção [wdf-service-install] que contém informações necessárias para instalar o driver KMDF. O parâmetro serviceName especifica o driver KMDF e é limitado a um máximo de 31 caracteres de comprimento. O parâmetro sectionName faz referência à seção [wdf-service-install]. Um arquivo INF válido normalmente requer pelo menos uma diretiva KmdfService . No entanto, se um driver KMDF fizer parte do sistema operacional, uma diretiva KmdfService para o driver KMDF não será necessária. Portanto, um arquivo INF válido pode não ter nenhuma diretiva KmdfService , embora a maioria dos arquivos INF tenha uma diretiva KmdfService para cada driver KMDF.

[Seção Diretivas KMDF para wdf-service-install]

Veja a seguir um exemplo de código. Cada diretiva específica do KMDF na seção [wdf-service-install] é descrita abaixo. O nome da seção vem da diretiva KmdfService na seção DDInstall.wdf.

[Echo_service_wdfsect]
KmdfLibraryVersion = $KMDFVERSION$

KmdfLibraryVersion

KmdfLibraryVersion = <version>

O formato da cadeia de caracteres de versão é major.minor. Normalmente, você deve especificar $KMDFVERSION$ e, em seguida, o processo de build do WDK o substituirá pelo número de versão correto.