supply_page.h File Reference

The SUPPLY link page at the IOmcu: a PD mini on a PIO UART, its wiring, what it is to do and what it last said. More...

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

Go to the source code of this file.

Data Structures
struct	supply_page_t
	The SUPPLY page state: registers, and the wiring change in hand. More...
struct	supply_port_view_t
	The supply as a programming port sees it (kst_port.h). More...

Macros
#define	SUPPLY_BAUD_COUNT   7u
	The module's UART Baudrate settings, 0 to 6, and 7 to find it.
#define	SUPPLY_BAUD_AUTO   7u
#define	SUPPLY_PAGE_OFF_WAIT_MS   12u
	The longest an OFF waits for a programming port's frame to end, in ms.

Enumerations
enum	supply_wire_t { SUPPLY_WIRE_IDLE = 0 , SUPPLY_WIRE_WAIT , SUPPLY_WIRE_READY }
	Where a wiring change that waits for a state read is. More...

Functions
uint32_t	supply_page_baud (uint16_t setting)
	The baud rate of a UART setting.
void	supply_page_init (supply_page_t *p)
	Clears the page to its start: BAUD 1 (19200), BAUD_FOUND AUTO, the scan at 1.
uint8_t	supply_page_rate (supply_page_t *p, const pdmini_t *drv)
	The rate the UART is to run at now, 0 to 6.
uint32_t	supply_page_uart_baud (const supply_page_t *p)
	The baud the UART is to be opened at now.
uint8_t	supply_page_write (supply_page_t *p, uint8_t off, uint8_t n, const uint16_t *in, const outputs_t *o, bool beat_alive)
	A write, validated whole before any of it is stored.
void	supply_page_follow (supply_page_t *p, const pdmini_t *drv)
	What the driver says now, straight before a write is judged: FLAGS bit 6 (the output on or maybe on) and whether its module has answered.
bool	supply_page_wire_ready (const supply_page_t *p, uint16_t *regs)
	The wiring change whose state read showed the output off, into regs (ENABLE to BAUD): true while one is SUPPLY_WIRE_READY.
uint8_t	supply_page_wire_write (supply_page_t *p, const outputs_t *o)
	The ready wiring written: judged whole as a link write is, against the driver's state as supply_page_follow() last took it, without waiting again. 0, or the NACK reason, which refuses it (FLAGS bit 9).
void	supply_page_wire_refuse (supply_page_t *p)
	The ready wiring could not be put in force after it was written (no UART for its pins): refused, FLAGS bit 9, as a refused read is.
uint8_t	supply_page_slots_check (const supply_page_t *p, const uint16_t *slots)
	LINK_NACK_BAD_VALUE for an OUTPUTS page (slots, LINK_OS_COUNT registers) that binds a slot to a pin the supply holds; 0 otherwise.
void	supply_page_read (const supply_page_t *p, uint8_t off, uint8_t n, uint16_t *out)
	Copies registers of the SUPPLY page.
bool	supply_page_enabled (const supply_page_t *p)
	Whether the page drives a supply, and on which pins.
uint8_t	supply_page_tx (const supply_page_t *p)
	The TX pin register, as a GPIO number.
uint8_t	supply_page_rx (const supply_page_t *p)
	The RX pin register, as a GPIO number.
uint64_t	supply_page_pins (const supply_page_t *p)
	The pins it holds, as a reservation mask; 0 while not enabled.
void	supply_page_step (supply_page_t *p, bool beat_alive, pdmini_t *drv)
	One pass: the output off without a heartbeat, what the driver is to do, and what it last said into the read-only registers.
void	supply_page_port_view (const supply_page_t *p, supply_port_view_t *out)
	The page as of the last supply_page_step(), for a programming port.
bool	supply_page_port_set (supply_page_t *p, bool on, uint16_t mv, uint16_t ma, bool beat_alive)
	A programming port's request, in place of a link write of OUTPUT to SET_MA.
