1.\" $NetBSD: tprof.8,v 1.30 2023/04/18 00:21:23 gutteridge Exp $ 2.\" 3.\" Copyright (c)2011 YAMAMOTO Takashi, 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd April 17, 2023 28.Dt TPROF 8 29.Os 30.Sh NAME 31.Nm tprof 32.Nd record tprof profiling samples 33.Sh SYNOPSIS 34.Nm 35.Ar op 36.Op Ar arguments 37.Sh DESCRIPTION 38The 39.Nm 40tool can be used to monitor hardware events 41.Tn ( PMC Ns s ) 42during the execution of 43certain commands. 44.Pp 45The 46.Nm 47utility makes the kernel driver start profiling, 48executes the specified command, 49keeps recording samples from the kernel driver until the command finishes, 50and reports statistics to the standard error. 51.Pp 52The 53.Xr tprof 4 54pseudo driver and a suitable backend should be loaded beforehand. 55.Pp 56The 57.Nm 58utility accepts the following options. 59The first argument, 60.Ar op , 61specifies the action to take. 62Valid actions are: 63.Bl -tag -width Cm 64. 65.It Cm list 66. 67Display the following information: 68.Bl -bullet -compact 69.It 70a list of performance counter events available on the system 71.It 72the maximum number of counters that can be used simultaneously 73.It 74the default counter for 75.Cm monitor 76and 77.Cm top 78commands 79.El 80. 81.It Cm monitor Xo 82.Op Fl e Ar name\| Ns Oo Cm \&: Ns Ar option\^ Oc Ns Oo Cm \&, Ns Ar scale\^ Oc 83.Op Fl e Ar ... 84.Op Fl o Ar outfile 85.Ar command 86.Xc 87. 88Monitor the execution of 89.Ar command . 90The 91.Ar name 92specifies the event to count; it must be taken from the list of 93available events. 94.Ar option 95specifies the source of the event; it must be a combination of 96.Cm u 97(userland) and 98.Cm k 99(kernel). 100If omitted, it is assumed that both are specified. 101Multiple 102.Fl e 103arguments can be specified. 104If none of the 105.Fl e 106arguments are specified, the CPU's default counter is used. 107.Pp 108.Ar scale 109specifies the ratio of the speed to the cycle counter, or the counter until 110overflow. 111The counter reset value on overflow used for profiling is calculated from the 112speed of the cycle counter by default, but for some events this value may be 113too large (counter increasing too slowly) to be sufficient for profiling. 114For example, to specify an event that increases about 1000 times slower than 115the cycle counter, specify 116.Ql -e event,1000 . 117Also, if 118.Ql -e event,=200 119is specified, profiling is performed every time the counter is increased by 200. 120.Pp 121The collected samples are written into the file 122.Ar outfile 123if specified. 124The default is 125.Pa tprof.out . 126. 127.It Cm count Xo 128.Fl e Ar name\| Ns Op Cm \&: Ns Ar option 129.Op Fl e Ar ... 130.Op Fl i Ar interval 131.Ar command 132.Xc 133. 134Same as 135.Cm monitor , 136but does not do any profiling, 137only outputs counters every 138.Ar interval 139second. 140. 141.It Cm analyze Xo 142.Op Fl CkLPs 143.Op Fl p Ar pid 144.Ar file 145.Xc 146. 147Analyze the samples produced by a previous run of 148.Nm , 149stored in 150.Ar file , 151and generate a plain text representation of them. 152.Bl -tag -width Fl 153.It Fl C 154Don't distinguish CPUs. 155All samples are treated as its CPU number is 0. 156.It Fl k 157Kernel only. 158Ignore samples for userland code. 159.It Fl L 160Don't distinguish LWPs. 161All samples are treated as its LWP ID is 0. 162.It Fl P 163Don't distinguish processes. 164All samples are treated as its PID is 0. 165.It Fl p Ar pid 166Process only samples for the process with PID 167.Ar pid 168and ignore the rest. 169.It Fl s 170Per symbol. 171.El 172. 173.It Cm top Xo 174.Op Fl acu 175.Op Fl e Ar name\| Ns Oo Cm \&, Ns Ar scale\^ Oc 176.Op Fl e Ar ... 177.Op Fl i Ar interval 178.Xc 179. 180Displays profiling results in real-time. 181.Ar name 182specifies the name of the event to count. 183.Bl -tag -width Fl 184.It Fl a 185Starts in accumulation mode. 186The display is updated every 187.Ar interval 188second, but the values are accumulative. 189.It Fl c 190Show the delta of the event counters. 191.It Fl i Ar interval 192Set the update interval in seconds. 193The default value is 1. 194.It Fl u 195Userland processes are also included in the profiling. 196.El 197.Pp 198While 199.Nm 200.Ar top 201is running, it accepts commands from the terminal. 202These commands are currently recognized: 203.Bl -tag -width Ic 204.It Aq Ic a 205toggle accumurative mode. 206.It Aq Ic c 207shows/hides the event counters. 208.It Aq Ic q 209quit 210.Nm . 211.It Aq Ic z 212clear accumulated data. 213.El 214.El 215.Sh EXAMPLES 216The following command profiles the system during 20 seconds and writes the 217samples into the file 218.Pa myfile.out . 219.Pp 220.Dl # tprof monitor -e llc-misses:k -o myfile.out sleep 20 221.Pp 222The following command displays the results of the sampling. 223.Pp 224.Dl # tprof analyze myfile.out 225.Sh SUPPORT 226The following CPU models are supported: 227.Bl -hyphen -compact -offset indent 228.It 229ARMv7 230.It 231ARMv8 232.It 233x86 AMD Family 10h 234.It 235x86 AMD Family 15h 236.It 237x86 AMD Family 17h 238.It 239x86 AMD Family 19h 240.It 241x86 Intel Generic (all Intel CPUs) 242.It 243x86 Intel Skylake, Kabylake and Cometlake 244.It 245x86 Intel Silvermont/Airmont 246.It 247x86 Intel Goldmont 248.It 249x86 Intel Goldmont Plus 250.El 251.Sh DIAGNOSTICS 252The 253.Nm 254utility reports the following statistics about the activities of the 255.Xr tprof 4 256pseudo driver. 257.Bl -tag -width dropbuf_samples 258.It sample 259The number of samples collected and prepared for userland consumption. 260.It overflow 261The number of samples dropped because the per-CPU buffer was full. 262.It buf 263The number of buffers successfully prepared for userland consumption. 264.It emptybuf 265The number of buffers which have been dropped because they were empty. 266.It dropbuf 267The number of buffers dropped because the number of buffers kept in the kernel 268exceeds the limit. 269.It dropbuf_samples 270The number of samples dropped because the buffers containing the samples 271were dropped. 272.El 273.Sh SEE ALSO 274.Xr tprof 4 275.Sh AUTHORS 276.An -nosplit 277The 278.Nm 279utility was written by 280.An YAMAMOTO Takashi . 281It was revamped by 282.An Maxime Villard 283in 2018, and by 284.An Ryo Shimizu 285in 2022. 286.Sh CAVEATS 287The contents and representation of recorded samples are undocumented and 288will likely be changed for future releases of 289.Nx 290in an incompatible way. 291