busperf 0.1.0

Bus performance analysis tool
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

# Busperf

Copyright (c) 2025 [Antmicro](https://www.antmicro.com)

Busperf helps analyze bus performance and identify throughput bottlenecks based on simulation traces.
It ingests VCD/FST files with an accompanying bus description in YAML, then generates both visual and textual statistics on bus activity.
This helps users quickly identify buses with low utilization or high backpressure.
Additionally, the tool supports Python plugins for analyzing custom bus protocols.

## Usage

### Install and run

```sh
$ cargo install busperf
$ busperf --help
```

Shell completion can be generated as described [here](https://github.com/pacak/bpaf?tab=readme-ov-file#dynamic-shell-completion).

### GUI

![gui example](docs/screenshots/example.png)

In the panel on the left, there is a selectable list of the analyzer buses.
In the main panel on top, there is an overview of the statistics of the selected bus.
Below, there are two plot areas, for each you can select what type of statistics you want to view in it.

#### Shortcuts

- up arrow: move bus selection up
- down arrow: move bus selection down
- Plots:
  - double left click: reset plot view
  - right click: open in surfer

### Documentation

User docs can be found at [antmicro.github.io/busperf/](https://antmicro.github.io/busperf/).

Developer docs can be generated with:
```sh
$ cargo doc --no-deps --open
```

### Examples

- Print statistics about the bus described in `test.yaml` with traces from `test.vcd`
<!-- name="example-test" -->
```sh
cargo run -- analyze tests/test_dumps/test.vcd tests/test_dumps/test.yaml --text
```

- Print all statistics and set max burst delay to 1
<!-- name="example-test-verbose" -->
```sh
cargo run -- analyze tests/test_dumps/test.vcd tests/test_dumps/test.yaml --verbose -m 1 --text
```

- Write statistics to `stat.csv` formatted as CSV
<!-- name="example-csv" -->
```sh
cargo run -- analyze tests/test_dumps/test.vcd tests/test_dumps/test.yaml -o stat.csv --csv
```

- Print statistics to stdout in the md format
<!-- name="example-md" -->
```sh
cargo run -- analyze tests/test_dumps/test.vcd tests/test_dumps/test.yaml --md
```

- Write pretty printed statistics to `out`
<!-- name="example-pretty" -->
```sh
cargo run -- analyze tests/test_dumps/test.vcd tests/test_dumps/test.yaml -o out --text
```

- Clean files generated from examples
<!-- name="example-clean" -->
```sh
rm out stat.csv
```

### Build with `generate-html` feature

To allow Busperf to generate html with embedded viewer and analysis data you need to enable optional `generate-html` feature.
For that you need `cargo` with additional target `wasm32-unknown-unknown` and `wasm-bindgen-cli` installed.

```sh
$ rustup target add wasm32-unknown-unknown
$ cargo install -f wasm-bindgen-cli --version 0.2.105
```

Then you can build with cargo. Keep in mind that Busperf's build script can take some time, because it has to compile the viewer.

```sh
$ cargo build --features generate-html
```

### Build Busperf viewer for WASM

Busperf's data viewer can be compiled to WASM. This allows viewing data files generated by Busperf in a browser.

Build and serve with trunk:
```sh
$ cd busperf_web
$ trunk serve --release
```

Only build:
```sh
$ cd busperf_web
$ trunk build --release
```
The output of the build will be available in the busperf_web/dist directory.
It can be served with any http server.