void	supply_page_hold (supply_page_t *p, bool held)
	Whether a programming port holds the command registers (FLAGS bit 11, LINK_SP_PORT).
void	supply_page_port_frame (supply_page_t *p, bool frame_out, uint32_t now_ms)
	Whether a programming port has a frame on the wire, and the clock, once a pass before supply_page_step().

Detailed Description

The SUPPLY link page at the IOmcu: a PD mini on a PIO UART, its wiring, what it is to do and what it last said.

The registers are in link_pages.h (LINK_SP_*).

The wiring is refused while the output is on, and on pins an output or the board already holds; the pins it takes are reserved from the outputs for as long as it holds them (supply_page_pins()). A change while a module has answered waits for a state read sent after it (pdmini_check_off()): taken if that read shows the output off, refused if it shows it on or fails. FLAGS bit 8 says it waits, bit 9 that the last one was refused. The output switches on only with a live heartbeat from the panel and goes off when that stops, so a panel that dies leaves no supply running.

Host-tested; the IOmcu is wiring: it runs the PIO UART, feeds the driver and calls supply_page_step() every pass.

SPDX-License-Identifier: MIT

Macro Definition Documentation

SUPPLY_PAGE_OFF_WAIT_MS

#define SUPPLY_PAGE_OFF_WAIT_MS   12u

The longest an OFF waits for a programming port's frame to end, in ms.

A frame of the port and its answer are shorter; how long a servo needs after a frame to store a register is not measured.

Enumeration Type Documentation

supply_wire_t

enum supply_wire_t

Where a wiring change that waits for a state read is.

Enumerator
SUPPLY_WIRE_IDLE	none waits
SUPPLY_WIRE_WAIT	waits for the driver's state read
SUPPLY_WIRE_READY	the read showed off: to be written now

Function Documentation

supply_page_baud()

uint32_t supply_page_baud

(

uint16_t

setting

)

The baud rate of a UART setting.

Parameters

setting

UART setting, 0 to SUPPLY_BAUD_COUNT - 1.

Returns

9600, 19200, 38400, 57600, 115200, 230400 or 460800 for settings 0 to 6; 0 for a setting of 7 or more, including SUPPLY_BAUD_AUTO.

supply_page_enabled()

bool supply_page_enabled

(

const supply_page_t *

p

)

Whether the page drives a supply, and on which pins.

Parameters

p	The page state.

Returns

true when ENABLE is not 0, false otherwise or for NULL.

supply_page_follow()

void supply_page_follow	(	supply_page_t *	p,
		const pdmini_t *	drv )

What the driver says now, straight before a write is judged: FLAGS bit 6 (the output on or maybe on) and whether its module has answered.

drv NULL for no driver: nothing answered, nothing on. supply_page_step() does the same every pass.

Parameters

p	The page state, updated.
drv	The PD mini driver, or NULL.

supply_page_hold()

void supply_page_hold	(	supply_page_t *	p,
		bool	held )

Whether a programming port holds the command registers (FLAGS bit 11, LINK_SP_PORT).

While it does, supply_page_write() takes an OFF, which leaves SET_MV and SET_MA as they are whatever the write names, and refuses every other write of OUTPUT to SET_MA that changes one of the three with LINK_NACK_BAD_VALUE: the panel can switch the supply off, and cannot switch it on or move a set point under the servo.

Parameters

p	The page state. Nothing is done when NULL.
held	true while the programming port holds the registers.

supply_page_init()

void supply_page_init

(

supply_page_t *

p

)

Clears the page to its start: BAUD 1 (19200), BAUD_FOUND AUTO, the scan at 1.

Nothing is done when p is NULL.

Parameters

p	The page state, overwritten.

supply_page_pins()

uint64_t supply_page_pins

(

const supply_page_t *

p

)

The pins it holds, as a reservation mask; 0 while not enabled.

Parameters

