feat(ridesx): add QDL platform flasher for Qualcomm automotive SoCs

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

@@ -79,7 +79,7 @@ Drivers for flashing firmware and programming devices:
 - {doc}`Probe-RS <probe-rs>` (`jumpstarter-driver-probe-rs`) - Debug probe support
 - {doc}`ST-LINK MSD <stlink-msd>` (`jumpstarter-driver-stlink-msd`) - ST-LINK mass storage flasher for STM32
 - {doc}`U-Boot <uboot>` (`jumpstarter-driver-uboot`) - Universal Bootloader interface
-- {doc}`RideSX <ridesx>` (`jumpstarter-driver-ridesx`) - Flashing and power management for Qualcomm RideSX
+- {doc}`RideSX <ridesx>` (`jumpstarter-driver-ridesx`) - RideSX fastboot flashing, QDL platform updates, and power management for Qualcomm automotive SoCs
 
 ### Emulation
 

python/packages/jumpstarter-driver-network/jumpstarter_driver_network/adapters/pexpect.py

@@ -16,4 +16,7 @@ def PexpectAdapter(*, client: DriverClient, method: str = "connect"):
         try:
             yield fdspawn(sock)
         finally:
-            sock.close()
+            try:
+                sock.close()
+            except OSError:
+                pass  # fd already closed by fdspawn

python/packages/jumpstarter-driver-ridesx/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/

python/packages/jumpstarter-driver-ridesx/README.md

@@ -1,8 +1,11 @@
 # RideSX Driver
 
-`jumpstarter-driver-ridesx` provides functionality for Qualcomm RideSX devices,
-supporting fastboot flashing operations and power control through serial communication.
-It includes automatic compression handling (`.gz`, `.gzip`, `.xz`), built-in storage
+`jumpstarter-driver-ridesx` provides functionality for Qualcomm automotive platforms:
+
+- **RideSX** fastboot partition flashing
+- **QDL platform flashing** (`QualcommFlasher`) for full firmware/bootloader updates on SA8775P, SA8650P, and related SoCs
+
+RideSX support includes automatic compression handling (`.gz`, `.gzip`, `.xz`), built-in storage
 for firmware images with upload/download capabilities, and direct access to the
 underlying serial interface for custom commands.
 
@@ -19,6 +22,8 @@ automotive-image-builder build --target ridesx4 --export aboot.simg --mode packa
 $ pip3 install --extra-index-url {{index_url}} jumpstarter-driver-ridesx
 ```
 
+The QDL platform flasher (`QualcommFlasher`) is included in this package. The exporter host must provide `qdl` and `fastboot`.
+
 ## Configuration
 
 The RideSX driver supports two main components:
@@ -154,3 +159,194 @@ power_client.cycle(wait=5)  # Wait 5 seconds between off/on
 .. autoclass:: jumpstarter_driver_ridesx.client.RideSXPowerClient()
     :members: on, off, cycle, rescue, serial
 ```
