endpoints_link.c File Reference

The panel's half of the throttle's pulse endpoints. More...

#include "endpoints_link.h"
#include <stddef.h>
#include "link_pages.h"

Functions
endpoints_next_t	endpoints_next (bool owed, bool far_disarmed, uint32_t edit_ms, uint32_t now_ms)
	What a debt asks of a pass at now_ms.
bool	endpoints_owed_after (endpoints_outcome_t outcome)
	Whether the debt stands after an attempt that ended in outcome: true only for ENDPOINTS_NO_ANSWER, and for a value outside the enum.
bool	endpoints_page_holds (const uint16_t *page, uint16_t min_us, uint16_t max_us)
	Whether every throttle channel of a CHAN_CFG page page (LINK_CC_COUNT registers) holds min_us and max_us.
static endpoints_block_t	block_of (endpoints_outcome_t outcome)
	What an answered payment leaves for the switch to ARMED.
void	endpoints_publish (endpoints_debt_t *d, uint16_t min_us, uint16_t max_us, uint32_t now_ms)
	An edit of Idle pulse or Full pulse at now_ms, from any task: the pair, then the time, then the flag, so a payment that sees the flag sees the pair and the rest it starts from.
void	endpoints_link_up (endpoints_debt_t *d)
	A link-up edge: the pair is owed again and the far end held disarmed until it is paid.
void	endpoints_recheck (endpoints_debt_t *d)
	A binding was written: the throttle channels may have moved, so the pair is owed again, due at the next poll once its edit has rested.
endpoints_block_t	endpoints_block (const endpoints_debt_t *d)
	Why a switch to ARMED with the link up is refused for the pair: ENDPOINTS_BLOCK_OWED while owed, else what the last answered payment left.
bool	endpoints_blocked (const endpoints_debt_t *d)
	endpoints_block() is not ENDPOINTS_BLOCK_NONE.
bool	endpoints_owed (const endpoints_debt_t *d)
	Whether a pair is owed: true refuses a switch to ARMED with the link up.
bool	endpoints_held (const endpoints_debt_t *d)
	Whether the far end is held disarmed for the debt.
uint16_t	endpoints_min (const endpoints_debt_t *d)
	The pair as last published, in us; 0 for NULL.
uint16_t	endpoints_max (const endpoints_debt_t *d)
	The Full pulse as last published, in us; 0 for NULL.
endpoints_next_t	endpoints_take (endpoints_debt_t *d, bool far_disarmed, uint32_t now_ms)
	The debt at a poll, on the control task: what endpoints_next() finds.
void	endpoints_paid (endpoints_debt_t *d, endpoints_outcome_t outcome)
	The end of a payment endpoints_take() handed out: owed again on a missing answer, the hold and the block kept with it; otherwise paid, the hold ended, and the block set from outcome – none for ENDPOINTS_HELD and ENDPOINTS_TAKEN.

Detailed Description

The panel's half of the throttle's pulse endpoints.

See endpoints_link.h.

SPDX-License-Identifier: MIT

Function Documentation

block_of()

endpoints_block_t block_of ( endpoints_outcome_t outcome )

static

What an answered payment leaves for the switch to ARMED.

Parameters

outcome

The outcome of the payment.

Returns

The block reason for the outcome.

endpoints_block()

endpoints_block_t endpoints_block

(

const endpoints_debt_t *

d

)

Why a switch to ARMED with the link up is refused for the pair: ENDPOINTS_BLOCK_OWED while owed, else what the last answered payment left.

ENDPOINTS_BLOCK_NONE for NULL.

Parameters

d	The debt to read.

Returns

The block reason; ENDPOINTS_BLOCK_NONE for NULL.

endpoints_blocked()

bool endpoints_blocked

(

const endpoints_debt_t *

d

)

endpoints_block() is not ENDPOINTS_BLOCK_NONE.

Parameters

d	The debt to read.

Returns

true when endpoints_block() is not ENDPOINTS_BLOCK_NONE.

endpoints_held()

bool endpoints_held

(

const endpoints_debt_t *

d

)

Whether the far end is held disarmed for the debt.

False for NULL.

Parameters

d	The debt to read.

Returns

true when the far end is held disarmed.

endpoints_link_up()

void endpoints_link_up

(

endpoints_debt_t *

d

)

A link-up edge: the pair is owed again and the far end held disarmed until it is paid.

Control task only.

Parameters

d	The debt to update.

endpoints_max()

