The phase tap's capture: one PIO (programmable input/output) state machine on one input pin (tone_cap.pio) and a DMA (direct memory access) channel that collects its words in a ring of TONE_RING_WORDS words, endlessly, with the write address wrapping on the ring. More...

#include <stdbool.h>
#include <stdint.h>

Functions
bool	tone_cap_start (uint8_t pin)
	Claim a state machine and a DMA channel, load the program, start the capture on `pin`.
bool	tone_cap_pause (void)
	Mark the capture not running, so the next order tells core 1 to read nothing from it; the state machine and the channel stay, and tone_cap_wr() and tone_cap_stalled() still read them for a pass already under way.
void	tone_cap_resume (void)
	Mark a paused capture running again, when core 1 did not acknowledge the pause and nothing was taken down.
void	tone_cap_stop (void)
	Stop the capture and give back what it claimed; the pin is left an input with its pull-down on.
bool	tone_cap_running (void)
	Whether the capture runs.
uint64_t	tone_cap_start_us (void)
	The microsecond timer when the counter began.
void	tone_cap_rest (uint8_t pin)
	The pin as an input with its pull-down on, driven by nothing: a tap that is off.
const uint32_t *	tone_cap_ring (void)
	The ring.
uint32_t	tone_cap_wr (void)
	The slot the DMA writes next; 0 when the capture does not run.
bool	tone_cap_stalled (void)
	Whether the state machine dropped a word (its FIFO was full) since the last call; clears the flag.

Detailed Description

The phase tap's capture: one PIO (programmable input/output) state machine on one input pin (tone_cap.pio) and a DMA (direct memory access) channel that collects its words in a ring of TONE_RING_WORDS words, endlessly, with the write address wrapping on the ring.

Core 0 starts and stops it. Core 1 reads the ring and the channel's write position, with tone_svc_step() or a reader of its own, and the state machine's overflow flag. The ring is cleared when the capture starts. Nothing here drives the pin: it is an input for the PIO, and an input with its pull-down on while the tap is off.

Pull-down. The pin's pull-down is on while the tap is disabled, so a tap wire connected to nothing reads low, and stays on while the tap runs: against the series resistor of 4.7kOhm on the phase it divides a floating 3.7V phase to 3.2V or more, over the input's 2.0V threshold.

Time. The counter starts at 0 when the state machine is enabled. tone_cap_start_us() is the microsecond timer at that instant, to about 1us: the present tick is the timer less this, 37.5 ticks a microsecond (tone_svc_ticks()). The image is built for the 150MHz system clock; the capture is refused at any other.

SPDX-License-Identifier: MIT

Function Documentation

◆ tone_cap_pause()

bool tone_cap_pause ( void )

Mark the capture not running, so the next order tells core 1 to read nothing from it; the state machine and the channel stay, and tone_cap_wr() and tone_cap_stalled() still read them for a pass already under way.

True when it was running. The first step of taking the capture down: tell core 1, wait for it to acknowledge, then tone_cap_stop().

Returns: true when it was running.

◆ tone_cap_rest()

void tone_cap_rest ( uint8_t pin )

The pin as an input with its pull-down on, driven by nothing: a tap that is off.

Not while the capture runs.

Parameters

pin	GPIO number of the phase input.

◆ tone_cap_ring()

const uint32_t * tone_cap_ring ( void )

The ring.

Returns: The ring of edge words.

◆ tone_cap_running()

bool tone_cap_running ( void )

Whether the capture runs.

Returns: true while the capture runs.

◆ tone_cap_stalled()

bool tone_cap_stalled ( void )

Whether the state machine dropped a word (its FIFO was full) since the last call; clears the flag.

Called from core 1 only.

Returns: true when a word was dropped since the last call.

◆ tone_cap_start()

bool tone_cap_start ( uint8_t pin )

Claim a state machine and a DMA channel, load the program, start the capture on pin.

False, with nothing claimed, when no PIO block that reaches the pin has room for the program and a state machine, no DMA channel is free, or the system clock is not 150MHz.

Parameters

pin	GPIO number of the phase input.

Returns: true when the capture runs.

◆ tone_cap_start_us()

uint64_t tone_cap_start_us ( void )

The microsecond timer when the counter began.

Returns: The microsecond timer value when the counter began.

◆ tone_cap_stop()

void tone_cap_stop ( void )

Stop the capture and give back what it claimed; the pin is left an input with its pull-down on.

Safe when it is not running. Core 1 is not reading the ring or the channel at that moment (tone_cap_pause()).

◆ tone_cap_wr()

uint32_t tone_cap_wr ( void )

The slot the DMA writes next; 0 when the capture does not run.

Returns: The slot the DMA writes next, 0 when the capture does not run.

Functions