+
+## QDL platform flashing (`QualcommFlasher`)
+
+Manifest-driven QDL/fastboot flashing for vendor firmware packages (ES13, ES21, ES22, CS4, CS5, …).
+See `examples/exporter-platform.yaml` and reference manifests in
+`jumpstarter_driver_ridesx/qdl/examples/manifests/`.
+
+**driver**: `jumpstarter_driver_ridesx.qdl.driver.QualcommFlasher`
+
+TAC serial handles power on/off and mode switching (EDL/fastboot). Export as `firmware` with
+`tac`, `serial`, and `sail` children for identification.
+
+### Example exporter configuration
+
+```yaml
+apiVersion: jumpstarter.dev/v1alpha1
+kind: ExporterConfig
+metadata:
+  namespace: jumpstarter-lab
+  name: qualcomm-sa8775p
+endpoint:
+token:
+export:
+  firmware:
+    type: "jumpstarter_driver_ridesx.qdl.driver.QualcommFlasher"
+    config:
+      soc_type: sa8775p
+      work_dir: /var/lib/jumpstarter/qualcomm
+      board_revision: v3
+      power_cycle_delay: 2.0
+    children:
+      tac:
+        ref: tac
+      serial:
+        ref: serial
+      sail:
+        ref: sail
+  tac:
+    type: "jumpstarter_driver_pyserial.driver.PySerial"
+    config:
+      url: "/dev/ttyACM0"
+      baudrate: 115200
+  serial:
+    type: "jumpstarter_driver_pyserial.driver.PySerial"
+    config:
+      url: "/dev/ttyUSB1"
+      baudrate: 115200
+  sail:
+    type: "jumpstarter_driver_pyserial.driver.PySerial"
+    config:
+      url: "/dev/ttyUSB2"
+      baudrate: 115200
+```
+
+### Config parameters
+
+| Parameter            | Description                                          | Type  | Required | Default                        |
+| -------------------- | ---------------------------------------------------- | ----- | -------- | ------------------------------ |
+| soc_type             | SoC profile (`sa8775p`, `sa8540p1`, `sa8540p2`)      | str   | no       | sa8775p                        |
+| work_dir             | Base directory for firmware extraction                | str   | no       | /var/lib/jumpstarter/qualcomm  |
+| board_revision       | Board revision for CDT image selection (`v1`–`v4`)   | str   | no       |                                |
+| qdl_timeout          | Timeout for QDL subprocess steps (seconds)           | int   | no       | 1800                           |
+| fastboot_timeout     | Timeout for fastboot subprocess steps (seconds)      | int   | no       | 600                            |
+| power_cycle_delay    | Delay between power off/on (seconds)                 | float | no       | 2.0                            |
+| tac_command_timeout  | Timeout for TAC command acknowledgement (seconds)    | float | no       | 10.0                           |
+
+### Required children
+
+| Child  | Description                            | Required for flash | Required for `id` |
+| ------ | -------------------------------------- | ------------------ | ----------------- |
+| tac    | TAC serial for power and mode control  | Yes                | Yes               |
+| serial | Main boot serial console               | No                 | Yes               |
+| sail   | SAIL boot serial console               | No                 | Yes               |
+
+### CLI
+
+Both the firmware archive and `--manifest` accept local paths or `http://` / `https://` URLs.
+Firmware URLs are downloaded on the exporter. Manifest URLs are fetched by the client.
+
+```bash
+# Flash firmware (manifest auto-discovered from archive)
+j firmware flash https://example.com/firmware/sx4-r00021.1a.tar.xz
+
+# Flash with explicit manifest
+j firmware flash https://example.com/firmware/sx4-r00021.1a.tar.xz --manifest ./es22.yaml
+
+# Cache firmware on the exporter for faster re-flashing
+j firmware flash ./sx4-r00021.1a.tar.xz --cached
+
+# Force re-download when cache is incomplete or corrupted
+j firmware flash ./sx4-r00021.1a.tar.xz --cached --force-download
+
+# Identify running firmware
+j firmware id -v
+
+# Check firmware matches expected variant
+j firmware check ES22 --hypervisor prod --sail-fw-version 1.3.0
+
+# Boot into specific modes
+j firmware boot-to-edl
+j firmware boot-to-fastboot
+```
+
+Use `--cached` to keep extracted firmware on the exporter and reuse it on subsequent
+flashes. Each source URL gets its own cache directory (namespaced by a hash of the URL)
+under `work_dir/`, so different firmware archives never overwrite each other.
+
+If a download is interrupted, the cache may be left in an incomplete state. Use
+`--force-download` with `--cached` to clear the existing cache and re-download.
+
+Archives may embed `jumpstarter_manifest.yaml`. See `examples/exporter-platform.yaml` for
+exporter configuration and the QDL module for manifest schema details.
+
+### Board revision and CDT flash
+
+Fastboot flash operations in the manifest can include a `revision` field to conditionally
+flash based on the board hardware revision. The board revision is set via the
+`board_revision` field in the exporter driver config.
+
+When a flash operation has `revision` set and no board revision is configured, the
+flash command fails with an error.
+
+### Manifest example
+
+ABL and CDT flashing are regular fastboot steps in the manifest, giving full control over
+ordering, retries, and device mode switching:
+
+```yaml
+name: "SA8650P CS4 Firmware"
+data:
+  folder: "r00010.1"
+steps:
+  - set_mode: edl
+    check_dmesg: "qcserial"
+  - sleep: 5
+  - name: "UFS provisioning"
+    retry_mode: edl
+    qdl:
+      storage: ufs
+      programmer: prog_firehose_ddr.elf
+      files:
+        - provision_default.xml
+  - sleep: 10
+  - set_mode: edl
+    check_dmesg: "qcserial"
+  - name: "Flash UFS"
+    retry_mode: edl
+    qdl:
+      storage: ufs
+      programmer: prog_firehose_ddr.elf
+      files:
+        - "rawprogram*.xml"
+        - "patch*.xml"
+  - sleep: 30
+  - set_mode: fastboot
+    check_dmesg: "Product: Android"
+  - name: "Flash ABL"
+    fastboot:
+      flash:
+        - partition: abl_a
+          file: qam8650p_abl_signed.elf
+        - partition: abl_b
+          file: qam8650p_abl_signed.elf
+  - name: "Flash CDT"
+    fastboot:
+      flash:
+        - partition: cdt
+          file: ufs/LEMANSAU_QAM_1.1.0.bin
+          revision: v1
+        - partition: cdt
+          file: ufs/LEMANSAU_QAM_1.1.0.bin
+          revision: v2
+        - partition: cdt
+          file: ufs/LEMANSAU_QAM_1.2.0.bin
+          revision: v3
+        - partition: cdt
+          file: ufs/LEMANSAU_QAM_1.2.0.bin
+          revision: v4
+      continue: true
+```
+
+The `revision` field on flash operations filters by board revision — only the matching
+entry is flashed, the rest are skipped. The `continue: true` on the last fastboot step
+tells the device to boot after flashing.
+
+### Requirements on exporter host
+
+- `qdl` (Qualcomm download tool)
+- `fastboot`
+- USB access to the DUT in EDL/fastboot modes
+- TAC serial device for mode switching

