path: root/test/hil/hil_flash.py

#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
# Firmware flashing for the TinyUSB HIL rig: one flash_*/reset_* pair per flasher type
# (dispatched by config name via getattr) plus find_firmware. The bounded runner run_cmd
# lives in hil_util (never import hil_test here). Callers set the module global
# `build_dir`. `from __future__ import annotations` keeps the Board hints below
# unevaluated: the type is not defined in this module.

from __future__ import annotations

import json
import re
import subprocess
from pathlib import Path

import os
import sys

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))  # PYTHONSAFEPATH drops it
from helper import hil_util

build_dir = 'cmake-build'

# flasher names (dispatch key, board['flasher']['name'].lower()) whose reset_* is a no-op
RESET_NOOP = {'esptool', 'lm4flash'}

# extra parents find_firmware ALSO searches after build_dir. Empty by default so
# hil_test's -B stays authoritative: a board missing there must report "Skip (no
# binary)", never silently flash a stale binary from another tree.
EXTRA_BUILD_DIRS: list = []

_VID_PID_WARNED: set = set()   # one warning per probe, not per command


# -------------------------------------------------------------
# Flashing firmware
# -------------------------------------------------------------
def flash_jlink(board: Board, firmware: str, timeout=None) -> subprocess.CompletedProcess:
    flasher = board['flasher']
    script = ['halt', 'r', f'loadfile {firmware}', 'r', 'go', 'exit']
    f_jlink = Path(f'{board["name"]}_{Path(firmware).name}.jlink')
    with f_jlink.open('w') as f:
        f.writelines(f'{s}\n' for s in script)
    ret = hil_util.run_cmd(f'JLinkExe -USB {flasher["uid"]} {flasher["args"]} -if swd -JTAGConf -1,-1 -speed auto -NoGui 1 -ExitOnError 1 -CommandFile {f_jlink}',
                           timeout=timeout)
    f_jlink.unlink(missing_ok=True)
    return ret


def reset_jlink(board: Board) -> subprocess.CompletedProcess:
    flasher = board['flasher']
    script = ['halt', 'r', 'go', 'exit']
    f_jlink = Path(f'{board["name"]}_reset.jlink')
    if not f_jlink.exists():
        with f_jlink.open('w') as f:
            f.writelines(f'{s}\n' for s in script)
    ret = hil_util.run_cmd(f'JLinkExe -USB {flasher["uid"]} {flasher["args"]} -if swd -JTAGConf -1,-1 -speed auto -NoGui 1 -ExitOnError 1 -CommandFile {f_jlink}')
    return ret


def flash_stlink(board, firmware, timeout=None):
    # --verify catches the partial/corrupt write that exits 0 and sends the test phase
    # off to exercise bad firmware. Opt-IN here ("verify": true), unlike flash_openocd's
    # opt-out: a default-on read-back silently changes every roster entry that lacks the
    # key, including boards on rigs this was never validated against.
    flasher = board['flasher']
    verify = ' --verify' if flasher.get('verify', False) else ''
    return hil_util.run_cmd(f'STM32_Programmer_CLI --connect port=swd sn={flasher["uid"]} --write {firmware}{verify} --go',
                            timeout=timeout)


def reset_stlink(board):
    flasher = board['flasher']
    return hil_util.run_cmd(f'STM32_Programmer_CLI --connect port=swd sn={flasher["uid"]} --rst --go')


