windows drivers rs
v0.3.0
Repo ini adalah kumpulan peti karat yang memungkinkan pengembang untuk mengembangkan driver Windows di Rust. Ini adalah niat untuk mendukung model pengembangan driver WDM dan WDF. Repo ini berisi peti berikut:
bindgen , dan juga implementasi ulang makro manual yang Bindgen gagal menghasilkan.wdk-sys dan peti biasanya tidak perlu secara langsung bergantung pada wdk-macrosUntuk melihat contoh repo yang digunakan untuk membuat driver ini, lihat sampel-pengemudi windows-rust.
Catatan: Proyek ini masih dalam tahap awal pengembangan dan belum direkomendasikan untuk penggunaan produksi. Kami mendorong eksperimen, saran, dan diskusi masyarakat! Kami akan menggunakan Forum Diskusi GitHub kami sebagai bentuk utama keterlibatan dengan komunitas!
Proyek ini dibangun dengan dukungan pengemudi WDM, KMDF, dan UMDF, serta layanan Win32. Ini termasuk dukungan untuk semua versi WDF yang termasuk dalam WDK 22H2 dan lebih baru. Saat ini, peti yang tersedia di crates.io hanya mendukung KMDF v1.33, tetapi binding dapat dihasilkan untuk yang lainnya dengan mengkloning windows-drivers-rs dan memodifikasi konfigurasi yang ditentukan dalam build.rs dari wdk-sys . Dukungan Crates.io untuk konfigurasi WDK lainnya direncanakan dalam waktu dekat.
CATATAN :: Karena level ruang kerja contoh dan pengujian menggunakan konfigurasi WDK yang berbeda, dan WDR hanya mendukung satu konfigurasi WDK per ruang kerja, contoh-contoh dan folder tes di tingkat workspace dikecualikan dari manifes kargo root repositori.
Generasi pengikat melalui bindgen membutuhkan libclang . Cara termudah untuk memperoleh ini adalah melalui winget
winget install -i LLVM.LLVM --version 17.0.6 --force Untuk menjalankan tugas pasca-membangun (yaitu inf2cat , infverif , dll.), cargo make digunakan
cargo install --locked cargo-make --no-default-features --features tls-nativeMembangun program dengan WDK juga mengharuskan berada di lingkungan WDK yang valid. Cara yang disarankan untuk melakukan ini adalah dengan memasukkan prompt pengembang EWDK
Peti dalam repositori ini tersedia dari crates.io , tetapi memperhitungkan batasan saat ini yang diuraikan dalam konfigurasi yang didukung. Jika Anda perlu mendukung konfigurasi yang berbeda, coba kloning repo ini dan gunakan dependensi jalur
Buat paket kargo baru dengan peti lib:
cargo new < driver_name > -- lib Tambahkan dependensi pada peti windows-drivers-rs :
cd < driver_name >
cargo add -- build wdk - build
cargo add wdk wdk - sys wdk - alloc wdk - panic Atur tipe peti ke cdylib dengan menambahkan cuplikan berikut ke Cargo.toml :
[ lib ]
crate-type = [ " cdylib " ]Tambahkan bagian Metadata WDK dan konfigurasikan WDK untuk kasing Anda. Ini juga membuat tugas-tugas yang dibuat kargo tahu bahwa paket tersebut adalah pengemudi dan bahwa langkah pengemasan pengemudi perlu dijalankan.
Contoh UMDF:
[ package . metadata . wdk . driver-model ]
driver-type = " UMDF "
umdf-version-major = 1
target-umdf-version-minor = 33 Untuk peti mode kernel (mis. Driver KMDF , driver WDM ): Tetapkan strategi panik peti untuk abort Cargo.toml :
[ profile . dev ]
panic = " abort "
[ profile . release ]
panic = " abort " Buat build.rs dan tambahkan cuplikan berikut:
fn main ( ) -> Result < ( ) , wdk_build :: ConfigError > {
wdk_build :: configure_wdk_binary_build ( )
} Untuk peti mode kernel (mis. Driver KMDF , driver WDM ): Tandai peti pengemudi Anda sebagai no_std di lib.rs :
#! [ no_std ] Untuk peti mode kernel (mis. Driver KMDF , driver WDM ): Tambahkan penangan panik di lib.rs :
# [ cfg ( not ( test ) ) ]
extern crate wdk_panic ; Untuk peti mode kernel (mis. Driver KMDF , driver WDM ): Tambahkan alokasi global opsional di lib.rs :
# [ cfg ( not ( test ) ) ]
use wdk_alloc :: WdkAllocator ;
# [ cfg ( not ( test ) ) ]
# [ global_allocator ]
static GLOBAL_ALLOCATOR : WdkAllocator = WdkAllocator ; Ini hanya diperlukan jika Anda ingin dapat menggunakan modul alloc di perpustakaan standar karat.
Tambahkan driverentry di 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
} Catatan: Dalam peti mode kernel, Anda dapat menggunakan driver: &mut DRIVER_OBJECT alih -alih driver: PDRIVER_OBJECT .
Tambahkan 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()?
''' Tambahkan file INX yang cocok dengan nama peti cdylib Anda.
Aktifkan tautan CRT statis. Salah satu pendekatan adalah menambahkan ini ke .cargo/config.toml Anda:
[ build ]
rustflags = [ " -C " , " target-feature=+crt-static " ]Bangun pengemudi:
cargo make Paket driver yang ditandatangani, termasuk file WDRLocalTestCert.cer , akan dihasilkan di target/<Cargo profile>/package . Jika arsitektur target tertentu ditentukan, paket driver akan dihasilkan di target/<target architecture>/<Cargo profile>/package
Contoh minimal driver WDM , KMDF , dan UMDF dapat ditemukan di direktori Contoh.
cargo-make digunakan untuk memfasilitasi build menggunakan windows-drivers-rs , termasuk untuk mengeksekusi langkah pengemasan pengemudi pasca-membangun.
Untuk menjalankan tindakan default (Build and Package Driver):
cargo make default
Saat menjalankan tugas default, cukup cargo make juga berfungsi karena tugas default tersirat.
windows-drivers-rs memperluas cargo make untuk meneruskan argumen spesifik ke perintah cargo yang mendasarinya. Untuk menentukan argumen untuk diteruskan, mereka harus disediakan setelah secara eksplisit menentukan nama tugas cargo-make (mis. Menghilangkan nama untuk tugas default tidak didukung).
Untuk target tertentu:
cargo make default --target <TARGET TRIPLE>
Untuk pembuatan rilis:
cargo make default --release atau cargo make default --profile release
Untuk menentukan fitur spesifik:
cargo make default --features <FEATURES>
Untuk menentukan rust toolchain spesifik:
cargo make default +<TOOLCHAIN>
Untuk menampilkan bantuan dan melihat daftar lengkap CLI arg yang didukung untuk meneruskan ke kargo:
cargo make help
WDK_BUILD_ENABLE_SIGNTOOL_VERIFY Variabel lingkungan kargo-make dapat diatur ke true untuk mengaktifkan tugas yang menangani verifikasi tanda tangan dari file .sys dan .cat yang dihasilkan. signtool verify mengharuskan sertifikat untuk diinstal seperti pada Trusted Root Certification Authorities untuk verifikasi ini berfungsi. Tugas -tugas ini tidak diaktifkan secara default karena perilaku default WDR adalah untuk menandatangani dengan sertifikat pengujian yang dihasilkan. Sertifikat pengujian ini biasanya hanya diinstal ke Trusted Root Certification Authorities di komputer yang didedikasikan untuk pengujian, dan bukan mesin pengembangan pribadi, mengingat implikasi keamanan dari memasang sertifikat root Anda sendiri.
Jika Anda memahami implikasi ini, dan telah menginstal sertifikat pengujian, maka Anda dapat memvalidasi tanda tangan sebagai berikut:
cargo make --env WDK_BUILD_ENABLE_SIGNTOOL_VERIFY=true
Rilis ke peti.io tidak dilakukan setelah setiap perubahan digabungkan ke Main. Rilis hanya akan dilakukan ketika diminta oleh masyarakat, atau ketika tim windows-drivers-rs percaya ada nilai yang cukup dalam mendorong rilis.
Merek Dagang Proyek ini dapat berisi merek dagang atau logo untuk proyek, produk, atau layanan. Penggunaan resmi merek dagang atau logo Microsoft tunduk dan harus mengikuti pedoman merek dagang & merek Microsoft. Penggunaan merek dagang atau logo Microsoft dalam versi yang dimodifikasi dari proyek ini tidak boleh menyebabkan kebingungan atau menyiratkan sponsor Microsoft. Setiap penggunaan merek dagang atau logo pihak ketiga tunduk pada kebijakan pihak ketiga tersebut.
