ocgraph 0.3.0__py3-none-any.whl

ocgraph/data/encoding.py

@@ -0,0 +1,34 @@
+"""Encoding Class."""
+
+from __future__ import annotations
+
+
+class Encoding:
+    """
+    Encoding represents a sequence of bytes for instruction encoding.
+
+    E.g. the '31 c0' in:
+
+    '16bd3:	31 c0                	xor    %eax,%eax'
+    """
+
+    def __init__(self, bites: list[int]) -> None:
+        self.bites = bites
+
+    def __len__(self) -> int:
+        """
+        Return size of the bytes.
+
+        >>> len(Encoding([0xa,0xb,0xc]))
+        3
+        """
+        return len(self.bites)
+
+    def __repr__(self) -> str:
+        """
+        Convert an Encoding to a readable string.
+
+        >>> Encoding([0xa,0xb,0xc])
+        0xa 0xb 0xc
+        """
+        return " ".join(f"{b:#x}" for b in self.bites)

ocgraph/data/function_header.py

@@ -0,0 +1,23 @@
+"""Represents a function with an address."""
+
+
+class FunctionHeader:
+    """FunctionHeader Class."""
+
+    def __init__(
+        self,
+        name: str,
+        addr: int,
+    ) -> None:
+        """Create a new FunctionHeader."""
+        self.name = name
+        self.addr = addr
+
+    def __repr__(self) -> str:
+        """
+        Transform a FunctionHeader into a readable string.
+
+        >>> FunctionHeader("fn", 0x1234)
+        FunctionHeader(fn at 0x1234)
+        """
+        return f"FunctionHeader({self.name} at 0x{self.addr:x})"

ocgraph/data/instruction.py

@@ -0,0 +1,102 @@
+"""
+Represents a single assembly instruction with its operands, location and optional branch
+target.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .address import Address
+
+
+class Coverage(Enum):
+    """Enumeration for coverage records."""
+
+    MISS = "missed"
+    """Indicates instruction is not executed"""
+    LINE_TAKEN = "taken"
+    """Indicates instruction is executed"""
+    JUMP_PASS = "skipped"
+    """Indicates, if branch is just passed without jump"""
+    JUMP_TAKEN = "jumped"
+    """Indicates, if branch is just jumped without passed"""
+    JUMP_BOTH = "both taken"
+    """Indicates, if branch is just jumped without passed"""
+
+
+class Instruction:
+    """Instruction Class."""
+
+    lineno: int | None = None
+    """Line number in the file"""
+
+    address: Address | None = None
+    """Computed address of the instruction"""
+
+    opcode: str | None = None
+    """Disassembled opcode"""
+
+    ops: list[str] = []
+    """Disassembled operands of the instruction"""
+
+    target: Address | None = None
+    """Optional target of the instruction (branch)"""
+
+    returns: set[int] = set()
+    """Stores addresses of sink instructions like return"""
+
+    coverage: Coverage = Coverage.MISS
+    """If line is executed on test"""
+
+    branch_taken: bool | None = None
+
+    def __init__(
+        self,
+        lineno: int,
+        address: Address,
+        opcode: str,
+        ops: list[str],
+        target: Address | None,
+    ) -> None:
+        self.lineno = lineno
+        self.address = address
+        self.opcode = opcode
+        self.ops = ops
+        self.target = target
+        self.returns = set()
+        self.coverage = Coverage.MISS
+
+    def update_coverage(self, addresses: set[int], is_branch: bool = False) -> None:
+        """
+        Update the coverage information of the instruction.
+
+        :param addresses: Set of addresses executed after this instruction,
+            used to determine whether a branch was taken or not.
+        :param is_branch: Flag whether the instruction should be
+            interpreted as a branch
+        """
+        if not is_branch:
+            # exception for ret (target is None) or call (target.abs is None)
+            self.coverage = Coverage.LINE_TAKEN
+            self.returns = addresses
+        elif len(addresses) == 2 and self.target and self.target.abs_addr in addresses:
+            self.coverage = Coverage.JUMP_BOTH
+        elif len(addresses) == 1 and self.target and self.target.abs_addr in addresses:
+            self.coverage = Coverage.JUMP_TAKEN
+        elif len(addresses) == 1:
+            self.coverage = Coverage.JUMP_PASS
+        else:
+            msg = f"Invalid Coverage Information at {self.address}: {addresses}"
+            raise AssertionError(msg)
+
+    def __repr__(self) -> str:
+        """Convert an Instruction into a representative string."""
+        result = f"{self.address}: {self.opcode}"
+        if self.ops:
+            result += f" {self.ops}"
+        if self.target is not None:
+            result += " -> " + str(self.target)
+        return f"Instruction({result})"

ocgraph/data/jump_table.py

@@ -0,0 +1,60 @@
+"""Holds info about branch sources and destinations in asm function."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ocgraph.configuration.configuration import OcGraphConfiguration
+
+    from .address import Address
+    from .instruction import Instruction
+
+
+class JumpTable:
+    """JumpTable Class."""
+
+    def __init__(
+        self,
+        instructions: list[Instruction],
+        configuration: OcGraphConfiguration,
+    ) -> None:
+        self.config: OcGraphConfiguration = configuration
+
+        # Address where the jump begins and value which address
+        # to jump to. This also includes calls.
+        self.abs_sources: dict[int, Address] = {}
+        self.rel_sources: dict[int, Address] = {}
+
+        # Addresses where jumps end inside the current function.
+        self.abs_destinations: set[int] = set()
+        self.rel_destinations: set[int] = set()
+
+        # Iterate over the instructions and collect jump targets and branching points.
+        for instr in instructions:
+            if instr is None or instr.target is None or instr.address is None:
+                continue
+
+            if instr.target.abs_addr is not None and instr.address.abs_addr is not None:
+                self.abs_sources[instr.address.abs_addr] = instr.target
+                self.abs_destinations.add(instr.target.abs_addr)
+
+            if instr.target.offset is not None and instr.address.offset is not None:
+                self.rel_sources[instr.address.offset] = instr.target
+                self.rel_destinations.add(instr.target.offset)
+
+    def is_jump_target(self, addr: Address) -> bool:
+        """Return if address is a destination."""
+        if addr.abs_addr is not None:
+            return addr.abs_addr in self.abs_destinations
+        if addr.offset is not None:
+            return addr.offset in self.rel_destinations
+        return False
+
+    def get_target(self, addr: Address) -> Address | None:
+        """Return the target of a branch."""
+        if addr.abs_addr is not None:
+            return self.abs_sources.get(addr.abs_addr)
+        if addr.offset is not None:
+            return self.rel_sources.get(addr.offset)
+        return None