p	The page state.

Returns

Bits for the TX and RX pins, 0 when not enabled or for NULL.

supply_page_port_frame()

void supply_page_port_frame	(	supply_page_t *	p,
		bool	frame_out,
		uint32_t	now_ms )

Whether a programming port has a frame on the wire, and the clock, once a pass before supply_page_step().

An OFF taken while one is – written by the panel or forced by a lost heartbeat – reaches the driver when the frame has ended, SUPPLY_PAGE_OFF_WAIT_MS after it was asked at the latest. OUTPUT reads 0 from the moment it is asked.

Parameters

p	The page state. Nothing is done when NULL.
frame_out	true while a frame is on the wire.
now_ms	Current time in milliseconds.

supply_page_port_set()

bool supply_page_port_set	(	supply_page_t *	p,
		bool	on,
		uint16_t	mv,
		uint16_t	ma,
		bool	beat_alive )

A programming port's request, in place of a link write of OUTPUT to SET_MA.

Off is always taken and leaves the set points. On is refused (false, nothing changed) without a live heartbeat, while the supply is not wired or a wiring change waits, for set points outside the module's range, and for a voltage above SET_MV while OUTPUT is 1: the voltage of an output that is on is not raised here.

Parameters

p	The page state.
on	true for ON, false for OFF.
mv	Set voltage in millivolts, for ON.
ma	Set current in milliamps, for ON.
beat_alive	Whether the panel's heartbeat is live.

Returns

true when taken. false for NULL, an ON that is refused (see above), otherwise true for an OFF.

supply_page_port_view()

void supply_page_port_view	(	const supply_page_t *	p,
		supply_port_view_t *	out )

The page as of the last supply_page_step(), for a programming port.

Parameters

p	The page state.
out	Receives the view. Zeroed first; nothing else is done when p is NULL. Nothing is done when out is NULL.

supply_page_rate()

uint8_t supply_page_rate	(	supply_page_t *	p,
		const pdmini_t *	drv )

The rate the UART is to run at now, 0 to 6.

The setting itself, or under AUTO the one being tried: the next after every WHO_AM_I drv reports without a valid answer, until a module has answered once, from when the rate holds. Publishes it in BAUD_FOUND – 7 while AUTO has found none. drv NULL leaves the scan where it is.

Parameters

p	The page state. BAUD_FOUND is updated.
drv	The PD mini driver, or NULL.

Returns

The setting, 0 to 6. 1 for a NULL p.

supply_page_read()

void supply_page_read	(	const supply_page_t *	p,
		uint8_t	off,
		uint8_t	n,
		uint16_t *	out )

Copies registers of the SUPPLY page.

Nothing is done when p or out is NULL, or when off and n reach past LINK_SP_COUNT.

Parameters

p	The page state, not changed.
off	First register, 0 to LINK_SP_COUNT - 1.
n	Number of registers to copy.
out	Receives the n register values.

supply_page_rx()

uint8_t supply_page_rx

(

const supply_page_t *

p

)

The RX pin register, as a GPIO number.

Parameters

p	The page state.

Returns

The pin, 0 for NULL.

supply_page_slots_check()

uint8_t supply_page_slots_check	(	const supply_page_t *	p,
		const uint16_t *	slots )

LINK_NACK_BAD_VALUE for an OUTPUTS page (slots, LINK_OS_COUNT registers) that binds a slot to a pin the supply holds; 0 otherwise.

Checked before the page is stored, so no binding is kept that the bank would leave unbound – and that a restart, with the supply not yet wired, would drive on the module's pin.

Parameters

p	The page state.
slots	The OUTPUTS page, LINK_OS_COUNT registers.

Returns

LINK_NACK_BAD_VALUE for a NULL slots or a slot with a driver on a pin in supply_page_pins(), 0 otherwise.

supply_page_step()

void supply_page_step	(	supply_page_t *	p,
		bool	beat_alive,
		pdmini_t *	drv )

