The panel's half of the SENSE_MAP page (0x35, protocol 4.25): up to four INA3221 parts as SETUP > SENSORS has them, written to the IOmcu, and what each part is doing, for SENSORS and the alert band. More...

#include <stdbool.h>
#include <stdint.h>
#include "link_pages.h"
#include "sense_link.h"

Data Structures
struct	sense_map_want_t
	The map SENSORS asks for (settings_sensors_map()). More...
struct	sense_map_link_op_t
	One exchange the SENSE_MAP link asks the caller to make. More...
struct	sense_map_link_t
	The panel's state of the SENSE_MAP link page. More...

Macros
#define	SENSE_MAP_LINK_SETTLE_MS SENSE_LINK_SETTLE_MS
	A map rests this long after its last edit before it is written.
#define	SENSE_MAP_LINK_READ_MS 500u
	The page's IDs and FLAGS are read this often while a part is fitted.
#define	SENSE_MAP_LINK_EVENT_GAP_MS SENSE_LINK_EVENT_GAP_MS
	An event handed out has the alert band this long before the next.
#define	SENSE_MAP_LINK_ACK SENSE_LINK_ACK
#define	SENSE_MAP_LINK_NO_ANSWER SENSE_LINK_NO_ANSWER
#define	SENS_PART_OF(word, a)
	Part `a's` field of a status word.

Enumerations
enum	{ SENSE_MAP_LINK_EV_REFUSED = 0x01 , SENSE_MAP_LINK_EV_DARK = 0x02 , SENSE_MAP_LINK_EV_SILENT = 0x04 , SENSE_MAP_LINK_EV_WRONG = 0x08 }
	Things the caller tells the operator about, each once. More...
enum	sens_part_t { SENS_PART_UNKNOWN = 0 , SENS_PART_PENDING , SENS_PART_SEARCHING , SENS_PART_ONLINE , SENS_PART_SILENT , SENS_PART_WRONG , SENS_PART_REFUSED , SENS_PART_DARK , SENS_PART_SAME_ADDR , SENS_PART_OLD , SENS_PART_NO_BUS , SENS_PART_COUNT }
	What a fitted part is doing, for its heading on SETUP > SENSORS; 4 bits each in sense_map_link_status(). More...
enum	sense_map_link_op_kind_t { SENSE_MAP_LINK_OP_NONE = 0 , SENSE_MAP_LINK_OP_READ , SENSE_MAP_LINK_OP_WRITE , SENSE_MAP_LINK_OP_STATUS }
	The kinds of exchange of the SENSE_MAP link. More...

Functions
void	sense_map_link_init (sense_map_link_t *s)
	Sets up the SENSE_MAP link state.
void	sense_map_link_lost (sense_map_link_t *s)
	The link went: nothing on the page is known.
void	sense_map_link_came_up (sense_map_link_t *s, uint16_t minor, uint32_t now_ms)
	An IOmcu answered with protocol minor `minor`; below LINK_MINOR_SENSE_MAP nothing is sent to it.
void	sense_map_link_want (sense_map_link_t s, const sense_map_want_t w, uint32_t now_ms)
	The map SENSORS asks for now.
bool	sense_map_link_next (sense_map_link_t s, uint32_t now_ms, bool idle, sense_map_link_op_t op)
	The next exchange owed at `now_ms` into `op`; false for none.
void	sense_map_link_done (sense_map_link_t s, int result, const uint16_t regs, uint32_t now_ms)
	How it went: SENSE_MAP_LINK_ACK with the registers read (NULL for a write), a NACK's reason, or SENSE_MAP_LINK_NO_ANSWER.
bool	sense_map_link_page (const sense_map_link_t *s)
	Whether the IOmcu has the page: up, 4.25 or later, and no read refused.
uint16_t	sense_map_link_mirror_dmohm (const sense_map_link_t *s, unsigned ch)
	The shunt in 0.1mOhm of CH `ch` (1 to 3) of the part SENSE mirrors, as the page holds the map: the part SENSE's CLIPPED flag and SERVO_SENSE are about.
bool	sense_map_link_waits_for_pins (const sense_map_link_t s, const sense_link_t sl)
	Whether the map waits for SENSE's pins: it enables a part while SENSE has not been read since link-up or the sensor bus's pins it holds are not the ones asked.
bool	sense_map_link_held (const sense_map_link_t *s)
	Whether the page holds the map asked: read since link-up, not refused, and nothing owed.
bool	sense_map_link_in_force (const sense_map_link_t *s)
	Whether the IOmcu goes by a map written to it, not the one derived from SENSE: FLAGS' IN_FORCE as last read, or a write taken since.