def _openocd_cmd_base(flasher):
    # Optional roster field vid_pid, openocd-verbatim (e.g. "0x1a86 0x8010"), pins probe
    # discovery to the probe's IDs so openocd never opens foreign usbfs nodes to read
    # strings -- a wedged node makes that open hang unkillably (the 2026-08-10 convoy).
    # BEFORE args, because the rescue cfgs run `init` internally and reject (or never see)
    # a config command that follows it.
    vid_pid = ''
    if 'vid_pid' in flasher:
        # Validated HERE too, not just in convoy_safe: openocd only warns ("incomplete
        # vid_pid configuration directive") and exits 0 on a malformed value, so the pin
        # silently does not apply and discovery goes back to opening every usbfs node --
        # the convoy this field exists to stop. The same key name carries a DIFFERENT
        # syntax under tests.dev_attached ('1a86_55d4'), so the typo is one copy away.
        if valid_vid_pid(flasher['vid_pid']):
            vid_pid = f'-c "adapter usb vid_pid {flasher["vid_pid"]}" '
        else:
            # stderr + once-per-probe, like the missing-pin branch below: stdout here is
            # captured by test_example's redirect_stdout (shown only when the test FAILS)
            # and by hil_pool_check's StringIO spool, so on a PASSING run the operator
            # would never learn the pin was silently dropped.
            uid = flasher.get('uid', '?')
            if uid not in _VID_PID_WARNED:
                _VID_PID_WARNED.add(uid)
                print(f'warning: {uid} has a malformed vid_pid {flasher["vid_pid"]!r} '
                      f'(want "0xVVVV 0xPPPP"); probe pin DROPPED, so discovery will open '
                      f'foreign usbfs nodes', file=sys.stderr, flush=True)
    elif flasher.get('uid') not in _VID_PID_WARNED:
        # stderr, once per probe: test_example captures stdout, so a passing run would
        # swallow this and the operator would never learn discovery still opens every
        # usbfs node
        _VID_PID_WARNED.add(flasher.get('uid'))
        print(f'warning: openocd flasher {flasher.get("uid", "?")} has no vid_pid pin; '
              f'probe discovery will open every usbfs node (hangs on a wedged one)',
              file=sys.stderr, flush=True)
    return (f'openocd -c "tcl_port disabled" -c "gdb_port disabled" -c "telnet_port disabled" '
            f'-c "adapter serial {flasher["uid"]}" {vid_pid}{flasher["args"]}')


# `verify` is on by default, opted out per board with "verify": false. WCH targets must
# opt out: read-back over the WCH-Link sdi transport returns a repeated word instead of
# memory contents, so verification always mismatches (measured on ch32v103r and ch32v307v,
# 2026-07-30). Do NOT drop verify fleet-wide for them — every other openocd board reads
# back, and without it a partial or corrupt write exits 0 and the tests run bad firmware.
def flash_openocd(board, firmware, timeout=None):
    flasher = board['flasher']
    verify = ' verify' if flasher.get('verify', True) else ''
    ret = hil_util.run_cmd(f'{_openocd_cmd_base(flasher)} -c "program {firmware}{verify} reset exit"',
                           timeout=timeout)
    return ret


def reset_openocd(board, timeout=None):
    # timeout: usbtest's post-hang recovery bounds this (RECOVER_RESET_TIMEOUT); an
    # unbounded reset there would outlive the caller's outer kill and orphan openocd on
    # the probe, which is the stray the recovery exists to avoid.
    flasher = board['flasher']
    ret = hil_util.run_cmd(f'{_openocd_cmd_base(flasher)} -c "init; reset run; exit"',
                           timeout=timeout)
    return ret


# OpenOCD's messages for "the target's debug port did not answer". The probe is fine when
# these appear ("CMSIS-DAP: Interface ready" is still logged); the chip's debug clock is
# gone, which no probe-driven reset fixes -- the CMSIS-DAP probe has no nRESET line. Which
# message appears depends on DAP topology, not the board, so both are accepted for both
# chips; RESCUE_CFG below picks the rescue.
DAP_WEDGED = ('Failed to connect multidrop', 'Error connecting DP: cannot read IDR')

# How each RP target reaches its Rescue DP, keyed by the target cfg named in flasher args:
# (cfg substitution, pre args, post args). rp2040.cfg drives the Rescue DP behind a RESCUE
# flag and init/shutdowns itself; rp2350-rescue.cfg never shuts down, so it needs an
# explicit one or it sits in the server loop until CMD_TIMEOUT.
RESCUE_CFG = {
    'target/rp2040.cfg': ('target/rp2040.cfg', '-c "set RESCUE 1" ', ''),
    'target/rp2350.cfg': ('target/rp2350-rescue.cfg', '', ' -c "shutdown"'),
}


def rescue_openocd(board, flash_out: str = '', timeout=None) -> bool:
    """Power-on-reset a wedged RP2040/RP2350 through its Rescue DP, the one debug port not
    gated by the system clock (RP2040 datasheet 2.3.4.2): CDBGPWRUPREQ hard-resets the
    chip and the bootrom halts it ready to be flashed. Without it the board needs a
    physical replug -- the probe carries no reset line.

    No-op (False) unless this is an openocd RP board AND the flash output shows the wedge,
    so a flash that failed for any other reason still just retries. True when a rescue was
    attempted; the caller should retry the flash afterwards."""
    flasher = board['flasher']
    if flasher['name'].lower() != 'openocd' or not any(m in flash_out for m in DAP_WEDGED):
        return False
    for cfg, (rescue_cfg, pre, post) in RESCUE_CFG.items():
        if cfg in flasher['args']:
            args = flasher['args'].replace(cfg, rescue_cfg)
            return hil_util.run_cmd(f'{_openocd_cmd_base({**flasher, "args": pre + args})}{post}',
                                    timeout=timeout).returncode == 0
    return False


