Add a callable library function to parse_trace.py

[fifield]

This PR:

• Makes python/utils/parse_trace.py importable and
• Adds a function parse_trace that operates similar to the command line. The command line version is unchanged.
• Add an integration test test/npu-xrt/vec_mul_event_trace which generates trace then calls parse_trace and checks the trace from the python host code.

[Copilot]

Pull Request Overview

This PR makes python/utils/parse_trace.py importable as a library and adds a callable parse_trace() function that can process trace data programmatically. The command-line interface is preserved by refactoring the script execution code into a main() function.

Key changes:

• Adds parse_trace() library function that accepts numpy arrays and MLIR strings, returning trace events in Chrome Trace Event Format
• Refactors existing script logic into main() function to enable library usage while preserving CLI functionality
• Adds integration test demonstrating the API usage with event trace validation

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
python/utils/parse_trace.py	Adds library API parse_trace() function and refactors command-line logic into main() function; updates helper functions to accept optional of and debug parameters
test/npu-xrt/vec_mul_event_trace/test.py	Integration test that uses the new parse_trace() API to validate trace events from NPU execution
test/npu-xrt/vec_mul_event_trace/vector_scalar_mul.cc	AIE kernel implementation for vector-scalar multiplication with event markers
test/npu-xrt/vec_mul_event_trace/aie.mlir	MLIR configuration defining trace packet flows, control registers, and buffer descriptors

Comments suppressed due to low confidence (1)

python/utils/parse_trace.py:57

• [nitpick] When parse_trace is called as a library function, printing error messages to stderr and returning False from check_for_valid_trace causes the calling code to raise a ValueError on line 971. However, the error messages on lines 47-55 are still printed to stderr before the ValueError is raised. Consider removing these print statements from the library path since the exception message should be sufficient, or make the error messages conditional on whether this is being called from the library API vs command line.

def check_for_valid_trace(filename, trace_pkts, of=None, debug=False):
    if debug and of:
        print("len(trace_pkts): ", str(len(trace_pkts)), file=of)
        print("trace_pkts[0]:", trace_pkts[0], file=of)
    if len(trace_pkts) < 2 or trace_pkts[0] == "00000000":
        print(
            "[ERROR] Empty trace file. Valid trace was not written to",
            filename,
            file=sys.stderr,
        )
        print(
            "See https://github.com/Xilinx/mlir-aie/tree/main/programming_guide/section-4/section-4b#Additional-Debug-Hints for additional trace debug tips.",
            file=sys.stderr,
        )
        return False
    return True

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.