Add: Ability to drop old frames

Change the way pipeline TX handles the order of framebuffers. Track
per-frame sequence numbers so transport can dequeue the newest converted
frame instead of always taking the next one, needed as otherwise
we cannot drop frames, as they will not be in order.
(This also makes it easier for multi threaded applications to use
the api should improve performance with multiple threads from the api
only).

Add a new flag to the TX pipeline to enable droping frames when we jump
over epoch. Mostly will aid with user control pacing.

Implemented in a way that only drops one frame in a scenario where late
is detected. This creates limitation for extreamly high drops The stream
will still not adjust immidiately instead doing
send frame | drop frame | send frame | drop frame ...
until we catch up.
(Done mostly as big jumps over more than 2 frames could be undesirable
and if you have that big of a drop ... well this is the least of your
troubles).

Due to lack of consumer and producer print stats of the queue via
reporting the framebuffers statuses (removed the ACCURATE_FRAMEBUFF) as
it became redundant.

Reverts: 772621d

All above done in pipeline as the purpose of the api pipeline is to
smoothe the library tight timing requirements from the user
applications.

Fix the st20p wrong user timestamp reporting in frames snapped to
the next frame.

if times given by the application looks as follows
----|--frame-1--|--frame-2--|--frame-3--|--frame-4--|-...
epoch-1--|--epoch-2--|--epoch-3--|--epoch-4--|...

This causes frames to snap to the next epoch, resulting in incorrect
timestamp reporting where every frame appears to have a "wrong user
timestamp" due to the forward snapping behavior.

Fixes: 88c3566

Fix the usdt for st40p tx (only to add the spurn event).

Fixes: 921fa0d

Author: DawidWesierski4

doc/usdt.md

@@ -736,10 +736,16 @@ sudo bpftrace -e 'usdt::st40:rx_mbuf_enqueue_fail { printf("%s m%d,s%d: mbuf %p
 
 #### 2.5.6. st40p pipeline tracing
 
-The ST40 pipeline helpers (used by `RxSt40PipelineSample`, `TxSt40PipelineSample`, or any app built on `st40_pipeline_api.h`) expose their own provider to focus on frame-level callbacks rather than mbuf activity. Today only the RX side wires USDT probes (TX helpers reuse the regular logging path):
+The ST40 pipeline helpers (used by `RxSt40PipelineSample`, `TxSt40PipelineSample`, or any app built on `st40_pipeline_api.h`) expose their own provider to focus on frame-level callbacks across both TX and RX paths:
 
 ```c
 provider st40p {
+  /* tx */
+  probe tx_frame_get(int idx, int f_idx, void* va);
+  probe tx_frame_put(int idx, int f_idx, void* va);
+  probe tx_frame_next(int idx, int f_idx);
+  probe tx_frame_done(int idx, int f_idx, uint32_t tmstamp);
+  probe tx_frame_drop(int idx, int f_idx, uint32_t tmstamp);
   /* rx */
   probe rx_frame_available(int idx, int f_idx, uint32_t meta_num);
   probe rx_frame_get(int idx, int f_idx, uint32_t meta_num);
@@ -749,6 +755,19 @@ provider st40p {
 }
 ```
 
+To watch for ancillary frames that arrive too late to flush, hook the TX drop probe (customize the process name for your setup):
+
+```bash
+sudo bpftrace -e 'usdt::st40p:tx_frame_drop { printf("%s s%d: drop frame %d(timestamp:%u)\n", strftime("%H:%M:%S", nsecs), arg0, arg1, arg2); }' -p $(pidof TxSt40PipelineSample)
+```
+
+Example output like below:
+
+```text
+09:33:12 s0: drop frame 0(timestamp:241037184)
+09:33:12 s0: drop frame 1(timestamp:241037728)
+```
+
 Typical RX-side traces (customize the process name/PID for your sample or RxTxApp process):
 
 ```bash
@@ -868,18 +887,34 @@ Example output like below:
 09:22:58 s0: done frame 1(timestamp:3639352297)
 ```
 
