katra_core/
kind.rs

1//! Event vocabulary — the enum of everything KatraProfiler can capture.
2//!
3//! # Stability
4//!
5//! `EventKind` (and its sub-enums) are serialized into the trace format by
6//! variant index. **Append new variants at the end.** See the crate-level
7//! stability notes in `lib.rs`.
8
9use serde::{Deserialize, Serialize};
10
11/// A specific D3D12 API call of interest (KatraProfiler §5 / §16).
12#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
13#[serde(rename_all = "snake_case")]
14pub enum D3d12Call {
15    /// ID3D12CommandQueue::ExecuteCommandLists
16    QueueSubmit,
17    /// ID3D12CommandQueue::Signal
18    Signal,
19    /// ID3D12CommandQueue::Wait
20    Wait,
21    /// CreateCommittedResource / CreatePlacedResource
22    ResourceCreate,
23    /// Uploading data into a resource
24    ResourceUpload,
25    /// ID3D12GraphicsCommandList::ResourceBarrier
26    ResourceBarrier,
27    /// CopyDescriptors
28    DescriptorCopy,
29    /// CopyDescriptorsSimple
30    DescriptorWrite,
31    /// ID3D12GraphicsCommandList::Reset
32    CommandListReset,
33    /// ID3D12GraphicsCommandList::Close
34    CommandListClose,
35    /// ID3D12GraphicsCommandList4::ExecuteIndirect / execute
36    CommandListExecute,
37    /// CreatePipelineState
38    PipelineStateCreate,
39    /// CreateRootSignature
40    RootSignatureCreate,
41    /// ID3D12Device::MakeResident
42    MakeResident,
43    /// ID3D12Device::Evict
44    Evict,
45    /// Present
46    Present,
47    /// GetCopyableFootprints
48    GetCopyableFootprints,
49    /// ID3D12Resource::Map
50    Map,
51    /// ID3D12Resource::Unmap
52    Unmap,
53}
54
55/// A specific Vulkan call of interest.
56#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
57#[serde(rename_all = "snake_case")]
58pub enum VulkanCall {
59    /// vkQueueSubmit
60    QueueSubmit,
61    /// vkQueuePresentKHR
62    QueuePresent,
63    /// vkBeginCommandBuffer
64    CommandBufferBegin,
65    /// vkEndCommandBuffer
66    CommandBufferEnd,
67    /// vkCreateGraphicsPipelines / vkCreateComputePipelines
68    PipelineCreate,
69    /// vkAllocateMemory
70    MemoryAllocate,
71    /// vkMapMemory
72    MemoryMap,
73    /// vkCreateBuffer / vkCreateImage
74    ObjectCreate,
75    /// vkCmdCopyBuffer / vkCmdCopyImage
76    CmdCopy,
77    /// vkCmdCopyBufferToImage
78    CmdCopyBufferToImage,
79    /// vkCmdPipelineBarrier
80    CmdPipelineBarrier,
81    /// vkSignalSemaphore (timeline)
82    TimelineSignal,
83    /// vkWaitSemaphores (timeline)
84    TimelineWait,
85    /// vkUpdateDescriptorSets
86    DescriptorUpdate,
87    /// vkCreateFence
88    FenceCreate,
89}
90
91/// The phase of an event relative to the operation it describes.
92#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
93#[serde(rename_all = "snake_case")]
94pub enum Phase {
95    /// A point-in-time event (a syscall return, a present, ...).
96    Instant,
97    /// The start of a span (matched by `span_id` to an `End`).
98    Begin,
99    /// The end of a span.
100    End,
101    /// A counter delta/level (e.g. bytes copied, queue depth).
102    Counter,
103}
104
105/// Every kind of event KatraProfiler can capture (KatraProfiler §5).
106///
107/// Grouped by the layer that produces the event. Append-only.
108#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
109#[serde(rename_all = "snake_case")]
110pub enum EventKind {
111    // ---- Windows-facing activity -------------------------------------
112    /// NtReadFile
113    NtReadFile,
114    /// ReadFile
115    ReadFile,
116    /// A semantic file read (explicit or inferred; spans API layers).
117    FileRead,
118    /// File open (CreateFile)
119    FileOpen,
120    /// File close
121    FileClose,
122    /// MapViewOfFile / NtMapViewOfSection
123    MemoryMap,
124    /// UnmapViewOfFile
125    MemoryUnmap,
126    /// Waiting on a synchronization object (event, mutex, semaphore, ...)
127    SyncWait,
128    /// Signaling a synchronization object
129    SyncSignal,
130    /// Thread creation
131    ThreadCreate,
132    /// Thread wakeup
133    ThreadWakeup,
134    /// Heap allocation (RtlAllocateHeap, new, ...)
135    MemoryAlloc,
136    /// Heap free
137    MemoryFree,
138    /// A D3D12 API call (see [`D3d12Call`])
139    D3d12(D3d12Call),
140    /// Uploading data into a resource (semantic operation).
141    ResourceUpload,
142    /// A fence operation (signal/wait, generic)
143    FenceOperation,
144    /// Shader creation
145    ShaderCreate,
146    /// PSO creation
147    PsoCreate,
148    /// Present
149    Present,
150    // ---- Wine/Proton --------------------------------------------------
151    /// Windows→Unix transition
152    WinUnixTransition,
153    /// A wineserver call
154    ServerCall,
155    /// File/path translation
156    PathTranslation,
157    /// Compatibility-layer allocation
158    CompatibilityAlloc,
159    // ---- Linux ----------------------------------------------------------
160    /// A syscall
161    Syscall,
162    /// An io_uring submission batch
163    IoUringSubmit,
164    /// An io_uring completion
165    IoUringComplete,
166    /// An asynchronous file read (any backend)
167    IoRead,
168    /// A page fault
169    PageFault,
170    /// A context switch
171    ContextSwitch,
172    /// A scheduler wakeup
173    SchedulerWakeup,
174    /// Filesystem latency sample
175    FsLatency,
176    // ---- D3D12/vkd3d internals ------------------------------------------
177    /// Command-list creation
178    CommandListCreate,
179    /// A resource barrier/transition
180    Barrier,
181    /// Descriptor activity
182    DescriptorOp,
183    /// Resource state tracking
184    ResourceStateTrack,
185    /// Pipeline creation
186    PipelineCreate,
187    /// Shader translation (DXIL → IR → SPIR-V)
188    ShaderTranslate,
189    /// A cache hit
190    CacheHit,
191    /// A cache miss
192    CacheMiss,
193    /// Waiting on a fence value
194    FenceWait,
195    /// Signaling a fence value
196    FenceSignal,
197    // ---- Vulkan -----------------------------------------------------------
198    /// vkQueueSubmit
199    VkQueueSubmit,
200    /// Command-buffer lifecycle
201    VkCommandBuffer,
202    /// Vulkan pipeline creation
203    VkPipelineCreate,
204    /// Vulkan memory allocation
205    VkMemoryAlloc,
206    /// A copy operation
207    VkCopy,
208    /// A Vulkan barrier
209    VkBarrier,
210    /// Timeline synchronization
211    VkTimelineSync,
212    /// vkQueuePresentKHR
213    VkPresent,
214    // ---- GPU ---------------------------------------------------------------
215    /// A GPU timestamp sample
216    GpuTimestamp,
217    /// A GPU idle bubble
218    GpuIdleBubble,
219    /// GPU utilization sample
220    GpuUtilization,
221    /// A GPU draw
222    GpuDraw,
223    /// A GPU compute dispatch
224    GpuComputeDispatch,
225    // ---- Katra3D native ----------------------------------------------------
226    /// A Katra subsystem state change (coverage reporting)
227    KatraSubsystemState,
228    /// A semantic-graph operation
229    KatraGraphOp,
230    /// A Katra counter (aggregate or delta)
231    KatraCounter,
232    /// A KatraFlow prefetch decision
233    KatraPrefetch,
234    /// A Katra decompression operation
235    KatraDecompress,
236    /// A Katra staging operation
237    KatraStaging,
238    /// A Katra epoch transition
239    KatraEpoch,
240    /// A Katra arena allocation
241    KatraAllocate,
242    /// A Katra I/O wait
243    KatraIoWait,
244}
245
246impl EventKind {
247    /// Stable string name.
248    pub fn as_str(self) -> &'static str {
249        match self {
250            EventKind::NtReadFile => "nt_read_file",
251            EventKind::ReadFile => "read_file",
252            EventKind::FileRead => "file_read",
253            EventKind::FileOpen => "file_open",
254            EventKind::FileClose => "file_close",
255            EventKind::MemoryMap => "memory_map",
256            EventKind::MemoryUnmap => "memory_unmap",
257            EventKind::SyncWait => "sync_wait",
258            EventKind::SyncSignal => "sync_signal",
259            EventKind::ThreadCreate => "thread_create",
260            EventKind::ThreadWakeup => "thread_wakeup",
261            EventKind::MemoryAlloc => "memory_alloc",
262            EventKind::MemoryFree => "memory_free",
263            EventKind::D3d12(c) => match c {
264                D3d12Call::QueueSubmit => "d3d12_queue_submit",
265                D3d12Call::Signal => "d3d12_signal",
266                D3d12Call::Wait => "d3d12_wait",
267                D3d12Call::ResourceCreate => "d3d12_resource_create",
268                D3d12Call::ResourceUpload => "d3d12_resource_upload",
269                D3d12Call::ResourceBarrier => "d3d12_resource_barrier",
270                D3d12Call::DescriptorCopy => "d3d12_descriptor_copy",
271                D3d12Call::DescriptorWrite => "d3d12_descriptor_write",
272                D3d12Call::CommandListReset => "d3d12_cmdlist_reset",
273                D3d12Call::CommandListClose => "d3d12_cmdlist_close",
274                D3d12Call::CommandListExecute => "d3d12_cmdlist_execute",
275                D3d12Call::PipelineStateCreate => "d3d12_pso_create",
276                D3d12Call::RootSignatureCreate => "d3d12_root_signature_create",
277                D3d12Call::MakeResident => "d3d12_make_resident",
278                D3d12Call::Evict => "d3d12_evict",
279                D3d12Call::Present => "d3d12_present",
280                D3d12Call::GetCopyableFootprints => "d3d12_copyable_footprints",
281                D3d12Call::Map => "d3d12_map",
282                D3d12Call::Unmap => "d3d12_unmap",
283            },
284            EventKind::ResourceUpload => "resource_upload",
285            EventKind::FenceOperation => "fence_operation",
286            EventKind::ShaderCreate => "shader_create",
287            EventKind::PsoCreate => "pso_create",
288            EventKind::Present => "present",
289            EventKind::WinUnixTransition => "win_unix_transition",
290            EventKind::ServerCall => "server_call",
291            EventKind::PathTranslation => "path_translation",
292            EventKind::CompatibilityAlloc => "compatibility_alloc",
293            EventKind::Syscall => "syscall",
294            EventKind::IoUringSubmit => "io_uring_submit",
295            EventKind::IoUringComplete => "io_uring_complete",
296            EventKind::IoRead => "io_read",
297            EventKind::PageFault => "page_fault",
298            EventKind::ContextSwitch => "context_switch",
299            EventKind::SchedulerWakeup => "scheduler_wakeup",
300            EventKind::FsLatency => "fs_latency",
301            EventKind::CommandListCreate => "command_list_create",
302            EventKind::Barrier => "barrier",
303            EventKind::DescriptorOp => "descriptor_op",
304            EventKind::ResourceStateTrack => "resource_state_track",
305            EventKind::PipelineCreate => "pipeline_create",
306            EventKind::ShaderTranslate => "shader_translate",
307            EventKind::CacheHit => "cache_hit",
308            EventKind::CacheMiss => "cache_miss",
309            EventKind::FenceWait => "fence_wait",
310            EventKind::FenceSignal => "fence_signal",
311            EventKind::VkQueueSubmit => "vk_queue_submit",
312            EventKind::VkCommandBuffer => "vk_command_buffer",
313            EventKind::VkPipelineCreate => "vk_pipeline_create",
314            EventKind::VkMemoryAlloc => "vk_memory_alloc",
315            EventKind::VkCopy => "vk_copy",
316            EventKind::VkBarrier => "vk_barrier",
317            EventKind::VkTimelineSync => "vk_timeline_sync",
318            EventKind::VkPresent => "vk_present",
319            EventKind::GpuTimestamp => "gpu_timestamp",
320            EventKind::GpuIdleBubble => "gpu_idle_bubble",
321            EventKind::GpuUtilization => "gpu_utilization",
322            EventKind::GpuDraw => "gpu_draw",
323            EventKind::GpuComputeDispatch => "gpu_compute_dispatch",
324            EventKind::KatraSubsystemState => "katra_subsystem_state",
325            EventKind::KatraGraphOp => "katra_graph_op",
326            EventKind::KatraCounter => "katra_counter",
327            EventKind::KatraPrefetch => "katra_prefetch",
328            EventKind::KatraDecompress => "katra_decompress",
329            EventKind::KatraStaging => "katra_staging",
330            EventKind::KatraEpoch => "katra_epoch",
331            EventKind::KatraAllocate => "katra_allocate",
332            EventKind::KatraIoWait => "katra_io_wait",
333        }
334    }
335}
336
337impl std::fmt::Display for EventKind {
338    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
339        f.write_str(self.as_str())
340    }
341}
katra_core/kind.rs

katra_core/
kind.rs
