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.Os 32.Dt PMCANNOTATE 8 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 informations are 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 informations involving C sources are provided. 75.It Fl h 76Prints out informations 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.Sh LIMITATIONS 90As long as 91.Nm 92relies on the 93.Xr objdump 1 94utility to retrieve the C code, the program needs to be compiled with 95debugging options. 96Sometimes, in particular with heavy optimization levels, the 97.Xr objdump 1 98utility embeds the code of inlining functions directly in the callers, 99making an output difficult to read. 100The x86 version reports the sampling from pmcstat collecting the following 101instruction in regard of the interrupted one. 102This means that the samples may be attributed to the line below the one 103of interest. 104.Sh SEE ALSO 105.Xr objdump 1 , 106.Xr pmcstat 8 107.Sh AUTHORS 108.An Attilio Rao Aq attilio@FreeBSD.org 109