DOCSEARCHbyAlgolia
Submit Docs

CapFrameX Documentation

repository·master·Indexed 22 days ago

https://github.com/cxworld/capframex

A high-performance frametimes capture and analysis tool built on Intel's PresentMon. Includes guides for installing and building CapFrameX Linux, using the Vulkan layer for gaming performance metrics, and integrating Intel Perfmon metrics with the Linux perf tool for Top-down Microarchitecture Analysis (TMA).

Tokens
20.9K
Snippets
33
Records
93
Agent score
79%

What's inside CapFrameX

  1. Use Timed Processor Event Based Sampling (TPEBS) for Retire Latency

    master

    Retire latency indicates the elapsed cycles between the retirement of the instruction that caused a PEBS and the prior instruction retirement.

    This value is critical for TMA metrics like DRAM Bound / MEM_Latency / Local_Mem. You can use either a default value or a value collected during analysis. Default values are provided in the repository within */metrics/*_retire_latency.json files.

  2. How CapFrameX MCP Integration works

    master

    The CapFrameX MCP integration is an in-process implementation hosted within the existing CapFrameX.exe process. It utilizes the existing EmbedIO webserver infrastructure to host an MCP endpoint at http://localhost:<WebservicePort>/mcp.

    Key Architectural Details:

    • Transport: Uses HTTP + JSON-RPC 2.0. The server supports streaming responses via SSE (Server-Sent Events) if requested in the Accept header.
    • Lifecycle: The MCP server's lifecycle is tied directly to the CapFrameX application. If the app is running, the endpoint is active; if not, it is unreachable.
    • Security: The endpoint binds to localhost and follows the existing security posture of the CapFrameX webserver (no authentication required, scoped to localhost).
    • Capabilities: Because it runs in-process, MCP tools have direct access to CapFrameX's internal services (like ICaptureService and IAppConfiguration) via Dependency Injection without needing Inter-Process Communication (IPC).

  3. Architecture of the CapFrameX Linux Overlay

    master

    The CapFrameX Linux overlay is designed as a Vulkan implicit layer that injects rendering into the game process. The architecture consists of several interacting components:

    1. Vulkan Layer (Hooks): Intercepts Vulkan calls (like swapchain creation and vkQueuePresentKHR) to inject the overlay.
    2. Overlay Core (Rendering): Manages the rendering lifecycle and coordinates with the Vulkan layer.
    3. ImGui Backend: Handles the actual UI rendering using Dear ImGui.
    4. Collectors:
      • Frametime Collector: Captures timing data.
      • Telemetry Collector: Gathers hardware metrics.
    5. CapFrameX Daemon: Communicates with the layer via a Unix Socket (IPC) to manage sessions, recordings, and configurations.

  4. How Intel OC Mailbox works on Arrow Lake-S

    master

    The Intel OC Mailbox is a mechanism used to retrieve hardware telemetry (specifically NGU and D2D ratios) on Arrow Lake-S desktop platforms where the standard OOBMSM/TPMI PCI discovery path is absent. It operates by communicating through a specific pair of MSRs (0x607 and 0x608).

    Unlike the OOBMSM mechanism which relies on finding a specific PCI device and traversing an extended capability chain (TPMI/VSEC), the OC Mailbox is a direct MSR-based interface. This makes it a more direct, albeit platform-specific, way to access internal fabric clocks. The implementation in CapFrameX uses a SupportsOcMailbox check to determine if the architecture (Arrow Lake, NovaLake) can utilize this channel as a fallback for clock sensors.

  6. Correlate app frames with display flips

    master

    To calculate full latency (submit → flip → scanout), you must correlate your application's frame submission timestamps with the DRM display flip events. Depending on your graphics API, use the following methods:

    • Vulkan: Use VK_GOOGLE_display_timing or VK_EXT_present_timing extensions.
    • OpenGL: Use glXGetSyncValuesOML() or glXGetMscRateOML() on GLX.
    • Wayland: Use the wp_presentation_feedback protocol.

  7. Compare Installed Mode vs Portable Mode behavior

    master

    When using portable mode, CapFrameX behaves differently than a standard installation:

    FeatureInstalled ModePortable Mode
    Config storage%AppData%\CapFrameX\Configuration./Portable/Config
    Captures storageDocuments\CapFrameX\Captures./Portable/Captures
    ScreenshotsDocuments\CapFrameX\Screenshots./Portable/Screenshots
    Logs%AppData%\CapFrameX\Logs./Portable/Logs
    UI state (window size, column widths)%LocalAppData%\Jot./Portable/Config
    Window title"CapFrameX""CapFrameX Portable"
    Config migrationMigrates old settingsSkipped
    Start with WindowsAvailableDisabled

    Note: Settings configured in portable mode are isolated; they will not affect or be affected by a standard installed version of CapFrameX.

  8. Determine OOBMSM container layout for new platforms

    master

    When a new platform (like Arrow Lake) does not have a known layout in the intel/Intel-PMT/xml directory, the container byte offsets and bit positions for clocks must be derived. Three strategies are used:

    • Layout Inheritance: Test if the platform re-uses existing layouts. For example, check if the LNL Container_2 (0x82F8 bits[34..41] / [50..57] × 50 MHz) or MTL (0x6348 bits[48..55] × 100 MHz) produces plausible values that match HWiNFO at idle.
    • Pattern Matching: Search the OOBMSM aperture (BAR0 64 KB) for known constants. For example, D2D is often boot-fixed at a ratio of 21 (0x15).
    • Differential Snapshot: Capture aperture dumps at different load levels (idle, single-thread, all-core). A candidate bit field for NGU is one that rises monotonically with load, while D2D candidates are fields that remain constant across all load levels.

  9. Understand the Perfmon Metrics JSON format

    master

    The Perfmon Metrics repository provides JSON files that define metric equations for various platforms. Each JSON object follows a specific schema used to calculate performance metrics:

    • MetricName: The string name of the metric.
    • Level: Integer representing the hierarchy level (Root level is 1). Used with ParentCategory to define a tree structure.
    • BriefDescription: A description of the metric.
    • UnitOfMeasure: The unit (e.g., time, frequency, number of samples, percent).
    • Events: A list of events used in the formula, containing Name (from the JSON event list) and Alias (used in the formula).
    • Constants: A list of required constants (e.g., CORES_PER_SOCKET, SYSTEM_TSC_FREQ) with Name and Alias fields.
    • Formula: The arithmetic string using provided aliases to calculate the metric.
    • Category: Tagging for grouping (e.g., IO, TMA, microservices).
    • Threshold: Logic to indicate if a metric is meaningful. Supports operators like > 0.2, parent checks with P, and logical operators & or |. Special tags like $issueXX associate nodes across categories, and ~overlap indicates non-mutually exclusive costs.
    • ResolutionLevels: A list of valid aggregation levels (e.g., THREAD, CORE, SOCKET, SYSTEM). A tool must not compute metrics at a level not present in this list.

  10. Handle concurrency in MCP tools using EmbedIO

    master
    MCP tools are executed on thread-pool threads via EmbedIO. When writing tools that interact with shared state (such as ICaptureService), you must respect existing threading rules. Since tools access the same Dependency Injection (DI) singletons as existing controllers, they inherit the existing concurrency protections.

  11. How Intel OOBMSM sensor discovery works (TPMI vs VSEC)

    master

    The discovery of Intel OOBMSM telemetry (like NGU and D2D clocks) depends on how the platform exposes Punit telemetry. There are two primary paths:

    1. TPMI Path (Preferred): If the system presents a TPMI capability (id=0x0023) with a non-zero discovery offset (disc), the system uses a PFS (Platform Feature Set) walk. The discovery relies on matching specific GUIDs (e.g., 0x03086000 for PTL) to find the telemetry aperture.
    2. VSEC Path: If no TPMI capability is present but VSEC capabilities (id=0x000B) are found, the system uses a VSEC-direct discovery path. In this case, the vsec_id identifies the telemetry VSEC, and the disc offset is used directly as the sub-aperture base, bypassing the PFS table walk.

    Identifying which path the hardware uses is the first step in implementing support for new platforms like Arrow Lake.

  12. Design of the IntelClientImcClock PawnIO module

    master

    The IntelClientImcClock.p module is a proposed read-only PawnIO module designed to provide the Intel client IMC/QCLK clock-ratio for Panther Lake and related Core Ultra platforms. It aims to replace generic hardware access with a safe, high-level operation that returns the ratio, reference clock mode, and gear information, allowing consumers like CapFrameX to calculate the memory clock using their own measured bus clock.

    Key Design Principles:

    • Narrow API: Exposes a single primary IOCTL for reading clock information.
    • Security: Does not expose generic PCI config or arbitrary physical-memory access; all registers and offsets are hardcoded and allowlisted.
    • Platform Specificity: Targets Intel x64 client/SoC platforms, specifically validating against Panther Lake (PTL) and Core Ultra variants.
    /// Read Intel client IMC/QCLK clock-ratio information.
///
/// @param in_size Must be 0
/// @param out [0] = ABI version, currently 1
/// @param out [1] = source enum
/// @param out [2] = ratio
/// @param out [3] = reference clock mode enum
/// @param out [4] = gear enum or 0 if unknown/not applicable
/// @param out [5] = raw register value low dword
/// @param out [6] = flags
/// @out_size Must be 7
/// @return STATUS_SUCCESS if a supported source produced valid data.
///         STATUS_NOT_SUPPORTED if the CPU/platform/register source is unsupported.
///         Other NTSTATUS on PCI/MMIO read failure.
DEFINE_IOCTL_SIZED(ioctl_read_imc_clock, 0, 7)