# HG changeset patch
# User gthomas
# Date 1037370753 0
# Node ID 0ff80f81c4e86f25bdc25aae90df09a36c0e4dac
# Parent  adaa3da3f4e7ca21a4f04e4c4e69f9e68d34de19
Changes in profiling API.  Add documentation.

diff --git a/packages/services/profile/gprof/current/ChangeLog b/packages/services/profile/gprof/current/ChangeLog
--- a/packages/services/profile/gprof/current/ChangeLog
+++ b/packages/services/profile/gprof/current/ChangeLog
@@ -1,3 +1,11 @@
+2002-11-15  Gary Thomas  <gthomas@ecoscentric.com>
+
+	* src/profile.c: 
+	* include/profile.h: Add proper C++ protections.  Change timer
+	callback function to be __profile_hit() - less polluting.
+
+	* doc/profile.sgml: New file.
+
 2002-11-14  Gary Thomas  <gthomas@ecoscentric.com>
 
 	* src/profile.c: 
diff --git a/packages/services/profile/gprof/current/doc/profile.sgml b/packages/services/profile/gprof/current/doc/profile.sgml
new file mode 100644
--- /dev/null
+++ b/packages/services/profile/gprof/current/doc/profile.sgml
@@ -0,0 +1,84 @@
+<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>
+
diff --git a/packages/services/profile/gprof/current/include/profile.h b/packages/services/profile/gprof/current/include/profile.h
--- a/packages/services/profile/gprof/current/include/profile.h
+++ b/packages/services/profile/gprof/current/include/profile.h
@@ -50,21 +50,24 @@
 // Description:  
 //              
 // Usage:
-//               #include <cyg/infra/profile.h>
+//               #include <cyg/profile/profile.h>
 //              
 //
 //####DESCRIPTIONEND####
 //
 //==========================================================================
 
+#include <pkgconf/profile_gprof.h>
+#include <cyg/infra/cyg_type.h>
+
 // Enable profiling
-extern void profile_on(void *start_addr, void *end_addr, 
-                       int bucket_size, int sample_resolution);
+__externC void profile_on(void *start_addr, void *end_addr, 
+                          int bucket_size, int sample_resolution);
 
 // Callback used by timer routine
-extern void profile_hit(unsigned long pc);
+__externC void __profile_hit(unsigned long pc);
 
 // Timer setup routine, used when enabling profiling
-extern void hal_enable_profile_timer(int resolution);
+__externC void hal_enable_profile_timer(int resolution);
 
 #endif // CYGONCE_PROFILE_H
diff --git a/packages/services/profile/gprof/current/src/profile.c b/packages/services/profile/gprof/current/src/profile.c
--- a/packages/services/profile/gprof/current/src/profile.c
+++ b/packages/services/profile/gprof/current/src/profile.c
@@ -192,7 +192,7 @@ profile_read(int fd, void *buf, int len)
 }
 
 void
-profile_hit(unsigned long pc)
+__profile_hit(unsigned long pc)
 {
     int bucket;
     if (enabled) {