#![cfg(target_os = "windows")]
mod messages;
mod option;
mod utils;
use crate::messages::{
GetTraceResponseHeader, Request, Response, SetPerImageTracingOption, TRACE_VERSION,
TraceRecordHeader,
};
use crate::utils::ctl_code;
use core::mem::MaybeUninit;
pub use messages::{AddressFilterMode, AddressFilterRangeResponse, NUM_TRIES_UNLIMITED};
pub use option::IptOption;
use windows::Win32::Foundation::HANDLE;
use windows::Win32::Storage::FileSystem::{
CreateFileW, FILE_ATTRIBUTE_NORMAL, FILE_FLAG_NO_BUFFERING, FILE_FLAG_SEQUENTIAL_SCAN,
FILE_GENERIC_READ, FILE_SHARE_READ, OPEN_EXISTING,
};
use windows::Win32::System::IO::DeviceIoControl;
use windows::Win32::System::Ioctl::{
FILE_ANY_ACCESS, FILE_DEVICE_UNKNOWN, METHOD_BUFFERED, METHOD_OUT_DIRECT,
};
use windows::core::{Owned, w};
#[derive(Debug)]
pub struct Ipt {
ipt_handle: Owned<HANDLE>,
}
impl Ipt {
pub fn open() -> windows::core::Result<Self> {
let ipt_path = w!("\\\\.\\IPT");
unsafe {
CreateFileW(
ipt_path,
FILE_GENERIC_READ.0,
FILE_SHARE_READ,
None,
OPEN_EXISTING,
FILE_ATTRIBUTE_NORMAL | FILE_FLAG_SEQUENTIAL_SCAN | FILE_FLAG_NO_BUFFERING,
None,
)
}
.map(|h| Self {
ipt_handle: unsafe { Owned::new(h) },
})
.inspect_err(|e| {
#[cfg(feature = "log")]
log::error!(
"Failed to open IPT device: {e};\nMake sure the ipt service is running with\
`sc start ipt` from an admin shell."
);
})
}
pub fn get_interface_version(&self) -> windows::core::Result<u16> {
let request = Request::get_interface_version();
let (response, response_size) = self.send_ioctl(METHOD_BUFFERED, &request)?;
debug_assert_eq!(response_size as usize, size_of::<Response>());
Ok(unsafe { response.interface_version })
}
pub fn get_trace_buffer_size(&self, process_handle: HANDLE) -> windows::core::Result<u64> {
let request = Request::get_trace_buffer_size(process_handle);
let (response, response_size) = self.send_ioctl(METHOD_BUFFERED, &request)?;
debug_assert_eq!(response_size as usize, size_of::<Response>());
let trace_buffer_size = unsafe { response.trace_buffer_size };
debug_assert_eq!(trace_buffer_size.trace_version, TRACE_VERSION);
Ok(trace_buffer_size.trace_size)
}
pub fn get_trace_buffer(
&self,
process_handle: HANDLE,
out: &mut TraceBuffer,
) -> windows::core::Result<()> {
let request = Request::get_trace_buffer(process_handle);
let out_size = self.send_ioctl_raw_out(
METHOD_OUT_DIRECT,
&request,
out.inner.as_mut_ptr().cast(),
out.inner.capacity().try_into().unwrap_or(u32::MAX),
)?;
debug_assert!(out_size as usize <= out.inner.capacity());
unsafe { out.inner.set_len(out_size as usize) };
debug_assert!(
out.inner
.as_ptr()
.cast::<GetTraceResponseHeader>()
.is_aligned()
);
let header = unsafe {
out.inner
.as_ptr()
.cast::<GetTraceResponseHeader>()
.as_ref_unchecked()
};
debug_assert_eq!(header.trace_version, TRACE_VERSION);
#[cfg(feature = "log")]
{
if header.unknown != GetTraceResponseHeader::UNKNOWN_EXPECTED {
log::warn!(
"Trace header field `unknown` has an unexpected value {}, expected: {} ",
header.unknown,
GetTraceResponseHeader::UNKNOWN_EXPECTED
);
}
}
debug_assert_eq!(
header.bytes_written as usize,
out_size as usize - size_of::<GetTraceResponseHeader>()
);
Ok(())
}
pub fn set_system_wide_tracing_option(
&self,
ipt_option: IptOption,
num_tries: u32,
ttl_seconds: u32,
) -> windows::core::Result<()> {
let request = Request::set_system_wide_tracing_option(ipt_option, num_tries, ttl_seconds);
self.send_ioctl(METHOD_BUFFERED, &request)?;
Ok(())
}
pub fn set_per_image_tracing_option(
&self,
ipt_option: IptOption,
num_tries: u32,
ttl_seconds: u32,
image_name: &[u16],
second_string: Option<&[u16]>,
) -> windows::core::Result<()> {
let req = SetPerImageTracingOption::raw_request(
ipt_option,
num_tries,
ttl_seconds,
image_name,
second_string,
);
self.send_ioctl_raw_in(METHOD_BUFFERED, req.as_ptr().cast(), req.len() as u32)?;
Ok(())
}
pub fn start_process_trace(
&self,
process_handle: HANDLE,
ipt_option: IptOption,
) -> windows::core::Result<()> {
let request = Request::start_process_trace(process_handle, ipt_option);
self.send_ioctl(METHOD_BUFFERED, &request)?;
Ok(())
}
pub fn start_process_trace_ex(
&self,
process_handle: HANDLE,
trace_file_handle: HANDLE,
ipt_option: IptOption,
) -> windows::core::Result<()> {
let request =
Request::start_process_trace_ex(process_handle, trace_file_handle, ipt_option);
self.send_ioctl(METHOD_BUFFERED, &request)?;
Ok(())
}
pub fn stop_process_trace(&self, process_handle: HANDLE) -> windows::core::Result<()> {
let request = Request::stop_process_trace(process_handle);
self.send_ioctl(METHOD_BUFFERED, &request)?;
Ok(())
}
pub fn pause_thread_trace(&self, thread_handle: HANDLE) -> windows::core::Result<bool> {
let request = Request::pause_thread_trace(thread_handle);
let (response, response_size) = self.send_ioctl(METHOD_BUFFERED, &request)?;
debug_assert_eq!(response_size as usize, size_of::<Response>());
Ok(unsafe { response.pause_state.previously_paused } != 0)
}
pub fn resume_thread_trace(&self, thread_handle: HANDLE) -> windows::core::Result<bool> {
let request = Request::resume_thread_trace(thread_handle);
let (response, response_size) = self.send_ioctl(METHOD_BUFFERED, &request)?;
debug_assert_eq!(response_size as usize, size_of::<Response>());
Ok(unsafe { response.pause_state.previously_paused } != 0)
}
pub fn query_process_trace_configuration(
&self,
process_handle: HANDLE,
) -> windows::core::Result<IptOption> {
let request = Request::query_process_trace_configuration(process_handle);
let (response, response_size) = self.send_ioctl(METHOD_BUFFERED, &request)?;
debug_assert_eq!(response_size as usize, size_of::<Response>());
Ok(unsafe { response.trace_config.ipt_option })
}
pub fn query_system_wide_tracing_state(&self) -> windows::core::Result<u64> {
let request = Request::query_system_wide_tracing_state();
let (response, response_size) = self.send_ioctl(METHOD_BUFFERED, &request)?;
debug_assert_eq!(response_size as usize, size_of::<Response>());
Ok(unsafe { response.core_tracing_state.state })
}
pub fn stop_system_wide_tracing(&self) -> windows::core::Result<()> {
let request = Request::stop_system_wide_tracing();
self.send_ioctl(METHOD_BUFFERED, &request)?;
Ok(())
}
pub fn configure_thread_address_filter_range(
&self,
thread_handle: HANDLE,
range_index: u32,
mode: AddressFilterMode,
start_address: u64,
end_address: u64,
) -> windows::core::Result<()> {
let request = Request::configure_thread_address_filter_range(
thread_handle,
range_index,
mode,
start_address,
end_address,
);
self.send_ioctl(METHOD_BUFFERED, &request)?;
Ok(())
}
pub fn query_thread_address_filter_range(
&self,
thread_handle: HANDLE,
range_index: u32,
) -> windows::core::Result<AddressFilterRangeResponse> {
let request = Request::query_thread_address_filter_range(thread_handle, range_index);
let (response, response_size) = self.send_ioctl(METHOD_BUFFERED, &request)?;
debug_assert_eq!(response_size as usize, size_of::<Response>());
Ok(unsafe { response.address_filter_range })
}
pub fn query_thread_trace_stop_range_entered(
&self,
thread_handle: HANDLE,
) -> windows::core::Result<bool> {
let request = Request::query_thread_trace_stop_range_entered(thread_handle);
let (response, response_size) = self.send_ioctl(METHOD_BUFFERED, &request)?;
debug_assert_eq!(response_size as usize, size_of::<Response>());
Ok(unsafe { response.trace_stop_entered.entered } != 0)
}
fn send_ioctl(
&self,
ioctl_method: u32,
request: &Request,
) -> windows::core::Result<(Response, u32)> {
let mut response = MaybeUninit::<Response>::uninit();
let out_size = self.send_ioctl_raw(
ioctl_method,
(&raw const *request).cast(),
size_of::<Request>() as u32,
response.as_mut_ptr().cast(),
size_of::<Response>() as u32,
)?;
Ok((unsafe { response.assume_init() }, out_size))
}
fn send_ioctl_raw_in(
&self,
ioctl_method: u32,
input: *const core::ffi::c_void,
input_size: u32,
) -> windows::core::Result<Response> {
let mut response = MaybeUninit::<Response>::uninit();
let out_size = self.send_ioctl_raw(
ioctl_method,
input,
input_size,
response.as_mut_ptr().cast(),
size_of::<Response>() as u32,
)?;
debug_assert_eq!(out_size as usize, size_of::<Response>());
Ok(unsafe { response.assume_init() })
}
fn send_ioctl_raw_out(
&self,
ioctl_method: u32,
request: &Request,
out: *mut core::ffi::c_void,
out_capacity: u32,
) -> windows::core::Result<u32> {
self.send_ioctl_raw(
ioctl_method,
(&raw const *request).cast(),
size_of::<Request>() as u32,
out,
out_capacity,
)
}
fn send_ioctl_raw(
&self,
ioctl_method: u32,
input: *const core::ffi::c_void,
input_size: u32,
out: *mut core::ffi::c_void,
out_capacity: u32,
) -> windows::core::Result<u32> {
let ioctl = ctl_code(FILE_DEVICE_UNKNOWN, 1, ioctl_method, FILE_ANY_ACCESS);
let mut out_size = 0;
unsafe {
DeviceIoControl(
*self.ipt_handle,
ioctl,
Some(input),
input_size,
Some(out),
out_capacity,
Some(&raw mut out_size),
None,
)
}?;
Ok(out_size)
}
}
#[derive(Debug, Clone, PartialEq)]
pub struct TraceBuffer {
inner: Vec<u8>,
}
impl TraceBuffer {
#[must_use]
pub fn with_capacity(capacity: u64) -> Self {
Self {
inner: Vec::with_capacity(capacity as usize),
}
}
#[must_use]
pub const fn iter(&self) -> TraceBufferIter<'_> {
TraceBufferIter {
buffer: self,
i: size_of::<GetTraceResponseHeader>(),
}
}
}
impl<'a> IntoIterator for &'a TraceBuffer {
type Item = (&'a TraceRecordHeader, &'a [u8]);
type IntoIter = TraceBufferIter<'a>;
fn into_iter(self) -> TraceBufferIter<'a> {
self.iter()
}
}
pub struct TraceBufferIter<'a> {
buffer: &'a TraceBuffer,
i: usize,
}
impl<'a> Iterator for TraceBufferIter<'a> {
type Item = (&'a TraceRecordHeader, &'a [u8]);
fn next(&mut self) -> Option<Self::Item> {
if self.buffer.inner.len() < self.i + size_of::<TraceRecordHeader>() {
return None;
}
let header_ptr = self.buffer.inner[self.i..self.i + size_of::<TraceRecordHeader>()]
.as_ptr()
.cast::<TraceRecordHeader>();
self.i += size_of::<TraceRecordHeader>();
debug_assert!(header_ptr.is_aligned());
let header = unsafe { header_ptr.as_ref_unchecked() };
let data = &self.buffer.inner[self.i..self.i + header.payload_length as usize];
self.i += header.payload_length as usize;
Some((header, data))
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test() {
let ipt = Ipt::open().unwrap();
assert_eq!(ipt.get_interface_version().unwrap(), 1);
}
}