usr.sbin/pmcannotate/pmcannotate.8

   1 .\" Copyright (c) 2008 Nokia Corporation
   2 .\" All rights reserved.
   3 .\"
   4 .\" This software was developed by Attilio Rao for the IPSO project under
   5 .\" contract to Nokia Corporation.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" This software is provided by the authors ``as is'' and
  17 .\" any express or implied warranties, including, but not limited to, the
  18 .\" implied warranties of merchantability and fitness for a particular purpose
  19 .\" are disclaimed.  in no event shall the authors be liable
  20 .\" for any direct, indirect, incidental, special, exemplary, or consequential
  21 .\" damages (including, but not limited to, procurement of substitute goods
  22 .\" or services; loss of use, data, or profits; or business interruption)
  23 .\" however caused and on any theory of liability, whether in contract, strict
  24 .\" liability, or tort (including negligence or otherwise) arising in any way
  25 .\" out of the use of this software, even if advised of the possibility of
  26 .\" such damage.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd November 20, 2008
  31 .Dt PMCANNOTATE 8
  32 .Os
  33 .Sh NAME
  34 .Nm pmcannotate
  35 .Nd "sources printout with inlined profiling"
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Op Fl a
  39 .Op Fl h
  40 .Op Fl k Ar pathname
  41 .Op Fl l Ar level
  42 .Ar pmcout.out binaryobj
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 utility can produce both C sources or assembly sources of a program with
  47 a line-by-line based profiling.
  48 The profiling information is retrieved through a
  49 .Xr pmcstat 8
  50 raw output while the program operations are retrieved through the
  51 .Xr objdump 1
  52 tool.
  53 .Pp
  54 When calling
  55 .Nm
  56 the raw output is passed through the
  57 .Ar pmcout.out
  58 argument, while the program is passed through the
  59 .Ar binaryobj
  60 argument.
  61 .Pp
  62 As long as
  63 .Nm
  64 relies on
  65 .Xr objdump 1
  66 and
  67 .Xr pmcstat 8
  68 to work, it will fail if one of them is not available.
  69 .Sh OPTIONS
  70 The following options are available:
  71 .Bl -tag -width indent
  72 .It Fl a
  73 Shows the program profiling inlined in the assembly code only.
  74 No C information involving C sources is provided.
  75 .It Fl h
  76 Prints out information about the usage of the tool.
  77 .It Fl l Ar level
  78 Changes the lower bound (expressed in percentage) for traced functions
  79 that will be printed out in the report.
  80 The default value is 0.5%.
  81 .It Fl k Ar kerneldir
  82 Set the pathname of the kernel directory to argument
  83 .Ar kerneldir .
  84 This directory specifies where
  85 .Nm
  86 should look for the kernel and its modules.
  87 The default is
  88 .Pa /boot/kernel .
  89 .El
  90 .Sh LIMITATIONS
  91 As long as
  92 .Nm
  93 relies on the
  94 .Xr objdump 1
  95 utility to retrieve the C code, the program needs to be compiled with
  96 debugging options.
  97 Sometimes, in particular with heavy optimization levels, the
  98 .Xr objdump 1
  99 utility embeds the code of inlining functions directly in the callers,
 100 making an output difficult to read.
 101 The x86 version reports the sampling from pmcstat collecting the following
 102 instruction in regard of the interrupted one.
 103 This means that the samples may be attributed to the line below the one
 104 of interest.
 105 .Sh SEE ALSO
 106 .Xr objdump 1 ,
 107 .Xr pmcstat 8
 108 .Sh AUTHORS
 109 .An Attilio Rao Aq attilio@FreeBSD.org