One pass: the output off without a heartbeat, what the driver is to do, and what it last said into the read-only registers.

drv may be NULL while no supply is wired. A wiring change waiting asks the driver for its state read and follows the answer: off makes it SUPPLY_WIRE_READY, anything else refuses it (FLAGS bit 9). With no driver it is ready: nothing is attached to the module to switch it off.

Parameters

p	The page state. Nothing is done when NULL.
beat_alive	Whether the panel's heartbeat is live.
drv	The PD mini driver, or NULL.

supply_page_tx()

uint8_t supply_page_tx

(

const supply_page_t *

p

)

The TX pin register, as a GPIO number.

Parameters

p	The page state.

Returns

The pin, 0 for NULL.

supply_page_uart_baud()

uint32_t supply_page_uart_baud

(

const supply_page_t *

p

)

The baud the UART is to be opened at now.

Parameters

p	The page state.

Returns

supply_page_baud() of the rate from supply_page_rate()'s rules, or 0 for NULL.

supply_page_wire_ready()

bool supply_page_wire_ready	(	const supply_page_t *	p,
		uint16_t *	regs )

The wiring change whose state read showed the output off, into regs (ENABLE to BAUD): true while one is SUPPLY_WIRE_READY.

The caller writes it with supply_page_wire_write() in the same pass.

Parameters

p	The page state.
regs	Receives the four wiring registers, ENABLE to BAUD. Not written when false is returned.

Returns

true when a change is ready and regs is filled, false otherwise or for NULL.

supply_page_wire_refuse()

void supply_page_wire_refuse

(

supply_page_t *

p

)

The ready wiring could not be put in force after it was written (no UART for its pins): refused, FLAGS bit 9, as a refused read is.

Parameters

p	The page state. Nothing is done when NULL.

supply_page_wire_write()

uint8_t supply_page_wire_write	(	supply_page_t *	p,
		const outputs_t *	o )

The ready wiring written: judged whole as a link write is, against the driver's state as supply_page_follow() last took it, without waiting again. 0, or the NACK reason, which refuses it (FLAGS bit 9).

Parameters

p	The page state.
o	The outputs bank, for the pins.

Returns

0 when written. LINK_NACK_BAD_VALUE when no change is ready, or the refusal of the page write otherwise.

supply_page_write()

uint8_t supply_page_write	(	supply_page_t *	p,
		uint8_t	off,
		uint8_t	n,
		const uint16_t *	in,
		const outputs_t *	o,
		bool	beat_alive )

A write, validated whole before any of it is stored.

Refused: off the page (BAD_RANGE); a read-only register (READ_ONLY); a wiring change while the output is asked on or may be on, a pin past the bank, reserved, bound to an output or the other pin, a baud setting past 7 (AUTO), an ON without the supply enabled or without its set points in the same frame, a set point above the module's range, an ON while a wiring change waits, a wiring change that waits in the same frame as OUTPUT to SET_MA (BAD_VALUE); an ON without a live heartbeat (NOT_ARMED).

A wiring change that passes, while the driver's module has answered (supply_page_follow()), is acknowledged and not yet taken: it waits (SUPPLY_WIRE_WAIT, FLAGS bit 8) for a state read the next supply_page_step() asks of the driver. Another change replaces it and is read for again; a write of the wiring in force drops it.

Parameters

p	The page state, changed only when the write is taken.
off	First register, 0 to LINK_SP_COUNT - 1.
n	Number of registers to write. 0 is taken with no change.
in	The n new register values.
o	The outputs bank, for the pins a wiring change takes.
beat_alive	Whether the panel's heartbeat is live.

Returns

0 when taken, or when the write waits for a state read. The NACK reason otherwise: LINK_NACK_BAD_RANGE, LINK_NACK_READ_ONLY, LINK_NACK_BAD_VALUE or LINK_NACK_NOT_ARMED, as listed above.