perf(iconv): hoist per-char dispatch for UTF-8 source — UTF-8->UTF-32 ~2.5x faster (bd-48uzu9)

Found an unbenched real gap: iconv non-ASCII transcoding is 2-3.4x slower than
glibc (release, same machine): UTF-8->UTF-32LE fl 16.8us vs glibc 5.0us (3.39x),
UTF-8->KOI8-R fl 17.3us vs glibc 7.5us (2.31x) on a 3686B cyrillic-heavy buffer.
Root cause: the convert loop dispatches decode_char + encode_char (two ~100-arm
matches + nested calls + a redundant char::from_u32) for EVERY character.

LEVER (one): a tight monomorphic UTF-8-source fast path that inlines the decode
+ encode for the hot targets (UTF-32LE/BE, UTF-16LE/BE, single-byte via the
cached reverse map). Placed after the existing ASCII/sb_translation fast paths
(so their SIMD bulk-copy still wins). ANY non-trivial outcome — incomplete /
invalid sequence, out-of-range scalar, unrepresentable char, no output space, or
a pending BOM — leaves in_pos/out_pos untouched and falls through to the unchanged
generic body, so EILSEQ/EINVAL/E2BIG ordering and the long-tail encodings are
byte-for-byte identical.

Before -> after (release microbench, median of runs):
  UTF-8->UTF-32LE: 16.8us -> ~6.5us  (~2.5x; now 1.2-1.5x glibc, was 3.39x)
  UTF-8->UTF-16:   similar
  UTF-8->KOI8-R:   unchanged (bottleneck is the reverse-map binary search; tracked
                   as a separate lever in bd-48uzu9)

Isomorphism proof: iconv_differential_fuzz (live glibc oracle — explicitly covers
UTF-16LE/BE + UTF-32LE/BE <-> UTF-8 incl. astral/surrogate-pair cases) green;
conformance_diff_iconv 49 cases green; iconv_abi_test green; NEW
golden_iconv_utf8_fastpath.rs pins SHA-256 of the converted corpus for all four
fixed-width targets.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Dicklesworthstone

crates/frankenlibc-abi/tests/golden_iconv_utf8_fastpath.rs

@@ -0,0 +1,63 @@
+#![cfg(target_os = "linux")]
+//! Golden-output gate for the UTF-8-source fast path in `frankenlibc_core::iconv`.
+//!
+//! The convert loop has a hot-path specialization for `UTF-8 -> {UTF-32LE/BE,
+//! UTF-16LE/BE, single-byte}` that inlines the decode/encode to skip the generic
+//! per-char `decode_char`/`encode_char` dispatch. It must stay byte-for-byte
+//! identical to the generic path. This pins a SHA-256 over a representative
+//! corpus (ASCII + 2-byte Cyrillic + 3-byte CJK + 4-byte emoji) converted to each
+//! fast-path target, so any future drift in the specialization is caught here in
+//! addition to the live-glibc `iconv_differential_fuzz`.
+
+use frankenlibc_core::iconv::{iconv, iconv_open};
+use sha2::{Digest, Sha256};
+
+fn corpus() -> Vec<u8> {
+    // ASCII run, Cyrillic (2-byte), CJK (3-byte), emoji (4-byte), interleaved so
+    // the ASCII fast path, the multibyte decode, and surrogate-pair UTF-16
+    // encoding are all exercised.
+    let mut s = String::new();
+    for i in 0..400 {
+        s.push_str("token");
+        s.push(char::from_u32(0x0410 + (i % 0x40)).unwrap()); // А..я
+        s.push(char::from_u32(0x4E00 + (i % 0x100)).unwrap()); // CJK
+        if i % 3 == 0 {
+            s.push('😀'); // U+1F600, 4-byte UTF-8 / surrogate pair in UTF-16
+        }
+    }
+    s.into_bytes()
+}
+
+fn convert(to: &[u8], src: &[u8]) -> Vec<u8> {
+    let mut cd = iconv_open(to, b"UTF-8").expect("iconv_open");
+    let mut out = vec![0u8; src.len() * 4 + 16];
+    let r = iconv(&mut cd, Some(src), &mut out).expect("iconv");
+    out.truncate(r.out_written);
+    out
+}
+
+fn hex(bytes: &[u8]) -> String {
+    let mut h = Sha256::new();
+    h.update(bytes);
+    h.finalize().iter().map(|b| format!("{b:02x}")).collect()
+}
+
+#[test]
+fn iconv_utf8_fastpath_golden_sha256() {
+    let src = corpus();
+    // (target, pinned sha256 of the converted bytes).
+    let pins: &[(&[u8], &str)] = &[
+        (b"UTF-32LE", "9382fecee5c337ccff5db539b234eea072d55cac913068cd7b9c992d43379cb3"),
+        (b"UTF-32BE", "5fd675572d6cd289805314c18263fc0f1a612657bd6fe3db8648ed9799a32836"),
+        (b"UTF-16LE", "a894b8ad38008d8a86c591b35d4ef280758b3ccaaadabfad77b4a2e77fe81645"),
+        (b"UTF-16BE", "5f57cff0b2b725f9a1160cc00fee638092cb4c17bb9292f9228c304f640affa6"),
+    ];
+    for (to, pin) in pins {
+        let out = convert(to, &src);
+        let got = hex(&out);
+        eprintln!("{}: sha256={got} ({}B)", String::from_utf8_lossy(to), out.len());
+        if !pin.starts_with("__P") {
+            assert_eq!(&got, pin, "iconv UTF-8->{} golden drifted", String::from_utf8_lossy(to));
+        }
+    }
+}

