link_bringup.c File Reference

Bring-up of the link: status replies, round-trip times and the diagnosis. More...

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

Macros
#define	SHORTFALL_NUM   9
	The shortfall that counts as a fault: fewer replies than 9/10 of the polls.
#define	SHORTFALL_DEN   10
#define	ENOUGH_POLLS   4u
	Fewer replies than this and there is nothing to draw conclusions from.

Functions
static bool	well_short (uint32_t got, uint32_t of)
	Test whether fewer replies came back than the shortfall ratio allows.
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.
link_diag_t	link_bringup_diagnose (const link_bringup_t *b)
	Name the most fundamental thing that is wrong.
static uint32_t	since (uint32_t now, uint32_t prev)
	One counter's count since the previous snapshot.
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.

Detailed Description

Bring-up of the link: status replies, round-trip times and the diagnosis.

SPDX-License-Identifier: MIT

Macro Definition Documentation

SHORTFALL_NUM

#define SHORTFALL_NUM   9

The shortfall that counts as a fault: fewer replies than 9/10 of the polls.

Below that shortfall a link is working and occasionally missing, which is INTERMITTENT.

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.

since()

uint32_t since ( uint32_t now, uint32_t prev )

static

One counter's count since the previous snapshot.

Parameters

now	The counter at this snapshot.
prev	The counter at the previous snapshot.

Returns

now - prev, or now when the counter went backwards (it counts from 0 again).

well_short()

bool well_short ( uint32_t got, uint32_t of )

static

Test whether fewer replies came back than the shortfall ratio allows.

Parameters

got	The replies received.
of	The polls sent.

Returns

true when got is below 9/10 of of.