out-to-vcd.py

#!/usr/bin/env python3
"""
I/R/M trace -> VCD (no de-dup), with fixed byte-swapping of file hex.

Input lines:
  I <imageID> <imageOffset_hex>
  R <regname> -> <hex>
  M <addr_hex> -> <hex>

Behavior:
  - Time += 1 per I line (#0, #1, ...).
  - Signals:
      img_I<imageID>   (image offsets)
      reg_<regname>
      mem_0x<addr>
  - Each signal width = max hex width seen for that signal (bits).
  - Every R/M line emits a value change (no de-dup).
  - **Endianness**: file hex is **byte-swapped** before emission (MSB-first in VCD).
"""

import argparse
import gzip
import io
import re
from pathlib import Path
from typing import Dict, List, Tuple, TextIO

RE_I = re.compile(r'^\s*I\s+(\d+)\s+([0-9a-fA-F]+)\s*$')                # I <imageID> <imageOffset_hex>
RE_R = re.compile(r'^\s*R\s+([A-Za-z0-9_]+)\s*->\s*([0-9a-fA-F]+)\s*$')  # R <reg> -> <hex>
RE_M = re.compile(r'^\s*M\s+([0-9a-fA-F]+)\s*->\s*([0-9a-fA-F]+)\s*$')   # M <addr_hex> -> <hex>

SWAP_IMAGE = True
SWAP_REG   = True
SWAP_MEM   = True

def open_text_auto(path: Path) -> TextIO:
    if str(path).endswith(".gz"):
        return io.TextIOWrapper(gzip.open(path, "rb"), encoding="utf-8", errors="replace")
    return path.open("rt", encoding="utf-8", errors="replace")

def make_id(n: int) -> str:
    base = 94
    s = ""
    while True:
        s += chr(ord('!') + (n % base))
        n //= base
        if n == 0:
            return s

def normalize_hex(hexv: str, nibbles: int) -> str:
    hexv = hexv.strip()
    if hexv.lower().startswith("0x"):
        hexv = hexv[2:]
    return hexv.zfill(nibbles)

def swap_bytes_hex(hexv: str) -> str:
    """Swap endianness at byte granularity."""
    if len(hexv) % 2:
        hexv = "0" + hexv
    b = [hexv[i:i+2] for i in range(0, len(hexv), 2)]
    b.reverse()
    return "".join(b)

def hex_to_bits_msb(hexv: str, width_bits: int) -> str:
    return bin(int(hexv or "0", 16))[2:].zfill(width_bits)

def first_pass(infile: TextIO):
    image_order: List[int] = []
    image_off_width: Dict[int, int] = {}
    reg_order: List[str] = []
    reg_width: Dict[str, int] = {}
    mem_order: List[int] = []
    mem_width: Dict[int, int] = {}

    for raw in infile:
        s = raw.strip()
        if not s:
            continue
        if (m := RE_I.match(s)):
            image_id = int(m.group(1))
            offs = m.group(2)
            wbits = 4 * len(offs)
            if image_id not in image_off_width:
                image_off_width[image_id] = wbits
                image_order.append(image_id)
            elif wbits > image_off_width[image_id]:
                image_off_width[image_id] = wbits
            continue
        if (m := RE_R.match(s)):
            reg, val = m.group(1), m.group(2)
            wbits = 4 * len(val)
            if reg not in reg_width:
                reg_width[reg] = wbits
                reg_order.append(reg)
            elif wbits > reg_width[reg]:
                reg_width[reg] = wbits
            continue
        if (m := RE_M.match(s)):
            addr = int(m.group(1), 16)
            val = m.group(2)
            wbits = 4 * len(val)
            if addr not in mem_width:
                mem_width[addr] = wbits
                mem_order.append(addr)
            elif wbits > mem_width[addr]:
                mem_width[addr] = wbits
            continue

    return image_order, image_off_width, reg_order, reg_width, mem_order, mem_width

