The TONE link page. More...

#include "tone_page.h"
#include <string.h>
#include "link_msg.h"

Macros
#define	SEQ_PERIOD 65535u
	The beep numbers: 1 to 65535, then 1 again.

Functions
void	tone_page_defaults (uint16_t *cfg)
	The set-up as a page starts, into `cfg` (LINK_TN_CONFIG_COUNT registers): the tap off, GP22, 400 to 6500Hz, 8%, 3ms, 3 periods.
void	tone_page_init (tone_page_t *p)
	Set the page to its start: the defaults, and the first beep number 1.
bool	tone_page_enabled (const tone_page_t *p)
	Whether ENABLE bit 0 (the tap) is set.
uint8_t	tone_page_pin (const tone_page_t *p)
	The configured pin, from register LINK_TN_PIN.
bool	tone_page_wanted (const tone_page_t *p)
	Whether the capture is to run: enabled and not refused.
uint64_t	tone_page_pins (const tone_page_t *p)
	The pin as a reservation mask; 0 unless the capture is wanted.
static bool	adc_pin (uint16_t pin)
	The pins that are ADC inputs on either part the image may run on: GP26 to GP29 of the RP2350A, GP40 to GP47 of the RP2354B.
static uint8_t	pin_refusal (const tone_page_t p, const outputs_t o, uint16_t pin, uint64_t taken)
	Why `pin` may not carry the tap, as the NACK says it, or 0 when it may.
static bool	pin_free (const tone_page_t p, const outputs_t o, uint16_t pin, uint64_t taken)
	Whether `pin` passes pin_refusal() for the tap.
bool	tone_page_pin_free (const tone_page_t p, const outputs_t o, uint64_t taken)
	Whether the configured pin is free for the tap, as a write of ENABLE would judge it: the pull-down is put on it only if so.
static bool	values_ok (tone_page_t p, const uint16_t c)
	The values themselves, whatever is enabled: a set-up kept in flash is one a later enable can take without another write.
static void	forget_status (tone_page_t *p)
	A new set-up: what core 1 said under the old one is gone, so no read shows a tone or a flag before core 1 has run under the new one.
uint8_t	tone_page_write (tone_page_t p, uint8_t off, uint8_t n, const uint16_t in, const outputs_t *o, uint64_t taken)
	A write, validated whole before any of it is stored.
void	tone_page_restore (tone_page_t p, const uint16_t cfg, const outputs_t *o, uint64_t taken)
	The set-up kept in flash, loaded as a write would, at boot.
void	tone_page_revert (tone_page_t p, const uint16_t cfg, bool refused)
	Put back the set-up `cfg` and refusal state a write replaced, after the wiring could not take it.
void	tone_page_refuse (tone_page_t *p)
	The wiring could not take the pin of an enabled set-up.
void	tone_page_no_capture (tone_page_t *p)
	No capture runs this boot (core 1 did not start): an enabled set-up is refused as tone_page_refuse() does, and every later write that enables the tap is refused with LINK_NACK_BAD_VALUE until the IOmcu restarts. A write with ENABLE clear is taken.
void	tone_page_capture (tone_page_t *p)
	The capture starts again (the tap enabled, or its pin moved): the ring empties and the order carries a new capture generation.
void	tone_page_recapture (tone_page_t *p, uint32_t shift_ms)
	The capture starts again with the ring kept: a refused write that put the old set-up back.
uint8_t	tone_page_slots_check (const tone_page_t p, const uint16_t slots)
	LINK_NACK_BAD_VALUE for an OUTPUTS page (slots, LINK_OS_COUNT registers) that binds a slot to the tap's pin; 0 otherwise.
void	tone_page_cmd (const tone_page_t p, bool run, tone_cmd_t cmd)
	The order for core 1; `run` is whether the capture runs now.
void	tone_page_publish (tone_page_t p, const tone_status_t st, const tone_rec_t *rec, size_t n)
	What core 1 handed back: its status, and the `n` beeps it finished.
void	tone_page_beeps (tone_page_t p, uint16_t gen, uint16_t cap_gen, const tone_rec_t rec, size_t n)
	`n` beeps finished by core 1 under set-up `gen` and capture `cap_gen`, into the ring; dropped when the capture is not the one in force.
void	tone_page_dropped (tone_page_t *p, uint32_t n)
	`n` beeps lost between the cores, added to LOST.
static uint16_t	seq_of (uint64_t i)
	Beep index `i` (a count from 1) as the number the wire carries.
