Adding documentation, updating DAC output timing

[ryan-summers]

This PR adds extensive documentation to the asynchronous IO modules on stabilizer. This fixes #171

This PR also updates the DAC codes so that DAC + ADC batches are always synchronous (DAC codes are exactly 2 batches after the ADC sample that generated them). In this implementation, DAC batches are always delayed by exactly 1 additional batch size from the original ADC sample batch that generated them.

There are thus two DAC batches with fixed output-zero codes at the very start of stabilizer processing.

This PR fixes #185

TODO:

• Verify timing on stabilizer hardware
• Investigate updating DAC DMA to use DBM to prevent potential sample loss

[jordens]

Pretty sure the delay is two batches, not one. You'd measure from first sample of an ADC batch to (corresponding) first sample of a DAC batch.

[jordens]

We should do that by default. The risk of having the sequence of ADC0/1 winning the bus arbitration race change between samples is worse than the constant skew.

[ryan-summers]

The ADC0/ADC1 never race for the bus because of natural priority of the DMA transfers (since they are using the same DMA peripheral). This means the DMA peripheral arbitrates between ADC0 and ADC1 internally in a deterministic manner.

[irwineffect]

How might we be able to calculate this latency?

[ryan-summers]

The latency is 1 bus matrix clock. However, since the bus might be used by for example the CPU, it might get delayed further. Because this latency is in the range of a handful of AXI bus clocks, that's what I used the phrase "a very small amount"

[ryan-summers]

Essentially, the latency is not deterministic, hence why it's not clearly specified here

[irwineffect]

Could we specify some sort of worst case number? This allows someone to make the determination of "I don't care about this latency".

[irwineffect]

How much latency? We describe it in terms of "timer ticks" below, but nano- or microseconds would also be nice.

[ryan-summers]

This is the same as with the ADCs. It's actually an undeterministic number of AXI bus cycles, hence why it's unspecified.

[irwineffect]

Something that is implied but not plainly explained is how the ADC/DAC constraints sum up to create the constraints of the DSP application code. Something like:

Processing time for the DSP application code is bounded by the following constraints:

DSP application code starts after the ADC has generated a batch of samples, and must be completed by the time the next batch of ADC samples has been acquired (plus the FIFO buffer time). If this constraint is not met, <what will happen?>.

The DSP application code must also fill out the next DAC output buffer in time such that the DAC can switch to it when it has completed the current buffer. If this constraint is not met <what will happen?>

Because the ADC and DAC operate at the same rate, these two constraints actually implement the same time bounds, meeting one also means the other is also met.

How will the end user know that their DSP application code meets these constraints? Once this code is stabilized I imagine that we can provide equations to estimate how much time the DSP application has based on parameters like sampling rate and batch size.

Will we eventually have some sort of burden reporting mechanism so the end user can test code and see how much more they can add before hitting one of the limits?

[irwineffect]

Concerning my burden question, it seems like #166 might address it?

[ryan-summers]

@irwineffect I've added the blurb you provided to describe the DSP timing constraints - thanks for writing it up. In regard to knowing whether an application is meeting timing:

The ADC inputs listen for an overrun on the SPI peripheral, which generates an interrupt that panics. Thus, if timing is not met, the firmware will panic and make it obvious to the end user that timing is not being met. Ultimately, #166 will also aid with this as you point out.

[irwineffect]

Could we specify some sort of worst case number? This allows someone to make the determination of "I don't care about this latency".

[ryan-summers]

Timing for batch sizes > 1 was verified. It was found that batch_size = 1 results in an extra batch delay from input -> output, and I haven't been able to figure out the cause. I spawned an issue in #229 so we can track it as necessary.