katra-core 0.1.0

//! Structured event payloads.
//!
//! Payloads are plain, `Copy` scalar records so the hot capture path can
//! store them into preallocated per-thread buffers with **zero heap
//! allocation per event** (KatraProfiler budget: "avoid heap allocation
//! unless justified").
//!
//! The enum layout is part of the trace format; **append new variants at
//! the end**.

use serde::{Deserialize, Serialize};

/// Payload for file operations.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct FilePayload {
    /// File identity hash ([`crate::FileKey`]).
    pub file: u64,
    /// Byte offset.
    pub offset: u64,
    /// Byte length.
    pub length: u64,
    /// Flags (open flags, wait flags, ...).
    pub flags: u32,
    /// Result (bytes transferred, NTSTATUS/HRESULT, or -1).
    pub result: i64,
}

/// Payload for memory operations.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct MemPayload {
    /// Size in bytes.
    pub size: u64,
    /// Alignment in bytes.
    pub align: u32,
    /// Arena/resource id (0 = process heap).
    pub arena: u32,
}

/// Payload for synchronization operations.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct SyncPayload {
    /// Sync kind (0 event, 1 mutex, 2 semaphore, 3 fence, 4 condvar, ...).
    pub kind: u32,
    /// Value (fence value, semaphore count, ...).
    pub value: u64,
}

/// Payload for thread operations.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct ThreadPayload {
    /// Action (0 create, 1 wakeup, 2 exit, 3 yield, ...).
    pub action: u32,
    /// Extra (target thread id, ...).
    pub extra: u64,
}

/// Payload for D3D12 calls. The call identity is in [`crate::EventKind`];
/// `a..d` carry call-specific scalar arguments.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct D3d12Payload {
    /// Call-specific scalar 1.
    pub a: u64,
    /// Call-specific scalar 2.
    pub b: u64,
    /// Call-specific scalar 3.
    pub c: u64,
    /// Call-specific scalar 4.
    pub d: u64,
}

/// Payload for Vulkan calls. The call identity is in [`crate::EventKind`].
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct VulkanPayload {
    /// Call-specific scalar 1.
    pub a: u64,
    /// Call-specific scalar 2.
    pub b: u64,
    /// Call-specific scalar 3.
    pub c: u64,
    /// Call-specific scalar 4.
    pub d: u64,
}

/// Payload for GPU counters/samples.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct GpuPayload {
    /// Counter id (0 timestamp, 1 idle bubble ns, 2 utilization %, ...).
    pub counter: u32,
    /// Value.
    pub value: u64,
}

/// Payload for I/O events.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct IoPayload {
    /// Queue depth at submission (or 0).
    pub queue_depth: u32,
    /// Operation latency in ns (0 if unknown).
    pub latency_ns: u64,
    /// Bytes transferred.
    pub bytes: u64,
    /// Operation (0 read, 1 submit batch, 2 complete, ...).
    pub op: u32,
}

/// Payload for Katra-native events.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct KatraPayload {
    /// Subsystem index (see [`crate::Subsystem`]).
    pub subsystem: u16,
    /// Promotion state index (see [`crate::PromotionState`]).
    pub state: u16,
    /// Detail (budget bytes, epoch, node id, ...).
    pub detail: u64,
}

/// Payload for shader events.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct ShaderPayload {
    /// Shader stage (0 vertex, 1 pixel, 2 compute, ...).
    pub stage: u32,
    /// Input identity hash (DXIL).
    pub input_hash: u64,
    /// Output identity hash (SPIR-V).
    pub output_hash: u64,
}

/// Payload for cache events.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct CachePayload {
    /// Cache layer (1 DXIL, 2 IR, 3 SPIR-V, 4 pipeline).
    pub layer: u8,
    /// Whether the lookup hit.
    pub hit: bool,
    /// Content key hash.
    pub key: u64,
    /// Artifact size in bytes.
    pub size: u64,
}

/// Payload for present events.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct PresentPayload {
    /// Frame index.
    pub frame: u64,
    /// Present mode (0 vsync, 1 immediate, 2 mailbox, ...).
    pub present_mode: u32,
}

/// Payload for decompression events.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct DecompressPayload {
    /// Compressed input bytes.
    pub input_bytes: u64,
    /// Decompressed output bytes.
    pub output_bytes: u64,
    /// Format (0 gdeflate, 1 gzip, 2 zlib, 3 raw deflate, ...).
    pub format: u32,
    /// Decompression latency in ns.
    pub latency_ns: u64,
}

/// Payload for future/unknown event kinds (extension escape hatch).
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct RawPayload {
    /// Generic scalar 1.
    pub a: u64,
    /// Generic scalar 2.
    pub b: u64,
    /// Generic scalar 3.
    pub c: u64,
    /// Generic scalar 4.
    pub d: u64,
}

/// The payload of a [`crate::TraceEvent`]. Plain scalars only; append-only.
#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub enum Payload {
    /// No payload.
    #[default]
    None,
    /// File operation.
    File(FilePayload),
    /// Memory operation.
    Mem(MemPayload),
    /// Synchronization operation.
    Sync(SyncPayload),
    /// Thread operation.
    Thread(ThreadPayload),
    /// D3D12 call.
    D3d12(D3d12Payload),
    /// Vulkan call.
    Vulkan(VulkanPayload),
    /// GPU sample.
    Gpu(GpuPayload),
    /// I/O operation.
    Io(IoPayload),
    /// Katra-native operation.
    Katra(KatraPayload),
    /// Shader operation.
    Shader(ShaderPayload),
    /// Cache operation.
    Cache(CachePayload),
    /// Present operation.
    Present(PresentPayload),
    /// Decompression operation.
    Decompress(DecompressPayload),
    /// Extension payload.
    Raw(RawPayload),
}

impl Payload {
    /// The payload kind as a stable string (for reports).
    pub fn as_str(&self) -> &'static str {
        match self {
            Payload::None => "none",
            Payload::File(_) => "file",
            Payload::Mem(_) => "mem",
            Payload::Sync(_) => "sync",
            Payload::Thread(_) => "thread",
            Payload::D3d12(_) => "d3d12",
            Payload::Vulkan(_) => "vulkan",
            Payload::Gpu(_) => "gpu",
            Payload::Io(_) => "io",
            Payload::Katra(_) => "katra",
            Payload::Shader(_) => "shader",
            Payload::Cache(_) => "cache",
            Payload::Present(_) => "present",
            Payload::Decompress(_) => "decompress",
            Payload::Raw(_) => "raw",
        }
    }

    /// Convenience constructor for a D3D12 call payload.
    pub fn d3d12(a: u64, b: u64, c: u64, d: u64) -> Self {
        Payload::D3d12(D3d12Payload { a, b, c, d })
    }

    /// Convenience constructor for a Vulkan call payload.
    pub fn vulkan(a: u64, b: u64, c: u64, d: u64) -> Self {
        Payload::Vulkan(VulkanPayload { a, b, c, d })
    }

    /// Convenience constructor for a raw payload.
    pub fn raw(a: u64, b: u64, c: u64, d: u64) -> Self {
        Payload::Raw(RawPayload { a, b, c, d })
    }
}