types.hpp

Go to the documentation of this file.

/**
 * @file types.hpp
 * @brief Audio common types and configuration
 * @ingroup hal
 *
 * Platform-agnostic audio types shared across the HAL layer.
 * These types are used by both the HAL interface and platform implementations.
 *
 * Audio drivers (SAI, I2S, etc.) include this header and use these types
 * in their public interface, ensuring a consistent contract across platforms.
 */
 
#ifndef SBL_HAL_AUDIO_TYPES_HPP_
#define SBL_HAL_AUDIO_TYPES_HPP_
 
#include <cstdint>
 
namespace sbl {
namespace hal {
namespace audio {
 
/**
 * @brief SAI block direction layout
 *
 * Determines which SAI block is TX (to DAC) and which is RX (from ADC).
 * This is board-level configuration — the codec wiring determines the mapping.
 */
enum class SaiLayout {
    A_TX_B_RX,  ///< Block A = Master TX, Block B = Slave RX (Daisy Seed / AK4556)
    A_RX_B_TX   ///< Block A = Slave RX,  Block B = Master TX (Patch SM / PCM3060)
};
 
/**
 * @brief Audio stream configuration
 *
 * Describes the audio format for streaming. Drivers may ignore fields
 * that are fixed by hardware (e.g., sample_rate when set by PLL).
 */
struct AudioConfig {
    uint32_t sample_rate = 48000;  ///< Sample rate in Hz
    uint8_t  bit_depth = 24;       ///< Bits per sample
    uint16_t block_size = 48;      ///< Stereo frames per callback
    SaiLayout layout = SaiLayout::A_TX_B_RX;  ///< SAI block direction
};
 
/**
 * @brief Audio processing callback (called from ISR context)
 *
 * Audio samples are int32_t in 24-bit signed range (±8,388,607).
 * Saturation is the caller's responsibility — use sbl::dsp::saturate_24()
 * from <sbl/dsp/fixed.hpp> before writing to tx_buf. The SAI driver outputs
 * raw values with no implicit clamping.
 *
 * @param tx_buf  Interleaved output [L0,R0,L1,R1,...] - fill these
 * @param rx_buf  Interleaved input  [L0,R0,L1,R1,...] - read-only
 * @param frames  Number of stereo frames (= block_size from AudioConfig)
 */
using AudioCallback = void(*)(int32_t* tx_buf, const int32_t* rx_buf, uint16_t frames);
 
} // namespace audio
} // namespace hal
} // namespace sbl
 
#endif // SBL_HAL_AUDIO_TYPES_HPP_