sense_limit_link.h File Reference

The panel's half of SENSE_LIMIT (0x36, protocol 4.27): a current limit per INA3221 channel, and the channels whose 50ms window passed it. More...

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

Go to the source code of this file.

Data Structures
struct	sense_limit_link_op_t
	One exchange for the caller to make. More...
struct	sense_limit_link_t
	The service's state; zeroed by sense_limit_link_init(). More...

Macros
#define	SENSE_LIMIT_LINK_SETTLE_MS   500u
	A limit edit rests this long before it is written, ms.
#define	SENSE_LIMIT_LINK_READ_MS   200u
	OVER is read this often while a limit is held, ms.
#define	SENSE_LIMIT_LINK_GAP_MS   5000u
	At most one alert this often, ms.
#define	SENSE_LIMIT_LINK_REPEAT_MS   30000u
	A channel's alert again at most this often while it keeps passing, ms.
#define	SENSE_LIMIT_LINK_ACK   0
	sense_limit_link_done()'s results besides a NACK's reason: the exchange answered, or not answered.
#define	SENSE_LIMIT_LINK_NO_ANSWER   (-1)
	sense_limit_link_done()'s result for an exchange not answered.

Enumerations
enum	sense_limit_link_op_kind_t { SENSE_LIMIT_LINK_OP_NONE = 0 , SENSE_LIMIT_LINK_OP_READ , SENSE_LIMIT_LINK_OP_WRITE , SENSE_LIMIT_LINK_OP_OVER }
	The exchanges the page is served with. More...
enum	sense_limit_link_ev_t { SENSE_LIMIT_LINK_EV_NONE = 0 , SENSE_LIMIT_LINK_EV_OVER , SENSE_LIMIT_LINK_EV_LOST , SENSE_LIMIT_LINK_EV_REFUSED }
	What sense_limit_link_event() hands out. More...
enum	sense_limit_st_t {   SENSE_LIMIT_ST_UNKNOWN = 0 , SENSE_LIMIT_ST_HELD , SENSE_LIMIT_ST_PENDING , SENSE_LIMIT_ST_REFUSED ,   SENSE_LIMIT_ST_OLD }
	What SETUP > SENSORS shows of the limits (sensors_rows_set_limits()). More...

Functions
void	sense_limit_link_init (sense_limit_link_t *s)
	Clears the service: no link, no limits asked.
void	sense_limit_link_lost (sense_limit_link_t *s)
	The link went: what was read is no longer the IOmcu's.
void	sense_limit_link_came_up (sense_limit_link_t *s, uint16_t minor, uint32_t now_ms)
	An IOmcu answered.
void	sense_limit_link_want (sense_limit_link_t *s, const uint16_t *ma, uint32_t now_ms)
	The limits SETUP > SENSORS asks. A change clears a refusal.
bool	sense_limit_link_next (sense_limit_link_t *s, uint32_t now_ms, sense_limit_link_op_t *op)
	The next exchange owed.
void	sense_limit_link_done (sense_limit_link_t *s, int result, const uint16_t *regs, uint32_t now_ms)
	How the exchange sense_limit_link_next() named went.
sense_limit_link_ev_t	sense_limit_link_event (sense_limit_link_t *s, uint32_t now_ms, unsigned *ch, uint16_t *ma)
	The next band alert.
uint16_t	sense_limit_link_held_ma (const sense_limit_link_t *s, unsigned ch)
	A channel's limit the page holds.
sense_limit_st_t	sense_limit_link_status (const sense_limit_link_t *s)
	What SETUP > SENSORS shows of the limits.
uint16_t	sense_limit_link_unheld (const sense_limit_link_t *s)
	The channels whose LIMIT row SETUP marks.

Detailed Description

The panel's half of SENSE_LIMIT (0x36, protocol 4.27): a current limit per INA3221 channel, and the channels whose 50ms window passed it.

An alert only: a limit passed stops nothing and drives nothing.