bool	sense_map_link_take_reread (sense_map_link_t *s)
	Whether a write was taken since the last call: SENSE's set-up is to be read again.
uint8_t	sense_map_link_event (sense_map_link_t s, uint32_t now_ms, uint8_t part, uint16_t *id)
	The events since the last call, SENSE_MAP_LINK_EV_*, the lowest bit first, one at a time; 0 for none, and 0 while the last one handed out is younger than SENSE_MAP_LINK_EVENT_GAP_MS at `now_ms`.
bool	sense_map_link_event_stands (const sense_map_link_t *s, uint8_t ev, uint8_t part)
	Whether the cause of event `ev` for part `part` still holds: the map refused, the part dark, or, for SILENT and WRONG, the part fitted on a link that answers.
void	sense_map_link_event_back (sense_map_link_t *s, uint8_t ev, uint8_t part)
	Put back an event sense_map_link_event() handed out that never reached the band, with the part it named.
sens_part_t	sense_map_link_part (const sense_map_link_t s, const sense_link_t sl, unsigned a, unsigned mirror, uint32_t now_ms)
	What fitted part `a` is doing at `now_ms`, a sens_part_t.
uint16_t	sense_map_link_status (const sense_map_link_t s, const sense_link_t sl, unsigned mirror, uint32_t now_ms)
	The four parts' sense_map_link_part(), 4 bits each, part 0 lowest; SENS_PART_UNKNOWN for a part not fitted.

Detailed Description

The panel's half of the SENSE_MAP page (0x35, protocol 4.25): up to four INA3221 parts as SETUP > SENSORS has them, written to the IOmcu, and what each part is doing, for SENSORS and the alert band.

The map is registers 0 to 25 of the page (link_pages.h): ENABLE, FAST, twelve shunts and twelve WATCH values, all kept in the IOmcu's flash. The page judges the whole map at every write, so the panel writes it whole, in one frame of 26 registers:

the page is read whole, 32 registers, once per link-up, and nothing is written that it already holds;
the map asked goes out once it has rested SENSE_MAP_LINK_SETTLE_MS since its last edit – each write is a flash save at the IOmcu – and only while the caller says the bank is idle: the page refuses any change while it drives;
a map the page refuses is not written again until the map asked changes, and says so once (SENSE_MAP_LINK_EV_REFUSED);
after a write is taken the caller reads SENSE's set-up again (sense_link_reread()): SENSE's ENABLE bit 1 and registers 8 to 10 mirror the map from then on.

Two maps are not written, and said once per edit: one with a fitted part whose three shunts are 0 (SENSE_MAP_LINK_EV_DARK), which the page refuses, and none for a part fitted on the INA228's address while the INA228 is on: that part is left out of ENABLE, as SENSE leaves both monitors off, and SENSE_LINK_EV_SAME_ADDR says it. With the sensor bus's SDA or SCL unset every part is left out, and FAST with them: SENSE then clears its pins and enables nothing (SENSE_LINK_EV_PINS_UNSET).

While a part is fitted the page's ID and FLAGS registers are read every SENSE_MAP_LINK_READ_MS. A fitted part that is not online SENSE_LINK_GRACE_MS after the map was taken, or that was online and stops, is said not to answer (SENSE_MAP_LINK_EV_SILENT); one that answers with another identity likewise (SENSE_MAP_LINK_EV_WRONG); each once, for the parts other than the mirror part, which SENSE's own reads already report (sense_link.h).

An IOmcu older than 4.25 has no SENSE_MAP: nothing is sent to it, and SENSE's one-part frame carries the mirror part (settings_sensors.h). sense_map_link_part() then says OLD for every other fitted part.

Pure C, no link of its own: the caller makes each exchange and reports how it went. Control task only.

SPDX-License-Identifier: MIT

Macro Definition Documentation

◆ SENS_PART_OF

#define SENS_PART_OF	(		word,
			a )

Value:

((sens_part_t)(((word) >> (4u * (a))) & 0x0Fu))

sens_part_t

What a fitted part is doing, for its heading on SETUP > SENSORS; 4 bits each in sense_map_link_status...

Definition sense_map_link.h:93

Part a's field of a status word.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Things the caller tells the operator about, each once.

Enumerator
SENSE_MAP_LINK_EV_REFUSED	The page refused the map.
SENSE_MAP_LINK_EV_DARK	A fitted part has every channel off: no map is written.
SENSE_MAP_LINK_EV_SILENT	A fitted part does not answer at its address.
SENSE_MAP_LINK_EV_WRONG	Something answers at a fitted part's address with another identity.

◆ sens_part_t

enum sens_part_t

