arq.h File Reference

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "arq_events.h"

Include dependency graph for arq.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	arq_info
	Runtime ARQ connection and mode state shared across modules. More...
struct	arq_keydown_t
struct	arq_action_t
	Single modem action item popped by modem TX worker. More...
struct	arq_runtime_snapshot_t
	Snapshot of current ARQ runtime state for telemetry/decision making. More...

Macros
#define	CALLSIGN_MAX_SIZE   16
#define	CALLSIGN_MAX_SECONDARY   4
#define	ARQ_BANDWIDTH_NARROW_HZ   500
#define	ARQ_BANDWIDTH_FULL_HZ   2300
#define	ARQ_BANDWIDTH_TACTICAL_HZ   2750
#define	RX   0
#define	TX   1
#define	HEADER_SIZE   1
#define	PACKET_ARQ_CONTROL   0x00
#define	PACKET_ARQ_DATA   0x01
#define	PACKET_ARQ_CALL   0x02
#define	PACKET_BROADCAST_CONTROL   0x03
#define	PACKET_BROADCAST_PAYLOAD   0x04
#define	ARQ_NAV_GAP_MS   60
#define	ARQ_NAV_LEAD_MS   (640 + ARQ_NAV_GAP_MS)
#define	ARQ_KEYDOWN_FRAMES   17
#define	ARQ_KEYDOWN_FRAME_MAX   1280

Enumerations
enum	arq_action_type_t {   ARQ_ACTION_NONE = 0 , ARQ_ACTION_TX_CONTROL = 1 , ARQ_ACTION_TX_PAYLOAD = 2 , ARQ_ACTION_MODE_SWITCH = 3 ,   ARQ_ACTION_TX_KEYDOWN = 4 , ARQ_ACTION_TX_PATTERN = 5 }
	Action types emitted by ARQ for modem worker execution. More...
enum	arq_pattern_kind_t { ARQ_PATTERN_ACK = 0 , ARQ_PATTERN_BREAK = 1 }
	Pattern kind (ARQ_ACTION_TX_PATTERN). More...

Functions
void	arq_set_trx (int trx)
int	arq_get_trx (void)
int	arq_get_bw (void)
void	arq_conn_get_calls (char *my_call, char *src_addr, char *dst_addr, size_t bufsz)
void	arq_notify_virtual_time (void)
int	arq_init (size_t frame_size, int mode)
	Initialize ARQ subsystem.
void	arq_shutdown ()
	Shut down ARQ workers and release ARQ resources.
void	arq_tick_1hz (void)
	Execute 1 Hz ARQ maintenance tick.
void	arq_post_event (int event)
	Post an FSM event to ARQ.
void	arq_post_pattern_ack (bool is_break)
bool	arq_is_link_connected (void)
	Check whether ARQ link is connected.
void	arq_discard_stale_rx (void)
	Drop received bytes an ended session left in the RX buffer.
int	arq_reported_bandwidth_hz (void)
	Get the configured ARQ bandwidth token to report to VARA clients.
int	arq_queue_data (const uint8_t *data, size_t len)
	Queue outbound payload bytes for ARQ transmission.
int	arq_get_tx_backlog_bytes (void)
	Get pending outbound payload backlog.
void	arq_set_disconnect_drain_timeout_s (int seconds)
	Set the absolute cap on how long an app DISCONNECT may stay deferred while draining the last TX bytes.
int	arq_set_listen_mode (int mode)
void	arq_set_active_modem_mode (int mode, size_t frame_size)
	Inform ARQ of modem mode/frame size actually active in modem.
bool	arq_handle_incoming_connect_frame (uint8_t *data, size_t frame_size, float rx_snr, int mode)
	Handle an incoming CALL/ACCEPT frame (protocol version 1).
void	arq_handle_carousel_frame (const uint8_t *data, size_t frame_size, int mode, bool from_control, float rx_snr, uint32_t age_ms)
bool	arq_handle_incoming_cq_frame (uint8_t *data, size_t frame_size)
	Handle incoming compact CQ frame and emit host-side CQFRAME notification.
void	arq_notify_cq_tx_started (void)
	Emit VARA-style async status for an outgoing CQFRAME transmission.