def convert(in_path: Path, out_path: Path, *, timescale="1ns",
            scope_image="image", scope_regs="regs", scope_mem="mem",
            emit_comments=False):
    with open_text_auto(in_path) as f:
        image_order, image_off_width, reg_order, reg_width, mem_order, mem_width = first_pass(f)

    # Assign ids: images first, then regs, then mem
    ids: Dict[str, str] = {}
    i = 0
    for image_id in image_order:
        ids[f"img_I{image_id}"] = make_id(i); i += 1
    for reg in reg_order:
        ids[f"reg_{reg}"] = make_id(i); i += 1
    for addr in mem_order:
        ids[f"mem_0x{addr:016X}"] = make_id(i); i += 1

    with out_path.open("wt", encoding="utf-8") as out, open_text_auto(in_path) as f:
        # Header
        out.write(f"$date\n  generated from {in_path.name}\n$end\n")
        out.write("$version\n  I/R/M -> VCD (byte-swapped, no de-dup)\n$end\n")
        out.write(f"$timescale {timescale} $end\n")

        out.write(f"$scope module {scope_image} $end\n")
        for image_id in image_order:
            w = image_off_width[image_id]
            out.write(f"$var wire {w} {ids[f'img_I{image_id}']} img_I{image_id} $end\n")
        out.write("$upscope $end\n")

        out.write(f"$scope module {scope_regs} $end\n")
        for reg in reg_order:
            w = reg_width[reg]
            out.write(f"$var wire {w} {ids[f'reg_{reg}']} reg_{reg} $end\n")
        out.write("$upscope $end\n")

        out.write(f"$scope module {scope_mem} $end\n")
        for addr in mem_order:
            w = mem_width[addr]
            out.write(f"$var wire {w} {ids[f'mem_0x{addr:016X}']} mem_0x{addr:016X} $end\n")
        out.write("$upscope $end\n")

        out.write("$enddefinitions $end\n")

        # Unknown init
        out.write("$dumpvars\n")
        for image_id in image_order:
            out.write("b" + ("x" * image_off_width[image_id]) + f" {ids[f'img_I{image_id}']}\n")
        for reg in reg_order:
            out.write("b" + ("x" * reg_width[reg]) + f" {ids[f'reg_{reg}']}\n")
        for addr in mem_order:
            out.write("b" + ("x" * mem_width[addr]) + f" {ids[f'mem_0x{addr:016X}']}\n")
        out.write("$end\n")

        # Body
        tick = -1
        have_time = False
        for raw in f:
            line = raw.rstrip("\n")

            # I <imageID> <imageOffset_hex>
            if (mi := RE_I.match(line)):
                image_id = int(mi.group(1))
                offs_hex = mi.group(2)
                tick += 1
                out.write(f"#{tick}\n")
                if emit_comments:
                    out.write(f"$comment IMAGE={image_id} OFFSET=0x{offs_hex} $end\n")
                have_time = True

                nibbles = image_off_width[image_id] // 4
                offs_norm = normalize_hex(offs_hex, nibbles)
                if SWAP_IMAGE:
                    offs_norm = swap_bytes_hex(offs_norm)
                bits = hex_to_bits_msb(offs_norm, image_off_width[image_id])
                out.write(f"b{bits} {ids[f'img_I{image_id}']}\n")
                continue

            s = line.strip()

            # R <reg> -> <hex>
            if (mr := RE_R.match(s)):
                if not have_time:
                    tick += 1
                    out.write(f"#{tick}\n")
                    have_time = True
                reg, hexv = mr.group(1), mr.group(2)
                nibbles = reg_width[reg] // 4
                val = normalize_hex(hexv, nibbles)
                if SWAP_REG:
                    val = swap_bytes_hex(val)
                bits = hex_to_bits_msb(val, reg_width[reg])
                out.write(f"b{bits} {ids[f'reg_{reg}']}\n")
                continue

            # M <addr_hex> -> <hex>
            if (mm := RE_M.match(s)):
                if not have_time:
                    tick += 1
                    out.write(f"#{tick}\n")
                    have_time = True
                addr = int(mm.group(1), 16)
                hexv = mm.group(2)
                nibbles = mem_width[addr] // 4
                val = normalize_hex(hexv, nibbles)
                if SWAP_MEM:
                    val = swap_bytes_hex(val)
                bits = hex_to_bits_msb(val, mem_width[addr])
                out.write(f"b{bits} {ids[f'mem_0x{addr:016X}']}\n")
                continue

def main():
    ap = argparse.ArgumentParser(description="Convert I(imageID,imageOffset)/R/M trace to VCD (byte-swapped).")
    ap.add_argument("input", type=Path, help="Input trace (.out or .gz)")
    ap.add_argument("-o", "--output", type=Path, help="Output VCD (default: input with .vcd)")
    ap.add_argument("--timescale", default="1ns")
    ap.add_argument("--scope-image", default="image")
    ap.add_argument("--scope-regs", default="regs")
    ap.add_argument("--scope-mem", default="mem")
    ap.add_argument("--comments", action="store_true", help="Emit $comment IMAGE/OFFSET after each tick")
    args = ap.parse_args()

    in_path: Path = args.input
    out_path: Path = args.output or in_path.with_suffix(".vcd")

    convert(
        in_path=in_path,
        out_path=out_path,
        timescale=args.timescale,
        scope_image=args.scope_image,
        scope_regs=args.scope_regs,
        scope_mem=args.scope_mem,
        emit_comments=args.comments,
    )
    print(f"Wrote: {out_path}")

if __name__ == "__main__":
    main()