openocd-python 2026.2.12__py3-none-any.whl

openocd/rtt.py

@@ -0,0 +1,233 @@
+"""Real-Time Transfer (RTT) support via OpenOCD.
+
+SEGGER RTT provides high-speed bidirectional communication between
+a debug host and an embedded target using shared memory in RAM.
+OpenOCD exposes RTT through its ``rtt`` command family.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from typing import TYPE_CHECKING
+
+from openocd.errors import OpenOCDError
+from openocd.types import RTTChannel
+
+if TYPE_CHECKING:
+    from openocd.connection.base import Connection
+
+log = logging.getLogger(__name__)
+
+
+class RTTManager:
+    """Control and use SEGGER RTT channels via OpenOCD.
+
+    Typical flow::
+
+        rtt = RTTManager(conn)
+        await rtt.setup(address=0x20000000, size=0x1000)
+        await rtt.start()
+        channels = await rtt.channels()
+        data = await rtt.read(0)
+        await rtt.write(0, "hello\\n")
+        await rtt.stop()
+    """
+
+    def __init__(self, conn: Connection) -> None:
+        self._conn = conn
+
+    async def setup(
+        self,
+        address: int,
+        size: int,
+        id_string: str = "SEGGER RTT",
+    ) -> None:
+        """Configure RTT control block search parameters.
+
+        Args:
+            address: Start address of the RAM region to search.
+            size: Size of the search region in bytes.
+            id_string: RTT control block identifier (default "SEGGER RTT").
+
+        Raises:
+            OpenOCDError: If the setup command fails.
+        """
+        cmd = f'rtt setup 0x{address:X} 0x{size:X} "{id_string}"'
+        response = await self._conn.send(cmd)
+        _check_rtt_response(response, cmd)
+        log.info(
+            "RTT setup: search 0x%08X +0x%X id=%r",
+            address,
+            size,
+            id_string,
+        )
+
+    async def start(self) -> None:
+        """Start RTT — searches for the control block and activates channels.
+
+        Raises:
+            OpenOCDError: If the control block is not found or start fails.
+        """
+        response = await self._conn.send("rtt start")
+        _check_rtt_response(response, "rtt start")
+        log.info("RTT started")
+
+    async def stop(self) -> None:
+        """Stop RTT communication.
+
+        Raises:
+            OpenOCDError: If the stop command fails.
+        """
+        response = await self._conn.send("rtt stop")
+        _check_rtt_response(response, "rtt stop")
+        log.info("RTT stopped")
+
+    async def channels(self) -> list[RTTChannel]:
+        """List available RTT channels.
+
+        Returns:
+            List of RTTChannel descriptors (index, name, size, direction).
+
+        Raises:
+            OpenOCDError: If the channels command fails.
+        """
+        response = await self._conn.send("rtt channels")
+        _check_rtt_response(response, "rtt channels")
+        return _parse_channels(response)
+
+    async def read(self, channel: int) -> str:
+        """Read pending data from an RTT up-channel.
+
+        Args:
+            channel: Channel index (typically 0 for Terminal).
+
+        Returns:
+            The data read as a string (may be empty if nothing pending).
+
+        Raises:
+            OpenOCDError: If the read command fails.
+        """
+        cmd = f"rtt channelread {channel}"
+        response = await self._conn.send(cmd)
+        _check_rtt_response(response, cmd)
+        return response
+
+    async def write(self, channel: int, data: str) -> None:
+        """Write data to an RTT down-channel.
+
+        Args:
+            channel: Channel index (typically 0 for Terminal).
+            data: String data to send to the target.
+
+        Raises:
+            OpenOCDError: If the write command fails.
+        """
+        # Escape TCL special characters to prevent injection
+        escaped = (
+            data.replace("\\", "\\\\")
+            .replace('"', '\\"')
+            .replace("[", "\\[")
+            .replace("$", "\\$")
+        )
+        cmd = f'rtt channelwrite {channel} "{escaped}"'
+        response = await self._conn.send(cmd)
+        _check_rtt_response(response, cmd)
+
+
+class SyncRTTManager:
+    """Synchronous wrapper around RTTManager."""
+
+    def __init__(self, manager: RTTManager, loop: asyncio.AbstractEventLoop) -> None:
+        self._manager = manager
+        self._loop = loop
+
+    def setup(
+        self,
+        address: int,
+        size: int,
+        id_string: str = "SEGGER RTT",
+    ) -> None:
+        self._loop.run_until_complete(
+            self._manager.setup(address, size, id_string)
+        )
+
+    def start(self) -> None:
+        self._loop.run_until_complete(self._manager.start())
+
+    def stop(self) -> None:
+        self._loop.run_until_complete(self._manager.stop())
+
+    def channels(self) -> list[RTTChannel]:
+        return self._loop.run_until_complete(self._manager.channels())
+
+    def read(self, channel: int) -> str:
+        return self._loop.run_until_complete(self._manager.read(channel))
+
+    def write(self, channel: int, data: str) -> None:
+        self._loop.run_until_complete(self._manager.write(channel, data))
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _check_rtt_response(response: str, command: str) -> None:
+    """Raise on error responses from RTT commands."""
+    if response and "error" in response.lower():
+        raise OpenOCDError(f"RTT command failed ({command}): {response}")
+
+
+def _parse_channels(response: str) -> list[RTTChannel]:
+    """Parse the output of ``rtt channels`` into RTTChannel objects.
+
+    OpenOCD typically outputs lines like::
+
+        Up-channels:
+          0: Terminal 1024
+        Down-channels:
+          0: Terminal 16
+
+    The exact format may vary by OpenOCD version; this parser is
+    intentionally lenient.
+    """
+    channels: list[RTTChannel] = []
+    direction = "up"
+
+    for line in response.splitlines():
+        stripped = line.strip()
+        lower = stripped.lower()
+
+        if "up-channel" in lower or lower.startswith("up"):
+            direction = "up"
+            continue
+        if "down-channel" in lower or lower.startswith("down"):
+            direction = "down"
+            continue
+
+        # Try to parse lines like "0: Terminal 1024"
+        if ":" in stripped and stripped[0].isdigit():
+            parts = stripped.split(":", 1)
+            try:
+                index = int(parts[0].strip())
+            except ValueError:
+                continue
+
+            rest = parts[1].strip().split()
+            name = rest[0] if rest else f"channel_{index}"
+            size = 0
+            if len(rest) >= 2:
+                with contextlib.suppress(ValueError):
+                    size = int(rest[-1])
+
+            channels.append(
+                RTTChannel(
+                    index=index,
+                    name=name,
+                    size=size,
+                    direction=direction,
+                )
+            )
+
+    return channels

openocd/session.py

@@ -0,0 +1,330 @@
+"""Session — the main entry point for openocd-python.
+
+Manages the connection lifecycle and provides access to all subsystems
+(target, memory, registers, flash, JTAG, SVD, etc.).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from openocd.connection.tcl_rpc import TclRpcConnection
+from openocd.process import OpenOCDProcess
+
+if TYPE_CHECKING:
+    from openocd.breakpoints import BreakpointManager, SyncBreakpointManager
+    from openocd.flash import Flash, SyncFlash
+    from openocd.jtag import JTAGController, SyncJTAGController
+    from openocd.memory import Memory, SyncMemory
+    from openocd.registers import Registers, SyncRegisters
+    from openocd.rtt import RTTManager
+    from openocd.svd import SVDManager, SyncSVDManager
+    from openocd.target import SyncTarget, Target
+    from openocd.transport import Transport
+
+log = logging.getLogger(__name__)
+
+
+class Session:
+    """Main entry point. Manages connection and provides access to subsystems."""
+
+    def __init__(self, connection: TclRpcConnection, process: OpenOCDProcess | None = None) -> None:
+        self._conn = connection
+        self._process = process
+        self._target: Target | None = None
+        self._memory: Memory | None = None
+        self._registers: Registers | None = None
+        self._flash: Flash | None = None
+        self._jtag: JTAGController | None = None
+        self._breakpoints: BreakpointManager | None = None
+        self._rtt: RTTManager | None = None
+        self._svd: SVDManager | None = None
+        self._transport: Transport | None = None
+
+    # ------------------------------------------------------------------
+    # Factory methods
+    # ------------------------------------------------------------------
+
+    @classmethod
+    async def start(
+        cls,
+        config: str | Path,
+        *,
+        tcl_port: int = 6666,
+        openocd_bin: str | None = None,
+        timeout: float = 10.0,
+        extra_args: list[str] | None = None,
+    ) -> Session:
+        """Spawn an OpenOCD process and connect to it.
+
+        Args:
+            config: Config file path or ``-f``/``-c`` flags string.
+            tcl_port: TCL RPC port.
+            openocd_bin: Custom OpenOCD binary path.
+            timeout: Seconds to wait for OpenOCD readiness.
+            extra_args: Additional CLI arguments for OpenOCD.
+        """
+        proc = OpenOCDProcess()
+        await proc.start(
+            str(config), extra_args=extra_args, tcl_port=tcl_port, openocd_bin=openocd_bin
+        )
+        await proc.wait_ready(timeout=timeout)
+
+        try:
+            conn = TclRpcConnection(timeout=timeout)
+            await conn.connect("localhost", tcl_port)
+        except Exception:
+            await proc.stop()
+            raise
+
+        return cls(connection=conn, process=proc)
+
+    @classmethod
+    async def connect(
+        cls,
+        host: str = "localhost",
+        port: int = 6666,
+        timeout: float = 10.0,
+    ) -> Session:
+        """Connect to an already-running OpenOCD instance."""
+        conn = TclRpcConnection(timeout=timeout)
+        await conn.connect(host, port)
+        return cls(connection=conn)
+
+    # ------------------------------------------------------------------
+    # Sync factory wrappers
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def start_sync(cls, config: str | Path, **kwargs) -> SyncSession:
+        """Synchronous version of start(). Returns a SyncSession."""
+        loop = _get_or_create_loop()
+        session = loop.run_until_complete(cls.start(config, **kwargs))
+        return SyncSession(session, loop)
+
+    @classmethod
+    def connect_sync(cls, host: str = "localhost", port: int = 6666, **kwargs) -> SyncSession:
+        """Synchronous version of connect(). Returns a SyncSession."""
+        loop = _get_or_create_loop()
+        session = loop.run_until_complete(cls.connect(host, port, **kwargs))
+        return SyncSession(session, loop)
+
+    # ------------------------------------------------------------------
+    # Context manager
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> Session:
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the connection and stop the subprocess if we spawned it."""
+        await self._conn.close()
+        if self._process:
+            await self._process.stop()
+
+    # ------------------------------------------------------------------
+    # Raw command escape hatch
+    # ------------------------------------------------------------------
+
+    async def command(self, cmd: str) -> str:
+        """Send a raw OpenOCD command and return the response string."""
+        return await self._conn.send(cmd)
+
+    # ------------------------------------------------------------------
+    # Subsystem accessors (lazy-initialized)
+    # ------------------------------------------------------------------
+
+    @property
+    def target(self) -> Target:
+        if self._target is None:
+            from openocd.target import Target
+            self._target = Target(self._conn)
+        return self._target
+
+    @property
+    def memory(self) -> Memory:
+        if self._memory is None:
+            from openocd.memory import Memory
+            self._memory = Memory(self._conn)
+        return self._memory
+
+    @property
+    def registers(self) -> Registers:
+        if self._registers is None:
+            from openocd.registers import Registers
+            self._registers = Registers(self._conn)
+        return self._registers
+
+    @property
+    def flash(self) -> Flash:
+        if self._flash is None:
+            from openocd.flash import Flash
+            self._flash = Flash(self._conn)
+        return self._flash
+
+    @property
+    def jtag(self) -> JTAGController:
+        if self._jtag is None:
+            from openocd.jtag import JTAGController
+            self._jtag = JTAGController(self._conn)
+        return self._jtag
+
+    @property
+    def breakpoints(self) -> BreakpointManager:
+        if self._breakpoints is None:
+            from openocd.breakpoints import BreakpointManager
+            self._breakpoints = BreakpointManager(self._conn)
+        return self._breakpoints
+
+    @property
+    def rtt(self) -> RTTManager:
+        if self._rtt is None:
+            from openocd.rtt import RTTManager
+            self._rtt = RTTManager(self._conn)
+        return self._rtt
+
+    @property
+    def svd(self) -> SVDManager:
+        if self._svd is None:
+            from openocd.svd import SVDManager
+            self._svd = SVDManager(self._conn, self.memory)
+        return self._svd
+
+    @property
+    def transport(self) -> Transport:
+        if self._transport is None:
+            from openocd.transport import Transport
+            self._transport = Transport(self._conn)
+        return self._transport
+
+    # ------------------------------------------------------------------
+    # Event shortcuts
+    # ------------------------------------------------------------------
+
+    def on_halt(self, callback: Callable[[str], None]) -> None:
+        """Register a callback for target halt events."""
+        def _filter(msg: str) -> None:
+            if "halted" in msg.lower():
+                callback(msg)
+        self._conn.on_notification(_filter)
+
+    def on_reset(self, callback: Callable[[str], None]) -> None:
+        """Register a callback for target reset events."""
+        def _filter(msg: str) -> None:
+            if "reset" in msg.lower():
+                callback(msg)
+        self._conn.on_notification(_filter)
+
+
+# ======================================================================
+# Sync wrapper
+# ======================================================================
+
+class SyncSession:
+    """Wraps an async Session for synchronous use."""
+
+    def __init__(self, session: Session, loop: asyncio.AbstractEventLoop) -> None:
+        self._session = session
+        self._loop = loop
+        self._target: SyncTarget | None = None
+        self._memory: SyncMemory | None = None
+        self._registers: SyncRegisters | None = None
+        self._flash: SyncFlash | None = None
+        self._jtag: SyncJTAGController | None = None
+        self._breakpoints: SyncBreakpointManager | None = None
+        self._svd: SyncSVDManager | None = None
+
+    def __enter__(self) -> SyncSession:
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self._loop.run_until_complete(self._session.close())
+
+    def command(self, cmd: str) -> str:
+        return self._loop.run_until_complete(self._session.command(cmd))
+
+    @property
+    def target(self) -> SyncTarget:
+        if self._target is None:
+            from openocd.target import SyncTarget
+            self._target = SyncTarget(self._session.target, self._loop)
+        return self._target
+
+    @property
+    def memory(self) -> SyncMemory:
+        if self._memory is None:
+            from openocd.memory import SyncMemory
+            self._memory = SyncMemory(self._session.memory, self._loop)
+        return self._memory
+
+    @property
+    def registers(self) -> SyncRegisters:
+        if self._registers is None:
+            from openocd.registers import SyncRegisters
+            self._registers = SyncRegisters(self._session.registers, self._loop)
+        return self._registers
+
+    @property
+    def flash(self) -> SyncFlash:
+        if self._flash is None:
+            from openocd.flash import SyncFlash
+            self._flash = SyncFlash(self._session.flash, self._loop)
+        return self._flash
+
+    @property
+    def jtag(self) -> SyncJTAGController:
+        if self._jtag is None:
+            from openocd.jtag import SyncJTAGController
+            self._jtag = SyncJTAGController(self._session.jtag, self._loop)
+        return self._jtag
+
+    @property
+    def breakpoints(self) -> SyncBreakpointManager:
+        if self._breakpoints is None:
+            from openocd.breakpoints import SyncBreakpointManager
+            self._breakpoints = SyncBreakpointManager(self._session.breakpoints, self._loop)
+        return self._breakpoints
+
+    @property
+    def svd(self) -> SyncSVDManager:
+        if self._svd is None:
+            from openocd.svd import SyncSVDManager
+            self._svd = SyncSVDManager(self._session.svd, self._loop)
+        return self._svd
+
+
+# ======================================================================
+# Helpers
+# ======================================================================
+
+def _get_or_create_loop() -> asyncio.AbstractEventLoop:
+    """Get or create an event loop for synchronous usage.
+
+    Raises RuntimeError if called from within an already-running async
+    context (where ``run_until_complete`` would deadlock).
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        pass  # No running loop — this is the expected path for sync usage
+    else:
+        raise RuntimeError(
+            "Cannot use sync API from an async context. "
+            "Use the async Session.start()/connect() instead."
+        )
+    try:
+        loop = asyncio.get_event_loop()
+        if loop.is_closed():
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+    except RuntimeError:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+    return loop

