ocgraph 0.3.0__py3-none-any.whl

ocgraph/configuration/architecture/sparc.py

@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: GTDGmbH
+"""Contains instruction info for Sparc-compatible targets."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .architecture import GenericArchitecture
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ocgraph.data import Instruction
+
+# fmt: off
+sparc_v8_call_opcodes = [
+    "call",
+]
+
+sparc_v8_sink_opcodes = [
+    # ret: return from subroutine
+    # retl: return from leaf subroutine
+    "ret", "retl",
+]
+
+sparc_v8_Bicc_opcodes = [
+    # conditional icc branch opcodes
+    "ba", "bn", "bne", "be", "bg", "ble", "bge", "bl", "bgu", "bleu", "bcc",
+    "bcs", "bpos", "bneg", "bvc", "bvs",
+]
+
+sparc_v8_FBfcc_opcodes = [
+    # conditional fcc branch opcodes
+    "fba", "fbn", "fbu", "fbg", "fbug", "fbl", "fbul", "fblg", "fbne", "fbe",
+    "fbue", "fbge", "fbuge", "fble", "fbule", "fbo",
+]
+
+sparc_v8_CBfcc_opcodes = [
+    # conditional coprocessor opcodes
+    "cba", "cbn", "cb3", "cb2", "cb23", "cb1", "cb13", "cb12", "cb123", "cb0",
+    "cb03", "cb02", "cb023", "cb01", "cb013", "cb012",
+]
+
+sparc_v8_Ticc_opcodes = [
+    # conditional traps on icc
+    "ta", "tn", "tne", "te", "tg", "tle", "tge", "tl", "tgu", "tleu", "tcc",
+    "tcs", "tpos", "tneg", "tvc", "tvs",
+]
+
+sparc_v8_branch_cond_delay_opcodes = [
+    f"{x},a" for x in
+    sparc_v8_Bicc_opcodes +
+    sparc_v8_FBfcc_opcodes +
+    sparc_v8_CBfcc_opcodes
+]
+
+sparc_v8_unconditional_branch_opcodes = [
+    "jmpl", "jmp", "b", "b,a",
+]
+
+sparc_v8_delayed_opcodes = sparc_v8_Bicc_opcodes + \
+                           sparc_v8_FBfcc_opcodes + \
+                           sparc_v8_CBfcc_opcodes + \
+                           sparc_v8_branch_cond_delay_opcodes + \
+                           sparc_v8_unconditional_branch_opcodes
+
+sparc_v8_conditional_branch_opcodes = sparc_v8_Bicc_opcodes + \
+                                      sparc_v8_FBfcc_opcodes + \
+                                      sparc_v8_CBfcc_opcodes + \
+                                      sparc_v8_Ticc_opcodes + \
+                                      sparc_v8_branch_cond_delay_opcodes
+# fmt: on
+
+
+class SparcArchitecture(GenericArchitecture):
+    """SparcArchitecture Class."""
+
+    def is_call(self, instruction: Instruction) -> bool:
+        return instruction.opcode in sparc_v8_call_opcodes
+
+    def is_branch(self, instruction: Instruction) -> bool:
+        return instruction.opcode in (
+            sparc_v8_conditional_branch_opcodes + sparc_v8_unconditional_branch_opcodes
+        )
+
+    def get_branch_delay(self, instruction: Instruction) -> int:
+        if instruction.opcode in sparc_v8_delayed_opcodes or self.is_sink(instruction):
+            delay = 2
+        else:
+            delay = 1
+        return delay
+
+    def is_direct_branch(self, instruction: Instruction) -> bool:
+        # every branch is disassembled with the complete offset,
+        # i.e. every branch is direct
+        return self.is_branch(instruction)
+
+    def is_unconditional_branch(self, instruction: Instruction) -> bool:
+        return instruction.opcode in sparc_v8_unconditional_branch_opcodes
+
+    def is_sink(self, instruction: Instruction) -> bool:
+        return instruction.opcode in sparc_v8_sink_opcodes

ocgraph/configuration/architecture/x86.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: GTDGmbH
+"""Contains instruction info for X86-compatible targets."""
+
+from ocgraph.data import Instruction
+
+from .architecture import GenericArchitecture
+
+
+class X86Architecture(GenericArchitecture):
+    """X86Architecture Class."""
+
+    def is_call(self, instruction: Instruction) -> bool:
+        # Various flavors of call:
+        #   call   *0x26a16(%rip)
+        #   call   0x555555555542
+        #   addr32 call 0x55555558add0
+        if instruction.opcode:
+            return "call" in instruction.opcode
+        return False
+
+    def is_branch(self, instruction: Instruction) -> bool:
+        if instruction.opcode:
+            return instruction.opcode[0] == "j"
+        return False
+
+    def is_unconditional_branch(self, instruction: Instruction) -> bool:
+        if instruction.opcode:
+            return instruction.opcode.startswith("jmp")
+        return False
+
+    def is_sink(self, instruction: Instruction) -> bool:
+        if instruction.opcode:
+            return instruction.opcode.startswith("ret")
+        return False

ocgraph/configuration/configuration.py

@@ -0,0 +1,122 @@
+# SPDX-License-Identifier: GTDGmbH
+"""Module for configuration of the ocgraph package."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from .architecture import (
+    ArmArchitecture,
+    MSP430Architecture,
+    PpcArchitecture,
+    SparcArchitecture,
+    X86Architecture,
+)
+from .disassembler import (
+    GdbDisassembler,
+    ObjDumpArmDisassembler,
+    ObjDumpMsp430Disassembler,
+    ObjDumpPpcDisassembler,
+    ObjDumpSparcDisassembler,
+    ObjDumpx86Disassembler,
+)
+from .logger import OCGraphLogger, preset_logging
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .architecture import Architecture
+    from .disassembler import Disassembler
+
+# fmt: off
+disassembler_option: dict[str, dict[str, Disassembler]] = {
+    "OBJDUMP": {
+        "sparc": ObjDumpSparcDisassembler(),
+        "ppc": ObjDumpPpcDisassembler(),
+        "x86": ObjDumpx86Disassembler(),
+        "arm": ObjDumpArmDisassembler(),
+        "msp430": ObjDumpMsp430Disassembler(),
+    },
+    "GDB": {
+        "sparc": GdbDisassembler(),
+        "ppc": GdbDisassembler(),
+        "x86": GdbDisassembler(),
+        "arm": GdbDisassembler(),
+        "msp430": GdbDisassembler(),
+    },
+}
+
+architecture_option: dict[str, dict[str, str | Architecture | Disassembler]] = {
+    "x86": {
+        "platform": "X86",
+        "architecture": X86Architecture(),
+    },
+    "arm": {
+        "platform": "ARM",
+        "architecture": ArmArchitecture(),
+    },
+    "sparc": {
+        "platform": "SPARC",
+        "architecture": SparcArchitecture(),
+    },
+    "ppc": {
+        "platform": "PPC",
+        "architecture": PpcArchitecture(),
+    },
+    "msp430": {
+        "platform": "MSP430",
+        "architecture": MSP430Architecture(),
+    },
+}
+# fmt: on
+
+
+class OcGraphConfiguration:
+    """Implement configuration presets for the ASM2CFG tool."""
+
+    def __init__(
+        self,
+        arch: str = "sparc",
+        disassembler: str = "OBJDUMP",
+        logging_preset: str = "default",
+    ) -> None:
+        if architecture_option.get(arch) is None:
+            msg = "Architecture option not supported!"
+            raise NotImplementedError(msg)
+        if disassembler_option.get(disassembler) is None:
+            msg = "Disassembler option not supported!"
+            raise NotImplementedError(msg)
+        if preset_logging.get(logging_preset) is None:
+            msg = "Logging preset not supported!"
+            raise NotImplementedError(msg)
+
+        # load module preset
+        _preset = architecture_option[arch]
+        _preset["disassembler"] = disassembler_option[disassembler][arch]
+        self.__dict__ = _preset
+
+        # configure logging
+        self.logger = OCGraphLogger("OcGraph", logging_preset, "ocgraph")
+
+    @staticmethod
+    def architectures() -> list[str]:
+        """Return all available architectures options."""
+        return list(architecture_option.keys())
+
+    @staticmethod
+    def disassemblers() -> list[str]:
+        """Return all available disassemblers options."""
+        return list(disassembler_option.keys())
+
+    @staticmethod
+    def loggers() -> list[str]:
+        """Return all available disassemblers options."""
+        return list(preset_logging.keys())
+
+    logger: logging.Logger = logging.getLogger("OcGraph")
+    """Logging mechanism for module"""
+
+    architecture: Architecture
+    """Target architecture instance"""
+
+    disassembler: Disassembler
+    """Target disassembler tool like OBJDump, GDB, ..."""

