use crate::IptOption;
use crate::option::IptOptionRaw;
use core::slice;
use windows::Win32::Foundation::HANDLE;
pub const TRACE_VERSION: u16 = 1;
pub const NUM_TRIES_UNLIMITED: u32 = 0xFEDC_BA98;
#[repr(C)]
pub struct Request {
version: [u32; 2],
request_type: RequestType,
_reserved: u32,
payload: RequestPayload,
}
impl Request {
const VERSION: [u32; 2] = [1, 0];
#[must_use]
const fn new(request_type: RequestType, payload: RequestPayload) -> Self {
Self {
version: Self::VERSION,
request_type,
_reserved: 0,
payload,
}
}
pub const fn get_interface_version() -> Self {
Self::new(RequestType::GetInterfaceVersion, RequestPayload::empty())
}
pub fn get_trace_buffer_size(process_handle: HANDLE) -> Self {
Self::new(
RequestType::GetTraceBufferSize,
GetTraceBuffer::new(process_handle).into(),
)
}
pub fn get_trace_buffer(process_handle: HANDLE) -> Self {
Self::new(
RequestType::GetTraceBuffer,
GetTraceBuffer::new(process_handle).into(),
)
}
pub fn set_system_wide_tracing_option(
ipt_option: IptOption,
num_tries: u32,
ttl_seconds: u32,
) -> Self {
Self::new(
RequestType::SetSystemWideTracingOption,
SetSystemWideTracingOption::new(ipt_option, num_tries, ttl_seconds).into(),
)
}
pub fn start_process_trace(process_handle: HANDLE, ipt_option: IptOption) -> Self {
Self::new(
RequestType::StartProcessTrace,
StartProcessTrace::new(process_handle, ipt_option).into(),
)
}
pub fn stop_process_trace(process_handle: HANDLE) -> Self {
Self::new(RequestType::StopProcessTrace, process_handle.into())
}
pub fn pause_thread_trace(thread_handle: HANDLE) -> Self {
Self::new(RequestType::PauseThreadTrace, thread_handle.into())
}
pub fn resume_thread_trace(thread_handle: HANDLE) -> Self {
Self::new(RequestType::ResumeThreadTrace, thread_handle.into())
}
pub fn query_process_trace_configuration(process_handle: HANDLE) -> Self {
Self::new(
RequestType::QueryProcessTraceConfiguration,
process_handle.into(),
)
}
pub const fn query_system_wide_tracing_state() -> Self {
Self::new(
RequestType::QuerySystemWideTracingState,
RequestPayload::empty(),
)
}
pub const fn stop_system_wide_tracing() -> Self {
Self::new(RequestType::StopSystemWideTracing, RequestPayload::empty())
}
pub fn configure_thread_address_filter_range(
thread_handle: HANDLE,
range_index: u32,
mode: AddressFilterMode,
start_address: u64,
end_address: u64,
) -> Self {
Self::new(
RequestType::ConfigureThreadAddressFilterRange,
ConfigureThreadAddressFilterRange::new(
thread_handle,
range_index,
mode,
start_address,
end_address,
)
.into(),
)
}
pub fn query_thread_address_filter_range(thread_handle: HANDLE, range_index: u32) -> Self {
Self::new(
RequestType::QueryThreadAddressFilterRange,
QueryThreadAddressFilterRange::new(thread_handle, range_index).into(),
)
}
pub fn query_thread_trace_stop_range_entered(thread_handle: HANDLE) -> Self {
Self::new(
RequestType::QueryThreadTraceStopRangeEntered,
thread_handle.into(),
)
}
pub fn start_process_trace_ex(
process_handle: HANDLE,
trace_file_handle: HANDLE,
ipt_option: IptOption,
) -> Self {
Self::new(
RequestType::StartProcessTraceEx,
StartProcessTraceEx::new(process_handle, trace_file_handle, ipt_option).into(),
)
}
}
#[repr(u32)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum RequestType {
GetInterfaceVersion = 0,
GetTraceBufferSize = 1,
GetTraceBuffer = 2,
SetSystemWideTracingOption = 3,
SetPerImageTracingOption = 4,
StartProcessTrace = 5,
StopProcessTrace = 6,
PauseThreadTrace = 7,
ResumeThreadTrace = 8,
QueryProcessTraceConfiguration = 9,
QuerySystemWideTracingState = 10,
StopSystemWideTracing = 12,
ConfigureThreadAddressFilterRange = 13,
QueryThreadAddressFilterRange = 14,
QueryThreadTraceStopRangeEntered = 15,
StartProcessTraceEx = 16,
}
#[repr(C)]
union RequestPayload {
get_trace_buffer: GetTraceBuffer,
set_system_wide_tracing_option: SetSystemWideTracingOption,
start_process_trace: StartProcessTrace,
start_process_trace_ex: StartProcessTraceEx,
handle: HANDLE,
configure_thread_address_filter_range: ConfigureThreadAddressFilterRange,
query_thread_address_filter_range: QueryThreadAddressFilterRange,
set_per_image_tracing_option: SetPerImageTracingOption,
_pad: [u8; 32],
}
impl RequestPayload {
const fn empty() -> Self {
Self { _pad: [0; 32] }
}
}
impl From<GetTraceBuffer> for RequestPayload {
fn from(get_trace_buffer: GetTraceBuffer) -> Self {
Self { get_trace_buffer }
}
}
impl From<SetSystemWideTracingOption> for RequestPayload {
fn from(set_system_wide_tracing_option: SetSystemWideTracingOption) -> Self {
Self {
set_system_wide_tracing_option,
}
}
}
impl From<StartProcessTrace> for RequestPayload {
fn from(start_process_trace: StartProcessTrace) -> Self {
Self {
start_process_trace,
}
}
}
impl From<StartProcessTraceEx> for RequestPayload {
fn from(start_process_trace_ex: StartProcessTraceEx) -> Self {
Self {
start_process_trace_ex,
}
}
}
impl From<HANDLE> for RequestPayload {
fn from(handle: HANDLE) -> Self {
Self { handle }
}
}
impl From<ConfigureThreadAddressFilterRange> for RequestPayload {
fn from(configure_thread_address_filter_range: ConfigureThreadAddressFilterRange) -> Self {
Self {
configure_thread_address_filter_range,
}
}
}
impl From<QueryThreadAddressFilterRange> for RequestPayload {
fn from(query_thread_address_filter_range: QueryThreadAddressFilterRange) -> Self {
Self {
query_thread_address_filter_range,
}
}
}
impl From<SetPerImageTracingOption> for RequestPayload {
fn from(set_per_image_tracing_option: SetPerImageTracingOption) -> Self {
Self {
set_per_image_tracing_option,
}
}
}
#[repr(C)]
pub union Response {
pub interface_version: u16,
pub trace_buffer_size: TraceBufferSizeResponse,
pub pause_state: PreviouslyEnabledResponse,
pub trace_config: IptOptionResponse,
pub core_tracing_state: SystemWideTracingStateResponse,
pub address_filter_range: AddressFilterRangeResponse,
pub trace_stop_entered: TraceStopRangeEnteredResponse,
_pad: [u8; 24],
}
impl Response {
pub(crate) const fn as_bytes(&self) -> &[u8] {
unsafe { &self._pad }
}
}
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct TraceBufferSizeResponse {
pub trace_version: u16,
_padding: [u8; 6],
pub trace_size: u64,
}
#[repr(C)]
#[derive(Debug, Clone, Copy)]
struct GetTraceBuffer {
trace_version: u16,
_padding: [u8; 6],
process_handle: HANDLE,
}
impl GetTraceBuffer {
pub const fn new(process_handle: HANDLE) -> Self {
Self {
trace_version: TRACE_VERSION,
_padding: [0; 6],
process_handle,
}
}
}
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub struct GetTraceResponseHeader {
pub trace_version: u16,
pub response_version: u16,
pub bytes_written: u32,
}
impl GetTraceResponseHeader {
#[cfg(feature = "log")]
pub const RESPONSE_VERSION_EXPECTED: u16 = 1;
}
#[repr(C, packed(4))]
#[derive(Debug)]
#[non_exhaustive]
pub struct TraceRecordHeader {
pub thread_id: u64,
pub timing_settings: u32,
pub mtc_frequency: u32,
pub frequency_to_tsc_ratio: u32,
pub output_offset: u32,
pub payload_length: u32,
}
#[repr(C)]
#[derive(Debug, Clone, Copy)]
struct SetSystemWideTracingOption {
ipt_option: IptOptionRaw,
num_tries: u32,
ttl_seconds: u32,
}
impl SetSystemWideTracingOption {
pub fn new(ipt_option: IptOption, num_tries: u32, ttl_seconds: u32) -> Self {
Self {
ipt_option: ipt_option.into(),
num_tries,
ttl_seconds,
}
}
}
#[repr(C, packed(4))]
#[derive(Debug, Clone, Copy)]
pub struct SetPerImageTracingOption {
ipt_option: IptOptionRaw,
num_tries: u32,
ttl_seconds: u32,
image_name_length: u16,
second_string_length: u16,
}
impl SetPerImageTracingOption {
pub fn raw_request(
ipt_option: IptOption,
num_tries: u32,
ttl_seconds: u32,
image_name: &[u16],
second_string: Option<&[u16]>,
) -> Vec<u8> {
let header_size = size_of::<Request>() - size_of::<RequestPayload>() + size_of::<Self>();
let mut out = Vec::new();
assert!(!image_name.is_empty(), "image_name must not be empty");
let image_name_length = u16::try_from(image_name.len() * 2)
.expect("image_name too long to encode as a u16 byte length");
let second_string_length = second_string
.map(|s| {
u16::try_from(s.len() * 2)
.expect("second_string length too long to encode as a u16 byte length")
})
.unwrap_or(0);
let request_payload = Self {
ipt_option: ipt_option.into(),
num_tries,
ttl_seconds,
image_name_length,
second_string_length,
};
let request = Request {
version: Request::VERSION,
request_type: RequestType::SetPerImageTracingOption,
_reserved: 0,
payload: request_payload.into(),
};
out.extend_from_slice(unsafe {
slice::from_raw_parts((&raw const request).cast(), header_size)
});
out.extend(image_name.iter().flat_map(|c| c.to_ne_bytes()));
out.extend(
second_string
.unwrap_or(&[])
.iter()
.flat_map(|c| c.to_ne_bytes()),
);
out.extend_from_slice(&vec![0; size_of::<Request>().saturating_sub(out.len())]);
out
}
}
#[repr(C)]
#[derive(Debug, Clone, Copy)]
struct StartProcessTrace {
process_handle: HANDLE,
ipt_option: IptOptionRaw,
}
impl StartProcessTrace {
pub fn new(process_handle: HANDLE, ipt_option: IptOption) -> Self {
Self {
process_handle,
ipt_option: ipt_option.into(),
}
}
}
#[repr(C)]
#[derive(Debug, Clone, Copy)]
struct StartProcessTraceEx {
process_handle: HANDLE,
trace_file_handle: HANDLE,
ipt_option: IptOptionRaw,
}
impl StartProcessTraceEx {
pub fn new(process_handle: HANDLE, trace_file_handle: HANDLE, ipt_option: IptOption) -> Self {
Self {
process_handle,
trace_file_handle,
ipt_option: ipt_option.into(),
}
}
}
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct PreviouslyEnabledResponse {
pub previously_enabled: u8,
}
#[repr(C)]
#[derive(Debug, Clone, Copy)]
pub struct IptOptionResponse {
pub ipt_option: IptOptionRaw,
}
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SystemWideTracingStateResponse {
pub state: u64,
}
#[repr(u32)]
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AddressFilterMode {
Disabled = 0,
Filter = 1,
TraceStop = 2,
}
impl AddressFilterMode {
pub(crate) const fn from_repr(repr: u32) -> Option<Self> {
match repr {
0 => Some(Self::Disabled),
1 => Some(Self::Filter),
2 => Some(Self::TraceStop),
_ => None,
}
}
}
#[repr(C)]
#[derive(Debug, Clone, Copy)]
struct ConfigureThreadAddressFilterRange {
thread_handle: HANDLE,
range_index: u32,
mode: AddressFilterMode,
start_address: u64,
end_address: u64,
}
impl ConfigureThreadAddressFilterRange {
pub const fn new(
thread_handle: HANDLE,
range_index: u32,
mode: AddressFilterMode,
start_address: u64,
end_address: u64,
) -> Self {
Self {
thread_handle,
range_index,
mode,
start_address,
end_address,
}
}
}
#[repr(C)]
#[derive(Debug, Clone, Copy)]
struct QueryThreadAddressFilterRange {
thread_handle: HANDLE,
range_index: u32,
}
impl QueryThreadAddressFilterRange {
pub const fn new(thread_handle: HANDLE, range_index: u32) -> Self {
Self {
thread_handle,
range_index,
}
}
}
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AddressFilterRangeResponse {
pub mode: AddressFilterMode,
pub start_address: u64,
pub end_address: u64,
}
#[repr(C)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TraceStopRangeEnteredResponse {
pub entered: u8,
}
#[cfg(test)]
mod tests {
use super::*;
use core::mem::offset_of;
#[test]
fn new_sets_version_and_zeroes_reserved() {
let request = Request::new(RequestType::PauseThreadTrace, RequestPayload::empty());
assert_eq!(request.version, Request::VERSION);
assert_eq!(request.request_type, RequestType::PauseThreadTrace);
assert_eq!(request._reserved, 0);
}
#[test]
fn message_sizes_match_driver_minimums() {
assert_eq!(size_of::<Request>(), 0x30);
assert_eq!(size_of::<Response>(), 0x18);
}
#[test]
fn trace_record_header_size() {
assert_eq!(size_of::<TraceRecordHeader>(), 28);
}
#[test]
fn get_trace_buffer_layout() {
assert_eq!(offset_of!(GetTraceBuffer, trace_version), 0);
assert_eq!(offset_of!(GetTraceBuffer, process_handle), 8);
}
#[test]
fn get_trace_buffer_size_response_layout() {
assert_eq!(offset_of!(TraceBufferSizeResponse, trace_version), 0);
assert_eq!(offset_of!(TraceBufferSizeResponse, trace_size), 8);
}
#[test]
fn fetch_trace_response_header_size() {
assert_eq!(size_of::<GetTraceResponseHeader>(), 8);
}
#[test]
fn set_system_wide_tracing_option_layout() {
assert_eq!(offset_of!(SetSystemWideTracingOption, ipt_option), 0);
assert_eq!(offset_of!(SetSystemWideTracingOption, num_tries), 8);
assert_eq!(offset_of!(SetSystemWideTracingOption, ttl_seconds), 12);
}
#[test]
fn set_per_image_tracing_option_layout() {
assert_eq!(offset_of!(SetPerImageTracingOption, ipt_option), 0);
assert_eq!(offset_of!(SetPerImageTracingOption, num_tries), 8);
assert_eq!(offset_of!(SetPerImageTracingOption, ttl_seconds), 12);
assert_eq!(offset_of!(SetPerImageTracingOption, image_name_length), 16);
assert_eq!(
offset_of!(SetPerImageTracingOption, second_string_length),
18
);
}
#[test]
fn set_per_image_tracing_option_write_request() {
let image_name: [u16; 3] = [b'a' as u16, b'b' as u16, b'c' as u16];
let second_string: [u16; 2] = [b'x' as u16, b'y' as u16];
let ipt_option = IptOption::default();
let raw_option = IptOptionRaw::from(ipt_option).raw_value();
let out = SetPerImageTracingOption::raw_request(
ipt_option,
NUM_TRIES_UNLIMITED,
42,
&image_name,
Some(&second_string),
);
assert!(out.len() >= 0x30);
assert_eq!(u32::from_ne_bytes(out[0..4].try_into().unwrap()), 1); assert_eq!(u32::from_ne_bytes(out[4..8].try_into().unwrap()), 0); assert_eq!(u32::from_ne_bytes(out[8..12].try_into().unwrap()), 4); assert_eq!(u32::from_ne_bytes(out[12..16].try_into().unwrap()), 0); assert_eq!(
u64::from_ne_bytes(out[16..24].try_into().unwrap()),
raw_option
);
assert_eq!(
u32::from_ne_bytes(out[24..28].try_into().unwrap()),
NUM_TRIES_UNLIMITED
);
assert_eq!(u32::from_ne_bytes(out[28..32].try_into().unwrap()), 42);
assert_eq!(u16::from_ne_bytes(out[32..34].try_into().unwrap()), 6);
assert_eq!(u16::from_ne_bytes(out[34..36].try_into().unwrap()), 4);
assert_eq!(&out[36..42], [b'a', 0, b'b', 0, b'c', 0]);
assert_eq!(&out[42..46], [b'x', 0, b'y', 0]);
}
#[test]
fn start_process_trace_layout() {
assert_eq!(offset_of!(StartProcessTrace, process_handle), 0);
assert_eq!(offset_of!(StartProcessTrace, ipt_option), 8);
}
#[test]
fn start_process_trace_ex_layout() {
assert_eq!(offset_of!(StartProcessTraceEx, process_handle), 0);
assert_eq!(offset_of!(StartProcessTraceEx, trace_file_handle), 8);
assert_eq!(offset_of!(StartProcessTraceEx, ipt_option), 16);
}
#[test]
fn configure_thread_address_filter_range_layout() {
assert_eq!(
offset_of!(ConfigureThreadAddressFilterRange, thread_handle),
0
);
assert_eq!(
offset_of!(ConfigureThreadAddressFilterRange, range_index),
8
);
assert_eq!(offset_of!(ConfigureThreadAddressFilterRange, mode), 12);
assert_eq!(
offset_of!(ConfigureThreadAddressFilterRange, start_address),
16
);
assert_eq!(
offset_of!(ConfigureThreadAddressFilterRange, end_address),
24
);
assert_eq!(size_of::<ConfigureThreadAddressFilterRange>(), 32);
}
#[test]
fn query_thread_address_filter_range_layout() {
assert_eq!(offset_of!(QueryThreadAddressFilterRange, thread_handle), 0);
assert_eq!(offset_of!(QueryThreadAddressFilterRange, range_index), 8);
}
#[test]
fn address_filter_range_response_layout() {
assert_eq!(offset_of!(AddressFilterRangeResponse, mode), 0);
assert_eq!(offset_of!(AddressFilterRangeResponse, start_address), 8);
assert_eq!(offset_of!(AddressFilterRangeResponse, end_address), 16);
}
}