pyGdbToolkit 0.1.0__py3-none-any.whl

pyGdbToolkit/arch/arm/session_state.py

@@ -0,0 +1,96 @@
+# SPDX-FileCopyrightText: 2026 H2Lab Development Team
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Session-cached Arm target inspection shared by the Arm-aware GDB commands.
+
+This module is not exported by :mod:`pyGdbToolkit.arch.arm` on purpose: it binds
+the Arm inspection results to the unified session, whereas the ``arch`` package
+stays independent from any session or GDB concern.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ...session import SESSION, SessionSlice, ToolkitSession
+from .coresight import CoreSightDiscovery, discover_rom_tables
+from .cortex_m import CPUID_ADDRESS, CortexMTargetDescription, decode_cpuid
+from .models import DeviceReport
+from .providers import DEFAULT_PROVIDER_REGISTRY
+
+
+@dataclass
+class ArmInspectionState(SessionSlice):
+    """Cache the Arm identity, the ROM-table discovery, and the vendor device report."""
+
+    target: CortexMTargetDescription | None = None
+    discovery: CoreSightDiscovery | None = None
+    report: DeviceReport | None = None
+
+    def reset(self) -> None:
+        """Drop every cached Arm inspection result."""
+        self.target = None
+        self.discovery = None
+        self.report = None
+
+
+def cortex_m_target(session: ToolkitSession = SESSION) -> CortexMTargetDescription:
+    """Return the decoded Cortex-M CPUID identity of the session target.
+
+    Parameters
+    ----------
+    session : ToolkitSession
+        Session owning the target access and the cached inspection results.
+
+    Returns
+    -------
+    CortexMTargetDescription
+        The decoded CPUID identity.
+    """
+    state = session.state(ArmInspectionState)
+    if state.target is None:
+        state.target = decode_cpuid(session.memory.read_uint32(CPUID_ADDRESS))
+    return state.target
+
+
+def rom_table_discovery(session: ToolkitSession = SESSION) -> CoreSightDiscovery:
+    """Return the CoreSight ROM-table discovery of the session target.
+
+    Parameters
+    ----------
+    session : ToolkitSession
+        Session owning the target access and the cached inspection results.
+
+    Returns
+    -------
+    CoreSightDiscovery
+        The MCU and processor ROM-table discovery results.
+    """
+    state = session.state(ArmInspectionState)
+    if state.discovery is None:
+        state.discovery = discover_rom_tables(session.memory)
+    return state.discovery
+
+
+def device_report(session: ToolkitSession = SESSION) -> DeviceReport:
+    """Return the manufacturer device report of the session target.
+
+    Parameters
+    ----------
+    session : ToolkitSession
+        Session owning the target access and the cached inspection results.
+
+    Returns
+    -------
+    DeviceReport
+        The report of the first provider recognizing the target, or a generic one.
+    """
+    state = session.state(ArmInspectionState)
+    if state.report is None:
+        state.report = DEFAULT_PROVIDER_REGISTRY.inspect(
+            session.memory,
+            cortex_m_target(session),
+            rom_table_discovery(session),
+        )
+    return state.report

pyGdbToolkit/arch/arm/target.py

