openocd-python 2026.2.12__py3-none-any.whl

openocd/svd/parser.py

@@ -0,0 +1,128 @@
+"""SVD file loading and peripheral/register lookup.
+
+Wraps cmsis_svd to parse CMSIS-SVD XML files and provide indexed access
+to peripherals and their registers.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+from cmsis_svd import SVDParser
+
+from openocd.errors import SVDError
+
+log = logging.getLogger(__name__)
+
+
+class SVDParserWrapper:
+    """Load and cache parsed SVD device data."""
+
+    def __init__(self) -> None:
+        self._device: Any = None
+        self._peripherals: dict[str, Any] = {}
+
+    @property
+    def loaded(self) -> bool:
+        """Whether an SVD file has been parsed."""
+        return self._device is not None
+
+    def load(self, svd_path: Path) -> None:
+        """Parse an SVD file and index peripherals/registers.
+
+        Args:
+            svd_path: Path to the .svd file on disk.
+
+        Raises:
+            SVDError: If the file cannot be found or parsed.
+        """
+        path = Path(svd_path)
+        if not path.exists():
+            raise SVDError(f"SVD file not found: {path}")
+
+        try:
+            parser = SVDParser.for_xml_file(str(path))
+            self._device = parser.get_device()
+        except Exception as exc:
+            raise SVDError(f"Failed to parse SVD file {path}: {exc}") from exc
+
+        self._peripherals = {p.name: p for p in self._device.get_peripherals()}
+        log.info(
+            "Loaded SVD for %s — %d peripherals",
+            getattr(self._device, "name", "unknown"),
+            len(self._peripherals),
+        )
+
+    def _require_loaded(self) -> None:
+        if not self.loaded:
+            raise SVDError("No SVD file loaded — call load() first")
+
+    def get_peripheral(self, name: str) -> Any:
+        """Look up a peripheral by name.
+
+        Args:
+            name: Peripheral name (case-sensitive, e.g. "GPIOA", "USART1").
+
+        Returns:
+            The cmsis_svd peripheral object.
+
+        Raises:
+            SVDError: If no SVD is loaded or the peripheral is not found.
+        """
+        self._require_loaded()
+        periph = self._peripherals.get(name)
+        if periph is None:
+            raise SVDError(
+                f"Peripheral '{name}' not found. "
+                f"Available: {', '.join(sorted(self._peripherals))}"
+            )
+        return periph
+
+    def get_register(self, peripheral: str, register: str) -> Any:
+        """Look up a register within a peripheral.
+
+        Args:
+            peripheral: Peripheral name.
+            register: Register name (e.g. "CR1", "SR").
+
+        Returns:
+            The cmsis_svd register object.
+
+        Raises:
+            SVDError: If the peripheral or register is not found.
+        """
+        periph = self.get_peripheral(peripheral)
+        registers = periph.registers or []
+        for reg in registers:
+            if reg.name == register:
+                return reg
+
+        available = [r.name for r in registers]
+        raise SVDError(
+            f"Register '{register}' not found in {peripheral}. "
+            f"Available: {', '.join(sorted(available))}"
+        )
+
+    def list_peripherals(self) -> list[str]:
+        """Return sorted names of all peripherals in the SVD.
+
+        Raises:
+            SVDError: If no SVD is loaded.
+        """
+        self._require_loaded()
+        return sorted(self._peripherals.keys())
+
+    def list_registers(self, peripheral: str) -> list[str]:
+        """Return sorted register names for a peripheral.
+
+        Args:
+            peripheral: Peripheral name.
+
+        Raises:
+            SVDError: If the peripheral is not found.
+        """
+        periph = self.get_peripheral(peripheral)
+        registers = periph.registers or []
+        return sorted(r.name for r in registers)

openocd/svd/peripheral.py

@@ -0,0 +1,186 @@
+"""SVDManager — combines SVD parsing, register decoding, and hardware reads.
+
+This is the primary interface for SVD-based register inspection. It ties
+the SVD parser, bitfield decoder, and the Memory subsystem together so
+callers can do things like:
+
+    decoded = await svd.read_register("GPIOA", "ODR")
+    print(decoded)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from openocd.svd.decoder import decode_register
+from openocd.svd.parser import SVDParserWrapper
+from openocd.types import DecodedRegister
+
+if TYPE_CHECKING:
+    from openocd.connection.base import Connection
+    from openocd.memory import Memory
+
+log = logging.getLogger(__name__)
+
+
+class SVDManager:
+    """High-level SVD register access: parse, read, decode."""
+
+    def __init__(self, conn: Connection, memory: Memory) -> None:
+        self._conn = conn
+        self._memory = memory
+        self._parser = SVDParserWrapper()
+
+    @property
+    def loaded(self) -> bool:
+        """Whether an SVD file has been loaded."""
+        return self._parser.loaded
+
+    async def load(self, svd_path: Path) -> None:
+        """Parse an SVD file and make its peripherals available.
+
+        This is a synchronous file parse wrapped in the async interface
+        for consistency with the rest of the API.
+
+        Args:
+            svd_path: Path to the .svd XML file.
+
+        Raises:
+            SVDError: If the file is missing or unparseable.
+        """
+        await asyncio.to_thread(self._parser.load, svd_path)
+
+    def list_peripherals(self) -> list[str]:
+        """Return sorted peripheral names from the loaded SVD.
+
+        Raises:
+            SVDError: If no SVD is loaded.
+        """
+        return self._parser.list_peripherals()
+
+    def list_registers(self, peripheral: str) -> list[str]:
+        """Return sorted register names for a peripheral.
+
+        Args:
+            peripheral: Peripheral name (e.g. "GPIOA").
+
+        Raises:
+            SVDError: If no SVD is loaded or peripheral not found.
+        """
+        return self._parser.list_registers(peripheral)
+
+    async def read_register(self, peripheral: str, register: str) -> DecodedRegister:
+        """Read a register from hardware and decode it using SVD metadata.
+
+        This is the primary method: it computes the register's memory-mapped
+        address from the SVD, reads 32 bits from the target, and returns
+        a fully decoded result with named bitfields.
+
+        Args:
+            peripheral: Peripheral name (e.g. "GPIOA").
+            register: Register name (e.g. "ODR").
+
+        Returns:
+            DecodedRegister with address, raw value, and decoded fields.
+
+        Raises:
+            SVDError: If peripheral/register not found.
+            TargetError: If the memory read fails.
+        """
+        periph_obj = self._parser.get_peripheral(peripheral)
+        reg_obj = self._parser.get_register(peripheral, register)
+        address = periph_obj.base_address + reg_obj.address_offset
+
+        values = await self._memory.read_u32(address)
+        raw = values[0]
+        return decode_register(periph_obj, reg_obj, raw)
+
+    async def read_peripheral(self, peripheral: str) -> dict[str, DecodedRegister]:
+        """Read and decode every register in a peripheral.
+
+        Args:
+            peripheral: Peripheral name.
+
+        Returns:
+            Dict mapping register name to its DecodedRegister.
+
+        Raises:
+            SVDError: If peripheral not found.
+            TargetError: If any memory read fails.
+        """
+        periph_obj = self._parser.get_peripheral(peripheral)
+        registers = periph_obj.registers or []
+        result: dict[str, DecodedRegister] = {}
+
+        for reg_obj in registers:
+            address = periph_obj.base_address + reg_obj.address_offset
+            try:
+                values = await self._memory.read_u32(address)
+                raw = values[0]
+                result[reg_obj.name] = decode_register(periph_obj, reg_obj, raw)
+            except Exception as exc:
+                log.warning(
+                    "Failed to read %s.%s @ 0x%08X: %s",
+                    peripheral,
+                    reg_obj.name,
+                    address,
+                    exc,
+                )
+                # Skip unreadable registers (write-only, reserved, etc.)
+
+        return result
+
+    def decode(self, peripheral: str, register: str, value: int) -> DecodedRegister:
+        """Decode a raw value without reading hardware.
+
+        Useful when you already have the register value (from a log,
+        a previous read, or a known reset value).
+
+        Args:
+            peripheral: Peripheral name.
+            register: Register name.
+            value: Raw 32-bit register value.
+
+        Returns:
+            DecodedRegister with the decoded bitfields.
+        """
+        periph_obj = self._parser.get_peripheral(peripheral)
+        reg_obj = self._parser.get_register(peripheral, register)
+        return decode_register(periph_obj, reg_obj, value)
+
+
+class SyncSVDManager:
+    """Synchronous wrapper around SVDManager."""
+
+    def __init__(self, manager: SVDManager, loop: asyncio.AbstractEventLoop) -> None:
+        self._manager = manager
+        self._loop = loop
+
+    @property
+    def loaded(self) -> bool:
+        return self._manager.loaded
+
+    def load(self, svd_path: Path) -> None:
+        self._loop.run_until_complete(self._manager.load(svd_path))
+
+    def list_peripherals(self) -> list[str]:
+        return self._manager.list_peripherals()
+
+    def list_registers(self, peripheral: str) -> list[str]:
+        return self._manager.list_registers(peripheral)
+
+    def read_register(self, peripheral: str, register: str) -> DecodedRegister:
+        return self._loop.run_until_complete(
+            self._manager.read_register(peripheral, register)
+        )
+
+    def read_peripheral(self, peripheral: str) -> dict[str, DecodedRegister]:
+        return self._loop.run_until_complete(
+            self._manager.read_peripheral(peripheral)
+        )
+
+    def decode(self, peripheral: str, register: str, value: int) -> DecodedRegister:
+        return self._manager.decode(peripheral, register, value)

