arm-stack

#!/usr/bin/env python3
"""
ARM Stack Usage Analyzer

A comprehensive tool for analyzing stack usage in ARM embedded projects.
This tool parses object files and stack usage information to provide detailed
analysis of function call graphs and stack consumption patterns.

Originally inspired by avstack.pl, this implementation provides enhanced
visualization, filtering capabilities, and better error handling.

Requirements:
    - ARM GCC toolchain (arm-none-eabi-objdump)
    - Project compiled with -fstack-usage flag
    - Object files (.o or .c.obj) and stack usage files (.su)

Author: wizath
GitHub: https://github.com/wizath
License: MIT
Version: 1.13
"""

import sys
import os
import re
import subprocess
import glob
import json
import logging
from collections import defaultdict, namedtuple
from typing import Dict, Set, List, Optional
import argparse
from pathlib import Path
from datetime import datetime

# Version information
__version__ = "1.13"
__author__ = "wizath"
__github__ = "https://github.com/wizath"


class Colors:
    """ANSI color codes for enhanced terminal output"""
    HEADER = '\033[95m'
    BLUE = '\033[94m'
    CYAN = '\033[96m'
    GREEN = '\033[92m'
    YELLOW = '\033[93m'
    RED = '\033[91m'
    BOLD = '\033[1m'
    UNDERLINE = '\033[4m'
    END = '\033[0m'


# Tool configuration constants
DEFAULT_OBJDUMP = "arm-none-eabi-objdump"
CALL_COST = 4  # ARM function call overhead in bytes
DEFAULT_STACK_MARGIN = 1.5  # Safety margin for thread stack recommendations
SUBPROCESS_TIMEOUT = 60  # Timeout for subprocess calls in seconds
MAX_UNRESOLVED_DISPLAY = 20  # Maximum unresolved functions to display
MAX_FUNCTION_NAME_LEN = 39  # Maximum function name length before truncation

# RTOS thread/task creation patterns for auto-detection
# Format: (function_pattern, entry_func_arg_position, stack_size_arg_position)
RTOS_THREAD_PATTERNS = {
    'FreeRTOS': [
        (r'xTaskCreate\s*\(\s*(\w+)', 0, None),
        (r'xTaskCreateStatic\s*\(\s*(\w+)', 0, None),
    ],
    'Zephyr': [
        (r'k_thread_create\s*\([^,]+,\s*[^,]+,\s*[^,]+,\s*(\w+)', 0, None),
        (r'K_THREAD_DEFINE\s*\(\s*\w+\s*,\s*\d+\s*,\s*(\w+)', 0, None),
    ],
    'CMSIS-RTOS': [
        (r'osThreadNew\s*\(\s*(\w+)', 0, None),
        (r'osThreadCreate\s*\([^,]+,\s*(\w+)', 0, None),
    ],
    'ThreadX': [
        (r'tx_thread_create\s*\([^,]+,\s*[^,]+,\s*(\w+)', 0, None),
    ],
    'Azure-RTOS': [
        (r'tx_thread_create\s*\([^,]+,\s*[^,]+,\s*(\w+)', 0, None),
    ],
    'embOS': [
        (r'OS_TASK_Create\s*\([^,]+,\s*[^,]+,\s*(\w+)', 0, None),
        (r'OS_TASK_CreateEx\s*\([^,]+,\s*[^,]+,\s*(\w+)', 0, None),
    ],
    'uC/OS': [
        (r'OSTaskCreate\s*\(\s*(\w+)', 0, None),
        (r'OSTaskCreateExt\s*\(\s*(\w+)', 0, None),
    ],
    'POSIX': [
        (r'pthread_create\s*\([^,]+,\s*[^,]+,\s*(\w+)', 0, None),
    ],
}

# Data structure for function information
FunctionInfo = namedtuple('FunctionInfo', [
    'name',              # Function name (cleaned)
    'cost',              # Total stack cost including callees
    'frame_size',        # Local frame size from .su file
    'height',            # Call chain depth
    'is_recursive',      # Whether function is recursive
    'is_root',           # Whether function is a root (entry point)
    'is_unbounded',      # Whether function has unbounded stack usage
    'unbounded_reason',  # Reason for unbounded stack (recursion, function_pointer, etc.)
    'code_size',         # Function code size in flash (bytes)
    'data_size',         # Initialized data (.data) per source file
    'bss_size',          # Uninitialized data (.bss) per source file
    'has_heap_alloc'     # Whether function calls malloc/free etc.
])

# Heap allocation function patterns to detect
HEAP_ALLOC_FUNCTIONS = {
    'malloc', 'free', 'calloc', 'realloc',  # Standard C
    'pvPortMalloc', 'vPortFree',             # FreeRTOS
    'k_malloc', 'k_free',                    # Zephyr
    'mem_malloc', 'mem_free',                # lwIP
    'OS_MemGet', 'OS_MemPut',                # uC/OS
}

# Data structure for detected thread/task information
ThreadInfo = namedtuple('ThreadInfo', [
    'entry_func',        # Thread entry function name
    'rtos',              # Detected RTOS type
    'source_file',       # Source file where thread was created
    'stack_usage',       # Calculated stack usage
    'recommended',       # Recommended stack size (with margin)
    'is_unbounded'       # Whether stack usage is unbounded
])


class AnalysisData:
    """Shared data container for analysis results between components."""

    def __init__(self):
        # Core data structures for analysis
        self.frame_size: Dict[str, int] = {}
        self.call_graph: Dict[str, Set[str]] = defaultdict(set)
        self.total_cost: Dict[str, int] = {}
        self.call_depth: Dict[str, int] = {}
        self.visited: Dict[str, str] = {}
        self.has_caller: Set[str] = set()
        self.unresolved: Set[str] = set()

        # Symbol resolution tables
        self.addresses: Dict[int, str] = {}
        self.global_name: Dict[str, str] = {}
        self.ambiguous: Set[str] = set()

        # Function pointer detection
        self.has_function_pointer: Set[str] = set()
        self.rtl_available: bool = False

        # Code size tracking (flash usage)
        self.code_size: Dict[str, int] = {}
        self.elf_code_size: Dict[str, int] = {}
        self.elf_file: Optional[str] = None

        # Static allocation tracking (RAM usage)
        self.data_size: Dict[str, int] = {}
        self.bss_size: Dict[str, int] = {}
        self.static_size: Dict[str, int] = {}
        self.elf_data_size: Dict[str, int] = {}
        self.elf_bss_size: Dict[str, int] = {}
        self.func_static_vars: Dict[str, List[tuple]] = {}

        # Memory region tracking (symbol -> section name)
        self.symbol_sections: Dict[str, str] = {}  # symbol -> section name
        self.section_sizes: Dict[str, int] = {}    # section -> total size
        self.section_symbols: Dict[str, Dict[str, int]] = {}  # section -> {symbol: size}

        # Heap allocation detection
        self.has_heap_alloc: Set[str] = set()

        # Git repository information
        self.git_info: Dict[str, str] = {}

        # Thread/task detection
        self.detected_threads: List[ThreadInfo] = []


class ObjectFileParser:
    """Handles parsing of object files, .su files, and ELF binaries."""

    def __init__(self, build_dir: Path, objdump_path: str, data: AnalysisData):
        self.build_dir = build_dir
        self.objdump_path = objdump_path
        self.data = data
        self.logger = logging.getLogger(__name__)

    def find_object_files(self) -> List[str]:
        """Locate all relevant object files in the build directory."""
        patterns = ["**/*.o", "**/*.c.obj"]
        obj_files = []

        for pattern in patterns:
            obj_files.extend(glob.glob(str(self.build_dir / pattern), recursive=True))

        filtered = [
            f for f in obj_files
            if "CMakeFiles/CompilerIdC" not in f
            and "CMakeFiles/CompilerIdCXX" not in f
        ]

        self.logger.info(f"  Found {len(filtered)} object files")
        return sorted(filtered)

    def parse_disassembly(self, obj_file: str) -> None:
        """Parse object file disassembly to extract call graph."""
        try:
            result = subprocess.run(
                [self.objdump_path, "-dr", obj_file],
                capture_output=True, text=True, check=True,
                timeout=SUBPROCESS_TIMEOUT
            )

            current_function = None

            for line in result.stdout.splitlines():
                line = line.strip()

                func_match = re.match(r'^([0-9a-fA-F]+) <(.*)>:', line)
                if func_match:
                    addr, name = func_match.groups()
                    current_function = f"{name}@{obj_file}"
                    self.data.call_graph[current_function] = set()

                    if name in self.data.global_name:
                        self.data.ambiguous.add(name)
                    self.data.global_name[name] = current_function

                    addr = addr.lstrip('0') or '0'
                    self.data.addresses[f"{addr}@{obj_file}"] = current_function

                call_match = re.search(r': R_[A-Za-z0-9_]+_CALL\s+(.+)', line)
                if call_match and current_function:
                    target = call_match.group(1)

                    if target in HEAP_ALLOC_FUNCTIONS:
                        self.data.has_heap_alloc.add(current_function)

                    if target == ".text":
                        target = f"@{obj_file}"
                    elif target.startswith(".text+0x"):
                        offset = target[9:]
                        target = f"{offset}@{obj_file}"

                    self.data.call_graph[current_function].add(target)

        except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as e:
            print(f"{Colors.RED}Error disassembling {obj_file}: {e}{Colors.END}")
            sys.exit(1)

    def parse_su_file(self, obj_file: str) -> None:
        """Parse stack usage file to extract frame sizes."""
        if obj_file.endswith('.o'):
            su_file = obj_file[:-2] + '.su'
        elif obj_file.endswith('.c.obj'):
            su_file = obj_file[:-6] + '.c.su'
        else:
            return

        try:
            with open(su_file, 'r') as f:
                for line in f:
                    match = re.match(r'.*:(\w+)\s+(\d+)\s+(\w+)', line)
                    if match:
                        func_name, size, qualifier = match.groups()
                        func_full_name = f"{func_name}@{obj_file}"
                        self.data.frame_size[func_full_name] = int(size) + CALL_COST
        except FileNotFoundError:
            pass

    def parse_static_sizes(self, obj_file: str) -> None:
        """Parse object file to extract .data and .bss sizes."""
        nm_path = self.objdump_path.replace('objdump', 'nm')

        try:
            result = subprocess.run(
                [nm_path, '--print-size', obj_file],
                capture_output=True, text=True, check=True,
                timeout=SUBPROCESS_TIMEOUT
            )

            total_data = 0
            total_bss = 0

            for line in result.stdout.splitlines():
                parts = line.strip().split()
                if len(parts) >= 4:
                    size_hex, sym_type, sym_name = parts[1], parts[2], parts[3]
                    try:
                        size = int(size_hex, 16)
                    except ValueError:
                        continue

                    if sym_type in ('D', 'd'):
                        total_data += size
                        var_type = 'data'
                    elif sym_type in ('B', 'b'):
                        total_bss += size
                        var_type = 'bss'
                    else:
                        continue

                    if '.' in sym_name:
                        func_name = sym_name.split('.')[0]
                        var_name = sym_name.split('.', 1)[1]
                        if func_name not in self.data.func_static_vars:
                            self.data.func_static_vars[func_name] = []
                        self.data.func_static_vars[func_name].append((var_name, size, var_type))

            if total_data > 0:
                self.data.data_size[obj_file] = total_data
            if total_bss > 0:
                self.data.bss_size[obj_file] = total_bss
            if total_data + total_bss > 0:
                self.data.static_size[obj_file] = total_data + total_bss

        except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError):
            pass

    def parse_elf(self, elf_file: str) -> None:
        """Parse ELF file for accurate linked sizes."""
        self.data.elf_file = elf_file
        nm_path = self.objdump_path.replace('objdump', 'nm')

        self.logger.info(f"Parsing ELF file: {elf_file}")

        try:
            result = subprocess.run(
                [nm_path, '--print-size', elf_file],
                capture_output=True, text=True, check=True,
                timeout=SUBPROCESS_TIMEOUT
            )

            for line in result.stdout.splitlines():
                parts = line.strip().split()
                if len(parts) >= 4:
                    size_hex, sym_type, name = parts[1], parts[2], parts[3]
                    try:
                        size = int(size_hex, 16)
                    except ValueError:
                        continue

                    if sym_type in ('T', 't'):
                        self.data.elf_code_size[name] = size
                    elif sym_type in ('D', 'd'):
                        self.data.elf_data_size[name] = size
                    elif sym_type in ('B', 'b'):
                        self.data.elf_bss_size[name] = size

            self.logger.info(f"  Code: {len(self.data.elf_code_size)} functions")
            self.logger.info(f"  .data: {len(self.data.elf_data_size)} symbols")
            self.logger.info(f"  .bss: {len(self.data.elf_bss_size)} symbols")

        except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError) as e:
            self.logger.warning(f"Failed to parse ELF: {e}")

        # Also parse sections for memory region detection
        self._parse_elf_sections(elf_file)

    def _parse_elf_sections(self, elf_file: str) -> None:
        """Parse ELF sections to detect memory regions (SRAM vs HyperRAM etc)."""
        try:
            # Use objdump -h to get section headers
            result = subprocess.run(
                [self.objdump_path, '-h', elf_file],
                capture_output=True, text=True, check=True,
                timeout=SUBPROCESS_TIMEOUT
            )

            for line in result.stdout.splitlines():
                # Format: "idx name size vma lma file_off algn flags"
                # Example: "  3 .data 00001234 20000000 08010000 00010000 2**2"
                parts = line.split()
                if len(parts) >= 6 and parts[0].isdigit():
                    section_name = parts[1]
                    try:
                        size = int(parts[2], 16)
                        vma = int(parts[3], 16)
                    except ValueError:
                        continue

                    if size > 0:
                        self.data.section_sizes[section_name] = size

            # Now get symbol-to-section mapping using nm -S
            nm_path = self.objdump_path.replace('objdump', 'nm')
            result = subprocess.run(
                [nm_path, '-S', '--format=sysv', elf_file],
                capture_output=True, text=True, check=True,
                timeout=SUBPROCESS_TIMEOUT
            )

            for line in result.stdout.splitlines():
                # SysV format: "name |address |class|type|size|line|section"
                if '|' in line:
                    parts = [p.strip() for p in line.split('|')]
                    if len(parts) >= 7:
                        name, size_str, section = parts[0], parts[4], parts[6]
                        if name and section and section != '':
                            self.data.symbol_sections[name] = section
                            # Parse size and group by section
                            try:
                                size = int(size_str, 16) if size_str else 0
                                if size > 0:
                                    if section not in self.data.section_symbols:
                                        self.data.section_symbols[section] = {}
                                    self.data.section_symbols[section][name] = size
                            except ValueError:
                                pass

        except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError):
            pass

    def parse_map_file(self, map_file: str) -> None:
        """Parse linker map file for detailed memory region info."""
        self.logger.info(f"Parsing map file: {map_file}")

        try:
            with open(map_file, 'r') as f:
                content = f.read()

            # Parse memory configuration section for section-to-region mapping
            # This is informational - actual usage comes from ELF sections
            self.logger.info("  Parsed map file for memory layout info")

        except FileNotFoundError:
            self.logger.warning(f"Map file not found: {map_file}")
        except Exception as e:
            self.logger.warning(f"Failed to parse map file: {e}")


