katra-core 0.1.0

//! Event vocabulary — the enum of everything KatraProfiler can capture.
//!
//! # Stability
//!
//! `EventKind` (and its sub-enums) are serialized into the trace format by
//! variant index. **Append new variants at the end.** See the crate-level
//! stability notes in `lib.rs`.

use serde::{Deserialize, Serialize};

/// A specific D3D12 API call of interest (KatraProfiler §5 / §16).
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum D3d12Call {
    /// ID3D12CommandQueue::ExecuteCommandLists
    QueueSubmit,
    /// ID3D12CommandQueue::Signal
    Signal,
    /// ID3D12CommandQueue::Wait
    Wait,
    /// CreateCommittedResource / CreatePlacedResource
    ResourceCreate,
    /// Uploading data into a resource
    ResourceUpload,
    /// ID3D12GraphicsCommandList::ResourceBarrier
    ResourceBarrier,
    /// CopyDescriptors
    DescriptorCopy,
    /// CopyDescriptorsSimple
    DescriptorWrite,
    /// ID3D12GraphicsCommandList::Reset
    CommandListReset,
    /// ID3D12GraphicsCommandList::Close
    CommandListClose,
    /// ID3D12GraphicsCommandList4::ExecuteIndirect / execute
    CommandListExecute,
    /// CreatePipelineState
    PipelineStateCreate,
    /// CreateRootSignature
    RootSignatureCreate,
    /// ID3D12Device::MakeResident
    MakeResident,
    /// ID3D12Device::Evict
    Evict,
    /// Present
    Present,
    /// GetCopyableFootprints
    GetCopyableFootprints,
    /// ID3D12Resource::Map
    Map,
    /// ID3D12Resource::Unmap
    Unmap,
}

/// A specific Vulkan call of interest.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum VulkanCall {
    /// vkQueueSubmit
    QueueSubmit,
    /// vkQueuePresentKHR
    QueuePresent,
    /// vkBeginCommandBuffer
    CommandBufferBegin,
    /// vkEndCommandBuffer
    CommandBufferEnd,
    /// vkCreateGraphicsPipelines / vkCreateComputePipelines
    PipelineCreate,
    /// vkAllocateMemory
    MemoryAllocate,
    /// vkMapMemory
    MemoryMap,
    /// vkCreateBuffer / vkCreateImage
    ObjectCreate,
    /// vkCmdCopyBuffer / vkCmdCopyImage
    CmdCopy,
    /// vkCmdCopyBufferToImage
    CmdCopyBufferToImage,
    /// vkCmdPipelineBarrier
    CmdPipelineBarrier,
    /// vkSignalSemaphore (timeline)
    TimelineSignal,
    /// vkWaitSemaphores (timeline)
    TimelineWait,
    /// vkUpdateDescriptorSets
    DescriptorUpdate,
    /// vkCreateFence
    FenceCreate,
}

/// The phase of an event relative to the operation it describes.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Phase {
    /// A point-in-time event (a syscall return, a present, ...).
    Instant,
    /// The start of a span (matched by `span_id` to an `End`).
    Begin,
    /// The end of a span.
    End,
    /// A counter delta/level (e.g. bytes copied, queue depth).
    Counter,
}

