report.hpp

Go to the documentation of this file.

/**
 * @file report.hpp
 * @brief Profiling report formatters (human-readable and tagged)
 *
 * Formats AudioBudget + named SectionProfiles into log-friendly strings.
 * Gated behind SBL_PROFILING_ENABLED — compiles to nothing when disabled.
 *
 * Two output modes:
 *
 * Human-readable (format_report):
 *   CPU: avg=36.9% peak=38.8% overruns=0
 *     osc=85119 svf=12928 verb=41100 dly=9344
 *
 * Tagged (format_tagged_report + format_tagged_histogram):
 *   `#PROF` cpu_avg=36.9 cpu_peak=38.8 cpu_min=34.2 overruns=0 blocks=48000
 *   `#PROF.OSC` ticks=85119
 *   `#PROF.SVF` ticks=12928
 *   `#HIST` b0_10=0 b10_20=0 b20_30=150 b30_40=47200 ...
 *
 * See docs/conventions/tagged-output.md for the tagged output spec.
 *
 * Usage:
 *   sbl::diagnostics::NamedSection sections[] = {
 *       {"osc", s_prof_osc.avg}, {"svf", s_prof_svf.avg},
 *   };
 *   char buf[256];
 *   sbl::diagnostics::format_tagged_report(buf, sizeof(buf), s_budget, sections, 2);
 *   uart_write(buf);
 *   sbl::diagnostics::format_tagged_histogram(buf, sizeof(buf), s_budget);
 *   uart_write(buf);
 */
#ifndef SBL_COMMON_DIAGNOSTICS_REPORT_HPP_
#define SBL_COMMON_DIAGNOSTICS_REPORT_HPP_
 
#include <cstdint>
#include <cstddef>
#include <sbl/common/diagnostics/audio_budget.hpp>
#include <sbl/common/log/format.hpp>
 
namespace sbl::diagnostics {
 
struct NamedSection {
    const char* name;
    uint32_t avg;
};
 
/**
 * @brief Format a profiling report into a buffer
 *
 * @param buf Output buffer
 * @param size Buffer size
 * @param budget AudioBudget instance
 * @param sections Array of named section profiles
 * @param n Number of sections
 * @return Number of characters written
 */
inline int format_report(char* buf, size_t size, const AudioBudget& budget,
                         const NamedSection* sections, size_t n) {
#ifdef SBL_PROFILING_ENABLED
    int pos = sbl::log::format(buf, size,
        "CPU: avg=%d.%d%% peak=%d.%d%% overruns=%u\r\n",
        static_cast<int>(budget.avg_load() * 100.0f),
        static_cast<int>(budget.avg_load() * 1000.0f) % 10,
        static_cast<int>(budget.peak_load() * 100.0f),
        static_cast<int>(budget.peak_load() * 1000.0f) % 10,
        budget.overruns());
 
    if (n > 0 && static_cast<size_t>(pos) < size - 1) {
        // "  name=val name=val ...\r\n"
        size_t remaining = size - static_cast<size_t>(pos);
        int spos = sbl::log::format(buf + pos, remaining, "  ");
        pos += spos;
 
        for (size_t i = 0; i < n && static_cast<size_t>(pos) < size - 1; ++i) {
            remaining = size - static_cast<size_t>(pos);
            if (i > 0) {
                spos = sbl::log::format(buf + pos, remaining, " ");
                pos += spos;
                remaining = size - static_cast<size_t>(pos);
            }
            spos = sbl::log::format(buf + pos, remaining, "%s=%u",
                                    sections[i].name, sections[i].avg);
            pos += spos;
        }
 
        remaining = size - static_cast<size_t>(pos);
        spos = sbl::log::format(buf + pos, remaining, "\r\n");
        pos += spos;
    }
 
    return pos;
#else
    (void)budget; (void)sections; (void)n;
    if (size > 0) buf[0] = '\0';
    return 0;
#endif
}
 
// ─── Tagged output formatters (FDP-028) ─────────────────────────────
 
/**
 * @brief Format profiling data as tagged output lines
 *
 * Emits one `#PROF` summary line followed by one `#PROF.<NAME>` line per section.
 * Section names are uppercased in the tag (e.g., "osc" → `#PROF.OSC`).
 *
 * @return Number of characters written
 */
inline int format_tagged_report(char* buf, size_t size, const AudioBudget& budget,
                                const NamedSection* sections, size_t n) {
#ifdef SBL_PROFILING_ENABLED
    int pos = sbl::log::format(buf, size,
        "#PROF cpu_avg=%d.%d cpu_peak=%d.%d cpu_min=%d.%d overruns=%u blocks=%u\r\n",
        static_cast<int>(budget.avg_load() * 100.0f),
        static_cast<int>(budget.avg_load() * 1000.0f) % 10,
        static_cast<int>(budget.peak_load() * 100.0f),
        static_cast<int>(budget.peak_load() * 1000.0f) % 10,
        static_cast<int>(budget.min_load() * 100.0f),
        static_cast<int>(budget.min_load() * 1000.0f) % 10,
        budget.overruns(),
        budget.count());
 
    for (size_t i = 0; i < n && static_cast<size_t>(pos) < size - 1; ++i) {
        size_t remaining = size - static_cast<size_t>(pos);
        pos += sbl::log::format(buf + pos, remaining,
            "#PROF.%s ticks=%u\r\n",
            sections[i].name, sections[i].avg);
    }
 
    return pos;
#else
    (void)budget; (void)sections; (void)n;
    if (size > 0) buf[0] = '\0';
    return 0;
#endif
}
 
/**
 * @brief Format CPU load histogram as a tagged output line
 *
 * Emits a single `#HIST` line with 11 bucket counts (10% each, last is >100%).
 *
 * @return Number of characters written
 */
inline int format_tagged_histogram(char* buf, size_t size, const AudioBudget& budget) {
#ifdef SBL_PROFILING_ENABLED
    static const char* labels[] = {
        "b0_10", "b10_20", "b20_30", "b30_40", "b40_50",
        "b50_60", "b60_70", "b70_80", "b80_90", "b90_100", "over"
    };
 
    int pos = sbl::log::format(buf, size, "#HIST");
 
    for (size_t i = 0; i < budget.hist_size() && static_cast<size_t>(pos) < size - 1; ++i) {
        size_t remaining = size - static_cast<size_t>(pos);
        pos += sbl::log::format(buf + pos, remaining, " %s=%u",
                                labels[i], budget.hist_bucket(i));
    }
 
    if (static_cast<size_t>(pos) < size - 1) {
        size_t remaining = size - static_cast<size_t>(pos);
        pos += sbl::log::format(buf + pos, remaining, "\r\n");
    }
 
    return pos;
#else
    (void)budget;
    if (size > 0) buf[0] = '\0';
    return 0;
#endif
}
 
} // namespace sbl::diagnostics
 
#endif // SBL_COMMON_DIAGNOSTICS_REPORT_HPP_