static const tone_rec_t *	find (const tone_page_t *p, uint16_t sel)
	The ring's entry for beep number `sel`, or NULL if it is not there.
void	tone_page_read (const tone_page_t p, uint8_t off, uint8_t n, uint16_t out)
	A TONE page read.

Detailed Description

The TONE link page.

See tone_page.h.

SPDX-License-Identifier: MIT

Function Documentation

◆ adc_pin()

bool adc_pin ( uint16_t pin )

static

The pins that are ADC inputs on either part the image may run on: GP26 to GP29 of the RP2350A, GP40 to GP47 of the RP2354B.

Rated IOVDD + 0.5V, not fault tolerant.

Parameters

pin	GPIO number.

Returns: true for an ADC pin, false otherwise.

◆ find()

const tone_rec_t * find	(	const tone_page_t *	p,
		uint16_t	sel )

static

The ring's entry for beep number sel, or NULL if it is not there.

Parameters

p	The page state, read only.
sel	Wire beep number, as EVT_SEL carries it.

Returns: The ring entry, or NULL for sel of 0 or a beep not in the ring.

◆ forget_status()

void forget_status ( tone_page_t * p )

static

A new set-up: what core 1 said under the old one is gone, so no read shows a tone or a flag before core 1 has run under the new one.

The ring and the counters are the capture's and stay.

Parameters

p	The page state. The status and window fields are cleared.

◆ pin_free()

bool pin_free	(	const tone_page_t *	p,
		const outputs_t *	o,
		uint16_t	pin,
		uint64_t	taken )

static

Whether pin passes pin_refusal() for the tap.

Parameters

p	The page state.
o	The outputs bank.
pin	GPIO number to judge.
taken	Mask of the pins other pages hold.

Returns: true when pin_refusal() returns 0, false otherwise.

◆ pin_refusal()

uint8_t pin_refusal	(	const tone_page_t *	p,
		const outputs_t *	o,
		uint16_t	pin,
		uint64_t	taken )

static

Why pin may not carry the tap, as the NACK says it, or 0 when it may.

BAD_VALUE for a pin no binding frees: past the bank, an ADC pin, or one the board reserves. BUSY for a pin something the panel sets up holds: another page's (taken), or an output's. The tap's own pin is not reserved against it.

Parameters

p	The page state, for the tap's own pin.
o	The outputs bank.
pin	GPIO number to judge.
taken	Mask of the pins other pages hold, bit n for GPn.

Returns: 0 when the pin may carry the tap. LINK_NACK_BAD_VALUE or LINK_NACK_BUSY as described above.

◆ seq_of()

uint16_t seq_of ( uint64_t i )

static

Beep index i (a count from 1) as the number the wire carries.

Parameters

i	Beep count, from 1 for the first beep.

Returns: The wire number, 1 to SEQ_PERIOD, or 0 for i of 0.

◆ tone_page_beeps()

void tone_page_beeps	(	tone_page_t *	p,
		uint16_t	gen,
		uint16_t	cap_gen,
		const tone_rec_t *	rec,
		size_t	n )

n beeps finished by core 1 under set-up gen and capture cap_gen, into the ring; dropped when the capture is not the one in force.

A beep finished under an earlier set-up of the same capture is taken: a change of the range keeps the ring and the numbering, and a beep the detector finished before it took the change is a beep that happened.

Parameters

p	The page state.
gen	The set-up generation the beeps finished under. Not checked.
cap_gen	The capture generation the beeps belong to.
rec	The beeps, `n` of them.
n	Number of beeps in `rec`.

◆ tone_page_capture()

void tone_page_capture ( tone_page_t * p )

The capture starts again (the tap enabled, or its pin moved): the ring empties and the order carries a new capture generation.

Parameters

p	The page state.

◆ tone_page_cmd()

void tone_page_cmd	(	const tone_page_t *	p,
		bool	run,
		tone_cmd_t *	cmd )

The order for core 1; run is whether the capture runs now.

Nothing is done when p or cmd is NULL.

Parameters

p	The page state.
run	Whether the capture is asked to run now.
cmd	Receives the order. Set to all zero, then filled in.

◆ tone_page_defaults()

void tone_page_defaults ( uint16_t * cfg )

The set-up as a page starts, into cfg (LINK_TN_CONFIG_COUNT registers): the tap off, GP22, 400 to 6500Hz, 8%, 3ms, 3 periods.

Parameters

