safety_gate.c File Reference

SPDX-License-Identifier: MIT. More...

#include "safety_gate.h"
#include <stddef.h>
#include "link_control.h"
#include "link_msg.h"
#include "link_pages.h"

Functions
bool	safety_gate_may_arm (const heartbeat_mon_t *beat, const link_dev_t *dev)
	Whether a write of ARM is taken: heartbeat trusted, link out of failsafe, latch clear.
bool	safety_gate_supply_ok (const heartbeat_mon_t *beat, const link_dev_t *dev)
	Whether the supply's output may be on: heartbeat trusted and link out of failsafe.
safety_gate_t	safety_gate_step (heartbeat_mon_t *beat, bool line_edge, link_dev_t *dev, uint16_t *control, uint32_t now_ms)
	One pass of the main loop, after the link has been served.
bool	safety_gate_arm_now (bool gate_arm, uint16_t quiet_mask, bool update_holds)
	Whether the bank is armed for this pass: the pass's decision (safety_gate_t.arm, gate_arm) and two holds only the firmware can see.
uint8_t	safety_gate_control_write (uint16_t *control, uint8_t off, uint8_t n, const uint16_t *in, const heartbeat_mon_t *beat, link_dev_t *dev)
	A write to the CONTROL page: link_control_write() with this end's answer to whether the bench may arm, and the CLEAR acted on.
void	safety_gate_status (const heartbeat_mon_t *beat, const link_dev_t *dev, const uint16_t *control, uint16_t *state, uint16_t *faults)
	The STATUS page's state register and the two fault bits this decision owns (LINK_FAULT_LINK_SILENT, LINK_FAULT_HEARTBEAT).
bool	safety_gate_line_trusted (uint16_t faults)
	The panel's reading of a STATUS fault bitmap: whether the far end trusts the heartbeat.

Detailed Description

SPDX-License-Identifier: MIT.

Function Documentation

safety_gate_arm_now()

bool safety_gate_arm_now	(	bool	gate_arm,
		uint16_t	quiet_mask,
		bool	update_holds )

Whether the bank is armed for this pass: the pass's decision (safety_gate_t.arm, gate_arm) and two holds only the firmware can see.

Not while a programming port is out of PWM (quiet_mask, the ports kst_port_quiet_mask() names, non-zero): programming and an armed bank are exclusive at this end too, and the port takes no ENTER while the bank is armed.

Nor while a firmware update runs or its image waits for BUY (update_holds): the control page refuses the ARM, and this holds the bank down for an ARM written before the session began.

True only when gate_arm is true, quiet_mask is 0 and update_holds is false.

Parameters

gate_arm	The pass's arm decision.
quiet_mask	Programming ports out of PWM; 0 when none.
update_holds	true while a firmware update holds the bank down.

Returns

true when the bank may be armed.

safety_gate_control_write()

uint8_t safety_gate_control_write	(	uint16_t *	control,
		uint8_t	off,
		uint8_t	n,
		const uint16_t *	in,
		const heartbeat_mon_t *	beat,
		link_dev_t *	dev )

A write to the CONTROL page: link_control_write() with this end's answer to whether the bench may arm, and the CLEAR acted on.

An ARM refused with LINK_NACK_NOT_ARMED sets the latch. A CLEAR acknowledged while the heartbeat is not yet trusted is followed by such a refusal, and the line becoming trusted a few milliseconds later would otherwise leave this end unlatched with nobody armed.

Returns 0 when the window is stored, else the NACK reason.

Parameters

control	CONTROL page, LINK_CT_COUNT registers.
off	First register of the window.
n	Registers in the window.
in	The window's values.
beat	Heartbeat monitor.
dev	Link device state.

Returns

0 when the window is stored, else the NACK reason.

safety_gate_line_trusted()

bool safety_gate_line_trusted

(

uint16_t

faults

)

The panel's reading of a STATUS fault bitmap: whether the far end trusts the heartbeat.

Parameters

faults

STATUS fault bitmap.

Returns

true when the heartbeat is trusted.

safety_gate_may_arm()

bool safety_gate_may_arm	(	const heartbeat_mon_t *	beat,
		const link_dev_t *	dev )

Whether a write of ARM is taken: heartbeat trusted, link out of failsafe, latch clear.

Parameters

beat	Heartbeat monitor.
dev	Link device state.

Returns

true when an ARM is taken.

safety_gate_status()

void safety_gate_status	(	const heartbeat_mon_t *	beat,
		const link_dev_t *	dev,
		const uint16_t *	control,
		uint16_t *	state,
		uint16_t *	faults )

The STATUS page's state register and the two fault bits this decision owns (LINK_FAULT_LINK_SILENT, LINK_FAULT_HEARTBEAT).

The latch is not reported: after a start the state is idle and both bits are clear.

Parameters

beat	Heartbeat monitor.
dev	Link device state.
control	CONTROL page, LINK_CT_COUNT registers.
state	Receives the state register.
faults	Receives the fault bitmap.

safety_gate_step()

safety_gate_t safety_gate_step	(	heartbeat_mon_t *	beat,
		bool	line_edge,
		link_dev_t *	dev,
		uint16_t *	control,
		uint32_t	now_ms )

One pass of the main loop, after the link has been served.

line_edge is whether the heartbeat pin changed level since the last pass. control is the CONTROL page, LINK_CT_COUNT registers: on an off edge ARM and THROTTLE are zeroed there, so a read shows what the bank holds. Both watchdogs are judged before the arm, so a pass never arms on the answer of the pass before.

Parameters

beat	Heartbeat monitor.
line_edge	true when the heartbeat pin changed level.
dev	Link device state.
control	CONTROL page, LINK_CT_COUNT registers.
now_ms	Current time, in milliseconds.

Returns

The decision of this pass.

safety_gate_supply_ok()

bool safety_gate_supply_ok	(	const heartbeat_mon_t *	beat,
		const link_dev_t *	dev )

Whether the supply's output may be on: heartbeat trusted and link out of failsafe.

The arm latch is not part of it.

Parameters

beat	Heartbeat monitor.
dev	Link device state.

Returns

true when the supply may be on.