runtime(io),ui: preserve RTL PPM apply semantics and C API constness

Author: arancormonk

include/dsd-neo/io/rtl_stream_c.h

@@ -27,22 +27,39 @@ typedef struct RtlSdrContext RtlSdrContext;
 
 /* Lifecycle */
 /**
- * @brief Create a new RTL-SDR stream context from options.
+ * @brief Create a new RTL-SDR stream context from an immutable options snapshot.
+ *
+ * The supplied options are copied internally and never mutated. Use
+ * rtl_stream_create_mirrored() when the caller needs live RTL PPM updates to
+ * propagate back into its owning @ref dsd_opts.
+ *
  * @param opts Decoder options snapshot used to configure the stream. Must not be NULL.
  * @param out_ctx [out] On success, receives an opaque context pointer.
  * @return 0 on success; otherwise <0 on error.
  */
 int rtl_stream_create(const dsd_opts* opts, RtlSdrContext** out_ctx);
+/**
+ * @brief Create a new RTL-SDR stream context mirrored to caller-owned options.
+ *
+ * The stream still owns an internal copy of @p opts, but live requested PPM
+ * updates also write back into the caller-owned structure so restarts and
+ * config snapshots retain the current correction.
+ *
+ * @param opts Mutable caller-owned decoder options to mirror. Must not be NULL.
+ * @param out_ctx [out] On success, receives an opaque context pointer.
+ * @return 0 on success; otherwise <0 on error.
+ */
+int rtl_stream_create_mirrored(dsd_opts* opts, RtlSdrContext** out_ctx);
 /**
  * @brief Start the stream threads and device I/O.
- * @param ctx Stream context created by rtl_stream_create().
+ * @param ctx Stream context created by rtl_stream_create() or rtl_stream_create_mirrored().
  * @return 0 on success; otherwise <0 on error.
  */
 int rtl_stream_start(RtlSdrContext* ctx);
 /**
  * @brief Stop the stream and cleanup resources associated with the run.
  * Safe to call multiple times; subsequent calls are no-ops.
- * @param ctx Stream context created by rtl_stream_create().
+ * @param ctx Stream context created by rtl_stream_create() or rtl_stream_create_mirrored().
  * @return 0 on success; otherwise <0 on error.
  */
 int rtl_stream_stop(RtlSdrContext* ctx);
@@ -52,7 +69,7 @@ int rtl_stream_stop(RtlSdrContext* ctx);
  * Mirrors rtl_stream_stop() but avoids toggling global shutdown state so the
  * UI can reconfigure and restart streaming without terminating the process.
  *
- * @param ctx Stream context created by rtl_stream_create().
+ * @param ctx Stream context created by rtl_stream_create() or rtl_stream_create_mirrored().
  * @return 0 on success; otherwise <0 on error.
  */
 int rtl_stream_soft_stop(RtlSdrContext* ctx);

include/dsd-neo/runtime/config.h

