<PART ID="services-profile-gprof">
<TITLE>Application profiling</TITLE>
<PARTINTRO>
<PARA>
The profile_gprof package provides a mechanism to measure the
runtime performance of an application.  This is done by gathering
an execution histogram, which can then be uploaded to a host
and analyzed using the 
<function>gprof</function>
utility program.
</PARA>
<para>
Since the collected histogram data is volatile, some mechanism 
must be used to export the data from the target.  
Currently, this process is done using
<emphasis>TFTP</emphasis>.
When profiling is started on the target device, a 
<emphasis>TFTP</emphasis>
server will be started
which exports the single file
<filename>PROFILE.DAT</filename>
</para>
</PARTINTRO>
<CHAPTER id="profile-functions">
<TITLE>Profiling functions</TITLE>
<SECT1 id="services-profile-api">
<title> API </title>
<para>
In order for profile data to be gathered for an application, the
program has to initiate the process.
Once started, execution histogram data will be collected in a
dynamic memory buffer.
This data can be uploaded to a host using <emphasis>TFTP</emphasis>.
A side effect of the upload of the data is that the histogram
is reset.
This is useful, especially for high resolution histograms, since
the histogram data are collected as 16-bit counters which can be quickly
saturated.
For example, if the histogram is being collected at a rate of 10,000
samples per second, a hot spot in the program could saturate after
only 6.5 seconds.
</para>
<para> The API for the application profiling functions can be
found in the file <filename>&lt;cyg/profile/profile.h&gt;</filename>.
</para>
<sect2 id="services-profile-api-profile-on">
<title>profile_on</title>
<para>
This function is used to initiate the gathering of the
runtime execution histogram data.
</para>
<programlisting>
void profile_on(void *start, void *end, int bucket_size, int resolution);
</programlisting>
<para>
Calling this function will initiate execution profiling.
An execution histogram is collected at the rate of
<parameter>resolution</parameter> times per second.
The area between <parameter>start</parameter> and <parameter>end</parameter>
will be divided up into a number of buckets, each representing 
<parameter>bucket_size</parameter> 
program bytes in length.  Using statistical sampling (via a high speed timer), when
the program counter is found to be within the range 
<parameter>start</parameter>..<parameter>end</parameter>, the appropriate
bucket (histogram entry) will be incremented.
</para>
<para>
The choice of <parameter>resolution</parameter> and <parameter>bucket_size</parameter>
control how large the data gathered will be, as well as how much overhead is 
encumbered for gathering the histogram.
Smaller values for <parameter>bucket_size</parameter> will garner better
results (<function>gprof</function> can more closely align the data with
actual function names) at the expense of a larger data buffer.
</para>
<note><title>NOTE</title>
<para>
The value of <parameter>bucket_size</parameter> will be rounded up to a power of two.
</para>
</note>
</sect2>
</SECT1>
</CHAPTER>
</PART>

