The panel's half of the TONE link page. More...

#include "tone_link.h"
#include <stddef.h>
#include <string.h>
#include "link_msg.h"

Macros
#define	FRAME_N 4u
#define	FRAME0_AT ((uint8_t)LINK_TN_ENABLE)
#define	FRAME1_AT ((uint8_t)LINK_TN_SPLIT_PCT)
#define	FRAME1_CFG (LINK_TN_CONFIG_COUNT - (unsigned)LINK_TN_SPLIT_PCT)
#define	CYCLE 65535u
#define	ST(reg)
#define	RESTART_BEHIND 1024u

Functions
static unsigned	pos_of (uint16_t n)
	The position of a beep number in the ring.
static uint16_t	num_of (unsigned pos)
	The beep number at a position in the ring.
static uint16_t	succ_of (uint16_t n)
	The number after `n`, and the one before.
static uint16_t	pred_of (uint16_t n)
	The number before a beep.
static unsigned	dist (uint16_t from, uint16_t to)
	Beeps from `from`, the last one taken, to `to`, the newest.
void	tone_link_init (tone_link_t *t)
	Sets up the tone link state.
void	tone_link_lost (tone_link_t *t)
	The link went: nothing on the page is known, and nothing is read or written until it comes up again.
void	tone_link_came_up (tone_link_t *t, uint16_t minor, uint32_t now_ms)
	An IOmcu answered with protocol minor `minor`.
static bool	setup_valid (const tone_setup_t *w)
	Whether `w` is a set-up SETUP can name: every value inside the page's own range.
void	tone_link_want (tone_link_t t, const tone_setup_t w, uint32_t now_ms)
	The set-up SETUP names now.
static bool	pair_valid (unsigned f_min, unsigned f_max, unsigned gap_ms)
	Whether a tone range and a gap are a set-up the page takes: the high tone above the low one, and a silence at least one period of the low tone long.
static bool	frame0_differs (const tone_link_t *t)
	Whether the wanted first frame differs from the held one.
static bool	frame1_differs (const tone_link_t *t)
	Whether the wanted second frame differs from the held one.
static bool	pin_retry_due (const tone_link_t *t, uint32_t now_ms)
	Whether the first frame is owed again for a pin something else holds: the page's FLAGS say the saved tap met a busy pin at boot, the page holds what is asked, and TONE_LINK_RETRY_MS have passed since the last try.
static tone_link_op_kind_t	write_owed (const tone_link_t t, uint16_t regs, bool retry)
	The write owed now, or NONE, with its registers in `regs`.
static void	read_op (tone_link_op_t *op, tone_link_op_kind_t kind, uint8_t off, uint8_t n)
	Sets up a read operation of the TONE page.
static unsigned	owed (const tone_link_t *t)
	Beeps the page has that the panel has not taken, by the last status.
bool	tone_link_next (tone_link_t t, uint32_t now_ms, tone_link_op_t op)
	The next exchange owed at `now_ms`, into `op`; false for none.
static bool	may_pass_later (const tone_link_t *t, int result)
	Whether a first frame refused with `result` may pass later, unchanged: the page said its pin is busy.
static void	written (tone_link_t *t, tone_link_op_kind_t w, int result, uint32_t now_ms)
	Handles the result of a write.
static void	judge_status (tone_link_t *t)
	What a status read says that the operator is told: a pin that is not free and an overrun, each on its edge.
static void	note_window (tone_link_t *t, uint32_t now_ms)
	When WINDOW last moved, after a status read.
static void	follow_head (tone_link_t *t)
	Where the panel stands against BEEP_HEAD after a status read.
static void	take_beep (tone_link_t t, const uint16_t r)
	Takes the beep a read holds into the panel's history.
void	tone_link_done (tone_link_t t, int result, const uint16_t regs, uint32_t now_ms)
	How the exchange tone_link_next() gave went: TONE_LINK_ACK with the registers read (`regs`, op.n of them; NULL for a write), a NACK reason, or TONE_LINK_NO_ANSWER.
bool	tone_link_event_stands (const tone_link_t *t, uint16_t ev)
	Whether what `ev`, one TONE_LINK_EV_* bit, says still holds now.
