audio_budget.hpp

Go to the documentation of this file.

/**
 * @file audio_budget.hpp
 * @brief Audio callback tick budget tracker
 *
 * Measures per-block tick consumption in audio callbacks using the
 * platform timing backend. Tracks average (EWMA), peak, min, overrun count,
 * and a per-block load histogram (11 buckets, 10% each).
 *
 * Gated behind SBL_PROFILING_ENABLED. When the define is absent, all
 * methods compile to no-ops and the class has zero data members -- no
 * binary impact whatsoever.
 *
 * Usage:
 *   static sbl::diagnostics::AudioBudget budget;
 *   budget.init(48000, 48);
 *
 *   void audio_callback(int32_t* tx, const int32_t* rx, uint16_t frames) {
 *       budget.on_block_start();
 *       // ... DSP ...
 *       budget.on_block_end();
 *   }
 *
 *   // In control loop:
 *   budget.avg_load()   // [0.0, 1.0+]
 *   budget.peak_load()  // worst-case since last reset
 *   budget.overruns()   // count of callbacks that exceeded budget
 */
#ifndef SBL_COMMON_DIAGNOSTICS_AUDIO_BUDGET_HPP_
#define SBL_COMMON_DIAGNOSTICS_AUDIO_BUDGET_HPP_
 
#include <cstdint>
 
#include <cstddef>
 
#ifdef SBL_PROFILING_ENABLED
#include <sbl/common/diagnostics/ticks.hpp>
#endif
 
namespace sbl::diagnostics {
 
class AudioBudget {
    static constexpr size_t HIST_BUCKETS = 11;
 
public:
    /// Configure budget from audio parameters.
    /// budget_ticks = (tick_rate() / sample_rate) * block_size
    void init(uint32_t sample_rate, uint16_t block_size) {
#ifdef SBL_PROFILING_ENABLED
        budget_ = (tick_rate() / sample_rate) * block_size;
        reset();
#else
        (void)sample_rate; (void)block_size;
#endif
    }
 
    /// Mark the start of audio processing (call first in callback)
    void on_block_start() {
#ifdef SBL_PROFILING_ENABLED
        start_ = ticks();
#endif
    }
 
    /// Mark the end of audio processing (call last in callback)
    void on_block_end() {
#ifdef SBL_PROFILING_ENABLED
        uint32_t elapsed = ticks() - start_;
        ++count_;
 
        if (elapsed > max_) max_ = elapsed;
        if (elapsed < min_) min_ = elapsed;
        if (elapsed > budget_) ++overruns_;
 
        // EWMA smoothing, alpha = 1/128 (~130ms settling at 1ms blocks)
        avg_ += (static_cast<float>(elapsed) - avg_) * (1.0f / 128.0f);
 
        // Histogram: bucket index = load_percent / 10, clamped to [0, HIST_BUCKETS-1]
        uint32_t pct = (elapsed * 100) / budget_;
        uint32_t bucket = pct / 10;
        if (bucket >= HIST_BUCKETS) bucket = HIST_BUCKETS - 1;
        hist_[bucket]++;
#endif
    }
 
    // --- Queries (safe to call from control context) ---
 
    /// Average load as fraction [0.0, 1.0+]
    float avg_load() const {
#ifdef SBL_PROFILING_ENABLED
        return avg_ / static_cast<float>(budget_);
#else
        return 0.0f;
#endif
    }
 
    /// Peak (worst-case) load since last reset
    float peak_load() const {
#ifdef SBL_PROFILING_ENABLED
        return static_cast<float>(max_) / static_cast<float>(budget_);
#else
        return 0.0f;
#endif
    }
 
    /// Minimum load since last reset
    float min_load() const {
#ifdef SBL_PROFILING_ENABLED
        return static_cast<float>(min_) / static_cast<float>(budget_);
#else
        return 0.0f;
#endif
    }
 
    /// Raw tick counts
    uint32_t avg_ticks() const {
#ifdef SBL_PROFILING_ENABLED
        return static_cast<uint32_t>(avg_);
#else
        return 0;
#endif
    }
 
    uint32_t peak_ticks() const {
#ifdef SBL_PROFILING_ENABLED
        return max_;
#else
        return 0;
#endif
    }
 
    uint32_t min_ticks() const {
#ifdef SBL_PROFILING_ENABLED
        return min_;
#else
        return 0;
#endif
    }
 
    uint32_t budget_ticks() const {
#ifdef SBL_PROFILING_ENABLED
        return budget_;
#else
        return 0;
#endif
    }
 
    /// Number of callbacks that exceeded the tick budget
    uint32_t overruns() const {
#ifdef SBL_PROFILING_ENABLED
        return overruns_;
#else
        return 0;
#endif
    }
 
    /// Total callbacks measured
    uint32_t count() const {
#ifdef SBL_PROFILING_ENABLED
        return count_;
#else
        return 0;
#endif
    }
 
    // --- Histogram (10% buckets: 0-10%, 10-20%, ..., 90-100%, >100%) ---
 
    /// Number of histogram buckets
    static constexpr size_t hist_size() { return HIST_BUCKETS; }
 
    /// Read histogram bucket count (0-indexed, last bucket is >100%)
    uint32_t hist_bucket(size_t i) const {
#ifdef SBL_PROFILING_ENABLED
        return (i < HIST_BUCKETS) ? hist_[i] : 0;
#else
        (void)i; return 0;
#endif
    }
 
    /// Reset statistics (budget preserved)
    void reset() {
#ifdef SBL_PROFILING_ENABLED
        avg_ = 0.0f;
        max_ = 0;
        min_ = budget_;
        overruns_ = 0;
        count_ = 0;
        for (auto& b : hist_) b = 0;
#endif
    }
 
private:
#ifdef SBL_PROFILING_ENABLED
    uint32_t start_    = 0;
    uint32_t budget_   = 0;
    float    avg_      = 0.0f;
    uint32_t max_      = 0;
    uint32_t min_      = 0;
    uint32_t overruns_ = 0;
    uint32_t count_    = 0;
 
    uint32_t hist_[HIST_BUCKETS] = {};
#endif
};
 
} // namespace sbl::diagnostics
 
#endif // SBL_COMMON_DIAGNOSTICS_AUDIO_BUDGET_HPP_