scripts/ff400.sh hardcodes one FF400 port order; snd_fireface puts the ADAT block first or last

[mkovero]

Problem

The Fireface 400's JACK/ALSA channel order under snd_fireface is not stable. The ADAT (and S/PDIF) block sometimes comes before the analog AN1–AN8 block and sometimes after it. The operator reports this as expected behaviour at this point.

scripts/ff400.sh hardcodes one of the two orders, ADAT first (comment from line 42 onward, "confirmed empirically"; CHNAME at lines 46 and 125). It then writes that onto the ports with jack_alias (lines 130–131). On a boot where the order is the other one, every analog port is labelled ADAT and vice versa. Because the aliases look like driver output, jack_lsp -A is then read as evidence of physical routing.

That happened 2026-09-14 on pupu (192.168.9.27: snd_fireface, kernel 7.2.4-rt3, JACK via ALSA). The order that boot was analog first, measured two ways:

• A silent 18-channel jack_rec: capture_1..8 carry an analog floor (−107…−112 dBFS, plus room noise on the mic input), and capture_9..18 read exact digital zero.
• A −60 dBFS 1 kHz tone on playback_1 and on playback_2: the FF400's meter:stream-input and meter:analog-output rise on the same index, and the tone arrives on the analog input wired to that output.

The script's aliases were wrong for that boot, and the first probe drove an ADAT port. Any fixed table, in either direction, is wrong on some boots.

A second, separate problem with its rig copy (ff400-card1.sh): the init path forces mic phantom power off (numid=90 off,off), and pupu's measurement mic on IN1 needs it on.

Places to check

• What moves the order: boot, driver load, FireWire bus reset, JACK restart. Knowing when it can change decides when it must be re-checked.
• Silent detection that worked on pupu: with nothing connected to ADAT/S/PDIF, those captures read exact digital zero, and the analog inputs never do (a −107 dBFS floor is ~37 LSB at 24-bit). This breaks as soon as something is connected to an ADAT or S/PDIF input.
• The playback order has so far matched the capture order when both were checked; that is an observation, not a guarantee.

What must be true

