Types

All types in openocd-python are frozen dataclasses — they are immutable after construction. Nothing mutable leaves the API surface. Import them from the top-level package:

from openocd import (
    TargetState, Register, FlashSector, FlashBank,
    TAPInfo, JTAGState, MemoryRegion, BitField,
    DecodedRegister, Breakpoint, Watchpoint, RTTChannel,
)

Target types

TargetState

Snapshot of target execution state, returned by target.halt(), target.step(), target.state(), and target.wait_halt().

@dataclass(frozen=True)
class TargetState:
    name: str
    state: Literal["running", "halted", "reset", "debug-running", "unknown"]
    current_pc: int | None = None

Field	Type	Default	Description
name	str	(required)	Target name (e.g. stm32f1x.cpu)
state	Literal[...]	(required)	One of "running", "halted", "reset", "debug-running", "unknown"
current_pc	int | None	None	Program counter (populated only when halted)

Register types

Register

A single CPU register, returned by registers.read_all().

@dataclass(frozen=True)
class Register:
    name: str
    number: int
    value: int
    size: int
    dirty: bool = False

Field	Type	Default	Description
name	str	(required)	Register name (e.g. r0, pc, xPSR)
number	int	(required)	Register number in OpenOCD’s numbering
value	int	(required)	Current register value
size	int	(required)	Register width in bits (typically 32)
dirty	bool	False	Whether the register has been modified but not committed

Flash types

FlashSector

One sector inside a flash bank.

@dataclass(frozen=True)
class FlashSector:
    index: int
    offset: int
    size: int
    protected: bool

Field	Type	Description
index	int	Sector number within the bank
offset	int	Byte offset from the bank base address
size	int	Sector size in bytes
protected	bool	True if write protection is enabled

FlashBank

A flash bank reported by OpenOCD, returned by flash.banks() and flash.info().

@dataclass(frozen=True)
class FlashBank:
    index: int
    name: str
    base: int
    size: int
    bus_width: int
    chip_width: int
    target: str
    sectors: list[FlashSector] = field(default_factory=list)

Field	Type	Default	Description
index	int	(required)	Bank number
name	str	(required)	Bank name (e.g. stm32f1x.flash)
base	int	(required)	Base address in memory
size	int	(required)	Total bank size in bytes
bus_width	int	(required)	Bus width
chip_width	int	(required)	Chip width
target	str	(required)	Associated target or driver name
sectors	list[FlashSector]	[]	Sector list (populated only by flash.info())

JTAG types

TAPInfo

One TAP discovered on the JTAG chain, returned by jtag.scan_chain().

@dataclass(frozen=True)
class TAPInfo:
    name: str
    chip: str
    tap_name: str
    idcode: int
    ir_length: int
    enabled: bool

Field	Type	Description
name	str	Full dotted name (e.g. stm32f1x.cpu)
chip	str	Chip portion of the name (e.g. stm32f1x)
tap_name	str	TAP portion of the name (e.g. cpu)
idcode	int	Detected IDCODE value
ir_length	int	Instruction register length in bits
enabled	bool	Whether the TAP is enabled in the scan chain

JTAGState

Enum of all 16 IEEE 1149.1 TAP controller states. Used with jtag.pathmove().

class JTAGState(str, Enum):
    RESET = "RESET"
    IDLE = "IDLE"
    DRSELECT = "DRSELECT"
    DRCAPTURE = "DRCAPTURE"
    DRSHIFT = "DRSHIFT"
    DREXIT1 = "DREXIT1"
    DRPAUSE = "DRPAUSE"
    DREXIT2 = "DREXIT2"
    DRUPDATE = "DRUPDATE"
    IRSELECT = "IRSELECT"
    IRCAPTURE = "IRCAPTURE"
    IRSHIFT = "IRSHIFT"
    IREXIT1 = "IREXIT1"
    IRPAUSE = "IRPAUSE"
    IREXIT2 = "IREXIT2"
    IRUPDATE = "IRUPDATE"

JTAGState is a str enum, so each member’s .value is its name as a string.

Memory types

MemoryRegion

A chunk of memory read from the target.

@dataclass(frozen=True)
class MemoryRegion:
    address: int
    size: int
    data: bytes

Field	Type	Description
address	int	Start address of the region
size	int	Size of the region in bytes
data	bytes	Raw memory contents

SVD types

BitField

One decoded bitfield inside a register, part of DecodedRegister.fields.

@dataclass(frozen=True)
class BitField:
    name: str
    offset: int
    width: int
    value: int
    description: str

Field	Type	Description
name	str	Field name from the SVD (e.g. ODR0)
offset	int	Bit offset within the register
width	int	Field width in bits
value	int	Extracted field value
description	str	Description from SVD metadata

DecodedRegister

A register value decoded into named bitfields via SVD, returned by svd.read_register() and svd.decode().

@dataclass(frozen=True)
class DecodedRegister:
    peripheral: str
    register: str
    address: int
    raw_value: int
    fields: list[BitField] = field(default_factory=list)

Field	Type	Default	Description
peripheral	str	(required)	Peripheral name (e.g. GPIOA)
register	str	(required)	Register name (e.g. ODR)
address	int	(required)	Memory-mapped address
raw_value	int	(required)	Raw 32-bit value
fields	list[BitField]	[]	Decoded bitfields, sorted by bit offset

DecodedRegister implements __str__ for formatted output:

GPIOA.ODR @ 0x4001080C = 0x00000001
  [  0:0] ODR0                 = 0x1  Port output data bit 0
  [  1:1] ODR1                 = 0x0  Port output data bit 1

Multi-bit fields show the range (e.g. [7:4]), single-bit fields show just the offset (e.g. [0] displayed as [ 0:0]).

Breakpoint types

Breakpoint

An active breakpoint, returned by breakpoints.list().

@dataclass(frozen=True)
class Breakpoint:
    number: int
    type: Literal["hw", "sw"]
    address: int
    length: int
    enabled: bool

Field	Type	Description
number	int	Breakpoint index
type	Literal["hw", "sw"]	Hardware or software breakpoint
address	int	Instruction address
length	int	Instruction length in bytes (2 = Thumb, 4 = ARM)
enabled	bool	Whether the breakpoint is active

Watchpoint

An active data watchpoint, returned by breakpoints.list_watchpoints().

@dataclass(frozen=True)
class Watchpoint:
    number: int
    address: int
    length: int
    access: Literal["r", "w", "rw"]

Field	Type	Description
number	int	Watchpoint index
address	int	Watched memory address
length	int	Size of watched region in bytes
access	Literal["r", "w", "rw"]	Access type: read, write, or both

RTT types

RTTChannel

An RTT channel descriptor, returned by rtt.channels().

@dataclass(frozen=True)
class RTTChannel:
    index: int
    name: str
    size: int
    direction: Literal["up", "down"]

Field	Type	Description
index	int	Channel number
name	str	Channel name (e.g. Terminal)
size	int	Buffer size in bytes
direction	Literal["up", "down"]	up = target-to-host, down = host-to-target