Especificación de directivas WDF en archivos INF

  • Artículo

Un archivo INF que instala un controlador WDF debe contener dos secciones específicas de WDF:

  • Sección [DDInstall.wdf] para cada sección [DDInstall]
  • Sección [wdf-service-install], con el nombre de sección especificado en una directiva KmdfService o UmdfService en [DDInstall.wdf]

Estas secciones contienen directivas específicas de WDF. Las directivas específicas de UMDF comienzan con el prefijo UMDF y las directivas específicas de KMDF comienzan por el prefijo de KMDF.

En el ejemplo de código siguiente se muestran directivas específicas de UMDF:

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

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

En el ejemplo de código siguiente se muestran directivas específicas de KMDF:

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

[Echo_service_wdfsect]
KmdfLibraryVersion = $KMDFVERSION$

[Directivas UMDF para las secciones DDInstall.WDF]

A continuación se muestra un ejemplo de código. Cada directiva específica de UMDF de la sección DDInstall.WDF se describe a continuación.

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

UmdfService

`UmdfService = <serviceName>, <sectionName>

Asocia un controlador UMDF a una sección [wdf-service-install] que contiene información necesaria para instalar el controlador UMDF. El parámetro serviceName especifica el controlador UMDF y está limitado a un máximo de 31 caracteres de longitud. El parámetro sectionName hace referencia a la sección [wdf-service-install]. Normalmente, un archivo INF válido requiere al menos una directiva UmdfService . Sin embargo, si un controlador UMDF forma parte del sistema operativo, no se requiere una directiva UmdfService para el controlador UMDF. Por lo tanto, es posible que un archivo INF válido no tenga ninguna directiva UmdfService , aunque la mayoría de los archivos INF tienen una directiva UmdfService para cada controlador UMDF.

UmdfHostProcessSharing

Esta directiva se admite en las versiones 1.11 y posteriores de UMDF.

UmdfHostProcessSharing = <ProcessSharingDisabled | ProcessSharingEnabled>

Determina si una pila de dispositivos se coloca en un grupo de procesos compartidos (ProcessSharingEnabled) o en su propio proceso individual (ProcessSharingDisabled). El valor predeterminado es ProcessSharingEnabled. Esta directiva es específica del dispositivo en lugar de específica del controlador.

Para obtener más información sobre la agrupación de dispositivos, consulte Uso de la agrupación de dispositivos en controladores UMDF.

UmdfDirectHardwareAccess

Esta directiva se admite en las versiones 1.11 y posteriores de UMDF.

UmdfDirectHardwareAccess = <AllowDirectHardwareAccess | RejectDirectHardwareAccess>

Indica si el marco debe permitir que el controlador use cualquiera de las características de acceso directo al hardware, como el acceso a los registros de dispositivos y los puertos, el examen de los recursos de hardware asignados al dispositivo, el control de interrupciones de hardware o la adquisición de recursos de conexión.

Si UmdfDirectHardwareAccess está establecido en AllowDirectHardwareAccess, el marco permite al controlador usar interfaces UMDF que realizan acceso directo al hardware.

Debe especificar AllowDirectHardwareAccess si el controlador UMDF accede a recursos de hardware como registros o puertos, interrupciones, patillas de E/S de uso general (GPIO) o conexiones de bus serie como I2C, SPI y puerto serie. El controlador recibe todos estos recursos a través de los parámetros ResourcesRaw y ResourcesTranslated de su función de devolución de llamada EvtDevicePrepareHardware .

Nota

A partir de la versión 2.15 de UMDF, no es necesario especificar AllowDirectHardwareAccess para recibir listas de recursos de hardware en su rutina de devolución de llamada EvtDevicePrepareHardware . Si no lo especifica, el controlador no tiene los derechos de acceso para usar estos recursos, con una excepción: si el dispositivo tiene asignado uno o varios recursos de conexión (CmResourceTypeConnection) y uno o varios recursos de interrupción (CmResourceTypeInterrupt), el controlador puede llamar a WdfInterruptCreate desde su rutina de devolución de llamada EvtDevicePrepareHardware (pero no desde EvtDriverDeviceAdd).

Para obtener información sobre cómo conectar un controlador UMDF a determinados tipos de recursos, consulte:

Si UmdfDirectHardwareAccess está establecido en RejectDirectHardwareAccess, el marco no permite que los controladores usen ninguna característica de acceso directo al hardware. El valor predeterminado es RejectDirectHardwareAccess.

Para obtener información sobre cómo un controlador UMDF accede a los recursos de hardware, consulte Búsqueda y asignación de recursos de hardware.

UmdfHostPriority

Esta directiva se admite en las versiones 2.15 y posteriores de UMDF.

UmdfHostPriority = <PriorityHigh>

Un controlador de cliente HID de UMDF puede establecer UmdfHostPriority en PriorityHigh para aumentar su prioridad de subproceso. Esta directiva solo se debe usar para los controladores táctiles o de entrada que son sensibles al tiempo de respuesta del usuario. Cuando un controlador especifica PriorityHigh, el sistema lo coloca en un grupo de dispositivos independiente junto con otros controladores de prioridad similar. Dado que el grupo de dispositivos adicional usa más memoria, debe usar esta configuración con precaución. Para obtener más información sobre la agrupación de dispositivos, consulte Uso de la agrupación de dispositivos en controladores UMDF.

UmdfRegisterAccessMode

Esta directiva se admite en las versiones 1.11 y posteriores de UMDF.

UmdfRegisterAccessMode = <RegisterAccessUsingSystemCall | RegisterAccessUsingUserModeMapping>

Indica si el marco debe asignar los registros al espacio de direcciones en modo de usuario (para que una llamada del sistema no participe en el acceso a los registros) o use una llamada del sistema para acceder a los registros.

Si UmdfRegisterAccessMode está establecido en RegisterAccessUsingSystemCall, el marco usa una llamada del sistema para acceder a los registros.

Si UmdfRegisterAccessMode está establecido en RegisterAccessUsingUserModeMapping, el marco asigna los registros al espacio de direcciones en modo de usuario para que una llamada del sistema no sea necesaria para acceder a los registros. El valor predeterminado es RegisterAccessUsingSystemCall.

UmdfServiceOrder

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

Muestra el orden en el que el coins installer instala los controladores de UMDF en la pila de dispositivos. Incluso si el co-instalador instala solo un controlador UMDF en la pila de dispositivos, el archivo INF debe contener esta directiva. Los parámetros serviceNameXx corresponden a los parámetros serviceName de cada directiva UmdfService . Dado que los controladores UMDF se agregan a la pila de dispositivos en el orden en que aparecen, el primer parámetro especifica el controlador UMDF más bajo de la pila de dispositivos.

Para asegurarse de que un coinstaladores de UMDF instala el dispositivo, solo debe haber una directiva UmdfServiceOrder en cualquier sección DDInstall específica de WDF. Es decir, la directiva UmdfServiceOrder no se puede importar mediante las directivas Include y Needs .

UmdfImpersonationLevel

UmdfImpersonationLevel = <level>

Informa al marco sobre el nivel máximo de suplantación que puede tener el controlador UMDF. Una directiva UmdfImpersonationLevel es opcional; Si no se especifica un nivel de suplantación, el valor predeterminado es Identificación. Cuando una aplicación abre un identificador de archivo, la aplicación puede conceder un mayor nivel de suplantación al controlador. Sin embargo, el controlador no puede llamar al método IWDFIoRequest::Impersonate para solicitar un nivel de suplantación mayor que el nivel que especifica UmdfImpersonationLevel . Los valores posibles para esta directiva son:

  • Anónimo

  • Identificación

  • Suplantación

  • Delegación

Estos valores corresponden a los valores especificados en la enumeración SECURITY_IMPERSONATION_LEVEL .

UmdfMethodNeitherAction

UmdfMethodNeitherAction = <Copy | Reject>

Indica si el marco aceptará (Copiar) o rechazará (Rechazar) las solicitudes de E/S de un dispositivo, si los objetos de solicitud contienen códigos de control de E/S que especifican el método de acceso de búfer METHOD_NEITHER . Una directiva UmdfMethodNeitherAction es opcional. Si no se especifica la directiva , el valor predeterminado es Reject.

Para obtener más información sobre cómo admitir el método de acceso de búfer de METHOD_NEITHER en controladores basados en UMDF, vea Usar ni E/S almacenada en búfer ni E/S directa en controladores UMDF.

UmdfDispatcher

UmdfDispatcher = <FileHandle | WinUsb | NativeUSB>

Informa al marco de trabajo dónde enviar E/S después de que la E/S pase por la parte del modo de usuario de la pila de dispositivos. De forma predeterminada, la E/S se envía al reflector (WUDFRd.sys). Al establecer UmdfDispatcher en WinUsb, el controlador indica a UMDF que envíe E/S a la arquitectura de WinUsb. A partir de UMDF 2.15, especificar NativeUSB hace que el reflector controle la E/S USB.

  • Si algún controlador de la pila usa un destino basado en identificador de archivo, establezca esta directiva en FileHandle.
  • Si el controlador usa UMDF 2.15 o posterior y usa destinos de E/S USB, establezca esta directiva en NativeUSB.
  • Si el controlador es anterior a UMDF 2.15 y usa destinos de E/S USB, establezca esta directiva en WinUsb.

Una directiva UmdfDispatcher es opcional.

En el ejemplo de código siguiente se muestra la directiva UmdfDispatcher en una sección DDInstall específica de WDF.

[Xxx_Install.Wdf]
UmdfDispatcher=NativeUSB

UmdfKernelModeClientPolicy

Esta directiva se admite en las versiones 1.9 y posteriores de UMDF.

UmdfKernelModeClientPolicy = <AllowKernelModeClientsRejectKernelModeClients | >

Para permitir que los controladores en modo kernel se carguen por encima de un controlador en modo de usuario en versiones anteriores de UMDF, consulte Compatibilidad de cliente en modo kernel en versiones anteriores de UMDF.

Indica si el marco debe permitir que el controlador reciba solicitudes de E/S de controladores en modo kernel.

Si UmdfKernelModeClientPolicy está establecido en AllowKernelModeClients, el marco permite que los controladores en modo kernel se carguen por encima de un controlador en modo usuario y entrega solicitudes de E/S de controladores en modo kernel al controlador en modo usuario.

Si UmdfKernelModeClientPolicy está establecido en RejectKernelModeClients, el marco no permite que los controladores de modo kernel se carguen por encima de un controlador en modo de usuario y no entrega solicitudes de E/S de ningún controlador en modo kernel al controlador en modo de usuario. Si el archivo INF de un controlador no contiene esta directiva, el valor predeterminado es RejectKernelModeClients. Para obtener más información, consulte Compatibilidad con clientes en modo kernel.

UmdfFileObjectPolicy

Esta directiva se admite en las versiones 1.11 y posteriores de UMDF.

UmdfFileObjectPolicy = <RejectNullAndUnknownFileObjects | AllowNullAndUnknownFileObjects>

Indica si el marco debe permitir el procesamiento de solicitudes de E/S (IWDFIoRequest) que no están asociados a un objeto de archivo (IWDFFile) o están asociados a un objeto de archivo desconocido (un objeto de archivo para el que un controlador no ha visto previamente una solicitud de creación).

Si UmdfFileObjectPolicy se establece en RejectNullAndUnknownFileObjects, el marco no permite el procesamiento de solicitudes asociadas a un objeto de archivo NULL o desconocido.

Si UmdfFileObjectPolicy se establece en AllowNullAndUnknownFileObjects, el marco permite el procesamiento de solicitudes asociadas a un objeto de archivo NULL o desconocido.

El valor predeterminado es RejectNullAndUnknownFileObjects.

UmdfFsContextUsePolicy

Esta directiva se admite en las versiones 1.11 y posteriores de UMDF.

UmdfFsContextUsePolicy = <CanUseFsContext | CanUseFsContext2 | CannotUseFsContexts>

Indica si el marco puede almacenar información interna en miembros de contexto específicos de un objeto de archivo WDM. Si un controlador en modo kernel de la misma pila usa un miembro determinado del objeto de archivo, puede usar esta directiva para solicitar que el marco no use la misma ubicación.

Si UmdfFsContextUsePolicy se establece en CanUseFsContext, el marco almacena información en el miembro FsContext del objeto de archivo WDM.

Si UmdfFsContextUsePolicy se establece en CanUseFsContext2, el marco almacena información en el miembro FsContext2 del objeto de archivo WDM.

Si UmdfFsContextUsePolicy se establece en CannotUseFsContexts, el marco no usa FsContext ni FsContext2.

El valor predeterminado es CanUseFsContext.

[Sección directivas de UMDF para wdf-service-install]

A continuación se muestra un ejemplo de código. Cada directiva específica de UMDF de la sección [wdf-service-install] se describe a continuación. El nombre de sección se especifica en una directiva UmdfService en la sección [DDInstall.wdf].

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

UmdfLibraryVersion

UmdfLibraryVersion = <version>

Informa al co-installer sobre el número de versión del marco que usará el controlador UMDF. El formato de la cadena de versión es <principal>.<menor>.<servicio>. Cuando los controladores de la pila de dispositivos usan más de una versión del marco, el archivo INF copia varios co-installers--uno para cada versión del marco- en la misma ubicación en la unidad de disco duro. Sin embargo, el archivo INF agrega solo el coinstalación de versión más alta al valor del Registro CoInstallers32 . Para obtener más información sobre cómo copiar co-instaladores, consulte Uso del co-instalador de UMDF.

El co-instalador comprueba la cadena de versión y la usa para buscar el co-instalador específico de la versión para el controlador UMDF. A continuación, el co-instalador extrae el marco del co-instalador específico de la versión.

ServiceBinary

ServiceBinary = <binarypath>

Informa a UMDF sobre dónde colocar el binario del controlador UMDF en la unidad de disco duro.

Los controladores UMDF deben copiarse y ejecutarse desde el Windows\System32\Drivers\UMDF directorio .

DriverCLSID

Nota Esta directiva solo se admite en UMDF 1.x, que está en desuso. Para obtener más información, consulta UmDF 1.x Design Guide( Guía de diseño de UMDF 1.x).

DriverCLSID = <{CLSID}>

Informa a UMDF sobre el identificador de clase (CLSID) del controlador UMDF. Cuando UMDF carga el controlador UMDF, el host UMDF usa el CLSID del controlador UMDF para crear una instancia de la interfaz IDriverEntry del controlador UMDF.

UmdfExtensions

UmdfExtensions = <cxServiceName>

Necesario para los controladores que se comunican con los controladores de extensión de clase proporcionados por Microsoft. El parámetro cxServiceName corresponde al servicio asociado al binario del controlador de extensión de clase.

Los nombres de servicio de los controladores de extensión de clase se pueden encontrar como una subclave en la siguiente clave del Registro: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services

[Directivas DE KMDF para las secciones DDInstall.WDF]

A continuación se muestra un ejemplo de código. Cada directiva específica de KMDF de la sección DDInstall.WDF se describe a continuación.

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

KmdfService

KmdfService = <serviceName>, <sectionName>

Asocia un controlador KMDF a una sección [wdf-service-install] que contiene información necesaria para instalar el controlador KMDF. El parámetro serviceName especifica el controlador KMDF y está limitado a un máximo de 31 caracteres de longitud. El parámetro sectionName hace referencia a la sección [wdf-service-install]. Normalmente, un archivo INF válido requiere al menos una directiva KmdfService . Sin embargo, si un controlador KMDF forma parte del sistema operativo, no se requiere una directiva KmdfService para el controlador KMDF. Por lo tanto, un archivo INF válido podría no tener ninguna directiva KmdfService , aunque la mayoría de los archivos INF tienen una directiva KmdfService para cada controlador KMDF.

[Directivas de KMDF para la sección wdf-service-install]

A continuación se muestra un ejemplo de código. Cada directiva específica de KMDF de la sección [wdf-service-install] se describe a continuación. El nombre de sección procede de la directiva KmdfService en la sección DDInstall.wdf.

[Echo_service_wdfsect]
KmdfLibraryVersion = $KMDFVERSION$

KmdfLibraryVersion

KmdfLibraryVersion = <version>

El formato de la cadena de versión es major.minor. Normalmente, debe especificar $KMDFVERSION$ y, a continuación, el proceso de compilación de WDK lo reemplazará por el número de versión correcto.