io(rtl),dsp,tests: fix FS/4 rotation phase handling

Author: arancormonk

include/dsd-neo/dsp/simd_widen.h

@@ -60,12 +60,49 @@ void widen_u8_to_f32_bias127(const unsigned char* src, float* dst, uint32_t len)
  */
 void widen_rotate90_u8_to_f32_bias127(const unsigned char* src, float* dst, uint32_t len);
 
+/**
+ * @brief Rotate 90° (IQ) and widen u8→float centered at 127.5 with explicit phase.
+ *
+ * Applies the `j^n` sequence starting at `phase & 3`, where phase 0 leaves the
+ * first I/Q pair unchanged. Processes `floor(len/2)` pairs and returns the phase
+ * to use for the next pair-aligned chunk.
+ *
+ * Callers must preserve I/Q byte alignment themselves. If a transport split can
+ * leave one dangling byte, buffer that byte externally and resume with a
+ * pair-aligned span on the next call.
+ *
+ * @param src Source buffer of unsigned bytes (I/Q interleaved).
+ * @param dst Destination float buffer.
+ * @param len Number of bytes in src to process.
+ * @param phase Starting rotation phase in [0, 3]; other bits are ignored.
+ * @return Next rotation phase after processing the available I/Q pairs.
+ */
+uint32_t widen_rotate90_u8_to_f32_bias127_phase(const unsigned char* src, float* dst, uint32_t len, uint32_t phase);
+
+/**
+ * @brief Legacy in-place byte-domain 90° IQ rotation with explicit phase.
+ *
+ * Rotates interleaved u8 I/Q samples using byte-domain negation (`255 - x`).
+ * Intended to pair with `widen_u8_to_f32_bias128_scalar()` for the legacy
+ * two-pass RTL path. Processes `floor(len/2)` pairs and returns the phase to
+ * use for the next pair-aligned chunk.
+ *
+ * Callers must preserve I/Q byte alignment themselves. If a transport split can
+ * leave one dangling byte, buffer that byte externally and resume with a
+ * pair-aligned span on the next call.
+ *
+ * @param buf Buffer of interleaved I/Q bytes to rotate in place.
+ * @param len Number of bytes in buf to process.
+ * @param phase Starting rotation phase in [0, 3]; other bits are ignored.
+ * @return Next rotation phase after processing the available I/Q pairs.
+ */
+uint32_t rotate90_u8_inplace_phase(unsigned char* buf, uint32_t len, uint32_t phase);
+
 /**
  * @brief Widen u8 to float centered at 128 (for legacy pre-rotation negation).
  *
  * Scalar widening that subtracts 128 instead of 127. Intended to pair with
- * legacy byte-wise rotate_90(u8) which performs 255-x negation so that overall
- * effect equals correct centered negation (127-x).
+ * legacy byte-wise `rotate90_u8_inplace_phase()` which performs 255-x negation.
  *
  * @param src Source buffer of unsigned bytes.
  * @param dst Destination float buffer.

include/dsd-neo/io/rtl_device.h

@@ -201,11 +201,15 @@ int rtl_device_stop_async(struct rtl_device* dev);
  * @brief Mute the incoming raw USB/TCP byte stream for a short duration.
  *
  * Note: The argument is in raw input BYTES (u8 I/Q interleaved), not int16
- * samples. This matches how the underlying callback consumes the value
- * (clamping and subtracting from the remaining byte count per callback).
+ * samples. The requested mute span is rounded up to whole I/Q pairs, but the
+ * internal remaining byte count may still go odd between rtl_tcp callbacks
+ * because TCP read boundaries are arbitrary. If a prior chunk ended on an odd
+ * byte boundary, the implementation may discard one additional future byte
+ * internally so unmuted processing resumes on an I/Q boundary.
  *
  * @param dev RTL-SDR device handle.
- * @param bytes Number of input bytes to overwrite with 0x7F (mute).
+ * @param bytes Number of input bytes to discard while muted. Odd values are
+ *              rounded up so the muted span always covers whole I/Q pairs.
  */
 void rtl_device_mute(struct rtl_device* dev, int bytes);
 

src/dsp/simd_widen.cpp

@@ -16,6 +16,51 @@
 
 #include <stdint.h>
 
