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
44The
45.Nm
46utility can produce both C sources or assembly sources of a program with
47a line-by-line based profiling.
48The profiling information is retrieved through a
49.Xr pmcstat 8
50raw output while the program operations are retrieved through the
51.Xr objdump 1
52tool.
53.Pp
54When calling
55.Nm
56the raw output is passed through the
57.Ar pmcout.out
58argument, while the program is passed through the
59.Ar binaryobj
60argument.
61.Pp
62As long as
63.Nm
64relies on
65.Xr objdump 1
66and
67.Xr pmcstat 8
68to work, it will fail if one of them is not available.
69.Sh OPTIONS
70The following options are available:
71.Bl -tag -width indent
72.It Fl a
73Shows the program profiling inlined in the assembly code only.
74No C information involving C sources is provided.
75.It Fl h
76Prints out information about the usage of the tool.
77.It Fl l Ar level
78Changes the lower bound (expressed in percentage) for traced functions
79that will be printed out in the report.
80The default value is 0.5%.
81.It Fl k Ar kerneldir
82Set the pathname of the kernel directory to argument
83.Ar kerneldir .
84This directory specifies where
85.Nm
86should look for the kernel and its modules.
87The default is
88.Pa /boot/kernel .
89.El
90.Sh LIMITATIONS
91As long as
92.Nm
93relies on the
94.Xr objdump 1
95utility to retrieve the C code, the program needs to be compiled with
96debugging options.
97Sometimes, in particular with heavy optimization levels, the
98.Xr objdump 1
99utility embeds the code of inlining functions directly in the callers,
100making an output difficult to read.
101The x86 version reports the sampling from pmcstat collecting the following
102instruction in regard of the interrupted one.
103This means that the samples may be attributed to the line below the one
104of interest.
105.Sh SEE ALSO
106.Xr objdump 1 ,
107.Xr pmcstat 8
108.Sh AUTHORS
109.An Attilio Rao Aq Mt attilio@FreeBSD.org
110