Device model — capability table, per-chip addressing, Gen2 session bring-up

[petrmanek]

The hardware-recognition layer and everything needed to open and address a Gen2 or multi-chip readout.

Tasks

• c: hw_info capability table + probe-on-open
• c: chip-index parameters on per-chip functions (shim pins chip=0)
• c: InterfaceSelect 0x50 auto-issued for Gen2 at open (unacknowledged — no wait)
• c: comm_status chip count replacing chip_detected, mid-run meaning documented (F4); 0x18 measuring flag — lands with Gen2 support
• c: ChangePorts 0xF0 + local-port parameters in device open
• c: UDP discovery (broadcast echo-chip-id, generation detection)

Acceptance

Gen1 open path byte-identical to 1.x; Gen2 open sequence verified against the emulator's Gen2 profile; multi-chip envelope placement covered by golden vectors.

[petrmanek]

Progress note, 2026-09-02. The recognition half of the first task has
landed, ahead of the rest of this issue:

• katherine_device_info_t and katherine_device_info_recognize(), a static
  ten-row table covering the hardware-type codes (0x01-0x03, 0x0A,
  0x20, 0x21, 0x24-0x27) with ASIC, generation, chip count and a
  supported flag — c4da730, covered by test_device_info.c.
• Recognition runs at katherine_device_init(), so device->device_info and
  device->fw_version are populated before any caller asks.

Deliberately not ticked, because the table is narrower than this issue
needs. It answers "what is this readout" but not yet the questions the
remaining tasks dispatch on: px_chunks/px_chunk_size, md_word_size,
md_hdr_map, dac_scan_count, needs_interface_select,
supports_change_ports, acq_time_float_seconds. #27's F3 needs the last of
those, though generation alone would serve as a stand-in.

Also relevant to the last task: KATHERINE_E_ADDR currently conflates a
malformed address string with a failed bind(), which an allocator walking
upward from a base port has to tell apart. Agreed 2026-09-02 to settle that
with the port work here and to land it before 2.0 — see risk item 6 in the
roadmap for the proposal (one new code for an unavailable local endpoint).

[petrmanek]

A device aimed at one of its own addresses reports plausible success, found
while writing the C++ smoke test (#33) and worth deciding here, since this is
where the device model and port selection live.

What happens

katherine_device_init() binds the control socket to 0.0.0.0:1555 and sends
commands to remote port 1555. Aimed at an address some local interface is
assigned, the datagram therefore arrives back at the socket that sent it, and
katherine_cmd_wait_ack_crd() accepts it:

reply_id = (uint8_t) buf[KATHERINE_CMD_OPCODE_BYTE];   /* byte 6 */
if (reply_id == opcode || reply_id == substitute) { ... return KATHERINE_E_OK; }

A request carries its own operation code in byte 6 -- katherine_cmd_transact()
reads it from there to know what to wait for -- and a command is exactly
KATHERINE_CMD_CRD_SIZE bytes, so the length check passes too. A reflected
request correlates with itself by construction, and bytes 0-5 of the request
are then read as the response's payload.

Measured, on Linux, pointing a device at 127.0.0.1:

127.0.0.1: SUCCEEDED (hw_type=0) -- self-echo accepted as ack
127.0.0.2: threw: operation timed out
192.0.2.1: threw: operation timed out

So katherine_get_readout_status() returns KATHERINE_E_OK with a zeroed
status against no readout at all.

Why the existing defences do not apply

• The remote pin cannot help. from_pinned_remote() compares the sender
  against addr_remote, and the reflection genuinely comes from the pinned
  remote: we sent it there, the host looped it back with that source address.
• katherine_udp_set_strict_ack() cannot help either. Strict mode sets
  substitute = opcode, which removes only the firmware's substitute
  identifier; the exact-opcode branch still matches. This is reachable in both
  modes.
• The stray-response budget never engages, because the datagram is accepted
  on the first iteration rather than counted as a stray.

Only 127.0.0.1 self-echoes on Linux, not the rest of 127/8, because delivery
requires the destination to be an address some interface is assigned rather
than merely routed. macOS assigns only 127.0.0.1 by default -- which is why our
own CI aliases 127.0.0.2 for the emulator, and why that address behaves as a
live one there.

Why it belongs to this issue

Nothing here is urgent: the failure needs a device configured to its own
address, which no working setup has. It is filed because the fix, if there is
to be one, is a decision about the device model rather than a patch:

1. Refuse a remote address that is local to this host at
   katherine_device_init(), which is the narrow fix and catches the whole
   class. It needs an enumeration of local addresses, which is per-platform.
2. Distinguish a request from a response on the wire. The cleanest answer
   and probably not available: byte 6 carries the opcode in both directions, so
   correlation alone cannot tell them apart.
3. Do nothing, and document it. Defensible, given how the failure has to be
   provoked.

Option 1 interacts with this issue's port work directly. Once
local_ctl_port/local_data_port and ChangePorts (0xF0) let a caller choose
ports, a device and a local emulator can legitimately share a host, at which
point "is the remote local?" stops being a reliable proxy for "is this
misconfigured" and the check would need to compare the (address, port) pair
against this session's own.

For now c/tests/ avoids the hazard by construction: test_cxx_device.cpp
documents 127.0.0.3 and the assigned-vs-routed rule behind it.