link_bringup.h File Reference

Both ends' link counters turned into one diagnosis. More...

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

Go to the source code of this file.

Data Structures
struct	link_bringup_t
	The link counters of both ends, and the round-trip statistics. More...

Enumerations
enum	link_diag_t {   LINK_DIAG_OK = 0 , LINK_DIAG_SILENT , LINK_DIAG_PROTOCOL_MISMATCH , LINK_DIAG_REPLIES_LOST ,   LINK_DIAG_CORRUPT , LINK_DIAG_STALE , LINK_DIAG_INTERMITTENT }
	The most fundamental fault a link shows. More...

Functions
link_diag_t	link_bringup_diagnose (const link_bringup_t *b)
	Name the most fundamental thing that is wrong.
void	link_bringup_window (const link_bringup_t *now, const link_bringup_t *prev, link_bringup_t *out)
	The counts of one report window: what happened between two snapshots, for link_bringup_diagnose() to judge the recent link rather than the whole session.
const char *	link_diag_text (link_diag_t d)
	One line naming the fault.
const char *	link_diag_hint (link_diag_t d)
	One line naming what to check, in the order worth checking it.
uint8_t	link_bringup_status_count (uint16_t minor)
	How many STATUS registers to read from an IOmcu of protocol minor minor: LINK_ST_COUNT from LINK_MINOR_REFUSED, LINK_ST_COUNT_V420 before it.
bool	link_bringup_take_status (link_bringup_t *b, const link_msg_t *st, uint16_t *faults)
	Take a STATUS reply read from register 0 into b and the fault bitmap into faults (either may be NULL).
void	link_bringup_add_rtt (link_bringup_t *b, uint32_t us)
	Fold one round-trip measurement in.

Detailed Description

Both ends' link counters turned into one diagnosis.

Wrong pins, a mismatched bit rate, a missing terminator and a firmware skew all present as a link that does not work. The counters read from both ends and compared tell them apart: an IOmcu that decoded 100 requests while the panel heard no answers is a return-path fault, which the panel's own numbers cannot show.

Pure arithmetic over two structs, so every diagnosis has a host test that constructs the fault.

SPDX-License-Identifier: MIT

Enumeration Type Documentation

link_diag_t

enum link_diag_t

The most fundamental fault a link shows.

Enumerator
LINK_DIAG_SILENT	Nothing came back at all.
LINK_DIAG_PROTOCOL_MISMATCH	It answers, but it is not speaking this protocol.
LINK_DIAG_REPLIES_LOST	Requests arrive and answers do not: the return path, not the link.
LINK_DIAG_CORRUPT	Frames arrive corrupt. Bit timing, noise, or termination.
LINK_DIAG_STALE	Answers arrive too late to be wanted. A slow far end, or a timeout tighter than the round trip.
LINK_DIAG_INTERMITTENT	It works, and not every time.

Function Documentation

link_bringup_add_rtt()

void link_bringup_add_rtt	(	link_bringup_t *	b,
		uint32_t	us )

Fold one round-trip measurement in.

Parameters

b	The counters to update; NULL is ignored.
us	The round trip, in microseconds.

link_bringup_diagnose()

link_diag_t link_bringup_diagnose

(

const link_bringup_t *

b

)

Name the most fundamental thing that is wrong.

Most fundamental, not most numerous: a silent link also has a hundred timeouts, and reporting the timeouts is reporting a consequence. The order the checks run in is the diagnosis.

Parameters

b	The counters of both ends.

Returns

LINK_DIAG_OK before four polls have been made, else the first fault the checks find.

link_bringup_status_count()

uint8_t link_bringup_status_count

(

uint16_t

minor

)

How many STATUS registers to read from an IOmcu of protocol minor minor: LINK_ST_COUNT from LINK_MINOR_REFUSED, LINK_ST_COUNT_V420 before it.

An older page refuses the longer read with LINK_NACK_BAD_RANGE, which would lose the counters it does have.

Parameters

minor

The protocol minor the IOmcu reports.

Returns

LINK_ST_COUNT or LINK_ST_COUNT_V420.

link_bringup_take_status()

bool link_bringup_take_status	(	link_bringup_t *	b,
		const link_msg_t *	st,
		uint16_t *	faults )

Take a STATUS reply read from register 0 into b and the fault bitmap into faults (either may be NULL).

False, and nothing taken, for anything but a DATA reply from offset 0 with at least LINK_ST_COUNT_V420 registers. A reply that ends before LINK_ST_REFUSED_HI clears have_refused and dev_refused: an older IOmcu counts no refusals, and a count is not carried over from an IOmcu that answered before it.

Parameters

b	The counters to fill; may be NULL.
st	The STATUS reply.
faults	Receives the fault bitmap; may be NULL.

Returns

true when the reply was taken, else false.

link_bringup_window()

void link_bringup_window	(	const link_bringup_t *	now,
		const link_bringup_t *	prev,
		link_bringup_t *	out )

The counts of one report window: what happened between two snapshots, for link_bringup_diagnose() to judge the recent link rather than the whole session.

Each counter of out is now - prev. A counter that is lower in now than in prev counts from 0 again – an IOmcu that restarted, or a 16-bit status register that wrapped – and its window count is the value in now. A restarted counter that has passed its previous figure by the time of now is not told from one that kept counting, and its window count is short by the previous figure.

Flags, identity, the round-trip figures and the IOmcu's two CAN error counters are taken from now: have_status, have_refused, have_identity, proto_major, proto_minor, rt_samples, rt_min_us, rt_max_us, rt_mean_us, dev_crc_errors and dev_resyncs. The error counters are levels that good frames lower, so a difference of two readings can be 0 while errors keep coming.

Parameters

now	The counters at this report.
prev	The counters at the previous report; NULL for the first report, which makes the window everything since the counters started (the same as an all-zero prev).
out	Receives the window; may be the same object as now.

link_diag_hint()

const char * link_diag_hint

(

link_diag_t

d

)

One line naming what to check, in the order worth checking it.

Parameters

d	The fault.

Returns

The hint for d, one line; empty for LINK_DIAG_OK.

link_diag_text()

const char * link_diag_text

(

link_diag_t

d

)

One line naming the fault.

Parameters

d	The fault.

Returns

The text for d, one line.