ocgraph/configuration/disassembler/__init__.py

@@ -0,0 +1,10 @@
+"""The main file of the disassembler module."""
+
+from .disassembler import Disassembler as Disassembler
+from .disassembler import ObjdumpDisassembler as ObjdumpDisassembler
+from .gdb_default import GdbDisassembler as GdbDisassembler
+from .objdump_arm import ObjDumpArmDisassembler as ObjDumpArmDisassembler
+from .objdump_msp430 import ObjDumpMsp430Disassembler as ObjDumpMsp430Disassembler
+from .objdump_ppc import ObjDumpPpcDisassembler as ObjDumpPpcDisassembler
+from .objdump_sparc import ObjDumpSparcDisassembler as ObjDumpSparcDisassembler
+from .objdump_x86 import ObjDumpx86Disassembler as ObjDumpx86Disassembler

ocgraph/configuration/disassembler/disassembler.py

@@ -0,0 +1,148 @@
+"""Class configuring the used disassembler tool."""
+
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from re import Match
+from typing import TYPE_CHECKING
+
+from ocgraph.data import Address, FunctionHeader, Instruction
+
+if TYPE_CHECKING:  # pragma: no cover
+    from collections.abc import Generator
+
+    from ocgraph.configuration.architecture.architecture import Architecture
+
+# Common regexes
+HEX_PATTERN = r"[0-9a-fA-F]+"
+HEX_LONG_PATTERN = r"(?:0x0*)?" + HEX_PATTERN
+
+
+class DisassemblerError(Exception):
+    """Raised when the extract_information method was not successful."""
+
+
+class Disassembler(ABC):
+    """Disassembler Class."""
+
+    architecture: Architecture
+    """Architecture configuration used by the disassembler"""
+
+    name: str = ""
+    """Disassembler tool identification like SparcV8Objdump, GDB, ..."""
+
+    @abstractmethod
+    def extract_information(self, lines: list[str]) -> Generator[Instruction | FunctionHeader]:
+        """
+        Parse the given lines of disassembler output.
+
+        This extracts all available information from the disassembler
+        output and returns a generator providing Instruction or a
+        FunctionHeader.
+        """
+        raise NotImplementedError  # pragma: no cover
+
+    @abstractmethod
+    def parse_jump_target(self, ops: list[str]) -> int | None:
+        """Return the jump target value from a list of operands."""
+        raise NotImplementedError  # pragma: no cover
+
+
+class ObjdumpDisassembler(Disassembler):
+    """Objdump Disassembler Class."""
+
+    name: str = ""
+    """ Disassembler tool identification like SparcV8Objdump, GDB, ..."""
+
+    function_header_regex: str = r"^([0-9a-fA-F]+) <(.*)>:$"
+    function_header_groups: dict[str, int] = {
+        "address": 1,
+        "name": 2,
+    }
+
+    instruction_regex: str = (
+        r"^\s*([0-9a-fA-F]+):\t((?:[0-9a-fA-F]+ )+) *\t(\S+)[\t ]*([^\n\r\f\v;]*?) ?[\t ]*(?:|[#!;] *([0-9a-fA-F]+) *<(.*?)(\+.*)?>|\t.*:.*|<(.*)(\+.*)>|[#!;] 0x([0-9a-fA-F]+)|;abs 0x([0-9a-fA-F]+)|;.*)$"
+    )
+    instruction_groups: dict[str, int] = {
+        "address": 1,
+        "encoding": 2,
+        "mnemonic": 3,
+        "operands": 4,
+        "decoded_immediate1": 5,
+        "symbol": 6,
+        "symbol_offset": 7,
+        "relative_jump_base": 8,
+        "relative_jump_offset": 9,
+        "decoded_immediate2": 10,
+        "absolute_jump_target": 11,
+    }
+
+    def __init__(self) -> None:
+        self.current_function: str | None = None
+
+    def extract_information(self, lines: list[str]) -> Generator[Instruction | FunctionHeader]:
+        """
+        Parse the given lines of disassembler output.
+
+        This extracts all available information from the disassembler
+        output and returns a generator providing Instruction or a
+        FunctionHeader.
+        """
+
+        def get_match(match_object: Match[str], match_number: int) -> str:
+            return match_object.group(match_number)
+
+        for i, line in enumerate(lines):
+            instruction = re.match(self.instruction_regex, line)
+            function_header = re.match(self.function_header_regex, line)
+
+            if function_header:
+                address = get_match(function_header, self.function_header_groups["address"])
+                name = get_match(function_header, self.function_header_groups["name"])
+                self.current_function = name
+                yield FunctionHeader(name, int(address, 16))
+            elif instruction:
+                relative_jump_base = get_match(
+                    instruction,
+                    self.instruction_groups["relative_jump_base"],
+                )
+                relative_jump_offset = get_match(
+                    instruction,
+                    self.instruction_groups["relative_jump_offset"],
+                )
+                address = get_match(instruction, self.instruction_groups["address"])
+                absolute_jump_target = get_match(
+                    instruction,
+                    self.instruction_groups["absolute_jump_target"],
+                )
+                ops = [
+                    x.strip()
+                    for x in get_match(instruction, self.instruction_groups["operands"]).split(",")
+                ]
+
+                if address and relative_jump_base and relative_jump_offset:
+                    target = Address(
+                        base=relative_jump_base,
+                        offset=int(relative_jump_offset, 16),
+                    )
+                elif address and absolute_jump_target:
+                    target = Address(
+                        abs_addr=int(absolute_jump_target, 16),
+                        base=relative_jump_base,
+                    )
+                else:
+                    target = Address(abs_addr=None)
+
+                yield Instruction(
+                    lineno=i,
+                    address=Address(abs_addr=int(address, 16), base=self.current_function),
+                    opcode=get_match(instruction, self.instruction_groups["mnemonic"]),
+                    ops=ops,
+                    target=target,
+                )
+
+    def parse_jump_target(self, ops: list[str]) -> int | None:
+        """Return the jump target value from a list of operands."""
+        # it assumes the last operand of the branch to be the target address
+        return int(ops[-1], 16)

