1 files changed, 84 insertions, 37 deletions
diff --git a/doc/bsp_howto/timer.t b/doc/bsp_howto/timer.t
index d2d5629682..8794ea00ee 100644
--- a/doc/bsp_howto/timer.t
+++ b/doc/bsp_howto/timer.t
@@ -8,67 +8,114 @@
 
 @chapter Timer Driver
 
-You can program the timer driver for your own needs, but here are two uses
-of it: 
+The timer driver is primarily used by the RTEMS Timing Tests.  
+This driver provides as accurate a benchmark timer as possible.
+It typically reports its time in microseconds, CPU cycles, or
+bus cycles.  This information can be very useful for determining
+precisely what pieces of code require optimization and to measure the
+impact of specific minor changes.
 
-@section UART'S FIFO Full Mode
+The gen68340 BSP also uses the TImer Driver to support a high performance
+mode of the on-CPU UART.
 
-The gen68340 BSP is an example of the use of the timer to support the UART
-input FIFO full mode (FIFO means First In First Out and roughly means
-buffer). This mode consists in the UART raising an interrupt when n
-characters have been received (n is the UA RT's FIFO length). It results
-in a lower interrupt processing time, but the problem is that a scanf
-primitive will block on a receipt of less than n characters. The solution
-is to set a timer that will check whether there are some characters
-waiting in th e UART's input FIFO. The delay time has to be set carefully
-otherwise high rates will be broken: 
+@section Benchmark Timer
 
-@itemize @bullet
+The RTEMS Timing Test Suite requires a benchmark timer.  The
+RTEMS Timing Test Suite is very helpful for determining
+the performance of target hardware and comparing its performance
+to that of other RTEMS targets.
 
-@item if no character was received last time the interrupt subroutine was
-entered, set a long delay,
+This section describes the routines which are assumed to exist by
+the RTEMS Timing Test Suite.  The names used are @b{EXACTLY} what
+is used in the RTEMS Timing Test Suite so follow the naming convention.
 
-@item otherwise set the delay to the delay needed for n characters
-receipt. 
+@subsection Timer_initialize
 
-@end itemize
+Initialize the timer source.
 
-@section Measuring RTEMS Primitives Time
+@example
+void Timer_initialize(void)
+@{
+  initialize the benchmark timer
+@}
+@end example
 
-RTEMS Timing Test Suite needs a timer support. You have to provide two
-primitives: 
+@subsection Read_timer
 
+The @code{Read_timer} routine 
+returns the number of benchmark time units (typically microseconds)
+that have elapsed since the last call to @code{Timer_initialize}. 
 
+@example
+int Read_timer(void)
+@{
+  stop time = read the hardware timer
+  if the subtract overhead feature is enabled
+    subtract overhead from stop time 
+  return the stop time
+@}
+@end example
 
-Function
+Many implementations of this routine subtract the overhead required
+to initialize and read the benchmark timer.  This makes the times reported
+more accurate.
 
-Description
+Some implementations report 0 if the harware timer value change is 
+sufficiently small.  This is intended to indicate that the execution time 
+is below the resolution of the timer.
+
+@subsection An Empty Function
+
+This routine is invoked by the RTEMS Timing Test Suite to measure 
+the cost of invoking a subroutine.
 
 @example
-void Timer_initialize (void)
+rtems_status_code Empty_function (void)
+@{
+  return RTEMS_SUCCESSFUL;
+@}
 @end example
 
-Initialize the timer to be a counter to the microsecond.
+@subsection Set_find_average_overhead
+
+This routine is invoked by the "Check Timer" (@code{tmck}) test in the 
+RTEMS Timing Test Suite.  It makes the @code{Read_timer}
+routine NOT subtract the overhead required
+to initialize and read the benchmark timer.  This is used
+by the @code{tmoverhd} test to determine the overhead
+required to initialize and read the timer.
 
 @example
-int Read_timer (void)
+void Set_find_average_overhead(rtems_boolean find_flag)
+@{
+    disable the subtract overhead feature
+@}
 @end example
 
-Returns the number of microseconds elapsed since the last call to
-Timer_initialize. 
+The @code{Timer_driver_Find_average_overhead} variable is usually
+used to indicate the state of the "subtract overhead feature".
 
-@example
-rtems_status_code Empty_function (void)
+@section gen68340 UART FIFO Full Mode
 
-return RTEMS_SUCCESSFUL;
-@end example
+The gen68340 BSP is an example of the use of the timer to support the UART
+input FIFO full mode (FIFO means First In First Out and roughly means
+buffer). This mode consists in the UART raising an interrupt when n
+characters have been received (@i{n} is the UART's FIFO length). It results
+in a lower interrupt processing time, but the problem is that a scanf
+primitive will block on a receipt of less than @i{n} characters. The solution
+is to set a timer that will check whether there are some characters
+waiting in the UART's input FIFO. The delay time has to be set carefully
+otherwise high rates will be broken: 
 
-@example
-void Set_find_average_overhead (rtems_boolean find_flag)
-@end example
+@itemize @bullet
 
-DOES NOTHING ??????????
+@item if no character was received last time the interrupt subroutine was
+entered, set a long delay,
+
+@item otherwise set the delay to the delay needed for @i{n} characters
+receipt. 
+
+@end itemize
 
-