class CallGraphAnalyzer:
    """Handles call graph analysis and stack cost calculation."""

    def __init__(self, data: AnalysisData, show_warnings: bool = True):
        self.data = data
        self.show_warnings = show_warnings
        self.logger = logging.getLogger(__name__)

    def resolve_symbols(self) -> None:
        """Resolve function references across object files."""
        for func_name, callees in list(self.data.call_graph.items()):
            resolved_callees = set()

            for callee in callees:
                if callee.startswith('@'):
                    resolved_callees.add(callee)
                elif '@' in callee:
                    addr_key = callee
                    if addr_key in self.data.addresses:
                        resolved_callees.add(self.data.addresses[addr_key])
                    else:
                        self.data.unresolved.add(callee)
                elif callee in self.data.global_name:
                    resolved_callees.add(self.data.global_name[callee])
                else:
                    self.data.unresolved.add(callee)

            self.data.call_graph[func_name] = resolved_callees

    def trace_call_graph(self) -> None:
        """Calculate stack costs through DFS traversal."""
        self.logger.info("Analyzing call graph...")

        def trace(func_name: str) -> None:
            if func_name in self.data.visited:
                if self.data.visited[func_name] == "?":
                    self.data.visited[func_name] = "R"
                    self.data.total_cost[func_name] = float('inf')
                    self.data.call_depth[func_name] = float('inf')
                return

            self.data.visited[func_name] = "?"

            if func_name in self.data.has_function_pointer:
                self.data.visited[func_name] = "P"
                self.data.total_cost[func_name] = float('inf')
                self.data.call_depth[func_name] = float('inf')
                return

            max_depth = 0
            max_frame = 0

            if func_name in self.data.call_graph:
                for callee in self.data.call_graph[func_name]:
                    self.data.has_caller.add(callee)
                    trace(callee)

                    callee_cost = self.data.total_cost.get(callee, 0)
                    callee_depth = self.data.call_depth.get(callee, 0)

                    if callee_cost == float('inf') or callee_depth == float('inf'):
                        self.data.visited[func_name] = "U"
                        self.data.total_cost[func_name] = float('inf')
                        self.data.call_depth[func_name] = float('inf')
                        return

                    max_frame = max(max_frame, callee_cost)
                    max_depth = max(max_depth, callee_depth)

            self.data.call_depth[func_name] = max_depth + 1
            self.data.total_cost[func_name] = max_frame + self.data.frame_size.get(func_name, 0)

            if self.data.visited[func_name] == "?":
                self.data.visited[func_name] = " "

        for func_name in self.data.call_graph:
            trace(func_name)