uint16_t	tone_link_event (tone_link_t *t, uint32_t now_ms)
	One event for the alert band, which shows one line and replaces it with the next: the most pressing waiting, cleared, and the rest kept.
void	tone_link_event_back (tone_link_t *t, uint16_t ev)
	Put back an event tone_link_event() handed out that never reached the band, so it is handed out again after the gap.
bool	tone_link_settled (const tone_link_t *t)
	Whether nothing is owed: the page holds the set-up asked, less the frames it refused.
uint8_t	tone_link_unheld (const tone_link_t *t)
	The frames whose values as asked are not the ones the page holds, TONE_LINK_ROWS_*: not written yet, or refused.
unsigned	tone_link_beeps (const tone_link_t t, tone_beep_t out, unsigned max)
	The beeps the panel has read, newest first, at most `max`; how many.
uint32_t	tone_link_read_count (const tone_link_t *t)
	Beeps read since init, and beeps the panel did not read: the ring moved past them, or the page no longer held them.
uint32_t	tone_link_missed (const tone_link_t *t)
	Counts the beeps the panel did not read.
uint16_t	tone_link_flags (const tone_link_t *t)
	FLAGS as last read, 0 before any read.
static tone_state_t	state_of (const tone_link_t t, bool fresh, bool read)
	What the tap is doing, as the screen words it; `fresh` says the last status read is recent enough to speak for the page.
void	tone_link_readout (const tone_link_t t, uint32_t now_ms, tone_readout_t r)
	The screen's copy of everything above, at `now_ms`.
unsigned	tone_link_pin (const tone_link_t *t)
	The pin and the tone range asked, for the alerts' text.
unsigned	tone_link_f_min (const tone_link_t *t)
	The lower end of the tone range asked, for the alerts' text.
unsigned	tone_link_f_max (const tone_link_t *t)
	The upper end of the tone range asked, for the alerts' text.
bool	tone_link_held_pin (const tone_link_t t, int pin)
	The tap's pin the page holds by its last read or write, as the IOmcu reserves it (tone_page_pins()): the pin while ENABLE has the tap on and the last status read does not say the pin refused, -1 otherwise and while the IOmcu has no TONE page.

Detailed Description

The panel's half of the TONE link page.

See tone_link.h.

SPDX-License-Identifier: MIT

Macro Definition Documentation

◆ ST

#define ST ( reg )

Value:

((unsigned)(reg) - (unsigned)LINK_TN_FLAGS)

LINK_TN_FLAGS

@ LINK_TN_FLAGS

Definition link_pages.h:1221

Function Documentation

◆ dist()

unsigned dist	(	uint16_t	from,
		uint16_t	to )

static

Beeps from from, the last one taken, to to, the newest.

Parameters

from	The last beep taken.
to	The newest beep.

Returns: The number of beeps from from to to.

◆ follow_head()

void follow_head ( tone_link_t * t )

static

Where the panel stands against BEEP_HEAD after a status read.

Parameters

t	The link state.

◆ frame0_differs()

bool frame0_differs ( const tone_link_t * t )

static

Whether the wanted first frame differs from the held one.

Parameters

t	The link state.

Returns: true when they differ.

◆ frame1_differs()

bool frame1_differs ( const tone_link_t * t )

static

Whether the wanted second frame differs from the held one.

Parameters

t	The link state.

Returns: true when they differ.

◆ judge_status()

void judge_status ( tone_link_t * t )

static

What a status read says that the operator is told: a pin that is not free and an overrun, each on its edge.

Parameters

t	The link state.

◆ may_pass_later()

bool may_pass_later	(	const tone_link_t *	t,
		int	result )

static

Whether a first frame refused with result may pass later, unchanged: the page said its pin is busy.

A 4.17 page says BUSY for that and BAD_VALUE for a set-up no freed pin makes good. An older page says BAD_VALUE for both, so its refusal may pass later unless the panel sees the frame's own values fail: a high tone not above the low one, or the gap held too short for the low tone.

Parameters

t	The link state.
result	The NACK reason.

Returns: true when it may pass later.

◆ note_window()

void note_window	(	tone_link_t *	t,
		uint32_t	now_ms )

static