What a fitted part is doing, for its heading on SETUP > SENSORS; 4 bits each in sense_map_link_status().

Enumerator
SENS_PART_UNKNOWN	no IOmcu answers, or not read yet
SENS_PART_PENDING	the map asked is not written yet
SENS_PART_SEARCHING	taken; the IOmcu is looking for the part
SENS_PART_ONLINE	answering as an INA3221
SENS_PART_SILENT	not answering at its address
SENS_PART_WRONG	another identity answers there
SENS_PART_REFUSED	the page refused the map
SENS_PART_DARK	every channel off: no map is written
SENS_PART_SAME_ADDR	the INA228 is on at its address
SENS_PART_OLD	an IOmcu older than 4.25 reads one part only, and not this one
SENS_PART_NO_BUS	the sensor bus's SDA or SCL is unset

◆ sense_map_link_op_kind_t

enum sense_map_link_op_kind_t

The kinds of exchange of the SENSE_MAP link.

Enumerator
SENSE_MAP_LINK_OP_READ	SENSE_MAP 0 to 31
SENSE_MAP_LINK_OP_WRITE	SENSE_MAP 0 to 25
SENSE_MAP_LINK_OP_STATUS	SENSE_MAP 26 to 30: IDs and FLAGS

Function Documentation

◆ sense_map_link_came_up()

void sense_map_link_came_up	(	sense_map_link_t *	s,
		uint16_t	minor,
		uint32_t	now_ms )

An IOmcu answered with protocol minor minor; below LINK_MINOR_SENSE_MAP nothing is sent to it.

Parameters

s	The link state.
minor	The IOmcu's protocol minor version.
now_ms	The time, in ms.

◆ sense_map_link_done()

void sense_map_link_done	(	sense_map_link_t *	s,
		int	result,
		const uint16_t *	regs,
		uint32_t	now_ms )

How it went: SENSE_MAP_LINK_ACK with the registers read (NULL for a write), a NACK's reason, or SENSE_MAP_LINK_NO_ANSWER.

Parameters

s	The link state.
result	The result: an acknowledgement, a NACK's reason or SENSE_MAP_LINK_NO_ANSWER.
regs	The registers read, or NULL for a write.
now_ms	The time, in ms.

◆ sense_map_link_event()

uint8_t sense_map_link_event	(	sense_map_link_t *	s,
		uint32_t	now_ms,
		uint8_t *	part,
		uint16_t *	id )

The events since the last call, SENSE_MAP_LINK_EV_*, the lowest bit first, one at a time; 0 for none, and 0 while the last one handed out is younger than SENSE_MAP_LINK_EVENT_GAP_MS at now_ms.

part is the lowest part it names, 0 to 3 (0 for REFUSED), with its ID for WRONG in id. SILENT and WRONG are handed out a part at a time.

Parameters

s	The link state.
now_ms	The time, in ms.
part	Receives the lowest part the event names, 0 to 3.
id	Receives the ID for WRONG.

Returns: The event, a SENSE_MAP_LINK_EV_* bit, or 0 for none.

◆ sense_map_link_event_back()

void sense_map_link_event_back	(	sense_map_link_t *	s,
		uint8_t	ev,
		uint8_t	part )

Put back an event sense_map_link_event() handed out that never reached the band, with the part it named.

Not once its cause is over (sense_map_link_event_stands()).

Parameters

s	The link state.
ev	The event, a SENSE_MAP_LINK_EV_* bit.
part	The part, 0 to 3.

◆ sense_map_link_event_stands()

bool sense_map_link_event_stands	(	const sense_map_link_t *	s,
		uint8_t	ev,
		uint8_t	part )

Whether the cause of event ev for part part still holds: the map refused, the part dark, or, for SILENT and WRONG, the part fitted on a link that answers.

Parameters

s	The link state.
ev	The event, a SENSE_MAP_LINK_EV_* bit.
part	The part, 0 to 3.

Returns: true while the cause of the event holds.

◆ sense_map_link_held()

bool sense_map_link_held ( const sense_map_link_t * s )

Whether the page holds the map asked: read since link-up, not refused, and nothing owed.

False on an IOmcu older than 4.25.

Parameters

s	The link state.

Returns: true when the page holds the map asked.

◆ sense_map_link_in_force()

bool sense_map_link_in_force ( const sense_map_link_t * s )

Whether the IOmcu goes by a map written to it, not the one derived from SENSE: FLAGS' IN_FORCE as last read, or a write taken since.

False before the page is read and on an IOmcu older than 4.25.

Parameters

s	The link state.

Returns: true when the IOmcu goes by the map written to it.

◆ sense_map_link_init()