+static inline void
+apply_j4_rotation_f32(float in_i, float in_q, uint32_t phase, float* out_i, float* out_q) {
+    switch (phase & 3U) {
+        case 0:
+            *out_i = in_i;
+            *out_q = in_q;
+            break;
+        case 1:
+            *out_i = -in_q;
+            *out_q = in_i;
+            break;
+        case 2:
+            *out_i = -in_i;
+            *out_q = -in_q;
+            break;
+        default:
+            *out_i = in_q;
+            *out_q = -in_i;
+            break;
+    }
+}
+
+static inline void
+apply_j4_rotation_u8(unsigned char in_i, unsigned char in_q, uint32_t phase, unsigned char* out_i,
+                     unsigned char* out_q) {
+    switch (phase & 3U) {
+        case 0:
+            *out_i = in_i;
+            *out_q = in_q;
+            break;
+        case 1:
+            *out_i = (unsigned char)(255U - (uint32_t)in_q);
+            *out_q = in_i;
+            break;
+        case 2:
+            *out_i = (unsigned char)(255U - (uint32_t)in_i);
+            *out_q = (unsigned char)(255U - (uint32_t)in_q);
+            break;
+        default:
+            *out_i = in_q;
+            *out_q = (unsigned char)(255U - (uint32_t)in_i);
+            break;
+    }
+}
+
 void
 widen_u8_to_f32_bias127(const unsigned char* src, float* dst, uint32_t len) {
     if (!src || !dst || len == 0) {
@@ -40,35 +85,48 @@ widen_u8_to_f32_bias128_scalar(const unsigned char* src, float* dst, uint32_t le
     }
 }
 
-void
-widen_rotate90_u8_to_f32_bias127(const unsigned char* src, float* dst, uint32_t len) {
+uint32_t
+widen_rotate90_u8_to_f32_bias127_phase(const unsigned char* src, float* dst, uint32_t len, uint32_t phase) {
+    uint32_t cur_phase = phase & 3U;
     if (!src || !dst || len < 2) {
-        return;
+        return cur_phase;
     }
+
     const float inv = 1.0f / 127.5f;
     uint32_t pairs = len >> 1;
     for (uint32_t n = 0; n < pairs; n++) {
         uint32_t idx = n << 1;
         float i_raw = ((float)src[idx + 0] - 127.5f) * inv;
         float q_raw = ((float)src[idx + 1] - 127.5f) * inv;
-        float ri = i_raw;
-        float rq = q_raw;
-        switch (n & 3U) {
-            case 1:
-                ri = -q_raw;
-                rq = i_raw;
-                break; /* +90° */
-            case 2:
-                ri = -i_raw;
-                rq = -q_raw;
-                break; /* 180° */
-            case 3:
-                ri = q_raw;
-                rq = -i_raw;
-                break;      /* -90° */
-            default: break; /* 0° */
-        }
-        dst[idx + 0] = ri;
-        dst[idx + 1] = rq;
+        apply_j4_rotation_f32(i_raw, q_raw, cur_phase, &dst[idx + 0], &dst[idx + 1]);
+        cur_phase = (cur_phase + 1U) & 3U;
+    }
+
+    return cur_phase;
+}
+
+void
+widen_rotate90_u8_to_f32_bias127(const unsigned char* src, float* dst, uint32_t len) {
+    (void)widen_rotate90_u8_to_f32_bias127_phase(src, dst, len, 0U);
+}
+
+uint32_t
+rotate90_u8_inplace_phase(unsigned char* buf, uint32_t len, uint32_t phase) {
+    uint32_t cur_phase = phase & 3U;
+    if (!buf || len < 2) {
+        return cur_phase;
     }
+
+    uint32_t pairs = len >> 1;
+    for (uint32_t n = 0; n < pairs; n++) {
+        uint32_t idx = n << 1;
+        unsigned char out_i = 0;
+        unsigned char out_q = 0;
+        apply_j4_rotation_u8(buf[idx + 0], buf[idx + 1], cur_phase, &out_i, &out_q);
+        buf[idx + 0] = out_i;
+        buf[idx + 1] = out_q;
+        cur_phase = (cur_phase + 1U) & 3U;
+    }
+
+    return cur_phase;
 }

src/io/radio/rtl_capture_phase.h

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+/*
+ * Copyright (C) 2026 by arancormonk <180709949+arancormonk@users.noreply.github.com>
+ */
+
+/**
+ * @file
+ * @brief Helpers for preserving capture-side FS/4 rotation phase across chunks and drops.
+ */
+
+#ifndef DSD_NEO_IO_RADIO_RTL_CAPTURE_PHASE_H
+#define DSD_NEO_IO_RADIO_RTL_CAPTURE_PHASE_H
+
+#include <limits.h>
+#include <stddef.h>
+
+struct rtl_capture_u8_byte_carry {
+    unsigned char byte;
+    unsigned int valid;
+};
+
+static inline void
+rtl_capture_u8_byte_carry_clear(struct rtl_capture_u8_byte_carry* carry) {
+    if (!carry) {
+        return;
+    }
+    carry->byte = 0;
+    carry->valid = 0;
+}
+
+static inline void
+rtl_capture_u8_byte_carry_save(struct rtl_capture_u8_byte_carry* carry, unsigned char byte) {
+    if (!carry) {
+        return;
+    }
+    carry->byte = byte;
+    carry->valid = 1U;
+}
+
+static inline size_t
+rtl_capture_u8_byte_carry_ready_bytes(size_t byte_count, const struct rtl_capture_u8_byte_carry* carry) {
+    size_t total = byte_count + (size_t)((carry && carry->valid) ? 1U : 0U);
+    return total & ~((size_t)1U);
+}
+
+static inline size_t
+rtl_capture_u8_byte_carry_consume_prefix(const unsigned char* src, size_t byte_count,
+                                         struct rtl_capture_u8_byte_carry* carry, unsigned char out_pair[2]) {
+    if (!src || byte_count == 0 || !carry || !carry->valid || !out_pair) {
+        return 0;
+    }
+    out_pair[0] = carry->byte;
+    out_pair[1] = src[0];
+    rtl_capture_u8_byte_carry_clear(carry);
+    return 1;
+}
+
+static inline size_t
+rtl_capture_u8_byte_carry_drop_aligned(const unsigned char* src, size_t byte_count,
+                                       struct rtl_capture_u8_byte_carry* carry) {
+    size_t total = byte_count + (size_t)((carry && carry->valid) ? 1U : 0U);
+    if ((total & 1U) == 0U) {
+        rtl_capture_u8_byte_carry_clear(carry);
+        return total;
+    }
+    if (!src || byte_count == 0) {
+        return 0;
+    }
+    rtl_capture_u8_byte_carry_save(carry, src[byte_count - 1]);
+    return total - 1U;
+}
+
+static inline int
+rtl_capture_phase_advance_pairs(int phase, size_t pair_count) {
+    return (phase + (int)(pair_count & 3U)) & 3;
+}
+
+static inline int
+rtl_capture_phase_advance_u8_bytes(int phase, size_t byte_count) {
+    /* Raw u8 input is interleaved I/Q, so only full byte pairs advance the j^n state. */
+    return rtl_capture_phase_advance_pairs(phase, byte_count >> 1);
+}
+
+static inline int
+rtl_capture_phase_advance_u8_bytes_fragmented(int phase, size_t byte_count, unsigned int* partial_byte_count) {
+    if (!partial_byte_count) {
+        return rtl_capture_phase_advance_u8_bytes(phase, byte_count);
+    }
+    size_t total = byte_count + (size_t)(*partial_byte_count & 1U);
+    *partial_byte_count = (unsigned int)(total & 1U);
+    return rtl_capture_phase_advance_pairs(phase, total >> 1);
+}
+
+static inline int
+rtl_capture_align_u8_iq_bytes(int byte_count) {
+    if (byte_count <= 0) {
+        return 0;
+    }
+    if ((byte_count & 1) == 0) {
+        return byte_count;
+    }
+    if (byte_count >= (INT_MAX - 1)) {
+        return INT_MAX - 1;
+    }
+    return byte_count + 1;
+}
+
+static inline int
+rtl_capture_restart_fragmented_u8_bytes(int byte_count, unsigned int* partial_byte_count) {
+    /* A new stream boundary cannot complete a partial I/Q byte from the old stream. */
+    if (partial_byte_count) {
+        *partial_byte_count = 0;
+    }
+    return rtl_capture_align_u8_iq_bytes(byte_count);
+}
+
+static inline int
+rtl_capture_restart_u8_stream(int* phase, int byte_count, unsigned int* partial_byte_count) {
+    /* A fresh stream always resumes with phase-0 sample alignment. */
+    if (phase) {
+        *phase = 0;
+    }
+    return rtl_capture_restart_fragmented_u8_bytes(byte_count, partial_byte_count);
+}
+
+static inline int
+rtl_capture_restart_u8_stream_with_pending(int* phase, int byte_count, unsigned int* partial_byte_count,
+                                           size_t* pending_byte_count) {
+    /* Buffered raw bytes cannot be stitched across an explicit stream restart. */
+    if (pending_byte_count) {
+        *pending_byte_count = 0;
+    }
+    return rtl_capture_restart_u8_stream(phase, byte_count, partial_byte_count);
+}
+
+#endif /* DSD_NEO_IO_RADIO_RTL_CAPTURE_PHASE_H */