windows drivers rs
v0.3.0
Этот репо является коллекцией ящиков ржавчины, которая позволяет разработчикам разрабатывать драйверы Windows в Rust. Это намерение поддерживать модели разработки водителей WDM и WDF. Этот репо содержит следующие ящики:
bindgen , так и ручные переопределения макросов, которые BindGen не могут генерировать.wdk-sys , а ящики обычно никогда не должны напрямую зависеть от wdk-macrosЧтобы увидеть пример этого репо, используемого для создания драйверов, см. Windows-Rust-Driver-Samples.
Примечание: этот проект все еще находится на ранних стадиях разработки и еще не рекомендуется для использования производства. Мы поощряем эксперименты, предложения и дискуссии сообщества! Мы будем использовать наш форум по обсуждению GitHub в качестве основной формы взаимодействия с сообществом!
Этот проект был построен с учетом поддержки водителей WDM, KMDF и UMDF, а также услуг Win32. Это включает в себя поддержку всех версий WDF, включенных в WDK 22H2 и новее. В настоящее время ящики, доступные на crates.io , поддерживают только KMDF v1.33, но привязки могут быть сгенерированы для всего остального путем клонирования windows-drivers-rs и изменяя конфигурацию, указанную в build.rs wdk-sys . Поддержка Crates.io для других конфигураций WDK запланирована в ближайшем будущем.
ПРИМЕЧАНИЕ.: Поскольку примеры и тесты на уровне рабочей области используют различные конфигурации WDK, а WDR поддерживает только одну конфигурацию WDK в рабочем пространстве, примеры и тесты на уровне рабочего пространства исключены из манифеста грузового корневого корнета.
Генерация связывания через bindgen требует libclang . Самый простой способ приобрести это через winget
winget install -i LLVM.LLVM --version 17.0.6 --force Для выполнения задач после сборки (т.е. inf2cat , infverif cargo make т. Д.)
cargo install --locked cargo-make --no-default-features --features tls-nativeСтроительство программ с WDK также требует быть в действительной среде WDK. Рекомендуемый способ сделать это - войти в подсказку разработчика EWDK
Ящики в этом репозитории доступны на crates.io , но принимают во внимание текущие ограничения, изложенные в поддерживаемых конфигурациях. Если вам нужно поддерживать другую конфигурацию, попробуйте клонировать это репо и использовать зависимости от пути
Создайте новый грузовой пакет с ящиком из либерального ящика:
cargo new < driver_name > -- lib Добавьте зависимости от ящиков windows-drivers-rs :
cd < driver_name >
cargo add -- build wdk - build
cargo add wdk wdk - sys wdk - alloc wdk - panic Установите тип ящика в cdylib , добавив следующий фрагмент в Cargo.toml :
[ lib ]
crate-type = [ " cdylib " ]Добавьте раздел метаданных WDK и настройте WDK для вашего варианта использования. Это также позволяет задачам в грузовом стиле знать, что пакет является драйвером и что для выполнения этапов упаковки водителя.
Пример UMDF:
[ package . metadata . wdk . driver-model ]
driver-type = " UMDF "
umdf-version-major = 1
target-umdf-version-minor = 33 Для ящиков режима ядра (пример KMDF драйверы, драйверы WDM ): установить стратегию паники ящика, чтобы abort в Cargo.toml :
[ profile . dev ]
panic = " abort "
[ profile . release ]
panic = " abort " Создайте build.rs и добавьте следующий фрагмент:
fn main ( ) -> Result < ( ) , wdk_build :: ConfigError > {
wdk_build :: configure_wdk_binary_build ( )
} Для ящиков режима ядра (пример KMDF драйверы, драйверы WDM ): отметьте ящик своего драйвера как no_std в lib.rs :
#! [ no_std ] Для ящиков режима ядра (пример KMDF драйверы, драйверы WDM ): добавьте обработчик паники в lib.rs :
# [ cfg ( not ( test ) ) ]
extern crate wdk_panic ; Для ящиков в режиме ядра (пример драйверов KMDF , драйверы WDM ): добавьте дополнительного глобального выплаты в lib.rs :
# [ cfg ( not ( test ) ) ]
use wdk_alloc :: WdkAllocator ;
# [ cfg ( not ( test ) ) ]
# [ global_allocator ]
static GLOBAL_ALLOCATOR : WdkAllocator = WdkAllocator ; Это требуется только в том случае, если вы хотите иметь возможность использовать модули alloc в стандартной библиотеке Rust.
Добавьте водители в 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
} Примечание. В ящиках в режиме ядра вы можете использовать driver: &mut DRIVER_OBJECT вместо driver: PDRIVER_OBJECT .
Добавьте 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()?
''' Добавьте INX -файл, который соответствует имени вашего ящика cdylib .
Включить статическую связь CRT. Один подход состоит в том, чтобы добавить это в свой .cargo/config.toml :
[ build ]
rustflags = [ " -C " , " target-feature=+crt-static " ]Создайте водителя:
cargo make Подписанный пакет драйверов, включая файл WDRLocalTestCert.cer , будет генерироваться в target/<Cargo profile>/package . Если была указана конкретная целевая архитектура, пакет драйверов будет сгенерирован в target/<target architecture>/<Cargo profile>/package
Минимальные примеры драйверов WDM , KMDF и UMDF можно найти в каталоге примеров.
cargo-make используется для облегчения сборки с использованием windows-drivers-rs , в том числе для выполнения этапов упаковки драйверов после сборки.
Чтобы выполнить действие по умолчанию (сборка и драйвер пакета):
cargo make default
При выполнении задачи по умолчанию, просто cargo make Make также работает, так как задача default подразумевается.
windows-drivers-rs расширяет cargo make , чтобы направить конкретные аргументы в основные команды cargo . Чтобы указать аргументы для пересылки, они должны быть предоставлены после явного указания имени задачи cargo-make (т.е. исключение имени для задачи default не поддерживается).
Для определенной цели:
cargo make default --target <TARGET TRIPLE>
Для выпуска сборки:
cargo make default --release или cargo make default --profile release
Чтобы указать конкретные функции:
cargo make default --features <FEATURES>
Чтобы указать конкретный инструмент инструментов ржавчины:
cargo make default +<TOOLCHAIN>
Чтобы отобразить помощь и увидеть полный список поддерживаемых CLI Args для перенаправления на груз:
cargo make help
Вместочная переменная среды для грузового приготовления WDK_BUILD_ENABLE_SIGNTOOL_VERIFY может быть установлена на true , чтобы включить задачи, которые обрабатывают проверку подписи сгенерированных файлов .sys и .cat . signtool verify требует, чтобы сертификат был установлен, как в Trusted Root Certification Authorities для этой проверки для функционирования. Эти задачи не включены по умолчанию, так как поведение WDR по умолчанию - подписать сгенерированным сертификатом испытаний. Эти сертификаты испытаний обычно устанавливаются только в Trusted Root Certification Authorities на компьютерах, посвященных тестирующим драйверам, а не на машинах для личных разработок, учитывая последствия для безопасности установки собственных корневых сертификатов.
Если вы понимаете эти последствия и установили сертификат испытаний, то вы можете проверить подписи следующим образом:
cargo make --env WDK_BUILD_ENABLE_SIGNTOOL_VERIFY=true
Выпуски для Crates.io не производятся после каждого изменения, объединенного в Main. Выпуски будут выполнены только по запросу сообщества или когда команда windows-drivers-rs считает, что в выпуске есть достаточная ценность.
Товарные знаки Этот проект может содержать товарные знаки или логотипы для проектов, продуктов или услуг. Уполномоченное использование товарных знаков или логотипов Microsoft подлежит и должно следовать указаниям Microsoft по товарной марке и брендам. Использование товарных знаков Microsoft или логотипов в модифицированных версиях этого проекта не должно вызывать путаницу или подразумевать спонсорство Microsoft. Любое использование сторонних товарных знаков или логотипов подвержена политике сторонних сторон.