+#### 2.6.5. tx_frame_drop USDT
+
+usage: customize the application process name as your setup
+
+```bash
+sudo bpftrace -e 'usdt::st20p:tx_frame_drop { printf("%s s%d: drop frame %d(timestamp:%u)\n", strftime("%H:%M:%S", nsecs), arg0, arg1, arg2); }' -p $(pidof RxTxApp)
+```
+
+Example output like below:
+
+```text
+09:25:04 s0: drop frame 0(timestamp:3639471120)
+09:25:04 s0: drop frame 1(timestamp:3639472621)
+```
+
 And if you want to trace all st20p tx events, use below bpftrace script.
 
 ```bash
 sudo bpftrace -e '
 usdt::st20p:tx_frame_get { printf("%s s%d: get frame %d(addr:%p)\n", strftime("%H:%M:%S", nsecs), arg0, arg1, arg2); }
 usdt::st20p:tx_frame_put { printf("%s s%d: put frame %d(addr:%p,stat:%d)\n", strftime("%H:%M:%S", nsecs), arg0, arg1, arg2, arg3); }
 usdt::st20p:tx_frame_done { printf("%s s%d: done frame %d(timestamp:%u)\n", strftime("%H:%M:%S", nsecs), arg0, arg1, arg2); }
+usdt::st20p:tx_frame_drop { printf("%s s%d: drop frame %d(timestamp:%u)\n", strftime("%H:%M:%S", nsecs), arg0, arg1, arg2); }
 usdt::st20p:tx_frame_next { printf("%s s%d: next frame %d\n", strftime("%H:%M:%S", nsecs), arg0, arg1); }
 ' -p $(pidof RxTxApp)
 ```
 
-#### 2.6.5. rx_frame_get USDT
+#### 2.6.6. rx_frame_get USDT
 
 usage: customize the application process name as your setup
 
@@ -895,7 +930,7 @@ Example output like below:
 10:37:16 s0: get frame 2(addr:0x3209a17000)
 ```
 
-#### 2.6.6. rx_frame_put USDT
+#### 2.6.7. rx_frame_put USDT
 
 usage: customize the application process name as your setup
 
@@ -911,7 +946,7 @@ Example output like below:
 10:37:33 s0: put frame 2(addr:0x3209a17000)
 ```
 
-#### 2.6.7. rx_frame_available USDT
+#### 2.6.8. rx_frame_available USDT
 
 usage: customize the application process name as your setup
 
