#![cfg(all(target_os = "windows", target_arch = "x86_64"))]
mod messages;
mod option;
mod utils;
use crate::messages::{
GetTraceResponseHeader, Request, Response, SetPerImageTracingOption, TRACE_VERSION,
};
use crate::utils::ctl_code;
use core::iter::FusedIterator;
use core::mem::MaybeUninit;
pub use messages::{
AddressFilterMode, AddressFilterRangeResponse, NUM_TRIES_UNLIMITED, TraceRecordHeader,
};
pub use option::{IptOption, MatchSettings, RingFilter, TimingMode, TraceMode};
use windows::Win32::Foundation::{ERROR_INVALID_DATA, 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::{Error, Owned, w};
#[derive(Debug, PartialEq, Eq)]
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);
out.inner.clear();
let (result, 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),
);
assert!(
out_size as usize <= out.inner.capacity(),
"driver reported writing {out_size} bytes into a {} byte buffer",
out.inner.capacity()
);
if (out_size as usize) < size_of::<GetTraceResponseHeader>() {
result?;
return Err(Error::new(
ERROR_INVALID_DATA.to_hresult(),
"driver reported a response shorter than a trace response header",
));
}
unsafe { out.inner.set_len(out_size as usize) };
let header = unsafe {
out.inner
.as_ptr()
.cast::<GetTraceResponseHeader>()
.read_unaligned()
};
debug_assert_eq!(header.trace_version, TRACE_VERSION);
#[cfg(feature = "log")]
{
if header.response_version != GetTraceResponseHeader::RESPONSE_VERSION_EXPECTED {
log::warn!(
"Trace header field `response_version` has an unexpected value {}, expected: {}",
header.response_version,
GetTraceResponseHeader::RESPONSE_VERSION_EXPECTED
);
}
}
debug_assert_eq!(
header.bytes_written as usize,
out_size as usize - size_of::<GetTraceResponseHeader>()
);
result
}
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_enabled } != 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_enabled } != 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>());
let raw = unsafe { response.trace_config.ipt_option };
IptOption::try_from(raw).map_err(|_| {
Error::new(
ERROR_INVALID_DATA.to_hresult(),
"driver returned an option word that does not decode into an IptOption",
)
})
}
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>());
if AddressFilterMode::from_repr(u32::from_ne_bytes(
response.as_bytes()[0..size_of::<AddressFilterMode>()]
.try_into()
.unwrap(),
))
.is_none()
{
return Err(Error::new(
ERROR_INVALID_DATA.to_hresult(),
"driver reported a reserved address filter mode",
));
}
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 (result, 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,
);
result?;
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();
self.send_ioctl_raw(
ioctl_method,
input,
input_size,
response.as_mut_ptr().cast(),
size_of::<Response>() as u32,
)
.0?;
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;
let result = unsafe {
DeviceIoControl(
*self.ipt_handle,
ioctl,
Some(input),
input_size,
Some(out),
out_capacity,
Some(&raw mut out_size),
None,
)
};
(result, out_size)
}
}
#[derive(Debug, Clone, PartialEq)]
pub struct TraceBuffer {
inner: Vec<u8>,
}
impl TraceBuffer {
#[must_use]
pub const fn new() -> Self {
Self { inner: Vec::new() }
}
#[must_use]
pub fn with_capacity(capacity: u64) -> Self {
Self {
inner: Vec::with_capacity(capacity as usize),
}
}
#[must_use]
pub const fn capacity(&self) -> u64 {
self.inner.capacity() as u64
}
#[must_use]
pub const fn len(&self) -> usize {
self.inner.len()
}
#[must_use]
pub const fn is_empty(&self) -> bool {
self.inner.is_empty()
}
pub fn reserve(&mut self, capacity: u64) {
self.inner.reserve(capacity as usize)
}
pub fn clear(&mut self) {
self.inner.clear()
}
#[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> {
let remaining = self.buffer.inner.len().saturating_sub(self.i);
if remaining < size_of::<TraceRecordHeader>() {
#[cfg(feature = "log")]
if remaining != 0 {
log::warn!(
"Trace buffer ends with {remaining} trailing bytes, too few for a {} byte \
record header; the response is truncated",
size_of::<TraceRecordHeader>()
);
}
return None;
}
let header_ptr = self.buffer.inner[self.i..self.i + size_of::<TraceRecordHeader>()]
.as_ptr()
.cast::<TraceRecordHeader>();
debug_assert!(header_ptr.is_aligned());
let header = unsafe { header_ptr.as_ref_unchecked() };
let payload_length = header.payload_length as usize;
let payload_start = self.i + size_of::<TraceRecordHeader>();
if self.buffer.inner.len() - payload_start < payload_length {
#[cfg(feature = "log")]
log::warn!(
"Trace record for thread {} claims a {payload_length} byte payload but only {} \
bytes remain; the response is truncated",
{ header.thread_id },
self.buffer.inner.len() - payload_start
);
return None;
}
self.i = payload_start + payload_length;
let data = &self.buffer.inner[payload_start..self.i];
Some((header, data))
}
}
impl<'a> FusedIterator for TraceBufferIter<'a> {}
impl Default for TraceBuffer {
fn default() -> Self {
Self::new()
}
}