dbxdebug 0.2.1__py3-none-any.whl

dbxdebug/video.py

@@ -0,0 +1,239 @@
+"""
+DOS video memory access utilities.
+
+Provides screen capture and video memory inspection for DOS text mode.
+"""
+
+from loguru import logger
+
+from .gdb import GDBClient
+
+# DOS video memory addresses
+DOS_VIDEO_PAGE_ONE = "0xB800:0000"
+DOS_VIDEO_PAGE_TWO = "0xB800:1000"
+DOS_VIDEO_MEMORY_SIZE = 0xFA0  # 4000 bytes (80 * 25 * 2)
+
+# BIOS Data Area addresses
+BDA_MODE = "0x0040:0049"
+BDA_COLUMN_COUNT = "0x0040:004A"
+BDA_ROW_COUNT = "0x0040:0084"
+BDA_TIMER_TICK = "0x0040:006C"  # 4-byte tick counter, 18.2065 Hz
+
+# Timer constants
+TIMER_FREQUENCY = 18.2065  # Hz
+
+
+class DOSVideoTools:
+    """Tools for analyzing DOS program screen output."""
+
+    def __init__(self, host: str = "localhost", port: int = GDBClient.DEFAULT_PORT):
+        """
+        Initialize video tools with GDB connection.
+
+        Args:
+            host: GDB server hostname
+            port: GDB server port
+        """
+        self.gdb = GDBClient(host, port)
+
+    def close(self) -> None:
+        """Close the GDB connection."""
+        self.gdb.close()
+
+    def __enter__(self) -> "DOSVideoTools":
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.close()
+
+    def read_timer_ticks(self) -> int | None:
+        """
+        Read the BIOS timer tick counter (18.2065 Hz).
+
+        Returns:
+            Tick count or None on error
+        """
+        try:
+            data = self.gdb.read_memory(BDA_TIMER_TICK, 4)
+            return int.from_bytes(data, "little")
+        except Exception as e:
+            logger.exception(e)
+            return None
+
+    def read_video_mode(self) -> int | None:
+        """
+        Read the current video mode.
+
+        Returns:
+            Video mode number or None on error
+        """
+        try:
+            data = self.gdb.read_memory(BDA_MODE, 1)
+            return data[0]
+        except Exception as e:
+            logger.exception(e)
+            return None
+
+    def screen_dump(self, page: int = 1) -> list[str] | None:
+        """
+        Dump the DOS text screen as a list of strings.
+
+        Args:
+            page: Video page number (1 or 2)
+
+        Returns:
+            List of 25 strings (80 chars each) or None on error
+        """
+        try:
+            addr = DOS_VIDEO_PAGE_ONE if page == 1 else DOS_VIDEO_PAGE_TWO
+            memory = self.gdb.read_memory(addr, DOS_VIDEO_MEMORY_SIZE)
+
+            lines = []
+            for row in range(25):
+                line_text = ""
+                for col in range(80):
+                    char_index = (row * 80 + col) * 2
+                    if char_index < len(memory):
+                        char = memory[char_index]
+                        if char == 0:
+                            line_text += " "
+                        elif 32 <= char <= 126:
+                            line_text += chr(char)
+                        else:
+                            line_text += chr(char)
+                    else:
+                        line_text += " "
+                lines.append(line_text)
+            return lines
+        except Exception as e:
+            logger.exception(e)
+            return None
+
+    def screen_dump_with_ticks(self) -> tuple[list[str] | None, int | None]:
+        """
+        Dump screen and timer ticks together for timing correlation.
+
+        Returns:
+            Tuple of (lines, ticks) or (None, None) on error
+        """
+        try:
+            # Read timer first (small read, fast)
+            tick_data = self.gdb.read_memory(BDA_TIMER_TICK, 4)
+            ticks = int.from_bytes(tick_data, "little")
+
+            # Then read screen
+            memory = self.gdb.read_memory(DOS_VIDEO_PAGE_ONE, DOS_VIDEO_MEMORY_SIZE)
+
+            lines = []
+            for row in range(25):
+                line_text = ""
+                for col in range(80):
+                    char_index = (row * 80 + col) * 2
+                    if char_index < len(memory):
+                        char = memory[char_index]
+                        if char == 0 or char == 32:
+                            line_text += " "
+                        elif 32 <= char <= 126:
+                            line_text += chr(char)
+                        else:
+                            line_text += chr(char)
+                    else:
+                        line_text += " "
+                lines.append(line_text)
+            return (lines, ticks)
+        except Exception as e:
+            logger.exception(e)
+            return (None, None)
+
+    def screen_raw(self, page: int = 1) -> bytes | None:
+        """
+        Read raw video memory (characters and attributes).
+
+        Args:
+            page: Video page number (1 or 2)
+
+        Returns:
+            Raw bytes or None on error
+        """
+        try:
+            addr = DOS_VIDEO_PAGE_ONE if page == 1 else DOS_VIDEO_PAGE_TWO
+            return self.gdb.read_memory(addr, DOS_VIDEO_MEMORY_SIZE)
+        except Exception as e:
+            logger.exception(e)
+            return None
+
+    def screen_debug(self) -> list[bytes] | None:
+        """
+        Read raw video memory from both pages.
+
+        Returns:
+            List of [page1_bytes, page2_bytes] or None on error
+        """
+        try:
+            return [
+                self.gdb.read_memory(DOS_VIDEO_PAGE_ONE, DOS_VIDEO_MEMORY_SIZE),
+                self.gdb.read_memory(DOS_VIDEO_PAGE_TWO, DOS_VIDEO_MEMORY_SIZE),
+            ]
+        except Exception as e:
+            logger.exception(e)
+            return None
+
+
+def decode_vga_attribute(attr_byte: int) -> dict:
+    """
+    Decode a VGA text mode attribute byte.
+
+    Attribute format: IRGB irgb
+    - Upper 4 bits: background color (IRGB)
+    - Lower 4 bits: foreground color (irgb)
+    - Bit 7: blink flag
+
+    Args:
+        attr_byte: Attribute byte value
+
+    Returns:
+        Dict with foreground, background, colors, and blink flag
+    """
+    color_names = [
+        "Black",
+        "Blue",
+        "Green",
+        "Cyan",
+        "Red",
+        "Magenta",
+        "Brown",
+        "Light Gray",
+        "Dark Gray",
+        "Light Blue",
+        "Light Green",
+        "Light Cyan",
+        "Light Red",
+        "Light Magenta",
+        "Yellow",
+        "White",
+    ]
+
+    foreground = attr_byte & 0x0F
+    background = (attr_byte & 0x70) >> 4
+    blink = (attr_byte & 0x80) != 0
+
+    return {
+        "foreground": foreground,
+        "background": background,
+        "fg_color": color_names[foreground],
+        "bg_color": color_names[background],
+        "blink": blink,
+        "raw_value": attr_byte,
+    }
+
+
+def format_attribute_info(attr_byte: int) -> str:
+    """Format attribute information as a readable string."""
+    info = decode_vga_attribute(attr_byte)
+
+    result = f"Attribute 0x{attr_byte:02X}:\n"
+    result += f"  Foreground: {info['fg_color']} (0x{info['foreground']:X})\n"
+    result += f"  Background: {info['bg_color']} (0x{info['background']:X})\n"
+    result += f"  Blinking: {'Yes' if info['blink'] else 'No'}\n"
+
+    return result

