gpu_diagnostics.hpp

Go to the documentation of this file.

// gpu_diagnostics.hpp — one sink for GPU-layer diagnostics.
//
// Dawn hands errors to a callback; Skia hands log records to an SkLogHandler.
// Both funnel through emit_gpu_diagnostic(), which publishes a `gpu`-category
// Perfetto instant event so a device error lands on the same timeline as the
// frame that provoked it. This ADDS a trace signal — every call site keeps its
// runtime::log_* call, because a log is what a user reads and a trace is what a
// timeline query joins against.
//
// RT-safety: the Dawn uncaptured-error callback fires on the render thread.
// emit_gpu_diagnostic() allocates nothing: the message is copied into a bounded
// stack buffer and attached to a compile-time event name as a debug annotation,
// so the event name stays interned and nothing reaches the heap. It is still a
// Perfetto TRACE_EVENT and therefore must never be placed on the audio thread's
// live process() path (see trace.hpp).
//
// Observability: a bridge that quietly emits nothing forever is indistinguishable
// from a quiet GPU. gpu_diagnostics_stats() and skia_log_bridge_state() exist so
// "nothing was wired up" is always distinguishable from "nothing went wrong".
#pragma once
 
#if defined(PULP_GPU_RUNTIME)
// This build's device layer is gpu-runtime's (tools/cmake/PulpGpuRuntime.cmake):
// these are its types and functions under their Pulp names, so a Pulp object
// and a gpu-runtime object are one and the same.
#include <gpu_runtime/gpu_diagnostics.hpp>
 
namespace pulp::render {
using gpu_runtime::emit_gpu_diagnostic;
using gpu_runtime::gpu_diagnostics_stats;
using gpu_runtime::GpuDiagnosticSeverity;
using gpu_runtime::GpuDiagnosticsStats;
using gpu_runtime::install_skia_log_bridge;
using gpu_runtime::install_skia_log_bridge_if_enabled;
using gpu_runtime::kGpuDiagnosticMessageLimit;
using gpu_runtime::kSkiaLogTextLimit;
using gpu_runtime::LogTextBudget;
using gpu_runtime::skia_log_bridge_available;
using gpu_runtime::skia_log_bridge_enabled;
using gpu_runtime::skia_log_bridge_state;
using gpu_runtime::SkiaLogBridgeState;
using gpu_runtime::SkiaLogBridgeStatus;
using gpu_runtime::to_string;
} // namespace pulp::render
#else // !PULP_GPU_RUNTIME
 
#include <atomic>
#include <cstddef>
#include <cstdint>
#include <string_view>
 
namespace pulp::render {

enum class GpuDiagnosticSeverity {
    info,
    warning,
    error,
    fatal,
};

const char* to_string(GpuDiagnosticSeverity severity) noexcept;

void emit_gpu_diagnostic(GpuDiagnosticSeverity severity, const char* source,
                         std::string_view message) noexcept;

inline constexpr std::size_t kGpuDiagnosticMessageLimit = 512;

struct GpuDiagnosticsStats {
    std::uint64_t emitted = 0;
    std::uint64_t traced = 0;
    std::uint64_t truncated = 0;
};
 
GpuDiagnosticsStats gpu_diagnostics_stats() noexcept;

enum class SkiaLogBridgeStatus {
    not_attempted,
    installed,
    declined_handler_present,
    declined_not_enabled,
    unavailable_no_skia,
};

const char* to_string(SkiaLogBridgeStatus status) noexcept;
 
struct SkiaLogBridgeState {
    SkiaLogBridgeStatus status = SkiaLogBridgeStatus::not_attempted;
    std::uint64_t records_forwarded = 0;
    std::uint64_t text_logged = 0;
    std::uint64_t text_suppressed = 0;
};

inline constexpr std::uint64_t kSkiaLogTextLimit = 50;

class LogTextBudget {
  public:
    explicit constexpr LogTextBudget(std::uint64_t limit) noexcept : limit_(limit) {}
 
    bool admit() noexcept {
        const auto index = seen_.fetch_add(1, std::memory_order_relaxed);
        return index < limit_;
    }
 
    std::uint64_t admitted() const noexcept {
        const auto seen = seen_.load(std::memory_order_relaxed);
        return seen < limit_ ? seen : limit_;
    }
 
    std::uint64_t suppressed() const noexcept {
        const auto seen = seen_.load(std::memory_order_relaxed);
        return seen > limit_ ? seen - limit_ : 0;
    }
 
  private:
    std::uint64_t limit_;
    std::atomic<std::uint64_t> seen_{0};
};
 
SkiaLogBridgeState skia_log_bridge_state() noexcept;

bool skia_log_bridge_available() noexcept;

bool skia_log_bridge_enabled() noexcept;

SkiaLogBridgeStatus install_skia_log_bridge_if_enabled() noexcept;

SkiaLogBridgeStatus install_skia_log_bridge() noexcept;
 
} // namespace pulp::render
 
#endif // PULP_GPU_RUNTIME