@@ -636,6 +636,7 @@ typedef struct dsdneoUserConfig {
     char rtl_freq[64];
     int rtl_gain;
     int rtl_ppm;
+    int rtl_ppm_is_set; /* distinguish explicit 0 from omitted */
     int rtl_bw_khz;
     int rtl_sql;
     int rtl_volume;

src/engine/engine.c

@@ -1518,7 +1518,7 @@ liveScanner(dsd_opts* opts, dsd_state* state) {
 #ifdef USE_RADIO
     if (opts->audio_in_type == AUDIO_IN_RTL) {
         if (state->rtl_ctx == NULL) {
-            if (rtl_stream_create(opts, &state->rtl_ctx) < 0) {
+            if (rtl_stream_create_mirrored(opts, &state->rtl_ctx) < 0) {
                 LOG_ERROR("Failed to create radio stream.\n");
             }
         }
@@ -1875,7 +1875,7 @@ dsd_engine_run(dsd_opts* opts, dsd_state* state) {
 #ifdef USE_RADIO
         else if (opts->audio_in_type == AUDIO_IN_RTL) {
             if (state->rtl_ctx == NULL) {
-                if (rtl_stream_create(opts, &state->rtl_ctx) < 0) {
+                if (rtl_stream_create_mirrored(opts, &state->rtl_ctx) < 0) {
                     LOG_ERROR("Failed to create radio stream.\n");
                 }
             }

src/io/radio/rtl_stream_c.cpp

@@ -71,23 +71,16 @@ struct RtlSdrContext {
     RtlSdrOrchestrator* stream;
 };
 
-/**
- * @brief Create a new RTL-SDR stream context from options.
- *
- * @param opts Decoder options snapshot used to configure the stream. Must not be NULL.
- * @param out_ctx [out] On success, receives an opaque context pointer.
- * @return 0 on success; otherwise <0 on error.
- */
-extern "C" int
-rtl_stream_create(const dsd_opts* opts, RtlSdrContext** out_ctx) {
+static int
+rtl_stream_create_impl(const dsd_opts* opts, dsd_opts* mirrored_opts, RtlSdrContext** out_ctx) {
     if (!out_ctx || !opts) {
         return -1;
     }
     *out_ctx = (RtlSdrContext*)calloc(1, sizeof(RtlSdrContext));
     if (!*out_ctx) {
         return -1;
     }
-    (*out_ctx)->stream = new (std::nothrow) RtlSdrOrchestrator(*opts, const_cast<dsd_opts*>(opts));
+    (*out_ctx)->stream = new (std::nothrow) RtlSdrOrchestrator(*opts, mirrored_opts);
     if (!(*out_ctx)->stream) {
         free(*out_ctx);
         *out_ctx = NULL;
@@ -96,10 +89,34 @@ rtl_stream_create(const dsd_opts* opts, RtlSdrContext** out_ctx) {
     return 0;
 }
 
+/**
+ * @brief Create a new RTL-SDR stream context from an immutable options snapshot.
+ *
+ * @param opts Decoder options snapshot used to configure the stream. Must not be NULL.
+ * @param out_ctx [out] On success, receives an opaque context pointer.
+ * @return 0 on success; otherwise <0 on error.
+ */
+extern "C" int
+rtl_stream_create(const dsd_opts* opts, RtlSdrContext** out_ctx) {
+    return rtl_stream_create_impl(opts, NULL, out_ctx);
+}
+
+/**
+ * @brief Create a new RTL-SDR stream context mirrored to caller-owned options.
+ *
+ * @param opts Mutable caller-owned decoder options to mirror. Must not be NULL.
+ * @param out_ctx [out] On success, receives an opaque context pointer.
+ * @return 0 on success; otherwise <0 on error.
+ */
+extern "C" int
+rtl_stream_create_mirrored(dsd_opts* opts, RtlSdrContext** out_ctx) {
+    return rtl_stream_create_impl(opts, opts, out_ctx);
+}
+
 /**
  * @brief Start the stream threads and device I/O.
  *
- * @param ctx Stream context created by rtl_stream_create().
+ * @param ctx Stream context created by rtl_stream_create() or rtl_stream_create_mirrored().
  * @return 0 on success; otherwise <0 on error.
  */
 extern "C" int
@@ -115,7 +132,7 @@ rtl_stream_start(RtlSdrContext* ctx) {
  *
  * Safe to call multiple times; subsequent calls are no-ops.
  *
- * @param ctx Stream context created by rtl_stream_create().
+ * @param ctx Stream context created by rtl_stream_create() or rtl_stream_create_mirrored().
  * @return 0 on success; otherwise <0 on error.
  */
 extern "C" int

src/runtime/config_user.cpp

@@ -218,6 +218,17 @@ is_valid_rtl_bw_khz(int bw) {
     return (bw == 4 || bw == 6 || bw == 8 || bw == 12 || bw == 16 || bw == 24 || bw == 48);
 }
 
+static int
+resolve_configured_rtl_ppm(const dsdneoUserConfig* cfg, const dsd_opts* opts) {
+    if (!cfg) {
+        return opts ? opts->rtlsdr_ppm_error : 0;
+    }
+    if (cfg->rtl_ppm_is_set) {
+        return cfg->rtl_ppm;
+    }
+    return opts ? opts->rtlsdr_ppm_error : 0;
+}
+
 static void
 apply_shared_radio_tuning_from_config(const dsdneoUserConfig* cfg, dsd_opts* opts) {
     if (!cfg || !opts) {
@@ -229,7 +240,7 @@ apply_shared_radio_tuning_from_config(const dsdneoUserConfig* cfg, dsd_opts* opt
     }
 
     int gain = cfg->rtl_gain ? cfg->rtl_gain : opts->rtl_gain_value;
-    int ppm = cfg->rtl_ppm;
+    int ppm = resolve_configured_rtl_ppm(cfg, opts);
     int bw = cfg->rtl_bw_khz ? cfg->rtl_bw_khz : opts->rtl_dsp_bw_khz;
     int sql = cfg->rtl_sql;
     int vol = cfg->rtl_volume ? cfg->rtl_volume : opts->rtl_volume_multiplier;
@@ -257,6 +268,7 @@ snapshot_apply_live_rtl_values(const dsd_opts* opts, dsdneoUserConfig* cfg) {
 
     cfg->rtl_gain = opts->rtl_gain_value;
     cfg->rtl_ppm = opts->rtlsdr_ppm_error;
+    cfg->rtl_ppm_is_set = 1;
     cfg->rtl_bw_khz = opts->rtl_dsp_bw_khz;
     cfg->rtl_sql = (int)local_pwr_to_dB(opts->rtl_squelch_level);
     cfg->rtl_volume = opts->rtl_volume_multiplier;
@@ -286,6 +298,7 @@ snapshot_parse_rtl_device_spec(const char* audio_in_dev, dsdneoUserConfig* cfg)
     }
     if (n > 4) {
         cfg->rtl_ppm = atoi(tok[4]);
+        cfg->rtl_ppm_is_set = 1;
     }
     if (n > 5) {
         cfg->rtl_bw_khz = atoi(tok[5]);
@@ -321,6 +334,7 @@ snapshot_parse_rtltcp_device_spec(const char* audio_in_dev, dsdneoUserConfig* cf
     }
     if (n > 5) {
         cfg->rtl_ppm = atoi(tok[5]);
+        cfg->rtl_ppm_is_set = 1;
     }
     if (n > 6) {
         cfg->rtl_bw_khz = atoi(tok[6]);
@@ -529,7 +543,7 @@ dsd_user_config_render_ini(const dsdneoUserConfig* cfg, FILE* out) {
             if (cfg->rtl_gain) {
                 fprintf(out, "rtl_gain = %d\n", cfg->rtl_gain);
             }
-            if (cfg->rtl_ppm) {
+            if (cfg->rtl_ppm_is_set) {
                 fprintf(out, "rtl_ppm = %d\n", cfg->rtl_ppm);
             }
             if (cfg->rtl_bw_khz) {
@@ -553,7 +567,7 @@ dsd_user_config_render_ini(const dsdneoUserConfig* cfg, FILE* out) {
             if (cfg->rtl_gain) {
                 fprintf(out, "rtl_gain = %d\n", cfg->rtl_gain);
             }
-            if (cfg->rtl_ppm) {
+            if (cfg->rtl_ppm_is_set) {
                 fprintf(out, "rtl_ppm = %d\n", cfg->rtl_ppm);
             }
             if (cfg->rtl_bw_khz) {
@@ -574,7 +588,7 @@ dsd_user_config_render_ini(const dsdneoUserConfig* cfg, FILE* out) {
             if (cfg->rtl_gain) {
                 fprintf(out, "rtl_gain = %d\n", cfg->rtl_gain);
             }
-            if (cfg->rtl_ppm) {
+            if (cfg->rtl_ppm_is_set) {
                 fprintf(out, "rtl_ppm = %d\n", cfg->rtl_ppm);
             }
             if (cfg->rtl_bw_khz) {
@@ -732,7 +746,7 @@ dsd_apply_user_config_to_opts(const dsdneoUserConfig* cfg, dsd_opts* opts, dsd_s
                      * defaults initOpts()/CLI already established (AGC and
                      * multiplier 2) instead of forcing hardcoded values. */
                     int gain = cfg->rtl_gain ? cfg->rtl_gain : opts->rtl_gain_value;
-                    int ppm = cfg->rtl_ppm;
+                    int ppm = resolve_configured_rtl_ppm(cfg, opts);
                     int bw = cfg->rtl_bw_khz ? cfg->rtl_bw_khz : opts->rtl_dsp_bw_khz;
                     int sql = cfg->rtl_sql;
                     int vol = cfg->rtl_volume ? cfg->rtl_volume : opts->rtl_volume_multiplier;
@@ -744,7 +758,7 @@ dsd_apply_user_config_to_opts(const dsdneoUserConfig* cfg, dsd_opts* opts, dsd_s
                 if (cfg->rtltcp_host[0]) {
                     if (cfg->rtl_freq[0]) {
                         int gain = cfg->rtl_gain ? cfg->rtl_gain : opts->rtl_gain_value;
-                        int ppm = cfg->rtl_ppm;
+                        int ppm = resolve_configured_rtl_ppm(cfg, opts);
                         int bw = cfg->rtl_bw_khz ? cfg->rtl_bw_khz : opts->rtl_dsp_bw_khz;
                         int sql = cfg->rtl_sql;
                         int vol = cfg->rtl_volume ? cfg->rtl_volume : opts->rtl_volume_multiplier;

src/runtime/config_user_loader.cpp

@@ -222,6 +222,7 @@ apply_input_section_key(dsdneoUserConfig* cfg, const char* key_lc, const char* v
         cfg->rtl_gain = (int)parse_int_for_mode(val, 22, mode);
     } else if (strcmp(key_lc, "rtl_ppm") == 0) {
         cfg->rtl_ppm = (int)parse_int_for_mode(val, 0, mode);
+        cfg->rtl_ppm_is_set = 1;
     } else if (strcmp(key_lc, "rtl_bw_khz") == 0) {
         cfg->rtl_bw_khz = (int)parse_int_for_mode(val, 12, mode);
     } else if (strcmp(key_lc, "rtl_sql") == 0) {

src/ui/terminal/menu_services.c

@@ -656,7 +656,7 @@ svc_rtl_restart(dsd_opts* opts, dsd_state* state) {
     /* If the radio pipeline is the active input, immediately recreate and start the stream
        so changes take effect as soon as the user confirms the setting. */
     if (opts->audio_in_type == AUDIO_IN_RTL) {
-        if (rtl_stream_create(opts, &state->rtl_ctx) < 0) {
+        if (rtl_stream_create_mirrored(opts, &state->rtl_ctx) < 0) {
             return -1;
         }
         if (rtl_stream_start(state->rtl_ctx) < 0) {

src/ui/terminal/ui_cmd_queue.c

@@ -1086,13 +1086,15 @@ cfg_uses_rtl_runtime(const dsdneoUserConfig* cfg) {
 
 static void
 apply_cfg_live_rtl_ppm_request(dsd_opts* opts, const dsdneoUserConfig* cfg, int old_audio_in_type) {
-    if (!opts || old_audio_in_type != AUDIO_IN_RTL || opts->audio_in_type != AUDIO_IN_RTL
-        || !cfg_uses_rtl_runtime(cfg)) {
+    if (!opts || old_audio_in_type != AUDIO_IN_RTL || opts->audio_in_type != AUDIO_IN_RTL || !cfg_uses_rtl_runtime(cfg)
+        || !cfg->rtl_ppm_is_set) {
         return;
     }
     /* Config apply must mint a fresh request generation even when the input
      * device string is unchanged, otherwise same-value retries after a failed
-     * apply are mistaken for stale state and never reach the controller. */
+     * apply are mistaken for stale state and never reach the controller.
+     * Omitted rtl_ppm must preserve the live correction instead of clearing it
+     * back to the config struct's zero-initialized default. */
     (void)rtl_stream_request_ppm(opts, cfg->rtl_ppm);
 }
 

tests/io/test_io_rtl_stream_ppm_sync.cpp

@@ -77,11 +77,70 @@ test_adjust_and_getter_use_active_snapshot_when_caller_is_stale(void) {
     return rc;
 }
 
+static int
+test_c_api_create_mirrored_updates_live_caller_opts(void) {
+    dsd_opts caller_opts;
+    init_test_opts(&caller_opts);
+    caller_opts.rtlsdr_ppm_error = 11;
+
+    RtlSdrContext* ctx = nullptr;
+
+    int rc = 0;
+    rc |= expect_int_eq("c api mirrored create rc", rtl_stream_create_mirrored(&caller_opts, &ctx), 0);
+    if (!ctx) {
+        std::fprintf(stderr, "FAIL: c api mirrored create returned null ctx\n");
+        return 1;
+    }
+
+    dsd_opts request_opts;
+    init_test_opts(&request_opts);
+    request_opts.rtlsdr_ppm_error = 0;
+
+    rc |= expect_int_eq("request through live helper rc", rtl_stream_request_ppm(&request_opts, -12), 0);
+    rc |= expect_int_eq("mirrored caller updated", caller_opts.rtlsdr_ppm_error, -12);
+    rc |= expect_int_eq("request opts updated", request_opts.rtlsdr_ppm_error, -12);
+    rc |= expect_int_eq("getter observes mirrored caller", rtl_stream_get_requested_ppm(&caller_opts), -12);
+
+    rc |= expect_int_eq("c api mirrored destroy rc", rtl_stream_destroy(ctx), 0);
+    return rc;
+}
+
+static int
+test_c_api_create_preserves_const_source_snapshot(void) {
+    dsd_opts seed_opts;
+    init_test_opts(&seed_opts);
+    seed_opts.rtlsdr_ppm_error = 11;
+
+    const dsd_opts const_source_opts = seed_opts;
+    RtlSdrContext* ctx = nullptr;
+
+    int rc = 0;
+    rc |= expect_int_eq("c api create rc", rtl_stream_create(&const_source_opts, &ctx), 0);
+    if (!ctx) {
+        std::fprintf(stderr, "FAIL: c api create returned null ctx\n");
+        return 1;
+    }
+
+    dsd_opts request_opts;
+    init_test_opts(&request_opts);
+    request_opts.rtlsdr_ppm_error = 0;
+
+    rc |= expect_int_eq("request through live helper rc", rtl_stream_request_ppm(&request_opts, -12), 0);
+    rc |= expect_int_eq("const source opts remain unchanged", const_source_opts.rtlsdr_ppm_error, 11);
+    rc |= expect_int_eq("request opts updated", request_opts.rtlsdr_ppm_error, -12);
+    rc |= expect_int_eq("getter still observes active snapshot", rtl_stream_get_requested_ppm(&const_source_opts), -12);
+
+    rc |= expect_int_eq("c api destroy rc", rtl_stream_destroy(ctx), 0);
+    return rc;
+}
+
 int
 main(void) {
     int rc = 0;
     rc |= test_caller_request_updates_active_snapshot();
     rc |= test_active_request_updates_caller_snapshot();
     rc |= test_adjust_and_getter_use_active_snapshot_when_caller_is_stale();
+    rc |= test_c_api_create_mirrored_updates_live_caller_opts();
+    rc |= test_c_api_create_preserves_const_source_snapshot();
     return rc ? 1 : 0;
 }