fix: address PR review feedback

- Remove ELF-to-BIN conversion per maintainer feedback; reject .elf
  files with a clear error message pointing to objcopy
- Remove objcopy_path config option (no longer needed)
- Fix info() docstring to match implementation (only parses DETAILS.TXT)
- Use os.open/os.fsync/os.close for proper fd-based sync
- Remove dump() from README (unsupported API)
- Add stlink-msd to docs toctree (fixes check-warnings CI)

Made-with: Cursor

Author: vtz

python/docs/source/reference/package-apis/drivers/index.md

@@ -95,6 +95,8 @@ Drivers for debugging and programming devices:
   UF2 flashing via BOOTSEL mass storage
 * **[Probe-RS](probe-rs.md)** (`jumpstarter-driver-probe-rs`) - Debugging probe
   support
+* **[ST-LINK MSD](stlink-msd.md)** (`jumpstarter-driver-stlink-msd`) - ST-LINK
+  mass storage flasher for STM32 Nucleo and Discovery boards
 * **[Android Emulator](androidemulator.md)** (`jumpstarter-driver-androidemulator`) -
   Android emulator lifecycle management with ADB tunneling
 * **[QEMU](qemu.md)** (`jumpstarter-driver-qemu`) - QEMU virtualization platform
@@ -145,6 +147,7 @@ shell.md
 ssh.md
 snmp.md
 someip.md
+stlink-msd.md
 tasmota.md
 tmt.md
 tftp.md

python/packages/jumpstarter-driver-stlink-msd/README.md

@@ -11,24 +11,21 @@ built-in mass storage interface handles all the flash programming.
 
 | Format | Handling |
 |--------|----------|
-| `.elf` | Auto-converted to `.bin` via `objcopy`, then copied to the volume |
 | `.bin` | Copied directly to the ST-LINK volume |
 | `.hex` | Copied directly to the ST-LINK volume |
 
-Using `.elf` allows the same build artifact for both virtual (Renode) and physical targets.
+ELF files must be converted externally before flashing:
+
+```shell
+arm-none-eabi-objcopy -O binary zephyr.elf zephyr.bin
+```
 
 ## Installation
 
 ```shell
 pip3 install --extra-index-url https://pkg.jumpstarter.dev/simple/ jumpstarter-driver-stlink-msd
 ```
 
-For `.elf` support, ensure one of these is on your `PATH`:
-
-- `arm-none-eabi-objcopy` (ARM GCC toolchain)
-- `llvm-objcopy` (LLVM/Clang)
-- `arm-zephyr-eabi-objcopy` (Zephyr SDK)
-
 ## Configuration
 
 ```yaml
@@ -37,25 +34,21 @@ export:
     type: jumpstarter_driver_stlink_msd.driver.StlinkMsdFlasher
     config:
       # volume_name: "NOD_H755ZI"   # optional: auto-detected if only one ST-LINK is connected
-      # objcopy_path: "/path/to/objcopy"  # optional: auto-detected from PATH
 ```
 
 | Parameter     | Description                                                      | Type           | Required | Default      |
 |---------------|------------------------------------------------------------------|----------------|----------|--------------|
 | volume_name   | Name of the mounted ST-LINK volume (e.g. `NOD_H755ZI`)          | str \| None    | no       | auto-detect  |
-| objcopy_path  | Path to objcopy binary for ELF-to-BIN conversion                 | str \| None    | no       | auto-detect  |
 
 ## Shell Commands
 
 ```shell
-j flasher flash firmware.elf       # flash an ELF (auto-converts to .bin)
 j flasher flash firmware.bin       # flash a raw binary
+j flasher flash firmware.hex       # flash an Intel HEX file
 j flasher info                     # show ST-LINK volume details
 ```
 
 ## API
 
-- **`flash(source, target=None)`** — Flash firmware to the board. Accepts `.elf`, `.bin`, or `.hex`.
-  ELF files are automatically converted to `.bin` using `objcopy`.
+- **`flash(source, target=None)`** — Flash firmware to the board. Accepts `.bin` or `.hex` files.
 - **`info()`** — Read `DETAILS.TXT` from the ST-LINK volume and return board metadata.
-- **`dump()`** — Not supported (ST-LINK mass storage is write-only).

python/packages/jumpstarter-driver-stlink-msd/jumpstarter_driver_stlink_msd/client.py

@@ -12,18 +12,13 @@ class StlinkMsdFlasherClient(FlasherClient):
     """Client interface for ST-LINK mass storage flasher.
 
     Flashes STM32 boards by copying firmware to the ST-LINK's USB
-    mass storage volume. Supports .elf, .bin, and .hex files.
+    mass storage volume. Supports .bin and .hex files.
     """
 
     def info(self) -> dict[str, str]:
         """Read board info from the ST-LINK volume."""
         return self.call("info")
 