When WINDOW last moved, after a status read.

A page that does not run reads WINDOW 0 and is not judged by it: each such read counts as a move, so a capture that starts has TONE_LINK_WINDOW_STALE_MS from the last read that found it not running to show its first window.

Parameters

t	The link state.
now_ms	The time, in ms.

◆ num_of()

uint16_t num_of ( unsigned pos )

static

The beep number at a position in the ring.

Parameters

pos	The position.

Returns: The beep number; CYCLE for position 0.

◆ owed()

unsigned owed ( const tone_link_t * t )

static

Beeps the page has that the panel has not taken, by the last status.

Parameters

t	The link state.

Returns: The number of beeps owed.

◆ pair_valid()

bool pair_valid	(	unsigned	f_min,
		unsigned	f_max,
		unsigned	gap_ms )

static

Whether a tone range and a gap are a set-up the page takes: the high tone above the low one, and a silence at least one period of the low tone long.

Parameters

f_min	The low tone, in Hz.
f_max	The high tone, in Hz.
gap_ms	The silence, in ms.

Returns: true when the page takes the pair.

◆ pin_retry_due()

bool pin_retry_due	(	const tone_link_t *	t,
		uint32_t	now_ms )

static

Whether the first frame is owed again for a pin something else holds: the page's FLAGS say the saved tap met a busy pin at boot, the page holds what is asked, and TONE_LINK_RETRY_MS have passed since the last try.

Parameters

t	The link state.
now_ms	The time, in ms.

Returns: true when it is owed now.

◆ pos_of()

unsigned pos_of ( uint16_t n )

static

The position of a beep number in the ring.

Parameters

n	The beep number.

Returns: n modulo CYCLE.

◆ pred_of()

uint16_t pred_of ( uint16_t n )

static

The number before a beep.

Parameters

n	The beep number.

Returns: The beep number before n.

◆ read_op()

void read_op	(	tone_link_op_t *	op,
		tone_link_op_kind_t	kind,
		uint8_t	off,
		uint8_t	n )

static

Sets up a read operation of the TONE page.

Parameters

op	Receives the operation.
kind	The operation kind.
off	The first register.
n	The number of registers.

◆ setup_valid()

bool setup_valid ( const tone_setup_t * w )

static

Whether w is a set-up SETUP can name: every value inside the page's own range.

A zeroed one – a snapshot nobody has published into – is not, and is no reason to write anything. F_MAX_HZ above F_MIN_HZ and a GAP_MS as long as F_MIN_HZ's period are for the page to judge.

Parameters

w	The set-up.

Returns: true when every value is inside the page's range.

◆ state_of()

tone_state_t state_of	(	const tone_link_t *	t,
		bool	fresh,
		bool *	read )

static

What the tap is doing, as the screen words it; fresh says the last status read is recent enough to speak for the page.

read, false on the call, is set when the state is the one that read gives, so its values are current.

Parameters

t	The link state.
fresh	true when the last status read is recent enough to speak for the page.
read	Set when the state comes from the page read; false on entry.

Returns: The tap state.

◆ succ_of()

uint16_t succ_of ( uint16_t n )

static

The number after n, and the one before.

Parameters

n	The beep number.

Returns: The beep number after n.

◆ take_beep()

void take_beep	(	tone_link_t *	t,
		const uint16_t *	r )

static

Takes the beep a read holds into the panel's history.

Parameters

t	The link state.
r	The registers read.

◆ tone_link_beeps()

unsigned tone_link_beeps	(	const tone_link_t *	t,
		tone_beep_t *	out,
		unsigned	max )

The beeps the panel has read, newest first, at most max; how many.

Parameters

t	The link state.
out	Receives the beeps, newest first.
max	The number of entries out holds.

Returns: The number of beeps written to out.

◆ tone_link_came_up()

void tone_link_came_up	(	tone_link_t *	t,
		uint16_t	minor,
		uint32_t	now_ms )

An IOmcu answered with protocol minor minor.

Below TONE_LINK_MINOR it has no page and nothing is sent to it, and the tap enabled on SETUP raises TONE_LINK_EV_NO_PAGE.

Parameters

t	The link state.
minor	The IOmcu's protocol minor version.
now_ms	The time, in ms.