dbxdebug-0.2.1.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: dbxdebug
+Version: 0.2.1
+Summary: Client library and CLI for DOSBox-X remote debug protocols (GDB and QMP)
+Author: lokkju
+License-Expression: MIT
+Keywords: debugging,dosbox,dosbox-x,emulator,gdb,qmp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Emulators
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0
+Requires-Dist: loguru>=0.7
+Description-Content-Type: text/markdown
+
+# dbxdebug
+
+Client library and CLI for DOSBox-X remote debug protocols.
+
+## Features
+
+- **GDB Client**: Remote debugging via GDB Remote Serial Protocol
+  - Memory read/write
+  - Register inspection
+  - Breakpoint management
+  - Execution control (step, continue, halt)
+
+- **QMP Client**: Keyboard input via QEMU Monitor Protocol
+  - Key press/release with timing control
+  - Text typing with shift handling
+  - Key combinations (Ctrl+C, Alt+F4, etc.)
+
+- **Video Tools**: DOS text mode screen capture
+  - Screen capture (text, raw, HTML)
+  - Timed multi-frame recording
+  - Color analysis
+  - BIOS timer correlation
+
+## Installation
+
+```bash
+uv sync
+```
+
+## CLI Usage
+
+```
+dbxdebug
+├── mem              # Memory operations (alias: gdb)
+│   ├── read         # Read memory
+│   └── write        # Write hex bytes
+│
+├── cpu              # CPU and execution control
+│   ├── regs         # Display registers
+│   ├── break        # Set breakpoint
+│   ├── delete       # Remove breakpoint
+│   ├── step         # Single step
+│   ├── cont         # Continue execution
+│   └── halt         # Stop execution
+│
+├── key              # Keyboard input (alias: qmp)
+│   ├── send         # Key chord (e.g., ctrl c)
+│   ├── type         # Type text string
+│   ├── down         # Press and hold key
+│   ├── up           # Release key
+│   └── list         # List QMP commands
+│
+└── screen           # Screen capture
+    ├── show         # Display text to stdout
+    ├── capture      # Save frame to file (-f raw|html|text)
+    ├── record       # Multi-frame timed capture
+    ├── watch        # Real-time display
+    ├── info         # Video mode, BIOS ticks
+    └── colors       # Analyze color palette
+```
+
+### Examples
+
+```bash
+# Memory
+dbxdebug mem read b800:0000 4000 --hex
+dbxdebug mem write 0x1000 90909090
+
+# CPU / Debugging
+dbxdebug cpu regs
+dbxdebug cpu break 0x1000
+dbxdebug cpu step
+dbxdebug cpu cont
+
+# Keyboard
+dbxdebug key send a
+dbxdebug key send ctrl c
+dbxdebug key send ctrl alt delete
+dbxdebug key type "Hello World!"
+
+# Screen
+dbxdebug screen show
+dbxdebug screen capture -f html -o snapshot
+dbxdebug screen record -d 60 -r 30 -o session.capture.gz
+dbxdebug screen watch
+dbxdebug screen colors
+```
+
+## Library Usage
+
+```python
+from dbxdebug import (
+    GDBClient, QMPClient, DOSVideoTools,
+    ScreenRecorder, load_capture,
+    ctrl_key, CTRL_C, DBX_KEY,
+)
+
+# Memory and debugging
+with GDBClient() as gdb:
+    regs = gdb.read_registers()
+    mem = gdb.read_memory("b800:0000", 4000)
+    gdb.write_memory(0x1000, b"\x90\x90")
+    gdb.set_breakpoint(0x1000)
+    gdb.step()
+    gdb.continue_execution()
+
+# Keyboard input
+with QMPClient() as qmp:
+    qmp.send_key(["ctrl", "c"])       # Key chord
+    qmp.send_key(CTRL_C)              # Using constant
+    qmp.type_text("Hello World!")     # Type string
+    qmp.key_down("shift")             # Hold key
+    qmp.key_up("shift")               # Release key
+
+# Screen capture
+with DOSVideoTools() as video:
+    lines = video.screen_dump()           # Text lines
+    raw = video.screen_raw()              # Raw bytes with attrs
+    lines, ticks = video.screen_dump_with_ticks()
+
+# Timed recording
+with DOSVideoTools() as video:
+    recorder = ScreenRecorder()
+    recorder.record(video, duration=10.0, sample_rate=50)
+    recorder.save("session.capture.gz")
+
+# Load and analyze capture
+data = load_capture("session.capture.gz")
+```
+
+## Ports
+
+| Protocol | Default Port | Purpose |
+|----------|--------------|---------|
+| GDB      | 2159         | Debugging, memory access |
+| QMP      | 4444         | Keyboard input |
+
+Enable in DOSBox-X config:
+```ini
+[dosbox]
+gdbserver=true
+qmpserver=true
+```

