gpu_neural_realtime_node.hpp

Go to the documentation of this file.

#pragma once
 
#include <cstdint>
#include <memory>
 
#include <pulp/audio/buffer.hpp>
#include <pulp/gpu_audio/gpu_audio_capability.hpp>
#include <pulp/gpu_audio/gpu_audio_node.hpp>
#include <pulp/gpu_audio/gpu_audio_status.hpp>
 
namespace pulp::gpu_audio {

enum class NeuralFamily : std::uint8_t {
    Unknown = 0,
    WaveNet = 1,
    Tcn = 2,
    Ssm = 3,
    Lstm = 4,
    Gru = 5,
    Custom = 255,
};

class GpuNeuralModel;
using GpuNeuralModelHandle = std::shared_ptr<GpuNeuralModel>;
 
class GpuNeuralRealtimeNode;
namespace detail {
struct RealtimeGpuHealth;
struct NeuralRealtimeTestAccess;
struct SharedIoProviderIdentity;
} // namespace detail

class GpuNeuralRealtimeNode : public GpuAudioNode {
  public:
    enum class ShadowPolicy : std::uint8_t {
        Auto = 0,
        Inline = 1,
        Worker = 2,
        None = 3,
    };

    static constexpr float kAutoInlineMaxCostPct = 15.0f;

    struct ShadowStatus {
        ShadowPolicy requested = ShadowPolicy::Auto;
        float inline_cost_per_channel_pct = -1.0f;
        float inline_cost_total_pct = -1.0f;
        std::uint64_t shadow_input_dropped = 0;
        std::uint64_t shadow_resyncs = 0;
        bool workgroup_joined = false;
    };

    enum class PrepareError : std::uint8_t {
        None,
        InvalidConfig,
        FamilyMismatch,
        ChannelMismatch,
        BackendInflightExceeded,
        ModelBound,
        ShadowPrepareFailed,
        ShadowUnpublished,
        BridgeFailed,
        ReleaseFailed,
        ShadowRequired,
        ShadowModelMismatch,
    };
 
    struct Config {
        NeuralFamily family = NeuralFamily::Unknown;
        GpuNeuralModelHandle model;
        std::uint32_t channels = 1;
        std::uint32_t lead_blocks = 2;
        std::uint32_t capacity = 8;
        std::uint32_t max_inflight = 0;
        std::uint32_t prewarm_blocks = 0;
        std::uint64_t completion_service_wait_ns = 0;
        MissPolicy miss_policy = MissPolicy::CpuFallback;
        ShadowPolicy shadow_policy = ShadowPolicy::Auto;
        GpuNeuralModelHandle shadow_model;
        std::uint32_t shadow_queue_blocks = 16;
        void* shadow_audio_workgroup = nullptr;
        std::uint32_t watchdog_blocks = 0;
    };

    explicit GpuNeuralRealtimeNode(Config config);
    ~GpuNeuralRealtimeNode() override;
    GpuNeuralRealtimeNode(const GpuNeuralRealtimeNode&) = delete;
    GpuNeuralRealtimeNode& operator=(const GpuNeuralRealtimeNode&) = delete;
 
    GpuAudioNodeDescriptor descriptor() const override;
    bool prepare() override;
    bool release() noexcept;

    bool cpu_fallback_prepared() const noexcept override;
    void prime_fallback(const audio::BufferView<const float>& input,
                        std::uint32_t n) noexcept override;
    void process_cpu_fallback(const audio::BufferView<const float>& input,
                              audio::BufferView<float>& output, std::uint32_t n) noexcept override;
    void process_block(const audio::BufferView<const float>&, audio::BufferView<float>&,
                       std::uint32_t) final;
 
    // Host/UI reads; see the threading note on the class.

    PrepareError last_prepare_error() const noexcept;
    std::uint64_t sanitized_input_samples() const noexcept;
    std::uint64_t callback_contract_violations() const noexcept;
    NeuralFamily family() const noexcept;
    bool gpu_kernel_available() const noexcept;
    std::uint64_t epoch() const noexcept;
    bool fenced() const noexcept;
    GpuAudioRecoveryReason recovery_reason() const noexcept;
    std::uint64_t recovery_sequence() const noexcept;
    GpuAudioStatus status_snapshot() const noexcept override;
    bool bind_realtime_path(detail::RealtimeGpuNodeBinding& binding) noexcept override;
    GpuAudioCapabilityReport capability_report() const noexcept;
    ShadowStatus shadow_status() const noexcept;
 
  private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
    friend struct detail::NeuralRealtimeTestAccess;
    bool ready() const noexcept;
    bool authenticated_provider() const noexcept;
    // Provider identity for the transport: Dawn when authenticated, Cpu when
    // prepared without a GPU backend, otherwise Unknown.
    GpuAudioProvider transport_provider() const noexcept;
    detail::SharedIoProviderIdentity provider_identity_for_transport() const noexcept;
    static std::uint8_t process(void*, const audio::BufferView<const float>&,
                                audio::BufferView<float>&, std::uint32_t, std::uint64_t, bool,
                                std::uint64_t) noexcept;
    static std::uint32_t service(void*, std::uint64_t) noexcept;
    static bool fence(void*) noexcept;
    static void offline_render(void*, bool offline) noexcept;
    static void delivered(void*, std::uint64_t, std::uint8_t, std::uint64_t,
                          std::uint64_t) noexcept;
    static std::uint64_t next_sequence(void*) noexcept;
    static bool health(const void*, detail::RealtimeGpuHealth&) noexcept;
};
 
} // namespace pulp::gpu_audio