Ryan Malloy
bc7cb77ec4
Critical fixes: - Separate notification and command connections to eliminate dual-reader race condition on the TCL RPC stream (C-1) - Fix _get_or_create_loop() swallowing its own RuntimeError, causing deadlock when sync API called from async context (C-2) - Add bounds checking to config string parser (C-3) - Clean up OpenOCD subprocess on connection failure in Session.start (H-1) Defense in depth: - Add MAX_RESPONSE_SIZE (10MB) guard against unbounded buffer growth - Preserve bytes after separator in _read_until_separator remainder buffer - Set notification_failed flag when listener crashes, warn on next send - Standardize error detection to case-insensitive across all modules - Escape TCL special characters in RTT channelwrite to prevent injection - Redirect OpenOCD stdout to DEVNULL to prevent pipe buffer deadlock - Run SVD XML parsing in asyncio.to_thread to avoid blocking event loop Consistency: - Cache SyncSession subsystem wrappers (match async Session pattern) - Make DecodedRegister frozen (match all other dataclasses) - Add py.typed marker for PEP 561 type checker support - Accept list[str] config in OpenOCDProcess.start for paths with spaces Tests: - Add 50 error-path tests covering connection, target, memory, register, flash, breakpoint, session, process, and notification failure modes
openocd-python
Typed, async-first Python bindings for the full OpenOCD command surface.
Install
pip install openocd-python
Quick Start
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=)