gpu_audio_program.hpp

Go to the documentation of this file.

#pragma once
 
#include <cstdint>
#include <type_traits>
 
#include <pulp/gpu_audio/gpu_audio_capability.hpp>
 
namespace pulp::gpu_audio {

enum class GpuAudioProgramKind : std::uint8_t {
    Unknown = 0,
    Convolution = 1,
    Spectral = 2,
    Neural = 3,
    Custom = 255,
};

enum class GpuAudioTerminalDisposition : std::uint8_t {
    Unknown = 0,
    GpuDelivered = 1,
    CpuFallback = 2,
    Silence = 3,
    StaleRejected = 4,
    LateRejected = 5,
    DeviceLost = 6,
    Cancelled = 7,
    kCount,
};
static_assert(static_cast<std::uint32_t>(GpuAudioTerminalDisposition::kCount) ==
                  GpuAudioStatus::kTerminalDispositionCount,
              "GpuAudioStatus::terminal_counts must cover every terminal disposition");
static_assert(static_cast<std::uint32_t>(GpuAudioTerminalDisposition::GpuDelivered) == 1 &&
                  static_cast<std::uint32_t>(GpuAudioTerminalDisposition::CpuFallback) == 2,
              "validate_gpu_audio_status indexes terminal_counts by these values");

enum class GpuAudioProgramError : std::uint8_t {
    None = 0,
    MissingKind = 1,
    InvalidShape = 2,
    PathUnavailable = 3,
    MissingAlgorithmicLead = 4,
    MissingPipelineDepth = 5,
    InsufficientPipelineDepth = 6,
    MissingProviderSlots = 7,
    MissingProviderIdentity = 8,
    ProviderResourcesNotOwned = 9,
    ProviderResourcesOnCpu = 10,
    ProviderResourcesOnStaged = 11,
    ProviderOnCpu = 12,
    CpuPipelineOnCpu = 13,
    CpuFallbackNotPrepared = 14,
    // The descriptor is valid in isolation, but the prepared transport did
    // not authenticate the same path/provider contract.  These values are
    // appended so the existing wire/debug values remain stable.
    CapabilityNotPrepared = 15,
    CapabilityIneligible = 16,
    CapabilityPathMismatch = 17,
    CapabilityProviderMismatch = 18,
    CapabilityLeadMismatch = 19,
    CapabilityFallbackPolicyMismatch = 20,
    CapabilityFallbackUnavailable = 21,
    // A descriptor enum outside its declared domain, and a capability report
    // that agrees with the descriptor but is not self-consistent (see
    // validate_gpu_audio_capability). Appended like the values above.
    InvalidEnumValue = 22,
    CapabilityInvalid = 23,
    // A staged or shared-memory descriptor naming the CPU provider, which
    // validate_gpu_audio_capability() rejects as CpuProviderOnGpuPath, so
    // such a program could never bind. Appended.
    CpuProviderOnGpuPath = 24,
};

struct GpuAudioProgramDescriptor {
    GpuAudioProgramKind kind = GpuAudioProgramKind::Unknown;
    GpuAudioExecutionPath path = GpuAudioExecutionPath::Unavailable;
    GpuAudioProvider provider = GpuAudioProvider::Unknown;
    MissPolicy miss_policy = MissPolicy::Silence;
    std::uint32_t channels = 0;
    std::uint32_t block_size = 0;
    std::uint32_t sample_rate = 0;
    std::uint32_t algorithmic_lead_blocks = 0;
    std::uint32_t pipeline_depth = 0;
    std::uint32_t provider_slots = 0;
    bool provider_owned_resources = false;
    bool cpu_fallback_prepared = false;
};
 
struct GpuAudioProgramValidation {
    GpuAudioProgramError error = GpuAudioProgramError::None;
 