/// Every kind of event KatraProfiler can capture (KatraProfiler §5).
///
/// Grouped by the layer that produces the event. Append-only.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EventKind {
    // ---- Windows-facing activity -------------------------------------
    /// NtReadFile
    NtReadFile,
    /// ReadFile
    ReadFile,
    /// A semantic file read (explicit or inferred; spans API layers).
    FileRead,
    /// File open (CreateFile)
    FileOpen,
    /// File close
    FileClose,
    /// MapViewOfFile / NtMapViewOfSection
    MemoryMap,
    /// UnmapViewOfFile
    MemoryUnmap,
    /// Waiting on a synchronization object (event, mutex, semaphore, ...)
    SyncWait,
    /// Signaling a synchronization object
    SyncSignal,
    /// Thread creation
    ThreadCreate,
    /// Thread wakeup
    ThreadWakeup,
    /// Heap allocation (RtlAllocateHeap, new, ...)
    MemoryAlloc,
    /// Heap free
    MemoryFree,
    /// A D3D12 API call (see [`D3d12Call`])
    D3d12(D3d12Call),
    /// Uploading data into a resource (semantic operation).
    ResourceUpload,
    /// A fence operation (signal/wait, generic)
    FenceOperation,
    /// Shader creation
    ShaderCreate,
    /// PSO creation
    PsoCreate,
    /// Present
    Present,
    // ---- Wine/Proton --------------------------------------------------
    /// Windows→Unix transition
    WinUnixTransition,
    /// A wineserver call
    ServerCall,
    /// File/path translation
    PathTranslation,
    /// Compatibility-layer allocation
    CompatibilityAlloc,
    // ---- Linux ----------------------------------------------------------
    /// A syscall
    Syscall,
    /// An io_uring submission batch
    IoUringSubmit,
    /// An io_uring completion
    IoUringComplete,
    /// An asynchronous file read (any backend)
    IoRead,
    /// A page fault
    PageFault,
    /// A context switch
    ContextSwitch,
    /// A scheduler wakeup
    SchedulerWakeup,
    /// Filesystem latency sample
    FsLatency,
    // ---- D3D12/vkd3d internals ------------------------------------------
    /// Command-list creation
    CommandListCreate,
    /// A resource barrier/transition
    Barrier,
    /// Descriptor activity
    DescriptorOp,
    /// Resource state tracking
    ResourceStateTrack,
    /// Pipeline creation
    PipelineCreate,
    /// Shader translation (DXIL → IR → SPIR-V)
    ShaderTranslate,
    /// A cache hit
    CacheHit,
    /// A cache miss
    CacheMiss,
    /// Waiting on a fence value
    FenceWait,
    /// Signaling a fence value
    FenceSignal,
    // ---- Vulkan -----------------------------------------------------------
    /// vkQueueSubmit
    VkQueueSubmit,
    /// Command-buffer lifecycle
    VkCommandBuffer,
    /// Vulkan pipeline creation
    VkPipelineCreate,
    /// Vulkan memory allocation
    VkMemoryAlloc,
    /// A copy operation
    VkCopy,
    /// A Vulkan barrier
    VkBarrier,
    /// Timeline synchronization
    VkTimelineSync,
    /// vkQueuePresentKHR
    VkPresent,
    // ---- GPU ---------------------------------------------------------------
    /// A GPU timestamp sample
    GpuTimestamp,
    /// A GPU idle bubble
    GpuIdleBubble,
    /// GPU utilization sample
    GpuUtilization,
    /// A GPU draw
    GpuDraw,
    /// A GPU compute dispatch
    GpuComputeDispatch,
    // ---- Katra3D native ----------------------------------------------------
    /// A Katra subsystem state change (coverage reporting)
    KatraSubsystemState,
    /// A semantic-graph operation
    KatraGraphOp,
    /// A Katra counter (aggregate or delta)
    KatraCounter,
    /// A KatraFlow prefetch decision
    KatraPrefetch,
    /// A Katra decompression operation
    KatraDecompress,
    /// A Katra staging operation
    KatraStaging,
    /// A Katra epoch transition
    KatraEpoch,
    /// A Katra arena allocation
    KatraAllocate,
    /// A Katra I/O wait
    KatraIoWait,
}

