link_host.c File Reference

The host end of the link: starting transactions, accepting replies and timeouts. More...

#include "link_host.h"
#include "link_can.h"
#include <string.h>

Functions
static bool	elapsed (uint32_t now, uint32_t then, uint32_t ms)
	Test whether a timeout has elapsed, across the 32-bit millisecond wrap.
void	link_host_init (link_host_t *h, uint32_t now_ms)
	Set up the panel's link state.
static bool	start (link_host_t *h, uint8_t op, uint8_t page, uint8_t offset, uint8_t count, const uint16_t *regs, uint32_t now_ms, link_msg_t *out)
	Build a request and mark it outstanding.
bool	link_host_read (link_host_t *h, uint8_t page, uint8_t offset, uint8_t count, uint32_t now_ms, link_msg_t *out)
	Build a request.
bool	link_host_write (link_host_t *h, uint8_t page, uint8_t offset, uint8_t count, const uint16_t *regs, uint32_t now_ms, link_msg_t *out)
	Build a write request.
static bool	window_complete (const link_host_t *h)
	Everything in the window has arrived.
static void	answered (link_host_t *h, uint32_t now_ms, bool refused)
	Close the outstanding request as answered.
bool	link_host_accept (link_host_t *h, const link_msg_t *part, uint32_t now_ms, link_msg_t *whole)
	Offer one received message against the outstanding request.
bool	link_host_tick (link_host_t *h, uint32_t now_ms)
	Time out the outstanding request, and report the link down once.
bool	link_host_pending (const link_host_t *h)
	Whether a request is outstanding.
void	link_host_abandon (link_host_t *h)
	Give up on the outstanding request.

Detailed Description

The host end of the link: starting transactions, accepting replies and timeouts.

SPDX-License-Identifier: MIT

Function Documentation

answered()

void answered ( link_host_t * h, uint32_t now_ms, bool refused )

static

Close the outstanding request as answered.

Parameters

h	The panel's link state.
now_ms	The time of the answer, in ms.
refused	true when the answer is a NACK, counted in nacks.

elapsed()

bool elapsed ( uint32_t now, uint32_t then, uint32_t ms )

static

Test whether a timeout has elapsed, across the 32-bit millisecond wrap.

Parameters

now	The current time, in ms.
then	The time the wait started, in ms.
ms	The timeout, in ms.

Returns

true when at least ms milliseconds have passed since then.

link_host_abandon()

void link_host_abandon

(

link_host_t *

h

)

Give up on the outstanding request.

For a caller that failed to transmit it: nothing is on the wire to wait for, and an outstanding request refuses every later one until its timeout.

Parameters

h	The panel's link state.

link_host_accept()

bool link_host_accept	(	link_host_t *	h,
		const link_msg_t *	part,
		uint32_t	now_ms,
		link_msg_t *	whole )

Offer one received message against the outstanding request.

True when the request is answered, which for a read may take several messages: whole then holds the reassembled reply. Parts that land without completing it return false and are not a fault; the caller keeps feeding until it gets true or the request times out.

Anything that does not answer the question in flight is counted as a mismatch and refused. A late reply can arrive after the panel has moved on, and accepting it would attach one page's registers to another page's request.

Parameters

h	The panel's link state.
part	The received message.
now_ms	The current time, in ms.
whole	Receives the reassembled reply when the request is answered.

Returns

true when the request is answered, else false.

link_host_init()

void link_host_init	(	link_host_t *	h,
		uint32_t	now_ms )

Set up the panel's link state.

Parameters

h	The state to set up; NULL is ignored.
now_ms	The current time, in ms; starts the link-quiet clock.

link_host_pending()

bool link_host_pending

(

const link_host_t *

h

)

Whether a request is outstanding.

A caller waiting for an answer needs this rather than link_host_tick()'s return, which is true for the link going quiet as well as for this request's timeout: only one of the two releases the slot, and a wait that ended on the other one left the host unable to send anything again.

Parameters

h	The panel's link state.

Returns

true while a request is outstanding.

link_host_read()

bool link_host_read	(	link_host_t *	h,
		uint8_t	page,
		uint8_t	offset,
		uint8_t	count,
		uint32_t	now_ms,
		link_msg_t *	out )

Build a request.

Returns false if the window does not fit a page or a request is already outstanding: one at a time.

Parameters

h	The panel's link state.
page	Page number to read.
offset	First register within the page.
count	Number of registers, 1 to LINK_MAX_REGS.
now_ms	The current time, in ms; starts the request's timeout.
out	Receives the request to send.

Returns

true when the request was built, else false.

link_host_tick()

bool link_host_tick	(	link_host_t *	h,
		uint32_t	now_ms )

Time out the outstanding request, and report the link down once.

Two clocks: a request is abandoned when it has been outstanding for LINK_HOST_TIMEOUT_MS, every time; the link is reported down when nothing has been answered for LINK_HOST_TIMEOUT_MS, once until the next reply.

True if it abandoned a request or escalated; a caller waiting for a reply stops waiting.

Parameters

h	The panel's link state.
now_ms	The current time, in ms.

Returns

true if it abandoned a request or escalated; a caller waiting for a reply stops waiting.

link_host_write()

bool link_host_write	(	link_host_t *	h,
		uint8_t	page,
		uint8_t	offset,
		uint8_t	count,
		const uint16_t *	regs,
		uint32_t	now_ms,
		link_msg_t *	out )

Build a write request.

Parameters

h	The panel's link state.
page	Page number to write.
offset	First register within the page.
count	Number of registers, 1 to LINK_MAX_REGS.
regs	The count values to write.
now_ms	The current time, in ms; starts the request's timeout.
out	Receives the request to send.

Returns

true when the request was built, else false.

start()

bool start ( link_host_t * h, uint8_t op, uint8_t page, uint8_t offset, uint8_t count, const uint16_t * regs, uint32_t now_ms, link_msg_t * out )

static

Build a request and mark it outstanding.

Parameters

h	The panel's link state.
op	LINK_OP_READ or LINK_OP_WRITE.
page	Page number.
offset	First register within the page.
count	Number of registers, 1 to LINK_MAX_REGS.
regs	The values of a write; NULL for a read.
now_ms	The current time, in ms; starts the request's timeout.
out	Receives the request.

Returns

true when the request was built, false when h or out is NULL, when one is already outstanding, or when the window does not fit a page.

window_complete()

bool window_complete ( const link_host_t * h )

static

Everything in the window has arrived.

Parameters

h	The panel's link state.

Returns

true when all count bits of acc_seen are set.