ocgraph/configuration/disassembler/gdb_default.py

@@ -0,0 +1,11 @@
+"""Class for parsing the input."""
+
+from __future__ import annotations
+
+from .disassembler import ObjdumpDisassembler
+
+
+class GdbDisassembler(ObjdumpDisassembler):
+    """x86 GDB disassembler."""
+
+    name: str = "Default GDB Disassembler (x86 Binutils)"

ocgraph/configuration/disassembler/objdump_arm.py

@@ -0,0 +1,11 @@
+"""Class for parsing the objdump ARM input."""
+
+from __future__ import annotations
+
+from .disassembler import ObjdumpDisassembler
+
+
+class ObjDumpArmDisassembler(ObjdumpDisassembler):
+    """Objdump ARM disassembler."""
+
+    name: str = "ARM Objdump Disassembler"

ocgraph/configuration/disassembler/objdump_msp430.py

@@ -0,0 +1,27 @@
+"""Class for parsing the objdump MSP430 input."""
+
+from __future__ import annotations
+
+import re
+
+from .disassembler import ObjdumpDisassembler
+
+
+class ObjDumpMsp430Disassembler(ObjdumpDisassembler):
+    """Objdump MSP430 disassembler."""
+
+    name: str = "MSP430 Objdump Disassembler"
+
+    def parse_jump_target(self, ops: list[str]) -> int | None:
+        pattern_jump = r"abs\s+(0x[0-9a-fA-F]+)"
+        pattern_call = r"#0x([0-9a-fA-F]+)"
+        for op in ops:
+            match_jump = re.search(pattern_jump, op)
+            match_call = re.search(pattern_call, op)
+            if match_jump:
+                abs_adr = match_jump.group(1)
+                return int(abs_adr, 16)
+            if match_call:
+                abs_adr = match_call.group(1)
+                return int(abs_adr, 16)
+        return None

