Annotation of src/usr.sbin/tprof/tprof.8, Revision 1.24
1.24 ! ryo 1: .\" $NetBSD: tprof.8,v 1.23 2022/12/16 08:00:47 ryo Exp $
1.1 yamt 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: .\"
1.23 ryo 27: .Dd December 16, 2022
1.1 yamt 28: .Dt TPROF 8
29: .Os
30: .Sh NAME
31: .Nm tprof
32: .Nd record tprof profiling samples
33: .Sh SYNOPSIS
34: .Nm
1.5 maxv 35: .Ar op
36: .Op Ar arguments
1.1 yamt 37: .Sh DESCRIPTION
38: The
39: .Nm
1.5 maxv 40: tool can be used to monitor hardware events (PMCs) during the execution of
41: certain commands.
1.1 yamt 42: .Pp
1.5 maxv 43: The
1.1 yamt 44: .Nm
45: utility makes the kernel driver start profiling,
46: executes the specified command,
47: keeps recording samples from the kernel driver until the command finishes,
48: and reports statistics to the standard error.
49: .Pp
50: The
51: .Nm tprof
1.2 wiz 52: pseudo driver and a suitable backend should be loaded beforehand.
1.16 msaitoh 53: See
54: .Xr tprof 4
55: for the details.
1.1 yamt 56: .Pp
57: The
58: .Nm
59: utility accepts the following options.
1.5 maxv 60: The first argument,
61: .Ar op ,
62: specifies the action to take.
63: Valid actions are:
1.9 wiz 64: .Bl -tag -width offline -offset indent
1.5 maxv 65: .It list
1.4 maxv 66: Display a list of performance counter events available on the system.
1.5 maxv 67: .It monitor Xo
68: .Fl e
1.24 ! ryo 69: .Ar name[:option][,scale]
1.17 ryo 70: .Op Fl e Ar ...
1.5 maxv 71: .Op Fl o Ar outfile
72: .Ar command
73: .Xc
74: Monitor the execution of command
75: .Ar command .
1.4 maxv 76: .Ar name
77: specifies the name of the event to count; it must be taken from the list of
78: available events.
79: .Ar option
80: specifies the source of the event; it must be a combination of
81: .Ar u
82: (userland) and
83: .Ar k
1.18 ryo 84: (kernel). If omitted, it is assumed that both are specified.
1.5 maxv 85: The collected samples are written into the file
1.24 ! ryo 86: .Ar scale
! 87: specifies the ratio of the speed to the cycle counter, or the counter until
! 88: overflow.
! 89: The counter reset value on overflow used for profiling is calculated from the
! 90: speed of the cycle counter by default, but for some events this value may be
! 91: too large (counter increasing too slowly) to be sufficient for profiling.
! 92: For example, to specify an event that increases about 1000 times slower than
! 93: the cycle counter, specify
! 94: .Dq Pa -e event,1000 .
! 95: Also, if
! 96: .Dq Pa -e event,=200
! 97: is specified, profiling is performed every time the counter is increased by 200.
1.5 maxv 98: .Ar outfile
99: if specified.
1.2 wiz 100: The default is
101: .Dq Pa tprof.out .
1.18 ryo 102: .It count Xo
103: .Fl e
104: .Ar name[:option]
105: .Op Fl e Ar ...
106: .Op Fl i Ar interval
107: .Ar command
108: .Xc
109: Same as
110: .Ar monitor ,
111: but does not do any profiling,
112: only outputs counters every
113: .Ar interval
114: second.
1.6 maxv 115: .It analyze Xo
1.9 wiz 116: .Op Fl CkLPs
1.6 maxv 117: .Op Fl p Ar pid
1.8 maxv 118: .Ar file
1.6 maxv 119: .Xc
120: Analyze the samples produced by a previous run of
121: .Nm tprof ,
1.8 maxv 122: stored in
123: .Ar file ,
124: and generate a plain text representation of them.
1.9 wiz 125: .Bl -tag -width XPXpidXX -offset indent
1.6 maxv 126: .It Fl C
127: Don't distinguish CPUs.
128: All samples are treated as its CPU number is 0.
129: .It Fl k
130: Kernel only.
131: Ignore samples for userland code.
132: .It Fl L
133: Don't distinguish LWPs.
134: All samples are treated as its LWP ID is 0.
135: .It Fl P
136: Don't distinguish processes.
137: All samples are treated as its PID is 0.
138: .It Fl p Ar pid
139: Process only samples for the process with PID
140: .Ar pid
141: and ignore the rest.
142: .It Fl s
143: Per symbol.
1.1 yamt 144: .El
1.19 ryo 145: .It top Xo
146: .Oo
147: .Fl e
1.24 ! ryo 148: .Ar name[,scale]
1.19 ryo 149: .Op Fl e Ar ...
150: .Oc
151: .Op Fl i Ar interval
1.20 ryo 152: .Op Fl acu
1.19 ryo 153: .Xc
154: Displays profiling results in real-time.
155: .Ar name
156: specifies the name of the event to count.
157: .Bl -tag -width XXintervalX -offset indent
158: .It Fl i Ar interval
159: set the update interval in seconds. The default value is 1.
1.20 ryo 160: .It Fl a
161: Starts in accumulation mode. The display is updated every
162: .Ar interval
163: second, but the values are accumulative.
1.19 ryo 164: .It Fl c
165: show the delta of the event counters.
166: .It Fl u
167: Userland processes are also included in the profiling.
168: .El
1.21 ryo 169: .Pp
170: While
171: .Nm
172: .Ar top
173: is running, it accepts commands from the terminal.
174: These commands are currently recognized:
175: .Bl -tag -width XXcommandsX -offset indent
176: .It Ic a
177: toggle accumurative mode.
1.23 ryo 178: .It Ic c
179: shows/hides the event counters.
1.21 ryo 180: .It Ic q
181: quit
182: .Nm .
183: .It Ic z
184: clear accumulated data.
185: .El
1.9 wiz 186: .El
1.1 yamt 187: .Sh EXAMPLES
1.5 maxv 188: The following command profiles the system during 20 seconds and writes the
189: samples into the file myfile.out.
190: .Dl # tprof monitor -e llc-misses:k -o myfile.out sleep 20
1.6 maxv 191: The following command displays the results of the sampling.
1.8 maxv 192: .Dl # tprof analyze myfile.out
1.10 maxv 193: .Sh SUPPORT
194: The following CPU models are supported:
195: .Bl -hyphen -compact -offset indent
196: .It
197: ARMv7
198: .It
199: ARMv8
200: .It
201: x86 AMD Family 10h
202: .It
1.15 jmcneill 203: x86 AMD Family 15h
204: .It
1.14 maxv 205: x86 AMD Family 17h
206: .It
1.22 ryo 207: x86 AMD Family 19h
208: .It
1.10 maxv 209: x86 Intel Generic (all Intel CPUs)
210: .It
211: x86 Intel Skylake/Kabylake
1.11 maxv 212: .It
213: x86 Intel Silvermont/Airmont
1.12 knakahar 214: .It
215: x86 Intel Goldmont
1.13 knakahar 216: .It
217: x86 Intel Goldmont Plus
1.10 maxv 218: .El
1.1 yamt 219: .Sh DIAGNOSTICS
220: The
221: .Nm
222: utility reports the following statistics about the activities of the
223: .Nm tprof
224: pseudo driver.
225: .Bl -tag -width dropbuf_samples
226: .It sample
227: The number of samples collected and prepared for userland consumption.
228: .It overflow
229: The number of samples dropped because the per-CPU buffer was full.
230: .It buf
231: The number of buffers successfully prepared for userland consumption.
232: .It emptybuf
1.2 wiz 233: The number of buffers which have been dropped because they were empty.
1.1 yamt 234: .It dropbuf
235: The number of buffers dropped because the number of buffers kept in the kernel
236: exceeds the limit.
237: .It dropbuf_samples
1.2 wiz 238: The number of samples dropped because the buffers containing the samples
1.1 yamt 239: were dropped.
240: .El
1.2 wiz 241: .Sh SEE ALSO
242: .Xr tprof 4
1.1 yamt 243: .Sh AUTHORS
1.9 wiz 244: .An -nosplit
1.1 yamt 245: The
246: .Nm
1.14 maxv 247: utility was written by
1.1 yamt 248: .An YAMAMOTO Takashi .
1.4 maxv 249: It was revamped by
250: .An Maxime Villard
1.20 ryo 251: in 2018, and by
252: .An Ryo Shimizu
253: in 2022.
1.3 yamt 254: .Sh CAVEATS
255: The contents and representation of recorded samples are undocumented and
256: will likely be changed for future releases of
257: .Nx
258: in an incompatible way.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to tprof.8 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / usr.sbin / tprof