@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: 2026 H2Lab Development Team
+# SPDX-License-Identifier: Apache-2.0
+
+"""Shared Arm target-description types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum, unique
+
+from ..base import Architecture, TargetDescription
+
+
+@unique
+class ArmProfile(StrEnum):
+    """Architectural execution profiles implemented by Arm cores."""
+
+    CORTEX_M = "cortex-m"
+    CORTEX_A = "cortex-a"
+    CORTEX_R = "cortex-r"
+
+
+@dataclass(frozen=True)
+class ArmTargetDescription(TargetDescription):
+    """Target identity common to all Arm architecture profiles."""
+
+    profile: ArmProfile
+
+    def __post_init__(self) -> None:
+        """Require Arm target descriptions to retain the Arm architecture tag."""
+        if self.architecture is not Architecture.ARM:
+            raise ValueError("an Arm target description must use the Arm architecture")

pyGdbToolkit/arch/base.py

@@ -0,0 +1,143 @@
+# SPDX-FileCopyrightText: 2026 H2Lab Development Team
+# SPDX-License-Identifier: Apache-2.0
+
+"""Portable architecture target-description and register-reading contracts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum, unique
+from typing import Protocol
+
+from ..target_memory import TargetMemory
+
+
+@unique
+class Architecture(StrEnum):
+    """Architectures supported by the target-description registry."""
+
+    ARM = "arm"
+    RISCV = "riscv"
+    XTENSA = "xtensa"
+
+
+@dataclass(frozen=True)
+class TargetDescription:
+    """Architecture-neutral identity for an inspected target."""
+
+    architecture: Architecture
+    family: str
+    core_name: str
+    revision: str
+
+
+@dataclass(frozen=True)
+class RegisterValue:
+    """A system-register value or the explicit reason it could not be read."""
+
+    name: str
+    address: int
+    width_bits: int
+    value: int | None = None
+    unavailable_reason: str | None = None
+
+    def __post_init__(self) -> None:
+        """Validate that a register result has exactly one value state."""
+        if (self.value is None) == (self.unavailable_reason is None):
+            raise ValueError("a register value must be available or unavailable")
+        if self.address < 0:
+            raise ValueError("a register address must not be negative")
+        if self.width_bits <= 0:
+            raise ValueError("a register width must be positive")
+
+    @classmethod
+    def known(cls, name: str, address: int, width_bits: int, value: int) -> RegisterValue:
+        """Create an available register value."""
+        return cls(name=name, address=address, width_bits=width_bits, value=value)
+
+    @classmethod
+    def unavailable(
+        cls,
+        name: str,
+        address: int,
+        width_bits: int,
+        reason: str,
+    ) -> RegisterValue:
+        """Create an unavailable register result."""
+        return cls(
+            name=name,
+            address=address,
+            width_bits=width_bits,
+            unavailable_reason=reason,
+        )
+
+    @property
+    def is_available(self) -> bool:
+        """Whether the target supplied a register value."""
+        return self.value is not None
+
+
+@dataclass(frozen=True)
+class SystemRegisterSet:
+    """One architecture-specific system-register block read through a common API."""
+
+    architecture: Architecture
+    block_name: str
+    registers: tuple[RegisterValue, ...]
+
+    def get(self, name: str) -> RegisterValue | None:
+        """Find a register by case-insensitive name."""
+        normalized_name = name.upper()
+        for register in self.registers:
+            if register.name.upper() == normalized_name:
+                return register
+        return None
+
+
+@dataclass(frozen=True)
+class ProbeResult:
+    """A probe result containing a target description or explicit unavailability."""
+
+    target: TargetDescription | None = None
+    unavailable_reason: str | None = None
+    access_error: bool = False
+
+    def __post_init__(self) -> None:
+        """Validate that a probe result has exactly one state."""
+        if (self.target is None) == (self.unavailable_reason is None):
+            raise ValueError("a probe result must contain a target or an unavailable reason")
+        if self.target is not None and self.access_error:
+            raise ValueError("a successful probe result cannot contain an access error")
+
+    @classmethod
+    def detected(cls, target: TargetDescription) -> ProbeResult:
+        """Create a successful probe result."""
+        return cls(target=target)
+
+    @classmethod
+    def unavailable(cls, reason: str, *, access_error: bool = False) -> ProbeResult:
+        """Create an unsuccessful probe result."""
+        return cls(unavailable_reason=reason, access_error=access_error)
+
+    @property
+    def is_available(self) -> bool:
+        """Whether an architecture probe identified a target."""
+        return self.target is not None
+
+
+class ArchitectureProbe(Protocol):
+    """An architecture implementation that can identify and inspect a target."""
+
+    architecture: Architecture
+
+    def probe(self, reader: TargetMemory) -> ProbeResult:
+        """Identify a target or return an explicit unsupported result."""
+        ...
+
+    def read_system_registers(
+        self,
+        reader: TargetMemory,
+        target: TargetDescription,
+    ) -> SystemRegisterSet:
+        """Read the architecture-specific system-register block for a target."""
+        ...

pyGdbToolkit/arch/diagnostics.py

