link_host.h File Reference

The panel's half of the link: poll, match the reply to the question, and escalate when the answers stop. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "link_msg.h"
#include "link_pages.h"

Go to the source code of this file.

Data Structures
struct	link_host_t
	The panel's state for one link: the outstanding request, the counters and the reassembly buffer. More...

Macros
#define	LINK_HOST_TIMEOUT_MS   1000u
	How long the panel tolerates silence before it escalates: five times the IOmcu's 200ms, so the end holding the outputs gives up first.

Functions
void	link_host_init (link_host_t *h, uint32_t now_ms)
	Set up the panel's link state.
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.
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.
void	link_host_abandon (link_host_t *h)
	Give up on the outstanding request.
bool	link_host_pending (const link_host_t *h)
	Whether a request is outstanding.

Detailed Description

The panel's half of the link: poll, match the reply to the question, and escalate when the answers stop.

One request outstanding at a time, which is the protocol: the IOmcu transmits only when asked, so there is one request in flight and nothing to arbitrate.

SPDX-License-Identifier: MIT

Function Documentation

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.