dbxdebug-0.2.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+dbxdebug/__init__.py,sha256=9VE7gig7l6WQMdXdYa2_NFrYkBDldAIjw2lRlgESu1M,2650
+dbxdebug/capture_io.py,sha256=fxHHLnXky29_K8r0j2FpeOP4nx9BtmLtjJ8NT4zgkNc,5681
+dbxdebug/cli.py,sha256=kIfWbLntUgHj_xGq19hoerEwU4J-lL1yxZx8fSzX8CM,21269
+dbxdebug/dbx_kbd.py,sha256=nVE9Br9G-FajK0ZX3wrlm-sngtQ2aQilNGTlhsT3smY,9409
+dbxdebug/gdb.py,sha256=RzJM0cekLk6-v6-x0ldLBIoKHLR4iFYnXc_dRMEOQyo,8730
+dbxdebug/html.py,sha256=AQLSsRU5gQ-O7UO0vgqSE7L6D40yZja_jH0Yz9Ce4lQ,15098
+dbxdebug/keyboard.py,sha256=CdS5i7g4PYLCsjtJkopS3mY5DE6zz1d-BmAK5grDOZc,4025
+dbxdebug/qmp.py,sha256=hkNiMyg_VBHX8RH4SKIXY36T4BqLbmvcHlErTI8lUTo,7212
+dbxdebug/utils.py,sha256=bEai_WicXvnGTTaTf0DJtNJ78vI0g-m0KfnuegZ7fXY,2703
+dbxdebug/video.py,sha256=knQdG0hmtLzufjrA_MqWAmh-lMWyKQ4ZWf7uKMMVIC0,6981
+dbxdebug-0.2.1.dist-info/METADATA,sha256=Li4B-9M91UQqPeRl20F4qXxjSoQ3L01McxJ6aZVZ15E,4562
+dbxdebug-0.2.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+dbxdebug-0.2.1.dist-info/entry_points.txt,sha256=lzVCl-Qns7sa1y8IO6Jil3LeQPKupF7vTESe7LeUICg,47
+dbxdebug-0.2.1.dist-info/RECORD,,

dbxdebug-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dbxdebug-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dbxdebug = dbxdebug.cli:main