Add an EtwDriverProvider for Windows kernel-mode support.

README.md

@@ -156,6 +156,22 @@ These tools can also be used to capture ETW events:
 
 There are other tools, such as the Windows Performance Recorder, which can capture ETW events.
 
+## Building and using tracing for Windows kernel-mode drivers
+
+This repo has experimental support for ETW tracing in Windows kernel-mode drivers written in Rust (see the [windows-drivers-rs](https://github.com/microsoft/windows-drivers-rs) repo.)  To allow this repo to be built without requiring the Windows Driver Kit in all scenarios, this `windows_drivers` feature - present in both the `win_etw_provider` and `win_etw_macros` crates - is **mutually exclusive** with the default `windows_apps` feature.  
+
+To build this feature, you must install the Windows Driver Kit and LLVM to enable linking to driver DDIs.  See [the windows-drivers-rs README](https://github.com/microsoft/windows-drivers-rs?tab=readme-ov-file#build-requirements) for details on on how to do this.
+
+Once this is done, the `windows_drivers` feature can be built.
+
+To use this feature in a Rust driver, when adding the `win_etw_provider` and `win_etw_macros` crates to your Cargo.toml file, make sure you set `default-features` to **false** in your cargo.toml file and activate the `windows_drivers` feature for both:
+
+```toml
+[dependencies]
+win_etw_macros = { version = "^0.1.11", default-features = false, features = "windows_drivers" }
+win_etw_provider = { version = "^0.1.11", default-features = false, features = "windows_drivers" }
+```
+
 ## Ideas for improvement
 
 * Better handling of per-event overrides, rather than using `Option<&EventOptions>`.

win_etw_macros/Cargo.toml

@@ -20,3 +20,8 @@ quote = "^1.0"
 win_etw_metadata = { version = "0.1.2", path = "../win_etw_metadata" }
 uuid = { version = "^1.3", features = ["v5"]}
 sha1_smol = "1.0.0"
+
+[features]
+default = ["windows_apps"]
+windows_apps = []
+windows_drivers = []

win_etw_macros/src/lib.rs

@@ -25,10 +25,6 @@
 //! win_etw_provider = "0.1.*"
 //! ```
 //!
-//! `win_etw_macros` contains the procedural macro that generates eventing code.
-//! `win_etw_provider` contains library code that is called by the code that is generated by
-//! `win_etw_macros`.
-//!
 //! ### Define the event provider and its events
 //!
 //! Add a trait definition to your source code and annotate it with the `#[trace_logging_provider]`
@@ -182,6 +178,19 @@
 //!
 //! There are other tools, such as the Windows Performance Recorder, which can capture ETW events.
 //!
+//! # Using this crate for kernel-mode driver development
+//!
+//! This crate can be used when developing Windows device drivers in conjunction with the [wdk](https://crates.io/crates/wdk) crate.
+//!
+//! If you are developing for kernel-mode, you should add these dependencies to your crate:
+//! ```text
+//![dependencies]
+//!win_etw_macros = { version = "^0.1.11", default-features = false, features = "windows_drivers" }
+//!win_etw_provider = { version = "^0.1.11", default-features = false, features = "windows_drivers" }
+//! ```
+//!
+//! Then apply the `#[trace_logging_provider_kernel]` macro rather than `#[trace_logging_provider]`.
+//!
 //! # References
 //! * [Event Tracing for Windows (ETW) Simplified](https://support.microsoft.com/en-us/help/2593157/event-tracing-for-windows-etw-simplified)
 //! * [TraceLogging for Event Tracing for Windows (ETW)](https://docs.microsoft.com/en-us/windows/win32/tracelogging/trace-logging-portal)
@@ -224,11 +233,26 @@ pub fn trace_logging_provider(
     input: proc_macro::TokenStream,
 ) -> proc_macro::TokenStream {
     // let logging_trait = parse_macro_input!(input as syn::ItemTrait);
-    let output = trace_logging_events_core(attr.into(), input.into());
+    let output = trace_logging_events_core::<false>(attr.into(), input.into());
     output.into()
 }
 
-fn trace_logging_events_core(attr: TokenStream, item_tokens: TokenStream) -> TokenStream {
+/// Allows you to create ETW Trace Logging Providers in a Windows driver kernel-mode context. See the module docs for more detailed
+/// instructions for this macro.
+#[cfg(all(not(feature = "windows_apps"), feature = "windows_drivers"))]
+#[proc_macro_attribute]
+pub fn trace_logging_provider_kernel(
+    attr: proc_macro::TokenStream,
+    input: proc_macro::TokenStream,
+) -> proc_macro::TokenStream {
+    let output = trace_logging_events_core::<true>(attr.into(), input.into());
+    output.into()
+}
+
+fn trace_logging_events_core<const KERNEL_MODE: bool>(
+    attr: TokenStream,
+    item_tokens: TokenStream,
+) -> TokenStream {
     let mut errors: Vec<Error> = Vec::new();
 
     let logging_trait: syn::ItemTrait = match syn::parse2(item_tokens) {
@@ -603,10 +627,16 @@ fn trace_logging_events_core(attr: TokenStream, item_tokens: TokenStream) -> Tok
         provider_attrs.provider_group_guid.as_ref(),
     );
 
+    let provider_type = if KERNEL_MODE {
+        quote! { win_etw_provider::EtwDriverProvider }
+    } else {
+        quote! { win_etw_provider::EtwProvider }
+    };
+
     output.extend(quote! {
         #( #provider_doc_attrs )*
         #vis struct #provider_ident {
-            provider: ::core::option::Option<::win_etw_provider::EtwProvider>,
+            provider: ::core::option::Option<#provider_type>,
         }
 
         impl #provider_ident {
@@ -621,7 +651,7 @@ fn trace_logging_events_core(attr: TokenStream, item_tokens: TokenStream) -> Tok
             /// event consumers, etc. Applications should only create event sources during process
             /// initialization, and should always reuse them, never re-creating them.
             pub fn new() -> Self {
-                let provider = match ::win_etw_provider::EtwProvider::new(&Self::PROVIDER_GUID) {
+                let provider = match #provider_type::new(&Self::PROVIDER_GUID) {
                     Ok(mut provider) => {
                         #[cfg(target_os = "windows")]
                         {
@@ -647,7 +677,7 @@ fn trace_logging_events_core(attr: TokenStream, item_tokens: TokenStream) -> Tok
             /// initialization, and should always reuse them, never re-creating them.
             pub fn new_err() -> ::core::result::Result<Self, ::win_etw_provider::Error> {
                 Ok(Self {
-                    provider: Some(::win_etw_provider::EtwProvider::new(&Self::PROVIDER_GUID)?),
+                    provider: Some(#provider_type::new(&Self::PROVIDER_GUID)?),
                 })
             }
 

win_etw_macros/src/tests.rs

@@ -47,7 +47,7 @@ impl syn::parse::Parse for CompileErrors {
 }
 
 fn test_worker(attrs: TokenStream, input: TokenStream, expected_errors: &[&'static str]) {
-    let output = trace_logging_events_core(attrs, input);
+    let output = trace_logging_events_core::<false>(attrs, input);
 
     // Set WIN_ETW_SHOW_OUTPUT=1 (or = anything at all) to see the output of
     // the trace_logging_provider macro for unit tests. This is useful during

win_etw_provider/Cargo.toml

@@ -7,7 +7,6 @@ description = "Enables apps to report events to Event Tracing for Windows (ETW).
 license = "Apache-2.0 OR MIT"
 homepage = "https://github.com/microsoft/rust_win_etw"
 readme = "../README.md"
-rust-version = "1.77"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
@@ -16,6 +15,7 @@ widestring = {version = "^1.0", default-features = false, features = ["alloc"]}
 zerocopy = { version = "0.7.32", features = ["derive"] }
 win_etw_metadata = { version = "^0.1.2", path = "../win_etw_metadata" }
 uuid = {version = "1", optional = true}
+wdk-sys = { version = "^0.2.0", optional = true }
 
 [target.'cfg(windows)'.dependencies]
 winapi = { version = "^0.3", features = ["evntprov", "winerror", "evntrace"] }
@@ -27,7 +27,9 @@ uuid = "1"
 
 [features]
 std = []
-default = ["no_std"]
+default = ["no_std", "windows_apps"]
+windows_apps = []
 no_std = []
+windows_drivers = ["wdk-sys", "no_std"]
 # dev is used only for development
-dev = []
+dev = []