windows drivers rs
v0.3.0
Ce repo est une collection de caisses de rouille qui permettent aux développeurs de développer des pilotes Windows dans la rouille. C'est l'intention de prendre en charge les modèles de développement du pilote WDM et WDF. Ce repo contient les caisses suivantes:
bindgen , ainsi que les réimplémentations manuelles des macros que Bindgen ne parvient pas à générer.wdk-sys et les caisses ne devraient généralement jamais avoir besoin de dépendre directement de wdk-macrosPour voir un exemple de ce dépôt utilisé pour créer des pilotes, voir les échantillons Windows-Rust-Driver.
Remarque: Ce projet est encore en début de développement et n'est pas encore recommandé pour l'utilisation de la production. Nous encourageons l'expérimentation communautaire, les suggestions et les discussions! Nous utiliserons notre forum de discussions GitHub comme principale forme d'engagement avec la communauté!
Ce projet a été construit avec le soutien aux pilotes WDM, KMDF et UMDF, ainsi que les services Win32. Cela comprend la prise en charge de toutes les versions de WDF incluses dans WDK 22H2 et plus récentes. Actuellement, les caisses disponibles sur crates.io ne prennent en charge que KMDF v1.33, mais les liaisons peuvent être générées pour tout le reste en clonage windows-drivers-rs et modifiant la configuration spécifiée dans build.rs de wdk-sys . Crates.io La prise en charge des autres configurations WDK est prévue dans un avenir proche.
Remarque:: Étant donné que les exemples de niveau d'espace de travail et les tests utilisent différentes configurations WDK, et que WDR ne prend en charge qu'une seule configuration WDK par espace de travail, le dossier des exemples et tests au niveau de l'espace de travail est exclu du manifeste du fret de la racine du référentiel.
La génération de liaison via bindgen nécessite libclang . La façon la plus simple d'acquérir ceci est via winget
winget install -i LLVM.LLVM --version 17.0.6 --force Pour exécuter des tâches post-construction (c.-à-d. inf2cat , infverif , etc.), cargo make est utilisée
cargo install --locked cargo-make --no-default-features --features tls-nativeLa construction de programmes avec le WDK nécessite également d'être dans un environnement WDK valide. La façon recommandée de procéder est d'entrer une invite de développeur EWDK
Les caisses de ce référentiel sont disponibles sur crates.io , mais prennent en compte les limitations actuelles décrites dans les configurations prises en charge. Si vous devez prendre en charge une configuration différente, essayez de cloner ce dépôt et d'utiliser des dépendances de chemin
Créez un nouveau package de fret avec une caisse Lib:
cargo new < driver_name > -- lib Ajouter des dépendances sur les caisses windows-drivers-rs :
cd < driver_name >
cargo add -- build wdk - build
cargo add wdk wdk - sys wdk - alloc wdk - panic Réglez le type de caisse sur cdylib en ajoutant l'extrait suivant sur Cargo.toml :
[ lib ]
crate-type = [ " cdylib " ]Ajoutez une section de métadonnées WDK et configurez le WDK pour votre cas d'utilisation. Cela permet également aux tâches de fabrication de cargaisage de savoir que le package est un pilote et que les étapes d'emballage du pilote doivent s'exécuter.
Exemple UMDF:
[ package . metadata . wdk . driver-model ]
driver-type = " UMDF "
umdf-version-major = 1
target-umdf-version-minor = 33 Pour les caisses en mode noyau (ex. Drivers KMDF , pilotes WDM ): définissez la stratégie de panique de caisse pour abort dans Cargo.toml :
[ profile . dev ]
panic = " abort "
[ profile . release ]
panic = " abort " Créez un build.rs et ajoutez l'extrait suivant:
fn main ( ) -> Result < ( ) , wdk_build :: ConfigError > {
wdk_build :: configure_wdk_binary_build ( )
} Pour les caisses en mode noyau (Ex. Drivers KMDF , pilotes WDM ): Marquez votre caisse de conducteur comme no_std dans lib.rs :
#! [ no_std ] Pour les caisses en mode noyau (Ex. Drivers KMDF , pilotes WDM ): Ajoutez un gestionnaire de panique dans lib.rs :
# [ cfg ( not ( test ) ) ]
extern crate wdk_panic ; Pour les caisses en mode du noyau (Ex. Drivers KMDF , pilotes WDM ): Ajoutez un allocateur global facultatif dans lib.rs :
# [ cfg ( not ( test ) ) ]
use wdk_alloc :: WdkAllocator ;
# [ cfg ( not ( test ) ) ]
# [ global_allocator ]
static GLOBAL_ALLOCATOR : WdkAllocator = WdkAllocator ; Ceci n'est requis que si vous souhaitez pouvoir utiliser les modules alloc dans la bibliothèque Standard Rust.
Ajoutez un conducteur dans 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
} Remarque: Dans les caisses en mode du noyau, vous pouvez utiliser driver: &mut DRIVER_OBJECT au lieu driver: PDRIVER_OBJECT .
Ajouter 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()?
''' Ajoutez un fichier INX qui correspond au nom de votre caisse cdylib .
Activer la liaison CRT statique. Une approche consiste à l'ajouter à votre .cargo/config.toml :
[ build ]
rustflags = [ " -C " , " target-feature=+crt-static " ]Construisez le conducteur:
cargo make Un package de pilotes signé, y compris un fichier WDRLocalTestCert.cer , sera généré sur target/<Cargo profile>/package . Si une architecture cible spécifique a été spécifiée, le package du pilote sera généré à target/<target architecture>/<Cargo profile>/package
Des exemples minimaux de pilotes WDM , KMDF et UMDF peuvent être trouvés dans le répertoire des exemples.
cargo-make est utilisée pour faciliter les builds à l'aide windows-drivers-rs , y compris pour exécuter les étapes d'emballage du pilote post-construction.
Pour exécuter l'action par défaut (build et pilote de package):
cargo make default
Lors de l'exécution de la tâche par défaut, il suffit de faire fonctionner cargo make car la tâche default est implicite.
windows-drivers-rs étend cargo make pour transmettre des arguments spécifiques aux commandes cargo sous-jacentes. Afin de spécifier les arguments à transmettre, ils doivent être fournis après avoir explicitement spécifié le nom de la tâche cargo-make (c'est-à-dire que l'omission du nom de la tâche default n'est pas pris en charge).
Pour une cible spécifique:
cargo make default --target <TARGET TRIPLE>
Pour les constructions de libération:
cargo make default --release ou cargo make default --profile release
Pour spécifier des fonctionnalités spécifiques:
cargo make default --features <FEATURES>
Pour spécifier une chaîne d'outils de rouille spécifique:
cargo make default +<TOOLCHAIN>
Pour afficher l'aide et voir la liste complète des args CLI pris en charge à transmettre à la cargaison:
cargo make help
La variable d'environnement WDK_BUILD_ENABLE_SIGNTOOL_VERIFY GARGO-MAKE peut être définie sur true pour activer les tâches qui gèrent la vérification de signature des fichiers .sys et .cat générés. signtool verify nécessite que le certificat soit installé comme dans les Trusted Root Certification Authorities pour que cette vérification fonctionne. Ces tâches ne sont pas activées par défaut, car le comportement par défaut de WDR est de signer avec un certificat de test généré. Ces certificats de test ne sont généralement installés que dans Trusted Root Certification Authorities sur des ordinateurs dédiés aux tests de tests, et non aux machines de développement personnel, compte tenu des implications de sécurité de l'installation de vos propres certificats racine.
Si vous comprenez ces implications et avez installé le certificat de test, vous pouvez valider les signatures comme suit:
cargo make --env WDK_BUILD_ENABLE_SIGNTOOL_VERIFY=true
Les versions sur Crates.io ne sont pas effectuées après que chaque changement a fusionné en main. Les sorties ne seront effectuées que lorsque la communauté demandera par la communauté ou lorsque l'équipe windows-drivers-rs pense qu'il y a une valeur suffisante dans la poussée d'une version.
Marquettes Ce projet peut contenir des marques ou des logos pour des projets, des produits ou des services. L'utilisation autorisée de marques ou de logos Microsoft est soumise et doit suivre les directives de marque et de marque de Microsoft. L'utilisation de marques ou de logos de Microsoft dans des versions modifiées de ce projet ne doit pas provoquer de confusion ou impliquer le parrainage de Microsoft. Toute utilisation de marques ou de logos tiers est soumis aux politiques de ces tiers.
