arq_timing.h

Go to the documentation of this file.

/* HERMES Modem — ARQ Timing: instrumentation context and record API
 *
 * Copyright (C) 2025 Rhizomatica
 * Author: Rafael Diniz <rafael@riseup.net>
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 */
 
#ifndef ARQ_TIMING_H_
#define ARQ_TIMING_H_
 
#include <stdbool.h>
#include <stdint.h>
 
/* ======================================================================
 * Timing context
 *
 * Timestamps are uint64_t monotonic milliseconds (from hermes_log startup).
 * Counters are unsigned and accumulate over the session lifetime.
 * SNR values are stored as integer * 10 to avoid float in the critical path.
 * ====================================================================== */
 
typedef struct
{
    /* Per-frame timestamps (reset at each new TX sequence) */
    uint64_t tx_queue_ms;       /* when frame was submitted to action queue    */
    uint64_t tx_start_ms;       /* when PTT went ON (frame on air)             */
    uint64_t tx_end_ms;         /* when PTT went OFF                           */
    uint64_t ack_rx_ms;         /* when ACK for this seq was decoded           */
    uint64_t data_rx_ms;        /* when last data frame was decoded (IRS side) */
    uint64_t ack_tx_start_ms;   /* when ACK TX started (IRS side)              */
 
    /* Derived measurements */
    uint32_t rtt_ms;            /* OTA RTT for last ACKed frame                */
    uint32_t ack_delay_ms;      /* peer-reported delay between data-rx/ack-tx  */
 
    /* Per-frame retry state */
    uint32_t retry_count;       /* retries for current tx_seq                  */
 
    /* SNR (integer * 10, e.g. -23 = -2.3 dB) */
    int      last_snr_local_x10;
    int      last_snr_peer_x10;
 
    /* Session cumulative counters */
    uint64_t tx_bytes;
    uint64_t rx_bytes;
    uint64_t retries_total;
    uint64_t frames_tx;
    uint64_t frames_rx;
} arq_timing_ctx_t;
 
/* ======================================================================
 * API
 * ====================================================================== */
 
void arq_timing_init(arq_timing_ctx_t *ctx);
 
void arq_timing_record_tx_queue(arq_timing_ctx_t *ctx, int seq, int mode,
                                int backlog_bytes, int payload_bytes);
 
void arq_timing_record_tx_start(arq_timing_ctx_t *ctx, int seq, int mode,
                                int backlog_bytes);
 
void arq_timing_record_tx_end(arq_timing_ctx_t *ctx, int seq);
 
void arq_timing_record_ack_rx(arq_timing_ctx_t *ctx, int seq,
                               uint8_t ack_delay_raw, int peer_snr_x10);
 
void arq_timing_record_data_rx(arq_timing_ctx_t *ctx, int seq,
                                int bytes, int snr_x10);
 
void arq_timing_record_ack_tx(arq_timing_ctx_t *ctx, int seq);
 
void arq_timing_record_retry(arq_timing_ctx_t *ctx, int seq,
                              int attempt, const char *reason);
 
void arq_timing_record_turn(arq_timing_ctx_t *ctx, bool to_iss,
                             const char *reason);
 
void arq_timing_record_connect(arq_timing_ctx_t *ctx, int mode);
 
void arq_timing_record_disconnect(arq_timing_ctx_t *ctx, const char *reason);
 
#endif /* ARQ_TIMING_H_ */