Add: gst/st40p: unify rx defaults and input formats

- add GST_MTL_DEFAULT_FRAMEBUFF_CNT to gst_mtl_common so every plugin can share
  the same fallback value; wire st20p/st30p/st40p RX to seed and consume it so
  ops structs pick up the common default when the element-specific property is 0

- relax the README ranges for st40p_rx frame buffers (0..G_MAXUINT) and note
  that rtp-ring-size is rejected unless it is a power of two, matching the new
  runtime check instead of auto-rounding values at startup

- rework st40p_tx to expose an enum-based input-format property (raw UDW,
  RFC8331 packed, simplified RFC8331 produced by rx) while keeping
  parse-8331-meta as a deprecated alias for compatibility

- implement the simplified RFC8331 parser so tx can ingest the 8-byte headers
  emitted by mtl_st40p_rx without repacking parity bits; switch the chain
  function to dispatch on the new enum and warn when DID/SDID are ignored

- update ancillary validation helpers/tests to set input-format rather than the
  old boolean so CI and pytest continue to run in the intended mode

Author: moleksy

ecosystem/gstreamer_plugin/README.md

@@ -409,11 +409,15 @@ The `mtl_st40p_tx` plugin supports all pad capabilities (the data is not checked
 | tx-sdid               | uint     | Secondary Data ID for the ancillary data.                          | 0 to 255         | 0             |
 | use-pts-for-pacing    | gboolean | [User controlled timestamping offset](#233-pts-controlled-pacing)  | TRUE/FALSE       | FALSE         |
 | pts-pacing-offset     | uint     | [User controlled timestamping offset](#233-pts-controlled-pacing)  | 0 to G_MAXUINT   | 0             |
-| parse-8331-meta       | gboolean | Treat the input as rfc8331 payload data                            | TRUE/FALSE       | FALSE         |
+| input-format          | enum     | Encoding of incoming ANC buffers (`raw-udw`, `rfc8331-packed`, `rfc8331`) | enum            | `raw-udw`     |
+| parse-8331-meta       | gboolean | **Deprecated.** Shortcut for `input-format=rfc8331-packed`.         | TRUE/FALSE       | FALSE         |
 | max-combined-udw-size | uint     | Maximum combined size of all user data words to send in one buffer | 0 to (20 * 255)  | 20 * 255      |
 
-> **Note:**  
-> If `parse-8331-meta` is not enabled, only one ANC packet per frame is supported. It is recommended to limit the `max-combined-udw-size` if you are only using this option, since by default `max-combined-udw-size` is set to its maximum value.
+> **Note:**
+> - `raw-udw` streams carry a single ANC packet per frame without per-packet metadata; the element uses `tx-did`/`tx-sdid` for the outgoing headers, so keeping `max-combined-udw-size` small avoids oversized frames.
+> - `rfc8331-packed` expects the 10-bit RFC8331 payload (including headers) generated by external tools. This is the mode formerly controlled by `parse-8331-meta`.
+> - `rfc8331` accepts the simplified 8-bit representation produced by `mtl_st40p_rx output-format=rfc8331`, enabling metadata round-trips without re-packing parity bits.
+> - The `parse-8331-meta` flag remains available for backward compatibility but will be removed in a future release. Update existing pipelines to use `input-format=rfc8331-packed` (or `rfc8331`) to avoid breakage when the legacy boolean disappears.
 
 #### 5.1.2. Example GStreamer Pipeline for Transmission
 
@@ -442,7 +446,7 @@ The `mtl_st40p_rx` plugin supports all pad capabilities (the data is not checked
 
 | Property Name       | Type    | Description                                                 | Range                       | Default Value |
 |---------------------|---------|-------------------------------------------------------------|-----------------------------|---------------|
-| rx-framebuff-cnt    | uint    | Number of frame buffers allocated in the pipeline           | 2 to 16                     | 3             |
+| rx-framebuff-cnt    | uint    | Number of frame buffers allocated in the pipeline           | 0 to G_MAXUINT              | 3             |
 | max-udw-size        | uint    | Maximum user-data word buffer size in bytes per frame       | 1024 to 1,048,576           | 131,072       |
 | rtp-ring-size       | uint    | Size of the internal RTP ring (must be power of two)        | 64 to 16,384                | 1,024         |
 | timeout             | uint    | Timeout in seconds for blocking frame retrieval             | 0 to 300                    | 60            |
@@ -454,6 +458,10 @@ header (C, line number, horizontal offset, S, stream number, DID, SDID, data cou
 its user data words so that downstream elements receive complete RFC8331 payloads. Selecting
 `raw-udw` delivers only the user-data words exactly as received on the wire.
 
+> **Note:** `rtp-ring-size` values are validated at runtime. If the supplied number is not a power of
+> two the element fails to initialize, matching the behavior enforced inside
+> `gst_mtl_st40p_rx_start()`.
+
 #### 5.2.2. Example GStreamer Pipeline for Reception
 
 To run the `mtl_st40p_rx` plugin, use the following command:

ecosystem/gstreamer_plugin/gst_mtl_common.h

@@ -29,6 +29,7 @@
 #endif
 
 #define DEFAULT_FRAMERATE 25
+#define GST_MTL_DEFAULT_FRAMEBUFF_CNT 3
 
 enum {
   PROP_GENERAL_0,
@@ -65,6 +66,7 @@ typedef struct GeneralArgs {
   gchar dma_dev[MTL_PORT_MAX_LEN];
   gint log_level;
   gboolean enable_onboard_ptp;
+  guint framebuff_cnt;
 } GeneralArgs;
 
 typedef struct SessionPortArgs {

ecosystem/gstreamer_plugin/gst_mtl_st20p_rx.c

@@ -183,7 +183,8 @@ static void gst_mtl_st20p_rx_class_init(Gst_Mtl_St20p_RxClass* klass) {
       gobject_class, PROP_ST20P_RX_FRAMEBUFF_NUM,
       g_param_spec_uint("rx-framebuff-num", "Number of framebuffers",
                         "Number of framebuffers to be used for transmission.", 0,
-                        G_MAXUINT, 3, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+                        G_MAXUINT, GST_MTL_DEFAULT_FRAMEBUFF_CNT,
+                        G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
   g_object_class_install_property(
       gobject_class, PROP_ST20P_RX_WIDTH,
@@ -251,7 +252,7 @@ static gboolean gst_mtl_st20p_rx_start(GstBaseSrc* basesrc) {
   if (src->framebuffer_num) {
     ops_rx.framebuff_cnt = src->framebuffer_num;
   } else {
-    ops_rx.framebuff_cnt = 3;
+    ops_rx.framebuff_cnt = src->generalArgs.framebuff_cnt;
   }
 
   if (!gst_mtl_common_parse_pixel_format(src->pixel_format, &ops_rx.output_fmt)) {
@@ -310,6 +311,7 @@ static void gst_mtl_st20p_rx_init(Gst_Mtl_St20p_Rx* src) {
 
   src->fps_n = DEFAULT_FRAMERATE;
   src->fps_d = 1;
+  src->generalArgs.framebuff_cnt = GST_MTL_DEFAULT_FRAMEBUFF_CNT;
 
   srcpad = gst_element_get_static_pad(element, "src");
   if (!srcpad) {
@@ -338,6 +340,11 @@ static void gst_mtl_st20p_rx_set_property(GObject* object, guint prop_id,
       break;
     case PROP_ST20P_RX_FRAMEBUFF_NUM:
       self->framebuffer_num = g_value_get_uint(value);
+      if (self->framebuffer_num) {
+        self->generalArgs.framebuff_cnt = self->framebuffer_num;
+      } else {
+        self->generalArgs.framebuff_cnt = GST_MTL_DEFAULT_FRAMEBUFF_CNT;
+      }
       break;
     case PROP_ST20P_RX_WIDTH:
       self->width = g_value_get_uint(value);

ecosystem/gstreamer_plugin/gst_mtl_st30p_rx.c

@@ -157,7 +157,8 @@ static void gst_mtl_st30p_rx_class_init(Gst_Mtl_St30p_RxClass* klass) {
       gobject_class, PROP_ST30P_RX_FRAMEBUFF_NUM,
       g_param_spec_uint("rx-framebuff-num", "Number of framebuffers",
                         "Number of framebuffers to be used for transmission.", 0,
-                        G_MAXUINT, 3, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+                        G_MAXUINT, GST_MTL_DEFAULT_FRAMEBUFF_CNT,
+                        G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
   g_object_class_install_property(
       gobject_class, PROP_ST30P_RX_CHANNEL,
@@ -237,7 +238,7 @@ static gboolean gst_mtl_st30p_rx_start(GstBaseSrc* basesrc) {
   if (src->framebuffer_num) {
     ops_rx->framebuff_cnt = src->framebuffer_num;
   } else {
-    ops_rx->framebuff_cnt = 3;
+    ops_rx->framebuff_cnt = src->generalArgs.framebuff_cnt;
   }
 
   gst_mtl_common_copy_general_to_session_args(&(src->generalArgs), &(src->portArgs));
@@ -268,6 +269,8 @@ static void gst_mtl_st30p_rx_init(Gst_Mtl_St30p_Rx* src) {
   GstElement* element = GST_ELEMENT(src);
   GstPad* srcpad;
 
+  src->generalArgs.framebuff_cnt = GST_MTL_DEFAULT_FRAMEBUFF_CNT;
+
   srcpad = gst_element_get_static_pad(element, "src");
   if (!srcpad) {
     GST_ERROR_OBJECT(src, "Failed to get src pad from child element");
@@ -288,6 +291,11 @@ static void gst_mtl_st30p_rx_set_property(GObject* object, guint prop_id,
   switch (prop_id) {
     case PROP_ST30P_RX_FRAMEBUFF_NUM:
       self->framebuffer_num = g_value_get_uint(value);
+      if (self->framebuffer_num) {
+        self->generalArgs.framebuff_cnt = self->framebuffer_num;
+      } else {
+        self->generalArgs.framebuff_cnt = GST_MTL_DEFAULT_FRAMEBUFF_CNT;
+      }
       break;
     case PROP_ST30P_RX_CHANNEL:
       self->channel = g_value_get_uint(value);

ecosystem/gstreamer_plugin/gst_mtl_st40p_rx.c

@@ -67,12 +67,7 @@
 #include <config.h>
 #endif
 
-#include <arpa/inet.h> /* For htonl */
-#include <errno.h>
 #include <gst/gstinfo.h>
-#include <stdint.h>
-#include <stdio.h>
-#include <stdlib.h>
 #include <string.h>
 
 #include "gst_mtl_st40p_rx.h"
@@ -99,14 +94,6 @@ static GType gst_mtl_st40p_rx_output_format_get_type(void) {
 GST_DEBUG_CATEGORY_STATIC(gst_mtl_st40p_rx_debug);
 #define GST_CAT_DEFAULT gst_mtl_st40p_rx_debug
 
-/* Force verbose logging for all mtl* categories at plugin load time */
-static void gst_mtl_st40p_set_debug_thresholds(void) {
-  gst_debug_category_set_threshold(gst_mtl_st40p_rx_debug, GST_LEVEL_LOG);
-  gst_debug_set_threshold_for_name("mtl_st40p_tx", GST_LEVEL_LOG);
-  gst_debug_set_threshold_for_name("mtl_common", GST_LEVEL_LOG);
-  gst_debug_set_threshold_for_name("mtl", GST_LEVEL_LOG);
-}
-
 #ifndef GST_LICENSE
 #define GST_LICENSE "LGPL"
 #endif
@@ -131,9 +118,8 @@ static void gst_mtl_st40p_set_debug_thresholds(void) {
 #define PACKAGE_VERSION "1.0"
 #endif
 
-#define DEFAULT_RX_FRAMEBUFF_CNT 3
-#define DEFAULT_MAX_UDW_SIZE (128 * 1024)  // 128KB default
-#define DEFAULT_RTP_RING_SIZE 1024         // power-of-two default
+#define DEFAULT_MAX_UDW_SIZE (128 * 1024) /* 128KB default */
+#define DEFAULT_RTP_RING_SIZE 1024        /* power-of-two default */
 
 enum {
   PROP_ST40P_RX_FRAMEBUFF_CNT = PROP_GENERAL_MAX,
@@ -288,6 +274,10 @@ static gboolean gst_mtl_st40p_rx_serialize_frame(Gst_Mtl_St40p_Rx* src,
   }
 }
 
+static gboolean gst_mtl_st40p_is_power_of_two(uint32_t value) {
+  return value && ((value & (value - 1)) == 0);
+}
+
 static void gst_mtl_st40p_rx_class_init(Gst_Mtl_St40p_RxClass* klass) {
   GObjectClass* gobject_class;
   GstElementClass* gstelement_class;
@@ -305,13 +295,12 @@ static void gst_mtl_st40p_rx_class_init(Gst_Mtl_St40p_RxClass* klass) {
   gstbasesrc_class->create = GST_DEBUG_FUNCPTR(gst_mtl_st40p_rx_create);
 
   gst_mtl_common_init_general_arguments(gobject_class);
-  gst_mtl_st40p_set_debug_thresholds();
 
   g_object_class_install_property(
       gobject_class, PROP_ST40P_RX_FRAMEBUFF_CNT,
       g_param_spec_uint("rx-framebuff-cnt", "RX Frame Buffer Count",
-                        "Number of frame buffers for RX pipeline", 2, 16,
-                        DEFAULT_RX_FRAMEBUFF_CNT,
+                        "Number of frame buffers for RX pipeline", 0, G_MAXUINT,
+                        GST_MTL_DEFAULT_FRAMEBUFF_CNT,
                         G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
 
   g_object_class_install_property(
@@ -357,7 +346,8 @@ static void gst_mtl_st40p_rx_class_init(Gst_Mtl_St40p_RxClass* klass) {
 }
 
 static void gst_mtl_st40p_rx_init(Gst_Mtl_St40p_Rx* src) {
-  src->rx_framebuff_cnt = DEFAULT_RX_FRAMEBUFF_CNT;
+  src->generalArgs.framebuff_cnt = GST_MTL_DEFAULT_FRAMEBUFF_CNT;
+  src->rx_framebuff_cnt = GST_MTL_DEFAULT_FRAMEBUFF_CNT;
   src->max_udw_size = DEFAULT_MAX_UDW_SIZE;
   src->rtp_ring_size = DEFAULT_RTP_RING_SIZE;
   src->timeout_s = 60;
@@ -385,6 +375,11 @@ static void gst_mtl_st40p_rx_set_property(GObject* object, guint prop_id,
   switch (prop_id) {
     case PROP_ST40P_RX_FRAMEBUFF_CNT:
       src->rx_framebuff_cnt = g_value_get_uint(value);
+      if (src->rx_framebuff_cnt) {
+        src->generalArgs.framebuff_cnt = src->rx_framebuff_cnt;
+      } else {
+        src->generalArgs.framebuff_cnt = GST_MTL_DEFAULT_FRAMEBUFF_CNT;
+      }
       break;
     case PROP_ST40P_RX_MAX_UDW_SIZE:
       src->max_udw_size = g_value_get_uint(value);
@@ -457,27 +452,19 @@ static gboolean gst_mtl_st40p_rx_start(GstBaseSrc* basesrc) {
   }
 
   ops_rx.name = "st40p_rx";
-  ops_rx.framebuff_cnt = src->rx_framebuff_cnt;
+  ops_rx.framebuff_cnt =
+      src->rx_framebuff_cnt ? src->rx_framebuff_cnt : src->generalArgs.framebuff_cnt;
   ops_rx.max_udw_buff_size = src->max_udw_size;
   ops_rx.flags = 0; /* Use non-blocking mode - blocking causes preroll timeout */
 
   GST_DEBUG_OBJECT(src, "RX START: framebuff_cnt=%d, max_udw_buff_size=%d",
                    ops_rx.framebuff_cnt, ops_rx.max_udw_buff_size);
 
-  /* set rtp ring size ensuring power-of-two */
   uint32_t ring_sz = src->rtp_ring_size ? src->rtp_ring_size : DEFAULT_RTP_RING_SIZE;
-  if ((ring_sz & (ring_sz - 1)) != 0) {
-    uint32_t v = ring_sz;
-    v--;
-    v |= v >> 1;
-    v |= v >> 2;
-    v |= v >> 4;
-    v |= v >> 8;
-    v |= v >> 16;
-    v++;
-    GST_WARNING_OBJECT(src, "RX START: rtp-ring-size %u not power of two, using %u",
-                       ring_sz, v);
-    ring_sz = v;
+  /* ST40 pipeline requires ring size to be 2^n; fail fast on invalid input. */
+  if (!gst_mtl_st40p_is_power_of_two(ring_sz)) {
+    GST_ERROR_OBJECT(src, "RX START: rtp-ring-size %u must be a power of two", ring_sz);
+    return FALSE;
   }
   ops_rx.rtp_ring_size = ring_sz;