windows drivers rs
v0.3.0
Este repositorio es una colección de cajas de óxido que permiten a los desarrolladores desarrollar controladores de Windows en Rust. Es la intención de admitir los modelos de desarrollo de controladores WDM y WDF. Este repositorio contiene las siguientes cajas:
bindgen , como también las reimplementaciones manuales de las macros que BindGen no genera.wdk-sys y las cajas generalmente nunca deben necesitar depender directamente de wdk-macrosPara ver un ejemplo de este repositorio utilizado para crear controladores, consulte Windows-Rust-Driver-Samples.
Nota: Este proyecto todavía se encuentra en las primeras etapas de desarrollo y aún no se recomienda para el uso de producción. ¡Alentamos la experimentación, sugerencias y discusiones comunitarias! ¡Usaremos nuestro foro de discusiones de GitHub como la forma principal de compromiso con la comunidad!
Este proyecto fue construido con el apoyo de los controladores WDM, KMDF y UMDF en mente, así como los servicios Win32. Esto incluye soporte para todas las versiones de WDF incluidas en WDK 22H2 y más nueva. Actualmente, las cajas disponibles en crates.io solo admiten KMDF V1.33, pero se pueden generar enlaces para todo lo demás clonando windows-drivers-rs y modificando la configuración especificada en build.rs de wdk-sys . El soporte de CRATES.IO para otras configuraciones de WDK está planificada en el futuro cercano.
Nota: Dado que los ejemplos y las pruebas de nivel de espacio de trabajo usan diferentes configuraciones de WDK, y WDR solo admite una configuración WDK por espacio de trabajo, los ejemplos de nivel de trabajo y la carpeta de pruebas están excluidos del manifiesto de carga del repositorio de la raíz.
La generación de unión a través de bindgen requiere libclang . La forma más fácil de adquirir esto es a través de winget
winget install -i LLVM.LLVM --version 17.0.6 --force Para ejecutar tareas posteriores a la construcción (es decir, inf2cat , infverif , etc.), se usa cargo make
cargo install --locked cargo-make --no-default-features --features tls-nativeLa construcción de programas con el WDK también requiere estar en un entorno WDK válido. La forma recomendada de hacerlo es ingresar a un aviso de desarrollador EWDK
Las cajas en este repositorio están disponibles en crates.io , pero tenga en cuenta las limitaciones actuales descritas en configuraciones compatibles. Si necesita admitir una configuración diferente, intente clonar este repositorio y usar dependencias de ruta
Cree un nuevo paquete de carga con una caja lib:
cargo new < driver_name > -- lib Agregue dependencias en las cajas de windows-drivers-rs :
cd < driver_name >
cargo add -- build wdk - build
cargo add wdk wdk - sys wdk - alloc wdk - panic Establezca el tipo de caja en cdylib agregando el siguiente fragmento a Cargo.toml :
[ lib ]
crate-type = [ " cdylib " ]Agregue una sección de metadatos WDK y configure el WDK para su caso de uso. Esto también permite que las tareas de carga de carga sepan que el paquete es un conductor y que los pasos de empaque del conductor deben ejecutarse.
Ejemplo de UMDF:
[ package . metadata . wdk . driver-model ]
driver-type = " UMDF "
umdf-version-major = 1
target-umdf-version-minor = 33 Para cajas de modo de kernel (por ejemplo, controladores KMDF , controladores WDM ): Establezca la estrategia de pánico de la caja para abort en Cargo.toml :
[ profile . dev ]
panic = " abort "
[ profile . release ]
panic = " abort " Cree un build.rs y agregue el siguiente fragmento:
fn main ( ) -> Result < ( ) , wdk_build :: ConfigError > {
wdk_build :: configure_wdk_binary_build ( )
} Para cajas de modo kernel (por ejemplo, controladores KMDF , controladores WDM ): Marque la caja de su controlador como no_std en lib.rs :
#! [ no_std ] Para cajas de modo de núcleo (por ejemplo, controladores KMDF , controladores WDM ): agregue un manejador de pánico en lib.rs :
# [ cfg ( not ( test ) ) ]
extern crate wdk_panic ; Para cajas de modo de kernel (por ejemplo, controladores KMDF , controladores WDM ): agregue un asignador global opcional en lib.rs :
# [ cfg ( not ( test ) ) ]
use wdk_alloc :: WdkAllocator ;
# [ cfg ( not ( test ) ) ]
# [ global_allocator ]
static GLOBAL_ALLOCATOR : WdkAllocator = WdkAllocator ; Esto solo se requiere si desea poder usar los módulos alloc en la biblioteca Rust Standard.
Agregue un Conductor Entry en lib.rs :
use wdk_sys :: {
PDRIVER_OBJECT ,
NTSTATUS ,
PCUNICODE_STRING ,
} ;
# [ export_name = "DriverEntry" ] // WDF expects a symbol with the name DriverEntry
pub unsafe extern "system" fn driver_entry (
driver : PDRIVER_OBJECT ,
registry_path : PCUNICODE_STRING ,
) -> NTSTATUS {
0
} Nota: En las cajas de modo kernel, puede usar driver: &mut DRIVER_OBJECT en lugar del driver: PDRIVER_OBJECT .
Agregue un Makefile.toml :
extend = " target/rust-driver-makefile.toml "
[ config ]
load_script = '''
#!@rust
//! ```cargo
//! [dependencies]
//! wdk-build = "0.3.0"
//! ```
#![allow(unused_doc_comments)]
wdk_build::cargo_make::load_rust_driver_makefile()?
''' Agregue un archivo INX que coincida con el nombre de su caja cdylib .
Habilitar el enlace CRT estático. Un enfoque es agregar esto a su .cargo/config.toml :
[ build ]
rustflags = [ " -C " , " target-feature=+crt-static " ]Construye el controlador:
cargo make Se generará un paquete de controlador firmado, incluido un archivo WDRLocalTestCert.cer , en target/<Cargo profile>/package . Si se especificó una arquitectura de destino específica, el paquete del controlador se generará en target/<target architecture>/<Cargo profile>/package
Se pueden encontrar ejemplos mínimos de controladores WDM , KMDF y UMDF en el directorio de ejemplos.
cargo-make se utiliza para facilitar las compilaciones con windows-drivers-rs , incluso para ejecutar pasos de embalaje del controlador posterior a la construcción.
Para ejecutar la acción predeterminada (compilación y controlador de paquete):
cargo make default
Al ejecutar la tarea predeterminada, Just cargo make Make también funciona ya que la tarea default está implícita.
windows-drivers-rs extiende cargo make para reenviar argumentos específicos a los comandos cargo subyacentes. Para especificar los argumentos para reenviarlos, deben proporcionarse después de especificar explícitamente el nombre de la tarea cargo-make (es decir, omitir el nombre de la tarea default no es compatible).
Para un objetivo específico:
cargo make default --target <TARGET TRIPLE>
Para construcciones de lanzamiento:
cargo make default --release o cargo make default --profile release
Para especificar características específicas:
cargo make default --features <FEATURES>
Para especificar una cadena de herramientas de óxido específica:
cargo make default +<TOOLCHAIN>
Para mostrar ayuda y ver la lista completa de CLI Args compatibles para reenviar a la carga:
cargo make help
La variable de entorno WDK_BUILD_ENABLE_SIGNTOOL_VERIFY Cargo-Make se puede establecer en true para habilitar las tareas que manejan la verificación de la firma de los archivos .sys y .cat generados. signtool verify requiere que el certificado se instale como en las Trusted Root Certification Authorities para que esta verificación funcione. Estas tareas no están habilitadas de forma predeterminada ya que el comportamiento predeterminado de WDR es firmar con un certificado de prueba generado. Estos certificados de prueba generalmente solo se instalan en Trusted Root Certification Authorities en computadoras dedicadas a probar controladores, y no máquinas de desarrollo personal, dadas las implicaciones de seguridad de instalar sus propios certificados raíz.
Si comprende estas implicaciones y ha instalado el certificado de prueba, puede validar las firmas de la siguiente manera:
cargo make --env WDK_BUILD_ENABLE_SIGNTOOL_VERIFY=true
Las liberaciones a las cajas no se realizan después de que cada cambio se fusione con Main. Las versiones solo se realizarán cuando lo solicite la comunidad, o cuando el equipo windows-drivers-rs cree que hay un valor suficiente para impulsar una liberación.
Marcas comerciales Este proyecto puede contener marcas comerciales o logotipos para proyectos, productos o servicios. El uso autorizado de marcas o logotipos de Microsoft está sujeto y debe seguir las pautas de marca y marca de Microsoft. El uso de marcas registradas de Microsoft o logotipos en versiones modificadas de este proyecto no debe causar confusión o implicar el patrocinio de Microsoft. Cualquier uso de marcas comerciales o logotipos de terceros está sujeto a las políticas de esas partes de terceros.
