avl-riscv-coverage 0.0.1__py3-none-any.whl

avl_riscv_coverage/__init__.py

@@ -0,0 +1,24 @@
+from ._coverage import COVERPACKAGES, CoverPackage
+from ._elf import EXTENSIONS, INSTRUCTIONS, parse_elf
+from ._instr import Instruction
+from ._isa import ISA, Encoding, extract_isa
+from ._spike import parse_spike_log
+from ._trace import TRACE, Trace
+
+# Add version
+__version__ : str = "0.0.1"
+
+__all__ = [
+    "COVERPACKAGES",
+    "CoverPackage",
+    "EXTENSIONS",
+    "INSTRUCTIONS",
+    "parse_elf",
+    "Instruction",
+    "ISA",
+    "extract_isa",
+    "Encoding",
+    "parse_spike_log",
+    "TRACE",
+    "Trace",
+]

avl_riscv_coverage/__main__.py

@@ -0,0 +1,185 @@
+import argparse
+import atexit
+import importlib
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from avl import Coverage
+
+from ._coverage import COVERPACKAGES
+from ._elf import EXTENSIONS, parse_elf
+from ._isa import ISA, extract_isa
+from ._spike import parse_spike_log
+from ._trace import TRACE
+
+# Path of the current script (__main__.py) and reference json file
+script_path = os.path.dirname(os.path.abspath(__file__))
+ref_path = os.path.join(script_path, "instr_dict.json")
+packages_path = os.path.join(script_path, "coverage_packages")
+def main():
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--ref", type=str, default=ref_path, help=f"Pointer to instr_dict.json (generated from https://github.com/riscv/riscv-opcodes) (default: {ref_path})")
+    parser.add_argument("--extensions", nargs="*", default=None, help="List of extensions")
+    parser.add_argument("--packages", nargs="*", default=[packages_path], help="List of python packages containing covergroups")
+    parser.add_argument("--elf", default=None, help="Elf file for testcase")
+    parser.add_argument("--trace", default=None, help="List of trace files")
+    parser.add_argument("--output", default="output", help="Output directory for report")
+    parser.add_argument("--html", action="store_true", help="Generate HTML report")
+    parser.add_argument("--verbose", action="store_true", help="Verbose messages")
+
+    args = parser.parse_args()
+
+    # Parse ISA
+    # Creates reference dict for all encodings supported
+    if args.verbose:
+        print(f"Parsing reference json file : {args.ref} ... ", end="")
+
+    if args.ref is None or not os.path.exists(args.ref):
+        print(f"ERROR : must supply a valid instruction reference json file (searched for: {args.ref})")
+        sys.exit(1)
+    else:
+        extract_isa(args.ref)
+
+    if args.verbose:
+        print("OK")
+
+    # Parse the elf file
+    # Constructs the dicts of instructions and extensions in the elf
+    if args.verbose:
+        print(f"Parsing elf file : {args.elf} ... ", end="")
+
+    if args.elf is None or not os.path.exists(args.elf):
+        print(f"ERROR : must supply a valid elf file (searched for {args.elf})")
+        sys.exit(1)
+    else:
+        parse_elf(args.elf)
+
+    if args.verbose:
+        print("OK")
+
+    # Prune un-supported extensions
+    if args.verbose:
+        print("Pruning un-supported encodings ... ", end="")
+
+    prune = []
+    for k, v in ISA.items():
+        # Remove instructions with different base
+        if v.base not in ["RV", EXTENSIONS["base"]]:
+            prune.append(k)
+            continue
+
+        # Remove instructions from unsupported extensions
+        matches = list(set(v.extensions) & set(EXTENSIONS.keys()))
+        if len(matches) == 0:
+            prune.append(k)
+
+    a = len(ISA)
+    for p in prune:
+        del ISA[p]
+    b = len(ISA)
+
+    if args.verbose:
+        print(f"{a-b} removed")
+
+    # Parse Tracefile
+    if args.verbose:
+        print(f"Parsing trace file : {args.trace} ... ", end="")
+
+    if args.trace is None or not os.path.exists(args.trace):
+        print(f"ERROR : must supply a valid trace (searched for: {args.trace})")
+        sys.exit(1)
+    else:
+        parse_spike_log(args.trace)
+
+    if args.verbose:
+        print("OK")
+
+
+    # Create output directory
+    if args.verbose:
+        print(f"Creating output directory : {args.output} ... ", end="")
+
+    try:
+        path = Path(args.output)
+        path.mkdir(parents=True, exist_ok=True)
+    except Exception:
+        print("Failed to create {args.output} {e}")
+        sys.exit(1)
+
+    if args.verbose:
+        print("OK")
+
+    # Create covergroups
+    if args.packages is not None:
+        if args.verbose:
+            print(f"Adding coverage packages : {','.join(args.packages)} ... ", end="")
+
+        for p in map(Path, args.packages):
+            assert p.is_dir(), f"Packages must be directories: {p}"
+
+            for f in sorted(p.rglob("*.py")):
+                package_name = os.path.basename(f).split(".",1)[0]
+                package_spec = importlib.util.spec_from_file_location(package_name, Path(f))
+                package_module = importlib.util.module_from_spec(package_spec)
+                package_spec.loader.exec_module(package_module)
+
+        if args.verbose:
+            print("OK")
+
+    # Process traces
+    if args.verbose:
+        print("Processing Trace ... ", end="")
+
+    instr = TRACE[0]
+    while True:
+        if instr is None:
+            break
+
+        # Sample all Coverpackages
+        for p in COVERPACKAGES:
+            p.sample(instr)
+
+        instr = instr.next
+
+    if args.verbose:
+        print("OK")
+
+    # Move coverage.json to output
+    if args.verbose:
+        print(f"Moving coverage.json to {args.output} ... ", end="")
+
+    try:
+        # Call the atexit to generate the report - then prevent pre-registered callback
+        Coverage().__at_exit__()
+        atexit.unregister(Coverage().__at_exit__)
+
+        Path("coverage.json").replace(Path(os.path.join(args.output, "coverage.json")))
+    except Exception as e:
+        print(f"Failed to relocate coverage.json to {args.output} : {e}")
+        sys.exit(1)
+
+    if args.verbose:
+        print("OK")
+
+    # Generate report
+    if args.html:
+        if args.verbose:
+            print(f"Generating report {args.output}/html/index.html ... ", end="")
+
+        try:
+            subprocess.run(
+                ['avl-coverage-analysis', '--path', args.output, "--output", os.path.join(args.output, "html"), "--stats"],
+                capture_output=True, text=True, check=True
+            )
+        except (subprocess.CalledProcessError, FileNotFoundError) as e:
+            print(f"Could not run avl-coverage-analysis: {e}")
+            sys.exit(1)
+
+        if args.verbose:
+            print("OK")
+
+if __name__ == "__main__":
+    main()

avl_riscv_coverage/_coverage.py

@@ -0,0 +1,32 @@
+from ._trace import Trace
+
+COVERPACKAGES = []
+"""
+List of all registered CoverPackage classes
+"""
+
+class CoverPackage:
+
+    def __init__(self, name : str) -> None:
+        """
+        Constructor
+
+        :param name: Coverage Package name
+        :type name: str
+        """
+        self.name = name
+
+    def sample(self, trace : Trace) -> None:
+        """
+        Sample a given trace element
+
+        :param trace: Trace element
+        :type trace: Trace
+        """
+        raise ValueError(f"Unimplemented sample function: {self.name}")
+
+
+__all__ = [
+    "COVERPACKAGES",
+    "CoverPackage",
+]

avl_riscv_coverage/_elf.py

@@ -0,0 +1,154 @@
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+from elftools.elf.elffile import ELFFile
+
+from ._instr import Instruction
+
+INSTRUCTIONS: dict[str, Instruction]= {}
+"""Dictionary of all instructions based on contents of elf file"""
+
+EXTENSIONS: dict[str, str] = {}
+"""Dictionary of all available extensions and their version based on properties of elf file"""
+
+
+def _parse_arch_string_(arch_string : str) -> dict[str, str]:
+    """
+    Parse RISC-V architecture string like 'rv64i2p1_m2p0_a2p1...'
+
+    :param arch_string: Architectural definition string extracted from elf
+    :type arch_string: str
+    :returns Dictionary of extensions and versions
+    :rtype : dict[str, str]
+    """
+
+    extensions = {}
+
+    if not arch_string.startswith('rv'):
+        return extensions
+
+    # Extract base (rv32/rv64)
+    if arch_string.startswith('rv64'):
+        base = 'RV64'
+        rest = arch_string[4:]
+    elif arch_string.startswith('rv32'):
+        base = 'RV32'
+        rest = arch_string[4:]
+    else:
+        return extensions
+
+    extensions['base'] = base
+
+    # Split by underscore
+    parts = rest.split('_')
+
+    # Parse each extension with version
+    # Format: extension_name + version (e.g., i2p1, m2p0, zicsr2p0)
+    for part in parts:
+        if not part:
+            continue
+
+        # Match pattern: letters followed by optional version (digit+p+digit)
+        match = re.match(r'^([a-z]+)(\d+p\d+)?$', part, re.IGNORECASE)
+        if match:
+            ext_name = match.group(1).upper()
+            version = match.group(2) if match.group(2) else None
+
+            # Handle special case: 'g' expands to imafd + zicsr + zifencei
+            if ext_name == 'G':
+                extensions['I'] = version
+                extensions['M'] = version
+                extensions['A'] = version
+                extensions['F'] = version
+                extensions['D'] = version
+                extensions['Zicsr'] = version
+                extensions['Zifencei'] = version
+            else:
+                extensions[ext_name] = version
+
+    return extensions
+
+def _parse_riscv_attribes_(data : str) -> dict[str, str]:
+    """
+    Quick parser specifically for your data format
+
+    :param data: Attributes data extracted from elf file
+    :type data: str
+    :returns Dictionary of extensions and versions
+    :rtype : dict[str, str]
+    """
+
+    # Find the architecture string (starts with 'rv')
+    arch_start = data.find(b'rv')
+    if arch_start == -1:
+        return None
+
+    # Find the null terminator after the arch string
+    arch_end = data.find(b'\x00', arch_start)
+    if arch_end == -1:
+        arch_end = len(data)
+
+    arch_string = data[arch_start:arch_end].decode('ascii')
+
+    return _parse_arch_string_(arch_string)
+
+def parse_elf(elfpath : Path) -> None:
+    """
+    Parse given elf file.
+    Extract class and instructions
+
+    :param elfpath: path to elf file
+    :type elfpath: path
+    """
+
+    with open(elfpath, "rb") as f:
+        elf = ELFFile(f)
+
+        # Check if it's RISC-V
+        if elf.header['e_machine'] != 'EM_RISCV':
+            raise ValueError (f"Not a RISC-V binary: {elf.header['e_machine']}")
+
+        # Extract Extensions
+        attrs_section = elf.get_section_by_name('.riscv.attributes')
+
+        if not attrs_section:
+            raise ValueError("No .riscv.attributes section found")
+        else:
+            EXTENSIONS.update(_parse_riscv_attribes_(attrs_section.data()))
+
+        # Discover mode
+        if EXTENSIONS["base"] not in ["RV64", "RV32"]:
+            raise ValueError(f"Unknown base architecture {EXTENSIONS['base']}")
+
+        # Run objdump to extract instructions
+        try:
+            result = subprocess.run(
+                ['riscv64-unknown-elf-objdump', '-d', elfpath],
+                capture_output=True, text=True, check=True
+            )
+
+            for line in result.stdout.split('\n'):
+                # Parse: "  2000000342:	0d0075d7          	vsetvli	a1,zero,e32,m1,ta,ma"
+                match = re.match(r'\s*([0-9a-f]+):\s+([0-9a-f]+)\s+(.+)', line)
+                if match:
+                    addr = int(match.group(1), 16)
+                    bytes_hex = int(match.group(2), 16)
+
+                    INSTRUCTIONS[addr] = Instruction(addr, bytes_hex)
+
+        except (subprocess.CalledProcessError, FileNotFoundError) as e:
+            print(f"Could not run objdump: {e}")
+            sys.exit(1)
+
+        # Link instructions to prev / next
+        for instr in INSTRUCTIONS.values():
+            n = INSTRUCTIONS.get(instr.pc + instr.size, None)
+            instr.link(n)
+
+__all__ = [
+    "INSTRUCTIONS",
+    "EXTENSIONS",
+    "parse_elf",
+    ]

avl_riscv_coverage/_instr.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from ._isa import Encoding
+
+
+class Instruction:
+    def __init__(self, pc : int, encoding_bytes : int) -> None:
+        """
+        Constructor
+
+        :param pc: Program counter
+        :type pc: int
+        :param encoding_bytes: Instruction encoding
+        :type encoding_bytes: int
+        """
+        self.pc = pc
+        self.encoding_bytes = encoding_bytes
+        self.encoding = None
+        self.operands = {}
+        self.prev = None
+        self.next = None
+
+        self.decode()
+
+    def __str__(self) -> str:
+        """
+        Return a string representation of the Instruction.
+
+        :return: String representation of the Instruction.
+        :rtype: str
+        """
+
+        s = f"{self.pc:016x} : "
+        s += f"{self.prev.encoding.mnemonic}" if self.prev is not None else "None"
+        s += " -> "
+        s += f"\033[31m{self.encoding.mnemonic}\033[0m"
+        s += " -> "
+        s += f"{self.next.encoding.mnemonic}" if self.next is not None else "None"
+
+        return s
+
+    def link(self, next : Instruction) -> None:
+        """
+        Create 2 way link to next instruction (if you can)
+
+        Next / Prev refers to location in program (i.e. pc +/- one instruction)
+        not location in trace
+
+        :param next: Next instruction
+        :type next: Instruction
+        """
+        if next is not None:
+            self.next = next
+            self.next.prev = self
+
+
+    def decode(self) -> None:
+        """
+        Decode instruction to get mnemonic and operands
+        """
+
+        # Determine size (compressed or standard)
+        if (self.encoding_bytes & 0b11) != 0b11:
+            self.size = 2
+            instr_code = self.encoding_bytes & 0xFFFF
+        else:
+            self.size = 4
+            instr_code = self.encoding_bytes & 0xFFFFFFFF
+
+        self.encoding = Encoding.get_encoding(instr_code)
+
+        # Extract Operand Values
+        for k in self.encoding.operands.keys():
+            self.operands[k] = Encoding.get_operand(instr_code, k)
+
+__all__ = [
+    "Instruction"
+]