openocd-python 2026.2.12__py3-none-any.whl

openocd/__init__.py

@@ -0,0 +1,64 @@
+"""openocd-python — typed, async-first Python bindings for OpenOCD."""
+
+from openocd.errors import (
+    ConnectionError,
+    FlashError,
+    JTAGError,
+    OpenOCDError,
+    ProcessError,
+    SVDError,
+    TargetError,
+    TargetNotHaltedError,
+    TimeoutError,
+)
+from openocd.session import Session, SyncSession
+from openocd.types import (
+    BitField,
+    Breakpoint,
+    DecodedRegister,
+    FlashBank,
+    FlashSector,
+    JTAGState,
+    MemoryRegion,
+    Register,
+    RTTChannel,
+    TAPInfo,
+    TargetState,
+    Watchpoint,
+)
+
+__all__ = [
+    # Session
+    "Session",
+    "SyncSession",
+    # Types
+    "BitField",
+    "Breakpoint",
+    "DecodedRegister",
+    "FlashBank",
+    "FlashSector",
+    "JTAGState",
+    "MemoryRegion",
+    "RTTChannel",
+    "Register",
+    "TAPInfo",
+    "TargetState",
+    "Watchpoint",
+    # Errors
+    "ConnectionError",
+    "FlashError",
+    "JTAGError",
+    "OpenOCDError",
+    "ProcessError",
+    "SVDError",
+    "TargetError",
+    "TargetNotHaltedError",
+    "TimeoutError",
+]
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("openocd-python")
+except Exception:
+    __version__ = "0.0.0"

openocd/breakpoints.py