-    def flash_file(self, filepath) -> str:
-        """Flash a local file to the STM32 board."""
-        absolute = Path(filepath).resolve()
-        return self.flash(absolute)
-
     def cli(self):
         base = super().cli()
         base.commands.pop("flash", None)
@@ -42,7 +37,7 @@ def info():
         @click.argument("file", type=click.Path(exists=True))
         @click.option("--compression", type=click.Choice(Compression, case_sensitive=False))
         def flash(file, compression):
-            """Flash firmware (.elf, .bin, or .hex) to the STM32 board."""
+            """Flash firmware (.bin or .hex) to the STM32 board."""
             name = Path(file).name
             click.echo(f"Flashing {name}...")
             self.flash(file, target=name, compression=compression)

python/packages/jumpstarter-driver-stlink-msd/jumpstarter_driver_stlink_msd/driver.py

@@ -4,7 +4,6 @@
 
 import os
 import shutil
-import subprocess
 import tempfile
 from dataclasses import dataclass
 
@@ -15,61 +14,29 @@
 from .stlink_mount import find_all_stlink_mounts, find_stlink_mount
 from jumpstarter.driver import Driver, export
 
+_SUPPORTED_EXTENSIONS = frozenset({".bin", ".hex"})
 
-def _find_objcopy() -> str | None:
-    """Find an objcopy binary that can handle ARM ELF files."""
-    for name in (
-        "arm-none-eabi-objcopy",
-        "llvm-objcopy",
-        "arm-zephyr-eabi-objcopy",
-        "objcopy",
-    ):
-        path = shutil.which(name)
-        if path:
-            return path
-    return None
-
-
-def _elf_to_bin(elf_path: str, bin_path: str, objcopy_path: str | None = None) -> None:
-    """Convert an ELF file to raw binary using objcopy."""
-    objcopy = objcopy_path or _find_objcopy()
-    if objcopy is None:
-        raise FileNotFoundError(
-            "No objcopy found. Install arm-none-eabi-gcc, llvm, or the Zephyr SDK."
-        )
-
-    result = subprocess.run(
-        [objcopy, "-O", "binary", elf_path, bin_path],
-        capture_output=True,
-        text=True,
-    )
-    if result.returncode != 0:
-        raise RuntimeError(f"objcopy failed: {result.stderr.strip()}")
 
-
-def _detect_format(filename: str) -> str:
-    """Detect firmware format from filename extension."""
-    lower = filename.lower()
-    if lower.endswith(".elf"):
-        return "elf"
-    if lower.endswith(".bin"):
-        return "bin"
-    if lower.endswith(".hex"):
-        return "hex"
-    return "unknown"
+def _validate_firmware_name(name: str) -> None:
+    """Raise if the firmware file extension is not supported by ST-LINK MSD."""
+    _, ext = os.path.splitext(name.lower())
+    if ext not in _SUPPORTED_EXTENSIONS:
+        raise ValueError(
+            f"Unsupported firmware format '{ext or name}'. "
+            f"ST-LINK mass storage only accepts .bin or .hex files. "
+            f"Convert ELF files with: arm-none-eabi-objcopy -O binary input.elf output.bin"
+        )
 
 
 @dataclass(kw_only=True)
 class StlinkMsdFlasher(FlasherInterface, Driver):
     """Flash STM32 boards by copying firmware to the ST-LINK USB mass storage volume.
 
-    Supports .elf files (converted to .bin via objcopy), .bin files (copied directly),
-    and .hex files (copied directly). This allows using the same .elf build artifact
-    for both virtual targets (Renode) and physical targets (Nucleo/Discovery boards).
+    Supports .bin and .hex files. ELF files must be converted to .bin
+    externally (e.g. via ``arm-none-eabi-objcopy -O binary``).
     """
 
     volume_name: str | None = None
-    objcopy_path: str | None = None
 
     def __post_init__(self):
         if hasattr(super(), "__post_init__"):
@@ -101,7 +68,7 @@ def _resolve_mount(self) -> str:
 
     @export
     def info(self) -> dict[str, str]:
-        """Read DETAILS.TXT and MBED.HTM from the ST-LINK volume."""
+        """Read DETAILS.TXT from the ST-LINK volume and return board metadata."""
         mount = self._resolve_mount()
         result: dict[str, str] = {}
 
