Skip to content

Commit 0ec7b0e

Browse files
uslsteenuslsteen
authored
uScope Introduction (#1)
* Introduced tool for converting O3PipeView output to Perfetto tracings * This initial release transforms textual O3PipeView debug output into JSON traces compatible with Perfetto/Chrome Tracing. * The project was named uScope (microScope) because it is dedicated to microarchitectural research * It provides an interactive visualization of O3CPU pipeline stages and execution unit occupancy. * Introduced Quick Start video * [infra] Reference tracing compressed into archive * [infra] GitHub workflows was introduced
1 parent d08876f commit 0ec7b0e

28 files changed

Lines changed: 2440 additions & 2 deletions

‎.github/workflows/python-ci.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ master ]
6+
pull_request:
7+
branches: [ master ]
8+
9+
jobs:
10+
test:
11+
runs-on: ubuntu-latest
12+
strategy:
13+
matrix:
14+
python-version: ["3.8", "3.9", "3.10", "3.11"]
15+
16+
steps:
17+
- name: Checkout repository
18+
uses: actions/checkout@v3
19+
20+
- name: Set up Python ${{ matrix.python-version }}
21+
uses: actions/setup-python@v4
22+
with:
23+
python-version: ${{ matrix.python-version }}
24+
25+
- name: Install package in development mode
26+
run: |
27+
python -m pip install --upgrade pip
28+
pip install -e .
29+
30+
- name: Run conversion on reference example
31+
run: |
32+
uScope --input-file examples/reference/reference.out \
33+
--output-file reference.json
34+
35+
- name: Compare output with reference
36+
run: |
37+
gunzip -c examples/reference/reference.json.gz > expected.json
38+
diff -u reference.json expected.json

‎README.md‎