ocgraph/interface/__init__.py

@@ -0,0 +1,5 @@
+"""The main file of the interface module."""
+
+from .analyzer import Analyzer as Analyzer
+from .coverage_reader import CoverageReader as CoverageReader
+from .drawer import Drawer as Drawer

ocgraph/interface/analyzer.py

@@ -0,0 +1,220 @@
+"""Class for read and analyze the input string."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ocgraph.data import Address, BasicBlock, Instruction, JumpTable
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ocgraph.configuration import OcGraphConfiguration
+    from ocgraph.configuration.disassembler import Disassembler
+
+
+class Analyzer:
+    """Analyzer Class."""
+
+    def __init__(self, config: OcGraphConfiguration) -> None:
+        self.configuration = config
+        self.logger = self.configuration.logger
+        self.parser: Disassembler = self.configuration.disassembler
+
+        self.lines: list[str] = []
+        self.function_name: str = ""
+        self.instructions: list[Instruction] = []
+        self.jump_table: JumpTable
+        self.basic_blocks: dict[int, BasicBlock] = {}
+
+    def parse_file(self, file_path: str) -> None:
+        """Parse a assembler file."""
+        with open(file_path, encoding="utf8") as asm_file:
+            lines = asm_file.readlines()
+        self.parse_lines(lines)
+
+    def parse_lines(self, lines: list[str]) -> None:
+        """Parse a list of assembly lines."""
+        self.lines = lines
+        self._parse_instructions()
+        # Compute already known jump targets
+        # This is only a first pass as indirect jumps can't be
+        # discovered yet
+        self._compute_jump_targets()
+
+    def analyze(self) -> None:
+        # Re-compute jump targets this time with indirect branches
+        self._compute_jump_targets()
+        self._infer_relative_addresses()
+        self._create_jump_table()
+        self._create_basic_blocks()
+
+    def _parse_instructions(self) -> None:
+        self.instructions = []
+
+        for info in self.parser.extract_information(self.lines):
+            if isinstance(info, Instruction):
+                self.instructions.append(info)
+            else:
+                if self.function_name:
+                    msg = "we handle only one function for now"
+                    raise RuntimeError(msg)
+                self.logger.info(f"New function {info.name}")
+                self.function_name = info.name
+
+    def _compute_jump_targets(self) -> None:
+        # Infer target address for jump instructions
+        for instr in self.instructions:
+            if (
+                instr.target is None or instr.target.abs_addr is None
+            ) and self.configuration.architecture.is_direct_branch(instr):
+                if instr.target is None:
+                    instr.target = Address(None)
+                # parse the absolute target out of the operands
+                # (first hex address is assumed to be the target address)
+                try:
+                    instr.target.abs_addr = self.parser.parse_jump_target(instr.ops)
+                except ValueError:
+                    # Mark the address as not (yet) known
+                    instr.target.abs_addr = None
+
+    def _infer_relative_addresses(self) -> None:
+        # Infer relative addresses (for objdump or stripped gdb)
+        if (
+            len(self.instructions) > 0
+            and self.instructions[0].address
+            and self.instructions[0].address.abs_addr is not None
+        ):
+            start_address = self.instructions[0].address.abs_addr
+        else:
+            start_address = 0
+        if (
+            len(self.instructions) > 0
+            and self.instructions[-1].address
+            and self.instructions[-1].address.abs_addr is not None
+        ):
+            end_address = self.instructions[-1].address.abs_addr
+        else:
+            end_address = 0xFFFFFFFF
+
+        for instr in self.instructions:
+            for addr in (instr.address, instr.target):
+                if (
+                    addr is not None
+                    and addr.abs_addr is not None
+                    and addr.offset is None
+                    and start_address <= addr.abs_addr <= end_address
+                ):
+                    addr.offset = addr.abs_addr - start_address
+
+        self.logger.debug("Instructions:")
+        for instruction in self.instructions:
+            if instruction is not None:
+                self.logger.debug(f"  {instruction}")
+
+    def _create_jump_table(self) -> None:
+        self.jump_table = JumpTable(self.instructions, self.configuration)
+
+        self.logger.debug("Absolute destinations:")
+        for dst in self.jump_table.abs_destinations:
+            if dst:
+                self.logger.debug(f"  {dst:#x}")
+            else:
+                self.logger.debug("  None")
+        self.logger.debug("Relative destinations:")
+        for dst in self.jump_table.rel_destinations:
+            if dst:
+                self.logger.debug(f"  {dst:#x}")
+            else:
+                self.logger.debug("  None")
+        self.logger.debug("Absolute branches:")
+        for key, addr in self.jump_table.abs_sources.items():
+            self.logger.debug(f"  {key:#x} -> {addr}")
+        self.logger.debug("Relative branches:")
+        for key, addr in self.jump_table.rel_sources.items():
+            self.logger.debug(f"  {key:#x} -> {addr}")
+
+    def _create_basic_blocks(self) -> None:
+        """
+        Now iterate over the assembly again and split it to basic blocks using the branching
+        information from earlier.
+        """
+        self.basic_blocks = {}
+
+        curr_basic_block: BasicBlock | None = None
+        # Store last block if ending with branch opcode
+        prev_branch_block: BasicBlock | None = None
+
+        # block completion flag (introduced for SPARC pipeline)
+        block_completion: int = 0
+
+        for instruction in self.instructions:
+            # if block completion is in progress
+            if block_completion > 0:
+                block_completion -= 1
+                if block_completion > 0 and curr_basic_block:
+                    self.basic_blocks[curr_basic_block.key].add_instruction(instruction)
+                    continue
+                curr_basic_block = None
+
+            # Current program counter
+            pc_addr = instruction.address
+            # Get optional jump target
+            jump_target = self.jump_table.get_target(pc_addr or Address(None))
+            is_unconditional = self.configuration.architecture.is_unconditional_branch(
+                instruction,
+            )
+
+            # Start new blocks if last ended
+            if curr_basic_block is None and pc_addr is not None and pc_addr.abs_addr is not None:
+                # Create new basic block
+                self.basic_blocks[pc_addr.abs_addr] = curr_basic_block = BasicBlock(
+                    key=pc_addr.abs_addr,
+                )
+
+                # if previous basic block ended in branch instruction. Add the basic
+                # block what follows if the jump was not taken.
+                if prev_branch_block is not None:
+                    prev_branch_block.add_no_jump_edge(curr_basic_block)
+                    prev_branch_block = None
+            # or if current address is a jump target
+            elif (
+                curr_basic_block is not None
+                and pc_addr is not None
+                and pc_addr.abs_addr is not None
+                and self.jump_table.is_jump_target(pc_addr)
+            ):
+                closing_block = curr_basic_block
+                self.basic_blocks[pc_addr.abs_addr] = curr_basic_block = BasicBlock(
+                    key=pc_addr.abs_addr,
+                )
+                closing_block.add_no_jump_edge(pc_addr.abs_addr)
+
+            if curr_basic_block is not None:
+                curr_basic_block.add_instruction(instruction)
+
+            # End current block if current opcode is a jump/branch/sink
+            if jump_target and curr_basic_block:
+                curr_basic_block.add_jump_edge(jump_target.abs_addr)
+                prev_branch_block = None if is_unconditional else curr_basic_block
+                block_completion = self.configuration.architecture.get_branch_delay(
+                    instruction,
+                )
+            elif self.configuration.architecture.is_sink(instruction):
+                block_completion = self.configuration.architecture.get_branch_delay(
+                    instruction,
+                )
+                prev_branch_block = None
+
+        if prev_branch_block:
+            # If last instruction of the function is jump/call, then add dummy
+            # block to designate end of the function.
+            end_instruction = Instruction(
+                0,
+                Address(None),
+                "",
+                [],
+                Address(None),
+            )
+            end_block = BasicBlock("end_of_function")
+            end_block.add_instruction(end_instruction)
+            prev_branch_block.add_no_jump_edge(end_block.key)
+            self.basic_blocks[end_block.key] = end_block

ocgraph/interface/coverage_reader.py

@@ -0,0 +1,70 @@
+# SPDX-License-Identifier: GTDGmbH
+"""Class for read coverage input and update the instruction."""
+
+from __future__ import annotations
+
+import ast
+import csv
+from typing import TYPE_CHECKING
+
+from ocgraph.data import Address, Instruction
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ocgraph.configuration import OcGraphConfiguration
+
+
+class CoverageReader:  # pylint: disable=too-few-public-methods
+    """CoverageReader Class."""
+
+    def __init__(
+        self,
+        instructions: list[Instruction],
+        config: OcGraphConfiguration,
+    ) -> None:
+        self.instructions = instructions
+        self.config = config
+
+    def update_by_csv(self, file_path: str) -> None:
+        """Read coverage csv file and update."""
+        # Store for coverage information
+        coverage_info: dict[int, set[int]] = {}
+
+        # read the csv file. expected values in address and branch_jumps
+        with open(file_path, newline="", encoding="utf-8") as csvfile:
+            reader = csv.DictReader(csvfile)
+            for row in reader:
+                _temp = ast.literal_eval(row["branch_jumps"])
+                coverage_info[int(row["address"], 0)] = {int(x, 0) for x in _temp}
+
+        # update instructions
+        for instr in self.instructions:
+            if (
+                instr.address
+                and instr.address.abs_addr
+                and (covered_branch_targets := coverage_info.get(instr.address.abs_addr, None))
+                is not None
+            ):
+                is_branch = self.config.architecture.is_branch(instr)
+
+                # Check if this is a branch which misses its branch target.
+                # This happens when the branch is indirect and
+                # objdump does not know the address of the branch target.
+                if is_branch:
+                    if instr.target is None:
+                        instr.target = Address(None)
+
+                    if instr.target.abs_addr is None:
+                        max_distance = 0
+                        likely_branch_target = None
+
+                        # Determine the most interesting branch target,
+                        # which is the one furthest away from the branch location
+                        for branch_target in covered_branch_targets:
+                            distance = abs(instr.address.abs_addr - branch_target)
+                            if distance > max_distance:
+                                max_distance = distance
+                                likely_branch_target = branch_target
+
+                        instr.target.abs_addr = likely_branch_target
+
+                instr.update_coverage(covered_branch_targets, is_branch=is_branch)