ocgraph/configuration/disassembler/objdump_ppc.py

@@ -0,0 +1,11 @@
+"""Class for parsing the objdump PPC input."""
+
+from __future__ import annotations
+
+from .disassembler import ObjdumpDisassembler
+
+
+class ObjDumpPpcDisassembler(ObjdumpDisassembler):
+    """Objdump PPC disassembler."""
+
+    name: str = "PPC Objdump Disassembler (PPC Binutils)"

ocgraph/configuration/disassembler/objdump_sparc.py

@@ -0,0 +1,11 @@
+"""Class for parsing the objdump SPARC input."""
+
+from __future__ import annotations
+
+from .disassembler import ObjdumpDisassembler
+
+
+class ObjDumpSparcDisassembler(ObjdumpDisassembler):
+    """Objdump SPARC disassembler."""
+
+    name: str = "SPARC Objdump Disassembler (SparcV8 Binutils)"

ocgraph/configuration/disassembler/objdump_x86.py

@@ -0,0 +1,11 @@
+"""Class for parsing the objdump x86 input."""
+
+from __future__ import annotations
+
+from .disassembler import ObjdumpDisassembler
+
+
+class ObjDumpx86Disassembler(ObjdumpDisassembler):
+    """x86 objdump disassembler."""
+
+    name: str = "x86 Disassembler (x86 Binutils)"

