pounder_test/src/digital_input_stamper.rs

163 lines
7.0 KiB
Rust
Raw Normal View History

///! Digital Input 0 (DI0) reference clock timestamper
///!
///! This module provides a means of timestamping the rising edges of an external reference clock on
///! the DI0 with a timer value from TIM5.
///!
///! This module only supports input clocks on DI0 and may or may not utilize DMA to collect
///! timestamps.
///!
///! # Design
///! An input capture channel is configured on DI0 and fed into TIM5's capture channel 4. TIM5 is
2020-12-08 23:14:27 +08:00
///! then run in a free-running mode with a configured tick rate (PSC) and maximum count value
///! (ARR). Whenever an edge on DI0 triggers, the current TIM5 counter value is captured and
///! recorded as a timestamp. This timestamp can be either directly read from the timer channel or
///! can be collected asynchronously via DMA collection.
///!
///! When DMA is used for timestamp collection, a DMA transfer is configured to collect as many
///! timestamps as there are samples, but it is intended that this DMA transfer should never
///! complete. Instead, when all samples are collected, the module pauses the DMA transfer and
///! checks to see how many timestamps were collected. These collected timestamps are then returned
///! for further processing.
///!
2020-12-08 23:14:27 +08:00
///! To prevent silently discarding timestamps, the TIM5 input capture over-capture flag is
///! continually checked. Any over-capture event (which indicates an overwritten timestamp) then
///! triggers a panic to indicate the dropped timestamp so that design parameters can be adjusted.
///!
///! # Tradeoffs
///! It appears that DMA transfers can take a significant amount of time to disable (400ns) if they
///! are being prematurely stopped (such is the case here). As such, for a sample batch size of 1,
///! this can take up a significant amount of the total available processing time for the samples.
///! To avoid this, the module does not use DMA when the sample batch size is one. Instead, the
///! module manually checks for any captured timestamps from the timer capture channel manually. In
///! this mode, the maximum input clock frequency supported is equal to the configured sample rate.
///!
///! There is a small window while the DMA buffers are swapped where a timestamp could potentially
///! be lost. To prevent this, the `acuire_buffer()` method should not be pre-empted. Any lost
///! timestamp will trigger an over-capture interrupt.
use super::{
hal, timers, DmaConfig, PeripheralToMemory, Transfer, SAMPLE_BUFFER_SIZE,
};
// The DMA buffers must exist in a location where DMA can access. By default, RAM uses DTCM, which
// is off-limits to the normal DMA peripheral. Instead, we use AXISRAM.
#[link_section = ".axisram.buffers"]
static mut BUF: [[u32; SAMPLE_BUFFER_SIZE]; 2] = [[0; SAMPLE_BUFFER_SIZE]; 2];
/// The timestamper for DI0 reference clock inputs.
pub struct InputStamper {
2020-12-08 00:58:36 +08:00
_di0_trigger: hal::gpio::gpioa::PA3<hal::gpio::Alternate<hal::gpio::AF2>>,
next_buffer: Option<&'static mut [u32; SAMPLE_BUFFER_SIZE]>,
transfer: Option<
Transfer<
hal::dma::dma::Stream6<hal::stm32::DMA1>,
timers::tim5::Channel4InputCapture,
PeripheralToMemory,
&'static mut [u32; SAMPLE_BUFFER_SIZE],
>,
>,
capture_channel: Option<timers::tim5::Channel4InputCapture>,
}
impl InputStamper {
/// Construct the DI0 input timestamper.
///
/// # Args
/// * `trigger` - The capture trigger input pin.
/// * `stream` - The DMA stream to use for collecting timestamps.
/// * `timer_channel - The timer channel used for capturing timestamps.
/// * `batch_size` - The number of samples collected per processing batch.
pub fn new(
2020-12-08 00:58:36 +08:00
trigger: hal::gpio::gpioa::PA3<hal::gpio::Alternate<hal::gpio::AF2>>,
2020-12-08 00:29:36 +08:00
stream: hal::dma::dma::Stream6<hal::stm32::DMA1>,
2020-12-08 00:58:36 +08:00
timer_channel: timers::tim5::Channel4,
batch_size: usize,
) -> Self {
2020-12-08 00:58:36 +08:00
// Utilize the TIM5 CH4 as an input capture channel - use TI4 (the DI0 input trigger) as the
// capture source.
2020-12-08 00:58:36 +08:00
let input_capture =
timer_channel.to_input_capture(timers::CaptureTrigger::Input24);
// For small batch sizes, the overhead of DMA can become burdensome to the point where
// timing is not met. The DMA requires 500ns overhead, whereas a direct register read only
// requires ~80ns. When batches of 2-or-greater are used, use a DMA-based approach.
let (transfer, input_capture) = if batch_size >= 2 {
input_capture.listen_dma();
// Set up the DMA transfer.
let dma_config = DmaConfig::default().memory_increment(true);
2020-12-08 23:14:27 +08:00
let timestamp_transfer: Transfer<_, _, PeripheralToMemory, _> =
Transfer::init(
stream,
input_capture,
unsafe { &mut BUF[0] },
None,
dma_config,
);
(Some(timestamp_transfer), None)
} else {
(None, Some(input_capture))
};
Self {
2020-12-08 18:29:59 +08:00
next_buffer: unsafe { Some(&mut BUF[1]) },
transfer,
capture_channel: input_capture,
_di0_trigger: trigger,
}
}
2020-12-08 23:14:27 +08:00
/// Start capture timestamps on DI0.
pub fn start(&mut self) {
if let Some(transfer) = &mut self.transfer {
transfer.start(|capture_channel| {
capture_channel.enable();
});
} else {
self.capture_channel.as_mut().unwrap().enable();
}
}
/// Get all of the timestamps that have occurred during the last processing cycle.
pub fn acquire_buffer(&mut self) -> &[u32] {
// If we are using DMA, finish the transfer and swap over buffers.
if self.transfer.is_some() {
let next_buffer = self.next_buffer.take().unwrap();
2020-12-08 23:14:27 +08:00
self.transfer.as_mut().unwrap().pause(|channel| {
if channel.check_overcapture() {
panic!("DI0 timestamp overrun");
}
});
let (prev_buffer, _, remaining_transfers) = self
.transfer
.as_mut()
.unwrap()
.next_transfer(next_buffer)
.unwrap();
let valid_count = prev_buffer.len() - remaining_transfers;
self.next_buffer.replace(prev_buffer);
// Note that we likely didn't finish the transfer, so only return the number of
// timestamps actually collected.
&self.next_buffer.as_ref().unwrap()[..valid_count]
} else {
2020-12-08 23:14:27 +08:00
if self.capture_channel.as_ref().unwrap().check_overcapture() {
panic!("DI0 timestamp overrun");
}
// If we aren't using DMA, just manually check the input capture channel for a
// timestamp.
match self.capture_channel.as_mut().unwrap().latest_capture() {
Some(stamp) => {
self.next_buffer.as_mut().unwrap()[0] = stamp;
&self.next_buffer.as_ref().unwrap()[..1]
}
None => &[],
}
}
}
}