    constexpr bool accepted() const noexcept {
        return error == GpuAudioProgramError::None;
    }
};

constexpr GpuAudioProgramValidation
validate_gpu_audio_program(const GpuAudioProgramDescriptor& program) noexcept {
    const auto kind = program.kind;
    if ((kind != GpuAudioProgramKind::Unknown && kind != GpuAudioProgramKind::Convolution &&
         kind != GpuAudioProgramKind::Spectral && kind != GpuAudioProgramKind::Neural &&
         kind != GpuAudioProgramKind::Custom) ||
        static_cast<std::uint8_t>(program.path) >
            static_cast<std::uint8_t>(GpuAudioExecutionPath::Cpu) ||
        static_cast<std::uint8_t>(program.provider) >
            static_cast<std::uint8_t>(GpuAudioProvider::Cpu) ||
        static_cast<int>(program.miss_policy) < 0 ||
        static_cast<int>(program.miss_policy) > static_cast<int>(MissPolicy::CpuFallback))
        return {GpuAudioProgramError::InvalidEnumValue};
    if (program.kind == GpuAudioProgramKind::Unknown)
        return {GpuAudioProgramError::MissingKind};
    if (program.channels == 0 || program.block_size == 0 || program.sample_rate == 0)
        return {GpuAudioProgramError::InvalidShape};
    if (program.miss_policy == MissPolicy::CpuFallback && !program.cpu_fallback_prepared)
        return {GpuAudioProgramError::CpuFallbackNotPrepared};
 
    if (program.path == GpuAudioExecutionPath::Unavailable)
        return {GpuAudioProgramError::PathUnavailable};
 
    if (program.path == GpuAudioExecutionPath::Staged ||
        program.path == GpuAudioExecutionPath::SharedMemory) {
        if (program.algorithmic_lead_blocks == 0)
            return {GpuAudioProgramError::MissingAlgorithmicLead};
        if (program.pipeline_depth == 0)
            return {GpuAudioProgramError::MissingPipelineDepth};
        if (program.pipeline_depth <= program.algorithmic_lead_blocks)
            return {GpuAudioProgramError::InsufficientPipelineDepth};
        if (program.provider_slots == 0)
            return {GpuAudioProgramError::MissingProviderSlots};
    }
 
    if ((program.path == GpuAudioExecutionPath::Staged ||
         program.path == GpuAudioExecutionPath::SharedMemory) &&
        program.provider == GpuAudioProvider::Cpu)
        return {GpuAudioProgramError::CpuProviderOnGpuPath};
 
    if (program.path == GpuAudioExecutionPath::SharedMemory) {
        if (program.provider == GpuAudioProvider::Unknown)
            return {GpuAudioProgramError::MissingProviderIdentity};
        if (!program.provider_owned_resources)
            return {GpuAudioProgramError::ProviderResourcesNotOwned};
    } else if (program.path == GpuAudioExecutionPath::Staged) {
        if (program.provider_owned_resources)
            return {GpuAudioProgramError::ProviderResourcesOnStaged};
    } else {
        if (program.provider != GpuAudioProvider::Unknown)
            return {GpuAudioProgramError::ProviderOnCpu};
        if (program.provider_owned_resources)
            return {GpuAudioProgramError::ProviderResourcesOnCpu};
        if (program.algorithmic_lead_blocks != 0 || program.pipeline_depth != 0 ||
            program.provider_slots != 0)
            return {GpuAudioProgramError::CpuPipelineOnCpu};
    }
 
    return {};
}

constexpr GpuAudioProgramValidation
validate_gpu_audio_program(const GpuAudioProgramDescriptor& program,
                           const GpuAudioCapabilityReport& capability) noexcept {
    const auto descriptor = validate_gpu_audio_program(program);
    if (!descriptor.accepted())
        return descriptor;
    if (!capability.prepared)
        return {GpuAudioProgramError::CapabilityNotPrepared};
    if (capability.eligibility != GpuAudioEligibility::Eligible)
        return {GpuAudioProgramError::CapabilityIneligible};
    if (capability.path != program.path)
        return {GpuAudioProgramError::CapabilityPathMismatch};
    if (capability.fallback_policy != program.miss_policy)
        return {GpuAudioProgramError::CapabilityFallbackPolicyMismatch};
    if (program.algorithmic_lead_blocks != capability.prepared_lead_blocks)
        return {GpuAudioProgramError::CapabilityLeadMismatch};
    if (program.path == GpuAudioExecutionPath::SharedMemory &&
        capability.provider != program.provider)
        return {GpuAudioProgramError::CapabilityProviderMismatch};
    // A known descriptor provider must still be witnessed by the prepared
    // capability for staged paths.  Unknown is the honest generic staged
    // value and remains valid when both sides leave identity unspecified.
    if (program.path == GpuAudioExecutionPath::Staged &&
        program.provider != GpuAudioProvider::Unknown && capability.provider != program.provider)
        return {GpuAudioProgramError::CapabilityProviderMismatch};
    if (program.miss_policy == MissPolicy::CpuFallback && !capability.fallback_available)
        return {GpuAudioProgramError::CapabilityFallbackUnavailable};
    // The checks above compare the two sides. A report can agree with the
    // descriptor on every compared field and still contradict itself, for
    // example an out-of-domain enum in a field the descriptor leaves Unknown.
    if (!validate_gpu_audio_capability(capability).accepted())
        return {GpuAudioProgramError::CapabilityInvalid};
    return {};
}
 
static_assert(std::is_trivially_copyable_v<GpuAudioProgramDescriptor>);
static_assert(std::is_trivially_copyable_v<GpuAudioProgramValidation>);
 
} // namespace pulp::gpu_audio