valentine

mux.rs (19108B)

---

 //! Routing (mux) model and write encoding — the highest-risk part of the device
 //! protocol, built deliberately and conservatively.
 //!
 //! The device routing is a flat array `mux[dest] = source`, where `dest` and
 //! `source` are **port numbers**: a flattened index across all port types in a
 //! fixed order (None, Analogue, S/PDIF, ADAT, Mix, PCM), counting that type's
 //! *outputs* (for destinations) or *inputs* (for sources). Hardware IDs
 //! (`base | index`) are a separate encoding used on the wire.
 //!
 //! Writing routing means re-emitting the **entire** mux as 3 tables (one per
 //! sample-rate band), each in `mux_assignment` order, every entry packed as
 //! `dest_id | (source_id << 12)`. We port the kernel's `scarlett2_usb_set_mux`
 //! exactly. **Nothing here writes to the device** — this module only models and
 //! encodes; the caller decides when (and a dry-run verifies first).
 
 use crate::matrix::MuxEntry;
 
 /// Port types in the device's canonical enumeration order. The numeric order is
 /// load-bearing: port-number flattening walks types in exactly this sequence.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum PortKind {
     None = 0,
     Analogue,
     Spdif,
     Adat,
     Mix,
     Pcm,
 }
 
 impl PortKind {
     pub const ORDER: [PortKind; 6] = [
         PortKind::None,
         PortKind::Analogue,
         PortKind::Spdif,
         PortKind::Adat,
         PortKind::Mix,
         PortKind::Pcm,
     ];
 
     /// Hardware ID base for this kind (matches `scarlett2_ports[].id`).
     pub fn id_base(self) -> u16 {
         match self {
             PortKind::None => 0x000,
             PortKind::Analogue => 0x080,
             PortKind::Spdif => 0x180,
             PortKind::Adat => 0x200,
             PortKind::Mix => 0x300,
             PortKind::Pcm => 0x600,
         }
     }
 }
 
 /// `(inputs, outputs)` counts per kind for the 18i20 g3, in [`PortKind::ORDER`].
 /// From `s18i20_gen3_info.port_count`.
 pub const PORT_COUNT_18I20_GEN3: [(u16, u16); 6] = [
     (1, 0),   // None
     (9, 10),  // Analogue (9 sources incl. talkback; 10 line outs)
     (2, 2),   // S/PDIF
     (8, 8),   // ADAT
     (12, 25), // Mix
     (20, 20), // PCM
 ];
 
 /// Direction selector for port-number ↔ id conversions.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Dir {
     In,
     Out,
 }
 
 fn count(pc: &[(u16, u16); 6], kind: PortKind, dir: Dir) -> u16 {
     let (i, o) = pc[kind as usize];
     match dir {
         Dir::In => i,
         Dir::Out => o,
     }
 }
 
 /// Convert a flat port number to a hardware id, in the given direction.
 /// Mirrors `scarlett2_mux_src_num_to_id` (and the OUT equivalent).
 pub fn num_to_id(pc: &[(u16, u16); 6], dir: Dir, mut num: u16) -> u16 {
     for kind in PortKind::ORDER {
         let c = count(pc, kind, dir);
         if num < c {
             return kind.id_base() | num;
         }
         num -= c;
     }
     0 // out of range → Off
 }
 
 /// Convert a hardware id to a flat port number, in the given direction.
 /// Mirrors `scarlett2_mux_id_to_num`. Returns None if the id isn't in range.
 pub fn id_to_num(pc: &[(u16, u16); 6], dir: Dir, id: u16) -> Option<u16> {
     let mut port_num = 0u16;
     for kind in PortKind::ORDER {
         let base = kind.id_base();
         let c = count(pc, kind, dir);
         if id >= base && id < base + c {
             return Some(port_num + (id - base));
         }
         port_num += c;
     }
     None
 }
 
 /// Total destination count (sum of outputs across kinds) = mux length.
 pub fn num_dsts(pc: &[(u16, u16); 6]) -> usize {
     pc.iter().map(|(_, o)| *o as usize).sum()
 }
 
 /// One `mux_assignment` entry: a run of `count` destinations of `kind` starting
 /// at output index `start`.
 #[derive(Debug, Clone, Copy)]
 pub struct Assign {
     pub kind: PortKind,
     pub start: u16,
     pub count: u16,
 }
 
 /// The 18i20 g3 mux_assignment tables (3 sample-rate bands), from
 /// `s18i20_gen3_info.mux_assignment`. Terminating `{0,0,0}` entries omitted.
 pub fn mux_assignment_18i20_gen3() -> [Vec<Assign>; 3] {
     use PortKind::*;
     let a = |kind, start, count| Assign { kind, start, count };
     [
         vec![
             a(Pcm, 0, 8), a(Pcm, 10, 10), a(Analogue, 0, 10), a(Spdif, 0, 2),
             a(Adat, 0, 8), a(Pcm, 8, 2), a(Mix, 0, 25), a(None, 0, 12),
         ],
         vec![
             a(Pcm, 0, 8), a(Pcm, 10, 8), a(Analogue, 0, 10), a(Spdif, 0, 2),
             a(Adat, 0, 8), a(Pcm, 8, 2), a(Mix, 0, 25), a(None, 0, 10),
         ],
         vec![
             a(Pcm, 0, 10), a(Analogue, 0, 10), a(Spdif, 0, 2), a(None, 0, 24),
         ],
     ]
 }
 
 /// Start port-number (OUT direction) of a kind — `scarlett2_get_port_start_num`.
 fn port_start_out(pc: &[(u16, u16); 6], kind: PortKind) -> u16 {
     let mut n = 0;
     for k in PortKind::ORDER {
         if k == kind {
             break;
         }
         n += count(pc, k, Dir::Out);
     }
     n
 }
 
 /// The full routing state: `mux[dest_num] = source_num`.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct MuxState {
     pub pc: [(u16, u16); 6],
     pub mux: Vec<u16>,
 }
 
 impl MuxState {
     /// Build from the device's `GET_MUX` entries (hardware ids), decoding each
     /// to port numbers. Unknown ids are ignored (left as Off).
     pub fn from_entries(pc: [(u16, u16); 6], entries: &[MuxEntry]) -> Self {
         let mut mux = vec![0u16; num_dsts(&pc)];
         for e in entries {
             if let (Some(dst), Some(src)) = (
                 id_to_num(&pc, Dir::Out, e.dest),
                 id_to_num(&pc, Dir::In, e.source),
             ) {
                 if (dst as usize) < mux.len() {
                     mux[dst as usize] = src;
                 }
             }
         }
         Self { pc, mux }
     }
 
     /// Set the source feeding a destination (both as port numbers).
     pub fn set(&mut self, dst: u16, src: u16) {
         if (dst as usize) < self.mux.len() {
             self.mux[dst as usize] = src;
         }
     }
 
     /// Current source port number feeding `dst`.
     pub fn get(&self, dst: u16) -> u16 {
         self.mux.get(dst as usize).copied().unwrap_or(0)
     }
 
     /// Encode all 3 sample-rate-band tables, ready for `write_routing_tables`.
     pub fn encode_all(&self, assign: &[Vec<Assign>; 3]) -> Vec<Vec<u32>> {
         assign.iter().map(|a| self.encode_table(a)).collect()
     }
 
     /// Encode one mux table to the `u32` payload values for SET_MUX, exactly as
     /// the kernel does: walk the assignment, pack `dst_id | (src_id << 12)`,
     /// empty (None/id 0) slots as 0.
     pub fn encode_table(&self, assign: &[Assign]) -> Vec<u32> {
         let mut out = Vec::new();
         for entry in assign {
             let base_dst_id = entry.kind.id_base() + entry.start;
             let mux_start = port_start_out(&self.pc, entry.kind) + entry.start;
             if entry.kind.id_base() == 0 {
                 // None: empty slots
                 for _ in 0..entry.count {
                     out.push(0);
                 }
                 continue;
             }
             for j in 0..entry.count {
                 let mux_idx = (mux_start + j) as usize;
                 let src_num = self.mux.get(mux_idx).copied().unwrap_or(0);
                 let src_id = num_to_id(&self.pc, Dir::In, src_num);
                 let dst_id = base_dst_id + j;
                 out.push(dst_id as u32 | ((src_id as u32) << 12));
             }
         }
         out
     }
 
     /// Round-trip a set of device entries through encode and decode the result
     /// back to `dest_id -> source_id`, for offline verification that our encoding
     /// reproduces the device's routing without loss. Pure; no device.
     pub fn roundtrip_decode(entries: &[MuxEntry], pc: [(u16, u16); 6]) -> Vec<(u16, u16)> {
         let st = MuxState::from_entries(pc, entries);
         let assign = mux_assignment_18i20_gen3();
         let mut out = Vec::new();
         for v in st.encode_table(&assign[0]) {
             let dst = (v & 0xfff) as u16;
             let src = ((v >> 12) & 0xfff) as u16;
             if dst != 0 {
                 out.push((dst, src));
             }
         }
         out
     }
 }
 
 /// A left/right grouping of ports: `right` is None for a lone mono port.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct PairRow {
     pub left: u16,
     pub right: Option<u16>,
     pub name: String,
 }
 
 /// Group ports of one direction into stereo pairs by kind: consecutive same-kind
 /// ports at even/odd index collapse into one row ("Analogue Out 1-2"); a lone
 /// trailing port stays mono. Used for both destinations (Dir::Out) and sources
 /// (Dir::In). For sources, a leading Off row (port 0) is included.
 fn pair_ports(pc: &[(u16, u16); 6], dir: Dir, name: impl Fn(u16) -> String) -> Vec<PairRow> {
     // Flat list of (port_num, kind, index_within_kind) in enumeration order.
     let mut flat: Vec<(u16, PortKind, u16)> = Vec::new();
     let mut port = 0u16;
     for kind in PortKind::ORDER {
         let c = count(pc, kind, dir);
         for idx in 0..c {
             flat.push((port, kind, idx));
             port += 1;
         }
     }
 
     let mut rows = Vec::new();
     let mut i = 0;
     while i < flat.len() {
         let (pl, kl, il) = flat[i];
         // None/Off ports stay mono (the single Off entry).
         let can_pair = kl != PortKind::None
             && i + 1 < flat.len()
             && flat[i + 1].1 == kl
             && il % 2 == 0
             && flat[i + 1].2 == il + 1;
         if can_pair {
             let pr = flat[i + 1].0;
             // "Analogue Out 1-2": kind word from the left name, indices joined.
             let lname = name(pl);
             let word = lname.rsplit_once(' ').map(|(w, _)| w).unwrap_or(&lname);
             rows.push(PairRow {
                 left: pl,
                 right: Some(pr),
                 name: format!("{word} {}-{}", il + 1, il + 2),
             });
             i += 2;
         } else {
             rows.push(PairRow { left: pl, right: None, name: name(pl) });
             i += 1;
         }
     }
     rows
 }
 
 /// Destinations grouped into stereo pairs (for the routing panel's default view).
 pub fn dest_pairs(pc: &[(u16, u16); 6]) -> Vec<PairRow> {
     pair_ports(pc, Dir::Out, |d| crate::ports::sink_name(num_to_id(pc, Dir::Out, d)))
 }
 
 /// Selectable sources grouped into stereo pairs, with Off first.
 pub fn source_pairs(pc: &[(u16, u16); 6]) -> Vec<PairRow> {
     pair_ports(pc, Dir::In, |s| {
         if s == 0 {
             "Off".to_string()
         } else {
             crate::ports::source_name(num_to_id(pc, Dir::In, s))
         }
     })
 }
 
 /// Enumerate every destination as `(dest_port_num, display_name)` in port order.
 pub fn dest_list(pc: &[(u16, u16); 6]) -> Vec<(u16, String)> {
     (0..num_dsts(pc) as u16)
         .map(|d| (d, crate::ports::sink_name(num_to_id(pc, Dir::Out, d))))
         .collect()
 }
 
 /// Enumerate every selectable source as `(src_port_num, display_name)`, starting
 /// with Off (port 0). Order matches the device's source numbering.
 pub fn source_list(pc: &[(u16, u16); 6]) -> Vec<(u16, String)> {
     let total_in: u16 = pc.iter().map(|(i, _)| *i).sum();
     (0..total_in)
         .map(|s| {
             let name = if s == 0 {
                 "Off".to_string()
             } else {
                 crate::ports::source_name(num_to_id(pc, Dir::In, s))
             };
             (s, name)
         })
         .collect()
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
 
     const PC: [(u16, u16); 6] = PORT_COUNT_18I20_GEN3;
 
     #[test]
     fn roundtrip_preserves_real_device_routing() {
         // The user's actual routing (from adatverify), incl. ADAT 7/8 ← PCM 19/20.
         // The round-trip MUST reproduce every entry — if any drops to Off, that's
         // the corruption that zeroed ADAT 7/8 on hardware.
         let e = |dst: u16, src: u16| MuxEntry { dest: dst, source: src };
         let entries = vec![
             // ADAT Out 1-8 (0x200..0x207) ← PCM 13-20 (0x60c..0x613)
             e(0x200, 0x60c), e(0x201, 0x60d), e(0x202, 0x60e), e(0x203, 0x60f),
             e(0x204, 0x610), e(0x205, 0x611), e(0x206, 0x612), e(0x207, 0x613),
             // Analogue Out 1-2 ← PCM 1-2
             e(0x080, 0x600), e(0x081, 0x601),
             // Mixer In 1-2 ← Analogue 1-2
             e(0x300, 0x080), e(0x301, 0x081),
         ];
         let got = MuxState::roundtrip_decode(&entries, PC);
         for me in &entries {
             let (dst, src) = (me.dest, me.source);
             let found = got.iter().find(|(d, _)| *d == dst).map(|(_, s)| *s);
             assert_eq!(
                 found,
                 Some(src),
                 "dest {dst:#05x} should map to src {src:#05x}, got {found:?}"
             );
         }
     }
 
     #[test]
     fn per_table_entry_counts_match_assignment() {
         // Each encoded table's length must equal the sum of its assignment
         // entry counts (the kernel sends exactly that many words). A mismatch —
         // especially an over-long table 1/2 — is a prime 0x3 suspect.
         let st = MuxState { pc: PC, mux: vec![0u16; num_dsts(&PC)] };
         let assign = mux_assignment_18i20_gen3();
         for (t, a) in assign.iter().enumerate() {
             let expected: usize = a.iter().map(|e| e.count as usize).sum();
             let got = st.encode_table(a).len();
             assert_eq!(got, expected, "table {t}: encoded {got} != assignment sum {expected}");
         }
         // Print the actual per-table sizes for the record.
         let sizes: Vec<usize> = assign.iter().map(|a| st.encode_table(a).len()).collect();
         // Kernel/Focusrite: tables are 77, 75, 36-ish depending on band. Just
         // assert table 0 is the largest and all are <= SCARLETT2_MUX_MAX (77).
         assert!(sizes.iter().all(|&s| s <= 77), "a table exceeds MUX_MAX 77: {sizes:?}");
     }
 
     #[test]
     fn encoded_table_covers_all_adat_destinations() {
         // Every ADAT Out (0x200..0x207) must appear as a destination in the
         // encoded table 0. If 7/8 are missing, the assignment table is wrong and
         // a write would corrupt/zero them — the suspected cause.
         let st = MuxState { pc: PC, mux: vec![0u16; num_dsts(&PC)] };
         let table = st.encode_table(&mux_assignment_18i20_gen3()[0]);
         let dests: std::collections::HashSet<u16> =
             table.iter().map(|v| (v & 0xfff) as u16).collect();
         for i in 0..8u16 {
             assert!(
                 dests.contains(&(0x200 + i)),
                 "ADAT Out {} (id {:#05x}) missing from encoded table",
                 i + 1,
                 0x200 + i
             );
         }
     }
 
     #[test]
     fn encoded_table_has_no_duplicate_destinations() {
         // Each destination must appear at most once; a dup means two entries
         // fight over one dest (device may reject → 0x3, or last-wins corrupts).
         let st = MuxState { pc: PC, mux: vec![0u16; num_dsts(&PC)] };
         let table = st.encode_table(&mux_assignment_18i20_gen3()[0]);
         let mut seen = std::collections::HashSet::new();
         for v in &table {
             let dst = (v & 0xfff) as u16;
             if dst != 0 {
                 assert!(seen.insert(dst), "duplicate destination {dst:#05x} in table");
             }
         }
     }
 
     #[test]
     fn dest_pairs_group_stereo_and_keep_mono() {
         let dp = dest_pairs(&PC);
         // First row: Analogue Out 1-2 (paired).
         assert_eq!(dp[0].left, 0);
         assert_eq!(dp[0].right, Some(1));
         assert!(dp[0].name.contains("1-2"));
         // Every destination appears exactly once across the rows.
         let mut seen = std::collections::HashSet::new();
         for r in &dp {
             assert!(seen.insert(r.left));
             if let Some(rt) = r.right {
                 assert!(seen.insert(rt));
             }
         }
         assert_eq!(seen.len(), num_dsts(&PC));
     }
 
     #[test]
     fn source_pairs_start_with_off_mono() {
         let sp = source_pairs(&PC);
         assert_eq!(sp[0].left, 0);
         assert_eq!(sp[0].right, None);
         assert_eq!(sp[0].name, "Off");
     }
 
     #[test]
     fn dest_and_source_lists_are_complete() {
         let dests = dest_list(&PC);
         assert_eq!(dests.len(), 65);
         assert_eq!(dests[0].1, "Analogue Out 1");
         let srcs = source_list(&PC);
         // 1 off-as-port0 already counted in the (1,0) None inputs; total inputs
         // = 1+9+2+8+12+20 = 52.
         assert_eq!(srcs.len(), 52);
         assert_eq!(srcs[0].1, "Off");
     }
 
     #[test]
     fn source_num_to_id_matches_kernel_walk() {
         // src 0 = Off; src 1 = Analogue 1 (0x080); src 9 = Analogue 9 (0x088);
         // then S/PDIF, ADAT, Mix, PCM.
         assert_eq!(num_to_id(&PC, Dir::In, 0), 0x000);
         assert_eq!(num_to_id(&PC, Dir::In, 1), 0x080);
         assert_eq!(num_to_id(&PC, Dir::In, 9), 0x088); // talkback
         assert_eq!(num_to_id(&PC, Dir::In, 10), 0x180); // S/PDIF 1
         assert_eq!(num_to_id(&PC, Dir::In, 12), 0x200); // ADAT 1
         assert_eq!(num_to_id(&PC, Dir::In, 20), 0x300); // Mix A
         assert_eq!(num_to_id(&PC, Dir::In, 32), 0x600); // PCM 1
     }
 
     #[test]
     fn dest_id_to_num_matches_probe_layout() {
         // Verified against the metermap probe: Analogue Out 0..9, S/PDIF 10..11,
         // ADAT 12..19, Mixer In 20..44, PCM cap 45..64.
         assert_eq!(id_to_num(&PC, Dir::Out, 0x080), Some(0)); // Analogue Out 1
         assert_eq!(id_to_num(&PC, Dir::Out, 0x200), Some(12)); // ADAT Out 1
         assert_eq!(id_to_num(&PC, Dir::Out, 0x300), Some(20)); // Mixer In 1
         assert_eq!(id_to_num(&PC, Dir::Out, 0x600), Some(45)); // PCM cap 1
     }
 
     #[test]
     fn num_id_round_trip_in_and_out() {
         for n in 0..num_dsts(&PC) as u16 {
             let id = num_to_id(&PC, Dir::Out, n);
             assert_eq!(id_to_num(&PC, Dir::Out, id), Some(n), "out dst {n}");
         }
     }
 
     #[test]
     fn total_dst_count_is_65() {
         assert_eq!(num_dsts(&PC), 65);
     }
 
     #[test]
     fn encode_then_decode_reproduces_state() {
         // The core safety property: build a state, encode every table, decode the
         // packed entries back, and confirm we recover the same routing. If this
         // holds, our write faithfully represents the model.
         let entries = vec![
             MuxEntry { dest: 0x080, source: 0x600 }, // Analogue Out 1 <- PCM 1
             MuxEntry { dest: 0x302, source: 0x082 }, // Mixer In 3 <- Analogue 3
             MuxEntry { dest: 0x60c, source: 0x200 }, // PCM cap 13 <- ADAT 1
         ];
         let st = MuxState::from_entries(PC, &entries);
         let assign = mux_assignment_18i20_gen3();
         // Decode table 0 and check our three routes survive the pack/unpack.
         let packed = st.encode_table(&assign[0]);
         let mut found = std::collections::HashMap::new();
         for v in packed {
             let dst_id = (v & 0xfff) as u16;
             let src_id = ((v >> 12) & 0xfff) as u16;
             if src_id != 0 {
                 found.insert(dst_id, src_id);
             }
         }
         assert_eq!(found.get(&0x080), Some(&0x600));
         assert_eq!(found.get(&0x302), Some(&0x082));
         assert_eq!(found.get(&0x60c), Some(&0x200));
     }
 }