@@ -0,0 +1,300 @@
+# SPDX-FileCopyrightText: 2026 H2Lab Development Team
+# SPDX-License-Identifier: Apache-2.0
+
+"""Portable diagnostic-service contracts, reports, and runtime dispatch."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum, auto, unique
+from typing import Protocol, TypeAlias
+
+from ..target_memory import TargetMemory
+from .base import Architecture, TargetDescription
+from .registry import ArchitectureRegistry
+
+DiagnosticValue: TypeAlias = bool | int | str | None
+
+
+@unique
+class DiagnosticServiceName(StrEnum):
+    """Architecture-neutral diagnostics offered by command entry points."""
+
+    SECURITY_AUDIT = "security-audit"
+    FAULT_ANALYSIS = "fault-analysis"
+
+
+@unique
+class DiagnosticSeverity(StrEnum):
+    """Common severity levels used by diagnostic findings."""
+
+    PASS = auto()
+    INFO = auto()
+    WARNING = auto()
+    ERROR = auto()
+    CRITICAL = auto()
+
+
+@dataclass(frozen=True)
+class DiagnosticField:
+    """One named, scalar diagnostic value suitable for a renderer."""
+
+    name: str
+    value: DiagnosticValue
+
+
+@dataclass(frozen=True)
+class DiagnosticTableRow:
+    """One renderer-independent row in a diagnostic table."""
+
+    values: tuple[DiagnosticValue, ...]
+
+
+@dataclass(frozen=True)
+class DiagnosticTable:
+    """One renderer-independent table in a diagnostic report."""
+
+    title: str
+    columns: tuple[str, ...]
+    rows: tuple[DiagnosticTableRow, ...]
+
+    def __post_init__(self) -> None:
+        """Ensure every row matches the declared table column count."""
+        if not self.columns:
+            raise ValueError("a diagnostic table must have at least one column")
+        if any(len(row.values) != len(self.columns) for row in self.rows):
+            raise ValueError("diagnostic table rows must match the column count")
+
+
+@dataclass(frozen=True)
+class DiagnosticPanel:
+    """One renderer-independent, ordered group of diagnostic lines."""
+
+    title: str
+    lines: tuple[str, ...]
+
+
+DiagnosticContent: TypeAlias = DiagnosticTable | DiagnosticPanel
+
+
+@dataclass(frozen=True)
+class DiagnosticFinding:
+    """One portable diagnostic observation."""
+
+    category: str
+    severity: DiagnosticSeverity
+    title: str
+    detail: str
+
+
+@dataclass(frozen=True)
+class DiagnosticSection:
+    """One renderer-independent grouping of diagnostic values."""
+
+    title: str
+    fields: tuple[DiagnosticField, ...]
+
+
+@dataclass(frozen=True)
+class DiagnosticReport:
+    """A complete architecture-specific diagnostic report."""
+
+    service: DiagnosticServiceName
+    target: TargetDescription
+    sections: tuple[DiagnosticSection, ...] = ()
+    findings: tuple[DiagnosticFinding, ...] = ()
+    tables: tuple[DiagnosticTable, ...] = ()
+    panels: tuple[DiagnosticPanel, ...] = ()
+    blocks: tuple[DiagnosticContent, ...] = ()
+
+
+@dataclass(frozen=True)
+class DiagnosticResult:
+    """A completed report or a reason the requested diagnostic is unavailable."""
+
+    report: DiagnosticReport | None = None
+    target: TargetDescription | None = None
+    unavailable_reason: str | None = None
+    access_error: bool = False
+
+    def __post_init__(self) -> None:
+        """Require exactly one completed or unavailable result state."""
+        if (self.report is None) == (self.unavailable_reason is None):
+            raise ValueError("a diagnostic result must contain a report or an unavailable reason")
+        if self.report is not None and self.target != self.report.target:
+            raise ValueError("a completed diagnostic result must retain its report target")
+        if self.report is not None and self.access_error:
+            raise ValueError("a completed diagnostic result cannot contain an access error")
+
+    @classmethod
+    def completed(cls, report: DiagnosticReport) -> DiagnosticResult:
+        """Create a completed diagnostic result."""
+        return cls(report=report, target=report.target)
+
+    @classmethod
+    def unavailable(
+        cls,
+        reason: str,
+        target: TargetDescription | None = None,
+        *,
+        access_error: bool = False,
+    ) -> DiagnosticResult:
+        """Create an explicitly unavailable diagnostic result."""
+        return cls(target=target, unavailable_reason=reason, access_error=access_error)
+
+    @property
+    def is_available(self) -> bool:
+        """Whether the requested diagnostic completed."""
+        return self.report is not None
+
+
+class DiagnosticService(Protocol):
+    """An architecture-specific collector behind a portable diagnostic service."""
+
+    architecture: Architecture
+    service: DiagnosticServiceName
+
+    def supports(self, target: TargetDescription) -> bool:
+        """Return whether the service can collect this target description."""
+        ...
+
+    def collect(
+        self,
+        reader: TargetMemory,
+        target: TargetDescription,
+        access: DiagnosticRuntimeAccess | None = None,
+    ) -> DiagnosticReport:
+        """Collect one report for a compatible target."""
+        ...
+
+
+class DiagnosticRegisterReader(Protocol):
+    """Read a runtime register from any of a service-provided set of names."""
+
+    def read_first(self, names: tuple[str, ...]) -> int | None:
+        """Return the first available named register, or ``None``."""
+        ...
+
+
+class DiagnosticSymbolResolver(Protocol):
+    """Resolve a runtime address for architecture-neutral report renderers."""
+
+    def resolve(self, address: int) -> str:
+        """Return a symbol description or ``"?"`` when no symbol is available."""
+        ...
+
+
+@dataclass(frozen=True)
+class DiagnosticRuntimeAccess:
+    """Optional neutral runtime facilities needed by a diagnostic collector."""
+
+    registers: DiagnosticRegisterReader | None = None
+    symbols: DiagnosticSymbolResolver | None = None
+
+
+class DiagnosticRuntime(Protocol):
+    """Portable runtime entry point used by architecture-neutral commands."""
+
+    def diagnose(
+        self,
+        reader: TargetMemory,
+        service: DiagnosticServiceName,
+        access: DiagnosticRuntimeAccess | None = None,
+    ) -> DiagnosticResult:
+        """Identify the target and run one requested diagnostic service."""
+        ...
+
+
+class DiagnosticServiceRegistry:
+    """Resolve diagnostic collectors by requested service and target architecture."""
+
+    def __init__(self, services: tuple[DiagnosticService, ...] = ()) -> None:
+        """Create a registry and register its initial service implementations."""
+        self._services: dict[tuple[Architecture, DiagnosticServiceName], DiagnosticService] = {}
+        for service in services:
+            self.register(service)
+
+    def register(self, service: DiagnosticService) -> None:
+        """Register one service implementation.
+
+        Raises
+        ------
+        ValueError
+            If a service is already registered for the same architecture and name.
+        """
+        key = (service.architecture, service.service)
+        if key in self._services:
+            raise ValueError(
+                f"diagnostic service '{service.service}' is already registered "
+                f"for architecture '{service.architecture}'"
+            )
+        self._services[key] = service
+
+    def resolve(
+        self,
+        service: DiagnosticServiceName,
+        target: TargetDescription,
+    ) -> DiagnosticService | None:
+        """Return the registered service implementation compatible with a target."""
+        implementation = self._services.get((target.architecture, service))
+        if implementation is None or not implementation.supports(target):
+            return None
+        return implementation
+
+    def dispatch(
+        self,
+        reader: TargetMemory,
+        service: DiagnosticServiceName,
+        target: TargetDescription,
+        access: DiagnosticRuntimeAccess | None = None,
+    ) -> DiagnosticResult:
+        """Run a compatible service or return an explicit unsupported result."""
+        implementation = self._services.get((target.architecture, service))
+        if implementation is None:
+            return DiagnosticResult.unavailable(
+                (
+                    f"diagnostic service '{service}' is not registered "
+                    f"for architecture '{target.architecture}'"
+                ),
+                target,
+            )
+        if not implementation.supports(target):
+            return DiagnosticResult.unavailable(
+                f"diagnostic service '{service}' does not support target '{target.core_name}'",
+                target,
+            )
+
+        report = implementation.collect(reader, target, access)
+        if report.service is not service:
+            raise ValueError("diagnostic service returned a report for a different service")
+        if report.target != target:
+            raise ValueError("diagnostic service returned a report for a different target")
+        return DiagnosticResult.completed(report)
+
+
+class ArchitectureDiagnosticRuntime:
+    """Adapt architecture probing and service dispatch to the diagnostic runtime protocol."""
+
+    def __init__(
+        self,
+        architecture_registry: ArchitectureRegistry,
+        service_registry: DiagnosticServiceRegistry,
+    ) -> None:
+        """Create a runtime using the supplied architecture and service registries."""
+        self._architecture_registry = architecture_registry
+        self._service_registry = service_registry
+
+    def diagnose(
+        self,
+        reader: TargetMemory,
+        service: DiagnosticServiceName,
+        access: DiagnosticRuntimeAccess | None = None,
+    ) -> DiagnosticResult:
+        """Identify the target, then dispatch its implementation of a diagnostic."""
+        probe_result = self._architecture_registry.probe(reader)
+        if probe_result.target is None:
+            return DiagnosticResult.unavailable(
+                probe_result.unavailable_reason or "target unavailable",
+                access_error=probe_result.access_error,
+            )
+        return self._service_registry.dispatch(reader, service, probe_result.target, access)

pyGdbToolkit/arch/registry.py

@@ -0,0 +1,43 @@
+# SPDX-FileCopyrightText: 2026 H2Lab Development Team
+# SPDX-License-Identifier: Apache-2.0
+
+"""Architecture probe registry."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from ..target_memory import TargetMemory
+from .base import ArchitectureProbe, ProbeResult
+
+
+class ArchitectureRegistry:
+    """Run registered architecture probes in their declared priority order."""
+
+    def __init__(self, probes: Sequence[ArchitectureProbe]) -> None:
+        """Create a registry from an immutable probe sequence."""
+        self._probes = tuple(probes)
+
+    def probe(self, reader: TargetMemory) -> ProbeResult:
+        """Return the first successful architecture probe result.
+
+        Parameters
+        ----------
+        reader
+            Target-memory reader used by each architecture probe.
+
+        Returns
+        -------
+        ProbeResult
+            The first detected target or an explicit unsupported result.
+        """
+        access_error: ProbeResult | None = None
+        for probe in self._probes:
+            result = probe.probe(reader)
+            if result.is_available:
+                return result
+            if result.access_error and access_error is None:
+                access_error = result
+        if access_error is not None:
+            return access_error
+        return ProbeResult.unavailable("no registered architecture probe recognized the target")