source: rtems/doc/bsp_howto/timer.t @ 46d17c9

4.9
Last change on this file since 46d17c9 was 46d17c9, checked in by Joel Sherrill <joel.sherrill@…>, on Sep 30, 2008 at 4:27:30 PM

2008-09-30 Joel Sherrill <joel.sherrill@…>

  • bsp_howto/timer.t: Eliminate uses of old benchmark timer names.
  • Property mode set to 100644
File size: 3.4 KB
Line 
1@c
2@c  COPYRIGHT (c) 1988-2002.
3@c  On-Line Applications Research Corporation (OAR).
4@c  All rights reserved.
5@c
6@c  $Id$
7@c
8
9@chapter Timer Driver
10
11The timer driver is primarily used by the RTEMS Timing Tests. 
12This driver provides as accurate a benchmark timer as possible.
13It typically reports its time in microseconds, CPU cycles, or
14bus cycles.  This information can be very useful for determining
15precisely what pieces of code require optimization and to measure the
16impact of specific minor changes.
17
18The gen68340 BSP also uses the Timer Driver to support a high performance
19mode of the on-CPU UART.
20
21@section Benchmark Timer
22
23The RTEMS Timing Test Suite requires a benchmark timer.  The
24RTEMS Timing Test Suite is very helpful for determining
25the performance of target hardware and comparing its performance
26to that of other RTEMS targets.
27
28This section describes the routines which are assumed to exist by
29the RTEMS Timing Test Suite.  The names used are @b{EXACTLY} what
30is used in the RTEMS Timing Test Suite so follow the naming convention.
31
32@subsection benchmark_timer_initialize
33
34Initialize the timer source.
35
36@example
37void benchmark_timer_initialize(void)
38@{
39  initialize the benchmark timer
40@}
41@end example
42
43@subsection Read_timer
44
45The @code{benchmark_timer_read} routine returns the number of benchmark
46time units (typically microseconds) that have elapsed since the last
47call to @code{benchmark_timer_initialize}.
48
49@example
50int benchmark_timer_read(void)
51@{
52  stop time = read the hardware timer
53  if the subtract overhead feature is enabled
54    subtract overhead from stop time
55  return the stop time
56@}
57@end example
58
59Many implementations of this routine subtract the overhead required
60to initialize and read the benchmark timer.  This makes the times reported
61more accurate.
62
63Some implementations report 0 if the harware timer value change is
64sufficiently small.  This is intended to indicate that the execution time
65is below the resolution of the timer.
66
67@subsection benchmark_timer_disable_subtracting_average_overhead
68
69This routine is invoked by the "Check Timer" (@code{tmck}) test in the
70RTEMS Timing Test Suite.  It makes the @code{benchmark_timer_read}
71routine NOT subtract the overhead required
72to initialize and read the benchmark timer.  This is used
73by the @code{tmoverhd} test to determine the overhead
74required to initialize and read the timer.
75
76@example
77void benchmark_timer_disable_subtracting_average_overhead(bool find_flag)
78@{
79    disable the subtract overhead feature
80@}
81@end example
82
83The @code{benchmark_timer_find_average_overhead} variable is used to
84indicate the state of the "subtract overhead feature".
85
86@section gen68340 UART FIFO Full Mode
87
88The gen68340 BSP is an example of the use of the timer to support the UART
89input FIFO full mode (FIFO means First In First Out and roughly means
90buffer). This mode consists in the UART raising an interrupt when n
91characters have been received (@i{n} is the UART's FIFO length). It results
92in a lower interrupt processing time, but the problem is that a scanf
93primitive will block on a receipt of less than @i{n} characters. The solution
94is to set a timer that will check whether there are some characters
95waiting in the UART's input FIFO. The delay time has to be set carefully
96otherwise high rates will be broken:
97
98@itemize @bullet
99
100@item if no character was received last time the interrupt subroutine was
101entered, set a long delay,
102
103@item otherwise set the delay to the delay needed for @i{n} characters
104receipt.
105
106@end itemize
Note: See TracBrowser for help on using the repository browser.