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