void	arq_notify_cq_tx_complete (void)
void	arq_handle_incoming_frame (uint8_t *data, size_t frame_size, float rx_snr)
	Handle incoming regular ARQ control/data frame.
void	arq_update_link_metrics (int sync, float snr, int rx_status, bool frame_decoded)
	Feed decoder/link metrics into ARQ adaptation.
void	arq_note_rx_preamble (int mode)
	A decoder for mode has just caught a frame's preamble: the channel is busy for that frame's airtime even if the decoder then loses sync.
void	arq_note_rx_frame_done (void)
void	arq_note_rx_nav (uint32_t age_ms, uint32_t hold_ms)
	A NAV header that began age_ms ago says the peer's keydown ends within hold_ms of its start: the channel is busy until then, whether or not any of the keydown's frames can be decoded.
bool	arq_try_dequeue_action (arq_action_t *action)
	Try to dequeue next modem action without blocking.
bool	arq_wait_dequeue_action (arq_action_t *action, int timeout_ms)
	Wait for next modem action.
bool	arq_get_runtime_snapshot (arq_runtime_snapshot_t *snapshot)
	Copy ARQ runtime snapshot.
int	arq_submit_tcp_cmd (const arq_cmd_msg_t *cmd)
	Submit parsed control command from TCP bridge to ARQ.
int	arq_submit_tcp_payload (const uint8_t *data, size_t len)
	Submit payload bytes from TCP bridge to ARQ.
void	clear_connection_data ()
	Clear legacy ARQ connection state and buffers.
void	reset_arq_info (arq_info *arq_conn)
	Reset external arq_info structure.
void	arq_set_retry_slots (int slots)
	Set runtime retry slot counts.
void	arq_set_retry_stagger_ms (int ms)
void	call_remote ()
	Trigger outgoing call attempt using current ARQ addresses.
void	callee_accept_connection ()
	Trigger callee-side accept flow in compatibility path.

Variables
arq_info	arq_conn

Macro Definition Documentation

ARQ_BANDWIDTH_FULL_HZ

#define ARQ_BANDWIDTH_FULL_HZ   2300

ARQ_BANDWIDTH_NARROW_HZ

#define ARQ_BANDWIDTH_NARROW_HZ   500

ARQ_BANDWIDTH_TACTICAL_HZ

#define ARQ_BANDWIDTH_TACTICAL_HZ   2750

ARQ_KEYDOWN_FRAME_MAX

#define ARQ_KEYDOWN_FRAME_MAX   1280

ARQ_KEYDOWN_FRAMES

#define ARQ_KEYDOWN_FRAMES   17

ARQ_NAV_GAP_MS

#define ARQ_NAV_GAP_MS   60

ARQ_NAV_LEAD_MS

#define ARQ_NAV_LEAD_MS   (640 + ARQ_NAV_GAP_MS)

CALLSIGN_MAX_SECONDARY

#define CALLSIGN_MAX_SECONDARY   4

CALLSIGN_MAX_SIZE

#define CALLSIGN_MAX_SIZE   16

HEADER_SIZE

#define HEADER_SIZE   1

PACKET_ARQ_CALL

#define PACKET_ARQ_CALL   0x02

PACKET_ARQ_CONTROL

#define PACKET_ARQ_CONTROL   0x00

PACKET_ARQ_DATA

#define PACKET_ARQ_DATA   0x01

PACKET_BROADCAST_CONTROL

#define PACKET_BROADCAST_CONTROL   0x03

PACKET_BROADCAST_PAYLOAD

#define PACKET_BROADCAST_PAYLOAD   0x04

RX

#define RX   0

TX

#define TX   1

Enumeration Type Documentation

arq_action_type_t

enum arq_action_type_t

Action types emitted by ARQ for modem worker execution.

Enumerator
ARQ_ACTION_NONE
ARQ_ACTION_TX_CONTROL
ARQ_ACTION_TX_PAYLOAD
ARQ_ACTION_MODE_SWITCH
ARQ_ACTION_TX_KEYDOWN
ARQ_ACTION_TX_PATTERN

arq_pattern_kind_t

enum arq_pattern_kind_t

Pattern kind (ARQ_ACTION_TX_PATTERN).

