# Sampling Module Design Datasheet

TODO this should be generated by the gateware build infrastructure

TODO there is also potential to make samples 9 bits, which would take the same
number of EBR resources as 8 bits, it would make the packets larger, but I don't
think that's a major concern. I am thinking we should do 9 bits. It won't slow
down any of our operations, as it goes from byte sized loads to half word loads,
which are all single instructions anyways

## Operation

When the ADCs are enabled (via CCR->ENABLE), then the data FIFOs are
continuously updated with incoming samples. The user can start (CCR->START)
a new capture, which primes the block to save the appropriate samples.
A capture does not happen until it is triggered, which can be done either
automatically (iff CCR->AUTO_TRG_EN is set to 1), or via manual software trigger
(via CCR->TRIGGER). The samples are configured with 2 parameters: CAP_OFFSET, and CAP_LEN.
CAP_OFFSET determines how many samples prior to the trigger will be saved, and CAP_LEN
determines the total number of samples to save.

The sample received on the clock that the trigger will be the (0-indexed) CAP_OFFSET'th sample
in the total capture. (TODO better description for that)

*Note: a capture can not be triggered unless the SR->READY flag is set. The READY
flag is set by the following logic: `CCR->ENABLE && CCR->START && samples_saved >= CACHED_CAP_OFFSET`.*

### Automatic Triggering and Peak Detection

Each acquisition unit has its own peak detector in. This measures the difference
between the maximum and minimum values read within 3/4 of a cycle. The time of a
cycle is determined by the frequency set via CCR->FREQ. This value can be read
via PP_VALUE_X (X being the ADC number).

This value can be manually read by software for each channel to do gain
adjustments or peak detection in software if wanted, however this value can also
be used to trigger automatically. The automatic trigger occurs as soon as this value
is greater than or equal to the value set in CCR->PP_THRESH.

### Interrupts

An external interrupt will be sent to the CPU by this module for both the
trigger event and the acquisition complete event. It will be two different
lines, maskable by the RISCV mie CSR. TBD is how to reset them or if that needs
to happen or whatever.

## Registers

32 bits unless specified otherwise. Fields not specified will always read 0 and writes will do nothing

Shared across all acquisition blocks, except for PP_VALUE_X, and DATA_X which both have one register per ADC.

### CCR (R/W)

Configuration and Control Register

Default value: 0 for all fields

| Field          | Bit Width | Description |
|----------------|-----------|-------------|
| ENABLE         | 1         | Enables/Disables the ADC itself. Also starts pulling data into FIFO |
| START          | 1         | Set this bit to prime a capture. Locks in all offset and frequency settings (sets when not enabled and ready will do nothing, sets with an ongoing trigger re-load new settings, start trigger anew, clear to stop capture), value when read will be if a trigger is active |
| TRIGGER        | 1         | Manually trigger a capture. Will always read 0 |
| AUTO_TRG_EN    | 1         | Enables 
| FREQ           | 2         | Sets the frequency the ping detector submodule uses. (See FREQ_ENUM) |
| PP_THRESH      | 10        | Full scale peak to peak threshold to auto trigger a capture.  |


FREQ_ENUM:
- 0b00: 25kHz
- 0b01: 30kHz
- 0b10: 35kHz
- 0b11: 40kHz

### SR (R/O)

Status Register

This will have 4 sets of fields of status bits, one per ADC

| Field          | Bit Width | Description |
|----------------|-----------|-------------|
| READY          | 1         | FIFO has acquired enough samples to hold requested history. |
| TRIGGERED      | 1         | Capture has been triggered. Cleared on next START |
| COMPLETE       | 1         | Capture is finished, cleared on next START |
| TBD status bits| TBD       | Any status lines we get from the ADC will be exported here |

### CAP_OFFSET

32-bit field that determines how many samples to acquire from before the trigger. Must be < CAP_LEN - 10
(max value enforced by hardware)

### CAP_LEN

32-bit field that determines how many samples total to acquire for the whole trigger. Must be < size of FIFO
(max size enforced by hardware)

### PP_VALUE_X

One register per acquisition block

10-bit field with the highest measured peak-to-peak values

Write anything to reset to 0

Gets reset to 0 when a new capture is started (note: not when it is triggered)

### DATA_X

8-bit register (otherwise just 0s), returns the top 8 bits of each sample.
(maybe not the top, depending on scale/range, but that can be changed later).
All other bits are 0.

Reading this register before a trigger occurs is invalid.

Reading a byte consumes the byte from the FIFO, user is expected to track the correct
number of bytes to read, reading over the end of the FIFO is invalid.

All invalid reads return 0. (Real data should never be 0, so this is a good indicator.)

## Interrupts

Since all of these should have the same timing offsets, these interrupts are common to all acquisition blocks.

Trigger
Capture complete