◆ tone_link_done()

void tone_link_done	(	tone_link_t *	t,
		int	result,
		const uint16_t *	regs,
		uint32_t	now_ms )

How the exchange tone_link_next() gave went: TONE_LINK_ACK with the registers read (regs, op.n of them; NULL for a write), a NACK reason, or TONE_LINK_NO_ANSWER.

Parameters

t	The link state.
result	The result: an acknowledgement, a NACK's reason or TONE_LINK_NO_ANSWER.
regs	The registers read, or NULL for a write.
now_ms	The time, in ms.

◆ tone_link_event()

uint16_t tone_link_event	(	tone_link_t *	t,
		uint32_t	now_ms )

One event for the alert band, which shows one line and replaces it with the next: the most pressing waiting, cleared, and the rest kept.

0 while none waits or while the last one handed out is younger than TONE_LINK_EVENT_GAP_MS at now_ms.

Parameters

t	The link state.
now_ms	The time, in ms.

Returns: The event bit for the alert band, or 0 for none.

◆ tone_link_event_back()

void tone_link_event_back	(	tone_link_t *	t,
		uint16_t	ev )

Put back an event tone_link_event() handed out that never reached the band, so it is handed out again after the gap.

An event about an IOmcu is not put back once the link has gone.

Parameters

t	The link state.
ev	The event to put back.

◆ tone_link_event_stands()

bool tone_link_event_stands	(	const tone_link_t *	t,
		uint16_t	ev )

Whether what ev, one TONE_LINK_EV_* bit, says still holds now.

A refused frame – TONE_LINK_EV_PIN_REFUSED for the first, TONE_LINK_EV_SETUP_REFUSED for the second – until the page is known to hold that frame as asked: not refused, and written and taken. A value stepped back on SETUP ends it once the IOmcu takes the frame, after TONE_LINK_SETTLE_MS and a poll. TONE_LINK_EV_PIN_BUSY until the tap is off as asked and held, or a status read under the first frame as asked shows its pin taken (FLAGS bit 1 clear). With no IOmcu answering they stand. True for every other event.

The caller takes back an alert it showed for such an event once this is false; tone_link_event() drops one waiting that is over.

Parameters

t	The link state.
ev	One TONE_LINK_EV_* bit.

Returns: true while the cause of the event holds.

◆ tone_link_f_max()

unsigned tone_link_f_max ( const tone_link_t * t )

The upper end of the tone range asked, for the alerts' text.

Parameters

t	The link state.

Returns: The upper end of the tone range asked.

◆ tone_link_f_min()

unsigned tone_link_f_min ( const tone_link_t * t )

The lower end of the tone range asked, for the alerts' text.

Parameters

t	The link state.

Returns: The lower end of the tone range asked.

◆ tone_link_flags()

uint16_t tone_link_flags ( const tone_link_t * t )

FLAGS as last read, 0 before any read.

Parameters

t	The link state.

Returns: FLAGS as last read.

◆ tone_link_held_pin()

bool tone_link_held_pin	(	const tone_link_t *	t,
		int *	pin )

The tap's pin the page holds by its last read or write, as the IOmcu reserves it (tone_page_pins()): the pin while ENABLE has the tap on and the last status read does not say the pin refused, -1 otherwise and while the IOmcu has no TONE page.

False, -1, while that is not known: no link, or no read yet. pin may be NULL.

Parameters

t	The link state.
pin	Receives the pin, or -1 while not known; may be NULL.

Returns: true when the pin is known.

◆ tone_link_init()

void tone_link_init ( tone_link_t * t )

Sets up the tone link state.

Parameters

t	The link state to set up.

◆ tone_link_lost()

void tone_link_lost ( tone_link_t * t )

The link went: nothing on the page is known, and nothing is read or written until it comes up again.

The beep history stays on screen.

Parameters

t	The link state.

◆ tone_link_missed()

uint32_t tone_link_missed ( const tone_link_t * t )

Counts the beeps the panel did not read.

Parameters

t	The link state.

Returns: The beeps missed since init.

◆ tone_link_next()

bool tone_link_next	(	tone_link_t *	t,
		uint32_t	now_ms,
		tone_link_op_t *	op )

