pyGdbToolkit 0.1.0__py3-none-any.whl

pyGdbToolkit/cmd_faultinfo.py

@@ -0,0 +1,99 @@
+# SPDX-FileCopyrightText: 2026 H2Lab Development Team
+# SPDX-License-Identifier: Apache-2.0
+
+"""The architecture-neutral ``fault_info`` GDB command entry point."""
+
+from __future__ import annotations
+
+import gdb
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from .arch import (
+    DiagnosticPanel,
+    DiagnosticReport,
+    DiagnosticServiceName,
+    DiagnosticTable,
+)
+from .diagnostic_runtime import gdb_diagnostic_access
+from .session import SESSION, ToolkitSession
+from .target_memory import TargetReadError
+
+CONSOLE = Console(force_terminal=True)
+
+
+def run_fault_analysis(
+    session: ToolkitSession = SESSION,
+) -> DiagnosticReport:
+    """Run the registered fault-analysis service against the selected target.
+
+    Parameters
+    ----------
+    session : ToolkitSession
+        Unified session providing target access and the portable diagnostic runtime.
+
+    Returns
+    -------
+    DiagnosticReport
+        Renderer-independent diagnostic report returned by the selected service.
+
+    Raises
+    ------
+    gdb.GdbError
+        If target access fails or no service supports the selected target.
+    """
+    try:
+        result = session.diagnose(
+            DiagnosticServiceName.FAULT_ANALYSIS,
+            gdb_diagnostic_access(),
+        )
+    except TargetReadError as error:
+        raise gdb.GdbError(str(error)) from error
+    if result.report is not None:
+        return result.report
+    if result.access_error:
+        raise gdb.GdbError(result.unavailable_reason or "target unavailable")
+    raise gdb.GdbError("fault_info only supports ARM Cortex-M targets")
+
+
+def render_report(report: DiagnosticReport) -> None:
+    """Render a generic diagnostic report through the shared Rich console."""
+    blocks = report.blocks or (*report.tables, *report.panels)
+    for block in blocks:
+        if isinstance(block, DiagnosticTable):
+            table = Table(
+                title=block.title,
+                box=box.SIMPLE_HEAVY,
+                header_style="bold cyan",
+                show_header=True,
+            )
+            for column in block.columns:
+                table.add_column(column, style="bold" if column in {"Property", "Register"} else "")
+            for row in block.rows:
+                table.add_row(*("" if value is None else str(value) for value in row.values))
+            CONSOLE.print(table)
+        elif isinstance(block, DiagnosticPanel):
+            CONSOLE.print(
+                Panel(
+                    "\n".join(block.lines),
+                    title=f"[bold yellow]{block.title}[/bold yellow]",
+                    box=box.SIMPLE_HEAVY,
+                )
+            )
+
+
+class FaultInfoCmd(gdb.Command):
+    """Run portable fault analysis and render the returned diagnostic report."""
+
+    def __init__(self) -> None:
+        """Register the command with GDB."""
+        super().__init__("fault_info", gdb.COMMAND_USER)
+
+    def invoke(self, arg: str, from_tty: bool) -> None:
+        """Execute ``fault_info`` without command-line arguments."""
+        del from_tty
+        if arg.strip():
+            raise gdb.GdbError("fault_info does not accept arguments")
+        render_report(run_fault_analysis())

pyGdbToolkit/cmd_lscpu.py

@@ -0,0 +1,116 @@
+# SPDX-FileCopyrightText: 2026 H2Lab Development Team
+# SPDX-License-Identifier: Apache-2.0
+
+"""The ``lscpu`` GDB command for Cortex-M targets."""
+
+from __future__ import annotations
+
+import gdb
+from rich import box
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from .arch.arm.coresight import RomTableDiscovery
+from .arch.arm.models import DeviceReport, FieldValue
+from .arch.arm.session_state import device_report
+from .target_memory import TargetReadError
+
+CONSOLE = Console(force_terminal=True)
+
+
+class LscpuCmd(gdb.Command):
+    """Display CPU and electronic-signature information for a Cortex-M target."""
+
+    def __init__(self) -> None:
+        """Register the command with GDB."""
+        super().__init__("lscpu", gdb.COMMAND_USER)
+
+    def invoke(self, arg: str, from_tty: bool) -> None:
+        """Run the command.
+
+        Parameters
+        ----------
+        arg
+            The user-supplied argument string. This command accepts no arguments.
+        from_tty
+            Whether GDB invoked the command from its terminal.
+
+        Raises
+        ------
+        gdb.GdbError
+            If arguments are supplied or the target CPUID cannot be read.
+        """
+        del from_tty
+        if arg.strip():
+            raise gdb.GdbError("lscpu does not accept arguments")
+
+        try:
+            report = device_report()
+        except TargetReadError as error:
+            raise gdb.GdbError(str(error)) from error
+
+        render_report(report)
+
+
+def render_report(report: DeviceReport) -> None:
+    """Render a stable device report through the shared Rich console.
+
+    Parameters
+    ----------
+    report
+        Decoded CPU and device information.
+    """
+    table = Table(
+        title="Cortex-M CPU report",
+        box=box.SIMPLE_HEAVY,
+        header_style="bold cyan",
+        show_header=True,
+    )
+    table.add_column("Property", style="bold", no_wrap=True)
+    table.add_column("Value")
+    table.add_row("Core type", report.target.core_name)
+    table.add_row("Core revision", report.target.rnp_revision)
+    table.add_row("Implementer", report.target.implementer_name)
+    table.add_row(
+        "MCU ROM JEP106 identity",
+        _field_text(_rom_jep106_field(report.discovery.mcu_rom)),
+    )
+    table.add_row("Vendor", report.vendor)
+    table.add_row("Product line", _field_text(report.product_line))
+    table.add_row("Part number", _field_text(report.part_number))
+    table.add_row("RAM", _field_text(report.ram))
+    table.add_row("Flash", _field_text(report.flash))
+    table.add_row("Package type", _field_text(report.package))
+    table.add_row("Serial number", _field_text(report.serial_number))
+    CONSOLE.print(table)
+
+
+def _field_text(field: FieldValue) -> Text:
+    """Create a Rich value cell with a visible unavailable-state reason.
+
+    Parameters
+    ----------
+    field
+        A ``FieldValue`` supplied by the report model.
+
+    Returns
+    -------
+    Text
+        The formatted field cell.
+    """
+    display = field.display()
+    if field.is_available:
+        return Text(display)
+    return Text.assemble(("Unavailable: ", "yellow"), display.removeprefix("Unavailable: "))
+
+
+def _rom_jep106_field(discovery: RomTableDiscovery) -> FieldValue:
+    """Format a table root's validated JEP106 identity when it is available."""
+    if discovery.table is None:
+        assert discovery.unavailable_reason is not None
+        return FieldValue.unavailable(discovery.unavailable_reason)
+    identity = discovery.table.identity.peripheral_id.jep106
+    if identity is None:
+        return FieldValue.unavailable("ROM-table root does not advertise a JEDEC manufacturer")
+    return FieldValue.known(identity.display())