openocd/svd/__init__.py

@@ -0,0 +1,5 @@
+"""SVD (System View Description) integration for peripheral/register decoding."""
+
+from openocd.svd.peripheral import SVDManager, SyncSVDManager
+
+__all__ = ["SVDManager", "SyncSVDManager"]

openocd/svd/decoder.py

@@ -0,0 +1,54 @@
+"""Register value decoding using SVD metadata.
+
+Takes a raw integer read from hardware and splits it into named bitfields
+using the field definitions from a parsed SVD file.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from openocd.types import BitField, DecodedRegister
+
+
+def decode_register(
+    peripheral_obj: Any,
+    register_obj: Any,
+    raw_value: int,
+) -> DecodedRegister:
+    """Decode a raw register value into named bitfields using SVD metadata.
+
+    Args:
+        peripheral_obj: cmsis_svd peripheral (used for base_address and name).
+        register_obj: cmsis_svd register (used for fields, address_offset, name).
+        raw_value: The 32-bit value read from hardware.
+
+    Returns:
+        A DecodedRegister with all fields extracted and annotated.
+    """
+    address = peripheral_obj.base_address + register_obj.address_offset
+    fields: list[BitField] = []
+
+    for svd_field in register_obj.fields or []:
+        mask = ((1 << svd_field.bit_width) - 1) << svd_field.bit_offset
+        value = (raw_value & mask) >> svd_field.bit_offset
+        fields.append(
+            BitField(
+                name=svd_field.name,
+                offset=svd_field.bit_offset,
+                width=svd_field.bit_width,
+                value=value,
+                description=svd_field.description or "",
+            )
+        )
+
+    # Sort fields by bit offset (low to high) for consistent display
+    fields.sort(key=lambda f: f.offset)
+
+    return DecodedRegister(
+        peripheral=peripheral_obj.name,
+        register=register_obj.name,
+        address=address,
+        raw_value=raw_value,
+        fields=fields,
+    )