cfg	Receives LINK_TN_CONFIG_COUNT registers. Nothing is done when NULL.

◆ tone_page_dropped()

void tone_page_dropped	(	tone_page_t *	p,
		uint32_t	n )

n beeps lost between the cores, added to LOST.

Parameters

p	The page state. Nothing is done when NULL.
n	Number of beeps lost.

◆ tone_page_enabled()

bool tone_page_enabled ( const tone_page_t * p )

Whether ENABLE bit 0 (the tap) is set.

Parameters

p	The page state.

Returns: true when enabled, false when not, or when p is NULL.

◆ tone_page_init()

void tone_page_init ( tone_page_t * p )

Set the page to its start: the defaults, and the first beep number 1.

Nothing is done when p is NULL.

Parameters

p	The page state, overwritten.

◆ tone_page_no_capture()

void tone_page_no_capture ( tone_page_t * p )

No capture runs this boot (core 1 did not start): an enabled set-up is refused as tone_page_refuse() does, and every later write that enables the tap is refused with LINK_NACK_BAD_VALUE until the IOmcu restarts. A write with ENABLE clear is taken.

Parameters

p	The page state.

◆ tone_page_pin()

uint8_t tone_page_pin ( const tone_page_t * p )

The configured pin, from register LINK_TN_PIN.

Parameters

p	The page state.

Returns: The pin number, 0 for NULL.

◆ tone_page_pin_free()

bool tone_page_pin_free	(	const tone_page_t *	p,
		const outputs_t *	o,
		uint64_t	taken )

Whether the configured pin is free for the tap, as a write of ENABLE would judge it: the pull-down is put on it only if so.

Parameters

p	The page state.
o	The outputs bank.
taken	Mask of the pins other pages hold.

Returns: true when the pin is free, false when it is not or p or o is NULL.

◆ tone_page_pins()

uint64_t tone_page_pins ( const tone_page_t * p )

The pin as a reservation mask; 0 unless the capture is wanted.

Parameters

p	The page state.

Returns: Bit n set for the configured pin n, or 0.

◆ tone_page_publish()

void tone_page_publish	(	tone_page_t *	p,
		const tone_status_t *	st,
		const tone_rec_t *	rec,
		size_t	n )

What core 1 handed back: its status, and the n beeps it finished.

Taken when st was made under the set-up in force; ignored otherwise.

Parameters

p	The page state.
st	The status core 1 returned.
rec	The beeps core 1 finished, `n` of them.
n	Number of beeps in `rec`.

◆ tone_page_read()

void tone_page_read	(	const tone_page_t *	p,
		uint8_t	off,
		uint8_t	n,
		uint16_t *	out )

A TONE page read.

Nothing is done when p or out is NULL, or when off and n reach past LINK_TN_COUNT.

Parameters

p	The page state, not changed.
off	First register, 0 to LINK_TN_COUNT - 1.
n	Number of registers to read.
out	Receives the `n` register values.

◆ tone_page_recapture()

void tone_page_recapture	(	tone_page_t *	p,
		uint32_t	shift_ms )

The capture starts again with the ring kept: a refused write that put the old set-up back.

The order carries a new capture generation; the beeps already in the ring stay readable, because the panel was told nothing restarted. shift_ms, the time from the old capture's start to the new one's, is added to every later beep's start, so EVT_START_MS keeps its origin. A beep under way was cut: FLAGS shows OVERRUN until the next capture.

Parameters

p	The page state.
shift_ms	Milliseconds from the old capture's start to the new one's.

◆ tone_page_refuse()

void tone_page_refuse ( tone_page_t * p )

The wiring could not take the pin of an enabled set-up.

Nothing changes unless the set-up is enabled.

Parameters

p	The page state.

◆ tone_page_restore()

void tone_page_restore	(	tone_page_t *	p,
		const uint16_t *	cfg,
		const outputs_t *	o,
		uint64_t	taken )

The set-up kept in flash, loaded as a write would, at boot.

A set-up that is not valid starts as the defaults. A valid one that enables the tap on a pin that is no longer free is kept, and the tap does not run: FLAGS says PIN_REFUSED and the pin is not reserved.

Nothing is done when p, cfg or o is NULL.

Parameters

p	The page state, overwritten.
cfg	The kept set-up, LINK_TN_CONFIG_COUNT registers.
o	The outputs bank, for the pin's reservation.
taken	Mask of the pins other pages hold, as tone_page_write() takes it.