ocgraph/configuration/logger.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: GTDGmbH
+# Copyright 2024 by GTD GmbH.
+"""Class configuring the OCGraph logging."""
+
+from __future__ import annotations
+
+import logging
+
+# fmt: off
+preset_logging: dict[str, dict[str, bool | int]] = {
+    "development": {
+        "file_log": True,
+        "file_level": logging.DEBUG,
+        "console_log": True,
+        "console_level": logging.DEBUG,
+    },
+
+    "module": {
+        "file_log": False,
+        "file_level": logging.ERROR,
+        "console_log": False,
+        "console_level": logging.ERROR,
+    },
+
+    "default": {
+        "file_log": True,
+        "file_level": logging.INFO,
+        "console_log": True,
+        "console_level": logging.INFO,
+    },
+}
+# fmt: on
+
+
+class OCGraphLogger(logging.Logger):
+    """Logging mechanism for module."""
+
+    def __init__(self, name: str, preset: str = "default", file: str = "") -> None:
+        super().__init__(name)
+        log_config = preset_logging.get(preset)
+        if log_config:
+            if log_config["file_log"]:
+                logging_file = file + ".log"
+                file_stream = logging.FileHandler(logging_file)
+                file_stream.setLevel(log_config["file_level"])
+                self.addHandler(file_stream)
+            if log_config["console_log"]:
+                console_stream = logging.StreamHandler()
+                console_stream.setLevel(log_config["console_level"])
+                self.addHandler(console_stream)

ocgraph/data/__init__.py

@@ -0,0 +1,9 @@
+"""Main file of the data module."""
+
+from .address import Address as Address
+from .basic_block import BasicBlock as BasicBlock
+from .encoding import Encoding as Encoding
+from .function_header import FunctionHeader as FunctionHeader
+from .instruction import Coverage as Coverage
+from .instruction import Instruction as Instruction
+from .jump_table import JumpTable as JumpTable

ocgraph/data/address.py

@@ -0,0 +1,58 @@
+"""Represents location in program which may be absolute or relative."""
+
+from __future__ import annotations
+
+
+class Address:
+    """Address Class."""
+
+    def __init__(
+        self,
+        abs_addr: int | None = None,
+        base: str | None = None,
+        offset: int | None = None,
+    ) -> None:
+        self.abs_addr = abs_addr
+        self.base = base
+        self.offset = offset
+
+    def is_absolute(self) -> bool:
+        """
+        Return if Address is absolute.
+
+        Examples
+        --------
+        >>> Address(abs_addr=0x1234).is_absolute()
+        True
+        >>> Address(base="fn").is_absolute()
+        False
+
+        """
+        return self.base is None
+
+    def is_relative(self) -> bool:
+        """
+        Return if Address is relative.
+
+        >>> Address(abs_addr=0x1234).is_relative()
+        False
+        >>> Address(base="fn").is_relative()
+        True
+        """
+        return not self.is_absolute()
+
+    def __repr__(self) -> str:
+        """
+        Convert an Address into a representative string.
+
+        >>> Address(abs_addr=0x1234)
+        Address(0x1234, None+None)
+        >>> Address(base="fn", offset=0x1234)
+        Address(None, fn+0x1234)
+        >>> Address(abs_addr=0x5678, base="fn", offset=0x1234)
+        Address(0x5678, fn+0x1234)
+        """
+        abs_addr = f"0x{self.abs_addr:x}" if self.abs_addr is not None else None
+        base = self.base
+        offset = f"0x{self.offset:x}" if self.offset is not None else None
+        return f"Address({abs_addr}, {base}+{offset})"

ocgraph/data/basic_block.py

@@ -0,0 +1,37 @@
+"""Basic Block Class."""
+
+from typing import Any
+
+from .instruction import Instruction
+
+
+class BasicBlock:
+    """Class to represent an object code basic block as node in CFG."""
+
+    def __init__(self, key: Any) -> None:
+        self.key = key
+        self.instructions: list[Instruction] = []
+        self.jump_edge = None
+        self.no_jump_edge = None
+
+    def add_instruction(self, instruction: Instruction) -> None:
+        """Add instruction to this block."""
+        self.instructions.append(instruction)
+
+    def add_jump_edge(self, basic_block_key: Any) -> None:
+        """Add jump target block to this block."""
+        if isinstance(basic_block_key, BasicBlock):
+            self.jump_edge = basic_block_key.key
+        else:
+            self.jump_edge = basic_block_key
+
+    def add_no_jump_edge(self, basic_block_key: Any) -> None:
+        """Add no jump target block to this block."""
+        if isinstance(basic_block_key, BasicBlock):
+            self.no_jump_edge = basic_block_key.key
+        else:
+            self.no_jump_edge = basic_block_key
+
+    def __repr__(self) -> str:
+        """Convert a BasicBlock into a representative string."""
+        return f"BasicBlock({', '.join([str(i) for i in self.instructions])})"