Return to tprof.8 CVS log

Up to [cvs.NetBSD.org] / src / usr.sbin / tprof

Annotation of src/usr.sbin/tprof/tprof.8, Revision 1.14.2.1

1.14.2.1! martin      1: .\"    $NetBSD: tprof.8,v 1.14 2019/05/29 17:09:17 maxv 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.14.2.1! martin     27: .Dd October 11, 2019
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.1       yamt       53: .Pp
                     54: The
                     55: .Nm
                     56: utility accepts the following options.
1.5       maxv       57: The first argument,
                     58: .Ar op ,
                     59: specifies the action to take.
                     60: Valid actions are:
1.9       wiz        61: .Bl -tag -width offline -offset indent
1.5       maxv       62: .It list
1.4       maxv       63: Display a list of performance counter events available on the system.
1.5       maxv       64: .It monitor Xo
                     65: .Fl e
                     66: .Ar name:option
                     67: .Op Fl o Ar outfile
                     68: .Ar command
                     69: .Xc
                     70: Monitor the execution of command
                     71: .Ar command .
1.4       maxv       72: .Ar name
                     73: specifies the name of the event to count; it must be taken from the list of
                     74: available events.
                     75: .Ar option
                     76: specifies the source of the event; it must be a combination of
                     77: .Ar u
                     78: (userland) and
                     79: .Ar k
                     80: (kernel).
1.5       maxv       81: The collected samples are written into the file
                     82: .Ar outfile
                     83: if specified.
1.2       wiz        84: The default is
                     85: .Dq Pa tprof.out .
1.6       maxv       86: .It analyze Xo
1.9       wiz        87: .Op Fl CkLPs
1.6       maxv       88: .Op Fl p Ar pid
1.8       maxv       89: .Ar file
1.6       maxv       90: .Xc
                     91: Analyze the samples produced by a previous run of
                     92: .Nm tprof ,
1.8       maxv       93: stored in
                     94: .Ar file ,
                     95: and generate a plain text representation of them.
1.9       wiz        96: .Bl -tag -width XPXpidXX -offset indent
1.6       maxv       97: .It Fl C
                     98: Don't distinguish CPUs.
                     99: All samples are treated as its CPU number is 0.
                    100: .It Fl k
                    101: Kernel only.
                    102: Ignore samples for userland code.
                    103: .It Fl L
                    104: Don't distinguish LWPs.
                    105: All samples are treated as its LWP ID is 0.
                    106: .It Fl P
                    107: Don't distinguish processes.
                    108: All samples are treated as its PID is 0.
                    109: .It Fl p Ar pid
                    110: Process only samples for the process with PID
                    111: .Ar pid
                    112: and ignore the rest.
                    113: .It Fl s
                    114: Per symbol.
1.1       yamt      115: .El
1.9       wiz       116: .El
1.1       yamt      117: .Sh EXAMPLES
1.5       maxv      118: The following command profiles the system during 20 seconds and writes the
                    119: samples into the file myfile.out.
                    120: .Dl # tprof monitor -e llc-misses:k -o myfile.out sleep 20
1.6       maxv      121: The following command displays the results of the sampling.
1.8       maxv      122: .Dl # tprof analyze myfile.out
1.10      maxv      123: .Sh SUPPORT
                    124: The following CPU models are supported:
                    125: .Bl -hyphen -compact -offset indent
                    126: .It
                    127: ARMv7
                    128: .It
                    129: ARMv8
                    130: .It
                    131: x86 AMD Family 10h
                    132: .It
1.14.2.1! martin    133: x86 AMD Family 15h
        !           134: .It
1.14      maxv      135: x86 AMD Family 17h
                    136: .It
1.10      maxv      137: x86 Intel Generic (all Intel CPUs)
                    138: .It
                    139: x86 Intel Skylake/Kabylake
1.11      maxv      140: .It
                    141: x86 Intel Silvermont/Airmont
1.12      knakahar  142: .It
                    143: x86 Intel Goldmont
1.13      knakahar  144: .It
                    145: x86 Intel Goldmont Plus
1.10      maxv      146: .El
1.1       yamt      147: .Sh DIAGNOSTICS
                    148: The
                    149: .Nm
                    150: utility reports the following statistics about the activities of the
                    151: .Nm tprof
                    152: pseudo driver.
                    153: .Bl -tag -width dropbuf_samples
                    154: .It sample
                    155: The number of samples collected and prepared for userland consumption.
                    156: .It overflow
                    157: The number of samples dropped because the per-CPU buffer was full.
                    158: .It buf
                    159: The number of buffers successfully prepared for userland consumption.
                    160: .It emptybuf
1.2       wiz       161: The number of buffers which have been dropped because they were empty.
1.1       yamt      162: .It dropbuf
                    163: The number of buffers dropped because the number of buffers kept in the kernel
                    164: exceeds the limit.
                    165: .It dropbuf_samples
1.2       wiz       166: The number of samples dropped because the buffers containing the samples
1.1       yamt      167: were dropped.
                    168: .El
1.2       wiz       169: .Sh SEE ALSO
                    170: .Xr tprof 4
1.1       yamt      171: .Sh AUTHORS
1.9       wiz       172: .An -nosplit
1.1       yamt      173: The
                    174: .Nm
1.14      maxv      175: utility was written by
1.1       yamt      176: .An YAMAMOTO Takashi .
1.4       maxv      177: It was revamped by
                    178: .An Maxime Villard
                    179: in 2018.
1.3       yamt      180: .Sh CAVEATS
                    181: The contents and representation of recorded samples are undocumented and
                    182: will likely be changed for future releases of
                    183: .Nx
                    184: in an incompatible way.