driver.hpp

Go to the documentation of this file.

/**
 * @file driver.hpp
 * @brief Audio driver interface - canonical types and convenience functions
 * @ingroup hal
 *
 * This header provides the portable audio API for Sound Byte Libs.
 *
 * ## Audio Driver Contract
 *
 * Drivers implement the following static interface:
 *
 *   static void init()                          - Configure with defaults
 *   static void init(const AudioConfig&)        - Configure with custom settings
 *   static void set_callback(AudioCallback)     - Register processing function
 *   static void start()                         - Begin streaming
 *   static void stop()                          - Stop streaming
 *
 * Every block the driver clocks out advances SampleClock by its frame count
 * (sample_clock.hpp), after the callback returns — the elapsed-samples
 * source for control code.
 *
 * ## Convenience Functions
 *
 *   sbl::audio::start<sbl::driver::Sai>(my_callback);
 *   sbl::audio::stop<sbl::driver::Sai>();
 *
 * Usage in application:
 *   \#include <sbl/hw/hal/audio/driver.hpp>
 *   \#include <sbl/hw/driver/sai.hpp>
 *
 *   sbl::audio::start<sbl::driver::Sai>(audio_callback);
 */
 
#ifndef SBL_HW_HAL_AUDIO_DRIVER_HPP_
#define SBL_HW_HAL_AUDIO_DRIVER_HPP_
 
#include "types.hpp"
 
namespace sbl {
 
namespace audio {
    using AudioConfig = sbl::hal::audio::AudioConfig;
    using AudioCallback = sbl::hal::audio::AudioCallback;
 
    /**
     * @brief Configure audio with defaults, set callback, and start streaming
     *
     * @tparam Driver Audio driver type (e.g., sbl::driver::Sai)
     * @param cb Audio processing callback (called from ISR context)
     *
     * @note Not ISR-safe — init-time only (configures audio hardware + DMA)
     */
    template<typename Driver>
    inline void start(AudioCallback cb) {
        Driver::init();
        Driver::set_callback(cb);
        Driver::start();
    }
 
    /**
     * @brief Configure with custom settings, set callback, and start streaming
     *
     * @tparam Driver Audio driver type (e.g., sbl::driver::Sai)
     * @param config Audio configuration (sample rate, bit depth, block size)
     * @param cb Audio processing callback (called from ISR context)
     *
     * @note Not ISR-safe — init-time only (configures audio hardware + DMA)
     */
    template<typename Driver>
    inline void start(const AudioConfig& config, AudioCallback cb) {
        Driver::init(config);
        Driver::set_callback(cb);
        Driver::start();
    }
 
    /**
     * @brief Stop audio streaming
     *
     * @tparam Driver Audio driver type (e.g., sbl::driver::Sai)
     *
     * @note Not ISR-safe — tears down audio streaming hardware
     */
    template<typename Driver>
    inline void stop() {
        Driver::stop();
    }
 
} // namespace audio
 
} // namespace sbl
 
#endif // SBL_HW_HAL_AUDIO_DRIVER_HPP_