fixed_ir_convolver.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/signal/convolver.hpp>
#include <pulp/signal/convolver_messages.hpp>
#include <pulp/signal/fir_filter.hpp>
 
#include <algorithm>
#include <cstddef>
#include <cstdint>
#include <type_traits>
#include <vector>
 
#if defined(__APPLE__)
#include <TargetConditionals.h>
#endif
 
// The direct-engine table was measured on Apple Silicon Macs with the
// Accelerate backend in single precision; it applies only there.
#if defined(PULP_SIMD_DEFAULT_BACKEND_ACCELERATE) && defined(__aarch64__) &&                       \
    defined(TARGET_OS_OSX) && TARGET_OS_OSX
#define PULP_FIXED_IR_MEASURED_TABLE 1
#else
#define PULP_FIXED_IR_MEASURED_TABLE 0
#endif
 
namespace pulp::signal {

enum class ConvolutionBackend : std::uint8_t {
    none,            
    direct_fir,      
    partitioned_fft, 
};

template <typename SampleType = float> class FixedIrConvolverT {
  public:
    void load_ir(const SampleType* ir, std::size_t ir_length, std::size_t block_size) {
        load_ir(ir, ir_length, block_size, choose_backend(ir_length, block_size));
    }

    void load_ir(const SampleType* ir, std::size_t ir_length, std::size_t block_size,
                 ConvolutionBackend engine) {
        direct_.set_coefficients({});
        partitioned_ = PartitionedConvolverT<SampleType>{};
        violations_ = 0;
        if (ir == nullptr || ir_length == 0 || engine == ConvolutionBackend::none) {
            backend_ = ConvolutionBackend::none;
            block_size_ = 0;
            return;
        }
        block_size_ = detail::convolver_block_size(block_size);
        backend_ = engine;
        if (backend_ == ConvolutionBackend::direct_fir)
            direct_.set_coefficients(std::vector<SampleType>(ir, ir + ir_length));
        else
            partitioned_.load_ir(ir, ir_length, block_size);
    }

    static constexpr ConvolutionBackend choose_backend(std::size_t ir_length,
                                                       std::size_t block_size) noexcept {
        return ir_length <= direct_fir_limit(block_size) ? ConvolutionBackend::direct_fir
                                                         : ConvolutionBackend::partitioned_fft;
    }

    static constexpr std::size_t direct_fir_limit(std::size_t block_size) noexcept {
#if PULP_FIXED_IR_MEASURED_TABLE
        if constexpr (!std::is_same_v<SampleType, float>) {
            (void)block_size;
            return 0;
        } else {
            switch (detail::convolver_block_size(block_size)) {
            case 1:
            case 2:
            case 4:
            case 8:
                return 4096;
            case 16:
                return 576;
            case 32:
            case 64:
                return 128;
            default:
                return 64;
            }
        }
#else
        (void)block_size;
        return 0;
#endif
    }

    void process(const SampleType* input, SampleType* output, std::size_t num_samples) {
        switch (backend_) {
        case ConvolutionBackend::none:
            if (input != output)
                std::copy_n(input, num_samples, output);
            return;
        case ConvolutionBackend::partitioned_fft:
            // The FFT engine fails closed and recovers on its own; only the
            // count lives here, so both engines report it the same way.
            if (num_samples != block_size_)
                ++violations_;
            partitioned_.process(input, output, num_samples);
            return;
        case ConvolutionBackend::direct_fir:
            // A direct FIR has no partitioning, so any count up to the
            // prepared maximum continues the stream.
            if (num_samples > block_size_) {
                std::fill_n(output, num_samples, SampleType{0});
                ++violations_;
                direct_.reset();
                return;
            }
            direct_.process(input, output, static_cast<int>(num_samples));
            return;
        }
    }

    void reset() {
        direct_.reset();
        partitioned_.reset();
        violations_ = 0;
    }
 
    [[nodiscard]] bool is_loaded() const noexcept {
        return backend_ != ConvolutionBackend::none;
    }

    [[nodiscard]] std::size_t block_size() const noexcept {
        return block_size_;
    }
    [[nodiscard]] std::size_t latency() const noexcept {
        return 0;
    }

    [[nodiscard]] std::uint64_t block_size_violations() const noexcept {
        return violations_;
    }
    [[nodiscard]] ConvolutionBackend backend() const noexcept {
        return backend_;
    }
 
  private:
    ConvolutionBackend backend_ = ConvolutionBackend::none;
    std::size_t block_size_ = 0;
    std::uint64_t violations_ = 0;
    FirFilterT<SampleType> direct_;
    PartitionedConvolverT<SampleType> partitioned_;
};
 
using FixedIrConvolver = FixedIrConvolverT<float>;
using FixedIrConvolver64 = FixedIrConvolverT<double>;
 
} // namespace pulp::signal