impl EventKind {
    /// Stable string name.
    pub fn as_str(self) -> &'static str {
        match self {
            EventKind::NtReadFile => "nt_read_file",
            EventKind::ReadFile => "read_file",
            EventKind::FileRead => "file_read",
            EventKind::FileOpen => "file_open",
            EventKind::FileClose => "file_close",
            EventKind::MemoryMap => "memory_map",
            EventKind::MemoryUnmap => "memory_unmap",
            EventKind::SyncWait => "sync_wait",
            EventKind::SyncSignal => "sync_signal",
            EventKind::ThreadCreate => "thread_create",
            EventKind::ThreadWakeup => "thread_wakeup",
            EventKind::MemoryAlloc => "memory_alloc",
            EventKind::MemoryFree => "memory_free",
            EventKind::D3d12(c) => match c {
                D3d12Call::QueueSubmit => "d3d12_queue_submit",
                D3d12Call::Signal => "d3d12_signal",
                D3d12Call::Wait => "d3d12_wait",
                D3d12Call::ResourceCreate => "d3d12_resource_create",
                D3d12Call::ResourceUpload => "d3d12_resource_upload",
                D3d12Call::ResourceBarrier => "d3d12_resource_barrier",
                D3d12Call::DescriptorCopy => "d3d12_descriptor_copy",
                D3d12Call::DescriptorWrite => "d3d12_descriptor_write",
                D3d12Call::CommandListReset => "d3d12_cmdlist_reset",
                D3d12Call::CommandListClose => "d3d12_cmdlist_close",
                D3d12Call::CommandListExecute => "d3d12_cmdlist_execute",
                D3d12Call::PipelineStateCreate => "d3d12_pso_create",
                D3d12Call::RootSignatureCreate => "d3d12_root_signature_create",
                D3d12Call::MakeResident => "d3d12_make_resident",
                D3d12Call::Evict => "d3d12_evict",
                D3d12Call::Present => "d3d12_present",
                D3d12Call::GetCopyableFootprints => "d3d12_copyable_footprints",
                D3d12Call::Map => "d3d12_map",
                D3d12Call::Unmap => "d3d12_unmap",
            },
            EventKind::ResourceUpload => "resource_upload",
            EventKind::FenceOperation => "fence_operation",
            EventKind::ShaderCreate => "shader_create",
            EventKind::PsoCreate => "pso_create",
            EventKind::Present => "present",
            EventKind::WinUnixTransition => "win_unix_transition",
            EventKind::ServerCall => "server_call",
            EventKind::PathTranslation => "path_translation",
            EventKind::CompatibilityAlloc => "compatibility_alloc",
            EventKind::Syscall => "syscall",
            EventKind::IoUringSubmit => "io_uring_submit",
            EventKind::IoUringComplete => "io_uring_complete",
            EventKind::IoRead => "io_read",
            EventKind::PageFault => "page_fault",
            EventKind::ContextSwitch => "context_switch",
            EventKind::SchedulerWakeup => "scheduler_wakeup",
            EventKind::FsLatency => "fs_latency",
            EventKind::CommandListCreate => "command_list_create",
            EventKind::Barrier => "barrier",
            EventKind::DescriptorOp => "descriptor_op",
            EventKind::ResourceStateTrack => "resource_state_track",
            EventKind::PipelineCreate => "pipeline_create",
            EventKind::ShaderTranslate => "shader_translate",
            EventKind::CacheHit => "cache_hit",
            EventKind::CacheMiss => "cache_miss",
            EventKind::FenceWait => "fence_wait",
            EventKind::FenceSignal => "fence_signal",
            EventKind::VkQueueSubmit => "vk_queue_submit",
            EventKind::VkCommandBuffer => "vk_command_buffer",
            EventKind::VkPipelineCreate => "vk_pipeline_create",
            EventKind::VkMemoryAlloc => "vk_memory_alloc",
            EventKind::VkCopy => "vk_copy",
            EventKind::VkBarrier => "vk_barrier",
            EventKind::VkTimelineSync => "vk_timeline_sync",
            EventKind::VkPresent => "vk_present",
            EventKind::GpuTimestamp => "gpu_timestamp",
            EventKind::GpuIdleBubble => "gpu_idle_bubble",
            EventKind::GpuUtilization => "gpu_utilization",
            EventKind::GpuDraw => "gpu_draw",
            EventKind::GpuComputeDispatch => "gpu_compute_dispatch",
            EventKind::KatraSubsystemState => "katra_subsystem_state",
            EventKind::KatraGraphOp => "katra_graph_op",
            EventKind::KatraCounter => "katra_counter",
            EventKind::KatraPrefetch => "katra_prefetch",
            EventKind::KatraDecompress => "katra_decompress",
            EventKind::KatraStaging => "katra_staging",
            EventKind::KatraEpoch => "katra_epoch",
            EventKind::KatraAllocate => "katra_allocate",
            EventKind::KatraIoWait => "katra_io_wait",
        }
    }
}

impl std::fmt::Display for EventKind {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}