ACA visualiser

Below is a summary of how to use the ACA visualisation tool.

Running

The visualiser can be run with the following command where the trace and probe files have been generated by a simulator.:

  python3 visualiser <path to trace file> <path to probe file> <stages string> --force

The <stages string> argument is a string of single character named pipeline stages used in the simulator that generated the trace file. As an example, a simulated pipeline with 3 stages Fetch, Decode, and Execute could use the <stages string> "fde". There must be at least 2 pipeline stages and each stage name must be 1 character in length.

The --force argument is an optional argument that forces the re-writing of .cache files for the specified trace and probe files.

File formats

Trace file

The trace file inputted to the tool should contain the set of instructions simulated. Each line represents an instruction and, for an n-stage pipeline, should conform to the following format:

<stage 0>:...:<stage n-1>:<instruction_address>:<microOp_number>:<ID>:<disassembly>

The first n fields represent the cycles in which each pipeline stage was complete, n should match the length of the <stages string> argument provided.

If a flush occurs and not all stages are reached by the instruction, the value of those stages should be set to 0. The <instruction_address> is the PC value of the instruction in a hexadecimal format. For the ACA class, the <microOp_number> field can be ignored and set to 0 whilst the <ID> field should be a unique numerical value allocated sequentially to each fetched instruction. Finally, the <disassembly> field is the instruction opcode and operand in a string format. Below are some examples:

InOrder with stages Fetch/Decode/Execute (<stages string> = fde):

• Without flush

10:11:33:0x00009c:0:39:div x23, x22, x0

• With flush after decode

10:11:0:0x00009c:0:39:div x23, x22, x0

OutOfOrder with stages Fetch/Decode/Rename/Dispatch/Issue/Complete/Retire (<stages string> = fdnpicr):

• Without flush

10:11:12:13:14:37:38:0x00009c:0:39:div x23, x22, x0

• With flush after rename

10:11:12:0:0:0:0:0x00009c:0:39:div x23, x22, x0

Probe file

The probe file contains the occurrence of each probe event. Each line represents a cycle and within a line should be all probe events that occurred during the single cycle. A line in the probe file must follow the format:

<probe_event>,<instruction_ID>:<probe_event>,<instruction_ID>:...

If a probe event did not occur within the cycle, a "-" symbol is used.

The <probe_event> field is a numerical value that relates to the defined set at the top of the visualisation.py file within the probe_titles list. The probe_event defines an index in the list, for example from the list:

probe_titles=[
             ("Stalled.fetch.instructionFetch","s"),
             ("Stalled.fetch.instructionDecode","s"),
             ("Stalled.rename.robFull","s"),
             ...
             ]

<probe_event> 1 would relate to "Stalled.fetch.instructionDecode". There is no defined format for the names of the entries in the probe_titles list but each must be a pair of strings containing a probe name and a probe type. The following probe types are used by the tool:

• e, Exception
• h, Halt
• s, Stall
• b, Branch
• f, Flush

A suggested format for the probe names would be <Probe Type>.<Pipeline Unit>.<Reason>.

The <instruction_ID> field should be the trace <ID> field on the instruction that caused the <probe_event> to occur. If the event wasn't caused by an instruction, then it can be set to 0. An example snippet of 8 cycles within a probe file is given below:

-
14,30
-
7,30:8,33
-
-
2,41:9,0
-

Display

The visualiser interface is split into 5 windows. The Timeline window displays the traces of each instruction whilst the right-adjacent window displays information about each instruction detailed in the window header.

The bottom 3 windows are related to probing. The far-left bottom window shows the probes that occurred in the displayed trace timeline whilst the middle bottom window shows which probe-type each line is displaying. Finally, the far-right bottom window shows any instruction numbers that are associated with the probes that have occurred, the instruction numbers displayed line-up with the display of the probes from left-to-right i.e. the first instruction number will link to the left-most probe occurrence.

Controls

The "up" and "down arrow" keys can be used to scroll the timeline up and down respectively whilst the "page up" and "page down" keys can be used to jump to the next instruction above or below the currently displayed instructions respectively.

If some information cannot be viewed as it goes beyond the window sizes then the "left" and "right arrow" keys can be used to horizontally scroll.

The "q" key can be used to exit the program.

Selecting probes

To open the probe selection the "p" key should be pressed. Within this menu, the "up" and "down arrows" can be used to move the selector and the "enter" key can be used to toggle the selected probe on or off. The "a" key can be used to select all probes and the "n" key to deselect all probes.

The "z" key can be used to confirm the selection.

Jumping to specific instructions

To open the jump-to menu the "j" key should be pressed. Within this menu, an instruction number can be typed and jumped to. The "enter" key confirms the input and the "backspace" key can be used to undo the input.

The "z" key can be used to exit the menu.

Example inputs

In the examples folder, two sets of example trace and probe file inputs have been provided as a way to explore the tool and get to grips with its usage. One set offers an output from a 3-stage scalar inorder pipeline whilst the other a 7-stage 4-way superscalar outoforder pipeline.

Visualiser snapshot

Below is a snapshot of the visualiser tool in use: