Fix: use media-clock ticks for RL RTP timestamp offset

The RL pacing warm-up compensation was computed in nanoseconds and
subtracted from the TAI time before converting to media-clock ticks.
This caused rounding errors for fractional frame rates like 1080i59,
where the ns-domain subtraction could land on a tick boundary and
produce repeated or skipped RTP timestamps.
Convert the offset to media-clock ticks directly.

Also document the truncation-toward-zero requirement for callers that
derive TAI timestamps from rational frame periods (see issue #1321).

Author: DawidWesierski4

include/st_api.h

@@ -368,6 +368,18 @@ enum st_fps st_name_to_fps(const char* name);
 /**
  * Helper function to convert ST10_TIMESTAMP_FMT_TAI to ST10_TIMESTAMP_FMT_MEDIA_CLK.
  *
+ * The conversion quantises the continuous TAI time to a discrete media-clock tick
+ * by computing: tick = round(tai_ns * sampling_rate / 1e9).  Because the media
+ * clock is discrete, a difference of just 1 ns in the input can change the output
+ * by one tick when the value lies exactly on a tick boundary.
+ *
+ * Callers that derive tai_ns from a frame number and frame period (which is a
+ * rational number, e.g. 1001/60000 s for 59.94 fps) must use truncation toward
+ * zero — **not** rounding — when converting the rational time to nanoseconds,
+ * i.e.  tai_ns = (uint64_t)(frame_number * period_num / period_den).
+ * Using roundl() or similar can push the value past a tick boundary, producing
+ * repeated or skipped RTP timestamps.
+ *
  * @param tai_ns
  *   time in nanoseconds since the TAI epoch.
  * @param sampling_rate

lib/src/st2110/st_header.h

@@ -173,8 +173,8 @@ struct st_tx_video_pacing {
   /* in ns, idle time at the end of frame, frame_time - tr_offset - (trs * pkts) */
   double frame_idle_time;
   double reactive;
-  float pad_interval;        /* padding pkt interval(pkts level) for RL pacing */
-  uint64_t rl_rtp_offset_ns; /* RL-only RTP timestamp shift (ns), compensates warm-up */
+  float pad_interval;           /* padding pkt interval(pkts level) for RL pacing */
+  uint32_t rl_rtp_offset_ticks; /* RL-only RTP timestamp shift (media-clk ticks) */
 
   uint64_t cur_epochs; /* epoch of current frame */
   /* timestamp for rtp header */

lib/src/st2110/st_tx_video_session.c

@@ -15,6 +15,8 @@
 #include "st_video_transmitter.h"
 
 #define MTL_LATENCY_COMPENSATION_PACKET_SHIFT 5
+#define MTL_LATENCY_COMPENSATION_PACKET_SHIFT_MIN_TICK \
+  1 /* at least shift 1 tick for RL pacing */
 
 #ifdef MTL_SIMULATE_PACKET_DROPS
 static inline void tv_simulate_packet_loss(struct st_tx_video_session_impl* s,
@@ -523,7 +525,7 @@ static int tv_init_pacing(struct mtl_main_impl* impl,
   dbg("%s[%02d], max_onward_epochs %u\n", __func__, idx, pacing->max_onward_epochs);
   /* default VRX compensate as rl accuracy, update later in tv_train_pacing */
   pacing->pad_interval = s->st20_total_pkts;
-  pacing->rl_rtp_offset_ns = 0; /* set later for RL pacing */
+  pacing->rl_rtp_offset_ticks = 0; /* set later for RL pacing */
 
   int num_port = s->ops.num_port;
   int ret;
@@ -560,8 +562,10 @@ static int tv_init_pacing(struct mtl_main_impl* impl,
 
   /* RL pacing: shift RTP timestamp back by few packets to compensate warm-up pad */
   if (s->pacing_way[MTL_SESSION_PORT_P] == ST21_TX_PACING_WAY_RL) {
-    pacing->rl_rtp_offset_ns =
-        (uint64_t)(MTL_LATENCY_COMPENSATION_PACKET_SHIFT * pacing->trs);
+    pacing->rl_rtp_offset_ticks =
+        RTE_MAX(MTL_LATENCY_COMPENSATION_PACKET_SHIFT_MIN_TICK,
+                st10_tai_to_media_clk(MTL_LATENCY_COMPENSATION_PACKET_SHIFT * pacing->trs,
+                                      s->fps_tm.sampling_clock_rate));
   }
 
   /* calculate vrx pkts */
@@ -602,10 +606,10 @@ static int tv_init_pacing(struct mtl_main_impl* impl,
   }
   info(
       "%s[%02d], trs %f trOffset %f vrx %u warm_pkts %u frame time %fms fps %f "
-      "rl_rtp_adj %" PRIu64 "ns\n",
+      "rl_rtp_adj %u ticks\n",
       __func__, idx, pacing->trs, pacing->tr_offset, pacing->vrx, pacing->warm_pkts,
       pacing->frame_time / NS_PER_MS, st_frame_rate(s->ops.fps),
-      pacing->rl_rtp_offset_ns);
+      pacing->rl_rtp_offset_ticks);
   /* resolve pacing tasklet */
   for (int i = 0; i < num_port; i++) {
     ret = st_video_resolve_pacing_tasklet(s, i);
@@ -746,9 +750,10 @@ static void tv_update_rtp_time_stamp(struct st_tx_video_session_impl* s,
     } else {
       tai_for_rtp_ts = pacing->ptp_time_cursor;
     }
-    tai_for_rtp_ts += delta_ns - pacing->rl_rtp_offset_ns;
+    tai_for_rtp_ts += delta_ns;
     pacing->rtp_time_stamp =
-        st10_tai_to_media_clk(tai_for_rtp_ts, s->fps_tm.sampling_clock_rate);
+        st10_tai_to_media_clk(tai_for_rtp_ts, s->fps_tm.sampling_clock_rate) -
+        pacing->rl_rtp_offset_ticks;
   }
   dbg("%s(%d), rtp time stamp %u\n", __func__, s->idx, pacing->rtp_time_stamp);
 }
@@ -1366,10 +1371,10 @@ static int tv_build_rtp(struct mtl_main_impl* impl, struct st_tx_video_session_i
       } else {
         tai_for_rtp_ts = s->pacing.ptp_time_cursor;
       }
-      tai_for_rtp_ts += (uint64_t)s->ops.rtp_timestamp_delta_us * NS_PER_US -
-                        s->pacing.rl_rtp_offset_ns;
+      tai_for_rtp_ts += (uint64_t)s->ops.rtp_timestamp_delta_us * NS_PER_US;
       s->pacing.rtp_time_stamp =
-          st10_tai_to_media_clk(tai_for_rtp_ts, s->fps_tm.sampling_clock_rate);
+          st10_tai_to_media_clk(tai_for_rtp_ts, s->fps_tm.sampling_clock_rate) -
+          s->pacing.rl_rtp_offset_ticks;
     }
     dbg("%s(%d), rtp time stamp %u\n", __func__, s->idx, s->pacing.rtp_time_stamp);
   }
@@ -1439,10 +1444,10 @@ static int tv_build_rtp_chain(struct mtl_main_impl* impl,
       } else {
         tai_for_rtp_ts = s->pacing.ptp_time_cursor;
       }
-      tai_for_rtp_ts += (uint64_t)s->ops.rtp_timestamp_delta_us * NS_PER_US -
-                        s->pacing.rl_rtp_offset_ns;
+      tai_for_rtp_ts += (uint64_t)s->ops.rtp_timestamp_delta_us * NS_PER_US;
       s->pacing.rtp_time_stamp =
-          st10_tai_to_media_clk(tai_for_rtp_ts, s->fps_tm.sampling_clock_rate);
+          st10_tai_to_media_clk(tai_for_rtp_ts, s->fps_tm.sampling_clock_rate) -
+          s->pacing.rl_rtp_offset_ticks;
     }
     dbg("%s(%d), rtp time stamp %u\n", __func__, s->idx, s->pacing.rtp_time_stamp);
   }