• The script does not publish a channel-name mapping it has not determined for the running driver instance: detect it, take it as input, or stop aliasing.
• Phantom power is not forced to a fixed state by a generic init. It belongs to the rig profile (docs/rigs/<rig>.md, scripts/rig/hosts/<rig>.env in PR docs(rig): one runbook and scripts for testing binaries on a rig #441). PR docs(rig): one runbook and scripts for testing binaries on a rig #441's scripts check the analog block's position silently and refuse to emit when it is not where the profile expects.

What makes the check fail

On a boot with each order, run the script, then drive playback_1 at a low level. The check must go red if the alias shown for system:playback_1 names anything other than the port that carried the tone. Testing only on a boot with the script's hardcoded order cannot go red.

[mkovero]

The port count moves with the sample rate too. On pupu, JACK exposed 18 system:capture_* ports at 48 kHz and 14 at 96 kHz (2026-09-14, same FF400, same driver), so a moved block does not land at a fixed offset. Any detection has to count the ports at run time, not assume 18. PR #441's scripts/rig/lib/port_order.py locates the analog block by which captures are live (non-zero), and it read live 1-8 of 14 at 96 kHz.

[mkovero]

spec

type: bug

problem statement
scripts/ff400.sh publishes JACK channel-name aliases from one fixed table: 18 ports, ADAT/S/PDIF first. Under snd_fireface the FF400's block order is not stable (analog-first was measured on pupu on 2026-09-14), and the port count changes with sample rate (18 capture ports at 48 kHz, 14 at 96 kHz). When the table is wrong for the running driver instance, every analog port gets an ADAT alias and every ADAT port an analog one. The aliases look like driver output, so jack_lsp -A gets read as proof of routing, and on pupu the first probe drove an ADAT port because of it. That is a drive-path hazard: the stimulus reaches a port the operator did not pick. A second, separate problem is in the same script: its generic init forces mic phantom power off. That is wrong for any rig whose measurement mic needs phantom power (pupu, IN1). Phantom state belongs to each rig, not to a generic default.

acceptance criteria

• The script publishes no capture or playback alias unless it has determined the block order for the running driver instance. A value from an earlier boot, or from a table in the script, does not count as determined. The architect picks the mechanism from the three the issue names: detect, take as input, or stop aliasing.
• A playback mapping inferred only from the capture order counts as undetermined, unless the architect records the capture→playback coupling as accepted and cites the evidence. The issue calls that coupling an observation, not a guarantee.
• No port count is assumed. The script behaves correctly with 18 capture ports at 48 kHz and with 14 capture ports at 96 kHz on the FF400 — provenance: measured
• When the order cannot be determined (for example, something is connected to an ADAT or S/PDIF input, so those captures are no longer digital zero), the script prints that it did not set aliases and lists where to look. It does not state a cause, and it does not fall back to the fixed table.
• After the script runs, no FF400 channel-name alias shown by jack_lsp -A names a different port from the one it is attached to. This includes aliases left over from an earlier run of the script.
• The generic init no longer sets phantom power (numid=90) to a fixed state. The script changes phantom power only when given a value (from a rig profile or explicit input). It never prints a phantom state it neither set nor read back.
• Fail-test, playback, from the issue. Run it on the rig, once on a boot with analog-first order and once on a boot with ADAT-first order: run the script, drive system:playback_1 at −60 dBFS (the level that produced a readable arrival on pupu on 2026-09-14) — provenance: measured. The check goes red if the alias shown for system:playback_1 names any port other than the one that carried the tone. A run on the old hardcoded order alone does not satisfy this criterion.
• Fail-test, capture, on the same two boots: the alias shown for the capture port that receives the tone names the analog input the tone arrived on.
• Each fail-test run records: which order that boot had and how it was established (silent capture, tone, or both), the sample rate, the capture port count, and the per-run emission consent.

out of scope

• The rig's out-of-tree copy ff400-card1.sh on pupu. The operator updates it after this fix lands.
• Finding out what moves the order (boot, driver load, FireWire bus reset, JACK restart). This issue uses that only as input to the architect question below; the investigation itself is not part of this issue.
• Making snd_fireface's order stable. That is upstream driver behaviour.
• Getting a correct mapping while ADAT or S/PDIF inputs are in use. The script is only required to refuse in that case, not to succeed.
• PR docs(rig): one runbook and scripts for testing binaries on a rig #441's preflight and emit-refusal checks in scripts/rig/. They are already in that PR.
• The channel map in ac-daemon / ac config. This fix does not change which port ac drives; it only stops the script from mislabelling ports.

files likely affected

• scripts/ff400.sh — alias table, hardcoded port count, phantom-power init
• scripts/rig/lib/port_order.py, scripts/rig/hosts/pupu.env, docs/rigs/pupu.md — exist only on unmerged PR docs(rig): one runbook and scripts for testing binaries on a rig #441; possible reuse, and where phantom state could live
• docs/runbooks/rig-testing.md (PR docs(rig): one runbook and scripts for testing binaries on a rig #441) — unknown; only if it tells the operator to run ff400.sh

needs architect review
yes — four open questions:

1. Which of detect / take as input / stop aliasing to use. Each one changes what the fail-test can observe: with no aliases, the playback check can only confirm that no wrong alias is left over.
2. How this relates to PR docs(rig): one runbook and scripts for testing binaries on a rig #441. port_order.py there already finds the analog block silently (live 1-8 of 14 at 96 kHz). Should ff400.sh reuse it, duplicate it, or be replaced by scripts/rig/? The phantom criterion points at profile files that exist only on that unmerged PR. If that dependency stays, apply blocked with the condition "PR docs(rig): one runbook and scripts for testing binaries on a rig #441 merged → remove blocked".
3. Whether a mapping determined at init is still valid later. Nobody knows yet whether a JACK restart or a bus reset can change the order, so a correct alias can go stale.
4. Whether to accept the capture→playback order coupling (see criterion 2).

estimated complexity
medium: 2–8h — covers the script change only. The rig check on both orders has no time bound, because nobody knows yet how to force the second order.

[mkovero]

design decision

Revised 2026-09-14, re-entry from qa on PR #450. Option A (stop aliasing) and all of the alias, phantom, and #441 decisions still stand, unchanged. What changed:

1. Mixer widths: the old note ("read the width from amixer cget… nobody has checked whether they change with rate") is replaced. The widths are now established from upstream source. They do not follow sample rate, and analog-source-gain / adat-source-gain are 8 wide, not 18. The rule is now one rule for every array write (see mixer widths [revised]).
2. Alias tools: the jack_alias -u flag and the jack_lsp -A indentation are now checked on a real jack2, no longer an open assumption.
3. Tests: case (e) is revised and cases (h)–(i) are added. The current (e) ties control width to port count, which is the false coupling.
4. A new section, what PR fix: ff400.sh stops aliasing unstable FF400 port order #450 has to become, names what comes out of the branch.
   Sections without a [revised] mark are the original decision.

core question
What should scripts/ff400.sh publish as FF400 channel names on JACK ports: names it detects, names it is given, or none? The answer also settles triage's other questions: how this relates to #441, whether an alias can go stale, and whether playback order can be inferred from capture order.
[revised] Re-entry adds a second question. Which ALSA control widths may the script assume, now that criterion 3 forbids assuming a port count?

option A — stop aliasing, clear the script's own leftovers
ff400.sh sets no jack_alias at all. It removes every alias with the FF400: prefix (the namespace its old table wrote) from system:capture_* and system:playback_*. It reads the port list from jack_lsp when it runs. It prints that it set no aliases and lists where to look for the real order. show loses its CHNAME table and prints hardware index numbers without names. The generic init stops writing numid=90. All of this lives in scripts/ff400.sh, with no dependency on #441.
tradeoffs: This fixes the harm itself: a label that looks like driver output. It covers every sample rate, port count and block order, and it cannot go stale. The cost: QjackCtl and Carla users lose readable names on every boot, including boots where the old table happened to be right.

option B — detect the capture block silently, alias only what was detected
ff400.sh records 1 s from every system:capture_* port, finds the non-zero block the way #441's port_order.py does, and aliases only that block as AN1..AN8. It sets no playback aliases.
tradeoffs: This keeps some names, but the detection pins down very little:

• Of 14–18 capture ports, only the 8 analog ones get located. Exact-zero channels carry no information about which is ADAT and which is S/PDIF, so those names stay undetermined.
• No playback port gets located. Detecting playback needs emission, and a generic init script must not emit.
• The order inside the analog block (AN1 before AN2 …) is still assumed. On 2026-09-14 it was measured only for indices 1–2.
• The script would have to duplicate port_order.py or wait for docs(rig): one runbook and scripts for testing binaries on a rig #441 to merge.
• An alias set at init is never re-checked. If a FireWire bus reset can move the order while JACK keeps running, the alias goes wrong silently (triage Q3).

option C — take the order as input (ff400.sh --order analog-first|adat-first)
tradeoffs: This moves the decision to the operator. The operator can only learn the order from the same silent capture or from an emission probe. An order remembered from an earlier boot is exactly the value criterion 1 rules out. The published alias still looks like driver output, and a later reader cannot tell how old the input was.

recommendation
Option A. An alias is the one output that turns an unchecked assumption into something that looks like proof. Nothing in ac reads aliases: ac-daemon/src/audio has no JACK alias lookup, so dropping them affects no consumer. The check that actually protects the drive path already sits in the right place: #441's emitting scripts re-detect the analog block before every emission and refuse when it has moved. An alias set at init cannot give that guarantee (Q3), so publishing one adds risk and no protection.

Answers to triage's questions:

1. Mechanism: stop aliasing (A).
2. docs(rig): one runbook and scripts for testing binaries on a rig #441: no reuse, no duplication, no blocked. Once ff400.sh stops naming ports, it has no need to know the order. port_order.py stays the only place that detects it.
3. Staleness: moot under A, because no alias is published. The detection that matters runs per emission, in docs(rig): one runbook and scripts for testing binaries on a rig #441.
4. Capture→playback coupling: not accepted. Capture and playback have both been checked only on analog-first boots, so the evidence has never covered an order change. A coupling that was never observed across the event that would break it has no evidence behind it. Under A, nothing depends on it.

Phantom power: remove the numid=90 write and the phantom power: off line. Do not add a phantom input to this script. The criterion allows "only when given a value", and "never" satisfies it. Reason: on pupu (2026-09-15, #441 comment) the driver skipped writes that matched its cached value, and amixer cget returned that cache, not the device state. A generic script that set phantom from an input could not honestly print the resulting state. Per-rig phantom state and the toggle-write restore belong to the rig profile (docs/rigs/<rig>.md, #441) and are verified by emission.

[revised] Mixer widths — decision. Every array cset in the script (numid=8, 9..26, 45..62, 63..80) sends exactly the value count that the control reports for itself. The script reads all of those counts before its first mixer write. If any count is missing or unusable, it exits non-zero, names the numid, and writes nothing. Criterion 3 is about JACK port count; these are ALSA control widths, a separate quantity. The design no longer treats them as linked, and the script must not claim they are.

Evidence, from upstream source, not from the installed build — provenance: derived:

• snd_fireface (kernel sound/firewire/fireface/ff.c, spec_ff400) has pcm_capture_channels = {18, 14, 10} per rate mode. This explains the measured 18/14 JACK ports. The kernel directory creates no mixer controls.
• The mixer controls come from the userspace snd-firewire-ctl-services. In runtime/fireface/src/former_ctls.rs, add_int_elems(elem_id, elem_count, …, value_count, …) (signature in runtime/core/src/card_cntr.rs) is called with model constants from protocols/fireface/src/former/ff400.rs. None of them depends on rate:

numid	control	elements × values
8	output-volume	1 × 18
9–26	mixer:analog-source-gain	18 × 8
27–44	mixer:spdif-source-gain	18 × 2
45–62	mixer:adat-source-gain	18 × 8
63–80	mixer:stream-source-gain	18 × 18

Adding elements in that order yields exactly the numid ranges the script already uses, so the numid layout still stands as-is.

• Wrong-count writes fail silently, not loudly. amixer cset reads the current value (amixer.c, snd_ctl_elem_read before the parse). alsa-lib's snd_ctl_ascii_value_parse loops idx < count and never errors. Extra values are dropped. Missing values leave the rest at their current value, except that a comma-free string repeats its single value into every slot. So main's 18-value writes to 9..26 / 45..62 "work" because 10 zeros are thrown away. Qa's premise that "amixer cset will reject the count-mismatched write" does not hold. The defect class here is silent config, not an abort.

Why read the counts instead of hardcoding the table above: the table comes from upstream master. The ctl-service version installed on pupu has not been checked, and reading costs one cget per control. The table becomes the test fixture and the rig check, not a script literal.

affected modules

• scripts/ff400.sh — remove the alias table and alias writes; clear FF400: leftovers; remove CHNAME from show; remove the phantom write and its status line; [revised] check every array control's width before writing and write exactly that width
• scripts/ff400_test.sh — new rig-free test with stubbed jack_lsp / jack_alias / amixer on PATH

No crate changes.

file manifest

scripts/ff400.sh
scripts/ff400_test.sh

interface changes

• ff400.sh arguments: unchanged (show | +4dbu | -10dbv | high). No new flags.
• Behaviour: no longer creates JACK aliases; removes existing FF400:-prefixed aliases; no longer changes phantom power. [revised] Exits non-zero, before any mixer write, when a control width it needs cannot be read.
• Output text: the JACK aliases: lines are replaced (see notes). phantom power: off becomes a line saying the script does not change it. show loses the ADAT/S/PDIF/AN name column.
• No ZMQ, CLI (ac), Rust API or Cargo feature changes.

ZMQ protocol impact
no

implementation notes for developer

• Section order. The alias-clearing section runs first, before any amixer write. With set -e, a failing mixer write must not leave a wrong alias in place (criterion 5).
• Clearing leftovers. Take the port list from jack_lsp -A at run time, never from seq 1 18 (criterion 3). On each system:capture_* / system:playback_* port, unset only aliases that start with FF400:. jackd's ALSA backend sets its own alias on these ports, and that one stays. JACK allows 2 aliases per port, and the old script hid alias failures (2>/dev/null || true), so a port can still carry a stale alias from any earlier run. Do not suppress unalias failures. If any FF400: alias remains after the pass, name the port and exit non-zero.
• [revised] Alias tools — now checked. On the 192.168.9.25 dev box (jack2, "JACK example tools version 4"), jack_alias --help shows [options] portname alias with -u, --unalias, and jack_lsp -A prints each port name flush left with its aliases indented by exactly three spaces ( alsa_pcm:hw:…:out1). fix: ff400.sh stops aliasing unstable FF400 port order #450's parser and stubs match that output. Still unchecked: whether jackd lets a client unset an alias on a system: port that client does not own. The post-clear verify pass turns a refusal into a loud failure that names the port, so a refusal cannot pass silently. The rig check below settles it.
• JACK unreachable. When jack_lsp fails, do not print "no aliases". On pupu, jackd has kept running with its socket unlinked, and its aliases were still there. Print that the script could not reach a JACK server and did not check aliases, and name what to check (jack_lsp run as the user jackd runs as; ss -xlp | grep jack). Do not state a cause.
• Not-set line (criterion 4). Printed on every run, because under A the order is never determined. It says the script set no channel-name aliases, then lists where to find the actual order: a silent capture on every system:capture_*, where unconnected ADAT/S/PDIF inputs read exact digital zero; the FF400 meter:stream-input / meter:analog-output controls during a probe; the port-order row of scripts/rig/preflight.sh, where scripts/rig/ exists. No cause, no fallback to the table.
• show. Remove CHNAME and print the stream-source-gain diagonal by index only. The phantom readback row may stay, since criterion 6 allows a readback; label it as a driver-cache value. [revised] A row whose cget fails prints that it could not be read. It is not skipped (fix: ff400.sh stops aliasing unstable FF400 port order #450 currently has 2>/dev/null + continue, which makes a row vanish silently).
• [revised] Mixer widths. One helper, used for all four array families:
  • Read and check first. Before the first mixer cset (level mode included), read the value count of numid=8, 9..26, 45..62 and 63..80. Any empty or non-numeric count → exit non-zero, name the numid, write nothing. For a 63..80 row i, a count ≤ i means the numid layout differs from the one this script assumes. Treat it the same way: exit non-zero, name the numid. Do not write an all-zero row, which is what fix: ff400.sh stops aliasing unstable FF400 port order #450 does now.
  • Write exactly that count. Unity × count for numid=8; zeros × count for 9..26 / 45..62; the identity row for 63..80.
  • Source of the count. Read it from cget's info line (; type=INTEGER,access=…,values=N,…), which states the count directly, rather than by counting commas in the value line. Either is acceptable if the test covers it.
  • Messages print the width actually written (unity (32768) × N).
  • Comments state the widths are fixed by the ctl-service model and do not follow sample rate. Cite former_ctls.rs, not issue scripts/ff400.sh hardcodes one FF400 port order; snd_fireface puts the ADAT block first or last #444's port counts.
• Header comment. Lines 2–7 say "known defaults". State that the script sets no aliases and does not change phantom power. Add no claims about device state.
• Test model. scripts/rig/lib_test.sh on docs(rig): one runbook and scripts for testing binaries on a rig #441 (origin/rig-testing-runbook, not on main) shows the repo's rig-free shell-test style. ff400_test.sh puts its stubs first on PATH. Every case must be able to fail against current ff400.sh:
  • (a) FF400:capture_ADAT1 planted on system:capture_1 is gone after the run;
  • (b) a non-FF400: alias on the same port is untouched;
  • (c) no jack_alias call without -u;
  • (d) no cset numid=90;
  • [revised] (e) runs with 14 and with 18 JACK ports while the stub reports the same control widths both times. The alias result and every cset are unchanged across the two;
  • (f) a failing jack_lsp prints the "did not check" line, not "no aliases";
  • (g) a failing unalias → exit non-zero;
  • [added] (h) the amixer stub reports per-family widths matching the table (8 → 18, 9–26 / 45–62 → 8, 63–80 → 18). For every cset in $AMIXER_LOG, the value count equals the width the stub reported for that numid. This asserts on what the script sent. It does not simulate amixer rejecting a wrong count, because real amixer does not reject one (see evidence), and a stub that rejects would test a behaviour the real tool does not have. This case must go red against fix: ff400.sh stops aliasing unstable FF400 port order #450 as it stands (18 values to an 8-wide control);
  • [added] (i) the stub returns an empty cget for one 63..80 numid → exit non-zero, the numid is named, and the log contains no cset at all.
• Criteria 7–8 under this design. No FF400: alias exists after the script runs, so the tone step can confirm only that no wrong alias is left. The part that can fail is case (a) on the rig: plant the old table's aliases (run main's ff400.sh), run the new script, check jack_lsp -A. That test does not depend on boot order. I am not changing criteria 7–8; qa holds them as written. See risks for the conflict.
• PR body: say what this does not fix (see risks). Note that docs/rigs/pupu.md (docs(rig): one runbook and scripts for testing binaries on a rig #441) says ff400.sh "forces phantom off" and describes an ADAT-first alias table. Whichever PR merges second corrects that passage. Do not edit docs(rig): one runbook and scripts for testing binaries on a rig #441's branch from this PR.

[added] what PR #450 has to become (revise the branch, do not start again)

• Keep: clear_ff400_aliases and where it is called; removal of the phantom write and its status line; removal of CHNAME; the labelled phantom readback in show; header text; test cases (a)–(d), (f), (g) and their jack_lsp / jack_alias stubs.
• Comes out:
  • the _ctl_width comment claiming control width "follows the driver's live port count… 18 at 48 kHz, 14 at 96 kHz". It is false (see evidence) and would become the next unverified cite;
  • [[ -n "$width" && "$width" -gt 0 ]] || continue in the routing loop — a silent skip;
  • the if i < n … else all-zero row branch;
  • the literal 18-value string at the 9..26 / 45..62 loop;
  • 2>/dev/null + continue on show's diagonal;
  • the amixer stub's cget arm, which gives only 8 / 63..80 a width tied to AMIXER_WIDTH, and case (e)'s coupling of AMIXER_WIDTH to port count.
• Goes in: the read-and-check-first width helper applied to all four families; test cases (e) revised, (h), (i).
• Not adopted from qa's suggested additions: the amixer stub that rejects a count mismatch. Case (h) replaces it for the reason given there. Qa's point that the stream-source-gain row width is not asserted is covered by (h), which checks every cset.

scope
scope-none. Matches triage.

risks

• Criteria 7–8 require both boot orders, and nobody knows how to force the second. Under A, the result is identical on either order, so that requirement can hold verification open indefinitely without adding a case that can fail. Mitigation: operator/triage decide whether to amend 7–8 to the planted-alias rig check. Until they do, 7–8 stand; this is a verification gate, not an implementation ambiguity.

• [added] The width table is from upstream master, not the ctl-service installed on pupu. Mitigation: the script reads widths rather than trusting the table, and refuses on an unusable one. Rig check for the operator, read-only: amixer -c <FF400 card> cget numid=8, =9, =45, =63 at 96 kHz, recording values=N from each info line. Expected 18 / 8 / 8 / 18 — provenance: derived. A different count means only that the fixture needs updating; the script's behaviour is unaffected. On pupu, run it inside a session that stays open: an SSH logout that closes the last session unlinks jackd's socket.

• [added] Unaliasing a system: port from a foreign client is unverified (see notes). Mitigation: the verify pass exits non-zero and names the port, and rig case (a) exercises it.

• Operators lose port names in JACK GUIs. Mitigation: the not-set line lists where the real order is found, and docs(rig): one runbook and scripts for testing binaries on a rig #441's preflight.sh reports it per session.

• Deleting an alias someone else set with an FF400: prefix. Mitigation: exact prefix match, system: ports only; the PR states that the prefix is treated as this script's namespace.

• Not fixed here, and the rig tester should not expect it:

  1. CARD=0 is an index. On pupu the card is addressed by name because its index can move, so on a boot where card 0 is another device, every amixer write lands on that device.
  2. After a JACK restart the driver skips same-value writes, so the script's level/gain/routing writes may leave the device at driver defaults while readback shows the requested values (pupu, 2026-09-15).
  3. [added] mixer:spdif-source-gain (27..44) is never muted, although the header promises no hardware loopback. S/PDIF input can still loop back to the outputs.

  All three are silent-config defects in this script and belong in separate issues, not this one.