tone_page.h File Reference

The TONE link page at the IOmcu: the phase tap that hears an ESC's (electronic speed controller) beeps on one motor phase. More...

#include <stdbool.h>
#include <stdint.h>
#include "link_pages.h"
#include "outputs.h"
#include "tone.h"
#include "tone_svc.h"

Go to the source code of this file.

Data Structures
struct	tone_page_t
	The TONE page state: the set-up, what core 1 last reported, and the beep ring of the capture. More...

Functions
void	tone_page_init (tone_page_t *p)
	Set the page to its start: the defaults, and the first beep number 1.
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.
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_read (const tone_page_t *p, uint8_t off, uint8_t n, uint16_t *out)
	A TONE page read.
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.
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.
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.
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.

Detailed Description

The TONE link page at the IOmcu: the phase tap that hears an ESC's (electronic speed controller) beeps on one motor phase.

The registers are in link_pages.h (LINK_TN_*).

The set-up, registers 0 to 6, is refused on a value out of its range, on a combination the detector refuses (tone_init()), and, while the tap is enabled, on a pin past the bank, reserved, bound to an output, held by the SENSE or SUPPLY page, or an ADC (analog to digital converter) pin. The pin it takes is reserved from the outputs for as long as the tap is enabled and runs (tone_page_pins()). The tap is an input and drives nothing, so a change is taken armed or not.

Host-tested. The page holds the contract and the checks. Capturing is core 0's wiring (PIO state machine, DMA ring, pull-down) and detecting is core 1's (tone_svc.h): the page turns the set-up into the order core 1 runs (tone_page_cmd()), and takes the beeps and status core 1 hands back (tone_page_publish()) into the 64-beep ring and the read-only registers. Until a status under the set-up in force arrives the read-only registers read 0 and the ring is as it was.

Beep numbers. Beeps are numbered from 1 to 65535 and then from 1 again, so that 0 can mean none. BEEP_HEAD is the newest, 0 before the first. The ring holds the last LINK_TN_RING beeps of the capture running; a capture that starts again empties it and the numbers go on.

SPDX-License-Identifier: MIT

Function Documentation

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.