The next exchange owed at now_ms, into op; false for none.

The caller makes the exchange and reports with tone_link_done().

Parameters

t	The link state.
now_ms	The time, in ms.
op	Receives the exchange owed.

Returns: true when an exchange is owed.

◆ tone_link_pin()

unsigned tone_link_pin ( const tone_link_t * t )

The pin and the tone range asked, for the alerts' text.

Parameters

t	The link state.

Returns: The tap's pin asked.

◆ tone_link_read_count()

uint32_t tone_link_read_count ( const tone_link_t * t )

Beeps read since init, and beeps the panel did not read: the ring moved past them, or the page no longer held them.

Parameters

t	The link state.

Returns: The beeps read since init.

◆ tone_link_readout()

void tone_link_readout	(	const tone_link_t *	t,
		uint32_t	now_ms,
		tone_readout_t *	r )

The screen's copy of everything above, at now_ms.

The status's values are filled only while tone_readout_t.read holds; the beeps and the missed count are the panel's own and stay.

Parameters

t	The link state.
now_ms	The time, in ms.
r	Receives the copy.

◆ tone_link_settled()

bool tone_link_settled ( const tone_link_t * t )

Whether nothing is owed: the page holds the set-up asked, less the frames it refused.

Parameters

t	The link state.

Returns: true when nothing is owed.

◆ tone_link_unheld()

uint8_t tone_link_unheld ( const tone_link_t * t )

The frames whose values as asked are not the ones the page holds, TONE_LINK_ROWS_*: not written yet, or refused.

The comparison is want against held, the two this module writes from. 0 while no IOmcu answers and before the page has been read. An IOmcu without the page holds no tap, and a tap that is on is named.

Parameters

t	The link state.

Returns: The frames not held as asked, as a TONE_LINK_ROWS_* value.

◆ tone_link_want()

void tone_link_want	(	tone_link_t *	t,
		const tone_setup_t *	w,
		uint32_t	now_ms )

The set-up SETUP names now.

The tap enabled while an IOmcu without the page answers raises TONE_LINK_EV_NO_PAGE. A set-up with a value outside the page's range – a zeroed snapshot – is ignored: nothing is asked, and nothing is written for it.

Parameters

t	The link state.
w	The set-up SETUP names.
now_ms	The time, in ms.

◆ write_owed()

tone_link_op_kind_t write_owed	(	const tone_link_t *	t,
		uint16_t *	regs,
		bool	retry )

static

The write owed now, or NONE, with its registers in regs.

retry counts a first frame owed again for a busy pin.

Parameters

t	The link state.
regs	Receives the registers of the write.
retry	true to count a first frame owed again for a busy pin.

Returns: The write owed, or TONE_LINK_OP_NONE.

◆ written()

void written	(	tone_link_t *	t,
		tone_link_op_kind_t	w,
		int	result,
		uint32_t	now_ms )

static

Handles the result of a write.

Parameters

t	The link state.
w	The write.
result	The result: an acknowledgement, a NACK reason or no answer.
now_ms	The time, in ms.

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ ST

Function Documentation

◆ dist()

◆ follow_head()

◆ frame0_differs()

◆ frame1_differs()

◆ judge_status()

◆ may_pass_later()

◆ note_window()

◆ num_of()

◆ owed()

◆ pair_valid()

◆ pin_retry_due()

◆ pos_of()

◆ pred_of()

◆ read_op()

◆ setup_valid()

◆ state_of()

◆ succ_of()

◆ take_beep()

◆ tone_link_beeps()

◆ tone_link_came_up()

◆ tone_link_done()

◆ tone_link_event()

◆ tone_link_event_back()

◆ tone_link_event_stands()

◆ tone_link_f_max()

◆ tone_link_f_min()

◆ tone_link_flags()

◆ tone_link_held_pin()

◆ tone_link_init()

◆ tone_link_lost()

◆ tone_link_missed()

◆ tone_link_next()

◆ tone_link_pin()

◆ tone_link_read_count()

◆ tone_link_readout()

◆ tone_link_settled()

◆ tone_link_unheld()

◆ tone_link_want()

◆ write_owed()

◆ written()