Skip to content

Latest commit

 

History

History
 
 

utils

README.md

Programming Examples Utilities

These utilities are helpful in the current programming examples context and include helpful C/C++ libraries, and python and shell scripts.

Open CV Utilities (OpenCVUtils.h)

OpenCV utilities used in vision processing pipelines to help read and/or initialize images and video. Currently supported functions include the following. Please view header for more specific function information.

  • imageCompare
  • readImage
  • initializeSingleGrayImageTest
  • initializeSingleImageTest
  • initializeVideoCapture
  • initializeVideoFile
  • addSaltPepperNoise
  • medianBlur1D

Clean microcode shell script (clean_microcode.sh)

Shell script to do in-place cleanup of microcode files (e.g. core_*.lst). When viewing microcode, it's helpful for some of the extra information like hardware and software breakpoints to be removed so it's easier to see back-to-back lines of microcode.

Trace parser (parse_trace.py)

The text file generated by the host code (test.cpp or test.py) are formatted as 32-bit hex values, one per line. This python script parses the raw trace packet data and creates a waveform json file for view on Perfetto http://ui.perfetto.dev. The script syntax is:

parse_trace.py --filename trace.txt --mlir build/aie_trace.mlir --colshift 1 > parse_eventIR_vs.json
  • --filename : Input trace packet text file. This is generated during the running of our python host code
  • --mlir : MLIR source. This is needed to parse what events and tiles we are monitoring to generate labels for our waveform visualizer.
  • --colshift : runtime column shift. This specifies how much the actual design was shifted from the default position when it was scheduled and called. The reason we need this is becuase even if our design is configured for column 0, the actual loading and execution of the design may place it in column 1, 2, 3 etc. We account for this shift since the parser needs to match the actual column location of the generated trace data. Usually 1 is the right value. NOTE - the underlying tools currently default to column 1 to avoid using column 0 on Ryzen AI since that column does not have a shimDMA and is therefore avoided at the moment.

Trace parser - eventIR based (parse_eventIR.py)

The text file generated by the host code (test.cpp or test.py) are formatted as 32-bit hex values, one per line. This python script executes a number of steps in order to transform it from trace packet text file into a waveform json file.

NOTE - There seems to be some inconsistencies in the results generated by this parser. As of now, it is used to compare to existing the hwfrontend tool only.

The script syntax is:

parse_eventIR.py --filename trace.txt --mlir build/aie_trace.mlir --colshift 1 > parse_eventIR_vs.json
  • --filename : Input trace packet text file. This is generated during the running of our python host code
  • --mlir : MLIR source. This is needed to parse what events and tiles we are monitoring to generate labels for our waveform visualizer.
  • --colshift : runtime column shift. This specifies how much the actual design was shifted from the default position when it was scheduled and called. The reason we need this is becuase even if our design is configured for column 0, the actual loading and execution of the design may place it in column 1, 2, 3 etc. We account for this shift since the parser needs to match the actual column location of the generated trace data. Usually 1 is the right value. NOTE - the underlying tools currently default to column 1 to avoid using column 0 on Ryzen AI since that column does not have a shimDMA and is therefore avoided at the moment.

The parse script create a temporary directory tmpTrace performs the following steps within that folder:

  1. Fixes raw trace data
  2. Parse MLIR to build event table
  3. Create .target file
  4. Create config.json
  5. Run Vitis/aietools hwfrontend utility to parse raw trace data --> generates eventIR.txt
  6. Convert eventIR.txt to perfetto_compatible.json

1. Fixes raw trace data

We prepend 0x before each hex line and save it prep.<trace file> since the hwfrontend utility expects it.

2. Parse MLIR to build event table

The MLIR parser is pretty rudimentary as it scans the source mlir file looking for aiex.npu.write32 calls and does a pattern match for trace unit config address and then grab the hex events, which it looks up from an internal table to provide waveform labels. It would be better to use an MLIR pass that already has the config information and cross reference it with a more official event-to-label lookup table instead.

3. Create .target file

Create a dummy file (.target) in the tmpTrace with the file content 'hw' since hwfrontend utility expects it.

4. Create config.json

This step uses the information from the MLIR parse step to create a fixed config that has the matching events in a config.json file. This file is used by hwfrontend when it's parsing the trace packet data. While core tile config seems correct, memtile and shimtile are not yet supported or tested.

5. Run Vitis/aietools hwfrontend utility to parse raw trace data --> generates eventIR.txt

This is the main parse utility that generates a much more friendly eventIR file format. This utilty is the same one used by the adf tools for aiesimulator. However, the utility is very particular and some combinations of trace packet data might confuse the parser or cause an error. See the Tips section at the end for workarounds to known issues.

6. Convert eventIR.txt to perfetto_compatible.json

While the Perfetto-compliant json file format is not the same as the eventIR file format. The conversion between them is more straightforward that between trace packets and Perfetto-compliant json. Having said that, it is still possible this pass to be further tested and improved.

Tips

Workaround 1: For case where the start event is 1 or maybe in general, the trace output might have a few packets with just 0xdbffdbff data. These seem to give the following error and needs to have those packets deleted up to an actual valid event packet.

CRITICAL WARNING: [hwanalyze 77-5570] trace_out_hex3:1 Start Frame for Tile(2, 4) Module: cm looks to be missing as trace configuration is not available.

Workaround 2: If the start timer value is too large, it reports an error:

WARNING: [hwanalyze 77-5569] trace_out_hex2:1 Overrun Tile(2, 4) Module: cm. Hence further decoding of this particular module will be skipped.

So reducing the start frame from something like:

0xf4000000
0x00a93c62

to

0xf0000000
0x0005d0f7

which reduces the timer from 11,091,042 cycles to 381,175 seems to fix it.