windows drivers rs
v0.3.0
Este repositório é uma coleção de caixas de ferrugem que permite aos desenvolvedores desenvolver drivers do Windows em ferrugem. É intenção suportar modelos de desenvolvimento de driver WDM e WDF. Este repo contém as seguintes caixas:
bindgen e também reimplementações manuais de macros que o BindGen não geram.wdk-sys e caixas normalmente nunca precisam depender diretamente de wdk-macrosPara ver um exemplo deste repositório usado para criar drivers, consulte SHAMPES Windows-Rust-Driver.
Nota: Este projeto ainda está em estágios iniciais de desenvolvimento e ainda não é recomendado para o uso da produção. Incentivamos a experimentação da comunidade, sugestões e discussões! Usaremos nosso fórum de discussões no Github como a principal forma de envolvimento com a comunidade!
Este projeto foi construído com o apoio aos drivers WDM, KMDF e UMDF em mente, bem como serviços Win32. Isso inclui suporte para todas as versões do WDF incluídas no WDK 22H2 e mais recente. Atualmente, as caixas disponíveis no crates.io suportam apenas o KMDF v1.33, mas as ligações podem ser geradas para todo o resto clonando windows-drivers-rs e modificando a configuração especificada no build.rs de wdk-sys . Crates.io O suporte a outras configurações do WDK está planejado em um futuro próximo.
NOTA:: Como os exemplos e testes do nível da área de trabalho usam diferentes configurações do WDK, e o WDR suporta apenas uma configuração WDK por espaço de trabalho, os exemplos de nível de trabalho e pasta de testes são excluídos do manifesto de carga da raiz do repositório.
A geração de ligação via bindgen requer libclang . A maneira mais fácil de adquirir isso é via winget
winget install -i LLVM.LLVM --version 17.0.6 --force Para executar tarefas pós-construção (ou seja, inf2cat , infverif , etc.), cargo make é usada
cargo install --locked cargo-make --no-default-features --features tls-nativeA construção de programas com o WDK também exige estar em um ambiente WDK válido. A maneira recomendada de fazer isso é inserir um prompt de desenvolvedor EWDK
As caixas deste repositório estão disponíveis na crates.io , mas leve em consideração as limitações atuais descritas nas configurações suportadas. Se você precisar suportar uma configuração diferente, tente clonar este repo e usar dependências de caminho
Crie um novo pacote de carga com uma caixa Lib:
cargo new < driver_name > -- lib Adicione dependências em caixas windows-drivers-rs :
cd < driver_name >
cargo add -- build wdk - build
cargo add wdk wdk - sys wdk - alloc wdk - panic Defina o tipo de caixa como cdylib , adicionando o seguinte snippet para Cargo.toml :
[ lib ]
crate-type = [ " cdylib " ]Adicione uma seção de metadados WDK e configure o WDK para o seu caso de uso. Isso também permite que as tarefas de make de carga saibam que o pacote é um driver e que as etapas de embalagem do motorista precisam ser executadas.
Exemplo umdf:
[ package . metadata . wdk . driver-model ]
driver-type = " UMDF "
umdf-version-major = 1
target-umdf-version-minor = 33 Para caixas de modo de kernel (por exemplo, drivers KMDF , drivers WDM ): Defina a estratégia de pânico para abort em Cargo.toml :
[ profile . dev ]
panic = " abort "
[ profile . release ]
panic = " abort " Crie um build.rs e adicione o seguinte snippet:
fn main ( ) -> Result < ( ) , wdk_build :: ConfigError > {
wdk_build :: configure_wdk_binary_build ( )
} Para caixas de modo de kernel (por exemplo, drivers KMDF , drivers WDM ): marque seu caixa de motorista como no_std em lib.rs :
#! [ no_std ] Para caixas de modo de kernel (por exemplo, drivers KMDF , drivers WDM ): Adicione um manipulador de pânico no lib.rs :
# [ cfg ( not ( test ) ) ]
extern crate wdk_panic ; Para caixas de modo de kernel (por exemplo, drivers KMDF , drivers WDM ): adicione um alocador global opcional no lib.rs :
# [ cfg ( not ( test ) ) ]
use wdk_alloc :: WdkAllocator ;
# [ cfg ( not ( test ) ) ]
# [ global_allocator ]
static GLOBAL_ALLOCATOR : WdkAllocator = WdkAllocator ; Isso só é necessário se você deseja usar os módulos alloc na biblioteca padrão de ferrugem.
Adicione um driverEntry em 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: Nos caixas do modo de kernel, você pode usar driver: &mut DRIVER_OBJECT em vez de driver: PDRIVER_OBJECT .
Adicione um 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()?
''' Adicione um arquivo INX que corresponda ao nome do seu cdylib Crate.
Habilite a ligação estática do CRT. Uma abordagem é adicionar isso ao seu .cargo/config.toml :
[ build ]
rustflags = [ " -C " , " target-feature=+crt-static " ]Construa o motorista:
cargo make Um pacote de driver assinado, incluindo um arquivo WDRLocalTestCert.cer , será gerado no target/<Cargo profile>/package . Se uma arquitetura de destino específica foi especificada, o pacote de driver será gerado no target/<target architecture>/<Cargo profile>/package
Exemplos mínimos de drivers WDM , KMDF e UMDF podem ser encontrados no diretório de exemplos.
cargo-make é usado para facilitar as construções usando windows-drivers-rs , inclusive para executar etapas de embalagem de motorista pós-compra.
Para executar a ação padrão (Build and Package Driver):
cargo make default
Ao executar a tarefa padrão, apenas cargo make também funciona, pois a tarefa default está implícita.
windows-drivers-rs estende cargo make para encaminhar argumentos específicos para os comandos cargo subjacente. Para especificar argumentos para encaminhar, eles devem ser fornecidos após especificar explicitamente o nome da tarefa cargo-make (ou seja. Omitindo o nome da tarefa default não é suportado).
Para um alvo específico:
cargo make default --target <TARGET TRIPLE>
Para construções de lançamento:
cargo make default --release ou cargo make default --profile release
Para especificar recursos específicos:
cargo make default --features <FEATURES>
Para especificar uma cadeia de ferramentas de ferrugem específica:
cargo make default +<TOOLCHAIN>
Para exibir ajuda e ver a lista completa de CLI Args suportados para encaminhar para a carga:
cargo make help
A variável WDK_BUILD_ENABLE_SIGNTOOL_VERIFY MAKEM MAKE pode ser definida como true para ativar tarefas que lidam com a verificação de assinatura dos arquivos .sys e .cat gerados. signtool verify exige que o certificado seja instalado como nas Trusted Root Certification Authorities para que essa verificação funcione. Essas tarefas não são ativadas por padrão, pois o comportamento padrão do WDR é assinar com um certificado de teste gerado. Esses certificados de teste geralmente são instalados apenas em Trusted Root Certification Authorities em computadores dedicados aos drivers de teste, e não em máquinas de desenvolvimento pessoal, dadas as implicações de segurança da instalação de seus próprios certificados raiz.
Se você entender essas implicações e instalar o certificado de teste, poderá validar as assinaturas da seguinte forma:
cargo make --env WDK_BUILD_ENABLE_SIGNTOOL_VERIFY=true
Os lançamentos para Crates.io não são feitos após cada alteração se fundir para o principal. Os lançamentos só serão feitos quando solicitados pela comunidade ou quando a equipe windows-drivers-rs acredita que há valor suficiente para impulsionar uma liberação.
Marcas comerciais Este projeto pode conter marcas comerciais ou logotipos para projetos, produtos ou serviços. O uso autorizado de marcas comerciais ou logotipos da Microsoft está sujeito e deve seguir as diretrizes de marca registrada e marca da Microsoft. O uso de marcas comerciais da Microsoft ou logotipos em versões modificadas deste projeto não deve causar confusão ou implicar o patrocínio da Microsoft. Qualquer uso de marcas comerciais ou logotipos de terceiros estão sujeitas às políticas de terceiros.
