pyGdbToolkit 0.1.0__py3-none-any.whl

pyGdbToolkit/cmd_profile.py

@@ -0,0 +1,1402 @@
+# SPDX-FileCopyrightText: 2026 H2Lab Development Team
+# SPDX-License-Identifier: Apache-2.0
+
+"""The ``profile`` GDB command for firmware peripheral usage analysis."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import glob
+import json
+import os
+from pathlib import Path
+import time
+from typing import Any
+
+import gdb
+from rich import box
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from .arch.arm.session_state import device_report
+from .cmd_svd import SESSION as SVD_SESSION
+from .cmd_svd import is_svd_loaded
+from .session import SESSION as TOOLKIT_SESSION
+from .session import SessionSlice
+from .svd import (
+    SvdDevice,
+    SvdError,
+    SvdPeripheral,
+    SvdRegister,
+    parse_svd_file,
+    resolve_and_fetch_svd,
+)
+from .target_memory import TargetMemory, TargetReadError
+
+CONSOLE = Console(force_terminal=True)
+
+
+@dataclass(frozen=True)
+class RegisterUsage:
+    """Detailed hit statistics for a specific peripheral register."""
+
+    name: str
+    address_offset: int
+    address: int
+    hit_count: int
+    hit_addresses: tuple[int, ...]
+    reference_types: tuple[str, ...]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the register usage model to a plain dictionary.
+
+        Returns
+        -------
+        dict[str, Any]
+            Dictionary representation of register usage metrics.
+        """
+        return {
+            "name": self.name,
+            "address_offset": f"0x{self.address_offset:04X}",
+            "address": f"0x{self.address:08X}",
+            "hit_count": self.hit_count,
+            "hit_addresses": [f"0x{addr:08X}" for addr in self.hit_addresses],
+            "reference_types": list(self.reference_types),
+        }
+
+
+@dataclass(frozen=True)
+class PeripheralUsage:
+    """Detailed hit statistics for a peripheral."""
+
+    name: str
+    base_address: int
+    group_name: str | None
+    description: str
+    hit_count: int
+    total_registers: int
+    used_registers_count: int
+    registers: tuple[RegisterUsage, ...]
+    unnamed_offset_hits: int = 0
+
+    @property
+    def is_active(self) -> bool:
+        """Return whether the peripheral has at least one recorded hit.
+
+        Returns
+        -------
+        bool
+            True if peripheral was referenced, False otherwise.
+        """
+        return self.hit_count > 0
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the peripheral usage model to a plain dictionary.
+
+        Returns
+        -------
+        dict[str, Any]
+            Dictionary representation of peripheral usage metrics.
+        """
+        return {
+            "name": self.name,
+            "base_address": f"0x{self.base_address:08X}",
+            "group_name": self.group_name,
+            "description": self.description,
+            "hit_count": self.hit_count,
+            "total_registers": self.total_registers,
+            "used_registers_count": self.used_registers_count,
+            "registers": {r.name: r.to_dict() for r in self.registers},
+            "unnamed_offset_hits": self.unnamed_offset_hits,
+        }
+
+
+@dataclass(frozen=True)
+class ProfileReport:
+    """Comprehensive profiling report generated by scanning target memory."""
+
+    device_name: str
+    vendor: str | None
+    region_name: str
+    start_address: int
+    scanned_bytes: int
+    total_words_scanned: int
+    elapsed_seconds: float
+    total_peripherals: int
+    active_peripherals_count: int
+    peripherals: tuple[PeripheralUsage, ...]
+
+    @property
+    def inactive_peripherals_count(self) -> int:
+        """Return the number of inactive peripherals.
+
+        Returns
+        -------
+        int
+            Inactive peripheral count.
+        """
+        return self.total_peripherals - self.active_peripherals_count
+
+    @property
+    def active_ratio_pct(self) -> float:
+        """Return the percentage of active peripherals.
+
+        Returns
+        -------
+        float
+            Percentage of active peripherals.
+        """
+        if self.total_peripherals == 0:
+            return 0.0
+        return (self.active_peripherals_count / self.total_peripherals) * 100.0
+
+    @property
+    def active_peripherals(self) -> list[PeripheralUsage]:
+        """Return all active peripherals ordered by hit count descending.
+
+        Returns
+        -------
+        list[PeripheralUsage]
+            List of active peripheral usage objects.
+        """
+        return [p for p in self.peripherals if p.is_active]
+
+    @property
+    def inactive_peripherals(self) -> list[PeripheralUsage]:
+        """Return all inactive peripherals ordered by name.
+
+        Returns
+        -------
+        list[PeripheralUsage]
+            List of inactive peripheral usage objects.
+        """
+        return [p for p in self.peripherals if not p.is_active]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the complete profile report to a nested dictionary.
+
+        Returns
+        -------
+        dict[str, Any]
+            Dictionary representation of the profile report.
+        """
+        return {
+            "device": self.device_name,
+            "vendor": self.vendor,
+            "region": self.region_name,
+            "start_address": f"0x{self.start_address:08X}",
+            "end_address": f"0x{(self.start_address + self.scanned_bytes):08X}",
+            "scanned_bytes": self.scanned_bytes,
+            "total_words_scanned": self.total_words_scanned,
+            "elapsed_seconds": round(self.elapsed_seconds, 4),
+            "summary": {
+                "total_peripherals": self.total_peripherals,
+                "active_peripherals": self.active_peripherals_count,
+                "inactive_peripherals": self.inactive_peripherals_count,
+                "active_ratio_pct": round(self.active_ratio_pct, 2),
+            },
+            "active_peripherals": [p.to_dict() for p in self.active_peripherals],
+            "inactive_peripherals": [p.name for p in self.inactive_peripherals],
+        }
+
+
+@dataclass
+class ProfileSessionState(SessionSlice):
+    """Store accumulated profiling state, reports, and active peripherals across the GDB session."""
+
+    device_name: str | None = None
+    vendor: str | None = None
+    reports: list[ProfileReport] = field(default_factory=list)
+    active_peripherals: dict[str, dict[str, Any]] = field(default_factory=dict)
+    scanned_regions: list[dict[str, Any]] = field(default_factory=list)
+
+    def reset(self) -> None:
+        """Drop every accumulated profiling result."""
+        self.device_name = None
+        self.vendor = None
+        self.reports.clear()
+        self.active_peripherals.clear()
+        self.scanned_regions.clear()
+
+    @property
+    def last_report(self) -> ProfileReport | None:
+        """Return the most recent profiling report.
+
+        Returns
+        -------
+        ProfileReport | None
+            Latest report or None.
+        """
+        return self.reports[-1] if self.reports else None
+
+    def record_report(self, report: ProfileReport) -> None:
+        """Accumulate a new profiling report into the session state.
+
+        Parameters
+        ----------
+        report : ProfileReport
+            New profiling report to merge.
+        """
+        self.device_name = report.device_name
+        self.vendor = report.vendor
+        self.reports.append(report)
+        self.scanned_regions.append(
+            {
+                "region": report.region_name,
+                "start_address": f"0x{report.start_address:08X}",
+                "end_address": f"0x{(report.start_address + report.scanned_bytes):08X}",
+                "scanned_bytes": report.scanned_bytes,
+                "words_scanned": report.total_words_scanned,
+                "elapsed_seconds": round(report.elapsed_seconds, 4),
+            }
+        )
+
+        for periph in report.active_peripherals:
+            p_name = periph.name
+            if p_name not in self.active_peripherals:
+                self.active_peripherals[p_name] = {
+                    "name": periph.name,
+                    "base_address": f"0x{periph.base_address:08X}",
+                    "base_address_int": periph.base_address,
+                    "group_name": periph.group_name,
+                    "description": periph.description,
+                    "hit_count": 0,
+                    "total_registers": periph.total_registers,
+                    "regions": set(),
+                    "registers": {},
+                    "unnamed_offset_hits": 0,
+                }
+
+            p_entry = self.active_peripherals[p_name]
+            p_entry["hit_count"] += periph.hit_count
+            p_entry["regions"].add(report.region_name.upper())
+            p_entry["unnamed_offset_hits"] += periph.unnamed_offset_hits
+
+            for reg in periph.registers:
+                if reg.hit_count == 0:
+                    continue
+                r_name = reg.name
+                if r_name not in p_entry["registers"]:
+                    p_entry["registers"][r_name] = {
+                        "name": reg.name,
+                        "address_offset": f"0x{reg.address_offset:04X}",
+                        "address": f"0x{reg.address:08X}",
+                        "hit_count": 0,
+                        "hit_addresses": set(),
+                        "reference_types": set(),
+                        "regions": set(),
+                    }
+                r_entry = p_entry["registers"][r_name]
+                r_entry["hit_count"] += reg.hit_count
+                r_entry["hit_addresses"].update(reg.hit_addresses)
+                r_entry["reference_types"].update(reg.reference_types)
+                r_entry["regions"].add(report.region_name.upper())
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert the accumulated session profiling findings to a dictionary.
+
+        Returns
+        -------
+        dict[str, Any]
+            Dictionary representation of all accumulated findings.
+        """
+        active_list: list[dict[str, Any]] = []
+        for _, p_data in sorted(
+            self.active_peripherals.items(),
+            key=lambda item: int(item[1]["hit_count"]),
+            reverse=True,
+        ):
+            regs_dict: dict[str, Any] = {}
+            for r_name, r_data in p_data["registers"].items():
+                regs_dict[r_name] = {
+                    "name": r_data["name"],
+                    "address_offset": r_data["address_offset"],
+                    "address": r_data["address"],
+                    "hit_count": r_data["hit_count"],
+                    "hit_addresses": [f"0x{a:08X}" for a in sorted(r_data["hit_addresses"])],
+                    "reference_types": sorted(r_data["reference_types"]),
+                    "regions": sorted(r_data["regions"]),
+                }
+
+            active_list.append(
+                {
+                    "name": p_data["name"],
+                    "base_address": p_data["base_address"],
+                    "group_name": p_data["group_name"],
+                    "description": p_data["description"],
+                    "total_hits": p_data["hit_count"],
+                    "total_registers": p_data["total_registers"],
+                    "active_registers_count": len(regs_dict),
+                    "regions": sorted(p_data["regions"]),
+                    "registers": regs_dict,
+                    "unnamed_offset_hits": p_data["unnamed_offset_hits"],
+                }
+            )
+
+        return {
+            "device": self.device_name,
+            "vendor": self.vendor,
+            "scanned_regions": self.scanned_regions,
+            "total_active_peripherals": len(self.active_peripherals),
+            "active_peripherals": active_list,
+        }
+
+
+PROFILE_SESSION = TOOLKIT_SESSION.state(ProfileSessionState)
+
+
+def resolve_memory_region(device: SvdDevice, region: str) -> tuple[int, int]:
+    """Determine the default base address and size for a memory region from SVD and architecture.
+
+    Parameters
+    ----------
+    device : SvdDevice
+        Loaded SVD device definition.
+    region : str
+        Target memory region name ('flash' or 'sram').
+
+    Returns
+    -------
+    tuple[int, int]
+        Tuple of (start_address, default_size_in_bytes).
+    """
+    region_norm = region.strip().lower()
+    vendor = (device.vendor or "").strip().lower()
+
+    if region_norm == "flash":
+        for periph in device.peripherals:
+            p_name = periph.name.upper()
+            if periph.base_address < 0x20000000 and any(
+                k in p_name for k in ("FLASH", "ROM", "MEM", "NVMC")
+            ):
+                return periph.base_address, 0x80000
+
+        if "stmicro" in vendor or "stm" in vendor:
+            return 0x08000000, 0x80000
+        if "raspberry" in vendor:
+            return 0x10000000, 0x200000
+        if "microchip" in vendor or "atmel" in vendor:
+            return 0x00400000, 0x80000
+
+        return 0x00000000, 0x80000
+
+    if region_norm in ("sram", "ram"):
+        for periph in device.peripherals:
+            p_name = periph.name.upper()
+            if 0x20000000 <= periph.base_address < 0x40000000 and any(
+                k in p_name for k in ("RAM", "SRAM", "AXISRAM", "DTCM")
+            ):
+                return periph.base_address, 0x20000
+
+        return 0x20000000, 0x20000
+
+    return 0x00000000, 0x10000
+
+
+def _decode_thumb_movw_movt(chunk: bytes, offset: int) -> tuple[int, int] | None:
+    """Decode a Thumb-2 MOVW or MOVT 32-bit instruction at a given offset.
+
+    Parameters
+    ----------
+    chunk : bytes
+        Memory buffer.
+    offset : int
+        Byte offset in buffer.
+
+    Returns
+    -------
+    tuple[int, int] | None
+        Tuple of (destination_register_id, imm16_value) or None if not matching.
+    """
+    if offset + 4 > len(chunk):
+        return None
+
+    hw1 = int.from_bytes(chunk[offset : offset + 2], byteorder="little")
+    hw2 = int.from_bytes(chunk[offset + 2 : offset + 4], byteorder="little")
+
+    is_movw = (hw1 & 0xFBF0) == 0xF240 and (hw2 & 0x8000) == 0
+    is_movt = (hw1 & 0xFBF0) == 0xF2C0 and (hw2 & 0x8000) == 0
+
+    if not (is_movw or is_movt):
+        return None
+
+    i_bit = (hw1 >> 10) & 1
+    imm4 = hw1 & 0x000F
+    imm3 = (hw2 >> 12) & 0x07
+    rd = (hw2 >> 8) & 0x0F
+    imm8 = hw2 & 0x00FF
+
+    imm16 = (imm4 << 12) | (i_bit << 11) | (imm3 << 8) | imm8
+    kind = 1 if is_movt else 0
+    return rd, (kind << 16) | imm16
+
+
+def _decode_arm_movw_movt(word: int) -> tuple[int, int, int] | None:
+    """Decode an ARM 32-bit MOVW or MOVT instruction.
+
+    Parameters
+    ----------
+    word : int
+        Raw 32-bit ARM instruction word.
+
+    Returns
+    -------
+    tuple[int, int, int] | None
+        Tuple of (is_movt_flag, destination_register_id, imm16_value) or None.
+    """
+    if (word & 0x0FF00000) == 0x03000000:
+        imm4 = (word >> 16) & 0x0F
+        rd = (word >> 12) & 0x0F
+        imm12 = word & 0x0FFF
+        imm16 = (imm4 << 12) | imm12
+        return 0, rd, imm16
+
+    if (word & 0x0FF00000) == 0x03400000:
+        imm4 = (word >> 16) & 0x0F
+        rd = (word >> 12) & 0x0F
+        imm12 = word & 0x0FFF
+        imm16 = (imm4 << 12) | imm12
+        return 1, rd, imm16
+
+    return None
+
+
+def analyze_memory_profile(
+    device: SvdDevice,
+    reader: TargetMemory,
+    region_name: str,
+    start_address: int,
+    size: int,
+    chunk_size: int = 4096,
+) -> ProfileReport:
+    """Scan a target memory region to identify active peripherals and register manipulations.
+
+    Parameters
+    ----------
+    device : SvdDevice
+        Loaded SVD device definition.
+    reader : TargetMemory
+        Target memory reader interface.
+    region_name : str
+        Memory region identifier ('flash' or 'sram').
+    start_address : int
+        Starting physical address to scan.
+    size : int
+        Total number of bytes to scan.
+    chunk_size : int
+        Chunk size in bytes for batched memory reads.
+
+    Returns
+    -------
+    ProfileReport
+        Detailed profiling report.
+    """
+    start_time = time.time()
+
+    exact_registers: dict[int, tuple[SvdPeripheral, SvdRegister]] = {}
+    peripheral_bases: dict[int, SvdPeripheral] = {}
+    peripheral_ranges: list[tuple[int, int, SvdPeripheral]] = []
+
+    for periph in device.peripherals:
+        peripheral_bases[periph.base_address] = periph
+        max_offset = 0
+        for reg in periph.registers:
+            addr = periph.base_address + reg.address_offset
+            exact_registers[addr] = (periph, reg)
+            if reg.address_offset > max_offset:
+                max_offset = reg.address_offset
+
+        span = max(0x400, max_offset + 4)
+        peripheral_ranges.append((periph.base_address, periph.base_address + span, periph))
+
+    periph_hits: dict[str, dict[str, Any]] = {}
+    for periph in device.peripherals:
+        reg_map: dict[str, dict[str, Any]] = {}
+        for r in periph.registers:
+            reg_map[r.name] = {
+                "name": r.name,
+                "address_offset": r.address_offset,
+                "address": periph.base_address + r.address_offset,
+                "hits": [],
+                "ref_types": set(),
+            }
+        periph_hits[periph.name] = {
+            "periph": periph,
+            "total_hits": 0,
+            "registers": reg_map,
+            "unnamed_hits": 0,
+        }
+
+    scanned_bytes = 0
+    words_scanned = 0
+    current_addr = start_address
+    end_address = start_address + size
+
+    while current_addr < end_address:
+        read_len = min(chunk_size, end_address - current_addr)
+        try:
+            chunk = reader.read_bytes(current_addr, read_len)
+        except (TargetReadError, ValueError):
+            break
+
+        if not chunk:
+            break
+
+        chunk_len = len(chunk)
+        scanned_bytes += chunk_len
+        words_scanned += chunk_len // 4
+
+        # 1. Scan 32-bit aligned words (Literal Pools & Pointer tables)
+        for offset in range(0, chunk_len - 3, 4):
+            word_val = int.from_bytes(chunk[offset : offset + 4], byteorder="little")
+            hit_addr = current_addr + offset
+
+            if word_val in exact_registers:
+                p, r = exact_registers[word_val]
+                p_data = periph_hits[p.name]
+                p_data["total_hits"] += 1
+                r_entry = p_data["registers"][r.name]
+                r_entry["hits"].append(hit_addr)
+                r_entry["ref_types"].add("literal_pointer")
+            elif word_val in peripheral_bases:
+                p = peripheral_bases[word_val]
+                p_data = periph_hits[p.name]
+                p_data["total_hits"] += 1
+                if p.registers:
+                    first_reg = p.registers[0]
+                    r_entry = p_data["registers"][first_reg.name]
+                    r_entry["hits"].append(hit_addr)
+                    r_entry["ref_types"].add("literal_base_pointer")
+                else:
+                    p_data["unnamed_hits"] += 1
+
+        # 2. Scan Thumb-2 MOVW + MOVT pairs (16-bit aligned)
+        for offset in range(0, chunk_len - 7, 2):
+            res1 = _decode_thumb_movw_movt(chunk, offset)
+            if res1 is not None and (res1[1] >> 16) == 0:
+                rd1, low_imm16 = res1[0], res1[1] & 0xFFFF
+                res2 = _decode_thumb_movw_movt(chunk, offset + 4)
+                if res2 is not None and (res2[1] >> 16) == 1 and res2[0] == rd1:
+                    high_imm16 = res2[1] & 0xFFFF
+                    target_addr = (high_imm16 << 16) | low_imm16
+                    hit_addr = current_addr + offset
+
+                    if target_addr in exact_registers:
+                        p, r = exact_registers[target_addr]
+                        p_data = periph_hits[p.name]
+                        p_data["total_hits"] += 1
+                        r_entry = p_data["registers"][r.name]
+                        r_entry["hits"].append(hit_addr)
+                        r_entry["ref_types"].add("thumb_movw_movt")
+                    elif target_addr in peripheral_bases:
+                        p = peripheral_bases[target_addr]
+                        p_data = periph_hits[p.name]
+                        p_data["total_hits"] += 1
+                        if p.registers:
+                            first_reg = p.registers[0]
+                            r_entry = p_data["registers"][first_reg.name]
+                            r_entry["hits"].append(hit_addr)
+                            r_entry["ref_types"].add("thumb_movw_movt_base")
+                        else:
+                            p_data["unnamed_hits"] += 1
+
+        # 3. Scan ARM 32-bit MOVW + MOVT pairs (32-bit aligned)
+        for offset in range(0, chunk_len - 7, 4):
+            w1 = int.from_bytes(chunk[offset : offset + 4], byteorder="little")
+            arm_dec1 = _decode_arm_movw_movt(w1)
+            if arm_dec1 is not None and arm_dec1[0] == 0:
+                rd1, low_imm16 = arm_dec1[1], arm_dec1[2]
+                w2 = int.from_bytes(chunk[offset + 4 : offset + 8], byteorder="little")
+                arm_dec2 = _decode_arm_movw_movt(w2)
+                if arm_dec2 is not None and arm_dec2[0] == 1 and arm_dec2[1] == rd1:
+                    high_imm16 = arm_dec2[2]
+                    target_addr = (high_imm16 << 16) | low_imm16
+                    hit_addr = current_addr + offset
+
+                    if target_addr in exact_registers:
+                        p, r = exact_registers[target_addr]
+                        p_data = periph_hits[p.name]
+                        p_data["total_hits"] += 1
+                        r_entry = p_data["registers"][r.name]
+                        r_entry["hits"].append(hit_addr)
+                        r_entry["ref_types"].add("arm_movw_movt")
+                    elif target_addr in peripheral_bases:
+                        p = peripheral_bases[target_addr]
+                        p_data = periph_hits[p.name]
+                        p_data["total_hits"] += 1
+                        if p.registers:
+                            first_reg = p.registers[0]
+                            r_entry = p_data["registers"][first_reg.name]
+                            r_entry["hits"].append(hit_addr)
+                            r_entry["ref_types"].add("arm_movw_movt_base")
+                        else:
+                            p_data["unnamed_hits"] += 1
+
+        current_addr += chunk_len
+        if chunk_len < read_len:
+            break
+
+    elapsed = time.time() - start_time
+
+    periph_usages: list[PeripheralUsage] = []
+    active_count = 0
+
+    for periph in device.peripherals:
+        p_data = periph_hits[periph.name]
+        reg_usages: list[RegisterUsage] = []
+        active_regs = 0
+
+        for r in periph.registers:
+            r_info = p_data["registers"][r.name]
+            h_count = len(r_info["hits"])
+            if h_count > 0:
+                active_regs += 1
+            reg_usages.append(
+                RegisterUsage(
+                    name=r.name,
+                    address_offset=r_info["address_offset"],
+                    address=r_info["address"],
+                    hit_count=h_count,
+                    hit_addresses=tuple(r_info["hits"]),
+                    reference_types=tuple(sorted(r_info["ref_types"])),
+                )
+            )
+
+        p_hit_count = p_data["total_hits"]
+        if p_hit_count > 0:
+            active_count += 1
+
+        periph_usages.append(
+            PeripheralUsage(
+                name=periph.name,
+                base_address=periph.base_address,
+                group_name=periph.group_name,
+                description=periph.description,
+                hit_count=p_hit_count,
+                total_registers=len(periph.registers),
+                used_registers_count=active_regs,
+                registers=tuple(reg_usages),
+                unnamed_offset_hits=p_data["unnamed_hits"],
+            )
+        )
+
+    periph_usages.sort(key=lambda pu: pu.hit_count, reverse=True)
+
+    return ProfileReport(
+        device_name=device.name,
+        vendor=device.vendor,
+        region_name=region_name.lower(),
+        start_address=start_address,
+        scanned_bytes=scanned_bytes,
+        total_words_scanned=words_scanned,
+        elapsed_seconds=elapsed,
+        total_peripherals=len(device.peripherals),
+        active_peripherals_count=active_count,
+        peripherals=tuple(periph_usages),
+    )
+
+
+def render_profile_report(report: ProfileReport) -> None:
+    """Render a comprehensive profiling analysis report using Rich.
+
+    Parameters
+    ----------
+    report : ProfileReport
+        The completed profiling report.
+    """
+    kb_scanned = report.scanned_bytes / 1024.0
+    end_addr = report.start_address + report.scanned_bytes
+
+    summary_table = Table(
+        box=box.SIMPLE_HEAVY,
+        header_style="bold cyan",
+        show_header=False,
+    )
+    summary_table.add_column("Key", style="bold")
+    summary_table.add_column("Value")
+
+    summary_table.add_row("Device / SoC", f"{report.device_name} ({report.vendor or 'Generic'})")
+    summary_table.add_row(
+        "Scanned Region",
+        f"{report.region_name.upper()} @ 0x{report.start_address:08X} - 0x{end_addr:08X} "
+        f"({kb_scanned:.1f} KiB)",
+    )
+    summary_table.add_row(
+        "Active Peripherals",
+        Text(
+            f"{report.active_peripherals_count} / {report.total_peripherals} "
+            f"({report.active_ratio_pct:.1f}%)",
+            style="bold green" if report.active_peripherals_count > 0 else "yellow",
+        ),
+    )
+    summary_table.add_row(
+        "Inactive Peripherals",
+        f"{report.inactive_peripherals_count} / {report.total_peripherals}",
+    )
+    summary_table.add_row(
+        "Total Words Scanned",
+        f"{report.total_words_scanned:,} (in {report.elapsed_seconds:.3f}s)",
+    )
+
+    panel = Panel(
+        summary_table,
+        title=f"Target Peripheral Profile: {report.region_name.upper()}",
+        border_style="cyan",
+        box=box.ROUNDED,
+    )
+    CONSOLE.print(panel)
+
+    if report.active_peripherals:
+        table = Table(
+            title=f"Active Peripherals Detected in {report.region_name.upper()}",
+            box=box.SIMPLE_HEAVY,
+            header_style="bold cyan",
+            show_header=True,
+        )
+        table.add_column("Peripheral", style="bold", no_wrap=True)
+        table.add_column("Base Address", style="magenta", no_wrap=True)
+        table.add_column("Group", style="dim", no_wrap=True)
+        table.add_column("Hits", style="bold green", justify="right", no_wrap=True)
+        table.add_column("Active Regs", justify="center", no_wrap=True)
+        table.add_column("Referenced Registers")
+
+        for p in report.active_peripherals:
+            active_reg_names = [r.name for r in p.registers if r.hit_count > 0]
+            if len(active_reg_names) > 6:
+                regs_str = ", ".join(active_reg_names[:6]) + f" (+{len(active_reg_names) - 6} more)"
+            elif active_reg_names:
+                regs_str = ", ".join(active_reg_names)
+            else:
+                regs_str = "Base address only"
+
+            regs_ratio = f"{p.used_registers_count}/{p.total_registers}"
+            table.add_row(
+                p.name,
+                f"0x{p.base_address:08X}",
+                p.group_name or "--",
+                str(p.hit_count),
+                regs_ratio,
+                regs_str,
+            )
+        CONSOLE.print(table)
+    else:
+        CONSOLE.print(
+            Text(
+                f"No active peripheral references detected in {report.region_name.upper()} scan.",
+                style="yellow",
+            )
+        )
+
+    if report.inactive_peripherals:
+        inactive_names = [p.name for p in report.inactive_peripherals]
+        if len(inactive_names) > 20:
+            inactive_preview = (
+                ", ".join(inactive_names[:20]) + f" ... (+{len(inactive_names) - 20} more)"
+            )
+        else:
+            inactive_preview = ", ".join(inactive_names)
+
+        inactive_table = Table(
+            title="Inactive Peripherals Summary",
+            box=box.SIMPLE_HEAVY,
+            header_style="bold cyan",
+            show_header=True,
+        )
+        inactive_table.add_column("Count", style="yellow", justify="right", no_wrap=True)
+        inactive_table.add_column("Unreferenced Peripherals")
+        inactive_table.add_row(str(len(inactive_names)), inactive_preview)
+        CONSOLE.print(inactive_table)
+
+
+def dump_profile_to_json(session_state: ProfileSessionState, output_path: Path) -> int:
+    """Serialize the accumulated profiling results to a JSON file on disk.
+
+    Parameters
+    ----------
+    session_state : ProfileSessionState
+        Profile session state to serialize.
+    output_path : Path
+        Destination file path.
+
+    Returns
+    -------
+    int
+        Size of the written file in bytes.
+    """
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    with output_path.open("w", encoding="utf-8") as json_file:
+        json.dump(session_state.to_dict(), json_file, indent=2)
+    return output_path.stat().st_size
+
+
+def render_dump_success(
+    session_state: ProfileSessionState, file_path: Path, file_size: int
+) -> None:
+    """Render a Rich confirmation table when a profile report is exported to JSON.
+
+    Parameters
+    ----------
+    session_state : ProfileSessionState
+        Profile session state dumped.
+    file_path : Path
+        Output file path.
+    file_size : int
+        Size in bytes.
+    """
+    table = Table(
+        title="Profile Report Exported",
+        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("Device", session_state.device_name or "Unknown")
+    table.add_row(
+        "Scanned Regions",
+        ", ".join(r["region"].upper() for r in session_state.scanned_regions) or "None",
+    )
+    table.add_row("Output File", Text(str(file_path), style="bold green"))
+    table.add_row("Active Peripherals", str(len(session_state.active_peripherals)))
+    table.add_row("File Size", f"{file_size:,} bytes")
+    CONSOLE.print(table)
+
+
+def render_show_peripherals(
+    session_state: ProfileSessionState, periph_filter: str | None = None
+) -> None:
+    """Render the accumulated list of active peripherals or details for one peripheral.
+
+    Parameters
+    ----------
+    session_state : ProfileSessionState
+        Active profiling session state.
+    periph_filter : str | None
+        Optional peripheral name filter.
+    """
+    if not session_state.active_peripherals:
+        panel = Panel(
+            Text.assemble(
+                ("No Profiling Data: ", "bold yellow"),
+                (
+                    "No peripheral manipulation has been recorded yet in this session.\n",
+                    "default",
+                ),
+                ("Run ", "dim"),
+                ("profile analyze flash", "bold cyan"),
+                (" or ", "dim"),
+                ("profile analyze sram", "bold cyan"),
+                (" to analyze target memory.", "dim"),
+            ),
+            title="Firmware Peripheral Profile",
+            box=box.ROUNDED,
+        )
+        CONSOLE.print(panel)
+        return
+
+    if periph_filter:
+        target_name = periph_filter.strip().upper()
+        matched_key = next(
+            (k for k in session_state.active_peripherals if k.upper() == target_name),
+            None,
+        )
+        if matched_key is None:
+            CONSOLE.print(
+                Text(
+                    f"Peripheral '{periph_filter}' is not present among actively used peripherals.",
+                    style="yellow",
+                )
+            )
+            return
+
+        p_data = session_state.active_peripherals[matched_key]
+        table = Table(
+            title=f"Active Registers: {p_data['name']} (Base {p_data['base_address']})",
+            box=box.SIMPLE_HEAVY,
+            header_style="bold cyan",
+            show_header=True,
+        )
+        table.add_column("Register", style="bold", no_wrap=True)
+        table.add_column("Offset", style="dim", no_wrap=True)
+        table.add_column("Address", style="magenta", no_wrap=True)
+        table.add_column("Hits", style="bold green", justify="right", no_wrap=True)
+        table.add_column("Regions", style="bold yellow", no_wrap=True)
+        table.add_column("Reference Types", style="dim")
+        table.add_column("Hit Locations Preview")
+
+        regs_dict: dict[str, Any] = p_data["registers"]
+        for r_name, r_info in sorted(
+            regs_dict.items(), key=lambda item: int(item[1]["hit_count"]), reverse=True
+        ):
+            hit_addrs = [f"0x{a:08X}" for a in sorted(r_info["hit_addresses"])]
+            locs_str = (
+                ", ".join(hit_addrs[:4]) + f" (+{len(hit_addrs) - 4} more)"
+                if len(hit_addrs) > 4
+                else ", ".join(hit_addrs)
+            )
+            table.add_row(
+                r_name,
+                r_info["address_offset"],
+                r_info["address"],
+                str(r_info["hit_count"]),
+                ", ".join(sorted(r_info["regions"])),
+                ", ".join(sorted(r_info["reference_types"])),
+                locs_str,
+            )
+        CONSOLE.print(table)
+        return
+
+    regions_str = ", ".join(r["region"].upper() for r in session_state.scanned_regions)
+    summary_table = Table(
+        box=box.SIMPLE_HEAVY,
+        header_style="bold cyan",
+        show_header=False,
+    )
+    summary_table.add_column("Key", style="bold")
+    summary_table.add_column("Value")
+    summary_table.add_row(
+        "Device / SoC",
+        f"{session_state.device_name or 'Unknown'} ({session_state.vendor or 'Generic'})",
+    )
+    summary_table.add_row("Scanned Regions", regions_str or "--")
+    summary_table.add_row(
+        "Total Active Peripherals",
+        Text(str(len(session_state.active_peripherals)), style="bold green"),
+    )
+    summary_table.add_row(
+        "Total Analysis Runs",
+        str(len(session_state.scanned_regions)),
+    )
+
+    panel = Panel(
+        summary_table,
+        title="Firmware Active Peripheral Profile",
+        border_style="cyan",
+        box=box.ROUNDED,
+    )
+    CONSOLE.print(panel)
+
+    table = Table(
+        title="Active Peripherals Used by Firmware (Accumulated)",
+        box=box.SIMPLE_HEAVY,
+        header_style="bold cyan",
+        show_header=True,
+    )
+    table.add_column("Peripheral", style="bold", no_wrap=True)
+    table.add_column("Base Address", style="magenta", no_wrap=True)
+    table.add_column("Group", style="dim", no_wrap=True)
+    table.add_column("Total Hits", style="bold green", justify="right", no_wrap=True)
+    table.add_column("Active Regs", justify="center", no_wrap=True)
+    table.add_column("Regions", style="bold yellow", no_wrap=True)
+    table.add_column("Referenced Registers")
+
+    for _, p_data in sorted(
+        session_state.active_peripherals.items(),
+        key=lambda item: int(item[1]["hit_count"]),
+        reverse=True,
+    ):
+        regs_dict = p_data["registers"]
+        active_reg_names = list(regs_dict.keys())
+        if len(active_reg_names) > 6:
+            regs_str = ", ".join(active_reg_names[:6]) + f" (+{len(active_reg_names) - 6} more)"
+        elif active_reg_names:
+            regs_str = ", ".join(active_reg_names)
+        else:
+            regs_str = "Base address only"
+
+        regs_ratio = f"{len(regs_dict)}/{p_data['total_registers']}"
+        table.add_row(
+            p_data["name"],
+            p_data["base_address"],
+            p_data["group_name"] or "--",
+            str(p_data["hit_count"]),
+            regs_ratio,
+            ", ".join(sorted(p_data["regions"])),
+            regs_str,
+        )
+
+    CONSOLE.print(table)
+
+
+def render_help() -> None:
+    """Render the profile command overview and help table."""
+    table = Table(
+        title="Firmware Peripheral Profiling & Memory Analysis",
+        box=box.SIMPLE_HEAVY,
+        header_style="bold cyan",
+        show_header=True,
+    )
+    table.add_column("Command Syntax", style="bold yellow", no_wrap=True)
+    table.add_column("Description")
+    table.add_row(
+        "profile analyze flash [<addr>] [<size>]",
+        "Analyze Flash memory for register manipulations and summarize with Rich",
+    )
+    table.add_row(
+        "profile analyze sram [<addr>] [<size>]",
+        "Analyze SRAM memory for register manipulations and summarize with Rich",
+    )
+    table.add_row(
+        "profile show [<peripheral>]",
+        "Display the accumulated list of peripherals used by the firmware",
+    )
+    table.add_row(
+        "profile dump <file.json>",
+        "Export the accumulated profiling analysis results to a JSON file",
+    )
+    table.add_row("profile help", "Show this command reference")
+    CONSOLE.print(table)
+
+
+def _ensure_svd_loaded() -> SvdDevice:
+    """Ensure an SVD device model is loaded in the session, auto-detecting if needed.
+
+    Returns
+    -------
+    SvdDevice
+        The active SVD device model.
+
+    Raises
+    ------
+    gdb.GdbError
+        If no SVD file could be loaded or detected.
+    """
+    if is_svd_loaded() and SVD_SESSION.device is not None:
+        return SVD_SESSION.device
+
+    try:
+        report = device_report()
+    except TargetReadError as err:
+        raise gdb.GdbError(
+            f"No SVD loaded and cannot detect target memory: {err}. "
+            "Run 'svd load' or 'svd read <file.svd>' first."
+        ) from err
+
+    try:
+        svd_path, _ = resolve_and_fetch_svd(report)
+        device = parse_svd_file(svd_path)
+        SVD_SESSION.device = device
+        SVD_SESSION.svd_dict = device.to_dict()
+        SVD_SESSION.svd_path = svd_path
+        return device
+    except SvdError as err:
+        raise gdb.GdbError(
+            f"No SVD definition currently loaded. Failed to auto-load SVD: {err}. "
+            "Please run 'svd load' or 'svd read <file.svd>' first."
+        ) from err
+
+
+def _parse_int_arg(arg_str: str) -> int:
+    """Parse an integer argument supporting hex, bin, and dec notation.
+
+    Parameters
+    ----------
+    arg_str : str
+        Input string.
+
+    Returns
+    -------
+    int
+        Decoded integer.
+    """
+    arg_str = arg_str.strip()
+    if arg_str.startswith("#"):
+        return int(arg_str[1:], 16)
+    if arg_str.startswith(("0x", "0X")):
+        return int(arg_str, 16)
+    if arg_str.startswith(("0b", "0B")):
+        return int(arg_str, 2)
+    return int(arg_str, 10)
+
+
+class ProfileCmd(gdb.Command):
+    """Profile target memory (Flash/SRAM) to identify active SVD peripheral usage."""
+
+    def __init__(self) -> None:
+        super().__init__("profile", gdb.COMMAND_USER, gdb.COMPLETE_NONE, True)
+
+    def invoke(self, arg: str, from_tty: bool) -> None:
+        """Display help overview.
+
+        Parameters
+        ----------
+        arg : str
+            Command arguments.
+        from_tty : bool
+            Whether invoked interactively from terminal.
+        """
+        del arg
+        del from_tty
+        render_help()
+
+    def complete_args(self, subcmd: str, text: str, word: str) -> list[str]:
+        """Provide intelligent GDB auto-completion for profile subcommands.
+
+        Parameters
+        ----------
+        subcmd : str
+            Subcommand name.
+        text : str
+            Full argument string.
+        word : str
+            Word currently being completed.
+
+        Returns
+        -------
+        list[str]
+            Completion matches.
+        """
+        command_prefix = f"profile {subcmd}"
+        arg_text = text
+        if arg_text.startswith(command_prefix):
+            arg_text = arg_text[len(command_prefix) :].lstrip()
+        tokens = arg_text.split()
+
+        if subcmd in ("analyze", "analyse"):
+            if not tokens or (len(tokens) == 1 and not arg_text.endswith(" ")):
+                options = ["flash", "sram"]
+                return [o for o in options if o.startswith(word.lower())]
+            return []
+
+        if subcmd == "show":
+            if not tokens or (len(tokens) == 1 and not arg_text.endswith(" ")):
+                names = list(PROFILE_SESSION.active_peripherals.keys())
+                if SVD_SESSION.device is not None:
+                    for p in SVD_SESSION.device.peripherals:
+                        if p.name not in names:
+                            names.append(p.name)
+                return [n for n in names if n.upper().startswith(word.upper())]
+            return []
+
+        if subcmd == "dump":
+            if not tokens or (len(tokens) == 1 and not arg_text.endswith(" ")):
+                pattern = f"{word}*"
+                expanded = os.path.expanduser(pattern)
+                matches = glob.glob(expanded)
+                results: list[str] = []
+                for m in matches:
+                    if os.path.isdir(m):
+                        results.append(f"{m}/")
+                    elif m.lower().endswith(".json"):
+                        results.append(m)
+                return results
+            return []
+
+        return []
+
+    def _invoke_analyze(self, args: list[str]) -> None:
+        """Handle 'profile analyze flash|sram [<addr>] [<size>]'.
+
+        Parameters
+        ----------
+        args : list[str]
+            Subcommand arguments.
+
+        Raises
+        ------
+        gdb.GdbError
+            If arguments are invalid or memory scan fails.
+        """
+        if not args:
+            raise gdb.GdbError("Usage: profile analyze <flash|sram> [<start_addr>] [<size>]")
+
+        target_region = args[0].lower()
+        if target_region not in ("flash", "sram", "ram"):
+            raise gdb.GdbError(f"Unknown memory region '{args[0]}': expected 'flash' or 'sram'.")
+
+        device = _ensure_svd_loaded()
+        default_start, default_size = resolve_memory_region(device, target_region)
+
+        start_addr = default_start
+        size = default_size
+
+        if len(args) >= 2:
+            try:
+                start_addr = _parse_int_arg(args[1])
+            except ValueError as err:
+                raise gdb.GdbError(f"Invalid start address '{args[1]}': {err}") from err
+
+        if len(args) >= 3:
+            try:
+                size = _parse_int_arg(args[2])
+            except ValueError as err:
+                raise gdb.GdbError(f"Invalid memory size '{args[2]}': {err}") from err
+
+        try:
+            reader = TOOLKIT_SESSION.memory
+        except TargetReadError as err:
+            raise gdb.GdbError(f"Cannot access target memory: {err}") from err
+
+        report = analyze_memory_profile(
+            device=device,
+            reader=reader,
+            region_name=target_region,
+            start_address=start_addr,
+            size=size,
+        )
+        PROFILE_SESSION.record_report(report)
+        render_profile_report(report)
+
+    def _invoke_show(self, args: list[str]) -> None:
+        """Handle 'profile show [<peripheral>]'.
+
+        Parameters
+        ----------
+        args : list[str]
+            Subcommand arguments.
+
+        Raises
+        ------
+        gdb.GdbError
+            If too many arguments are supplied.
+        """
+        if len(args) > 1:
+            raise gdb.GdbError("Usage: profile show [<peripheral>]")
+
+        periph_name = args[0] if args else None
+        render_show_peripherals(PROFILE_SESSION, periph_name)
+
+    def _invoke_dump(self, args: list[str]) -> None:
+        """Handle 'profile dump <file.json>'.
+
+        Parameters
+        ----------
+        args : list[str]
+            Subcommand arguments.
+
+        Raises
+        ------
+        gdb.GdbError
+            If arguments are invalid or writing fails.
+        """
+        if len(args) != 1:
+            raise gdb.GdbError("Usage: profile dump <file.json>")
+
+        out_path = Path(args[0]).expanduser().resolve()
+
+        if not PROFILE_SESSION.active_peripherals:
+            device = _ensure_svd_loaded()
+            default_start, default_size = resolve_memory_region(device, "flash")
+            try:
+                reader = TOOLKIT_SESSION.memory
+            except TargetReadError as err:
+                raise gdb.GdbError(f"Cannot access target memory: {err}") from err
+
+            report = analyze_memory_profile(
+                device=device,
+                reader=reader,
+                region_name="flash",
+                start_address=default_start,
+                size=default_size,
+            )
+            PROFILE_SESSION.record_report(report)
+
+        try:
+            file_size = dump_profile_to_json(PROFILE_SESSION, out_path)
+            render_dump_success(PROFILE_SESSION, out_path, file_size)
+        except OSError as err:
+            raise gdb.GdbError(f"Failed to write dump to '{out_path}': {err}") from err
+
+
+class _ProfileSubcommand(gdb.Command):
+    """Base class for concrete ``profile`` subcommands registered under the prefix command."""
+
+    def __init__(self, parent: ProfileCmd, name: str) -> None:
+        self.parent = parent
+        self.name = name
+        super().__init__(f"profile {name}", gdb.COMMAND_USER)
+
+    def _argv(self, arg: str) -> list[str]:
+        """Split command arguments using GDB CLI lexer.
+
+        Parameters
+        ----------
+        arg : str
+            Argument string.
+
+        Returns
+        -------
+        list[str]
+            Parsed arguments.
+        """
+        return list(gdb.string_to_argv(arg)) if arg.strip() else []
+
+    def complete(self, text: str, word: str) -> list[str]:
+        """Complete arguments for the concrete subcommand.
+
+        Parameters
+        ----------
+        text : str
+            Full argument string.
+        word : str
+            Word to complete.
+
+        Returns
+        -------
+        list[str]
+            Completion options.
+        """
+        return self.parent.complete_args(self.name, text, word)
+
+
+class ProfileAnalyzeCmd(_ProfileSubcommand):
+    """Analyze target Flash or SRAM for peripheral register usage."""
+
+    def __init__(self, parent: ProfileCmd) -> None:
+        super().__init__(parent, "analyze")
+
+    def invoke(self, arg: str, from_tty: bool) -> None:
+        """Execute ``profile analyze <flash|sram>``."""
+        del from_tty
+        self.parent._invoke_analyze(self._argv(arg))
+
+
+class ProfileAnalyseCmd(_ProfileSubcommand):
+    """Analyze target Flash or SRAM for peripheral register usage (French alias)."""
+
+    def __init__(self, parent: ProfileCmd) -> None:
+        super().__init__(parent, "analyse")
+
+    def invoke(self, arg: str, from_tty: bool) -> None:
+        """Execute ``profile analyse <flash|sram>``."""
+        del from_tty
+        self.parent._invoke_analyze(self._argv(arg))
+
+
+class ProfileShowCmd(_ProfileSubcommand):
+    """Display the accumulated list of peripherals used by the firmware."""
+
+    def __init__(self, parent: ProfileCmd) -> None:
+        super().__init__(parent, "show")
+
+    def invoke(self, arg: str, from_tty: bool) -> None:
+        """Execute ``profile show [<peripheral>]``."""
+        del from_tty
+        self.parent._invoke_show(self._argv(arg))
+
+
+class ProfileDumpCmd(_ProfileSubcommand):
+    """Dump the latest profiling analysis results to a JSON file."""
+
+    def __init__(self, parent: ProfileCmd) -> None:
+        super().__init__(parent, "dump")
+
+    def invoke(self, arg: str, from_tty: bool) -> None:
+        """Execute ``profile dump <file.json>``."""
+        del from_tty
+        self.parent._invoke_dump(self._argv(arg))
+
+
+class ProfileHelpCmd(_ProfileSubcommand):
+    """Show the profile command reference."""
+
+    def __init__(self, parent: ProfileCmd) -> None:
+        super().__init__(parent, "help")
+
+    def invoke(self, arg: str, from_tty: bool) -> None:
+        """Execute ``profile help``."""
+        del arg
+        del from_tty
+        render_help()