Enumerator
ARQ_PATTERN_ACK
ARQ_PATTERN_BREAK

Function Documentation

arq_conn_get_calls()

void arq_conn_get_calls	(	char *	my_call,
		char *	src_addr,
		char *	dst_addr,
		size_t	bufsz
	)

arq_discard_stale_rx()

void arq_discard_stale_rx

(

void

)

Drop received bytes an ended session left in the RX buffer.

Does nothing while a session is up. Check and clear are one step under the session lock, so they cannot straddle a session starting.

arq_get_bw()

int arq_get_bw

(

void

)

arq_get_runtime_snapshot()

bool arq_get_runtime_snapshot

(

arq_runtime_snapshot_t *

snapshot

)

Copy ARQ runtime snapshot.

Parameters

snapshot

Output snapshot pointer.

Returns

true when snapshot contains initialized state.

arq_get_trx()

int arq_get_trx

(

void

)

arq_get_tx_backlog_bytes()

int arq_get_tx_backlog_bytes

(

void

)

Get pending outbound payload backlog.

Returns

Backlog size in bytes.

arq_handle_carousel_frame()

void arq_handle_carousel_frame	(	const uint8_t *	data,
		size_t	frame_size,
		int	mode,
		bool	from_control,
		float	rx_snr,
		uint32_t	age_ms
	)

arq_handle_incoming_connect_frame()

bool arq_handle_incoming_connect_frame	(	uint8_t *	data,
		size_t	frame_size,
		float	rx_snr,
		int	mode
	)

Handle an incoming CALL/ACCEPT frame (protocol version 1).

Parameters

data	Frame bytes.
frame_size	Frame length in bytes.
rx_snr	SNR the frame was decoded at (dB); sets the start rung.
mode	The carrier it came on (DATAC16 or MFSK); the answer goes on it.

Returns

true if frame was handled by ARQ connect path.

arq_handle_incoming_cq_frame()

bool arq_handle_incoming_cq_frame	(	uint8_t *	data,
		size_t	frame_size
	)

Handle incoming compact CQ frame and emit host-side CQFRAME notification.

Parameters

data	Incoming frame bytes.
frame_size	Frame length in bytes.

Returns

true if frame was handled by CQ path.

arq_handle_incoming_frame()

void arq_handle_incoming_frame	(	uint8_t *	data,
		size_t	frame_size,
		float	rx_snr
	)

Handle incoming regular ARQ control/data frame.

Parameters

data	Frame bytes.
frame_size	Frame length in bytes.
rx_snr	Local receive SNR at decode time (dB); 0.0 = unknown.

arq_init()

int arq_init	(	size_t	frame_size,
		int	mode
	)

Initialize ARQ subsystem.

Parameters

frame_size	Active modem frame size in bytes.
mode	Initial modem mode.

Returns

0 on success, non-zero on failure.

arq_is_link_connected()

bool arq_is_link_connected

(

void

)

Check whether ARQ link is connected.

Returns

true when connected; otherwise false.

arq_note_rx_frame_done()

void arq_note_rx_frame_done

(

void

)

arq_note_rx_nav()

void arq_note_rx_nav	(	uint32_t	age_ms,
		uint32_t	hold_ms
	)

A NAV header that began age_ms ago says the peer's keydown ends within hold_ms of its start: the channel is busy until then, whether or not any of the keydown's frames can be decoded.

arq_note_rx_preamble()

void arq_note_rx_preamble

(

int

mode

)

A decoder for mode has just caught a frame's preamble: the channel is busy for that frame's airtime even if the decoder then loses sync.

arq_note_rx_frame_done() ends it when a frame decodes.

arq_notify_cq_tx_complete()

void arq_notify_cq_tx_complete

(

void

)

arq_notify_cq_tx_started()

void arq_notify_cq_tx_started

(

void

)

Emit VARA-style async status for an outgoing CQFRAME transmission.

VARA clients such as varim treat CQFRAME as a pending operation and expect PENDING/CANCELPENDING around the actual send lifecycle.

arq_notify_virtual_time()

void arq_notify_virtual_time

(

void

)

arq_post_event()

void arq_post_event

(

int

event

)

Post an FSM event to ARQ.