# openocd's own syntax: one or more "0xVVVV 0xPPPP" pairs. Validated rather than merely
# tested for truthiness -- `vid_pid` is a hand-edited roster field whose NAME is also used,
# with a different syntax, by tests.dev_attached, and convoy_safe reads a non-empty value
# as PROOF the flasher can deliver a recovery past a poisoned node. A typo there silently
# promised a recovery that openocd would reject at startup.
_VID_PID_RE = re.compile(r'^0x[0-9a-fA-F]{4}(\s+0x[0-9a-fA-F]{4})+$')


def valid_vid_pid(value) -> bool:
    return isinstance(value, str) and bool(_VID_PID_RE.match(value.strip()))


def recover_flasher(board: dict) -> dict:
    """The flasher that delivers RECOVERY for this board.

    Optional roster key `flasher_recover`, else the primary. It exists because delivery and
    normal flashing have different requirements: a board flashed by jlink/stlink/lm4flash
    cannot reach its probe past a poisoned usbfs node, but the same probe driven by openocd
    often can (see convoy_safe). Keeping it a separate key rather than a list means the
    primary's shape never changes, so nothing that reads board['flasher'] has to care.
    """
    return board.get('flasher_recover') or board['flasher']


def convoy_safe(flasher: dict) -> bool:
    """Can this flasher DELIVER a recovery while a usbfs node on the rig is poisoned?

    A post-HUNG reflash only helps if the flasher reaches its probe without opening the
    wedged node. Two shapes qualify:

    * openocd pinned with the roster's `vid_pid` -- the match is made from the cached
      descriptor and the loop `continue`s BEFORE libusb_open, so a foreign node is never
      opened. On 2026-08-12 it was the only flasher that still reached its probe.
    * esptool -- delivery is `-p <ttyACM>`, a named port; it never enumerates usbfs.

    Everything else enumerates by OPENING nodes, would block in D state on the poisoned
    one, survive SIGKILL and become a second stray. JLinkExe cannot be pinned: selection
    is serial-only (-USB/-SelectEmuBySN) and reading a serial requires the open (J-Link
    Commander V9.66 exposes no VID/PID filter), so those boards can only become
    convoy-safe by moving to openocd.

    Verified against openocd 0ce743125 (the rig's build), because the INVERSE is what
    bites: cmsis_dap_usb_bulk.c:107 skips on `id_filter && !id_match`, and `id_filter` is
    only `vids[0] || pids[0]` -- so without the pin nothing is skipped and every device on
    the bus is opened, which the code itself expects to mostly fail. Enumeration cannot
    block: libusb reads the `descriptors` sysfs attribute, and descriptors_read (v6.12.101
    drivers/usb/core/sysfs.c) is a memcpy from udev->rawdescriptors under no lock.

    The pin gates the BULK backend, which is the one that runs: `auto` tries usb_bulk ->
    hid -> tcp (cmsis_dap.c:62) and stops at the first that opens, so a CMSIS-DAP v2 probe
    never reaches the rest. It does NOT cover the HID fallback that a v1 probe or a failed
    bulk open takes -- cmsis_dap_usb_hid.c:91 calls hid_enumerate(0x0, 0x0), pin ignored,
    and filters afterwards, while hidapi's hidraw backend reads `manufacturer` and
    `product` for every HID device it lists (linux/hid.c:744), both usb_string_attr and so
    served under the device lock. A wedged DUT running hid_generic_inout,
    hid_boot_interface or hid_composite_freertos is a HID device and would stall that walk
    -- interruptibly, so it hangs rather than joining the D-state convoy and run_cmd's
    timeout ends it, but "never opens a foreign node" is true of the bulk path, not of
    every path openocd can take.
    """
    name = (flasher.get('name') or '').lower()
    if name == 'esptool':
        return True
    # EXACT, not startswith: rescue_openocd and usbtest's
    # getattr(hil_flash, f'flash_{name}') both require the exact name, so an
    # 'openocd_wch'-style entry would pass this gate, reserve USBTEST_RECOVERY_BUDGET,
    # and then find no recovery path at all -- paying for a path that cannot fire, which
    # is the precise cost this gate exists to avoid.
    if name != 'openocd':
        return False
    if valid_vid_pid(flasher.get('vid_pid')):
        return True
    # openocd over the JLINK driver is safe WITHOUT a pin, and cannot use one: jlink.c
    # never reads adapter_usb_get_vids/pids (selection is adapter serial / usb address /
    # usb location), but libjaylink's discovery returns early unless idVendor == 0x1366 and
    # the PID is in its table, and only THEN calls libusb_open (discovery_usb.c). So it
    # never opens a foreign node -- which is exactly what JLinkExe, SEGGER's own tool,
    # does do. Verified against openocd 0ce743125 and libjaylink master.
    return 'interface/jlink.cfg' in (flasher.get('args') or '')


