doc/html/ref/profile-functions.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Profiling functions</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="Application profiling"
  23 HREF="services-profile-gprof.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Application profiling"
  26 HREF="services-profile-gprof.html"><LINK
  27 REL="NEXT"
  28 TITLE="eCos Power Management Support"
  29 HREF="services-power.html"></HEAD
  30 ><BODY
  31 CLASS="CHAPTER"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="services-profile-gprof.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="services-power.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="CHAPTER"
  82 ><H1
  83 ><A
  84 NAME="PROFILE-FUNCTIONS">Chapter 52. Profiling functions</H1
  85 ><DIV
  86 CLASS="SECT1"
  87 ><H1
  88 CLASS="SECT1"
  89 ><A
  90 NAME="SERVICES-PROFILE-API">API</H1
  91 ><P
  92 >In order for profile data to be gathered for an application, the
  93 program has to initiate the process.
  94 Once started, execution histogram data will be collected in a
  95 dynamic memory buffer.
  96 This data can be uploaded to a host using <SPAN
  97 CLASS="emphasis"
  98 ><I
  99 CLASS="EMPHASIS"
 100 >TFTP</I
 101 ></SPAN
 102 >.
 103 A side effect of the upload of the data is that the histogram
 104 is reset.
 105 This is useful, especially for high resolution histograms, since
 106 the histogram data are collected as 16-bit counters which can be quickly
 107 saturated.
 108 For example, if the histogram is being collected at a rate of 10,000
 109 samples per second, a hot spot in the program could saturate after
 110 only 6.5 seconds.</P
 111 ><P
 112 > The API for the application profiling functions can be
 113 found in the file <TT
 114 CLASS="FILENAME"
 115 >&lt;cyg/profile/profile.h&gt;</TT
 116 >.</P
 117 ><DIV
 118 CLASS="SECT2"
 119 ><H2
 120 CLASS="SECT2"
 121 ><A
 122 NAME="SERVICES-PROFILE-API-PROFILE-ON">profile_on</H2
 123 ><P
 124 >This function is used to initiate the gathering of the
 125 runtime execution histogram data.</P
 126 ><TABLE
 127 BORDER="5"
 128 BGCOLOR="#E0E0F0"
 129 WIDTH="70%"
 130 ><TR
 131 ><TD
 132 ><PRE
 133 CLASS="PROGRAMLISTING"
 134 >void profile_on(void *start, void *end, int bucket_size, int resolution);</PRE
 135 ></TD
 136 ></TR
 137 ></TABLE
 138 ><P
 139 >Calling this function will initiate execution profiling.
 140 An execution histogram is collected at the rate of
 141 <TT
 142 CLASS="PARAMETER"
 143 ><I
 144 >resolution</I
 145 ></TT
 146 > times per second.
 147 The area between <TT
 148 CLASS="PARAMETER"
 149 ><I
 150 >start</I
 151 ></TT
 152 > and <TT
 153 CLASS="PARAMETER"
 154 ><I
 155 >end</I
 156 ></TT
 157 >
 158 will be divided up into a number of buckets, each representing
 159 <TT
 160 CLASS="PARAMETER"
 161 ><I
 162 >bucket_size</I
 163 ></TT
 164 >
 165 program bytes in length.  Using statistical sampling (via a high speed timer), when
 166 the program counter is found to be within the range
 167 <TT
 168 CLASS="PARAMETER"
 169 ><I
 170 >start</I
 171 ></TT
 172 >..<TT
 173 CLASS="PARAMETER"
 174 ><I
 175 >end</I
 176 ></TT
 177 >, the appropriate
 178 bucket (histogram entry) will be incremented.</P
 179 ><P
 180 >The choice of <TT
 181 CLASS="PARAMETER"
 182 ><I
 183 >resolution</I
 184 ></TT
 185 > and <TT
 186 CLASS="PARAMETER"
 187 ><I
 188 >bucket_size</I
 189 ></TT
 190 >
 191 control how large the data gathered will be, as well as how much overhead is
 192 encumbered for gathering the histogram.
 193 Smaller values for <TT
 194 CLASS="PARAMETER"
 195 ><I
 196 >bucket_size</I
 197 ></TT
 198 > will garner better
 199 results (<TT
 200 CLASS="FUNCTION"
 201 >gprof</TT
 202 > can more closely align the data with
 203 actual function names) at the expense of a larger data buffer.</P
 204 ><DIV
 205 CLASS="NOTE"
 206 ><BLOCKQUOTE
 207 CLASS="NOTE"
 208 ><P
 209 ><B
 210 >NOTE: </B
 211 >The value of <TT
 212 CLASS="PARAMETER"
 213 ><I
 214 >bucket_size</I
 215 ></TT
 216 > will be rounded up to a power of two.</P
 217 ></BLOCKQUOTE
 218 ></DIV
 219 ></DIV
 220 ></DIV
 221 ></DIV
 222 ><DIV
 223 CLASS="NAVFOOTER"
 224 ><HR
 225 ALIGN="LEFT"
 226 WIDTH="100%"><TABLE
 227 SUMMARY="Footer navigation table"
 228 WIDTH="100%"
 229 BORDER="0"
 230 CELLPADDING="0"
 231 CELLSPACING="0"
 232 ><TR
 233 ><TD
 234 WIDTH="33%"
 235 ALIGN="left"
 236 VALIGN="top"
 237 ><A
 238 HREF="services-profile-gprof.html"
 239 ACCESSKEY="P"
 240 >Prev</A
 241 ></TD
 242 ><TD
 243 WIDTH="34%"
 244 ALIGN="center"
 245 VALIGN="top"
 246 ><A
 247 HREF="ecos-ref.html"
 248 ACCESSKEY="H"
 249 >Home</A
 250 ></TD
 251 ><TD
 252 WIDTH="33%"
 253 ALIGN="right"
 254 VALIGN="top"
 255 ><A
 256 HREF="services-power.html"
 257 ACCESSKEY="N"
 258 >Next</A
 259 ></TD
 260 ></TR
 261 ><TR
 262 ><TD
 263 WIDTH="33%"
 264 ALIGN="left"
 265 VALIGN="top"
 266 >Application profiling</TD
 267 ><TD
 268 WIDTH="34%"
 269 ALIGN="center"
 270 VALIGN="top"
 271 ><A
 272 HREF="services-profile-gprof.html"
 273 ACCESSKEY="U"
 274 >Up</A
 275 ></TD
 276 ><TD
 277 WIDTH="33%"
 278 ALIGN="right"
 279 VALIGN="top"
 280 >eCos Power Management Support</TD
 281 ></TR
 282 ></TABLE
 283 ></DIV
 284 ></BODY
 285 ></HTML
 286 >