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