python/packages/jumpstarter-driver-ridesx/examples/exporter-platform.yaml

@@ -0,0 +1,37 @@
+apiVersion: jumpstarter.dev/v1alpha1
+kind: ExporterConfig
+metadata:
+  namespace: jumpstarter-lab
+  name: qualcomm-sa8775p
+endpoint: <endpoint>
+token: <token>
+export:
+  firmware:
+    type: "jumpstarter_driver_ridesx.qdl.driver.QualcommFlasher"
+    config:
+      soc_type: sa8775p
+      work_dir: /var/lib/jumpstarter/qualcomm
+      board_revision: v3
+      power_cycle_delay: 2.0
+    children:
+      tac:
+        ref: tac
+      serial:
+        ref: serial
+      sail:
+        ref: sail
+  tac:
+    type: "jumpstarter_driver_pyserial.driver.PySerial"
+    config:
+      url: "/dev/ttyACM0"
+      baudrate: 115200
+  serial:
+    type: "jumpstarter_driver_pyserial.driver.PySerial"
+    config:
+      url: "/dev/ttyUSB1"
+      baudrate: 115200
+  sail:
+    type: "jumpstarter_driver_pyserial.driver.PySerial"
+    config:
+      url: "/dev/ttyUSB2"
+      baudrate: 115200

python/packages/jumpstarter-driver-ridesx/jumpstarter_driver_ridesx/client.py

@@ -16,8 +16,6 @@
 from jumpstarter.client.decorators import driver_click_group
 from jumpstarter.common.exceptions import JumpstarterException
 
-PROMPT = "CMD >> "
-
 
 class RideSXFlashError(JumpstarterException):
     """User-facing flash operation failure."""

python/packages/jumpstarter-driver-ridesx/jumpstarter_driver_ridesx/driver.py

@@ -8,6 +8,7 @@
 
 from jumpstarter_driver_opendal.driver import Opendal
 
+from .tac import PROMPT, send_power_commands_sequence
 from jumpstarter.common.exceptions import ConfigurationError
 from jumpstarter.common.fls import get_fls_binary
 from jumpstarter.driver import Driver, export
@@ -394,7 +395,7 @@ async def boot_to_fastboot(self):
                     chunk = await stream.receive()
                     data += chunk
                 self.logger.debug(f"Command {command} acknowledged with 'ok'")
-                prompt = b"CMD >> "
+                prompt = PROMPT
                 while prompt not in data:
                     chunk = await stream.receive()
                     data += chunk
@@ -429,7 +430,7 @@ async def on(self):
             ("usbDevicePower 1", 0),
             ("gpio vbusdis1 0", 0.03),
         ]
-        await _send_power_commands_sequence(self.children["serial"], self.logger, commands)
+        await send_power_commands_sequence(self.children["serial"], self.logger, commands)
 
     @export
     async def off(self):
@@ -440,7 +441,7 @@ async def off(self):
             ("usbDevicePower 1", 0),
             ("devicePower 0", 0.5),
         ]
-        await _send_power_commands_sequence(self.children["serial"], self.logger, commands)
+        await send_power_commands_sequence(self.children["serial"], self.logger, commands)
 
     @export
     async def cycle(self, delay: float = 2):
@@ -454,23 +455,3 @@ async def cycle(self, delay: float = 2):
     async def rescue(self):
         """Rescue mode - not implemented for RideSX"""
         raise NotImplementedError("Rescue mode not available for RideSX")
-
-
-async def _send_power_command(serial, logger, command: str):
-    """Send a power command to the device via serial"""
-    async with serial.connect() as stream:
-        logger.info(f"Executing power command: {command}")
-        await stream.send(f"{command}\r".encode())
-        data = b""
-        while b"ok" not in data:
-            chunk = await stream.receive()
-            data += chunk
-        logger.debug(f"Command {command} acknowledged with 'ok'")
-
-
-async def _send_power_commands_sequence(serial, logger, commands):
-    """Send a sequence of power commands with delays"""
-    for command, delay in commands:
-        await _send_power_command(serial, logger, command)
-        if delay > 0:
-            await asyncio.sleep(delay)

python/packages/jumpstarter-driver-ridesx/jumpstarter_driver_ridesx/qdl/__init__.py

@@ -0,0 +1 @@
+"""QDL platform firmware flashing for Qualcomm automotive SoCs."""