◆ tone_page_revert()

void tone_page_revert	(	tone_page_t *	p,
		const uint16_t *	cfg,
		bool	refused )

Put back the set-up cfg and refusal state a write replaced, after the wiring could not take it.

Nothing is done when p or cfg is NULL.

Parameters

p	The page state, overwritten.
cfg	The set-up to put back, LINK_TN_CONFIG_COUNT registers.
refused	The refusal state to put back.

◆ tone_page_slots_check()

uint8_t tone_page_slots_check	(	const tone_page_t *	p,
		const uint16_t *	slots )

LINK_NACK_BAD_VALUE for an OUTPUTS page (slots, LINK_OS_COUNT registers) that binds a slot to the tap's pin; 0 otherwise.

Parameters

p	The page state.
slots	The OUTPUTS page, LINK_OS_COUNT registers.

Returns: LINK_NACK_BAD_VALUE when a slot with a driver binds the pin held by tone_page_pins(), 0 otherwise. LINK_NACK_BAD_VALUE for a NULL slots.

◆ tone_page_wanted()

bool tone_page_wanted ( const tone_page_t * p )

Whether the capture is to run: enabled and not refused.

Parameters

p	The page state.

Returns: true when the tap is enabled and not refused, false otherwise.

◆ tone_page_write()

uint8_t tone_page_write	(	tone_page_t *	p,
		uint8_t	off,
		uint8_t	n,
		const uint16_t *	in,
		const outputs_t *	o,
		uint64_t	taken )

A write, validated whole before any of it is stored.

Registers 0 to 7 are the set-up and EVT_SEL alone is the beep shown; anything else is read only. Refused: off the page (BAD_RANGE); a read-only register (READ_ONLY); a value out of its range, register 7 other than 0, a set-up tone_init() refuses, and with the tap enabled a pin past the bank, an ADC pin or one the board reserves (BAD_VALUE); with the tap enabled on a page that runs no capture this boot (tone_page_no_capture(), BAD_VALUE: no freed pin makes it good before a restart); with the tap enabled a pin in taken or bound to an output (BUSY, since 4.17: freed, the same write is taken). A write of the set-up in force is taken, unless the tap is refused: then it is tried again.

taken is the pins another page holds: SUPPLY's, PROG's, and SENSE's including the ones core 1 has not let go of yet. Every reserved pin outside it is judged a board pin.

Parameters

p	The page state, changed only when the write is taken.
off	First register, 0 to LINK_TN_COUNT - 1.
n	Number of registers to write. 0 is taken with no change.
in	The `n` new register values.
o	The outputs bank, for the pin's reservation.
taken	Mask of the pins other pages hold, bit n for GPn.

Returns: 0 when taken. LINK_NACK_BAD_RANGE for a NULL pointer or a range past LINK_TN_COUNT. LINK_NACK_READ_ONLY for a range that reaches register 8 (FLAGS) or above. LINK_NACK_BAD_VALUE for the refusals above. LINK_NACK_BUSY for a pin in taken or bound to an output.

◆ values_ok()

bool values_ok	(	tone_page_t *	p,
		const uint16_t *	c )

static

The values themselves, whatever is enabled: a set-up kept in flash is one a later enable can take without another write.

The detector's own verdict is the last word: tone_init() refuses a gap shorter than the lowest tone's period and any range the tick clock cannot resolve.

Parameters

p	The page state; its scratch detector is set by tone_init().
c	The set-up to judge, LINK_TN_CONFIG_COUNT registers.

Returns: true when every register is in range, register 7 is 0 and tone_init() accepts the set-up, false otherwise.

Macros

Functions

Detailed Description

Function Documentation

◆ adc_pin()

◆ find()

◆ forget_status()

◆ pin_free()

◆ pin_refusal()

◆ seq_of()

◆ tone_page_beeps()

◆ tone_page_capture()

◆ tone_page_cmd()

◆ tone_page_defaults()

◆ tone_page_dropped()

◆ tone_page_enabled()

◆ tone_page_init()

◆ tone_page_no_capture()

◆ tone_page_pin()

◆ tone_page_pin_free()

◆ tone_page_pins()

◆ tone_page_publish()

◆ tone_page_read()

◆ tone_page_recapture()

◆ tone_page_refuse()

◆ tone_page_restore()

◆ tone_page_revert()

◆ tone_page_slots_check()

◆ tone_page_wanted()

◆ tone_page_write()

◆ values_ok()