openocd-python 2026.2.12__tar.gz

openocd_python-2026.2.12/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/

openocd_python-2026.2.12/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ryan Malloy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openocd_python-2026.2.12/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: openocd-python
+Version: 2026.2.12
+Summary: Typed, async-first Python bindings for the full OpenOCD command surface
+Project-URL: Homepage, https://git.supported.systems/ryan/openocd-python
+Project-URL: Issues, https://git.supported.systems/ryan/openocd-python/issues
+Author-email: Ryan Malloy <ryan@supported.systems>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: debugging,embedded,hardware,jtag,openocd,swd
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Embedded Systems
+Classifier: Topic :: System :: Hardware
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cmsis-svd>=0.4
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# openocd-python
+
+Typed, async-first Python bindings for the full OpenOCD command surface.
+
+## Install
+
+```bash
+pip install openocd-python
+```
+
+## Quick Start
+
+```python
+from openocd import Session
+
+# Connect to a running OpenOCD instance
+async with Session.connect() as ocd:
+    state = await ocd.target.halt()
+    pc = await ocd.registers.pc()
+    mem = await ocd.memory.read_u32(0x08000000, 4)
+    print(f"PC: {pc:#x}")
+
+# Or spawn OpenOCD and connect
+async with Session.start("interface/cmsis-dap.cfg -f target/stm32f1x.cfg") as ocd:
+    await ocd.target.halt()
+    regs = await ocd.registers.read_all()
+
+# Synchronous API available too
+with Session.start_sync("interface/cmsis-dap.cfg") as ocd:
+    ocd.target.halt()
+    print(f"PC: {ocd.registers.pc():#x}")
+```
+
+## Features
+
+- **Async-first** with sync wrappers for every method
+- **Typed returns** — dataclasses, not raw strings
+- **Full OpenOCD surface**: target control, memory, registers, flash, JTAG, breakpoints, RTT
+- **SVD decoding** — read a peripheral register and get named bitfields
+- **Process management** — spawn and manage OpenOCD subprocesses
+- **Dual transport** — TCL RPC (primary) and telnet (fallback)
+
+## Requirements
+
+- Python 3.11+
+- OpenOCD installed and on PATH (or pass `openocd_bin=`)

openocd_python-2026.2.12/README.md

@@ -0,0 +1,46 @@
+# openocd-python
+
+Typed, async-first Python bindings for the full OpenOCD command surface.
+
+## Install
+
+```bash
+pip install openocd-python
+```
+
+## Quick Start
+
+```python
+from openocd import Session
+
+# Connect to a running OpenOCD instance
+async with Session.connect() as ocd:
+    state = await ocd.target.halt()
+    pc = await ocd.registers.pc()
+    mem = await ocd.memory.read_u32(0x08000000, 4)
+    print(f"PC: {pc:#x}")
+
+# Or spawn OpenOCD and connect
+async with Session.start("interface/cmsis-dap.cfg -f target/stm32f1x.cfg") as ocd:
+    await ocd.target.halt()
+    regs = await ocd.registers.read_all()
+
+# Synchronous API available too
+with Session.start_sync("interface/cmsis-dap.cfg") as ocd:
+    ocd.target.halt()
+    print(f"PC: {ocd.registers.pc():#x}")
+```
+
+## Features
+
+- **Async-first** with sync wrappers for every method
+- **Typed returns** — dataclasses, not raw strings
+- **Full OpenOCD surface**: target control, memory, registers, flash, JTAG, breakpoints, RTT
+- **SVD decoding** — read a peripheral register and get named bitfields
+- **Process management** — spawn and manage OpenOCD subprocesses
+- **Dual transport** — TCL RPC (primary) and telnet (fallback)
+
+## Requirements
+
+- Python 3.11+
+- OpenOCD installed and on PATH (or pass `openocd_bin=`)

openocd_python-2026.2.12/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openocd-python"
+version = "2026.02.12"
+description = "Typed, async-first Python bindings for the full OpenOCD command surface"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    {name = "Ryan Malloy", email = "ryan@supported.systems"},
+]
+keywords = ["openocd", "jtag", "swd", "embedded", "debugging", "hardware"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Debuggers",
+    "Topic :: Software Development :: Embedded Systems",
+    "Topic :: System :: Hardware",
+    "Typing :: Typed",
+]
+dependencies = [
+    "cmsis-svd>=0.4",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.8",
+]
+
+[project.scripts]
+openocd-python = "openocd.cli:main"
+
+[project.urls]
+Homepage = "https://git.supported.systems/ryan/openocd-python"
+Issues = "https://git.supported.systems/ryan/openocd-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/openocd"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+markers = [
+    "hardware: requires physical DAP-Link hardware (deselect with '-m not hardware')",
+]

openocd_python-2026.2.12/src/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_python-2026.2.12/src/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_python-2026.2.12/src/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_python-2026.2.12/src/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"]