openocd/target.py

@@ -0,0 +1,164 @@
+"""Target state control — halt, resume, step, reset, and state queries.
+
+Wraps the OpenOCD target commands: halt, resume, step, reset,
+wait_halt, and targets (for state inspection).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from typing import Literal
+
+from openocd.connection.tcl_rpc import TclRpcConnection
+from openocd.errors import TargetError, TimeoutError
+from openocd.types import TargetState
+
+log = logging.getLogger(__name__)
+
+# Matches a target row from "targets" output, e.g.:
+#   " 0* stm32f1x.cpu       cortex_m   little stm32f1x.cpu       halted"
+_TARGET_ROW_RE = re.compile(
+    r"^\s*\d+\*?\s+"       # index, optional current marker
+    r"(\S+)\s+"            # target name
+    r"\S+\s+"              # type
+    r"\S+\s+"              # endian
+    r"\S+\s+"              # tap name
+    r"(\S+)"               # state
+)
+
+
+class Target:
+    """Target execution control — halt, resume, step, reset."""
+
+    def __init__(self, conn: TclRpcConnection) -> None:
+        self._conn = conn
+
+    async def halt(self) -> TargetState:
+        """Halt the target and return the resulting state."""
+        resp = await self._conn.send("halt")
+        if "error" in resp.lower() and "already" not in resp.lower():
+            raise TargetError(f"halt failed: {resp}")
+        return await self._parse_state()
+
+    async def resume(self, address: int | None = None) -> None:
+        """Resume execution, optionally from a specific address."""
+        cmd = "resume"
+        if address is not None:
+            cmd = f"resume 0x{address:x}"
+        resp = await self._conn.send(cmd)
+        if "error" in resp.lower():
+            raise TargetError(f"resume failed: {resp}")
+
+    async def step(self, address: int | None = None) -> TargetState:
+        """Single-step and return the resulting state."""
+        cmd = "step"
+        if address is not None:
+            cmd = f"step 0x{address:x}"
+        resp = await self._conn.send(cmd)
+        if "error" in resp.lower():
+            raise TargetError(f"step failed: {resp}")
+        return await self._parse_state()
+
+    async def reset(self, mode: Literal["run", "halt", "init"] = "halt") -> None:
+        """Reset the target.
+
+        Args:
+            mode: Reset mode — "run" resumes after reset, "halt" stops at
+                  the reset vector, "init" runs init scripts after reset.
+        """
+        resp = await self._conn.send(f"reset {mode}")
+        if "error" in resp.lower():
+            raise TargetError(f"reset failed: {resp}")
+
+    async def wait_halt(self, timeout_ms: int = 5000) -> TargetState:
+        """Block until the target halts or the timeout expires.
+
+        Args:
+            timeout_ms: Maximum wait time in milliseconds.
+
+        Raises:
+            TimeoutError: Target did not halt within the deadline.
+        """
+        resp = await self._conn.send(f"wait_halt {timeout_ms}")
+        if "timed out" in resp.lower() or "time out" in resp.lower():
+            raise TimeoutError(f"Target did not halt within {timeout_ms}ms")
+        if "error" in resp.lower():
+            raise TargetError(f"wait_halt failed: {resp}")
+        return await self._parse_state()
+
+    async def state(self) -> TargetState:
+        """Query and return the current target state."""
+        return await self._parse_state()
+
+    async def _parse_state(self) -> TargetState:
+        """Parse the ``targets`` command output into a TargetState.
+
+        The output looks like::
+
+            TargetName         Type       Endian TapName            State
+          --  ------------------ ---------- ------ ------------------ ------------
+           0* stm32f1x.cpu       cortex_m   little stm32f1x.cpu       halted
+
+        If the target is halted, also reads the program counter via ``reg pc``.
+        """
+        resp = await self._conn.send("targets")
+
+        name = "unknown"
+        raw_state = "unknown"
+
+        for line in resp.splitlines():
+            m = _TARGET_ROW_RE.match(line)
+            if m:
+                name = m.group(1)
+                raw_state = m.group(2).lower()
+                break
+
+        # Normalize to our known state literals
+        if raw_state not in ("running", "halted", "reset", "debug-running"):
+            raw_state = "unknown"
+
+        pc: int | None = None
+        if raw_state == "halted":
+            try:
+                pc = await self._read_pc()
+            except Exception:
+                log.debug("Could not read PC while halted", exc_info=True)
+
+        return TargetState(name=name, state=raw_state, current_pc=pc)
+
+    async def _read_pc(self) -> int:
+        """Read the program counter from the halted target."""
+        resp = await self._conn.send("reg pc")
+        # Output: "pc (/32): 0x08001234"
+        m = re.search(r":\s*(0x[0-9a-fA-F]+)", resp)
+        if not m:
+            raise TargetError(f"Cannot parse PC from: {resp}")
+        return int(m.group(1), 16)
+
+
+class SyncTarget:
+    """Synchronous wrapper around Target."""
+
+    def __init__(self, target: Target, loop: asyncio.AbstractEventLoop) -> None:
+        self._target = target
+        self._loop = loop
+
+    def halt(self) -> TargetState:
+        return self._loop.run_until_complete(self._target.halt())
+
+    def resume(self, address: int | None = None) -> None:
+        self._loop.run_until_complete(self._target.resume(address))
+
+    def step(self, address: int | None = None) -> TargetState:
+        return self._loop.run_until_complete(self._target.step(address))
+
+    def reset(self, mode: Literal["run", "halt", "init"] = "halt") -> None:
+        self._loop.run_until_complete(self._target.reset(mode))
+
+    def wait_halt(self, timeout_ms: int = 5000) -> TargetState:
+        return self._loop.run_until_complete(self._target.wait_halt(timeout_ms))
+
+    def state(self) -> TargetState:
+        return self._loop.run_until_complete(self._target.state())

openocd/transport.py

@@ -0,0 +1,149 @@
+"""Transport selection and debug adapter configuration.
+
+OpenOCD supports multiple debug transports (JTAG, SWD, SWIM, etc.)
+and various adapter interfaces (CMSIS-DAP, ST-Link, J-Link, etc.).
+This module provides access to transport and adapter state.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from openocd.errors import OpenOCDError
+
+if TYPE_CHECKING:
+    from openocd.connection.base import Connection
+
+log = logging.getLogger(__name__)
+
+
+class Transport:
+    """Query and configure the debug transport and adapter.
+
+    Usage::
+
+        transport = Transport(conn)
+        current = await transport.select()    # e.g. "swd"
+        available = await transport.list()     # e.g. ["jtag", "swd"]
+        speed = await transport.adapter_speed()      # current kHz
+        await transport.adapter_speed(4000)          # set to 4 MHz
+    """
+
+    def __init__(self, conn: Connection) -> None:
+        self._conn = conn
+
+    async def select(self) -> str:
+        """Get the currently selected transport.
+
+        Returns:
+            Transport name string (e.g. "jtag", "swd", "swim").
+
+        Raises:
+            OpenOCDError: If the command fails.
+        """
+        response = await self._conn.send("transport select")
+        response = response.strip()
+        if not response:
+            raise OpenOCDError("Empty response from 'transport select'")
+        return response
+
+    async def list(self) -> list[str]:
+        """List transports available for the current adapter.
+
+        Returns:
+            List of transport name strings.
+
+        Raises:
+            OpenOCDError: If the command fails.
+        """
+        response = await self._conn.send("transport list")
+        response = response.strip()
+        if not response:
+            raise OpenOCDError("Empty response from 'transport list'")
+
+        # OpenOCD may return a Tcl list like "jtag swd" or one per line
+        transports: list[str] = []
+        for line in response.splitlines():
+            for token in line.split():
+                cleaned = token.strip("{}")
+                if cleaned:
+                    transports.append(cleaned)
+        return transports
+
+    async def adapter_info(self) -> str:
+        """Get adapter/interface information.
+
+        Tries ``adapter name`` first (newer OpenOCD), falls back to
+        ``adapter info`` for older versions.
+
+        Returns:
+            Adapter description string.
+        """
+        # "adapter name" is the preferred command in OpenOCD >= 0.12
+        response = await self._conn.send("adapter name")
+        response = response.strip()
+
+        if not response or "invalid" in response.lower() or "error" in response.lower():
+            response = await self._conn.send("adapter info")
+            response = response.strip()
+
+        if not response:
+            raise OpenOCDError("Could not determine adapter info")
+        return response
+
+    async def adapter_speed(self, khz: int | None = None) -> int:
+        """Get or set the adapter clock speed.
+
+        Args:
+            khz: If provided, set the adapter speed to this value in kHz.
+                 If None, just query the current speed.
+
+        Returns:
+            The current (or newly set) adapter speed in kHz.
+
+        Raises:
+            OpenOCDError: If the command fails or response is not parseable.
+        """
+        cmd = f"adapter speed {khz}" if khz is not None else "adapter speed"
+
+        response = await self._conn.send(cmd)
+        response = response.strip()
+
+        # OpenOCD response is typically just a number, or
+        # "adapter speed: 4000 kHz" depending on the interface
+        speed = _parse_speed(response)
+        if speed is None:
+            raise OpenOCDError(f"Cannot parse adapter speed from: {response!r}")
+
+        if khz is not None:
+            log.info("Adapter speed set to %d kHz", speed)
+        return speed
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _parse_speed(response: str) -> int | None:
+    """Extract a numeric kHz value from an adapter speed response.
+
+    Handles formats like:
+        "4000"
+        "adapter speed: 4000 kHz"
+        "4000 kHz"
+    """
+    # Try the whole thing as a plain integer
+    try:
+        return int(response)
+    except ValueError:
+        pass
+
+    # Pull out the first integer-looking token
+    for token in response.replace(":", " ").split():
+        try:
+            return int(token)
+        except ValueError:
+            continue
+
+    return None