tone_svc.h File Reference

The tone service: what core 1 runs for the phase tap each 1ms tick. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "edge_ring.h"
#include "tone.h"

Go to the source code of this file.

Data Structures
struct	tone_cmd_t
	The order from core 0. More...
struct	tone_rec_t
	A finished beep, in the TONE page's units. More...
struct	tone_status_t
	What the service reports each pass. More...
struct	tone_svc_t
	State of the tone service: the detector, the ring reader and the generations last seen. More...

Macros
#define	TONE_SVC_SYS_HZ   150000000u
	The system clock the capture is built for, and the tick it gives: one count per 4 cycles.
#define	TONE_SVC_TICK_HZ   (TONE_SVC_SYS_HZ / 4u)
#define	TONE_SVC_HOLD_NS   8000u
	The hold-off the capture applies, 8us.
#define	TONE_SVC_MARGIN_US   20u
	How far behind the present the detector is advanced.
#define	TONE_RING_WORDS   4096u
	The capture ring, in 32-bit words: 16kB, 42.7ms at 96,000 edges/s.
#define	TONE_SVC_BATCH   64u
	Edges taken in one pass.
#define	TONE_SVC_BEEPS   TONE_BEEP_QUEUE
	Beeps handed back in one pass.

Functions
void	tone_svc_init (tone_svc_t *s)
	Clear the service state.
uint64_t	tone_svc_ticks (uint64_t us)
	us microseconds after the capture started, in ticks.
size_t	tone_svc_step (tone_svc_t *s, const tone_cmd_t *cmd, const uint32_t *ring, uint32_t wr, uint64_t now, bool fifo_overrun, tone_rec_t *rec, tone_status_t *st)
	One pass.
void	tone_svc_rec (const tone_beep_t *b, tone_rec_t *r)
	A detector beep in the page's units, ticks of TONE_SVC_TICK_HZ.
void	tone_svc_cfg (const tone_cmd_t *cmd, tone_cfg_t *c)
	The detector's configuration for an order: the defaults of tone.h at the capture's tick, with the order's range, split, gap and minimum.

Detailed Description

The tone service: what core 1 runs for the phase tap each 1ms tick.

The PIO (programmable input/output) program stamps the edges of one motor phase and applies the capture's hold-off (tone.h, tone_holdoff_t); a DMA (direct memory access) channel collects its words in a ring (edge_ring.h). A pass takes the words written since the last one, feeds the detector (tone.c) with them, advances it to the present less the hold-off, and hands back the beeps it finished and a status.

Core 0 gives the service an order (tone_cmd_t) built from its set-up. A new set-up generation restarts the detector; a new capture generation also starts the ring reader again, because the DMA writes from slot 0 of a ring the counter has started over in. A pass under an order with run clear does nothing and reports not running.

The present tick. The caller passes the ticks elapsed since the capture started, from the 1MHz timer (tone_svc_ticks()); the words' own counts are exact, and this only places them among the 2^31 ticks a count repeats in. The detector is advanced no further than the present less TONE_SVC_MARGIN_US, which covers the timer's offset from the counter (about 2us), a word in the FIFO or in flight to the ring (under 1us), and the pass's own delay, so that no word stamped before the horizon is still to come.

Pure C, no SDK. Host-tested in test_tone_svc.

SPDX-License-Identifier: MIT

Macro Definition Documentation

TONE_SVC_SYS_HZ

#define TONE_SVC_SYS_HZ   150000000u

The system clock the capture is built for, and the tick it gives: one count per 4 cycles.

system clock, Hz

TONE_SVC_TICK_HZ

#define TONE_SVC_TICK_HZ   (TONE_SVC_SYS_HZ / 4u)

the capture's tick, Hz

Function Documentation

tone_svc_cfg()

void tone_svc_cfg	(	const tone_cmd_t *	cmd,
		tone_cfg_t *	c )

The detector's configuration for an order: the defaults of tone.h at the capture's tick, with the order's range, split, gap and minimum.

Parameters

cmd	Order from core 0.
c	Receives the detector settings.

tone_svc_init()

void tone_svc_init

(

tone_svc_t *

s

)

Clear the service state.

Parameters

s	Service state; cleared to zero.

tone_svc_rec()

void tone_svc_rec	(	const tone_beep_t *	b,
		tone_rec_t *	r )

A detector beep in the page's units, ticks of TONE_SVC_TICK_HZ.

Parameters

b	Beep from the detector.
r	Receives the beep in the page's units.

tone_svc_step()

size_t tone_svc_step	(	tone_svc_t *	s,
		const tone_cmd_t *	cmd,
		const uint32_t *	ring,
		uint32_t	wr,
		uint64_t	now,
		bool	fifo_overrun,
		tone_rec_t *	rec,
		tone_status_t *	st )

One pass.

ring is the capture ring (TONE_RING_WORDS words), wr the slot the DMA writes next, now the present in ticks since the capture started, fifo_overrun true when the state machine dropped a word (its FIFO was full): the words read in that pass and in the next are discarded, the beep under way ends and the status shows the overrun. The caller reads the flag before wr, so the next pass's boundary lies after the flag was cleared; words the FIFO still held at the drop reach the ring before that boundary unless the DMA stalls for a whole pass, 1ms, and a stall that long overflows the FIFO again. The beeps finished go to rec, at most TONE_SVC_BEEPS; the count is returned. st is always written.

Parameters

s	Service state.
cmd	Order from core 0.
ring	Capture ring, TONE_RING_WORDS words.
wr	Slot the DMA writes next.
now	Present, in ticks since the capture started.
fifo_overrun	true when the state machine dropped a word.
rec	Receives the finished beeps; NULL to take none.
st	Receives the status; always written.

Returns

Number of beeps written to rec.

tone_svc_ticks()

uint64_t tone_svc_ticks

(

uint64_t

us

)

us microseconds after the capture started, in ticks.

Parameters

us	Time, microseconds.

Returns

Ticks of the capture's clock.