Parameters

event

Event identifier from fsm.h.

arq_post_pattern_ack()

void arq_post_pattern_ack

(

bool

is_break

)

arq_queue_data()

int arq_queue_data	(	const uint8_t *	data,
		size_t	len
	)

Queue outbound payload bytes for ARQ transmission.

Parameters

data	Pointer to payload bytes.
len	Number of bytes to queue.

Returns

Number of bytes queued, or negative on error.

arq_reported_bandwidth_hz()

int arq_reported_bandwidth_hz

(

void

)

Get the configured ARQ bandwidth token to report to VARA clients.

Returns

500, 2300, or 2750 when configured; otherwise 2300.

arq_set_active_modem_mode()

void arq_set_active_modem_mode	(	int	mode,
		size_t	frame_size
	)

Inform ARQ of modem mode/frame size actually active in modem.

Parameters

mode	Active FreeDV mode.
frame_size	Active frame size in bytes.

arq_set_disconnect_drain_timeout_s()

void arq_set_disconnect_drain_timeout_s

(

int

seconds

)

Set the absolute cap on how long an app DISCONNECT may stay deferred while draining the last TX bytes.

Parameters

seconds

Window in seconds. Values <= 0 reset to the compiled default (ARQ_DISCONNECT_DRAIN_TIMEOUT_S_DEFAULT).

arq_set_listen_mode()

int arq_set_listen_mode

(

int

mode

)

arq_set_retry_slots()

void arq_set_retry_slots

(

int

slots

)

Set runtime retry slot counts.

Updates the CALL and ACCEPT retry counters used by the ARQ FSM. DISCONNECT retries are left at the compiled default. Pass 0 to restore all counters to compiled defaults.

Parameters

slots

Number of retry slots, or 0 to restore defaults.

arq_set_retry_stagger_ms()

void arq_set_retry_stagger_ms

(

int

ms

)

arq_set_trx()

void arq_set_trx

(

int

trx

)

arq_shutdown()

void arq_shutdown

(

)

Shut down ARQ workers and release ARQ resources.

arq_submit_tcp_cmd()

int arq_submit_tcp_cmd

(

const arq_cmd_msg_t *

cmd

)

Submit parsed control command from TCP bridge to ARQ.

Parameters

cmd	Command message.

Returns

0 on success, negative on queue/error.

arq_submit_tcp_payload()

int arq_submit_tcp_payload	(	const uint8_t *	data,
		size_t	len
	)

Submit payload bytes from TCP bridge to ARQ.

Parameters

data	Payload bytes.
len	Payload length in bytes.

Returns

0 on success, negative on queue/error.

arq_tick_1hz()

void arq_tick_1hz

(

void

)

Execute 1 Hz ARQ maintenance tick.

arq_try_dequeue_action()

bool arq_try_dequeue_action

(

arq_action_t *

action

)

Try to dequeue next modem action without blocking.

Parameters

action

Output action item.

Returns

true if an action was dequeued.

arq_update_link_metrics()

void arq_update_link_metrics	(	int	sync,
		float	snr,
		int	rx_status,
		bool	frame_decoded
	)

Feed decoder/link metrics into ARQ adaptation.

Parameters

sync	Decoder sync flag.
snr	Estimated SNR.
rx_status	Decoder RX status flags.
frame_decoded	True when a frame decoded this cycle.

arq_wait_dequeue_action()

bool arq_wait_dequeue_action	(	arq_action_t *	action,
		int	timeout_ms
	)

Wait for next modem action.

Parameters

action	Output action item.
timeout_ms	Wait timeout in milliseconds.

Returns

true if an action was dequeued.

call_remote()

void call_remote

(

)

Trigger outgoing call attempt using current ARQ addresses.

callee_accept_connection()

void callee_accept_connection

(

)

Trigger callee-side accept flow in compatibility path.

clear_connection_data()

void clear_connection_data

(

)

Clear legacy ARQ connection state and buffers.

reset_arq_info()

void reset_arq_info

(

arq_info *

arq_conn

)

Reset external arq_info structure.

Parameters

arq_conn

Pointer to structure to reset.

Variable Documentation

arq_conn

arq_info arq_conn

extern