scan.hpp

Go to the documentation of this file.

/**
 * @file scan.hpp
 * @brief ADC DMA scan interface — continuous multi-channel acquisition
 * @ingroup hal
 *
 * Platform-agnostic interface for DMA-based ADC scanning. The driver
 * handles all DMA configuration internally; the HAL just forwards calls.
 *
 * Usage:
 *   #include <sbl/hw/hal/adc/scan.hpp>
 *
 *   SBL_DMA_BUFFER static volatile uint16_t adc_buf[2];
 *   const sbl::AdcHandle channels[] = { sbl::hw::adc::knob1, sbl::hw::adc::knob2 };
 *   sbl::adc::start_scan<sbl::driver::Adc>(channels, 2, adc_buf);
 *
 *   // Main loop: just read adc_buf[0], adc_buf[1] — always fresh
 */
 
#ifndef SBL_HW_HAL_ADC_SCAN_HPP_
#define SBL_HW_HAL_ADC_SCAN_HPP_
 
#include "handle.hpp"
#include "types.hpp"
 
namespace sbl {
namespace adc {
 
using SampleTime = sbl::hal::adc::SampleTime;
 
/**
 * @brief Start continuous DMA scan of multiple ADC channels
 *
 * The ADC scans all channels in sequence with circular DMA, depositing
 * results into buffer[0..num_channels-1]. The CPU reads the buffer at
 * any time for the latest value — no synchronization needed (16-bit
 * aligned reads are atomic on Cortex-M).
 *
 * @tparam Driver ADC driver type (e.g., sbl::driver::Adc)
 * @param channels     Array of AdcHandle defining the scan sequence
 * @param num_channels Number of channels to scan (1–16)
 * @param buffer       DMA-accessible buffer with num_channels elements
 * @param sample_time  Sampling duration for all channels (default: Slow)
 *
 * @note Not ISR-safe — init-time only (configures ADC + DMA hardware)
 */
template<typename Driver>
inline void start_scan(const AdcHandle* channels, uint8_t num_channels,
                       uint16_t* buffer,
                       SampleTime sample_time = SampleTime::Slow) {
    Driver::start_dma_scan(channels, num_channels, buffer, sample_time);
}
 
/**
 * @brief Start continuous DMA scan with per-channel sample times
 *
 * Allows different sample times per channel — use SampleTime::Slow for
 * high-impedance pot sources and SampleTime::Medium or Fast for buffered
 * CV jack inputs.
 *
 * @tparam Driver ADC driver type (e.g., sbl::driver::Adc)
 * @param channels      Array of AdcHandle defining the scan sequence
 * @param num_channels  Number of channels to scan (1–16)
 * @param buffer        DMA-accessible buffer with num_channels elements
 * @param sample_times  Per-channel sampling durations (array of num_channels)
 *
 * @note Not ISR-safe — init-time only (configures ADC + DMA hardware)
 */
template<typename Driver>
inline void start_scan(const AdcHandle* channels, uint8_t num_channels,
                       uint16_t* buffer,
                       const SampleTime* sample_times) {
    Driver::start_dma_scan(channels, num_channels, buffer, sample_times);
}
 
/**
 * @brief Stop DMA scan mode
 *
 * Stops continuous conversion and disables DMA. After this call,
 * polling functions (read<Driver>()) can be used again.
 *
 * @tparam Driver ADC driver type
 *
 * @note Not ISR-safe — tears down DMA and ADC hardware
 */
template<typename Driver>
inline void stop_scan() {
    Driver::stop_dma_scan();
}
 
} // namespace adc
} // namespace sbl
 
#endif // SBL_HW_HAL_ADC_SCAN_HPP_