Relevant source files

The following files were used as context for generating this wiki page: - [src/contextswitch_etw/contextswitch_etw.cpp](https://github.com/zeux/microprofile/blob/master/src/contextswitch_etw/contextswitch_etw.cpp) - [src/microprofile.html](https://github.com/zeux/microprofile/blob/master/src/microprofile.html) - [contextswitch_dtrace.sh](https://github.com/zeux/microprofile/blob/master/contextswitch_dtrace.sh) - [microprofile.h](https://github.com/zeux/microprofile/blob/master/microprofile.h) - [.travis.yml](https://github.com/zeux/microprofile/blob/master/.travis.yml)

# GPU Profiling **MicroProfile** is a lightweight, cross‑platform profiler that can capture both CPU and GPU performance data. The *GPU profiling* subsystem provides a unified API for inserting GPU timestamps, retrieving them, and visualising the results in the HTML UI. It also integrates with OS‑level context‑switch tracing (ETW on Windows, DTrace on macOS) so that GPU work can be correlated with thread scheduling events. --- ## Table of Contents 1. [GPU Timestamp API](#gpu-timestamp-api) 2. [Backend Initialization (OpenGL, D3D11, D3D12, Vulkan)](#backend-initialization) 3. [Context‑Switch Tracing Integration](#context-switch-tracing) 4. [Data Flow from GPU to UI](#data-flow) 5. [Build & Continuous Integration](#build-ci) 6. [References](#references) --- ## GPU Timestamp API MicroProfile defines a small set of functions that abstract GPU timer handling. They are declared in **microprofile.h** and implemented per‑backend in the corresponding source files (not included here). | Function | Purpose | Typical Call Site | |----------|---------|-------------------| | `uint32_t MicroProfileGpuInsertTimer(void* pContext)` | Inserts a GPU timestamp marker and returns a key that can later be queried. | Inside a rendering loop, immediately before a GPU workload. | | `uint64_t MicroProfileGpuGetTimeStamp(uint32_t nKey)` | Retrieves the timestamp associated with a previously inserted marker. | After the GPU work has completed (or at frame end). | | `uint64_t MicroProfileTicksPerSecondGpu()` | Returns the GPU timestamp frequency, enabling conversion to seconds. | Used by the UI to display time in ms/µs. | | `void MicroProfileGpuSetContext(void* pContext)` | (Optional) Sets the current GPU context for multi‑threaded recording. | When using D3D12/Vulkan with multiple command queues. | *All functions are no‑ops when GPU timing is disabled.* Sources: [microprofile.h](https://github.com/zeux/microprofile/blob/master/microprofile.h) (see the “Gpu time stamps” comment block)【Sources: microprofile.h】. ### Example Usage (C++) ```cpp // Insert a timer before drawing a mesh uint32_t timerKey = MicroProfileGpuInsertTimer(gpContext); // ... issue GPU draw calls ... // Retrieve the timestamp after the draw completes uint64_t gpuTicks = MicroProfileGpuGetTimeStamp(timerKey); ``` --- ## Backend Initialization MicroProfile supports four major graphics APIs. The initialization macros are defined in **microprofile.h** and the concrete implementations live in the respective backend source files (e.g., `microprofile_gpu_gl.cpp`, `microprofile_gpu_d3d11.cpp`, etc.). | Backend | Macro | Init Function | Notes | |---------|-------|---------------|-------| | OpenGL | `MICROPROFILE_GPU_TIMERS_GL` | `MicroProfileGpuInitGL()` | Must be called once after an OpenGL context is created. | | Direct3D 11 | `MICROPROFILE_GPU_TIMERS_D3D11` | `MicroProfileGpuInitD3D11(Device)` | Pass the `ID3D11Device*`. | | Direct3D 12 | `MICROPROFILE_GPU_TIMERS_D3D12` | `MicroProfileGpuInitD3D12(Device, CommandQueue)` | For multi‑threaded use `MICROPROFILE_GPU_TIMERS_MULTITHREADED`. | | Vulkan | `MICROPROFILE_GPU_TIMERS_VK` | `MicroProfileGpuInitVK(Device, PhysicalDevice, Queue)` | Mirrors D3D12 workflow. | These macros are guarded by `#ifdef MICROPROFILE_IMPL` in the header, ensuring they are only compiled in the implementation translation unit. Sources: [microprofile.h](https://github.com/zeux/microprofile/blob/master/microprofile.h) (see the “Gpu time stamps” section)【Sources: microprofile.h】. ### Initialization Flowchart ```mermaid graph TB appStart[Application Start] --> initSelect[Select GPU Backend] initSelect --> glInit[Call MicroProfileGpuInitGL] initSelect --> d3d11Init[Call MicroProfileGpuInitD3D11] initSelect --> d3d12Init[Call MicroProfileGpuInitD3D12] initSelect --> vkInit[Call MicroProfileGpuInitVK] glInit --> ready[GPU Profiling Ready] d3d11Init --> ready d3d12Init --> ready vkInit --> ready ``` *All node IDs are alphanumeric; special characters in labels are escaped.* --- ## Context‑Switch Tracing To correlate GPU work with CPU scheduling, MicroProfile can capture OS context‑switch events: | Platform | Mechanism | Key Components | |----------|-----------|----------------| | Windows | **ETW** (Event Tracing for Windows) | `contextswitch_etw.cpp` creates a real‑time trace, receives `EventCSwitch` records, and writes them to a named pipe `\\.\pipe\microprofile-contextswitch`. | | macOS | **DTrace** | `contextswitch_dtrace.sh` runs a privileged DTrace script that prints `MPTD` lines to a FIFO (`/tmp/microprofile-contextswitch`). | ### Windows ETW Flow (simplified) ```mermaid graph TB startNode[Start ETW Trace] --> shutdown[Shutdown existing trace] shutdown --> startTrace[StartTrace#40;#41; -#62; Kernel Logger] startTrace --> pipeOpen[ReopenPipe#40;#41; -#62; CreateNamedPipe] pipeOpen --> waitConn[Wait for UI connection] waitConn --> eventLoop[ProcessTrace#40;#41; loop] eventLoop --> cswitch[ContextSwitchCallback] cswitch --> writePipe[WriteFile to pipe] writePipe --> stats[UpdateSwitchStats] stats --> loopBack[Continue loop] ``` *The callback extracts `NewThreadId`, `OldThreadId`, timestamps, and CPU number, then forwards a `MicroProfileContextSwitch` struct through the pipe.* Sources: `src/contextswitch_etw/contextswitch_etw.cpp` (functions `ContextSwitchStartTrace`, `ContextSwitchCallback`, `ContextSwitchPut`, `ReopenPipe`)【Sources: src/contextswitch_etw/contextswitch_etw.cpp】. ### macOS DTrace Flow ```mermaid graph TB scriptStart[Run contextswitch_dtrace.sh] --> requireRoot[Require root] requireRoot --> mkfifo[Create FIFO #47;tmp#47;microprofile-contextswitch] mkfifo --> dtraceRun[dtrace -q -n fbt::thread_dispatch:return] dtraceRun --> output[Write MPTD lines to FIFO] output --> uiRead[UI reads FIFO] uiRead --> correlate[Correlate with GPU frames] ``` Sources: `contextswitch_dtrace.sh` (pipeline creation and DTrace command)【Sources: contextswitch_dtrace.sh】. ### UI Hook The HTML UI (`microprofile.html`) contains a menu entry **“Context Switch”** that toggles the display of context‑switch data. When enabled, the JavaScript opens the named pipe (or FIFO) and merges the events with the timeline view. Sources: `src/microprofile.html` (menu item under **Options** → **Context Switch**)【Sources: src/microprofile.html】. --- ## Data Flow from GPU to UI 1. **Instrumentation** – Application code calls `MicroProfileGpuInsertTimer` / `MicroProfileGpuGetTimeStamp`. 2. **Backend** – The selected graphics backend records a GPU timestamp and stores it in a ring buffer keyed by the returned token. 3. **Aggregation** – At the end of each frame, MicroProfile aggregates CPU and GPU timings into `MicroProfileTimer` structures (defined in the hidden implementation). 4. **Export** – The profiler serialises the aggregated data into a binary stream that the HTML page fetches via XHR or WebSocket (implementation not shown). 5. **Visualization** – JavaScript in `microprofile.html` builds the timeline, draws GPU bars, and optionally overlays context‑switch bars when the **Context Switch** option is active. ### End‑to‑End Flowchart ```mermaid graph TB appCode[App Code] --> gpuInsert[MicroProfileGpuInsertTimer] gpuInsert --> backend[Backend records timestamp] backend --> gpuKey[Return key] appCode --> gpuGet[MicroProfileGpuGetTimeStamp] gpuGet --> backendRead[Backend reads timestamp] backendRead --> agg[Aggregate with CPU data] agg --> export[Serialise to binary] export --> uiFetch[HTML UI fetches data] uiFetch --> render[Render timeline & GPU bars] render --> overlay[Overlay context‑switch if enabled] ``` --- ## Build & Continuous Integration The project uses **Travis CI** to verify that the profiler builds on Linux and macOS. The `.travis.yml` file simply invokes `make -C src test`, which compiles the core library and runs the test suite (including the ETW and DTrace helpers where applicable). ```yaml # .travis.yml excerpt os: - linux - osx sudo: false language: cpp script: make -C src test ``` Sources: [.travis.yml](https://github.com/zeux/microprofile/blob/master/.travis.yml)【Sources: .travis.yml】. --- ## References - **MicroProfile GPU API** – `microprofile.h` (GPU timestamp section). - **Windows ETW Context‑Switch Collector** – `src/contextswitch_etw/contextswitch_etw.cpp`. - **macOS DTrace Collector** – `contextswitch_dtrace.sh`. - **HTML UI Controls** – `src/microprofile.html` (Options → Context Switch). - **CI Configuration** – `.travis.yml`. --- ### Summary MicroProfile’s GPU profiling subsystem provides a thin, cross‑API abstraction for inserting and reading GPU timestamps, backed by per‑API initialization routines. By coupling these timestamps with OS‑level context‑switch traces (ETW on Windows, DTrace on macOS) and feeding the combined data to a web‑based UI, developers gain a unified view of CPU, GPU, and scheduling activity. The architecture is deliberately lightweight, making it suitable for both development builds and production‑grade performance analysis.