def flash_esptool(board: Board, firmware: str, timeout=None) -> subprocess.CompletedProcess:
    flasher = board['flasher']
    port = hil_util.get_serial_dev(flasher["uid"], None, None, 0)
    fw_dir = Path(firmware).parent
    with (fw_dir / 'config.env').open() as f:
        idf_target = json.load(f)['IDF_TARGET']
    with (fw_dir / 'flash_args').open() as f:
        flash_args = f.read().strip().replace('\n', ' ')
    command = (f'esptool --chip {idf_target} -p {port} {flasher["args"]} '
               f'--before=default_reset --after=hard_reset write_flash {flash_args}')
    ret = hil_util.run_cmd(command, cwd=str(fw_dir), timeout=timeout)
    return ret


def reset_esptool(board):
    # NO-OP, and marked as one: esptool's reset would be `--after hard_reset`, which is not
    # wired here. Returning rc 0 without resetting is why callers must never read the exit
    # code as proof -- recovery_steps skips a primitive carrying `no_op`.
    return subprocess.CompletedProcess(args=['dummy'], returncode=0)


reset_esptool.no_op = True


def flash_lm4flash(board, firmware, timeout=None):
    # TI Tiva-C / Stellaris ICDI: lightweight lm4flash, resets and runs after write
    flasher = board['flasher']
    ret = hil_util.run_cmd(f'lm4flash -s {flasher["uid"]} {flasher["args"]} {firmware}',
                           timeout=timeout)
    return ret


def reset_lm4flash(board):
    # lm4flash has no reset-only mode; it resets+runs on flash, so reset is a no-op
    return subprocess.CompletedProcess(args=['dummy'], returncode=0)


reset_lm4flash.no_op = True


# The one place a flasher's firmware extension is decided. A flasher with no entry falls
# back to .elf-or-.bin and can be handed the wrong file — test_ci_select's
# TestRosterFlashersDispatch fails if a roster names one.
FLASHER_SUFFIX = {
    'esptool': '.bin',
    'jlink': '.elf',
    'lm4flash': '.bin',
    'openocd': '.elf',
    'stlink': '.elf',
}


def find_firmware(variant: str, example: str, roots: list | None = None, flasher: str | None = None):
    """Locate a built example's firmware under <build_dir>/cmake-build-<variant>/<example>/,
    then under EXTRA_BUILD_DIRS. `roots` overrides that search list entirely for one call
    (e.g. a build just produced by tools/build.py in its fixed cmake-build/ layout)
    without widening the global policy. `flasher` is the roster flasher name and selects
    which extension counts (FLASHER_SUFFIX), so a build that produced only the other one
    is reported missing — a clean "Skip (no binary)" — instead of being handed to the
    flasher, which would fail opaquely and burn every retry plus the board lock.
    Accepts the single-config layout (firmware directly in the example dir) or Ninja
    Multi-Config (a per-config subdir like RelWithDebInfo/).
    Returns the full Path INCLUDING extension, or None if not built."""
    base = Path(example).name
    suffixes = [FLASHER_SUFFIX.get(flasher.lower())] if flasher else []
    if not suffixes or suffixes == [None]:
        suffixes = ['.elf', '.bin']
    for bd in dict.fromkeys(roots if roots is not None else [build_dir, *EXTRA_BUILD_DIRS]):
        fw_dir = hil_util.TINYUSB_ROOT / bd / f'cmake-build-{variant}' / example
        if not fw_dir.is_dir():
            continue
        for cand in [fw_dir / base, fw_dir / 'RelWithDebInfo' / base,
                     *(p.with_suffix('') for s in suffixes for p in sorted(fw_dir.glob(f'*/{base}{s}')))]:
            for s in suffixes:
                if cand.with_suffix(s).exists():
                    return cand.with_suffix(s)
    return None