source: rtems/doc/bsp_howto/timer.t @ 8fbe2e6

4.11
Last change on this file since 8fbe2e6 was 8fbe2e6, checked in by Joel Sherrill <joel.sherrill@…>, on Sep 4, 2014 at 1:59:49 PM

Use correct prototype of benchmark_timer_read()

This change starts with removing the effectively empty file
timerdrv.h. The prototypes for benchmark_timer_XXX() were in
btimer.h which was not universally used. Thus every use of
timerdrv.h had to be changed to btimer.h. Then the prototypes
for benchmark_timer_read() had to be adjusted to return
benchmark_timer_t rather than int or uint32_t.

I took this opportunity to also correct the file headers to
separate the copyright from the file description comments which
is needed to ensure the copyright isn't propagated into Doxygen
output.

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