@@ -0,0 +1,234 @@
+"""Breakpoint and watchpoint management.
+
+Wraps OpenOCD's ``bp``, ``rbp``, ``wp``, and ``rwp`` commands for
+setting, removing, and listing hardware/software breakpoints and
+data watchpoints.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+from typing import Literal
+
+from openocd.connection.base import Connection
+from openocd.errors import OpenOCDError
+from openocd.types import Breakpoint, Watchpoint
+
+log = logging.getLogger(__name__)
+
+
+class BreakpointError(OpenOCDError):
+    """A breakpoint or watchpoint operation failed."""
+
+
+# ---------------------------------------------------------------------------
+# Parsers
+# ---------------------------------------------------------------------------
+
+# Breakpoint(IVA): 0x08001234, 0x2, 1   (hw=1) or 0 (sw)
+_BP_RE = re.compile(
+    r"Breakpoint\([^)]*\):\s*(?P<addr>0x[0-9a-fA-F]+),\s*"
+    r"(?P<len>0x[0-9a-fA-F]+),\s*(?P<hw>\d+)"
+)
+
+# Watchpoint output varies across OpenOCD versions. Common formats:
+#   address: 0x20000000, len: 0x4, r/w/a: 2 (access), value: ...
+#   Watchpoint(DWT): 0x20000000, 0x4, 2
+_WP_RE = re.compile(
+    r"(?:address:\s*(?P<addr1>0x[0-9a-fA-F]+).*?len:\s*(?P<len1>0x[0-9a-fA-F]+).*?r/w/a:\s*(?P<rwa1>\d+))"
+    r"|"
+    r"(?:Watchpoint\([^)]*\):\s*(?P<addr2>0x[0-9a-fA-F]+),\s*(?P<len2>0x[0-9a-fA-F]+),\s*(?P<rwa2>\d+))"
+)
+
+# OpenOCD watchpoint access type encoding
+_WP_ACCESS_MAP = {0: "r", 1: "w", 2: "rw"}
+_WP_ACCESS_CMD = {"r": "r", "w": "w", "rw": "a"}
+
+
+def _check_error(response: str, context: str) -> None:
+    """Raise BreakpointError if the response indicates failure."""
+    if "error" in response.lower():
+        raise BreakpointError(f"{context}: {response.strip()}")
+
+
+def _parse_breakpoint_list(text: str) -> list[Breakpoint]:
+    """Parse the output of ``bp`` (no arguments) into Breakpoint objects."""
+    breakpoints: list[Breakpoint] = []
+    for idx, m in enumerate(_BP_RE.finditer(text)):
+        hw_flag = int(m.group("hw"))
+        breakpoints.append(
+            Breakpoint(
+                number=idx,
+                type="hw" if hw_flag else "sw",
+                address=int(m.group("addr"), 16),
+                length=int(m.group("len"), 16),
+                enabled=True,
+            )
+        )
+    return breakpoints
+
+
+def _parse_watchpoint_list(text: str) -> list[Watchpoint]:
+    """Parse watchpoint listing output."""
+    watchpoints: list[Watchpoint] = []
+    for idx, m in enumerate(_WP_RE.finditer(text)):
+        # Match could come from either alternative in the regex
+        if m.group("addr1") is not None:
+            addr = int(m.group("addr1"), 16)
+            length = int(m.group("len1"), 16)
+            rwa = int(m.group("rwa1"))
+        else:
+            addr = int(m.group("addr2"), 16)
+            length = int(m.group("len2"), 16)
+            rwa = int(m.group("rwa2"))
+
+        watchpoints.append(
+            Watchpoint(
+                number=idx,
+                address=addr,
+                length=length,
+                access=_WP_ACCESS_MAP.get(rwa, "rw"),
+            )
+        )
+    return watchpoints
+
+
+class BreakpointManager:
+    """Manage breakpoints and watchpoints via OpenOCD.
+
+    Breakpoints can be either software (patching the instruction) or
+    hardware (using on-chip comparators). Watchpoints trigger on data
+    access to a given address range.
+    """
+
+    def __init__(self, conn: Connection) -> None:
+        self._conn = conn
+
+    # ------------------------------------------------------------------
+    # Breakpoints
+    # ------------------------------------------------------------------
+
+    async def add(self, address: int, length: int = 2, hw: bool = False) -> None:
+        """Set a breakpoint at the given address.
+
+        Args:
+            address: Instruction address for the breakpoint.
+            length: Breakpoint length in bytes (2 for Thumb, 4 for ARM).
+            hw: Request a hardware breakpoint. If False, OpenOCD uses a
+                software breakpoint when possible.
+        """
+        cmd = f"bp 0x{address:08X} {length}"
+        if hw:
+            cmd += " hw"
+        resp = await self._conn.send(cmd)
+        _check_error(resp, f"bp 0x{address:08X}")
+        log.info("Breakpoint set at 0x%08X (len=%d, hw=%s)", address, length, hw)
+
+    async def remove(self, address: int) -> None:
+        """Remove a breakpoint at the given address.
+
+        Args:
+            address: Address of the breakpoint to remove.
+        """
+        cmd = f"rbp 0x{address:08X}"
+        resp = await self._conn.send(cmd)
+        _check_error(resp, f"rbp 0x{address:08X}")
+        log.info("Breakpoint removed at 0x%08X", address)
+
+    async def list(self) -> list[Breakpoint]:
+        """List all active breakpoints.
+
+        Returns:
+            A list of Breakpoint objects describing each active breakpoint.
+        """
+        resp = await self._conn.send("bp")
+        # An empty response or no matches means no breakpoints set
+        if not resp.strip():
+            return []
+        return _parse_breakpoint_list(resp)
+
+    # ------------------------------------------------------------------
+    # Watchpoints
+    # ------------------------------------------------------------------
+
+    async def add_watchpoint(
+        self,
+        address: int,
+        length: int,
+        access: Literal["r", "w", "rw"] = "rw",
+    ) -> None:
+        """Set a data watchpoint.
+
+        Args:
+            address: Memory address to watch.
+            length: Number of bytes to watch (must be power of 2 on most targets).
+            access: Access type -- ``"r"`` for read, ``"w"`` for write,
+                    ``"rw"`` for read/write (access).
+        """
+        access_flag = _WP_ACCESS_CMD.get(access, "a")
+        cmd = f"wp 0x{address:08X} {length} {access_flag}"
+        resp = await self._conn.send(cmd)
+        _check_error(resp, f"wp 0x{address:08X}")
+        log.info("Watchpoint set at 0x%08X (len=%d, access=%s)", address, length, access)
+
+    async def remove_watchpoint(self, address: int) -> None:
+        """Remove a watchpoint at the given address.
+
+        Args:
+            address: Address of the watchpoint to remove.
+        """
+        cmd = f"rwp 0x{address:08X}"
+        resp = await self._conn.send(cmd)
+        _check_error(resp, f"rwp 0x{address:08X}")
+        log.info("Watchpoint removed at 0x%08X", address)
+
+    async def list_watchpoints(self) -> list[Watchpoint]:
+        """List all active watchpoints.
+
+        Returns:
+            A list of Watchpoint objects describing each active watchpoint.
+        """
+        # OpenOCD doesn't have a dedicated "list watchpoints" command
+        # but 'wp' with no arguments on some builds returns the list.
+        # The more reliable approach is using the TCL command.
+        resp = await self._conn.send("wp")
+        if not resp.strip():
+            return []
+        return _parse_watchpoint_list(resp)
+
+
+# ======================================================================
+# Sync wrapper
+# ======================================================================
+
+class SyncBreakpointManager:
+    """Synchronous wrapper around BreakpointManager."""
+
+    def __init__(self, bp_manager: BreakpointManager, loop: asyncio.AbstractEventLoop) -> None:
+        self._bp = bp_manager
+        self._loop = loop
+
+    def add(self, address: int, length: int = 2, hw: bool = False) -> None:
+        self._loop.run_until_complete(self._bp.add(address, length=length, hw=hw))
+
+    def remove(self, address: int) -> None:
+        self._loop.run_until_complete(self._bp.remove(address))
+
+    def list(self) -> list[Breakpoint]:
+        return self._loop.run_until_complete(self._bp.list())
+
+    def add_watchpoint(
+        self,
+        address: int,
+        length: int,
+        access: Literal["r", "w", "rw"] = "rw",
+    ) -> None:
+        self._loop.run_until_complete(self._bp.add_watchpoint(address, length, access=access))
+
+    def remove_watchpoint(self, address: int) -> None:
+        self._loop.run_until_complete(self._bp.remove_watchpoint(address))
+
+    def list_watchpoints(self) -> list[Watchpoint]:
+        return self._loop.run_until_complete(self._bp.list_watchpoints())

openocd/cli.py

@@ -0,0 +1,161 @@
+"""CLI entry point for openocd-python.
+
+Provides quick diagnostics and a REPL for interactive use:
+
+    $ openocd-python --help
+    $ openocd-python info               # probe detection + target info
+    $ openocd-python repl               # interactive command REPL
+    $ openocd-python read 0x08000000 16 # quick memory read
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+
+
+def main() -> None:
+    try:
+        from importlib.metadata import version
+
+        pkg_version = version("openocd-python")
+    except Exception:
+        pkg_version = "dev"
+
+    parser = argparse.ArgumentParser(
+        prog="openocd-python",
+        description=f"OpenOCD Python bindings v{pkg_version}",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"openocd-python {pkg_version}"
+    )
+    parser.add_argument(
+        "--host", default="localhost", help="OpenOCD host (default: localhost)"
+    )
+    parser.add_argument(
+        "--port", type=int, default=6666, help="OpenOCD TCL RPC port (default: 6666)"
+    )
+
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("info", help="Show target and adapter information")
+
+    repl_parser = sub.add_parser("repl", help="Interactive OpenOCD command REPL")
+    repl_parser.add_argument(
+        "--timeout", type=float, default=10.0, help="Command timeout in seconds"
+    )
+
+    read_parser = sub.add_parser("read", help="Read memory and display as hexdump")
+    read_parser.add_argument("address", help="Start address (hex, e.g. 0x08000000)")
+    read_parser.add_argument(
+        "size", type=int, nargs="?", default=64, help="Bytes to read (default: 64)"
+    )
+
+    sub.add_parser("scan", help="Scan the JTAG chain")
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    asyncio.run(_dispatch(args))
+
+
+async def _dispatch(args: argparse.Namespace) -> None:
+    from openocd.session import Session
+
+    async with Session.connect(host=args.host, port=args.port) as ocd:
+        if args.command == "info":
+            await _cmd_info(ocd)
+        elif args.command == "repl":
+            await _cmd_repl(ocd, timeout=args.timeout)
+        elif args.command == "read":
+            await _cmd_read(ocd, args.address, args.size)
+        elif args.command == "scan":
+            await _cmd_scan(ocd)
+
+
+async def _cmd_info(ocd) -> None:
+    """Display target state and adapter information."""
+    from openocd.errors import OpenOCDError
+
+    print("=== OpenOCD Target Info ===\n")
+
+    try:
+        state = await ocd.target.state()
+        print(f"  Target:  {state.name}")
+        print(f"  State:   {state.state}")
+        if state.current_pc is not None:
+            print(f"  PC:      0x{state.current_pc:08X}")
+    except OpenOCDError as e:
+        print(f"  Target:  (error: {e})")
+
+    print()
+
+    try:
+        transport_name = await ocd.transport.select()
+        print(f"  Transport: {transport_name}")
+    except OpenOCDError:
+        pass
+
+    try:
+        adapter = await ocd.transport.adapter_info()
+        print(f"  Adapter:   {adapter}")
+    except OpenOCDError:
+        pass
+
+    try:
+        speed = await ocd.transport.adapter_speed()
+        print(f"  Speed:     {speed} kHz")
+    except OpenOCDError:
+        pass
+
+
+async def _cmd_repl(ocd, timeout: float = 10.0) -> None:
+    """Interactive command REPL."""
+    print("OpenOCD REPL (type 'quit' or Ctrl-D to exit)\n")
+    while True:
+        try:
+            cmd = input("ocd> ")
+        except (EOFError, KeyboardInterrupt):
+            print()
+            break
+        if cmd.strip().lower() in ("quit", "exit", "q"):
+            break
+        if not cmd.strip():
+            continue
+        try:
+            result = await ocd.command(cmd)
+            if result.strip():
+                print(result)
+        except Exception as e:
+            print(f"Error: {e}")
+
+
+async def _cmd_read(ocd, address_str: str, size: int) -> None:
+    """Read memory and display as hexdump."""
+    addr = int(address_str, 0)
+    dump = await ocd.memory.hexdump(addr, size)
+    print(dump)
+
+
+async def _cmd_scan(ocd) -> None:
+    """Scan the JTAG chain."""
+    taps = await ocd.jtag.scan_chain()
+    if not taps:
+        print("No TAPs found on the JTAG chain.")
+        return
+
+    print(f"{'TAP Name':<25s} {'IDCODE':>10s}  IR  Enabled")
+    print("-" * 50)
+    for tap in taps:
+        print(
+            f"{tap.name:<25s} 0x{tap.idcode:08X}  {tap.ir_length:>2d}  "
+            f"{'yes' if tap.enabled else 'no'}"
+        )
+
+
+if __name__ == "__main__":
+    main()

openocd/connection/__init__.py

@@ -0,0 +1,7 @@
+"""Connection backends for communicating with OpenOCD."""
+
+from openocd.connection.base import Connection
+from openocd.connection.tcl_rpc import TclRpcConnection
+from openocd.connection.telnet import TelnetConnection
+
+__all__ = ["Connection", "TclRpcConnection", "TelnetConnection"]

openocd/connection/base.py

@@ -0,0 +1,30 @@
+"""Abstract base class for OpenOCD connection backends."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+
+
+class Connection(ABC):
+    """Protocol-agnostic interface to an OpenOCD instance."""
+
+    @abstractmethod
+    async def connect(self, host: str, port: int) -> None:
+        """Open a connection to the given host and port."""
+
+    @abstractmethod
+    async def send(self, command: str) -> str:
+        """Send a command string and return the response."""
+
+    @abstractmethod
+    async def close(self) -> None:
+        """Close the connection."""
+
+    @abstractmethod
+    async def enable_notifications(self) -> None:
+        """Enable asynchronous event notifications from OpenOCD."""
+
+    @abstractmethod
+    def on_notification(self, callback: Callable[[str], None]) -> None:
+        """Register a callback for incoming notifications."""