uint16_t endpoints_max

(

const endpoints_debt_t *

d

)

The Full pulse as last published, in us; 0 for NULL.

Parameters

d	The debt to read.

Returns

The Full pulse in us; 0 for NULL.

endpoints_min()

uint16_t endpoints_min

(

const endpoints_debt_t *

d

)

The pair as last published, in us; 0 for NULL.

Parameters

d	The debt to read.

Returns

The Idle pulse in us; 0 for NULL.

endpoints_next()

endpoints_next_t endpoints_next	(	bool	owed,
		bool	far_disarmed,
		uint32_t	edit_ms,
		uint32_t	now_ms )

What a debt asks of a pass at now_ms.

owed: a pair is owed. far_disarmed: the control write of this pass put ARM = 0 at the far end and was acknowledged. edit_ms: the time of the last edit.

Due once now_ms - edit_ms, taken modulo 2^32, reaches ENDPOINTS_SETTLE_MS: 299ms after an edit waits, 300ms pays.

Parameters

owed	true while a pair is owed.
far_disarmed	true when the control write of this pass put ARM = 0 at the far end and it was acknowledged.
edit_ms	The time of the last edit, in ms.
now_ms	The time of this pass, in ms.

Returns

What the pass asks for, as endpoints_next_t.

endpoints_owed()

bool endpoints_owed

(

const endpoints_debt_t *

d

)

Whether a pair is owed: true refuses a switch to ARMED with the link up.

False for NULL.

Parameters

d	The debt to read.

Returns

true when a pair is owed.

endpoints_owed_after()

bool endpoints_owed_after

(

endpoints_outcome_t

outcome

)

Whether the debt stands after an attempt that ended in outcome: true only for ENDPOINTS_NO_ANSWER, and for a value outside the enum.

Parameters

outcome

The outcome of the attempt.

Returns

true when the debt stands.

endpoints_page_holds()

bool endpoints_page_holds	(	const uint16_t *	page,
		uint16_t	min_us,
		uint16_t	max_us )

Whether every throttle channel of a CHAN_CFG page page (LINK_CC_COUNT registers) holds min_us and max_us.

A page with no throttle channel holds any pair. False for NULL.

Parameters

page	The CHAN_CFG page, LINK_CC_COUNT registers.
min_us	The Idle pulse, in us.
max_us	The Full pulse, in us.

Returns

true when every throttle channel holds the pair; false for NULL.

endpoints_paid()

void endpoints_paid	(	endpoints_debt_t *	d,
		endpoints_outcome_t	outcome )

The end of a payment endpoints_take() handed out: owed again on a missing answer, the hold and the block kept with it; otherwise paid, the hold ended, and the block set from outcome – none for ENDPOINTS_HELD and ENDPOINTS_TAKEN.

Parameters

d	The debt, or NULL.
outcome	The result of the payment.

endpoints_publish()

void endpoints_publish	(	endpoints_debt_t *	d,
		uint16_t	min_us,
		uint16_t	max_us,
		uint32_t	now_ms )

An edit of Idle pulse or Full pulse at now_ms, from any task: the pair, then the time, then the flag, so a payment that sees the flag sees the pair and the rest it starts from.

Parameters

d	The debt to update.
min_us	The Idle pulse, in us.
max_us	The Full pulse, in us.
now_ms	The time of the edit, in ms.

endpoints_recheck()

void endpoints_recheck

(

endpoints_debt_t *

d

)

A binding was written: the throttle channels may have moved, so the pair is owed again, due at the next poll once its edit has rested.

Control task only.

Parameters

d	The debt to update.

endpoints_take()

endpoints_next_t endpoints_take	(	endpoints_debt_t *	d,
		bool	far_disarmed,
		uint32_t	now_ms )

The debt at a poll, on the control task: what endpoints_next() finds.

On ENDPOINTS_PAY the flag has been taken, and the caller pays the pair endpoints_min() and endpoints_max() read now and ends the payment with endpoints_paid(). The flag is taken before the exchanges and given back by a missing answer, so an edit published while they run stays owed. A switch to ARMED asks endpoints_owed() on the same task, so never between the taking and the outcome.

On ENDPOINTS_PAID the hold ends. A NULL d changes nothing and returns ENDPOINTS_WAIT_DISARM.

Parameters

d	The debt, or NULL.
far_disarmed	true when the far end is disarmed.
now_ms	The time of the poll, in ms.

Returns

What endpoints_next() finds at this poll.