README.md 5.41 KB
Newer Older
Antonio Caggiano's avatar
Antonio Caggiano committed
1
2
Graphics Perfetto producers
---------------------------
Quim Aguado's avatar
Quim Aguado committed
3

4
This project contains a collection of graphics-related [Perfetto producers](https://perfetto.dev/#/architecture.md). A producer is a client process for the Perfetto tracing service. Currently available are the following producers:
Quim Aguado's avatar
Quim Aguado committed
5

Antonio Caggiano's avatar
Antonio Caggiano committed
6
- Panfrost performance counters
7
- Intel performance counters
Quim Aguado's avatar
Quim Aguado committed
8

Antonio Caggiano's avatar
Antonio Caggiano committed
9
## Build
Quim Aguado's avatar
Quim Aguado committed
10

Antonio Caggiano's avatar
Antonio Caggiano committed
11
This section guides you through the building process assuming you are compiling on Ubuntu.
Quim Aguado's avatar
Quim Aguado committed
12

Antonio Caggiano's avatar
Antonio Caggiano committed
13
14
1. Install dependencies:

15
16
17
   ```sh
   apt install build-essential meson cmake libwayland-dev rapidjson-dev libdrm-dev libprotobuf-dev libgtest-dev libdocopt-dev
   ```
Antonio Caggiano's avatar
Antonio Caggiano committed
18

Antonio Caggiano's avatar
Antonio Caggiano committed
19
2. Generate the project:
Antonio Caggiano's avatar
Antonio Caggiano committed
20

21
22
23
   ```sh
   meson build
   ```
Antonio Caggiano's avatar
Antonio Caggiano committed
24

Antonio Caggiano's avatar
Antonio Caggiano committed
25
3. Compile and run tests (it may take a while):
Antonio Caggiano's avatar
Antonio Caggiano committed
26

27
28
29
   ```sh
   ninja -C build test
   ```
Quim Aguado's avatar
Quim Aguado committed
30

Antonio Caggiano's avatar
Antonio Caggiano committed
31
32
### Cross-compile

Antonio Caggiano's avatar
Antonio Caggiano committed
33
34
35
36
In order to capture a trace on a remote arm64 target, Perfetto and the gfx-pps producers need to be cross-compiled for Linux aarch64.

#### Cross-compile perfetto

Antonio Caggiano's avatar
Antonio Caggiano committed
37
It is not possible to compile Perfetto on Linux aarch64 as you need to run `tools/gn`, which is not compiled for that architecture.
Antonio Caggiano's avatar
Antonio Caggiano committed
38
39
40

To cross-compile on amd64 using clang, follow these steps:

Antonio Caggiano's avatar
Antonio Caggiano committed
41
1. Change directory to `perfetto`
Antonio Caggiano's avatar
Antonio Caggiano committed
42

43
44
45
   ```sh
   cd <path>/perfetto
   ```
Antonio Caggiano's avatar
Antonio Caggiano committed
46
47
48

2. Generate a build directory

49
50
51
   ```sh
   tools/gn args out/arm64
   ```
Antonio Caggiano's avatar
Antonio Caggiano committed
52

53
   Typing in the following GN args
Antonio Caggiano's avatar
Antonio Caggiano committed
54

55
56
57
58
59
60
61
62
   ```js
   // args.gn
   target_os = "linux"
   target_cpu = "arm64"
   is_debug = false
   target_sysroot = "/usr/aarch64-linux-gnu"
   target_gcc_toolchain = "/usr"
   ```
Antonio Caggiano's avatar
Antonio Caggiano committed
63
64
65

3. Compile perfetto and the tracing service

66
67
68
   ```sh
   tools/ninja -C out/arm64 perfetto traced traced_probes
   ```
Antonio Caggiano's avatar
Antonio Caggiano committed
69
70
71

#### Cross-compile gfx-pps producers

Antonio Caggiano's avatar
Antonio Caggiano committed
72
To cross-compile with meson, you need to take these steps:
Antonio Caggiano's avatar
Antonio Caggiano committed
73

Antonio Caggiano's avatar
Antonio Caggiano committed
74
1. Prepare a chroot for cross-building
Antonio Caggiano's avatar
Antonio Caggiano committed
75

76
77
78
79
80
   ```sh
   sudo debootstrap --variant=buildd focal /srv/target/focal
   sudo chroot /srv/target/focal
   mount -t proc proc /proc
   ```
Antonio Caggiano's avatar
Antonio Caggiano committed
81

Antonio Caggiano's avatar
Antonio Caggiano committed
82
83
2. Add arm64 to `/etc/apt/souces.list`

84
85
86
87
   ```
   deb [arch=amd64] http://archive.ubuntu.com/ubuntu focal main
   deb [arch=arm64] http://ports.ubuntu.com/ubuntu-ports focal main
   ```
Antonio Caggiano's avatar
Antonio Caggiano committed
88
89
90

3. Enable multiarch by adding arm64

91
92
93
   ```sh
   dpkg --add-architecture arm64
   ```
Antonio Caggiano's avatar
Antonio Caggiano committed
94
95
96

4. Install the arm64 toolchain and other required packages:

97
98
99
100
   ```sh
   apt update
   apt install build-essential libc6-arm64-cross gcc-aarch64-linux-gnu g++-aarch64-linux-gnu meson cmake libdrm-dev:arm64 libwayland-dev:arm64 libprotobuf-dev:arm64 rapidjson-dev:arm64 libgtest-dev:arm64 libdocopt-dev:arm64
   ```
Antonio Caggiano's avatar
Antonio Caggiano committed
101

Antonio Caggiano's avatar
Antonio Caggiano committed
102
103
104
5. Create a [cross file](https://mesonbuild.com/Cross-compilation.html) for meson like the following snippet: [aarch64-linux](https://gitlab.freedesktop.org/Fahien/gfx-pps/snippet/1086)

6. Generate the project using that cross file:
Antonio Caggiano's avatar
Antonio Caggiano committed
105

106
107
108
   ```sh
   meson build/arm64 --cross-file aarch64-linux
   ```
Antonio Caggiano's avatar
Antonio Caggiano committed
109

Antonio Caggiano's avatar
Antonio Caggiano committed
110
7. Compile and run tests
Antonio Caggiano's avatar
Antonio Caggiano committed
111

112
113
114
   ```sh
   ninja -C build/arm64 test
   ```
Antonio Caggiano's avatar
Antonio Caggiano committed
115

Quim Aguado's avatar
Quim Aguado committed
116
117
## Run

Antonio Caggiano's avatar
Antonio Caggiano committed
118
To capture a trace with perfetto you need to take the following steps:
Quim Aguado's avatar
Quim Aguado committed
119

Antonio Caggiano's avatar
Antonio Caggiano committed
120
1. Create a [trace config](https://perfetto.dev/#/trace-config.md), which is a json formatted text file with extension `.cfg`, or use one of those under the `script` directory.
Quim Aguado's avatar
Quim Aguado committed
121

Antonio Caggiano's avatar
Antonio Caggiano committed
122
2. Copy the config file to `perfetto/test/configs`. Under this directory you can also find more example of trace configs.
Quim Aguado's avatar
Quim Aguado committed
123

Antonio Caggiano's avatar
Antonio Caggiano committed
124
3. Change directory to `perfetto` and run a [convenience script](https://perfetto.dev/#/running.md) to start the tracing service:
Antonio Caggiano's avatar
Antonio Caggiano committed
125

126
127
128
129
   ```sh
   cd <path>/perfetto
   CONFIG=test.cfg OUT=out/build ./tools/tmux
   ```
Quim Aguado's avatar
Quim Aguado committed
130

131
4. Start other producers you may need, like `producer-gpu`.
Quim Aguado's avatar
Quim Aguado committed
132

Antonio Caggiano's avatar
Antonio Caggiano committed
133
134
5. Start perfetto under the tmux session initiated in step 3.

Antonio Caggiano's avatar
Antonio Caggiano committed
135
136
137
138
139
140
6. Once tracing has finished, you can detach from tmux with <kbd>ctrl</kbd>+<kbd>b</kbd>, <kbd>d</kbd>, and the convenience script should automatically copy the trace files into `$HOME/Downloads`.

7. Go to [ui.perfetto.dev](https://ui.perfetto.dev) and upload `$HOME/Downloads/trace.protobuf` by clicking on *Open trace file*.

### GPU producer

141
142
143
144
145
146
147
The GPU producer contains at the current state a data-source able to query performance counters using a Panfrost driver for Arm Mali devices, or an Intel driver for Intel Graphics devices.

#### Panfrost driver

The Panfrost driver uses unstable ioctls that behave correctly on kernel version [5.4.23+](https://lwn.net/Articles/813601/) and [5.5.7+](https://lwn.net/Articles/813600/).

To run the producer, follow these two simple steps:
Antonio Caggiano's avatar
Antonio Caggiano committed
148
149
150

1. Enable Panfrost unstable ioctls via kernel parameter:

151
152
153
   ```sh
   modprobe panfrost unstable_ioctls=1
   ```
Antonio Caggiano's avatar
Antonio Caggiano committed
154
155
156

2. Run the producer:

157
158
159
160
161
162
163
164
   ```sh
   ./build/producer-gpu
   ```

#### Intel driver

The Intel driver needs root access to read system-wide [RenderBasic]() performance counters, so you can simply run it with sudo:

Antonio Caggiano's avatar
Antonio Caggiano committed
165
```sh
166
sudo ./build/producer-gpu
Antonio Caggiano's avatar
Antonio Caggiano committed
167
```
Antonio Caggiano's avatar
Antonio Caggiano committed
168

Antonio Caggiano's avatar
Antonio Caggiano committed
169
170
## Troubleshooting

171
172
### Tmux

Antonio Caggiano's avatar
Antonio Caggiano committed
173
174
175
176
If the convenience script `tools/tmux` keeps copying artifacts to your `SSH_TARGET` without starting the tmux session, make sure you have `tmux` installed in your system.

```sh
apt install tmux
Antonio Caggiano's avatar
Antonio Caggiano committed
177
```
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199

### Missing counter names

If the trace viewer shows a list of counters with a description like `gpu_counter(#)` instead of their proper names, maybe you had a data loss due to the trace buffer being full and wrapped.

In order to prevent this loss of data you can tweak the trace config file in two different ways:

- Increase the size of the buffer in use:

  ```js
  buffers {
      size_kb: 2048,
      fill_policy: RING_BUFFER,
  }
  ```

- Periodically flush the trace buffer into the output file:

  ```js
  write_into_file: true
  file_write_period_ms: 250
  ```