@@ -120,44 +87,34 @@ def info(self) -> dict[str, str]:
     async def flash(self, source, target: str | None = None):
         """Flash firmware to the STM32 board via ST-LINK mass storage.
 
-        Accepts .elf (auto-converted to .bin), .bin, or .hex files.
-        The ``target`` parameter is the destination filename on the volume
-        (default: ``firmware.bin``).
+        Accepts .bin or .hex files only. ELF files are rejected — convert
+        them externally before flashing.
+
+        :param source: Firmware resource (local path or storage handle).
+        :param target: Destination filename on the volume (default: ``firmware.bin``).
         """
         mount = self._resolve_mount()
-        src_name = target or "firmware.bin"
+        dest_name = target or "firmware.bin"
+        _validate_firmware_name(dest_name)
 
         with tempfile.TemporaryDirectory() as tmpdir:
-            tmp_path = os.path.join(tmpdir, "input_firmware")
+            tmp_path = os.path.join(tmpdir, dest_name)
 
             async with await FileWriteStream.from_path(tmp_path) as stream:
                 async with self.resource(source) as res:
                     async for chunk in res:
                         await stream.send(chunk)
 
-            fmt = _detect_format(src_name)
-            if fmt == "unknown":
-                fmt = _detect_format(tmp_path)
-
-            if fmt == "elf":
-                bin_path = os.path.join(tmpdir, "firmware.bin")
-                self.logger.info("Converting ELF to BIN using objcopy")
-                await to_thread.run_sync(
-                    lambda: _elf_to_bin(tmp_path, bin_path, self.objcopy_path)
-                )
-                flash_src = bin_path
-                dest_name = src_name.rsplit(".", 1)[0] + ".bin" if src_name.lower().endswith(".elf") else src_name
-            else:
-                flash_src = tmp_path
-                dest_name = src_name
-
             dest_path = os.path.join(mount, dest_name)
             self.logger.info("Copying firmware to %s", dest_path)
 
             def _copy() -> None:
-                shutil.copy2(flash_src, dest_path)
-                with open(dest_path, "rb") as f:
-                    os.fsync(f.fileno())
+                shutil.copy2(tmp_path, dest_path)
+                fd = os.open(dest_path, os.O_RDONLY)
+                try:
+                    os.fsync(fd)
+                finally:
+                    os.close(fd)
 
             await to_thread.run_sync(_copy)
 

python/packages/jumpstarter-driver-stlink-msd/jumpstarter_driver_stlink_msd/driver_test.py

@@ -1,7 +1,6 @@
-from unittest.mock import patch
-
 import pytest
 
+from .driver import _validate_firmware_name
 from .stlink_mount import looks_like_stlink_volume
 
 
@@ -37,34 +36,23 @@ def test_looks_like_stlink_volume_not_dir(tmp_path):
     assert looks_like_stlink_volume(f) is False
 
 
-def test_detect_format():
-    from .driver import _detect_format
-
-    assert _detect_format("firmware.elf") == "elf"
-    assert _detect_format("firmware.bin") == "bin"
-    assert _detect_format("firmware.hex") == "hex"
-    assert _detect_format("firmware.unknown") == "unknown"
-    assert _detect_format("FIRMWARE.ELF") == "elf"
+def test_validate_firmware_name_bin():
+    _validate_firmware_name("firmware.bin")
 
 
-def test_elf_to_bin_missing_objcopy():
-    from .driver import _elf_to_bin
+def test_validate_firmware_name_hex():
+    _validate_firmware_name("firmware.hex")
 
-    with pytest.raises(FileNotFoundError, match="No objcopy found"):
-        with patch("jumpstarter_driver_stlink_msd.driver._find_objcopy", return_value=None):
-            _elf_to_bin("/fake/input.elf", "/fake/output.bin")
 
+def test_validate_firmware_name_bin_uppercase():
+    _validate_firmware_name("FIRMWARE.BIN")
 
-def test_elf_to_bin_success(tmp_path):
-    from .driver import _elf_to_bin
 
-    elf_file = tmp_path / "test.elf"
-    bin_file = tmp_path / "test.bin"
-    elf_file.write_bytes(b"\x7fELF" + b"\x00" * 100)
+def test_validate_firmware_name_elf_rejected():
+    with pytest.raises(ValueError, match="Unsupported firmware format"):
+        _validate_firmware_name("firmware.elf")
 
-    fake_objcopy = tmp_path / "fake_objcopy.sh"
-    fake_objcopy.write_text('#!/bin/sh\ncp "$3" "$4"\n')
-    fake_objcopy.chmod(0o755)
 
-    _elf_to_bin(str(elf_file), str(bin_file), objcopy_path=str(fake_objcopy))
-    assert bin_file.exists()
+def test_validate_firmware_name_unknown_rejected():
+    with pytest.raises(ValueError, match="Unsupported firmware format"):
+        _validate_firmware_name("firmware.xyz")