@@ -937,7 +972,7 @@ usdt::st20p:rx_frame_available { printf("%s s%d: available frame %d(addr:%p, tms
 ' -p $(pidof RxTxApp)
 ```
 
-#### 2.6.8. tx_frame_dump USDT
+#### 2.6.9. tx_frame_dump USDT
 
 Usage: Attaching to this hook initiates the process, which continues to dump frames to a local file every 5 seconds until detachment occurs.
 
@@ -952,7 +987,7 @@ Example output like below:
 13:26:46 s0: dump frame 0x3206217000 size 8294400 to imtl_usdt_st20ptx_s0_1920_1080_CzYDQe.yuv
 ```
 
-#### 2.6.9. rx_frame_dump USDT
+#### 2.6.10. rx_frame_dump USDT
 
 Usage: Attaching to this hook initiates the process, which continues to dump frames to a local file every 5 seconds until detachment occurs.
 
@@ -1207,18 +1242,34 @@ Example output like below:
 15:05:38 s0: done frame 1(timestamp:380834179)
 ```
 
+#### 2.8.5. tx_frame_drop USDT
+
+usage: customize the application process name as your setup
+
+```bash
+sudo bpftrace -e 'usdt::st22p:tx_frame_drop { printf("%s s%d: drop frame %d(timestamp:%u)\n", strftime("%H:%M:%S", nsecs), arg0, arg1, arg2); }' -p $(pidof RxTxApp)
+```
+
+Example output like below:
+
+```text
+15:06:42 s0: drop frame 0(timestamp:380846682)
+15:06:42 s0: drop frame 1(timestamp:380848184)
+```
+
 And if you want to trace all st22p tx events, use below bpftrace script.
 
 ```bash
 sudo bpftrace -e '
 usdt::st22p:tx_frame_get { printf("%s s%d: get frame %d(addr:%p)\n", strftime("%H:%M:%S", nsecs), arg0, arg1, arg2); }
 usdt::st22p:tx_frame_put { printf("%s s%d: put frame %d(addr:%p)\n", strftime("%H:%M:%S", nsecs), arg0, arg1, arg2); }
+usdt::st22p:tx_frame_drop { printf("%s s%d: drop frame %d(timestamp:%u)\n", strftime("%H:%M:%S", nsecs), arg0, arg1, arg2); }
 usdt::st22p:tx_frame_done { printf("%s s%d: done frame %d(timestamp:%u)\n", strftime("%H:%M:%S", nsecs), arg0, arg1, arg2); }
 usdt::st22p:tx_frame_next { printf("%s s%d: next frame %d\n", strftime("%H:%M:%S", nsecs), arg0, arg1); }
 ' -p $(pidof RxTxApp)
 ```
 
-#### 2.8.5. rx_frame_get USDT
+#### 2.8.6. rx_frame_get USDT
 
 usage: customize the application process name as your setup
 
@@ -1234,7 +1285,7 @@ Example output like below:
 15:10:54 s0: get frame 2(addr:0x320830e600)
 ```
 
-#### 2.8.6. rx_frame_put USDT
+#### 2.8.7. rx_frame_put USDT
 
 usage: customize the application process name as your setup
 
@@ -1250,7 +1301,7 @@ Example output like below:
 15:11:08 s0: put frame 2(addr:0x320830e600)
 ```
 
-#### 2.8.7. rx_frame_available USDT
+#### 2.8.8. rx_frame_available USDT
 
 usage: customize the application process name as your setup
 
@@ -1276,7 +1327,7 @@ usdt::st22p:rx_frame_available { printf("%s s%d: available frame %d(addr:%p, tms
 ' -p $(pidof RxTxApp)
 ```
 
-#### 2.8.8. tx_frame_dump USDT
+#### 2.8.9. tx_frame_dump USDT
 
 Usage: Attaching to this hook initiates the process, which continues to dump frames to a local file every 5 seconds until detachment occurs.
 
@@ -1291,7 +1342,7 @@ Example output like below:
 15:22:04 s0: dump frame 0x3205b0e600 size 5184000 to imtl_usdt_st22ptx_s0_1920_1080_oOJwjO.yuv
 ```
 
-#### 2.8.9. rx_frame_dump USDT
+#### 2.8.10. rx_frame_dump USDT
 
 Usage: Attaching to this hook initiates the process, which continues to dump frames to a local file every 5 seconds until detachment occurs.
 
@@ -1306,7 +1357,7 @@ Example output like below:
 15:23:04 s0: dump frame 0x3207d0e600 size 5184000 to imtl_usdt_st22prx_s0_1920_1080_N72BCd.yuv
 ```
 
-#### 2.8.10. tx_encode_get USDT
+#### 2.8.11. tx_encode_get USDT
 
 usage: customize the application process name as your setup
 
@@ -1321,7 +1372,7 @@ Example output like below:
 16:20:25 s0: get encode 1(src:0x320610e600,dst:0x32032400fc)
 ```
 
-#### 2.8.11. tx_encode_put USDT
+#### 2.8.12. tx_encode_put USDT
 
 usage: customize the application process name as your setup
 
@@ -1345,7 +1396,7 @@ usdt::st22p:tx_encode_put { printf("%s s%d: put encode %d(src:%p,dst:%p), result
 ' -p $(pidof RxTxApp)
 ```
 
-#### 2.8.12. rx_decode_get USDT
+#### 2.8.13. rx_decode_get USDT
 
 usage: customize the application process name as your setup
 
@@ -1361,7 +1412,7 @@ Example output like below:
 16:18:43 s0: get decode 2(src:0x3208f0e600,dst:0x320830e600), codestream size: 777600
 ```
 
-#### 2.8.13. rx_decode_put USDT
+#### 2.8.14. rx_decode_put USDT
 
 usage: customize the application process name as your setup
 
@@ -1471,18 +1522,34 @@ Example output like below:
 15:51:58 s0: done frame 2(timestamp:447476096)
 ```
 
+#### 2.9.5. tx_frame_drop USDT
+
+usage: customize the application process name as your setup
+
+```bash
+sudo bpftrace -e 'usdt::st30p:tx_frame_drop { printf("%s s%d: drop frame %d(timestamp:%u)\n", strftime("%H:%M:%S", nsecs), arg0, arg1, arg2); }' -p $(pidof RxTxApp)
+```
+
+Example output like below:
+
+```text
+15:52:11 s0: drop frame 0(timestamp:447476608)
+15:52:11 s0: drop frame 1(timestamp:447477088)
+```
+
 And if you want to trace all st30p tx events, use below bpftrace script.
 
 ```bash
 sudo bpftrace -e '
 usdt::st30p:tx_frame_get { printf("%s s%d: get frame %d(addr:%p)\n", strftime("%H:%M:%S", nsecs), arg0, arg1, arg2); }
 usdt::st30p:tx_frame_put { printf("%s s%d: put frame %d(addr:%p)\n", strftime("%H:%M:%S", nsecs), arg0, arg1, arg2); }
+usdt::st30p:tx_frame_drop { printf("%s s%d: drop frame %d(timestamp:%u)\n", strftime("%H:%M:%S", nsecs), arg0, arg1, arg2); }
 usdt::st30p:tx_frame_done { printf("%s s%d: done frame %d(timestamp:%u)\n", strftime("%H:%M:%S", nsecs), arg0, arg1, arg2); }
 usdt::st30p:tx_frame_next { printf("%s s%d: next frame %d\n", strftime("%H:%M:%S", nsecs), arg0, arg1); }
 ' -p $(pidof RxTxApp)
 ```
 
-#### 2.9.5. rx_frame_get USDT
+#### 2.9.6. rx_frame_get USDT
 
 usage: customize the application process name as your setup
 
@@ -1498,7 +1565,7 @@ Example output like below:
 15:57:50 s0: get frame 2(addr:0x32034009c0)
 ```
 
-#### 2.9.6. rx_frame_put USDT
+#### 2.9.7. rx_frame_put USDT
 
 usage: customize the application process name as your setup
 
@@ -1514,7 +1581,7 @@ Example output like below:
 15:58:14 s0: put frame 2(addr:0x32034009c0)
 ```
 
-#### 2.9.7. rx_frame_available USDT
+#### 2.9.8. rx_frame_available USDT
 
 usage: customize the application process name as your setup
 
@@ -1540,7 +1607,7 @@ usdt::st30p:rx_frame_available { printf("%s s%d: available frame %d(addr:%p, tms
 ' -p $(pidof RxTxApp)
 ```
 
-#### 2.9.8. tx_frame_dump USDT
+#### 2.9.9. tx_frame_dump USDT
 
 Usage: This utility is designed to capture and store audio frames transmitted over the network. Attaching to this hook initiates the process, which continues to dump frames to a local file until detachment occurs.
 
@@ -1568,7 +1635,7 @@ Then use ffmpeg tools to convert ram PCM file to a wav, customize the format as
 ffmpeg -f s24be -ar 48000 -ac 2 -i imtl_usdt_st30ptx_s0_48000_24_c2_LgAKKR.pcm dump.wav
 ```
 
-#### 2.9.9. rx_frame_dump USDT
+#### 2.9.10. rx_frame_dump USDT
 
 Usage: Similar to tx_frame_dump hook, this utility is designed to capture and store audio frames received over the network. Attaching to this hook initiates the process, which continues to dump frames to a local file until detachment occurs.
 

include/st20_api.h

@@ -1171,6 +1171,13 @@ struct st20_tx_ops {
   int (*notify_frame_done)(void* priv, uint16_t frame_idx,
                            struct st20_tx_frame_meta* meta);
 
+  /**
+   * Optional. Callback triggered when a frame epoch is omitted/skipped in the lib.
+   * This occurs when the transmission timing falls behind schedule and an epoch
+   * must be skipped to maintain synchronization. (or in the user pacing mode
+   * when the user time is behind the lib sending time).
+   */
+  int (*notify_frame_late)(void* priv, uint64_t epoch_skipped);
   /**
    * Optional. The event callback when there is some event(vsync or others) happened for
    * this session. Only non-block method can be used in this callback as it run from lcore
@@ -1321,6 +1328,14 @@ struct st22_tx_ops {
   int (*notify_frame_done)(void* priv, uint16_t frame_idx,
                            struct st22_tx_frame_meta* meta);
 
+  /**
+   * Optional. Callback triggered when a frame epoch is omitted/skipped in the lib.
+   * This occurs when the transmission timing falls behind schedule and an epoch
+   * must be skipped to maintain synchronization. (or in the user pacing mode
+   * when the user time is behind the lib sending time).
+   */
+  int (*notify_frame_late)(void* priv, uint64_t epoch_skipped);
+
   /**
    * Optional. The event callback when there is some event(vsync or others) happened for
    * this session. Only non-block method can be used in this callback as it run from lcore

include/st30_api.h

@@ -385,6 +385,14 @@ struct st30_tx_ops {
   int (*notify_frame_done)(void* priv, uint16_t frame_idx,
                            struct st30_tx_frame_meta* meta);
 
+  /**
+   * Optional. Callback triggered when a frame epoch is omitted/skipped in the lib.
+   * This occurs when the transmission timing falls behind schedule and an epoch
+   * must be skipped to maintain synchronization. (or in the user pacing mode
+   * when the user time is behind the lib sending time).
+   */
+  int (*notify_frame_late)(void* priv, uint64_t epoch_skipped);
+
   /*
    * Optional. The size of fifo ring which used between the packet builder and pacing.
    * Leave to zero to use default value: the packet number within

include/st30_pipeline_api.h

@@ -52,6 +52,13 @@ enum st30p_tx_flag {
   /** Enable the st30p_tx_get_frame block behavior to wait until a frame becomes
    available or timeout(default: 1s, use st30p_tx_set_block_timeout to customize)*/
   ST30P_TX_FLAG_BLOCK_GET = (MTL_BIT32(15)),
+
+  /**
+   * Drop frames when the mtl reports late frames (transport can't keep up).
+   * When late frame is detected, next frame from pipeline is ommited.
+   * Untill we resume normal frame sending.
+   */
+  ST30P_TX_FLAG_DROP_WHEN_LATE = (MTL_BIT32(16)),
 };
 
 /** The structure info for st30 frame meta. */
@@ -130,10 +137,18 @@ struct st30p_tx_ops {
   int (*notify_frame_available)(void* priv);
   /**
    * Optional. Callback when frame done.
-   * And only non-block method can be used within this callback as it run from lcore
-   * tasklet routine.
+   * If TX_FLAG_DROP_WHEN_LATE is enabled AND notify_frame_late is set,
+   * then this will be called only when notify_frame_late is NOT called.
    */
   int (*notify_frame_done)(void* priv, struct st30_frame* frame);
+  /**
+   * Optional. Callback when frame timing issues occur.
+   * If ST30P_TX_FLAG_DROP_WHEN_LATE is enabled: triggered when a frame is dropped
+   * from the pipeline due to late transmission.
+   * If ST30P_TX_FLAG_DROP_WHEN_LATE is disabled: triggered when the transport
+   * layer reports late frame delivery.
+   */
+  int (*notify_frame_late)(void* priv, uint64_t epoch_skipped);
 
   /**
    * Optional. The rtp timestamp delta(us) to the start time of frame.

include/st40_api.h

@@ -337,6 +337,8 @@ struct st40_tx_ops {
   int (*notify_frame_done)(void* priv, uint16_t frame_idx,
                            struct st40_tx_frame_meta* meta);
 
+  int (*notify_frame_late)(void* priv, uint64_t epoch_skipped);
+
   /** Optional. UDP source port number, leave as 0 to use same port as dst */
   uint16_t udp_src_port[MTL_SESSION_PORT_MAX];
   /**