class StackAnalyzer:
    """
    Main orchestrator for ARM stack usage analysis.

    Coordinates the parsing, analysis, and reporting components:
    - ObjectFileParser: Parses object files, .su files, and ELF binaries
    - CallGraphAnalyzer: Resolves symbols and calculates stack costs
    - Report generation methods for various output formats
    """

    def __init__(
            self,
            build_dir: str,
            threshold: int = 10,
            show_warnings: bool = True,
            objdump_path: str = DEFAULT_OBJDUMP,
            stack_margin: float = DEFAULT_STACK_MARGIN):
        """
        Initialize the stack analyzer.

        Args:
            build_dir: Path to build directory containing object files
            threshold: Minimum stack usage threshold for reporting (bytes)
            show_warnings: Whether to display symbol resolution warnings
            objdump_path: Path to objdump executable
            stack_margin: Safety margin multiplier for thread stack recommendations
        """
        self.build_dir = Path(build_dir)
        self.threshold = threshold
        self.show_warnings = show_warnings
        self.objdump_path = objdump_path
        self.stack_margin = stack_margin
        self.logger = logging.getLogger(__name__)

        # Shared data container
        self._data = AnalysisData()

        # Component classes
        self._parser = ObjectFileParser(self.build_dir, objdump_path, self._data)
        self._analyzer = CallGraphAnalyzer(self._data, show_warnings)

        # Expose data attributes for backward compatibility
        self.frame_size = self._data.frame_size
        self.call_graph = self._data.call_graph
        self.total_cost = self._data.total_cost
        self.call_depth = self._data.call_depth
        self.visited = self._data.visited
        self.has_caller = self._data.has_caller
        self.unresolved = self._data.unresolved
        self.addresses = self._data.addresses
        self.global_name = self._data.global_name
        self.ambiguous = self._data.ambiguous
        self.has_function_pointer = self._data.has_function_pointer
        self.rtl_available = self._data.rtl_available
        self.code_size = self._data.code_size
        self.elf_code_size = self._data.elf_code_size
        self.elf_file = self._data.elf_file
        self.data_size = self._data.data_size
        self.bss_size = self._data.bss_size
        self.static_size = self._data.static_size

        # ELF-based static sizes (accurate after linking)
        self.elf_data_size = self._data.elf_data_size
        self.elf_bss_size = self._data.elf_bss_size
        self.func_static_vars = self._data.func_static_vars
        self.has_heap_alloc = self._data.has_heap_alloc
        self.git_info = self._data.git_info
        self.detected_threads = self._data.detected_threads
        self.symbol_sections = self._data.symbol_sections
        self.section_sizes = self._data.section_sizes
        self.section_symbols = self._data.section_symbols

    def find_object_files(self) -> List[str]:
        """Locate all relevant object files in the build directory."""
        if not self.build_dir.exists():
            raise FileNotFoundError(f"Build directory '{self.build_dir}' does not exist")
        return self._parser.find_object_files()

    def _find_rtl_files(self, obj_files: List[str]) -> List[str]:
        """
        Find RTL dump files corresponding to object files.

        RTL files are generated with -fdump-rtl-dfinish and have extensions like:
        - .c.270r.dfinish (GCC 5.x)
        - .c.271r.dfinish (GCC 6.x)
        - .c.272r.dfinish (GCC 7.x+)

        Args:
            obj_files: List of object file paths

        Returns:
            List of RTL dump file paths
        """
        rtl_files = []

        for obj_file in obj_files:
            # Get base name for RTL file search
            if obj_file.endswith('.o'):
                base_name = obj_file[:-2]  # Remove .o
            elif obj_file.endswith('.c.obj'):
                base_name = obj_file[:-6]  # Remove .c.obj
            else:
                continue

            # Search for RTL dump files with various extensions
            rtl_pattern = f"{base_name}.c.*r.dfinish"
            matching_files = glob.glob(rtl_pattern)

            if matching_files:
                # Use the first matching RTL file (should be only one)
                rtl_files.append(matching_files[0])

        return rtl_files

    def _detect_git_info(self) -> None:
        """
        Detect git repository information from current working directory.

        Extracts:
        - Git commit hash (full and short)
        - Current branch name
        - Repository status (clean/dirty)
        - Remote origin URL (if available)
        """
        try:
            # Check if we're in a git repository
            result = subprocess.run(['git', 'rev-parse', '--is-inside-work-tree'],
                                    capture_output=True, text=True, cwd=os.getcwd(),
                                    timeout=SUBPROCESS_TIMEOUT)

            if result.returncode != 0:
                self.logger.debug("Not in a git repository")
                return

            # Get commit hash (full)
            result = subprocess.run(['git', 'rev-parse', 'HEAD'],
                                    capture_output=True, text=True, cwd=os.getcwd(),
                                    timeout=SUBPROCESS_TIMEOUT)
            if result.returncode == 0:
                self.git_info['commit_hash'] = result.stdout.strip()
                self.git_info['commit_hash_short'] = result.stdout.strip()[:8]

            # Get current branch name
            result = subprocess.run(['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
                                    capture_output=True, text=True, cwd=os.getcwd(),
                                    timeout=SUBPROCESS_TIMEOUT)
            if result.returncode == 0:
                self.git_info['branch'] = result.stdout.strip()

            # Check if repository is clean
            result = subprocess.run(['git', 'status', '--porcelain'],
                                    capture_output=True, text=True, cwd=os.getcwd(),
                                    timeout=SUBPROCESS_TIMEOUT)
            if result.returncode == 0:
                self.git_info['is_clean'] = len(result.stdout.strip()) == 0
                self.git_info['status'] = 'clean' if self.git_info['is_clean'] else 'dirty'

            # Get remote origin URL (if available)
            result = subprocess.run(['git', 'remote', 'get-url', 'origin'],
                                    capture_output=True, text=True, cwd=os.getcwd(),
                                    timeout=SUBPROCESS_TIMEOUT)
            if result.returncode == 0:
                self.git_info['remote_url'] = result.stdout.strip()

            # Get commit message (first line)
            result = subprocess.run(['git', 'log', '-1', '--pretty=format:%s'],
                                    capture_output=True, text=True, cwd=os.getcwd(),
                                    timeout=SUBPROCESS_TIMEOUT)
            if result.returncode == 0:
                self.git_info['commit_message'] = result.stdout.strip()

            # Get commit author and date
            result = subprocess.run(['git', 'log', '-1', '--pretty=format:%an'],
                                    capture_output=True, text=True, cwd=os.getcwd(),
                                    timeout=SUBPROCESS_TIMEOUT)
            if result.returncode == 0:
                self.git_info['commit_author'] = result.stdout.strip()

            result = subprocess.run(['git', 'log', '-1', '--pretty=format:%ci'],
                                    capture_output=True, text=True, cwd=os.getcwd(),
                                    timeout=SUBPROCESS_TIMEOUT)
            if result.returncode == 0:
                self.git_info['commit_date'] = result.stdout.strip()

            if self.git_info:
                branch = self.git_info.get('branch', 'unknown')
                commit = self.git_info.get('commit_hash_short', 'unknown')
                self.logger.info(f"  ✓ Git repository detected: {branch}@{commit}")
                if not self.git_info.get('is_clean', True):
                    self.logger.info("  ⚠ Repository has uncommitted changes")

        except FileNotFoundError:
            self.logger.debug("Git not available")
        except Exception as e:
            if self.show_warnings:
                self.logger.warning(f"⚠️ Error detecting git info: {e}")

    def check_prerequisites(self) -> None:
        """
        Verify that all required tools and files are available for analysis.

        Checks for:
        - ARM objdump tool availability
        - Build directory existence
        - Presence of object files and stack usage files

        Returns:
            List of object files to process

        Raises:
            SystemExit: If prerequisites are not met
        """
        self.logger.info("🔍 Checking prerequisites...")

        # Detect git repository information
        self._detect_git_info()

        # Verify ARM toolchain availability
        try:
            subprocess.run([self.objdump_path, "--version"], capture_output=True, check=True,
                           timeout=SUBPROCESS_TIMEOUT)
            self.logger.info(f"  ✓ {self.objdump_path} found")
        except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
            error_msg = (f"{Colors.RED}❌ Error: {self.objdump_path} not found or timed out. "
                         f"Please install ARM GCC toolchain or specify correct path with --objdump.{Colors.END}")
            print(error_msg)
            sys.exit(1)

        # Verify build directory
        if not self.build_dir.exists():
            print(f"{Colors.RED}❌ Error: Build directory '{self.build_dir}' does not exist.{Colors.END}")
            print(f"{Colors.YELLOW}💡 Please run cmake and build the project first.{Colors.END}")
            sys.exit(1)

        # Locate object files
        obj_files = self.find_object_files()
        self.logger.info(f"  ✓ Found {len(obj_files)} object files")

        # Verify stack usage files exist
        su_files = []
        for obj_file in obj_files:
            # Handle both .o and .c.obj extensions
            if obj_file.endswith('.o'):
                su_file = obj_file[:-2] + '.su'
            elif obj_file.endswith('.c.obj'):
                su_file = obj_file[:-6] + '.c.su'
            else:
                continue

            if os.path.exists(su_file):
                su_files.append(su_file)

        if not su_files:
            print(f"{Colors.RED}❌ Error: No stack usage files (.su) found.{Colors.END}")
            print(f"{Colors.YELLOW}💡 Please compile with -fstack-usage flag to generate .su files.{Colors.END}")
            print(f"{Colors.YELLOW}💡 Add '-fstack-usage' to your CMakeLists.txt target_compile_options.{Colors.END}")
            sys.exit(1)

        self.logger.info(f"  ✓ Found {len(su_files)} stack usage files (from {len(obj_files)} object files)")

        # Check for RTL dump files for function pointer detection
        rtl_files = self._find_rtl_files(obj_files)
        if rtl_files:
            self.rtl_available = True
            self.logger.info(f"  ✓ Found {len(rtl_files)} RTL dump files for function pointer detection")
        else:
            self.logger.info("  ⚠ No RTL dump files found. Function pointer detection disabled.")
            self.logger.info("  💡 Compile with -fdump-rtl-dfinish for enhanced analysis.")

        return obj_files

    def parse_object_files(self, obj_files: List[str]) -> None:
        """
        Parse all object files to extract call graph and stack usage information.

        Args:
            obj_files: List of object file paths to process
        """
        self.logger.info(f"Parsing {len(obj_files)} object files...")

        for i, obj_file in enumerate(obj_files, 1):
            if i % 50 == 0 or i == len(obj_files):
                self.logger.debug(f"Progress: {i}/{len(obj_files)} files processed")

            self._parser.parse_disassembly(obj_file)
            self._parser.parse_su_file(obj_file)
            self._parse_code_sizes(obj_file)
            self._parser.parse_static_sizes(obj_file)

        if self._data.rtl_available:
            self._parse_rtl_files(obj_files)

        self.logger.info("Parsing complete")

    def _parse_disassembly(self, obj_file: str) -> None:
        """
        Parse objdump disassembly output to build function call graph.

        Extracts:
        - Function definitions and their addresses
        - Function call relationships via relocation entries
        - Symbol address mappings for resolution

        Args:
            obj_file: Path to object file to disassemble

        Raises:
            SystemExit: If disassembly fails
        """
        try:
            result = subprocess.run([self.objdump_path, "-dr", obj_file],
                                    capture_output=True, text=True, check=True,
                                    timeout=SUBPROCESS_TIMEOUT)

            current_function = None

            for line in result.stdout.splitlines():
                line = line.strip()

                # Match function definition: "00000000 <function_name>:"
                func_match = re.match(r'^([0-9a-fA-F]+) <(.*)>:', line)
                if func_match:
                    addr, name = func_match.groups()
                    current_function = f"{name}@{obj_file}"
                    self.call_graph[current_function] = set()

                    # Track ambiguous function names across object files
                    if name in self.global_name:
                        self.ambiguous.add(name)
                    self.global_name[name] = current_function

                    # Store address mapping for symbol resolution
                    addr = addr.lstrip('0') or '0'
                    self.addresses[f"{addr}@{obj_file}"] = current_function

                # Match function call: ": R_ARM_CALL target"
                call_match = re.search(r': R_[A-Za-z0-9_]+_CALL\s+(.+)', line)
                if call_match and current_function:
                    target = call_match.group(1)

                    # Detect heap allocation function calls
                    if target in HEAP_ALLOC_FUNCTIONS:
                        self.has_heap_alloc.add(current_function)

                    # Handle different call target formats
                    if target == ".text":
                        target = f"@{obj_file}"
                    elif target.startswith(".text+0x"):
                        offset = target[9:]  # Remove ".text+0x" prefix
                        target = f"{offset}@{obj_file}"

                    self.call_graph[current_function].add(target)

        except (subprocess.CalledProcessError, subprocess.TimeoutExpired) as e:
            print(f"{Colors.RED}❌ Error disassembling {obj_file}: {e}{Colors.END}")
            sys.exit(1)

    def _parse_su_file(self, obj_file: str) -> None:
        """
        Parse stack usage (.su) file to extract function frame sizes.

        The .su file format is: "path:line:column:function_name size qualifier"
        Frame sizes are adjusted by adding the ARM call overhead cost.

        Args:
            obj_file: Object file path (corresponding .su file will be located)
        """
        # Handle both .o and .c.obj extensions
        if obj_file.endswith('.o'):
            su_file = obj_file[:-2] + '.su'
        elif obj_file.endswith('.c.obj'):
            su_file = obj_file[:-6] + '.c.su'
        else:
            return

        try:
            with open(su_file, 'r', encoding='utf-8') as f:
                for line in f:
                    # Parse: "/path/file.c:137:20:function_name   size   qualifier"
                    match = re.search(r':([^:\t ]+)[\t ]+([0-9]+)[\t ]+', line)
                    if match:
                        func_name, size = match.groups()
                        # Add ARM function call overhead to frame size
                        self.frame_size[f"{func_name}@{obj_file}"] = int(size) + CALL_COST

        except FileNotFoundError:
            # Stack usage files may not exist for assembly files or system libraries
            pass

    def _parse_code_sizes(self, obj_file: str) -> None:
        """
        REMOVED: Object file code sizes are meaningless (include dead code).
        Use --elf option to get accurate linked code sizes.
        """
        # Object file sizes are misleading - skip entirely
        # Users must provide --elf for code size statistics
        pass

    def parse_elf_code_sizes(self, elf_file: str) -> None:
        """Parse ELF file for accurate linked code and static sizes."""
        self._parser.parse_elf(elf_file)

    def parse_map_file(self, map_file: str) -> None:
        """Parse linker map file for memory region details."""
        self._parser.parse_map_file(map_file)

    def _parse_static_sizes(self, obj_file: str) -> None:
        """
        Parse object file to extract static allocation sizes using nm.

        Uses arm-none-eabi-nm to get .data and .bss symbol sizes from object files.
        Separates initialized (.data) from uninitialized (.bss) data.
        Also detects per-function static variables (named like func.varname).

        Args:
            obj_file: Object file path to analyze
        """
        nm_path = self.objdump_path.replace('objdump', 'nm')

        try:
            result = subprocess.run(
                [nm_path, '--print-size', obj_file],
                capture_output=True, text=True, check=True,
                timeout=SUBPROCESS_TIMEOUT
            )

            total_data = 0
            total_bss = 0
            for line in result.stdout.splitlines():
                # Format: "address size type name"
                # D/d = initialized data (.data), B/b = uninitialized data (.bss)
                parts = line.strip().split()
                if len(parts) >= 4:
                    size_hex, sym_type, sym_name = parts[1], parts[2], parts[3]
                    try:
                        size = int(size_hex, 16)
                    except ValueError:
                        continue

                    # Separate .data (D/d) from .bss (B/b)
                    if sym_type in ('D', 'd'):
                        total_data += size
                        var_type = 'data'
                    elif sym_type in ('B', 'b'):
                        total_bss += size
                        var_type = 'bss'
                    else:
                        continue

                    # Detect per-function static variables (pattern: func.varname or func.N)
                    if '.' in sym_name:
                        func_name = sym_name.split('.')[0]
                        var_name = sym_name.split('.', 1)[1]
                        if func_name not in self.func_static_vars:
                            self.func_static_vars[func_name] = []
                        self.func_static_vars[func_name].append((var_name, size, var_type))

            if total_data > 0:
                self.data_size[obj_file] = total_data
            if total_bss > 0:
                self.bss_size[obj_file] = total_bss
            if total_data + total_bss > 0:
                self.static_size[obj_file] = total_data + total_bss

        except (subprocess.CalledProcessError, subprocess.TimeoutExpired):
            pass
        except FileNotFoundError:
            pass

    def detect_thread_entries(self) -> None:
        """
        Detect RTOS thread/task entry functions by scanning source files.

        Searches for common RTOS task creation patterns (FreeRTOS, Zephyr, etc.)
        and extracts the thread entry function names for stack analysis.
        """
        self.logger.info("🔍 Detecting RTOS thread entry points...")

        # Find all C source files in build directory and parent
        source_dirs = [self.build_dir]
        if self.build_dir.parent != self.build_dir:
            source_dirs.append(self.build_dir.parent)

        source_files = []
        for src_dir in source_dirs:
            source_files.extend(glob.glob(str(src_dir / "**/*.c"), recursive=True))
            source_files.extend(glob.glob(str(src_dir / "**/*.cpp"), recursive=True))

        detected_entries = {}  # entry_func -> (rtos, source_file)

        for source_file in source_files:
            try:
                with open(source_file, 'r', encoding='utf-8', errors='ignore') as f:
                    content = f.read()

                for rtos_name, patterns in RTOS_THREAD_PATTERNS.items():
                    for pattern, _, _ in patterns:
                        matches = re.findall(pattern, content)
                        for match in matches:
                            entry_func = match if isinstance(match, str) else match[0]
                            if entry_func and entry_func not in detected_entries:
                                detected_entries[entry_func] = (rtos_name, source_file)

            except (IOError, OSError):
                continue

        # Build ThreadInfo for each detected entry
        for entry_func, (rtos_name, source_file) in detected_entries.items():
            # Find the function's stack usage
            stack_usage = 0
            is_unbounded = False

            # Search for the function in our analyzed data
            for func_key, cost in self.total_cost.items():
                func_name = func_key.split('@')[0] if '@' in func_key else func_key
                if func_name == entry_func:
                    if cost == float('inf'):
                        is_unbounded = True
                        stack_usage = 0
                    else:
                        stack_usage = cost
                    break

            # Calculate recommended size (round up to nearest power of 2 or 256)
            if is_unbounded:
                recommended = 0
            else:
                with_margin = int(stack_usage * self.stack_margin)
                # Round up to nearest 256 bytes
                recommended = ((with_margin + 255) // 256) * 256
                # Minimum 512 bytes
                recommended = max(recommended, 512)

            thread_info = ThreadInfo(
                entry_func=entry_func,
                rtos=rtos_name,
                source_file=os.path.basename(source_file),
                stack_usage=stack_usage,
                recommended=recommended,
                is_unbounded=is_unbounded
            )
            self.detected_threads.append(thread_info)

        if self.detected_threads:
            self.logger.info(f"  ✓ Detected {len(self.detected_threads)} thread entry points")
        else:
            self.logger.info("  ✓ No RTOS thread patterns detected")

    def _parse_rtl_files(self, obj_files: List[str]) -> None:
        """
        Parse RTL dump files to detect function pointer calls.

        RTL dumps contain detailed information about function calls including
        indirect calls via function pointers, which make stack analysis unbounded.

        Args:
            obj_files: List of object file paths to find corresponding RTL files
        """
        self.logger.info("🔍 Analyzing RTL dumps for function pointer detection...")

        rtl_files = self._find_rtl_files(obj_files)
        functions_with_pointers = 0

        for rtl_file in rtl_files:
            try:
                self._parse_single_rtl_file(rtl_file)
            except Exception as e:
                if self.show_warnings:
                    self.logger.warning(f"⚠️ Error parsing RTL file {rtl_file}: {e}")

        functions_with_pointers = len(self.has_function_pointer)
        if functions_with_pointers > 0:
            self.logger.info(f"  ✓ Detected {functions_with_pointers} functions with function pointer calls")
        else:
            self.logger.info("  ✓ No function pointer calls detected")

    def _parse_single_rtl_file(self, rtl_file: str) -> None:
        """
        Parse a single RTL dump file to detect function pointer calls.

        RTL format analysis:
        - Function definitions: ";; Function function_name (symbol_name, funcdef_no=N)"
        - Direct calls: '(call ... "function_name" ...)'
        - Indirect calls: '(call ...' without quoted function name

        Args:
            rtl_file: Path to RTL dump file
        """
        # Extract object file path from RTL file for function mapping
        if '.c.' in rtl_file and rtl_file.endswith('.dfinish'):
            # Convert RTL filename back to object file
            base_name = rtl_file.split('.c.')[0]
            obj_file = base_name + '.o'
            if not os.path.exists(obj_file):
                obj_file = base_name + '.c.obj'
        else:
            return

        current_function = None

        # Regex patterns for RTL analysis
        function_pattern = re.compile(r'^;; Function (.*) \((\S+), funcdef_no=\d+.*\).*$')
        # Direct calls have symbol_ref with quoted function names
        direct_call_pattern = re.compile(r'.*\(call.*symbol_ref.*"([^"]+)".*\).*')
        # Indirect calls use registers instead of symbol_ref
        indirect_call_pattern = re.compile(r'.*\(call.*\(mem:SI \(reg.*\).*\).*')

        try:
            with open(rtl_file, 'r', encoding='utf-8', errors='ignore') as f:
                for line in f:
                    line = line.strip()

                    # Match function definition
                    func_match = function_pattern.match(line)
                    if func_match:
                        symbol_name = func_match.group(2)
                        current_function = f"{symbol_name}@{obj_file}"
                        continue

                    # Skip if no current function context
                    if not current_function:
                        continue

                    # Check for direct function calls (these are safe)
                    if direct_call_pattern.match(line):
                        continue

                    # Check for indirect function calls (function pointers)
                    if indirect_call_pattern.match(line):
                        self.has_function_pointer.add(current_function)
                        if self.show_warnings:
                            func_name = current_function.split('@')[0]
                            self.logger.debug(f"  Function pointer call detected in {func_name}")

        except FileNotFoundError:
            if self.show_warnings:
                self.logger.warning(f"⚠️ RTL file not found: {rtl_file}")
        except Exception as e:
            if self.show_warnings:
                self.logger.warning(f"⚠️ Error reading RTL file {rtl_file}: {e}")

    def resolve_symbols(self) -> None:
        """Resolve function call targets using symbol tables."""
        self.logger.info("Resolving symbols...")
        self._analyzer.resolve_symbols()

    def create_interrupt_node(self) -> None:
        """Create virtual interrupt node for ISR analysis."""
        self._data.call_graph["INTERRUPT"] = set()
        for func_name in self._data.call_graph:
            if "__vector_" in func_name:
                self._data.call_graph["INTERRUPT"].add(func_name)

    def trace_call_graph(self, quiet: bool = False) -> None:
        """Traverse the call graph to calculate stack costs."""
        self._analyzer.trace_call_graph()

    def _get_code_size(self, func_full_name: str) -> int:
        """Get code size for a function, preferring ELF (linked) over object file."""
        if self.elf_code_size:
            # Use ELF code size (by function name, not full path)
            base_name = func_full_name.split('@')[0] if '@' in func_full_name else func_full_name
            return self.elf_code_size.get(base_name, 0)
        else:
            # Fallback to object file code size
            return self.code_size.get(func_full_name, 0)

    def _prepare_function_data(self) -> tuple:
        """
        Prepare function data and file statistics for reporting.

        Returns:
            Tuple of (functions, file_stats, main_cost, max_iv_cost)
        """
        functions = []
        file_stats = defaultdict(lambda: {'count': 0, 'total_cost': 0, 'max_cost': 0, 'functions': []})
        max_iv_cost = 0
        main_cost = 0

        for func_full_name in sorted(self.total_cost.keys(),
                                     key=lambda x: self.total_cost[x], reverse=True):

            # Extract clean function name and source file using partition for efficiency
            display_name = func_full_name
            source_file = "unknown"

            if '@' in func_full_name:
                base_name, _, obj_file = func_full_name.partition('@')

                # Extract source file name from object file path
                if '/' in obj_file:
                    source_file = os.path.basename(obj_file).replace('.c.obj', '.c').replace('.o', '')
                else:
                    source_file = obj_file.replace('.c.obj', '.c').replace('.o', '')

                # Use clean name if not ambiguous
                if base_name not in self.ambiguous:
                    display_name = base_name

            # Determine function characteristics
            visit_status = self.visited.get(func_full_name, ' ')
            is_recursive = visit_status == 'R'
            is_root = func_full_name not in self.has_caller
            cost = self.total_cost[func_full_name]

            # Determine unbounded status and reason
            is_unbounded = cost == float('inf')
            unbounded_reason = None
            if is_unbounded:
                if visit_status == 'R':
                    unbounded_reason = 'recursion'
                elif visit_status == 'P':
                    unbounded_reason = 'function_pointer'
                elif visit_status == 'U':
                    unbounded_reason = 'unbounded_callee'
                else:
                    unbounded_reason = 'unknown'

            # Track special functions for summary (skip unbounded functions)
            if not is_unbounded:
                if "__vector_" in func_full_name:
                    max_iv_cost = max(max_iv_cost, cost)
                elif func_full_name.startswith("main@"):
                    main_cost = cost

            # Get static sizes for this file (separate .data and .bss)
            _, _, obj_file_path = func_full_name.partition('@')
            file_data_size = self.data_size.get(obj_file_path, 0)
            file_bss_size = self.bss_size.get(obj_file_path, 0)

            # Check if function has heap allocation calls
            has_heap = func_full_name in self.has_heap_alloc

            func_info = FunctionInfo(
                name=display_name,
                cost=cost,
                frame_size=self.frame_size.get(func_full_name, 0),
                height=self.call_depth.get(func_full_name, 0),
                is_recursive=is_recursive,
                is_root=is_root,
                is_unbounded=is_unbounded,
                unbounded_reason=unbounded_reason,
                code_size=self._get_code_size(func_full_name),
                data_size=file_data_size,
                bss_size=file_bss_size,
                has_heap_alloc=has_heap
            )

            functions.append(func_info)

            # Update file statistics
            if cost > 0:
                file_stats[source_file]['count'] += 1
                file_stats[source_file]['total_cost'] += cost
                file_stats[source_file]['max_cost'] = max(file_stats[source_file]['max_cost'], cost)
                file_stats[source_file]['functions'].append((display_name, cost, is_root))

        return functions, file_stats, main_cost, max_iv_cost

    def generate_report(self) -> Dict:
        """
        Generate and display comprehensive stack usage analysis report.

        The report includes:
        - File-based stack usage summary
        - Detailed function table with costs and depths
        - Peak stack usage estimates
        - Unresolved function warnings
        """
        print(f"\n{Colors.BOLD}{Colors.HEADER}{'='*80}{Colors.END}")
        print(f"{Colors.BOLD}{Colors.HEADER}📈 STACK USAGE ANALYSIS REPORT{Colors.END}")
        print(f"{Colors.BOLD}{Colors.HEADER}{'='*80}{Colors.END}\n")

        # Prepare function data and file statistics
        functions, file_stats, main_cost, max_iv_cost = self._prepare_function_data()

        # Generate report sections
        self._print_file_hierarchy(file_stats)
        self._print_function_table(functions)
        self._print_summary(main_cost, max_iv_cost)
        self._print_unresolved()
        self._print_thread_recommendations()

        # Return data for potential JSON export
        return self._build_analysis_data(functions, file_stats, main_cost, max_iv_cost)

    def generate_analysis_data(self) -> Dict:
        """
        Generate analysis data without printing report (for JSON mode).

        Returns:
            Analysis data dictionary
        """
        functions, file_stats, main_cost, max_iv_cost = self._prepare_function_data()
        return self._build_analysis_data(functions, file_stats, main_cost, max_iv_cost)

    def generate_short_report(self) -> None:
        """
        Generate a short report with only function names and stack usage.

        Outputs a simple sorted list of functions with their stack costs.
        """
        # Collect functions with their costs
        function_costs = []

        for func_full_name in self.total_cost.keys():
            cost = self.total_cost[func_full_name]
            if cost >= self.threshold or cost == float('inf'):
                # Extract clean function name
                display_name = func_full_name
                if '@' in func_full_name:
                    base_name = func_full_name.split('@')[0]
                    # Use clean name if not ambiguous
                    if base_name not in self.ambiguous:
                        display_name = base_name

                cost_display = "unbounded" if cost == float('inf') else str(cost)
                function_costs.append((display_name, cost, cost_display))

        # Sort by cost (unbounded first, then descending)
        function_costs.sort(key=lambda x: (0 if x[1] == float('inf') else 1, -x[1] if x[1] != float('inf') else 0))

        # Output the list
        for func_name, _, cost_display in function_costs:
            print(f"{func_name}: {cost_display}")

    def _build_analysis_data(
            self,
            functions: List[FunctionInfo],
            file_stats: Dict,
            main_cost: int,
            max_iv_cost: int) -> Dict:
        """
        Build the analysis data dictionary.

        Args:
            functions: List of function information
            file_stats: File statistics dictionary
            main_cost: Main function cost
            max_iv_cost: Maximum interrupt cost

        Returns:
            Analysis data dictionary
        """
        metadata = {
            'timestamp': datetime.now().isoformat(),
            'build_dir': str(self.build_dir),
            'threshold': self.threshold,
            'total_functions': len(functions),
            'functions_analyzed': len([f for f in functions if f.cost > 0]),
            'rtl_analysis_enabled': self.rtl_available,
            'code_size_source': 'elf' if self.elf_file else 'object_files',
            'elf_file': self.elf_file
        }

        # Add git information if available
        if self.git_info:
            metadata['git'] = self.git_info.copy()

        # Calculate RAM totals
        total_data = sum(self.elf_data_size.values()) if self.elf_data_size else sum(self.data_size.values())
        total_bss = sum(self.elf_bss_size.values()) if self.elf_bss_size else sum(self.bss_size.values())
        total_static = total_data + total_bss
        stack_peak = main_cost + max_iv_cost
        heap_funcs = len(self.has_heap_alloc)

        return {
            'metadata': metadata,
            'summary': {
                'main_cost': main_cost,
                'max_interrupt_cost': max_iv_cost,
                'total_peak_estimate': stack_peak,
                'max_single_function': max((f.cost for f in functions if f.cost != float('inf')), default=0),
                'average_stack_usage': sum(f.cost for f in functions if f.cost != float('inf')) // max(len([f for f in functions if f.cost != float('inf')]), 1),
                'total_code_size': sum(self.elf_code_size.values()) if self.elf_code_size else None,
                'max_code_size': max(self.elf_code_size.values()) if self.elf_code_size else None,
                # RAM analysis
                'total_data_size': total_data,
                'total_bss_size': total_bss,
                'total_static_size': total_static,
                'estimated_ram_usage': stack_peak + total_static,
                'functions_with_heap': heap_funcs,
                'heap_usage_detected': heap_funcs > 0
            },
            'functions': [
                {
                    'name': func.name,
                    'total_cost': func.cost if not func.is_unbounded else 'unbounded',
                    'frame_size': func.frame_size,
                    'call_depth': func.height if func.height != float('inf') else 'unbounded',
                    'is_recursive': func.is_recursive,
                    'is_root': func.is_root,
                    'is_unbounded': func.is_unbounded,
                    'unbounded_reason': func.unbounded_reason,
                    'code_size': func.code_size,
                    'data_size': func.data_size,
                    'bss_size': func.bss_size,
                    'has_heap_alloc': func.has_heap_alloc
                }
                for func in functions if func.cost > 0 or func.is_unbounded
            ],
            'files': {
                filename: {
                    'function_count': stats['count'],
                    'total_cost': stats['total_cost'],
                    'max_cost': stats['max_cost'],
                    'functions': [
                        {'name': name, 'cost': cost, 'is_root': is_root}
                        for name, cost, is_root in stats['functions']
                    ]
                }
                for filename, stats in file_stats.items()
                if stats['total_cost'] > 0
            },
            'ram': {
                'data_size': total_data,
                'bss_size': total_bss,
                'static_total': total_static,
                'stack_peak': stack_peak,
                'estimated_total': stack_peak + total_static,
                'heap_detected': heap_funcs > 0,
                'note': 'heap size not included (dynamic)' if heap_funcs > 0 else None
            },
            'static_vars': {
                func: [{'name': n, 'size': s, 'type': t} for n, s, t in vars]
                for func, vars in self.func_static_vars.items()
            },
            'threads': [
                {
                    'entry_func': t.entry_func,
                    'rtos': t.rtos,
                    'source_file': t.source_file,
                    'stack_usage': t.stack_usage if not t.is_unbounded else 'unbounded',
                    'recommended': t.recommended if not t.is_unbounded else 'unbounded',
                    'is_unbounded': t.is_unbounded
                }
                for t in self.detected_threads
            ],
            'section_sizes': self.section_sizes,
            'symbols_by_section': {
                section: {
                    name: size for name, size in sorted(
                        symbols.items(), key=lambda x: x[1], reverse=True
                    )[:30]  # Top 30 per section
                }
                for section, symbols in self.section_symbols.items()
                if sum(symbols.values()) > 0
            } if self.section_symbols else {},
            'call_graph': {
                func: sorted(list(callees))
                for func, callees in self.call_graph.items()
                if callees  # Only include functions that call others
            },
            'unresolved': sorted(list(self.unresolved))
        }

    def _print_file_hierarchy(self, file_stats: Dict) -> None:
        """
        Display stack usage organized by source file.

        Shows top functions per file and total usage statistics.

        Args:
            file_stats: Dictionary mapping filenames to usage statistics
        """
        print(f"{Colors.BOLD}📁 Stack Usage by Source File{Colors.END}\n")

        # Sort files by total stack usage (descending)
        sorted_files = sorted(file_stats.items(),
                              key=lambda x: x[1]['total_cost'], reverse=True)

        # Display files with non-zero stack usage
        for filename, stats in sorted_files:
            if stats['total_cost'] > 0:
                # Show top 3 functions per file
                top_funcs = sorted(stats['functions'], key=lambda x: x[1], reverse=True)[:3]

                print(f"{filename}")
                for name, cost, is_root in top_funcs:
                    print(f"  - {name} ({cost} bytes)")
                print(f"  Total: {stats['total_cost']} bytes ({stats['count']} functions)\n")

    def _print_function_table(self, functions: List[FunctionInfo]) -> None:
        """
        Display detailed function stack usage table.

        Shows functions above the threshold with their costs, frame sizes,
        and call depths. Functions are sorted by total cost (descending).

        Args:
            functions: List of function information objects
        """
        # Apply threshold filter (include unbounded functions)
        filtered_functions = [f for f in functions if f.cost >= self.threshold or f.is_unbounded]

        if not filtered_functions:
            print(f"{Colors.YELLOW}⚠️  No functions with significant stack usage found{Colors.END}")
            return

        print(f"{Colors.BOLD}📋 Function Stack Usage Analysis{Colors.END}")
        threshold_msg = (f"   (Showing {len(filtered_functions)} functions with stack usage "
                         f"≥{self.threshold} bytes or unbounded)")
        print(f"{Colors.CYAN}{threshold_msg}{Colors.END}")
        frame_msg = "   Total = Frame + Max(Callees), Frame = Local variables, Depth = Call chain length"
        print(f"{Colors.CYAN}{frame_msg}{Colors.END}")
        flash_msg = "   Flash = Code size, Static = .data+.bss per source file"
        print(f"{Colors.CYAN}{flash_msg}{Colors.END}")
        symbols_msg = "   Symbols: ▶=Root, 🔄=Recursive, ⚠=Function pointer, ❌=Unbounded, 🗑=Heap alloc"
        print(f"{Colors.CYAN}{symbols_msg}{Colors.END}\n")

        # Table header with proper alignment
        header = f"{'Flag':<5}{'Function Name':<40} {'Total':<9} {'Frame':<7} {'Depth':<6} {'Flash':<7} {'Static':<7}"
        print(f"{Colors.BOLD}{Colors.UNDERLINE}{header}{Colors.END}")
        separator = (f"{'─────':<5}{'────────────────────────────────────────':<40} "
                     f"{'─────────':<9} {'─────':<7} {'─────':<6} {'─────':<7} {'──────':<7}")
        print(f"{Colors.BOLD}{Colors.UNDERLINE}{separator}{Colors.END}")

        # Display function rows
        for func in filtered_functions:
            self._print_function_row(func, Colors.END)

        # Summary information
        very_low_cost = len([f for f in functions if f.cost < self.threshold and f.cost > 0])
        if very_low_cost > 0:
            low_cost_msg = (f"\n{Colors.CYAN}💭 {very_low_cost} functions with very low cost "
                            f"(<{self.threshold} bytes) hidden for clarity{Colors.END}")
            print(low_cost_msg)

        displayed_count = len(filtered_functions)
        total_with_usage = len([f for f in functions if f.cost > 0])
        summary_msg = (f"\n{Colors.BOLD}📊 Displayed {displayed_count} of {total_with_usage} "
                       f"functions with stack usage{Colors.END}")
        print(summary_msg)

    def _print_function_row(self, func: FunctionInfo, color: str) -> None:
        """
        Print a single function row in the analysis table.

        Uses consistent formatting with visual indicators for function types:
        - ▶ for root functions (entry points)
        - 🔄 for recursive functions
        - ⚠ for functions with function pointer calls
        - ❌ for unbounded functions (other reasons)
        - Color coding based on stack cost

        Args:
            func: Function information object
            color: Base color for the row
        """
        # Determine function type indicator with consistent spacing
        if func.is_unbounded:
            if func.unbounded_reason == 'recursion':
                flag = f"{Colors.RED}🔄{Colors.END}  "  # Recursive function
            elif func.unbounded_reason == 'function_pointer':
                flag = f"{Colors.YELLOW}⚠{Colors.END}   "  # Function pointer call
            else:
                flag = f"{Colors.RED}❌{Colors.END}  "  # Other unbounded reason
        elif func.has_heap_alloc:
            flag = f"{Colors.YELLOW}🗑{Colors.END}   "  # Heap allocation
        elif func.is_root:
            flag = f"{Colors.GREEN}▶{Colors.END}   "  # Root function
        else:
            flag = "     "  # Regular function

        # Apply cost-based color coding
        cost_display = str(func.cost)

        if func.is_unbounded:
            cost_display = "unbounded"
        # Color coding is applied directly in the row formatting below

        # Handle long function names
        display_name = func.name
        if len(display_name) > MAX_FUNCTION_NAME_LEN:
            display_name = display_name[:MAX_FUNCTION_NAME_LEN - 3] + "..."

        # Handle unbounded depth display
        depth_display = str(func.height) if func.height != float('inf') else "∞"

        # Handle flash/code size display
        flash_display = str(func.code_size) if func.code_size > 0 else "-"

        # Handle RAM allocation display (.data + .bss for this source file)
        total_static = func.data_size + func.bss_size
        static_display = str(total_static) if total_static > 0 else "-"

        # Print formatted row with consistent alignment
        row = (f"{flag}{display_name:<40} {cost_display:<9} {func.frame_size:<7} "
               f"{depth_display:<6} {flash_display:<7} {static_display:<7}")
        print(row)

    def _print_summary(self, main_cost: int, max_iv_cost: int) -> None:
        """
        Display analysis summary with peak stack usage estimates.

        Provides estimates for:
        - Main execution path stack usage
        - Worst-case interrupt handler stack usage
        - Combined peak usage estimate
        - General statistics

        Args:
            main_cost: Stack cost of main function
            max_iv_cost: Maximum interrupt handler cost
        """
        print(f"\n{Colors.BOLD}{Colors.HEADER}📊 ANALYSIS SUMMARY{Colors.END}")
        print("─" * 50)

        interrupt_cost = self.total_cost.get("INTERRUPT", 0)
        total_peak = main_cost + max_iv_cost

        print("🎯 Peak execution estimate:")
        print(f"   Main function cost:     {Colors.CYAN}{main_cost:>6}{Colors.END} bytes")
        print(f"   Worst interrupt cost:   {Colors.YELLOW}{max_iv_cost:>6}{Colors.END} bytes")
        print(f"   Virtual interrupt node: {Colors.BLUE}{interrupt_cost:>6}{Colors.END} bytes")
        total_msg = (f"   {Colors.BOLD}Total estimated peak:   "
                     f"{Colors.GREEN}{total_peak:>6}{Colors.END}{Colors.BOLD} bytes{Colors.END}")
        print(total_msg)

        # Additional statistics
        all_costs = list(self.total_cost.values())
        if all_costs:
            print("\n📈 Stack Statistics:")
            print(f"   Functions analyzed:     {Colors.CYAN}{len(all_costs):>6}{Colors.END}")
            print(f"   Average stack usage:    {Colors.YELLOW}{sum(all_costs)//len(all_costs):>6}{Colors.END} bytes")
            print(f"   Maximum single function:{Colors.RED}{max(all_costs):>6}{Colors.END} bytes")

        # Flash/code size statistics (only with ELF)
        if self.elf_code_size:
            all_code_sizes = [s for s in self.elf_code_size.values() if s > 0]
            total_flash = sum(all_code_sizes)
            print(f"\n💾 Flash Statistics (from ELF):")
            print(f"   Functions with code:    {Colors.CYAN}{len(all_code_sizes):>6}{Colors.END}")
            print(f"   Total code size:        {Colors.YELLOW}{total_flash:>6}{Colors.END} bytes ({total_flash/1024:.1f} KB)")
            print(f"   Largest function:       {Colors.RED}{max(all_code_sizes):>6}{Colors.END} bytes")
        else:
            print(f"\n💾 Flash Statistics: {Colors.YELLOW}Not available (use --elf for code sizes){Colors.END}")

        # RAM Analysis
        print(f"\n{Colors.BOLD}🗄️  RAM ANALYSIS{Colors.END}")
        print("─" * 40)

        # .data section (initialized data)
        total_data = sum(self.elf_data_size.values()) if self.elf_data_size else sum(self.data_size.values())
        # .bss section (uninitialized data)
        total_bss = sum(self.elf_bss_size.values()) if self.elf_bss_size else sum(self.bss_size.values())
        total_static = total_data + total_bss

        print(f"   .data (initialized):    {Colors.CYAN}{total_data:>6}{Colors.END} bytes")
        print(f"   .bss (uninitialized):   {Colors.CYAN}{total_bss:>6}{Colors.END} bytes")
        print(f"   Static total:           {Colors.YELLOW}{total_static:>6}{Colors.END} bytes")
        print(f"   Stack peak:             {Colors.YELLOW}{total_peak:>6}{Colors.END} bytes")

        estimated_ram = total_peak + total_static
        print(f"   {Colors.BOLD}Estimated RAM usage:    {Colors.GREEN}{estimated_ram:>6}{Colors.END}{Colors.BOLD} bytes{Colors.END}")

        # Heap allocation warning
        if self.has_heap_alloc:
            print(f"\n   {Colors.YELLOW}⚠️  Heap allocations detected in {len(self.has_heap_alloc)} functions:{Colors.END}")
            for i, func in enumerate(sorted(self.has_heap_alloc)):
                if i < 5:
                    func_name = func.split('@')[0] if '@' in func else func
                    print(f"      • {func_name}")
                elif i == 5:
                    print(f"      • ... and {len(self.has_heap_alloc) - 5} more")
                    break
            print(f"   {Colors.YELLOW}   Heap size is dynamic and NOT included in estimate{Colors.END}")

        # Per-function static variables summary
        if self.func_static_vars:
            total_func_static = sum(sum(s for _, s, _ in vars) for vars in self.func_static_vars.values())
            print(f"\n   Per-function statics:   {Colors.CYAN}{total_func_static:>6}{Colors.END} bytes in {len(self.func_static_vars)} functions")

        # Section sizes breakdown (if ELF parsed)
        if self.section_sizes:
            # Filter to RAM sections only (exclude .text, .rodata, etc.)
            ram_sections = {
                name: size for name, size in self.section_sizes.items()
                if name not in ('.text', '.rodata', '.ARM.extab', '.ARM.exidx', '.init', '.fini')
                and not name.startswith('.debug')
                and size > 0
            }

            if ram_sections:
                print(f"\n{Colors.BOLD}LINKER SECTIONS (RAM){Colors.END}")
                print("-" * 40)

                sorted_sections = sorted(ram_sections.items(), key=lambda x: x[1], reverse=True)
                total_ram = 0

                for section_name, size in sorted_sections:
                    total_ram += size
                    print(f"   {section_name:<20} {Colors.CYAN}{size:>8}{Colors.END} bytes")

                print(f"\n   {'Total RAM:':<20} {Colors.YELLOW}{total_ram:>8}{Colors.END} bytes")

        # Show top symbols per RAM section (if ELF parsed with section info)
        if self.section_symbols:
            # Filter to RAM-related sections only
            ram_section_names = [s for s in self.section_symbols.keys()
                                 if s not in ('.text', '.rodata', '.ARM.extab', '.ARM.exidx', '.init', '.fini')
                                 and not s.startswith('.debug')]

            if ram_section_names:
                print(f"\n{Colors.BOLD}TOP STATIC ALLOCATIONS BY SECTION{Colors.END}")
                print("-" * 55)

                for section in sorted(ram_section_names):
                    symbols = self.section_symbols[section]
                    section_total = sum(symbols.values())
                    if section_total < 100:
                        continue

                    sorted_syms = sorted(symbols.items(), key=lambda x: x[1], reverse=True)[:10]
                    print(f"\n   {Colors.CYAN}{section}{Colors.END} ({section_total} bytes total):")
                    for name, size in sorted_syms:
                        if size >= 100:
                            print(f"      {name:<40} {size:>8} bytes")

    def _print_unresolved(self) -> None:
        """
        Display list of unresolved function references.

        These are typically external library functions or system calls
        that don't have corresponding object files in the build directory.
        """
        if self.unresolved:
            print(f"\n{Colors.YELLOW}{Colors.BOLD}⚠️  UNRESOLVED FUNCTIONS{Colors.END}")
            print("─" * 30)
            print(f"{Colors.YELLOW}The following functions could not be resolved:{Colors.END}")

            # Display limited list to avoid overwhelming output
            sorted_unresolved = sorted(self.unresolved)
            for i, func in enumerate(sorted_unresolved):
                if i < MAX_UNRESOLVED_DISPLAY:
                    print(f"   • {func}")
                elif i == MAX_UNRESOLVED_DISPLAY:
                    print(f"   • ... and {len(sorted_unresolved) - MAX_UNRESOLVED_DISPLAY} more")
                    break

    def _print_thread_recommendations(self) -> None:
        """
        Display thread stack size recommendations.

        Shows detected RTOS threads with their calculated stack usage
        and recommended stack sizes including safety margin.
        """
        if not self.detected_threads:
            return

        print(f"\n{Colors.BOLD}{Colors.HEADER}🧵 THREAD STACK RECOMMENDATIONS{Colors.END}")
        print("─" * 60)
        print(f"{Colors.CYAN}Safety margin: {self.stack_margin:.1f}x "
              f"(configure with --stack-margin){Colors.END}\n")

        # Table header
        header = f"{'Thread Entry':<30} {'RTOS':<12} {'Calculated':<12} {'Recommended':<12}"
        print(f"{Colors.BOLD}{Colors.UNDERLINE}{header}{Colors.END}")
        separator = f"{'─' * 30:<30} {'─' * 12:<12} {'─' * 12:<12} {'─' * 12:<12}"
        print(f"{Colors.BOLD}{Colors.UNDERLINE}{separator}{Colors.END}")

        # Sort by recommended size descending
        sorted_threads = sorted(self.detected_threads,
                               key=lambda t: t.recommended, reverse=True)

        for thread in sorted_threads:
            name = thread.entry_func
            if len(name) > 29:
                name = name[:26] + "..."

            if thread.is_unbounded:
                calc_str = f"{Colors.RED}unbounded{Colors.END}"
                rec_str = f"{Colors.RED}REVIEW!{Colors.END}"
            else:
                calc_str = f"{thread.stack_usage}"
                rec_str = f"{Colors.GREEN}{thread.recommended}{Colors.END}"

            print(f"{name:<30} {thread.rtos:<12} {calc_str:<12} {rec_str:<12}")

        # Summary
        bounded_threads = [t for t in self.detected_threads if not t.is_unbounded]
        if bounded_threads:
            total_recommended = sum(t.recommended for t in bounded_threads)
            print(f"\n{Colors.BOLD}Total recommended stack space: "
                  f"{Colors.GREEN}{total_recommended}{Colors.END}{Colors.BOLD} bytes{Colors.END}")

        unbounded_count = len([t for t in self.detected_threads if t.is_unbounded])
        if unbounded_count > 0:
            print(f"{Colors.YELLOW}⚠️  {unbounded_count} thread(s) have unbounded stack - "
                  f"manual review required{Colors.END}")

    def export_json(self, output_file: str, data: Dict) -> None:
        """
        Export analysis data to JSON format.

        Args:
            output_file: Path to output JSON file
            data: Analysis data dictionary to export
        """
        try:
            with open(output_file, 'w', encoding='utf-8') as f:
                json.dump(data, f, indent=2, sort_keys=True)
            print(f"\n{Colors.GREEN}✓ Analysis data exported to {output_file}{Colors.END}")
        except Exception as e:
            print(f"{Colors.RED}❌ Error exporting JSON: {e}{Colors.END}")


def load_json_data(file_path: str) -> Optional[Dict]:
    """
    Load analysis data from JSON file.

    Args:
        file_path: Path to JSON file

    Returns:
        Analysis data dictionary or None if failed
    """
    try:
        with open(file_path, 'r', encoding='utf-8') as f:
            return json.load(f)
    except Exception as e:
        print(f"{Colors.RED}❌ Error loading {file_path}: {e}{Colors.END}")
        return None


def read_and_display_json(json_file: str, threshold: int = 0, output_format: str = 'table') -> None:
    """
    Read JSON analysis file and display it, optionally filtering by threshold.

    Args:
        json_file: Path to JSON analysis file
        threshold: Minimum stack usage threshold in bytes (0 = show all)
        output_format: Output format ('table', 'json', 'short')
    """
    data = load_json_data(json_file)
    if not data:
        return

    # Get all functions or filter by threshold
    all_functions = data.get('functions', [])
    if threshold > 0:
        # Filter functions by threshold
        filtered_functions = []
        for func in all_functions:
            cost = func.get('total_cost')
            if cost == 'unbounded' or (isinstance(cost, (int, float)) and cost >= threshold):
                filtered_functions.append(func)
        functions_to_show = filtered_functions
        is_filtered = True
    else:
        functions_to_show = all_functions
        is_filtered = False

    if output_format == 'json':
        # Output data as JSON
        if is_filtered:
            filtered_data = data.copy()
            filtered_data['functions'] = functions_to_show
            filtered_data['metadata']['filtered_threshold'] = threshold
            filtered_data['metadata']['filtered_count'] = len(functions_to_show)
            print(json.dumps(filtered_data, indent=2, sort_keys=True))
        else:
            print(json.dumps(data, indent=2, sort_keys=True))

    elif output_format == 'short':
        # Simple list format
        for func in sorted(functions_to_show, key=lambda x: 0 if x['total_cost'] == 'unbounded' else -x['total_cost']):
            cost_display = func['total_cost'] if func['total_cost'] == 'unbounded' else str(func['total_cost'])
            print(f"{func['name']}: {cost_display}")

    else:
        # Table format (default)
        title = "📊 FILTERED STACK USAGE ANALYSIS" if is_filtered else "📊 STACK USAGE ANALYSIS"
        print(f"{Colors.BOLD}{Colors.HEADER}{title}{Colors.END}")
        print(f"{Colors.CYAN}Source: {json_file}{Colors.END}")

        if is_filtered:
            print(f"{Colors.CYAN}Threshold: ≥{threshold} bytes or unbounded{Colors.END}")
            print(f"{Colors.CYAN}Showing: {len(functions_to_show)} of {len(all_functions)} functions{Colors.END}\n")
        else:
            print(f"{Colors.CYAN}Showing: {len(functions_to_show)} functions{Colors.END}\n")

        if not functions_to_show:
            if is_filtered:
                print(f"{Colors.YELLOW}⚠️  No functions found with stack usage ≥{threshold} bytes{Colors.END}")
            else:
                print(f"{Colors.YELLOW}⚠️  No functions found in analysis{Colors.END}")
            return

        # Display metadata summary
        metadata = data.get('metadata', {})
        if metadata:
            print(f"{Colors.BOLD}📋 Analysis Metadata:{Colors.END}")
            if 'timestamp' in metadata:
                print(f"  Analysis time: {metadata['timestamp']}")
            if 'build_dir' in metadata:
                print(f"  Build directory: {metadata['build_dir']}")
            if 'total_functions' in metadata:
                print(f"  Total functions: {metadata['total_functions']}")
            if 'rtl_analysis_enabled' in metadata:
                rtl_status = "enabled" if metadata['rtl_analysis_enabled'] else "disabled"
                print(f"  RTL analysis: {rtl_status}")
            if 'git' in metadata and metadata['git']:
                git_info = metadata['git']
                print(f"  Git: {git_info.get('branch', 'unknown')}@{git_info.get('commit_hash_short', 'unknown')}")
            print()

        # Table header
        header = f"{'Function Name':<40} {'Total':<9} {'Frame':<7} {'Depth':<5} {'Type':<12}"
        print(f"{Colors.BOLD}{Colors.UNDERLINE}{header}{Colors.END}")
        separator = (f"{'────────────────────────────────────────':<40} "
                     f"{'─────────':<9} {'─────':<7} {'─────':<5} "
                     f"{'────────────':<12}")
        print(f"{Colors.BOLD}{Colors.UNDERLINE}{separator}{Colors.END}")

        # Sort by cost (unbounded first, then descending)
        sorted_functions = sorted(functions_to_show, key=lambda x: (
            0 if x['total_cost'] == 'unbounded' else 1, -(x['total_cost'] if x['total_cost'] != 'unbounded' else 0)))

        for func in sorted_functions:
            # Determine function type and color
            if func.get('is_unbounded', False):
                if func.get('unbounded_reason') == 'recursion':
                    type_indicator = f"{Colors.RED}🔄 Recursive{Colors.END}"
                elif func.get('unbounded_reason') == 'function_pointer':
                    type_indicator = f"{Colors.YELLOW}⚠ Func Ptr{Colors.END}"
                else:
                    type_indicator = f"{Colors.RED}❌ Unbounded{Colors.END}"
                cost_display = f"{Colors.RED}{Colors.BOLD}unbounded{Colors.END}"
            else:
                type_indicator = f"{Colors.GREEN}▶ Root{Colors.END}" if func.get('is_root', False) else "  Normal"
                cost = func['total_cost']
                if cost >= 500:
                    cost_display = f"{Colors.RED}{Colors.BOLD}{cost}{Colors.END}"
                elif cost >= 200:
                    cost_display = f"{Colors.RED}{cost}{Colors.END}"
                elif cost >= 100:
                    cost_display = f"{Colors.YELLOW}{cost}{Colors.END}"
                else:
                    cost_display = f"{Colors.CYAN}{cost}{Colors.END}"

            # Handle long function names
            display_name = func['name']
            if len(display_name) > MAX_FUNCTION_NAME_LEN:
                display_name = display_name[:MAX_FUNCTION_NAME_LEN - 3] + "..."

            depth_display = str(func.get('call_depth', 0)) if func.get('call_depth') != 'unbounded' else "∞"

            row = (f"{display_name:<40} {cost_display:<9} {func.get('frame_size', 0):<7} "
                   f"{depth_display:<5} {type_indicator}")
            print(row)

        # Summary
        print(f"\n{Colors.BOLD}📈 Summary:{Colors.END}")
        unbounded_count = len([f for f in functions_to_show if f.get('is_unbounded', False)])
        bounded_count = len(functions_to_show) - unbounded_count
        print(f"  Unbounded functions: {Colors.RED}{unbounded_count}{Colors.END}")
        print(f"  Bounded functions:   {Colors.GREEN}{bounded_count}{Colors.END}")
        print(f"  Total shown:         {Colors.CYAN}{len(functions_to_show)}{Colors.END}")

        if is_filtered and len(functions_to_show) < len(all_functions):
            hidden_count = len(all_functions) - len(functions_to_show)
            print(f"  Hidden (< threshold): {Colors.YELLOW}{hidden_count}{Colors.END}")


def compare_analyses(old_data: Dict, new_data: Dict) -> None:
    """
    Compare two stack analysis results and display git-diff like output.

    Args:
        old_data: Previous analysis data
        new_data: Current analysis data
    """
    print(f"\n{Colors.BOLD}{Colors.HEADER}{'='*80}{Colors.END}")
    print(f"{Colors.BOLD}{Colors.HEADER}📊 STACK USAGE COMPARISON{Colors.END}")
    print(f"{Colors.BOLD}{Colors.HEADER}{'='*80}{Colors.END}\n")

    # Compare metadata
    old_time = old_data.get('metadata', {}).get('timestamp', 'unknown')
    new_time = new_data.get('metadata', {}).get('timestamp', 'unknown')
    print(f"{Colors.CYAN}Comparing:{Colors.END}")
    print(f"  Old: {old_time}")
    print(f"  New: {new_time}")

    # Compare summary statistics
    old_summary = old_data.get('summary', {})
    new_summary = new_data.get('summary', {})

    print(f"\n{Colors.BOLD}📈 Summary Changes:{Colors.END}")
    _print_summary_diff('Peak estimate', old_summary.get('total_peak_estimate', 0),
                        new_summary.get('total_peak_estimate', 0))
    _print_summary_diff('Max single function', old_summary.get('max_single_function', 0),
                        new_summary.get('max_single_function', 0))
    _print_summary_diff('Average usage', old_summary.get('average_stack_usage', 0),
                        new_summary.get('average_stack_usage', 0))

    # Compare functions
    old_functions = {f['name']: f for f in old_data.get('functions', [])}
    new_functions = {f['name']: f for f in new_data.get('functions', [])}

    all_functions = set(old_functions.keys()) | set(new_functions.keys())
    changes = []

    for func_name in sorted(all_functions):
        old_func = old_functions.get(func_name)
        new_func = new_functions.get(func_name)

        if old_func and new_func:
            old_cost = old_func['total_cost']
            new_cost = new_func['total_cost']
            if old_cost != new_cost:
                diff = new_cost - old_cost
                changes.append((func_name, old_cost, new_cost, diff, 'modified'))
        elif old_func and not new_func:
            changes.append((func_name, old_func['total_cost'], 0, -old_func['total_cost'], 'removed'))
        elif not old_func and new_func:
            changes.append((func_name, 0, new_func['total_cost'], new_func['total_cost'], 'added'))

    if changes:
        print(f"\n{Colors.BOLD}🔄 Function Changes:{Colors.END}")
        header = f"{'Status':<8} {'Function Name':<40} {'Old':<7} {'New':<7} {'Diff':<8}"
        print(f"{Colors.BOLD}{Colors.UNDERLINE}{header}{Colors.END}")
        separator = (f"{'────────':<8} {'────────────────────────────────────────':<40} "
                     f"{'───':<7} {'───':<7} {'────────':<8}")
        print(f"{Colors.BOLD}{Colors.UNDERLINE}{separator}{Colors.END}")

        # Sort by absolute difference (largest changes first)
        changes.sort(key=lambda x: abs(x[3]), reverse=True)

        for func_name, old_cost, new_cost, diff, status in changes[:20]:  # Show top 20 changes
            _print_function_diff(func_name, old_cost, new_cost, diff, status)

        if len(changes) > 20:
            print(f"\n{Colors.CYAN}💭 {len(changes) - 20} more changes not shown{Colors.END}")
    else:
        print(f"\n{Colors.GREEN}✓ No function-level changes detected{Colors.END}")

    # Compare file statistics
    old_files = old_data.get('files', {})
    new_files = new_data.get('files', {})

    file_changes = []
    all_files = set(old_files.keys()) | set(new_files.keys())

    for file_name in sorted(all_files):
        old_file = old_files.get(file_name, {})
        new_file = new_files.get(file_name, {})

        old_total = old_file.get('total_cost', 0)
        new_total = new_file.get('total_cost', 0)

        if old_total != new_total:
            diff = new_total - old_total
            file_changes.append((file_name, old_total, new_total, diff))

    if file_changes:
        print(f"\n{Colors.BOLD}📁 File-level Changes:{Colors.END}")
        file_changes.sort(key=lambda x: abs(x[3]), reverse=True)

        for file_name, old_total, new_total, diff in file_changes[:10]:
            _print_file_diff(file_name, old_total, new_total, diff)


def _print_summary_diff(label: str, old_val: int, new_val: int) -> None:
    """Print a summary statistic difference."""
    diff = new_val - old_val
    if diff == 0:
        print(f"  {label:<20}: {new_val:>6} bytes (no change)")
    else:
        color = Colors.RED if diff > 0 else Colors.GREEN
        sign = '+' if diff > 0 else ''
        summary_msg = (f"  {label:<20}: {old_val:>6} → {color}{new_val:>6}{Colors.END} bytes "
                       f"({color}{sign}{diff:>+6}{Colors.END})")
        print(summary_msg)


def _print_function_diff(func_name: str, old_cost: int, new_cost: int, diff: int, status: str) -> None:
    """Print a function difference in git-diff style."""
    # Truncate long function names
    display_name = func_name[:MAX_FUNCTION_NAME_LEN - 3] + "..." if len(func_name) > MAX_FUNCTION_NAME_LEN else func_name

    if status == 'added':
        add_msg = (f"{Colors.GREEN}+ ADD   {Colors.END} {display_name:<40} {'-':<7} "
                   f"{new_cost:<7} {Colors.GREEN}+{diff:<7}{Colors.END}")
        print(add_msg)
    elif status == 'removed':
        del_msg = (f"{Colors.RED}- DEL   {Colors.END} {display_name:<40} {old_cost:<7} "
                   f"{'-':<7} {Colors.RED}{diff:<8}{Colors.END}")
        print(del_msg)
    else:  # modified
        color = Colors.RED if diff > 0 else Colors.GREEN
        sign = '+' if diff > 0 else ''
        mod_msg = (f"{color}~ MOD   {Colors.END} {display_name:<40} {old_cost:<7} "
                   f"{new_cost:<7} {color}{sign}{diff:<7}{Colors.END}")
        print(mod_msg)


def _print_file_diff(file_name: str, old_total: int, new_total: int, diff: int) -> None:
    """Print a file-level difference."""
    color = Colors.RED if diff > 0 else Colors.GREEN
    sign = '+' if diff > 0 else ''
    file_msg = (f"  {file_name:<30}: {old_total:>6} → {color}{new_total:>6}{Colors.END} bytes "
                f"({color}{sign}{diff:>+6}{Colors.END})")
    print(file_msg)


def main():
    """
    Main entry point for the stack analyzer tool.

    Handles command line argument parsing, tool initialization,
    and orchestrates the complete analysis workflow.
    """
    parser = argparse.ArgumentParser(
        description="Analyze stack usage of ARM embedded firmware",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog="""
Examples:
  python3 arm-stack build
  python3 arm-stack build --elf build/firmware.elf    # Use ELF for accurate code sizes
  python3 arm-stack cmake-build-debug
  python3 arm-stack build --threshold 50
  python3 arm-stack build --no-color
  python3 arm-stack build --no-warnings
  python3 arm-stack build --export-json stack_usage.json
  python3 arm-stack build --elf build/fw.elf --export-json usage.json
  python3 arm-stack build --json > stack_usage.json
  python3 arm-stack build --short
  python3 arm-stack build --objdump /path/to/arm-none-eabi-objdump
  python3 arm-stack --compare old.json new.json
  python3 arm-stack --read-json analysis.json
  python3 arm-stack --read-json analysis.json --threshold 100

Thread Stack Analysis (auto-detects FreeRTOS, Zephyr, CMSIS-RTOS, etc.):
  python3 arm-stack build --threads
  python3 arm-stack build --threads --stack-margin 2.0

Function Pointer Detection:
  Compile with: gcc -c -fstack-usage -fdump-rtl-dfinish source.c
  Analyze with: python3 arm-stack build
        """
    )
    parser.add_argument('build_dir', nargs='?', help='Build directory containing object files')
    parser.add_argument('--elf', type=str, metavar='FILE',
                        help='ELF file to get actual linked code sizes (more accurate than object files)')
    parser.add_argument('--map', type=str, metavar='FILE',
                        help='Linker map file for detailed memory region analysis')
    parser.add_argument('--threshold', type=int, default=10,
                        help='Minimum stack usage threshold in bytes (default: 10)')
    parser.add_argument('--no-color', action='store_true', help='Disable colored output')
    parser.add_argument('--no-warnings', action='store_true', help='Suppress warning messages')
    parser.add_argument('--export-json', type=str, metavar='FILE',
                        help='Export analysis data to JSON file')
    parser.add_argument('--json', action='store_true',
                        help='Output analysis results in JSON format to stdout')
    parser.add_argument('--short', action='store_true',
                        help='Output only a sorted list of functions with stack usage')
    parser.add_argument('--objdump', type=str, default=DEFAULT_OBJDUMP, metavar='PATH',
                        help=f'Path to objdump executable (default: {DEFAULT_OBJDUMP})')
    parser.add_argument('--compare', type=str, nargs=2, metavar=('OLD', 'NEW'),
                        help='Compare two JSON analysis files')
    parser.add_argument('--read-json', type=str, metavar='FILE',
                        help='Read and display JSON analysis file (can be combined with --threshold for filtering)')
    parser.add_argument(
        '--filter-json',
        type=str,
        metavar='FILE',
        help='Read JSON file and filter functions by stack usage threshold (deprecated: use --read-json)')
    parser.add_argument('--threads', action='store_true',
                        help='Detect RTOS thread entry points and recommend stack sizes')
    parser.add_argument('--stack-margin', type=float, default=DEFAULT_STACK_MARGIN,
                        metavar='FACTOR',
                        help=f'Safety margin multiplier for thread stack recommendations (default: {DEFAULT_STACK_MARGIN})')
    parser.add_argument('--version', action='version', version=f'%(prog)s {__version__} by {__author__} ({__github__})')

    args = parser.parse_args()

    # Configure logging
    if args.json or args.short:
        # Quiet modes: only show errors
        log_level = logging.ERROR
        log_stream = sys.stderr
    elif args.no_warnings:
        # No warnings: show info but not warnings
        log_level = logging.INFO
        log_stream = sys.stdout
    else:
        # Normal mode: show info and warnings
        log_level = logging.INFO
        log_stream = sys.stdout

    logging.basicConfig(
        level=log_level,
        format='%(message)s',
        stream=log_stream,
        force=True
    )

    # Configure output formatting
    if args.no_color or args.json or args.short:
        for attr in dir(Colors):
            if not attr.startswith('_'):
                setattr(Colors, attr, '')

    # Handle comparison mode
    if args.compare:
        old_file, new_file = args.compare
        print(f"{Colors.BOLD}{Colors.HEADER}🔍 ARM Stack Usage Analyzer - Comparison Mode{Colors.END}")
        print(f"{Colors.CYAN}Comparing: {old_file} vs {new_file}{Colors.END}")

        old_data = load_json_data(old_file)
        new_data = load_json_data(new_file)

        if old_data and new_data:
            compare_analyses(old_data, new_data)
        else:
            print(f"{Colors.RED}❌ Failed to load comparison files{Colors.END}")
            sys.exit(1)
        return

    # Handle JSON reading/filtering mode
    if args.read_json:
        if not args.json and not args.short:
            print(f"{Colors.BOLD}{Colors.HEADER}🔍 ARM Stack Usage Analyzer - JSON Reader Mode{Colors.END}")

        output_format = 'json' if args.json else ('short' if args.short else 'table')
        read_and_display_json(args.read_json, args.threshold, output_format)
        return

    # Handle legacy JSON filtering mode (deprecated)
    if args.filter_json:
        if not args.json and not args.short:
            print(f"{Colors.BOLD}{Colors.HEADER}🔍 ARM Stack Usage Analyzer - JSON Filter Mode (deprecated){Colors.END}")
            print(f"{Colors.YELLOW}⚠️  --filter-json is deprecated, use --read-json instead{Colors.END}")

        output_format = 'json' if args.json else ('short' if args.short else 'table')
        read_and_display_json(args.filter_json, args.threshold, output_format)
        return

    # Require build directory for analysis mode
    if not args.build_dir:
        parser.error("build_dir is required unless using --compare, --read-json, or --filter-json")

    # Display tool header (unless in JSON or short mode)
    if not args.json and not args.short:
        print(f"{Colors.BOLD}{Colors.HEADER}🔍 ARM Stack Usage Analyzer{Colors.END}")
        print(f"{Colors.CYAN}Build directory: {args.build_dir}{Colors.END}")
        if args.elf:
            print(f"{Colors.GREEN}ELF file: {args.elf}{Colors.END}")
        else:
            print(f"{Colors.YELLOW}No --elf provided - code size statistics will be skipped{Colors.END}")
        if args.threshold != 10:
            print(f"{Colors.CYAN}Threshold: {args.threshold} bytes{Colors.END}")
        if args.no_warnings:
            print(f"{Colors.CYAN}Warnings: disabled{Colors.END}")
        if args.export_json:
            print(f"{Colors.CYAN}JSON export: {args.export_json}{Colors.END}")
        if args.objdump != DEFAULT_OBJDUMP:
            print(f"{Colors.CYAN}Objdump: {args.objdump}{Colors.END}")
        print()

    # Initialize and run analysis
    analyzer = StackAnalyzer(
        args.build_dir,
        args.threshold,
        not args.no_warnings,
        args.objdump,
        args.stack_margin
    )

    try:
        # Verification and setup phase
        obj_files = analyzer.check_prerequisites()

        # Parse ELF for accurate code sizes if provided
        if args.elf:
            analyzer.parse_elf_code_sizes(args.elf)

        # Parse linker map file for memory region details if provided
        if args.map:
            analyzer.parse_map_file(args.map)

        # Analysis workflow
        analyzer.parse_object_files(obj_files)
        analyzer.resolve_symbols()
        analyzer.create_interrupt_node()
        analyzer.trace_call_graph()

        # Detect thread entry points if requested
        if args.threads:
            analyzer.detect_thread_entries()

        if args.json:
            # JSON mode: generate data and output to stdout
            analysis_data = analyzer.generate_analysis_data()
            print(json.dumps(analysis_data, indent=2, sort_keys=True))
        elif args.short:
            # Short mode: output only function list
            analyzer.generate_short_report()
        else:
            # Normal mode: generate report
            analysis_data = analyzer.generate_report()

            # Export to JSON if requested
            if args.export_json:
                analyzer.export_json(args.export_json, analysis_data)

    except KeyboardInterrupt:
        print(f"\n{Colors.YELLOW}⚠️  Analysis interrupted by user{Colors.END}")
        sys.exit(1)
    except Exception as e:
        print(f"{Colors.RED}❌ Error during analysis: {e}{Colors.END}")
        sys.exit(1)


if __name__ == "__main__":
    main()