Lines changed: 60 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,60 @@
1-
# PipeViewPerfetto
2-
Tool to convert O3PipeView output from Gem5 simulator to Perfetto tracing
1+
# uScope
2+
3+
[![Research Project](https://img.shields.io/badge/Research-Project-blue)](https://github.com/ProteusLab/uScope)
4+
[![gem5](https://img.shields.io/badge/gem5-simulation-green)](https://www.gem5.org)
5+
[![Computer Architecture](https://img.shields.io/badge/Computer-Architecture-orange)](https://en.wikipedia.org/wiki/Computer_architecture)
6+
[![Status: Active](https://img.shields.io/badge/Status-Active-brightgreen)](https://github.com/ProteusLab/uScope)
7+
[![Python 3.8+](https://img.shields.io/badge/Python-3.8%2B-blue)](https://www.python.org)
8+
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
9+
10+
**uScope** gives you a microscopic view of a [gem5](https://www.gem5.org) O3CPU simulation by transforming [PipeView traces]((https://www.gem5.org/documentation/general_docs/cpu_models/visualization/)) into [Perfetto](https://perfetto.dev/) timelines.
11+
12+
Verify, optimize, and explore cycle-approximate simulation with uScope!
13+
14+
<p align="center">
15+
<img src="images/quick_start.gif" alt="Video">
16+
</p>
17+
18+
## Features
19+
20+
- 📊 **Integration with Perfetto / Chrome Tracing** – leverage a modern, fast visualization platform for in‑depth pipeline analysis.
21+
- 🚀 **Extends gem5's performance analysis** – transform O3PipeView traces into an interactive timeline, offering a novel perspective on verification and performance analysis of PipeView traces..
22+
- 🎯 **Identify compute‑bound and memory‑bound bottlenecks** – visualize pipeline stage occupancy and execution unit utilization to quickly determine whether performance is limited by computation or memory access.
23+
- 🔍 **Interactive exploration** – zoom, pan, and inspect individual instructions in Perfetto.
24+
25+
## Quick Start
26+
27+
```bash
28+
pip install --upgrade pip setuptools wheel
29+
git git@github.com:ProteusLab/uScope.git
30+
cd uScope
31+
pip install -e .
32+
```
33+
34+
## Usage
35+
36+
1. Collect a trace from gem5 with the O3PipeView debug flag:
37+
38+
```bash
39+
/path/to/gem5.opt \
40+
--debug-flags=O3PipeView \
41+
--debug-file=trace.out \
42+
configs/example/se.py \
43+
--cpu-type=O3CPU \
44+
--cmd=/path/to/your-program
45+
```
46+
47+
2. Convert the trace:
48+
49+
```bash
50+
uScope --input-file trace.out --output trace.json
51+
```
52+
53+
3. Open ```trace.json``` in Perfetto UI to explore the pipeline.
54+
55+
## Examples
56+
57+
- Explore the [examples/](examples/) directory for assembly programs and their corresponding tracings.
58+
59+
## Contributing
60+
We welcome contributions! Feel free to open issues or submit pull requests.

‎examples/README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Examples
2+
3+
1. [Vector addition sample](vector_addition/)
4+
2. [Reference sample](reference/)

‎examples/reference/README.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Refence Program
2+
3+
- [Reference sample](reference.S) assembly program is designed to test a wide range of [Functional Units in an O3CPU Gem5 simulation](https://github.com/gem5/gem5/blob/stable/src/cpu/o3/FUPool.py).
4+
5+
- It sequentially executes blocks of instructions targeting ```IntALU```, ```IntMultDiv```, ```FP_ALU```, ```FP_MultDiv```, ```SIMD_Unit```, ```ReadPort```, and ```WritePort```. [The resulting O3PipeView trace](reference.json) is used as a reference to verify that uScope correctly maps all operation classes to their respective functional units in the Perfetto JSON output.
6+
7+
## Usage
8+
9+
### 1. Compile
10+
11+
From the `examples/reference` directory, run:
12+
13+
```bash
14+
riscv64-linux-gnu-gcc reference.S -O0 -march=rv64imafdv -mabi=lp64d -static -mcmodel=medany -fvisibility=hidden -nostdlib -nostartfiles -o reference
15+
```
16+
17+
### 2. Collect an O3PipeView trace with gem5
18+
19+
Navigate to your gem5 build directory and execute:
20+
21+
```bash
22+
/path/to/gem5.opt \
23+
--debug-flags=O3PipeView \
24+
--debug-file=reference.out \
25+
configs/example/se.py \
26+
--cpu-type=O3CPU \
27+
--caches \
28+
--cmd=/path/to/reference \
29+
--mem-size=8GB
30+
```
31+
32+
The trace file reference.out will be created in the gem5 output directory (usually ```m5out/```).
33+
34+
### 3. Convert the trace using uScope
35+
36+
In the gem5 output directory (e.g., ```m5out```), run tool:
37+
38+
```bash
39+
uScope --input-file reference.out --output reference.json
40+
```
41+
42+
### 4. Visualize the result
43+
44+
Open the generated reference.json in the Perfetto UI. You can also use the built-in Chrome Tracing viewer at chrome://tracing.
45+
46+
### 5. Compare with the reference
47+
A pre‑converted reference JSON (```reference.json```) is provided in this directory.
48+
You can use it to verify that your conversion matches the expected output.

‎examples/reference/reference.S‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
.section .data
2+
.align 4
3+
int_a: .word 10, 20
4+
int_b: .word 5, 4
5+
int_c: .space 32
6+
7+
.align 4
8+
fp_a: .float 1.0, 2.0
9+
fp_b: .float 0.125, 0.0625
10+
fp_c: .space 32
11+
12+
.align 4
13+
vec_a: .word 100, 200
14+
vec_b: .word 1, 2
15+
vec_c: .space 32
16+
17+
.section .text
18+
.global _start
19+
_start:
20+
# IntALU
21+
la x10, int_a
22+
la x11, int_b
23+
la x12, int_c
24+
li x13, 2
25+
26+
int_alu_loop:
27+
lw x14, 0(x10) # ReadPort
28+
lw x15, 0(x11) # ReadPort
29+
add x16, x14, x15 # IntALU
30+
sub x17, x14, x15 # IntALU
31+
and x18, x14, x15 # IntALU
32+
or x19, x14, x15 # IntALU
33+
sw x20, 0(x12) # WritePort
34+
35+
addi x10, x10, 4
36+
addi x11, x11, 4
37+
addi x12, x12, 4
38+
addi x13, x13, -1
39+
bnez x13, int_alu_loop
40+
41+
# IntMultDiv
42+
la x10, int_a
43+
la x11, int_b
44+
li x13, 2
45+
46+
int_mul_loop:
47+
lw x14, 0(x10) # ReadPort
48+
lw x15, 0(x11) # ReadPort
49+
mul x16, x14, x15 # IntMult
50+
div x17, x14, x15 # IntDiv
51+
sw x18, 0(x12) # WritePort
52+
53+
addi x10, x10, 4
54+
addi x11, x11, 4
55+
addi x13, x13, -1
56+
bnez x13, int_mul_loop
57+
58+
# FP_ALU
59+
la x10, fp_a
60+
la x11, fp_b
61+
la x12, fp_c
62+
li x13, 2
63+
64+
fp_alu_loop:
65+
flw f0, 0(x10) # ReadPort
66+
flw f1, 0(x11) # ReadPort
67+
fadd.s f2, f0, f1 # FloatAdd
68+
fsub.s f3, f0, f1 # FloatAdd
69+
feq.s x14, f0, f1 # FloatCmp
70+
fsw f2, 0(x12) # WritePort
71+
addi x12, x12, 4
72+
fsw f3, 0(x12) # WritePort
73+
addi x12, x12, 4
74+
75+
addi x10, x10, 4
76+
addi x11, x11, 4
77+
addi x13, x13, -1
78+
bnez x13, fp_alu_loop
79+
80+
# FP_MultDiv
81+
la x10, fp_a
82+
la x11, fp_b
83+
la x12, fp_c
84+
li x13, 2
85+
86+
fp_mul_loop:
87+
flw f0, 0(x10) # ReadPort
88+
flw f1, 0(x11) # ReadPort
89+
fmul.s f2, f0, f1 # FloatMult
90+
fdiv.s f3, f0, f1 # FloatDiv
91+
fsw f2, 0(x12) # WritePort
92+
addi x12, x12, 4
93+
fsw f3, 0(x12) # WritePort
94+
addi x12, x12, 4
95+
96+
addi x10, x10, 4
97+
addi x11, x11, 4
98+
addi x13, x13, -1
99+
bnez x13, fp_mul_loop
100+
101+
# 5. SIMD_Unit
102+
la x10, vec_a
103+
la x11, vec_b
104+
la x12, vec_c
105+
li t0, 4
106+
vsetvli t0, t0, e32, m1, ta, ma
107+
108+
vle32.v v1, (x10) # ReadPort
109+
vle32.v v2, (x11) # ReadPort
110+
vadd.vv v3, v1, v2 # SimdAdd
111+
vmul.vv v4, v1, v2 # SimdMult
112+
vse32.v v3, (x12) # WritePort
113+
addi x12, x12, 32
114+
vse32.v v4, (x12) # WritePort
115+
116+
li a0, 0
117+
li a7, 93
118+
ecall

‎examples/reference/reference.json.gz‎

23.5 KB
Binary file not shown.

0 commit comments

Comments
 (0)