1. At link-up the page is read whole, registers 0 to 15. An IOmcu older than 4.27 is sent nothing; one that names 4.27 or later and refuses the page with BAD_PAGE is sent nothing more until the next link-up, and that is said as a refusal.
2. The limits asked (SETUP > SENSORS' LIMIT rows, in mA) are written, registers 0 to 11 in one write, SENSE_LIMIT_LINK_SETTLE_MS after the last edit, in any bank state, and only where the page holds something else. While the page holds a limit, one OVER read goes first, so the bits judged under the old limits are taken with them. A refused write is said once and not written again until the next edit.
3. While the page holds a limit that is not 0, OVER and OVER_COUNT (registers 12 and 13) are read every SENSE_LIMIT_LINK_READ_MS. A read clears OVER on the IOmcu, so its bits are taken here once, each with the limit the page held when it was read.

What the band is told, at most one alert every SENSE_LIMIT_LINK_GAP_MS:

• a channel over its limit, once per SENSE_LIMIT_LINK_REPEAT_MS while it keeps passing it: the bits of a channel told within that time are dropped. Channels take turns from the one after the channel told last, so twelve that keep passing are each told within twelve gaps;
• OVER_COUNT moved with no bit to show for it: a reply carrying the bits was lost. An unanswered exchange takes the link down, so the count is kept across a lost link and compared at the link-up read: OVER 0 and a count that moved and is not 0. A count of 0 is an IOmcu that started again with no window over since; one that had windows over since names them in OVER;
• the limits refused, by a write or by BAD_PAGE.

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

SPDX-License-Identifier: MIT

Enumeration Type Documentation

sense_limit_link_ev_t

enum sense_limit_link_ev_t

What sense_limit_link_event() hands out.

Enumerator
SENSE_LIMIT_LINK_EV_OVER	channel *ch passed its limit
SENSE_LIMIT_LINK_EV_LOST	a channel passed; which was lost
SENSE_LIMIT_LINK_EV_REFUSED	the limits were refused

sense_limit_link_op_kind_t

enum sense_limit_link_op_kind_t

The exchanges the page is served with.

Enumerator
SENSE_LIMIT_LINK_OP_READ	registers 0 to 15
SENSE_LIMIT_LINK_OP_WRITE	registers 0 to 11
SENSE_LIMIT_LINK_OP_OVER	registers 12 and 13

sense_limit_st_t

enum sense_limit_st_t

What SETUP > SENSORS shows of the limits (sensors_rows_set_limits()).

Enumerator
SENSE_LIMIT_ST_UNKNOWN	no link, or not read yet
SENSE_LIMIT_ST_HELD	the page holds the limits asked
SENSE_LIMIT_ST_PENDING	a write is owed
SENSE_LIMIT_ST_REFUSED	the page refused them
SENSE_LIMIT_ST_OLD	the IOmcu has no SENSE_LIMIT

Function Documentation

sense_limit_link_came_up()

void sense_limit_link_came_up	(	sense_limit_link_t *	s,
		uint16_t	minor,
		uint32_t	now_ms )

An IOmcu answered.

Parameters

s	the service; NULL does nothing.
minor	its protocol minor; below LINK_MINOR_SENSE_LIMIT (27) the page is sent nothing.
now_ms	the time, ms; a limit asked before rests from it.

sense_limit_link_done()

void sense_limit_link_done	(	sense_limit_link_t *	s,
		int	result,
		const uint16_t *	regs,
		uint32_t	now_ms )

How the exchange sense_limit_link_next() named went.

Parameters

s	the service; NULL does nothing.
result	SENSE_LIMIT_LINK_ACK, a NACK's reason (LINK_NACK_*), or SENSE_LIMIT_LINK_NO_ANSWER.
regs	for an answered read, the registers it asked for; else NULL.
now_ms	the time, ms.

sense_limit_link_event()

sense_limit_link_ev_t sense_limit_link_event	(	sense_limit_link_t *	s,
		uint32_t	now_ms,
		unsigned *	ch,
		uint16_t *	ma )

The next band alert.

Parameters

s	the service.
now_ms	the time, ms.
ch	for EV_OVER the channel, 0 to 11; may be NULL.
ma	for EV_OVER the limit the window was judged by, mA; may be NULL.

Returns

the alert; EV_NONE for none, for a NULL s and while the last is younger than SENSE_LIMIT_LINK_GAP_MS.

sense_limit_link_held_ma()

uint16_t sense_limit_link_held_ma	(	const sense_limit_link_t *	s,
		unsigned	ch )

A channel's limit the page holds.

Parameters

s	the service.
ch	the channel, 0 to 11.

Returns

the limit, mA; 0 for none, not read, or ch out of range.

sense_limit_link_init()

void sense_limit_link_init

(

sense_limit_link_t *

s

)

Clears the service: no link, no limits asked.

Parameters

s	the service; NULL does nothing.

sense_limit_link_lost()

void sense_limit_link_lost

(

sense_limit_link_t *

s

)

The link went: what was read is no longer the IOmcu's.

The limits asked stay, and OVER_COUNT as last read, for the link-up read.

Parameters

s	the service; NULL does nothing.

sense_limit_link_next()

bool sense_limit_link_next	(	sense_limit_link_t *	s,
		uint32_t	now_ms,
		sense_limit_link_op_t *	op )

The next exchange owed.

Parameters

s	the service.
now_ms	the time, ms.
op	where the exchange goes; zeroed for none.

Returns

true for an exchange to make and report to sense_limit_link_done(); false for none, and for a NULL s or op.

sense_limit_link_status()

sense_limit_st_t sense_limit_link_status

(

const sense_limit_link_t *

s

)

What SETUP > SENSORS shows of the limits.

Parameters

s	the service.

Returns

the status; SENSE_LIMIT_ST_UNKNOWN with no link or a NULL s.

sense_limit_link_unheld()

uint16_t sense_limit_link_unheld

(

const sense_limit_link_t *

s

)

The channels whose LIMIT row SETUP marks.

Parameters

s	the service.

Returns

bit c for channel c: on an IOmcu without the page every limit asked that is not 0; else, once the page is read, every limit the page holds otherwise than asked, owed or refused. 0 with no link.

sense_limit_link_want()

void sense_limit_link_want	(	sense_limit_link_t *	s,
		const uint16_t *	ma,
		uint32_t	now_ms )

The limits SETUP > SENSORS asks. A change clears a refusal.

Parameters

s	the service; NULL does nothing.
ma	LIMIT_MA[0] to [11], mA, 0 for none; above 32767 taken as NULL does nothing.
now_ms	the time, ms; a change rests SENSE_LIMIT_LINK_SETTLE_MS from it.