void sense_map_link_init ( sense_map_link_t * s )

Sets up the SENSE_MAP link state.

Parameters

s	The link state to set up.

◆ sense_map_link_lost()

void sense_map_link_lost ( sense_map_link_t * s )

The link went: nothing on the page is known.

Parameters

s	The link state.

◆ sense_map_link_mirror_dmohm()

uint16_t sense_map_link_mirror_dmohm	(	const sense_map_link_t *	s,
		unsigned	ch )

The shunt in 0.1mOhm of CH ch (1 to 3) of the part SENSE mirrors, as the page holds the map: the part SENSE's CLIPPED flag and SERVO_SENSE are about.

0 without a map read, or for no such part.

Parameters

s	The link state.
ch	The channel, 1 to 3.

Returns: The shunt in 0.1mOhm, or 0 without a map read or for no such part.

◆ sense_map_link_next()

bool sense_map_link_next	(	sense_map_link_t *	s,
		uint32_t	now_ms,
		bool	idle,
		sense_map_link_op_t *	op )

The next exchange owed at now_ms into op; false for none.

The write goes only while idle.

Parameters

s	The link state.
now_ms	The time, in ms.
idle	true while the bus is idle.
op	Receives the exchange owed.

Returns: true when an exchange is owed.

◆ sense_map_link_page()

bool sense_map_link_page ( const sense_map_link_t * s )

Whether the IOmcu has the page: up, 4.25 or later, and no read refused.

Parameters

s	The link state.

Returns: true when the IOmcu has the page.

◆ sense_map_link_part()

sens_part_t sense_map_link_part	(	const sense_map_link_t *	s,
		const sense_link_t *	sl,
		unsigned	a,
		unsigned	mirror,
		uint32_t	now_ms )

What fitted part a is doing at now_ms, a sens_part_t.

sl is SENSE's link, which reads the mirror part mirror (0 to 3, 0xFF none) on an IOmcu older than 4.25.

Parameters

s	The link state.
sl	The SENSE link.
a	The fitted part, 0 to 3.
mirror	The part SENSE mirrors, 0 to 3, or 0xFF for none.
now_ms	The time, in ms.

Returns: What fitted part a is doing, as sens_part_t.

◆ sense_map_link_status()

uint16_t sense_map_link_status	(	const sense_map_link_t *	s,
		const sense_link_t *	sl,
		unsigned	mirror,
		uint32_t	now_ms )

The four parts' sense_map_link_part(), 4 bits each, part 0 lowest; SENS_PART_UNKNOWN for a part not fitted.

Parameters

s	The link state.
sl	The SENSE link.
mirror	The part SENSE mirrors, 0 to 3, or 0xFF for none.
now_ms	The time, in ms.

Returns: The four parts' sense_map_link_part() values, 4 bits each, part 0 lowest.

◆ sense_map_link_take_reread()

bool sense_map_link_take_reread ( sense_map_link_t * s )

Whether a write was taken since the last call: SENSE's set-up is to be read again.

Cleared.

Parameters

s	The link state.

Returns: true when a write was taken since the last call.

◆ sense_map_link_waits_for_pins()

bool sense_map_link_waits_for_pins	(	const sense_map_link_t *	s,
		const sense_link_t *	sl )

Whether the map waits for SENSE's pins: it enables a part while SENSE has not been read since link-up or the sensor bus's pins it holds are not the ones asked.

The page judges a map against the pins it holds, so SENSE writes them first.

Parameters

s	The link state.
sl	The SENSE link.

Returns: true when the map waits for SENSE's pins.

◆ sense_map_link_want()

void sense_map_link_want	(	sense_map_link_t *	s,
		const sense_map_want_t *	w,
		uint32_t	now_ms )

The map SENSORS asks for now.

Parameters

s	The link state.
w	The map to ask for.
now_ms	The time, in ms.

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ SENS_PART_OF

Enumeration Type Documentation

◆ anonymous enum

◆ sens_part_t

◆ sense_map_link_op_kind_t

Function Documentation

◆ sense_map_link_came_up()

◆ sense_map_link_done()

◆ sense_map_link_event()

◆ sense_map_link_event_back()

◆ sense_map_link_event_stands()

◆ sense_map_link_held()

◆ sense_map_link_in_force()

◆ sense_map_link_init()

◆ sense_map_link_lost()

◆ sense_map_link_mirror_dmohm()

◆ sense_map_link_next()

◆ sense_map_link_page()

◆ sense_map_link_part()

◆ sense_map_link_status()

◆ sense_map_link_take_reread()

◆ sense_map_link_waits_for_pins()

◆ sense_map_link_want()