crates/frankenlibc-core/src/iconv/mod.rs

@@ -9425,6 +9425,74 @@ pub fn iconv(
             }
         }
 
+        // Hot-path specialization (perf): UTF-8 source is the dominant direction,
+        // yet the generic body below dispatches decode_char + encode_char (two
+        // ~100-arm matches plus nested calls) for every character. For the common
+        // UTF-8 -> fixed-width-Unicode and UTF-8 -> single-byte targets, inline
+        // the UTF-8 decode and the encode so the steady state is a tight loop.
+        // This is byte-for-byte ISOMORPHIC to the generic path: it uses the SAME
+        // `utf8_decode_step` + `char::from_u32` validation and the SAME encode
+        // logic, and ANY non-trivial outcome (incomplete/invalid sequence,
+        // out-of-range scalar, unrepresentable char, insufficient output, or a
+        // pending BOM) leaves `in_pos`/`out_pos` untouched and falls through to
+        // the generic body, which reproduces the exact EILSEQ/EINVAL/E2BIG
+        // ordering. Placed after the ASCII/sb_translation fast paths so their
+        // SIMD bulk-copy still wins for ASCII-transparent pairs.
+        if from_enc == Encoding::Utf8 && !cd.emit_bom {
+            let b0 = input[in_pos];
+            let decoded = if b0 < 0x80 {
+                Some((u32::from(b0), 1usize))
+            } else {
+                match crate::string::wchar::utf8_decode_step(&input[in_pos..]) {
+                    crate::string::wchar::Utf8Step::Char { wc, len } => Some((wc, len)),
+                    _ => None,
+                }
+            };
+            if let Some((wc, len)) = decoded
+                && let Some(ch) = char::from_u32(wc)
+            {
+                let avail = outbuf.len() - out_pos;
+                let wrote: Option<usize> = match cd.to {
+                    Encoding::Utf32Le if avail >= 4 => {
+                        outbuf[out_pos..out_pos + 4].copy_from_slice(&(ch as u32).to_le_bytes());
+                        Some(4)
+                    }
+                    Encoding::Utf32Be if avail >= 4 => {
+                        outbuf[out_pos..out_pos + 4].copy_from_slice(&(ch as u32).to_be_bytes());
+                        Some(4)
+                    }
+                    Encoding::Utf16Le | Encoding::Utf16Be => {
+                        let mut units = [0u16; 2];
+                        let enc = ch.encode_utf16(&mut units);
+                        let needed = enc.len() * 2;
+                        if avail >= needed {
+                            let be = matches!(cd.to, Encoding::Utf16Be);
+                            for (idx, unit) in enc.iter().enumerate() {
+                                let bytes = if be { unit.to_be_bytes() } else { unit.to_le_bytes() };
+                                outbuf[out_pos + idx * 2] = bytes[0];
+                                outbuf[out_pos + idx * 2 + 1] = bytes[1];
+                            }
+                            Some(needed)
+                        } else {
+                            None
+                        }
+                    }
+                    _ => match cd.to_reverse.as_ref() {
+                        Some(rev) if avail >= 1 => rev.lookup(ch).map(|byte| {
+                            outbuf[out_pos] = byte;
+                            1
+                        }),
+                        _ => None,
+                    },
+                };
+                if let Some(w) = wrote {
+                    in_pos += len;
+                    out_pos += w;
+                    continue;
+                }
+            }
+        }
+
         let (ch, consumed) = match decode_char(from_enc, &input[in_pos..]) {
             Ok(v) => v,
             Err(DecodeError::Incomplete) => {